gsd-pi 2.65.0-dev.5c8557b → 2.65.0-dev.d0517ff

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

@@ -6,7 +6,7 @@
  * No execution state, no hooks, no tools — the LLM does the rest.
  */
 import { showNextAction } from "../shared/tui.js";
-import { loadFile } from "./files.js";
+import { loadFile, saveFile } from "./files.js";
 import { isDbAvailable, getMilestoneSlices } from "./gsd-db.js";
 import { parseRoadmapSlices } from "./roadmap-slices.js";
 import { loadPrompt, inlineTemplate } from "./prompt-loader.js";
@@ -34,6 +34,19 @@ import { findMilestoneIds, nextMilestoneId, reserveMilestoneId, getReservedMiles
 import { parkMilestone, discardMilestone } from "./milestone-actions.js";
 import { selectAndApplyModel } from "./auto-model-selection.js";
 import { DISCUSS_TOOLS_ALLOWLIST } from "./constants.js";
+import { runPreparation, formatCodebaseBrief, formatPriorContextBrief, formatEcosystemBrief, } from "./preparation.js";
+// ─── Preparation result storage ─────────────────────────────────────────────
+// Stores the most recent preparation result for injection into discuss prompts.
+// S02 will consume this when building the prepared discussion prompt.
+let lastPreparationResult = null;
+/** Get the most recent preparation result (for S02 prompt building). */
+export function getLastPreparationResult() {
+    return lastPreparationResult;
+}
+/** Clear the preparation result (called after discussion completes). */
+export function clearPreparationResult() {
+    lastPreparationResult = null;
+}
 // ─── 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";
@@ -74,7 +87,7 @@ function _getPendingAutoStart(basePath) {
  * Exported for testing (#2985).
  */
 export function setPendingAutoStart(basePath, entry) {
-    pendingAutoStartMap.set(basePath, entry);
+    pendingAutoStartMap.set(basePath, { createdAt: Date.now(), ...entry });
 }
 /**
  * Clear pending auto-start state.
@@ -248,8 +261,10 @@ async function dispatchWorkflow(pi, note, customType = "gsd-run", ctx, unitType)
     // "Grammar is too complex" when the combined tool schema is too large.
     // Discuss flows only need a small subset of GSD tools — strip the heavy
     // planning/execution/completion tools to keep the grammar within limits.
+    let savedTools = null;
     if (unitType?.startsWith("discuss-")) {
         const currentTools = pi.getActiveTools();
+        savedTools = currentTools;
         // Keep all non-GSD tools (builtins, other extensions) and only the
         // GSD tools on the discuss allowlist.
         const scopedTools = currentTools.filter((t) => !t.startsWith("gsd_") || DISCUSS_TOOLS_ALLOWLIST.includes(t));
@@ -268,6 +283,12 @@ async function dispatchWorkflow(pi, note, customType = "gsd-run", ctx, unitType)
         content: `Read the following GSD workflow protocol and execute exactly.\n\n${workflow}\n\n## Your Task\n\n${note}`,
         display: false,
     }, { triggerTurn: true });
+    // Restore full tool set after the message is queued. The LLM turn has
+    // already captured the scoped set — restoring prevents the narrowed
+    // tools from leaking into subsequent dispatches (#3628).
+    if (savedTools) {
+        pi.setActiveTools(savedTools);
+    }
 }
 /**
  * Resolve a model ID string to a model object from available models.
@@ -340,6 +361,86 @@ function buildHeadlessDiscussPrompt(nextId, seedContext, _basePath) {
         multiMilestoneCommitInstruction: buildDocsCommitInstruction("docs: project plan — N milestones"),
     });
 }
+/**
+ * Build the prepared discuss prompt with brief injection.
+ * Uses the discuss-prepared template which encodes the 4-layer discussion protocol.
+ *
+ * @param nextId - The milestone ID being discussed
+ * @param preamble - Preamble text for the discuss prompt
+ * @param _basePath - Root directory of the project (unused, kept for signature consistency)
+ * @param prepResult - Preparation result containing briefs to inject
+ * @returns The prepared discuss prompt string
+ */
+function buildPreparedPrompt(nextId, preamble, _basePath, prepResult) {
+    const milestoneRel = `.gsd/milestones/${nextId}`;
+    // Use context-enhanced instead of context for prepared discussions
+    const inlinedTemplates = [
+        inlineTemplate("project", "Project"),
+        inlineTemplate("requirements", "Requirements"),
+        inlineTemplate("context-enhanced", "Context Enhanced"),
+        inlineTemplate("roadmap", "Roadmap"),
+        inlineTemplate("decisions", "Decisions"),
+    ].join("\n\n---\n\n");
+    // Format the briefs from the preparation result
+    const codebaseBrief = prepResult.codebaseBrief || formatCodebaseBrief(prepResult.codebase);
+    const priorContextBrief = prepResult.priorContextBrief || formatPriorContextBrief(prepResult.priorContext);
+    const ecosystemBrief = prepResult.ecosystemBrief || formatEcosystemBrief(prepResult.ecosystem);
+    return loadPrompt("discuss-prepared", {
+        milestoneId: nextId,
+        preamble,
+        codebaseBrief,
+        priorContextBrief,
+        ecosystemBrief,
+        contextPath: `${milestoneRel}/${nextId}-CONTEXT.md`,
+        roadmapPath: `${milestoneRel}/${nextId}-ROADMAP.md`,
+        inlinedTemplates,
+        commitInstruction: buildDocsCommitInstruction(`docs(${nextId}): context, requirements, and roadmap`),
+        multiMilestoneCommitInstruction: buildDocsCommitInstruction("docs: project plan — N milestones"),
+    });
+}
+/**
+ * Run preparation phase if enabled, then build the discuss prompt.
+ * This is the main entry point for new milestone discussions with preparation.
+ * Stores the preparation result for S02 to inject into the discuss prompt.
+ *
+ * When preparation succeeds, uses the discuss-prepared template with brief injection.
+ * Falls back to the standard discuss template when preparation is disabled or fails.
+ *
+ * @param ctx - Extension command context with UI for progress notifications
+ * @param nextId - The milestone ID being discussed
+ * @param preamble - Preamble text for the discuss prompt
+ * @param basePath - Root directory of the project
+ * @returns The discuss prompt string
+ */
+async function prepareAndBuildDiscussPrompt(ctx, nextId, preamble, basePath) {
+    // Clear stale preparation result immediately to prevent cross-session/project
+    // state leaks. This ensures data from a prior milestone/project never leaks
+    // into subsequent discussions (adversarial review fix #3602).
+    lastPreparationResult = null;
+    const prefs = loadEffectiveGSDPreferences()?.preferences ?? {};
+    // Run preparation if enabled (default: true)
+    if (prefs.discuss_preparation !== false) {
+        try {
+            const prepResult = await runPreparation(basePath, ctx.ui, {
+                discuss_preparation: prefs.discuss_preparation,
+                discuss_web_research: prefs.discuss_web_research,
+                discuss_depth: prefs.discuss_depth,
+            });
+            lastPreparationResult = prepResult;
+            // Use prepared prompt if preparation was enabled and produced results
+            if (prepResult.enabled) {
+                return buildPreparedPrompt(nextId, preamble, basePath, prepResult);
+            }
+        }
+        catch {
+            // If preparation throws, ensure stale data doesn't persist
+            lastPreparationResult = null;
+        }
+    }
+    // Fall back to standard discuss prompt for backward compatibility
+    // lastPreparationResult is already null (cleared at entry or on error)
+    return buildDiscussPrompt(nextId, preamble, basePath);
+}
 /**
  * Bootstrap a .gsd/ project from scratch for headless use.
  * Ensures git repo, .gsd/ structure, gitignore, and preferences all exist.
@@ -376,7 +477,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 });
+    pendingAutoStartMap.set(basePath, { ctx, pi, basePath, milestoneId: nextId, createdAt: Date.now() });
     // Dispatch — headless milestone creation is a planning activity
     await dispatchWorkflow(pi, prompt, "gsd-run", ctx, "plan-milestone");
 }
@@ -457,6 +558,7 @@ async function buildDiscussSlicePrompt(mid, sid, sTitle, base, options) {
         contextPath: sliceContextPath,
         projectRoot: base,
         inlinedTemplates,
+        structuredQuestionsAvailable: options?.structuredQuestionsAvailable ?? "false",
         commitInstruction: buildDocsCommitInstruction(`docs(${mid}/${sid}): slice context from discuss`),
     });
 }
@@ -474,6 +576,16 @@ export async function showDiscuss(ctx, pi, basePath) {
     // Invalidate caches to pick up artifacts written by a just-completed discuss/plan
     invalidateAllCaches();
     const state = await deriveState(basePath);
+    // Rebuild STATE.md from derived state before any dispatch (#3475).
+    // Without this, guided prompts read a stale STATE.md cache and the
+    // agent bootstraps from the wrong milestone.
+    try {
+        const { buildStateMarkdown } = await import("./doctor.js");
+        await saveFile(resolveGsdRootFile(basePath, "STATE"), buildStateMarkdown(state));
+    }
+    catch (err) {
+        logWarning("guided", `STATE.md rebuild failed: ${err.message}`);
+    }
     // No active milestone (or corrupted milestone with undefined id) —
     // check for pending milestones to discuss instead
     if (!state.activeMilestone?.id) {
@@ -521,28 +633,30 @@ export async function showDiscuss(ctx, pi, basePath) {
             const basePrompt = loadPrompt("guided-discuss-milestone", {
                 milestoneId: mid, milestoneTitle, inlinedTemplates: discussMilestoneTemplates, structuredQuestionsAvailable,
                 commitInstruction: buildDocsCommitInstruction(`docs(${mid}): milestone context from discuss`),
+                fastPathInstruction: "",
             });
             const seed = draftContent
                 ? `${basePrompt}\n\n## Prior Discussion (Draft Seed)\n\n${draftContent}`
                 : basePrompt;
-            pendingAutoStartMap.set(basePath, { ctx, pi, basePath, milestoneId: mid, step: false });
+            pendingAutoStartMap.set(basePath, { ctx, pi, basePath, milestoneId: mid, step: false, createdAt: Date.now() });
             await dispatchWorkflow(pi, seed, "gsd-discuss", ctx, "discuss-milestone");
         }
         else if (choice === "discuss_fresh") {
             const discussMilestoneTemplates = inlineTemplate("context", "Context");
             const structuredQuestionsAvailable = pi.getActiveTools().includes("ask_user_questions") ? "true" : "false";
-            pendingAutoStartMap.set(basePath, { ctx, pi, basePath, milestoneId: mid, step: false });
+            pendingAutoStartMap.set(basePath, { ctx, pi, basePath, milestoneId: mid, step: false, createdAt: Date.now() });
             await dispatchWorkflow(pi, loadPrompt("guided-discuss-milestone", {
                 milestoneId: mid, milestoneTitle, inlinedTemplates: discussMilestoneTemplates, structuredQuestionsAvailable,
                 commitInstruction: buildDocsCommitInstruction(`docs(${mid}): milestone context from discuss`),
+                fastPathInstruction: "",
             }), "gsd-discuss", ctx, "discuss-milestone");
         }
         else if (choice === "skip_milestone") {
             const milestoneIds = findMilestoneIds(basePath);
             const uniqueMilestoneIds = !!loadEffectiveGSDPreferences()?.preferences?.unique_milestone_ids;
             const nextId = nextMilestoneIdReserved(milestoneIds, uniqueMilestoneIds);
-            pendingAutoStartMap.set(basePath, { ctx, pi, basePath, milestoneId: nextId, step: false });
-            await dispatchWorkflow(pi, buildDiscussPrompt(nextId, `New milestone ${nextId}.`, basePath), "gsd-run", ctx, "discuss-milestone");
+            pendingAutoStartMap.set(basePath, { ctx, pi, basePath, milestoneId: nextId, step: false, createdAt: Date.now() });
+            await dispatchWorkflow(pi, await prepareAndBuildDiscussPrompt(ctx, nextId, `New milestone ${nextId}.`, basePath), "gsd-run", ctx, "discuss-milestone");
         }
         return;
     }
@@ -672,7 +786,8 @@ export async function showDiscuss(ctx, pi, basePath) {
             if (confirm !== "rediscuss")
                 continue;
         }
-        const prompt = await buildDiscussSlicePrompt(mid, chosen.id, chosen.title, basePath, { rediscuss: isRediscuss });
+        const sqAvail = pi.getActiveTools().includes("ask_user_questions") ? "true" : "false";
+        const prompt = await buildDiscussSlicePrompt(mid, chosen.id, chosen.title, basePath, { rediscuss: isRediscuss, structuredQuestionsAvailable: sqAvail });
         await dispatchWorkflow(pi, prompt, "gsd-discuss", ctx, "discuss-slice");
         // Wait for the discuss session to finish, then loop back to the picker
         await ctx.waitForIdle();
@@ -712,16 +827,55 @@ async function showDiscussQueuedMilestone(ctx, pi, basePath, pendingMilestones)
     const chosen = pendingMilestones.find(m => m.id === choice);
     if (!chosen)
         return;
-    await dispatchDiscussForMilestone(ctx, pi, basePath, chosen.id, chosen.title);
+    const hasDraft = !!resolveMilestoneFile(basePath, chosen.id, "CONTEXT-DRAFT");
+    let fastPath = hasDraft;
+    if (!hasDraft) {
+        const mode = await showNextAction(ctx, {
+            title: `Discuss ${chosen.id}`,
+            summary: [
+                "Choose how to start the discussion.",
+                "Fast path skips generic scouting — use it when you already know the scope.",
+            ],
+            actions: [
+                {
+                    id: "full",
+                    label: "Full discussion",
+                    description: "Scout the codebase, ask open-ended questions, explore deeply",
+                    recommended: true,
+                },
+                {
+                    id: "fast",
+                    label: "I have the scope — fast path",
+                    description: "Treat your first message as authoritative seed context; skip scouting",
+                },
+            ],
+            notYetMessage: "Run /gsd discuss when ready.",
+        });
+        if (mode === "not_yet")
+            return;
+        fastPath = mode === "fast";
+    }
+    await dispatchDiscussForMilestone(ctx, pi, basePath, chosen.id, chosen.title, { fastPath });
 }
 /**
  * Dispatch the guided-discuss-milestone prompt for a milestone without
  * setting pendingAutoStart — so discussing a queued milestone does not
  * implicitly activate it when the session ends.
  */
-async function dispatchDiscussForMilestone(ctx, pi, basePath, mid, milestoneTitle) {
+async function dispatchDiscussForMilestone(ctx, pi, basePath, mid, milestoneTitle, opts = {}) {
     const draftFile = resolveMilestoneFile(basePath, mid, "CONTEXT-DRAFT");
     const draftContent = draftFile ? await loadFile(draftFile) : null;
+    const hasSeed = !!(draftContent || opts.fastPath);
+    const fastPathInstruction = hasSeed
+        ? [
+            "> **Fast path active — scope provided.**",
+            "> Do NOT perform a generic codebase scouting pass.",
+            "> Do at most 2 targeted reads to check for obvious conflicts with existing work.",
+            "> Treat the seed context or the operator's first message as authoritative.",
+            "> Move directly to the depth summary and write step.",
+            "> Ask only questions where the answer would materially change scope.",
+        ].join("\n")
+        : "";
     const discussMilestoneTemplates = inlineTemplate("context", "Context");
     const structuredQuestionsAvailable = pi.getActiveTools().includes("ask_user_questions") ? "true" : "false";
     const basePrompt = loadPrompt("guided-discuss-milestone", {
@@ -730,6 +884,7 @@ async function dispatchDiscussForMilestone(ctx, pi, basePath, mid, milestoneTitl
         inlinedTemplates: discussMilestoneTemplates,
         structuredQuestionsAvailable,
         commitInstruction: buildDocsCommitInstruction(`docs(${mid}): milestone context from discuss`),
+        fastPathInstruction,
     });
     const prompt = draftContent
         ? `${basePrompt}\n\n## Prior Discussion (Draft Seed)\n\n${draftContent}`
@@ -856,8 +1011,8 @@ async function handleMilestoneActions(ctx, pi, basePath, milestoneId, milestoneT
         const milestoneIds = findMilestoneIds(basePath);
         const uniqueMilestoneIds = !!loadEffectiveGSDPreferences()?.preferences?.unique_milestone_ids;
         const nextId = nextMilestoneIdReserved(milestoneIds, uniqueMilestoneIds);
-        pendingAutoStartMap.set(basePath, { ctx, pi, basePath, milestoneId: nextId, step: stepMode });
-        await dispatchWorkflow(pi, buildDiscussPrompt(nextId, `New milestone ${nextId}.`, basePath), "gsd-run", ctx, "discuss-milestone");
+        pendingAutoStartMap.set(basePath, { ctx, pi, basePath, milestoneId: nextId, step: stepMode, createdAt: Date.now() });
+        await dispatchWorkflow(pi, await prepareAndBuildDiscussPrompt(ctx, nextId, `New milestone ${nextId}.`, basePath), "gsd-run", ctx, "discuss-milestone");
         return true;
     }
     // "back" or null
@@ -955,14 +1110,35 @@ export async function showSmartEntry(ctx, pi, basePath, options) {
         }
     }
     const state = await deriveState(basePath);
+    // Rebuild STATE.md from derived state before any dispatch (#3475).
+    try {
+        const { buildStateMarkdown } = await import("./doctor.js");
+        await saveFile(resolveGsdRootFile(basePath, "STATE"), buildStateMarkdown(state));
+    }
+    catch (err) {
+        logWarning("guided", `STATE.md rebuild failed: ${err.message}`);
+    }
     if (!state.activeMilestone?.id) {
         // Guard: if a discuss session is already in flight, don't re-inject the prompt.
         // Both /gsd and /gsd auto reach this branch when no milestone exists yet.
         // Without this guard, every subsequent /gsd call overwrites the pending auto-start
         // and fires another dispatchWorkflow, resetting the conversation mid-interview.
         if (pendingAutoStartMap.has(basePath)) {
-            ctx.ui.notify("Discussion already in progress — answer the question above to continue.", "info");
-            return;
+            // #3274: If /clear interrupted the discussion, the pending entry is stale.
+            // Detect staleness: no manifest, no CONTEXT.md, AND entry is older than
+            // 30s (avoids race between .set() and LLM writing first artifact).
+            const entry = pendingAutoStartMap.get(basePath);
+            const ageMs = Date.now() - (entry.createdAt || 0);
+            const manifestExists = existsSync(join(gsdRoot(basePath), "DISCUSSION-MANIFEST.json"));
+            const milestoneHasContext = existsSync(join(gsdRoot(basePath), "milestones", entry.milestoneId, `${entry.milestoneId}-CONTEXT.md`));
+            if (!manifestExists && !milestoneHasContext && ageMs > 30_000) {
+                // Stale entry from an interrupted discussion — clear and continue
+                pendingAutoStartMap.delete(basePath);
+            }
+            else {
+                ctx.ui.notify("Discussion already in progress — answer the question above to continue.", "info");
+                return;
+            }
         }
         const milestoneIds = findMilestoneIds(basePath);
         // Sanity check (#456): if findMilestoneIds returns [] but the milestones
@@ -989,8 +1165,8 @@ 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 });
-            await dispatchWorkflow(pi, buildDiscussPrompt(nextId, `New project, milestone ${nextId}. Do NOT read or explore .gsd/ — it's empty scaffolding.`, basePath), "gsd-run", ctx, "discuss-milestone");
+            pendingAutoStartMap.set(basePath, { ctx, pi, basePath, milestoneId: nextId, step: stepMode, createdAt: Date.now() });
+            await dispatchWorkflow(pi, await prepareAndBuildDiscussPrompt(ctx, nextId, `New project, milestone ${nextId}. Do NOT read or explore .gsd/ — it's empty scaffolding.`, basePath), "gsd-run", ctx, "discuss-milestone");
         }
         else {
             const choice = await showNextAction(ctx, {
@@ -1007,8 +1183,8 @@ 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 });
-                await dispatchWorkflow(pi, buildDiscussPrompt(nextId, `New milestone ${nextId}.`, basePath), "gsd-run", ctx, "discuss-milestone");
+                pendingAutoStartMap.set(basePath, { ctx, pi, basePath, milestoneId: nextId, step: stepMode, createdAt: Date.now() });
+                await dispatchWorkflow(pi, await prepareAndBuildDiscussPrompt(ctx, nextId, `New milestone ${nextId}.`, basePath), "gsd-run", ctx, "discuss-milestone");
             }
         }
         return;
@@ -1039,8 +1215,8 @@ export async function showSmartEntry(ctx, pi, basePath, options) {
             const milestoneIds = findMilestoneIds(basePath);
             const uniqueMilestoneIds = !!loadEffectiveGSDPreferences()?.preferences?.unique_milestone_ids;
             const nextId = nextMilestoneIdReserved(milestoneIds, uniqueMilestoneIds);
-            pendingAutoStartMap.set(basePath, { ctx, pi, basePath, milestoneId: nextId, step: stepMode });
-            await dispatchWorkflow(pi, buildDiscussPrompt(nextId, `New milestone ${nextId}.`, basePath), "gsd-run", ctx, "discuss-milestone");
+            pendingAutoStartMap.set(basePath, { ctx, pi, basePath, milestoneId: nextId, step: stepMode, createdAt: Date.now() });
+            await dispatchWorkflow(pi, await prepareAndBuildDiscussPrompt(ctx, nextId, `New milestone ${nextId}.`, basePath), "gsd-run", ctx, "discuss-milestone");
         }
         else if (choice === "status") {
             const { fireStatusViaCommand } = await import("./commands.js");
@@ -1081,28 +1257,30 @@ export async function showSmartEntry(ctx, pi, basePath, options) {
             const basePrompt = loadPrompt("guided-discuss-milestone", {
                 milestoneId, milestoneTitle, inlinedTemplates: discussMilestoneTemplates, structuredQuestionsAvailable,
                 commitInstruction: buildDocsCommitInstruction(`docs(${milestoneId}): milestone context from discuss`),
+                fastPathInstruction: "",
             });
             const seed = draftContent
                 ? `${basePrompt}\n\n## Prior Discussion (Draft Seed)\n\n${draftContent}`
                 : basePrompt;
-            pendingAutoStartMap.set(basePath, { ctx, pi, basePath, milestoneId, step: stepMode });
+            pendingAutoStartMap.set(basePath, { ctx, pi, basePath, milestoneId, step: stepMode, createdAt: Date.now() });
             await dispatchWorkflow(pi, seed, "gsd-discuss", ctx, "discuss-milestone");
         }
         else if (choice === "discuss_fresh") {
             const discussMilestoneTemplates = inlineTemplate("context", "Context");
             const structuredQuestionsAvailable = pi.getActiveTools().includes("ask_user_questions") ? "true" : "false";
-            pendingAutoStartMap.set(basePath, { ctx, pi, basePath, milestoneId, step: stepMode });
+            pendingAutoStartMap.set(basePath, { ctx, pi, basePath, milestoneId, step: stepMode, createdAt: Date.now() });
             await dispatchWorkflow(pi, loadPrompt("guided-discuss-milestone", {
                 milestoneId, milestoneTitle, inlinedTemplates: discussMilestoneTemplates, structuredQuestionsAvailable,
                 commitInstruction: buildDocsCommitInstruction(`docs(${milestoneId}): milestone context from discuss`),
+                fastPathInstruction: "",
             }), "gsd-discuss", ctx, "discuss-milestone");
         }
         else if (choice === "skip_milestone") {
             const milestoneIds = findMilestoneIds(basePath);
             const uniqueMilestoneIds = !!loadEffectiveGSDPreferences()?.preferences?.unique_milestone_ids;
             const nextId = nextMilestoneIdReserved(milestoneIds, uniqueMilestoneIds);
-            pendingAutoStartMap.set(basePath, { ctx, pi, basePath, milestoneId: nextId, step: stepMode });
-            await dispatchWorkflow(pi, buildDiscussPrompt(nextId, `New milestone ${nextId}.`, basePath), "gsd-run", ctx, "discuss-milestone");
+            pendingAutoStartMap.set(basePath, { ctx, pi, basePath, milestoneId: nextId, step: stepMode, createdAt: Date.now() });
+            await dispatchWorkflow(pi, await prepareAndBuildDiscussPrompt(ctx, nextId, `New milestone ${nextId}.`, basePath), "gsd-run", ctx, "discuss-milestone");
         }
         return;
     }
@@ -1110,7 +1288,18 @@ export async function showSmartEntry(ctx, pi, basePath, options) {
     if (!state.activeSlice) {
         const roadmapFile = resolveMilestoneFile(basePath, milestoneId, "ROADMAP");
         const hasRoadmap = !!(roadmapFile && await loadFile(roadmapFile));
-        if (!hasRoadmap) {
+        // A roadmap file with zero parseable slices (placeholder text) should be
+        // treated the same as no roadmap — offer "Create roadmap" instead of "Go auto"
+        // which would immediately get stuck in blocked state (#3441).
+        let roadmapHasSlices = false;
+        if (hasRoadmap) {
+            const roadmapContent = await loadFile(roadmapFile);
+            if (roadmapContent) {
+                const parsed = parseRoadmapSlices(roadmapContent);
+                roadmapHasSlices = parsed.length > 0;
+            }
+        }
+        if (!hasRoadmap || !roadmapHasSlices) {
             // No roadmap → discuss or plan
             const contextFile = resolveMilestoneFile(basePath, milestoneId, "CONTEXT");
             const hasContext = !!(contextFile && await loadFile(contextFile));
@@ -1146,7 +1335,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 });
+                pendingAutoStartMap.set(basePath, { ctx, pi, basePath, milestoneId, step: stepMode, createdAt: Date.now() });
                 const planMilestoneTemplates = [
                     inlineTemplate("roadmap", "Roadmap"),
                     inlineTemplate("plan", "Slice Plan"),
@@ -1173,14 +1362,15 @@ export async function showSmartEntry(ctx, pi, basePath, options) {
                 await dispatchWorkflow(pi, loadPrompt("guided-discuss-milestone", {
                     milestoneId, milestoneTitle, inlinedTemplates: discussMilestoneTemplates, structuredQuestionsAvailable,
                     commitInstruction: buildDocsCommitInstruction(`docs(${milestoneId}): milestone context from discuss`),
+                    fastPathInstruction: "",
                 }), "gsd-run", ctx, "discuss-milestone");
             }
             else if (choice === "skip_milestone") {
                 const milestoneIds = findMilestoneIds(basePath);
                 const uniqueMilestoneIds = !!loadEffectiveGSDPreferences()?.preferences?.unique_milestone_ids;
                 const nextId = nextMilestoneIdReserved(milestoneIds, uniqueMilestoneIds);
-                pendingAutoStartMap.set(basePath, { ctx, pi, basePath, milestoneId: nextId, step: stepMode });
-                await dispatchWorkflow(pi, buildDiscussPrompt(nextId, `New milestone ${nextId}.`, basePath), "gsd-run", ctx, "discuss-milestone");
+                pendingAutoStartMap.set(basePath, { ctx, pi, basePath, milestoneId: nextId, step: stepMode, createdAt: Date.now() });
+                await dispatchWorkflow(pi, await prepareAndBuildDiscussPrompt(ctx, nextId, `New milestone ${nextId}.`, basePath), "gsd-run", ctx, "discuss-milestone");
             }
             else if (choice === "discard_milestone") {
                 const confirmed = await showConfirm(ctx, {
@@ -1306,7 +1496,8 @@ export async function showSmartEntry(ctx, pi, basePath, options) {
             }), "gsd-run", ctx, "plan-slice");
         }
         else if (choice === "discuss") {
-            await dispatchWorkflow(pi, await buildDiscussSlicePrompt(milestoneId, sliceId, sliceTitle, basePath, { rediscuss: hasContext }), "gsd-run", ctx, "discuss-slice");
+            const sqAvail = pi.getActiveTools().includes("ask_user_questions") ? "true" : "false";
+            await dispatchWorkflow(pi, await buildDiscussSlicePrompt(milestoneId, sliceId, sliceTitle, basePath, { rediscuss: hasContext, structuredQuestionsAvailable: sqAvail }), "gsd-run", ctx, "discuss-slice");
         }
         else if (choice === "research") {
             const researchTemplates = inlineTemplate("research", "Research");

package/dist/resources/extensions/gsd/index.js

@@ -1,4 +1,4 @@
-export { isDepthVerified, isQueuePhaseActive, setQueuePhaseActive, shouldBlockContextWrite, shouldBlockQueueExecution, } from "./bootstrap/write-gate.js";
+export { isDepthConfirmationAnswer, isDepthVerified, isQueuePhaseActive, setQueuePhaseActive, shouldBlockContextWrite, shouldBlockQueueExecution, } from "./bootstrap/write-gate.js";
 export default async function registerExtension(pi) {
     const { registerGsdExtension } = await import("./bootstrap/register-extension.js");
     registerGsdExtension(pi);

package/dist/resources/extensions/gsd/json-persistence.js

@@ -1,5 +1,6 @@
 import { existsSync, readFileSync, writeFileSync, mkdirSync, renameSync } from "node:fs";
 import { dirname } from "node:path";
+import { randomBytes } from "node:crypto";
 /**
  * Load a JSON file with validation, returning a default on failure.
  * Handles missing files, corrupt JSON, and schema mismatches uniformly.
@@ -45,9 +46,11 @@ export function loadJsonFileOrNull(filePath, validate) {
 export function saveJsonFile(filePath, data) {
     try {
         mkdirSync(dirname(filePath), { recursive: true });
-        const tmp = filePath + ".tmp";
+        // Use randomized tmp suffix to prevent concurrent-write data loss
+        const tmp = `${filePath}.tmp.${randomBytes(4).toString("hex")}`;
         writeFileSync(tmp, JSON.stringify(data, null, 2) + "\n", "utf-8");
         renameSync(tmp, filePath);
+        // No cleanup needed — renameSync atomically removes tmp on success
     }
     catch {
         // Non-fatal — don't let persistence failures break operation
@@ -60,7 +63,7 @@ export function saveJsonFile(filePath, data) {
 export function writeJsonFileAtomic(filePath, data) {
     try {
         mkdirSync(dirname(filePath), { recursive: true });
-        const tmp = filePath + ".tmp";
+        const tmp = `${filePath}.tmp.${randomBytes(4).toString("hex")}`;
         writeFileSync(tmp, JSON.stringify(data, null, 2), "utf-8");
         renameSync(tmp, filePath);
     }

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

@@ -438,12 +438,6 @@ export function migrateHierarchyToDb(basePath) {
         // Ghost milestone: no CONTEXT, ROADMAP, or SUMMARY → skip
         if (!hasRoadmap && !hasContext && !hasSummary)
             continue;
-        // Determine milestone status
-        let milestoneStatus = 'active';
-        if (hasSummary)
-            milestoneStatus = 'complete';
-        else if (hasParked)
-            milestoneStatus = 'parked';
         // Determine milestone title from roadmap H1 or CONTEXT heading
         let milestoneTitle = '';
         let roadmapContent = null;
@@ -453,6 +447,17 @@ export function migrateHierarchyToDb(basePath) {
             roadmap = parseRoadmap(roadmapContent);
             milestoneTitle = roadmap.title;
         }
+        // Determine milestone status
+        let milestoneStatus = 'active';
+        if (hasSummary)
+            milestoneStatus = 'complete';
+        else if (hasParked)
+            milestoneStatus = 'parked';
+        // Import milestones with all-done roadmap slices as complete (#3390, #3379)
+        // even when SUMMARY.md is missing — the roadmap checkboxes are authoritative.
+        else if (roadmap && roadmap.slices.length > 0 && roadmap.slices.every(s => s.done)) {
+            milestoneStatus = 'complete';
+        }
         if (!milestoneTitle && hasContext) {
             const contextContent = readFileSync(contextPath, 'utf-8');
             const h1Match = contextContent.match(/^#\s+(.+)/m);
@@ -492,7 +497,8 @@ export function migrateHierarchyToDb(basePath) {
         // Parse roadmap for slices
         if (!roadmap)
             continue;
-        for (const sliceEntry of roadmap.slices) {
+        for (let si = 0; si < roadmap.slices.length; si++) {
+            const sliceEntry = roadmap.slices[si];
             // Per K002: use 'complete' not 'done'
             const sliceStatus = sliceEntry.done ? 'complete' : 'pending';
             // Parse slice plan early so goal is available for insertSlice planning column
@@ -510,6 +516,7 @@ export function migrateHierarchyToDb(basePath) {
                 risk: sliceEntry.risk,
                 depends: sliceEntry.depends,
                 demo: sliceEntry.demo,
+                sequence: si + 1, // Preserve roadmap parse order (#3356)
                 planning: {
                     goal: plan?.goal ?? '',
                 },

package/dist/resources/extensions/gsd/parallel-orchestrator.js

@@ -440,19 +440,25 @@ export function spawnWorker(basePath, milestoneId) {
         return false;
     let child;
     try {
+        const workerEnv = {
+            ...process.env,
+            GSD_MILESTONE_LOCK: milestoneId,
+            // Pass the real project root so workers don't need to re-derive it.
+            // Without this, process.cwd() resolves symlinks and the worktree
+            // path heuristic can match the user-level ~/.gsd instead of the
+            // project .gsd, causing writes to ~ and corrupting user config.
+            GSD_PROJECT_ROOT: basePath,
+            // Prevent workers from spawning their own parallel sessions
+            GSD_PARALLEL_WORKER: "1",
+        };
+        // Apply worker model override if configured, so workers use a cheaper
+        // model (e.g. Haiku) rather than inheriting the coordinator's model.
+        if (state.config.worker_model) {
+            workerEnv.GSD_WORKER_MODEL = state.config.worker_model;
+        }
         child = spawn(process.execPath, [binPath, "headless", "--json", "auto"], {
             cwd: worker.worktreePath,
-            env: {
-                ...process.env,
-                GSD_MILESTONE_LOCK: milestoneId,
-                // Pass the real project root so workers don't need to re-derive it.
-                // Without this, process.cwd() resolves symlinks and the worktree
-                // path heuristic can match the user-level ~/.gsd instead of the
-                // project .gsd, causing writes to ~ and corrupting user config.
-                GSD_PROJECT_ROOT: basePath,
-                // Prevent workers from spawning their own parallel sessions
-                GSD_PARALLEL_WORKER: "1",
-            },
+            env: workerEnv,
             stdio: ["ignore", "pipe", "pipe"],
             detached: false,
         });

package/dist/resources/extensions/gsd/pre-execution-checks.js

@@ -197,8 +197,10 @@ export async function checkPackageExistence(tasks, _basePath) {
 export function normalizeFilePath(filePath) {
     if (!filePath)
         return filePath;
+    // Strip backtick wrapping from LLM-generated paths (#3649)
+    let normalized = filePath.replace(/`/g, "");
     // Normalize path separators to forward slashes
-    let normalized = filePath.replace(/\\/g, "/");
+    normalized = normalized.replace(/\\/g, "/");
     // Remove leading ./
     while (normalized.startsWith("./")) {
         normalized = normalized.slice(2);
@@ -225,10 +227,13 @@ function getExpectedOutputsUpTo(tasks, taskIndex) {
     return outputs;
 }
 /**
- * Check that all files referenced in task.files and task.inputs either:
+ * Check that all files referenced in task.inputs either:
  *   1. Exist on disk, OR
  *   2. Are in a prior task's expected_output
  *
+ * task.files ("files likely touched") is excluded — it intentionally includes
+ * files the task will create, so they don't need to pre-exist (#3626).
+ *
  * All paths are normalized before comparison to ensure ./src/a.ts matches src/a.ts.
  */
 export function checkFilePathConsistency(tasks, basePath) {
@@ -236,7 +241,7 @@ export function checkFilePathConsistency(tasks, basePath) {
     for (let i = 0; i < tasks.length; i++) {
         const task = tasks[i];
         const priorOutputs = getExpectedOutputsUpTo(tasks, i);
-        const filesToCheck = [...task.files, ...task.inputs];
+        const filesToCheck = [...task.inputs];
         for (const file of filesToCheck) {
             // Skip empty strings
             if (!file.trim())
@@ -281,10 +286,12 @@ export function checkTaskOrdering(tasks, _basePath) {
             }
         }
     }
-    // Check each task's inputs against file creators
+    // Check each task's inputs against file creators.
+    // Only check task.inputs — task.files ("files likely touched") intentionally
+    // includes files the task will create, so they don't indicate read-before-create (#3677).
     for (let i = 0; i < tasks.length; i++) {
         const task = tasks[i];
-        const filesToCheck = [...task.files, ...task.inputs];
+        const filesToCheck = [...task.inputs];
         for (const file of filesToCheck) {
             const normalizedFile = normalizeFilePath(file);
             const creator = fileCreators.get(normalizedFile);

package/dist/resources/extensions/gsd/preferences-types.js

@@ -80,6 +80,9 @@ export const KNOWN_PREFERENCE_KEYS = new Set([
     "enhanced_verification_pre",
     "enhanced_verification_post",
     "enhanced_verification_strict",
+    "discuss_preparation",
+    "discuss_web_research",
+    "discuss_depth",
 ]);
 /** Canonical list of all dispatch unit types. */
 export const KNOWN_UNIT_TYPES = [