gsd-pi 2.80.0-dev.42bd34838 → 2.80.0-dev.488219eb6

package/src/resources/extensions/gsd/tests/browser-teardown.test.ts

@@ -90,44 +90,3 @@ test("getBrowser() guard triggers closeBrowser when browser is active", async ()
   assert.equal(closeCalled, true, "browser.close() should have been called");
   assert.equal(getBrowser(), null, "browser should be null after guarded teardown");
 });
-
-// ─── Source code verification ───────────────────────────────────────────────
-
-test("stopAuto finally block includes browser teardown", async () => {
-  // Verify the source code contains the browser teardown call
-  const { readFileSync } = await import("node:fs");
-  const { resolve } = await import("node:path");
-  const autoSource = readFileSync(resolve(import.meta.dirname, "..", "auto.ts"), "utf-8");
-
-  assert.ok(
-    autoSource.includes("closeBrowser"),
-    "auto.ts should reference closeBrowser for teardown in stopAuto",
-  );
-  assert.ok(
-    autoSource.includes("getBrowser"),
-    "auto.ts should check getBrowser() before calling closeBrowser",
-  );
-  assert.ok(
-    autoSource.includes("browser-tools/lifecycle"),
-    "auto.ts should import from browser-tools/lifecycle",
-  );
-});
-
-test("postUnitPreVerification includes browser teardown between units", async () => {
-  const { readFileSync } = await import("node:fs");
-  const { resolve } = await import("node:path");
-  const postUnitSource = readFileSync(resolve(import.meta.dirname, "..", "auto-post-unit.ts"), "utf-8");
-
-  assert.ok(
-    postUnitSource.includes("closeBrowser"),
-    "auto-post-unit.ts should reference closeBrowser for inter-unit teardown",
-  );
-  assert.ok(
-    postUnitSource.includes("getBrowser"),
-    "auto-post-unit.ts should check getBrowser() before calling closeBrowser",
-  );
-  assert.ok(
-    postUnitSource.includes("browser-teardown"),
-    "auto-post-unit.ts should have browser-teardown debug phase",
-  );
-});

package/src/resources/extensions/gsd/tests/clean-root-preflight.test.ts

@@ -131,9 +131,11 @@ test("postflightPopStash — restores stashed changes and emits info notificatio
     run('git commit -m "simulate merge"', repo);
 
     const postNotifications: Array<{ msg: string; level: string }> = [];
-    postflightPopStash(repo, "M004", preflight.stashMarker, (msg, level) => {
+    const postflight = postflightPopStash(repo, "M004", preflight.stashMarker, (msg, level) => {
       postNotifications.push({ msg, level });
     });
+    assert.equal(postflight.restored, true, "postflight must report successful restore");
+    assert.equal(postflight.needsManualRecovery, false, "successful restore must not need manual recovery");
 
     // The stashed README.md change must be restored
     const content = readFileSync(join(repo, "README.md"), "utf-8");
@@ -171,7 +173,8 @@ test("preflight + merge + postflight round-trip preserves uncommitted changes",
     run('git commit -m "feat: add feature"', repo);
 
     // Postflight: pop stash
-    postflightPopStash(repo, "M005", preflight.stashMarker, () => {});
+    const postflight = postflightPopStash(repo, "M005", preflight.stashMarker, () => {});
+    assert.equal(postflight.needsManualRecovery, false, "clean restore must not stop auto-mode");
 
     // README.md must still have our local content
     const restored = readFileSync(join(repo, "README.md"), "utf-8");
@@ -197,9 +200,12 @@ test("postflightPopStash conflict warning names the exact stash ref", () => {
     run('git commit -m "simulate conflicting merge"', repo);
 
     const notifications: Array<{ msg: string; level: string }> = [];
-    postflightPopStash(repo, "M005C", preflight.stashMarker, (msg, level) => {
+    const postflight = postflightPopStash(repo, "M005C", preflight.stashMarker, (msg, level) => {
       notifications.push({ msg, level });
     });
+    assert.equal(postflight.restored, false, "conflicted restore must report restored=false");
+    assert.equal(postflight.needsManualRecovery, true, "conflicted restore must require manual recovery");
+    assert.match(postflight.message, /failed after merge of milestone M005C/);
 
     const warning = notifications.find((n) => n.level === "warning")?.msg ?? "";
     assert.match(warning, /git stash pop stash@\{\d+\}/);
@@ -219,7 +225,8 @@ test("postflightPopStash restores the matching GSD stash, not stash@{0}", () =>
     writeFileSync(join(repo, "other.txt"), "other stash\n");
     run('git stash push --include-untracked -m "unrelated newer stash"', repo);
 
-    postflightPopStash(repo, "M006", preflight.stashMarker, () => {});
+    const postflight = postflightPopStash(repo, "M006", preflight.stashMarker, () => {});
+    assert.equal(postflight.needsManualRecovery, false, "targeted restore must not need manual recovery");
 
     const content = readFileSync(join(repo, "README.md"), "utf-8");
     assert.equal(content.replace(/\r\n/g, "\n"), "# target stash\n");
@@ -242,7 +249,8 @@ test("postflightPopStash restores the exact preflight marker when another same-m
     writeFileSync(join(repo, "same-milestone.txt"), "newer same milestone stash\n");
     run('git stash push --include-untracked -m "gsd-preflight-stash [gsd-preflight-stash:M007:other]"', repo);
 
-    postflightPopStash(repo, "M007", preflight.stashMarker, () => {});
+    const postflight = postflightPopStash(repo, "M007", preflight.stashMarker, () => {});
+    assert.equal(postflight.needsManualRecovery, false, "exact marker restore must not need manual recovery");
 
     const content = readFileSync(join(repo, "README.md"), "utf-8");
     assert.equal(content.replace(/\r\n/g, "\n"), "# target stash\n");
@@ -260,7 +268,8 @@ test("postflightPopStash falls back to milestone marker prefix when exact marker
     writeFileSync(join(repo, "README.md"), "# fallback stash\n");
     run('git stash push --include-untracked -m "gsd-preflight-stash [gsd-preflight-stash:M008:fallback]"', repo);
 
-    postflightPopStash(repo, "M008", undefined, () => {});
+    const postflight = postflightPopStash(repo, "M008", undefined, () => {});
+    assert.equal(postflight.needsManualRecovery, false, "fallback marker restore must not need manual recovery");
 
     const content = readFileSync(join(repo, "README.md"), "utf-8");
     assert.equal(content.replace(/\r\n/g, "\n"), "# fallback stash\n");

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

@@ -1,41 +1,48 @@
 /**
  * clear-stale-autostart.test.ts — #3667
  *
- * Verify that guided-flow.ts adds a createdAt timestamp to pending auto-start
- * entries and implements a staleness check (30s age guard) so that /clear
- * interrupted discussions don't permanently block future /gsd invocations.
+ * Pending auto-start entries carry a createdAt timestamp so later /gsd
+ * invocations can distinguish an in-flight discussion from a stale one.
  */
 
-import { describe, test } from "node:test";
+import { describe, test, afterEach } from "node:test";
 import assert from "node:assert/strict";
-import { readFileSync } from "node:fs";
-import { join, dirname } from "node:path";
-import { fileURLToPath } from "node:url";
-
-const __dirname = dirname(fileURLToPath(import.meta.url));
-const sourceFile = join(__dirname, "..", "guided-flow.ts");
+import { mkdtempSync, mkdirSync, realpathSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+import {
+  _getPendingAutoStart,
+  clearPendingAutoStart,
+  setPendingAutoStart,
+} from "../guided-flow.ts";
+
+afterEach(() => {
+  clearPendingAutoStart();
+});
 
 describe("clear stale pending auto-start (#3667)", () => {
-  const source = readFileSync(sourceFile, "utf-8");
-
-  test("PendingAutoStartEntry interface includes createdAt field", () => {
-    assert.match(source, /createdAt:\s*number/);
+  test("setPendingAutoStart defaults createdAt to Date.now()", (t) => {
+    const base = realpathSync(mkdtempSync(join(tmpdir(), "gsd-pending-autostart-")));
+    t.after(() => rmSync(base, { recursive: true, force: true }));
+    mkdirSync(join(base, ".gsd"), { recursive: true });
+    const before = Date.now();
+
+    setPendingAutoStart(base, { basePath: base, milestoneId: "M001" });
+
+    const entry = _getPendingAutoStart(base);
+    assert.ok(entry);
+    assert.equal(typeof entry!.createdAt, "number");
+    assert.ok(entry!.createdAt >= before);
   });
 
-  test("setPendingAutoStart defaults createdAt to Date.now()", () => {
-    assert.match(source, /createdAt:\s*Date\.now\(\)/);
-  });
+  test("setPendingAutoStart preserves explicit createdAt for stale-entry checks", (t) => {
+    const base = realpathSync(mkdtempSync(join(tmpdir(), "gsd-pending-autostart-old-")));
+    t.after(() => rmSync(base, { recursive: true, force: true }));
+    mkdirSync(join(base, ".gsd"), { recursive: true });
 
-  test("staleness check uses 30_000ms threshold", () => {
-    assert.match(source, /30[_]?000/);
-  });
-
-  test("stale entry detection checks manifest and context files", () => {
-    assert.match(source, /DISCUSSION-MANIFEST\.json/);
-    assert.match(source, /CONTEXT\.md/);
-  });
+    setPendingAutoStart(base, { basePath: base, milestoneId: "M001", createdAt: 123 });
 
-  test("stale entries are deleted from the map", () => {
-    assert.match(source, /pendingAutoStartMap\.delete\(basePath\)/);
+    assert.equal(_getPendingAutoStart(base)?.createdAt, 123);
   });
 });

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

@@ -1,3 +1,5 @@
+// Project/App: GSD-2
+// File Purpose: Unit tests for cmux integration, layout, and CLI isolation.
 import test, { describe, beforeEach, afterEach } from "node:test";
 import assert from "node:assert/strict";
 import * as fs from "node:fs";
@@ -7,6 +9,7 @@ import { fileURLToPath } from "node:url";
 import {
   buildCmuxProgress,
   buildCmuxStatusLabel,
+  CmuxClient,
   detectCmuxEnvironment,
   markCmuxPromptShown,
   resetCmuxPromptState,
@@ -256,60 +259,55 @@ describe("createGridLayout", () => {
 });
 
 describe("CmuxClient stdio isolation", () => {
-  test("runSync and runAsync explicitly set stdio to prevent terminal interference", () => {
-    // Read the cmux index source and verify that execFileSync/spawn calls
-    // inside runSync/runAsync include stdio options that isolate stdin and stderr.
-    // This prevents the cmux CLI child process from inheriting the parent's
-    // stdin/stderr, which can steal keyboard input or corrupt TUI rendering (#1922).
-    const cmuxIndexPath = path.resolve(
-      path.dirname(fileURLToPath(import.meta.url)),
-      "../../cmux/index.ts",
-    );
-    const source = fs.readFileSync(cmuxIndexPath, "utf-8");
-
-    // Extract runSync method body
-    const runSyncMatch = source.match(/private runSync\(args: string\[\]\)[^{]*\{([\s\S]*?)\n  \}/);
-    assert.ok(runSyncMatch, "runSync method must exist");
-    const runSyncBody = runSyncMatch[1];
-    assert.ok(
-      runSyncBody.includes('stdio:'),
-      "runSync must explicitly set stdio to prevent terminal interference (see #1922)",
-    );
-    assert.ok(
-      runSyncBody.includes('"ignore"'),
-      "runSync stdio must ignore stdin to prevent stealing keyboard input from TUI",
-    );
-
-    // Extract runAsync method body
-    const runAsyncMatch = source.match(/private async runAsync\(args: string\[\]\)[^{]*\{([\s\S]*?)\n  \}/);
-    assert.ok(runAsyncMatch, "runAsync method must exist");
-    const runAsyncBody = runAsyncMatch[1];
-    assert.ok(
-      runAsyncBody.includes('stdio:'),
-      "runAsync must explicitly set stdio to prevent terminal interference (see #1922)",
-    );
-    assert.ok(
-      runAsyncBody.includes('"ignore"'),
-      "runAsync stdio must ignore stdin to prevent stealing keyboard input from TUI",
-    );
-  });
-
-  test("isCmuxCliAvailable uses stdio ignore to prevent terminal interference", () => {
-    const cmuxIndexPath = path.resolve(
-      path.dirname(fileURLToPath(import.meta.url)),
-      "../../cmux/index.ts",
-    );
-    const source = fs.readFileSync(cmuxIndexPath, "utf-8");
-
-    // Find isCmuxCliAvailable or the cli-check function body
-    const fnMatch = source.match(/function isCmuxCliAvailable[\s\S]*?\{([\s\S]*?)\n\}/);
-    if (!fnMatch) return; // function may be inlined or renamed — skip rather than fail
-
-    const fnBody = fnMatch[1];
-    assert.ok(
-      fnBody.includes('"ignore"') || !fnBody.includes('execFileSync'),
-      "isCmuxCliAvailable must not inherit parent stdio (see #1922)",
+  test("runSync and runAsync execute the cmux CLI without inheriting test stdin", async () => {
+    const binDir = fs.mkdtempSync(path.join(tmpdir(), "cmux-bin-"));
+    const logPath = path.join(binDir, "calls.jsonl");
+    const cmuxPath = path.join(binDir, "cmux");
+    const originalPath = process.env.PATH;
+    fs.writeFileSync(
+      cmuxPath,
+      [
+        "#!/usr/bin/env node",
+        "const fs = require('node:fs');",
+        `fs.appendFileSync(${JSON.stringify(logPath)}, JSON.stringify(process.argv.slice(2)) + '\\n');`,
+        "if (process.argv.includes('--json')) process.stdout.write(JSON.stringify({surfaces:[{id:'surface-1'}]}));",
+        "else process.stdout.write('ok');",
+      ].join("\n"),
+      "utf-8",
     );
+    fs.chmodSync(cmuxPath, 0o755);
+    process.env.PATH = `${binDir}:${originalPath ?? ""}`;
+    try {
+      const client = new CmuxClient({
+        enabled: true,
+        available: true,
+        cliAvailable: true,
+        notifications: true,
+        sidebar: true,
+        splits: true,
+        browser: false,
+        workspaceId: "workspace-1",
+        surfaceId: "surface-0",
+        socketPath: "/tmp/cmux.sock",
+      });
+
+      client.setStatus("M001", "executing");
+      await client.listSurfaceIds();
+
+      const calls = fs.readFileSync(logPath, "utf-8").trim().split("\n").map((line) => JSON.parse(line));
+      const commandPrefixes = calls.map((call) => call.slice(0, 2));
+      assert.ok(
+        commandPrefixes.some((prefix) => JSON.stringify(prefix) === JSON.stringify(["set-status", "gsd"])),
+        "set-status command should be invoked",
+      );
+      assert.ok(
+        commandPrefixes.some((prefix) => JSON.stringify(prefix) === JSON.stringify(["list-surfaces", "--json"])),
+        "list-surfaces command should be invoked",
+      );
+    } finally {
+      process.env.PATH = originalPath;
+      fs.rmSync(binDir, { recursive: true, force: true });
+    }
   });
 });
 

package/src/resources/extensions/gsd/tests/cold-resume-db-reopen.test.ts

@@ -1,65 +1,43 @@
 /**
  * cold-resume-db-reopen.test.ts — Regression test for #2940.
- *
- * Validates that the paused-session resume path in auto.ts opens the project
- * database before calling rebuildState() / deriveState(), matching the fresh
- * bootstrap path in auto-start.ts.
- *
- * Without this, cold resume falls back to markdown parsing which misreads
- * done cells and redispatches wrong slices.
  */
 
-import { readFileSync } from "node:fs";
-import { join } from "node:path";
-
-import { createTestContext } from "./test-helpers.ts";
-
-const { assertTrue, report } = createTestContext();
-
-const autoSrc = readFileSync(join(import.meta.dirname, "..", "auto.ts"), "utf-8");
-
-console.log("\n=== resume path refreshes resources and opens DB before rebuildState/deriveState ===");
-
-// The resume block is the `if (s.paused) { ... }` section that calls rebuildState/deriveState.
-// Locate the resume section by finding `s.paused = false;` followed by `rebuildState`.
-const resumeSectionStart = autoSrc.indexOf("if (s.paused) {", autoSrc.indexOf("// If resuming from paused state"));
-assertTrue(resumeSectionStart > 0, "auto.ts has the paused-session resume block");
-
-const resumeSectionEndCandidates = [
-  autoSrc.indexOf("await runAutoLoopWithUok(", resumeSectionStart),
-  autoSrc.indexOf("await autoLoop(", resumeSectionStart),
-].filter((idx) => idx > resumeSectionStart);
-const resumeSectionEnd = resumeSectionEndCandidates.length > 0 ? Math.min(...resumeSectionEndCandidates) : -1;
-assertTrue(resumeSectionEnd > resumeSectionStart, "resume block reaches the dispatch loop");
-
-const resumeSection = autoSrc.slice(resumeSectionStart, resumeSectionEnd);
-
-// The resume path must refresh managed resources and open the DB before
-// rebuildState/deriveState so resumed auto-mode uses current extension code.
-const rebuildIdx = resumeSection.indexOf("rebuildState(");
-assertTrue(rebuildIdx > 0, "resume block calls rebuildState");
-
-const deriveIdx = resumeSection.indexOf("deriveState(");
-assertTrue(deriveIdx > 0, "resume block calls deriveState");
-
-const preDeriveSection = resumeSection.slice(0, rebuildIdx);
-
-assertTrue(
-  preDeriveSection.includes("initResources("),
-  "resume path must refresh managed resources before rebuildState/deriveState (#3761)",
-);
-
-// There must be a DB open call before the first rebuildState call
-const dbOpenPatterns = [
-  "openProjectDbIfPresent(",
-  "openDatabase(",
-  "ensureDbOpen(",
-];
-
-const hasDbOpen = dbOpenPatterns.some(pat => preDeriveSection.includes(pat));
-assertTrue(
-  hasDbOpen,
-  "resume path must open DB before rebuildState/deriveState (#2940)",
-);
-
-report();
+import test from "node:test";
+import assert from "node:assert/strict";
+import { refreshResumeResourcesAndDb } from "../auto.ts";
+
+test("resume refreshes managed resources and opens DB before state rebuild", async () => {
+  const calls: string[] = [];
+
+  await refreshResumeResourcesAndDb("/tmp/project", {
+    env: {
+      GSD_CODING_AGENT_DIR: "/tmp/agent",
+      GSD_PKG_ROOT: "/tmp/pkg",
+    } as NodeJS.ProcessEnv,
+    importModule: async (specifier: string) => {
+      calls.push(`import:${specifier}`);
+      if (specifier.endsWith("/dist/resource-loader.js")) {
+        return {
+          initResources: (agentDir: string) => calls.push(`initResources:${agentDir}`),
+        };
+      }
+      if (specifier === "./prompt-loader.js") {
+        return {
+          primeCache: () => calls.push("primeCache"),
+        };
+      }
+      throw new Error(`unexpected import: ${specifier}`);
+    },
+    openProjectDb: async (basePath: string) => {
+      calls.push(`openDb:${basePath}`);
+    },
+  });
+
+  assert.deepEqual(calls, [
+    "import:file:///tmp/pkg/dist/resource-loader.js",
+    "initResources:/tmp/agent",
+    "import:./prompt-loader.js",
+    "primeCache",
+    "openDb:/tmp/project",
+  ]);
+});

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

@@ -1,24 +1,31 @@
 import test from "node:test";
 import assert from "node:assert/strict";
-import { readFileSync } from "node:fs";
-import { dirname, join } from "node:path";
-import { fileURLToPath } from "node:url";
+import { getStoredToolKey } from "../commands-config.ts";
 
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
+test("stored tool key lookup skips empty api_key entries", () => {
+  const auth = {
+    getCredentialsForProvider(providerId: string) {
+      assert.equal(providerId, "tavily");
+      return [
+        { type: "api_key", key: "" },
+        { type: "oauth", accessToken: "oauth-token" },
+        { type: "api_key", key: "tool-key" },
+      ];
+    },
+  };
 
-test("commands-config source-level: tool key lookup skips empty api_key entries", () => {
-  const source = readFileSync(join(__dirname, "..", "commands-config.ts"), "utf-8");
-  assert.ok(
-    source.includes('getCredentialsForProvider(providerId)'),
-    "commands-config should read the full credential list",
-  );
-  assert.ok(
-    source.includes('c.type === "api_key" && c.key'),
-    "commands-config should require a non-empty api_key when resolving stored tool keys",
-  );
-  assert.ok(
-    !source.includes("auth.get(tool.id)"),
-    "commands-config should not rely on auth.get(tool.id), which can return an empty shadowing entry",
-  );
+  assert.equal(getStoredToolKey(auth as any, "tavily"), "tool-key");
+});
+
+test("stored tool key lookup returns undefined when only shadowing credentials exist", () => {
+  const auth = {
+    getCredentialsForProvider() {
+      return [
+        { type: "api_key", key: "" },
+        { type: "oauth", accessToken: "oauth-token" },
+      ];
+    },
+  };
+
+  assert.equal(getStoredToolKey(auth as any, "brave"), undefined);
 });

package/src/resources/extensions/gsd/tests/complete-milestone-excerpt.test.ts

@@ -261,3 +261,34 @@ test("#4780 closer prompt: uses excerpts + lists on-demand slice SUMMARY paths",
     `closer prompt length ${prompt.length} should be < raw summary size ${rawSize} + 20KB headroom`,
   );
 });
+
+test("complete-milestone prompt caps repeated inlined context around 20k chars", async (t) => {
+  const base = createBase();
+  t.after(() => cleanup(base));
+  invalidateAllCaches();
+
+  writeRoadmap(base, makeRoadmap());
+  writeSummary(base, "S01", makeFatSummary("S01"));
+  writeSummary(base, "S02", makeFatSummary("S02"));
+  writeFileSync(
+    join(base, ".gsd", "milestones", "M001", "M001-CONTEXT.md"),
+    "# M001 Context\n\n" + "Large milestone context body. ".repeat(1200),
+  );
+  writeFileSync(
+    join(base, ".gsd", "KNOWLEDGE.md"),
+    "# Project Knowledge\n\n## Patterns\n\n### Test Milestone shared\n" + "Large scoped knowledge body. ".repeat(1200),
+  );
+
+  const prompt = await buildCompleteMilestonePrompt("M001", "Test Milestone", base);
+  const contextStart = prompt.indexOf("## Inlined Context (preloaded");
+  const contextEnd = prompt.indexOf("## Steps", contextStart);
+  assert.ok(contextStart >= 0, "prompt should include inlined context");
+  assert.ok(contextEnd > contextStart, "prompt should include steps after inlined context");
+
+  const inlinedContext = prompt.slice(contextStart, contextEnd);
+  assert.ok(
+    inlinedContext.length <= 21_000,
+    `inlined context ${inlinedContext.length} chars should stay near the 20k cap`,
+  );
+  assert.match(inlinedContext, /\[\.\.\.truncated \d+ sections\]/);
+});

package/src/resources/extensions/gsd/tests/complete-milestone.test.ts

@@ -547,4 +547,144 @@ describe("complete-milestone", () => {
       cleanup(base);
     }
   });
+
+  test("verification-gate step numbers match the actual numbered verification steps", () => {
+    // Regression for step-number drift: step 1 (duplicate guard) was inserted
+    // in ea5a2cc0 and the rest renumbered, but the gate text was not updated.
+    // Re-derive the verification-step indices from the rendered prompt and
+    // assert the gate / "Important" footer reference the correct numbers.
+    const prompt = loadPromptFromWorktree("complete-milestone", {
+      workingDirectory: "/tmp/test-project",
+      milestoneId: "M001",
+      milestoneTitle: "Step Number Drift",
+      roadmapPath: ".gsd/milestones/M001/M001-ROADMAP.md",
+      inlinedContext: "context",
+      milestoneSummaryPath: ".gsd/milestones/M001/M001-SUMMARY.md",
+      skillActivation: "{{skillActivation block}}",
+      extractLearningsSteps: "{{extract learnings block}}",
+    });
+
+    function findStep(needle: RegExp): number {
+      const lines = prompt.split("\n");
+      for (const line of lines) {
+        const m = /^(\d+)\.\s/.exec(line);
+        if (m && needle.test(line)) return Number(m[1]);
+      }
+      throw new Error(`no numbered step matches ${needle}`);
+    }
+
+    const codeChange = findStep(/Verify code changes/);
+    const successCriteria = findStep(/Verify every \*\*success criterion\*\*/);
+    const defOfDone = findStep(/Verify \*\*definition of done\*\*/);
+    const completeMilestone = findStep(/Persist completion through `gsd_complete_milestone`/);
+    const requirementUpdate = findStep(/gsd_requirement_update/);
+
+    // Gate clause references the verification steps.
+    const gateLine = prompt.split("\n").find(l => l.includes("Verification failure was recorded") || l.includes("verification failure was recorded"));
+    assert.ok(gateLine, "verification gate sentence is present");
+    assert.ok(
+      gateLine!.includes(`steps ${codeChange}, ${successCriteria}, or ${defOfDone}`),
+      `gate must cite verification steps ${codeChange}, ${successCriteria}, ${defOfDone}; got: ${gateLine}`,
+    );
+    // "Do NOT proceed with steps X-Y" — Y must be at least the gsd_complete_milestone step.
+    const proceedMatch = /Do NOT proceed with steps (\d+)[–-](\d+)/.exec(gateLine!);
+    assert.ok(proceedMatch, "gate must include a 'Do NOT proceed with steps X–Y' clause");
+    assert.ok(
+      Number(proceedMatch![1]) > requirementUpdate - 1 && Number(proceedMatch![2]) >= completeMilestone,
+      `'Do NOT proceed' range ${proceedMatch![1]}–${proceedMatch![2]} must cover steps from after the gate through gsd_complete_milestone (${completeMilestone})`,
+    );
+
+    // "Important" footer references the same verification steps.
+    const importantLine = prompt.split("\n").find(l => l.includes("Do NOT skip code-change"));
+    assert.ok(importantLine, "Important footer is present");
+    assert.ok(
+      importantLine!.includes(`steps ${codeChange}-${defOfDone}`) ||
+        importantLine!.includes(`steps ${codeChange}–${defOfDone}`),
+      `Important footer must cite verification range ${codeChange}-${defOfDone}; got: ${importantLine}`,
+    );
+
+    // On-demand Read ordering line cites the gsd_complete_milestone step.
+    const readOrderLine = prompt.split("\n").find(l => l.includes("On-demand Read ordering"));
+    assert.ok(readOrderLine, "On-demand Read ordering line is present");
+    assert.ok(
+      readOrderLine!.includes(`(step ${completeMilestone})`),
+      `On-demand Read ordering must cite step ${completeMilestone}; got: ${readOrderLine}`,
+    );
+  });
+
+  test("sanitizeCompleteMilestoneParams preserves actorName and triggerReason", async () => {
+    const { sanitizeCompleteMilestoneParams } = await import("../bootstrap/sanitize-complete-milestone.ts");
+
+    const sanitized = sanitizeCompleteMilestoneParams({
+      milestoneId: "M001",
+      title: "T",
+      oneLiner: "x",
+      narrative: "n",
+      verificationPassed: true,
+      actorName: "  executor-01  ",
+      triggerReason: " milestone validation passed ",
+    } as any);
+
+    assert.strictEqual(sanitized.actorName, "executor-01");
+    assert.strictEqual(sanitized.triggerReason, "milestone validation passed");
+  });
+
+  test("sanitizeCompleteMilestoneParams omits blank actorName/triggerReason rather than emitting empty strings", async () => {
+    const { sanitizeCompleteMilestoneParams } = await import("../bootstrap/sanitize-complete-milestone.ts");
+
+    const sanitized = sanitizeCompleteMilestoneParams({
+      milestoneId: "M001",
+      title: "T",
+      oneLiner: "x",
+      narrative: "n",
+      verificationPassed: true,
+      // actorName/triggerReason omitted
+    } as any);
+
+    assert.strictEqual(sanitized.actorName, undefined);
+    assert.strictEqual(sanitized.triggerReason, undefined);
+  });
+
+  test("rendered SUMMARY.md uses placeholder text for empty enrichment fields", async () => {
+    const { handleCompleteMilestone } = await import("../tools/complete-milestone.ts");
+    const base = createFixtureBase();
+    const mid = "M001";
+    const dbPath = join(base, ".gsd", "gsd.db");
+    try {
+      openDatabase(dbPath);
+      insertMilestone({ id: mid, title: "Empty Enrichment", status: "active" });
+      insertSlice({ id: "S01", milestoneId: mid, title: "Slice", status: "complete" });
+      insertTask({ id: "T01", sliceId: "S01", milestoneId: mid, title: "Task", status: "complete" });
+
+      const result = await handleCompleteMilestone({
+        milestoneId: mid,
+        title: "Empty Enrichment",
+        oneLiner: "no enrichment",
+        narrative: "did the thing",
+        // enrichment fields intentionally empty (post-sanitizer state)
+        successCriteriaResults: "",
+        definitionOfDoneResults: "",
+        requirementOutcomes: "",
+        keyDecisions: [],
+        keyFiles: [],
+        lessonsLearned: [],
+        followUps: "",
+        deviations: "",
+        verificationPassed: true,
+      }, base);
+
+      assert.ok(!("error" in result), `handler should succeed: ${JSON.stringify(result)}`);
+      const summary = readFileSync((result as { summaryPath: string }).summaryPath, "utf-8");
+      assert.match(summary, /## Success Criteria Results\n\nNot provided\./);
+      assert.match(summary, /## Definition of Done Results\n\nNot provided\./);
+      assert.match(summary, /## Requirement Outcomes\n\nNot provided\./);
+      assert.match(summary, /## Deviations\n\nNone\./);
+      assert.match(summary, /## Follow-ups\n\nNone\./);
+    } finally {
+      try { closeDatabase(); } catch { /* */ }
+      clearPathCache();
+      clearParseCache();
+      cleanup(base);
+    }
+  });
 });