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

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

@@ -1,13 +1,20 @@
 import { existsSync, readdirSync, 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";
 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;
@@ -64,8 +71,10 @@ export function scanMarkdownHierarchy(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 +120,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 +132,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-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.`;
+}

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

@@ -4,21 +4,78 @@
 // - preflight: dispatch git clean before complete-milestone agent (auto-dispatch)
 // - 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 { commitPendingMilestoneCloseoutChanges, findMissingSummaries, isVerificationNotApplicable, readUatGateVerdict, } from "./auto-dispatch.js";
 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, milestoneId) {
+    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, milestoneId) {
+    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.
@@ -29,8 +86,16 @@ export async function isMilestoneCloseoutSettled(mid, basePath) {
         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;
                 }
             }
@@ -57,38 +122,42 @@ export async function evaluateCompleteMilestoneDispatch(ctx) {
     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" };
+            }
         }
     }
     const closeoutGitStop = commitPendingMilestoneCloseoutChanges(basePath, mid);
     if (closeoutGitStop)
         return closeoutGitStop;
     if (prefs?.uat_dispatch) {
-        let closedSliceIds;
-        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",
                 };
             }
@@ -96,7 +165,7 @@ export async function evaluateCompleteMilestoneDispatch(ctx) {
             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/dist/resources/extensions/gsd/milestone-merge-transaction.js

@@ -0,0 +1,10 @@
+// Project/App: gsd-pi
+// File Purpose: Process-level transaction wrapper for milestone merge closeout.
+export function runMilestoneMergeTransaction(deps, input) {
+    return deps.mergeMilestoneToMain(input.basePath, input.milestoneId, input.roadmapContent);
+}
+export function createMilestoneMergeTransaction(mergeMilestoneToMain) {
+    return function mergeMilestoneTransaction(basePath, milestoneId, roadmapContent) {
+        return runMilestoneMergeTransaction({ mergeMilestoneToMain }, { basePath, milestoneId, roadmapContent });
+    };
+}

package/dist/resources/extensions/gsd/milestone-planning-persistence.js

@@ -0,0 +1,156 @@
+// 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";
+function validatePlanPromotion(params) {
+    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) {
+    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, params) {
+    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.message}`);
+        invalidateStateCache();
+        return { error: `render failed: ${renderErr.message}` };
+    }
+}
+async function runPostPlanHooks(basePath, params) {
+    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.message}`);
+    }
+}
+export async function persistMilestonePlan(params, basePath) {
+    // ── 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 = null;
+    try {
+        transaction(() => {
+            guardError = validatePlanPromotion(params);
+            if (guardError)
+                return;
+            writePlanRows(params);
+        });
+    }
+    catch (err) {
+        return { error: `db write failed: ${err.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/dist/resources/extensions/gsd/milestone-readiness.js

@@ -0,0 +1,77 @@
+// Project/App: gsd-pi
+// File Purpose: Classify milestone readiness from DB status, slices, and artifacts.
+import { readFileSync } from "node:fs";
+import { getMilestone, getMilestoneSlices, isDbAvailable } from "./gsd-db.js";
+import { parseRoadmapSlices } from "./roadmap-slices.js";
+import { logWarning } from "./workflow-logger.js";
+export function classifyMilestoneReadiness(input) {
+    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) {
+    return readiness.kind === "needs-discussion" ||
+        (readiness.kind === "queued-shell" && readiness.hasDraftContext);
+}
+export function describeMilestoneReadinessPhase(phase) {
+    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, roadmapFile) {
+    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.message}`);
+        return 0;
+    }
+}
+export function assessMilestoneHandoffReadiness(input) {
+    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, readiness) {
+    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/dist/resources/extensions/gsd/milestone-reopen-events.js

@@ -1,11 +1,9 @@
-import { join } from "node:path";
-import { gsdRoot } from "./paths.js";
+import { workflowEventArchivePath, workflowEventLogPath } from "./workflow-event-ledger.js";
 import { readEvents } from "./workflow-events.js";
 export function latestExplicitReopenAt(basePath, milestoneId) {
-    const root = gsdRoot(basePath);
     const candidates = [
-        join(root, "event-log.jsonl"),
-        join(root, `event-log-${milestoneId}.jsonl.archived`),
+        workflowEventLogPath(basePath),
+        workflowEventArchivePath(basePath, milestoneId),
     ];
     let latest = null;
     for (const file of candidates) {

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

@@ -0,0 +1,50 @@
+// 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";
+function isActiveUnmergedWorktree(input) {
+    if (!input.milestoneId || input.milestoneMerged)
+        return false;
+    return isInAutoWorktree(input.basePath);
+}
+export function evaluateAllCompleteSettlement(input) {
+    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}\` to finish the system-owned merge.`,
+        nextAction: `Retry \`/gsd dispatch complete-milestone ${milestoneId}\`.`,
+        milestoneId,
+    };
+}