gsd-pi 2.68.0 → 2.68.1-dev.c1497ab

package/README.md

@@ -21,58 +21,49 @@ One command. Walk away. Come back to a built project with clean git history.
 
 > GSD now provisions a managed [RTK](https://github.com/rtk-ai/rtk) binary on supported macOS, Linux, and Windows installs to compress shell-command output in `bash`, `async_bash`, `bg_shell`, and verification flows. GSD forces `RTK_TELEMETRY_DISABLED=1` for all managed invocations. Set `GSD_RTK_DISABLED=1` to disable the integration.
 
-> **📋 NOTICE: New to Node on Mac?** If you installed Node.js via Homebrew, you may be running a development release instead of LTS. **[Read this guide](./docs/node-lts-macos.md)** to pin Node 24 LTS and avoid compatibility issues.
+> **📋 NOTICE: New to Node on Mac?** If you installed Node.js via Homebrew, you may be running a development release instead of LTS. **[Read this guide](./docs/user-docs/node-lts-macos.md)** to pin Node 24 LTS and avoid compatibility issues.
 
 </div>
 
 ---
 
-## What's New in v2.67
+## What's New in v2.68
 
-### Context Engineering
-
-- **Tiered Context Injection (M005)** — relevance-scoped context with 65%+ token reduction. Decision scope cascade derives context from slice metadata instead of blanket injection.
-- **Resilient transient error recovery** — defers to Core RetryHandler and fixes cmdCtx race conditions for more reliable auto-mode sessions.
-
-### Provider & Model Improvements
-
-- **Anthropic subscription routing** — users with Anthropic subscriptions are automatically routed through Claude Code CLI provider with proper display names across all UI surfaces.
-- **Claude Code provider hardening** — native Windows claude lookup, fallback guards, and `out of extra usage` error matching.
-- **XML parameter recovery** — pi-ai recovers XML parameters trapped in JSON strings from providers.
-
-### Safety & Data Integrity
+### MCP Workflow Tools
 
-- **LLM safety harness** — auto-mode damage control prevents the LLM from running destructive operations or querying `gsd.db` directly via bash.
-- **5-wave state machine hardening** — critical data integrity fixes across atomic writes, randomized tmp paths, event log reconciliation, session recovery, and consistency enforcement. 86+ regression tests added.
-- **Discussion gate enforcement** — mechanical enforcement for discussion question gates with fail-closed behavior.
-- **Enhanced verification** — pre-execution plan verification checks, post-execution cross-task consistency checks, blocking behavior and strict mode.
+- **Full workflow over MCP** — slice replanning, milestone management, slice completion, task completion, and core planning tools are now exposed over MCP for external integrations.
+- **Transport-gated MCP** — workflow tool availability adapts to provider transport capabilities automatically.
+- **Write gate enforcement** — workflow MCP respects write gates, preventing unauthorized state mutations from external clients.
 
-### Parallel Execution & Dispatch
+### Reliability & Recovery
 
-- **Slice-level parallelism** — dependency-aware parallel dispatch within a milestone, not just across milestones.
-- **Parallel research slices** — research and milestone validation run in parallel.
-- **Worker model override** — configure different models for parallel milestone workers.
+- **False degraded-mode fix** — eliminates spurious degraded-mode warnings when the DB hasn't been initialized yet.
+- **Stale session resume suppression** — prevents stale interrupted-session resume prompts from hijacking fresh sessions.
+- **Merge conflict recovery** — `autoCommitDirtyState` guarded with cwd restore on `MergeConflictError`.
+- **Auto-resume hardening** — `autoStartTime` restored on resume, managed resources resynced on auto resume.
 
-### TUI & Notifications
+### TUI & Developer Experience
 
-- **Persistent notification panel** — TUI overlay, widget, and web API for real-time notifications.
-- **Remote questions race** — local TUI races against remote channel (Slack/Discord) instead of remote-only routing.
-- **OS-specific keyboard shortcuts** — shortcut hints now adapt to macOS/Linux/Windows.
-- **`/gsd show-config`** — inspect active configuration at a glance.
+- **Contextual tips system** — TUI and web terminal now surface contextual tips based on workflow state.
+- **Claude Code MCP streaming** — real-time streaming and tool output rendering for Claude Code MCP connections.
 
 ### Infrastructure
 
-- **Ollama native provider** — `/api/chat` provider with full option exposure, `apiKey` auth mode, and headless probe.
-- **MCP OAuth** — MCP client supports OAuth auth provider for HTTP transport.
-- **WAL-safe migration backup** — database migrations create WAL-safe backups with stronger regression tests.
-- **Xcode/xcodegen detection** — project detection now supports Xcode bundles and xcodegen.
-- **170+ bug fixes** — state machine resilience, worktree safety, prompt injection, session recovery, and more.
+- **Weekly model registry refresh** — CI workflow auto-regenerates the model registry on a weekly schedule.
+- **Codebase cache auto-refresh** — stale codebase cache is refreshed automatically without manual intervention.
 
 See the full [Changelog](./CHANGELOG.md) for details on every release.
 
 <details>
-<summary>Previous highlights (v2.63 and earlier)</summary>
-
+<summary>Previous highlights (v2.67 and earlier)</summary>
+
+- **Tiered Context Injection (M005)** — relevance-scoped context with 65%+ token reduction
+- **Resilient transient error recovery** — defers to Core RetryHandler and fixes cmdCtx race conditions
+- **Anthropic subscription routing** — auto-routed through Claude Code CLI provider with proper display names
+- **5-wave state machine hardening** — critical data integrity fixes across atomic writes, event log reconciliation, session recovery
+- **Discussion gate enforcement** — mechanical enforcement with fail-closed behavior
+- **Slice-level parallelism** — dependency-aware parallel dispatch within a milestone
+- **Persistent notification panel** — TUI overlay, widget, and web API for real-time notifications
 - **MCP server** — 6 read-only project state tools for external integrations, auto-wrapup guard, and question dedup
 - **Ollama extension** — first-class local LLM support via Ollama, with dynamic routing enabled by default
 - **Discord bot & daemon** — dedicated daemon package, Discord bot, and headless text mode with tool calls
@@ -95,30 +86,35 @@ See the full [Changelog](./CHANGELOG.md) for details on every release.
 
 ## Documentation
 
-Full documentation is available at **[gsd.build](https://gsd.build)** (powered by Mintlify) and in the [`docs/`](./docs/) directory:
-
-- **[Getting Started](./docs/getting-started.md)** — install, first run, basic usage
-- **[Auto Mode](./docs/auto-mode.md)** — autonomous execution deep-dive
-- **[Configuration](./docs/configuration.md)** — all preferences, models, git, and hooks
-- **[Custom Models](./docs/custom-models.md)** — add custom providers (Ollama, vLLM, LM Studio, proxies)
-- **[Token Optimization](./docs/token-optimization.md)** — profiles, context compression, complexity routing
-- **[Cost Management](./docs/cost-management.md)** — budgets, tracking, projections
-- **[Git Strategy](./docs/git-strategy.md)** — worktree isolation, branching, merge behavior
-- **[Parallel Orchestration](./docs/parallel-orchestration.md)** — run multiple milestones simultaneously
-- **[Working in Teams](./docs/working-in-teams.md)** — unique IDs, shared artifacts
-- **[Skills](./docs/skills.md)** — bundled skills, discovery, custom authoring
-- **[Commands Reference](./docs/commands.md)** — all commands and keyboard shortcuts
-- **[Architecture](./docs/architecture.md)** — system design and dispatch pipeline
-- **[Troubleshooting](./docs/troubleshooting.md)** — common issues, doctor, forensics, recovery
-- **[CI/CD Pipeline](./docs/ci-cd-pipeline.md)** — three-stage promotion pipeline (Dev → Test → Prod)
-- **[VS Code Extension](./vscode-extension/README.md)** — chat participant, sidebar dashboard, RPC integration
-- **[Visualizer](./docs/visualizer.md)** — workflow visualizer with stats and discussion status
-- **[Remote Questions](./docs/remote-questions.md)** — route decisions to Slack or Discord when human input is needed
-- **[Dynamic Model Routing](./docs/dynamic-model-routing.md)** — complexity-based model selection and budget pressure
-- **[Web Interface](./docs/web-interface.md)** — browser-based project management and real-time progress
-- **[Pipeline Simplification (ADR-003)](./docs/ADR-003-pipeline-simplification.md)** — merged research into planning, mechanical completion
+Full documentation is in the [`docs/`](./docs/) directory:
+
+### User Guides
+
+- **[Getting Started](./docs/user-docs/getting-started.md)** — install, first run, basic usage
+- **[Auto Mode](./docs/user-docs/auto-mode.md)** — autonomous execution deep-dive
+- **[Configuration](./docs/user-docs/configuration.md)** — all preferences, models, git, and hooks
+- **[Custom Models](./docs/user-docs/custom-models.md)** — add custom providers (Ollama, vLLM, LM Studio, proxies)
+- **[Token Optimization](./docs/user-docs/token-optimization.md)** — profiles, context compression, complexity routing
+- **[Cost Management](./docs/user-docs/cost-management.md)** — budgets, tracking, projections
+- **[Git Strategy](./docs/user-docs/git-strategy.md)** — worktree isolation, branching, merge behavior
+- **[Parallel Orchestration](./docs/user-docs/parallel-orchestration.md)** — run multiple milestones simultaneously
+- **[Working in Teams](./docs/user-docs/working-in-teams.md)** — unique IDs, shared artifacts
+- **[Skills](./docs/user-docs/skills.md)** — bundled skills, discovery, custom authoring
+- **[Commands Reference](./docs/user-docs/commands.md)** — all commands and keyboard shortcuts
+- **[Troubleshooting](./docs/user-docs/troubleshooting.md)** — common issues, doctor, forensics, recovery
+- **[Visualizer](./docs/user-docs/visualizer.md)** — workflow visualizer with stats and discussion status
+- **[Remote Questions](./docs/user-docs/remote-questions.md)** — route decisions to Slack or Discord when human input is needed
+- **[Dynamic Model Routing](./docs/user-docs/dynamic-model-routing.md)** — complexity-based model selection and budget pressure
+- **[Web Interface](./docs/user-docs/web-interface.md)** — browser-based project management and real-time progress
+- **[Migration from v1](./docs/user-docs/migration.md)** — `.planning` → `.gsd` migration
 - **[Docker Sandbox](./docker/README.md)** — run GSD auto mode in an isolated Docker container
-- **[Migration from v1](./docs/migration.md)** — `.planning` → `.gsd` migration
+
+### Developer Docs
+
+- **[Architecture](./docs/dev/architecture.md)** — system design and dispatch pipeline
+- **[CI/CD Pipeline](./docs/dev/ci-cd-pipeline.md)** — three-stage promotion pipeline (Dev → Test → Prod)
+- **[Pipeline Simplification (ADR-003)](./docs/dev/ADR-003-pipeline-simplification.md)** — merged research into planning, mechanical completion
+- **[VS Code Extension](./vscode-extension/README.md)** — chat participant, sidebar dashboard, RPC integration
 
 ---
 
@@ -334,7 +330,7 @@ gsd headless query
 gsd headless dispatch plan
 ```
 
-Headless auto-responds to interactive prompts, detects completion, and exits with structured codes: `0` complete, `1` error/timeout, `2` blocked. Auto-restarts on crash with exponential backoff. Use `gsd headless query` for instant, machine-readable state inspection — returns phase, next dispatch preview, and parallel worker costs as a single JSON object without spawning an LLM session. Pair with [remote questions](./docs/remote-questions.md) to route decisions to Slack or Discord when human input is needed.
+Headless auto-responds to interactive prompts, detects completion, and exits with structured codes: `0` complete, `1` error/timeout, `2` blocked. Auto-restarts on crash with exponential backoff. Use `gsd headless query` for instant, machine-readable state inspection — returns phase, next dispatch preview, and parallel worker costs as a single JSON object without spawning an LLM session. Pair with [remote questions](./docs/user-docs/remote-questions.md) to route decisions to Slack or Discord when human input is needed.
 
 **Multi-session orchestration** — headless mode supports file-based IPC in `.gsd/parallel/` for coordinating multiple GSD workers across milestones. Build orchestrators that spawn, monitor, and budget-cap a fleet of GSD workers.
 
@@ -507,9 +503,8 @@ auto_report: true
 | `verification_commands`| Array of shell commands to run after task execution (e.g., `["npm run lint", "npm run test"]`)        |
 | `verification_auto_fix`| Auto-retry on verification failures (default: true)                                                   |
 | `verification_max_retries` | Max retries for verification failures (default: 2)                                               |
-| `require_slice_discussion` | Pause auto-mode before each slice for human discussion review                                    |
+| `phases.require_slice_discussion` | Pause auto-mode before each slice for human discussion review                                    |
 | `auto_report`          | Auto-generate HTML reports after milestone completion (default: true)                                 |
-| `searchExcludeDirs`    | Directories to exclude from `@` file autocomplete (e.g., `["node_modules", ".git", "dist"]`)          |
 
 ### Agent Instructions
 
@@ -539,7 +534,7 @@ token_profile: budget      # or balanced (default), quality
 
 **Budget pressure** graduates model downgrading as you approach your budget ceiling — 50%, 75%, and 90% thresholds progressively shift work to cheaper tiers.
 
-See the full [Token Optimization Guide](./docs/token-optimization.md) for details.
+See the full [Token Optimization Guide](./docs/user-docs/token-optimization.md) for details.
 
 ### Bundled Tools
 
@@ -574,13 +569,15 @@ GSD ships with 24 extensions, all loaded automatically:
 
 ### Bundled Agents
 
-Three specialized subagents for delegated work:
+Five specialized subagents for delegated work:
 
-| Agent          | Role                                                         |
-| -------------- | ------------------------------------------------------------ |
-| **Scout**      | Fast codebase recon — returns compressed context for handoff |
-| **Researcher** | Web research — finds and synthesizes current information     |
-| **Worker**     | General-purpose execution in an isolated context window      |
+| Agent               | Role                                                         |
+| ------------------- | ------------------------------------------------------------ |
+| **Scout**           | Fast codebase recon — returns compressed context for handoff |
+| **Researcher**      | Web research — finds and synthesizes current information     |
+| **Worker**          | General-purpose execution in an isolated context window      |
+| **JavaScript Pro**  | JavaScript-specialized execution and debugging               |
+| **TypeScript Pro**  | TypeScript-specialized execution and debugging               |
 
 ---
 
@@ -655,9 +652,8 @@ gsd (CLI binary)
           ├─ resource-loader.ts  Syncs bundled extensions + agents to ~/.gsd/agent/
           └─ src/resources/
               ├─ extensions/gsd/    Core GSD extension (auto, state, commands, ...)
-              ├─ extensions/...     23 supporting extensions
-              ├─ agents/            scout, researcher, worker
-              ├─ AGENTS.md          Agent routing instructions
+              ├─ extensions/...     21 supporting extensions
+              ├─ agents/            scout, researcher, worker, javascript-pro, typescript-pro
               └─ GSD-WORKFLOW.md    Manual bootstrap protocol
 ```
 

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

@@ -37,8 +37,9 @@ import { getRtkSessionSavings } from "../shared/rtk-session-stats.js";
 import { initMetrics, resetMetrics, getLedger, getProjectTotals, formatCost, formatTokenCount, } from "./metrics.js";
 import { logWarning } from "./workflow-logger.js";
 import { homedir } from "node:os";
-import { join } from "node:path";
+import { join, dirname } from "node:path";
 import { readFileSync, existsSync, mkdirSync, writeFileSync, unlinkSync } from "node:fs";
+import { createRequire } from "node:module";
 import { atomicWriteSync } from "./atomic-write.js";
 import { autoCommitCurrentBranch, captureIntegrationBranch, detectWorktreeName, getCurrentBranch, getMainBranch, setActiveMilestoneId, } from "./worktree.js";
 import { GitServiceImpl } from "./git-service.js";
@@ -1021,7 +1022,12 @@ export async function startAuto(ctx, pi, base, verboseMode, options) {
         // Re-sync managed resources on resume so long-lived auto sessions pick up
         // bundled extension updates before resume-time verification/state logic runs.
         const agentDir = process.env.GSD_CODING_AGENT_DIR || join(process.env.GSD_HOME || homedir(), ".gsd", "agent");
-        const { initResources } = await import("../../../" + "resource-loader.js");
+        // Resolve resource-loader from the gsd-pi package root — the relative
+        // "../../../resource-loader.js" path only works from the source tree but
+        // breaks when extensions are deployed to ~/.gsd/agent/extensions/gsd/.
+        const _req = createRequire(import.meta.url);
+        const pkgRoot = dirname(_req.resolve("gsd-pi/package.json"));
+        const { initResources } = await import(join(pkgRoot, "dist", "resource-loader.js"));
         initResources(agentDir);
         // Open the project DB before rebuild/derive so resume uses DB-backed
         // state instead of falling back to stale markdown parsing (#2940).

package/dist/resources/extensions/gsd/bootstrap/write-gate.js

@@ -40,13 +40,9 @@ let activeQueuePhase = false;
 let pendingGateId = null;
 /**
  * Recognized gate question ID patterns.
- * These appear in both discuss-prepared.md (4-layer) and discuss.md (depth/requirements/roadmap).
+ * These appear in discuss.md (depth/requirements/roadmap).
  */
 const GATE_QUESTION_PATTERNS = [
-    "layer1_scope_gate",
-    "layer2_architecture_gate",
-    "layer3_error_gate",
-    "layer4_quality_gate",
     "depth_verification",
 ];
 /**

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

@@ -36,19 +36,7 @@ import { parkMilestone, discardMilestone } from "./milestone-actions.js";
 import { selectAndApplyModel } from "./auto-model-selection.js";
 import { DISCUSS_TOOLS_ALLOWLIST } from "./constants.js";
 import { getWorkflowTransportSupportError, getRequiredWorkflowToolsForGuidedUnit, } from "./workflow-mcp.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;
-}
+import { runPreparation, formatCodebaseBrief, formatPriorContextBrief, } from "./preparation.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";
@@ -335,7 +323,7 @@ function resolveAvailableModel(modelId, availableModels, currentProvider) {
  * Build the discuss-and-plan prompt for a new milestone.
  * Used by all three "new milestone" paths (first ever, no active, all complete).
  */
-function buildDiscussPrompt(nextId, preamble, _basePath) {
+function buildDiscussPrompt(nextId, preamble, _basePath, preparationContext) {
     const milestoneRel = `.gsd/milestones/${nextId}`;
     const inlinedTemplates = [
         inlineTemplate("project", "Project"),
@@ -347,6 +335,7 @@ function buildDiscussPrompt(nextId, preamble, _basePath) {
     return loadPrompt("discuss", {
         milestoneId: nextId,
         preamble,
+        preparationContext: preparationContext ?? "",
         contextPath: `${milestoneRel}/${nextId}-CONTEXT.md`,
         roadmapPath: `${milestoneRel}/${nextId}-ROADMAP.md`,
         inlinedTemplates,
@@ -377,50 +366,12 @@ 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.
+ * Preparation analyzes the codebase and prior context, injecting the results
+ * as supplementary context into the standard discuss template. The discuss
+ * template drives the conversation (asks "What's the vision?" first), while
+ * the preparation briefs give the agent grounding in the existing codebase.
  *
  * @param ctx - Extension command context with UI for progress notifications
  * @param nextId - The milestone ID being discussed
@@ -429,12 +380,12 @@ function buildPreparedPrompt(nextId, preamble, _basePath, prepResult) {
  * @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)
+    // Run preparation if enabled (default: true) — results are injected as
+    // supplementary context into the standard discuss prompt, NOT as a
+    // replacement template. The discuss prompt always leads with "What's the
+    // vision?" so the user defines the scope, not the codebase analysis.
+    let preparationContext = "";
     if (prefs.discuss_preparation !== false) {
         try {
             const prepResult = await runPreparation(basePath, ctx.ui, {
@@ -442,20 +393,24 @@ async function prepareAndBuildDiscussPrompt(ctx, nextId, preamble, basePath) {
                 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);
+                const codebaseBrief = prepResult.codebaseBrief || formatCodebaseBrief(prepResult.codebase);
+                const priorContextBrief = prepResult.priorContextBrief || formatPriorContextBrief(prepResult.priorContext);
+                const parts = [];
+                if (codebaseBrief)
+                    parts.push(`### Codebase Brief\n\n${codebaseBrief}`);
+                if (priorContextBrief)
+                    parts.push(`### Prior Context Brief\n\n${priorContextBrief}`);
+                if (parts.length > 0) {
+                    preparationContext = `\n\n## Preparation Context\n\nThe system analyzed the codebase before this discussion. Use these findings as background context — they describe what already exists, NOT what the user wants to build. Always ask the user what they want to build first.\n\n${parts.join("\n\n")}`;
+                }
             }
         }
-        catch {
-            // If preparation throws, ensure stale data doesn't persist
-            lastPreparationResult = null;
+        catch (err) {
+            logWarning("guided", `preparation failed, proceeding without context: ${err.message}`);
         }
     }
-    // Fall back to standard discuss prompt for backward compatibility
-    // lastPreparationResult is already null (cleared at entry or on error)
-    return buildDiscussPrompt(nextId, preamble, basePath);
+    return buildDiscussPrompt(nextId, preamble, basePath, preparationContext);
 }
 /**
  * Bootstrap a .gsd/ project from scratch for headless use.

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

@@ -5,7 +5,7 @@ import { tierOrdinal } from "./complexity-classifier.js";
 // ─── Known Model Tiers ───────────────────────────────────────────────────────
 // Maps known model IDs to their capability tier. Used when tier_models is not
 // explicitly configured to pick the best available model for each tier.
-const MODEL_CAPABILITY_TIER = {
+export const MODEL_CAPABILITY_TIER = {
     // Light-tier models (cheapest)
     "claude-haiku-4-5": "light",
     "claude-3-5-haiku-latest": "light",
@@ -80,15 +80,45 @@ const MODEL_COST_PER_1K_INPUT = {
 // Per-model capability profiles (0–100 scale). Used for capability-aware
 // model selection within an eligible tier set.
 export const MODEL_CAPABILITY_PROFILES = {
+    // ── Anthropic ──────────────────────────────────────────────────────────────
     "claude-opus-4-6": { coding: 95, debugging: 90, research: 85, reasoning: 95, speed: 30, longContext: 80, instruction: 90 },
     "claude-sonnet-4-6": { coding: 85, debugging: 80, research: 75, reasoning: 80, speed: 60, longContext: 75, instruction: 85 },
+    "claude-sonnet-4-5-20250514": { coding: 85, debugging: 80, research: 75, reasoning: 80, speed: 60, longContext: 75, instruction: 85 },
+    "claude-3-5-sonnet-latest": { coding: 82, debugging: 78, research: 72, reasoning: 78, speed: 62, longContext: 70, instruction: 82 },
     "claude-haiku-4-5": { coding: 60, debugging: 50, research: 45, reasoning: 50, speed: 95, longContext: 50, instruction: 75 },
+    "claude-3-5-haiku-latest": { coding: 60, debugging: 50, research: 45, reasoning: 50, speed: 95, longContext: 50, instruction: 75 },
+    "claude-3-haiku-20240307": { coding: 50, debugging: 40, research: 35, reasoning: 40, speed: 95, longContext: 40, instruction: 65 },
+    "claude-3-opus-latest": { coding: 90, debugging: 85, research: 82, reasoning: 90, speed: 35, longContext: 75, instruction: 88 },
+    // ── OpenAI GPT ─────────────────────────────────────────────────────────────
     "gpt-4o": { coding: 80, debugging: 75, research: 70, reasoning: 75, speed: 65, longContext: 70, instruction: 80 },
     "gpt-4o-mini": { coding: 55, debugging: 45, research: 40, reasoning: 45, speed: 90, longContext: 45, instruction: 70 },
+    "gpt-4-turbo": { coding: 78, debugging: 72, research: 68, reasoning: 72, speed: 50, longContext: 65, instruction: 78 },
+    "gpt-4.1": { coding: 82, debugging: 78, research: 72, reasoning: 78, speed: 62, longContext: 72, instruction: 82 },
+    "gpt-4.1-mini": { coding: 58, debugging: 48, research: 42, reasoning: 48, speed: 88, longContext: 48, instruction: 72 },
+    "gpt-4.1-nano": { coding: 40, debugging: 30, research: 25, reasoning: 30, speed: 95, longContext: 30, instruction: 60 },
+    "gpt-5": { coding: 92, debugging: 88, research: 85, reasoning: 92, speed: 40, longContext: 85, instruction: 90 },
+    "gpt-5-mini": { coding: 62, debugging: 52, research: 48, reasoning: 52, speed: 88, longContext: 52, instruction: 74 },
+    "gpt-5-nano": { coding: 42, debugging: 32, research: 28, reasoning: 32, speed: 95, longContext: 32, instruction: 62 },
+    "gpt-5-pro": { coding: 94, debugging: 90, research: 88, reasoning: 94, speed: 35, longContext: 88, instruction: 92 },
+    "gpt-5.1": { coding: 93, debugging: 89, research: 86, reasoning: 93, speed: 42, longContext: 86, instruction: 91 },
+    "gpt-5.1-codex-max": { coding: 90, debugging: 85, research: 70, reasoning: 85, speed: 55, longContext: 75, instruction: 85 },
+    "gpt-5.1-codex-mini": { coding: 65, debugging: 55, research: 40, reasoning: 50, speed: 88, longContext: 48, instruction: 72 },
+    "gpt-5.2": { coding: 93, debugging: 90, research: 87, reasoning: 93, speed: 42, longContext: 87, instruction: 91 },
+    "gpt-5.2-codex": { coding: 93, debugging: 90, research: 72, reasoning: 88, speed: 50, longContext: 78, instruction: 88 },
+    "gpt-5.3-codex": { coding: 94, debugging: 91, research: 74, reasoning: 89, speed: 50, longContext: 80, instruction: 89 },
+    "gpt-5.3-codex-spark": { coding: 68, debugging: 58, research: 42, reasoning: 52, speed: 90, longContext: 50, instruction: 74 },
+    "gpt-5.4": { coding: 95, debugging: 92, research: 88, reasoning: 94, speed: 42, longContext: 88, instruction: 92 },
+    // ── OpenAI o-series (reasoning-first) ──────────────────────────────────────
+    "o1": { coding: 78, debugging: 82, research: 78, reasoning: 90, speed: 20, longContext: 65, instruction: 82 },
+    "o3": { coding: 80, debugging: 85, research: 80, reasoning: 92, speed: 25, longContext: 70, instruction: 85 },
+    "o4-mini": { coding: 75, debugging: 80, research: 72, reasoning: 88, speed: 60, longContext: 65, instruction: 80 },
+    "o4-mini-deep-research": { coding: 75, debugging: 80, research: 85, reasoning: 88, speed: 30, longContext: 80, instruction: 80 },
+    // ── Google ─────────────────────────────────────────────────────────────────
     "gemini-2.5-pro": { coding: 75, debugging: 70, research: 85, reasoning: 75, speed: 55, longContext: 90, instruction: 75 },
     "gemini-2.0-flash": { coding: 50, debugging: 40, research: 50, reasoning: 40, speed: 95, longContext: 60, instruction: 65 },
+    "gemini-flash-2.0": { coding: 50, debugging: 40, research: 50, reasoning: 40, speed: 95, longContext: 60, instruction: 65 },
+    // ── DeepSeek ───────────────────────────────────────────────────────────────
     "deepseek-chat": { coding: 75, debugging: 65, research: 55, reasoning: 70, speed: 70, longContext: 55, instruction: 65 },
-    "o3": { coding: 80, debugging: 85, research: 80, reasoning: 92, speed: 25, longContext: 70, instruction: 85 },
 };
 // ─── Base Task Requirements Data Table ───────────────────────────────────────
 // Per-unit-type base requirement vectors. Weights indicate how important each

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

@@ -28,6 +28,8 @@ After reflection is confirmed, decide the approach based on the actual scope —
 
 **Anti-reduction rule:** If the user describes a big vision, plan the big vision. Do not ask "what's the minimum viable version?" or try to reduce scope unless the user explicitly asks for an MVP or minimal version. When something is complex or risky, phase it into a later milestone — do not cut it. The user's ambition is the target, and your job is to sequence it intelligently, not shrink it.
 
+{{preparationContext}}
+
 ## Mandatory Investigation Before First Question Round
 
 Before asking your first question, do a mandatory investigation pass. This is not optional.

package/dist/resources/extensions/gsd/templates/context.md

@@ -38,6 +38,28 @@ To call this milestone complete, we must prove:
 - {{one real end-to-end scenario}}
 - {{what cannot be simulated if this milestone is to be considered truly done}}
 
+## Architectural Decisions
+
+### {{decisionTitle}}
+
+**Decision:** {{decisionStatement}}
+
+**Rationale:** {{rationale}}
+
+**Alternatives Considered:**
+- {{alternative}} — {{whyNotChosen}}
+
+---
+
+> Add additional decisions as separate `### Decision Title` blocks following the same structure above.
+> See `.gsd/DECISIONS.md` for the full append-only register of all project decisions.
+
+## Error Handling Strategy
+
+{{errorHandlingStrategy}}
+
+> Describe the approach for handling failures, edge cases, and error propagation. Include retry policies, fallback behaviors, and user-facing error messages where relevant.
+
 ## Risks and Unknowns
 
 - {{riskOrUnknown}} — {{whyItMatters}}
@@ -47,8 +69,6 @@ To call this milestone complete, we must prove:
 - `{{fileOrModule}}` — {{howItRelates}}
 - `{{fileOrModule}}` — {{howItRelates}}
 
-> See `.gsd/DECISIONS.md` for all architectural and pattern decisions — it is an append-only register; read it during planning, append to it during execution.
-
 ## Relevant Requirements
 
 - {{requirementId}} — {{howThisMilestoneAdvancesIt}}
@@ -71,6 +91,18 @@ To call this milestone complete, we must prove:
 
 - {{systemOrService}} — {{howThisMilestoneInteractsWithIt}}
 
+## Testing Requirements
+
+{{testingRequirements}}
+
+> Specify test types (unit, integration, e2e), coverage expectations, and specific test scenarios that must pass.
+
+## Acceptance Criteria
+
+{{acceptanceCriteria}}
+
+> Per-slice acceptance criteria gathered during discussion. Each slice should have clear, testable criteria.
+
 ## Open Questions
 
 - {{question}} — {{currentThinking}}

package/dist/web/standalone/.next/BUILD_ID

@@ -1 +1 @@
-ka3ShQTakcliYL-EXRRb6
+5D80IWYltFwlAJiCZ84MC

package/dist/web/standalone/.next/app-path-routes-manifest.json

@@ -1,24 +1,24 @@
 {
   "/_not-found/page": "/_not-found",
   "/_global-error/page": "/_global-error",
-  "/api/boot/route": "/api/boot",
   "/api/bridge-terminal/input/route": "/api/bridge-terminal/input",
   "/api/bridge-terminal/resize/route": "/api/bridge-terminal/resize",
+  "/api/boot/route": "/api/boot",
   "/api/bridge-terminal/stream/route": "/api/bridge-terminal/stream",
   "/api/dev-mode/route": "/api/dev-mode",
   "/api/cleanup/route": "/api/cleanup",
+  "/api/doctor/route": "/api/doctor",
   "/api/captures/route": "/api/captures",
   "/api/export-data/route": "/api/export-data",
-  "/api/doctor/route": "/api/doctor",
   "/api/forensics/route": "/api/forensics",
-  "/api/git/route": "/api/git",
   "/api/browse-directories/route": "/api/browse-directories",
-  "/api/history/route": "/api/history",
+  "/api/git/route": "/api/git",
   "/api/hooks/route": "/api/hooks",
+  "/api/history/route": "/api/history",
   "/api/inspect/route": "/api/inspect",
   "/api/knowledge/route": "/api/knowledge",
-  "/api/live-state/route": "/api/live-state",
   "/api/notifications/route": "/api/notifications",
+  "/api/live-state/route": "/api/live-state",
   "/api/experimental/route": "/api/experimental",
   "/api/preferences/route": "/api/preferences",
   "/api/recovery/route": "/api/recovery",
@@ -26,22 +26,22 @@
   "/api/onboarding/route": "/api/onboarding",
   "/api/session/browser/route": "/api/session/browser",
   "/api/session/command/route": "/api/session/command",
-  "/api/files/route": "/api/files",
   "/api/session/events/route": "/api/session/events",
-  "/api/settings-data/route": "/api/settings-data",
   "/api/session/manage/route": "/api/session/manage",
   "/api/shutdown/route": "/api/shutdown",
+  "/api/settings-data/route": "/api/settings-data",
   "/api/skill-health/route": "/api/skill-health",
   "/api/steer/route": "/api/steer",
+  "/api/files/route": "/api/files",
   "/api/terminal/input/route": "/api/terminal/input",
   "/api/switch-root/route": "/api/switch-root",
   "/api/terminal/resize/route": "/api/terminal/resize",
-  "/api/terminal/sessions/route": "/api/terminal/sessions",
-  "/api/undo/route": "/api/undo",
   "/api/terminal/stream/route": "/api/terminal/stream",
-  "/api/update/route": "/api/update",
   "/api/terminal/upload/route": "/api/terminal/upload",
+  "/api/undo/route": "/api/undo",
+  "/api/terminal/sessions/route": "/api/terminal/sessions",
   "/api/visualizer/route": "/api/visualizer",
-  "/page": "/",
-  "/api/remote-questions/route": "/api/remote-questions"
+  "/api/update/route": "/api/update",
+  "/api/remote-questions/route": "/api/remote-questions",
+  "/page": "/"
 }

package/dist/web/standalone/.next/build-manifest.json

@@ -4,14 +4,14 @@
   ],
   "devFiles": [],
   "lowPriorityFiles": [
-    "static/ka3ShQTakcliYL-EXRRb6/_buildManifest.js",
-    "static/ka3ShQTakcliYL-EXRRb6/_ssgManifest.js"
+    "static/5D80IWYltFwlAJiCZ84MC/_buildManifest.js",
+    "static/5D80IWYltFwlAJiCZ84MC/_ssgManifest.js"
   ],
   "rootMainFiles": [
     "static/chunks/webpack-6e4d7e9a4f57bed4.js",
     "static/chunks/4bd1b696-e356ca5ba0218e27.js",
     "static/chunks/3794-42fdce068d44fa4f.js",
-    "static/chunks/main-app-d3d4c336195465f9.js"
+    "static/chunks/main-app-fdab67f7802d7832.js"
   ],
   "rootMainFilesTree": {},
   "pages": {