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

package/dist/resources/extensions/gsd/guided-unit-completion.js

@@ -0,0 +1,225 @@
+// Project/App: gsd-pi
+// File Purpose: Recover guided-unit completion signals that did not produce expected tool/file evidence.
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { clearPathCache, relMilestoneFile, resolveMilestoneFile, resolveMilestonePath, } from "./paths.js";
+import { _getPendingAutoStart, deletePendingAutoStart, hasPendingAutoStart, } from "./pending-auto-start.js";
+import { logWarning } from "./workflow-logger.js";
+// #4573: cap for how many times we nudge the LLM after a premature ready
+// phrase before giving up and asking the user to re-run /gsd.
+const MAX_READY_REJECTS = 2;
+// #4573: matches the canonical ready phrase the discuss prompt asks the LLM
+// to emit. Accepts any M-prefixed milestone ID (three digits + optional
+// suffix) with optional trailing punctuation.
+const READY_PHRASE_RE = /\bMilestone\s+M\d{3}[A-Z0-9-]*\s+ready\.?/i;
+const emptyTurnCounterByBase = new Map();
+const MAX_EMPTY_TURN_RETRIES = 2;
+// Phrases that indicate the LLM is about to do something but has not yet.
+// Kept tight to avoid flagging legitimate narration like "I'll wait for your answer."
+//
+// "make" was previously in the verb list but matches conversational meta phrases
+// like "Let me make sure I understand…" which are NOT action announcements —
+// removed to prevent the empty-turn nudge from auto-replying to user questions
+// in discuss flows.
+const COMMIT_INTENT_RE = /\b(?:I['’]ll|I will|Next,? I['’]ll|Now I['’]ll|Let me|I['’]m going to|I am going to)\s+(?:now\s+)?(?:write|create|call|invoke|update|add|run|execute|generate|produce|emit|compose|implement|save|apply|commit)\b/i;
+/**
+ * Extract the concatenated text content from an assistant message, whether it
+ * stores content as a string or as an array of text blocks.
+ */
+function extractAssistantText(msg) {
+    if (!msg)
+        return "";
+    const content = msg.content;
+    if (typeof content === "string")
+        return content;
+    if (!Array.isArray(content))
+        return "";
+    const parts = [];
+    for (const block of content) {
+        if (!block || typeof block !== "object")
+            continue;
+        if (block.type === "text" && typeof block.text === "string")
+            parts.push(block.text);
+    }
+    return parts.join("\n");
+}
+/**
+ * Return true if the assistant message contains any tool-use block.
+ *
+ * The canonical pi-ai `AssistantMessage.content` (see packages/pi-ai/src/types.ts)
+ * uses `type: "toolCall"` and `type: "serverToolUse"` for tool invocations —
+ * every provider (anthropic-direct, claude-code-cli, openai, etc.) normalizes
+ * incoming tool blocks into these two shapes before they reach guided-flow.
+ *
+ * The Anthropic API wire shape `"tool_use"` / `"server_tool_use"` does NOT appear
+ * in the internal AssistantMessage — those literals are only used when sending
+ * messages back out to the Anthropic API. Matching them here was a latent bug:
+ * `hasToolUse` returned `false` for every real tool call, which let the
+ * empty-turn nudge fire and pre-empt MCP tools that block on the user
+ * (e.g. `ask_user_questions`). See investigation in PR for #4658.
+ */
+function hasToolUse(msg) {
+    if (!msg)
+        return false;
+    const content = msg.content;
+    if (!Array.isArray(content))
+        return false;
+    return content.some((b) => b &&
+        typeof b === "object" &&
+        (b.type === "toolCall" || b.type === "serverToolUse"));
+}
+/**
+ * #4573 — Detect and recover from the "ready phrase without files" failure mode.
+ *
+ * When the LLM emits "Milestone {{id}} ready." but has not written the
+ * milestone CONTEXT/ROADMAP artifacts, `checkAutoStartAfterDiscuss()` silently
+ * returns false and the next /gsd invocation loops into the "All milestones
+ * complete" warning.
+ *
+ * This function, called from `handleAgentEnd` after `checkAutoStartAfterDiscuss`
+ * returns false, pattern-matches the ready phrase on the last assistant message.
+ * If it fired AND neither the canonical M###-CONTEXT.md/M###-ROADMAP.md nor
+ * legacy CONTEXT.md/ROADMAP.md files exist, it:
+ *   1. Notifies the user that the signal was rejected.
+ *   2. Injects a system message via `pi.sendMessage(..., {triggerTurn:true})`
+ *      telling the LLM the signal was premature and to emit the writes now.
+ *   3. Caps at `MAX_READY_REJECTS` per-entry; beyond that, gives up and asks
+ *      the user to re-run /gsd.
+ *
+ * Returns true when a nudge (or give-up) was emitted, signaling the caller to
+ * skip `resolveAgentEnd`.
+ */
+export function maybeHandleReadyPhraseWithoutFiles(event, lookupBasePath) {
+    const entry = _getPendingAutoStart(lookupBasePath);
+    if (!entry)
+        return false;
+    const { ctx, pi, basePath, milestoneId } = entry;
+    // Gate: last assistant message must contain the ready phrase
+    const lastMsg = event.messages[event.messages.length - 1];
+    const text = extractAssistantText(lastMsg);
+    if (!READY_PHRASE_RE.test(text))
+        return false;
+    // Bust paths.ts cached dir listings before checking for fresh writes. The
+    // LLM's Write tool calls do not invalidate paths.ts caches, so a stale
+    // listing taken before the milestone dir or its CONTEXT/ROADMAP files
+    // existed would falsely report the artifacts as missing and trigger the
+    // 3-strike "ready without files" abort even though the writes succeeded.
+    clearPathCache();
+    // Gate: artifacts must still be missing — if they exist, the happy path
+    // already fired and we have nothing to do.
+    const contextFile = resolveMilestoneFile(basePath, milestoneId, "CONTEXT");
+    const roadmapFile = resolveMilestoneFile(basePath, milestoneId, "ROADMAP");
+    if (contextFile || roadmapFile)
+        return false;
+    // Diagnostic: when the cached resolver reports both files missing, also probe
+    // the canonical paths with uncached existsSync so we can tell whether the
+    // recovery is firing on real-missing files or a path-resolution miss
+    // (basePath/symlink mismatch, stale cache despite agent-end-recovery flush,
+    // legacy descriptor dir not matching, etc.).
+    try {
+        const mDir = resolveMilestonePath(basePath, milestoneId);
+        const canonicalCtx = mDir ? join(mDir, `${milestoneId}-CONTEXT.md`) : null;
+        const canonicalRoadmap = mDir ? join(mDir, `${milestoneId}-ROADMAP.md`) : null;
+        logWarning("guided", `ready-phrase-reject diagnostic mid=${milestoneId} basePath=${basePath} ` +
+            `mDir=${mDir ?? "null"} ` +
+            `canonical-ctx=${canonicalCtx ?? "null"} ctx-exists=${canonicalCtx ? existsSync(canonicalCtx) : "n/a"} ` +
+            `canonical-roadmap=${canonicalRoadmap ?? "null"} roadmap-exists=${canonicalRoadmap ? existsSync(canonicalRoadmap) : "n/a"}`);
+    }
+    catch (e) {
+        logWarning("guided", `ready-phrase-reject diagnostic failed: ${e.message}`);
+    }
+    entry.readyRejectCount = (entry.readyRejectCount ?? 0) + 1;
+    if (entry.readyRejectCount > MAX_READY_REJECTS) {
+        // Give up: clear state and tell the user to re-run /gsd. Avoids an
+        // infinite nudge loop when the LLM never produces the writes.
+        deletePendingAutoStart(basePath);
+        ctx.ui.notify(`Milestone ${milestoneId}: LLM signaled "ready" ${entry.readyRejectCount} times without writing files. ` +
+            `Stopping auto-nudge. Run /gsd to try again.`, "error");
+        return true;
+    }
+    const contextRel = relMilestoneFile(basePath, milestoneId, "CONTEXT");
+    const roadmapRel = relMilestoneFile(basePath, milestoneId, "ROADMAP");
+    ctx.ui.notify(`Milestone ${milestoneId}: "ready" signal rejected — ${contextRel} and ${roadmapRel} are missing. Asking the LLM to complete the writes.`, "warning");
+    const nudge = `You emitted "Milestone ${milestoneId} ready." but neither ` +
+        `${contextRel} nor ${roadmapRel} exists on disk. ` +
+        `The ready phrase is a POST-WRITE signal and has been rejected. ` +
+        `In this turn: (1) write PROJECT.md, REQUIREMENTS.md, and the milestone ` +
+        `CONTEXT.md, (2) call gsd_plan_milestone, then (3) emit the ready phrase. ` +
+        `Do not describe these steps — execute them as tool calls. ` +
+        `This is retry ${entry.readyRejectCount}/${MAX_READY_REJECTS}; further ` +
+        `premature signals will clear the session.`;
+    try {
+        pi.sendMessage({ customType: "gsd-ready-no-files", content: nudge, display: false }, { triggerTurn: true });
+    }
+    catch (e) {
+        logWarning("guided", `ready-phrase nudge sendMessage failed: ${e.message}`);
+        return false;
+    }
+    return true;
+}
+/**
+ * Reset the empty-turn counter for a basePath after a successful tool-use turn.
+ * Called from handleAgentEnd when the last message contains tool_use blocks.
+ */
+export function resetEmptyTurnCounter(basePath) {
+    if (basePath)
+        emptyTurnCounterByBase.delete(basePath);
+    else
+        emptyTurnCounterByBase.clear();
+}
+export function maybeHandleEmptyIntentTurn(event, isAuto, lookupBasePath) {
+    // Gate: only fire when there is system-driven work in flight. Interactive
+    // /gsd discuss (user-driven) produces legitimate text-only turns.
+    if (!isAuto && !hasPendingAutoStart(lookupBasePath))
+        return false;
+    const lastMsg = event.messages[event.messages.length - 1];
+    if (!lastMsg)
+        return false;
+    if (hasToolUse(lastMsg))
+        return false;
+    const text = extractAssistantText(lastMsg).trim();
+    if (!text)
+        return false;
+    // Skip if the LLM is emitting the ready phrase — that is the ready-no-files
+    // path, handled by maybeHandleReadyPhraseWithoutFiles.
+    if (READY_PHRASE_RE.test(text))
+        return false;
+    // Skip if the LLM is clearly handing back to the user. Discuss flows
+    // often pose a question and follow it with a conditional intent on the
+    // same line ("Did I capture that correctly? If so, I'll write the
+    // requirements."). A line-trailing `?` check misses these because the
+    // line ends in `.`. Match any sentence-terminating `?` (followed by
+    // whitespace or end-of-text) — false negatives here auto-reply to the
+    // user, which is a much worse failure mode than a missed nudge.
+    if (/\?(?:\s|$)/.test(text))
+        return false;
+    // Must contain a commit-intent phrase — this is the stall we care about.
+    if (!COMMIT_INTENT_RE.test(text))
+        return false;
+    // Resolve the target basePath + pi for injection. Prefer the pending
+    // autostart entry (discuss flow); otherwise we cannot inject.
+    const entry = _getPendingAutoStart(lookupBasePath);
+    if (!entry)
+        return false;
+    const { ctx, pi, basePath } = entry;
+    const count = (emptyTurnCounterByBase.get(basePath) ?? 0) + 1;
+    emptyTurnCounterByBase.set(basePath, count);
+    if (count > MAX_EMPTY_TURN_RETRIES) {
+        ctx.ui.notify(`Empty-turn recovery: LLM announced intent ${count} times without calling any tool. ` +
+            `Stopping auto-nudge.`, "error");
+        return false; // let the normal flow resolve/pause the unit
+    }
+    ctx.ui.notify(`Empty-turn detected: LLM announced intent but called no tool. Prompting it to execute.`, "info");
+    const nudge = `Your last turn announced an action (e.g. "I'll write…" or "Let me call…") ` +
+        `but contained no tool call. The system records zero tool-use blocks for ` +
+        `that turn. Execute the announced action NOW as a tool call in this turn. ` +
+        `Do not describe it again. Retry ${count}/${MAX_EMPTY_TURN_RETRIES}.`;
+    try {
+        pi.sendMessage({ customType: "gsd-empty-turn-recovery", content: nudge, display: false }, { triggerTurn: true });
+    }
+    catch (e) {
+        logWarning("guided", `empty-turn nudge sendMessage failed: ${e.message}`);
+        return false;
+    }
+    return true;
+}

package/dist/resources/extensions/gsd/markdown-renderer.js

@@ -125,7 +125,8 @@ function renderRoadmapMarkdown(milestone, slices) {
     lines.push("");
     for (const slice of slices) {
         const done = isClosedStatus(slice.status) ? "x" : " ";
-        const depends = `[${(slice.depends ?? []).join(",")}]`;
+        const cleanDepends = (slice.depends ?? []).map(d => d.replace(/^\[|\]$/g, '')).filter(d => /^[A-Za-z0-9][A-Za-z0-9-]*$/.test(d));
+        const depends = `[${cleanDepends.join(",")}]`;
         const safeTitle = sanitizeInlineRoadmapText(slice.title || slice.id) || slice.id;
         const safeRisk = normalizeRiskLevel(slice.risk);
         // ADR-011: sketch slices get a `[sketch]` badge so the roadmap shows at a

package/dist/resources/extensions/gsd/mcp-filter.js

@@ -1,6 +1,7 @@
 import { existsSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { resolve } from "node:path";
+import { toMcpWildcardToolName } from "./mcp-tool-name.js";
 import { resolveModelMcpConfig } from "./preferences-mcp.js";
 function isRecord(value) {
     return !!value && typeof value === "object" && !Array.isArray(value);
@@ -123,5 +124,5 @@ export function computeMcpDisallowedTools(modelId, mcpConfig, discoveredServers,
     if (workflowServerName && !(entry.blocked_servers ?? []).includes(workflowServerName)) {
         blocked.delete(workflowServerName);
     }
-    return [...blocked].map((name) => `mcp__${name}__*`);
+    return [...blocked].map(toMcpWildcardToolName);
 }

package/dist/resources/extensions/gsd/mcp-tool-name.js

@@ -0,0 +1,26 @@
+// Project/App: gsd-pi
+// File Purpose: Shared parsing and formatting helpers for MCP-scoped tool names.
+const MCP_TOOL_PREFIX = "mcp__";
+export function parseMcpToolName(toolName) {
+    if (!toolName.startsWith(MCP_TOOL_PREFIX))
+        return null;
+    const toolSeparator = toolName.indexOf("__", MCP_TOOL_PREFIX.length);
+    if (toolSeparator < 0)
+        return null;
+    return {
+        serverName: toolName.slice(MCP_TOOL_PREFIX.length, toolSeparator),
+        toolName: toolName.slice(toolSeparator + 2),
+    };
+}
+export function stripMcpToolPrefix(toolName) {
+    return parseMcpToolName(toolName)?.toolName ?? toolName;
+}
+export function toMcpToolName(serverName, toolName) {
+    return `${MCP_TOOL_PREFIX}${serverName}__${toolName}`;
+}
+export function toMcpWildcardToolName(serverName) {
+    return toMcpToolName(serverName, "*");
+}
+export function mcpToolMatchesBaseName(toolName, baseName) {
+    return parseMcpToolName(toolName)?.toolName === baseName;
+}

package/dist/resources/extensions/gsd/md-importer.js

@@ -5,7 +5,8 @@
 // Exports: parseDecisionsTable, parseRequirementsSections, migrateFromMarkdown
 import { readFileSync, readdirSync, existsSync, statSync } from 'node:fs';
 import { join } from 'node:path';
-import { upsertDecision, upsertRequirement, insertArtifact, insertMilestone, insertSlice, insertTask, openDatabase, transaction, updateMilestoneStatus, updateSliceStatus, _getAdapter, } from './gsd-db.js';
+import { upsertDecision, upsertRequirement, insertArtifact, insertMilestone, insertSlice, insertTask, transaction, updateMilestoneStatus, updateSliceStatus, _getAdapter, } from './gsd-db.js';
+import { openWorkflowDatabasePath } from './db-workspace.js';
 import { resolveGsdRootFile, resolveMilestoneFile, resolveSliceFile, resolveTasksDir, milestonesDir, gsdRoot, resolveTaskFiles, } from './paths.js';
 import { findMilestoneIds } from './guided-flow.js';
 import { parseRoadmap, parsePlan } from './parsers-legacy.js';
@@ -542,7 +543,7 @@ export function migrateHierarchyToDb(basePath) {
                 title: sliceEntry.title,
                 status: sliceStatus,
                 risk: sliceEntry.risk,
-                depends: sliceEntry.depends,
+                depends: (sliceEntry.depends ?? []).map(d => d.replace(/^\[|\]$/g, '')).filter(d => /^[A-Za-z0-9][A-Za-z0-9-]*$/.test(d)),
                 demo: sliceEntry.demo,
                 sequence: si + 1, // Preserve roadmap parse order (#3356)
                 isSketch: sliceEntry.isSketch ?? false, // ADR-011: preserve the `[sketch]` flag on re-import
@@ -628,7 +629,7 @@ export function migrateFromMarkdown(gsdDir) {
     const dbPath = join(gsdRoot(gsdDir), 'gsd.db');
     // Open DB if not already open
     if (!_getAdapter()) {
-        openDatabase(dbPath);
+        openWorkflowDatabasePath(dbPath);
     }
     let decisions = 0;
     let requirements = 0;

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

@@ -5,7 +5,7 @@ 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";
 export class MigrationBlockedError extends Error {
@@ -110,6 +110,6 @@ export async function assertMigrationTargetAvailable(targetRoot) {
         }
     }
     finally {
-        closeDatabase();
+        closeWorkflowDatabase();
     }
 }

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

@@ -1,6 +1,7 @@
 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() {
@@ -124,7 +125,7 @@ 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;
     const markdownEmpty = sameCounts(markdown, zeroCounts());

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

@@ -9,13 +9,13 @@ import { parseRoadmap } from "./parsers-legacy.js";
 import { resolveMilestoneFile } from "./paths.js";
 import { getMilestone, getMilestoneSlices, isDbAvailable } from "./gsd-db.js";
 import { isClosedStatus } from "./status-guards.js";
-import { verifyExpectedArtifact } from "./auto-recovery.js";
 import { runSafely } from "./auto-utils.js";
 import { extractVerdict, isAcceptableUatVerdict } from "./verdict-parser.js";
 import { logWarning } from "./workflow-logger.js";
 import { hasImplementationArtifacts } from "./milestone-implementation-evidence.js";
 import { buildCompleteMilestonePrompt } from "./auto-prompts.js";
-import { checkCloseoutConsistencyGate } from "./closeout-consistency-gate.js";
+import { proveMilestoneCloseout } from "./milestone-closeout-proof.js";
+import { resolveCanonicalMilestoneRoot } from "./worktree-manager.js";
 import { commitPendingMilestoneCloseoutChanges, findMissingSummaries, isVerificationNotApplicable, readUatGateVerdict, } from "./auto-dispatch.js";
 const COMPLETE_MILESTONE_DB_SETTLE_MS = 1500;
 const COMPLETE_MILESTONE_DB_SETTLE_POLL_MS = 100;
@@ -29,8 +29,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;
                 }
             }

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 { renderAllProjections } from "./workflow-projections.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 renderAllProjections(basePath, params.milestoneId);
+        writeManifest(basePath);
+        appendEvent(basePath, {
+            cmd: "plan-milestone",
+            params: { milestoneId: params.milestoneId },
+            ts: new Date().toISOString(),
+            actor: "agent",
+            actor_name: params.actorName,
+            trigger_reason: params.triggerReason,
+        });
+    }
+    catch (hookErr) {
+        logWarning("tool", `plan-milestone post-mutation hook warning: ${hookErr.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,
+    };
+}