gsd-pi 2.23.0 → 2.24.0

package/dist/resources/extensions/gsd/tests/auto-preflight.test.ts

@@ -17,6 +17,7 @@ writeFileSync(join(gsd, "milestones", "M001", "slices", "S01", "S01-PLAN.md"), `
 writeFileSync(join(gsd, "milestones", "M001", "slices", "S01", "tasks", "T01-SUMMARY.md"), `---\nid: T01\nparent: S01\nmilestone: M001\nprovides: []\nrequires: []\naffects: []\nkey_files: []\nkey_decisions: []\npatterns_established: []\nobservability_surfaces: []\ndrill_down_paths: []\nduration: 5m\nverification_result: passed\ncompleted_at: 2026-03-09T00:00:00Z\n---\n\n# T01: Old Task\n\n**Done**\n\n## What Happened\nDone.\n\n## Diagnostics\n- log\n`);
 writeFileSync(join(gsd, "milestones", "M001", "slices", "S01", "S01-SUMMARY.md"), `---\nid: S01\nparent: M001\nmilestone: M001\nprovides: []\nrequires: []\naffects: []\nkey_files: []\nkey_decisions: []\npatterns_established: []\nobservability_surfaces: []\ndrill_down_paths: []\nduration: 5m\nverification_result: passed\ncompleted_at: 2026-03-09T00:00:00Z\n---\n\n# S01: Old Slice\n\n**Done**\n\n## What Happened\nDone.\n\n## Verification\nDone.\n\n## Deviations\nNone\n\n## Known Limitations\nNone\n\n## Follow-ups\nNone\n\n## Files Created/Modified\n- \`x\` — x\n\n## Forward Intelligence\n\n### What the next slice should know\n- x\n\n### What's fragile\n- x\n\n### Authoritative diagnostics\n- x\n\n### What assumptions changed\n- x\n`);
 
+writeFileSync(join(gsd, "milestones", "M001", "M001-VALIDATION.md"), `---\nverdict: pass\nremediation_round: 0\n---\n\n# Validation\nPassed.\n`);
 writeFileSync(join(gsd, "milestones", "M001", "M001-SUMMARY.md"), `---\nid: M001\nstatus: complete\ncompleted_at: 2026-03-09T00:00:00Z\n---\n\n# M001: Historical\n\nComplete.\n`);
 
 writeFileSync(join(gsd, "milestones", "M009", "M009-ROADMAP.md"), `# M009: Active\n\n## Slices\n- [ ] **S01: Active Slice** \`risk:low\` \`depends:[]\`\n  > After this: active works\n`);

package/dist/resources/extensions/gsd/tests/auto-recovery.test.ts

@@ -10,6 +10,7 @@ import {
   verifyExpectedArtifact,
   diagnoseExpectedArtifact,
   buildLoopRemediationSteps,
+  selfHealRuntimeRecords,
   completedKeysPath,
   persistCompletedKey,
   removePersistedKey,
@@ -273,6 +274,68 @@ test("removePersistedKey is safe when file doesn't exist", () => {
   }
 });
 
+// ─── Dual-load across worktree boundary (#769) ───────────────────────────
+
+test("loadPersistedKeys unions keys from project root and worktree", () => {
+  // Simulate two separate .gsd directories (project root + worktree)
+  // each with a different set of completed keys. Loading from both
+  // into the same Set should produce the union.
+  const projectRoot = makeTmpBase();
+  const worktree = makeTmpBase();
+  try {
+    // Persist different keys in each location
+    persistCompletedKey(projectRoot, "execute-task/M001/S01/T01");
+    persistCompletedKey(projectRoot, "plan-slice/M001/S02");
+
+    persistCompletedKey(worktree, "execute-task/M001/S01/T02");
+    persistCompletedKey(worktree, "plan-slice/M001/S02"); // overlap
+
+    // Load from both into the same set (mimicking startup dual-load)
+    const keys = new Set<string>();
+    loadPersistedKeys(projectRoot, keys);
+    loadPersistedKeys(worktree, keys);
+
+    assert.ok(keys.has("execute-task/M001/S01/T01"), "key from project root");
+    assert.ok(keys.has("plan-slice/M001/S02"), "shared key");
+    assert.ok(keys.has("execute-task/M001/S01/T02"), "key from worktree");
+    assert.equal(keys.size, 3, "union should deduplicate overlapping keys");
+  } finally {
+    cleanup(projectRoot);
+    cleanup(worktree);
+  }
+});
+
+test("completed-units.json set-union merge produces correct result", () => {
+  // Verify that a manual set-union merge (as done in syncStateToProjectRoot)
+  // correctly merges two JSON arrays of keys.
+  const projectRoot = makeTmpBase();
+  const worktree = makeTmpBase();
+  try {
+    // Write keys to both locations
+    const prKeysFile = join(projectRoot, ".gsd", "completed-units.json");
+    const wtKeysFile = join(worktree, ".gsd", "completed-units.json");
+
+    writeFileSync(prKeysFile, JSON.stringify(["a", "b"]));
+    writeFileSync(wtKeysFile, JSON.stringify(["b", "c", "d"]));
+
+    // Perform the same merge logic used in syncStateToProjectRoot
+    const srcKeys: string[] = JSON.parse(readFileSync(wtKeysFile, "utf8"));
+    let dstKeys: string[] = [];
+    if (existsSync(prKeysFile)) {
+      dstKeys = JSON.parse(readFileSync(prKeysFile, "utf8"));
+    }
+    const merged = [...new Set([...dstKeys, ...srcKeys])];
+    writeFileSync(prKeysFile, JSON.stringify(merged, null, 2));
+
+    // Verify the merged result
+    const result: string[] = JSON.parse(readFileSync(prKeysFile, "utf8"));
+    assert.deepStrictEqual(result.sort(), ["a", "b", "c", "d"]);
+  } finally {
+    cleanup(projectRoot);
+    cleanup(worktree);
+  }
+});
+
 // ─── verifyExpectedArtifact: parse cache collision regression ─────────────
 
 test("verifyExpectedArtifact detects roadmap [x] change despite parse cache", () => {
@@ -343,7 +406,8 @@ test("verifyExpectedArtifact accepts plan-slice with actual tasks", () => {
   const base = makeTmpBase();
   try {
     const sliceDir = join(base, ".gsd", "milestones", "M001", "slices", "S01");
-    mkdirSync(sliceDir, { recursive: true });
+    const tasksDir = join(sliceDir, "tasks");
+    mkdirSync(tasksDir, { recursive: true });
     writeFileSync(join(sliceDir, "S01-PLAN.md"), [
       "# S01: Test Slice",
       "",
@@ -352,6 +416,8 @@ test("verifyExpectedArtifact accepts plan-slice with actual tasks", () => {
       "- [ ] **T01: Implement feature** `est:2h`",
       "- [ ] **T02: Write tests** `est:1h`",
     ].join("\n"));
+    writeFileSync(join(tasksDir, "T01-PLAN.md"), "# T01 Plan");
+    writeFileSync(join(tasksDir, "T02-PLAN.md"), "# T02 Plan");
     assert.strictEqual(
       verifyExpectedArtifact("plan-slice", "M001/S01", base),
       true,
@@ -366,7 +432,8 @@ test("verifyExpectedArtifact accepts plan-slice with completed tasks", () => {
   const base = makeTmpBase();
   try {
     const sliceDir = join(base, ".gsd", "milestones", "M001", "slices", "S01");
-    mkdirSync(sliceDir, { recursive: true });
+    const tasksDir = join(sliceDir, "tasks");
+    mkdirSync(tasksDir, { recursive: true });
     writeFileSync(join(sliceDir, "S01-PLAN.md"), [
       "# S01: Test Slice",
       "",
@@ -375,6 +442,8 @@ test("verifyExpectedArtifact accepts plan-slice with completed tasks", () => {
       "- [x] **T01: Implement feature** `est:2h`",
       "- [ ] **T02: Write tests** `est:1h`",
     ].join("\n"));
+    writeFileSync(join(tasksDir, "T01-PLAN.md"), "# T01 Plan");
+    writeFileSync(join(tasksDir, "T02-PLAN.md"), "# T02 Plan");
     assert.strictEqual(
       verifyExpectedArtifact("plan-slice", "M001/S01", base),
       true,
@@ -384,3 +453,134 @@ test("verifyExpectedArtifact accepts plan-slice with completed tasks", () => {
     cleanup(base);
   }
 });
+
+// ─── verifyExpectedArtifact: plan-slice task plan check (#739) ────────────
+
+test("verifyExpectedArtifact plan-slice passes when all task plan files exist", () => {
+  const base = makeTmpBase();
+  try {
+    const tasksDir = join(base, ".gsd", "milestones", "M001", "slices", "S01", "tasks");
+    const planPath = join(base, ".gsd", "milestones", "M001", "slices", "S01", "S01-PLAN.md");
+    const planContent = [
+      "# S01: Test Slice",
+      "",
+      "## Tasks",
+      "",
+      "- [ ] **T01: First task** `est:1h`",
+      "- [ ] **T02: Second task** `est:2h`",
+    ].join("\n");
+    writeFileSync(planPath, planContent);
+    writeFileSync(join(tasksDir, "T01-PLAN.md"), "# T01 Plan\n\nDo the thing.");
+    writeFileSync(join(tasksDir, "T02-PLAN.md"), "# T02 Plan\n\nDo the other thing.");
+
+    const result = verifyExpectedArtifact("plan-slice", "M001/S01", base);
+    assert.equal(result, true, "should pass when all task plan files exist");
+  } finally {
+    cleanup(base);
+  }
+});
+
+test("verifyExpectedArtifact plan-slice fails when a task plan file is missing (#739)", () => {
+  const base = makeTmpBase();
+  try {
+    const tasksDir = join(base, ".gsd", "milestones", "M001", "slices", "S01", "tasks");
+    const planPath = join(base, ".gsd", "milestones", "M001", "slices", "S01", "S01-PLAN.md");
+    const planContent = [
+      "# S01: Test Slice",
+      "",
+      "## Tasks",
+      "",
+      "- [ ] **T01: First task** `est:1h`",
+      "- [ ] **T02: Second task** `est:2h`",
+    ].join("\n");
+    writeFileSync(planPath, planContent);
+    // Only write T01-PLAN.md — T02 is missing
+    writeFileSync(join(tasksDir, "T01-PLAN.md"), "# T01 Plan\n\nDo the thing.");
+
+    const result = verifyExpectedArtifact("plan-slice", "M001/S01", base);
+    assert.equal(result, false, "should fail when T02-PLAN.md is missing");
+  } finally {
+    cleanup(base);
+  }
+});
+
+test("verifyExpectedArtifact plan-slice fails for plan with no tasks (#699)", () => {
+  const base = makeTmpBase();
+  try {
+    const planPath = join(base, ".gsd", "milestones", "M001", "slices", "S01", "S01-PLAN.md");
+    const planContent = [
+      "# S01: Test Slice",
+      "",
+      "## Goal",
+      "",
+      "Just some documentation updates, no tasks.",
+    ].join("\n");
+    writeFileSync(planPath, planContent);
+
+    const result = verifyExpectedArtifact("plan-slice", "M001/S01", base);
+    assert.equal(result, false, "should fail when plan has no task entries (empty scaffold, #699)");
+  } finally {
+    cleanup(base);
+  }
+});
+
+// ─── selfHealRuntimeRecords — worktree base path (#769) ──────────────────
+
+test("selfHealRuntimeRecords clears stale record when artifact exists at worktree base (#769)", async () => {
+  // Simulate worktree layout: the runtime record AND the artifact both live
+  // under the worktree's .gsd/, not the main project root.
+  const worktreeBase = makeTmpBase();
+  const mainBase = makeTmpBase();
+  try {
+    const { writeUnitRuntimeRecord, readUnitRuntimeRecord } = await import("../unit-runtime.ts");
+
+    // Write a stale runtime record in the worktree .gsd/runtime/units/
+    writeUnitRuntimeRecord(worktreeBase, "run-uat", "M001/S01", Date.now() - 7200_000, {
+      phase: "dispatched",
+    });
+
+    // Write the UAT result artifact in the worktree .gsd/milestones/
+    const uatPath = join(worktreeBase, ".gsd", "milestones", "M001", "slices", "S01", "S01-UAT-RESULT.md");
+    writeFileSync(uatPath, "---\nresult: pass\n---\n# UAT Result\nAll tests passed.\n");
+
+    // Verify the runtime record exists before heal
+    const before = readUnitRuntimeRecord(worktreeBase, "run-uat", "M001/S01");
+    assert.ok(before, "runtime record should exist before heal");
+
+    // Mock ExtensionContext with minimal notify
+    const notifications: string[] = [];
+    const mockCtx = {
+      ui: { notify: (msg: string) => { notifications.push(msg); } },
+    } as any;
+
+    // Call selfHeal with worktreeBase — this is the fix: using the worktree path
+    // so both the runtime record and artifact are found
+    const completedKeys = new Set<string>();
+    await selfHealRuntimeRecords(worktreeBase, mockCtx, completedKeys);
+
+    // The stale record should be cleared
+    const after = readUnitRuntimeRecord(worktreeBase, "run-uat", "M001/S01");
+    assert.equal(after, null, "runtime record should be cleared after heal");
+
+    // The completion key should be persisted
+    assert.ok(completedKeys.has("run-uat/M001/S01"), "completion key should be added");
+    assert.ok(notifications.some(n => n.includes("Self-heal")), "should emit self-heal notification");
+
+    // Now verify that calling with mainBase does NOT find/clear anything (the old bug)
+    // Write a stale record at mainBase but NO artifact there
+    writeUnitRuntimeRecord(mainBase, "run-uat", "M001/S01", Date.now() - 7200_000, {
+      phase: "dispatched",
+    });
+    const mainKeys = new Set<string>();
+    await selfHealRuntimeRecords(mainBase, mockCtx, mainKeys);
+
+    // The record at mainBase should be cleared by the stale timeout (>1h),
+    // but the completion key should NOT be set (artifact doesn't exist at mainBase)
+    const afterMain = readUnitRuntimeRecord(mainBase, "run-uat", "M001/S01");
+    assert.equal(afterMain, null, "stale record at main base should be cleared by timeout");
+    assert.ok(!mainKeys.has("run-uat/M001/S01"), "completion key should NOT be set when artifact is missing");
+  } finally {
+    cleanup(worktreeBase);
+    cleanup(mainBase);
+  }
+});

package/dist/resources/extensions/gsd/tests/auto-worktree-milestone-merge.test.ts

@@ -290,6 +290,40 @@ async function main(): Promise<void> {
       assertTrue(existsSync(join(repo, "feature.ts")), "feature.ts merged to main");
     }
 
+    // ─── Test 6: Skip checkout when main already current (#757) ───────
+    console.log("\n=== skip checkout when main already current (#757) ===");
+    {
+      const repo = freshRepo();
+      const wtPath = createAutoWorktree(repo, "M060");
+
+      addSliceToMilestone(repo, wtPath, "M060", "S01", "Skip checkout test", [
+        { file: "skip-checkout.ts", content: "export const skip = true;\n", message: "add skip-checkout" },
+      ]);
+
+      const roadmap = makeRoadmap("M060", "Skip checkout verification", [
+        { id: "S01", title: "Skip checkout test" },
+      ]);
+
+      // Verify main is already checked out at repo root (worktree default)
+      const branchAtRoot = run("git rev-parse --abbrev-ref HEAD", repo);
+      assertEq(branchAtRoot, "main", "main is already checked out at project root");
+
+      // mergeMilestoneToMain should succeed without attempting to checkout main
+      // (which would fail with "already used by worktree" error)
+      let threw = false;
+      try {
+        const result = mergeMilestoneToMain(repo, "M060", roadmap);
+        assertTrue(result.commitMessage.includes("feat(M060)"), "merge commit created");
+      } catch (err) {
+        threw = true;
+        console.error("Unexpected error:", err);
+      }
+      assertTrue(!threw, "does not fail when main is already checked out at project root");
+
+      // Verify the merge actually happened
+      assertTrue(existsSync(join(repo, "skip-checkout.ts")), "skip-checkout.ts merged to main");
+    }
+
   } finally {
     process.chdir(savedCwd);
     for (const d of tempDirs) {

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

@@ -45,6 +45,12 @@ function writeMilestoneSummary(base: string, mid: string, content: string): void
   writeFileSync(join(dir, `${mid}-SUMMARY.md`), content);
 }
 
+function writeMilestoneValidation(base: string, mid: string, verdict: string = "pass"): void {
+  const dir = join(base, ".gsd", "milestones", mid);
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, `${mid}-VALIDATION.md`), `---\nverdict: ${verdict}\nremediation_round: 0\n---\n\n# Validation\nValidated.`);
+}
+
 function cleanup(base: string): void {
   rmSync(base, { recursive: true, force: true });
 }
@@ -176,7 +182,8 @@ async function main(): Promise<void> {
       const roadmap = parseRoadmap(roadmapContent!);
       assertTrue(isMilestoneComplete(roadmap), "isMilestoneComplete returns true when all slices are [x]");
 
-      // Verify deriveState returns completing-milestone phase
+      // Verify deriveState returns completing-milestone phase (with validation already done)
+      writeMilestoneValidation(base, "M001");
       const state = await deriveState(base);
       assertEq(state.phase, "completing-milestone", "deriveState returns completing-milestone when all slices done, no summary");
       assertEq(state.activeMilestone?.id, "M001", "active milestone is M001");

package/dist/resources/extensions/gsd/tests/derive-state-db.test.ts

@@ -248,31 +248,24 @@ async function main(): Promise<void> {
     }
   }
 
-  // ─── Test 5: Requirements counting from DB content ────────────────────
-  console.log('\n=== derive-state-db: requirements from DB content ===');
+  // ─── Test 5: Requirements counting from disk (DB no longer used for content) ─
+  console.log('\n=== derive-state-db: requirements from disk content ===');
   {
     const base = createFixtureBase();
     try {
       // Write minimal milestone dir (needed for milestone discovery)
       mkdirSync(join(base, '.gsd', 'milestones', 'M001'), { recursive: true });
-      // Do NOT write REQUIREMENTS.md to disk — only in DB
-
-      openDatabase(':memory:');
-      insertArtifactRow('REQUIREMENTS.md', REQUIREMENTS_CONTENT, {
-        artifact_type: 'requirements',
-      });
+      // Write REQUIREMENTS.md to disk (DB content is no longer used by deriveState)
+      writeFile(base, 'REQUIREMENTS.md', REQUIREMENTS_CONTENT);
 
       invalidateStateCache();
       const state = await deriveState(base);
 
-      // Requirements should come from DB
-      assertEq(state.requirements?.active, 2, 'req-from-db: requirements.active = 2');
-      assertEq(state.requirements?.validated, 1, 'req-from-db: requirements.validated = 1');
-      assertEq(state.requirements?.total, 3, 'req-from-db: requirements.total = 3');
-
-      closeDatabase();
+      // Requirements should come from disk
+      assertEq(state.requirements?.active, 2, 'req-from-disk: requirements.active = 2');
+      assertEq(state.requirements?.validated, 1, 'req-from-disk: requirements.validated = 1');
+      assertEq(state.requirements?.total, 3, 'req-from-disk: requirements.total = 3');
     } finally {
-      closeDatabase();
       cleanup(base);
     }
   }
@@ -310,6 +303,7 @@ async function main(): Promise<void> {
       mkdirSync(join(base, '.gsd', 'milestones', 'M001'), { recursive: true });
       mkdirSync(join(base, '.gsd', 'milestones', 'M002'), { recursive: true });
       writeFile(base, 'milestones/M001/M001-ROADMAP.md', completedRoadmap);
+      writeFile(base, 'milestones/M001/M001-VALIDATION.md', `---\nverdict: pass\nremediation_round: 0\n---\n\n# Validation\nPassed.`);
       writeFile(base, 'milestones/M001/M001-SUMMARY.md', summaryContent);
       writeFile(base, 'milestones/M002/M002-ROADMAP.md', activeRoadmap);
 

package/dist/resources/extensions/gsd/tests/derive-state-deps.test.ts

@@ -26,6 +26,12 @@ function writeMilestoneSummary(base: string, mid: string, content: string): void
   writeFileSync(join(dir, `${mid}-SUMMARY.md`), content);
 }
 
+function writeMilestoneValidation(base: string, mid: string): void {
+  const dir = join(base, '.gsd', 'milestones', mid);
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, `${mid}-VALIDATION.md`), `---\nverdict: pass\nremediation_round: 0\n---\n\n# Validation\nPassed.`);
+}
+
 /**
  * Creates M00x-CONTEXT.md with a valid YAML frontmatter block.
  * frontmatter is the raw YAML lines between the --- delimiters.
@@ -120,6 +126,7 @@ async function main(): Promise<void> {
 - [x] **S01: Done** \`risk:low\` \`depends:[]\`
   > After this: Done.
 `);
+      writeMilestoneValidation(base, 'M001');
       writeMilestoneSummary(base, 'M001', '# M001 Summary\n\nFirst milestone is complete.');
 
       // M002: depends on M001, now unblocked
@@ -252,6 +259,7 @@ async function main(): Promise<void> {
 - [x] **S01: Done** \`risk:low\` \`depends:[]\`
   > After this: Done.
 `);
+      writeMilestoneValidation(base, 'M002');
       writeMilestoneSummary(base, 'M002', '# M002 Summary\n\nSecond milestone is complete.');
 
       const state = await deriveState(base);
@@ -321,6 +329,7 @@ async function main(): Promise<void> {
 - [x] **S01: Done** \`risk:low\` \`depends:[]\`
   > After this: Done.
 `);
+      writeMilestoneValidation(base, 'M004-0zjrg0');
       writeMilestoneSummary(base, 'M004-0zjrg0', '# M004-0zjrg0 Summary\n\nComplete.');
 
       // M005-b0m2hl: depends on M004-0zjrg0 (lowercase hex suffix)

package/dist/resources/extensions/gsd/tests/derive-state-draft.test.ts

@@ -54,6 +54,12 @@ function writeMilestoneSummary(base: string, mid: string, content: string): void
   writeFileSync(join(dir, `${mid}-SUMMARY.md`), content);
 }
 
+function writeMilestoneValidation(base: string, mid: string): void {
+  const dir = join(base, '.gsd', 'milestones', mid);
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, `${mid}-VALIDATION.md`), `---\nverdict: pass\nremediation_round: 0\n---\n\n# Validation\nPassed.`);
+}
+
 function cleanup(base: string): void {
   rmSync(base, { recursive: true, force: true });
 }
@@ -143,6 +149,7 @@ async function main(): Promise<void> {
 - [x] **S01: Done** \`risk:low\` \`depends:[]\`
   > After this: Done.
 `);
+      writeMilestoneValidation(base, 'M001');
       writeMilestoneSummary(base, 'M001', '# M001 Summary\n\nFirst milestone complete.');
 
       // M002: only CONTEXT-DRAFT.md
@@ -178,6 +185,7 @@ async function main(): Promise<void> {
 - [x] **S01: Done** \`risk:low\` \`depends:[]\`
   > After this: Done.
 `);
+      writeMilestoneValidation(base, 'M001');
       writeMilestoneSummary(base, 'M001', '# M001 Summary\n\nComplete.');
 
       // M002: draft only — should become active with needs-discussion

package/dist/resources/extensions/gsd/tests/derive-state.test.ts

@@ -38,6 +38,12 @@ function writeMilestoneSummary(base: string, mid: string, content: string): void
   writeFileSync(join(dir, `${mid}-SUMMARY.md`), content);
 }
 
+function writeMilestoneValidation(base: string, mid: string, verdict: string = 'pass'): void {
+  const dir = join(base, '.gsd', 'milestones', mid);
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, `${mid}-VALIDATION.md`), `---\nverdict: ${verdict}\nremediation_round: 0\n---\n\n# Validation\nValidated.`);
+}
+
 function writeRequirements(base: string, content: string): void {
   writeFileSync(join(base, '.gsd', 'REQUIREMENTS.md'), content);
 }
@@ -285,6 +291,7 @@ Continue from step 2.
   > After this: Done.
 `);
 
+      writeMilestoneValidation(base, 'M001');
       writeMilestoneSummary(base, 'M001', `# M001 Summary\n\nMilestone complete.`);
 
       const state = await deriveState(base);
@@ -381,6 +388,7 @@ Continue from step 2.
   > After this: Done.
 `);
 
+      writeMilestoneValidation(base, 'M001');
       writeMilestoneSummary(base, 'M001', `# M001 Summary\n\nFirst milestone complete.`);
 
       // M002: active (has incomplete slices)
@@ -486,6 +494,8 @@ Continue from step 2.
   > After this: S02 complete.
 `);
 
+      writeMilestoneValidation(base, 'M001');
+
       const state = await deriveState(base);
 
       assertEq(state.phase, 'completing-milestone', 'completing-ms: phase is completing-milestone');
@@ -521,6 +531,7 @@ Continue from step 2.
   > After this: Done.
 `);
 
+      writeMilestoneValidation(base, 'M001');
       writeMilestoneSummary(base, 'M001', `# M001 Summary\n\nMilestone is complete.`);
 
       const state = await deriveState(base);
@@ -550,6 +561,7 @@ Continue from step 2.
 - [x] **S01: Done** \`risk:low\` \`depends:[]\`
   > After this: Done.
 `);
+      writeMilestoneValidation(base, 'M001');
       writeMilestoneSummary(base, 'M001', `# M001 Summary\n\nFirst milestone complete.`);
 
       // M002: all slices done, no summary → completing-milestone
@@ -566,6 +578,8 @@ Continue from step 2.
   > After this: Done.
 `);
 
+      writeMilestoneValidation(base, 'M002');
+
       // M003: has incomplete slices → pending (M002 is active)
       writeRoadmap(base, 'M003', `# M003: Third Milestone
 

package/dist/resources/extensions/gsd/tests/integration-mixed-milestones.test.ts

@@ -51,6 +51,12 @@ function writeMilestoneSummary(base: string, mid: string, content: string): void
   writeFileSync(join(dir, `${mid}-SUMMARY.md`), content);
 }
 
+function writeMilestoneValidation(base: string, mid: string): void {
+  const dir = join(base, '.gsd', 'milestones', mid);
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, `${mid}-VALIDATION.md`), `---\nverdict: pass\nremediation_round: 0\n---\n\n# Validation\nPassed.`);
+}
+
 function cleanup(base: string): void {
   rmSync(base, { recursive: true, force: true });
 }
@@ -166,6 +172,7 @@ async function main(): Promise<void> {
   Did it.
 `);
 
+      writeMilestoneValidation(base, 'M001');
       writeMilestoneSummary(base, 'M001', `# M001: Legacy Feature Summary
 
 **One-liner summary**
@@ -265,6 +272,7 @@ Everything worked.
   Did it.
 `);
 
+      writeMilestoneValidation(base, 'M001');
       writeMilestoneSummary(base, 'M001', `# M001: Legacy Feature Summary
 
 **One-liner summary**

package/dist/resources/extensions/gsd/tests/migrate-writer-integration.test.ts

@@ -263,12 +263,12 @@ async function main(): Promise<void> {
       // No REQUIREMENTS.md since empty requirements
       assertTrue(!existsSync(join(base, '.gsd', 'REQUIREMENTS.md')), 'complete: REQUIREMENTS.md NOT written (empty)');
 
-      // deriveState: all slices done, all tasks done — needs milestone summary for 'complete'
-      // Without milestone summary, it should be 'completing-milestone' or 'summarizing'
+      // deriveState: all slices done, all tasks done — needs validation then milestone summary
+      // Without VALIDATION file, it should be 'validating-milestone'
       const state = await deriveState(base);
-      // All slices are done in roadmap. Milestone summary doesn't exist.
-      // deriveState should return 'completing-milestone' since all slices done but no milestone summary.
-      assertEq(state.phase, 'completing-milestone', 'complete: deriveState phase is completing-milestone');
+      // All slices are done in roadmap. No VALIDATION or SUMMARY exists.
+      // deriveState should return 'validating-milestone' since validation gate precedes completion.
+      assertEq(state.phase, 'validating-milestone', 'complete: deriveState phase is validating-milestone');
       assertTrue(state.activeMilestone !== null, 'complete: deriveState has activeMilestone');
       assertEq(state.activeMilestone!.id, 'M001', 'complete: deriveState activeMilestone is M001');