@opengsd/gsd-pi 1.2.0 → 1.3.0-dev.72e3af2a

package/dist/resources/extensions/gsd/guided-flow.js

@@ -8,7 +8,7 @@
 import { showNextAction } from "../shared/tui.js";
 import { notifyDiscussNeedsInteractiveMenu, notifySmartEntryNeedsInteractiveMenu, requiresInteractiveMenu, isInteractiveCommandContext, } from "./command-feedback.js";
 import { loadFile, saveFile } from "./files.js";
-import { isDbAvailable, getMilestone, getMilestoneSlices, insertMilestone } from "./gsd-db.js";
+import { isDbAvailable, getMilestone, getMilestoneSlices } from "./gsd-db.js";
 import { parseRoadmapSlices } from "./roadmap-slices.js";
 import { loadPrompt, inlineTemplate } from "./prompt-loader.js";
 import { buildCompleteSlicePrompt, buildDiscussMilestonePrompt, buildExecuteTaskPrompt, buildPlanMilestonePrompt, buildPlanSlicePrompt, buildSkillActivationBlock, } from "./auto-prompts.js";
@@ -20,9 +20,9 @@ import { assessInterruptedSession, formatInterruptedSessionRunningMessage, forma
 import { listUnitRuntimeRecords, clearUnitRuntimeRecord, isInFlightRuntimePhase } from "./unit-runtime.js";
 import { resolveExpectedArtifactPath } from "./auto.js";
 import { gsdHome } from "./gsd-home.js";
-import { gsdRoot, milestonesDir, resolveMilestoneFile, resolveMilestonePath, resolveSliceFile, resolveSlicePath, resolveGsdRootFile, relGsdRootFile, relMilestoneFile, relSliceFile, clearPathCache, } from "./paths.js";
+import { gsdRoot, milestonesDir, legacyMilestonesDir, resolveMilestoneFile, resolveSliceFile, resolveSlicePath, resolveGsdRootFile, relGsdRootFile, relMilestoneFile, relSliceFile, } from "./paths.js";
 import { join } from "node:path";
-import { readFileSync, existsSync, mkdirSync, readdirSync, rmSync, unlinkSync } from "node:fs";
+import { readFileSync, existsSync, mkdirSync, readdirSync, rmSync } from "node:fs";
 import { readSessionLockData, isSessionLockProcessAlive } from "./session-lock.js";
 import { nativeAddAll, nativeCommit, nativeHasCommittedHead, nativeIsRepo, nativeInit } from "./native-git-bridge.js";
 import { isInheritedRepo } from "./repo-identity.js";
@@ -42,15 +42,24 @@ export { nextMilestoneIdReserved } from "./milestone-id-reservation.js";
 import { parkMilestone, discardMilestone } from "./milestone-actions.js";
 import { buildCloseoutMenuActions, buildIdleMenuSummary, getPrimaryCloseoutRecommendation, handleCloseoutChoice, loadCloseoutContext, } from "./closeout-wizard.js";
 import { buildRequirementsBacklogDiscussContext, countUnmappedActiveRequirements, showRequirementsBacklogReview, } from "./requirements-backlog.js";
-import { selectAndApplyModel } from "./auto-model-selection.js";
+import { selectAndApplyModel, getRegisteredToolSnapshot } from "./auto-model-selection.js";
 import { DISCUSS_TOOLS_ALLOWLIST } from "./constants.js";
-import { getWorkflowTransportSupportError, getRequiredWorkflowToolsForGuidedUnit, supportsStructuredQuestions, } from "./workflow-mcp.js";
+import { detectWorkflowMcpLaunchConfig, resolveWorkflowMcpProjectRoot, supportsStructuredQuestions, } from "./workflow-mcp.js";
+import { usesWorkflowMcpTransport } from "./question-transport.js";
+import { getCachedWorkflowMcpProbe, probeAndCacheWorkflowMcp, warmWorkflowMcpProbeInBackground, workflowMcpProbeAdvertisesSurface, WORKFLOW_MCP_PROBE_TIMEOUT_MS, } from "./workflow-mcp-readiness-cache.js";
+import { probeCoversRequiredWorkflowTools } from "./tool-surface-readiness.js";
+import { getRequiredWorkflowToolsForUnit } from "./unit-tool-contracts.js";
+import { isWorkflowToolSurfaceName } from "./workflow-tool-surface.js";
+import { getUnitWorkflowDispatchReadinessError } from "./tool-contract.js";
 import { runPreparation, formatCodebaseBrief, formatPriorContextBrief, } from "./preparation.js";
 import { verifyExpectedArtifact } from "./auto-recovery.js";
-import { getPendingGate, extractDepthVerificationMilestoneId } from "./bootstrap/write-gate.js";
+import { clearPendingGate, extractDepthVerificationMilestoneId, getPendingGate } from "./bootstrap/write-gate.js";
 import { _getPendingAutoStart, deletePendingAutoStart, hasPendingAutoStart, setPendingAutoStart, } from "./pending-auto-start.js";
 import { clearGuidedUnitContext, setGuidedUnitContext } from "./guided-unit-context.js";
+import { checkAutoStartAfterDiscuss, scheduleAutoStartAfterIdle } from "./discussion-handoff.js";
+export { maybeHandleEmptyIntentTurn, maybeHandleReadyPhraseWithoutFiles, resetEmptyTurnCounter, } from "./guided-unit-completion.js";
 export { _getPendingAutoStart, clearPendingAutoStart, getDiscussionMilestoneId, setPendingAutoStart, } from "./pending-auto-start.js";
+export { checkAutoStartAfterDiscuss } from "./discussion-handoff.js";
 export function shouldSkipGitBootstrapAfterInit(result) {
     return result.gitEnabled === false;
 }
@@ -58,27 +67,12 @@ export function shouldSkipGitBootstrapAfterInit(result) {
 export { MILESTONE_ID_RE, generateMilestoneSuffix, nextMilestoneId, extractMilestoneSeq, parseMilestoneId, milestoneIdSort, maxMilestoneNum, findMilestoneIds, reserveMilestoneId, claimReservedId, getReservedMilestoneIds, clearReservedMilestoneIds, } from "./milestone-ids.js";
 export { showQueue, handleQueueReorder, showQueueAdd, buildExistingMilestonesContext, } from "./guided-flow-queue.js";
 import { logWarning } from "./workflow-logger.js";
-import { readManifest } from "./workflow-manifest.js";
 import { deleteRuntimeKv } from "./db/runtime-kv.js";
 import { PAUSED_SESSION_KV_KEY } from "./interrupted-session.js";
 import { buildWorkflowDispatchContent } from "./workflow-protocol.js";
 import { isFullGsdToolSurfaceRequested, restoreGsdWorkflowTools, scopeGsdWorkflowToolsForDispatch } from "./bootstrap/register-hooks.js";
 import { resolveActiveTaskChoiceRoute, } from "./smart-entry-routing.js";
 export { resolveGuidedExecuteLaunchMode } from "./smart-entry-routing.js";
-function scheduleAutoStartAfterIdle(ctx, pi, basePath, verboseMode, options, launch = startAutoDetached) {
-    const waitForIdle = typeof ctx.waitForIdle === "function"
-        ? ctx.waitForIdle.bind(ctx)
-        : async () => { };
-    void waitForIdle()
-        .then(() => {
-        setTimeout(() => launch(ctx, pi, basePath, verboseMode, options), 0);
-    })
-        .catch((err) => {
-        const message = err instanceof Error ? err.message : String(err);
-        ctx.ui.notify(`Auto-start failed while waiting for the prior turn to settle: ${message}`, "error");
-        logWarning("guided", `auto-start idle wait failed: ${message}`);
-    });
-}
 export const _scheduleAutoStartAfterIdleForTest = scheduleAutoStartAfterIdle;
 // ─── Scope-based validator wrappers ──────────────────────────────────────────
 // These thin wrappers accept a MilestoneScope so callers that already hold a
@@ -178,98 +172,11 @@ export function _roadmapHasParseableSlicesForTest(roadmapContent) {
         return false;
     return parseRoadmapSlices(roadmapContent).length > 0;
 }
-function hasExecutablePlanForHandoff(milestoneId, roadmapFile) {
-    if (isDbAvailable()) {
-        return getMilestoneSlices(milestoneId).length > 0;
-    }
-    if (!roadmapFile)
-        return false;
-    try {
-        return parseRoadmapSlices(readFileSync(roadmapFile, "utf-8")).length > 0;
-    }
-    catch (e) {
-        logWarning("guided", `failed to parse roadmap slices for ${milestoneId}: ${e.message}`);
-        return false;
-    }
-}
-function formatAcceptedDiscussHandoffMessage(milestoneId, contextFile, hasExecutablePlan) {
-    if (hasExecutablePlan)
-        return `Milestone ${milestoneId} ready.`;
-    if (contextFile)
-        return `Milestone ${milestoneId} context captured. Continuing the planning pipeline.`;
-    return `Milestone ${milestoneId} planning artifacts captured. Continuing the planning pipeline.`;
-}
-function manifestContainsMilestone(basePath, milestoneId) {
-    try {
-        const manifest = readManifest(basePath);
-        return (Array.isArray(manifest?.milestones) &&
-            manifest.milestones.some(m => m.id === milestoneId));
-    }
-    catch (e) {
-        logWarning("guided", `R3b: failed to read state manifest: ${e.message}`);
-        return false;
-    }
-}
-function notifyDbRowRecoveryFailed(entry) {
-    entry.ctx.ui.notify(`Milestone ${entry.milestoneId}: DB row recovery failed ${entry.r3bRecoveryCount} times. ` +
-        `Re-run /gsd to reset the recovery counter, or run /gsd-debug to diagnose without resetting.`, "error");
-}
-function noteDbRowRecoveryMiss(entry) {
-    entry.r3bRecoveryCount += 1;
-    if (entry.r3bRecoveryCount >= MAX_DB_ROW_RECOVERIES) {
-        notifyDbRowRecoveryFailed(entry);
-    }
-}
-function ensureMilestoneRowForAcceptedHandoff(entry, contextFile) {
-    if (!isDbAvailable())
-        return true;
-    const { basePath, milestoneId } = entry;
-    const milestoneRow = getMilestone(milestoneId);
-    if (milestoneRow)
-        return true;
-    if (manifestContainsMilestone(basePath, milestoneId)) {
-        logWarning("guided", `R3b: getMilestone(${milestoneId}) returned null but manifest has the row — treating as stale read`);
-        return true;
-    }
-    if (!contextFile) {
-        entry.ctx.ui.notify(`Milestone ${milestoneId}: discuss artifacts on disk but no DB row exists. ` +
-            `PROJECT.md may have failed to register milestones. ` +
-            `Re-save PROJECT.md with canonical "- [ ] M001: Title — One-liner" lines, ` +
-            `then re-run /gsd to recover.`, "error");
-        return false;
-    }
-    if (entry.r3bRecoveryCount >= MAX_DB_ROW_RECOVERIES) {
-        logWarning("guided", `R3b: milestone ${milestoneId} DB-row recovery limit reached ` +
-            `(${entry.r3bRecoveryCount}/${MAX_DB_ROW_RECOVERIES}); user already notified`);
-        return false;
-    }
-    logWarning("guided", `R3b: ${milestoneId} has CONTEXT.md but no DB row — inserting placeholder "queued" row ` +
-        `(attempt ${entry.r3bRecoveryCount + 1}/${MAX_DB_ROW_RECOVERIES})`);
-    try {
-        insertMilestone({ id: milestoneId, title: milestoneId, status: "queued" });
-    }
-    catch (e) {
-        logWarning("guided", `R3b: insertMilestone failed: ${e.message}`);
-    }
-    if (getMilestone(milestoneId))
-        return true;
-    noteDbRowRecoveryMiss(entry);
-    return false;
-}
 // ─── Commit Instruction Helpers ──────────────────────────────────────────────
 /** Build commit instruction for planning prompts. .gsd/ is managed externally and always gitignored. */
 function buildDocsCommitInstruction(_message) {
     return "Do not commit planning artifacts — .gsd/ is managed externally.";
 }
-// #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;
-// Cap failed in-flight DB row repair attempts before escalating to the user.
-const MAX_DB_ROW_RECOVERIES = 3;
-// #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 pendingDeepProjectSetupMap = new Map();
 const USER_DRIVEN_DEEP_SETUP_UNITS = new Set([
     "discuss-project",
@@ -304,8 +211,11 @@ function hasNestedFileOrSymlink(dir) {
     }
     return false;
 }
-function clearEmptyLegacyDeepSetupPseudoMilestones(basePath, entries) {
-    const mDir = milestonesDir(basePath);
+function clearEmptyLegacyDeepSetupPseudoMilestones(basePath, entries, dir) {
+    // These are LEGACY pseudo-milestone dirs — prefer legacyMilestonesDir (milestones/)
+    // when it exists; caller may also supply the dir directly.
+    const legacyDir = legacyMilestonesDir(basePath);
+    const mDir = dir ?? (existsSync(legacyDir) ? legacyDir : milestonesDir(basePath));
     const remaining = [];
     for (const entry of entries) {
         if (!LEGACY_DEEP_SETUP_PSEUDO_MILESTONE_DIRS.has(entry)) {
@@ -464,369 +374,70 @@ async function dispatchNextDeepProjectSetupStage(entry) {
     await dispatchWorkflow(entry.pi, `${result.prompt}\n\n${FOREGROUND_DEEP_SETUP_QUESTION_POLICY}`, "gsd-run", entry.ctx, result.unitType, { basePath: entry.basePath });
     return true;
 }
-/** Called from agent_end to check if auto-mode should start after discuss */
-export function checkAutoStartAfterDiscuss(lookupBasePath) {
-    const entry = _getPendingAutoStart(lookupBasePath);
-    if (!entry)
-        return false;
-    const { ctx, pi, basePath, milestoneId, step } = entry;
-    // Gate 1: Primary milestone must have CONTEXT.md or ROADMAP.md
-    // The "discuss" path creates CONTEXT.md; the "plan" path creates ROADMAP.md.
-    // Use pinned scope (immune to cwd-drift) for existence checks.
-    const contextFilePath = entry.scope.contextFile();
-    const roadmapFilePath = entry.scope.roadmapFile();
-    const contextFile = existsSync(contextFilePath) ? contextFilePath : null;
-    const roadmapFile = existsSync(roadmapFilePath) ? roadmapFilePath : null;
-    if (!contextFile && !roadmapFile)
-        return false; // neither artifact yet — keep waiting
-    // Gate 1a: a depth-verification gate is still pending for THIS milestone — the
-    // LLM emitted the confirmation question (via ask_user_questions or plain chat)
-    // but the user has not answered yet. Advancing now would skip the gate and
-    // race ahead with unverified context.
-    const basePathForGate = entry.scope.workspace.projectRoot;
-    const pendingGateId = getPendingGate(basePathForGate);
-    if (pendingGateId) {
-        const pendingMilestoneId = extractDepthVerificationMilestoneId(pendingGateId);
-        // Block advancement if the gate is for THIS milestone, OR if it's a
-        // project/requirements gate (no milestone id encoded) for the deep setup flow.
-        const isProjectGate = pendingGateId === "depth_verification_project_confirm" ||
-            pendingGateId === "depth_verification_requirements_confirm" ||
-            pendingGateId === "depth_verification_research_decision_confirm";
-        if (pendingMilestoneId === milestoneId || isProjectGate) {
-            return false;
-        }
-    }
-    // Gate 1b: accept the in-flight discuss handoff. A queued DB row with pinned
-    // CONTEXT.md is Discussion Complete, Planning Pending, not a plan-blocked
-    // failure. If the row is missing, only this pending handoff may repair it.
-    if (!ensureMilestoneRowForAcceptedHandoff(entry, contextFile))
-        return false;
-    // Gate 2: Multi-milestone completeness warning
-    // Parse PROJECT.md for milestone sequence, warn if any are missing context.
-    // Don't block — milestones can be intentionally queued without context.
-    const projectFile = resolveGsdRootFile(basePath, "PROJECT");
-    let projectIds = [];
-    if (projectFile) {
-        try {
-            const projectContent = readFileSync(projectFile, "utf-8");
-            projectIds = parseMilestoneSequenceFromProject(projectContent);
-            if (projectIds.length > 1) {
-                const missing = projectIds.filter(id => {
-                    const hasContext = !!resolveMilestoneFile(basePath, id, "CONTEXT");
-                    const hasDraft = !!resolveMilestoneFile(basePath, id, "CONTEXT-DRAFT");
-                    const hasDir = existsSync(join(gsdRoot(basePath), "milestones", id));
-                    return !hasContext && !hasDraft && !hasDir;
-                });
-                if (missing.length > 0) {
-                    ctx.ui.notify(`Multi-milestone validation: ${missing.join(", ")} not found in filesystem. ` +
-                        `Discussion may not have completed all readiness gates.`, "warning");
-                }
-            }
-        }
-        catch (e) {
-            logWarning("guided", `PROJECT.md parsing failed: ${e.message}`);
-        }
-    }
-    // Gate 3: Discussion manifest process verification (multi-milestone only)
-    // The LLM writes DISCUSSION-MANIFEST.json after each Phase 3 gate decision.
-    // When it exists, validate it before auto-starting. Project history alone is
-    // not a reliable signal for the current discussion mode.
-    const manifestPath = join(entry.scope.workspace.contract.projectGsd, "DISCUSSION-MANIFEST.json");
-    if (existsSync(manifestPath)) {
-        try {
-            const manifest = JSON.parse(readFileSync(manifestPath, "utf-8"));
-            const total = typeof manifest.total === "number" ? manifest.total : 0;
-            const completed = typeof manifest.gates_completed === "number" ? manifest.gates_completed : 0;
-            if (total > 1 && completed < total) {
-                // Discussion not complete — block auto-start until all gates are done
-                return false;
-            }
-            // Cross-check manifest milestones against PROJECT.md if available
-            if (projectIds.length > 0) {
-                const manifestIds = Object.keys(manifest.milestones ?? {});
-                const untracked = projectIds.filter(id => !manifestIds.includes(id));
-                if (untracked.length > 0) {
-                    ctx.ui.notify(`Discussion manifest missing gates for: ${untracked.join(", ")}`, "warning");
-                }
-            }
-        }
-        catch (e) {
-            logWarning("guided", `discussion manifest verification failed: ${e.message}`);
-        }
-    }
-    // Draft promotion cleanup: if a CONTEXT-DRAFT.md exists alongside the new
-    // CONTEXT.md, delete the draft — it's been consumed by the discussion.
-    try {
-        const draftFile = resolveMilestoneFile(basePath, milestoneId, "CONTEXT-DRAFT");
-        if (draftFile)
-            unlinkSync(draftFile);
-    }
-    catch (e) {
-        logWarning("guided", `CONTEXT-DRAFT.md unlink failed: ${e.message}`);
-    }
-    // Cleanup: remove discussion manifest after auto-start (only needed during discussion)
-    if (existsSync(manifestPath)) {
-        try {
-            unlinkSync(manifestPath);
-        }
-        catch (e) {
-            logWarning("guided", `manifest unlink failed: ${e.message}`);
-        }
-    }
-    deletePendingAutoStart(basePath);
-    const hasExecutablePlan = hasExecutablePlanForHandoff(milestoneId, roadmapFile);
-    ctx.ui.notify(formatAcceptedDiscussHandoffMessage(milestoneId, contextFile, hasExecutablePlan), "success");
-    if (entry.startAuto !== false) {
-        scheduleAutoStartAfterIdle(ctx, pi, basePath, false, { step: step ?? true });
-    }
-    return true;
-}
-/**
- * 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;
+export function resolveGuidedDispatchProjectRoot(basePath) {
+    return basePath ?? process.cwd();
 }
 /**
- * #4573 — Detect and recover from the "announces tool, never calls it" stall.
- *
- * The LLM emits text like "I'll now write the CONTEXT.md file" but the turn
- * ends with zero tool-use blocks. The harness has no post-turn tool-call
- * validation, so the unit promise resolves and the user sees a stalled state.
- *
- * This function, called from `handleAgentEnd`, inspects the last assistant
- * message. If ALL of the following are true, it injects a recovery message:
- *   - Text-only (no tool-use blocks)
- *   - Contains a commit-intent phrase ("I'll write", "I'll call", etc.)
- *   - Auto-mode is active OR a discussion autostart is pending
- *   - `emptyTurnRetryCount` is under the cap
- *
- * Per-handler state is held on the `PendingAutoStartEntry` when present, and
- * on a module-level map otherwise. The counter resets on any successful
- * tool-use turn via `resetEmptyTurnCounter`.
- */
-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;
-/**
- * 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.
+ * Wait until the workflow MCP server is reachable and advertising its tool
+ * surface. Returns failure details when timed out, or null when ready (or MCP
+ * is not the transport). Called inside dispatchWorkflow() so every guided-flow
+ * dispatch path is gated automatically.
  */
-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;
+const MCP_READINESS_TIMEOUT_MS = 15_000;
+const MCP_READINESS_POLL_MS = 200;
+async function awaitWorkflowMcpReadiness(pi, ctx, basePath, options = {}) {
+    const provider = ctx.model?.provider;
+    const authMode = provider ? ctx.modelRegistry.getProviderAuthMode(provider) : undefined;
+    if (!usesWorkflowMcpTransport(authMode, ctx.model?.baseUrl))
+        return null;
+    const projectRoot = resolveWorkflowMcpProjectRoot(basePath);
+    const launch = detectWorkflowMcpLaunchConfig(projectRoot);
+    if (!launch)
+        return null;
+    const requiredTools = options.unitType
+        ? getRequiredWorkflowToolsForUnit(options.unitType).filter(isWorkflowToolSurfaceName)
+        : [];
+    const coversExpectedSurface = (tools) => requiredTools.length > 0
+        ? probeCoversRequiredWorkflowTools(tools, requiredTools)
+        : workflowMcpProbeAdvertisesSurface(tools);
+    const serverPrefix = `mcp__${launch.name}__`;
+    const systemPrompt = () => typeof ctx.getSystemPrompt === "function" ? ctx.getSystemPrompt() : "";
+    const systemPromptCoversExpectedSurface = () => {
+        const prompt = systemPrompt();
+        return requiredTools.length > 0
+            ? requiredTools.every((tool) => prompt.includes(`${serverPrefix}${tool}`))
+            : prompt.includes(serverPrefix);
+    };
+    const sessionAlreadyReady = () => coversExpectedSurface(getRegisteredToolSnapshot(pi)) ||
+        systemPromptCoversExpectedSurface();
+    if (sessionAlreadyReady())
+        return null;
+    if (coversExpectedSurface(getCachedWorkflowMcpProbe(projectRoot)?.tools ?? [])) {
+        return null;
     }
-    return true;
-}
-/**
- * Extract milestone IDs from PROJECT.md milestone sequence table.
- * Looks for rows like "| M001 | Name | Status |" and extracts the ID column.
- */
-function parseMilestoneSequenceFromProject(content) {
-    const ids = [];
-    const lines = content.split(/\r?\n/);
-    for (const line of lines) {
-        const match = line.match(/^\|\s*(M\d{3}[A-Z0-9-]*)\s*\|/);
-        if (match)
-            ids.push(match[1]);
-    }
-    return ids;
-}
-export function resolveGuidedDispatchProjectRoot(basePath) {
-    return basePath ?? process.cwd();
+    const probe = options.probe ?? probeAndCacheWorkflowMcp;
+    const probeTimeoutMs = options.probeTimeoutMs ?? WORKFLOW_MCP_PROBE_TIMEOUT_MS;
+    ctx.ui.setStatus("gsd-step", `Waiting for ${launch.name} MCP server…`);
+    let lastError;
+    const deadline = Date.now() + (options.timeoutMs ?? MCP_READINESS_TIMEOUT_MS);
+    const pollMs = options.pollMs ?? MCP_READINESS_POLL_MS;
+    while (Date.now() < deadline) {
+        if (sessionAlreadyReady()) {
+            ctx.ui.setStatus("gsd-step", "");
+            return null;
+        }
+        const result = await probe(projectRoot, { timeoutMs: probeTimeoutMs });
+        if (result.ok && coversExpectedSurface(result.tools)) {
+            ctx.ui.setStatus("gsd-step", "");
+            return null;
+        }
+        lastError = result.error;
+        await new Promise((r) => setTimeout(r, pollMs));
+    }
+    ctx.ui.setStatus("gsd-step", "");
+    return lastError ? { server: launch.name, error: lastError } : { server: launch.name };
 }
+export const _awaitWorkflowMcpReadinessForTest = awaitWorkflowMcpReadiness;
 /**
  * Read GSD-WORKFLOW.md and dispatch it to the LLM with a contextual note.
  * This is the only way the wizard triggers work — everything else is the LLM's job.
@@ -841,7 +452,8 @@ async function dispatchWorkflow(pi, note, customType = "gsd-run", ctx, unitType,
     const projectRoot = resolveGuidedDispatchProjectRoot(resolvedOptions.basePath);
     const loadPreferences = resolvedOptions.deps?.loadPreferences ?? loadEffectiveGSDPreferences;
     const selectModel = resolvedOptions.deps?.selectModel ?? selectAndApplyModel;
-    const getTransportSupportError = resolvedOptions.deps?.getTransportSupportError ?? getWorkflowTransportSupportError;
+    const getDispatchReadinessError = resolvedOptions.deps?.getDispatchReadinessError
+        ?? getUnitWorkflowDispatchReadinessError;
     // Route through the dynamic routing pipeline (complexity classification,
     // tier downgrade, fallback chains) — same path as auto-mode dispatches (#2958).
     if (ctx && unitType) {
@@ -855,7 +467,8 @@ async function dispatchWorkflow(pi, note, customType = "gsd-run", ctx, unitType,
                 routing: result.routing,
             });
         }
-        const compatibilityError = getTransportSupportError(result.appliedModel?.provider ?? ctx.model?.provider, getRequiredWorkflowToolsForGuidedUnit(unitType), {
+        const compatibilityError = getDispatchReadinessError({
+            provider: result.appliedModel?.provider ?? ctx.model?.provider,
             projectRoot,
             surface: "guided flow",
             unitType,
@@ -874,6 +487,25 @@ async function dispatchWorkflow(pi, note, customType = "gsd-run", ctx, unitType,
             ctx.ui.notify(compatibilityError, "error");
             return;
         }
+        // ── Live MCP readiness gate ────────────────────────────────────────
+        // Units with required workflow tools must not dispatch until the MCP
+        // surface covers that exact contract; otherwise the model can race into
+        // "No such tool available" before recovery sees a clean readiness error.
+        warmWorkflowMcpProbeInBackground(projectRoot);
+        const requiredWorkflowTools = getRequiredWorkflowToolsForUnit(unitType).filter(isWorkflowToolSurfaceName);
+        const strictBlocking = requiredWorkflowTools.length > 0
+            && (process.env.GSD_GUIDED_MCP_BLOCKING ?? "").trim() !== "0";
+        if (strictBlocking) {
+            // If the workflow MCP server is configured but still connecting, wait
+            // for it instead of dispatching into a child session that will abort.
+            const readinessFailure = await awaitWorkflowMcpReadiness(pi, ctx, projectRoot, { unitType });
+            if (readinessFailure) {
+                const detail = readinessFailure.error ? ` ${readinessFailure.error}` : "";
+                ctx.ui.notify(`GSD workflow server "${readinessFailure.server}" did not connect in time.${detail} ` +
+                    `Run \`/gsd mcp check ${readinessFailure.server}\` for details.`, "warning");
+                return;
+            }
+        }
     }
     // Scope tools for guided workflow turns (#2949, token-consumption savings).
     // Providers with grammar-based constrained decoding (xAI/Grok) return
@@ -1103,7 +735,6 @@ function bootstrapGsdProject(basePath) {
         nativeInit(basePath, mainBranch);
     }
     const root = gsdRoot(basePath);
-    mkdirSync(join(root, "milestones"), { recursive: true });
     mkdirSync(join(root, "runtime"), { recursive: true });
     const gitPrefs = loadEffectiveGSDPreferences(basePath)?.preferences?.git;
     const manageGitignore = gitPrefs?.manage_gitignore;
@@ -1647,6 +1278,27 @@ function selfHealRuntimeRecords(basePath, ctx) {
         return { cleared: 0 };
     }
 }
+/**
+ * True when an agent turn is currently streaming or a dispatched message is
+ * still queued waiting to trigger one. Used by the pending-auto-start stale
+ * check: a live discuss turn can run for minutes before writing its first
+ * artifact, and deleting its entry as "stale" re-dispatches the workflow —
+ * resetting the interview and producing a duplicate completion turn.
+ */
+function isAgentTurnInFlight(ctx) {
+    try {
+        if (typeof ctx.isIdle === "function" && !ctx.isIdle())
+            return true;
+        if (typeof ctx.hasPendingMessages === "function" && ctx.hasPendingMessages())
+            return true;
+    }
+    catch {
+        // assertActive() throws on a stale runner context; fall through to
+        // artifact/age staleness signals.
+        logWarning("guided", "isAgentTurnInFlight: ctx method threw (stale runner); assuming no turn in flight");
+    }
+    return false;
+}
 // ─── Milestone Actions Submenu ──────────────────────────────────────────────
 /**
  * Shows a submenu with Park / Discard / Skip / Back options for the active milestone.
@@ -1735,6 +1387,7 @@ async function handleMilestoneActions(ctx, pi, basePath, milestoneId, milestoneT
 }
 export async function showSmartEntry(ctx, pi, basePath, options) {
     const stepMode = options?.step ?? true;
+    warmWorkflowMcpProbeInBackground(basePath);
     // ── Clear stale milestone ID reservations from previous cancelled sessions ──
     // Reservations only need to survive within a single /gsd interaction.
     // Without this, each cancelled session permanently bumps the next ID. (#2488)
@@ -1864,8 +1517,33 @@ export async function showSmartEntry(ctx, pi, basePath, options) {
             const { checkMarkdownHierarchyAgainstDb } = await import("./migration-auto-check.js");
             const result = await checkMarkdownHierarchyAgainstDb(basePath);
             if (result.action === "recovery-required") {
-                ctx.ui.notify(result.message ??
-                    `Markdown planning artifacts do not match the authoritative DB. Run \`${result.recoveryCommand ?? "/gsd recover --confirm"}\` to import markdown explicitly.`, "warning");
+                if (result.recoveryCommand === "/gsd rebuild markdown") {
+                    try {
+                        const { rebuildMarkdownProjectionsFromDb } = await import("./commands-maintenance.js");
+                        const rebuild = await rebuildMarkdownProjectionsFromDb(basePath);
+                        const after = await checkMarkdownHierarchyAgainstDb(basePath);
+                        if (after.action === "none") {
+                            ctx.ui.notify(`Self-heal: rebuilt markdown projections from the authoritative DB ` +
+                                `(${rebuild.rendered} rendered${rebuild.errors.length > 0 ? `, ${rebuild.errors.length} error(s)` : ""}).`, rebuild.errors.length > 0 ? "warning" : "info");
+                        }
+                        else {
+                            ctx.ui.notify((result.message ?? "Markdown planning artifacts still diverge from the DB after auto-rebuild.") +
+                                (rebuild.errors.length > 0
+                                    ? `\nAuto-rebuild had ${rebuild.errors.length} projection error(s). Run \`/gsd rebuild markdown\` after review.`
+                                    : ""), "warning");
+                        }
+                    }
+                    catch (rebuildErr) {
+                        const rebuildMessage = rebuildErr instanceof Error ? rebuildErr.message : String(rebuildErr);
+                        logWarning("guided", `markdown auto-rebuild failed: ${rebuildMessage}`, { file: "guided-flow.ts" });
+                        ctx.ui.notify(result.message ??
+                            `Markdown planning artifacts do not match the authoritative DB. Run \`${result.recoveryCommand ?? "/gsd rebuild markdown"}\` to re-project from the DB.`, "warning");
+                    }
+                }
+                else {
+                    ctx.ui.notify(result.message ??
+                        `Markdown planning artifacts do not match the authoritative DB. Run \`${result.recoveryCommand ?? "/gsd recover --confirm"}\` to import markdown explicitly.`, "warning");
+                }
             }
         }
         catch (err) {
@@ -1913,12 +1591,18 @@ export async function showSmartEntry(ctx, pi, basePath, options) {
         // and fires another dispatchWorkflow, resetting the conversation mid-interview.
         if (hasPendingAutoStart(basePath)) {
             // #3274: If /clear interrupted the discussion, the pending entry is stale.
-            // Detect staleness: no manifest, no milestone CONTEXT artifact, AND entry is older than
-            // 30s (avoids race between .set() and LLM writing first artifact).
+            // Detect staleness: no manifest, no milestone CONTEXT/CONTEXT-DRAFT artifact,
+            // the entry is older than 30s (avoids race between .set() and LLM writing the
+            // first artifact), AND no agent turn is in flight. A dispatched discuss turn
+            // can think for well over 30s before its first question round writes any
+            // artifact; deleting the entry while that turn is live re-dispatches the
+            // workflow, which both resets the interview and queues a duplicate turn that
+            // replays the final "context written" message after the real one.
             const entry = _getPendingAutoStart(basePath);
             const ageMs = Date.now() - (entry.createdAt || 0);
             const manifestExists = existsSync(join(gsdRoot(basePath), "DISCUSSION-MANIFEST.json"));
             const milestoneHasContext = !!resolveMilestoneFile(basePath, entry.milestoneId, "CONTEXT");
+            const milestoneHasDraft = !!resolveMilestoneFile(basePath, entry.milestoneId, "CONTEXT-DRAFT");
             const milestoneHasRoadmap = !!resolveMilestoneFile(basePath, entry.milestoneId, "ROADMAP");
             const milestoneRow = isDbAvailable() ? getMilestone(entry.milestoneId) : null;
             const discussPlanComplete = milestoneHasRoadmap && !!milestoneRow && milestoneRow.status !== "queued";
@@ -1927,11 +1611,30 @@ export async function showSmartEntry(ctx, pi, basePath, options) {
                 // Clear stale in-memory guard and continue through normal active-milestone routing.
                 deletePendingAutoStart(basePath);
             }
-            else if (!manifestExists && !milestoneHasContext && ageMs > 30_000) {
+            else if (!manifestExists &&
+                !milestoneHasContext &&
+                !milestoneHasDraft &&
+                ageMs > 30_000 &&
+                !isAgentTurnInFlight(ctx)) {
                 // Stale entry from an interrupted discussion — clear and continue
                 deletePendingAutoStart(basePath);
             }
             else {
+                if (milestoneHasContext && !isAgentTurnInFlight(ctx)) {
+                    // The discussion already produced CONTEXT but the agent_end handoff
+                    // never consumed the entry — e.g. an external-engine post-hoc gate
+                    // re-arm wiped the depth verification after the save (write-gate
+                    // two-process sync). CONTEXT can only be written through a verified
+                    // depth gate, so a gate still pending for this milestone is stale:
+                    // clear it and re-run the handoff instead of dead-ending.
+                    const gateBasePath = entry.scope.workspace.projectRoot;
+                    const pendingGateId = getPendingGate(gateBasePath);
+                    if (pendingGateId && extractDepthVerificationMilestoneId(pendingGateId) === entry.milestoneId) {
+                        clearPendingGate(gateBasePath);
+                    }
+                    if (checkAutoStartAfterDiscuss(basePath))
+                        return;
+                }
                 ctx.ui.notify("Discussion already in progress — answer the question above to continue.", "info");
                 return;
             }
@@ -1942,9 +1645,12 @@ export async function showSmartEntry(ctx, pi, basePath, options) {
         // cwd, etc). Warn instead of silently starting a new-project flow.
         if (milestoneIds.length === 0) {
             const mDir = milestonesDir(basePath);
-            if (existsSync(mDir)) {
+            const legDir = legacyMilestonesDir(basePath);
+            // Check flat-phase dir first; fall back to legacy milestones/ dir
+            const checkDir = existsSync(mDir) ? mDir : existsSync(legDir) ? legDir : null;
+            if (checkDir) {
                 try {
-                    const entries = clearEmptyLegacyDeepSetupPseudoMilestones(basePath, readdirSync(mDir));
+                    const entries = clearEmptyLegacyDeepSetupPseudoMilestones(basePath, readdirSync(checkDir), checkDir);
                     if (entries.length > 0) {
                         ctx.ui.notify(`Milestone directory has ${entries.length} entries but none were recognized as milestones. ` +
                             `This may indicate a corrupted state or wrong working directory. Run \`/gsd doctor\` to diagnose.`, "warning");