gsd-pi 2.32.0-dev.f3d5d53 → 2.33.0-dev.69bff0f

package/README.md

@@ -24,24 +24,19 @@ One command. Walk away. Come back to a built project with clean git history.
 
 ---
 
-## What's New in v2.32
-
-- **Simplified pipeline** — research merged into planning, mechanical completion (ADR-003)
-- **Always-on health widget** — 🟢🟡🔴 traffic-light indicator in the progress widget and visualizer health tab
-- **Environment health checks** — progress scoring and status integration for auto-mode
-- **Extension registry** — user-managed enable/disable for bundled and custom extensions
-- **Built-in skill authoring** — create and distribute custom skills from within GSD
-- **Workflow templates** — right-sized workflows for every task type (research, plan, execute, complete)
-- **AWS Bedrock auth** — automatic credential refresh via the new `aws-auth` extension
-- **`-w` / `--worktree` CLI flag** — launch isolated worktree sessions from the command line
-- **Native MCP client** — replaced MCPorter with a built-in MCP client for better reliability
-- **External state directory** — `.gsd/` now lives in `~/.gsd/projects/` with a symlink (ADR-002)
-- **Model health indicator** — live health status based on error trends and consecutive failures
-- **Quick-task branch cleanup** — `/gsd quick` branches auto-merge back after completion
-- **Windows EPERM fallback** — migration rename uses copy+delete when NTFS blocks rename
-- **Worktree identity fix** — stable project hash across worktrees and main repo
-- **Crash recovery guidance** — actionable next-step messages based on what was interrupted
-- **UAT verdict gating** — non-PASS verdicts now block slice progression instead of being ignored
+## What's New in v2.33
+
+- **Dispatch loop hardening** — defensive guards, reentrancy protection, and 125 new regression tests covering the full `deriveState → resolveDispatch` chain without an LLM
+- **Live regression test harness** — post-build pipeline validation that catches dispatch, parser, and lock lifecycle regressions before promotion
+- **Unified error handling** — `getErrorMessage()` helper replaces 65 inline duplicates across the codebase
+- **Centralized unit ID parsing** — `parseUnitId()` eliminates fragile regex patterns scattered across dispatch, recovery, and metrics code
+- **Milestone merge consolidation** — `tryMergeMilestone()` replaces 4 duplicate merge paths in the auto-mode loop
+- **Lock alignment fix** — retry lock path now matches primary lock settings, preventing `ECOMPROMISED` errors on resume
+- **NixOS/nix-darwin support** — symlinks in `.gsd/` are skipped during `makeTreeWritable` to prevent `EPERM` failures
+- **Windows EPERM fallback** — `.gsd/` migration uses copy+delete when NTFS blocks direct rename
+- **Worktree identity fix** — stable project hash resolved from main repo root, not worktree path
+- **Quick-task branch cleanup** — `/gsd quick` branches auto-merge back to the original branch after completion
+- **Crash recovery guidance** — actionable next-step messages based on what was interrupted and what state survived
 
 See the full [Changelog](./CHANGELOG.md) for details.
 

package/dist/resources/extensions/gsd/auto-dashboard.ts

@@ -20,6 +20,7 @@ import { parseRoadmap, parsePlan } from "./files.js";
 import { readFileSync, existsSync } from "node:fs";
 import { truncateToWidth, visibleWidth } from "@gsd/pi-tui";
 import { makeUI, GLYPH, INDENT } from "../shared/mod.js";
+import { parseUnitId } from "./unit-id.js";
 
 // ─── Dashboard Data ───────────────────────────────────────────────────────────
 
@@ -372,8 +373,9 @@ export function updateProgressWidget(
         lines.push("");
 
         const isHook = unitType.startsWith("hook/");
+        const hookParsed = isHook ? parseUnitId(unitId) : undefined;
         const target = isHook
-          ? (unitId.split("/").pop() ?? unitId)
+          ? (hookParsed!.task ?? hookParsed!.slice ?? unitId)
           : (task ? `${task.id}: ${task.title}` : unitId);
         const actionLeft = `${pad}${theme.fg("accent", "▸")} ${theme.fg("accent", verb)}  ${theme.fg("text", target)}`;
         const tierTag = tierBadge ? theme.fg("dim", `[${tierBadge}] `) : "";

package/dist/resources/extensions/gsd/auto-dispatch.ts

@@ -65,6 +65,28 @@ export function resetRewriteCircuitBreaker(): void {
   rewriteAttemptCount = 0;
 }
 
+/**
+ * Guard for accessing activeSlice/activeTask in dispatch rules.
+ * Returns a stop action if the expected ref is null (corrupt state).
+ */
+function requireSlice(state: GSDState): { sid: string; sTitle: string } | DispatchAction {
+  if (!state.activeSlice) {
+    return { action: "stop", reason: `Phase "${state.phase}" but no active slice — run /gsd doctor.`, level: "error" };
+  }
+  return { sid: state.activeSlice.id, sTitle: state.activeSlice.title };
+}
+
+function requireTask(state: GSDState): { sid: string; sTitle: string; tid: string; tTitle: string } | DispatchAction {
+  if (!state.activeSlice || !state.activeTask) {
+    return { action: "stop", reason: `Phase "${state.phase}" but no active slice/task — run /gsd doctor.`, level: "error" };
+  }
+  return { sid: state.activeSlice.id, sTitle: state.activeSlice.title, tid: state.activeTask.id, tTitle: state.activeTask.title };
+}
+
+function isStopAction(v: unknown): v is DispatchAction {
+  return typeof v === "object" && v !== null && "action" in v;
+}
+
 // ─── Rules ────────────────────────────────────────────────────────────────
 
 const DISPATCH_RULES: DispatchRule[] = [
@@ -93,8 +115,9 @@ const DISPATCH_RULES: DispatchRule[] = [
     name: "summarizing → complete-slice",
     match: async ({ state, mid, midTitle, basePath }) => {
       if (state.phase !== "summarizing") return null;
-      const sid = state.activeSlice!.id;
-      const sTitle = state.activeSlice!.title;
+      const sliceRef = requireSlice(state);
+      if (isStopAction(sliceRef)) return sliceRef as DispatchAction;
+      const { sid, sTitle } = sliceRef;
       return {
         action: "dispatch",
         unitType: "complete-slice",
@@ -222,8 +245,9 @@ const DISPATCH_RULES: DispatchRule[] = [
       if (state.phase !== "planning") return null;
       // Phase skip: skip research when preference or profile says so
       if (prefs?.phases?.skip_research || prefs?.phases?.skip_slice_research) return null;
-      const sid = state.activeSlice!.id;
-      const sTitle = state.activeSlice!.title;
+      const sliceRef = requireSlice(state);
+      if (isStopAction(sliceRef)) return sliceRef as DispatchAction;
+      const { sid, sTitle } = sliceRef;
       const researchFile = resolveSliceFile(basePath, mid, sid, "RESEARCH");
       if (researchFile) return null; // has research, fall through
       // Skip slice research for S01 when milestone research already exists —
@@ -242,8 +266,9 @@ const DISPATCH_RULES: DispatchRule[] = [
     name: "planning → plan-slice",
     match: async ({ state, mid, midTitle, basePath }) => {
       if (state.phase !== "planning") return null;
-      const sid = state.activeSlice!.id;
-      const sTitle = state.activeSlice!.title;
+      const sliceRef = requireSlice(state);
+      if (isStopAction(sliceRef)) return sliceRef as DispatchAction;
+      const { sid, sTitle } = sliceRef;
       return {
         action: "dispatch",
         unitType: "plan-slice",
@@ -256,8 +281,9 @@ const DISPATCH_RULES: DispatchRule[] = [
     name: "replanning-slice → replan-slice",
     match: async ({ state, mid, midTitle, basePath }) => {
       if (state.phase !== "replanning-slice") return null;
-      const sid = state.activeSlice!.id;
-      const sTitle = state.activeSlice!.title;
+      const sliceRef = requireSlice(state);
+      if (isStopAction(sliceRef)) return sliceRef as DispatchAction;
+      const { sid, sTitle } = sliceRef;
       return {
         action: "dispatch",
         unitType: "replan-slice",
@@ -270,8 +296,9 @@ const DISPATCH_RULES: DispatchRule[] = [
     name: "executing → execute-task (recover missing task plan → plan-slice)",
     match: async ({ state, mid, midTitle, basePath }) => {
       if (state.phase !== "executing" || !state.activeTask) return null;
-      const sid = state.activeSlice!.id;
-      const sTitle = state.activeSlice!.title;
+      const sliceRef = requireSlice(state);
+      if (isStopAction(sliceRef)) return sliceRef as DispatchAction;
+      const { sid, sTitle } = sliceRef;
       const tid = state.activeTask.id;
 
       // Guard: if the slice plan exists but the individual task plan files are
@@ -296,8 +323,9 @@ const DISPATCH_RULES: DispatchRule[] = [
     name: "executing → execute-task",
     match: async ({ state, mid, basePath }) => {
       if (state.phase !== "executing" || !state.activeTask) return null;
-      const sid = state.activeSlice!.id;
-      const sTitle = state.activeSlice!.title;
+      const sliceRef = requireSlice(state);
+      if (isStopAction(sliceRef)) return sliceRef as DispatchAction;
+      const { sid, sTitle } = sliceRef;
       const tid = state.activeTask.id;
       const tTitle = state.activeTask.title;
 

package/dist/resources/extensions/gsd/auto-idempotency.ts

@@ -18,6 +18,7 @@ import {
 import { resolveMilestoneFile } from "./paths.js";
 import { MAX_CONSECUTIVE_SKIPS, MAX_LIFETIME_DISPATCHES } from "./auto/session.js";
 import type { AutoSession } from "./auto/session.js";
+import { parseUnitId } from "./unit-id.js";
 
 export interface IdempotencyContext {
   s: AutoSession;
@@ -54,7 +55,7 @@ export function checkIdempotency(ictx: IdempotencyContext): IdempotencyResult {
       s.unitConsecutiveSkips.set(idempotencyKey, skipCount);
       if (skipCount > MAX_CONSECUTIVE_SKIPS) {
         // Cross-check: verify the unit's milestone is still active (#790)
-        const skippedMid = unitId.split("/")[0];
+        const skippedMid = parseUnitId(unitId).milestone;
         const skippedMilestoneComplete = skippedMid
           ? !!resolveMilestoneFile(basePath, skippedMid, "SUMMARY")
           : false;
@@ -110,7 +111,7 @@ export function checkIdempotency(ictx: IdempotencyContext): IdempotencyResult {
     const skipCount2 = (s.unitConsecutiveSkips.get(idempotencyKey) ?? 0) + 1;
     s.unitConsecutiveSkips.set(idempotencyKey, skipCount2);
     if (skipCount2 > MAX_CONSECUTIVE_SKIPS) {
-      const skippedMid2 = unitId.split("/")[0];
+      const skippedMid2 = parseUnitId(unitId).milestone;
       const skippedMilestoneComplete2 = skippedMid2
         ? !!resolveMilestoneFile(basePath, skippedMid2, "SUMMARY")
         : false;

package/dist/resources/extensions/gsd/auto-observability.ts

@@ -12,6 +12,7 @@ import {
   formatValidationIssues,
 } from "./observability-validator.js";
 import type { ValidationIssue } from "./observability-validator.js";
+import { parseUnitId } from "./unit-id.js";
 
 export async function collectObservabilityWarnings(
   ctx: ExtensionContext,
@@ -22,10 +23,7 @@ export async function collectObservabilityWarnings(
   // Hook units have custom artifacts — skip standard observability checks
   if (unitType.startsWith("hook/")) return [];
 
-  const parts = unitId.split("/");
-  const mid = parts[0];
-  const sid = parts[1];
-  const tid = parts[2];
+  const { milestone: mid, slice: sid, task: tid } = parseUnitId(unitId);
 
   if (!mid || !sid) return [];
 

package/dist/resources/extensions/gsd/auto-post-unit.ts

@@ -61,6 +61,7 @@ import {
 } from "./auto-dashboard.js";
 import { join } from "node:path";
 import { STATE_REBUILD_MIN_INTERVAL_MS } from "./auto-constants.js";
+import { parseUnitId } from "./unit-id.js";
 
 /**
  * Initialize a unit dispatch: stamp the current time, set `s.currentUnit`,
@@ -134,8 +135,7 @@ export async function postUnitPreVerification(pctx: PostUnitContext): Promise<"d
       let taskContext: TaskCommitContext | undefined;
 
       if (s.currentUnit.type === "execute-task") {
-        const parts = s.currentUnit.id.split("/");
-        const [mid, sid, tid] = parts;
+        const { milestone: mid, slice: sid, task: tid } = parseUnitId(s.currentUnit.id);
         if (mid && sid && tid) {
           const summaryPath = resolveTaskFile(s.basePath, mid, sid, tid, "SUMMARY");
           if (summaryPath) {
@@ -167,8 +167,8 @@ export async function postUnitPreVerification(pctx: PostUnitContext): Promise<"d
 
     // Doctor: fix mechanical bookkeeping
     try {
-      const scopeParts = s.currentUnit.id.split("/").slice(0, 2);
-      const doctorScope = scopeParts.join("/");
+      const { milestone, slice } = parseUnitId(s.currentUnit.id);
+      const doctorScope = slice ? `${milestone}/${slice}` : milestone;
       const sliceTerminalUnits = new Set(["complete-slice", "run-uat"]);
       const effectiveFixLevel = sliceTerminalUnits.has(s.currentUnit.type) ? "all" as const : "task" as const;
       const report = await runGSDDoctor(s.basePath, { fix: true, scope: doctorScope, fixLevel: effectiveFixLevel });
@@ -348,7 +348,7 @@ export async function postUnitPostVerification(pctx: PostUnitContext): Promise<"
   // instead of dispatching LLM sessions for complete-slice / validate-milestone.
   if (s.currentUnit?.type === "execute-task" && !s.stepMode) {
     try {
-      const [mid, sid] = s.currentUnit.id.split("/");
+      const { milestone: mid, slice: sid } = parseUnitId(s.currentUnit.id);
       if (mid && sid) {
         const state = await deriveState(s.basePath);
         if (state.phase === "summarizing" && state.activeSlice?.id === sid) {

package/dist/resources/extensions/gsd/auto-recovery.ts

@@ -42,6 +42,7 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync, unlinkSync } from "
 import { atomicWriteSync } from "./atomic-write.js";
 import { loadJsonFileOrNull } from "./json-persistence.js";
 import { dirname, join } from "node:path";
+import { parseUnitId } from "./unit-id.js";
 
 // ─── Artifact Resolution & Verification ───────────────────────────────────────
 
@@ -49,9 +50,7 @@ import { dirname, join } from "node:path";
  * Resolve the expected artifact for a unit to an absolute path.
  */
 export function resolveExpectedArtifactPath(unitType: string, unitId: string, base: string): string | null {
-  const parts = unitId.split("/");
-  const mid = parts[0]!;
-  const sid = parts[1];
+  const { milestone: mid, slice: sid, task: tid } = parseUnitId(unitId);
   switch (unitType) {
     case "research-milestone": {
       const dir = resolveMilestonePath(base, mid);
@@ -78,7 +77,6 @@ export function resolveExpectedArtifactPath(unitType: string, unitId: string, ba
       return dir ? join(dir, buildSliceFileName(sid!, "UAT-RESULT")) : null;
     }
     case "execute-task": {
-      const tid = parts[2];
       const dir = resolveSlicePath(base, mid, sid!);
       return dir && tid ? join(dir, "tasks", buildTaskFileName(tid, "SUMMARY")) : null;
     }
@@ -167,10 +165,7 @@ export function verifyExpectedArtifact(unitType: string, unitId: string, base: s
 
   // execute-task must also have its checkbox marked [x] in the slice plan
   if (unitType === "execute-task") {
-    const parts = unitId.split("/");
-    const mid = parts[0];
-    const sid = parts[1];
-    const tid = parts[2];
+    const { milestone: mid, slice: sid, task: tid } = parseUnitId(unitId);
     if (mid && sid && tid) {
       const planAbs = resolveSliceFile(base, mid, sid, "PLAN");
       if (planAbs && existsSync(planAbs)) {
@@ -187,9 +182,7 @@ export function verifyExpectedArtifact(unitType: string, unitId: string, base: s
   // but omitted T{tid}-PLAN.md files would be marked complete, causing execute-task
   // to dispatch with a missing task plan (see issue #739).
   if (unitType === "plan-slice") {
-    const parts = unitId.split("/");
-    const mid = parts[0];
-    const sid = parts[1];
+    const { milestone: mid, slice: sid } = parseUnitId(unitId);
     if (mid && sid) {
       try {
         const planContent = readFileSync(absPath, "utf-8");
@@ -213,9 +206,8 @@ export function verifyExpectedArtifact(unitType: string, unitId: string, base: s
   // state machine keeps returning the same complete-slice unit (roadmap still shows
   // the slice incomplete), so dispatchNextUnit recurses forever.
   if (unitType === "complete-slice") {
-    const parts = unitId.split("/");
-    const mid = parts[0];
-    const sid = parts[1];
+    const { milestone: mid, slice: sid } = parseUnitId(unitId);
+
     if (mid && sid) {
       const dir = resolveSlicePath(base, mid, sid);
       if (dir) {
@@ -268,9 +260,7 @@ export function writeBlockerPlaceholder(unitType: string, unitId: string, base:
 }
 
 export function diagnoseExpectedArtifact(unitType: string, unitId: string, base: string): string | null {
-  const parts = unitId.split("/");
-  const mid = parts[0];
-  const sid = parts[1];
+  const { milestone: mid, slice: sid, task: tid } = parseUnitId(unitId);
   switch (unitType) {
     case "research-milestone":
       return `${relMilestoneFile(base, mid!, "RESEARCH")} (milestone research)`;
@@ -281,7 +271,6 @@ export function diagnoseExpectedArtifact(unitType: string, unitId: string, base:
     case "plan-slice":
       return `${relSliceFile(base, mid!, sid!, "PLAN")} (slice plan)`;
     case "execute-task": {
-      const tid = parts[2];
       return `Task ${tid} marked [x] in ${relSliceFile(base, mid!, sid!, "PLAN")} + summary written`;
     }
     case "complete-slice":
@@ -539,10 +528,7 @@ export async function selfHealRuntimeRecords(
  * These are shown when automatic reconciliation is not possible.
  */
 export function buildLoopRemediationSteps(unitType: string, unitId: string, base: string): string | null {
-  const parts = unitId.split("/");
-  const mid = parts[0];
-  const sid = parts[1];
-  const tid = parts[2];
+  const { milestone: mid, slice: sid, task: tid } = parseUnitId(unitId);
   switch (unitType) {
     case "execute-task": {
       if (!mid || !sid || !tid) break;

package/dist/resources/extensions/gsd/auto-start.ts

@@ -64,6 +64,7 @@ import type { AutoSession } from "./auto/session.js";
 import { existsSync, mkdirSync, readdirSync, statSync, unlinkSync } from "node:fs";
 import { join } from "node:path";
 import { getErrorMessage } from "./error-utils.js";
+import { parseUnitId } from "./unit-id.js";
 
 export interface BootstrapDeps {
   shouldUseWorktreeIsolation: () => boolean;
@@ -139,7 +140,7 @@ export async function bootstrapAutoSession(
   if (crashLock && crashLock.pid !== process.pid) {
     // We already hold the session lock, so no concurrent session is running.
     // The crash lock is from a dead process — recover context from it.
-    const recoveredMid = crashLock.unitId.split("/")[0];
+    const recoveredMid = parseUnitId(crashLock.unitId).milestone;
     const milestoneAlreadyComplete = recoveredMid
       ? !!resolveMilestoneFile(base, recoveredMid, "SUMMARY")
       : false;

package/dist/resources/extensions/gsd/auto-stuck-detection.ts

@@ -39,6 +39,7 @@ import {
 import type { AutoSession } from "./auto/session.js";
 import { existsSync, mkdirSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
+import { parseUnitId } from "./unit-id.js";
 
 export interface StuckContext {
   s: AutoSession;
@@ -99,7 +100,7 @@ export async function checkStuckAndRecover(sctx: StuckContext): Promise<StuckRes
 
     // Final reconciliation pass for execute-task
     if (unitType === "execute-task") {
-      const [mid, sid, tid] = unitId.split("/");
+      const { milestone: mid, slice: sid, task: tid } = parseUnitId(unitId);
       if (mid && sid && tid) {
         const status = await inspectExecuteTaskDurability(basePath, unitId);
         if (status) {
@@ -168,7 +169,7 @@ export async function checkStuckAndRecover(sctx: StuckContext): Promise<StuckRes
     // Adaptive self-repair: each retry attempts a different remediation step.
     if (unitType === "execute-task") {
       const status = await inspectExecuteTaskDurability(basePath, unitId);
-      const [mid, sid, tid] = unitId.split("/");
+      const { milestone: mid, slice: sid, task: tid } = parseUnitId(unitId);
       if (status && mid && sid && tid) {
         if (status.summaryExists && !status.taskChecked) {
           const repaired = skipExecuteTask(basePath, mid, sid, tid, status, "self-repair", 0);

package/dist/resources/extensions/gsd/auto-supervisor.ts

@@ -1,5 +1,5 @@
 /**
- * Auto-mode Supervisor — SIGTERM handling and working-tree activity detection.
+ * Auto-mode Supervisor — signal handling and working-tree activity detection.
  *
  * Pure functions — no module-level globals or AutoContext dependency.
  */
@@ -8,10 +8,10 @@ import { clearLock } from "./crash-recovery.js";
 import { releaseSessionLock } from "./session-lock.js";
 import { nativeHasChanges } from "./native-git-bridge.js";
 
-// ─── SIGTERM Handling ─────────────────────────────────────────────────────────
+// ─── Signal Handling ──────────────────────────────────────────────────────────
 
 /**
- * Register a SIGTERM handler that clears the lock file and exits cleanly.
+ * Register SIGTERM and SIGINT handlers that clear lock files and exit cleanly.
  * Captures the active base path at registration time so the handler
  * always references the correct path even if the module variable changes.
  * Removes any previously registered handler before installing the new one.
@@ -22,20 +22,25 @@ export function registerSigtermHandler(
   currentBasePath: string,
   previousHandler: (() => void) | null,
 ): () => void {
-  if (previousHandler) process.off("SIGTERM", previousHandler);
+  if (previousHandler) {
+    process.off("SIGTERM", previousHandler);
+    process.off("SIGINT", previousHandler);
+  }
   const handler = () => {
     releaseSessionLock(currentBasePath);
     clearLock(currentBasePath);
     process.exit(0);
   };
   process.on("SIGTERM", handler);
+  process.on("SIGINT", handler);
   return handler;
 }
 
-/** Deregister the SIGTERM handler (called on stop/pause). */
+/** Deregister signal handlers (called on stop/pause). */
 export function deregisterSigtermHandler(handler: (() => void) | null): void {
   if (handler) {
     process.off("SIGTERM", handler);
+    process.off("SIGINT", handler);
   }
 }
 

package/dist/resources/extensions/gsd/auto-timeout-recovery.ts

@@ -18,6 +18,7 @@ import {
   writeBlockerPlaceholder,
 } from "./auto-recovery.js";
 import { existsSync } from "node:fs";
+import { parseUnitId } from "./unit-id.js";
 
 export interface RecoveryContext {
   basePath: string;
@@ -128,7 +129,7 @@ export async function recoverTimedOutUnit(
 
     // Retries exhausted — write missing durable artifacts and advance.
     const diagnostic = formatExecuteTaskRecoveryStatus(status);
-    const [mid, sid, tid] = unitId.split("/");
+    const { milestone: mid, slice: sid, task: tid } = parseUnitId(unitId);
     const skipped = mid && sid && tid
       ? skipExecuteTask(basePath, mid, sid, tid, status, reason, maxRecoveryAttempts)
       : false;

package/dist/resources/extensions/gsd/auto-verification.ts

@@ -25,6 +25,7 @@ import { removePersistedKey } from "./auto-recovery.js";
 import type { AutoSession, PendingVerificationRetry } from "./auto/session.js";
 import { join } from "node:path";
 import { getErrorMessage } from "./error-utils.js";
+import { parseUnitId } from "./unit-id.js";
 
 export interface VerificationContext {
   s: AutoSession;
@@ -58,10 +59,9 @@ export async function runPostUnitVerification(
     const prefs = effectivePrefs?.preferences;
 
     // Read task plan verify field
-    const parts = s.currentUnit.id.split("/");
+    const { milestone: mid, slice: sid, task: tid } = parseUnitId(s.currentUnit.id);
     let taskPlanVerify: string | undefined;
-    if (parts.length >= 3) {
-      const [mid, sid, tid] = parts;
+    if (mid && sid && tid) {
       const planFile = resolveSliceFile(s.basePath, mid, sid, "PLAN");
       if (planFile) {
         const planContent = await loadFile(planFile);
@@ -153,9 +153,8 @@ export async function runPostUnitVerification(
 
     // Write verification evidence JSON
     const attempt = s.verificationRetryCount.get(s.currentUnit.id) ?? 0;
-    if (parts.length >= 3) {
+    if (mid && sid && tid) {
       try {
-        const [mid, sid, tid] = parts;
         const sDir = resolveSlicePath(s.basePath, mid, sid);
         if (sDir) {
           const tasksDir = join(sDir, "tasks");

package/dist/resources/extensions/gsd/auto-worktree.ts

@@ -6,7 +6,7 @@
  * manages create, enter, detect, and teardown for auto-mode worktrees.
  */
 
-import { existsSync, readFileSync, realpathSync, unlinkSync, statSync, rmSync } from "node:fs";
+import { existsSync, readFileSync, realpathSync, unlinkSync, statSync, rmSync, readdirSync, cpSync, lstatSync as lstatSyncFn } from "node:fs";
 import { isAbsolute, join, sep } from "node:path";
 import { GSDError, GSD_IO_ERROR, GSD_GIT_ERROR } from "./errors.js";
 import { execSync, execFileSync } from "node:child_process";
@@ -45,6 +45,122 @@ import { getErrorMessage } from "./error-utils.js";
 /** Original project root before chdir into auto-worktree. */
 let originalBase: string | null = null;
 
+// ─── Worktree ↔ Main Repo Sync (#1311) ──────────────────────────────────────
+
+/**
+ * Sync .gsd/ state from the main repo into the worktree.
+ *
+ * When .gsd/ is a symlink to the external state directory, both the main
+ * repo and worktree share the same directory — no sync needed.
+ *
+ * When .gsd/ is a real directory (e.g., git-tracked or manage_gitignore:false),
+ * the worktree has its own copy that may be stale. This function copies
+ * missing milestones, CONTEXT, ROADMAP, DECISIONS, REQUIREMENTS, and
+ * PROJECT files from the main repo's .gsd/ into the worktree's .gsd/.
+ *
+ * Only adds missing content — never overwrites existing files in the worktree
+ * (the worktree's execution state is authoritative for in-progress work).
+ */
+export function syncGsdStateToWorktree(mainBasePath: string, worktreePath_: string): { synced: string[] } {
+  const mainGsd = gsdRoot(mainBasePath);
+  const wtGsd = gsdRoot(worktreePath_);
+  const synced: string[] = [];
+
+  // If both resolve to the same directory (symlink), no sync needed
+  try {
+    const mainResolved = realpathSync(mainGsd);
+    const wtResolved = realpathSync(wtGsd);
+    if (mainResolved === wtResolved) return { synced };
+  } catch {
+    // Can't resolve — proceed with sync as a safety measure
+  }
+
+  if (!existsSync(mainGsd) || !existsSync(wtGsd)) return { synced };
+
+  // Sync root-level .gsd/ files (DECISIONS, REQUIREMENTS, PROJECT, KNOWLEDGE)
+  const rootFiles = ["DECISIONS.md", "REQUIREMENTS.md", "PROJECT.md", "KNOWLEDGE.md", "OVERRIDES.md"];
+  for (const f of rootFiles) {
+    const src = join(mainGsd, f);
+    const dst = join(wtGsd, f);
+    if (existsSync(src) && !existsSync(dst)) {
+      try {
+        cpSync(src, dst);
+        synced.push(f);
+      } catch { /* non-fatal */ }
+    }
+  }
+
+  // Sync milestones: copy entire milestone directories that are missing
+  const mainMilestonesDir = join(mainGsd, "milestones");
+  const wtMilestonesDir = join(wtGsd, "milestones");
+  if (existsSync(mainMilestonesDir) && existsSync(wtMilestonesDir)) {
+    try {
+      const mainMilestones = readdirSync(mainMilestonesDir, { withFileTypes: true })
+        .filter(d => d.isDirectory() && /^M\d{3}/.test(d.name))
+        .map(d => d.name);
+
+      for (const mid of mainMilestones) {
+        const srcDir = join(mainMilestonesDir, mid);
+        const dstDir = join(wtMilestonesDir, mid);
+
+        if (!existsSync(dstDir)) {
+          // Entire milestone missing from worktree — copy it
+          try {
+            cpSync(srcDir, dstDir, { recursive: true });
+            synced.push(`milestones/${mid}/`);
+          } catch { /* non-fatal */ }
+        } else {
+          // Milestone directory exists but may be missing files (stale snapshot).
+          // Sync individual top-level milestone files (CONTEXT, ROADMAP, RESEARCH, etc.)
+          try {
+            const srcFiles = readdirSync(srcDir).filter(f => f.endsWith(".md") || f.endsWith(".json"));
+            for (const f of srcFiles) {
+              const srcFile = join(srcDir, f);
+              const dstFile = join(dstDir, f);
+              if (!existsSync(dstFile)) {
+                try {
+                  const srcStat = lstatSyncFn(srcFile);
+                  if (srcStat.isFile()) {
+                    cpSync(srcFile, dstFile);
+                    synced.push(`milestones/${mid}/${f}`);
+                  }
+                } catch { /* non-fatal */ }
+              }
+            }
+
+            // Sync slices directory if it exists in main but not in worktree
+            const srcSlicesDir = join(srcDir, "slices");
+            const dstSlicesDir = join(dstDir, "slices");
+            if (existsSync(srcSlicesDir) && !existsSync(dstSlicesDir)) {
+              try {
+                cpSync(srcSlicesDir, dstSlicesDir, { recursive: true });
+                synced.push(`milestones/${mid}/slices/`);
+              } catch { /* non-fatal */ }
+            } else if (existsSync(srcSlicesDir) && existsSync(dstSlicesDir)) {
+              // Both exist — sync missing slice directories
+              const srcSlices = readdirSync(srcSlicesDir, { withFileTypes: true })
+                .filter(d => d.isDirectory())
+                .map(d => d.name);
+              for (const sid of srcSlices) {
+                const srcSlice = join(srcSlicesDir, sid);
+                const dstSlice = join(dstSlicesDir, sid);
+                if (!existsSync(dstSlice)) {
+                  try {
+                    cpSync(srcSlice, dstSlice, { recursive: true });
+                    synced.push(`milestones/${mid}/slices/${sid}/`);
+                  } catch { /* non-fatal */ }
+                }
+              }
+            }
+          } catch { /* non-fatal */ }
+        }
+      }
+    } catch { /* non-fatal */ }
+  }
+
+  return { synced };
+}
+
 // ─── Worktree Post-Create Hook (#597) ────────────────────────────────────────
 
 /**
@@ -125,6 +241,12 @@ export function createAutoWorktree(basePath: string, milestoneId: string): strin
   // Ensure worktree shares external state via symlink
   ensureGsdSymlink(info.path);
 
+  // Sync .gsd/ state from main repo into the worktree (#1311).
+  // Even with the symlink, the worktree may have stale git-tracked files
+  // if .gsd/ is not gitignored. And on fresh create, the milestone files
+  // created on main since the branch point won't be in the worktree.
+  syncGsdStateToWorktree(basePath, info.path);
+
   // Run user-configured post-create hook (#597) — e.g. copy .env, symlink assets
   const hookError = runWorktreePostCreateHook(basePath, info.path);
   if (hookError) {
@@ -267,6 +389,18 @@ export function enterAutoWorktree(basePath: string, milestoneId: string): string
     throw new GSDError(GSD_IO_ERROR, `Auto-worktree path ${p} exists but .git is unreadable`);
   }
 
+  // Ensure worktree shares external state via symlink (#1311).
+  // On resume (enterAutoWorktree), the symlink may be missing if it was
+  // created before ensureGsdSymlink existed, or the .gsd/ directory may be
+  // a stale git-tracked copy instead of a symlink. Refreshing here ensures
+  // the worktree sees the same milestone state as the main repo.
+  ensureGsdSymlink(p);
+
+  // Sync .gsd/ state from main repo into worktree (#1311).
+  // Covers the case where .gsd/ is a real directory (not symlinked) and
+  // milestones were created on main after the worktree was last used.
+  syncGsdStateToWorktree(basePath, p);
+
   const previousCwd = process.cwd();
 
   try {