@opengsd/gsd-pi 1.5.0 → 1.6.0

package/src/resources/extensions/gsd/md-importer.ts

@@ -5,7 +5,7 @@
 // Exports: parseDecisionsTable, parseRequirementsSections, migrateFromMarkdown
 
 import { readFileSync, readdirSync, existsSync, statSync } from 'node:fs';
-import { join, relative, basename } from 'node:path';
+import { join, relative, basename, dirname } from 'node:path';
 import type { Decision, Requirement } from './types.js';
 import {
   upsertDecision,
@@ -24,6 +24,7 @@ import {
   resolveGsdRootFile,
   resolveMilestoneFile,
   resolveSliceFile,
+  resolveSlicePath,
   resolveTasksDir,
   legacyMilestonesDir,
   gsdRoot,
@@ -33,7 +34,7 @@ import {
 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 ───────────────────────────────────────────────────
@@ -816,23 +817,68 @@ export function migrateHierarchyToDb(basePath: string): {
         // Per K002: use 'complete' not 'done'
         let taskStatus: string = 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: string | null = 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: string | null = 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,
@@ -844,6 +890,12 @@ export function migrateHierarchyToDb(basePath: string): {
             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++;
       }
@@ -857,12 +909,31 @@ export function migrateHierarchyToDb(basePath: string): {
       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/src/resources/extensions/gsd/metrics.ts

@@ -265,7 +265,7 @@ export function snapshotUnitMetrics(
   }
   saveLedger(basePath, ledger);
 
-  if (isUnifiedAuditEnabled()) {
+  if (isUnifiedAuditEnabled(basePath)) {
     emitUokAuditEvent(
       basePath,
       buildAuditEnvelope({
@@ -458,7 +458,7 @@ export function snapshotUnitMetricsByScope(
   }
   saveLedger(base, scopedLedger);
 
-  if (isUnifiedAuditEnabled()) {
+  if (isUnifiedAuditEnabled(base)) {
     emitUokAuditEvent(
       base,
       buildAuditEnvelope({

package/src/resources/extensions/gsd/migration-auto-check.ts

@@ -102,13 +102,41 @@ function replaceSetPrefix(values: Set<string>, from: string, to: string): void {
   }
 }
 
+/**
+ * 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: HierarchyScan, from: string, to: string): void {
+  replaceSetPrefix(markdownScan.milestones, from, to);
+  replaceSetPrefix(markdownScan.slices, from, to);
+  replaceSetPrefix(markdownScan.tasks, from, to);
+  replaceSetPrefix(markdownScan.milestonesWithoutRoadmap, from, to);
+}
+
 function alignNumericMarkdownIdsWithDb(markdownScan: HierarchyScan, dbScan: HierarchyScan): void {
   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: string): string | null {
+  const match = id.match(/^(M\d{3})-[a-z0-9]{6}$/);
+  return match?.[1] ?? null;
+}
+
+function alignBareMarkdownIdsWithSuffixedDb(markdownScan: HierarchyScan, dbScan: HierarchyScan): void {
+  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);
   }
 }
 
@@ -208,6 +236,7 @@ export async function checkMarkdownHierarchyAgainstDb(
   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

package/src/resources/extensions/gsd/milestone-merge-transaction.ts

@@ -1,6 +1,8 @@
 // Project/App: gsd-pi
 // File Purpose: Process-level transaction wrapper for milestone merge closeout.
 
+import { mergeMilestoneToMain } from "./auto-worktree-merge.js";
+
 export interface MilestoneMergeTransactionResult {
   pushed: boolean;
   codeFilesChanged: boolean;
@@ -45,3 +47,16 @@ export function createMilestoneMergeTransaction(
     );
   };
 }
+
+/**
+ * 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: MilestoneMergeTransactionRunner = mergeMilestoneToMain,
+): MilestoneMergeTransactionRunner {
+  return createMilestoneMergeTransaction(mergeMilestone);
+}

package/src/resources/extensions/gsd/milestone-settlement.ts

@@ -1,7 +1,7 @@
 // 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,

package/src/resources/extensions/gsd/parallel-merge.ts

@@ -10,7 +10,7 @@ import { join } from "node:path";
 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,

package/src/resources/extensions/gsd/parallel-orchestrator.ts

@@ -21,7 +21,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/src/resources/extensions/gsd/paths.ts

@@ -11,7 +11,7 @@
  */
 
 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, type GsdTreeEntry } from "./native-parser-bridge.js";
@@ -379,21 +379,26 @@ export function resolveGsdPathContract(
   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,
@@ -696,7 +701,16 @@ function pickPreferredPhaseDir(phasesDir: string, matches: string[]): string {
   return best;
 }
 
-function phaseDirMatchesMilestoneId(dirName: string, milestoneId: string, phaseNum: number): boolean {
+function slugLooksLikeTeamSuffixProjection(slugPart: string): boolean {
+  return /^[a-z0-9]{6}(-|$)/.test(slugPart);
+}
+
+function phaseDirMatchesMilestoneId(
+  dirName: string,
+  milestoneId: string,
+  phaseNum: number,
+  allowTeamSuffixSlugs = false,
+): boolean {
   const numMatch = dirName.match(/^(\d+)-(.*)$/);
   if (!numMatch || parseInt(numMatch[1]!, 10) !== phaseNum) return false;
   const slugPart = numMatch[2]!;
@@ -704,8 +718,8 @@ function phaseDirMatchesMilestoneId(dirName: string, milestoneId: string, phaseN
   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: string, milestoneId: string): string | null {
@@ -726,6 +740,15 @@ function resolvePhaseDir(basePath: string, milestoneId: string): string | null {
           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
     }
@@ -898,10 +921,24 @@ export function resolveTaskFile(
   basePath: string, milestoneId: string, sliceId: string,
   taskId: string, suffix: string
 ): string | null {
+  const phaseDir = resolveMilestonePath(basePath, milestoneId);
+  if (!phaseDir) return 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) return null;
-  const file = resolveFile(tDir, taskId, suffix);
-  return file ? join(tDir, file) : null;
+  if (tDir) {
+    const file = resolveFile(tDir, taskId, suffix);
+    if (file) return join(tDir, file);
+  }
+
+  return null;
 }
 
 // ─── Relative Path Builders (for prompts — .gsd/milestones/...) ────────────
@@ -936,31 +973,41 @@ export function relMilestonePath(basePath: string, milestoneId: string, 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.
+ * 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 relMilestoneFile(
-  basePath: string, milestoneId: string, suffix: string
+export function targetMilestoneFile(
+  basePath: string, milestoneId: string, suffix: string, title?: string
 ): string {
-  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.
   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: string, milestoneId: string, suffix: string, title?: string
+): string {
+  const rel = relative(
+    gsdProjectionRoot(basePath),
+    resolveMilestoneFile(basePath, milestoneId, suffix) ?? targetMilestoneFile(basePath, milestoneId, suffix, title),
+  ).replace(/\\/g, "/");
+  return `.gsd/${rel}`;
 }
 
 /**
@@ -992,34 +1039,44 @@ export function relSlicePath(
 }
 
 /**
- * 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(
+export function targetSliceFile(
   basePath: string, milestoneId: string, sliceId: string, suffix: string, milestoneTitle?: string
 ): string {
-  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.
   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: string, milestoneId: string, sliceId: string, suffix: string, milestoneTitle?: string
+): string {
+  const rel = relative(
+    gsdProjectionRoot(basePath),
+    resolveSliceFile(basePath, milestoneId, sliceId, suffix)
+      ?? targetSliceFile(basePath, milestoneId, sliceId, suffix, milestoneTitle),
+  ).replace(/\\/g, "/");
+  return `.gsd/${rel}`;
 }
 
 /**
@@ -1031,7 +1088,7 @@ export function relSliceFile(
  */
 export function relTaskFile(
   basePath: string, milestoneId: string, sliceId: string,
-  taskId: string, suffix: string
+  taskId: string, suffix: string, milestoneTitle?: string
 ): string {
   const sDir = resolveSlicePath(basePath, milestoneId, sliceId);
   const phaseDir = resolveMilestonePath(basePath, milestoneId);
@@ -1044,6 +1101,6 @@ export function relTaskFile(
   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/src/resources/extensions/gsd/post-unit-hooks.ts

@@ -11,6 +11,7 @@ import type {
   HookStatusEntry,
   PostUnitGateBlock,
 } from "./types.js";
+import type { SidecarItem } from "./auto/session.js";
 import { getOrCreateRegistry, resolveHookArtifactPath } from "./rule-registry.js";
 
 // Re-export resolveHookArtifactPath so existing importers still work.
@@ -75,6 +76,37 @@ export function restoreHookState(basePath: string): void {
   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: string,
+  sidecarQueue: SidecarItem[],
+): void {
+  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: string): void {
   getOrCreateRegistry().clearPersistedState(basePath);
 }