gsd-pi 2.23.0 → 2.25.0

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

@@ -10,12 +10,15 @@ import {
   verifyExpectedArtifact,
   diagnoseExpectedArtifact,
   buildLoopRemediationSteps,
+  selfHealRuntimeRecords,
   completedKeysPath,
   persistCompletedKey,
   removePersistedKey,
   loadPersistedKeys,
 } from "../auto-recovery.ts";
 import { parseRoadmap, clearParseCache } from "../files.ts";
+import { invalidateAllCaches } from "../cache.ts";
+import { deriveState, invalidateStateCache } from "../state.ts";
 
 function makeTmpBase(): string {
   const base = join(tmpdir(), `gsd-test-${randomUUID()}`);
@@ -273,6 +276,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 +408,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 +418,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 +434,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 +444,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 +455,186 @@ 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);
+  }
+});
+
+// ─── #793: invalidateAllCaches unblocks skip-loop ─────────────────────────
+// When the skip-loop breaker fires, it must call invalidateAllCaches() (not
+// just invalidateStateCache()) to clear path/parse caches that deriveState
+// depends on. Without this, even after cache invalidation, deriveState reads
+// stale directory listings and returns the same unit, looping forever.
+test("#793: invalidateAllCaches clears all caches so deriveState sees fresh disk state", async () => {
+  const base = makeTmpBase();
+  try {
+    const mid = "M001";
+    const sid = "S01";
+    const planDir = join(base, ".gsd", "milestones", mid, "slices", sid);
+    const tasksDir = join(planDir, "tasks");
+    mkdirSync(tasksDir, { recursive: true });
+    mkdirSync(join(base, ".gsd", "milestones", mid), { recursive: true });
+
+    writeFileSync(
+      join(base, ".gsd", "milestones", mid, `${mid}-ROADMAP.md`),
+      `# M001: Test Milestone\n\n**Vision:** test.\n\n## Slices\n\n- [ ] **${sid}: Slice One** \`risk:low\` \`depends:[]\`\n  > After this: done.\n`,
+    );
+    const planUnchecked = `# ${sid}: Slice One\n\n**Goal:** test.\n\n## Tasks\n\n- [ ] **T01: Task One** \`est:10m\`\n- [ ] **T02: Task Two** \`est:10m\`\n`;
+    writeFileSync(join(planDir, `${sid}-PLAN.md`), planUnchecked);
+    writeFileSync(join(tasksDir, "T01-PLAN.md"), "# T01: Task One\n\n**Goal:** t\n\n## Steps\n- step\n\n## Verification\n- v\n");
+    writeFileSync(join(tasksDir, "T02-PLAN.md"), "# T02: Task Two\n\n**Goal:** t\n\n## Steps\n- step\n\n## Verification\n- v\n");
+
+    // Warm all caches
+    const state1 = await deriveState(base);
+    assert.equal(state1.activeTask?.id, "T01", "initial: T01 is active");
+
+    // Simulate task completion on disk (what the LLM does)
+    const planChecked = `# ${sid}: Slice One\n\n**Goal:** test.\n\n## Tasks\n\n- [x] **T01: Task One** \`est:10m\`\n- [ ] **T02: Task Two** \`est:10m\`\n`;
+    writeFileSync(join(planDir, `${sid}-PLAN.md`), planChecked);
+    writeFileSync(join(tasksDir, "T01-SUMMARY.md"), "---\nid: T01\n---\n# Summary\n");
+
+    // invalidateStateCache alone: _stateCache cleared but path/parse caches warm
+    invalidateStateCache();
+
+    // invalidateAllCaches: all caches cleared — deriveState must re-read disk
+    invalidateAllCaches();
+    const state2 = await deriveState(base);
+
+    // After full invalidation, T01 should be complete and T02 should be next
+    assert.notEqual(state2.activeTask?.id, "T01", "#793: T01 not re-dispatched after full invalidation");
+
+    // Verify the caches are truly cleared by calling clearParseCache and clearPathCache
+    // do not throw (they should be no-ops after invalidateAllCaches already cleared them)
+    clearParseCache(); // no-op, but should not throw
+    assert.ok(true, "clearParseCache after invalidateAllCaches is safe");
+  } finally {
+    cleanup(base);
+  }
+});

package/src/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/src/resources/extensions/gsd/tests/auto-worktree.test.ts

@@ -153,6 +153,64 @@ async function main(): Promise<void> {
     // After teardown, originalBase should be null
     assertEq(getAutoWorktreeOriginalBase(), null, "no split-brain: originalBase cleared");
 
+    // ─── #778: reconcile plan checkboxes on re-attach ─────────────────
+    console.log("\n=== #778: reconcile plan checkboxes on re-attach ===");
+    {
+      // Simulate: T01 [x] was committed to milestone branch, T02 [x] was
+      // written to project root by syncStateToProjectRoot() but the
+      // auto-commit crashed before it fired. On restart the worktree is
+      // re-created from the milestone branch HEAD (T02 still [ ]).
+      // reconcilePlanCheckboxes should forward-apply T02 [x] from the root.
+
+      const planRelPath = join(".gsd", "milestones", "M004", "slices", "S01", "S01-PLAN.md");
+      const planDir = join(tempDir, ".gsd", "milestones", "M004", "slices", "S01");
+      const { mkdirSync: mkdir, writeFileSync: write, readFileSync: read } = await import("node:fs");
+
+      // Plan on integration branch (project root): T01 [x], T02 [x]
+      mkdir(planDir, { recursive: true });
+      write(
+        join(tempDir, planRelPath),
+        "# S01 Plan\n- [x] **T01:** task one\n- [x] **T02:** task two\n- [ ] **T03:** task three\n",
+      );
+
+      // Write integration-branch plan to git so milestone branch starts from it
+      run(`git add .`, tempDir);
+      run(`git commit -m "add plan with T01 and T02 checked" --allow-empty`, tempDir);
+
+      // Create milestone branch with only T01 [x] (simulating crash before T02 commit)
+      const milestoneBranch = "milestone/M004";
+      run(`git checkout -b ${milestoneBranch}`, tempDir);
+      mkdir(planDir, { recursive: true });
+      write(
+        join(tempDir, planRelPath),
+        "# S01 Plan\n- [x] **T01:** task one\n- [ ] **T02:** task two\n- [ ] **T03:** task three\n",
+      );
+      run(`git add .`, tempDir);
+      run(`git commit -m "milestone: only T01 checked"`, tempDir);
+      run(`git checkout main`, tempDir);
+
+      // Restore project root plan (T01+T02 [x]) — simulates syncStateToProjectRoot
+      write(
+        join(tempDir, planRelPath),
+        "# S01 Plan\n- [x] **T01:** task one\n- [x] **T02:** task two\n- [ ] **T03:** task three\n",
+      );
+
+      // Create worktree re-attached to existing milestone branch (T02 still [ ] in branch)
+      const wtPath = createAutoWorktree(tempDir, "M004");
+
+      try {
+        const wtPlanPath = join(wtPath, planRelPath);
+        assertTrue(existsSync(wtPlanPath), "plan file exists in worktree after re-attach");
+
+        const wtPlan = read(wtPlanPath, "utf-8");
+        assertTrue(wtPlan.includes("- [x] **T02:"), "T02 should be [x] after reconciliation (was [ ] on branch)");
+        assertTrue(wtPlan.includes("- [x] **T01:"), "T01 stays [x]");
+        assertTrue(wtPlan.includes("- [ ] **T03:"), "T03 stays [ ] (not in root either)");
+      } finally {
+        teardownAutoWorktree(tempDir, "M004");
+      }
+    }
+
   } finally {
     // Always restore cwd and clean up
     process.chdir(savedCwd);

package/src/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/src/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/src/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/src/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/src/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