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

package/dist/resources/extensions/gsd/gsd-db.js

@@ -1001,6 +1001,11 @@ export function upsertMilestonePlanning(milestoneId, planning) {
 export function insertSlice(s) {
     if (!currentDb)
         throw new GSDError(GSD_STALE_STATE, "gsd-db: No database open");
+    const SLICE_ID_RE = /^[A-Za-z0-9][A-Za-z0-9-]*$/;
+    const invalidDep = (s.depends ?? []).find(d => !SLICE_ID_RE.test(d));
+    if (invalidDep !== undefined) {
+        throw new GSDError(GSD_STALE_STATE, `insertSlice: depends element "${invalidDep}" is not a valid slice ID`);
+    }
     currentDb.prepare(`INSERT INTO slices (
       milestone_id, id, title, status, risk, depends, demo, created_at,
       goal, success_criteria, proof_level, integration_closure, observability_impact, target_repositories, sequence,
@@ -2124,6 +2129,13 @@ export function deleteMilestone(milestoneId) {
 export function updateSliceFields(milestoneId, sliceId, fields) {
     if (!currentDb)
         throw new GSDError(GSD_STALE_STATE, "gsd-db: No database open");
+    const SLICE_ID_RE = /^[A-Za-z0-9][A-Za-z0-9-]*$/;
+    if (fields.depends !== undefined) {
+        const invalidDep = fields.depends.find(d => !SLICE_ID_RE.test(d));
+        if (invalidDep !== undefined) {
+            throw new GSDError(GSD_STALE_STATE, `updateSliceFields: depends element "${invalidDep}" is not a valid slice ID`);
+        }
+    }
     currentDb.prepare(`UPDATE slices SET
       title = COALESCE(:title, title),
       risk = COALESCE(:risk, risk),

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, 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";
@@ -47,10 +47,13 @@ import { DISCUSS_TOOLS_ALLOWLIST } from "./constants.js";
 import { getWorkflowTransportSupportError, getRequiredWorkflowToolsForGuidedUnit, supportsStructuredQuestions, } from "./workflow-mcp.js";
 import { runPreparation, formatCodebaseBrief, formatPriorContextBrief, } from "./preparation.js";
 import { verifyExpectedArtifact } from "./auto-recovery.js";
-import { getPendingGate, extractDepthVerificationMilestoneId } from "./bootstrap/write-gate.js";
+import { 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 { 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 +61,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 +166,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",
@@ -464,366 +365,6 @@ 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;
-}
-/**
- * #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.
- */
-export function resetEmptyTurnCounter(basePath) {
-    if (basePath)
-        emptyTurnCounterByBase.delete(basePath);
-    else
-        emptyTurnCounterByBase.clear();
-}
-export function maybeHandleEmptyIntentTurn(event, isAuto, lookupBasePath) {
-    // Gate: only fire when there is system-driven work in flight. Interactive
-    // /gsd discuss (user-driven) produces legitimate text-only turns.
-    if (!isAuto && !hasPendingAutoStart(lookupBasePath))
-        return false;
-    const lastMsg = event.messages[event.messages.length - 1];
-    if (!lastMsg)
-        return false;
-    if (hasToolUse(lastMsg))
-        return false;
-    const text = extractAssistantText(lastMsg).trim();
-    if (!text)
-        return false;
-    // Skip if the LLM is emitting the ready phrase — that is the ready-no-files
-    // path, handled by maybeHandleReadyPhraseWithoutFiles.
-    if (READY_PHRASE_RE.test(text))
-        return false;
-    // Skip if the LLM is clearly handing back to the user. Discuss flows
-    // often pose a question and follow it with a conditional intent on the
-    // same line ("Did I capture that correctly? If so, I'll write the
-    // requirements."). A line-trailing `?` check misses these because the
-    // line ends in `.`. Match any sentence-terminating `?` (followed by
-    // whitespace or end-of-text) — false negatives here auto-reply to the
-    // user, which is a much worse failure mode than a missed nudge.
-    if (/\?(?:\s|$)/.test(text))
-        return false;
-    // Must contain a commit-intent phrase — this is the stall we care about.
-    if (!COMMIT_INTENT_RE.test(text))
-        return false;
-    // Resolve the target basePath + pi for injection. Prefer the pending
-    // autostart entry (discuss flow); otherwise we cannot inject.
-    const entry = _getPendingAutoStart(lookupBasePath);
-    if (!entry)
-        return false;
-    const { ctx, pi, basePath } = entry;
-    const count = (emptyTurnCounterByBase.get(basePath) ?? 0) + 1;
-    emptyTurnCounterByBase.set(basePath, count);
-    if (count > MAX_EMPTY_TURN_RETRIES) {
-        ctx.ui.notify(`Empty-turn recovery: LLM announced intent ${count} times without calling any tool. ` +
-            `Stopping auto-nudge.`, "error");
-        return false; // let the normal flow resolve/pause the unit
-    }
-    ctx.ui.notify(`Empty-turn detected: LLM announced intent but called no tool. Prompting it to execute.`, "info");
-    const nudge = `Your last turn announced an action (e.g. "I'll write…" or "Let me call…") ` +
-        `but contained no tool call. The system records zero tool-use blocks for ` +
-        `that turn. Execute the announced action NOW as a tool call in this turn. ` +
-        `Do not describe it again. Retry ${count}/${MAX_EMPTY_TURN_RETRIES}.`;
-    try {
-        pi.sendMessage({ customType: "gsd-empty-turn-recovery", content: nudge, display: false }, { triggerTurn: true });
-    }
-    catch (e) {
-        logWarning("guided", `empty-turn nudge sendMessage failed: ${e.message}`);
-        return false;
-    }
-    return true;
-}
-/**
- * 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();
 }
@@ -1864,8 +1405,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) {