gsd-pi 2.77.0 → 2.78.0-dev.aeeb2ca00

package/src/resources/extensions/gsd/tests/slice-cadence.test.ts

@@ -0,0 +1,242 @@
+/**
+ * Tests for slice-cadence collapse — #4765.
+ *
+ * Covers mergeSliceToMain (squash + advance), resquashMilestoneOnMain,
+ * and the preference accessors.
+ */
+
+import { describe, test, beforeEach, afterEach } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync, realpathSync, readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { execFileSync } from "node:child_process";
+
+import {
+  mergeSliceToMain,
+  resquashMilestoneOnMain,
+  getCollapseCadence,
+  getMilestoneResquash,
+} from "../slice-cadence.ts";
+import { MergeConflictError } from "../git-service.ts";
+import { summarizeWorktreeTelemetry } from "../worktree-telemetry.ts";
+
+function git(args: string[], cwd: string): string {
+  return execFileSync("git", args, { cwd, stdio: ["ignore", "pipe", "pipe"], encoding: "utf-8" }).trim();
+}
+
+/** Create a temp git repo with an initial commit on main. */
+function createRepo(): string {
+  const dir = realpathSync(mkdtempSync(join(tmpdir(), "slice-cad-test-")));
+  git(["init"], dir);
+  git(["config", "user.email", "test@test.com"], dir);
+  git(["config", "user.name", "Test"], dir);
+  writeFileSync(join(dir, "README.md"), "# test\n");
+  git(["add", "."], dir);
+  git(["commit", "-m", "init"], dir);
+  git(["branch", "-M", "main"], dir);
+  mkdirSync(join(dir, ".gsd"), { recursive: true });
+  return dir;
+}
+
+function enterMilestoneBranch(dir: string, milestoneId: string): void {
+  git(["checkout", "-b", `milestone/${milestoneId}`], dir);
+}
+
+function commitFile(dir: string, file: string, content: string, msg: string): string {
+  writeFileSync(join(dir, file), content);
+  git(["add", "."], dir);
+  git(["commit", "-m", msg], dir);
+  return git(["rev-parse", "HEAD"], dir);
+}
+
+describe("getCollapseCadence / getMilestoneResquash", () => {
+  test("defaults to milestone cadence", () => {
+    assert.equal(getCollapseCadence(undefined), "milestone");
+    assert.equal(getCollapseCadence(null), "milestone");
+    assert.equal(getCollapseCadence({}), "milestone");
+    assert.equal(getCollapseCadence({ git: {} }), "milestone");
+  });
+  test("reads slice cadence when set", () => {
+    assert.equal(getCollapseCadence({ git: { collapse_cadence: "slice" } }), "slice");
+  });
+  test("milestone_resquash defaults to true when not set", () => {
+    assert.equal(getMilestoneResquash(undefined), true);
+    assert.equal(getMilestoneResquash({ git: {} }), true);
+    assert.equal(getMilestoneResquash({ git: { milestone_resquash: true } }), true);
+  });
+  test("milestone_resquash can be disabled explicitly", () => {
+    assert.equal(getMilestoneResquash({ git: { milestone_resquash: false } }), false);
+  });
+});
+
+describe("mergeSliceToMain", () => {
+  let dir: string;
+  let originalCwd: string;
+
+  beforeEach(() => {
+    dir = createRepo();
+    originalCwd = process.cwd();
+  });
+
+  afterEach(() => {
+    try { process.chdir(originalCwd); } catch { /* */ }
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  test("squashes one slice's commits onto main and advances the milestone branch", () => {
+    enterMilestoneBranch(dir, "M001");
+    commitFile(dir, "feature.txt", "slice 1 work\n", "feat: S01 work");
+
+    process.chdir(dir);
+    const result = mergeSliceToMain(dir, "M001", "S01");
+
+    assert.equal(result.skipped, false);
+    assert.ok(result.commitSha, "expected a commit SHA");
+    assert.equal(result.milestoneBranch, "milestone/M001");
+    assert.equal(result.mainBranch, "main");
+
+    const mainLog = git(["log", "main", "--oneline"], dir);
+    assert.ok(mainLog.includes("S01 of M001 (slice-cadence)"), `main log: ${mainLog}`);
+    assert.equal(readFileSync(join(dir, "feature.txt"), "utf-8"), "slice 1 work\n");
+
+    const mainSha = git(["rev-parse", "main"], dir);
+    const milestoneSha = git(["rev-parse", "milestone/M001"], dir);
+    assert.equal(milestoneSha, mainSha, "milestone branch must be advanced to main");
+
+    const summary = summarizeWorktreeTelemetry(dir);
+    assert.equal(summary.slicesMerged, 1);
+    assert.equal(summary.sliceMergeConflicts, 0);
+  });
+
+  test("handles sequential slice merges cleanly", () => {
+    enterMilestoneBranch(dir, "M001");
+    commitFile(dir, "a.txt", "slice 1\n", "feat: S01");
+
+    process.chdir(dir);
+    mergeSliceToMain(dir, "M001", "S01");
+
+    git(["checkout", "milestone/M001"], dir);
+    commitFile(dir, "b.txt", "slice 2\n", "feat: S02");
+
+    const result = mergeSliceToMain(dir, "M001", "S02");
+    assert.equal(result.skipped, false);
+
+    const mainLog = git(["log", "main", "--oneline"], dir);
+    assert.ok(mainLog.includes("S01 of M001"));
+    assert.ok(mainLog.includes("S02 of M001"));
+
+    assert.equal(readFileSync(join(dir, "a.txt"), "utf-8"), "slice 1\n");
+    assert.equal(readFileSync(join(dir, "b.txt"), "utf-8"), "slice 2\n");
+
+    const summary = summarizeWorktreeTelemetry(dir);
+    assert.equal(summary.slicesMerged, 2);
+  });
+
+  test("returns skipped when milestone branch has no commits ahead of main", () => {
+    enterMilestoneBranch(dir, "M001");
+
+    process.chdir(dir);
+    const result = mergeSliceToMain(dir, "M001", "S01");
+
+    assert.equal(result.skipped, true);
+    assert.equal(result.skippedReason, "no-commits-ahead");
+    assert.equal(result.commitSha, null);
+  });
+
+  test("throws MergeConflictError on a real conflict and leaves no merge artifacts", () => {
+    writeFileSync(join(dir, "shared.txt"), "main version\n");
+    git(["add", "."], dir);
+    git(["commit", "-m", "main-seed"], dir);
+
+    enterMilestoneBranch(dir, "M001");
+    commitFile(dir, "shared.txt", "slice version\n", "feat: S01 conflicting");
+
+    git(["checkout", "main"], dir);
+    commitFile(dir, "shared.txt", "main evolved\n", "main evolved");
+    git(["checkout", "milestone/M001"], dir);
+
+    process.chdir(dir);
+    assert.throws(
+      () => mergeSliceToMain(dir, "M001", "S01"),
+      (err: unknown) => err instanceof MergeConflictError,
+    );
+
+    const gitDir = join(dir, ".git");
+    for (const f of ["SQUASH_MSG", "MERGE_MSG", "MERGE_HEAD"]) {
+      assert.ok(!existsSync(join(gitDir, f)), `${f} should be cleaned up`);
+    }
+
+    const summary = summarizeWorktreeTelemetry(dir);
+    assert.equal(summary.sliceMergeConflicts, 1);
+  });
+
+  test("restores cwd even when merge fails (dirty working tree)", () => {
+    enterMilestoneBranch(dir, "M001");
+    commitFile(dir, "feature.txt", "slice 1\n", "feat: S01");
+    // Introduce an untracked file AFTER the slice commit so it's still
+    // present when mergeSliceToMain runs its status check.
+    writeFileSync(join(dir, "dirty.txt"), "uncommitted\n");
+
+    process.chdir(dir);
+    const cwdBefore = process.cwd();
+    assert.throws(() => mergeSliceToMain(dir, "M001", "S01"));
+    assert.equal(process.cwd(), cwdBefore, "cwd must be restored on failure");
+  });
+});
+
+describe("resquashMilestoneOnMain", () => {
+  let dir: string;
+  let originalCwd: string;
+
+  beforeEach(() => {
+    dir = createRepo();
+    originalCwd = process.cwd();
+  });
+
+  afterEach(() => {
+    try { process.chdir(originalCwd); } catch { /* */ }
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  test("collapses N slice commits on main into one milestone commit", () => {
+    const startSha = git(["rev-parse", "main"], dir);
+
+    enterMilestoneBranch(dir, "M001");
+    commitFile(dir, "a.txt", "slice 1\n", "feat: S01");
+    process.chdir(dir);
+    mergeSliceToMain(dir, "M001", "S01");
+
+    git(["checkout", "milestone/M001"], dir);
+    commitFile(dir, "b.txt", "slice 2\n", "feat: S02");
+    mergeSliceToMain(dir, "M001", "S02");
+
+    const beforeCount = parseInt(git(["rev-list", "--count", `${startSha}..main`], dir), 10);
+    assert.equal(beforeCount, 2);
+
+    const result = resquashMilestoneOnMain(dir, "M001", startSha);
+    assert.equal(result.resquashed, true);
+    assert.ok(result.newSha);
+
+    git(["checkout", "main"], dir);
+    const afterCount = parseInt(git(["rev-list", "--count", `${startSha}..main`], dir), 10);
+    assert.equal(afterCount, 1, "slice commits collapsed into one milestone commit");
+
+    const msg = git(["log", "-1", "--format=%s", "main"], dir);
+    assert.ok(msg.includes("M001") && msg.includes("2 slices"), `commit message should describe the resquash; got: ${msg}`);
+
+    assert.equal(readFileSync(join(dir, "a.txt"), "utf-8"), "slice 1\n");
+    assert.equal(readFileSync(join(dir, "b.txt"), "utf-8"), "slice 2\n");
+
+    const summary = summarizeWorktreeTelemetry(dir);
+    assert.equal(summary.milestoneResquashes, 1);
+  });
+
+  test("no-op when startSha equals HEAD", () => {
+    const startSha = git(["rev-parse", "main"], dir);
+    process.chdir(dir);
+    const result = resquashMilestoneOnMain(dir, "M001", startSha);
+    assert.equal(result.resquashed, false);
+    assert.equal(result.newSha, null);
+  });
+});

package/src/resources/extensions/gsd/tests/slice-context-injection.test.ts

@@ -11,6 +11,7 @@ import assert from "node:assert/strict";
 import { readFileSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
+import { extractSourceRegion } from "./test-helpers.ts";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const autoPromptsPath = join(__dirname, "..", "auto-prompts.ts");
@@ -32,7 +33,7 @@ describe("slice CONTEXT.md injection into prompt builders (#3452)", () => {
       assert.ok(fnStart !== -1, `${builder} should exist in auto-prompts.ts`);
 
       // Get a reasonable chunk after the function start
-      const chunk = source.slice(fnStart, fnStart + 3000);
+      const chunk = extractSourceRegion(source, `export async function ${builder}`);
 
       // ADR-011: buildPlanSlicePrompt / buildRefineSlicePrompt now delegate to
       // a shared helper (renderSlicePrompt) that performs the slice CONTEXT
@@ -42,7 +43,7 @@ describe("slice CONTEXT.md injection into prompt builders (#3452)", () => {
         ? (() => {
             const helperStart = source.indexOf("async function renderSlicePrompt");
             assert.ok(helperStart !== -1, "renderSlicePrompt helper must exist");
-            return source.slice(helperStart, helperStart + 3000);
+            return extractSourceRegion(source, "async function renderSlicePrompt");
           })()
         : chunk;
 

package/src/resources/extensions/gsd/tests/slice-parallel-orchestrator.test.ts

@@ -6,13 +6,83 @@
 
 import { describe, it } from "node:test";
 import assert from "node:assert/strict";
-import { readFileSync } from "node:fs";
+import { execFileSync, spawn } from "node:child_process";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { join, dirname } from "node:path";
+import { tmpdir } from "node:os";
 import { fileURLToPath } from "node:url";
+import { restoreSliceState } from "../slice-parallel-orchestrator.ts";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const gsdDir = join(__dirname, "..");
 
+function readLinuxProcessStartFingerprint(pid: number): string | null {
+  try {
+    const stat = readFileSync(`/proc/${pid}/stat`, "utf-8");
+    const afterCommand = stat.slice(stat.lastIndexOf(")") + 2).trim();
+    const fields = afterCommand.split(/\s+/);
+    const startTimeTicks = fields[19];
+    return startTimeTicks ? `linux-stat:${startTimeTicks}` : null;
+  } catch {
+    return null;
+  }
+}
+
+function readPsProcessStartFingerprint(pid: number): string | null {
+  try {
+    const raw = execFileSync("ps", ["-p", String(pid), "-o", "lstart="], {
+      stdio: ["ignore", "pipe", "ignore"],
+      encoding: "utf-8",
+    }).trim().replace(/\s+/g, " ");
+    return raw ? `ps-lstart:${raw}` : null;
+  } catch {
+    return null;
+  }
+}
+
+function readProcessStartFingerprint(pid: number): string | null {
+  return readLinuxProcessStartFingerprint(pid) ?? readPsProcessStartFingerprint(pid);
+}
+
+function makeTempProject(): string {
+  const basePath = mkdtempSync(join(tmpdir(), "gsd-slice-parallel-"));
+  mkdirSync(join(basePath, ".gsd"), { recursive: true });
+  return basePath;
+}
+
+function writeSliceOrchestratorState(
+  basePath: string,
+  worker: {
+    pid: number;
+    workerToken?: string;
+    processStartFingerprint?: string | null;
+  },
+): void {
+  writeFileSync(
+    join(basePath, ".gsd", "slice-orchestrator.json"),
+    JSON.stringify({
+      active: true,
+      workers: [{
+        milestoneId: "M900",
+        sliceId: "S01",
+        pid: worker.pid,
+        workerToken: worker.workerToken,
+        processStartFingerprint: worker.processStartFingerprint,
+        worktreePath: join(basePath, ".gsd", "worktrees", "M900-S01"),
+        startedAt: Date.now(),
+        state: "running",
+        completedUnits: 0,
+        cost: 0,
+      }],
+      totalCost: 0,
+      maxWorkers: 1,
+      startedAt: Date.now(),
+      basePath,
+    }),
+    "utf-8",
+  );
+}
+
 describe("slice-parallel-orchestrator structural tests", () => {
   it("orchestrator uses GSD_SLICE_LOCK env var", () => {
     const source = readFileSync(join(gsdDir, "slice-parallel-orchestrator.ts"), "utf-8");
@@ -46,6 +116,99 @@ describe("slice-parallel-orchestrator structural tests", () => {
       "Orchestrator must also pass GSD_MILESTONE_LOCK for milestone context",
     );
   });
+
+  it("recovery preserves terminal workers for coordinator-side collection", () => {
+    const source = readFileSync(join(gsdDir, "slice-parallel-orchestrator.ts"), "utf-8");
+    assert.ok(
+      source.includes('} else if (w.state === "running")') &&
+        source.includes("survivors.push(w);"),
+      "Recovery must only prune dead running workers, not stopped/error workers",
+    );
+  });
+
+  it("recovered PID-only workers are validated before signaling", () => {
+    const source = readFileSync(join(gsdDir, "slice-parallel-orchestrator.ts"), "utf-8");
+    assert.ok(
+      source.includes("isRecoveredSliceWorkerAlive(worker)") &&
+        source.includes('process.kill(worker.pid, "SIGTERM")'),
+      "stopSliceParallel must validate recovered worker identity before signaling a PID",
+    );
+  });
+
+  it("persists worker identity for crash recovery", () => {
+    const source = readFileSync(join(gsdDir, "slice-parallel-orchestrator.ts"), "utf-8");
+    assert.ok(
+      source.includes("workerToken") &&
+        source.includes("processStartFingerprint") &&
+        source.includes("GSD_SLICE_WORKER_TOKEN"),
+      "Orchestrator must persist stable worker identity metadata for recovered workers",
+    );
+  });
+
+  it("spawn failures remove stale worker state and worktree", () => {
+    const source = readFileSync(join(gsdDir, "slice-parallel-orchestrator.ts"), "utf-8");
+    assert.ok(
+      source.includes("sliceState.workers.delete(slice.id)") &&
+        source.includes("removeWorktree(basePath, wtName, { deleteBranch: true, force: true })"),
+      "Failed slice worker spawns must remove stale worker state and clean up the worktree",
+    );
+  });
+});
+
+describe("slice-parallel-orchestrator recovery identity", () => {
+  it("rejects a live PID when the process start fingerprint does not match", () => {
+    const basePath = makeTempProject();
+    try {
+      writeSliceOrchestratorState(basePath, {
+        pid: process.pid,
+        processStartFingerprint: "mismatched-fingerprint",
+      });
+
+      const restored = restoreSliceState(basePath);
+      assert.equal(restored, null, "mismatched fingerprint is treated as a dead worker");
+      assert.equal(
+        existsSync(join(basePath, ".gsd", "slice-orchestrator.json")),
+        false,
+        "state file is removed when no recovered worker identity validates",
+      );
+    } finally {
+      rmSync(basePath, { recursive: true, force: true });
+    }
+  });
+
+  it("keeps a recovered worker when PID, token, and process start fingerprint match", async () => {
+    const basePath = makeTempProject();
+    const token = `test-token-${Date.now()}`;
+    const child = spawn(
+      process.execPath,
+      ["-e", "setTimeout(() => {}, 30000)"],
+      {
+        env: { ...process.env, GSD_SLICE_WORKER_TOKEN: token },
+        stdio: "ignore",
+      },
+    );
+
+    try {
+      assert.ok(child.pid, "child process has a pid");
+      await new Promise((resolve) => setTimeout(resolve, 50));
+      const fingerprint = readProcessStartFingerprint(child.pid!);
+      if (!fingerprint) return;
+
+      writeSliceOrchestratorState(basePath, {
+        pid: child.pid!,
+        workerToken: token,
+        processStartFingerprint: fingerprint,
+      });
+
+      const restored = restoreSliceState(basePath);
+      assert.ok(restored, "matching worker identity is restored");
+      assert.equal(restored.workers.length, 1);
+      assert.equal(restored.workers[0].pid, child.pid);
+    } finally {
+      child.kill("SIGTERM");
+      rmSync(basePath, { recursive: true, force: true });
+    }
+  });
 });
 
 describe("slice_parallel preference gating", () => {

package/src/resources/extensions/gsd/tests/smart-entry-draft.test.ts

@@ -4,6 +4,7 @@ import { tmpdir } from "node:os";
 
 import { deriveState } from "../state.js";
 import { resolveMilestoneFile } from "../paths.js";
+import { extractSourceRegion } from "./test-helpers.ts";
 
 let passed = 0;
 let failed = 0;
@@ -81,7 +82,7 @@ assert(
 
 // Check the branch has draft-aware menu options
 const branchIdx = guidedFlowSource.indexOf('state.phase === "needs-discussion"');
-const branchChunk = guidedFlowSource.slice(branchIdx, branchIdx + 4000);
+const branchChunk = extractSourceRegion(guidedFlowSource, 'state.phase === "needs-discussion"');
 
 assert(
   branchChunk.includes("discuss_draft"),

package/src/resources/extensions/gsd/tests/stale-dirlistcache-4648.test.ts

@@ -0,0 +1,112 @@
+/**
+ * GSD-2 / agent-end-recovery — regression tests for #4648
+ *
+ * Covers the stale `dirListCache` bug where `maybeHandleReadyPhraseWithoutFiles`
+ * (and `checkAutoStartAfterDiscuss`) falsely reported milestone artifacts as
+ * missing, because the directory-listing cache in `paths.ts` was populated
+ * before the LLM wrote the files during the same turn.
+ *
+ * The fix invalidates the cache at the top of `handleAgentEnd`, before any
+ * artifact-existence check runs.
+ */
+
+import { describe, test } from "node:test";
+import assert from "node:assert/strict";
+import {
+  mkdtempSync,
+  mkdirSync,
+  rmSync,
+  writeFileSync,
+  readFileSync,
+} from "node:fs";
+import { join, dirname } from "node:path";
+import { tmpdir } from "node:os";
+import { fileURLToPath } from "node:url";
+
+import { resolveMilestoneFile } from "../paths.ts";
+import { clearPathCache } from "../paths.ts";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const AGENT_END_RECOVERY_PATH = join(
+  __dirname,
+  "..",
+  "bootstrap",
+  "agent-end-recovery.ts",
+);
+
+function mkBase(): string {
+  const base = mkdtempSync(join(tmpdir(), "gsd-4648-"));
+  mkdirSync(join(base, ".gsd", "milestones", "M001"), { recursive: true });
+  return base;
+}
+
+describe("#4648 stale dirListCache — behavioral", () => {
+  test("resolveMilestoneFile returns stale null until clearPathCache runs", () => {
+    const base = mkBase();
+    try {
+      clearPathCache();
+
+      // Prime the cache: directory exists but is empty at this point.
+      assert.equal(
+        resolveMilestoneFile(base, "M001", "CONTEXT"),
+        null,
+        "empty dir → null",
+      );
+
+      // Simulate the LLM writing CONTEXT.md during the turn.
+      writeFileSync(
+        join(base, ".gsd", "milestones", "M001", "M001-CONTEXT.md"),
+        "# M001 Context\n",
+      );
+
+      // Without a cache flush the resolver still reports null — this is the bug.
+      assert.equal(
+        resolveMilestoneFile(base, "M001", "CONTEXT"),
+        null,
+        "stale cache returns null even though the file exists on disk",
+      );
+
+      // The fix: clearPathCache() — after which the resolver finds the file.
+      clearPathCache();
+      const resolved = resolveMilestoneFile(base, "M001", "CONTEXT");
+      assert.ok(
+        resolved && /M001-CONTEXT\.md$/.test(resolved),
+        `after clearPathCache, resolver finds the file (got: ${resolved})`,
+      );
+    } finally {
+      clearPathCache();
+      rmSync(base, { recursive: true, force: true });
+    }
+  });
+});
+
+describe("#4648 agent-end-recovery wiring", () => {
+  test("handleAgentEnd invalidates the path cache before the discuss guards", () => {
+    const source = readFileSync(AGENT_END_RECOVERY_PATH, "utf-8");
+
+    assert.ok(
+      /import\s*\{\s*clearPathCache\s*\}\s*from\s*"\.\.\/paths\.js"/.test(source),
+      "agent-end-recovery.ts must import clearPathCache from ../paths.js",
+    );
+
+    const fnStart = source.indexOf("export async function handleAgentEnd");
+    assert.ok(fnStart > -1, "handleAgentEnd must exist");
+
+    const checkIdx = source.indexOf("checkAutoStartAfterDiscuss(", fnStart);
+    const clearIdx = source.indexOf("clearPathCache(", fnStart);
+    const readyIdx = source.indexOf(
+      "maybeHandleReadyPhraseWithoutFiles(",
+      fnStart,
+    );
+
+    assert.ok(clearIdx > -1, "handleAgentEnd must call clearPathCache");
+    assert.ok(
+      clearIdx < checkIdx,
+      "clearPathCache must run before checkAutoStartAfterDiscuss so the guard sees fresh disk state",
+    );
+    assert.ok(
+      clearIdx < readyIdx,
+      "clearPathCache must run before maybeHandleReadyPhraseWithoutFiles",
+    );
+  });
+});

package/src/resources/extensions/gsd/tests/state-machine-full-walkthrough.test.ts

@@ -13,6 +13,7 @@ import {
   isValidationTerminal,
   isGhostMilestone,
   invalidateStateCache,
+  getActiveMilestoneId,
 } from "../state.ts";
 import {
   openDatabase,
@@ -667,6 +668,29 @@ describe("state-machine-full-walkthrough", () => {
       assert.notEqual(state.phase, "completing-milestone", "should be complete, not completing");
       assert.equal(state.phase, "complete");
     });
+
+    test("failure-path milestone SUMMARY is not terminal completion", async () => {
+      const base = createFixtureBase();
+      writeRoadmap(base, "M001", doneSliceRoadmap());
+      writeMilestoneValidation(base, "M001", "pass");
+      const dir = join(base, ".gsd", "milestones", "M001");
+      writeFileSync(join(dir, "M001-SUMMARY.md"), [
+        "---",
+        "status: failed",
+        "---",
+        "",
+        "# BLOCKER",
+        "",
+        "auto-mode recovery failed; milestone is not complete.",
+      ].join("\n"));
+      invalidateStateCache();
+
+      const state = await deriveState(base);
+
+      assert.equal(state.phase, "completing-milestone");
+      assert.equal(state.registry[0]?.status, "active");
+      assert.equal(await getActiveMilestoneId(base), "M001");
+    });
   });
 
   // ═══════════════════════════════════════════════════════════════════════════
@@ -811,9 +835,9 @@ describe("state-machine-full-walkthrough", () => {
       assert.ok(state.blockers.length > 0, "should have blockers");
     });
 
-    test("no eligible slice (all deps unmet) → fallback picks slice with most deps satisfied", async () => {
+    test("no eligible slice (all deps unmet) → blocked", async () => {
       const base = createFixtureBase();
-      // S01 depends on S00 which doesn't exist — fallback picks S01 anyway
+      // S01 depends on S00 which doesn't exist.
       writeRoadmap(base, "M001", [
         "# M001: Test Milestone",
         "",
@@ -827,9 +851,9 @@ describe("state-machine-full-walkthrough", () => {
       invalidateStateCache();
       const state = await deriveState(base);
 
-      // With partial-dep fallback, S01 is picked despite unmet dep on S00
-      assert.equal(state.phase, "planning");
-      assert.equal(state.activeSlice?.id, "S01");
+      assert.equal(state.phase, "blocked");
+      assert.equal(state.activeSlice, null);
+      assert.ok(state.blockers.some(b => b.includes("No slice eligible")));
     });
   });
 

package/src/resources/extensions/gsd/tests/state-transition-matrix.test.ts

@@ -0,0 +1,44 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import {
+  STATE_TRANSITION_MATRIX,
+  findTransition,
+  validateTransitionMatrix,
+} from "../state-transition-matrix.ts";
+
+test("state transition matrix covers required swarm hardening events", () => {
+  const result = validateTransitionMatrix([
+    "context-ready",
+    "research-ready",
+    "plan-ready",
+    "task-dispatched",
+    "slice-complete",
+    "validation-pass",
+    "recovery-plan-ready",
+    "closeout-complete",
+  ]);
+
+  assert.equal(result.ok, true);
+  assert.deepEqual(result.missingEvents, []);
+  assert.deepEqual(result.duplicateKeys, []);
+});
+
+test("state transition matrix fails closed for recovery and closeout guards", () => {
+  const recovery = findTransition("blocked", "recovery-plan-ready");
+  assert.equal(recovery?.to, "executing");
+  assert.equal(recovery?.onFail, "blocked");
+  assert.equal(recovery?.reasonCode, "recovery");
+
+  const closeout = findTransition("completing-milestone", "closeout-complete");
+  assert.equal(closeout?.to, "complete");
+  assert.equal(closeout?.onFail, "blocked");
+});
+
+test("state transition matrix entries all have guard and reason codes", () => {
+  assert.ok(STATE_TRANSITION_MATRIX.length >= 8);
+  for (const entry of STATE_TRANSITION_MATRIX) {
+    assert.ok(entry.guard.length > 0, `${entry.event} must document its guard`);
+    assert.ok(entry.reasonCode.length > 0, `${entry.event} must include reason code`);
+  }
+});