gsd-pi 2.76.0-dev.4c866b677 → 2.76.0-dev.7218806ab

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

@@ -79,6 +79,13 @@ function runPlanV2Gate(ctx, basePath, state) {
 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;
+// #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 pendingAutoStartMap = new Map();
 /**
  * Backward-compat bridge: returns a mutable reference to the entry matching
@@ -225,6 +232,188 @@ export function checkAutoStartAfterDiscuss() {
     startAutoDetached(ctx, pi, basePath, false, { step });
     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.
+ */
+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 === "tool_use" || b.type === "tool-use"));
+}
+/**
+ * #4573 — Detect and recover from the "ready phrase without files" failure mode.
+ *
+ * When the LLM emits "Milestone {{id}} ready." but has not written CONTEXT.md
+ * or ROADMAP.md, `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 CONTEXT.md nor ROADMAP.md exists, 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) {
+    const entry = _getPendingAutoStart();
+    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;
+    // 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;
+    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.
+        pendingAutoStartMap.delete(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;
+    }
+    ctx.ui.notify(`Milestone ${milestoneId}: "ready" signal rejected — CONTEXT.md and ROADMAP.md are missing. Asking the LLM to complete the writes.`, "warning");
+    const nudge = `You emitted "Milestone ${milestoneId} ready." but neither ` +
+        `.gsd/milestones/${milestoneId}/${milestoneId}-CONTEXT.md nor ` +
+        `.gsd/milestones/${milestoneId}/${milestoneId}-ROADMAP.md 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."
+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|make|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) {
+    // Gate: only fire when there is system-driven work in flight. Interactive
+    // /gsd discuss (user-driven) produces legitimate text-only turns.
+    if (!isAuto && pendingAutoStartMap.size === 0)
+        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. Keep the heuristic
+    // tight: a trailing question mark on the last non-empty line is the common
+    // signal for "I asked the user a question and stopped."
+    const lines = text.split(/\r?\n/).map((l) => l.trim()).filter(Boolean);
+    const lastLine = lines[lines.length - 1] ?? "";
+    if (lastLine.endsWith("?"))
+        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();
+    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.

package/dist/resources/extensions/gsd/health-widget.js

@@ -91,6 +91,7 @@ export function initHealthWidget(ctx) {
         let data = initialData;
         let cachedLines;
         let refreshInFlight = false;
+        let isDisposed = false;
         const refresh = async () => {
             if (refreshInFlight)
                 return;
@@ -98,7 +99,8 @@ export function initHealthWidget(ctx) {
             try {
                 data = loadHealthWidgetData(basePath);
                 cachedLines = undefined;
-                _tui.requestRender();
+                if (!isDisposed)
+                    _tui.requestRender();
             }
             catch { /* non-fatal */ }
             finally {
@@ -122,6 +124,7 @@ export function initHealthWidget(ctx) {
             },
             invalidate() { cachedLines = undefined; cachedWidth = undefined; },
             dispose() {
+                isDisposed = true;
                 clearInterval(refreshTimer);
             },
         };

package/dist/resources/extensions/gsd/key-manager.js

@@ -12,6 +12,12 @@ import { getErrorMessage } from "./error-utils.js";
 export const PROVIDER_REGISTRY = [
     // LLM Providers
     { id: "anthropic", label: "Anthropic (Claude)", category: "llm", envVar: "ANTHROPIC_API_KEY", prefixes: ["sk-ant-"], hasOAuth: true, dashboardUrl: "console.anthropic.com" },
+    // Claude Code CLI: routes through the local `claude` binary — no API key,
+    // authentication is handled by the CLI's own OAuth flow.
+    // Referenced by doctor-providers.ts, auto-model-selection.ts, and others;
+    // must be in the canonical registry so all consumers see the same catalog.
+    // See: https://github.com/gsd-build/gsd-2/issues/4541
+    { id: "claude-code", label: "Claude Code CLI", category: "llm", hasOAuth: true },
     { id: "openai", label: "OpenAI", category: "llm", envVar: "OPENAI_API_KEY", prefixes: ["sk-"], dashboardUrl: "platform.openai.com/api-keys" },
     { id: "github-copilot", label: "GitHub Copilot", category: "llm", envVar: "GITHUB_TOKEN", hasOAuth: true },
     { id: "openai-codex", label: "ChatGPT Plus/Pro (Codex)", category: "llm", hasOAuth: true },

package/dist/resources/extensions/gsd/model-router.js

@@ -440,6 +440,20 @@ function getModelCost(modelId) {
 function bareModelId(modelId) {
     return modelId.includes("/") ? modelId.split("/").pop() : modelId;
 }
+// ─── Provider-specific Tool Limits ─────────────────────────────────────────
+/**
+ * Groq enforces a hard limit of 128 tools per request.
+ * Requests exceeding this limit receive a 400 error:
+ * "maximum number of items is 128"
+ * @see https://console.groq.com/docs/tool-use
+ */
+export const GROQ_MAX_TOOLS = 128;
+/**
+ * Provider IDs that map to the Groq API backend.
+ * Used to detect Groq at the GSD routing layer where only the provider string
+ * is available (the pi-ai openai-completions adapter is shared across providers).
+ */
+const GROQ_PROVIDER_IDS = new Set(["groq"]);
 // ─── Tool Compatibility Filter (ADR-005 Phase 3) ───────────────────────────
 /**
  * Check if a tool is compatible with a provider's capabilities.
@@ -461,8 +475,14 @@ export function isToolCompatibleWithProvider(toolName, providerCaps) {
 /**
  * Filter a list of tool names to only those compatible with a provider.
  * Used by the routing pipeline to adjust tool sets when switching providers.
+ *
+ * @param toolNames - The full list of active tool names to filter.
+ * @param providerApi - The pi-ai API string (e.g. "openai-completions").
+ * @param provider - Optional provider ID (e.g. "groq"). Used to apply
+ *   provider-specific limits that can't be expressed as API-level capabilities
+ *   (e.g. Groq's 128-tool hard limit on the shared openai-completions adapter).
  */
-export function filterToolsForProvider(toolNames, providerApi) {
+export function filterToolsForProvider(toolNames, providerApi, provider) {
     const providerCaps = getProviderCapabilities(providerApi);
     // Provider doesn't support tool calling at all
     if (!providerCaps.toolCalling) {
@@ -478,6 +498,14 @@ export function filterToolsForProvider(toolNames, providerApi) {
             filtered.push(name);
         }
     }
+    // Groq enforces a hard limit of 128 tools per request (#4376).
+    // Trim the compatible list to GROQ_MAX_TOOLS and move the excess to filtered.
+    if (provider && GROQ_PROVIDER_IDS.has(provider) && compatible.length > GROQ_MAX_TOOLS) {
+        const trimmed = compatible.splice(GROQ_MAX_TOOLS);
+        filtered.push(...trimmed);
+        console.warn(`[gsd] Groq tool limit: ${compatible.length + trimmed.length} tools active but Groq allows at most ${GROQ_MAX_TOOLS}. ` +
+            `Trimming to the first ${GROQ_MAX_TOOLS} tools. Removed: ${trimmed.join(", ")}`);
+    }
     return { compatible, filtered };
 }
 /**
@@ -486,8 +514,13 @@ export function filterToolsForProvider(toolNames, providerApi) {
  *
  * This is a hard filter only — it removes tools that would fail at the
  * provider level. It does NOT remove tools based on soft heuristics.
+ *
+ * @param activeToolNames - The full list of currently active tool names.
+ * @param selectedModelApi - The pi-ai API string for the selected model.
+ * @param provider - Optional provider ID (e.g. "groq") for provider-specific
+ *   limits beyond what the API-level capability profile expresses.
  */
-export function adjustToolSet(activeToolNames, selectedModelApi) {
-    const { compatible, filtered } = filterToolsForProvider(activeToolNames, selectedModelApi);
+export function adjustToolSet(activeToolNames, selectedModelApi, provider) {
+    const { compatible, filtered } = filterToolsForProvider(activeToolNames, selectedModelApi, provider);
     return { toolNames: compatible, removedTools: filtered };
 }

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

@@ -68,8 +68,13 @@ export function extractPackageReferences(description) {
             }
         }
     }
-    // require('pkg') or import from 'pkg' in code blocks
-    const importPattern = /(?:require\s*\(\s*['"]|from\s+['"])([a-zA-Z0-9@/_-]+)['"\)]/g;
+    // require('pkg') or `import ... from 'pkg'` in code blocks.
+    // The `from\s+['"]` branch MUST be preceded by an `import` keyword so that
+    // natural-language prose like `from "What's Next"` or `from 'master'` does
+    // not produce false package-existence failures.  Requiring the leading import
+    // keyword anchors the match to JavaScript/TypeScript syntax.
+    // See: https://github.com/gsd-build/gsd-2/issues/4388
+    const importPattern = /(?:require\s*\(\s*['"]|import\b[\s\S]*?\bfrom\s+['"])([a-zA-Z0-9@/_-]+)['"\)]/g;
     let importMatch;
     while ((importMatch = importPattern.exec(description)) !== null) {
         // Skip relative imports and node builtins
@@ -278,7 +283,12 @@ function extractPathFromAnnotation(raw) {
     }
     const annotatedMatch = trimmed.match(/^(.+?)\s+[—–-]\s+.+$/);
     if (annotatedMatch) {
-        return annotatedMatch[1].trim();
+        const prefix = annotatedMatch[1].trim();
+        const prefixBacktickMatch = prefix.match(/`([^`]+)`/);
+        if (prefixBacktickMatch && looksLikePathOrUrl(prefixBacktickMatch[1].trim())) {
+            return prefixBacktickMatch[1].trim();
+        }
+        return prefix.replace(/`/g, "").trim();
     }
     // Fallback: scan all backticked tokens and return the first one that looks
     // like a path or URL. Handles prose-annotated bullets such as:
@@ -333,13 +343,19 @@ function containsGlobPattern(candidate) {
 }
 /**
  * Build a set of files that will be created by tasks up to (but not including) taskIndex.
+ * Also includes outputs of completed tasks at any position — a completed task has already
+ * run and its outputs are available regardless of sequence position or disk state (#4071).
  * All paths are normalized for consistent comparison.
  */
 function getExpectedOutputsUpTo(tasks, taskIndex) {
     const outputs = new Set();
-    for (let i = 0; i < taskIndex; i++) {
-        for (const file of tasks[i].expected_output) {
-            outputs.add(normalizeFilePath(file));
+    for (let i = 0; i < tasks.length; i++) {
+        const task = tasks[i];
+        // Include prior tasks (i < taskIndex) OR completed tasks at any position
+        if (i < taskIndex || task.status === "completed") {
+            for (const file of task.expected_output) {
+                outputs.add(normalizeFilePath(file));
+            }
         }
     }
     return outputs;
@@ -416,8 +432,14 @@ export function checkTaskOrdering(tasks, basePath) {
         const task = tasks[i];
         for (const file of task.expected_output) {
             const normalizedFile = normalizeFilePath(file);
-            if (!fileCreators.has(normalizedFile)) {
-                fileCreators.set(normalizedFile, { taskId: task.id, index: i, originalPath: file });
+            const existing = fileCreators.get(normalizedFile);
+            if (!existing || (!existing.completed && task.status === "completed")) {
+                fileCreators.set(normalizedFile, {
+                    taskId: task.id,
+                    index: i,
+                    originalPath: file,
+                    completed: task.status === "completed",
+                });
             }
         }
     }
@@ -441,7 +463,11 @@ export function checkTaskOrdering(tasks, basePath) {
             const creator = fileCreators.get(normalizedFile);
             const absolutePath = resolve(basePath, normalizedFile);
             const existsOnDisk = existsSync(absolutePath);
-            if (creator && creator.index > i && !existsOnDisk) {
+            // Skip if the creating task has already completed — its output is available
+            // regardless of disk state (e.g. file was a temp artifact cleaned up after
+            // the task ran, or a replan introduced a new earlier-sequence task that
+            // reads this pre-execution output). (#4071)
+            if (creator && creator.index > i && !existsOnDisk && !creator.completed) {
                 // Task reads file that is created later — impossible ordering
                 results.push({
                     category: "file",

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

@@ -5,6 +5,14 @@
  * both the validation and runtime modules can import them without pulling
  * in filesystem or loading logic.
  */
+/**
+ * Resolve whether context-mode features (gsd_exec sandbox + compaction
+ * snapshot) should be active. Default is ON: missing config or missing
+ * `enabled` is treated as true. Only `enabled: false` disables.
+ */
+export function isContextModeEnabled(prefs) {
+    return prefs?.context_mode?.enabled !== false;
+}
 /** Default preference values for each workflow mode. */
 export const MODE_DEFAULTS = {
     solo: {
@@ -87,6 +95,7 @@ export const KNOWN_PREFERENCE_KEYS = new Set([
     "flat_rate_providers",
     "language",
     "context_window_override",
+    "context_mode",
 ]);
 /** Canonical list of all dispatch unit types. */
 export const KNOWN_UNIT_TYPES = [

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

@@ -660,6 +660,55 @@ export function validatePreferences(preferences) {
             errors.push("context_management must be an object");
         }
     }
+    // ─── Context Mode (gsd_exec sandbox) ────────────────────────────────────
+    if (preferences.context_mode !== undefined) {
+        if (typeof preferences.context_mode === "object" && preferences.context_mode !== null) {
+            const cmode = preferences.context_mode;
+            const validCmode = {};
+            if (cmode.enabled !== undefined) {
+                if (typeof cmode.enabled === "boolean")
+                    validCmode.enabled = cmode.enabled;
+                else
+                    errors.push("context_mode.enabled must be a boolean");
+            }
+            if (cmode.exec_timeout_ms !== undefined) {
+                const t = cmode.exec_timeout_ms;
+                if (typeof t === "number" && t >= 1000 && t <= 600_000)
+                    validCmode.exec_timeout_ms = Math.floor(t);
+                else
+                    errors.push("context_mode.exec_timeout_ms must be a number between 1000 and 600000");
+            }
+            if (cmode.exec_stdout_cap_bytes !== undefined) {
+                const b = cmode.exec_stdout_cap_bytes;
+                if (typeof b === "number" && b >= 4096 && b <= 16_777_216)
+                    validCmode.exec_stdout_cap_bytes = Math.floor(b);
+                else
+                    errors.push("context_mode.exec_stdout_cap_bytes must be a number between 4096 and 16777216");
+            }
+            if (cmode.exec_digest_chars !== undefined) {
+                const c = cmode.exec_digest_chars;
+                if (typeof c === "number" && c >= 0 && c <= 4000)
+                    validCmode.exec_digest_chars = Math.floor(c);
+                else
+                    errors.push("context_mode.exec_digest_chars must be a number between 0 and 4000");
+            }
+            if (cmode.exec_env_allowlist !== undefined) {
+                if (Array.isArray(cmode.exec_env_allowlist) &&
+                    cmode.exec_env_allowlist.every((v) => typeof v === "string" && /^[A-Z_][A-Z0-9_]*$/i.test(v))) {
+                    validCmode.exec_env_allowlist = cmode.exec_env_allowlist;
+                }
+                else {
+                    errors.push("context_mode.exec_env_allowlist must be an array of valid env var names");
+                }
+            }
+            if (Object.keys(validCmode).length > 0) {
+                validated.context_mode = validCmode;
+            }
+        }
+        else {
+            errors.push("context_mode must be an object");
+        }
+    }
     // ─── Parallel Config ────────────────────────────────────────────────────
     if (preferences.parallel && typeof preferences.parallel === "object") {
         const p = preferences.parallel;
@@ -716,6 +765,40 @@ export function validatePreferences(preferences) {
             validated.parallel = parallel;
         }
     }
+    // ─── Slice Parallel Config ───────────────────────────────────────────────
+    if (preferences.slice_parallel !== undefined) {
+        if (typeof preferences.slice_parallel === "object" && preferences.slice_parallel !== null) {
+            const sp = preferences.slice_parallel;
+            const validSp = {};
+            if (sp.enabled !== undefined) {
+                if (typeof sp.enabled === "boolean")
+                    validSp.enabled = sp.enabled;
+                else
+                    errors.push("slice_parallel.enabled must be a boolean");
+            }
+            if (sp.max_workers !== undefined) {
+                const maxWorkers = typeof sp.max_workers === "number" ? sp.max_workers : Number(sp.max_workers);
+                if (Number.isFinite(maxWorkers) && maxWorkers >= 1 && maxWorkers <= 8) {
+                    validSp.max_workers = Math.floor(maxWorkers);
+                }
+                else {
+                    errors.push("slice_parallel.max_workers must be a number between 1 and 8");
+                }
+            }
+            const knownSliceParallelKeys = new Set(["enabled", "max_workers"]);
+            for (const key of Object.keys(sp)) {
+                if (!knownSliceParallelKeys.has(key)) {
+                    warnings.push(`unknown slice_parallel key "${key}" — ignored`);
+                }
+            }
+            if (Object.keys(validSp).length > 0) {
+                validated.slice_parallel = validSp;
+            }
+        }
+        else {
+            errors.push("slice_parallel must be an object");
+        }
+    }
     // ─── Reactive Execution ─────────────────────────────────────────────────
     if (preferences.reactive_execution !== undefined) {
         if (typeof preferences.reactive_execution === "object" && preferences.reactive_execution !== null) {

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

@@ -26,12 +26,12 @@ export { resolveAllSkillReferences } from "./preferences-skills.js";
 // These lived in preferences-skills.ts but imported loadEffectiveGSDPreferences
 // back from this file, creating a circular dependency. Moved here since they
 // are trivial wrappers over loadEffectiveGSDPreferences.
-export function resolveSkillDiscoveryMode() {
-    const prefs = loadEffectiveGSDPreferences();
+export function resolveSkillDiscoveryMode(basePath) {
+    const prefs = loadEffectiveGSDPreferences(basePath);
     return prefs?.preferences.skill_discovery ?? "suggest";
 }
-export function resolveSkillStalenessDays() {
-    const prefs = loadEffectiveGSDPreferences();
+export function resolveSkillStalenessDays(basePath) {
+    const prefs = loadEffectiveGSDPreferences(basePath);
     return prefs?.preferences.skill_staleness_days ?? 60;
 }
 // ─── Re-exports: models ─────────────────────────────────────────────────────
@@ -46,16 +46,16 @@ function globalPreferencesPath() {
 function legacyGlobalPreferencesPath() {
     return join(homedir(), ".pi", "agent", "gsd-preferences.md");
 }
-function projectPreferencesPath() {
-    return join(gsdRoot(process.cwd()), "PREFERENCES.md");
+function projectPreferencesPath(basePath = process.cwd()) {
+    return join(gsdRoot(basePath), "PREFERENCES.md");
 }
 // Legacy lowercase files can still exist in older projects. Keep them as a
 // compatibility-only fallback, but route new reads/writes through PREFERENCES.md.
 function legacyGlobalPreferencesPathLowercase() {
     return join(gsdHome(), "preferences.md");
 }
-function legacyProjectPreferencesPathLowercase() {
-    return join(gsdRoot(process.cwd()), "preferences.md");
+function legacyProjectPreferencesPathLowercase(basePath = process.cwd()) {
+    return join(gsdRoot(basePath), "preferences.md");
 }
 export function getGlobalGSDPreferencesPath() {
     return globalPreferencesPath();
@@ -63,8 +63,8 @@ export function getGlobalGSDPreferencesPath() {
 export function getLegacyGlobalGSDPreferencesPath() {
     return legacyGlobalPreferencesPath();
 }
-export function getProjectGSDPreferencesPath() {
-    return projectPreferencesPath();
+export function getProjectGSDPreferencesPath(basePath) {
+    return projectPreferencesPath(basePath);
 }
 // ─── Loading ────────────────────────────────────────────────────────────────
 export function loadGlobalGSDPreferences() {
@@ -72,13 +72,13 @@ export function loadGlobalGSDPreferences() {
         ?? loadPreferencesFile(legacyGlobalPreferencesPathLowercase(), "global")
         ?? loadPreferencesFile(legacyGlobalPreferencesPath(), "global");
 }
-export function loadProjectGSDPreferences() {
-    return loadPreferencesFile(projectPreferencesPath(), "project")
-        ?? loadPreferencesFile(legacyProjectPreferencesPathLowercase(), "project");
+export function loadProjectGSDPreferences(basePath) {
+    return loadPreferencesFile(projectPreferencesPath(basePath), "project")
+        ?? loadPreferencesFile(legacyProjectPreferencesPathLowercase(basePath), "project");
 }
-export function loadEffectiveGSDPreferences() {
+export function loadEffectiveGSDPreferences(basePath) {
     const globalPreferences = loadGlobalGSDPreferences();
-    const projectPreferences = loadProjectGSDPreferences();
+    const projectPreferences = loadProjectGSDPreferences(basePath);
     if (!globalPreferences && !projectPreferences)
         return null;
     let result;
@@ -489,8 +489,8 @@ export function resolvePreDispatchHooks() {
  * Worktree isolation requires explicit opt-in because it depends on git
  * branch infrastructure that must be set up before use.
  */
-export function getIsolationMode() {
-    const prefs = loadEffectiveGSDPreferences()?.preferences?.git;
+export function getIsolationMode(basePath) {
+    const prefs = loadEffectiveGSDPreferences(basePath)?.preferences?.git;
     if (prefs?.isolation === "worktree")
         return "worktree";
     if (prefs?.isolation === "branch")

package/dist/resources/extensions/gsd/prompts/discuss-headless.md

@@ -162,6 +162,10 @@ Preserve the specification's exact terminology, emphasis, and specific framing.
 6. For each architectural or pattern decision, call `gsd_decision_save` — the tool auto-assigns IDs and regenerates `.gsd/DECISIONS.md` automatically.
 7. {{commitInstruction}}
 
+### Ready-phrase pre-condition (NON-BYPASSABLE)
+
+Before emitting the ready phrase, verify in the CURRENT turn that you have written `.gsd/PROJECT.md`, `.gsd/REQUIREMENTS.md`, `{{contextPath}}`, and called `gsd_plan_milestone`. If any is missing, **STOP** — emit the missing tool calls in this same turn. The system rejects premature ready signals and retries are capped.
+
 After writing the files, say exactly: "Milestone {{milestoneId}} ready." — nothing else. Auto-mode will start automatically.
 
 ### Multi-Milestone
@@ -234,6 +238,10 @@ For single-milestone projects, do NOT write this file.
 
 7. {{multiMilestoneCommitInstruction}}
 
+### Ready-phrase pre-condition (NON-BYPASSABLE)
+
+Before emitting the ready phrase, verify in the CURRENT turn that you have written `.gsd/PROJECT.md`, `.gsd/REQUIREMENTS.md`, the primary `CONTEXT.md`, called `gsd_plan_milestone` for the primary milestone, and written `.gsd/DISCUSSION-MANIFEST.json` with `gates_completed === total`. If any is missing, **STOP** — emit the missing tool calls in this same turn. The system rejects premature ready signals and retries are capped.
+
 After writing the files, say exactly: "Milestone {{milestoneId}} ready." — nothing else. Auto-mode will start automatically.
 
 ## Critical Rules

package/dist/resources/extensions/gsd/prompts/discuss.md

@@ -339,7 +339,20 @@ These sections are in addition to whatever other context the discussion surfaced
 6. For each architectural or pattern decision made during discussion, call `gsd_decision_save` — the tool auto-assigns IDs and regenerates `.gsd/DECISIONS.md` automatically.
 7. {{commitInstruction}}
 
-After writing the files, say exactly: "Milestone {{milestoneId}} ready." — nothing else. Auto-mode will start automatically.
+### Ready-phrase pre-condition (NON-BYPASSABLE)
+
+Before emitting the ready phrase, verify in the CURRENT turn that you have:
+
+- [ ] Written `.gsd/PROJECT.md` (step 2)
+- [ ] Written `.gsd/REQUIREMENTS.md` (step 3)
+- [ ] Written `{{contextPath}}` (step 4)
+- [ ] Called `gsd_plan_milestone` (step 5)
+
+If ANY box is unchecked, **STOP**. Do NOT emit the ready phrase. Emit the missing tool calls in this same turn. The system detects missing artifacts and will reject premature ready signals — you will be asked again and retries are capped.
+
+Do not announce the ready phrase as something you are "about to" do. Do not narrate "now writing the files" as a substitute for actually writing them. The ready phrase is a post-write signal, not an intent signal.
+
+After completing steps 1–7 above, say exactly: "Milestone {{milestoneId}} ready." — nothing else. Auto-mode will start automatically.
 
 ### Multi-Milestone
 
@@ -418,6 +431,20 @@ For single-milestone projects, do NOT write this file — it is only for multi-m
 
 7. {{multiMilestoneCommitInstruction}}
 
-After writing the files, say exactly: "Milestone M001 ready." — nothing else. Auto-mode will start automatically.
+### Ready-phrase pre-condition (NON-BYPASSABLE)
+
+Before emitting the ready phrase, verify in the CURRENT turn that you have:
+
+- [ ] Written `.gsd/PROJECT.md` (Phase 1)
+- [ ] Written `.gsd/REQUIREMENTS.md` (Phase 1)
+- [ ] Written primary-milestone `CONTEXT.md` (Phase 2)
+- [ ] Called `gsd_plan_milestone` for the primary milestone (Phase 2)
+- [ ] Written `.gsd/DISCUSSION-MANIFEST.json` with `gates_completed === total` (Phase 3)
+
+If ANY box is unchecked, **STOP**. Do NOT emit the ready phrase. Emit the missing tool calls in this same turn. The system detects missing artifacts and will reject premature ready signals — you will be asked again and retries are capped.
+
+Do not announce the ready phrase as something you are "about to" do. Do not narrate "now writing the files" as a substitute for actually writing them. The ready phrase is a post-write signal, not an intent signal.
+
+After completing all phases above, say exactly: "Milestone M001 ready." — nothing else. Auto-mode will start automatically.
 
 {{inlinedTemplates}}