gsd-pi 2.23.0 → 2.25.0

package/src/resources/extensions/gsd/tests/parallel-workers-multi-milestone-e2e.test.ts

@@ -0,0 +1,354 @@
+/**
+ * E2E test: Parallel workers across multiple milestones.
+ *
+ * Validates the full lifecycle of the worker registry + metrics + budget
+ * alerting across multiple milestone contexts. Uses real filesystem fixtures
+ * and the actual metrics/worker-registry modules (no mocking).
+ *
+ * Covers:
+ *  - Worker registry tracking across parallel batches
+ *  - Metrics ledger accumulation across milestones
+ *  - Budget alert level transitions including the 80% threshold
+ *  - Dashboard data aggregation with parallel worker context
+ *  - Cost projection with budget ceiling awareness
+ */
+
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+
+import { createTestContext } from './test-helpers.ts';
+import {
+  registerWorker,
+  updateWorker,
+  getActiveWorkers,
+  getWorkerBatches,
+  hasActiveWorkers,
+  resetWorkerRegistry,
+} from '../../subagent/worker-registry.ts';
+import {
+  getBudgetAlertLevel,
+  getNewBudgetAlertLevel,
+  getBudgetEnforcementAction,
+} from '../auto.ts';
+import {
+  type UnitMetrics,
+  type MetricsLedger,
+  getProjectTotals,
+  aggregateByPhase,
+  aggregateBySlice,
+  formatCost,
+  formatCostProjection,
+  getAverageCostPerUnitType,
+  predictRemainingCost,
+} from '../metrics.ts';
+
+const { assertEq, assertTrue, assertMatch, report } = createTestContext();
+
+// ─── Fixture helpers ──────────────────────────────────────────────────────────
+
+function createFixtureBase(): string {
+  const base = mkdtempSync(join(tmpdir(), 'gsd-e2e-parallel-'));
+  mkdirSync(join(base, '.gsd', 'milestones'), { recursive: true });
+  return base;
+}
+
+function writeMetricsLedger(base: string, ledger: MetricsLedger): void {
+  writeFileSync(join(base, '.gsd', 'metrics.json'), JSON.stringify(ledger, null, 2));
+}
+
+function readMetricsLedger(base: string): MetricsLedger {
+  return JSON.parse(readFileSync(join(base, '.gsd', 'metrics.json'), 'utf-8'));
+}
+
+function makeUnit(overrides: Partial<UnitMetrics> = {}): UnitMetrics {
+  return {
+    type: "execute-task",
+    id: "M001/S01/T01",
+    model: "claude-sonnet-4-20250514",
+    startedAt: Date.now() - 5000,
+    finishedAt: Date.now(),
+    tokens: { input: 1000, output: 500, cacheRead: 200, cacheWrite: 100, total: 1800 },
+    cost: 0.05,
+    toolCalls: 3,
+    assistantMessages: 2,
+    userMessages: 1,
+    ...overrides,
+  };
+}
+
+function cleanup(base: string): void {
+  rmSync(base, { recursive: true, force: true });
+}
+
+// ─── E2E: Parallel workers across M001 and M002 ──────────────────────────────
+
+console.log("\n=== E2E: Parallel workers across milestones ===");
+
+{
+  resetWorkerRegistry();
+  const base = createFixtureBase();
+
+  // Create milestone directories
+  mkdirSync(join(base, '.gsd', 'milestones', 'M001'), { recursive: true });
+  mkdirSync(join(base, '.gsd', 'milestones', 'M002'), { recursive: true });
+
+  // Simulate M001 parallel workers (batch 1)
+  const batch1Id = "batch-m001";
+  const w1 = registerWorker("scout", "Explore M001 codebase", 0, 3, batch1Id);
+  const w2 = registerWorker("researcher", "Research M001 APIs", 1, 3, batch1Id);
+  const w3 = registerWorker("worker", "Implement M001 feature", 2, 3, batch1Id);
+
+  assertEq(getActiveWorkers().length, 3, "M001: 3 parallel workers registered");
+  assertTrue(hasActiveWorkers(), "M001: has active workers");
+
+  const batches1 = getWorkerBatches();
+  assertEq(batches1.size, 1, "M001: single batch");
+  assertEq(batches1.get(batch1Id)!.length, 3, "M001: batch has 3 workers");
+
+  // Complete M001 workers
+  updateWorker(w1, "completed");
+  updateWorker(w2, "completed");
+  updateWorker(w3, "completed");
+  assertTrue(!hasActiveWorkers(), "M001: no active workers after completion");
+
+  // Simulate M002 parallel workers (batch 2) — overlapping with M001 cleanup
+  const batch2Id = "batch-m002";
+  const w4 = registerWorker("scout", "Explore M002 codebase", 0, 2, batch2Id);
+  const w5 = registerWorker("worker", "Implement M002 feature", 1, 2, batch2Id);
+
+  assertTrue(hasActiveWorkers(), "M002: has active workers");
+  const batches2 = getWorkerBatches();
+  // M001 workers may still be in cleanup window (5s timeout), M002 workers are active
+  assertTrue(batches2.has(batch2Id), "M002: batch exists");
+  assertEq(batches2.get(batch2Id)!.length, 2, "M002: batch has 2 workers");
+
+  // One worker fails in M002
+  updateWorker(w4, "completed");
+  updateWorker(w5, "failed");
+  assertTrue(!hasActiveWorkers(), "M002: no active workers after all finish");
+
+  // Verify worker statuses reflect correctly
+  const allWorkers = getActiveWorkers();
+  const m002Workers = allWorkers.filter(w => w.batchId === batch2Id);
+  if (m002Workers.length > 0) {
+    const failedWorker = m002Workers.find(w => w.status === "failed");
+    assertTrue(failedWorker !== undefined, "M002: failed worker tracked");
+    assertEq(failedWorker?.agent, "worker", "M002: failed worker is 'worker'");
+  }
+
+  cleanup(base);
+}
+
+// ─── E2E: Metrics accumulation across milestones ──────────────────────────────
+
+console.log("\n=== E2E: Metrics across milestones ===");
+
+{
+  const base = createFixtureBase();
+
+  // Build a ledger spanning two milestones
+  const ledger: MetricsLedger = {
+    version: 1,
+    projectStartedAt: Date.now() - 60000,
+    units: [
+      // M001 units
+      makeUnit({ type: "research-milestone", id: "M001", cost: 0.10 }),
+      makeUnit({ type: "plan-milestone", id: "M001", cost: 0.08 }),
+      makeUnit({ type: "plan-slice", id: "M001/S01", cost: 0.05 }),
+      makeUnit({ type: "execute-task", id: "M001/S01/T01", cost: 0.12 }),
+      makeUnit({ type: "execute-task", id: "M001/S01/T02", cost: 0.15 }),
+      makeUnit({ type: "complete-slice", id: "M001/S01", cost: 0.03 }),
+      makeUnit({ type: "plan-slice", id: "M001/S02", cost: 0.06 }),
+      makeUnit({ type: "execute-task", id: "M001/S02/T01", cost: 0.20 }),
+      makeUnit({ type: "complete-slice", id: "M001/S02", cost: 0.04 }),
+      // M002 units
+      makeUnit({ type: "research-milestone", id: "M002", cost: 0.12 }),
+      makeUnit({ type: "plan-milestone", id: "M002", cost: 0.09 }),
+      makeUnit({ type: "plan-slice", id: "M002/S01", cost: 0.07 }),
+      makeUnit({ type: "execute-task", id: "M002/S01/T01", cost: 0.18 }),
+    ],
+  };
+
+  writeMetricsLedger(base, ledger);
+  const loaded = readMetricsLedger(base);
+
+  // Verify totals
+  const totals = getProjectTotals(loaded.units);
+  assertEq(totals.units, 13, "metrics: 13 total units across M001+M002");
+  const totalCost = loaded.units.reduce((sum, u) => sum + u.cost, 0);
+  assertTrue(Math.abs(totals.cost - totalCost) < 0.001, "metrics: total cost matches sum");
+
+  // Verify phase aggregation
+  const phases = aggregateByPhase(loaded.units);
+  const research = phases.find(p => p.phase === "research");
+  assertTrue(research !== undefined, "metrics: research phase exists");
+  assertEq(research!.units, 2, "metrics: 2 research units (M001 + M002)");
+
+  const execution = phases.find(p => p.phase === "execution");
+  assertTrue(execution !== undefined, "metrics: execution phase exists");
+  assertEq(execution!.units, 4, "metrics: 4 execution units across both milestones");
+
+  // Verify slice aggregation
+  const slices = aggregateBySlice(loaded.units);
+  assertTrue(slices.length >= 4, "metrics: at least 4 slice aggregates (M001/S01, M001/S02, M002/S01, milestone-level)");
+
+  const m001s01 = slices.find(s => s.sliceId === "M001/S01");
+  assertTrue(m001s01 !== undefined, "metrics: M001/S01 slice aggregate exists");
+  // M001/S01 has: plan-slice + T01 + T02 + complete-slice = 4 units
+  assertEq(m001s01!.units, 4, "metrics: M001/S01 has 4 units");
+
+  // Cost projection
+  const projLines = formatCostProjection(slices, 3, 2.0);
+  assertTrue(projLines.length >= 1, "metrics: cost projection generated");
+  assertMatch(projLines[0], /Projected remaining/, "metrics: projection line text");
+
+  cleanup(base);
+}
+
+// ─── E2E: Budget alert progression through all thresholds ─────────────────────
+
+console.log("\n=== E2E: Budget alert progression 0→75→80→90→100 ===");
+
+{
+  // Simulate spending progression against a $10 budget ceiling
+  const ceiling = 10.0;
+
+  // Start: 50% spent
+  let lastLevel = getBudgetAlertLevel(5.0 / ceiling);
+  assertEq(lastLevel, 0, "budget: 50% → level 0");
+  assertEq(getNewBudgetAlertLevel(0, 5.0 / ceiling), null, "budget: no alert at 50%");
+
+  // Spend to 75%
+  let newLevel = getNewBudgetAlertLevel(lastLevel, 7.5 / ceiling);
+  assertEq(newLevel, 75, "budget: alert fires at 75%");
+  lastLevel = newLevel!;
+
+  // Spend to 78% — no alert (between 75 and 80)
+  assertEq(getNewBudgetAlertLevel(lastLevel, 7.8 / ceiling), null, "budget: no alert at 78%");
+
+  // Spend to 80% — 80% approach alert
+  newLevel = getNewBudgetAlertLevel(lastLevel, 8.0 / ceiling);
+  assertEq(newLevel, 80, "budget: approach alert fires at 80%");
+  lastLevel = newLevel!;
+
+  // Spend to 85% — no alert (still at 80 level)
+  assertEq(getNewBudgetAlertLevel(lastLevel, 8.5 / ceiling), null, "budget: no alert at 85%");
+
+  // Spend to 90%
+  newLevel = getNewBudgetAlertLevel(lastLevel, 9.0 / ceiling);
+  assertEq(newLevel, 90, "budget: alert fires at 90%");
+  lastLevel = newLevel!;
+
+  // Spend to 100%
+  newLevel = getNewBudgetAlertLevel(lastLevel, 10.0 / ceiling);
+  assertEq(newLevel, 100, "budget: alert fires at 100%");
+  lastLevel = newLevel!;
+
+  // Over budget — no re-emission
+  assertEq(getNewBudgetAlertLevel(lastLevel, 12.0 / ceiling), null, "budget: no re-alert over 100%");
+
+  // Enforcement at 80% — still "none" (enforcement only at 100%)
+  assertEq(getBudgetEnforcementAction("pause", 0.80), "none", "budget: no enforcement at 80%");
+  assertEq(getBudgetEnforcementAction("halt", 0.80), "none", "budget: no enforcement at 80%");
+  assertEq(getBudgetEnforcementAction("warn", 0.80), "none", "budget: no enforcement at 80%");
+}
+
+// ─── E2E: Budget prediction with multi-milestone cost data ────────────────────
+
+console.log("\n=== E2E: Budget prediction across milestones ===");
+
+{
+  const units: UnitMetrics[] = [
+    makeUnit({ type: "execute-task", id: "M001/S01/T01", cost: 0.10 }),
+    makeUnit({ type: "execute-task", id: "M001/S01/T02", cost: 0.15 }),
+    makeUnit({ type: "plan-slice", id: "M001/S01", cost: 0.05 }),
+    makeUnit({ type: "execute-task", id: "M002/S01/T01", cost: 0.20 }),
+    makeUnit({ type: "plan-slice", id: "M002/S01", cost: 0.08 }),
+  ];
+
+  const avgCosts = getAverageCostPerUnitType(units);
+  assertTrue(avgCosts.has("execute-task"), "prediction: has execute-task average");
+  assertTrue(avgCosts.has("plan-slice"), "prediction: has plan-slice average");
+
+  // Average execute-task cost: (0.10 + 0.15 + 0.20) / 3 = 0.15
+  const execAvg = avgCosts.get("execute-task")!;
+  assertTrue(Math.abs(execAvg - 0.15) < 0.001, `prediction: execute-task avg is $0.15 (got ${execAvg})`);
+
+  // Average plan-slice cost: (0.05 + 0.08) / 2 = 0.065
+  const planAvg = avgCosts.get("plan-slice")!;
+  assertTrue(Math.abs(planAvg - 0.065) < 0.001, `prediction: plan-slice avg is $0.065 (got ${planAvg})`);
+
+  // Predict remaining cost for 3 more execute-tasks and 1 plan-slice
+  const remaining = predictRemainingCost(avgCosts, [
+    "execute-task", "execute-task", "execute-task", "plan-slice",
+  ]);
+  // Expected: 3 * 0.15 + 1 * 0.065 = 0.515
+  assertTrue(Math.abs(remaining - 0.515) < 0.001, `prediction: remaining cost ~$0.515 (got ${remaining})`);
+}
+
+// ─── E2E: Parallel workers + budget alerts combined scenario ──────────────────
+
+console.log("\n=== E2E: Combined parallel workers + budget monitoring ===");
+
+{
+  resetWorkerRegistry();
+
+  // Simulate a scenario: 3 parallel workers running while budget is at 78%
+  const batchId = "batch-combined";
+  const w1 = registerWorker("scout", "Research APIs", 0, 3, batchId);
+  const w2 = registerWorker("worker", "Implement feature", 1, 3, batchId);
+  const w3 = registerWorker("worker", "Write tests", 2, 3, batchId);
+
+  // Budget is at 78% — no alert yet (between 75 and 80)
+  const ceiling = 10.0;
+  let lastLevel: ReturnType<typeof getBudgetAlertLevel> = 75; // already got 75% alert
+  assertEq(getNewBudgetAlertLevel(lastLevel, 7.8 / ceiling), null, "combined: no alert at 78% with workers running");
+  assertTrue(hasActiveWorkers(), "combined: workers running during budget check");
+
+  // First worker completes, cost rises to 80%
+  updateWorker(w1, "completed");
+  const level80 = getNewBudgetAlertLevel(lastLevel, 8.0 / ceiling);
+  assertEq(level80, 80, "combined: 80% approach alert fires after worker completes");
+  lastLevel = level80!;
+
+  // Second worker completes, cost rises to 88%
+  updateWorker(w2, "completed");
+  assertEq(getNewBudgetAlertLevel(lastLevel, 8.8 / ceiling), null, "combined: no alert at 88%");
+
+  // Third worker completes, cost reaches 90%
+  updateWorker(w3, "completed");
+  const level90 = getNewBudgetAlertLevel(lastLevel, 9.0 / ceiling);
+  assertEq(level90, 90, "combined: 90% alert fires after all workers complete");
+
+  assertTrue(!hasActiveWorkers(), "combined: no active workers at end");
+
+  resetWorkerRegistry();
+}
+
+// ─── E2E: formatCostProjection with budget ceiling warnings ───────────────────
+
+console.log("\n=== E2E: Cost projection ceiling warnings ===");
+
+{
+  const slices = [
+    { sliceId: "M001/S01", units: 4, tokens: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 }, cost: 3.0, duration: 10000 },
+    { sliceId: "M001/S02", units: 3, tokens: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 }, cost: 4.0, duration: 8000 },
+    { sliceId: "M002/S01", units: 3, tokens: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 }, cost: 5.0, duration: 12000 },
+  ];
+
+  // With ceiling NOT yet reached
+  const proj1 = formatCostProjection(slices, 2, 20.0);
+  assertTrue(proj1.length >= 1, "projection: has projection line");
+  assertMatch(proj1[0], /Projected remaining/, "projection: shows projection");
+  assertTrue(proj1.length === 1, "projection: no ceiling warning when under budget");
+
+  // With ceiling reached (spent 12.0 >= ceiling 10.0)
+  const proj2 = formatCostProjection(slices, 2, 10.0);
+  assertTrue(proj2.length >= 2, "projection: has ceiling warning when over budget");
+  assertMatch(proj2[1], /ceiling/, "projection: ceiling warning text");
+}
+
+// ─── Summary ──────────────────────────────────────────────────────────────────
+
+report();

package/src/resources/extensions/gsd/tests/queue-reorder-e2e.test.ts

@@ -58,6 +58,7 @@ function writeCompleteMilestone(base: string, mid: string): void {
 - [x] **S01: Done** \`risk:low\` \`depends:[]\`
   > After this: Done.
 `);
+  writeFileSync(join(dir, `${mid}-VALIDATION.md`), `---\nverdict: pass\nremediation_round: 0\n---\n\n# Validation\nPassed.`);
   writeFileSync(join(dir, `${mid}-SUMMARY.md`), `# ${mid} Summary\n\nComplete.`);
 }
 

package/src/resources/extensions/gsd/tests/smart-entry-draft.test.ts

@@ -81,7 +81,7 @@ assert(
 
 // Check the branch has draft-aware menu options
 const branchIdx = guidedFlowSource.indexOf('state.phase === "needs-discussion"');
-const branchChunk = guidedFlowSource.slice(branchIdx, branchIdx + 3000);
+const branchChunk = guidedFlowSource.slice(branchIdx, branchIdx + 4000);
 
 assert(
   branchChunk.includes("discuss_draft"),

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

@@ -0,0 +1,316 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdirSync, writeFileSync, existsSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { randomUUID } from "node:crypto";
+
+import { deriveState, isValidationTerminal } from "../state.ts";
+import { resolveExpectedArtifactPath, verifyExpectedArtifact, diagnoseExpectedArtifact, buildLoopRemediationSteps } from "../auto-recovery.ts";
+import { resolveDispatch, type DispatchContext } from "../auto-dispatch.ts";
+import type { GSDState } from "../types.ts";
+import { clearPathCache } from "../paths.ts";
+import { clearParseCache } from "../files.ts";
+
+// ─── Helpers ──────────────────────────────────────────────────────────────
+
+function makeTmpBase(): string {
+  const base = join(tmpdir(), `gsd-val-test-${randomUUID()}`);
+  mkdirSync(join(base, ".gsd", "milestones"), { recursive: true });
+  return base;
+}
+
+function cleanup(base: string): void {
+  clearPathCache();
+  clearParseCache();
+  try { rmSync(base, { recursive: true, force: true }); } catch { /* */ }
+}
+
+function writeRoadmap(base: string, mid: string, content: string): void {
+  const dir = join(base, ".gsd", "milestones", mid);
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, `${mid}-ROADMAP.md`), content);
+}
+
+function writeMilestoneSummary(base: string, mid: string, content: string): void {
+  const dir = join(base, ".gsd", "milestones", mid);
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, `${mid}-SUMMARY.md`), content);
+}
+
+function writeValidation(base: string, mid: string, content: string): void {
+  const dir = join(base, ".gsd", "milestones", mid);
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, `${mid}-VALIDATION.md`), content);
+}
+
+function writeSlicePlan(base: string, mid: string, sid: string, content: string): void {
+  const dir = join(base, ".gsd", "milestones", mid, "slices", sid);
+  mkdirSync(join(dir, "tasks"), { recursive: true });
+  writeFileSync(join(dir, `${sid}-PLAN.md`), content);
+}
+
+function writeSliceSummary(base: string, mid: string, sid: string, content: string): void {
+  const dir = join(base, ".gsd", "milestones", mid, "slices", sid);
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, `${sid}-SUMMARY.md`), content);
+}
+
+const ALL_DONE_ROADMAP = `# M001: Test Milestone
+
+## Vision
+Test
+
+## Success Criteria
+- It works
+
+## Slices
+
+- [x] **S01: First slice** \`risk:low\` \`depends:[]\`
+  > After this: it works
+
+## Boundary Map
+
+| From | To | Produces | Consumes |
+|------|-----|----------|----------|
+| S01  | terminal | output | nothing |
+`;
+
+const CONTEXT_FILE = `---
+id: M001
+title: Test Milestone
+---
+
+# Context
+Test context.
+`;
+
+// ─── isValidationTerminal ─────────────────────────────────────────────────
+
+test("isValidationTerminal returns true for verdict: pass", () => {
+  const content = "---\nverdict: pass\nremediation_round: 0\n---\n\n# Validation";
+  assert.equal(isValidationTerminal(content), true);
+});
+
+test("isValidationTerminal returns true for verdict: needs-attention", () => {
+  const content = "---\nverdict: needs-attention\nremediation_round: 0\n---\n\n# Validation";
+  assert.equal(isValidationTerminal(content), true);
+});
+
+test("isValidationTerminal returns false for verdict: needs-remediation", () => {
+  const content = "---\nverdict: needs-remediation\nremediation_round: 0\n---\n\n# Validation";
+  assert.equal(isValidationTerminal(content), false);
+});
+
+test("isValidationTerminal returns false for missing frontmatter", () => {
+  const content = "# Validation\nNo frontmatter here.";
+  assert.equal(isValidationTerminal(content), false);
+});
+
+test("isValidationTerminal returns false for missing verdict field", () => {
+  const content = "---\nremediation_round: 0\n---\n\n# Validation";
+  assert.equal(isValidationTerminal(content), false);
+});
+
+// ─── deriveState: validating-milestone ────────────────────────────────────
+
+test("deriveState returns validating-milestone when all slices done and no VALIDATION file", async () => {
+  const base = makeTmpBase();
+  try {
+    writeRoadmap(base, "M001", ALL_DONE_ROADMAP);
+    // Write CONTEXT so milestone has a title
+    const dir = join(base, ".gsd", "milestones", "M001");
+    writeFileSync(join(dir, "M001-CONTEXT.md"), CONTEXT_FILE);
+
+    const state = await deriveState(base);
+    assert.equal(state.phase, "validating-milestone");
+    assert.equal(state.activeMilestone?.id, "M001");
+    assert.equal(state.activeSlice, null);
+  } finally {
+    cleanup(base);
+  }
+});
+
+test("deriveState returns completing-milestone when VALIDATION exists with terminal verdict", async () => {
+  const base = makeTmpBase();
+  try {
+    writeRoadmap(base, "M001", ALL_DONE_ROADMAP);
+    writeValidation(base, "M001", "---\nverdict: pass\nremediation_round: 0\n---\n\n# Validation\nAll good.");
+
+    const state = await deriveState(base);
+    assert.equal(state.phase, "completing-milestone");
+    assert.equal(state.activeMilestone?.id, "M001");
+  } finally {
+    cleanup(base);
+  }
+});
+
+test("deriveState returns validating-milestone when VALIDATION exists with needs-remediation verdict", async () => {
+  const base = makeTmpBase();
+  try {
+    writeRoadmap(base, "M001", ALL_DONE_ROADMAP);
+    writeValidation(base, "M001", "---\nverdict: needs-remediation\nremediation_round: 0\n---\n\n# Validation\nNeeds fixes.");
+
+    const state = await deriveState(base);
+    assert.equal(state.phase, "validating-milestone");
+    assert.equal(state.activeMilestone?.id, "M001");
+  } finally {
+    cleanup(base);
+  }
+});
+
+test("deriveState returns complete when both VALIDATION and SUMMARY exist", async () => {
+  const base = makeTmpBase();
+  try {
+    writeRoadmap(base, "M001", ALL_DONE_ROADMAP);
+    writeValidation(base, "M001", "---\nverdict: pass\nremediation_round: 0\n---\n\n# Validation\nPassed.");
+    writeMilestoneSummary(base, "M001", "# Summary\nDone.");
+
+    const state = await deriveState(base);
+    assert.equal(state.phase, "complete");
+  } finally {
+    cleanup(base);
+  }
+});
+
+// ─── Dispatch rule ────────────────────────────────────────────────────────
+
+test("dispatch rule matches validating-milestone phase", async () => {
+  const state: GSDState = {
+    activeMilestone: { id: "M001", title: "Test" },
+    activeSlice: null,
+    activeTask: null,
+    phase: "validating-milestone",
+    recentDecisions: [],
+    blockers: [],
+    nextAction: "Validate milestone M001.",
+    registry: [{ id: "M001", title: "Test", status: "active" }],
+    progress: { milestones: { done: 0, total: 1 } },
+  };
+
+  const base = makeTmpBase();
+  try {
+    // Set up minimal milestone structure for the prompt builder
+    writeRoadmap(base, "M001", ALL_DONE_ROADMAP);
+
+    const ctx: DispatchContext = {
+      basePath: base,
+      mid: "M001",
+      midTitle: "Test",
+      state,
+      prefs: undefined,
+    };
+    const result = await resolveDispatch(ctx);
+    assert.equal(result.action, "dispatch");
+    if (result.action === "dispatch") {
+      assert.equal(result.unitType, "validate-milestone");
+      assert.equal(result.unitId, "M001");
+    }
+  } finally {
+    cleanup(base);
+  }
+});
+
+test("dispatch rule skips when skip_milestone_validation preference is set", async () => {
+  const state: GSDState = {
+    activeMilestone: { id: "M001", title: "Test" },
+    activeSlice: null,
+    activeTask: null,
+    phase: "validating-milestone",
+    recentDecisions: [],
+    blockers: [],
+    nextAction: "Validate milestone M001.",
+    registry: [{ id: "M001", title: "Test", status: "active" }],
+    progress: { milestones: { done: 0, total: 1 } },
+  };
+
+  const base = makeTmpBase();
+  try {
+    writeRoadmap(base, "M001", ALL_DONE_ROADMAP);
+
+    const ctx: DispatchContext = {
+      basePath: base,
+      mid: "M001",
+      midTitle: "Test",
+      state,
+      prefs: { phases: { skip_milestone_validation: true } },
+    };
+    const result = await resolveDispatch(ctx);
+    assert.equal(result.action, "skip");
+
+    // Verify the VALIDATION file was written
+    const validationPath = join(base, ".gsd", "milestones", "M001", "M001-VALIDATION.md");
+    assert.ok(existsSync(validationPath), "VALIDATION file should be written on skip");
+  } finally {
+    cleanup(base);
+  }
+});
+
+// ─── Artifact resolution & verification ───────────────────────────────────
+
+test("resolveExpectedArtifactPath returns VALIDATION path for validate-milestone", () => {
+  const base = makeTmpBase();
+  try {
+    mkdirSync(join(base, ".gsd", "milestones", "M001"), { recursive: true });
+    const result = resolveExpectedArtifactPath("validate-milestone", "M001", base);
+    assert.ok(result);
+    assert.ok(result!.includes("VALIDATION"));
+  } finally {
+    cleanup(base);
+  }
+});
+
+test("verifyExpectedArtifact passes when VALIDATION.md exists", () => {
+  const base = makeTmpBase();
+  try {
+    writeValidation(base, "M001", "---\nverdict: pass\n---\n# Val");
+    clearPathCache();
+    clearParseCache();
+    const result = verifyExpectedArtifact("validate-milestone", "M001", base);
+    assert.equal(result, true);
+  } finally {
+    cleanup(base);
+  }
+});
+
+test("verifyExpectedArtifact fails when VALIDATION.md is missing", () => {
+  const base = makeTmpBase();
+  try {
+    mkdirSync(join(base, ".gsd", "milestones", "M001"), { recursive: true });
+    clearPathCache();
+    clearParseCache();
+    const result = verifyExpectedArtifact("validate-milestone", "M001", base);
+    assert.equal(result, false);
+  } finally {
+    cleanup(base);
+  }
+});
+
+// ─── diagnoseExpectedArtifact ─────────────────────────────────────────────
+
+test("diagnoseExpectedArtifact returns validation path for validate-milestone", () => {
+  const base = makeTmpBase();
+  try {
+    const result = diagnoseExpectedArtifact("validate-milestone", "M001", base);
+    assert.ok(result);
+    assert.ok(result!.includes("VALIDATION"));
+    assert.ok(result!.includes("milestone validation report"));
+  } finally {
+    cleanup(base);
+  }
+});
+
+// ─── buildLoopRemediationSteps ────────────────────────────────────────────
+
+test("buildLoopRemediationSteps returns steps for validate-milestone", () => {
+  const base = makeTmpBase();
+  try {
+    const result = buildLoopRemediationSteps("validate-milestone", "M001", base);
+    assert.ok(result);
+    assert.ok(result!.includes("VALIDATION"));
+    assert.ok(result!.includes("verdict: pass"));
+    assert.ok(result!.includes("gsd doctor"));
+  } finally {
+    cleanup(base);
+  }
+});