gsd-pi 2.78.1-dev.b0759e59b → 2.78.1-dev.d8826a445

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

@@ -7,11 +7,11 @@
  */
 import { showNextAction } from "../shared/tui.js";
 import { loadFile, saveFile } from "./files.js";
-import { isDbAvailable, getMilestoneSlices } 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";
-import { deriveState } from "./state.js";
+import { deriveState, isGhostMilestone } from "./state.js";
 import { invalidateAllCaches } from "./cache.js";
 import { startAutoDetached } from "./auto.js";
 import { clearLock } from "./crash-recovery.js";
@@ -19,7 +19,7 @@ import { assessInterruptedSession, formatInterruptedSessionRunningMessage, forma
 import { listUnitRuntimeRecords, clearUnitRuntimeRecord } from "./unit-runtime.js";
 import { resolveExpectedArtifactPath } from "./auto.js";
 import { gsdHome } from "./gsd-home.js";
-import { gsdRoot, milestonesDir, resolveMilestoneFile, resolveSliceFile, resolveSlicePath, resolveGsdRootFile, relGsdRootFile, relMilestoneFile, relSliceFile, } from "./paths.js";
+import { gsdRoot, milestonesDir, resolveMilestoneFile, resolveMilestonePath, resolveSliceFile, resolveSlicePath, resolveGsdRootFile, relGsdRootFile, relMilestoneFile, relSliceFile, clearPathCache, } from "./paths.js";
 import { join } from "node:path";
 import { readFileSync, existsSync, mkdirSync, readdirSync, rmSync, unlinkSync } from "node:fs";
 import { readSessionLockData, isSessionLockProcessAlive } from "./session-lock.js";
@@ -43,10 +43,39 @@ 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 { createWorkspace, scopeMilestone } from "./workspace.js";
 // ─── Re-exports (preserve public API for existing importers) ────────────────
 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";
+// ─── Scope-based validator wrappers ──────────────────────────────────────────
+// These thin wrappers accept a MilestoneScope so callers that already hold a
+// pinned scope never have to re-derive (basePath, milestoneId) separately.
+// The underlying implementations in auto-recovery.ts / auto-artifact-paths.ts /
+// state.ts are unchanged — only the call surface in guided-flow.ts is migrated.
+/**
+ * Scope-based overload of verifyExpectedArtifact.
+ * Uses scope.workspace.projectRoot as the authoritative base path, making
+ * the check immune to cwd-drift and worktree-path divergence.
+ */
+export function verifyExpectedArtifactForScope(scope, unitType, unitId) {
+    return verifyExpectedArtifact(unitType, unitId, scope.workspace.projectRoot);
+}
+/**
+ * Scope-based overload of resolveExpectedArtifactPath.
+ * Returns the canonical absolute path (or null) using the scope's projectRoot.
+ */
+export function resolveExpectedArtifactPathForScope(scope, unitType, unitId) {
+    return resolveExpectedArtifactPath(unitType, unitId, scope.workspace.projectRoot);
+}
+/**
+ * Scope-based overload of isGhostMilestone.
+ * Binds basePath and milestoneId from the scope, ensuring path resolution
+ * uses the canonical project root regardless of the cwd at call time.
+ */
+export function isGhostMilestoneByScope(scope) {
+    return isGhostMilestone(scope.workspace.projectRoot, scope.milestoneId);
+}
 function needsPlanV2Gate(state) {
     return state.phase === "executing"
         || state.phase === "summarizing"
@@ -77,6 +106,10 @@ function buildDocsCommitInstruction(_message) {
 // #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;
+// H1 (#5012): cap for Gate 1b plan-blocked recovery hints. After this many
+// consecutive recovery attempts the loop is stopped and the user is directed
+// to investigate manually.
+const MAX_PLAN_BLOCKED_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.
@@ -110,9 +143,9 @@ This stage is running inside the foreground \`/gsd new-project --deep\` intervie
 /**
  * Backward-compat bridge: returns a mutable reference to the entry matching
  * basePath, or the sole entry when only one session exists.
- * Internal use only — external code should use the Map directly.
+ * Exported for testing — internal use only in production code.
  */
-function _getPendingAutoStart(basePath) {
+export function _getPendingAutoStart(basePath) {
     if (basePath)
         return pendingAutoStartMap.get(basePath) ?? null;
     if (pendingAutoStartMap.size === 1)
@@ -157,7 +190,9 @@ function clearEmptyLegacyDeepSetupPseudoMilestones(basePath, entries) {
  * Exported for testing (#2985).
  */
 export function setPendingAutoStart(basePath, entry) {
-    pendingAutoStartMap.set(basePath, { createdAt: Date.now(), ...entry });
+    const ws = createWorkspace(entry.basePath);
+    const scope = scopeMilestone(ws, entry.milestoneId);
+    pendingAutoStartMap.set(basePath, { createdAt: Date.now(), planBlockedRecoveryCount: 0, ...entry, scope });
 }
 /**
  * Clear pending auto-start state.
@@ -249,6 +284,10 @@ export async function checkDeepProjectSetupAfterTurn(_event, ctx, basePath) {
     if (!entry)
         return false;
     if (entry.currentUnitType && entry.currentUnitId) {
+        // TODO(C-future): PendingDeepProjectSetupEntry does not carry a MilestoneScope
+        // because deep-project-setup units span non-milestone unit types (discuss-project,
+        // discuss-requirements, etc.).  Migrate to verifyExpectedArtifactForScope once
+        // PendingDeepProjectSetupEntry is extended with a scope field.
         const artifactReady = verifyExpectedArtifact(entry.currentUnitType, entry.currentUnitId, entry.basePath);
         if (!artifactReady) {
             return false;
@@ -320,17 +359,61 @@ export function checkAutoStartAfterDiscuss() {
     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.
-    const contextFile = resolveMilestoneFile(basePath, milestoneId, "CONTEXT");
-    const roadmapFile = resolveMilestoneFile(basePath, milestoneId, "ROADMAP");
+    // 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 1b: Discriminate plan-blocked from discuss-incomplete when the DB row is queued.
+    // If the DB is available and the row is still "queued" but CONTEXT.md already exists on
+    // disk, the discuss phase completed but gsd_plan_milestone was hard-blocked by the
+    // depth-verification gate.  Emit a recovery hint so the next agent turn can retry
+    // gsd_plan_milestone, then return false (keep blocking auto-start).
+    // If CONTEXT.md does not exist (discuss-incomplete), Gate 1 already blocked above.
+    if (isDbAvailable()) {
+        const dbRow = getMilestone(milestoneId);
+        if (dbRow?.status === "queued" && contextFile) {
+            if (entry.planBlockedRecoveryCount >= MAX_PLAN_BLOCKED_RECOVERIES) {
+                // H1: recovery loop cap reached — stop triggering new turns, escalate to user.
+                logWarning("guided", `Gate 1b: milestone ${milestoneId} plan-blocked recovery limit reached ` +
+                    `(${entry.planBlockedRecoveryCount}/${MAX_PLAN_BLOCKED_RECOVERIES}); escalating to user`);
+                ctx.ui.notify(`Milestone ${milestoneId} plan_milestone has been blocked ${entry.planBlockedRecoveryCount} times. ` +
+                    `Re-run /gsd to reset the recovery counter, or run /gsd-debug to diagnose without resetting.`, "error");
+                return false;
+            }
+            logWarning("guided", `Gate 1b: milestone ${milestoneId} queued with CONTEXT.md present — ` +
+                `plan_milestone was blocked; emitting recovery hint ` +
+                `(attempt ${entry.planBlockedRecoveryCount + 1}/${MAX_PLAN_BLOCKED_RECOVERIES})`);
+            ctx.ui.notify(`Milestone ${milestoneId}: context file exists but milestone is still queued. ` +
+                `Retrying gsd_plan_milestone to complete the blocked planning step.`, "warning");
+            try {
+                pi.sendMessage({
+                    customType: "gsd-plan-milestone-blocked-recovery",
+                    content: `Milestone ${milestoneId} has ${contextFile} on disk but its DB row is still ` +
+                        `"queued". The gsd_plan_milestone tool was previously blocked by the ` +
+                        `depth-verification gate. Call gsd_plan_milestone now to complete the ` +
+                        `planning phase.`,
+                    display: false,
+                }, { triggerTurn: true });
+                // Increment only after a successful dispatch so transient sendMessage
+                // failures do not consume recovery budget.
+                entry.planBlockedRecoveryCount += 1;
+            }
+            catch (e) {
+                logWarning("guided", `Gate 1b recovery sendMessage failed: ${e.message}`);
+            }
+            return false;
+        }
+    }
     // Gate 2: STATE.md must exist — written as the last step in the discuss
     // output phase. This prevents auto-start from firing during Phase 3
     // (sequential readiness gates for remaining milestones) in multi-milestone
     // discussions, where M001-CONTEXT.md exists but M002/M003 haven't been
     // processed yet.
-    const stateFile = resolveGsdRootFile(basePath, "STATE");
-    if (!stateFile)
+    const stateFilePath = entry.scope.stateFile();
+    if (!existsSync(stateFilePath))
         return false; // discussion not finalized yet
     // Gate 3: Multi-milestone completeness warning
     // Parse PROJECT.md for milestone sequence, warn if any are missing context.
@@ -362,7 +445,7 @@ export function checkAutoStartAfterDiscuss() {
     // 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(gsdRoot(basePath), "DISCUSSION-MANIFEST.json");
+    const manifestPath = join(entry.scope.workspace.contract.projectGsd, "DISCUSSION-MANIFEST.json");
     if (existsSync(manifestPath)) {
         try {
             const manifest = JSON.parse(readFileSync(manifestPath, "utf-8"));
@@ -486,12 +569,35 @@ export function maybeHandleReadyPhraseWithoutFiles(event) {
     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
@@ -576,14 +682,14 @@ export function maybeHandleEmptyIntentTurn(event, isAuto) {
     // path, handled by maybeHandleReadyPhraseWithoutFiles.
     if (READY_PHRASE_RE.test(text))
         return false;
-    // Skip if the LLM is clearly handing back to the user. Last-line `?` is
-    // the strongest signal, but discuss flows often end with a freeform
-    // question followed by a closing remark ("…what should we build? I'll
-    // pick one if you don't care."). Treat ANY non-empty line ending in `?`
-    // as a question-asked signal — false negatives here auto-reply to the
+    // 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.
-    const lines = text.split(/\r?\n/).map((l) => l.trim()).filter(Boolean);
-    if (lines.some((l) => l.endsWith("?")))
+    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))
@@ -873,7 +979,7 @@ export async function showHeadlessMilestoneCreation(ctx, pi, basePath, seedConte
     // Build and dispatch the headless discuss prompt
     const prompt = buildHeadlessDiscussPrompt(nextId, seedContext, basePath);
     // Set pending auto start (auto-mode triggers on "Milestone X ready." via checkAutoStartAfterDiscuss)
-    pendingAutoStartMap.set(basePath, { ctx, pi, basePath, milestoneId: nextId, createdAt: Date.now() });
+    setPendingAutoStart(basePath, { ctx, pi, basePath, milestoneId: nextId });
     // Dispatch as discuss-milestone. The LLM writes PROJECT.md, REQUIREMENTS.md,
     // and CONTEXT.md, then calls gsd_plan_milestone — this is semantically the
     // discuss path, just non-interactive. Using "plan-milestone" here caused
@@ -1039,13 +1145,13 @@ export async function showDiscuss(ctx, pi, basePath) {
             const seed = draftContent
                 ? `${basePrompt}\n\n## Prior Discussion (Draft Seed)\n\n${draftContent}`
                 : basePrompt;
-            pendingAutoStartMap.set(basePath, { ctx, pi, basePath, milestoneId: mid, step: false, createdAt: Date.now() });
+            setPendingAutoStart(basePath, { ctx, pi, basePath, milestoneId: mid, step: false });
             await dispatchWorkflow(pi, seed, "gsd-discuss", ctx, "discuss-milestone");
         }
         else if (choice === "discuss_fresh") {
             const discussMilestoneTemplates = inlineTemplate("context", "Context");
             const structuredQuestionsAvailable = getStructuredQuestionsAvailability(pi, ctx);
-            pendingAutoStartMap.set(basePath, { ctx, pi, basePath, milestoneId: mid, step: false, createdAt: Date.now() });
+            setPendingAutoStart(basePath, { ctx, pi, basePath, milestoneId: mid, step: false });
             await dispatchWorkflow(pi, loadPrompt("guided-discuss-milestone", {
                 milestoneId: mid, milestoneTitle, inlinedTemplates: discussMilestoneTemplates, structuredQuestionsAvailable,
                 commitInstruction: buildDocsCommitInstruction(`docs(${mid}): milestone context from discuss`),
@@ -1058,7 +1164,7 @@ export async function showDiscuss(ctx, pi, basePath) {
             const milestoneIds = findMilestoneIds(basePath);
             const uniqueMilestoneIds = !!loadEffectiveGSDPreferences()?.preferences?.unique_milestone_ids;
             const nextId = nextMilestoneIdReserved(milestoneIds, uniqueMilestoneIds, basePath);
-            pendingAutoStartMap.set(basePath, { ctx, pi, basePath, milestoneId: nextId, step: false, createdAt: Date.now() });
+            setPendingAutoStart(basePath, { ctx, pi, basePath, milestoneId: nextId, step: false });
             await dispatchWorkflow(pi, await prepareAndBuildDiscussPrompt(ctx, pi, nextId, `New milestone ${nextId}.`, basePath), "gsd-run", ctx, "discuss-milestone");
         }
         return;
@@ -1312,6 +1418,9 @@ function selfHealRuntimeRecords(basePath, ctx) {
         for (const record of records) {
             const { unitType, unitId, phase } = record;
             // Clear records whose expected artifact already exists (completed but not cleaned up)
+            // TODO(C-future): selfHealRuntimeRecords iterates across all unit types (not just milestone
+            // units), so it cannot be converted to resolveExpectedArtifactPathForScope without
+            // first establishing a per-record scope.  Migrate once unit runtime records carry scope info.
             const artifactPath = resolveExpectedArtifactPath(unitType, unitId, basePath);
             if (artifactPath && existsSync(artifactPath)) {
                 clearUnitRuntimeRecord(basePath, unitType, unitId);
@@ -1414,7 +1523,7 @@ async function handleMilestoneActions(ctx, pi, basePath, milestoneId, milestoneT
         const milestoneIds = findMilestoneIds(basePath);
         const uniqueMilestoneIds = !!loadEffectiveGSDPreferences()?.preferences?.unique_milestone_ids;
         const nextId = nextMilestoneIdReserved(milestoneIds, uniqueMilestoneIds, basePath);
-        pendingAutoStartMap.set(basePath, { ctx, pi, basePath, milestoneId: nextId, step: stepMode, createdAt: Date.now() });
+        setPendingAutoStart(basePath, { ctx, pi, basePath, milestoneId: nextId, step: stepMode });
         await dispatchWorkflow(pi, await prepareAndBuildDiscussPrompt(ctx, pi, nextId, `New milestone ${nextId}.`, basePath), "gsd-run", ctx, "discuss-milestone");
         return true;
     }
@@ -1619,7 +1728,7 @@ export async function showSmartEntry(ctx, pi, basePath, options) {
         const isFirst = milestoneIds.length === 0;
         if (isFirst) {
             // First ever — skip wizard, just ask directly
-            pendingAutoStartMap.set(basePath, { ctx, pi, basePath, milestoneId: nextId, step: stepMode, createdAt: Date.now() });
+            setPendingAutoStart(basePath, { ctx, pi, basePath, milestoneId: nextId, step: stepMode });
             await dispatchWorkflow(pi, await prepareAndBuildDiscussPrompt(ctx, pi, nextId, `New project, milestone ${nextId}. Do NOT read or explore .gsd/ — it's empty scaffolding.`, basePath), "gsd-run", ctx, "discuss-milestone");
         }
         else {
@@ -1637,7 +1746,7 @@ export async function showSmartEntry(ctx, pi, basePath, options) {
                 notYetMessage: "Run /gsd when ready.",
             });
             if (choice === "new_milestone") {
-                pendingAutoStartMap.set(basePath, { ctx, pi, basePath, milestoneId: nextId, step: stepMode, createdAt: Date.now() });
+                setPendingAutoStart(basePath, { ctx, pi, basePath, milestoneId: nextId, step: stepMode });
                 await dispatchWorkflow(pi, await prepareAndBuildDiscussPrompt(ctx, pi, nextId, `New milestone ${nextId}.`, basePath), "gsd-run", ctx, "discuss-milestone");
             }
         }
@@ -1646,7 +1755,7 @@ export async function showSmartEntry(ctx, pi, basePath, options) {
     const milestoneId = state.activeMilestone.id;
     const milestoneTitle = state.activeMilestone.title;
     if (planV2GateDecision === "recover-missing-context") {
-        pendingAutoStartMap.set(basePath, { ctx, pi, basePath, milestoneId, step: stepMode, createdAt: Date.now() });
+        setPendingAutoStart(basePath, { ctx, pi, basePath, milestoneId, step: stepMode });
         await dispatchWorkflow(pi, await buildDiscussMilestonePrompt(milestoneId, milestoneTitle, basePath, getStructuredQuestionsAvailability(pi, ctx)), "gsd-discuss", ctx, "discuss-milestone");
         return;
     }
@@ -1674,7 +1783,7 @@ export async function showSmartEntry(ctx, pi, basePath, options) {
             const milestoneIds = findMilestoneIds(basePath);
             const uniqueMilestoneIds = !!loadEffectiveGSDPreferences()?.preferences?.unique_milestone_ids;
             const nextId = nextMilestoneIdReserved(milestoneIds, uniqueMilestoneIds, basePath);
-            pendingAutoStartMap.set(basePath, { ctx, pi, basePath, milestoneId: nextId, step: stepMode, createdAt: Date.now() });
+            setPendingAutoStart(basePath, { ctx, pi, basePath, milestoneId: nextId, step: stepMode });
             await dispatchWorkflow(pi, await prepareAndBuildDiscussPrompt(ctx, pi, nextId, `New milestone ${nextId}.`, basePath), "gsd-run", ctx, "discuss-milestone");
         }
         else if (choice === "status") {
@@ -1721,13 +1830,13 @@ export async function showSmartEntry(ctx, pi, basePath, options) {
             const seed = draftContent
                 ? `${basePrompt}\n\n## Prior Discussion (Draft Seed)\n\n${draftContent}`
                 : basePrompt;
-            pendingAutoStartMap.set(basePath, { ctx, pi, basePath, milestoneId, step: stepMode, createdAt: Date.now() });
+            setPendingAutoStart(basePath, { ctx, pi, basePath, milestoneId, step: stepMode });
             await dispatchWorkflow(pi, seed, "gsd-discuss", ctx, "discuss-milestone");
         }
         else if (choice === "discuss_fresh") {
             const discussMilestoneTemplates = inlineTemplate("context", "Context");
             const structuredQuestionsAvailable = getStructuredQuestionsAvailability(pi, ctx);
-            pendingAutoStartMap.set(basePath, { ctx, pi, basePath, milestoneId, step: stepMode, createdAt: Date.now() });
+            setPendingAutoStart(basePath, { ctx, pi, basePath, milestoneId, step: stepMode });
             await dispatchWorkflow(pi, loadPrompt("guided-discuss-milestone", {
                 milestoneId, milestoneTitle, inlinedTemplates: discussMilestoneTemplates, structuredQuestionsAvailable,
                 commitInstruction: buildDocsCommitInstruction(`docs(${milestoneId}): milestone context from discuss`),
@@ -1738,7 +1847,7 @@ export async function showSmartEntry(ctx, pi, basePath, options) {
             const milestoneIds = findMilestoneIds(basePath);
             const uniqueMilestoneIds = !!loadEffectiveGSDPreferences()?.preferences?.unique_milestone_ids;
             const nextId = nextMilestoneIdReserved(milestoneIds, uniqueMilestoneIds, basePath);
-            pendingAutoStartMap.set(basePath, { ctx, pi, basePath, milestoneId: nextId, step: stepMode, createdAt: Date.now() });
+            setPendingAutoStart(basePath, { ctx, pi, basePath, milestoneId: nextId, step: stepMode });
             await dispatchWorkflow(pi, await prepareAndBuildDiscussPrompt(ctx, pi, nextId, `New milestone ${nextId}.`, basePath), "gsd-run", ctx, "discuss-milestone");
         }
         return;
@@ -1794,7 +1903,7 @@ export async function showSmartEntry(ctx, pi, basePath, options) {
                 notYetMessage: "Run /gsd when ready.",
             });
             if (choice === "plan") {
-                pendingAutoStartMap.set(basePath, { ctx, pi, basePath, milestoneId, step: stepMode, createdAt: Date.now() });
+                setPendingAutoStart(basePath, { ctx, pi, basePath, milestoneId, step: stepMode });
                 await dispatchWorkflow(pi, await buildPlanMilestonePrompt(milestoneId, milestoneTitle, basePath), "gsd-run", ctx, "plan-milestone");
             }
             else if (choice === "discuss") {
@@ -1810,7 +1919,7 @@ export async function showSmartEntry(ctx, pi, basePath, options) {
                 const milestoneIds = findMilestoneIds(basePath);
                 const uniqueMilestoneIds = !!loadEffectiveGSDPreferences()?.preferences?.unique_milestone_ids;
                 const nextId = nextMilestoneIdReserved(milestoneIds, uniqueMilestoneIds, basePath);
-                pendingAutoStartMap.set(basePath, { ctx, pi, basePath, milestoneId: nextId, step: stepMode, createdAt: Date.now() });
+                setPendingAutoStart(basePath, { ctx, pi, basePath, milestoneId: nextId, step: stepMode });
                 await dispatchWorkflow(pi, await prepareAndBuildDiscussPrompt(ctx, pi, nextId, `New milestone ${nextId}.`, basePath), "gsd-run", ctx, "discuss-milestone");
             }
             else if (choice === "discard_milestone") {

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

@@ -1,9 +1,8 @@
 // GSD Markdown Renderer — DB → Markdown file generation
 //
 // Transforms DB state into correct markdown files on disk.
-// Each render function reads from DB (with disk fallback),
-// patches content to match DB status, writes atomically to disk,
-// stores updated content in the artifacts table, and invalidates caches.
+// Each render function reads from DB, writes a markdown projection to disk,
+// stores generated content in the artifacts table, and invalidates caches.
 //
 // Critical invariant: rendered markdown must round-trip through
 // parseRoadmap(), parsePlan(), parseSummary() in files.ts.
@@ -60,45 +59,16 @@ function taskSummaryForSlicePlan(description) {
     return firstBlock || beforeHeading;
 }
 /**
- * Load artifact content from DB first, falling back to reading from disk.
- * On disk fallback, stores the content in the artifacts table for future use.
- * Returns null if content is unavailable from both sources.
+ * Load artifact content from the DB. Markdown projections are not authoritative
+ * during runtime; when the artifact row is missing, callers regenerate from DB
+ * rows instead of patching disk fallback content and storing it back.
  */
-function loadArtifactContent(artifactPath, absPath, opts) {
-    // Try DB first
+function loadArtifactContent(artifactPath) {
     const artifact = getArtifact(artifactPath);
     if (artifact && artifact.full_content) {
         return artifact.full_content;
     }
-    // Fall back to disk
-    if (!absPath) {
-        process.stderr.write(`markdown-renderer: artifact not found in DB or on disk: ${artifactPath}\n`);
-        return null;
-    }
-    let content;
-    try {
-        content = readFileSync(absPath, "utf-8");
-    }
-    catch {
-        logWarning("renderer", `cannot read file from disk: ${absPath}`);
-        return null;
-    }
-    // Store in DB for future use (graceful degradation path)
-    try {
-        insertArtifact({
-            path: artifactPath,
-            artifact_type: opts.artifact_type,
-            milestone_id: opts.milestone_id,
-            slice_id: opts.slice_id ?? null,
-            task_id: opts.task_id ?? null,
-            full_content: content,
-        });
-    }
-    catch {
-        // Non-fatal: we have the content, DB storage is best-effort
-        logWarning("renderer", `failed to store disk fallback in DB: ${artifactPath}`);
-    }
-    return content;
+    return null;
 }
 /**
  * Write rendered content to disk and update the artifacts table.
@@ -401,17 +371,14 @@ export async function renderRoadmapCheckboxes(basePath, milestoneId) {
     }
     const absPath = resolveMilestoneFile(basePath, milestoneId, "ROADMAP");
     const artifactPath = absPath ? toArtifactPath(absPath, basePath) : null;
-    // Load content from DB (with disk fallback)
+    // Load content from DB; regenerate from DB rows when the artifact is absent.
     let content = null;
     if (artifactPath) {
-        content = loadArtifactContent(artifactPath, absPath, {
-            artifact_type: "ROADMAP",
-            milestone_id: milestoneId,
-        });
+        content = loadArtifactContent(artifactPath);
     }
     if (!content) {
-        process.stderr.write(`markdown-renderer: no roadmap content available for ${milestoneId}\n`);
-        return false;
+        await renderRoadmapFromDb(basePath, milestoneId);
+        return true;
     }
     // Apply checkbox patches for each slice
     let updated = content;
@@ -454,15 +421,11 @@ export async function renderPlanCheckboxes(basePath, milestoneId, sliceId) {
     const artifactPath = absPath ? toArtifactPath(absPath, basePath) : null;
     let content = null;
     if (artifactPath) {
-        content = loadArtifactContent(artifactPath, absPath, {
-            artifact_type: "PLAN",
-            milestone_id: milestoneId,
-            slice_id: sliceId,
-        });
+        content = loadArtifactContent(artifactPath);
     }
     if (!content) {
-        process.stderr.write(`markdown-renderer: no plan content available for ${milestoneId}/${sliceId}\n`);
-        return false;
+        await renderPlanFromDb(basePath, milestoneId, sliceId);
+        return true;
     }
     // Apply checkbox patches for each task
     let updated = content;