@opengsd/gsd-pi 1.1.1-dev.b2556262 → 1.2.0-dev.0b870afa

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

@@ -0,0 +1,131 @@
+// Project/App: gsd-pi
+// File Purpose: Single proof surface for milestone closeout readiness/finality.
+
+import { existsSync, readFileSync } from "node:fs";
+
+import {
+  CLOSEOUT_CONSISTENCY_BLOCKED_REASON,
+  checkCloseoutConsistencyGate,
+  type CloseoutConsistencyFailureReason,
+  type CloseoutConsistencyResult,
+} from "./closeout-consistency-gate.js";
+import { resolveExpectedArtifactPath } from "./auto-artifact-paths.js";
+import { classifyMilestoneSummaryContent } from "./milestone-summary-classifier.js";
+import { hasImplementationArtifacts } from "./milestone-implementation-evidence.js";
+
+export type CloseoutProofFailureReason =
+  | CloseoutConsistencyFailureReason
+  | "summary-artifact-missing"
+  | "summary-artifact-failed"
+  | "implementation-evidence-missing";
+
+export type ImplementationEvidenceRequirement = "present" | "not-absent";
+
+export type CloseoutProofResult =
+  | { ok: true }
+  | {
+      ok: false;
+      reason: CloseoutProofFailureReason;
+      recoveryReason: typeof CLOSEOUT_CONSISTENCY_BLOCKED_REASON;
+      message: string;
+    };
+
+export interface CloseoutProofOptions {
+  refreshFromDisk?: boolean;
+  allowOpenMilestone?: boolean;
+  summaryArtifactBasePath?: string;
+  implementationEvidence?: {
+    basePath: string;
+    requirement: ImplementationEvidenceRequirement;
+  };
+}
+
+function blocked(reason: CloseoutProofFailureReason, message: string): CloseoutProofResult {
+  return {
+    ok: false,
+    reason,
+    recoveryReason: CLOSEOUT_CONSISTENCY_BLOCKED_REASON,
+    message,
+  };
+}
+
+function fromConsistencyResult(result: CloseoutConsistencyResult): CloseoutProofResult {
+  if (result.ok) return result;
+  return {
+    ok: false,
+    reason: result.reason,
+    recoveryReason: result.recoveryReason,
+    message: result.message,
+  };
+}
+
+function checkSummaryArtifact(milestoneId: string, basePath: string): CloseoutProofResult {
+  const summaryPath = resolveExpectedArtifactPath("complete-milestone", milestoneId, basePath);
+  if (!summaryPath || !existsSync(summaryPath)) {
+    return blocked(
+      "summary-artifact-missing",
+      `Closeout proof blocked for ${milestoneId}: milestone summary artifact is missing.`,
+    );
+  }
+
+  const summaryOutcome = classifyMilestoneSummaryContent(readFileSync(summaryPath, "utf-8"));
+  if (summaryOutcome === "failure") {
+    return blocked(
+      "summary-artifact-failed",
+      `Closeout proof blocked for ${milestoneId}: milestone summary records failed closeout.`,
+    );
+  }
+
+  return { ok: true };
+}
+
+function checkImplementationEvidence(
+  milestoneId: string,
+  basePath: string,
+  requirement: ImplementationEvidenceRequirement,
+): CloseoutProofResult {
+  const evidence = hasImplementationArtifacts(basePath, milestoneId);
+  if (requirement === "present" && evidence === "present") return { ok: true };
+  if (requirement === "not-absent" && evidence !== "absent") return { ok: true };
+
+  return blocked(
+    "implementation-evidence-missing",
+    `Closeout proof blocked for ${milestoneId}: implementation evidence is ${evidence}.`,
+  );
+}
+
+export function proveMilestoneCloseout(
+  milestoneId: string,
+  options: CloseoutProofOptions = {},
+): CloseoutProofResult {
+  const consistency = checkCloseoutConsistencyGate(milestoneId, {
+    refreshFromDisk: options.refreshFromDisk,
+    allowOpenMilestone: options.allowOpenMilestone,
+    artifactBasePath: options.summaryArtifactBasePath,
+  });
+  if (!consistency.ok) return fromConsistencyResult(consistency);
+
+  if (options.summaryArtifactBasePath) {
+    const summary = checkSummaryArtifact(milestoneId, options.summaryArtifactBasePath);
+    if (!summary.ok) return summary;
+  }
+
+  if (options.implementationEvidence) {
+    const implementation = checkImplementationEvidence(
+      milestoneId,
+      options.implementationEvidence.basePath,
+      options.implementationEvidence.requirement,
+    );
+    if (!implementation.ok) return implementation;
+  }
+
+  return { ok: true };
+}
+
+export function formatCloseoutProofBlock(result: CloseoutProofResult): string {
+  if (result.ok) return "";
+  if (result.reason.startsWith("summary-") || result.reason.startsWith("implementation-")) {
+    return `${result.message} Recovery reason: ${result.recoveryReason}. Resolve the closeout evidence and run /gsd auto to retry.`;
+  }
+  return `${result.message} Recovery reason: ${result.recoveryReason}. Resolve the canonical DB state and run /gsd auto to retry.`;
+}

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

@@ -5,18 +5,28 @@
 // - postUnit: git commit, artifact verify, DB settle, then GitHub finalize
 // - recovery: DB repair from artifacts, then GitHub finalize
 
+import { existsSync } from "node:fs";
+
 import { loadFile } from "./files.js";
-import { parseRoadmap } from "./parsers-legacy.js";
 import { resolveMilestoneFile } from "./paths.js";
-import { getMilestone, getMilestoneSlices, isDbAvailable } from "./gsd-db.js";
+import {
+  getMilestone,
+  getClosedSliceIds,
+  getLatestAssessmentByScope,
+  getMilestoneSlices,
+  isDbAvailable,
+} from "./gsd-db.js";
 import { isClosedStatus } from "./status-guards.js";
-import { verifyExpectedArtifact } from "./auto-recovery.js";
+import { resolveExpectedArtifactPath } from "./auto-artifact-paths.js";
+import { handleCompleteMilestone } from "./tools/complete-milestone.js";
 import { runSafely } from "./auto-utils.js";
 import { extractVerdict, isAcceptableUatVerdict } from "./verdict-parser.js";
+import { uatSignoffBlockerGuidance } from "./guidance.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,
@@ -28,6 +38,76 @@ import {
 const COMPLETE_MILESTONE_DB_SETTLE_MS = 1500;
 const COMPLETE_MILESTONE_DB_SETTLE_POLL_MS = 100;
 
+/**
+ * True when a milestone is terminal for git cleanup (orphaned worktrees, stale branches).
+ * DB-authoritative (ADR-017): closed status, or validation-pass with all slices closed.
+ * When the DB is unavailable we cannot make this decision and conservatively
+ * return false so callers leave the worktree/branch alone instead of cleaning
+ * up based on parsed projections.
+ */
+export async function isCompletedMilestoneTerminal(
+  _basePath: string,
+  milestoneId: string,
+): Promise<boolean> {
+  if (!isDbAvailable()) return false;
+
+  const milestone = getMilestone(milestoneId);
+  if (!milestone) return false;
+
+  if (isClosedStatus(milestone.status)) {
+    return true;
+  }
+
+  const validation = getLatestAssessmentByScope(milestoneId, "milestone-validation");
+  if (validation?.status !== "pass") {
+    return false;
+  }
+
+  const slices = getMilestoneSlices(milestoneId);
+  if (slices.length === 0) return false;
+  return slices.every((slice) => isClosedStatus(slice.status));
+}
+
+/** Write a missing milestone SUMMARY projection when canonical DB closeout already settled. */
+export async function repairMissingMilestoneSummaryProjection(
+  basePath: string,
+  milestoneId: string,
+): Promise<{ ok: true } | { ok: false; error: string }> {
+  const milestone = getMilestone(milestoneId);
+  if (!milestone) {
+    return { ok: false, error: `milestone not found: ${milestoneId}` };
+  }
+
+  const artifactBasePath = resolveCanonicalMilestoneRoot(basePath, milestoneId);
+  const summaryPath = resolveExpectedArtifactPath("complete-milestone", milestoneId, artifactBasePath);
+  if (summaryPath && existsSync(summaryPath)) {
+    return { ok: true };
+  }
+
+  const result = await handleCompleteMilestone(
+    {
+      milestoneId,
+      title: milestone.title,
+      oneLiner: "Canonical closeout completed; summary projection repaired automatically.",
+      narrative:
+        "The workflow database recorded this milestone as complete, but the milestone SUMMARY artifact was missing on disk. " +
+        "Dispatch policy repaired the projection so closeout proof and cleanup can proceed.",
+      verificationPassed: true,
+      triggerReason: "closeout-projection-repair",
+    },
+    basePath,
+  );
+
+  if ("error" in result) {
+    return { ok: false, error: result.error };
+  }
+  const writtenSummaryPath = result.summaryPath;
+  if (result.stale || !writtenSummaryPath || !existsSync(writtenSummaryPath)) {
+    return { ok: false, error: "milestone SUMMARY projection write failed" };
+  }
+  return { ok: true };
+}
+
 /**
  * True when the milestone is closed in the DB and the completion summary artifact exists.
  * Polls briefly so post-unit verification can observe the tool's DB write.
@@ -38,8 +118,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;
         }
       }
@@ -70,7 +158,22 @@ export async function evaluateCompleteMilestoneDispatch(
   if (isDbAvailable()) {
     const milestone = getMilestone(mid);
     if (milestone && isClosedStatus(milestone.status)) {
-      return { action: "skip" };
+      const artifactBasePath = resolveCanonicalMilestoneRoot(basePath, mid);
+      const summaryPath = resolveExpectedArtifactPath("complete-milestone", mid, artifactBasePath);
+      const summaryMissing = !summaryPath || !existsSync(summaryPath);
+      if (summaryMissing) {
+        const repair = await repairMissingMilestoneSummaryProjection(basePath, mid);
+        if (!repair.ok) {
+          logWarning(
+            "dispatch",
+            `Milestone ${mid} is closed in DB but SUMMARY repair failed: ${repair.error}. Dispatching complete-milestone to retry.`,
+          );
+        } else {
+          return { action: "skip" };
+        }
+      } else {
+        return { action: "skip" };
+      }
     }
   }
 
@@ -78,31 +181,21 @@ export async function evaluateCompleteMilestoneDispatch(
   if (closeoutGitStop) return closeoutGitStop;
 
   if (prefs?.uat_dispatch) {
-    let closedSliceIds: string[];
-    if (isDbAvailable()) {
-      closedSliceIds = getMilestoneSlices(mid)
-        .filter((slice) => isClosedStatus(slice.status))
-        .map((slice) => slice.id);
-    } else {
-      const roadmapFile = resolveMilestoneFile(basePath, mid, "ROADMAP");
-      const roadmapContent = roadmapFile ? await loadFile(roadmapFile) : null;
-      if (!roadmapContent) {
-        return {
-          action: "stop",
-          reason: `Cannot complete milestone ${mid}: unable to verify UAT verdicts because ROADMAP is unavailable while DB is not accessible.`,
-          level: "warning",
-        };
-      }
-      const roadmap = parseRoadmap(roadmapContent);
-      closedSliceIds = roadmap.slices.filter((slice) => slice.done).map((slice) => slice.id);
+    // DB-authoritative (ADR-017): UAT sign-off gating never parses the
+    // ROADMAP projection. Without a DB we cannot verify — stop conservatively.
+    if (!isDbAvailable()) {
+      return {
+        action: "stop",
+        reason: `Cannot complete milestone ${mid}: unable to verify UAT verdicts because the workflow DB is not accessible.`,
+        level: "warning",
+      };
     }
-
-    for (const sliceId of closedSliceIds) {
+    for (const sliceId of getClosedSliceIds(mid)) {
       const result = await readUatGateVerdict(basePath, mid, sliceId);
       if (!result) {
         return {
           action: "stop",
-          reason: `Cannot complete milestone ${mid}: missing UAT PASS verdict for ${sliceId}. Manual UAT sign-off (PASS) is required before milestone closure.`,
+          reason: uatSignoffBlockerGuidance(mid, sliceId),
           level: "warning",
         };
       }
@@ -110,7 +203,7 @@ export async function evaluateCompleteMilestoneDispatch(
       if (!isAcceptableUatVerdict(verdict, uatType)) {
         return {
           action: "stop",
-          reason: `Cannot complete milestone ${mid}: UAT verdict for ${sliceId} is "${verdict}". Manual UAT sign-off (PASS) is required before milestone closure.`,
+          reason: uatSignoffBlockerGuidance(mid, sliceId, verdict),
           level: "warning",
         };
       }

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 { flushWorkflowProjections } from "./projection-flush.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 flushWorkflowProjections(basePath, { milestoneId: 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,
+  };
+}