@opengsd/gsd-pi 1.2.0-dev.4c756166 → 1.2.0-dev.955e4da0

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

@@ -5517,6 +5517,129 @@ test("dispatch Worktree Safety wins before stuck detection for execute-task with
   );
 });
 
+test("dispatch Worktree Safety honors degraded branch fallback instead of demanding the canonical worktree root", async (t) => {
+  _resetPendingResolve();
+
+  const ctx = makeMockCtx();
+  const pi = makeMockPi();
+  const notifications: string[] = [];
+  ctx.ui.notify = (msg: string) => { notifications.push(msg); };
+
+  // Worktree creation failed and the lifecycle fell back to the milestone
+  // branch in the project root. The safety gate must validate against that
+  // effective branch mode, not the configured worktree mode.
+  const projectRoot = mkdtempSync(join(tmpdir(), "gsd-wt-safety-degraded-"));
+  t.after(() => rmSync(projectRoot, { recursive: true, force: true }));
+
+  const s = makeLoopSession({
+    basePath: projectRoot,
+    originalBasePath: projectRoot,
+    canonicalProjectRoot: projectRoot,
+    isolationDegraded: true,
+  });
+  const deps = makeMockDeps({
+    getIsolationMode: () => "worktree",
+  });
+  const result = await runDispatch(
+    {
+      ctx,
+      pi,
+      s,
+      deps,
+      prefs: undefined,
+      iteration: 1,
+      flowId: "test-flow",
+      nextSeq: () => 1,
+    },
+    {
+      state: {
+        phase: "executing",
+        activeMilestone: { id: "M001", title: "Test", status: "active" },
+        activeSlice: { id: "S01", title: "Slice 1" },
+        activeTask: { id: "T01" },
+        registry: [{ id: "M001", status: "active" }],
+        blockers: [],
+      } as any,
+      mid: "M001",
+      midTitle: "Test",
+    },
+    {
+      recentUnits: [],
+      stuckRecoveryAttempts: 0,
+      consecutiveFinalizeTimeouts: 0,
+    },
+  );
+
+  assert.equal(result.action, "next", "dispatch must proceed under degraded branch isolation");
+  assert.ok(
+    !notifications.some((n) => n.includes("Worktree Safety failed")),
+    "degraded branch fallback must not trip a false invalid-root",
+  );
+  assert.ok(!deps.callLog.includes("stopAuto"), "auto-mode must not stop on the degraded fallback");
+});
+
+test("dispatch Worktree Safety honors stranded branch recovery instead of demanding the canonical worktree root", async (t) => {
+  _resetPendingResolve();
+
+  const ctx = makeMockCtx();
+  const pi = makeMockPi();
+  const notifications: string[] = [];
+  ctx.ui.notify = (msg: string) => { notifications.push(msg); };
+
+  // Bootstrap adopted stranded work by checking out the milestone branch in
+  // the project root (strandedRecoveryIsolationMode = "branch"). Isolation is
+  // NOT degraded — the adoption is intentional. The safety gate must validate
+  // against the effective branch mode, not the configured worktree mode.
+  const projectRoot = mkdtempSync(join(tmpdir(), "gsd-wt-safety-stranded-"));
+  t.after(() => rmSync(projectRoot, { recursive: true, force: true }));
+
+  const s = makeLoopSession({
+    basePath: projectRoot,
+    originalBasePath: projectRoot,
+    canonicalProjectRoot: projectRoot,
+    strandedRecoveryIsolationMode: "branch",
+  });
+  const deps = makeMockDeps({
+    getIsolationMode: () => "worktree",
+  });
+  const result = await runDispatch(
+    {
+      ctx,
+      pi,
+      s,
+      deps,
+      prefs: undefined,
+      iteration: 1,
+      flowId: "test-flow",
+      nextSeq: () => 1,
+    },
+    {
+      state: {
+        phase: "executing",
+        activeMilestone: { id: "M001", title: "Test", status: "active" },
+        activeSlice: { id: "S01", title: "Slice 1" },
+        activeTask: { id: "T01" },
+        registry: [{ id: "M001", status: "active" }],
+        blockers: [],
+      } as any,
+      mid: "M001",
+      midTitle: "Test",
+    },
+    {
+      recentUnits: [],
+      stuckRecoveryAttempts: 0,
+      consecutiveFinalizeTimeouts: 0,
+    },
+  );
+
+  assert.equal(result.action, "next", "dispatch must proceed under stranded branch recovery");
+  assert.ok(
+    !notifications.some((n) => n.includes("Worktree Safety failed")),
+    "stranded branch recovery must not trip a false invalid-root",
+  );
+  assert.ok(!deps.callLog.includes("stopAuto"), "auto-mode must not stop on stranded branch recovery");
+});
+
 test("runDispatch runs stuck detection while artifact verification retry is pending (#5719)", async (t) => {
   _resetPendingResolve();
 

package/src/resources/extensions/gsd/tests/auto-paused-ui-cleanup.test.ts

@@ -306,7 +306,9 @@ test("pauseAuto records the expected worktree path when paused from project root
 
     const meta = readPausedSessionMetadata(base);
     assert.ok(meta);
-    assert.equal(meta.worktreePath, join(base, ".gsd", "worktrees", "M001"));
+    // No worktree exists yet, so the recorded path is the canonical
+    // .gsd-worktrees/ creation location (worktree-placement seam).
+    assert.equal(meta.worktreePath, join(base, ".gsd-worktrees", "M001"));
   } finally {
     autoSession.reset();
     try {

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/clear-stale-autostart.test.ts

@@ -73,4 +73,26 @@ describe("clear stale pending auto-start (#3667)", () => {
       "pending auto-start gate must clear stale map entries for completed discussions",
     );
   });
+
+  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/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/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

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

@@ -157,7 +157,7 @@ describe("auto-worktree lifecycle", () => {
     try {
       const wtPath = createAutoWorktree(tempDir, "M001");
       const realWtPath = realpathSync(wtPath);
-      assert.ok(realWtPath.startsWith(storage), "git registered the symlink-resolved worktree path");
+      assert.equal(realWtPath, join(tempDir, ".gsd-worktrees", "M001"), "worktree uses canonical path under project root, not through the .gsd symlink");
 
       _resetAutoWorktreeOriginalBaseForTests();
       process.chdir(realWtPath);

package/src/resources/extensions/gsd/tests/integration/git-service.test.ts

@@ -293,11 +293,12 @@ describe('git-service', async () => {
 
   assert.deepStrictEqual(
     RUNTIME_EXCLUSION_PATHS.length,
-    16,
-    "exactly 16 runtime exclusion paths"
+    17,
+    "exactly 17 runtime exclusion paths"
   );
 
   const expectedPaths = [
+    ".gsd-worktrees/",
     ".gsd/activity/",
     ".gsd/audit/",
     ".gsd/forensics/",

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

@@ -1,6 +1,6 @@
 import assert from "node:assert/strict";
 import { createRequire } from "node:module";
-import { copyFileSync, mkdtempSync, renameSync, rmSync } from "node:fs";
+import { copyFileSync, mkdirSync, mkdtempSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
 import test from "node:test";
@@ -288,6 +288,90 @@ test("migration auto-check refreshes a stale open DB handle before comparing", a
   }
 });
 
+function writeScratchMilestoneDir(base: string, milestoneId: string, file?: string): void {
+  const dir = join(base, ".gsd", "milestones", milestoneId);
+  mkdirSync(dir, { recursive: true });
+  if (file) writeFileSync(join(dir, file), `# ${milestoneId} discussion context\n`);
+}
+
+test("migration auto-check ignores discussion-scratch milestone dirs (CONTEXT only, no DB row)", async () => {
+  const base = makeBase();
+  try {
+    await writeGSDDirectory(projectFixture(), base); // markdown: M001 / S01 / T01
+    assert.equal(await ensureDbOpen(base), true);
+    insertMilestone({ id: "M001", title: "Legacy Milestone", status: "active" });
+    insertSlice({ id: "S01", milestoneId: "M001", title: "Legacy Slice", status: "pending", risk: "medium", depends: [], demo: "Legacy slice demo", sequence: 1 });
+    insertTask({ id: "T01", sliceId: "S01", milestoneId: "M001", title: "Legacy Task", status: "pending" });
+
+    // Mid-discussion artifacts: dirs with no ROADMAP and no DB row. The queued
+    // DB row is only inserted at discussion handoff, so these are expected to
+    // be DB-less — not drift, and recover must not be recommended (it would
+    // import them as ghost active milestones).
+    writeScratchMilestoneDir(base, "M002", "M002-CONTEXT.md");
+    writeScratchMilestoneDir(base, "M003", "M003-CONTEXT-DRAFT.md");
+    writeScratchMilestoneDir(base, "M004"); // empty dir
+
+    const result = await checkMarkdownHierarchyAgainstDb(base);
+    assert.equal(result.action, "none");
+    assert.equal(result.reason, "in-sync");
+    assert.deepEqual(result.markdown, { milestones: 1, slices: 1, tasks: 1 });
+  } finally {
+    cleanup(base);
+  }
+});
+
+test("migration auto-check stays quiet mid-first-discussion (scratch dir over empty DB)", async () => {
+  const base = makeBase();
+  try {
+    await writeGSDDirectory({ projectContent: "# P\n", decisionsContent: "", requirements: [], milestones: [] }, base);
+    assert.equal(await ensureDbOpen(base), true);
+    writeScratchMilestoneDir(base, "M001", "M001-CONTEXT.md");
+
+    const result = await checkMarkdownHierarchyAgainstDb(base);
+    assert.equal(result.action, "none");
+    assert.equal(result.reason, "no-markdown");
+  } finally {
+    cleanup(base);
+  }
+});
+
+test("migration auto-check still reports real drift with scratch dirs excluded from counts", async () => {
+  const base = makeBase();
+  try {
+    await writeGSDDirectory(projectFixture(), base); // markdown: M001 / S01 / T01, DB empty
+    assert.equal(await ensureDbOpen(base), true);
+    writeScratchMilestoneDir(base, "M002", "M002-CONTEXT.md");
+
+    const result = await checkMarkdownHierarchyAgainstDb(base);
+    assert.equal(result.action, "recovery-required");
+    assert.equal(result.reason, "db-empty");
+    assert.equal(result.recoveryCommand, "/gsd recover --confirm");
+    // The scratch dir must not inflate the reported markdown count.
+    assert.deepEqual(result.markdown, { milestones: 1, slices: 1, tasks: 1 });
+  } finally {
+    cleanup(base);
+  }
+});
+
+test("migration auto-check still compares a roadmapless milestone that HAS a DB row", async () => {
+  const base = makeBase();
+  try {
+    await writeGSDDirectory({ projectContent: "# P\n", decisionsContent: "", requirements: [], milestones: [] }, base);
+    assert.equal(await ensureDbOpen(base), true);
+    // Post-handoff queued milestone: CONTEXT-only dir WITH a DB row. It must
+    // stay in the comparison (both sides have it → in-sync).
+    insertMilestone({ id: "M001", title: "M001", status: "queued" });
+    writeScratchMilestoneDir(base, "M001", "M001-CONTEXT.md");
+
+    const result = await checkMarkdownHierarchyAgainstDb(base);
+    assert.equal(result.action, "none");
+    assert.equal(result.reason, "in-sync");
+    assert.deepEqual(result.markdown, { milestones: 1, slices: 0, tasks: 0 });
+  } finally {
+    cleanup(base);
+  }
+});
+
 test("rebuildMarkdownProjectionsFromDb realigns markdown when DB holds extra rows", async () => {
   const base = makeBase();
   try {

package/src/resources/extensions/gsd/tests/recovery-classification-illegal-transition.test.ts

@@ -0,0 +1,30 @@
+// GSD — recovery-classification: illegal-transition kind (ADR-030)
+
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import { classifyFailure } from "../recovery-classification.ts";
+import { IllegalPhaseTransitionError } from "../state-transition-matrix.ts";
+
+test("classifyFailure recognizes IllegalPhaseTransitionError by class and escalates", () => {
+  const classification = classifyFailure({
+    error: new IllegalPhaseTransitionError("executing", "complete"),
+    unitType: "execute-task",
+    unitId: "T-1",
+  });
+
+  assert.equal(classification.failureKind, "illegal-transition");
+  assert.equal(classification.action, "escalate");
+  assert.equal(classification.exitReason, "illegal-transition");
+  assert.match(classification.reason, /Illegal phase transition/);
+});
+
+test("classifyFailure routes an explicit illegal-transition failureKind to the same case", () => {
+  const classification = classifyFailure({
+    error: new Error("derived edge rejected"),
+    failureKind: "illegal-transition",
+  });
+
+  assert.equal(classification.failureKind, "illegal-transition");
+  assert.equal(classification.action, "escalate");
+});