gsd-pi 2.44.0-dev.d25d507 → 2.45.0-dev.6b9da3e

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

@@ -0,0 +1,176 @@
+/**
+ * Regression test for #2322: recoveryAttempts persists across re-dispatches,
+ * causing instant task skip.
+ *
+ * When a unit hits recovery limits and is later re-dispatched, the
+ * recoveryAttempts counter from the prior execution carries over because
+ * the dispatch-time writeUnitRuntimeRecord call does not reset it.
+ * This causes the next execution to be instantly skipped with no steering
+ * message or second chance.
+ *
+ * The fix: include `recoveryAttempts: 0` in the dispatch-time runtime
+ * record write in runUnitPhase.
+ */
+
+import { mkdtempSync, mkdirSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import {
+  writeUnitRuntimeRecord,
+  readUnitRuntimeRecord,
+} from "../unit-runtime.ts";
+import { createTestContext } from "./test-helpers.ts";
+
+const { assertEq, assertTrue, report } = createTestContext();
+
+// ═══ Setup ════════════════════════════════════════════════════════════════════
+
+const base = mkdtempSync(join(tmpdir(), "gsd-recovery-reset-test-"));
+mkdirSync(join(base, ".gsd", "runtime", "units"), { recursive: true });
+
+try {
+  // ═══ #2322: recoveryAttempts should reset on re-dispatch ═══════════════════
+
+  {
+    console.log("\n=== #2322: recoveryAttempts should reset on re-dispatch ===");
+
+    const unitType = "execute-task";
+    const unitId = "M001/S01/T01";
+    const startedAt1 = Date.now() - 10000;
+
+    // Simulate first dispatch — clean state
+    writeUnitRuntimeRecord(base, unitType, unitId, startedAt1, {
+      phase: "dispatched",
+      wrapupWarningSent: false,
+      timeoutAt: null,
+      lastProgressAt: startedAt1,
+      progressCount: 0,
+      lastProgressKind: "dispatch",
+    });
+
+    // Simulate timeout recovery incrementing recoveryAttempts
+    writeUnitRuntimeRecord(base, unitType, unitId, startedAt1, {
+      phase: "recovered",
+      recoveryAttempts: 1,
+      lastRecoveryReason: "hard",
+    });
+
+    const afterRecovery = readUnitRuntimeRecord(base, unitType, unitId);
+    assertEq(afterRecovery?.recoveryAttempts, 1, "recoveryAttempts should be 1 after recovery");
+    assertEq(afterRecovery?.lastRecoveryReason, "hard", "lastRecoveryReason should be 'hard'");
+
+    // Simulate re-dispatch (second execution of same unit).
+    // This is what runUnitPhase should do at dispatch time — explicitly reset
+    // recoveryAttempts so the new execution gets its full recovery budget.
+    const startedAt2 = Date.now();
+    writeUnitRuntimeRecord(base, unitType, unitId, startedAt2, {
+      phase: "dispatched",
+      wrapupWarningSent: false,
+      timeoutAt: null,
+      lastProgressAt: startedAt2,
+      progressCount: 0,
+      lastProgressKind: "dispatch",
+      recoveryAttempts: 0, // FIX: must be explicitly reset
+    });
+
+    const afterRedispatch = readUnitRuntimeRecord(base, unitType, unitId);
+    assertEq(
+      afterRedispatch?.recoveryAttempts,
+      0,
+      "recoveryAttempts should be 0 after re-dispatch (was carried over from prior execution)",
+    );
+  }
+
+  // ═══ Verify the BUG scenario: omitting recoveryAttempts carries it over ═══
+
+  {
+    console.log("\n=== #2322: demonstrates bug — omitting recoveryAttempts carries it over ===");
+
+    const unitType = "execute-task";
+    const unitId = "M001/S01/T02";
+    const startedAt1 = Date.now() - 10000;
+
+    // First dispatch
+    writeUnitRuntimeRecord(base, unitType, unitId, startedAt1, {
+      phase: "dispatched",
+    });
+
+    // Timeout bumps recoveryAttempts to 1
+    writeUnitRuntimeRecord(base, unitType, unitId, startedAt1, {
+      recoveryAttempts: 1,
+      lastRecoveryReason: "hard",
+    });
+
+    // Re-dispatch WITHOUT resetting recoveryAttempts (the bug)
+    const startedAt2 = Date.now();
+    writeUnitRuntimeRecord(base, unitType, unitId, startedAt2, {
+      phase: "dispatched",
+      wrapupWarningSent: false,
+      timeoutAt: null,
+      lastProgressAt: startedAt2,
+      progressCount: 0,
+      lastProgressKind: "dispatch",
+      // recoveryAttempts: NOT included — this is the bug
+    });
+
+    const afterBuggyRedispatch = readUnitRuntimeRecord(base, unitType, unitId);
+    // This DEMONSTRATES the bug: recoveryAttempts is still 1
+    assertEq(
+      afterBuggyRedispatch?.recoveryAttempts,
+      1,
+      "BUG DEMO: recoveryAttempts carries over when not explicitly reset",
+    );
+  }
+
+  // ═══ Hard timeout maxRecoveryAttempts=1 — second dispatch must get full budget ═══
+
+  {
+    console.log("\n=== #2322: second dispatch gets full hard-timeout budget after reset ===");
+
+    const unitType = "execute-task";
+    const unitId = "M001/S01/T03";
+
+    // First dispatch
+    const start1 = Date.now() - 20000;
+    writeUnitRuntimeRecord(base, unitType, unitId, start1, {
+      phase: "dispatched",
+      recoveryAttempts: 0,
+    });
+
+    // Hard timeout recovery — exhausts the budget (maxRecoveryAttempts=1 for hard)
+    writeUnitRuntimeRecord(base, unitType, unitId, start1, {
+      phase: "recovered",
+      recoveryAttempts: 1,
+      lastRecoveryReason: "hard",
+    });
+
+    const afterExhausted = readUnitRuntimeRecord(base, unitType, unitId);
+    assertEq(afterExhausted?.recoveryAttempts, 1, "budget exhausted after hard recovery");
+
+    // Second dispatch with fix: reset recoveryAttempts
+    const start2 = Date.now();
+    writeUnitRuntimeRecord(base, unitType, unitId, start2, {
+      phase: "dispatched",
+      wrapupWarningSent: false,
+      timeoutAt: null,
+      lastProgressAt: start2,
+      progressCount: 0,
+      lastProgressKind: "dispatch",
+      recoveryAttempts: 0,
+    });
+
+    const afterReset = readUnitRuntimeRecord(base, unitType, unitId);
+    assertEq(afterReset?.recoveryAttempts, 0, "second dispatch has full recovery budget");
+
+    // Now a hard timeout should be recoverable (0 < 1)
+    assertTrue(
+      (afterReset?.recoveryAttempts ?? 0) < 1,
+      "hard recovery should be allowed (recoveryAttempts < maxRecoveryAttempts)",
+    );
+  }
+
+} finally {
+  rmSync(base, { recursive: true, force: true });
+}
+
+report();

package/src/resources/extensions/gsd/tests/stop-auto-merge-back.test.ts

@@ -0,0 +1,67 @@
+/**
+ * stop-auto-merge-back.test.ts — Regression test for #2317.
+ *
+ * When auto-mode stops after a milestone is complete, stopAuto should trigger
+ * merge-back (mergeAndExit) instead of just exiting the worktree with
+ * preserveBranch: true. Otherwise milestone code stays stranded on the
+ * worktree branch and never reaches main.
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+// ─── Source analysis: stopAuto calls mergeAndExit for complete milestones ────
+
+const autoSrcPath = join(import.meta.dirname, "..", "auto.ts");
+const autoSrc = readFileSync(autoSrcPath, "utf-8");
+
+test("#2317: stopAuto should check milestone completion status before choosing exit strategy", () => {
+  // stopAuto Step 4 should NOT unconditionally call exitMilestone(preserveBranch: true).
+  // It should check if the milestone is complete and call mergeAndExit instead.
+
+  // Find the Step 4 section
+  const step4Idx = autoSrc.indexOf("Step 4: Auto-worktree exit");
+  assert.ok(step4Idx !== -1, "Step 4 comment exists in stopAuto");
+
+  // Extract a reasonable window around Step 4 (up to Step 5)
+  const step5Idx = autoSrc.indexOf("Step 5:", step4Idx);
+  const step4Block = autoSrc.slice(step4Idx, step5Idx);
+
+  // The fix: Step 4 should call mergeAndExit when milestone is complete
+  assert.ok(
+    step4Block.includes("mergeAndExit"),
+    "Step 4 should call mergeAndExit for completed milestones",
+  );
+});
+
+test("#2317: stopAuto should detect milestone completion via SUMMARY file or DB", () => {
+  const step4Idx = autoSrc.indexOf("Step 4: Auto-worktree exit");
+  const step5Idx = autoSrc.indexOf("Step 5:", step4Idx);
+  const step4Block = autoSrc.slice(step4Idx, step5Idx);
+
+  // Should check completion status — either via SUMMARY file, DB getMilestone, or phase
+  const checksCompletion =
+    step4Block.includes("SUMMARY") ||
+    step4Block.includes("getMilestone") ||
+    step4Block.includes("complete") ||
+    step4Block.includes("isMilestoneComplete");
+
+  assert.ok(
+    checksCompletion,
+    "Step 4 should check if milestone is complete before deciding exit strategy",
+  );
+});
+
+test("#2317: stopAuto still preserves branch for incomplete milestones", () => {
+  const step4Idx = autoSrc.indexOf("Step 4: Auto-worktree exit");
+  const step5Idx = autoSrc.indexOf("Step 5:", step4Idx);
+  const step4Block = autoSrc.slice(step4Idx, step5Idx);
+
+  // preserveBranch should still be used as fallback for non-complete milestones
+  assert.ok(
+    step4Block.includes("preserveBranch"),
+    "Step 4 should still preserve branch for incomplete milestones (fallback path)",
+  );
+});

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

@@ -0,0 +1,108 @@
+/**
+ * Regression test for #2358: Survivor branch recovery skipped in phase=complete.
+ *
+ * When bootstrapAutoSession finds a survivor milestone branch and the derived
+ * state phase is "complete", recovery/finalization is skipped entirely because
+ * the survivor branch detection only triggers when phase === "pre-planning".
+ * The milestone finalization (merge, cleanup) never runs, leaving the worktree
+ * and branch alive.
+ *
+ * The fix broadens the survivor branch detection to also check phase === "complete",
+ * and adds a finalization path that runs mergeAndExit before falling through to
+ * the normal "complete" handling.
+ */
+
+import { createTestContext } from "./test-helpers.ts";
+
+const { assertTrue, assertEq, report } = createTestContext();
+
+// ═══ Test: survivor branch detection conditions ══════════════════════════════
+
+// The survivor branch detection block in auto-start.ts checks:
+//   state.activeMilestone &&
+//   state.phase === "pre-planning" &&  // <-- BUG: too restrictive
+//   shouldUseWorktreeIsolation() &&
+//   !detectWorktreeName(base) &&
+//   !base.includes(...)
+//
+// The fix should also include state.phase === "complete".
+
+{
+  console.log("\n=== #2358: survivor branch should be detected in phase=complete ===");
+
+  // Simulate the condition check before the fix (only pre-planning)
+  const phasesBeforeFix = ["pre-planning"];
+  const phasesAfterFix = ["pre-planning", "complete"];
+
+  const testPhase = "complete";
+
+  const detectedBefore = phasesBeforeFix.includes(testPhase);
+  assertEq(detectedBefore, false, "before fix: phase=complete should NOT trigger survivor detection");
+
+  const detectedAfter = phasesAfterFix.includes(testPhase);
+  assertEq(detectedAfter, true, "after fix: phase=complete SHOULD trigger survivor detection");
+}
+
+// ═══ Test: pre-planning survivor detection still works ═══════════════════════
+
+{
+  console.log("\n=== #2358: pre-planning survivor detection is not broken ===");
+
+  const phasesAfterFix = ["pre-planning", "complete"];
+  const testPhase = "pre-planning";
+
+  const detected = phasesAfterFix.includes(testPhase);
+  assertEq(detected, true, "pre-planning should still trigger survivor detection after fix");
+}
+
+// ═══ Test: other phases do NOT trigger survivor detection ════════════════════
+
+{
+  console.log("\n=== #2358: other phases should NOT trigger survivor detection ===");
+
+  const phasesAfterFix = ["pre-planning", "complete"];
+
+  for (const phase of ["planning", "executing", "blocked", "needs-discussion"]) {
+    const detected = phasesAfterFix.includes(phase);
+    assertEq(detected, false, `phase=${phase} should NOT trigger survivor detection`);
+  }
+}
+
+// ═══ Test: phase=complete + hasSurvivorBranch should trigger finalization ═════
+
+{
+  console.log("\n=== #2358: phase=complete + survivor branch triggers finalization path ===");
+
+  // Simulate the decision logic after the fix:
+  // if (hasSurvivorBranch && state.phase === "complete") -> finalize
+  // if (hasSurvivorBranch && state.phase === "needs-discussion") -> discuss
+  // if (!hasSurvivorBranch && state.phase === "complete") -> showSmartEntry
+
+  const scenarios = [
+    { hasSurvivorBranch: true, phase: "complete", expected: "finalize" },
+    { hasSurvivorBranch: true, phase: "needs-discussion", expected: "discuss" },
+    { hasSurvivorBranch: true, phase: "pre-planning", expected: "continue" },
+    { hasSurvivorBranch: false, phase: "complete", expected: "showSmartEntry" },
+  ];
+
+  for (const { hasSurvivorBranch, phase, expected } of scenarios) {
+    let result: string;
+    if (hasSurvivorBranch && phase === "complete") {
+      result = "finalize";
+    } else if (hasSurvivorBranch && phase === "needs-discussion") {
+      result = "discuss";
+    } else if (!hasSurvivorBranch && (!phase || phase === "complete")) {
+      result = "showSmartEntry";
+    } else {
+      result = "continue";
+    }
+
+    assertEq(
+      result,
+      expected,
+      `hasSurvivorBranch=${hasSurvivorBranch}, phase=${phase} -> expected ${expected}, got ${result}`,
+    );
+  }
+}
+
+report();

package/src/resources/extensions/gsd/tests/terminated-transient.test.ts

@@ -0,0 +1,49 @@
+/**
+ * terminated-transient.test.ts — Regression test for #2309.
+ *
+ * classifyProviderError should treat 'terminated' errors (process killed,
+ * connection reset) as transient with auto-resume, not permanent.
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { classifyProviderError } from "../provider-error-pause.ts";
+
+test("#2309: 'terminated' errors should be classified as transient", () => {
+  const result = classifyProviderError("terminated");
+  assert.equal(result.isTransient, true, "'terminated' should be transient");
+  assert.equal(result.isRateLimit, false, "'terminated' is not a rate limit");
+  assert.ok(result.suggestedDelayMs > 0, "'terminated' should have a retry delay");
+});
+
+test("#2309: 'connection reset' errors should be classified as transient", () => {
+  const result = classifyProviderError("connection reset by peer");
+  assert.equal(result.isTransient, true, "'connection reset' should be transient");
+});
+
+test("#2309: 'other side closed' errors should be classified as transient", () => {
+  const result = classifyProviderError("other side closed the connection");
+  assert.equal(result.isTransient, true, "'other side closed' should be transient");
+});
+
+test("#2309: 'fetch failed' errors should be classified as transient", () => {
+  const result = classifyProviderError("fetch failed: network error");
+  assert.equal(result.isTransient, true, "'fetch failed' should be transient");
+});
+
+test("#2309: 'connection refused' errors should be classified as transient", () => {
+  const result = classifyProviderError("ECONNREFUSED: connection refused");
+  assert.equal(result.isTransient, true, "'connection refused' should be transient");
+});
+
+test("#2309: permanent errors are still permanent", () => {
+  const authResult = classifyProviderError("unauthorized: invalid API key");
+  assert.equal(authResult.isTransient, false, "auth errors should stay permanent");
+  assert.equal(authResult.suggestedDelayMs, 0, "permanent errors have no delay");
+});
+
+test("#2309: rate limits are still transient", () => {
+  const rlResult = classifyProviderError("rate limit exceeded (429)");
+  assert.equal(rlResult.isTransient, true, "rate limits are still transient");
+  assert.equal(rlResult.isRateLimit, true, "rate limits are flagged as rate limits");
+});

package/src/resources/extensions/gsd/tests/tool-naming.test.ts

@@ -34,6 +34,7 @@ const RENAME_MAP: Array<{ canonical: string; alias: string }> = [
   { canonical: "gsd_replan_slice", alias: "gsd_slice_replan" },
   { canonical: "gsd_reassess_roadmap", alias: "gsd_roadmap_reassess" },
   { canonical: "gsd_complete_milestone", alias: "gsd_milestone_complete" },
+  { canonical: "gsd_validate_milestone", alias: "gsd_milestone_validate" },
 ];
 
 // ─── Registration count ──────────────────────────────────────────────────────
@@ -43,7 +44,7 @@ console.log('\n── Tool naming: registration count ──');
 const pi = makeMockPi();
 registerDbTools(pi);
 
-assert.deepStrictEqual(pi.tools.length, 24, 'Should register exactly 24 tools (12 canonical + 12 aliases)');
+assert.deepStrictEqual(pi.tools.length, 26, 'Should register exactly 26 tools (13 canonical + 13 aliases)');
 
 // ─── Both names exist for each pair ──────────────────────────────────────────
 

package/src/resources/extensions/gsd/tests/worktree-submodule-safety.test.ts

@@ -0,0 +1,65 @@
+/**
+ * worktree-submodule-safety.test.ts — #2337
+ *
+ * Worktree teardown (removeWorktree) uses --force which destroys
+ * uncommitted changes in submodule directories. This test verifies
+ * that the removal logic detects submodules and preserves their state.
+ */
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { createTestContext } from "./test-helpers.ts";
+
+const { assertTrue, report } = createTestContext();
+
+const srcPath = join(import.meta.dirname, "..", "worktree-manager.ts");
+const src = readFileSync(srcPath, "utf-8");
+
+console.log("\n=== #2337: Worktree teardown preserves submodule state ===");
+
+// ── Test 1: removeWorktree function exists ──────────────────────────────
+
+const removeWorktreeIdx = src.indexOf("export function removeWorktree");
+assertTrue(removeWorktreeIdx > 0, "worktree-manager.ts exports removeWorktree");
+
+const fnBody = src.slice(removeWorktreeIdx, removeWorktreeIdx + 3000);
+
+// ── Test 2: The function checks for submodules before force removal ─────
+
+const checksSubmodules =
+  fnBody.includes("submodule") ||
+  fnBody.includes(".gitmodules");
+
+assertTrue(
+  checksSubmodules,
+  "removeWorktree checks for submodules before force removal (#2337)",
+);
+
+// ── Test 3: Submodule changes are stashed or warned about ───────────────
+
+const preservesSubmoduleState =
+  fnBody.includes("stash") ||
+  fnBody.includes("uncommitted") ||
+  fnBody.includes("dirty") ||
+  fnBody.includes("submodule") && (fnBody.includes("warn") || fnBody.includes("preserv"));
+
+assertTrue(
+  preservesSubmoduleState,
+  "removeWorktree preserves or warns about submodule uncommitted changes (#2337)",
+);
+
+// ── Test 4: Force removal is skipped when submodules have changes ───────
+
+// The key fix: when submodules have dirty state, we should NOT use force
+// removal. Instead, use non-force first and fall back to force only after
+// submodule state is preserved.
+const hasConditionalForce =
+  fnBody.includes("submodule") &&
+  (fnBody.includes("force") || fnBody.includes("--force"));
+
+assertTrue(
+  hasConditionalForce,
+  "removeWorktree has conditional force logic around submodules (#2337)",
+);
+
+report();

package/src/resources/extensions/gsd/tools/plan-slice.ts

@@ -20,6 +20,7 @@ export interface PlanSliceTaskInput {
   inputs: string[];
   expectedOutput: string[];
   observabilityImpact?: string;
+  fullPlanMd?: string;
 }
 
 export interface PlanSliceParams {
@@ -167,6 +168,7 @@ export async function handlePlanSlice(
           inputs: task.inputs,
           expectedOutput: task.expectedOutput,
           observabilityImpact: task.observabilityImpact ?? "",
+          fullPlanMd: task.fullPlanMd,
         });
       }
     });

package/src/resources/extensions/gsd/tools/plan-task.ts

@@ -15,6 +15,7 @@ export interface PlanTaskParams {
   inputs: string[];
   expectedOutput: string[];
   observabilityImpact?: string;
+  fullPlanMd?: string;
 }
 
 export interface PlanTaskResult {
@@ -94,6 +95,7 @@ export async function handlePlanTask(
         inputs: params.inputs,
         expectedOutput: params.expectedOutput,
         observabilityImpact: params.observabilityImpact ?? "",
+        fullPlanMd: params.fullPlanMd,
       });
     });
   } catch (err) {

package/src/resources/extensions/gsd/tools/replan-slice.ts

@@ -21,6 +21,7 @@ export interface ReplanSliceTaskInput {
   verify: string;
   inputs: string[];
   expectedOutput: string[];
+  fullPlanMd?: string;
 }
 
 export interface ReplanSliceParams {
@@ -136,6 +137,7 @@ export async function handleReplanSlice(
             verify: updatedTask.verify || "",
             inputs: updatedTask.inputs || [],
             expectedOutput: updatedTask.expectedOutput || [],
+            fullPlanMd: updatedTask.fullPlanMd,
           });
         } else {
           // Insert new task then set planning fields
@@ -154,6 +156,7 @@ export async function handleReplanSlice(
             verify: updatedTask.verify || "",
             inputs: updatedTask.inputs || [],
             expectedOutput: updatedTask.expectedOutput || [],
+            fullPlanMd: updatedTask.fullPlanMd,
           });
         }
       }

package/src/resources/extensions/gsd/tools/validate-milestone.ts

@@ -0,0 +1,127 @@
+/**
+ * validate-milestone handler — the core operation behind gsd_validate_milestone.
+ *
+ * Persists milestone validation results to the assessments table,
+ * renders VALIDATION.md to disk, and invalidates caches.
+ */
+
+import { join } from "node:path";
+
+import {
+  transaction,
+  _getAdapter,
+} from "../gsd-db.js";
+import { resolveMilestonePath, clearPathCache } from "../paths.js";
+import { saveFile, clearParseCache } from "../files.js";
+import { invalidateStateCache } from "../state.js";
+
+export interface ValidateMilestoneParams {
+  milestoneId: string;
+  verdict: "pass" | "needs-attention" | "needs-remediation";
+  remediationRound: number;
+  successCriteriaChecklist: string;
+  sliceDeliveryAudit: string;
+  crossSliceIntegration: string;
+  requirementCoverage: string;
+  verdictRationale: string;
+  remediationPlan?: string;
+}
+
+export interface ValidateMilestoneResult {
+  milestoneId: string;
+  verdict: string;
+  validationPath: string;
+}
+
+function renderValidationMarkdown(params: ValidateMilestoneParams): string {
+  let md = `---
+verdict: ${params.verdict}
+remediation_round: ${params.remediationRound}
+---
+
+# Milestone Validation: ${params.milestoneId}
+
+## Success Criteria Checklist
+${params.successCriteriaChecklist}
+
+## Slice Delivery Audit
+${params.sliceDeliveryAudit}
+
+## Cross-Slice Integration
+${params.crossSliceIntegration}
+
+## Requirement Coverage
+${params.requirementCoverage}
+
+## Verdict Rationale
+${params.verdictRationale}
+`;
+
+  if (params.verdict === "needs-remediation" && params.remediationPlan) {
+    md += `\n## Remediation Plan\n${params.remediationPlan}\n`;
+  }
+
+  return md;
+}
+
+export async function handleValidateMilestone(
+  params: ValidateMilestoneParams,
+  basePath: string,
+): Promise<ValidateMilestoneResult | { error: string }> {
+  if (!params.milestoneId || typeof params.milestoneId !== "string" || params.milestoneId.trim() === "") {
+    return { error: "milestoneId is required and must be a non-empty string" };
+  }
+  const validVerdicts = ["pass", "needs-attention", "needs-remediation"];
+  if (!validVerdicts.includes(params.verdict)) {
+    return { error: `verdict must be one of: ${validVerdicts.join(", ")}` };
+  }
+
+  // ── Filesystem render ──────────────────────────────────────────────────
+  const validationMd = renderValidationMarkdown(params);
+
+  let validationPath: string;
+  const milestoneDir = resolveMilestonePath(basePath, params.milestoneId);
+  if (milestoneDir) {
+    validationPath = join(milestoneDir, `${params.milestoneId}-VALIDATION.md`);
+  } else {
+    const gsdDir = join(basePath, ".gsd");
+    const manualDir = join(gsdDir, "milestones", params.milestoneId);
+    validationPath = join(manualDir, `${params.milestoneId}-VALIDATION.md`);
+  }
+
+  try {
+    await saveFile(validationPath, validationMd);
+  } catch (renderErr) {
+    process.stderr.write(
+      `gsd-db: validate_milestone — disk render failed: ${(renderErr as Error).message}\n`,
+    );
+    return { error: `disk render failed: ${(renderErr as Error).message}` };
+  }
+
+  // ── DB write — store in assessments table ──────────────────────────────
+  const validatedAt = new Date().toISOString();
+
+  transaction(() => {
+    const adapter = _getAdapter()!;
+    adapter.prepare(
+      `INSERT OR REPLACE INTO assessments (path, milestone_id, slice_id, task_id, status, scope, full_content, created_at)
+       VALUES (:path, :mid, NULL, NULL, :verdict, 'milestone-validation', :content, :created_at)`,
+    ).run({
+      ":path": validationPath,
+      ":mid": params.milestoneId,
+      ":verdict": params.verdict,
+      ":content": validationMd,
+      ":created_at": validatedAt,
+    });
+  });
+
+  invalidateStateCache();
+  clearPathCache();
+  clearParseCache();
+
+  return {
+    milestoneId: params.milestoneId,
+    verdict: params.verdict,
+    validationPath,
+  };
+}