gsd-pi 2.27.0 → 2.28.0

package/README.md

@@ -141,21 +141,23 @@ Auto mode is a state machine driven by files on disk. It reads `.gsd/STATE.md`,
 
 3. **Git worktree isolation** — Each milestone runs in its own git worktree with a `milestone/<MID>` branch. All slice work commits sequentially — no branch switching, no merge conflicts. When the milestone completes, it's squash-merged to main as one clean commit.
 
-4. **Crash recovery** — A lock file tracks the current unit. If the session dies, the next `/gsd auto` reads the surviving session file, synthesizes a recovery briefing from every tool call that made it to disk, and resumes with full context. Parallel orchestrator state is persisted to disk with PID liveness detection, so multi-worker sessions survive crashes too.
+4. **Crash recovery** — A lock file tracks the current unit. If the session dies, the next `/gsd auto` reads the surviving session file, synthesizes a recovery briefing from every tool call that made it to disk, and resumes with full context. Parallel orchestrator state is persisted to disk with PID liveness detection, so multi-worker sessions survive crashes too. In headless mode, crashes trigger automatic restart with exponential backoff (default 3 attempts).
 
-5. **Stuck detection** — If the same unit dispatches twice (the LLM didn't produce the expected artifact), it retries once with a deep diagnostic. If it fails again, auto mode stops with the exact file it expected.
+5. **Provider error recovery** — Transient provider errors (rate limits, 500/503 server errors, overloaded) auto-resume after a delay. Permanent errors (auth, billing) pause for manual review. The model fallback chain retries transient network errors before switching models.
 
-6. **Timeout supervision** — Soft timeout warns the LLM to wrap up. Idle watchdog detects stalls. Hard timeout pauses auto mode. Recovery steering nudges the LLM to finish durable output before giving up.
+6. **Stuck detection** — If the same unit dispatches twice (the LLM didn't produce the expected artifact), it retries once with a deep diagnostic. If it fails again, auto mode stops with the exact file it expected.
 
-7. **Cost tracking** — Every unit's token usage and cost is captured, broken down by phase, slice, and model. The dashboard shows running totals and projections. Budget ceilings can pause auto mode before overspending.
+7. **Timeout supervision** — Soft timeout warns the LLM to wrap up. Idle watchdog detects stalls. Hard timeout pauses auto mode. Recovery steering nudges the LLM to finish durable output before giving up.
 
-8. **Adaptive replanning** — After each slice completes, the roadmap is reassessed. If the work revealed new information that changes the plan, slices are reordered, added, or removed before continuing.
+8. **Cost tracking** — Every unit's token usage and cost is captured, broken down by phase, slice, and model. The dashboard shows running totals and projections. Budget ceilings can pause auto mode before overspending.
 
-9. **Verification enforcement** — Configure shell commands (`npm run lint`, `npm run test`, etc.) that run automatically after task execution. Failures trigger auto-fix retries before advancing. Configurable via `verification_commands`, `verification_auto_fix`, and `verification_max_retries` preferences.
+9. **Adaptive replanning** — After each slice completes, the roadmap is reassessed. If the work revealed new information that changes the plan, slices are reordered, added, or removed before continuing.
 
-10. **Milestone validation** — After all slices complete, a `validate-milestone` gate compares roadmap success criteria against actual results before sealing the milestone.
+10. **Verification enforcement** — Configure shell commands (`npm run lint`, `npm run test`, etc.) that run automatically after task execution. Failures trigger auto-fix retries before advancing. Configurable via `verification_commands`, `verification_auto_fix`, and `verification_max_retries` preferences.
 
-11. **Escape hatch** — Press Escape to pause. The conversation is preserved. Interact with the agent, inspect what happened, or just `/gsd auto` to resume from disk state.
+11. **Milestone validation** — After all slices complete, a `validate-milestone` gate compares roadmap success criteria against actual results before sealing the milestone.
+
+12. **Escape hatch** — Press Escape to pause. The conversation is preserved. Interact with the agent, inspect what happened, or just `/gsd auto` to resume from disk state.
 
 ### `/gsd` and `/gsd next` — Step Mode
 
@@ -247,14 +249,14 @@ gsd headless new-milestone --context spec.md --auto
 # One unit at a time (cron-friendly)
 gsd headless next
 
-# Machine-readable JSONL event stream
-gsd headless --json status
+# Instant JSON snapshot (no LLM, ~50ms)
+gsd headless query
 
 # Force a specific pipeline phase
 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. 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/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.
 
@@ -295,6 +297,7 @@ On first run, GSD launches a branded setup wizard that walks you through LLM pro
 | `gsd config`            | Re-run the setup wizard (LLM provider + tool keys)              |
 | `gsd update`            | Update GSD to the latest version                                |
 | `gsd headless [cmd]`    | Run `/gsd` commands without TUI (CI, cron, scripts)             |
+| `gsd headless query`    | Instant JSON snapshot — state, next dispatch, costs (no LLM)    |
 | `gsd --continue` (`-c`) | Resume the most recent session for the current directory        |
 | `gsd sessions`          | Interactive session picker — browse and resume any saved session |
 
@@ -414,7 +417,8 @@ auto_report: true
 | `skill_rules`          | Situational rules for skill routing                                                                   |
 | `skill_staleness_days` | Skills unused for N days get deprioritized (default: 60, 0 = disabled)                                |
 | `unique_milestone_ids` | Uses unique milestone names to avoid clashes when working in teams of people                          |
-| `git.isolation`        | `worktree` (default) or `none` — disable worktree isolation for projects that don't need it           |
+| `git.isolation`        | `worktree` (default), `branch`, or `none` — disable worktree isolation for projects that don't need it           |
+| `git.manage_gitignore` | Set `false` to prevent GSD from modifying `.gitignore`                                                           |
 | `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)                                               |

package/dist/headless-query.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Headless Query — `gsd headless query`
+ *
+ * Single read-only command that returns the full project snapshot as JSON
+ * to stdout, without spawning an LLM session. Instant (~50ms).
+ *
+ * Output: { state, next, cost }
+ *   state — deriveState() output (phase, milestones, progress, blockers)
+ *   next  — dry-run dispatch preview (what auto-mode would do next)
+ *   cost  — aggregated parallel worker costs
+ */
+import type { GSDState } from './resources/extensions/gsd/types.js';
+export interface QuerySnapshot {
+    state: GSDState;
+    next: {
+        action: 'dispatch' | 'stop' | 'skip';
+        unitType?: string;
+        unitId?: string;
+        reason?: string;
+    };
+    cost: {
+        workers: Array<{
+            milestoneId: string;
+            pid: number;
+            state: string;
+            cost: number;
+            lastHeartbeat: number;
+        }>;
+        total: number;
+    };
+}
+export interface QueryResult {
+    exitCode: number;
+    data?: QuerySnapshot;
+}
+export declare function handleQuery(basePath: string): Promise<QueryResult>;

package/dist/headless-query.js

@@ -0,0 +1,59 @@
+/**
+ * Headless Query — `gsd headless query`
+ *
+ * Single read-only command that returns the full project snapshot as JSON
+ * to stdout, without spawning an LLM session. Instant (~50ms).
+ *
+ * Output: { state, next, cost }
+ *   state — deriveState() output (phase, milestones, progress, blockers)
+ *   next  — dry-run dispatch preview (what auto-mode would do next)
+ *   cost  — aggregated parallel worker costs
+ */
+import { deriveState } from './resources/extensions/gsd/state.js';
+import { resolveDispatch } from './resources/extensions/gsd/auto-dispatch.js';
+import { readAllSessionStatuses } from './resources/extensions/gsd/session-status-io.js';
+import { loadEffectiveGSDPreferences } from './resources/extensions/gsd/preferences.js';
+// ─── Implementation ─────────────────────────────────────────────────────────
+export async function handleQuery(basePath) {
+    const state = await deriveState(basePath);
+    // Derive next dispatch action
+    let next;
+    if (!state.activeMilestone) {
+        next = {
+            action: 'stop',
+            reason: state.phase === 'complete' ? 'All milestones complete.' : state.nextAction,
+        };
+    }
+    else {
+        const loaded = loadEffectiveGSDPreferences();
+        const dispatch = await resolveDispatch({
+            basePath,
+            mid: state.activeMilestone.id,
+            midTitle: state.activeMilestone.title,
+            state,
+            prefs: loaded?.preferences,
+        });
+        next = {
+            action: dispatch.action,
+            unitType: dispatch.action === 'dispatch' ? dispatch.unitType : undefined,
+            unitId: dispatch.action === 'dispatch' ? dispatch.unitId : undefined,
+            reason: dispatch.action === 'stop' ? dispatch.reason : undefined,
+        };
+    }
+    // Aggregate parallel worker costs
+    const statuses = readAllSessionStatuses(basePath);
+    const workers = statuses.map((s) => ({
+        milestoneId: s.milestoneId,
+        pid: s.pid,
+        state: s.state,
+        cost: s.cost,
+        lastHeartbeat: s.lastHeartbeat,
+    }));
+    const snapshot = {
+        state,
+        next,
+        cost: { workers, total: workers.reduce((sum, w) => sum + w.cost, 0) },
+    };
+    process.stdout.write(JSON.stringify(snapshot) + '\n');
+    return { exitCode: 0, data: snapshot };
+}

package/dist/headless.js

@@ -12,10 +12,7 @@
  */
 import { existsSync, readFileSync, mkdirSync, writeFileSync } from 'node:fs';
 import { join, resolve } from 'node:path';
-// RpcClient is not in @gsd/pi-coding-agent's public exports — import from dist directly.
-// This relative path resolves correctly from both src/ (via tsx) and dist/ (compiled).
-import { RpcClient } from '../packages/pi-coding-agent/dist/modes/rpc/rpc-client.js';
-import { attachJsonlLineReader, serializeJsonLine } from '../packages/pi-coding-agent/dist/modes/rpc/jsonl.js';
+import { RpcClient, attachJsonlLineReader, serializeJsonLine } from '@gsd/pi-coding-agent';
 // ---------------------------------------------------------------------------
 // CLI Argument Parser
 // ---------------------------------------------------------------------------
@@ -336,6 +333,12 @@ async function runHeadlessOnce(options, restartCount) {
         process.stderr.write("[headless] Run 'gsd' interactively first to initialize a project.\n");
         process.exit(1);
     }
+    // Query: read-only state snapshot, no RPC child needed
+    if (options.command === 'query') {
+        const { handleQuery } = await import('./headless-query.js');
+        const result = await handleQuery(process.cwd());
+        return { exitCode: result.exitCode, interrupted: false };
+    }
     // Resolve CLI path for the child process
     const cliPath = process.env.GSD_BIN_PATH || process.argv[1];
     if (!cliPath) {

package/dist/help-text.js

@@ -46,6 +46,7 @@ const SUBCOMMAND_HELP = {
         '  next                 Run one unit',
         '  status               Show progress dashboard',
         '  new-milestone        Create a milestone from a specification document',
+        '  query                JSON snapshot: state + next dispatch + costs (no LLM)',
         '',
         'new-milestone flags:',
         '  --context <path>     Path to spec/PRD file (use \'-\' for stdin)',
@@ -62,6 +63,7 @@ const SUBCOMMAND_HELP = {
         '  cat spec.md | gsd headless new-milestone --context -   From stdin',
         '  gsd headless new-milestone --context spec.md --auto    Create + auto-execute',
         '  gsd headless --supervised auto                     Supervised orchestrator mode',
+        '  gsd headless query                              Instant JSON state snapshot',
         '',
         'Exit codes: 0 = complete, 1 = error/timeout, 2 = blocked',
     ].join('\n'),

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

@@ -103,7 +103,7 @@ import {
 import { computeBudgets, resolveExecutorContextWindow } from "./context-budget.js";
 import { join } from "node:path";
 import { sep as pathSep } from "node:path";
-import { readdirSync, readFileSync, existsSync, mkdirSync, writeFileSync, unlinkSync, statSync } from "node:fs";
+import { readdirSync, readFileSync, existsSync, mkdirSync, writeFileSync, renameSync, unlinkSync, statSync } from "node:fs";
 import { nativeIsRepo, nativeInit, nativeAddPaths, nativeCommit } from "./native-git-bridge.js";
 import {
   autoCommitCurrentBranch,
@@ -2138,7 +2138,11 @@ async function dispatchNextUnit(
     // Clear completed-units.json for the finished milestone
     try {
       const file = completedKeysPath(s.basePath);
-      if (existsSync(file)) writeFileSync(file, JSON.stringify([]), "utf-8");
+      if (existsSync(file)) {
+        const tmpFile = file + ".tmp";
+        writeFileSync(tmpFile, JSON.stringify([]), "utf-8");
+        renameSync(tmpFile, file);
+      }
       s.completedKeySet.clear();
     } catch { /* non-fatal */ }
 
@@ -2286,7 +2290,11 @@ async function dispatchNextUnit(
     // Clear completed-units.json for the finished milestone so it doesn't grow unbounded.
     try {
       const file = completedKeysPath(s.basePath);
-      if (existsSync(file)) writeFileSync(file, JSON.stringify([]), "utf-8");
+      if (existsSync(file)) {
+        const tmpFile = file + ".tmp";
+        writeFileSync(tmpFile, JSON.stringify([]), "utf-8");
+        renameSync(tmpFile, file);
+      }
       s.completedKeySet.clear();
     } catch { /* non-fatal */ }
     // ── Milestone merge: squash-merge milestone branch to main before stopping ──

package/dist/resources/extensions/gsd/commands.ts

@@ -77,7 +77,7 @@ function projectRoot(): string {
 
 export function registerGSDCommand(pi: ExtensionAPI): void {
   pi.registerCommand("gsd", {
-    description: "GSD — Get Shit Done: /gsd help|next|auto|stop|pause|status|visualize|queue|quick|capture|triage|dispatch|history|undo|skip|export|cleanup|mode|prefs|config|hooks|run-hook|skill-health|doctor|forensics|migrate|remote|steer|knowledge|new-milestone|parallel",
+    description: "GSD — Get Shit Done: /gsd help|next|auto|stop|pause|status|visualize|queue|quick|capture|triage|dispatch|history|undo|skip|export|cleanup|mode|prefs|config|hooks|run-hook|skill-health|doctor|forensics|migrate|remote|steer|knowledge|new-milestone|parallel|update",
     getArgumentCompletions: (prefix: string) => {
       const subcommands = [
         { cmd: "help", desc: "Categorized command reference with descriptions" },
@@ -113,6 +113,7 @@ export function registerGSDCommand(pi: ExtensionAPI): void {
         { cmd: "knowledge", desc: "Add persistent project knowledge (rule, pattern, or lesson)" },
         { cmd: "new-milestone", desc: "Create a milestone from a specification document (headless)" },
         { cmd: "parallel", desc: "Parallel milestone orchestration (start, status, stop, merge)" },
+        { cmd: "update", desc: "Update GSD to the latest version" },
       ];
       const parts = prefix.trim().split(/\s+/);
 
@@ -181,7 +182,7 @@ export function registerGSDCommand(pi: ExtensionAPI): void {
 
       if (parts[0] === "export" && parts.length <= 2) {
         const flagPrefix = parts[1] ?? "";
-        return ["--json", "--markdown"]
+        return ["--json", "--markdown", "--html", "--html --all"]
           .filter((f) => f.startsWith(flagPrefix))
           .map((f) => ({ value: `export ${f}`, label: f }));
       }
@@ -575,6 +576,11 @@ Examples:
         return;
       }
 
+      if (trimmed === "update") {
+        await handleUpdate(ctx);
+        return;
+      }
+
       if (trimmed === "") {
         // Bare /gsd defaults to step mode
         await startAuto(ctx, pi, projectRoot(), false, { step: true });
@@ -625,11 +631,12 @@ function showHelp(ctx: ExtensionCommandContext): void {
     "",
     "MAINTENANCE",
     "  /gsd doctor         Diagnose and repair .gsd/ state  [audit|fix|heal] [scope]",
-    "  /gsd export         Export milestone/slice results  [--json|--markdown|--html]",
+    "  /gsd export         Export milestone/slice results  [--json|--markdown|--html] [--all]",
     "  /gsd cleanup        Remove merged branches or snapshots  [branches|snapshots]",
     "  /gsd migrate        Upgrade .gsd/ structures to new format",
     "  /gsd remote         Control remote auto-mode  [slack|discord|status|disconnect]",
     "  /gsd inspect        Show SQLite DB diagnostics (schema, row counts, recent entries)",
+    "  /gsd update         Update GSD to the latest version via npm",
   ];
   ctx.ui.notify(lines.join("\n"), "info");
 }
@@ -2091,3 +2098,48 @@ Examples:
     ctx.ui.notify("Failed to dispatch hook. Auto-mode may have been cancelled.", "error");
   }
 }
+
+// ─── Self-update handler ────────────────────────────────────────────────────
+
+async function handleUpdate(ctx: ExtensionCommandContext): Promise<void> {
+  const { execSync } = await import("node:child_process");
+  const { compareSemver } = await import("../../../update-check.js");
+
+  const NPM_PACKAGE = "gsd-pi";
+  const current = process.env.GSD_VERSION || "0.0.0";
+
+  ctx.ui.notify(`Current version: v${current}\nChecking npm registry...`, "info");
+
+  let latest: string;
+  try {
+    latest = execSync(`npm view ${NPM_PACKAGE} version`, {
+      encoding: "utf-8",
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+  } catch {
+    ctx.ui.notify("Failed to reach npm registry. Check your network connection.", "error");
+    return;
+  }
+
+  if (compareSemver(latest, current) <= 0) {
+    ctx.ui.notify(`Already up to date (v${current}).`, "info");
+    return;
+  }
+
+  ctx.ui.notify(`Updating: v${current} → v${latest}...`, "info");
+
+  try {
+    execSync(`npm install -g ${NPM_PACKAGE}@latest`, {
+      stdio: ["ignore", "pipe", "ignore"],
+    });
+    ctx.ui.notify(
+      `Updated to v${latest}. Restart your GSD session to use the new version.`,
+      "info",
+    );
+  } catch {
+    ctx.ui.notify(
+      `Update failed. Try manually: npm install -g ${NPM_PACKAGE}@latest`,
+      "error",
+    );
+  }
+}

package/dist/resources/extensions/gsd/crash-recovery.ts

@@ -10,7 +10,7 @@
  * so the file on disk reflects every tool call up to the crash point).
  */
 
-import { writeFileSync, readFileSync, unlinkSync, existsSync } from "node:fs";
+import { renameSync, writeFileSync, readFileSync, unlinkSync, existsSync } from "node:fs";
 import { join } from "node:path";
 import { gsdRoot } from "./paths.js";
 
@@ -49,7 +49,10 @@ export function writeLock(
       completedUnits,
       sessionFile,
     };
-    writeFileSync(lockPath(basePath), JSON.stringify(data, null, 2), "utf-8");
+    const lp = lockPath(basePath);
+    const tmpLp = lp + ".tmp";
+    writeFileSync(tmpLp, JSON.stringify(data, null, 2), "utf-8");
+    renameSync(tmpLp, lp);
   } catch (e) { /* non-fatal: lock write failure */ void e; }
 }
 

package/dist/resources/extensions/gsd/docs/preferences-reference.md

@@ -104,6 +104,8 @@ Setting `prefer_skills: []` does **not** disable skill discovery — it just mea
   - Object with provider: `{ model: "claude-opus-4-6", provider: "bedrock" }` — explicit provider targeting in object format
   - Omit a key to use whatever model is currently active. Fallbacks are tried when model switching fails (provider unavailable, rate limited, etc.).
 
+- `skill_staleness_days`: number — skills unused for this many days get deprioritized during discovery. Set to `0` to disable staleness tracking. Default: `60`.
+
 - `skill_discovery`: controls how GSD discovers and applies skills during auto-mode. Valid values:
   - `auto` — skills are found and applied automatically without prompting.
   - `suggest` — (default) skills are identified during research but not installed automatically.
@@ -126,6 +128,7 @@ Setting `prefer_skills: []` does **not** disable skill discovery — it just mea
   - `merge_strategy`: `"squash"` or `"merge"` — controls how worktree branches are merged back. `"squash"` combines all commits into one; `"merge"` preserves individual commits. Default: `"squash"`.
   - `isolation`: `"worktree"`, `"branch"`, or `"none"` — controls auto-mode git isolation strategy. `"worktree"` creates a milestone worktree for isolated work; `"branch"` works directly in the project root but creates a milestone branch (useful for submodule-heavy repos); `"none"` works directly on the current branch with no worktree or milestone branch (ideal for step-mode with hot reloads). Default: `"worktree"`.
   - `commit_docs`: boolean — when `false`, prevents GSD from committing `.gsd/` planning artifacts to git. The `.gsd/` folder is added to `.gitignore` and kept local-only. Useful for teams where only some members use GSD, or when company policy requires a clean repository. Default: `true`.
+  - `manage_gitignore`: boolean — when `false`, GSD will not touch `.gitignore` at all. Useful when your project has a strictly managed `.gitignore` and you don't want GSD adding entries. Default: `true`.
   - `worktree_post_create`: string — script to run after a worktree is created (both auto-mode and manual `/worktree`). Receives `SOURCE_DIR` and `WORKTREE_DIR` as environment variables. Can be absolute or relative to project root. Runs with 30-second timeout. Failure is non-fatal (logged as warning). Default: none.
 
 - `unique_milestone_ids`: boolean — when `true`, generates milestone IDs in `M{seq}-{rand6}` format (e.g. `M001-eh88as`) instead of plain sequential `M001`. Prevents ID collisions in team workflows where multiple contributors create milestones concurrently. Both formats coexist — existing `M001`-style milestones remain valid. Default: `false`.
@@ -161,6 +164,31 @@ Setting `prefer_skills: []` does **not** disable skill discovery — it just mea
   - `on_milestone`: boolean — notify when a milestone finishes. Default: `true`.
   - `on_attention`: boolean — notify when manual attention is needed. Default: `true`.
 
+- `dynamic_routing`: configures the dynamic model router that adjusts model selection based on task complexity. Keys:
+  - `enabled`: boolean — enable dynamic routing. Default: `false`.
+  - `tier_models`: object — model overrides per complexity tier. Keys: `light`, `standard`, `heavy`. Values are model ID strings.
+  - `escalate_on_failure`: boolean — escalate to a higher-tier model when the current one fails. Default: `true`.
+  - `budget_pressure`: boolean — downgrade model tier when budget is under pressure. Default: `true`.
+  - `cross_provider`: boolean — allow routing across different providers. Default: `true`.
+  - `hooks`: boolean — enable routing hooks. Default: `true`.
+
+- `auto_visualize`: boolean — show a visualizer hint after each milestone completion in auto-mode. Default: `false`.
+
+- `auto_report`: boolean — generate an HTML report snapshot after each milestone completion. Default: `true`.
+
+- `parallel`: configures parallel orchestration for running multiple slices concurrently. Keys:
+  - `enabled`: boolean — enable parallel execution. Default: `false`.
+  - `max_workers`: number — maximum concurrent workers (1-4). Default: `2`.
+  - `budget_ceiling`: number — optional per-parallel-run budget ceiling.
+  - `merge_strategy`: `"per-slice"` or `"per-milestone"` — when to merge worktree results back. Default: `"per-milestone"`.
+  - `auto_merge`: `"auto"`, `"confirm"`, or `"manual"` — merge behavior after completion. `"auto"` merges immediately; `"confirm"` asks first; `"manual"` leaves branches for you. Default: `"confirm"`.
+
+- `verification_commands`: string[] — shell commands to run as verification after task execution (e.g., `["npm test", "npm run lint"]`). Commands run in order; if any fails, the task is marked as needing fixes.
+
+- `verification_auto_fix`: boolean — when `true`, automatically attempt to fix verification failures instead of just reporting them. Default: `false`.
+
+- `verification_max_retries`: number — maximum number of fix-and-retry cycles for verification failures. Default: `0` (no retries).
+
 - `uat_dispatch`: boolean — when `true`, enables UAT (User Acceptance Testing) dispatch mode. Default: `false`.
 
 - `post_unit_hooks`: array — hooks that fire after a unit completes. Each entry has:
@@ -531,3 +559,58 @@ remote_questions:
 ```
 
 Routes interactive questions to a Slack channel for headless auto-mode sessions. Questions time out after 15 minutes if unanswered.
+
+---
+
+## Dynamic Routing Example
+
+```yaml
+---
+version: 1
+dynamic_routing:
+  enabled: true
+  tier_models:
+    light: openrouter/minimax/minimax-m2.5
+    standard: claude-sonnet-4-6
+    heavy: claude-opus-4-6
+  escalate_on_failure: true
+  budget_pressure: true
+---
+```
+
+Automatically selects model tier based on task complexity. Simple tasks use the `light` model, complex tasks escalate to `heavy`. Under budget pressure, tasks are routed to cheaper tiers.
+
+---
+
+## Parallel Execution Example
+
+```yaml
+---
+version: 1
+parallel:
+  enabled: true
+  max_workers: 3
+  merge_strategy: per-milestone
+  auto_merge: confirm
+---
+```
+
+Runs up to 3 slices concurrently in separate worktrees. Results are merged per-milestone with user confirmation.
+
+---
+
+## Verification Example
+
+```yaml
+---
+version: 1
+verification_commands:
+  - npm test
+  - npm run lint
+  - npm run typecheck
+verification_auto_fix: true
+verification_max_retries: 2
+---
+```
+
+Runs test, lint, and typecheck after each task. On failure, auto-fix is attempted up to 2 times before reporting the issue.

package/dist/resources/extensions/gsd/export.ts

@@ -98,43 +98,106 @@ export function writeExportFile(
 export async function handleExport(args: string, ctx: ExtensionCommandContext, basePath: string): Promise<void> {
   // HTML report — delegates to the full visualizer-data pipeline
   if (args.includes("--html")) {
+    const generateAll = args.includes("--all");
     try {
       const { loadVisualizerData } = await import("./visualizer-data.js");
       const { generateHtmlReport } = await import("./export-html.js");
-      const { writeReportSnapshot, reportsDir } = await import("./reports.js");
+      const { writeReportSnapshot, loadReportsIndex } = await import("./reports.js");
       const { basename: bn } = await import("node:path");
       const data = await loadVisualizerData(basePath);
       const projName = basename(basePath);
       const gsdVersion = process.env.GSD_VERSION ?? "0.0.0";
-      const doneSlices = data.milestones.reduce((s, m) => s + m.slices.filter(sl => sl.done).length, 0);
-      const totalSlices = data.milestones.reduce((s, m) => s + m.slices.length, 0);
-      const outPath = writeReportSnapshot({
-        basePath,
-        html: generateHtmlReport(data, {
-          projectName: projName,
-          projectPath: basePath,
-          gsdVersion,
-          indexRelPath: "index.html",
-        }),
-        milestoneId: data.milestones.find(m => m.status === "active")?.id ?? "manual",
-        milestoneTitle: data.milestones.find(m => m.status === "active")?.title ?? "",
-        kind: "manual",
+      const doneMilestones = data.milestones.filter(m => m.status === "complete").length;
+
+      const htmlOpts = {
         projectName: projName,
         projectPath: basePath,
         gsdVersion,
-        totalCost: data.totals?.cost ?? 0,
-        totalTokens: data.totals?.tokens.total ?? 0,
-        totalDuration: data.totals?.duration ?? 0,
-        doneSlices,
-        totalSlices,
-        doneMilestones: data.milestones.filter(m => m.status === "complete").length,
-        totalMilestones: data.milestones.length,
-        phase: data.phase,
-      });
-      ctx.ui.notify(
-        `HTML report saved: .gsd/reports/${bn(outPath)}\nBrowse all reports: .gsd/reports/index.html`,
-        "success",
-      );
+        indexRelPath: "index.html",
+      };
+
+      if (generateAll) {
+        // Generate a report snapshot for every milestone
+        const existing = loadReportsIndex(basePath);
+        const existingIds = new Set(existing?.entries.map(e => e.milestoneId) ?? []);
+
+        const targets = data.milestones.filter(m => !existingIds.has(m.id));
+        if (targets.length === 0) {
+          ctx.ui.notify(
+            "All milestones already have report snapshots. Run without --all to create a new snapshot for the active milestone.",
+            "info",
+          );
+          return;
+        }
+
+        const html = generateHtmlReport(data, htmlOpts);
+        const paths: string[] = [];
+
+        for (const ms of targets) {
+          const msSlicesDone = ms.slices.filter(sl => sl.done).length;
+          const msSlicesTotal = ms.slices.length;
+
+          // Accumulate project-wide progress up to and including this milestone
+          const msIdx = data.milestones.indexOf(ms);
+          let cumulativeDone = 0;
+          let cumulativeTotal = 0;
+          for (let i = 0; i <= msIdx; i++) {
+            cumulativeDone += data.milestones[i].slices.filter(sl => sl.done).length;
+            cumulativeTotal += data.milestones[i].slices.length;
+          }
+
+          const outPath = writeReportSnapshot({
+            basePath,
+            html,
+            milestoneId: ms.id,
+            milestoneTitle: ms.title,
+            kind: ms.status === "complete" ? "milestone" : "manual",
+            projectName: projName,
+            projectPath: basePath,
+            gsdVersion,
+            totalCost: data.totals?.cost ?? 0,
+            totalTokens: data.totals?.tokens.total ?? 0,
+            totalDuration: data.totals?.duration ?? 0,
+            doneSlices: cumulativeDone,
+            totalSlices: cumulativeTotal,
+            doneMilestones: data.milestones.slice(0, msIdx + 1).filter(m => m.status === "complete").length,
+            totalMilestones: data.milestones.length,
+            phase: ms.status === "complete" ? "complete" : data.phase,
+          });
+          paths.push(bn(outPath));
+        }
+
+        ctx.ui.notify(
+          `Generated ${paths.length} report snapshot${paths.length !== 1 ? "s" : ""}:\n${paths.map(p => `  ${p}`).join("\n")}\nBrowse all reports: .gsd/reports/index.html`,
+          "success",
+        );
+      } else {
+        // Single report for the active milestone (existing behavior)
+        const doneSlices = data.milestones.reduce((s, m) => s + m.slices.filter(sl => sl.done).length, 0);
+        const totalSlices = data.milestones.reduce((s, m) => s + m.slices.length, 0);
+        const outPath = writeReportSnapshot({
+          basePath,
+          html: generateHtmlReport(data, htmlOpts),
+          milestoneId: data.milestones.find(m => m.status === "active")?.id ?? "manual",
+          milestoneTitle: data.milestones.find(m => m.status === "active")?.title ?? "",
+          kind: "manual",
+          projectName: projName,
+          projectPath: basePath,
+          gsdVersion,
+          totalCost: data.totals?.cost ?? 0,
+          totalTokens: data.totals?.tokens.total ?? 0,
+          totalDuration: data.totals?.duration ?? 0,
+          doneSlices,
+          totalSlices,
+          doneMilestones,
+          totalMilestones: data.milestones.length,
+          phase: data.phase,
+        });
+        ctx.ui.notify(
+          `HTML report saved: .gsd/reports/${bn(outPath)}\nBrowse all reports: .gsd/reports/index.html`,
+          "success",
+        );
+      }
     } catch (err) {
       ctx.ui.notify(
         `HTML export failed: ${err instanceof Error ? err.message : String(err)}`,

package/dist/resources/extensions/gsd/prompts/execute-task.md

@@ -25,7 +25,7 @@ A researcher explored the codebase and a planner decomposed the work — you are
 {{priorTaskLines}}
 
 Then:
-0. Narrate step transitions, key implementation decisions, and verification outcomes as you work. Keep it terse — one line between tool-call clusters, not between every call.
+0. Narrate step transitions, key implementation decisions, and verification outcomes as you work. Keep it terse — one line between tool-call clusters, not between every call — but write complete sentences in user-facing prose, not shorthand notes or scratchpad fragments.
 1. **Load relevant skills before writing code.** Check the `GSD Skill Preferences` block in system context and the `<available_skills>` catalog in your system prompt. For each skill that matches this task's technology stack (e.g., React, Next.js, accessibility, component design), `read` its SKILL.md file now. Skills contain implementation rules and patterns that should guide your code. If no skills match this task, skip this step.
 2. Execute the steps in the inlined task plan
 3. Build the real thing. If the task plan says "create login endpoint", build an endpoint that actually authenticates against a real store, not one that returns a hardcoded success response. If the task plan says "create dashboard page", build a page that renders real data from the API, not a component with hardcoded props. Stubs and mocks are for tests, not for the shipped feature.

package/dist/resources/extensions/gsd/prompts/plan-milestone.md

@@ -16,7 +16,7 @@ A **researcher agent** already explored the codebase and documented findings in
 
 After you finish, each slice goes through its own research → plan → execute cycle. Slice researchers dive deeper into the specific area. Slice planners decompose into tasks. Executors build each task. Your roadmap sets the strategic frame for all of them.
 
-Narrate your decomposition reasoning — why you're grouping work this way, what risks are driving the order, what verification strategy you're choosing and why.
+Narrate your decomposition reasoning — why you're grouping work this way, what risks are driving the order, what verification strategy you're choosing and why. Use complete sentences rather than planner shorthand or fragmentary notes.
 
 Then:
 1. Use the **Roadmap** output template from the inlined context above