@opengsd/gsd-pi 1.5.0 → 1.6.0-dev.aa7f94e8

package/dist/resources/extensions/gsd/md-importer.js

@@ -4,14 +4,14 @@
 //
 // Exports: parseDecisionsTable, parseRequirementsSections, migrateFromMarkdown
 import { readFileSync, readdirSync, existsSync, statSync } from 'node:fs';
-import { join, basename } from 'node:path';
+import { join, basename, dirname } from 'node:path';
 import { upsertDecision, upsertRequirement, insertArtifact, insertMilestone, insertSlice, insertTask, transaction, updateMilestoneStatus, updateSliceStatus, _getAdapter, } from './gsd-db.js';
 import { openWorkflowDatabasePath } from './db-workspace.js';
-import { resolveGsdRootFile, resolveMilestoneFile, resolveSliceFile, resolveTasksDir, legacyMilestonesDir, gsdRoot, resolveTaskFiles, resolveMilestonePath, } from './paths.js';
+import { resolveGsdRootFile, resolveMilestoneFile, resolveSliceFile, resolveSlicePath, resolveTasksDir, legacyMilestonesDir, gsdRoot, resolveTaskFiles, resolveMilestonePath, } from './paths.js';
 import { findMilestoneIds } from './guided-flow.js';
 import { milestoneIdToPhaseNum } from './layout-policy.js';
 import { parseRoadmap, parsePlan } from './parsers-legacy.js';
-import { parseContextDependsOn } from './files.js';
+import { parseContextDependsOn, parseSummary } from './files.js';
 import { logWarning } from './workflow-logger.js';
 // ─── DECISIONS.md Parser ───────────────────────────────────────────────────
 const VALID_MADE_BY = new Set(['human', 'agent', 'collaborative']);
@@ -662,21 +662,63 @@ export function migrateHierarchyToDb(basePath) {
             for (const taskEntry of plan.tasks) {
                 // Per K002: use 'complete' not 'done'
                 let taskStatus = taskEntry.done ? 'complete' : 'pending';
-                // Pre-migration consistency (legacy layout only): if a task is marked
-                // done but has no per-task SUMMARY.md, import it as pending so it gets
-                // re-executed rather than silently entering the DB as complete.
-                // Flat-phase has no per-task summary files by design — the checkbox
-                // state is the authoritative completion signal and is imported as-is.
-                if (taskStatus === 'complete') {
-                    const tDir = resolveTasksDir(basePath, milestoneId, sliceEntry.id);
-                    if (tDir) {
-                        const summaryFile = join(tDir, `${taskEntry.id}-SUMMARY.md`);
-                        if (!existsSync(summaryFile)) {
-                            taskStatus = 'pending';
-                            process.stderr.write(`gsd-migrate: ${milestoneId}/${sliceEntry.id}/${taskEntry.id} marked done but missing summary — importing as pending\n`);
-                        }
+                // Resolve the per-task SUMMARY.md. Legacy layout keeps summaries under
+                // a tasks/ subdir; flat-phase writes TID-SUMMARY.md directly in the
+                // phase dir (execute-task's gsd_task_complete writes it there). A tasks/
+                // subdir may still exist in flat-phase for auxiliary artifacts — its
+                // mere existence must NOT redirect summary resolution into tasks/ (#1208).
+                const slicePath = resolveSlicePath(basePath, milestoneId, sliceEntry.id);
+                let taskSummaryFile = null;
+                let isLegacySlice = false;
+                // Legacy layout keeps per-task summaries under a tasks/ subdir. Its
+                // presence — not merely "is this a legacy slice" — is what makes a
+                // missing summary a downgrade signal. resolveTasksDir returns null when
+                // no such dir exists, so a legacy slice whose checkbox is the only
+                // completion signal (no tasks/ dir at all) is left complete on import.
+                let legacyTasksDir = null;
+                if (slicePath) {
+                    isLegacySlice = basename(dirname(slicePath)) === 'slices';
+                    legacyTasksDir = isLegacySlice
+                        ? resolveTasksDir(basePath, milestoneId, sliceEntry.id)
+                        : null;
+                    const summaryDir = legacyTasksDir ?? slicePath;
+                    taskSummaryFile = join(summaryDir, `${taskEntry.id}-SUMMARY.md`);
+                }
+                const hasTaskSummary = taskSummaryFile !== null && existsSync(taskSummaryFile);
+                // Pre-migration consistency (legacy tasks/ layout only): if a task is
+                // marked done but its tasks/ dir has no per-task SUMMARY.md, import it
+                // as pending so it gets re-executed rather than silently entering the DB
+                // as complete. A legacy slice with no tasks/ dir (checkbox-only
+                // completion) and flat-phase layout are both left as-is here.
+                if (taskStatus === 'complete' && legacyTasksDir !== null && !hasTaskSummary) {
+                    taskStatus = 'pending';
+                    process.stderr.write(`gsd-migrate: ${milestoneId}/${sliceEntry.id}/${taskEntry.id} marked done but missing summary — importing as pending\n`);
+                }
+                // Lost-update guard (#1222): a per-task SUMMARY.md is the durable
+                // completion attestation written by gsd_task_complete. When the plan
+                // checkbox is stale-unchecked but the SUMMARY exists on disk, a
+                // re-import must NOT downgrade the completed task back to pending — that
+                // silent revert is the lost-update that hard-stopped auto-mode after the
+                // first execute-task. The surviving SUMMARY wins over a stale checkbox.
+                // reopen-task removes the SUMMARY, so this never re-completes an
+                // intentionally reopened task.
+                // Flat-phase summaries are phase-scoped (T01-SUMMARY.md); when a milestone
+                // has multiple slices, require the summary parent frontmatter to match so
+                // one slice's completion does not attest a sibling's same-named task.
+                let summaryAttestsCompletion = hasTaskSummary;
+                if (summaryAttestsCompletion && !isLegacySlice && roadmap.slices.length > 1 && taskSummaryFile) {
+                    try {
+                        const summaryContent = readFileSync(taskSummaryFile, 'utf-8');
+                        summaryAttestsCompletion = parseSummary(summaryContent).frontmatter.parent === sliceEntry.id;
+                    }
+                    catch {
+                        summaryAttestsCompletion = false;
                     }
                 }
+                if (taskStatus === 'pending' && summaryAttestsCompletion) {
+                    taskStatus = 'complete';
+                    process.stderr.write(`gsd-migrate: ${milestoneId}/${sliceEntry.id}/${taskEntry.id} unchecked in plan but SUMMARY.md present — importing as complete (#1222)\n`);
+                }
                 insertTask({
                     id: taskEntry.id,
                     sliceId: sliceEntry.id,
@@ -687,6 +729,12 @@ export function migrateHierarchyToDb(basePath) {
                         files: taskEntry.files ?? [],
                         verify: taskEntry.verify ?? '',
                     },
+                    // #1222 (metadata half): re-import derives status from the plan/summary
+                    // but has none of the execution prose gsd_task_complete wrote to the DB.
+                    // Preserve the existing row's execution columns and completed_at so a
+                    // re-import cannot blank a completed task's summary metadata or refresh
+                    // its completion timestamp — the DB row is strictly richer than the plan.
+                    preserveCompletionMetadata: true,
                 });
                 counts.tasks++;
             }
@@ -699,14 +747,32 @@ export function migrateHierarchyToDb(basePath) {
             if (!sliceEntry.done) {
                 const sliceSummaryPath = resolveSliceFile(basePath, milestoneId, sliceEntry.id, 'SUMMARY');
                 const hasSliceSummary = sliceSummaryPath !== null && existsSync(sliceSummaryPath);
+                const slicePathForTasks = resolveSlicePath(basePath, milestoneId, sliceEntry.id);
+                const isLegacySliceLayout = slicePathForTasks !== null
+                    && basename(dirname(slicePathForTasks)) === 'slices';
+                const taskSummaryDir = slicePathForTasks
+                    ? (isLegacySliceLayout
+                        ? (resolveTasksDir(basePath, milestoneId, sliceEntry.id) ?? slicePathForTasks)
+                        : slicePathForTasks)
+                    : null;
                 const allTasksDone = plan.tasks.length > 0 && plan.tasks.every(t => {
-                    if (!t.done)
-                        return false;
-                    const tDir = resolveTasksDir(basePath, milestoneId, sliceEntry.id);
-                    // Flat-phase has no per-task summary files — checkbox state is authoritative.
-                    if (!tDir)
-                        return true;
-                    return existsSync(join(tDir, `${t.id}-SUMMARY.md`));
+                    const taskSummaryFile = taskSummaryDir !== null
+                        ? join(taskSummaryDir, `${t.id}-SUMMARY.md`)
+                        : null;
+                    const hasTaskSummary = taskSummaryFile !== null && existsSync(taskSummaryFile);
+                    let summaryAttestsCompletion = hasTaskSummary;
+                    if (summaryAttestsCompletion && !isLegacySliceLayout && roadmap.slices.length > 1 && taskSummaryFile) {
+                        try {
+                            const summaryContent = readFileSync(taskSummaryFile, 'utf-8');
+                            summaryAttestsCompletion = parseSummary(summaryContent).frontmatter.parent === sliceEntry.id;
+                        }
+                        catch {
+                            summaryAttestsCompletion = false;
+                        }
+                    }
+                    // Match per-task import rules above: SUMMARY attestation wins over a stale
+                    // checkbox (#1222); flat-phase checkboxes are authoritative without summary.
+                    return summaryAttestsCompletion || (t.done && !isLegacySliceLayout);
                 });
                 if (allTasksDone && hasSliceSummary) {
                     if (_getAdapter()) {

package/dist/resources/extensions/gsd/metrics.js

@@ -172,7 +172,7 @@ export function snapshotUnitMetrics(ctx, unitType, unitId, startedAt, model, opt
         ledger.units.push(unit);
     }
     saveLedger(basePath, ledger);
-    if (isUnifiedAuditEnabled()) {
+    if (isUnifiedAuditEnabled(basePath)) {
         emitUokAuditEvent(basePath, buildAuditEnvelope({
             traceId: opts?.traceId ?? `metrics:${unitType}:${unitId}`,
             turnId: opts?.turnId,
@@ -324,7 +324,7 @@ export function snapshotUnitMetricsByScope(scope, ctx, unitType, unitId, started
         scopedLedger.units.push(unit);
     }
     saveLedger(base, scopedLedger);
-    if (isUnifiedAuditEnabled()) {
+    if (isUnifiedAuditEnabled(base)) {
         emitUokAuditEvent(base, buildAuditEnvelope({
             traceId: opts?.traceId ?? `metrics:${unitType}:${unitId}`,
             turnId: opts?.turnId,

package/dist/resources/extensions/gsd/migration-auto-check.js

@@ -56,14 +56,40 @@ function replaceSetPrefix(values, from, to) {
         values.add(`${to}${value.slice(from.length)}`);
     }
 }
+/**
+ * Rewrite one milestone identity across EVERY markdown identity set. The
+ * roadmapless subset is a view of `milestones`, so it must speak the same
+ * aligned vocabulary; otherwise the discussion-phase exclusion below keys off
+ * the stale bare id, fails its `dbScan.milestones.has(...)` membership check,
+ * and decrements the milestone count even though the aligned identity remains
+ * in the set, reporting false drift for a milestone that is actually in sync.
+ * Centralising the set list here keeps every alignment path from silently
+ * missing a set (the defect that regressed the suffixed roadmapless case).
+ */
+function realignMilestonePrefix(markdownScan, from, to) {
+    replaceSetPrefix(markdownScan.milestones, from, to);
+    replaceSetPrefix(markdownScan.slices, from, to);
+    replaceSetPrefix(markdownScan.tasks, from, to);
+    replaceSetPrefix(markdownScan.milestonesWithoutRoadmap, from, to);
+}
 function alignNumericMarkdownIdsWithDb(markdownScan, dbScan) {
     for (const dbId of dbScan.milestones) {
         const paddedId = paddedMilestoneId(dbId);
         if (!paddedId || dbScan.milestones.has(paddedId) || !markdownScan.milestones.has(paddedId))
             continue;
-        replaceSetPrefix(markdownScan.milestones, paddedId, dbId);
-        replaceSetPrefix(markdownScan.slices, paddedId, dbId);
-        replaceSetPrefix(markdownScan.tasks, paddedId, dbId);
+        realignMilestonePrefix(markdownScan, paddedId, dbId);
+    }
+}
+function bareMilestoneId(id) {
+    const match = id.match(/^(M\d{3})-[a-z0-9]{6}$/);
+    return match?.[1] ?? null;
+}
+function alignBareMarkdownIdsWithSuffixedDb(markdownScan, dbScan) {
+    for (const dbId of dbScan.milestones) {
+        const bareId = bareMilestoneId(dbId);
+        if (!bareId || dbScan.milestones.has(bareId) || !markdownScan.milestones.has(bareId))
+            continue;
+        realignMilestonePrefix(markdownScan, bareId, dbId);
     }
 }
 /**
@@ -148,6 +174,7 @@ export async function checkMarkdownHierarchyAgainstDb(basePath) {
     const dbScan = scanDbHierarchy();
     const beforeDb = dbScan.counts;
     alignNumericMarkdownIdsWithDb(markdownScan, dbScan);
+    alignBareMarkdownIdsWithSuffixedDb(markdownScan, dbScan);
     // Discussion-phase scratch: a milestone dir with no ROADMAP and no DB row is
     // a pre-registration discussion artifact (CONTEXT/CONTEXT-DRAFT only — the
     // queued DB row is inserted only at discussion handoff). Treating it as

package/dist/resources/extensions/gsd/milestone-merge-transaction.js

@@ -1,5 +1,6 @@
 // Project/App: gsd-pi
 // File Purpose: Process-level transaction wrapper for milestone merge closeout.
+import { mergeMilestoneToMain } from "./auto-worktree-merge.js";
 export function runMilestoneMergeTransaction(deps, input) {
     return deps.mergeMilestone(input.basePath, input.milestoneId, input.roadmapContent);
 }
@@ -8,3 +9,13 @@ export function createMilestoneMergeTransaction(mergeMilestone) {
         return runMilestoneMergeTransaction({ mergeMilestone }, { basePath, milestoneId, roadmapContent });
     };
 }
+/**
+ * Production merge transaction adapter.
+ *
+ * This is the only production construction point that knows the legacy
+ * `auto-worktree.ts` merge primitive. Lifecycle callers depend on the
+ * transaction runner interface, not the legacy implementation module.
+ */
+export function createDefaultMilestoneMergeTransaction(mergeMilestone = mergeMilestoneToMain) {
+    return createMilestoneMergeTransaction(mergeMilestone);
+}

package/dist/resources/extensions/gsd/milestone-settlement.js

@@ -1,6 +1,6 @@
 // Project/App: gsd-pi
 // File Purpose: Milestone closeout settlement state across DB proof, artifacts, merge, and cleanup.
-import { isInAutoWorktree } from "./auto-worktree.js";
+import { isInAutoWorktree } from "./auto-worktree-entry.js";
 import { formatCloseoutProofBlock, proveMilestoneCloseout, } from "./milestone-closeout-proof.js";
 import { resolveCloseoutArtifactProjection } from "./artifact-projection.js";
 function isActiveUnmergedWorktree(input) {

package/dist/resources/extensions/gsd/parallel-merge.js

@@ -8,7 +8,7 @@ import { existsSync, readdirSync } from "node:fs";
 import { spawnSync } from "node:child_process";
 import { resolveGsdPathContract } from "./paths.js";
 import { worktreePathFor, worktreesDirs } from "./worktree-placement.js";
-import { getAutoWorktreePath } from "./auto-worktree.js";
+import { getAutoWorktreePath } from "./auto-worktree-path-resolution.js";
 import { buildWorktreeLifecycleDeps } from "./auto.js";
 import { mergeMilestoneStandalone, } from "./worktree-lifecycle.js";
 import { MergeConflictError } from "./git-service.js";

package/dist/resources/extensions/gsd/parallel-orchestrator.js

@@ -12,7 +12,9 @@ import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import { gsdRoot } from "./paths.js";
 import { createWorktree, worktreePath } from "./worktree-manager.js";
-import { autoWorktreeBranch, fastForwardReusedMilestoneBranchIfSafe, runWorktreePostCreateHook, syncGsdStateToWorktreeByScope } from "./auto-worktree.js";
+import { autoWorktreeBranch, fastForwardReusedMilestoneBranchIfSafe } from "./auto-worktree-branch-lifecycle.js";
+import { syncGsdStateToWorktreeByScope } from "./auto-worktree-sync.js";
+import { runWorktreePostCreateHook } from "./worktree-post-create-hook.js";
 import { nativeBranchExists } from "./native-git-bridge.js";
 import { readIntegrationBranch } from "./git-service.js";
 import { createWorkspace, scopeMilestone } from "./workspace.js";

package/dist/resources/extensions/gsd/paths.js

@@ -10,7 +10,7 @@
  * via prefix matching, so existing projects work without migration.
  */
 import { readdirSync, existsSync, realpathSync, statSync, Dirent } from "node:fs";
-import { join, dirname, normalize, resolve } from "node:path";
+import { join, dirname, normalize, relative, resolve } from "node:path";
 import { homedir } from "node:os";
 import { spawnSync } from "node:child_process";
 import { nativeScanGsdTree } from "./native-parser-bridge.js";
@@ -331,21 +331,26 @@ export function resolveGsdPathContract(workRoot, originalProjectRoot) {
     const resolvedWorkRoot = resolve(workRoot || process.cwd());
     const isWorktree = isGsdWorktreePath(resolvedWorkRoot);
     if (isWorktree && !originalProjectRoot?.trim()) {
-        const projectGsd = resolveExternalStateProjectGsdFromWorktreePath(resolvedWorkRoot);
-        if (projectGsd) {
+        const rawProjectGsd = resolveExternalStateProjectGsdFromWorktreePath(resolvedWorkRoot);
+        if (rawProjectGsd) {
+            // Canonicalize the `.gsd` root so the DB path matches what every other
+            // accessor (gsdRoot/gsdProjectionRoot) returns — otherwise an unresolved
+            // symlink (e.g. `/mnt/c/.../.gsd` → native ext4 on WSL) selects the wrong
+            // journal mode and yields a fragile, move-prone handle. See issue #1239.
+            const projectGsd = normalizeRealPath(rawProjectGsd);
             return {
                 projectRoot: dirname(dirname(projectGsd)),
                 workRoot: resolvedWorkRoot,
                 projectGsd,
-                worktreeGsd: join(resolvedWorkRoot, ".gsd"),
+                worktreeGsd: normalizeRealPath(join(resolvedWorkRoot, ".gsd")),
                 projectDb: join(projectGsd, "gsd.db"),
                 isWorktree,
             };
         }
     }
     const projectRoot = resolve(resolveWorktreeProjectRoot(resolvedWorkRoot, originalProjectRoot));
-    const projectGsd = join(projectRoot, ".gsd");
-    const worktreeGsd = isWorktree ? join(resolvedWorkRoot, ".gsd") : null;
+    const projectGsd = normalizeRealPath(join(projectRoot, ".gsd"));
+    const worktreeGsd = isWorktree ? normalizeRealPath(join(resolvedWorkRoot, ".gsd")) : null;
     return {
         projectRoot,
         workRoot: resolvedWorkRoot,
@@ -669,7 +674,10 @@ function pickPreferredPhaseDir(phasesDir, matches) {
     }
     return best;
 }
-function phaseDirMatchesMilestoneId(dirName, milestoneId, phaseNum) {
+function slugLooksLikeTeamSuffixProjection(slugPart) {
+    return /^[a-z0-9]{6}(-|$)/.test(slugPart);
+}
+function phaseDirMatchesMilestoneId(dirName, milestoneId, phaseNum, allowTeamSuffixSlugs = false) {
     const numMatch = dirName.match(/^(\d+)-(.*)$/);
     if (!numMatch || parseInt(numMatch[1], 10) !== phaseNum)
         return false;
@@ -678,8 +686,9 @@ function phaseDirMatchesMilestoneId(dirName, milestoneId, phaseNum) {
     if (suffix) {
         return slugPart === suffix || slugPart.startsWith(`${suffix}-`);
     }
-    // Plain sequential IDs must not resolve to unique-suffix phase dirs.
-    return !/^[a-z0-9]{6}(-|$)/.test(slugPart);
+    if (slugLooksLikeTeamSuffixProjection(slugPart) && !allowTeamSuffixSlugs)
+        return false;
+    return true;
 }
 function resolvePhaseDir(basePath, milestoneId) {
     // Try flat-phase layout first: phases/NN-slug/ (always scan phases/, even when
@@ -700,6 +709,16 @@ function resolvePhaseDir(basePath, milestoneId) {
                     matches.push(entry.name);
                 }
             }
+            // Bare milestone ids may only have a suffixed team-mode projection on disk.
+            if (matches.length === 0 && !milestoneIdUniqueSuffix(milestoneId)) {
+                for (const entry of readdirSync(phasesDir, { withFileTypes: true })) {
+                    if (!entry.isDirectory())
+                        continue;
+                    if (phaseDirMatchesMilestoneId(entry.name, milestoneId, phaseNum, true)) {
+                        matches.push(entry.name);
+                    }
+                }
+            }
         }
         catch {
             // unreadable — fall through
@@ -865,11 +884,22 @@ export function resolveTasksDir(basePath, milestoneId, sliceId) {
  * Resolve a specific task file.
  */
 export function resolveTaskFile(basePath, milestoneId, sliceId, taskId, suffix) {
-    const tDir = resolveTasksDir(basePath, milestoneId, sliceId);
-    if (!tDir)
+    const phaseDir = resolveMilestonePath(basePath, milestoneId);
+    if (!phaseDir)
         return null;
-    const file = resolveFile(tDir, taskId, suffix);
-    return file ? join(tDir, file) : null;
+    const legacyBase = legacyMilestonesDir(basePath);
+    const isLegacy = phaseDir.startsWith(legacyBase + "/") || phaseDir.startsWith(legacyBase + "\\");
+    if (suffix !== "PLAN" && !isLegacy) {
+        const flatPath = join(phaseDir, buildTaskFileName(taskId, suffix));
+        return existsSync(flatPath) ? flatPath : null;
+    }
+    const tDir = resolveTasksDir(basePath, milestoneId, sliceId);
+    if (tDir) {
+        const file = resolveFile(tDir, taskId, suffix);
+        if (file)
+            return join(tDir, file);
+    }
+    return null;
 }
 // ─── Relative Path Builders (for prompts — .gsd/milestones/...) ────────────
 /**
@@ -901,29 +931,30 @@ export function relMilestonePath(basePath, milestoneId, title) {
     return `.gsd/${LAYOUT_SEGMENTS.level1}/${canonicalPhaseDirName(milestoneId, title)}`;
 }
 /**
- * Build relative .gsd/ path to a milestone file.
- * Layout-aware: uses resolveMilestoneFile to find NN-SUFFIX.md (flat-phase)
- * or M001-SUFFIX.md (legacy). Falls back to a layout-appropriate canonical
- * name when the file doesn't exist yet.
- */
-export function relMilestoneFile(basePath, milestoneId, suffix) {
-    const mRel = relMilestonePath(basePath, milestoneId);
-    // resolveMilestoneFile checks NN-SUFFIX.md (flat-phase) and MID-SUFFIX.md (legacy).
-    const absFile = resolveMilestoneFile(basePath, milestoneId, suffix);
-    if (absFile) {
-        const fileName = absFile.split(/[/\\]/).pop();
-        return `${mRel}/${fileName}`;
-    }
-    // File doesn't exist yet — use layout-aware fallback filename.
+ * Build the canonical absolute write target for a milestone file.
+ * Existing compatibility filenames are intentionally ignored; readers that need
+ * to preserve an existing file should call resolveMilestoneFile first.
+ */
+export function targetMilestoneFile(basePath, milestoneId, suffix, title) {
     const mDir = resolveMilestonePath(basePath, milestoneId);
     const legacyBase = legacyMilestonesDir(basePath);
     const isLegacy = mDir
         ? mDir.startsWith(legacyBase + "/") || mDir.startsWith(legacyBase + "\\")
-        : false;
+        : isLegacyMilestonesLayout(basePath);
+    const dir = mDir ?? join(isLegacy ? legacyBase : milestonesDir(basePath), isLegacy ? milestoneId : canonicalPhaseDirName(milestoneId, title));
     const fileName = isLegacy
         ? `${milestoneId}-${suffix}.md`
         : `${String(milestoneIdToPhaseNum(milestoneId)).padStart(2, "0")}-${suffix}.md`;
-    return `${mRel}/${fileName}`;
+    return join(dir, fileName);
+}
+/**
+ * Build relative .gsd/ path to a milestone file.
+ * Preserves an existing compatibility filename when present; otherwise falls
+ * back to the canonical write target.
+ */
+export function relMilestoneFile(basePath, milestoneId, suffix, title) {
+    const rel = relative(gsdProjectionRoot(basePath), resolveMilestoneFile(basePath, milestoneId, suffix) ?? targetMilestoneFile(basePath, milestoneId, suffix, title)).replace(/\\/g, "/");
+    return `.gsd/${rel}`;
 }
 /**
  * Build relative .gsd/ path to a slice directory.
@@ -951,32 +982,36 @@ export function relSlicePath(basePath, milestoneId, sliceId, milestoneTitle) {
     return relMilestonePath(basePath, milestoneId, milestoneTitle);
 }
 /**
- * Build relative .gsd/ path to a slice file.
- * Layout-aware: legacy uses S01-SUFFIX.md; flat-phase uses NN-MM-SUFFIX.md.
- *
- * @param milestoneTitle - Optional milestone title forwarded to relSlicePath /
- *   relMilestonePath for title-aware flat-phase fallback dir naming. Only used
- *   when the phase directory does not yet exist on disk.
+ * Build the canonical absolute write target for a slice file.
+ * Existing compatibility filenames are intentionally ignored; readers that need
+ * to preserve an existing file should call resolveSliceFile first.
  */
-export function relSliceFile(basePath, milestoneId, sliceId, suffix, milestoneTitle) {
-    const sRel = relSlicePath(basePath, milestoneId, sliceId, milestoneTitle);
-    const absPath = resolveSliceFile(basePath, milestoneId, sliceId, suffix);
-    if (absPath) {
-        const fileName = absPath.split(/[/\\]/).pop();
-        return `${sRel}/${fileName}`;
-    }
-    // Fallback when file doesn't exist yet — use layout-aware filename.
+export function targetSliceFile(basePath, milestoneId, sliceId, suffix, milestoneTitle) {
     const mDir = resolveMilestonePath(basePath, milestoneId);
     const legacyBase = legacyMilestonesDir(basePath);
     const isLegacy = mDir
         ? mDir.startsWith(legacyBase + "/") || mDir.startsWith(legacyBase + "\\")
-        : false;
-    if (isLegacy) {
-        return `${sRel}/${sliceId}-${suffix}.md`;
-    }
-    const phaseNum = milestoneIdToPhaseNum(milestoneId);
-    const planNum = sliceIdToPlanNum(sliceId);
-    return `${sRel}/${planFileName(phaseNum, planNum, suffix)}`;
+        : isLegacyMilestonesLayout(basePath);
+    const milestoneDir = mDir
+        ?? dirname(targetMilestoneFile(basePath, milestoneId, "ROADMAP", milestoneTitle));
+    const slicesDir = join(milestoneDir, "slices");
+    const dir = isLegacy
+        ? join(slicesDir, resolveDir(slicesDir, sliceId) ?? sliceId)
+        : milestoneDir;
+    const fileName = isLegacy
+        ? `${sliceId}-${suffix}.md`
+        : planFileName(milestoneIdToPhaseNum(milestoneId), sliceIdToPlanNum(sliceId), suffix);
+    return join(dir, fileName);
+}
+/**
+ * Build relative .gsd/ path to a slice file.
+ * Preserves an existing compatibility filename when present; otherwise falls
+ * back to the canonical write target.
+ */
+export function relSliceFile(basePath, milestoneId, sliceId, suffix, milestoneTitle) {
+    const rel = relative(gsdProjectionRoot(basePath), resolveSliceFile(basePath, milestoneId, sliceId, suffix)
+        ?? targetSliceFile(basePath, milestoneId, sliceId, suffix, milestoneTitle)).replace(/\\/g, "/");
+    return `.gsd/${rel}`;
 }
 /**
  * Build relative .gsd/ path to a task file.
@@ -985,7 +1020,7 @@ export function relSliceFile(basePath, milestoneId, sliceId, suffix, milestoneTi
  * Flat-phase:     PLAN → slice plan path (tasks as checkboxes); other suffixes
  *                 (e.g. SUMMARY) → phase dir / TID-SUFFIX.md
  */
-export function relTaskFile(basePath, milestoneId, sliceId, taskId, suffix) {
+export function relTaskFile(basePath, milestoneId, sliceId, taskId, suffix, milestoneTitle) {
     const sDir = resolveSlicePath(basePath, milestoneId, sliceId);
     const phaseDir = resolveMilestonePath(basePath, milestoneId);
     // Legacy: slice path is a slices/SID/ subdir inside the milestone dir
@@ -997,6 +1032,6 @@ export function relTaskFile(basePath, milestoneId, sliceId, taskId, suffix) {
     if (suffix === "PLAN") {
         return relSliceFile(basePath, milestoneId, sliceId, "PLAN");
     }
-    const relS = relSlicePath(basePath, milestoneId, sliceId);
+    const relS = relSlicePath(basePath, milestoneId, sliceId, milestoneTitle);
     return `${relS}/${buildTaskFileName(taskId, suffix)}`;
 }

package/dist/resources/extensions/gsd/post-unit-hooks.js

@@ -42,6 +42,33 @@ export function persistHookState(basePath) {
 export function restoreHookState(basePath) {
     getOrCreateRegistry().restoreState(basePath);
 }
+/**
+ * Reconcile a restored `activeHook` against the session's sidecar queue.
+ *
+ * The registry persists `activeHook` to disk but the pending hook *dispatch*
+ * lives only on the non-persisted `s.sidecarQueue`. After a pause/resume or
+ * crash-recovery, `restoreHookState` re-hydrates `activeHook` while the dispatch
+ * is gone, so the registry believes a hook is in-flight but nothing will ever
+ * complete it — and the next unrelated unit's close-out is falsely charged
+ * against the stale hook and blocked. Re-enqueue the missing dispatch so the
+ * hook actually runs, restoring the invariant that a persisted `activeHook`
+ * always has a live dispatch (#1246).
+ */
+export function reconcileRestoredHookDispatch(basePath, sidecarQueue) {
+    const dispatch = getOrCreateRegistry().getPendingHookDispatch(basePath);
+    if (!dispatch)
+        return;
+    const alreadyQueued = sidecarQueue.some(item => item.kind === "hook" && item.unitType === dispatch.unitType);
+    if (alreadyQueued)
+        return;
+    sidecarQueue.push({
+        kind: "hook",
+        unitType: dispatch.unitType,
+        unitId: dispatch.unitId,
+        prompt: dispatch.prompt,
+        model: dispatch.model,
+    });
+}
 export function clearPersistedHookState(basePath) {
     getOrCreateRegistry().clearPersistedState(basePath);
 }