@opengsd/gsd-pi 1.1.1-dev.b2556262 → 1.2.0-dev.0b870afa

package/src/resources/extensions/gsd/tests/markdown-renderer-parse-cache.test.ts

@@ -0,0 +1,75 @@
+// Project/App: gsd-pi
+// File Purpose: Performance-contract test for the detectStaleRenders file-identity
+// parse cache (#442 Phase 1.5). Asserts the observable contract: an unchanged
+// projection is NOT re-parsed on the next dispatch (cache hit), while a changed
+// projection IS re-parsed (cache miss on path+mtime+size). Modeled on the
+// prepared-statement caching contract test in db-adapter.test.ts — it asserts
+// external behavior (parse happened / did not), never internal wiring.
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+import { openDatabase, closeDatabase, insertMilestone, insertSlice } from "../gsd-db.ts";
+import { clearParseCache } from "../files.ts";
+import { clearPathCache } from "../paths.ts";
+import { invalidateStateCache } from "../state.ts";
+import { detectStaleRenders } from "../markdown-renderer.ts";
+import { enableDebug, disableDebug, getDebugCounters } from "../debug-logger.ts";
+
+function roadmapMd(slices: Array<{ id: string; title: string; done: boolean }>): string {
+  const lines = ["# M001 Roadmap", "", "**Vision:** cache contract", "", "## Slices", ""];
+  for (const s of slices) lines.push(`- ${s.done ? "[x]" : "[ ]"} **${s.id}: ${s.title}** \`risk:medium\` \`depends:[]\``);
+  lines.push("");
+  return lines.join("\n");
+}
+
+test("#442: detectStaleRenders re-parses ROADMAP only when it changes on disk", (t) => {
+  const base = mkdtempSync(join(tmpdir(), "gsd-parse-cache-"));
+  const milestoneDir = join(base, ".gsd", "milestones", "M001");
+  mkdirSync(milestoneDir, { recursive: true });
+  const roadmapPath = join(milestoneDir, "M001-ROADMAP.md");
+  t.after(() => {
+    try { closeDatabase(); } catch { /* noop */ }
+    disableDebug();
+    rmSync(base, { recursive: true, force: true });
+  });
+
+  openDatabase(join(base, ".gsd", "gsd.db"));
+  insertMilestone({ id: "M001", title: "Cache", status: "active" });
+  insertSlice({ id: "S01", milestoneId: "M001", title: "Slice", status: "active", risk: "medium", depends: [], sequence: 1 });
+
+  // Start from a cold cache so counts are attributable to this test.
+  clearParseCache();
+  clearPathCache();
+  invalidateStateCache();
+
+  writeFileSync(roadmapPath, roadmapMd([{ id: "S01", title: "Slice", done: false }]));
+
+  enableDebug(base); // resets counters
+
+  // First dispatch: cold cache → the roadmap is read + parsed.
+  detectStaleRenders(base);
+  const afterCold = getDebugCounters().parseRoadmapCalls;
+  assert.ok(afterCold > 0, "cold dispatch must parse the roadmap");
+
+  // Second dispatch, file unchanged: cache hit → NO new parse.
+  detectStaleRenders(base);
+  const afterWarm = getDebugCounters().parseRoadmapCalls;
+  assert.equal(afterWarm, afterCold, "unchanged projection must not be re-parsed");
+
+  // Change the file (different content AND size) WITHOUT clearing caches:
+  // the path+mtime+size identity changes, forcing a re-parse.
+  writeFileSync(
+    roadmapPath,
+    roadmapMd([
+      { id: "S01", title: "Slice", done: true },
+      { id: "S02", title: "Added Slice", done: false },
+    ]),
+  );
+  detectStaleRenders(base);
+  const afterChange = getDebugCounters().parseRoadmapCalls;
+  assert.ok(afterChange > afterWarm, "a changed projection must be re-parsed");
+});

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

@@ -60,7 +60,9 @@ test("ensureProjectWorkflowMcpConfig creates .mcp.json with workflow and browser
     assert.equal(typeof browserArgs[mcpArgIndex + 6], "string");
     assert.ok((browserArgs[mcpArgIndex + 6] ?? "").length > 0, "identity-key must be non-empty");
     assert.equal(browserArgs[mcpArgIndex + 7], "--identity-project");
-    assert.equal(browserArgs[mcpArgIndex + 8], projectRoot);
+    assert.equal(typeof browserArgs[mcpArgIndex + 8], "string");
+    assert.ok((browserArgs[mcpArgIndex + 8] ?? "").length > 0, "identity-project must be non-empty");
+    assert.doesNotMatch(browserArgs[mcpArgIndex + 8] ?? "", /[\\/]/, "identity-project must not be a filesystem path");
     assert.equal((browserServer as { cwd?: string })?.cwd, projectRoot);
 
     const settings = JSON.parse(readFileSync(join(projectRoot, ".claude", "settings.local.json"), "utf-8")) as {

package/src/resources/extensions/gsd/tests/mcp-tool-name.test.ts

@@ -0,0 +1,34 @@
+// Project/App: gsd-pi
+// File Purpose: Regression coverage for shared MCP tool-name parsing helpers.
+
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import {
+  mcpToolMatchesBaseName,
+  parseMcpToolName,
+  stripMcpToolPrefix,
+  toMcpToolName,
+  toMcpWildcardToolName,
+} from "../mcp-tool-name.ts";
+
+test("parseMcpToolName parses exact and wildcard MCP tool names", () => {
+  assert.deepEqual(parseMcpToolName("mcp__gsd-workflow__ask_user_questions"), {
+    serverName: "gsd-workflow",
+    toolName: "ask_user_questions",
+  });
+  assert.deepEqual(parseMcpToolName("mcp__gsd-browser__*"), {
+    serverName: "gsd-browser",
+    toolName: "*",
+  });
+  assert.equal(parseMcpToolName("browser_navigate"), null);
+});
+
+test("MCP tool-name helpers strip, match, and format names consistently", () => {
+  assert.equal(stripMcpToolPrefix("mcp__custom-workflow__gsd_exec"), "gsd_exec");
+  assert.equal(stripMcpToolPrefix("read"), "read");
+  assert.equal(mcpToolMatchesBaseName("mcp__custom-workflow__gsd_exec", "gsd_exec"), true);
+  assert.equal(mcpToolMatchesBaseName("mcp__custom-workflow__gsd_exec", "gsd_summary_save"), false);
+  assert.equal(toMcpToolName("custom-workflow", "gsd_exec"), "mcp__custom-workflow__gsd_exec");
+  assert.equal(toMcpWildcardToolName("custom-workflow"), "mcp__custom-workflow__*");
+});

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";
@@ -287,3 +287,145 @@ test("migration auto-check refreshes a stale open DB handle before comparing", a
     cleanup(base);
   }
 });
+
+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 {
+    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",
+    });
+    insertSlice({
+      id: "S02",
+      milestoneId: "M001",
+      title: "Added in DB",
+      status: "pending",
+      risk: "medium",
+      depends: [],
+      demo: "d",
+      sequence: 2,
+    });
+    insertTask({
+      id: "T02",
+      sliceId: "S02",
+      milestoneId: "M001",
+      title: "Added task",
+      status: "pending",
+    });
+
+    const before = await checkMarkdownHierarchyAgainstDb(base);
+    assert.equal(before.recoveryCommand, "/gsd rebuild markdown");
+
+    const { rebuildMarkdownProjectionsFromDb } = await import("../commands-maintenance.ts");
+    const rebuild = await rebuildMarkdownProjectionsFromDb(base);
+    assert.ok(rebuild.rendered > 0, "expected markdown projections to render");
+
+    const after = await checkMarkdownHierarchyAgainstDb(base);
+    assert.equal(after.action, "none");
+    assert.equal(after.reason, "in-sync");
+    assert.deepEqual(after.markdown, { milestones: 1, slices: 2, tasks: 2 });
+    assert.deepEqual(after.beforeDb, { milestones: 1, slices: 2, tasks: 2 });
+  } finally {
+    cleanup(base);
+  }
+});

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

@@ -0,0 +1,99 @@
+// Project/App: gsd-pi
+// File Purpose: Tests for the shared milestone closeout proof surface.
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+import {
+  closeDatabase,
+  insertAssessment,
+  insertMilestone,
+  insertSlice,
+  openDatabase,
+} from "../gsd-db.js";
+import { proveMilestoneCloseout } from "../milestone-closeout-proof.js";
+
+const tmpDirs: string[] = [];
+
+function makeBase(): string {
+  const base = mkdtempSync(join(tmpdir(), "gsd-closeout-proof-"));
+  tmpDirs.push(base);
+  mkdirSync(join(base, ".gsd", "milestones", "M001"), { recursive: true });
+  try { closeDatabase(); } catch { /* noop */ }
+  openDatabase(join(base, ".gsd", "gsd.db"));
+  return base;
+}
+
+function insertValidationPass(): void {
+  insertAssessment({
+    path: "milestones/M001/M001-VALIDATION.md",
+    milestoneId: "M001",
+    status: "pass",
+    scope: "milestone-validation",
+    fullContent: "verdict: pass",
+  });
+}
+
+function writeSummary(base: string, status = "complete"): void {
+  writeFileSync(
+    join(base, ".gsd", "milestones", "M001", "M001-SUMMARY.md"),
+    `---\nstatus: ${status}\n---\n\n# Summary\n`,
+    "utf-8",
+  );
+}
+
+test.after(() => {
+  try { closeDatabase(); } catch { /* noop */ }
+  for (const dir of tmpDirs) {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("proveMilestoneCloseout accepts closed DB state plus summary artifact", () => {
+  const base = makeBase();
+  insertMilestone({ id: "M001", title: "Done", status: "complete" });
+  insertSlice({ id: "S01", milestoneId: "M001", title: "Done Slice", status: "complete" });
+  insertValidationPass();
+  writeSummary(base);
+
+  const result = proveMilestoneCloseout("M001", {
+    summaryArtifactBasePath: base,
+  });
+
+  assert.deepEqual(result, { ok: true });
+});
+
+test("proveMilestoneCloseout can prove readiness before DB milestone is closed", () => {
+  const base = makeBase();
+  insertMilestone({ id: "M001", title: "Ready", status: "active" });
+  insertSlice({ id: "S01", milestoneId: "M001", title: "Done Slice", status: "complete" });
+  insertValidationPass();
+  writeSummary(base);
+
+  const result = proveMilestoneCloseout("M001", {
+    allowOpenMilestone: true,
+    summaryArtifactBasePath: base,
+  });
+
+  assert.deepEqual(result, { ok: true });
+});
+
+test("proveMilestoneCloseout rejects explicit failure summaries", () => {
+  const base = makeBase();
+  insertMilestone({ id: "M001", title: "Done", status: "complete" });
+  insertSlice({ id: "S01", milestoneId: "M001", title: "Done Slice", status: "complete" });
+  insertValidationPass();
+  writeSummary(base, "failed");
+
+  const result = proveMilestoneCloseout("M001", {
+    summaryArtifactBasePath: base,
+  });
+
+  assert.equal(result.ok, false);
+  if (!result.ok) {
+    assert.equal(result.reason, "summary-artifact-failed");
+  }
+});

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

@@ -3,22 +3,24 @@
 
 import test from "node:test";
 import assert from "node:assert/strict";
-import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from "node:fs";
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync, existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
 import { openDatabase, insertAssessment, insertMilestone, insertSlice, closeDatabase } from "../gsd-db.js";
 import {
   isMilestoneCloseoutSettled,
   evaluateCompleteMilestoneDispatch,
+  isCompletedMilestoneTerminal,
+  repairMissingMilestoneSummaryProjection,
 } from "../milestone-closeout.js";
 import type { DispatchContext } from "../auto-dispatch.js";
 
 /** Build a minimal DispatchContext for the dispatch-policy branches under test. */
-function makeDispatchCtx(base: string, phase: string): DispatchContext {
+function makeDispatchCtx(base: string, phase: string, mid = "M001"): DispatchContext {
   return {
     basePath: base,
-    mid: "M001",
-    midTitle: "M001: Test",
+    mid,
+    midTitle: `${mid}: Test`,
     state: { phase } as DispatchContext["state"],
     prefs: undefined,
   } as DispatchContext;
@@ -55,6 +57,31 @@ test("isMilestoneCloseoutSettled requires DB closed and summary artifact", async
   assert.equal(settled, true);
 });
 
+test("isMilestoneCloseoutSettled accepts summary artifacts in a live milestone worktree", async () => {
+  const base = mkdtempSync(join(tmpdir(), "gsd-milestone-closeout-worktree-"));
+  tmpDirs.push(base);
+  mkdirSync(join(base, ".gsd"), { recursive: true });
+  openDatabase(join(base, ".gsd", "gsd.db"));
+  insertMilestone({ id: "M001", title: "Done", status: "complete" });
+  insertSlice({ id: "S01", milestoneId: "M001", title: "Done Slice", status: "complete" });
+  insertAssessment({
+    path: "milestones/M001/M001-VALIDATION.md",
+    milestoneId: "M001",
+    status: "pass",
+    scope: "milestone-validation",
+    fullContent: "verdict: pass",
+  });
+
+  const worktreeRoot = join(base, ".gsd", "worktrees", "M001");
+  const milestoneDir = join(worktreeRoot, ".gsd", "milestones", "M001");
+  mkdirSync(milestoneDir, { recursive: true });
+  writeFileSync(join(worktreeRoot, ".git"), `gitdir: ${join(base, ".git", "worktrees", "M001")}\n`);
+  writeFileSync(join(milestoneDir, "M001-SUMMARY.md"), "# Milestone Summary\n");
+
+  const settled = await isMilestoneCloseoutSettled("M001", base);
+  assert.equal(settled, true);
+});
+
 test("isMilestoneCloseoutSettled returns false when summary artifact is missing", async () => {
   const base = mkdtempSync(join(tmpdir(), "gsd-milestone-closeout-missing-"));
   tmpDirs.push(base);
@@ -94,3 +121,92 @@ test("evaluateCompleteMilestoneDispatch skips when milestone is already closed",
   assert.ok(action, "an already-closed milestone in completing-milestone should yield an action");
   assert.equal(action!.action, "skip", "already-closed milestone should resolve to skip (idempotent)");
 });
+
+test("isCompletedMilestoneTerminal accepts DB complete without SUMMARY artifact", async () => {
+  const base = mkdtempSync(join(tmpdir(), "gsd-terminal-db-complete-"));
+  tmpDirs.push(base);
+  mkdirSync(join(base, ".gsd"), { recursive: true });
+  openDatabase(join(base, ".gsd", "gsd.db"));
+  insertMilestone({ id: "M008", title: "Done", status: "complete" });
+  insertSlice({ id: "S01", milestoneId: "M008", title: "Slice", status: "complete" });
+
+  assert.equal(await isCompletedMilestoneTerminal(base, "M008"), true);
+});
+
+test("isCompletedMilestoneTerminal accepts validation-pass with all slices closed", async () => {
+  const base = mkdtempSync(join(tmpdir(), "gsd-terminal-validation-pass-"));
+  tmpDirs.push(base);
+  mkdirSync(join(base, ".gsd"), { recursive: true });
+  openDatabase(join(base, ".gsd", "gsd.db"));
+  insertMilestone({ id: "M008", title: "Active", status: "active" });
+  insertSlice({ id: "S01", milestoneId: "M008", title: "Slice", status: "complete" });
+  insertAssessment({
+    path: "milestones/M008/M008-VALIDATION.md",
+    milestoneId: "M008",
+    status: "pass",
+    scope: "milestone-validation",
+    fullContent: "verdict: pass",
+  });
+
+  assert.equal(await isCompletedMilestoneTerminal(base, "M008"), true);
+});
+
+test("evaluateCompleteMilestoneDispatch repairs missing SUMMARY when DB is closed", async () => {
+  const base = mkdtempSync(join(tmpdir(), "gsd-dispatch-repair-summary-"));
+  tmpDirs.push(base);
+  mkdirSync(join(base, ".gsd", "milestones", "M008"), { recursive: true });
+  openDatabase(join(base, ".gsd", "gsd.db"));
+  insertMilestone({ id: "M008", title: "Live Text Search", status: "complete" });
+  insertSlice({ id: "S01", milestoneId: "M008", title: "Slice", status: "complete" });
+  insertAssessment({
+    path: "milestones/M008/M008-VALIDATION.md",
+    milestoneId: "M008",
+    status: "pass",
+    scope: "milestone-validation",
+    fullContent: "verdict: pass",
+  });
+
+  const action = await evaluateCompleteMilestoneDispatch(
+    makeDispatchCtx(base, "completing-milestone", "M008"),
+  );
+  assert.equal(action?.action, "skip");
+  assert.ok(
+    existsSync(join(base, ".gsd", "milestones", "M008", "M008-SUMMARY.md")),
+    "repair should write the missing milestone SUMMARY projection",
+  );
+});
+
+test("repairMissingMilestoneSummaryProjection succeeds when milestone dir does not exist yet", async () => {
+  // Regression: resolveExpectedArtifactPath returns null before the milestone
+  // directory exists. The post-write success check must use the handler's
+  // returned summaryPath (the absolute path it just created), not the
+  // pre-write resolver result, otherwise repair always reports failure and
+  // dispatch falls back to re-dispatching complete-milestone.
+  const base = mkdtempSync(join(tmpdir(), "gsd-repair-summary-new-dir-"));
+  tmpDirs.push(base);
+  mkdirSync(join(base, ".gsd"), { recursive: true });
+  openDatabase(join(base, ".gsd", "gsd.db"));
+  insertMilestone({ id: "M042", title: "Done", status: "complete" });
+
+  const repair = await repairMissingMilestoneSummaryProjection(base, "M042");
+  assert.equal(repair.ok, true, "repair should report success when handler creates the SUMMARY");
+  assert.ok(
+    existsSync(join(base, ".gsd", "milestones", "M042", "M042-SUMMARY.md")),
+    "repair should write the SUMMARY artifact to the canonical projection path",
+  );
+});
+
+test("repairMissingMilestoneSummaryProjection is idempotent when SUMMARY exists", async () => {
+  const base = mkdtempSync(join(tmpdir(), "gsd-repair-summary-idempotent-"));
+  tmpDirs.push(base);
+  const milestoneDir = join(base, ".gsd", "milestones", "M001");
+  mkdirSync(milestoneDir, { recursive: true });
+  openDatabase(join(base, ".gsd", "gsd.db"));
+  insertMilestone({ id: "M001", title: "Done", status: "complete" });
+  const summaryPath = join(milestoneDir, "M001-SUMMARY.md");
+  writeFileSync(summaryPath, "# Existing summary\n");
+
+  const repair = await repairMissingMilestoneSummaryProjection(base, "M001");
+  assert.equal(repair.ok, true);
+  assert.equal(readFileSync(summaryPath, "utf-8"), "# Existing summary\n");
+});

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

@@ -0,0 +1,46 @@
+// Project/App: gsd-pi
+// File Purpose: Tests for the milestone merge transaction wrapper.
+
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import {
+  createMilestoneMergeTransaction,
+  runMilestoneMergeTransaction,
+} from "../milestone-merge-transaction.js";
+
+test("runMilestoneMergeTransaction delegates to the supplied merge runner", () => {
+  const calls: unknown[][] = [];
+  const result = runMilestoneMergeTransaction(
+    {
+      mergeMilestoneToMain: (basePath, milestoneId, roadmapContent) => {
+        calls.push([basePath, milestoneId, roadmapContent]);
+        return { pushed: true, codeFilesChanged: true, commitMessage: "merge M001" };
+      },
+    },
+    {
+      basePath: "/repo",
+      milestoneId: "M001",
+      roadmapContent: "# M001",
+    },
+  );
+
+  assert.deepEqual(calls, [["/repo", "M001", "# M001"]]);
+  assert.deepEqual(result, {
+    pushed: true,
+    codeFilesChanged: true,
+    commitMessage: "merge M001",
+  });
+});
+
+test("createMilestoneMergeTransaction returns a lifecycle-compatible runner", () => {
+  const runner = createMilestoneMergeTransaction(() => ({
+    pushed: false,
+    codeFilesChanged: false,
+  }));
+
+  assert.deepEqual(runner("/repo", "M002", "# M002"), {
+    pushed: false,
+    codeFilesChanged: false,
+  });
+});

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

@@ -0,0 +1,65 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import {
+  classifyMilestoneReadiness,
+  describeMilestoneReadinessPhase,
+  formatAcceptedDiscussHandoffMessage,
+  readinessNeedsDiscussion,
+} from "../milestone-readiness.ts";
+
+test("classifyMilestoneReadiness distinguishes queued shells from draft discussion work", () => {
+  const shell = classifyMilestoneReadiness({
+    status: "queued",
+    hasDraftContext: true,
+    sliceCount: 0,
+  });
+
+  assert.equal(shell.kind, "queued-shell");
+  assert.equal(readinessNeedsDiscussion(shell), true);
+});
+
+test("classifyMilestoneReadiness marks context-only milestones as planning pending", () => {
+  const readiness = classifyMilestoneReadiness({
+    status: "queued",
+    hasContext: true,
+    sliceCount: 0,
+  });
+
+  assert.equal(readiness.kind, "planning-pending");
+  assert.equal(formatAcceptedDiscussHandoffMessage("M001", readiness), "Milestone M001 context captured. Continuing the planning pipeline.");
+});
+
+test("classifyMilestoneReadiness marks persisted slices as executable plan", () => {
+  const readiness = classifyMilestoneReadiness({
+    status: "active",
+    hasContext: true,
+    sliceCount: 1,
+  });
+
+  assert.equal(readiness.kind, "executable-plan");
+  assert.equal(formatAcceptedDiscussHandoffMessage("M001", readiness), "Milestone M001 ready.");
+});
+
+test("formatAcceptedDiscussHandoffMessage preserves ready copy for any executable plan", () => {
+  const readiness = classifyMilestoneReadiness({
+    status: "complete",
+    hasContext: true,
+    sliceCount: 1,
+  });
+
+  assert.equal(readiness.kind, "terminal");
+  assert.equal(formatAcceptedDiscussHandoffMessage("M001", readiness), "Milestone M001 ready.");
+});
+
+test("describeMilestoneReadinessPhase keeps dashboard phase copy centralized", () => {
+  assert.deepEqual(describeMilestoneReadinessPhase("needs-discussion"), {
+    label: "Discuss milestone draft",
+    description: "Milestone has a draft context — needs discussion before planning.",
+  });
+  assert.deepEqual(describeMilestoneReadinessPhase("pre-planning"), {
+    label: "Research & plan milestone",
+    description: "Scout the landscape and create the roadmap.",
+  });
+  assert.equal(describeMilestoneReadinessPhase("executing"), null);
+});