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

package/src/resources/extensions/gsd/guided-flow.ts

@@ -40,12 +40,12 @@ import { listUnitRuntimeRecords, clearUnitRuntimeRecord, isInFlightRuntimePhase
 import { resolveExpectedArtifactPath } from "./auto.js";
 import { gsdHome } from "./gsd-home.js";
 import {
-  gsdRoot, milestonesDir, resolveMilestoneFile, resolveMilestonePath,
+  gsdRoot, milestonesDir, legacyMilestonesDir, resolveMilestoneFile,
   resolveSliceFile, resolveSlicePath, resolveGsdRootFile, relGsdRootFile,
-  relMilestoneFile, relSliceFile, clearPathCache,
+  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";
@@ -76,13 +76,25 @@ import {
   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,
+  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,
@@ -90,7 +102,7 @@ import {
 } from "./preparation.js";
 import { verifyExpectedArtifact } from "./auto-recovery.js";
 import type { MilestoneScope } from "./workspace.js";
-import { getPendingGate, extractDepthVerificationMilestoneId } from "./bootstrap/write-gate.js";
+import { clearPendingGate, extractDepthVerificationMilestoneId, getPendingGate } from "./bootstrap/write-gate.js";
 import {
   _getPendingAutoStart,
   clearPendingAutoStart,
@@ -98,9 +110,14 @@ import {
   getDiscussionMilestoneId,
   hasPendingAutoStart,
   setPendingAutoStart,
-  type PendingAutoStartEntry,
 } 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,
@@ -108,6 +125,7 @@ export {
   getDiscussionMilestoneId,
   setPendingAutoStart,
 } from "./pending-auto-start.js";
+export { checkAutoStartAfterDiscuss } from "./discussion-handoff.js";
 
 export function shouldSkipGitBootstrapAfterInit(result: { gitEnabled?: boolean }): boolean {
   return result.gitEnabled === false;
@@ -125,7 +143,6 @@ export {
   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";
@@ -141,32 +158,6 @@ export interface HeadlessMilestoneCreationOptions {
   startAutoAfterReady?: boolean;
 }
 
-type AutoStartOptions = Parameters<typeof startAutoDetached>[4];
-type AutoStartLauncher = typeof startAutoDetached;
-
-function scheduleAutoStartAfterIdle(
-  ctx: ExtensionCommandContext,
-  pi: ExtensionAPI,
-  basePath: string,
-  verboseMode: boolean,
-  options?: AutoStartOptions,
-  launch: AutoStartLauncher = startAutoDetached,
-): void {
-  const waitForIdle =
-    typeof (ctx as { waitForIdle?: unknown }).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 ──────────────────────────────────────────
@@ -321,116 +312,6 @@ export function _roadmapHasParseableSlicesForTest(
   return parseRoadmapSlices(roadmapContent).length > 0;
 }
 
-function hasExecutablePlanForHandoff(milestoneId: string, roadmapFile: string | null): boolean {
-  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 as Error).message}`,
-    );
-    return false;
-  }
-}
-
-function formatAcceptedDiscussHandoffMessage(
-  milestoneId: string,
-  contextFile: string | null,
-  hasExecutablePlan: boolean,
-): string {
-  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: string, milestoneId: string): boolean {
-  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 as Error).message}`);
-    return false;
-  }
-}
-
-function notifyDbRowRecoveryFailed(entry: PendingAutoStartEntry): void {
-  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: PendingAutoStartEntry): void {
-  entry.r3bRecoveryCount += 1;
-  if (entry.r3bRecoveryCount >= MAX_DB_ROW_RECOVERIES) {
-    notifyDbRowRecoveryFailed(entry);
-  }
-}
-
-function ensureMilestoneRowForAcceptedHandoff(
-  entry: PendingAutoStartEntry,
-  contextFile: string | null,
-): boolean {
-  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 as Error).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. */
@@ -451,18 +332,6 @@ interface PendingDeepProjectSetupEntry {
   currentUnitId?: string;
 }
 
-// #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<string, PendingDeepProjectSetupEntry>();
 const USER_DRIVEN_DEEP_SETUP_UNITS = new Set([
   "discuss-project",
@@ -497,8 +366,11 @@ function hasNestedFileOrSymlink(dir: string): boolean {
   return false;
 }
 
-function clearEmptyLegacyDeepSetupPseudoMilestones(basePath: string, entries: string[]): string[] {
-  const mDir = milestonesDir(basePath);
+function clearEmptyLegacyDeepSetupPseudoMilestones(basePath: string, entries: string[], dir?: string): string[] {
+  // 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: string[] = [];
   for (const entry of entries) {
     if (!LEGACY_DEEP_SETUP_PSEUDO_MILESTONE_DIRS.has(entry)) {
@@ -687,405 +559,6 @@ async function dispatchNextDeepProjectSetupStage(entry: PendingDeepProjectSetupE
   return true;
 }
 
-/** Called from agent_end to check if auto-mode should start after discuss */
-export function checkAutoStartAfterDiscuss(lookupBasePath?: string): boolean {
-  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: string[] = [];
-  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 as Error).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 as Error).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 as Error).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 as Error).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: any): string {
-  if (!msg) return "";
-  const content = msg.content;
-  if (typeof content === "string") return content;
-  if (!Array.isArray(content)) return "";
-  const parts: string[] = [];
-  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: any): boolean {
-  if (!msg) return false;
-  const content = msg.content;
-  if (!Array.isArray(content)) return false;
-  return content.some(
-    (b: any) =>
-      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: { messages: any[] }, lookupBasePath?: string): boolean {
-  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 as Error).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 as Error).message}`);
-    return false;
-  }
-  return true;
-}
-
-/**
- * #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<string, number>();
-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.
- */
-export function resetEmptyTurnCounter(basePath?: string): void {
-  if (basePath) emptyTurnCounterByBase.delete(basePath);
-  else emptyTurnCounterByBase.clear();
-}
-
-export function maybeHandleEmptyIntentTurn(
-  event: { messages: any[] },
-  isAuto: boolean,
-  lookupBasePath?: string,
-): boolean {
-  // 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 as Error).message}`);
-    return false;
-  }
-  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: string): string[] {
-  const ids: string[] = [];
-  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;
-}
-
 // ─── Types ────────────────────────────────────────────────────────────────────
 
 type UIContext = ExtensionContext;
@@ -1097,7 +570,7 @@ interface DispatchWorkflowOptions {
   deps?: {
     loadPreferences?: typeof loadEffectiveGSDPreferences;
     selectModel?: typeof selectAndApplyModel;
-    getTransportSupportError?: typeof getWorkflowTransportSupportError;
+    getDispatchReadinessError?: typeof getUnitWorkflowDispatchReadinessError;
   };
 }
 
@@ -1105,6 +578,93 @@ export function resolveGuidedDispatchProjectRoot(basePath?: string): string {
   return basePath ?? process.cwd();
 }
 
+/**
+ * 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.
+ */
+const MCP_READINESS_TIMEOUT_MS = 15_000;
+const MCP_READINESS_POLL_MS = 200;
+
+export interface WorkflowMcpReadinessFailure {
+  server: string;
+  error?: string;
+}
+
+async function awaitWorkflowMcpReadiness(
+  pi: ExtensionAPI,
+  ctx: ExtensionContext,
+  basePath: string,
+  options: {
+    unitType?: string;
+    timeoutMs?: number;
+    pollMs?: number;
+    probeTimeoutMs?: number;
+    probe?: typeof probeAndCacheWorkflowMcp;
+  } = {},
+): Promise<WorkflowMcpReadinessFailure | null> {
+  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: readonly string[]) =>
+    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;
+  }
+
+  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: string | undefined;
+  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.
@@ -1126,7 +686,8 @@ async function dispatchWorkflow(
   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).
@@ -1145,29 +706,49 @@ async function dispatchWorkflow(
       });
     }
 
-    const compatibilityError = getTransportSupportError(
-      result.appliedModel?.provider ?? ctx.model?.provider,
-      getRequiredWorkflowToolsForGuidedUnit(unitType),
-      {
-        projectRoot,
-        surface: "guided flow",
-        unitType,
-        authMode: result.appliedModel?.provider
-          ? ctx.modelRegistry.getProviderAuthMode(result.appliedModel.provider)
-          : ctx.model?.provider
-            ? ctx.modelRegistry.getProviderAuthMode(ctx.model.provider)
-            : undefined,
-        baseUrl: result.appliedModel?.baseUrl ?? ctx.model?.baseUrl,
-        // Guided flow starts the MCP workflow server as part of dispatch, so the
-        // parent session's activeTools doesn't include MCP tools yet. The MCP
-        // launch config check (detectWorkflowMcpLaunchConfig) is the right gate
-        // here — not whether MCP tools are pre-registered in the parent session.
-      },
-    );
+    const compatibilityError = getDispatchReadinessError({
+      provider: result.appliedModel?.provider ?? ctx.model?.provider,
+      projectRoot,
+      surface: "guided flow",
+      unitType,
+      authMode: result.appliedModel?.provider
+        ? ctx.modelRegistry.getProviderAuthMode(result.appliedModel.provider)
+        : ctx.model?.provider
+          ? ctx.modelRegistry.getProviderAuthMode(ctx.model.provider)
+          : undefined,
+      baseUrl: result.appliedModel?.baseUrl ?? ctx.model?.baseUrl,
+      // Guided flow starts the MCP workflow server as part of dispatch, so the
+      // parent session's activeTools doesn't include MCP tools yet. The MCP
+      // launch config check (detectWorkflowMcpLaunchConfig) is the right gate
+      // here — not whether MCP tools are pre-registered in the parent session.
+    });
     if (compatibilityError) {
       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).
@@ -1463,7 +1044,6 @@ function bootstrapGsdProject(basePath: string): void {
   }
 
   const root = gsdRoot(basePath);
-  mkdirSync(join(root, "milestones"), { recursive: true });
   mkdirSync(join(root, "runtime"), { recursive: true });
 
   const gitPrefs = loadEffectiveGSDPreferences(basePath)?.preferences?.git;
@@ -2124,6 +1704,25 @@ function selfHealRuntimeRecords(basePath: string, ctx: ExtensionContext): { clea
   }
 }
 
+/**
+ * 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: ExtensionCommandContext): boolean {
+  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 ──────────────────────────────────────────────
 
 /**
@@ -2231,6 +1830,7 @@ export async function showSmartEntry(
   options?: { step?: boolean },
 ): Promise<void> {
   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.
@@ -2367,11 +1967,42 @@ export async function showSmartEntry(
       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) {
       const message = err instanceof Error ? err.message : String(err);
@@ -2422,12 +2053,18 @@ export async function showSmartEntry(
     // 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";
@@ -2435,10 +2072,30 @@ export async function showSmartEntry(
         // The discuss flow already completed, but pending auto-start cleanup handshake did not run.
         // 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;
       }
@@ -2451,9 +2108,12 @@ export async function showSmartEntry(
     // 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. ` +