@opengsd/gsd-pi 1.2.0-dev.4813ead6 → 1.2.0-dev.5457a158

package/src/resources/extensions/gsd/tests/auto-post-unit-evidence-crossref-4909.test.ts

@@ -88,3 +88,49 @@ test("detects session execution tools supported by the evidence collector", () =
 
   assert.equal(_hasExecutionToolCallsInSessionForTest(entries), true);
 });
+
+test("detects execution tool calls in bare agent-end messages (no session-entry wrapper)", () => {
+  // The auto loop passes opts.agentEndMessages as bare {role, content}
+  // messages — not {type: "message", message} session-manager entries.
+  const entries = [
+    {
+      role: "assistant",
+      content: [
+        {
+          type: "toolCall",
+          name: "Bash",
+          arguments: { command: "test -s index.html && grep -q localStorage index.html" },
+        },
+      ],
+    },
+  ];
+
+  assert.equal(_hasExecutionToolCallsInSessionForTest(entries), true);
+});
+
+test("does not suppress for bare agent-end messages without execution tools", () => {
+  const entries = [
+    {
+      role: "assistant",
+      content: [
+        { type: "text", text: "Task complete." },
+        { type: "toolCall", name: "Write", arguments: { file_path: "index.html" } },
+      ],
+    },
+  ];
+
+  assert.equal(_hasExecutionToolCallsInSessionForTest(entries), false);
+});
+
+test("ignores bare user messages with toolCall-shaped content", () => {
+  const entries = [
+    {
+      role: "user",
+      content: [
+        { type: "toolCall", name: "bash", arguments: { command: "echo hi" } },
+      ],
+    },
+  ];
+
+  assert.equal(_hasExecutionToolCallsInSessionForTest(entries), false);
+});

package/src/resources/extensions/gsd/tests/auto-worktree-registry.test.ts

@@ -184,7 +184,7 @@ describe("auto-worktree workspace registry", () => {
     git(["commit", "-m", "add milestone"], tempDir);
 
     createAutoWorktree(tempDir, "M003");
-    const wtDir = join(tempDir, ".gsd", "worktrees", "M003");
+    const wtDir = join(tempDir, ".gsd-worktrees", "M003");
     writeFileSync(join(wtDir, "feature.txt"), "implemented\n");
     git(["add", "feature.txt"], wtDir);
     git(["commit", "-m", "feat: implement M003"], wtDir);
@@ -216,7 +216,7 @@ describe("auto-worktree workspace registry", () => {
     git(["commit", "-m", "add milestone"], tempDir);
 
     createAutoWorktree(tempDir, "M004");
-    const wtDir = join(tempDir, ".gsd", "worktrees", "M004");
+    const wtDir = join(tempDir, ".gsd-worktrees", "M004");
     writeFileSync(join(wtDir, "feature.txt"), "implemented\n");
     git(["add", "feature.txt"], wtDir);
     git(["commit", "-m", "feat: implement M004"], wtDir);

package/src/resources/extensions/gsd/tests/auto-worktree-repair.test.ts

@@ -35,7 +35,8 @@ test("repair target accepts a missing expected milestone worktree", () => {
 
     assert.equal(result.ok, true);
     if (result.ok) {
-      assert.equal(result.expectedPath, join(base, ".gsd", "worktrees", "M001"));
+      // No worktree exists yet, so the expected path is the canonical container.
+      assert.equal(result.expectedPath, join(base, ".gsd-worktrees", "M001"));
     }
   } finally {
     cleanup(base);
@@ -192,7 +193,8 @@ test("paused metadata path resolves to the expected worktree while paused at pro
       baseIsAutoWorktree: false,
     });
 
-    assert.equal(result, join(base, ".gsd", "worktrees", "M001"));
+    // No worktree exists yet, so resolution lands at the canonical container.
+    assert.equal(result, join(base, ".gsd-worktrees", "M001"));
   } finally {
     cleanup(base);
   }

package/src/resources/extensions/gsd/tests/checkout-branch-stash-guard.test.ts

@@ -5,7 +5,7 @@ import { mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, writeFileSy
 import { join } from "node:path";
 import { tmpdir } from "node:os";
 
-import { checkoutBranchWithStashGuard } from "../auto-worktree.ts";
+import { checkoutBranchWithStashGuard } from "../worktree-git-recovery.ts";
 
 function git(args: string[], cwd: string): string {
   return execFileSync("git", args, {
@@ -159,4 +159,69 @@ describe("checkoutBranchWithStashGuard", () => {
     const stashList = git(["stash", "list"], repo).trim();
     assert.equal(stashList, "");
   });
+
+  test("auto-resolves combined non-.gsd untracked collision and .gsd index conflict", (t) => {
+    // Regression for: gate checked nonGsdUnmerged.length === 0 but ignored
+    // .gsd/ index conflicts, so a failed pop with both an untracked non-.gsd/
+    // collision AND a .gsd/ tracked conflict would drop the stash while leaving
+    // .gsd/ index unmerged entries unresolved.
+    const repo = createRepo(t);
+    // Add .gsd/DECISIONS.md to base so both branches diverge from it
+    writeFileSync(join(repo, ".gsd", "DECISIONS.md"), "base\n");
+    git(["add", ".gsd/DECISIONS.md"], repo);
+    git(["commit", "-m", "add decisions"], repo);
+
+    git(["checkout", "-b", "milestone/M003"], repo);
+    // Branch has its own version of DECISIONS.md (non-JSONL .gsd/ file)
+    writeFileSync(join(repo, ".gsd", "DECISIONS.md"), "target-version\n");
+    mkdirSync(join(repo, ".harness"), { recursive: true });
+    writeFileSync(join(repo, ".harness", "settings.json"), "{\"theme\":\"dark\"}\n");
+    git(["add", ".gsd/DECISIONS.md", ".harness/settings.json"], repo);
+    git(["commit", "-m", "branch state"], repo);
+    git(["checkout", "main"], repo);
+
+    // On main: tracked .gsd/ change (creates unmerged index entry on pop) +
+    // untracked harness file (triggers "already exists, no checkout").
+    writeFileSync(join(repo, ".gsd", "DECISIONS.md"), "local-version\n");
+    mkdirSync(join(repo, ".harness"), { recursive: true });
+    writeFileSync(join(repo, ".harness", "settings.json"), "{\"theme\":\"light\"}\n");
+
+    checkoutBranchWithStashGuard(repo, "milestone/M003", "test-combined-gsd-conflict");
+
+    const branch = git(["branch", "--show-current"], repo).trim();
+    assert.equal(branch, "milestone/M003");
+    const decisions = readFileSync(join(repo, ".gsd", "DECISIONS.md"), "utf8");
+    assert.equal(decisions, "target-version\n");
+    assert.doesNotMatch(decisions, /<<<<<<<|=======|>>>>>>>/);
+    const status = git(["status", "--porcelain"], repo).trim();
+    assert.equal(status, "");
+    const stashList = git(["stash", "list"], repo).trim();
+    assert.equal(stashList, "");
+  });
+
+  test("auto-resolves non-.gsd untracked restore collisions (e.g. harness config outside .gsd/)", (t) => {
+    const repo = createRepo(t);
+    // Target branch has a harness config file committed; source (main) has it untracked.
+    // Use a path not affected by global gitignore rules (unlike .claude/settings.local.json).
+    git(["checkout", "-b", "milestone/M001"], repo);
+    mkdirSync(join(repo, ".harness"), { recursive: true });
+    writeFileSync(join(repo, ".harness", "settings.json"), "{\"theme\":\"dark\"}\n");
+    git(["add", ".harness/settings.json"], repo);
+    git(["commit", "-m", "add harness settings"], repo);
+    git(["checkout", "main"], repo);
+
+    mkdirSync(join(repo, ".harness"), { recursive: true });
+    writeFileSync(join(repo, ".harness", "settings.json"), "{\"theme\":\"light\"}\n");
+
+    checkoutBranchWithStashGuard(repo, "milestone/M001", "test-non-gsd-untracked-collision");
+
+    const branch = git(["branch", "--show-current"], repo).trim();
+    assert.equal(branch, "milestone/M001");
+    const wtContent = readFileSync(join(repo, ".harness", "settings.json"), "utf8");
+    assert.equal(wtContent, "{\"theme\":\"dark\"}\n");
+    const status = git(["status", "--porcelain"], repo).trim();
+    assert.equal(status, "");
+    const stashList = git(["stash", "list"], repo).trim();
+    assert.equal(stashList, "");
+  });
 });

package/src/resources/extensions/gsd/tests/clear-stale-autostart.test.ts

@@ -73,4 +73,48 @@ describe("clear stale pending auto-start (#3667)", () => {
       "pending auto-start gate must clear stale map entries for completed discussions",
     );
   });
+
+  test("guided-flow recovers a finished-but-unconsumed discussion instead of dead-ending", () => {
+    // CONTEXT exists + no live turn means the discussion completed but the
+    // agent_end handoff never consumed the entry (e.g. an external-engine
+    // post-hoc gate re-arm wiped the depth verification after the save).
+    // Without recovery, every /gsd prints "Discussion already in progress"
+    // forever: the stale heuristic requires CONTEXT to be absent and
+    // discussPlanComplete requires a ROADMAP that planning never produced.
+    const source = readFileSync(join(__dirname, "..", "guided-flow.ts"), "utf-8");
+    assert.ok(
+      source.includes("milestoneHasContext && !isAgentTurnInFlight(ctx)"),
+      "pending-entry guard must have a recovery branch for CONTEXT-present, no-turn-in-flight entries",
+    );
+    assert.ok(
+      source.includes("extractDepthVerificationMilestoneId(pendingGateId) === entry.milestoneId"),
+      "recovery must only clear a pending gate belonging to the entry's own milestone",
+    );
+    assert.ok(
+      source.includes("if (checkAutoStartAfterDiscuss(basePath)) return;"),
+      "recovery must re-run the discuss→auto handoff after clearing the stale gate",
+    );
+  });
+
+  test("guided-flow does not treat a live discuss turn as a stale pending entry", () => {
+    const source = readFileSync(join(__dirname, "..", "guided-flow.ts"), "utf-8");
+    assert.ok(
+      source.includes("!isAgentTurnInFlight(ctx)"),
+      "stale-entry deletion must be gated on no agent turn being in flight — a dispatched " +
+      "discuss turn can think for over 30s before writing its first artifact, and deleting " +
+      "its entry re-dispatches the workflow (duplicate interview + duplicate completion message)",
+    );
+    assert.ok(
+      source.includes('const milestoneHasDraft = !!resolveMilestoneFile(basePath, entry.milestoneId, "CONTEXT-DRAFT");'),
+      "stale-entry check must treat an existing CONTEXT-DRAFT as proof of an in-progress interview",
+    );
+    assert.ok(
+      source.includes("!milestoneHasDraft"),
+      "stale-entry deletion must require the CONTEXT-DRAFT to be absent",
+    );
+    assert.ok(
+      source.includes("ctx.hasPendingMessages"),
+      "in-flight detection must also cover dispatched-but-not-yet-started queued messages",
+    );
+  });
 });

package/src/resources/extensions/gsd/tests/commands-verdict.test.ts

@@ -472,18 +472,19 @@ test("auto-dispatch needs-attention pause message references /gsd verdict", asyn
   }
 });
 
-test("state.ts needs-remediation blocker messages reference /gsd verdict", async () => {
+test("guidance.ts needs-remediation blocker messages reference /gsd verdict", async () => {
   // We don't need to invoke deriveState — just assert the substring is in the
-  // source. The blocker strings are constructed inline and shipped to the user
-  // verbatim, so a static check is sufficient and avoids fragile DB setup.
-  const stateSource = readFileSync(
-    new URL("../state.ts", import.meta.url).pathname,
+  // source. The blocker strings are constructed in the guidance catalog and
+  // shipped to the user verbatim, so a static check is sufficient and avoids
+  // fragile DB setup.
+  const guidanceSource = readFileSync(
+    new URL("../guidance.ts", import.meta.url).pathname,
     "utf-8",
   );
-  const occurrences = stateSource.match(/`\/gsd verdict /g) ?? [];
+  const occurrences = guidanceSource.match(/`\/gsd verdict /g) ?? [];
   assert.ok(
     occurrences.length >= 2,
-    `expected at least 2 references to /gsd verdict in state.ts blockers, found ${occurrences.length}`,
+    `expected at least 2 references to /gsd verdict in guidance.ts blockers, found ${occurrences.length}`,
   );
 });
 

package/src/resources/extensions/gsd/tests/evidence-xref-gsd-exec.test.ts

@@ -0,0 +1,157 @@
+// Project/App: gsd-pi
+// File Purpose: Regression tests for evidence cross-referencing of gsd_exec /
+// gsd_uat_exec tool calls. Mirrors the live false-positive where an
+// execute-task agent ran its verification commands through gsd_exec (script
+// body in the `script` argument) and the cross-referencer reported
+// "No bash tool call found" despite successful execution.
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import {
+  resetEvidence,
+  getEvidence,
+  recordToolCall,
+  recordToolResult,
+  isExecutionToolName,
+  type BashEvidence,
+} from "../safety/evidence-collector.ts";
+import { crossReferenceEvidence } from "../safety/evidence-cross-ref.ts";
+
+function gsdExecResult(exitCode: number, id = "4858202d-2ed7-4a0a-9ef7-4e159e65da83"): unknown {
+  return {
+    content: [{
+      type: "text",
+      text: JSON.stringify({
+        operation: "gsd_exec",
+        id,
+        runtime: "bash",
+        exit_code: exitCode,
+        signal: null,
+        timed_out: false,
+        duration_ms: 272,
+        stdout_bytes: 592,
+        stderr_bytes: 0,
+        meta_path: `/tmp/does-not-exist/.gsd/exec/${id}.meta.json`,
+      }),
+    }],
+  };
+}
+
+test("evidence-xref: verification run through gsd_exec script matches the claimed command", () => {
+  resetEvidence();
+
+  // The live false positive: agent runs `node --test tests/verify-s01.test.js`
+  // inside a gsd_exec script with a cd prefix and exit-code echo suffix.
+  recordToolCall("tc-exec-1", "gsd_exec", {
+    script: 'cd /work/.gsd/worktrees/M001 && node --test tests/verify-s01.test.js; echo "EXIT=$?"',
+    purpose: "T02: run node --test contract checks against T01 index.html",
+  });
+  recordToolResult("tc-exec-1", "gsd_exec", gsdExecResult(0), false);
+
+  const mismatches = crossReferenceEvidence(
+    [{ command: "node --test tests/verify-s01.test.js", exitCode: 0, verdict: "passed" }],
+    getEvidence(),
+  );
+
+  assert.deepEqual(mismatches, [], "gsd_exec-executed verification must not be flagged as missing");
+});
+
+test("evidence-xref: multi-line gsd_exec script matches claims for each embedded command", () => {
+  resetEvidence();
+
+  recordToolCall("tc-exec-2", "gsd_exec", {
+    script: [
+      "cd /work/.gsd/worktrees/M001",
+      "sed -i '' \"s/'todos'/'tasks-v1'/\" index.html",
+      "node --test tests/verify-s01.test.js > /dev/null 2>&1",
+      'echo "BROKEN_EXIT=$?"',
+    ].join("\n"),
+    purpose: "T02: deliberate contract break must fail, then restore",
+  });
+  recordToolResult("tc-exec-2", "gsd_exec", gsdExecResult(0), false);
+
+  const mismatches = crossReferenceEvidence(
+    [{ command: "node --test tests/verify-s01.test.js > /dev/null 2>&1", exitCode: 0, verdict: "passed" }],
+    getEvidence(),
+  );
+
+  assert.deepEqual(mismatches, [], "command embedded in a multi-line script must match");
+});
+
+test("evidence-xref: claimed pass with failing gsd_exec exit_code is still an error", () => {
+  resetEvidence();
+
+  recordToolCall("tc-exec-3", "gsd_exec", {
+    script: "node --test tests/verify-s01.test.js",
+    purpose: "verification",
+  });
+  // gsd_exec reports failures via the JSON envelope's exit_code (and isError).
+  recordToolResult("tc-exec-3", "gsd_exec", gsdExecResult(1), true);
+
+  const mismatches = crossReferenceEvidence(
+    [{ command: "node --test tests/verify-s01.test.js", exitCode: 0, verdict: "passed" }],
+    getEvidence(),
+  );
+
+  assert.equal(mismatches.length, 1);
+  assert.equal(mismatches[0].severity, "error");
+  assert.match(mismatches[0].reason, /Claimed exitCode=0 but actual exitCode=1/);
+});
+
+test("evidence-collector: gsd_uat_exec and MCP-namespaced variants are execution tools", () => {
+  assert.equal(isExecutionToolName("gsd_uat_exec"), true);
+  assert.equal(isExecutionToolName("mcp__gsd-workflow__gsd_uat_exec"), true);
+  assert.equal(isExecutionToolName("mcp__gsd-workflow__gsd_exec"), true);
+
+  resetEvidence();
+  recordToolCall("tc-uat-1", "gsd_uat_exec", { script: "curl -fsS http://localhost:3000/health" });
+  const bash = getEvidence().filter((e): e is BashEvidence => e.kind === "bash");
+  assert.equal(bash.length, 1, "gsd_uat_exec must record bash evidence");
+  assert.equal(bash[0].command, "curl -fsS http://localhost:3000/health");
+});
+
+test("evidence-xref: blank-command evidence does not satisfy arbitrary claims", () => {
+  // Before script extraction existed, gsd_exec calls were recorded with
+  // command: "" — and `"x".includes("")` made them match every claim,
+  // masking genuine fabrications. Blank entries must never match.
+  const mismatches = crossReferenceEvidence(
+    [{ command: "node --test tests/verify-s01.test.js", exitCode: 0, verdict: "passed" }],
+    [{
+      kind: "bash",
+      toolCallId: "tc-blank",
+      command: "",
+      exitCode: 0,
+      outputSnippet: "",
+      timestamp: 1,
+    }],
+  );
+
+  assert.equal(mismatches.length, 1);
+  assert.equal(mismatches[0].severity, "warning");
+  assert.match(mismatches[0].reason, /No bash tool call found/);
+});
+
+test("evidence-collector: exit code falls back to .gsd/exec meta.json when result text omits it", (t) => {
+  const dir = mkdtempSync(join(tmpdir(), "gsd-exec-meta-"));
+  t.after(() => rmSync(dir, { recursive: true, force: true }));
+
+  const metaPath = join(dir, "run-1.meta.json");
+  writeFileSync(metaPath, JSON.stringify({ id: "run-1", exit_code: 7 }));
+
+  resetEvidence();
+  recordToolCall("tc-meta-1", "gsd_exec", { script: "exit 7" });
+  // Truncated result: meta_path survives but exit_code was cut off.
+  recordToolResult(
+    "tc-meta-1",
+    "gsd_exec",
+    { content: [{ type: "text", text: `{"operation":"gsd_exec","meta_path":${JSON.stringify(metaPath)}` }] },
+    false,
+  );
+
+  const bash = getEvidence().filter((e): e is BashEvidence => e.kind === "bash");
+  assert.equal(bash[0].exitCode, 7, "exit code must be recovered from meta.json");
+});

package/src/resources/extensions/gsd/tests/file-change-validator.test.ts

@@ -5,7 +5,7 @@ import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 
-import { validateFileChanges } from "../safety/file-change-validator.ts";
+import { validateFileChanges, effectiveFileChangeAllowlist } from "../safety/file-change-validator.ts";
 
 function git(cwd: string, ...args: string[]): string {
   return execFileSync("git", args, {
@@ -106,3 +106,35 @@ test("validateFileChanges ignores inline descriptions in expected output paths",
     "described expected output should not trigger unexpected-file warnings",
   );
 });
+
+test("effectiveFileChangeAllowlist includes .gitignore when GSD manages it", () => {
+  assert.deepEqual(effectiveFileChangeAllowlist([], undefined), [".gitignore"]);
+  assert.deepEqual(effectiveFileChangeAllowlist(["docs/**"], true), ["docs/**", ".gitignore"]);
+});
+
+test("effectiveFileChangeAllowlist keeps .gitignore auditable when management is disabled", () => {
+  assert.deepEqual(effectiveFileChangeAllowlist(["docs/**"], false), ["docs/**"]);
+});
+
+test("GSD-managed .gitignore edit swept into a task commit is not flagged", (t) => {
+  const base = mkdtempSync(join(tmpdir(), "gsd-file-change-validator-"));
+  t.after(() => rmSync(base, { recursive: true, force: true }));
+
+  git(base, "init");
+  git(base, "config", "user.email", "test@example.com");
+  git(base, "config", "user.name", "Test User");
+  writeFileSync(join(base, "index.html"), "<main></main>\n");
+  writeFileSync(join(base, ".gitignore"), "# ── GSD baseline (auto-generated) ──\n.gsd\n");
+  git(base, "add", ".");
+  git(base, "commit", "-m", "task commit with swept gitignore");
+
+  const audit = validateFileChanges(
+    base,
+    ["index.html"],
+    [],
+    effectiveFileChangeAllowlist([], undefined),
+  );
+
+  assert.ok(audit, "audit should be produced");
+  assert.deepEqual(audit.unexpectedFiles, [], ".gitignore must not be flagged when GSD manages it");
+});

package/src/resources/extensions/gsd/tests/guidance.test.ts

@@ -0,0 +1,125 @@
+// GSD Extension — Guidance module tests
+// The catalog is the test surface: every typed finding must resolve to
+// non-empty remediation, and load-bearing phrases must survive edits.
+
+import { describe, test } from "node:test";
+import assert from "node:assert/strict";
+
+import {
+  formatGuidance,
+  recoveryRemediation,
+  needsAttentionBlockerGuidance,
+  needsRemediationBlockerGuidance,
+  crashResumeHint,
+  doctorFixHint,
+  type RecoveryGuidanceKey,
+} from "../guidance.js";
+import { classifyFailure, type RecoveryFailureKind } from "../recovery-classification.js";
+import { isValidationBlockedState } from "../validation-block-guard.js";
+import type { GSDState } from "../types.js";
+
+const RECOVERY_KEYS: RecoveryGuidanceKey[] = [
+  "tool-schema",
+  "tool-contract",
+  "tool-unavailable",
+  "deterministic-policy",
+  "lifecycle-progression",
+  "stale-worker",
+  "worktree-invalid",
+  "verification-drift",
+  "reconciliation-drift",
+  "illegal-transition",
+  "runtime-unknown",
+  "provider-transient",
+  "provider-permanent",
+];
+
+describe("guidance catalog", () => {
+  test("every recovery guidance key resolves to non-empty remediation", () => {
+    for (const key of RECOVERY_KEYS) {
+      const remediation = recoveryRemediation(key);
+      assert.ok(remediation.length > 0, `empty remediation for ${key}`);
+    }
+  });
+
+  test("classifyFailure carries catalog remediation for every failure kind", () => {
+    const kinds: RecoveryFailureKind[] = [
+      "tool-schema",
+      "tool-contract",
+      "deterministic-policy",
+      "lifecycle-progression",
+      "stale-worker",
+      "worktree-invalid",
+      "verification-drift",
+      "reconciliation-drift",
+      "runtime-unknown",
+    ];
+    for (const kind of kinds) {
+      const result = classifyFailure({ error: new Error("boom"), failureKind: kind });
+      assert.equal(result.failureKind, kind);
+      assert.equal(result.exitReason, kind);
+      assert.ok(result.remediation.length > 0, `empty remediation for ${kind}`);
+    }
+  });
+
+  test("escalation kinds with weak guidance now name a concrete command", () => {
+    for (const key of ["stale-worker", "worktree-invalid", "verification-drift", "reconciliation-drift"] as const) {
+      assert.match(recoveryRemediation(key), /\/gsd /, `no command in remediation for ${key}`);
+    }
+  });
+
+  test("formatGuidance numbers steps under the summary", () => {
+    const text = formatGuidance({ summary: "It broke.", steps: ["Fix it.", "Retry."] });
+    assert.equal(text, "It broke.\n\n1. Fix it.\n2. Retry.");
+  });
+
+  test("formatGuidance with no steps is just the summary", () => {
+    assert.equal(formatGuidance({ summary: "All good.", steps: [] }), "All good.");
+  });
+});
+
+describe("milestone blocker guidance", () => {
+  test("needs-attention blocker keeps the phrase the validation-block guard matches", () => {
+    const state = { phase: "blocked", blockers: [needsAttentionBlockerGuidance("M005")] } as unknown as GSDState;
+    assert.ok(isValidationBlockedState(state));
+  });
+
+  test("needs-remediation blocker keeps the phrase the validation-block guard matches", () => {
+    const state = { phase: "blocked", blockers: [needsRemediationBlockerGuidance("M005")] } as unknown as GSDState;
+    assert.ok(isValidationBlockedState(state));
+  });
+
+  test("blockers carry the milestone id and concrete fix commands", () => {
+    const text = needsAttentionBlockerGuidance("M007");
+    assert.match(text, /M007/);
+    assert.match(text, /\/gsd status/);
+    assert.match(text, /\/gsd validate-milestone/);
+  });
+});
+
+describe("crash resume hints", () => {
+  test("bootstrap crash reports no work lost", () => {
+    assert.match(crashResumeHint("starting", "bootstrap") ?? "", /No work was lost/);
+  });
+
+  test("unit classes map to their resume hints", () => {
+    assert.match(crashResumeHint("research-milestone", "M001") ?? "", /may be incomplete/);
+    assert.match(crashResumeHint("execute-task", "T001") ?? "", /completed work is preserved/);
+    assert.match(crashResumeHint("complete-slice", "S001") ?? "", /interrupted/);
+  });
+
+  test("unknown unit types yield no hint", () => {
+    assert.equal(crashResumeHint("triage-captures", "X"), undefined);
+  });
+});
+
+describe("doctor fix hints", () => {
+  test("known codes resolve to a hint", () => {
+    assert.ok(doctorFixHint("stale_crash_lock"));
+    assert.ok(doctorFixHint("db_unavailable"));
+  });
+
+  test("codes without authored guidance resolve to undefined", () => {
+    assert.equal(doctorFixHint("delimiter_in_title"), undefined);
+  });
+});

package/src/resources/extensions/gsd/tests/integration/auto-worktree-milestone-merge.test.ts

@@ -746,7 +746,7 @@ describe("auto-worktree-milestone-merge", { timeout: 300_000 }, () => {
   });
 
   test("#2156: mergeMilestoneToMain removes external-state worktrees using the milestone branch name", () => {
-    const { repo, externalState } = freshRepoWithExternalGsd();
+    const { repo } = freshRepoWithExternalGsd();
     const wtPath = createAutoWorktree(repo, "M215");
 
     addSliceToMilestone(repo, wtPath, "M215", "S01", "External cleanup", [
@@ -754,9 +754,10 @@ describe("auto-worktree-milestone-merge", { timeout: 300_000 }, () => {
     ]);
 
     const realWtPath = realpathSync(wtPath);
-    assert.ok(
-      realWtPath.startsWith(externalState),
-      `worktree should be registered under external .gsd state, got ${realWtPath}`,
+    assert.equal(
+      realWtPath,
+      join(repo, ".gsd-worktrees", "M215"),
+      `worktree should use canonical path under project root, got ${realWtPath}`,
     );
 
     // Recreate the exact divergence from #1852: local .gsd/ is replaced with a
@@ -783,6 +784,52 @@ describe("auto-worktree-milestone-merge", { timeout: 300_000 }, () => {
     );
   });
 
+  test("#2156 (legacy): mergeMilestoneToMain removes external-state worktrees created under .gsd/worktrees/", () => {
+    const { repo, externalState } = freshRepoWithExternalGsd();
+    // Worktrees created by older versions live at .gsd/worktrees/<MID>; git
+    // resolves the symlink and registers them under external state. Canonical
+    // .gsd-worktrees/ creation never crosses the symlink, so this coverage
+    // creates the legacy worktree explicitly. createAutoWorktree chdirs into
+    // the new worktree and mergeMilestoneToMain reads process.cwd() as the
+    // worktree cwd, so mirror that here.
+    const wtPath = join(repo, ".gsd", "worktrees", "M216");
+    run(`git worktree add -b milestone/M216 "${wtPath}"`, repo);
+    process.chdir(wtPath);
+
+    addSliceToMilestone(repo, wtPath, "M216", "S01", "Legacy external cleanup", [
+      { file: "legacy-external-cleanup.ts", content: "export const legacyExternalCleanup = true;\n", message: "add legacy external cleanup" },
+    ]);
+
+    const realWtPath = realpathSync(wtPath);
+    assert.ok(
+      realWtPath.startsWith(externalState),
+      `legacy worktree should be registered under external .gsd state, got ${realWtPath}`,
+    );
+
+    // Recreate the exact divergence from #1852: local .gsd/ is replaced with a
+    // stale real directory, so the computed path no longer matches git's record.
+    unlinkSync(join(repo, ".gsd"));
+    mkdirSync(join(repo, ".gsd", "worktrees", "M216"), { recursive: true });
+    writeFileSync(join(repo, ".gsd", "STATE.md"), "# Local stale state\n");
+    writeFileSync(join(repo, ".gsd", "worktrees", "M216", "stale.txt"), "stale local artifact\n");
+
+    const roadmap = makeRoadmap("M216", "Legacy external cleanup", [
+      { id: "S01", title: "Legacy external cleanup" },
+    ]);
+
+    mergeMilestoneToMain(repo, "M216", roadmap);
+
+    assert.ok(
+      !run("git worktree list", repo).includes("M216"),
+      "merged legacy milestone worktree should be removed from git worktree list",
+    );
+    assert.ok(!existsSync(realWtPath), "real external worktree directory should be removed");
+    assert.ok(
+      !run("git branch", repo).includes("milestone/M216"),
+      "milestone branch should be deleted after merge cleanup",
+    );
+  });
+
   test("#2912: MERGE_HEAD cleaned up after squash-merge conflict", () => {
     const repo = freshRepo();
     const wtPath = createAutoWorktree(repo, "M291");