@opengsd/gsd-pi 1.2.0 → 1.3.0-dev.eed73bea

package/dist/resources/extensions/gsd/migrate/planning-writer.js

@@ -0,0 +1,203 @@
+// Project/App: gsd-pi
+// File Purpose: DB → .planning/ projection. Parallel to writer.ts (which
+// emits .gsd/). Produces the .planning/ markdown shape that gsd-core reads.
+//
+// Layout policy (spec §4.4): emits the layout recorded in the compat marker.
+// v1 supports flat-phases; multi-milestone and legacy-milestone-dir are stubbed
+// with a clear error until fixtures exist to validate them.
+import { mkdirSync } from "node:fs";
+import { join, relative } from "node:path";
+import { getAllMilestones, getMilestoneSlices, getSliceTasks } from "../gsd-db.js";
+import { saveFile } from "../files.js";
+import { applyPlanningProjectionWrites, } from "../compat/planning-compat.js";
+function planningRoot(basePath) {
+    return join(basePath, ".planning");
+}
+function slugify(title, fallback) {
+    const slug = title
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 40);
+    return slug || fallback;
+}
+function pad(n, width = 2) {
+    return String(n).padStart(width, "0");
+}
+/**
+ * Format a roadmap for the flat-phases layout. Mirrors the checkbox line
+ * format that parsers.ts parsePhaseEntry recognizes: `- [x] NN — Title`.
+ */
+function formatPlanningRoadmapFlat(entries) {
+    const lines = ["# Roadmap", "", "## Phases", ""];
+    for (const e of entries) {
+        const box = e.done ? "[x]" : "[ ]";
+        lines.push(`- ${box} ${pad(e.number)} — ${e.title}`);
+    }
+    lines.push("");
+    return lines.join("\n");
+}
+/**
+ * Format STATE.md in gsd-core's phase-progress schema. gsd-pi is authoritative
+ * for status; this is a one-way DB→projection (edits to STATE.md are not
+ * re-imported — see spec §7).
+ */
+function formatPlanningState(activeMilestone, totalPhases, completedPhases) {
+    const pct = totalPhases === 0 ? 0 : Math.round((completedPhases / totalPhases) * 100);
+    const ts = new Date().toISOString();
+    return [
+        "---",
+        "gsd_state_version: 1.0",
+        `milestone: ${activeMilestone}`,
+        'milestone_name: "milestone"',
+        "status: active",
+        `stopped_at: Phase 01 — in progress`,
+        `last_updated: "${ts}"`,
+        `last_activity: ${ts.slice(0, 10)}`,
+        "progress:",
+        `  total_phases: ${totalPhases}`,
+        `  completed_phases: ${completedPhases}`,
+        `  total_plans: ${totalPhases}`,
+        `  completed_plans: ${completedPhases}`,
+        `  percent: ${pct}`,
+        "---",
+        "",
+        "# Project State",
+        "",
+        "Current Phase: **01**",
+        "Status: **active**",
+        "",
+    ].join("\n");
+}
+function formatPlanningProject(title) {
+    return `# ${title}\n`;
+}
+/**
+ * Format a phase plan file with the XML-tagged structure parsers.ts
+ * parseOldPlan recognizes: <objective>, <tasks>, <verification>.
+ */
+function formatPlanningPlan(phaseNum, planNum, title, tasks) {
+    const lines = [];
+    lines.push(`# ${pad(phaseNum)}-${pad(planNum)}: ${title}`, "");
+    lines.push("<objective>");
+    lines.push(`${title}.`);
+    lines.push("</objective>");
+    lines.push("");
+    lines.push("<tasks>");
+    for (const t of tasks) {
+        const est = t.estimate ? ` _(${t.estimate})_` : "";
+        lines.push(`- [ ] **${t.id}**: ${t.title}${est}`);
+    }
+    lines.push("</tasks>");
+    lines.push("");
+    lines.push("<verification>");
+    lines.push("All tasks complete and tests pass.");
+    lines.push("</verification>");
+    lines.push("");
+    return lines.join("\n");
+}
+/**
+ * Project DB state to .planning/ in the recorded layout.
+ * Reads DB directly (canonical source). Writes via saveFile (atomic).
+ *
+ * v1: flat-phases only. Each milestone's slices become sequentially-numbered
+ * phase dirs; each task within a slice becomes a plan file (NN-MM-PLAN.md).
+ */
+export async function writePlanningDirectory(basePath, layout) {
+    if (layout !== "flat-phases") {
+        // v1: flat-phases only. multi-milestone and legacy-milestone-dir need
+        // fixtures to validate the reverse-mapping (transformer.ts is non-injective
+        // — three layouts collapse to one .gsd/ shape); stub until then.
+        throw new Error(`writePlanningDirectory: layout "${layout}" not yet supported (v1 supports flat-phases only)`);
+    }
+    const root = planningRoot(basePath);
+    mkdirSync(root, { recursive: true });
+    const paths = [];
+    const projectionWrites = [];
+    const toPlanningRel = (absPath) => relative(root, absPath).replace(/\\/g, "/");
+    const milestones = getAllMilestones();
+    if (milestones.length === 0) {
+        return { paths, layout };
+    }
+    // Flat-phases: each slice becomes one phase. Tasks within become plan files.
+    let phaseNum = 0;
+    const roadmapEntries = [];
+    for (const milestone of milestones) {
+        const slices = getMilestoneSlices(milestone.id);
+        for (const slice of slices) {
+            phaseNum++;
+            const phaseSlug = slugify(slice.title || slice.id, slice.id.toLowerCase());
+            const phaseDirName = `${pad(phaseNum)}-${phaseSlug}`;
+            const phaseDir = join(root, "phases", phaseDirName);
+            mkdirSync(phaseDir, { recursive: true });
+            const tasks = getSliceTasks(milestone.id, slice.id);
+            const isDone = tasks.length > 0 && tasks.every((t) => t.status === "complete");
+            roadmapEntries.push({
+                number: phaseNum,
+                title: slice.title || slice.id,
+                done: isDone,
+            });
+            if (tasks.length === 0) {
+                // Empty phase — write a single placeholder plan so the dir isn't empty.
+                const planPath = join(phaseDir, `${pad(phaseNum)}-01-PLAN.md`);
+                await saveFile(planPath, formatPlanningPlan(phaseNum, 1, slice.title || slice.id, []));
+                paths.push(planPath);
+                projectionWrites.push({
+                    relPath: toPlanningRel(planPath),
+                    entities: [`${milestone.id}/${slice.id}`],
+                });
+            }
+            else {
+                for (let ti = 0; ti < tasks.length; ti++) {
+                    const task = tasks[ti];
+                    const planNum = ti + 1;
+                    const planPath = join(phaseDir, `${pad(phaseNum)}-${pad(planNum)}-PLAN.md`);
+                    await saveFile(planPath, formatPlanningPlan(phaseNum, planNum, task.title || task.id, [
+                        {
+                            id: task.id,
+                            title: task.title || task.id,
+                            estimate: task.estimate || undefined,
+                        },
+                    ]));
+                    paths.push(planPath);
+                    projectionWrites.push({
+                        relPath: toPlanningRel(planPath),
+                        entities: [`${milestone.id}/${slice.id}/${task.id}`],
+                    });
+                }
+            }
+        }
+    }
+    // If no slices produced any phases, write a single empty phase so ROADMAP.md
+    // isn't blank and the layout is still discoverable.
+    if (roadmapEntries.length === 0) {
+        const phaseDirName = `${pad(1)}-milestone`;
+        const phaseDir = join(root, "phases", phaseDirName);
+        mkdirSync(phaseDir, { recursive: true });
+        const planPath = join(phaseDir, `${pad(1)}-01-PLAN.md`);
+        await saveFile(planPath, formatPlanningPlan(1, 1, milestones[0].title || milestones[0].id, []));
+        paths.push(planPath);
+        projectionWrites.push({
+            relPath: toPlanningRel(planPath),
+            entities: [milestones[0].id],
+        });
+        roadmapEntries.push({ number: 1, title: milestones[0].title || milestones[0].id, done: false });
+    }
+    // Root files
+    const milestoneEntities = milestones.map((m) => m.id);
+    const roadmapPath = join(root, "ROADMAP.md");
+    await saveFile(roadmapPath, formatPlanningRoadmapFlat(roadmapEntries));
+    paths.push(roadmapPath);
+    projectionWrites.push({ relPath: toPlanningRel(roadmapPath), entities: milestoneEntities });
+    const completedPhases = roadmapEntries.filter((e) => e.done).length;
+    const statePath = join(root, "STATE.md");
+    await saveFile(statePath, formatPlanningState(milestones[0].id, roadmapEntries.length, completedPhases));
+    paths.push(statePath);
+    projectionWrites.push({ relPath: toPlanningRel(statePath), entities: [milestones[0].id] });
+    const projectPath = join(root, "PROJECT.md");
+    await saveFile(projectPath, formatPlanningProject(milestones[0].title || milestones[0].id));
+    paths.push(projectPath);
+    projectionWrites.push({ relPath: toPlanningRel(projectPath), entities: [milestones[0].id] });
+    applyPlanningProjectionWrites(basePath, projectionWrites);
+    return { paths, layout };
+}

package/dist/resources/extensions/gsd/migrate/safety.js

@@ -5,9 +5,10 @@ import { basename, dirname, join, resolve } from "node:path";
 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";
 export class MigrationBlockedError extends Error {
     constructor(message) {
         super(message);
@@ -78,16 +79,26 @@ export function assertMigrationHasSlices(preview) {
     throw new MigrationBlockedError("Migration blocked - the legacy project would produce zero slices. Add a ROADMAP.md or phases/ content before migrating.");
 }
 function hasWorktreeState(targetRoot) {
-    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) {
     const targetGsdPath = gsdRoot(targetRoot);
@@ -110,6 +121,6 @@ export async function assertMigrationTargetAvailable(targetRoot) {
         }
     }
     finally {
-        closeDatabase();
+        closeWorkflowDatabase();
     }
 }

package/dist/resources/extensions/gsd/migrate-external.js

@@ -6,12 +6,13 @@
  * symlink replaces the original directory so all paths remain valid.
  */
 import { execFileSync } from "node:child_process";
-import { existsSync, lstatSync, mkdirSync, readdirSync, realpathSync, renameSync, cpSync, rmSync, symlinkSync } from "node:fs";
+import { existsSync, lstatSync, mkdirSync, readdirSync, realpathSync, renameSync, cpSync, rmSync, statSync, symlinkSync } from "node:fs";
 import { join } from "node:path";
 import { externalGsdRoot, isInsideWorktree } from "./repo-identity.js";
 import { getErrorMessage } from "./error-utils.js";
 import { hasGitTrackedGsdFiles } from "./gitignore.js";
 import { GIT_NO_PROMPT_ENV } from "./git-constants.js";
+import { gsdRoot, milestonesDir, resolveGsdRootFile } from "./paths.js";
 /**
  * Migrate a legacy in-project `.gsd/` directory to external storage.
  *
@@ -159,6 +160,9 @@ export function migrateToExternalState(basePath) {
             catch { /* best-effort restore */ }
             return { migrated: false, error: `Migration verification failed: ${getErrorMessage(verifyErr)}` };
         }
+        // Remove .gsd.migrating once the junction is verified. The git-index cleanup
+        // below is best-effort and does not need the staging copy to survive.
+        rmSync(migratingPath, { recursive: true, force: true });
         // Clean the git index — any .gsd/* files tracked before migration now
         // sit behind the symlink and git can't follow it, causing them to show
         // as deleted. Remove them from the index so the working tree stays clean.
@@ -174,8 +178,6 @@ export function migrateToExternalState(basePath) {
         catch {
             // Non-fatal — git may be unavailable or nothing was tracked
         }
-        // Remove .gsd.migrating only after symlink is verified and index is clean
-        rmSync(migratingPath, { recursive: true, force: true });
         return { migrated: true };
     }
     catch (err) {
@@ -194,17 +196,60 @@ export function migrateToExternalState(basePath) {
         };
     }
 }
+export function isCurrentGsdStateIntactForMigratingCleanup(basePath) {
+    try {
+        const stateFile = resolveGsdRootFile(basePath, "STATE");
+        const milestonesPath = milestonesDir(basePath);
+        const dbPath = join(gsdRoot(basePath), "gsd.db");
+        const hasDbFile = existsSync(dbPath);
+        const hasNonEmptyDb = hasDbFile && statSync(dbPath).size > 0;
+        return existsSync(stateFile) && existsSync(milestonesPath) && hasNonEmptyDb;
+    }
+    catch {
+        return false;
+    }
+}
+function normalizeResolvedPath(p) {
+    const normalized = p.replaceAll("\\", "/").replace(/\/+$/, "");
+    return process.platform === "win32" ? normalized.toLowerCase() : normalized;
+}
+function isLocalGsdExternalStateJunction(basePath, localGsd) {
+    try {
+        const stat = lstatSync(localGsd);
+        if (!stat.isSymbolicLink())
+            return false;
+        const resolved = normalizeResolvedPath(realpathSync(localGsd));
+        const resolvedExternal = normalizeResolvedPath(realpathSync(externalGsdRoot(basePath)));
+        return resolved === resolvedExternal;
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * Recover from a failed migration (`.gsd.migrating` exists).
- * Moves `.gsd.migrating` back to `.gsd` if `.gsd` doesn't exist.
+ * Moves `.gsd.migrating` back to `.gsd` if `.gsd` doesn't exist, or removes an
+ * orphaned staging directory when `.gsd` is already a verified external state
+ * junction with intact current state.
  */
 export function recoverFailedMigration(basePath) {
     const localGsd = join(basePath, ".gsd");
     const migratingPath = join(basePath, ".gsd.migrating");
     if (!existsSync(migratingPath))
         return false;
-    if (existsSync(localGsd))
-        return false; // both exist -- ambiguous, don't touch
+    if (existsSync(localGsd)) {
+        if (!isLocalGsdExternalStateJunction(basePath, localGsd))
+            return false;
+        if (!isCurrentGsdStateIntactForMigratingCleanup(basePath))
+            return false;
+        try {
+            rmSync(migratingPath, { recursive: true, force: true });
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
     try {
         renameSync(migratingPath, localGsd);
         return true;

package/dist/resources/extensions/gsd/migration-auto-check.js

@@ -1,13 +1,21 @@
-import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { ensureDbOpen } from "./bootstrap/dynamic-tools.js";
-import { getAllMilestones, getMilestoneSlices, getSliceTasks, isDbAvailable, refreshOpenDatabaseFromDisk, } from "./gsd-db.js";
+import { getAllMilestones, getMilestoneSlices, getSliceTasks, isDbAvailable, } from "./gsd-db.js";
+import { refreshWorkflowDatabaseFromDisk } from "./db-workspace.js";
 import { parsePlan, parseRoadmap } from "./parsers-legacy.js";
-import { milestonesDir, resolveMilestoneFile, resolveSliceFile, } from "./paths.js";
+import { findMilestoneIds } from "./milestone-ids.js";
+import { resolveMilestoneFile, resolveSliceFile, } from "./paths.js";
 function zeroCounts() {
     return { milestones: 0, slices: 0, tasks: 0 };
 }
 function emptyScan() {
-    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, b) {
     return a.milestones === b.milestones && a.slices === b.slices && a.tasks === b.tasks;
@@ -48,24 +56,16 @@ export function recoverWouldDeleteDbRows(basePath) {
     return scanHasExtraIdentities(scanDbHierarchy(), scanMarkdownHierarchy(basePath));
 }
 export function scanMarkdownHierarchy(basePath) {
-    const root = milestonesDir(basePath);
-    if (!existsSync(root))
-        return emptyScan();
     const scan = emptyScan();
-    for (const entry of readdirSync(root, { withFileTypes: true })) {
-        if (!entry.isDirectory() || !/^M\d+/.test(entry.name))
-            continue;
-        // Use the CANONICAL milestone id (e.g. "M001" or "M001-a1b2c3"), matching
-        // scanDbHierarchy's milestone.id — not the raw directory name, which may
-        // carry a legacy descriptor (e.g. "M001-some-descriptor"). The canonical id
-        // both keys the identity sets AND resolves files correctly: resolveFile's
-        // prefix/legacy-pattern matching handles the descriptor dir either way.
-        const milestoneId = entry.name.match(/^(M\d+(?:-[a-z0-9]{6})?)/)?.[1] ?? entry.name;
+    // findMilestoneIds handles both flat-phase (NN-slug) and legacy (M###) dirs.
+    for (const milestoneId of findMilestoneIds(basePath)) {
         scan.counts.milestones++;
         scan.milestones.add(milestoneId);
         const roadmapPath = resolveMilestoneFile(basePath, milestoneId, "ROADMAP");
-        if (!roadmapPath || !existsSync(roadmapPath))
+        if (!roadmapPath || !existsSync(roadmapPath)) {
+            scan.milestonesWithoutRoadmap.add(milestoneId);
             continue;
+        }
         const roadmap = parseRoadmap(readFileSync(roadmapPath, "utf-8"));
         scan.counts.slices += roadmap.slices.length;
         for (const slice of roadmap.slices) {
@@ -111,7 +111,6 @@ export function countDbHierarchy() {
 }
 export async function checkMarkdownHierarchyAgainstDb(basePath) {
     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
     // lost, which is itself recoverable drift. The previous early return here
@@ -124,9 +123,23 @@ export async function checkMarkdownHierarchyAgainstDb(basePath) {
     // 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());
     // Genuinely empty project: nothing on disk, nothing in the DB.

package/dist/resources/extensions/gsd/milestone-actions.js

@@ -12,7 +12,7 @@
  */
 import { existsSync, rmSync, writeFileSync, readFileSync, unlinkSync } from "node:fs";
 import { join } from "node:path";
-import { resolveMilestonePath, resolveMilestoneFile, buildMilestoneFileName, } from "./paths.js";
+import { resolveMilestonePath, resolveMilestoneFile, relMilestoneFile, } from "./paths.js";
 import { invalidateAllCaches } from "./cache.js";
 import { loadQueueOrder, saveQueueOrder } from "./queue-order.js";
 import { deleteMilestone, getMilestone, isDbAvailable, updateMilestoneStatus } from "./gsd-db.js";
@@ -52,7 +52,8 @@ export function parkMilestone(basePath, milestoneId, reason) {
         if (summaryFile)
             return false;
     }
-    const parkedPath = join(mDir, buildMilestoneFileName(milestoneId, "PARKED"));
+    // Use relMilestoneFile for layout-aware path (legacy: M001-PARKED.md, flat-phase: 01-PARKED.md)
+    const parkedPath = join(basePath, relMilestoneFile(basePath, milestoneId, "PARKED"));
     if (existsSync(parkedPath))
         return false; // already parked
     const content = [
@@ -89,7 +90,8 @@ export function unparkMilestone(basePath, milestoneId) {
     const mDir = resolveMilestonePath(basePath, milestoneId);
     if (!mDir || !existsSync(mDir))
         return false;
-    const parkedPath = join(mDir, buildMilestoneFileName(milestoneId, "PARKED"));
+    // Use relMilestoneFile for layout-aware path (legacy: M001-PARKED.md, flat-phase: 01-PARKED.md)
+    const parkedPath = join(basePath, relMilestoneFile(basePath, milestoneId, "PARKED"));
     const hadParkedFile = existsSync(parkedPath);
     const dbThinksParked = isDbAvailable() && getMilestone(milestoneId)?.status === "parked";
     // Recover the reverse desync too: DB can still say "parked" even when the

package/dist/resources/extensions/gsd/milestone-closeout-proof.js

@@ -0,0 +1,72 @@
+// 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, } 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";
+function blocked(reason, message) {
+    return {
+        ok: false,
+        reason,
+        recoveryReason: CLOSEOUT_CONSISTENCY_BLOCKED_REASON,
+        message,
+    };
+}
+function fromConsistencyResult(result) {
+    if (result.ok)
+        return result;
+    return {
+        ok: false,
+        reason: result.reason,
+        recoveryReason: result.recoveryReason,
+        message: result.message,
+    };
+}
+function checkSummaryArtifact(milestoneId, basePath) {
+    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, basePath, requirement) {
+    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, options = {}) {
+    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) {
+    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.`;
+}