gsd-pi 2.77.0-dev.58d3d4d6c → 2.77.0-dev.cfd69e714

package/src/resources/extensions/gsd/tests/cache-staleness-regression.test.ts

@@ -69,11 +69,11 @@ describe("cache-staleness-regression", () => {
       ].join('\n');
       writeMilestoneFile(base, 'M001', 'ROADMAP', roadmap);
 
-      // Step 3: WITHOUT invalidation, the old state might be cached
-      // The state cache has a 100ms TTL, so wait just past it
-      await new Promise(r => setTimeout(r, 150));
-
-      // Step 4: Invalidate and re-derive — should see the new roadmap
+      // Step 3: Explicit invalidation — this is the #1240 fix path. We
+      // do NOT rely on the 100ms TTL here; the production code calls
+      // invalidateAllCaches() / invalidateStateCache() immediately after
+      // writing planning files, so the next deriveState() must see the
+      // new roadmap without any wall-clock wait.
       invalidateAllCaches();
       invalidateStateCache();
       const state2 = await deriveState(base);
@@ -100,10 +100,8 @@ describe("cache-staleness-regression", () => {
       // Simulate: discussion completes, CONTEXT.md is written
       writeMilestoneFile(base, 'M001', 'CONTEXT', '# M001: Test\n\nFull context after discussion.\n');
 
-      // Wait past TTL
-      await new Promise(r => setTimeout(r, 150));
-
-      // Without invalidation, we'd still see 'needs-discussion'
+      // Explicit invalidation is the production fix path for #1249 —
+      // no wall-clock wait needed.
       invalidateAllCaches();
       invalidateStateCache();
       const state2 = await deriveState(base);
@@ -116,7 +114,7 @@ describe("cache-staleness-regression", () => {
     }
   });
 
-  test("state cache TTL: fresh reads after 100ms", async () => {
+  test("state cache TTL: within window returns cached; past window re-derives", async () => {
     const base = createBase();
     try {
       writeMilestoneFile(base, 'M001', 'CONTEXT', '# M001\n\nDesc.\n');
@@ -126,7 +124,7 @@ describe("cache-staleness-regression", () => {
       const state1 = await deriveState(base);
       assert.strictEqual(state1.phase, 'pre-planning', 'initial: pre-planning');
 
-      // Write roadmap immediately
+      // Write roadmap immediately — no invalidation
       writeMilestoneFile(base, 'M001', 'ROADMAP', [
         '# M001: Test',
         '',
@@ -136,18 +134,19 @@ describe("cache-staleness-regression", () => {
         '',
       ].join('\n'));
 
-      // Immediately after writing (within 100ms TTL), the cache might be stale
+      // Within the TTL window, deriveState() must return the cached
+      // pre-planning state — this is the "cached" half of the TTL
+      // contract and the reason invalidateStateCache() exists.
       const state2 = await deriveState(base);
-      // This MAY still show pre-planning if within TTL — that's expected behavior
+      assert.strictEqual(state2.phase, 'pre-planning', 'within TTL: cached pre-planning is returned');
 
-      // Wait past TTL
+      // Past the TTL + explicit parse-cache flush, the fresh derive must
+      // see the new roadmap. invalidateAllCaches() is required because
+      // the file-parse cache is independent of the state TTL.
       await new Promise(r => setTimeout(r, 150));
-
-      // ALSO invalidate parse cache (not just state cache)
       invalidateAllCaches();
-      invalidateStateCache();
       const state3 = await deriveState(base);
-      assert.strictEqual(state3.phase, 'planning', 'after TTL expiry + invalidation → planning');
+      assert.strictEqual(state3.phase, 'planning', 'past TTL: re-derive sees new roadmap');
     } finally {
       cleanup(base);
     }
@@ -194,7 +193,6 @@ describe("cache-staleness-regression", () => {
         '- [ ] **T02: Second Task** `est:1h`',
       ].join('\n'));
 
-      await new Promise(r => setTimeout(r, 150));
       invalidateAllCaches();
       invalidateStateCache();
       const state2 = await deriveState(base);
@@ -242,7 +240,6 @@ describe("cache-staleness-regression", () => {
         '- [x] **T01: Task** `est:1h`',
       ].join('\n'));
 
-      await new Promise(r => setTimeout(r, 150));
       invalidateAllCaches();
       invalidateStateCache();
       const state2 = await deriveState(base);
@@ -282,7 +279,6 @@ describe("cache-staleness-regression", () => {
         '',
       ].join('\n'));
 
-      await new Promise(r => setTimeout(r, 150));
       invalidateAllCaches();
       invalidateStateCache();
       const state2 = await deriveState(base);

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

@@ -0,0 +1,263 @@
+// GSD-2 — #4780: slice-summary excerpts replace full inlining in
+// buildCompleteMilestonePrompt. Verify (a) the excerpt helper emits
+// frontmatter fields + section heads + on-demand path, (b) the closer
+// prompt lists all slice SUMMARY paths under "On-demand Slice Summaries",
+// (c) regression on prompt size.
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+import { buildSliceSummaryExcerpt, buildCompleteMilestonePrompt } from "../auto-prompts.ts";
+import { invalidateAllCaches } from "../cache.ts";
+
+// ─── Fixture helpers ──────────────────────────────────────────────────────
+
+function createBase(): string {
+  const base = mkdtempSync(join(tmpdir(), "gsd-cm-excerpt-"));
+  mkdirSync(join(base, ".gsd", "milestones", "M001", "slices", "S01", "tasks"), { recursive: true });
+  mkdirSync(join(base, ".gsd", "milestones", "M001", "slices", "S02", "tasks"), { recursive: true });
+  return base;
+}
+
+function cleanup(base: string): void {
+  rmSync(base, { recursive: true, force: true });
+}
+
+function writeRoadmap(base: string, content: string): void {
+  writeFileSync(join(base, ".gsd", "milestones", "M001", "M001-ROADMAP.md"), content);
+}
+
+function writeSummary(base: string, sid: string, content: string): void {
+  writeFileSync(
+    join(base, ".gsd", "milestones", "M001", "slices", sid, `${sid}-SUMMARY.md`),
+    content,
+  );
+}
+
+// A summary with enough body narrative that full inlining would balloon the
+// prompt. The excerpt should keep frontmatter + sections but drop the
+// "What Happened" narrative.
+function makeFatSummary(sid: string): string {
+  const narrativePara =
+    "The team discovered several subtle integration issues, traced them to the cache layer, and produced a patch set that threads the cache key through every call site. ".repeat(20);
+  return [
+    "---",
+    `id: ${sid}`,
+    "parent: M001",
+    "milestone: M001",
+    "provides:",
+    "  - compact slice-summary excerpts",
+    "  - on-demand read path registry",
+    "affects:",
+    "  - complete-milestone prompt builder",
+    "key_decisions:",
+    "  - use parseSummary for frontmatter extraction",
+    "  - fall back to full inline when frontmatter fails",
+    "patterns_established:",
+    "  - excerpt-first inlining for closer units",
+    "key_files:",
+    "  - src/resources/extensions/gsd/auto-prompts.ts",
+    "duration: 1h",
+    "verification_result: passed",
+    "completed_at: 2026-04-24",
+    "blocker_discovered: false",
+    "---",
+    "",
+    `# ${sid}: Slice summary`,
+    "**Short one-liner for the slice**",
+    "",
+    "## What Happened",
+    "",
+    narrativePara,
+    "",
+    "## Deviations",
+    "",
+    "Extended the excerpt helper scope at review time.",
+    "",
+    "## Known Limitations",
+    "",
+    "Does not yet cover validate-milestone — follow-up.",
+    "",
+    "## Follow-ups",
+    "",
+    "- Wire the same excerpt into buildValidateMilestonePrompt",
+  ].join("\n");
+}
+
+function makeRoadmap(): string {
+  return [
+    "# M001 Roadmap",
+    "## Slices",
+    "- [x] **S01: Excerpt helper** `risk:medium` `depends:[]`",
+    "- [x] **S02: Closer wiring** `risk:low` `depends:[S01]`",
+  ].join("\n");
+}
+
+// ─── buildSliceSummaryExcerpt unit tests ──────────────────────────────────
+
+test("#4780 excerpt: emits compact block with frontmatter fields + section heads", async (t) => {
+  const base = createBase();
+  t.after(() => cleanup(base));
+  invalidateAllCaches();
+
+  const absPath = join(base, ".gsd", "milestones", "M001", "slices", "S01", "S01-SUMMARY.md");
+  const relPath = ".gsd/milestones/M001/slices/S01/S01-SUMMARY.md";
+  writeSummary(base, "S01", makeFatSummary("S01"));
+
+  const out = await buildSliceSummaryExcerpt(absPath, relPath, "S01");
+
+  // Compact header with source path for on-demand Read
+  assert.match(out, /### S01 Summary \(excerpt\)/);
+  assert.match(out, /Source: `\.gsd\/milestones\/M001\/slices\/S01\/S01-SUMMARY\.md`/);
+
+  // Frontmatter fields surfaced
+  assert.match(out, /\*\*Title:\*\* S01: Slice summary/);
+  assert.match(out, /\*\*One-liner:\*\*/);
+  assert.match(out, /\*\*Verification:\*\* `passed`/);
+  assert.match(out, /\*\*Blockers:\*\* none/);
+  assert.match(out, /\*\*Provides:\*\* compact slice-summary excerpts;/);
+  assert.match(out, /\*\*Key decisions:\*\* use parseSummary/);
+  assert.match(out, /\*\*Patterns established:\*\* excerpt-first inlining/);
+
+  // Section heads included (body-section markdown), not whole sections inlined
+  assert.match(out, /#### Deviations/);
+  assert.match(out, /#### Known limitations/);
+  assert.match(out, /#### Follow-ups/);
+
+  // On-demand instruction present
+  assert.match(out, /On-demand.*read.*for the full "What Happened"/);
+
+  // Bulk narrative is NOT inlined — excerpt is meaningfully shorter than full
+  // A 20x-repeated paragraph produces ~2.5KB; excerpt should come in well under.
+  const fullSize = makeFatSummary("S01").length;
+  assert.ok(
+    out.length < fullSize * 0.6,
+    `excerpt length ${out.length} should be < 60% of full summary length ${fullSize}`,
+  );
+});
+
+test("#4780 excerpt: blocker_discovered=true surfaces prominent marker", async (t) => {
+  const base = createBase();
+  t.after(() => cleanup(base));
+  invalidateAllCaches();
+
+  const content = [
+    "---",
+    "id: S01",
+    "parent: M001",
+    "milestone: M001",
+    "blocker_discovered: true",
+    "---",
+    "# S01",
+    "**One-liner**",
+    "",
+    "## What Happened",
+    "content",
+  ].join("\n");
+  const absPath = join(base, ".gsd", "milestones", "M001", "slices", "S01", "S01-SUMMARY.md");
+  writeSummary(base, "S01", content);
+
+  const out = await buildSliceSummaryExcerpt(absPath, "rel", "S01");
+  assert.match(out, /Blockers:\*\* ⚠️ blocker recorded/);
+});
+
+test("#4780 excerpt: fall back to full inline when frontmatter is unrecognizable", async (t) => {
+  const base = createBase();
+  t.after(() => cleanup(base));
+  invalidateAllCaches();
+
+  // No frontmatter, no id — parser returns empty id, triggering fallback
+  const garbage = "# S99\n\nJust a wall of text with no frontmatter at all.\n";
+  const absPath = join(base, ".gsd", "milestones", "M001", "slices", "S01", "S99-SUMMARY.md");
+  writeFileSync(absPath, garbage);
+
+  const out = await buildSliceSummaryExcerpt(absPath, "rel/path.md", "S99");
+  // Full content preserved (no excerpt wrapper), no data-loss
+  assert.match(out, /Just a wall of text/);
+  assert.match(out, /### S99 Summary/);
+});
+
+test("#4780 excerpt: missing file reports not-found fallback", async (t) => {
+  const base = createBase();
+  t.after(() => cleanup(base));
+
+  const out = await buildSliceSummaryExcerpt(null, "rel/missing.md", "S42");
+  assert.match(out, /### S42 Summary \(excerpt\)/);
+  assert.match(out, /not found — file does not exist yet/);
+});
+
+test("#4780 excerpt: section bodies are capped (coderabbit review)", async (t) => {
+  const base = createBase();
+  t.after(() => cleanup(base));
+  invalidateAllCaches();
+
+  // Long Follow-ups section (~4.8KB) would balloon the excerpt without
+  // the cap — regression coverage for the coderabbit finding on #4908.
+  const longFollowUps = "A verbose follow-up bullet that keeps restating the same point. ".repeat(60);
+  const content = [
+    "---",
+    "id: S01",
+    "parent: M001",
+    "milestone: M001",
+    "---",
+    "# S01: Test",
+    "**One-liner**",
+    "",
+    "## Follow-ups",
+    longFollowUps,
+  ].join("\n");
+  const absPath = join(base, ".gsd", "milestones", "M001", "slices", "S01", "S01-SUMMARY.md");
+  writeSummary(base, "S01", content);
+
+  const out = await buildSliceSummaryExcerpt(absPath, "rel/path.md", "S01");
+
+  assert.match(out, /\(truncated — see full `rel\/path\.md`\)/);
+  assert.ok(
+    out.length < 2000,
+    `excerpt length ${out.length} should be well under 2KB when one section hits the cap`,
+  );
+});
+
+// ─── buildCompleteMilestonePrompt integration test ─────────────────────────
+
+test("#4780 closer prompt: uses excerpts + lists on-demand slice SUMMARY paths", async (t) => {
+  const base = createBase();
+  t.after(() => cleanup(base));
+  invalidateAllCaches();
+
+  writeRoadmap(base, makeRoadmap());
+  writeSummary(base, "S01", makeFatSummary("S01"));
+  writeSummary(base, "S02", makeFatSummary("S02"));
+
+  const prompt = await buildCompleteMilestonePrompt("M001", "Test Milestone", base);
+
+  // Excerpt markers present for each slice
+  assert.match(prompt, /### S01 Summary \(excerpt\)/);
+  assert.match(prompt, /### S02 Summary \(excerpt\)/);
+
+  // On-demand path section exists with both slice paths
+  assert.match(prompt, /### On-demand Slice Summaries/);
+  assert.match(prompt, /S01-SUMMARY\.md/);
+  assert.match(prompt, /S02-SUMMARY\.md/);
+
+  // Fat narrative (the 20x-repeated paragraph) is NOT inlined
+  assert.ok(
+    !prompt.includes("threads the cache key through every call site."),
+    "closer prompt must not inline full 'What Happened' narrative after #4780",
+  );
+
+  // Prompt size is bounded — the two fat summaries' narratives alone would
+  // have exceeded ~4KB each. Post-fix closer prompt should be meaningfully
+  // smaller than their combined raw size.
+  const rawSize = makeFatSummary("S01").length + makeFatSummary("S02").length;
+  // Prompt includes roadmap, templates, and other inlines, so it may still
+  // be sizable — the guard is specifically that the fat narrative is gone.
+  // Use a soft bound: prompt - overhead should be less than 2x one summary.
+  assert.ok(
+    prompt.length < rawSize + 20_000,
+    `closer prompt length ${prompt.length} should be < raw summary size ${rawSize} + 20KB headroom`,
+  );
+});

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

@@ -153,6 +153,31 @@ describe("complete-milestone", () => {
     );
   });
 
+  test("prompt does not hard-fail main self-diff as missing implementation (#4699)", () => {
+    const prompt = loadPromptFromWorktree("complete-milestone", {
+      workingDirectory: "/tmp/test-project",
+      milestoneId: "M001",
+      milestoneTitle: "Main Retry Test",
+      roadmapPath: ".gsd/milestones/M001/M001-ROADMAP.md",
+      inlinedContext: "context",
+    });
+
+    assert.ok(
+      !prompt.includes("git diff --stat HEAD $(git merge-base HEAD main) -- ':!.gsd/'"),
+      "prompt must not require the known self-diff command from #4699",
+    );
+    assert.match(
+      prompt,
+      /self-diff/i,
+      "prompt should explicitly guard retries where HEAD and the integration branch are the same commit",
+    );
+    assert.match(
+      prompt,
+      /GSD-(?:Task|Unit)/,
+      "prompt should direct main-branch retries toward milestone-scoped GSD commit evidence",
+    );
+  });
+
   test("handleCompleteMilestone rejects when verificationPassed is false", async () => {
     const { handleCompleteMilestone } = await import("../tools/complete-milestone.ts");
     const base = createFixtureBase();

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

@@ -0,0 +1,192 @@
+// GSD-2 — #4782 phase 3 batch 3: complete-slice migrated through composer.
+
+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 { buildCompleteSlicePrompt } from "../auto-prompts.ts";
+import { invalidateAllCaches } from "../cache.ts";
+import {
+  openDatabase,
+  closeDatabase,
+  insertMilestone,
+  upsertMilestonePlanning,
+  insertSlice,
+  insertTask,
+} from "../gsd-db.ts";
+
+function makeBase(): string {
+  const base = mkdtempSync(join(tmpdir(), "gsd-completeslice-composer-"));
+  mkdirSync(join(base, ".gsd", "milestones", "M001", "slices", "S01", "tasks"), { recursive: true });
+  return base;
+}
+
+function cleanup(base: string): void {
+  try { closeDatabase(); } catch { /* noop */ }
+  invalidateAllCaches();
+  rmSync(base, { recursive: true, force: true });
+}
+
+function seed(base: string, mid: string): void {
+  openDatabase(join(base, ".gsd", "gsd.db"));
+  insertMilestone({ id: mid, title: "Composer Test", status: "active", depends_on: [] });
+  upsertMilestonePlanning(mid, {
+    title: "Composer Test",
+    status: "active",
+    vision: "Validate complete-slice migration",
+    successCriteria: ["Prompt compiles"],
+    keyRisks: [],
+    proofStrategy: [],
+    verificationContract: "",
+    verificationIntegration: "",
+    verificationOperational: "",
+    verificationUat: "",
+    definitionOfDone: [],
+    requirementCoverage: "",
+    boundaryMapMarkdown: "",
+  });
+  insertSlice({
+    id: "S01",
+    milestoneId: mid,
+    title: "First",
+    status: "complete",
+    risk: "low",
+    depends: [],
+    demo: "",
+    sequence: 1,
+  });
+  insertTask({
+    id: "T01",
+    sliceId: "S01",
+    milestoneId: mid,
+    title: "Task one",
+    status: "complete",
+  });
+}
+
+function writeArtifacts(base: string): void {
+  writeFileSync(
+    join(base, ".gsd", "milestones", "M001", "M001-ROADMAP.md"),
+    "# M001 Roadmap\n## Slices\n- [x] **S01: First** `risk:low` `depends:[]`\n",
+  );
+  writeFileSync(
+    join(base, ".gsd", "milestones", "M001", "slices", "S01", "S01-PLAN.md"),
+    "# S01 Plan\n\nSlice plan body.\n",
+  );
+  writeFileSync(
+    join(base, ".gsd", "milestones", "M001", "slices", "S01", "tasks", "T01-SUMMARY.md"),
+    "---\nid: T01\n---\n# T01 Summary\n\nTask one did the thing.\n",
+  );
+}
+
+test("#4782 phase 3: buildCompleteSlicePrompt composes roadmap → plan → task summaries → templates in declared order", async (t) => {
+  const base = makeBase();
+  t.after(() => cleanup(base));
+  invalidateAllCaches();
+
+  seed(base, "M001");
+  writeArtifacts(base);
+
+  const prompt = await buildCompleteSlicePrompt("M001", "Composer Test", "S01", "First", base);
+
+  // Context wrapper present
+  assert.match(prompt, /## Inlined Context \(preloaded — do not re-read these files\)/);
+
+  // Manifest-declared artifacts present
+  assert.match(prompt, /### Milestone Roadmap/);
+  assert.match(prompt, /### Slice Plan/);
+  assert.match(prompt, /### Task Summary: T01/);
+  assert.match(prompt, /### Output Template: Slice Summary/);
+
+  // Ordering: roadmap → slice plan → task summaries → slice summary template
+  const roadmapIdx = prompt.indexOf("### Milestone Roadmap");
+  const planIdx = prompt.indexOf("### Slice Plan");
+  const taskSummaryIdx = prompt.indexOf("### Task Summary: T01");
+  const sliceSummaryTemplateIdx = prompt.indexOf("### Output Template: Slice Summary");
+
+  assert.ok(roadmapIdx > -1 && planIdx > roadmapIdx, "roadmap precedes slice plan");
+  assert.ok(planIdx > -1 && taskSummaryIdx > planIdx, "slice plan precedes task summaries");
+  assert.ok(
+    taskSummaryIdx > -1 && sliceSummaryTemplateIdx > taskSummaryIdx,
+    "task summaries precede slice-summary template",
+  );
+
+  // Task body inlined
+  assert.match(prompt, /Task one did the thing/);
+});
+
+test("#4782 phase 3: buildCompleteSlicePrompt handles missing task summaries gracefully", async (t) => {
+  const base = makeBase();
+  t.after(() => cleanup(base));
+  invalidateAllCaches();
+
+  seed(base, "M001");
+  // Write roadmap + plan but no task summaries
+  writeFileSync(
+    join(base, ".gsd", "milestones", "M001", "M001-ROADMAP.md"),
+    "# M001 Roadmap\n## Slices\n- [x] **S01: First** `risk:low` `depends:[]`\n",
+  );
+  writeFileSync(
+    join(base, ".gsd", "milestones", "M001", "slices", "S01", "S01-PLAN.md"),
+    "# S01 Plan\n",
+  );
+
+  const prompt = await buildCompleteSlicePrompt("M001", "Composer Test", "S01", "First", base);
+
+  // Still succeeds — prior-task-summaries resolver returns null when dir is empty
+  assert.match(prompt, /### Milestone Roadmap/);
+  assert.match(prompt, /### Slice Plan/);
+  // No task summary blocks — they'd have a "### Task Summary:" prefix
+  assert.ok(!prompt.includes("### Task Summary:"));
+  // Roadmap still precedes slice plan despite the missing block
+  const roadmapIdx = prompt.indexOf("### Milestone Roadmap");
+  const planIdx = prompt.indexOf("### Slice Plan");
+  assert.ok(roadmapIdx > -1 && planIdx > roadmapIdx);
+});
+
+test("#4925 review: KNOWLEDGE splices BEFORE templates when no task summaries exist", async (t) => {
+  // Regression for the bug fixed in fcf3bfbe: the templates fallback was
+  // searching for "### Slice Summary" but inlineTemplate emits
+  // "### Output Template: Slice Summary", so templatesIdx stayed -1 and
+  // knowledge ended up appended after templates instead of before them.
+  const base = makeBase();
+  t.after(() => cleanup(base));
+  invalidateAllCaches();
+
+  seed(base, "M001");
+  // Roadmap + plan only — no T*-SUMMARY.md, so taskIdx must be -1 and the
+  // splice falls through to the templates anchor.
+  writeFileSync(
+    join(base, ".gsd", "milestones", "M001", "M001-ROADMAP.md"),
+    "# M001 Roadmap\n## Slices\n- [x] **S01: First** `risk:low` `depends:[]`\n",
+  );
+  writeFileSync(
+    join(base, ".gsd", "milestones", "M001", "slices", "S01", "S01-PLAN.md"),
+    "# S01 Plan\n",
+  );
+  // KNOWLEDGE.md with an H3 section whose header matches the slice title
+  // keyword "first" — queryKnowledge will return the section, so
+  // inlineKnowledgeBudgeted produces a non-null block and the splice
+  // path executes.
+  mkdirSync(join(base, ".gsd"), { recursive: true });
+  writeFileSync(
+    join(base, ".gsd", "KNOWLEDGE.md"),
+    "## Topics\n\n### First-slice notes\n\nNotes that should be inlined.\n",
+  );
+
+  const prompt = await buildCompleteSlicePrompt("M001", "Composer Test", "S01", "First", base);
+
+  // Sanity: the splice path actually fired.
+  assert.ok(!prompt.includes("### Task Summary:"), "fixture must have no task summaries to exercise the fallback");
+  const knowledgeIdx = prompt.indexOf("### Project Knowledge (scoped)");
+  const templatesIdx = prompt.indexOf("### Output Template: Slice Summary");
+  assert.ok(knowledgeIdx > -1, "knowledge block missing — fixture failed to populate KNOWLEDGE.md scope");
+  assert.ok(templatesIdx > -1, "templates block missing");
+  // The bug: knowledge appeared AFTER templates. The fix: knowledge before templates.
+  assert.ok(
+    knowledgeIdx < templatesIdx,
+    `knowledge (${knowledgeIdx}) must splice before templates (${templatesIdx}) when no task summaries exist`,
+  );
+});

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

@@ -14,6 +14,7 @@ import {
   getTask,
   getSliceTasks,
   insertVerificationEvidence,
+  SCHEMA_VERSION,
 } from '../gsd-db.ts';
 import { handleCompleteTask } from '../tools/complete-task.ts';
 
@@ -99,19 +100,22 @@ function makeValidParams() {
 }
 
 // ═══════════════════════════════════════════════════════════════════════════
-// complete-task: Schema v5 migration
+// complete-task: Fresh DB is migrated to the current schema version
 // ═══════════════════════════════════════════════════════════════════════════
 
-console.log('\n=== complete-task: schema v5 migration ===');
+console.log('\n=== complete-task: fresh DB migrates to current schema version ===');
 {
   const dbPath = tempDbPath();
   openDatabase(dbPath);
 
   const adapter = _getAdapter()!;
 
-  // Verify schema version is current (v22 — quality_gates DDL fix)
+  // Verify schema version matches the current source-of-truth constant.
+  // Asserting against SCHEMA_VERSION (not a hardcoded number) keeps this
+  // green across migration bumps while still catching a
+  // "fresh-DB-was-not-migrated" regression.
   const versionRow = adapter.prepare('SELECT MAX(version) as v FROM schema_version').get();
-  assertEq(versionRow?.['v'], 22, 'schema version should be 22');
+  assertEq(versionRow?.['v'], SCHEMA_VERSION, 'fresh DB should be migrated to current SCHEMA_VERSION');
 
   // Verify all 4 new tables exist
   const tables = adapter.prepare(
@@ -399,9 +403,12 @@ console.log('\n=== complete-task: handler idempotency ===');
   const r1 = await handleCompleteTask(params, basePath);
   assertTrue(!('error' in r1), 'first call should succeed');
 
-  // Verify only 1 task row
+  // Verify complete-task did not duplicate T01. State reconciliation may import
+  // the remaining plan task from disk so the DB stays aligned with S01-PLAN.md.
   const tasks = getSliceTasks('M001', 'S01');
-  assertEq(tasks.length, 1, 'should have exactly 1 task row after first call');
+  assertEq(tasks.length, 2, 'should have T01 plus reconciled T02 after first call');
+  assertEq(tasks.filter(t => t.id === 'T01').length, 1, 'should have exactly one T01 row after first call');
+  assertEq(tasks.find(t => t.id === 'T02')?.status, 'pending', 'T02 should be reconciled as pending');
 
   // Second call with same params — state machine guard rejects (task is already complete)
   const r2 = await handleCompleteTask(params, basePath);
@@ -410,9 +417,10 @@ console.log('\n=== complete-task: handler idempotency ===');
     assertMatch(r2.error, /already complete/, 'error should mention already complete');
   }
 
-  // Still only 1 task row (no duplication from rejected second call)
+  // Still no duplicate rows from the rejected second call.
   const tasksAfter = getSliceTasks('M001', 'S01');
-  assertEq(tasksAfter.length, 1, 'should still have exactly 1 task row after rejected second call');
+  assertEq(tasksAfter.length, 2, 'should still have T01 plus reconciled T02 after rejected second call');
+  assertEq(tasksAfter.filter(t => t.id === 'T01').length, 1, 'should still have exactly one T01 row');
 
   cleanupDir(basePath);
   cleanup(dbPath);