@opengsd/gsd-pi 1.2.0-dev.844675c9 → 1.2.0-dev.84c56d87

package/src/resources/extensions/gsd/milestone-closeout.ts

@@ -10,13 +10,13 @@ import { parseRoadmap } from "./parsers-legacy.js";
 import { resolveMilestoneFile } from "./paths.js";
 import { getMilestone, getMilestoneSlices, isDbAvailable } from "./gsd-db.js";
 import { isClosedStatus } from "./status-guards.js";
-import { verifyExpectedArtifact } from "./auto-recovery.js";
 import { runSafely } from "./auto-utils.js";
 import { extractVerdict, isAcceptableUatVerdict } from "./verdict-parser.js";
 import { logWarning } from "./workflow-logger.js";
 import { hasImplementationArtifacts } from "./milestone-implementation-evidence.js";
 import { buildCompleteMilestonePrompt } from "./auto-prompts.js";
-import { checkCloseoutConsistencyGate } from "./closeout-consistency-gate.js";
+import { proveMilestoneCloseout } from "./milestone-closeout-proof.js";
+import { resolveCanonicalMilestoneRoot } from "./worktree-manager.js";
 import type { DispatchAction, DispatchContext } from "./auto-dispatch.js";
 import {
   commitPendingMilestoneCloseoutChanges,
@@ -38,8 +38,16 @@ export async function isMilestoneCloseoutSettled(mid: string, basePath: string):
     if (isDbAvailable()) {
       const milestone = getMilestone(mid);
       if (milestone && isClosedStatus(milestone.status)) {
-        const closeoutGate = checkCloseoutConsistencyGate(mid, { refreshFromDisk: true });
-        if (closeoutGate.ok && verifyExpectedArtifact("complete-milestone", mid, basePath)) {
+        const artifactBasePath = resolveCanonicalMilestoneRoot(basePath, mid);
+        const closeoutProof = proveMilestoneCloseout(mid, {
+          refreshFromDisk: true,
+          summaryArtifactBasePath: artifactBasePath,
+          implementationEvidence: {
+            basePath,
+            requirement: "not-absent",
+          },
+        });
+        if (closeoutProof.ok) {
           return true;
         }
       }

package/src/resources/extensions/gsd/milestone-merge-transaction.ts

@@ -0,0 +1,47 @@
+// Project/App: gsd-pi
+// File Purpose: Process-level transaction wrapper for milestone merge closeout.
+
+export interface MilestoneMergeTransactionResult {
+  pushed: boolean;
+  codeFilesChanged: boolean;
+  commitMessage?: string;
+  prCreated?: boolean;
+}
+
+export interface MilestoneMergeTransactionInput {
+  basePath: string;
+  milestoneId: string;
+  roadmapContent: string;
+}
+
+export type MilestoneMergeTransactionRunner = (
+  basePath: string,
+  milestoneId: string,
+  roadmapContent: string,
+) => MilestoneMergeTransactionResult;
+
+export interface MilestoneMergeTransactionDeps {
+  mergeMilestoneToMain: MilestoneMergeTransactionRunner;
+}
+
+export function runMilestoneMergeTransaction(
+  deps: MilestoneMergeTransactionDeps,
+  input: MilestoneMergeTransactionInput,
+): MilestoneMergeTransactionResult {
+  return deps.mergeMilestoneToMain(
+    input.basePath,
+    input.milestoneId,
+    input.roadmapContent,
+  );
+}
+
+export function createMilestoneMergeTransaction(
+  mergeMilestoneToMain: MilestoneMergeTransactionRunner,
+): MilestoneMergeTransactionRunner {
+  return function mergeMilestoneTransaction(basePath, milestoneId, roadmapContent) {
+    return runMilestoneMergeTransaction(
+      { mergeMilestoneToMain },
+      { basePath, milestoneId, roadmapContent },
+    );
+  };
+}

package/src/resources/extensions/gsd/milestone-planning-persistence.ts

@@ -0,0 +1,224 @@
+// Project/App: gsd-pi
+// File Purpose: Persist planned milestone roadmaps and their DB-backed projections.
+
+import { clearParseCache } from "./files.js";
+import { isClosedStatus } from "./status-guards.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";
+
+export interface PersistMilestonePlanSlice {
+  sliceId: string;
+  title: string;
+  risk: string;
+  depends: string[];
+  demo: string;
+  goal: string;
+  successCriteria: string;
+  proofLevel: string;
+  integrationClosure: string;
+  observabilityImpact: string;
+  isSketch?: boolean;
+  sketchScope?: string;
+}
+
+export interface PersistMilestonePlanParams {
+  milestoneId: string;
+  title: string;
+  vision: string;
+  slices: PersistMilestonePlanSlice[];
+  status?: string;
+  dependsOn?: string[];
+  actorName?: string;
+  triggerReason?: string;
+  successCriteria?: string[];
+  keyRisks?: Array<{ risk: string; whyItMatters: string }>;
+  proofStrategy?: Array<{ riskOrUnknown: string; retireIn: string; whatWillBeProven: string }>;
+  verificationContract?: string;
+  verificationIntegration?: string;
+  verificationOperational?: string;
+  verificationUat?: string;
+  definitionOfDone?: string[];
+  requirementCoverage?: string;
+  boundaryMapMarkdown?: string;
+}
+
+export interface PersistMilestonePlanResult {
+  milestoneId: string;
+  roadmapPath: string;
+}
+
+function validatePlanPromotion(params: PersistMilestonePlanParams): string | null {
+  const existingMilestone = getMilestone(params.milestoneId);
+  if (existingMilestone && isClosedStatus(existingMilestone.status)) {
+    return `cannot re-plan milestone ${params.milestoneId}: it is already complete`;
+  }
+
+  // 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) {
+      return `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.`;
+    }
+  }
+
+  // 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) {
+        return `depends_on references unknown milestone: ${depId}`;
+      }
+      if (!isClosedStatus(dep.status)) {
+        return `depends_on milestone ${depId} is not yet complete (status: ${dep.status})`;
+      }
+    }
+  }
+
+  return null;
+}
+
+function writePlanRows(params: PersistMilestonePlanParams): void {
+  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,
+    });
+  }
+}
+
+async function renderPlanArtifacts(
+  basePath: string,
+  params: PersistMilestonePlanParams,
+): Promise<string | { error: string }> {
+  try {
+    const renderResult = await renderRoadmapFromDb(basePath, params.milestoneId);
+    return 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}` };
+  }
+}
+
+async function runPostPlanHooks(basePath: string, params: PersistMilestonePlanParams): Promise<void> {
+  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}`);
+  }
+}
+
+export async function persistMilestonePlan(
+  params: PersistMilestonePlanParams,
+  basePath: string,
+): Promise<PersistMilestonePlanResult | { error: string }> {
+  // ── 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(() => {
+      guardError = validatePlanPromotion(params);
+      if (guardError) return;
+      writePlanRows(params);
+    });
+  } catch (err) {
+    return { error: `db write failed: ${(err as Error).message}` };
+  }
+
+  if (guardError) {
+    return { error: guardError };
+  }
+
+  const roadmapPath = await renderPlanArtifacts(basePath, params);
+  if (typeof roadmapPath !== "string") return roadmapPath;
+
+  invalidateStateCache();
+  clearParseCache();
+
+  await runPostPlanHooks(basePath, params);
+
+  return {
+    milestoneId: params.milestoneId,
+    roadmapPath,
+  };
+}

package/src/resources/extensions/gsd/milestone-readiness.ts

@@ -0,0 +1,125 @@
+// Project/App: gsd-pi
+// File Purpose: Classify milestone readiness from DB status, slices, and artifacts.
+
+import { readFileSync } from "node:fs";
+import type { Phase } from "./types.js";
+import { getMilestone, getMilestoneSlices, isDbAvailable } from "./gsd-db.js";
+import { parseRoadmapSlices } from "./roadmap-slices.js";
+import { logWarning } from "./workflow-logger.js";
+
+export type MilestoneReadinessKind =
+  | "queued-shell"
+  | "needs-discussion"
+  | "planning-pending"
+  | "executable-plan"
+  | "terminal";
+
+export interface MilestoneReadiness {
+  kind: MilestoneReadinessKind;
+  hasContext: boolean;
+  hasDraftContext: boolean;
+  hasExecutablePlan: boolean;
+}
+
+export interface MilestoneReadinessInput {
+  status?: string | null;
+  hasContext?: boolean;
+  hasDraftContext?: boolean;
+  hasSummary?: boolean;
+  sliceCount?: number;
+}
+
+export interface HandoffReadinessInput {
+  milestoneId: string;
+  contextFile: string | null;
+  roadmapFile: string | null;
+}
+
+export function classifyMilestoneReadiness(input: MilestoneReadinessInput): MilestoneReadiness {
+  const hasContext = input.hasContext === true;
+  const hasDraftContext = !hasContext && input.hasDraftContext === true;
+  const hasSummary = input.hasSummary === true;
+  const sliceCount = input.sliceCount ?? 0;
+  const hasExecutablePlan = sliceCount > 0;
+  const status = input.status ?? null;
+
+  if (status === "complete" || hasSummary) {
+    return { kind: "terminal", hasContext, hasDraftContext, hasExecutablePlan };
+  }
+
+  if (status === "queued" && !hasContext && sliceCount === 0) {
+    return { kind: "queued-shell", hasContext, hasDraftContext, hasExecutablePlan };
+  }
+
+  if ((status === "needs-discussion" && !hasContext) || hasDraftContext) {
+    return { kind: "needs-discussion", hasContext, hasDraftContext, hasExecutablePlan };
+  }
+
+  if (hasExecutablePlan) {
+    return { kind: "executable-plan", hasContext, hasDraftContext, hasExecutablePlan };
+  }
+
+  return { kind: "planning-pending", hasContext, hasDraftContext, hasExecutablePlan };
+}
+
+export function readinessNeedsDiscussion(readiness: MilestoneReadiness): boolean {
+  return readiness.kind === "needs-discussion" ||
+    (readiness.kind === "queued-shell" && readiness.hasDraftContext);
+}
+
+export function describeMilestoneReadinessPhase(
+  phase: Phase,
+): { label: string; description: string } | null {
+  switch (phase) {
+    case "needs-discussion":
+      return {
+        label: "Discuss milestone draft",
+        description: "Milestone has a draft context — needs discussion before planning.",
+      };
+    case "pre-planning":
+      return {
+        label: "Research & plan milestone",
+        description: "Scout the landscape and create the roadmap.",
+      };
+    default:
+      return null;
+  }
+}
+
+function executablePlanSliceCount(milestoneId: string, roadmapFile: string | null): number {
+  if (isDbAvailable()) {
+    return getMilestoneSlices(milestoneId).length;
+  }
+  if (!roadmapFile) return 0;
+  try {
+    return parseRoadmapSlices(readFileSync(roadmapFile, "utf-8")).length;
+  } catch (e) {
+    logWarning(
+      "guided",
+      `failed to parse roadmap slices for ${milestoneId}: ${(e as Error).message}`,
+    );
+    return 0;
+  }
+}
+
+export function assessMilestoneHandoffReadiness(
+  input: HandoffReadinessInput,
+): MilestoneReadiness {
+  const milestone = isDbAvailable() ? getMilestone(input.milestoneId) : null;
+  return classifyMilestoneReadiness({
+    status: milestone?.status,
+    hasContext: input.contextFile != null,
+    sliceCount: executablePlanSliceCount(input.milestoneId, input.roadmapFile),
+  });
+}
+
+export function formatAcceptedDiscussHandoffMessage(
+  milestoneId: string,
+  readiness: MilestoneReadiness,
+): string {
+  if (readiness.hasExecutablePlan) return `Milestone ${milestoneId} ready.`;
+  if (readiness.hasContext) {
+    return `Milestone ${milestoneId} context captured. Continuing the planning pipeline.`;
+  }
+  return `Milestone ${milestoneId} planning artifacts captured. Continuing the planning pipeline.`;
+}

package/src/resources/extensions/gsd/milestone-settlement.ts

@@ -0,0 +1,81 @@
+// Project/App: gsd-pi
+// File Purpose: Milestone closeout settlement state across DB proof, artifacts, merge, and cleanup.
+
+import { isInAutoWorktree } from "./auto-worktree.js";
+import {
+  formatCloseoutProofBlock,
+  proveMilestoneCloseout,
+} from "./milestone-closeout-proof.js";
+import { resolveCloseoutArtifactProjection } from "./artifact-projection.js";
+
+export type MilestoneSettlementOutcome =
+  | { ok: true; reason: "settled" | "not-applicable" }
+  | {
+      ok: false;
+      reason: "closeout-blocked" | "merge-pending";
+      action: "pause";
+      message: string;
+      nextAction: string;
+      milestoneId: string;
+    };
+
+export interface MilestoneSettlementInput {
+  milestoneId: string | null | undefined;
+  statePhase: string;
+  basePath: string;
+  originalBasePath: string;
+  milestoneMerged: boolean;
+}
+
+function isActiveUnmergedWorktree(input: MilestoneSettlementInput): boolean {
+  if (!input.milestoneId || input.milestoneMerged) return false;
+  return isInAutoWorktree(input.basePath);
+}
+
+export function evaluateAllCompleteSettlement(
+  input: MilestoneSettlementInput,
+): MilestoneSettlementOutcome {
+  if (input.statePhase !== "complete") {
+    return { ok: true, reason: "not-applicable" };
+  }
+  if (!isActiveUnmergedWorktree(input)) {
+    return { ok: true, reason: "settled" };
+  }
+
+  const milestoneId = input.milestoneId;
+  if (!milestoneId) {
+    return { ok: true, reason: "settled" };
+  }
+
+  const projection = resolveCloseoutArtifactProjection({
+    milestoneId,
+    basePath: input.basePath,
+    originalBasePath: input.originalBasePath,
+  });
+  const proof = proveMilestoneCloseout(milestoneId, {
+    refreshFromDisk: true,
+    summaryArtifactBasePath: projection.summaryArtifactBasePath,
+  });
+
+  if (!proof.ok) {
+    return {
+      ok: false,
+      reason: "closeout-blocked",
+      action: "pause",
+      message: `${formatCloseoutProofBlock(proof)} The milestone branch has not been merged to main.`,
+      nextAction: `Resolve closeout blockers, then retry \`/gsd dispatch complete-milestone ${milestoneId}\`.`,
+      milestoneId,
+    };
+  }
+
+  return {
+    ok: false,
+    reason: "merge-pending",
+    action: "pause",
+    message:
+      `Milestone ${milestoneId} is complete, but its worktree branch has not been merged to main. ` +
+      `Retry with \`/gsd dispatch complete-milestone ${milestoneId}\` or merge manually.`,
+    nextAction: `Retry \`/gsd dispatch complete-milestone ${milestoneId}\` or merge manually.`,
+    milestoneId,
+  };
+}

package/src/resources/extensions/gsd/milestone-validation-evidence.ts

@@ -0,0 +1,95 @@
+// Project/App: gsd-pi
+// File Purpose: Forwarded validation evidence rules for milestone validation.
+
+import { getArtifact, getMilestone, getMilestoneSlices } from "./gsd-db.js";
+import { loadFile } from "./files.js";
+import { resolveSliceFile } from "./paths.js";
+import {
+  compactTextParts,
+  hasBrowserEvidenceText,
+  hasBrowserRequiredText,
+} from "./browser-evidence.js";
+
+export interface MilestoneValidationEvidenceParams {
+  milestoneId: string;
+  verdict: "pass" | "needs-attention" | "needs-remediation";
+  successCriteriaChecklist: string;
+  verificationClasses?: string;
+  verdictRationale: string;
+  remediationPlan?: string;
+}
+
+export 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);
+}
+
+export async function browserEvidenceGateRequiresAttention(
+  params: MilestoneValidationEvidenceParams,
+  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;
+
+  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 browserRequiringSlices = sliceEvidencePairs.filter((slice) =>
+    hasBrowserRequiredText(slice.sliceRequirementText),
+  );
+  const runtimeBypasses =
+    browserRequiringSlices.length > 0
+      ? browserRequiringSlices.every((slice) => hasRuntimeExecutableUatEvidenceText(slice.evidenceText))
+      : sliceEvidencePairs.some((slice) => hasRuntimeExecutableUatEvidenceText(slice.evidenceText));
+  if (runtimeBypasses) return false;
+
+  const persistedEvidence = sliceEvidencePairs.map((slice) => slice.evidenceText).join("\n\n");
+  const validationEvidence = compactTextParts([
+    params.successCriteriaChecklist,
+    params.verificationClasses,
+    params.verdictRationale,
+    params.remediationPlan,
+  ]);
+  return !hasBrowserEvidenceText(`${persistedEvidence}\n\n${validationEvidence}`);
+}
+
+export function applyBrowserEvidenceGate<T extends MilestoneValidationEvidenceParams>(
+  params: T,
+): Omit<T, "verdict" | "verdictRationale"> & { verdict: "needs-attention"; verdictRationale: string } {
+  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,
+  };
+}

package/src/resources/extensions/gsd/milestone-validation-verdict.ts

@@ -0,0 +1,80 @@
+// Project/App: gsd-pi
+// File Purpose: Resolve the authoritative milestone validation verdict across DB and disk projections.
+
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+
+import { resolveExpectedArtifactPath } from "./auto-artifact-paths.js";
+import { loadFile } from "./files.js";
+import { getLatestAssessmentByScope, isDbAvailable } from "./gsd-db.js";
+import { gsdProjectionRoot } from "./paths.js";
+import {
+  extractVerdict,
+  isValidMilestoneVerdict,
+  type ValidationVerdict,
+} from "./verdict-parser.js";
+import { resolveCanonicalMilestoneRoot } from "./worktree-manager.js";
+import { resolveWorktreeProjectRoot } from "./worktree-root.js";
+
+function verdictFromContent(content: string | null | undefined): ValidationVerdict | undefined {
+  if (!content) return undefined;
+  const verdict = extractVerdict(content);
+  return verdict && isValidMilestoneVerdict(verdict) ? verdict : undefined;
+}
+
+function verdictFromDb(milestoneId: string): ValidationVerdict | undefined {
+  if (!isDbAvailable()) return undefined;
+  const assessment = getLatestAssessmentByScope(milestoneId, "milestone-validation");
+  const status = typeof assessment?.status === "string" ? assessment.status : undefined;
+  return status && isValidMilestoneVerdict(status) ? status : undefined;
+}
+
+async function verdictFromValidationPath(path: string | null): Promise<ValidationVerdict | undefined> {
+  if (!path || !existsSync(path)) return undefined;
+  return verdictFromContent(await loadFile(path));
+}
+
+/**
+ * Resolve the milestone validation verdict using the same authority order as
+ * DB-backed state derivation, with filesystem fallbacks that mirror
+ * `resolveExpectedArtifactPath` (canonical worktree projection, then project
+ * root). Manual `/gsd verdict` overrides persist to the DB first; a stale
+ * worktree-local VALIDATION.md must not re-block auto-mode after the override.
+ */
+export async function resolveMilestoneValidationVerdict(
+  basePath: string,
+  milestoneId: string,
+): Promise<ValidationVerdict | undefined> {
+  const dbVerdict = verdictFromDb(milestoneId);
+  if (dbVerdict) return dbVerdict;
+
+  const canonicalBase = resolveCanonicalMilestoneRoot(basePath, milestoneId);
+  const canonicalPath = resolveExpectedArtifactPath(
+    "validate-milestone",
+    milestoneId,
+    canonicalBase,
+  );
+  const canonicalVerdict = await verdictFromValidationPath(canonicalPath);
+  if (canonicalVerdict) return canonicalVerdict;
+
+  const projectRoot = resolveWorktreeProjectRoot(basePath);
+  if (projectRoot !== canonicalBase) {
+    const projectPath = resolveExpectedArtifactPath(
+      "validate-milestone",
+      milestoneId,
+      projectRoot,
+    );
+    const projectVerdict = await verdictFromValidationPath(projectPath);
+    if (projectVerdict) return projectVerdict;
+  }
+
+  // Last resort: direct canonical projection path even when resolveDir helpers
+  // have not materialized the milestone directory yet.
+  const directPath = join(
+    gsdProjectionRoot(canonicalBase),
+    "milestones",
+    milestoneId,
+    `${milestoneId}-VALIDATION.md`,
+  );
+  return verdictFromValidationPath(directPath);
+}