@opengsd/gsd-pi 1.1.1-dev.b2556262 → 1.2.0-dev.4813ead6

package/src/resources/extensions/gsd/tool-presentation-plan.ts

@@ -7,7 +7,10 @@ import {
   RUN_UAT_TOOL_PRESENTATION_PLAN_ID,
   RUN_UAT_WORKFLOW_TOOL_NAMES,
 } from "./unit-tool-contracts.js";
+import { parseMcpToolName, toMcpToolName } from "./mcp-tool-name.js";
+import { createToolSurfaceSnapshot, type ToolSurfaceSnapshot } from "./tool-surface-snapshot.js";
 import { uatTypeIncludesBrowser } from "./uat-policy.js";
+import { canonicalWorkflowSurfaceToolName } from "./workflow-tool-surface.js";
 
 export {
   RUN_UAT_BROWSER_TOOL_NAMES,
@@ -33,6 +36,7 @@ export interface ToolPresentationPlan {
   blockedToolNames: Array<{ name: string; reason: string }>;
   aliases: Array<{ requested: string; canonical: string }>;
   diagnostics: string[];
+  toolSurface: ToolSurfaceSnapshot;
 }
 
 export interface RunUatResultPresentation {
@@ -62,44 +66,14 @@ export const RUN_UAT_CLAUDE_NATIVE_TOOL_NAMES = [
   "Grep",
 ] as const;
 
-const WORKFLOW_ALIAS_TO_CANONICAL: Record<string, string> = {
-  gsd_save_decision: "gsd_decision_save",
-  gsd_update_requirement: "gsd_requirement_update",
-  gsd_save_requirement: "gsd_requirement_save",
-  gsd_save_summary: "gsd_summary_save",
-  gsd_generate_milestone_id: "gsd_milestone_generate_id",
-  gsd_milestone_plan: "gsd_plan_milestone",
-  gsd_slice_plan: "gsd_plan_slice",
-  gsd_task_plan: "gsd_plan_task",
-  gsd_slice_replan: "gsd_replan_slice",
-  gsd_complete_slice: "gsd_slice_complete",
-  gsd_milestone_complete: "gsd_complete_milestone",
-  gsd_milestone_validate: "gsd_validate_milestone",
-  gsd_roadmap_reassess: "gsd_reassess_roadmap",
-  gsd_complete_task: "gsd_task_complete",
-  gsd_reopen_task: "gsd_task_reopen",
-  gsd_reopen_slice: "gsd_slice_reopen",
-  gsd_reopen_milestone: "gsd_milestone_reopen",
-};
-
 export function canonicalWorkflowToolName(toolName: string): string {
-  const mcp = parseMcpToolName(toolName);
-  const baseName = mcp?.tool ?? toolName;
-  return WORKFLOW_ALIAS_TO_CANONICAL[baseName] ?? baseName;
+  return canonicalWorkflowSurfaceToolName(toolName);
 }
 
-export function parseMcpToolName(toolName: string): { server: string; tool: string } | null {
-  if (!toolName.startsWith("mcp__")) return null;
-  const toolSeparator = toolName.indexOf("__", "mcp__".length);
-  if (toolSeparator < 0) return null;
-  return {
-    server: toolName.slice("mcp__".length, toolSeparator),
-    tool: toolName.slice(toolSeparator + 2),
-  };
-}
+export { parseMcpToolName } from "./mcp-tool-name.js";
 
 export function toWorkflowMcpToolName(serverName: string, toolName: string): string {
-  return `mcp__${serverName}__${canonicalWorkflowToolName(toolName)}`;
+  return toMcpToolName(serverName, canonicalWorkflowToolName(toolName));
 }
 
 function dedupe(values: readonly string[]): string[] {
@@ -212,6 +186,14 @@ export function resolveToolPresentationPlan(options: {
           : name
       )
     : allowedToolNames;
+  const toolSurface = createToolSurfaceSnapshot({
+    source: "presentation-plan",
+    phase: options.phase,
+    modelFacingToolNames: options.availableToolNames ?? requested,
+    registeredToolNames: options.availableToolNames ?? requested,
+    scopedToolNames: allowedToolNames,
+    presentedToolNames,
+  });
 
   if (options.phase === "run-uat") {
     for (const forbidden of RUN_UAT_FORBIDDEN_TOOL_NAMES) {
@@ -228,5 +210,6 @@ export function resolveToolPresentationPlan(options: {
     blockedToolNames,
     aliases,
     diagnostics: [],
+    toolSurface,
   };
 }

package/src/resources/extensions/gsd/tool-surface-snapshot.ts

@@ -0,0 +1,47 @@
+// Project/App: gsd-pi
+// File Purpose: Typed snapshots for model-facing, registered, scoped, and presented tool surfaces.
+
+export type ToolSurfaceSnapshotSource =
+  | "runtime-scope"
+  | "dispatch-scope"
+  | "provider-adjustment"
+  | "presentation-plan";
+
+export interface ToolSurfaceSnapshot {
+  source: ToolSurfaceSnapshotSource;
+  unitType?: string;
+  phase?: string;
+  modelFacingToolNames: string[];
+  registeredToolNames: string[];
+  scopedToolNames: string[];
+  presentedToolNames: string[];
+  capturedAt: number;
+}
+
+export interface ToolSurfaceSnapshotInput {
+  source: ToolSurfaceSnapshotSource;
+  unitType?: string;
+  phase?: string;
+  modelFacingToolNames?: readonly string[];
+  registeredToolNames?: readonly string[];
+  scopedToolNames?: readonly string[];
+  presentedToolNames?: readonly string[];
+  capturedAt?: number;
+}
+
+function dedupeToolNames(toolNames: readonly string[] | undefined): string[] {
+  return [...new Set(toolNames ?? [])];
+}
+
+export function createToolSurfaceSnapshot(input: ToolSurfaceSnapshotInput): ToolSurfaceSnapshot {
+  return {
+    source: input.source,
+    unitType: input.unitType,
+    phase: input.phase,
+    modelFacingToolNames: dedupeToolNames(input.modelFacingToolNames),
+    registeredToolNames: dedupeToolNames(input.registeredToolNames),
+    scopedToolNames: dedupeToolNames(input.scopedToolNames),
+    presentedToolNames: dedupeToolNames(input.presentedToolNames),
+    capturedAt: input.capturedAt ?? Date.now(),
+  };
+}

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

@@ -1,25 +1,8 @@
 // Project/App: gsd-pi
 // File Purpose: Plans milestone roadmap state through DB-backed workflow tools.
 
-import { clearParseCache } from "../files.js";
-import { isClosedStatus } from "../status-guards.js";
 import { isNonEmptyString, validateStringArray, validateTitle } from "../validation.js";
-import {
-  transaction,
-  getMilestone,
-  getMilestoneSlices,
-  getSlice,
-  insertMilestone,
-  insertSlice,
-  upsertMilestonePlanning,
-  upsertSlicePlanning,
-} from "../gsd-db.js";
-import { invalidateStateCache } from "../state.js";
-import { renderRoadmapFromDb } from "../markdown-renderer.js";
-import { renderAllProjections } from "../workflow-projections.js";
-import { writeManifest } from "../workflow-manifest.js";
-import { appendEvent } from "../workflow-events.js";
-import { logWarning } from "../workflow-logger.js";
+import { persistMilestonePlan } from "../milestone-planning-persistence.js";
 
 export interface PlanMilestoneSliceInput {
   sliceId: string;
@@ -115,11 +98,21 @@ function validateProofStrategy(value: unknown): Array<{ riskOrUnknown: string; r
   });
 }
 
+const SLICE_ID_RE = /^[A-Za-z0-9][A-Za-z0-9-]*$/;
+
 function validateSlices(value: unknown): PlanMilestoneSliceInput[] {
   if (!Array.isArray(value) || value.length === 0) {
     throw new Error("slices must be a non-empty array");
   }
 
+  // Pre-collect all slice IDs so depends cross-validation can reference the full set.
+  const allSliceIds = new Set<string>(
+    (value as unknown[])
+      .filter((e): e is Record<string, unknown> => !!e && typeof e === "object")
+      .map(e => e.sliceId)
+      .filter((id): id is string => isNonEmptyString(id)),
+  );
+
   const seen = new Set<string>();
   return value.map((entry, index) => {
     if (!entry || typeof entry !== "object") {
@@ -154,8 +147,13 @@ function validateSlices(value: unknown): PlanMilestoneSliceInput[] {
     const titleIssue = validateTitle(title);
     if (titleIssue) throw new Error(`slices[${index}].title is invalid: ${titleIssue}`);
     if (!isNonEmptyString(risk)) throw new Error(`slices[${index}].risk must be a non-empty string`);
-    if (!Array.isArray(depends) || depends.some((item) => !isNonEmptyString(item))) {
-      throw new Error(`slices[${index}].depends must be an array of non-empty strings`);
+    if (!Array.isArray(depends) || depends.some((item) => !isNonEmptyString(item) || !SLICE_ID_RE.test(item as string))) {
+      throw new Error(`slices[${index}].depends must be an array of valid slice IDs (e.g. "S01")`);
+    }
+    for (const dep of depends as string[]) {
+      if (!allSliceIds.has(dep)) {
+        throw new Error(`slices[${index}].depends references unknown slice "${dep}" — check that it is defined in the same milestone`);
+      }
     }
     if (!isNonEmptyString(demo)) throw new Error(`slices[${index}].demo must be a non-empty string`);
     if (!isNonEmptyString(goal)) throw new Error(`slices[${index}].goal must be a non-empty string`);
@@ -227,144 +225,5 @@ export async function handlePlanMilestone(
     return { error: `validation failed: ${(err as Error).message}` };
   }
 
-  // ── Guards + DB writes inside a single transaction (prevents TOCTOU) ───
-  // Guards must be inside the transaction so the state they check cannot
-  // change between the read and the write (#2723).
-  let guardError: string | null = null;
-
-  try {
-    transaction(() => {
-      const existingMilestone = getMilestone(params.milestoneId);
-      if (existingMilestone && isClosedStatus(existingMilestone.status)) {
-        guardError = `cannot re-plan milestone ${params.milestoneId}: it is already complete`;
-        return;
-      }
-
-      // Guard: refuse to re-plan a milestone that would drop completed slices (#2960).
-      // Allow re-planning when all completed slices are still present in the
-      // incoming plan — their status is preserved below (#2558). Block only when
-      // the new plan omits a completed slice, which could shadow completed work.
-      const existingSlices = getMilestoneSlices(params.milestoneId);
-      const completedSlices = existingSlices.filter(s => isClosedStatus(s.status));
-      if (completedSlices.length > 0) {
-        const incomingSliceIds = new Set(params.slices.map(s => s.sliceId));
-        const droppedCompleted = completedSlices.filter(s => !incomingSliceIds.has(s.id));
-        if (droppedCompleted.length > 0) {
-          guardError = `cannot re-plan milestone ${params.milestoneId}: ${droppedCompleted.length} completed slice(s) would be dropped (${droppedCompleted.map(s => s.id).join(", ")}). Use gsd_reassess_roadmap to modify the roadmap.`;
-          return;
-        }
-      }
-
-      // Validate depends_on: all dependencies must exist and be complete
-      if (params.dependsOn && params.dependsOn.length > 0) {
-        for (const depId of params.dependsOn) {
-          const dep = getMilestone(depId);
-          if (!dep) {
-            guardError = `depends_on references unknown milestone: ${depId}`;
-            return;
-          }
-          if (!isClosedStatus(dep.status)) {
-            guardError = `depends_on milestone ${depId} is not yet complete (status: ${dep.status})`;
-            return;
-          }
-        }
-      }
-
-      insertMilestone({
-        id: params.milestoneId,
-        title: params.title,
-        status: params.status ?? "active",
-        depends_on: params.dependsOn ?? [],
-      });
-
-      upsertMilestonePlanning(params.milestoneId, {
-        title: params.title,
-        status: params.status ?? "active",
-        depends_on: params.dependsOn ?? [],
-        vision: params.vision,
-        successCriteria: params.successCriteria,
-        keyRisks: params.keyRisks,
-        proofStrategy: params.proofStrategy,
-        verificationContract: params.verificationContract,
-        verificationIntegration: params.verificationIntegration,
-        verificationOperational: params.verificationOperational,
-        verificationUat: params.verificationUat,
-        definitionOfDone: params.definitionOfDone,
-        requirementCoverage: params.requirementCoverage,
-        boundaryMapMarkdown: params.boundaryMapMarkdown,
-      });
-
-      for (let i = 0; i < params.slices.length; i++) {
-        const slice = params.slices[i]!;
-        // Preserve completed/done status on re-plan (#2558).
-        // Without this, a re-plan after milestone transition would reset
-        // already-completed slices back to "pending".
-        const existing = getSlice(params.milestoneId, slice.sliceId);
-        const status = existing && (existing.status === "complete" || existing.status === "done")
-          ? existing.status
-          : "pending";
-        insertSlice({
-          id: slice.sliceId,
-          milestoneId: params.milestoneId,
-          title: slice.title,
-          status,
-          risk: slice.risk,
-          depends: slice.depends,
-          demo: slice.demo,
-          sequence: i + 1, // Preserve agent-ordered sequence (#3356)
-          // ADR-011: pass undefined through so ON CONFLICT preserves existing values
-          // when the caller omitted the fields on a re-plan.
-          isSketch: slice.isSketch,
-          sketchScope: slice.sketchScope,
-        });
-        upsertSlicePlanning(params.milestoneId, slice.sliceId, {
-          goal: slice.goal,
-          successCriteria: slice.successCriteria,
-          proofLevel: slice.proofLevel,
-          integrationClosure: slice.integrationClosure,
-          observabilityImpact: slice.observabilityImpact,
-        });
-      }
-    });
-  } catch (err) {
-    return { error: `db write failed: ${(err as Error).message}` };
-  }
-
-  if (guardError) {
-    return { error: guardError };
-  }
-
-  let roadmapPath: string;
-  try {
-    const renderResult = await renderRoadmapFromDb(basePath, params.milestoneId);
-    roadmapPath = renderResult.roadmapPath;
-  } catch (renderErr) {
-    logWarning("tool", `plan_milestone — render failed (DB rows preserved for debugging): ${(renderErr as Error).message}`);
-    invalidateStateCache();
-    return { error: `render failed: ${(renderErr as Error).message}` };
-  }
-
-  invalidateStateCache();
-  clearParseCache();
-
-  // ── Post-mutation hook: projections, manifest, event log ───────────────
-  try {
-    await renderAllProjections(basePath, params.milestoneId);
-    writeManifest(basePath);
-    appendEvent(basePath, {
-      cmd: "plan-milestone",
-      params: { milestoneId: params.milestoneId },
-      ts: new Date().toISOString(),
-      actor: "agent",
-      actor_name: params.actorName,
-      trigger_reason: params.triggerReason,
-    });
-  } catch (hookErr) {
-    logWarning("tool", `plan-milestone post-mutation hook warning: ${(hookErr as Error).message}`);
-  }
-
-  return {
-    milestoneId: params.milestoneId,
-    roadmapPath,
-  };
+  return persistMilestonePlan(params, basePath);
 }

package/src/resources/extensions/gsd/tools/reassess-roadmap.ts

@@ -75,12 +75,19 @@ function validateParams(params: ReassessRoadmapParams): ReassessRoadmapParams {
     throw new Error("sliceChanges.removed must be an array");
   }
 
+  const SLICE_ID_RE = /^[A-Za-z0-9][A-Za-z0-9-]*$/;
+
   // Validate each modified slice
   for (let i = 0; i < params.sliceChanges.modified.length; i++) {
     const s = params.sliceChanges.modified[i];
     if (!s || typeof s !== "object") throw new Error(`sliceChanges.modified[${i}] must be an object`);
     if (!isNonEmptyString(s.sliceId)) throw new Error(`sliceChanges.modified[${i}].sliceId is required`);
     if (!isNonEmptyString(s.title)) throw new Error(`sliceChanges.modified[${i}].title is required`);
+    if (s.depends !== undefined) {
+      if (!Array.isArray(s.depends) || s.depends.some((item: unknown) => !isNonEmptyString(item) || !SLICE_ID_RE.test(item as string))) {
+        throw new Error(`sliceChanges.modified[${i}].depends must be an array of valid slice IDs (e.g. "S01")`);
+      }
+    }
   }
 
   // Validate each added slice
@@ -89,6 +96,11 @@ function validateParams(params: ReassessRoadmapParams): ReassessRoadmapParams {
     if (!s || typeof s !== "object") throw new Error(`sliceChanges.added[${i}] must be an object`);
     if (!isNonEmptyString(s.sliceId)) throw new Error(`sliceChanges.added[${i}].sliceId is required`);
     if (!isNonEmptyString(s.title)) throw new Error(`sliceChanges.added[${i}].title is required`);
+    if (s.depends !== undefined) {
+      if (!Array.isArray(s.depends) || s.depends.some((item: unknown) => !isNonEmptyString(item) || !SLICE_ID_RE.test(item as string))) {
+        throw new Error(`sliceChanges.added[${i}].depends must be an array of valid slice IDs (e.g. "S01")`);
+      }
+    }
   }
 
   return params;
@@ -166,6 +178,37 @@ export async function handleReassessRoadmap(
         }
       }
 
+      // Cross-milestone depends validation — effective slice ID set after this reassessment
+      const removedIds = new Set<string>(params.sliceChanges.removed);
+      const effectiveSliceIds = new Set<string>(
+        existingSlices.map(s => s.id).filter(id => !removedIds.has(id)),
+      );
+      for (const added of params.sliceChanges.added) {
+        effectiveSliceIds.add(added.sliceId);
+      }
+      for (let i = 0; i < params.sliceChanges.modified.length; i++) {
+        const mod = params.sliceChanges.modified[i]!;
+        if (mod.depends !== undefined) {
+          for (const dep of mod.depends) {
+            if (!effectiveSliceIds.has(dep)) {
+              guardError = `sliceChanges.modified[${i}].depends references unknown slice "${dep}" — check that it is defined in this milestone`;
+              return;
+            }
+          }
+        }
+      }
+      for (let i = 0; i < params.sliceChanges.added.length; i++) {
+        const added = params.sliceChanges.added[i]!;
+        if (added.depends !== undefined) {
+          for (const dep of added.depends) {
+            if (!effectiveSliceIds.has(dep)) {
+              guardError = `sliceChanges.added[${i}].depends references unknown slice "${dep}" — check that it is defined in this milestone`;
+              return;
+            }
+          }
+        }
+      }
+
       // Record assessment
       insertAssessment({
         path: assessmentRelPath,

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

@@ -19,11 +19,11 @@ import {
   insertAssessment,
   getMilestoneSlices,
   getMilestone,
-  getArtifact,
 } from "../gsd-db.js";
-import { gsdProjectionRoot, clearPathCache, resolveSliceFile } from "../paths.js";
+import { gsdProjectionRoot, clearPathCache } from "../paths.js";
 import { resolveCanonicalMilestoneRoot } from "../worktree-manager.js";
-import { saveFile, clearParseCache, loadFile } from "../files.js";
+import { resolveWorktreeProjectRoot } from "../worktree-root.js";
+import { saveFile, clearParseCache } from "../files.js";
 import { invalidateStateCache } from "../state.js";
 import { VALIDATION_VERDICTS, isValidMilestoneVerdict } from "../verdict-parser.js";
 import { insertMilestoneValidationGates } from "../milestone-validation-gates.js";
@@ -31,7 +31,10 @@ import { logWarning } from "../workflow-logger.js";
 import { UokGateRunner } from "../uok/gate-runner.js";
 import { loadEffectiveGSDPreferences } from "../preferences.js";
 import { resolveUokFlags } from "../uok/flags.js";
-import { compactTextParts, hasBrowserEvidenceText, hasBrowserRequiredText } from "../browser-evidence.js";
+import {
+  applyBrowserEvidenceGate,
+  browserEvidenceGateRequiresAttention,
+} from "../milestone-validation-evidence.js";
 
 export interface ValidateMilestoneParams {
   milestoneId: string;
@@ -78,86 +81,6 @@ function getRequiredVerificationClasses(milestoneId: string): string[] {
   return required;
 }
 
-function hasRuntimeExecutableUatEvidenceText(text: string): boolean {
-  if (!/\buatType:\s*runtime-executable\b/i.test(text)) return false;
-  if (!/\bverdict:\s*PASS\b/i.test(text)) return false;
-  return /^\|\s*[^|\n]+\s*\|\s*runtime\s*\|\s*PASS\s*\|[^|\n]*\bgsd_uat_exec\b/mi.test(text);
-}
-
-async function browserEvidenceGateRequiresAttention(
-  params: ValidateMilestoneParams,
-  basePath: string,
-): Promise<boolean> {
-  if (params.verdict !== "pass") return false;
-
-  const milestone = getMilestone(params.milestoneId);
-  const slices = getMilestoneSlices(params.milestoneId);
-  const requirementText = compactTextParts([
-    milestone?.vision,
-    milestone?.success_criteria,
-    milestone?.verification_uat,
-    params.successCriteriaChecklist,
-    params.verificationClasses,
-    ...slices.flatMap((slice) => [
-      slice.demo,
-      slice.goal,
-      slice.success_criteria,
-    ]),
-  ]);
-  if (!hasBrowserRequiredText(requirementText)) return false;
-
-  // Collect per-slice evidence so the runtime bypass is checked independently
-  // for each slice. Concatenating all slices before checking would allow runtime
-  // evidence from one slice to cover another slice's browser requirements.
-  const sliceEvidencePairs: Array<{ sliceRequirementText: string; evidenceText: string }> = [];
-  for (const slice of slices) {
-    const chunks: string[] = [];
-    const artifactPath = `milestones/${params.milestoneId}/slices/${slice.id}/${slice.id}-ASSESSMENT.md`;
-    const artifact = getArtifact(artifactPath);
-    if (artifact?.full_content) chunks.push(artifact.full_content);
-    const assessmentPath = resolveSliceFile(basePath, params.milestoneId, slice.id, "ASSESSMENT");
-    const assessmentContent = assessmentPath ? await loadFile(assessmentPath) : null;
-    if (assessmentContent) chunks.push(assessmentContent);
-    sliceEvidencePairs.push({
-      sliceRequirementText: compactTextParts([slice.demo, slice.goal, slice.success_criteria]),
-      evidenceText: chunks.join("\n\n"),
-    });
-  }
-  const persistedEvidence = sliceEvidencePairs.map((s) => s.evidenceText).join("\n\n");
-
-  // Runtime bypass: each slice whose own requirement text has browser-observable
-  // criteria must have its own runtime-executable UAT evidence. When no individual
-  // slice has slice-level browser requirements (e.g., they come from milestone-level
-  // fields only), fall back to checking whether any slice has runtime evidence.
-  const browserRequiringSlices = sliceEvidencePairs.filter((s) =>
-    hasBrowserRequiredText(s.sliceRequirementText),
-  );
-  const runtimeBypasses =
-    browserRequiringSlices.length > 0
-      ? browserRequiringSlices.every((s) => hasRuntimeExecutableUatEvidenceText(s.evidenceText))
-      : sliceEvidencePairs.some((s) => hasRuntimeExecutableUatEvidenceText(s.evidenceText));
-  if (runtimeBypasses) return false;
-
-  const validationEvidence = compactTextParts([
-    params.successCriteriaChecklist,
-    params.verificationClasses,
-    params.verdictRationale,
-    params.remediationPlan,
-  ]);
-  return !hasBrowserEvidenceText(`${persistedEvidence}\n\n${validationEvidence}`);
-}
-
-function applyBrowserEvidenceGate(params: ValidateMilestoneParams): ValidateMilestoneParams {
-  const note = "Browser evidence gate: Browser-observable acceptance criteria were detected, but no persisted ASSESSMENT or validation evidence recorded browser actions with assertions. Downgraded from pass to needs-attention.";
-  return {
-    ...params,
-    verdict: "needs-attention",
-    verdictRationale: params.verdictRationale.trim()
-      ? `${params.verdictRationale.trim()}\n\n${note}`
-      : note,
-  };
-}
-
 function renderValidationMarkdown(params: ValidateMilestoneParams): string {
   let md = `---
 verdict: ${params.verdict}
@@ -279,6 +202,24 @@ export async function handleValidateMilestone(
   let projectionStale = false;
   try {
     await saveFile(validationPath, validationMd);
+    const projectRoot = resolveWorktreeProjectRoot(basePath);
+    if (projectRoot !== artifactBasePath) {
+      const projectValidationPath = join(
+        gsdProjectionRoot(projectRoot),
+        "milestones",
+        effectiveParams.milestoneId,
+        `${effectiveParams.milestoneId}-VALIDATION.md`,
+      );
+      try {
+        await saveFile(projectValidationPath, validationMd);
+      } catch (mirrorErr) {
+        logWarning(
+          "projection",
+          `validate_milestone project-root VALIDATION mirror failed for ${effectiveParams.milestoneId}`,
+          { error: (mirrorErr as Error).message },
+        );
+      }
+    }
   } catch (renderErr) {
     projectionStale = true;
     logWarning("projection", `validate_milestone projection write failed for ${effectiveParams.milestoneId}; DB validation remains committed`, {