gsd-pi 2.75.0-dev.063e5a3 → 2.75.0-dev.b6ad8c5f7

package/src/resources/extensions/gsd/tests/auto-wrapup-inflight-guard.test.ts

@@ -15,6 +15,9 @@ const autoSrc = readFileSync(autoPath, "utf-8");
 const runUnitPath = join(import.meta.dirname, "..", "auto", "run-unit.ts");
 const runUnitSrc = readFileSync(runUnitPath, "utf-8");
 
+const registerHooksPath = join(import.meta.dirname, "..", "bootstrap", "register-hooks.ts");
+const registerHooksSrc = readFileSync(registerHooksPath, "utf-8");
+
 describe("#3512: gsd-auto-wrapup must not interrupt in-flight tool calls", () => {
   test("soft timeout wrapup gates triggerTurn on getInFlightToolCount() === 0", () => {
     // The soft timeout sendMessage must NOT use a hardcoded `triggerTurn: true`.
@@ -70,6 +73,42 @@ describe("#3512: gsd-auto-wrapup must not interrupt in-flight tool calls", () =>
   });
 });
 
+describe("#4276: pending/skipped tools stay visible to auto-mode hooks", () => {
+  test("tool_call handler marks GSD tools in-flight before execution_start", () => {
+    const startMarker = 'pi.on("tool_call", async (event, ctx) => {';
+    const endMarker = 'pi.on("tool_result", async (event) => {';
+    const toolCallSection = registerHooksSrc.slice(
+      registerHooksSrc.indexOf(startMarker),
+      registerHooksSrc.indexOf(endMarker),
+    );
+
+    assert.ok(toolCallSection.length > 0, "Could not locate tool_call handler section");
+    assert.ok(
+      toolCallSection.includes("markToolStart(event.toolCallId, event.toolName)"),
+      "tool_call handler must mark tools pending before tool_execution_start fires",
+    );
+  });
+
+  test("tool_result handler clears pending tools and records queued-skip errors", () => {
+    const startMarker = 'pi.on("tool_result", async (event) => {';
+    const endMarker = 'pi.on("tool_execution_start", async (event) => {';
+    const toolResultSection = registerHooksSrc.slice(
+      registerHooksSrc.indexOf(startMarker),
+      registerHooksSrc.indexOf(endMarker),
+    );
+
+    assert.ok(toolResultSection.length > 0, "Could not locate tool_result handler section");
+    assert.ok(
+      toolResultSection.includes("markToolEnd(event.toolCallId)"),
+      "tool_result handler must clear pending tool tracking even when execution hooks never fire",
+    );
+    assert.ok(
+      toolResultSection.includes("recordToolInvocationError(event.toolName, errorText)"),
+      "tool_result handler must surface queued-skip errors for GSD tools",
+    );
+  });
+});
+
 describe("#3512: pauseAuto and stopAuto must flush queued follow-up messages", () => {
   test("stopAuto calls clearQueue()", () => {
     // stopAuto must flush queued messages to prevent late async_job_result

package/src/resources/extensions/gsd/tests/autocomplete-regressions-1675.test.ts

@@ -44,6 +44,14 @@ test("/gsd description includes discuss", () => {
   );
 });
 
+test("/gsd description includes debug", () => {
+  const pi = createMockPi();
+  registerGSDCommand(pi as any);
+
+  const gsd = pi.commands.get("gsd");
+  assert.ok(gsd.description.includes("debug"), "description should include debug");
+});
+
 test("/gsd next completions include --debug", () => {
   const pi = createMockPi();
   registerGSDCommand(pi as any);
@@ -54,6 +62,18 @@ test("/gsd next completions include --debug", () => {
   assert.ok(debug, "next --debug should appear in completions");
 });
 
+test("/gsd debug completions include list|status|continue|--diagnose", () => {
+  const pi = createMockPi();
+  registerGSDCommand(pi as any);
+
+  const gsd = pi.commands.get("gsd");
+  const completions = gsd.getArgumentCompletions("debug ");
+  const values = completions.map((c: any) => c.value);
+  for (const expected of ["debug list", "debug status", "debug continue", "debug --diagnose"]) {
+    assert.ok(values.includes(expected), `missing completion: ${expected}`);
+  }
+});
+
 test("/gsd widget completions include full|small|min|off", () => {
   const pi = createMockPi();
   registerGSDCommand(pi as any);
@@ -66,6 +86,25 @@ test("/gsd widget completions include full|small|min|off", () => {
   }
 });
 
+test("/gsd logs completions still include debug after adding /gsd debug", () => {
+  const pi = createMockPi();
+  registerGSDCommand(pi as any);
+
+  const gsd = pi.commands.get("gsd");
+  const completions = gsd.getArgumentCompletions("logs ");
+  const values = completions.map((c: any) => c.value);
+  assert.ok(values.includes("logs debug"), "logs debug completion should remain available");
+});
+
+test("/gsd help full includes /gsd debug command", async () => {
+  const ctx = createMockCtx();
+
+  await handleGSDCommand("help full", ctx as any, {} as any);
+
+  const helpText = ctx.notifications.map((n) => n.message).join("\n");
+  assert.match(helpText, /\/gsd debug\s+Create\/list\/continue persistent debug sessions/);
+});
+
 test("bare /gsd skip shows usage and does not fall through to unknown-command warning", async () => {
   const ctx = createMockCtx();
 

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

@@ -40,6 +40,8 @@ const ROUTES: Route[] = [
   { keywords: ["backlog", "parking lot", "later", "someday"], command: "backlog" },
   { keywords: ["add tests", "write tests", "generate tests", "test coverage"], command: "add-tests" },
   { keywords: ["next", "step", "next step", "what's next"], command: "next" },
+  { keywords: ["logs", "debug logs", "log files"], command: "logs" },
+  { keywords: ["debug", "debug session", "investigate", "troubleshoot", "diagnose issue"], command: "debug" },
 ];
 
 interface MatchResult {
@@ -120,8 +122,54 @@ test("/gsd do: prefers longer keyword match", () => {
   assert.ok(match.score >= 12);
 });
 
+test("/gsd do: routes debug troubleshooting intent to debug", () => {
+  const match = matchRoute("debug this flaky oauth callback");
+  assert.ok(match);
+  assert.equal(match.command, "debug");
+});
+
+test("/gsd do: keeps 'debug logs' routed to logs (longer keyword wins)", () => {
+  const match = matchRoute("show me debug logs for today");
+  assert.ok(match);
+  assert.equal(match.command, "logs");
+});
+
 test("/gsd do: routes 'session report' to session-report", () => {
   const match = matchRoute("show me the session report");
   assert.ok(match);
   assert.equal(match.command, "session-report");
 });
+
+test("/gsd do: routes 'diagnose issue' to debug (not doctor)", () => {
+  // 'diagnose issue' is an explicit keyword on the debug route to distinguish
+  // session-level issue diagnosis from /gsd doctor health checks.
+  const match = matchRoute("diagnose issue with oauth callback");
+  assert.ok(match);
+  assert.equal(match.command, "debug");
+});
+
+test("/gsd do: routes 'investigate flaky test' to debug", () => {
+  const match = matchRoute("investigate flaky test in CI");
+  assert.ok(match);
+  assert.equal(match.command, "debug");
+});
+
+test("/gsd do: 'debug logs' keyword wins over bare 'debug' (longer keyword precedence)", () => {
+  // 'debug logs' (10 chars) > 'debug' (5 chars)
+  const logsMatch = matchRoute("debug logs for the last run");
+  assert.ok(logsMatch);
+  assert.equal(logsMatch.command, "logs");
+  assert.ok(logsMatch.score >= 10, `expected score >= 10, got ${logsMatch.score}`);
+
+  // Bare 'debug' without 'logs' should still route to debug.
+  const debugMatch = matchRoute("debug the payment timeout issue");
+  assert.ok(debugMatch);
+  assert.equal(debugMatch.command, "debug");
+});
+
+test("/gsd do: 'diagnose' alone routes to doctor (health check), not debug", () => {
+  // 'diagnose' maps to the doctor route; 'diagnose issue' maps to debug.
+  const match = matchRoute("diagnose my project");
+  assert.ok(match);
+  assert.equal(match.command, "doctor");
+});

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

@@ -1,15 +1,19 @@
 import { describe, it, beforeEach, afterEach } from "node:test";
 import assert from "node:assert/strict";
-import { mkdirSync, writeFileSync, rmSync } from "node:fs";
-import { join } from "node:path";
+import { mkdirSync, writeFileSync, rmSync, readFileSync } from "node:fs";
+import { join, dirname } from "node:path";
 import { tmpdir } from "node:os";
 import { randomUUID } from "node:crypto";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
 
 import {
   parseExtractLearningsArgs,
   buildLearningsOutputPath,
   resolvePhaseArtifacts,
   buildExtractLearningsPrompt,
+  buildExtractionStepsBlock,
   buildFrontmatter,
   extractProjectName,
 } from "../commands-extract-learnings.js";
@@ -66,26 +70,38 @@ describe("resolvePhaseArtifacts", () => {
     rmSync(tmpBase, { recursive: true, force: true });
   });
 
-  it("finds required PLAN and SUMMARY when both present", () => {
-    writeFileSync(join(tmpBase, "M001-PLAN.md"), "# M001 Plan content", "utf-8");
+  it("finds required ROADMAP and SUMMARY when both present", () => {
+    writeFileSync(join(tmpBase, "M001-ROADMAP.md"), "# M001 Roadmap content", "utf-8");
     writeFileSync(join(tmpBase, "M001-SUMMARY.md"), "# M001 Summary content", "utf-8");
 
     const result = resolvePhaseArtifacts(tmpBase, "M001");
-    assert.equal(result.plan, join(tmpBase, "M001-PLAN.md"));
+    assert.equal(result.roadmap, join(tmpBase, "M001-ROADMAP.md"));
     assert.equal(result.summary, join(tmpBase, "M001-SUMMARY.md"));
     assert.deepEqual(result.missingRequired, []);
   });
 
-  it("reports missing PLAN as missingRequired", () => {
+  it("reports missing ROADMAP as missingRequired (regression for #4429)", () => {
     writeFileSync(join(tmpBase, "M001-SUMMARY.md"), "# Summary", "utf-8");
 
     const result = resolvePhaseArtifacts(tmpBase, "M001");
-    assert.ok(result.missingRequired.includes("M001-PLAN.md"));
-    assert.equal(result.plan, null);
+    assert.ok(result.missingRequired.includes("M001-ROADMAP.md"));
+    assert.equal(result.roadmap, null);
+  });
+
+  it("does NOT require M001-PLAN.md (regression for #4429 — milestones use ROADMAP)", () => {
+    writeFileSync(join(tmpBase, "M001-ROADMAP.md"), "# Roadmap", "utf-8");
+    writeFileSync(join(tmpBase, "M001-SUMMARY.md"), "# Summary", "utf-8");
+
+    const result = resolvePhaseArtifacts(tmpBase, "M001");
+    assert.ok(
+      !result.missingRequired.includes("M001-PLAN.md"),
+      "PLAN.md must not be demanded at milestone scope",
+    );
+    assert.deepEqual(result.missingRequired, []);
   });
 
   it("reports missing SUMMARY as missingRequired", () => {
-    writeFileSync(join(tmpBase, "M001-PLAN.md"), "# Plan", "utf-8");
+    writeFileSync(join(tmpBase, "M001-ROADMAP.md"), "# Roadmap", "utf-8");
 
     const result = resolvePhaseArtifacts(tmpBase, "M001");
     assert.ok(result.missingRequired.includes("M001-SUMMARY.md"));
@@ -95,12 +111,12 @@ describe("resolvePhaseArtifacts", () => {
   it("reports both required files missing when neither present", () => {
     const result = resolvePhaseArtifacts(tmpBase, "M001");
     assert.equal(result.missingRequired.length, 2);
-    assert.ok(result.missingRequired.includes("M001-PLAN.md"));
+    assert.ok(result.missingRequired.includes("M001-ROADMAP.md"));
     assert.ok(result.missingRequired.includes("M001-SUMMARY.md"));
   });
 
   it("finds optional VERIFICATION when present", () => {
-    writeFileSync(join(tmpBase, "M001-PLAN.md"), "# Plan", "utf-8");
+    writeFileSync(join(tmpBase, "M001-ROADMAP.md"), "# Roadmap", "utf-8");
     writeFileSync(join(tmpBase, "M001-SUMMARY.md"), "# Summary", "utf-8");
     writeFileSync(join(tmpBase, "M001-VERIFICATION.md"), "# Verification", "utf-8");
 
@@ -109,7 +125,7 @@ describe("resolvePhaseArtifacts", () => {
   });
 
   it("returns null for optional VERIFICATION when absent", () => {
-    writeFileSync(join(tmpBase, "M001-PLAN.md"), "# Plan", "utf-8");
+    writeFileSync(join(tmpBase, "M001-ROADMAP.md"), "# Roadmap", "utf-8");
     writeFileSync(join(tmpBase, "M001-SUMMARY.md"), "# Summary", "utf-8");
 
     const result = resolvePhaseArtifacts(tmpBase, "M001");
@@ -117,7 +133,7 @@ describe("resolvePhaseArtifacts", () => {
   });
 
   it("finds optional UAT when present", () => {
-    writeFileSync(join(tmpBase, "M001-PLAN.md"), "# Plan", "utf-8");
+    writeFileSync(join(tmpBase, "M001-ROADMAP.md"), "# Roadmap", "utf-8");
     writeFileSync(join(tmpBase, "M001-SUMMARY.md"), "# Summary", "utf-8");
     writeFileSync(join(tmpBase, "M001-UAT.md"), "# UAT", "utf-8");
 
@@ -126,7 +142,7 @@ describe("resolvePhaseArtifacts", () => {
   });
 
   it("returns null for optional UAT when absent, no error", () => {
-    writeFileSync(join(tmpBase, "M001-PLAN.md"), "# Plan", "utf-8");
+    writeFileSync(join(tmpBase, "M001-ROADMAP.md"), "# Roadmap", "utf-8");
     writeFileSync(join(tmpBase, "M001-SUMMARY.md"), "# Summary", "utf-8");
 
     const result = resolvePhaseArtifacts(tmpBase, "M001");
@@ -144,7 +160,7 @@ describe("buildExtractLearningsPrompt", () => {
       milestoneName: "Test Milestone",
       outputPath: "/project/.gsd/milestones/M001/M001-LEARNINGS.md",
       relativeOutputPath: ".gsd/milestones/M001/M001-LEARNINGS.md",
-      planContent: "# Plan content",
+      roadmapContent: "# Roadmap content",
       summaryContent: "# Summary content",
       verificationContent: null,
       uatContent: null,
@@ -162,7 +178,7 @@ describe("buildExtractLearningsPrompt", () => {
       milestoneName: "Test Milestone",
       outputPath: "/out/M001-LEARNINGS.md",
       relativeOutputPath: ".gsd/milestones/M001/M001-LEARNINGS.md",
-      planContent: "# Plan",
+      roadmapContent: "# Roadmap",
       summaryContent: "# Summary",
       verificationContent: null,
       uatContent: null,
@@ -176,13 +192,13 @@ describe("buildExtractLearningsPrompt", () => {
     assert.ok(result.includes("Surprises"));
   });
 
-  it("includes plan and summary content", () => {
+  it("includes roadmap and summary content", () => {
     const result = buildExtractLearningsPrompt({
       milestoneId: "M001",
       milestoneName: "Test Milestone",
       outputPath: "/out/M001-LEARNINGS.md",
       relativeOutputPath: ".gsd/milestones/M001/M001-LEARNINGS.md",
-      planContent: "PLAN_CONTENT_UNIQUE_123",
+      roadmapContent: "ROADMAP_CONTENT_UNIQUE_123",
       summaryContent: "SUMMARY_CONTENT_UNIQUE_456",
       verificationContent: null,
       uatContent: null,
@@ -190,7 +206,7 @@ describe("buildExtractLearningsPrompt", () => {
       projectName: "MyProject",
     });
 
-    assert.ok(result.includes("PLAN_CONTENT_UNIQUE_123"));
+    assert.ok(result.includes("ROADMAP_CONTENT_UNIQUE_123"));
     assert.ok(result.includes("SUMMARY_CONTENT_UNIQUE_456"));
   });
 
@@ -200,7 +216,7 @@ describe("buildExtractLearningsPrompt", () => {
       milestoneName: "Test Milestone",
       outputPath: "/out/M001-LEARNINGS.md",
       relativeOutputPath: ".gsd/milestones/M001/M001-LEARNINGS.md",
-      planContent: "# Plan",
+      roadmapContent: "# Roadmap",
       summaryContent: "# Summary",
       verificationContent: "VERIFICATION_UNIQUE_789",
       uatContent: "UAT_UNIQUE_012",
@@ -218,7 +234,7 @@ describe("buildExtractLearningsPrompt", () => {
       milestoneName: "Test Milestone",
       outputPath: "/out/M001-LEARNINGS.md",
       relativeOutputPath: ".gsd/milestones/M001/M001-LEARNINGS.md",
-      planContent: "# Plan",
+      roadmapContent: "# Roadmap",
       summaryContent: "# Summary",
       verificationContent: null,
       uatContent: null,
@@ -228,6 +244,64 @@ describe("buildExtractLearningsPrompt", () => {
 
     assert.ok(result.includes("M001-VERIFICATION.md"));
   });
+
+  it("does NOT reference phantom capture_thought tool (regression for #4429)", () => {
+    const result = buildExtractLearningsPrompt({
+      milestoneId: "M001",
+      milestoneName: "Test Milestone",
+      outputPath: "/out/M001-LEARNINGS.md",
+      relativeOutputPath: ".gsd/milestones/M001/M001-LEARNINGS.md",
+      roadmapContent: "# Roadmap",
+      summaryContent: "# Summary",
+      verificationContent: null,
+      uatContent: null,
+      missingArtifacts: [],
+      projectName: "MyProject",
+    });
+
+    assert.ok(
+      !result.includes("capture_thought"),
+      "prompt must not advertise the non-existent capture_thought tool",
+    );
+  });
+
+  it("does NOT reference phantom gsd_graph tool (regression for #4429)", () => {
+    const result = buildExtractLearningsPrompt({
+      milestoneId: "M001",
+      milestoneName: "Test Milestone",
+      outputPath: "/out/M001-LEARNINGS.md",
+      relativeOutputPath: ".gsd/milestones/M001/M001-LEARNINGS.md",
+      roadmapContent: "# Roadmap",
+      summaryContent: "# Summary",
+      verificationContent: null,
+      uatContent: null,
+      missingArtifacts: [],
+      projectName: "MyProject",
+    });
+
+    assert.ok(
+      !result.includes("gsd_graph"),
+      "prompt must not advertise the non-existent gsd_graph tool",
+    );
+  });
+
+  it("source-attribution example references ROADMAP.md, not PLAN.md (regression for #4429)", () => {
+    const result = buildExtractLearningsPrompt({
+      milestoneId: "M001",
+      milestoneName: "Test Milestone",
+      outputPath: "/out/M001-LEARNINGS.md",
+      relativeOutputPath: ".gsd/milestones/M001/M001-LEARNINGS.md",
+      roadmapContent: "# Roadmap",
+      summaryContent: "# Summary",
+      verificationContent: null,
+      uatContent: null,
+      missingArtifacts: [],
+      projectName: "MyProject",
+    });
+
+    assert.ok(result.includes("M001-ROADMAP.md/Architecture Decisions"));
+    assert.ok(!result.includes("M001-PLAN.md/Architecture Decisions"));
+  });
 });
 
 // ─── buildFrontmatter ─────────────────────────────────────────────────────────
@@ -338,3 +412,241 @@ describe("extractProjectName", () => {
     assert.equal(result, tmpBase.split("/").at(-1));
   });
 });
+
+// ─── buildExtractionStepsBlock ────────────────────────────────────────────────
+//
+// The steps block is the single source of truth for how learnings are routed
+// into KNOWLEDGE.md and the DECISIONS DB. Both the manual /gsd extract-learnings
+// path and the auto complete-milestone path render it verbatim, so every
+// structural assertion below protects both paths at once.
+
+describe("buildExtractionStepsBlock", () => {
+  const ctx = {
+    milestoneId: "M042",
+    outputPath: "/project/.gsd/milestones/M042/M042-LEARNINGS.md",
+    relativeOutputPath: ".gsd/milestones/M042/M042-LEARNINGS.md",
+  };
+
+  it("declares itself as the structured extraction procedure", () => {
+    const block = buildExtractionStepsBlock(ctx);
+    assert.ok(block.includes("Structured Learnings Extraction"));
+  });
+
+  it("instructs the LLM to write LEARNINGS.md at the given relative path", () => {
+    const block = buildExtractionStepsBlock(ctx);
+    assert.ok(block.includes(ctx.relativeOutputPath));
+    assert.ok(block.includes("YAML frontmatter"));
+  });
+
+  it("covers all four extraction categories", () => {
+    const block = buildExtractionStepsBlock(ctx);
+    assert.ok(block.includes("Decisions"));
+    assert.ok(block.includes("Lessons"));
+    assert.ok(block.includes("Patterns"));
+    assert.ok(block.includes("Surprises"));
+  });
+
+  it("requires a Source attribution for every item", () => {
+    const block = buildExtractionStepsBlock(ctx);
+    assert.ok(block.includes("Source:"));
+    assert.ok(block.includes("M042-ROADMAP.md"));
+  });
+
+  it("points the LLM at .gsd/KNOWLEDGE.md for append", () => {
+    const block = buildExtractionStepsBlock(ctx);
+    assert.ok(block.includes(".gsd/KNOWLEDGE.md"));
+  });
+
+  it("covers the missing-file case with the canonical KNOWLEDGE.md template", () => {
+    const block = buildExtractionStepsBlock(ctx);
+    assert.ok(block.includes("If the file does not exist yet, create it first"));
+    // Canonical column headers must be inlined so the LLM does not have to guess.
+    assert.ok(block.includes("| # | Scope | Rule | Why | Added |"));
+    assert.ok(block.includes("| # | Pattern | Where | Notes |"));
+    assert.ok(block.includes("| # | What Happened | Root Cause | Fix | Scope |"));
+  });
+
+  it("specifies the exact Patterns row format with milestone scope", () => {
+    const block = buildExtractionStepsBlock(ctx);
+    assert.ok(block.includes("| P<NNN>"));
+    assert.ok(block.includes(`| ${ctx.milestoneId} |`));
+  });
+
+  it("specifies the exact Lessons row format with milestone scope", () => {
+    const block = buildExtractionStepsBlock(ctx);
+    assert.ok(block.includes("| L<NNN>"));
+  });
+
+  it("enforces zero-padded three-digit IDs", () => {
+    const block = buildExtractionStepsBlock(ctx);
+    assert.ok(/zero[- ]pad/i.test(block));
+    assert.ok(block.includes("three digits") || block.includes("3 digits"));
+  });
+
+  it("instructs append-only behaviour (no edits to existing rows)", () => {
+    const block = buildExtractionStepsBlock(ctx);
+    assert.ok(block.includes("Append-only"));
+  });
+
+  it("uses em-dash as the placeholder for unknown column values", () => {
+    const block = buildExtractionStepsBlock(ctx);
+    assert.ok(block.includes("—"));
+    assert.ok(!block.includes("N/A"));
+  });
+
+  it("forbids modifications to the Rules table", () => {
+    const block = buildExtractionStepsBlock(ctx);
+    assert.ok(/do not.*rules/i.test(block.toLowerCase()) || block.includes("Do NOT modify"));
+    assert.ok(block.includes("## Rules"));
+  });
+
+  it("routes Decisions through the gsd_save_decision MCP tool", () => {
+    const block = buildExtractionStepsBlock(ctx);
+    assert.ok(block.includes("gsd_save_decision"));
+    assert.ok(block.includes("`scope`"));
+    assert.ok(block.includes("`decision`"));
+    assert.ok(block.includes("`choice`"));
+    assert.ok(block.includes("`rationale`"));
+    assert.ok(block.includes("`made_by`"));
+  });
+
+  it("forbids direct edits to DECISIONS.md (DB-authoritative)", () => {
+    const block = buildExtractionStepsBlock(ctx);
+    assert.ok(/never edit.+decisions\.md/i.test(block));
+  });
+
+  it("keeps Surprises milestone-local (not in KNOWLEDGE.md, no tool call)", () => {
+    const block = buildExtractionStepsBlock(ctx);
+    assert.ok(block.includes("Surprises stay only in LEARNINGS.md"));
+  });
+
+  it("enforces a deduplication rule across all persistence steps", () => {
+    const block = buildExtractionStepsBlock(ctx);
+    assert.ok(/deduplication/i.test(block) || /dedup/i.test(block));
+    assert.ok(/semantically equivalent/i.test(block));
+    assert.ok(/skip/i.test(block));
+  });
+
+  it("does NOT reference the non-existent capture_thought tool (#4429 regression)", () => {
+    const block = buildExtractionStepsBlock(ctx);
+    assert.ok(!block.includes("capture_thought"));
+  });
+
+  it("does NOT reference the non-existent gsd_graph tool (#4429 regression)", () => {
+    const block = buildExtractionStepsBlock(ctx);
+    assert.ok(!block.includes("gsd_graph"));
+  });
+
+  it("substitutes the milestone ID into every placeholder callout", () => {
+    const block = buildExtractionStepsBlock({
+      milestoneId: "M999",
+      outputPath: "/p/.gsd/milestones/M999/M999-LEARNINGS.md",
+      relativeOutputPath: ".gsd/milestones/M999/M999-LEARNINGS.md",
+    });
+    assert.ok(!block.includes("M042"));
+    assert.ok(block.includes("M999"));
+  });
+});
+
+// ─── buildExtractLearningsPrompt composition ──────────────────────────────────
+
+describe("buildExtractLearningsPrompt composes the steps block", () => {
+  it("embeds the exact buildExtractionStepsBlock output for the same context", () => {
+    const shared = {
+      milestoneId: "M007",
+      outputPath: "/p/.gsd/milestones/M007/M007-LEARNINGS.md",
+      relativeOutputPath: ".gsd/milestones/M007/M007-LEARNINGS.md",
+    };
+    const expected = buildExtractionStepsBlock(shared);
+    const prompt = buildExtractLearningsPrompt({
+      ...shared,
+      milestoneName: "Composition",
+      roadmapContent: "# Roadmap body",
+      summaryContent: "# Summary body",
+      verificationContent: null,
+      uatContent: null,
+      missingArtifacts: [],
+      projectName: "TestProj",
+    });
+
+    assert.ok(prompt.includes(expected));
+  });
+
+  it("no longer contains the orphan-file disclaimer from the previous revision", () => {
+    const prompt = buildExtractLearningsPrompt({
+      milestoneId: "M001",
+      milestoneName: "Test",
+      outputPath: "/out/M001-LEARNINGS.md",
+      relativeOutputPath: ".gsd/milestones/M001/M001-LEARNINGS.md",
+      roadmapContent: "# Roadmap",
+      summaryContent: "# Summary",
+      verificationContent: null,
+      uatContent: null,
+      missingArtifacts: [],
+      projectName: "P",
+    });
+
+    assert.ok(!prompt.includes("no automated pipeline currently consumes it"));
+  });
+});
+
+// ─── complete-milestone.md loadPrompt round-trip ─────────────────────────────
+
+describe("complete-milestone loadPrompt round-trip (#4429)", () => {
+  it("substitutes {{extractLearningsSteps}} end-to-end via prompt-loader", async () => {
+    const { loadPrompt } = await import("../prompt-loader.js");
+    const stepsBlock = buildExtractionStepsBlock({
+      milestoneId: "M123",
+      outputPath: "/p/.gsd/milestones/M123/M123-LEARNINGS.md",
+      relativeOutputPath: ".gsd/milestones/M123/M123-LEARNINGS.md",
+    });
+
+    const rendered = loadPrompt("complete-milestone", {
+      workingDirectory: "/p",
+      milestoneId: "M123",
+      milestoneTitle: "Test Milestone",
+      roadmapPath: ".gsd/milestones/M123/M123-ROADMAP.md",
+      inlinedContext: "(inlined context stub)",
+      milestoneSummaryPath: "/p/.gsd/milestones/M123/M123-SUMMARY.md",
+      extractLearningsSteps: stepsBlock,
+    });
+
+    // Placeholder must be gone — real content must be in.
+    assert.ok(!rendered.includes("{{extractLearningsSteps}}"));
+    assert.ok(rendered.includes("Structured Learnings Extraction"));
+    assert.ok(rendered.includes("gsd_save_decision"));
+    assert.ok(rendered.includes("M123"));
+  });
+});
+
+// ─── complete-milestone.md template wiring ────────────────────────────────────
+
+describe("complete-milestone.md template wiring (#4429)", () => {
+  const promptPath = join(
+    __dirname,
+    "..",
+    "prompts",
+    "complete-milestone.md",
+  );
+
+  it("declares the {{extractLearningsSteps}} placeholder", () => {
+    const content = readFileSync(promptPath, "utf-8");
+    assert.ok(content.includes("{{extractLearningsSteps}}"));
+  });
+
+  it("no longer contains the deprecated ad-hoc KNOWLEDGE.md step", () => {
+    const content = readFileSync(promptPath, "utf-8");
+    assert.ok(
+      !content.includes("Review all slice summaries for cross-cutting lessons, patterns, or gotchas"),
+      "the pre-#4429 one-sentence step 12 must be removed",
+    );
+  });
+
+  it("keeps the milestone-completion commit instruction after the placeholder", () => {
+    const content = readFileSync(promptPath, "utf-8");
+    const placeholderIdx = content.indexOf("{{extractLearningsSteps}}");
+    const commitIdx = content.indexOf("Do not commit manually");
+    assert.ok(placeholderIdx > 0);
+    assert.ok(commitIdx > placeholderIdx, "commit instruction must come after extraction block");
+  });
+});