gsd-pi 2.11.0 → 2.12.0

package/dist/onboarding.js

@@ -48,6 +48,7 @@ const LLM_PROVIDER_IDS = [
     'xai',
     'openrouter',
     'mistral',
+    'ollama-cloud',
     'custom-openai',
 ];
 /** API key prefix validation — loose checks to catch obvious mistakes */
@@ -61,6 +62,7 @@ const OTHER_PROVIDERS = [
     { value: 'xai', label: 'xAI (Grok)' },
     { value: 'openrouter', label: 'OpenRouter' },
     { value: 'mistral', label: 'Mistral' },
+    { value: 'ollama-cloud', label: 'Ollama Cloud' },
     { value: 'custom-openai', label: 'Custom (OpenAI-compatible)' },
 ];
 // ─── Dynamic imports ──────────────────────────────────────────────────────────
@@ -755,6 +757,7 @@ export function loadStoredEnvKeys(authStorage) {
         ['slack_bot', 'SLACK_BOT_TOKEN'],
         ['discord_bot', 'DISCORD_BOT_TOKEN'],
         ['groq', 'GROQ_API_KEY'],
+        ['ollama-cloud', 'OLLAMA_API_KEY'],
         ['custom-openai', 'CUSTOM_OPENAI_API_KEY'],
     ];
     for (const [provider, envVar] of providers) {

package/dist/resources/extensions/bg-shell/index.ts

@@ -574,6 +574,7 @@ interface StartOptions {
 	type?: ProcessType;
 	readyPattern?: string;
 	readyPort?: number;
+	readyTimeout?: number;
 	group?: string;
 	env?: Record<string, string>;
 }
@@ -689,7 +690,7 @@ function startProcess(opts: StartOptions): BgProcess {
 
 	// Port probing for server-type processes
 	if (bg.readyPort) {
-		startPortProbing(bg, bg.readyPort);
+		startPortProbing(bg, bg.readyPort, opts.readyTimeout);
 	}
 
 	// Shell sessions are ready immediately after spawn
@@ -707,9 +708,17 @@ function startProcess(opts: StartOptions): BgProcess {
 
 // ── Port Probing Loop ──────────────────────────────────────────────────────
 
-function startPortProbing(bg: BgProcess, port: number): void {
+function startPortProbing(bg: BgProcess, port: number, customTimeout?: number): void {
+	const timeout = customTimeout || DEFAULT_READY_TIMEOUT;
 	const interval = setInterval(async () => {
-		if (!bg.alive || bg.status !== "starting") {
+		if (!bg.alive) {
+			clearInterval(interval);
+			const stderrLines = bg.output.filter(l => l.stream === "stderr").slice(-10).map(l => l.line);
+			const detail = `Process exited (code ${bg.exitCode}) before port ${port} opened${stderrLines.length > 0 ? ` — ${stderrLines.join("; ").slice(0, 200)}` : ""}`;
+			addEvent(bg, { type: "port_timeout", detail, data: { port, exitCode: bg.exitCode } });
+			return;
+		}
+		if (bg.status !== "starting") {
 			clearInterval(interval);
 			return;
 		}
@@ -722,8 +731,18 @@ function startPortProbing(bg: BgProcess, port: number): void {
 		}
 	}, READY_POLL_INTERVAL);
 
-	// Stop probing after timeout
-	setTimeout(() => clearInterval(interval), DEFAULT_READY_TIMEOUT);
+	// Stop probing after timeout — transition to error state so the process
+	// doesn't stay in "starting" forever (fixes #428)
+	setTimeout(() => {
+		clearInterval(interval);
+		if (bg.alive && bg.status === "starting") {
+			const stderrLines = bg.output.filter(l => l.stream === "stderr").slice(-10).map(l => l.line);
+			const detail = `Port ${port} not open after ${timeout}ms${stderrLines.length > 0 ? ` — ${stderrLines.join("; ").slice(0, 200)}` : ""}`;
+			bg.status = "error";
+			addEvent(bg, { type: "port_timeout", detail, data: { port, timeout } });
+			pushAlert(bg, `Port ${port} readiness timeout after ${timeout / 1000}s`);
+		}
+	}, timeout);
 }
 
 // ── Process Kill ───────────────────────────────────────────────────────────
@@ -864,9 +883,19 @@ async function waitForReady(bg: BgProcess, timeout: number, signal?: AbortSignal
 			return { ready: false, detail: "Cancelled" };
 		}
 		if (!bg.alive) {
+			const stderrLines = bg.output.filter(l => l.stream === "stderr").slice(-5).map(l => l.line);
+			const stderrContext = stderrLines.length > 0 ? `\nstderr:\n${stderrLines.join("\n").slice(0, 500)}` : "";
+			return {
+				ready: false,
+				detail: `Process exited before becoming ready (code ${bg.exitCode})${bg.recentErrors.length > 0 ? ` — ${bg.recentErrors.slice(-1)[0]}` : ""}${stderrContext}`,
+			};
+		}
+		if (bg.status === "error") {
+			const stderrLines = bg.output.filter(l => l.stream === "stderr").slice(-5).map(l => l.line);
+			const stderrContext = stderrLines.length > 0 ? `\nstderr:\n${stderrLines.join("\n").slice(0, 500)}` : "";
 			return {
 				ready: false,
-				detail: `Process exited before becoming ready (code ${bg.exitCode})${bg.recentErrors.length > 0 ? ` — ${bg.recentErrors.slice(-1)[0]}` : ""}`,
+				detail: `Process entered error state${bg.readyPort ? ` (port ${bg.readyPort} never opened)` : ""}${stderrContext}`,
 			};
 		}
 		if (bg.status === "ready") {
@@ -887,7 +916,9 @@ async function waitForReady(bg: BgProcess, timeout: number, signal?: AbortSignal
 		}
 	}
 
-	return { ready: false, detail: `Timed out after ${timeout}ms waiting for ready signal` };
+	const stderrLines = bg.output.filter(l => l.stream === "stderr").slice(-5).map(l => l.line);
+	const stderrContext = stderrLines.length > 0 ? `\nstderr:\n${stderrLines.join("\n").slice(0, 500)}` : "";
+	return { ready: false, detail: `Timed out after ${timeout}ms waiting for ready signal${stderrContext}` };
 }
 
 // ── Query Shell Environment ────────────────────────────────────────────────
@@ -1234,6 +1265,15 @@ export default function (pi: ExtensionAPI) {
 		cleanupAll();
 	});
 
+	// Register signal handlers to clean up bg processes on unexpected exit (fixes #428)
+	// This prevents orphan processes and helps the parent restore terminal state
+	const signalCleanup = () => {
+		cleanupAll();
+	};
+	process.on("SIGTERM", signalCleanup);
+	process.on("SIGINT", signalCleanup);
+	process.on("beforeExit", signalCleanup);
+
 	// ── Compaction Awareness: Survive Context Resets ───────────────────
 
 	/** Build a compact state summary of all alive processes for context re-injection */
@@ -1424,6 +1464,9 @@ export default function (pi: ExtensionAPI) {
 			ready_port: Type.Optional(
 				Type.Number({ description: "Port to probe for readiness (for start). When open, process is considered ready." }),
 			),
+			ready_timeout: Type.Optional(
+				Type.Number({ description: "Max milliseconds to wait for ready_port/ready_pattern before marking as error (default: 30000)" }),
+			),
 			group: Type.Optional(
 				Type.String({ description: "Group name for related processes (for start, group_status)" }),
 			),
@@ -1449,6 +1492,7 @@ export default function (pi: ExtensionAPI) {
 						type: params.type as ProcessType | undefined,
 						readyPattern: params.ready_pattern,
 						readyPort: params.ready_port,
+						readyTimeout: params.ready_timeout,
 						group: params.group,
 					});
 

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

@@ -18,17 +18,18 @@ import type {
 
 import { deriveState, invalidateStateCache } from "./state.js";
 import type { GSDState } from "./types.js";
-import { loadFile, parseContinue, parsePlan, parseRoadmap, parseSummary, extractUatType, inlinePriorMilestoneSummary, getManifestStatus } from "./files.js";
+import { loadFile, parseContinue, parsePlan, parseRoadmap, parseSummary, extractUatType, inlinePriorMilestoneSummary, getManifestStatus, clearParseCache } from "./files.js";
 export { inlinePriorMilestoneSummary };
 import type { UatType } from "./files.js";
 import { collectSecretsFromManifest } from "../get-secrets-from-user.js";
-import { loadPrompt } from "./prompt-loader.js";
+import { loadPrompt, inlineTemplate } from "./prompt-loader.js";
 import {
   gsdRoot, resolveMilestoneFile, resolveSliceFile, resolveSlicePath,
   resolveMilestonePath, resolveDir, resolveTasksDir, resolveTaskFiles, resolveTaskFile,
   relMilestoneFile, relSliceFile, relTaskFile, relSlicePath, relMilestonePath,
   milestonesDir, resolveGsdRootFile, relGsdRootFile,
   buildMilestoneFileName, buildSliceFileName, buildTaskFileName,
+  clearPathCache,
 } from "./paths.js";
 import { saveActivityLog } from "./activity-log.js";
 import { synthesizeCrashRecovery, getDeepDiagnostic } from "./session-forensics.js";
@@ -42,6 +43,18 @@ import {
 } from "./unit-runtime.js";
 import { resolveAutoSupervisorConfig, resolveModelForUnit, resolveModelWithFallbacksForUnit, resolveSkillDiscoveryMode, loadEffectiveGSDPreferences } from "./preferences.js";
 import type { GSDPreferences } from "./preferences.js";
+import {
+  checkPostUnitHooks,
+  getActiveHook,
+  resetHookState,
+  isRetryPending,
+  consumeRetryTrigger,
+  runPreDispatchHooks,
+  persistHookState,
+  restoreHookState,
+  clearPersistedHookState,
+  formatHookStatus,
+} from "./post-unit-hooks.js";
 import {
   validatePlanBoundary,
   validateExecuteBoundary,
@@ -347,6 +360,8 @@ export async function stopAuto(ctx?: ExtensionContext, pi?: ExtensionAPI): Promi
   }
 
   resetMetrics();
+  resetHookState();
+  if (basePath) clearPersistedHookState(basePath);
   active = false;
   paused = false;
   stepMode = false;
@@ -564,6 +579,8 @@ export async function startAuto(
     ctx.ui.setStatus("gsd-auto", stepMode ? "next" : "auto");
     ctx.ui.setFooter(hideFooter);
     ctx.ui.notify(stepMode ? "Step-mode resumed." : "Auto-mode resumed.", "info");
+    // Restore hook state from disk in case session was interrupted
+    restoreHookState(base);
     // Rebuild disk state before resuming — user interaction during pause may have changed files
     try { await rebuildState(base); } catch { /* non-fatal */ }
     try {
@@ -575,6 +592,8 @@ export async function startAuto(
     // Self-heal: clear stale runtime records where artifacts already exist
     await selfHealRuntimeRecords(base, ctx);
     invalidateStateCache();
+    clearParseCache();
+    clearPathCache();
     await dispatchNextUnit(ctx, pi);
     return;
   }
@@ -670,6 +689,8 @@ export async function startAuto(
   unitRecoveryCount.clear();
   completedKeySet.clear();
   loadPersistedKeys(base, completedKeySet);
+  resetHookState();
+  restoreHookState(base);
   autoStartTime = Date.now();
   completedUnits = [];
   currentUnit = null;
@@ -767,6 +788,8 @@ export async function handleAgentEnd(
   // Invalidate deriveState() cache — the unit just completed and may have
   // written planning files (task summaries, roadmap checkboxes, etc.)
   invalidateStateCache();
+  clearParseCache();
+  clearPathCache();
 
   // Small delay to let files settle (git commits, file writes)
   await new Promise(r => setTimeout(r, 500));
@@ -806,6 +829,79 @@ export async function handleAgentEnd(
     }
   }
 
+  // ── Post-unit hooks: check if a configured hook should run before normal dispatch ──
+  if (currentUnit && !stepMode) {
+    const hookUnit = checkPostUnitHooks(currentUnit.type, currentUnit.id, basePath);
+    if (hookUnit) {
+      // Dispatch the hook unit instead of normal flow
+      const hookStartedAt = Date.now();
+      if (currentUnit) {
+        const modelId = ctx.model?.id ?? "unknown";
+        snapshotUnitMetrics(ctx, currentUnit.type, currentUnit.id, currentUnit.startedAt, modelId);
+        saveActivityLog(ctx, basePath, currentUnit.type, currentUnit.id);
+      }
+      currentUnit = { type: hookUnit.unitType, id: hookUnit.unitId, startedAt: hookStartedAt };
+      writeUnitRuntimeRecord(basePath, hookUnit.unitType, hookUnit.unitId, hookStartedAt, {
+        phase: "dispatched",
+        wrapupWarningSent: false,
+        timeoutAt: null,
+        lastProgressAt: hookStartedAt,
+        progressCount: 0,
+        lastProgressKind: "dispatch",
+      });
+
+      const state = await deriveState(basePath);
+      updateProgressWidget(ctx, hookUnit.unitType, hookUnit.unitId, state);
+      const hookState = getActiveHook();
+      ctx.ui.notify(
+        `Running post-unit hook: ${hookUnit.hookName} (cycle ${hookState?.cycle ?? 1})`,
+        "info",
+      );
+
+      // Switch model if the hook specifies one
+      if (hookUnit.model) {
+        const availableModels = ctx.modelRegistry.getAvailable();
+        const match = availableModels.find(m =>
+          m.id === hookUnit.model || `${m.provider}/${m.id}` === hookUnit.model,
+        );
+        if (match) {
+          try {
+            await pi.setModel(match);
+          } catch { /* non-fatal — use current model */ }
+        }
+      }
+
+      const result = await cmdCtx!.newSession();
+      if (result.cancelled) {
+        resetHookState();
+        await stopAuto(ctx, pi);
+        return;
+      }
+      const sessionFile = ctx.sessionManager.getSessionFile();
+      writeLock(basePath, hookUnit.unitType, hookUnit.unitId, completedUnits.length, sessionFile);
+      // Persist hook state so cycle counts survive crashes
+      persistHookState(basePath);
+      pi.sendMessage(
+        { customType: "gsd-auto", content: hookUnit.prompt, display: verbose },
+        { triggerTurn: true },
+      );
+      return; // handleAgentEnd will fire again when hook session completes
+    }
+
+    // Check if a hook requested a retry of the trigger unit
+    if (isRetryPending()) {
+      const trigger = consumeRetryTrigger();
+      if (trigger) {
+        ctx.ui.notify(
+          `Hook requested retry of ${trigger.unitType} ${trigger.unitId}.`,
+          "info",
+        );
+        // Fall through to normal dispatchNextUnit — state derivation will
+        // re-select the same unit since it hasn't been marked complete
+      }
+    }
+  }
+
   // In step mode, pause and show a wizard instead of immediately dispatching
   if (stepMode) {
     await showStepWizard(ctx, pi);
@@ -949,6 +1045,7 @@ export function describeNextUnit(state: GSDState): { label: string; description:
 // ─── Progress Widget ──────────────────────────────────────────────────────
 
 function unitVerb(unitType: string): string {
+  if (unitType.startsWith("hook/")) return `hook: ${unitType.slice(5)}`;
   switch (unitType) {
     case "research-milestone":
     case "research-slice": return "researching";
@@ -965,6 +1062,7 @@ function unitVerb(unitType: string): string {
 }
 
 function unitPhaseLabel(unitType: string): string {
+  if (unitType.startsWith("hook/")) return "HOOK";
   switch (unitType) {
     case "research-milestone": return "RESEARCH";
     case "research-slice": return "RESEARCH";
@@ -981,7 +1079,14 @@ function unitPhaseLabel(unitType: string): string {
 }
 
 function peekNext(unitType: string, state: GSDState): string {
+  // Show active hook info in progress display
+  const activeHookState = getActiveHook();
+  if (activeHookState) {
+    return `hook: ${activeHookState.hookName} (cycle ${activeHookState.cycle})`;
+  }
+
   const sid = state.activeSlice?.id ?? "";
+  if (unitType.startsWith("hook/")) return `continue ${sid}`;
   switch (unitType) {
     case "research-milestone": return "plan milestone roadmap";
     case "plan-milestone": return "plan or execute first slice";
@@ -1275,6 +1380,9 @@ async function dispatchNextUnit(
     return;
   }
 
+  // Clear stale directory listing cache so deriveState sees fresh disk state (#431)
+  clearPathCache();
+
   let state = await deriveState(basePath);
   let mid = state.activeMilestone?.id;
   let midTitle = state.activeMilestone?.title;
@@ -1338,6 +1446,8 @@ async function dispatchNextUnit(
         }
         // Re-derive state from the now-merged working tree
         invalidateStateCache();
+        clearParseCache();
+        clearPathCache();
         state = await deriveState(basePath);
         mid = state.activeMilestone?.id;
         midTitle = state.activeMilestone?.title;
@@ -1403,6 +1513,8 @@ async function dispatchNextUnit(
             );
             // Re-derive state from main so downstream logic sees merged state
             invalidateStateCache();
+            clearParseCache();
+            clearPathCache();
             state = await deriveState(basePath);
             mid = state.activeMilestone?.id;
             midTitle = state.activeMilestone?.title;
@@ -1715,6 +1827,28 @@ async function dispatchNextUnit(
     }
   }
 
+  // ── Pre-dispatch hooks: modify, skip, or replace the unit before dispatch ──
+  const preDispatchResult = runPreDispatchHooks(unitType, unitId, prompt, basePath);
+  if (preDispatchResult.firedHooks.length > 0) {
+    ctx.ui.notify(
+      `Pre-dispatch hook${preDispatchResult.firedHooks.length > 1 ? "s" : ""}: ${preDispatchResult.firedHooks.join(", ")}`,
+      "info",
+    );
+  }
+  if (preDispatchResult.action === "skip") {
+    ctx.ui.notify(`Skipping ${unitType} ${unitId} (pre-dispatch hook).`, "info");
+    // Yield then re-dispatch to advance to next unit
+    await new Promise(r => setImmediate(r));
+    await dispatchNextUnit(ctx, pi);
+    return;
+  }
+  if (preDispatchResult.action === "replace") {
+    prompt = preDispatchResult.prompt ?? prompt;
+    if (preDispatchResult.unitType) unitType = preDispatchResult.unitType;
+  } else if (preDispatchResult.prompt) {
+    prompt = preDispatchResult.prompt;
+  }
+
   const priorSliceBlocker = getPriorSliceCompletionBlocker(basePath, getMainBranch(basePath), unitType, unitId);
   if (priorSliceBlocker) {
     await stopAuto(ctx, pi);
@@ -2285,6 +2419,7 @@ async function buildResearchMilestonePrompt(mid: string, midTitle: string, base:
   if (requirementsInline) inlined.push(requirementsInline);
   const decisionsInline = await inlineGsdRootFile(base, "decisions.md", "Decisions");
   if (decisionsInline) inlined.push(decisionsInline);
+  inlined.push(inlineTemplate("research", "Research"));
 
   const inlinedContext = `## Inlined Context (preloaded — do not re-read these files)\n\n${inlined.join("\n\n---\n\n")}`;
 
@@ -2317,6 +2452,11 @@ async function buildPlanMilestonePrompt(mid: string, midTitle: string, base: str
   if (requirementsInline) inlined.push(requirementsInline);
   const decisionsInline = await inlineGsdRootFile(base, "decisions.md", "Decisions");
   if (decisionsInline) inlined.push(decisionsInline);
+  inlined.push(inlineTemplate("roadmap", "Roadmap"));
+  inlined.push(inlineTemplate("decisions", "Decisions"));
+  inlined.push(inlineTemplate("plan", "Slice Plan"));
+  inlined.push(inlineTemplate("task-plan", "Task Plan"));
+  inlined.push(inlineTemplate("secrets-manifest", "Secrets Manifest"));
 
   const inlinedContext = `## Inlined Context (preloaded — do not re-read these files)\n\n${inlined.join("\n\n---\n\n")}`;
 
@@ -2353,6 +2493,7 @@ async function buildResearchSlicePrompt(
   if (decisionsInline) inlined.push(decisionsInline);
   const requirementsInline = await inlineGsdRootFile(base, "requirements.md", "Requirements");
   if (requirementsInline) inlined.push(requirementsInline);
+  inlined.push(inlineTemplate("research", "Research"));
 
   const depContent = await inlineDependencySummaries(mid, sid, base);
 
@@ -2388,6 +2529,8 @@ async function buildPlanSlicePrompt(
   if (decisionsInline) inlined.push(decisionsInline);
   const requirementsInline = await inlineGsdRootFile(base, "requirements.md", "Requirements");
   if (requirementsInline) inlined.push(requirementsInline);
+  inlined.push(inlineTemplate("plan", "Slice Plan"));
+  inlined.push(inlineTemplate("task-plan", "Task Plan"));
 
   const depContent = await inlineDependencySummaries(mid, sid, base);
 
@@ -2449,6 +2592,10 @@ async function buildExecuteTaskPrompt(
   );
 
   const carryForwardSection = await buildCarryForwardSection(priorSummaries, base);
+  const inlinedTemplates = [
+    inlineTemplate("task-summary", "Task Summary"),
+    inlineTemplate("decisions", "Decisions"),
+  ].join("\n\n---\n\n");
 
   const taskSummaryPath = `${relSlicePath(base, mid, sid)}/tasks/${tid}-SUMMARY.md`;
 
@@ -2463,6 +2610,7 @@ async function buildExecuteTaskPrompt(
     resumeSection,
     priorTaskLines: priorLines,
     taskSummaryPath,
+    inlinedTemplates,
   });
 }
 
@@ -2495,6 +2643,8 @@ async function buildCompleteSlicePrompt(
       }
     }
   }
+  inlined.push(inlineTemplate("slice-summary", "Slice Summary"));
+  inlined.push(inlineTemplate("uat", "UAT"));
 
   const inlinedContext = `## Inlined Context (preloaded — do not re-read these files)\n\n${inlined.join("\n\n---\n\n")}`;
 
@@ -2547,6 +2697,7 @@ async function buildCompleteMilestonePrompt(
   const contextRel = relMilestoneFile(base, mid, "CONTEXT");
   const contextInline = await inlineFileOptional(contextPath, contextRel, "Milestone Context");
   if (contextInline) inlined.push(contextInline);
+  inlined.push(inlineTemplate("milestone-summary", "Milestone Summary"));
 
   const inlinedContext = `## Inlined Context (preloaded — do not re-read these files)\n\n${inlined.join("\n\n---\n\n")}`;
 
@@ -2993,6 +3144,9 @@ async function collectObservabilityWarnings(
   unitType: string,
   unitId: string,
 ): Promise<import("./observability-validator.ts").ValidationIssue[]> {
+  // 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];
@@ -3404,6 +3558,9 @@ export function resolveExpectedArtifactPath(unitType: string, unitId: string, ba
  * skipped writing the UAT file (see #176).
  */
 export function verifyExpectedArtifact(unitType: string, unitId: string, base: string): boolean {
+  // Clear stale directory listing cache so artifact checks see fresh disk state (#431)
+  clearPathCache();
+
   // fix-merge has no file artifact — verify by checking git state
   if (unitType === "fix-merge") {
     const unmerged = runGit(base, ["diff", "--name-only", "--diff-filter=U"], { allowFailure: true });

package/dist/resources/extensions/gsd/commands.ts

@@ -53,10 +53,10 @@ function dispatchDoctorHeal(pi: ExtensionAPI, scope: string | undefined, reportT
 
 export function registerGSDCommand(pi: ExtensionAPI): void {
   pi.registerCommand("gsd", {
-    description: "GSD — Get Shit Done: /gsd next|auto|stop|status|queue|prefs|doctor|migrate|remote",
+    description: "GSD — Get Shit Done: /gsd next|auto|stop|status|queue|prefs|hooks|doctor|migrate|remote",
 
     getArgumentCompletions: (prefix: string) => {
-      const subcommands = ["next", "auto", "stop", "status", "queue", "discuss", "prefs", "doctor", "migrate", "remote"];
+      const subcommands = ["next", "auto", "stop", "status", "queue", "discuss", "prefs", "hooks", "doctor", "migrate", "remote"];
       const parts = prefix.trim().split(/\s+/);
 
       if (parts.length <= 1) {
@@ -151,6 +151,12 @@ export function registerGSDCommand(pi: ExtensionAPI): void {
         return;
       }
 
+      if (trimmed === "hooks") {
+        const { formatHookStatus } = await import("./post-unit-hooks.js");
+        ctx.ui.notify(formatHookStatus(), "info");
+        return;
+      }
+
       if (trimmed === "migrate" || trimmed.startsWith("migrate ")) {
         await handleMigrate(trimmed.replace(/^migrate\s*/, "").trim(), ctx, pi);
         return;
@@ -168,7 +174,7 @@ export function registerGSDCommand(pi: ExtensionAPI): void {
       }
 
       ctx.ui.notify(
-        `Unknown: /gsd ${trimmed}. Use /gsd, /gsd next, /gsd auto, /gsd stop, /gsd status, /gsd queue, /gsd discuss, /gsd prefs [global|project|status|wizard|setup], /gsd doctor [audit|fix|heal] [M###/S##], /gsd migrate <path>, or /gsd remote [slack|discord|status|disconnect].`,
+        `Unknown: /gsd ${trimmed}. Use /gsd, /gsd next, /gsd auto, /gsd stop, /gsd status, /gsd queue, /gsd discuss, /gsd prefs [global|project|status|wizard|setup], /gsd hooks, /gsd doctor [audit|fix|heal] [M###/S##], /gsd migrate <path>, or /gsd remote [slack|discord|status|disconnect].`,
         "warning",
       );
     },

package/dist/resources/extensions/gsd/doctor.ts

@@ -22,7 +22,8 @@ export type DoctorIssueCode =
   | "task_done_must_haves_not_verified"
   | "active_requirement_missing_owner"
   | "blocked_requirement_missing_reason"
-  | "blocker_discovered_no_replan";
+  | "blocker_discovered_no_replan"
+  | "delimiter_in_title";
 
 export interface DoctorIssue {
   severity: DoctorSeverity;
@@ -91,15 +92,43 @@ function validatePreferenceShape(preferences: GSDPreferences): string[] {
   return issues;
 }
 
+/**
+ * Characters that are used as delimiters in GSD state management documents
+ * and should not appear in milestone or slice titles.
+ *
+ * - "—" (em dash, U+2014): used as a display separator in STATE.md and other docs.
+ *   A title containing "—" makes the separator ambiguous, corrupting state display
+ *   and confusing the LLM agent that reads and writes these files.
+ * - "–" (en dash, U+2013): visually similar to em dash; same ambiguity risk.
+ * - "/" (forward slash, U+002F): used as the path separator in unit IDs (M001/S01)
+ *   and git branch names (gsd/M001/S01). A slash in a title can break path resolution.
+ */
+const TITLE_DELIMITER_RE = /[\u2014\u2013\/]/; // em dash, en dash, forward slash
+
+/**
+ * Check whether a milestone or slice title contains characters that conflict
+ * with GSD's state document delimiter conventions.
+ * Returns a human-readable description of the problem, or null if the title is safe.
+ */
+export function validateTitle(title: string): string | null {
+  if (TITLE_DELIMITER_RE.test(title)) {
+    const found: string[] = [];
+    if (/[\u2014\u2013]/.test(title)) found.push("em/en dash (\u2014 or \u2013)");
+    if (/\//.test(title)) found.push("forward slash (/)");
+    return `title contains ${found.join(" and ")}, which conflict with GSD state document delimiters`;
+  }
+  return null;
+}
+
 function buildStateMarkdown(state: Awaited<ReturnType<typeof deriveState>>): string {
   const lines: string[] = [];
   lines.push("# GSD State", "");
 
   const activeMilestone = state.activeMilestone
-    ? `${state.activeMilestone.id} — ${state.activeMilestone.title}`
+    ? `${state.activeMilestone.id}: ${state.activeMilestone.title}`
     : "None";
   const activeSlice = state.activeSlice
-    ? `${state.activeSlice.id} — ${state.activeSlice.title}`
+    ? `${state.activeSlice.id}: ${state.activeSlice.title}`
     : "None";
 
   lines.push(`**Active Milestone:** ${activeMilestone}`);
@@ -477,6 +506,20 @@ export async function runGSDDoctor(basePath: string, options?: { fix?: boolean;
     const milestonePath = resolveMilestonePath(basePath, milestoneId);
     if (!milestonePath) continue;
 
+    // Validate milestone title for delimiter characters that break state documents.
+    const milestoneTitleIssue = validateTitle(milestone.title);
+    if (milestoneTitleIssue) {
+      issues.push({
+        severity: "warning",
+        code: "delimiter_in_title",
+        scope: "milestone",
+        unitId: milestoneId,
+        message: `Milestone ${milestoneId} ${milestoneTitleIssue}. Rename the milestone to remove these characters to prevent state corruption.`,
+        file: relMilestoneFile(basePath, milestoneId, "ROADMAP"),
+        fixable: false,
+      });
+    }
+
     const roadmapPath = resolveMilestoneFile(basePath, milestoneId, "ROADMAP");
     const roadmapContent = roadmapPath ? await loadFile(roadmapPath) : null;
     if (!roadmapContent) continue;
@@ -486,6 +529,20 @@ export async function runGSDDoctor(basePath: string, options?: { fix?: boolean;
       const unitId = `${milestoneId}/${slice.id}`;
       if (options?.scope && !matchesScope(unitId, options.scope) && options.scope !== milestoneId) continue;
 
+      // Validate slice title for delimiter characters.
+      const sliceTitleIssue = validateTitle(slice.title);
+      if (sliceTitleIssue) {
+        issues.push({
+          severity: "warning",
+          code: "delimiter_in_title",
+          scope: "slice",
+          unitId,
+          message: `Slice ${unitId} ${sliceTitleIssue}. Rename the slice to remove these characters to prevent state corruption.`,
+          file: relMilestoneFile(basePath, milestoneId, "ROADMAP"),
+          fixable: false,
+        });
+      }
+
       const slicePath = resolveSlicePath(basePath, milestoneId, slice.id);
       if (!slicePath) continue;