@opengsd/gsd-pi 1.2.0-dev.844675c9 → 1.2.0-dev.8e6112e9

package/src/resources/extensions/gsd/migrate/safety.ts

@@ -7,9 +7,10 @@ import { homedir } from "node:os";
 
 import { ensureDbOpen } from "../bootstrap/dynamic-tools.js";
 import { readCrashLock, isLockProcessAlive } from "../crash-recovery.js";
-import { closeDatabase } from "../gsd-db.js";
+import { closeWorkflowDatabase } from "../db-workspace.js";
 import { readPausedSessionMetadata } from "../interrupted-session.js";
 import { gsdRoot } from "../paths.js";
+import { canonicalWorktreesDir } from "../worktree-placement.js";
 import type { MigrationPreview } from "./writer.js";
 
 export interface MigrationPaths {
@@ -106,14 +107,24 @@ export function assertMigrationHasSlices(preview: MigrationPreview): void {
 }
 
 function hasWorktreeState(targetRoot: string): boolean {
-  const worktreesDir = join(gsdRoot(targetRoot), "worktrees");
-  if (!existsSync(worktreesDir)) return false;
-  try {
-    return readdirSync(worktreesDir, { withFileTypes: true })
-      .some((entry) => entry.isDirectory() || entry.isFile());
-  } catch {
-    return true;
+  // Legacy container is probed via gsdRoot() (symlink-resolved) on purpose —
+  // migration targets may have .gsd in the external-state layout.
+  const containers = [
+    canonicalWorktreesDir(targetRoot),
+    join(gsdRoot(targetRoot), "worktrees"),
+  ];
+  for (const worktreesDir of containers) {
+    if (!existsSync(worktreesDir)) continue;
+    try {
+      if (readdirSync(worktreesDir, { withFileTypes: true })
+        .some((entry) => entry.isDirectory() || entry.isFile())) {
+        return true;
+      }
+    } catch {
+      return true;
+    }
   }
+  return false;
 }
 
 export async function assertMigrationTargetAvailable(targetRoot: string): Promise<void> {
@@ -144,6 +155,6 @@ export async function assertMigrationTargetAvailable(targetRoot: string): Promis
       );
     }
   } finally {
-    closeDatabase();
+    closeWorkflowDatabase();
   }
 }

package/src/resources/extensions/gsd/migration-auto-check.ts

@@ -6,8 +6,8 @@ import {
   getMilestoneSlices,
   getSliceTasks,
   isDbAvailable,
-  refreshOpenDatabaseFromDisk,
 } from "./gsd-db.js";
+import { refreshWorkflowDatabaseFromDisk } from "./db-workspace.js";
 import { parsePlan, parseRoadmap } from "./parsers-legacy.js";
 import {
   milestonesDir,
@@ -39,6 +39,9 @@ interface HierarchyScan {
   milestones: Set<string>;
   slices: Set<string>;
   tasks: Set<string>;
+  // Markdown milestones whose dir has no ROADMAP (CONTEXT/CONTEXT-DRAFT only
+  // or empty). Always empty for DB scans.
+  milestonesWithoutRoadmap: Set<string>;
 }
 
 function zeroCounts(): HierarchyCounts {
@@ -46,7 +49,13 @@ function zeroCounts(): HierarchyCounts {
 }
 
 function emptyScan(): HierarchyScan {
-  return { counts: zeroCounts(), milestones: new Set(), slices: new Set(), tasks: new Set() };
+  return {
+    counts: zeroCounts(),
+    milestones: new Set(),
+    slices: new Set(),
+    tasks: new Set(),
+    milestonesWithoutRoadmap: new Set(),
+  };
 }
 
 function sameCounts(a: HierarchyCounts, b: HierarchyCounts): boolean {
@@ -109,7 +118,10 @@ export function scanMarkdownHierarchy(basePath: string): HierarchyScan {
     scan.milestones.add(milestoneId);
 
     const roadmapPath = resolveMilestoneFile(basePath, milestoneId, "ROADMAP");
-    if (!roadmapPath || !existsSync(roadmapPath)) continue;
+    if (!roadmapPath || !existsSync(roadmapPath)) {
+      scan.milestonesWithoutRoadmap.add(milestoneId);
+      continue;
+    }
 
     const roadmap = parseRoadmap(readFileSync(roadmapPath, "utf-8"));
     scan.counts.slices += roadmap.slices.length;
@@ -164,7 +176,6 @@ export async function checkMarkdownHierarchyAgainstDb(
   basePath: string,
 ): Promise<MigrationAutoCheckResult> {
   const markdownScan = scanMarkdownHierarchy(basePath);
-  const markdown = markdownScan.counts;
 
   // Always open the DB before deciding. An empty markdown tree does NOT imply
   // an empty project — the DB may hold authoritative rows whose markdown was
@@ -179,11 +190,25 @@ export async function checkMarkdownHierarchyAgainstDb(
   // The markdown projections may have just been written by a workflow/MCP
   // server in another process. Reopen before comparing so startup does not
   // warn from a stale long-lived SQLite handle.
-  refreshOpenDatabaseFromDisk();
+  refreshWorkflowDatabaseFromDisk();
 
   const dbScan = scanDbHierarchy();
   const beforeDb = dbScan.counts;
 
+  // Discussion-phase scratch: a milestone dir with no ROADMAP and no DB row is
+  // a pre-registration discussion artifact (CONTEXT/CONTEXT-DRAFT only — the
+  // queued DB row is inserted only at discussion handoff). Treating it as
+  // drift would warn on every live discussion and recommend
+  // `/gsd recover --confirm`, an import that materializes abandoned-discussion
+  // dirs as ghost active milestones. Exclude such dirs from this comparison
+  // only; recover preflights use the raw scans and still see them.
+  for (const id of markdownScan.milestonesWithoutRoadmap) {
+    if (dbScan.milestones.has(id)) continue;
+    markdownScan.milestones.delete(id);
+    markdownScan.counts.milestones--;
+  }
+  const markdown = markdownScan.counts;
+
   const markdownEmpty = sameCounts(markdown, zeroCounts());
   const dbEmpty = sameCounts(beforeDb, zeroCounts());
 

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 },
+    );
+  };
+}