gsd-pi 2.75.0-dev.063e5a3 → 2.75.0-dev.96d4bb599

package/README.md

@@ -27,85 +27,120 @@ One command. Walk away. Come back to a built project with clean git history.
 
 ---
 
-## What's New in v2.71
+## What's New in v2.75
 
-### MCP Secure Env Collect
+### Knowledge Graph & Learning Extraction
 
-- **Secure credential collection over MCP** — the new `secure_env_collect` tool uses MCP form elicitation to collect secrets (API keys, tokens) from external clients without exposing values in tool output. Masks input in interactive mode.
-- **Hardened elicitation schema** — MCP elicitation schema handling is stricter, with proper validation and fallback for providers that don't support forms.
+- **Knowledge graph system** — GSD now builds a structured knowledge graph from project artifacts. Learnings, decisions, and patterns are parsed into queryable graph nodes.
+- **`/gsd extract-learnings`** — new command extracts decisions, lessons, patterns, and surprises from completed phase artifacts into `LEARNINGS.md`, which feeds the knowledge graph automatically.
 
-### MCP Reliability
+### Unified Orchestration Kernel (UOK)
 
-- **Stream ordering preserved** — MCP tool output now renders in the correct order, fixing interleaved output in Claude Code and other MCP clients.
-- **isError flag propagation** — workflow tool execution failures now correctly return `isError: true`, so MCP clients can distinguish success from failure.
-- **Multi-round discuss questions** — new-project discuss phase supports multi-round questioning with structured question gates.
+- **UOK is now the default** — the unified orchestration kernel replaces the legacy execution path. Plan-v2 compile gates, unified audit envelopes, turn-level git transaction modes, reactive/parallel scheduling via execution graph, and model policy filtering are all enforced by default. Legacy fallback remains as an emergency escape.
 
-### Model Selection Hardening
+### Extension API
 
-- **Unconfigured models blocked** — models without a configured provider are filtered from selection surfaces, preventing dispatch failures.
-- **Provider readiness required** — saved default model selection now verifies the provider is ready before accepting it.
-- **Session override honored** — `/gsd model` selection persists as a session override across all dispatch phases.
-- **Minimal context guard** — model override logic is skipped in minimal command contexts where it doesn't apply.
+- **GSD Extension API** — third-party extensions can now be loaded from `.gsd/extensions/`, with a formal API surface for hooking into the GSD lifecycle (#3338).
 
-### Auto-Mode Resilience
+### v1 Command Parity
 
-- **Credential cooldown recovery** — auto-mode survives transient 429 rate-limit responses with structured cooldown errors and a bounded retry budget.
-- **Fire-and-forget auto start** — auto start is detached from active turns to prevent blocking.
-- **Scoped forensics** — stuck-loop forensics are now scoped to auto sessions only, preventing false positives in interactive use.
+- **12 missing commands added** — GSD v2 now covers all v1 commands, closing the migration gap.
 
 ### TUI Improvements
 
-- **Overlay subscription fix** — resolved overlay subscription lifecycle and `Ctrl+Shift+P` shortcut conflict.
-- **Improved overlays and shortcuts** — GSD overlays, keyboard shortcuts, and notification flows redesigned for consistency.
-- **Pinned output restored** — pinned output bar displays above the editor during tool execution again.
-- **Turn completion cleanup** — pinned latest output is cleared on turn completion, preventing stale output from persisting.
-- **Secure input masking** — extension input values are masked in interactive mode when collecting secrets.
+- **Chat frame redesign** — compaction notices, tool execution cards, and the chat frame now share a unified styling with timestamps and model headers.
+- **Inline tool calls** — assistant tool calls render inline with text instead of grouped at the end.
+- **Compaction and success fixes** — tool cards no longer stick after compaction; success notifications are properly promoted.
 
-### Provider Fixes
+### Auto-Mode & Reliability
 
-- **Full OAuth login URLs** — OAuth login URLs are now displayed in full instead of being truncated.
-- **MiniMax bearer auth** — MiniMax Anthropic API requests use proper bearer authentication.
-- **Case-insensitive tool rendering** — renderable tool matching is now case-insensitive, fixing missed tool output.
-- **Headless idle timeout** — idle timeout is kept off during interactive tool execution in headless mode.
+- **Session timeout recovery** — auto-resume timer handles session creation timeouts; timeout counter resets on resume.
+- **Compaction checkpoint fix** — all session phases are checkpointed during compaction, not just the executing phase.
+- **MCP worktree routing** — tool writes are routed to the active worktree when a milestone has one; worktree paths are accepted in the project root guard.
+- **Single-writer DB invariant** — the engine database now enforces a single-writer invariant, preventing corruption from concurrent access.
 
-### Reliability & Internals
+### Providers & CI
 
-- **TOCTOU file locking** — race conditions in event log and custom workflow graph file locking are fixed with proper atomic lock acquisition.
-- **State derive refactor** — `deriveStateFromDb` god function extracted into composable, testable helpers.
-- **Windows portability** — hardened cross-platform portability across runtime, tooling, and CI.
-- **Model routing transparency** — dynamic routing is skipped for interactive dispatches; model changes are always shown in the banner.
-- **Capability-aware routing (ADR-004)** — full implementation of capability scoring, `before_model_select` hook, and task metadata extraction.
-- **Multi-model provider strategy (ADR-005)** — infrastructure for multi-provider model selection wired into live paths.
-- **Anti-fabrication guardrails** — discuss prompts enforce turn-taking to prevent fabricated user responses.
-- **Milestone worktree cleanup** — merged worktree cleanup uses the milestone branch instead of generic lookups.
-- **Tool cache control** — `cache_control` breakpoints added to tool definitions for improved prompt caching.
+- **Alibaba DashScope** — added as a standalone provider (#3891).
+- **Persistent language preference** — `/gsd language` sets a persistent language preference.
+- **Flat-rate provider detection** — extended to custom and externalCli providers.
+- **Thinking level as effort** — Claude Code now passes thinking level as an effort parameter.
+- **Hardened release pipeline** — workspace versions synced in release commits, package-lock.json regenerated during bumps, incremental build cache issues resolved.
 
 See the full [Changelog](./CHANGELOG.md) for details on every release.
 
 <details>
-<summary>Previous highlights (v2.70 and earlier)</summary>
+<summary>v2.74 highlights</summary>
+
+- **DB-authoritative milestone completeness** — milestone completion state is derived from the database, not file markers (#4179)
+- **Flat-rate provider detection** — extended to custom and externalCli providers
+- **Thinking level as effort** — Claude Code passes thinking level as an effort parameter
+- **False milestone merge prevention** — auto-mode no longer falsely merges after a `complete-milestone` failure (#4175)
+- **Premature auto-stop fix** — prevents auto-mode from stopping early on blocked phase + missing reassessment
+- **Inline tool call rendering** — assistant tool calls render inline with text instead of grouped at the end
+- **Custom model preservation** — custom model selection preserved on `/gsd auto` bootstrap (#4122)
+
+</details>
+
+<details>
+<summary>v2.73 highlights</summary>
+
+- **Alibaba DashScope provider** — added as a standalone provider (#3891)
+- **Layered depth enforcement** — discuss phase enforces depth gates for thorough requirements gathering (#4079)
+- **Memory pressure watchdog** — stuck detection state persisted across sessions (#3708)
+- **Ollama cloud auth** — cloud auth support and real context window resolution via `/api/show` (#4017)
+- **DB corruption prevention** — direct writes to `gsd.db` blocked via hooks (#3674)
+- **Circular dependency cleanup** — 3 circular dependencies broken in extension modules (#3730)
+- **Subagent permissions** — GSD subagents default to `bypassPermissions` with safe built-ins pre-authorized
+- **Security hardening** — auth middleware activated, shutdown/update routes hardened (#4023)
+- **Stale slice reconciliation** — stale slice rows reconciled and STATE.md rebuilt before DB close (#3658)
+- **Subagent model preference** — `subagent_model` preference wired through to dispatch prompt builders
+- **Pipeline integrity** — 5 pipeline issues addressed from release audit, package-lock.json regenerated during bumps
+
+</details>
+
+<details>
+<summary>v2.72 highlights</summary>
+
+- **8 specialist subagents** — new specialist subagents and slim pro agents with GSD phase guard to prevent conflicts
+- **Model selection hardening** — unconfigured models blocked from selection, provider readiness required, session override honored
+- **Auto-mode resilience** — credential cooldown recovery with bounded retry budget, fire-and-forget auto start, scoped forensics
+- **TUI overhaul** — overlays, keyboard shortcuts, and notification flows redesigned for consistency
+- **Capability-aware routing (ADR-004)** — full implementation of capability scoring, `before_model_select` hook, and task metadata extraction
+- **Multi-model provider strategy (ADR-005)** — infrastructure for multi-provider model selection wired into live paths
+- **Anti-fabrication guardrails** — discuss prompts enforce turn-taking to prevent fabricated user responses
+- **Windows portability** — hardened cross-platform portability across runtime, tooling, and CI
+- **MCP reliability** — every registered tool exposed, SDK subpath resolution fixed, abort signals threaded through
+- **Tool cache control** — `cache_control` breakpoints added to tool definitions for improved prompt caching
+
+</details>
+
+<details>
+<summary>v2.71 highlights</summary>
+
+- **Secure credential collection over MCP** — `secure_env_collect` tool uses MCP form elicitation to collect secrets without exposing values in tool output
+- **MCP stream ordering** — tool output renders in correct order, fixing interleaved output in Claude Code and other MCP clients
+- **isError flag propagation** — workflow tool execution failures correctly return `isError: true`
+- **Multi-round discuss questions** — new-project discuss phase supports multi-round questioning with structured question gates
+- **TOCTOU file locking** — race conditions in event log and custom workflow graph file locking fixed with atomic lock acquisition
+- **State derive refactor** — `deriveStateFromDb` god function extracted into composable, testable helpers
+- **Pinned output fixes** — restored above editor during tool execution, cleared on turn completion
+
+</details>
+
+<details>
+<summary>v2.70 and earlier</summary>
 
 - **Full workflow over MCP (v2.68)** — slice replanning, milestone management, slice completion, task completion, and core planning tools exposed over MCP
 - **Transport-gated MCP (v2.68)** — workflow tool availability adapts to provider transport capabilities automatically
 - **Contextual tips system (v2.68)** — TUI and web terminal surface contextual tips based on workflow state
 - **Ask user questions over MCP (v2.70)** — interactive questions exposed via elicitation for external integrations
 - **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
-- **Capability-aware model routing (ADR-004)** — capability scoring, `before_model_select` hook, and task metadata extraction
 - **VS Code sidebar redesign** — SCM provider, checkpoints, diagnostics panel, activity feed, workflow controls, session forking
-- **`/gsd parallel watch`** — native TUI overlay for real-time worker monitoring
-- **Codebase map** — automatic codebase map injection for fresh agent contexts
-- **`--resume` flag** — resume previous sessions from the CLI
-- **Concurrent invocation guard** — prevents overlapping auto-mode runs
-- **VS Code integration** — status bar, file decorations, bash terminal, session tree, conversation history, and code lens
 - **Skills overhaul** — 30+ skill packs covering major frameworks, databases, and cloud platforms
 - **Single-writer state engine** — disciplined state transitions with machine guards and TOCTOU hardening
 - **DB-backed planning tools** — atomic SQLite tool calls for state transitions
@@ -175,8 +210,8 @@ GSD v2 solves all of these because it's not a prompt framework anymore — it's
 | Roadmap reassessment | Manual                       | Automatic after each slice completes                    |
 | Skill discovery      | None                         | Auto-detect and install relevant skills during research |
 | Verification         | Manual                       | Automated verification commands with auto-fix retries   |
-| Reporting            | None                         | Self-contained HTML reports with metrics and dep graphs  |
-| Parallel execution   | None                         | Multi-worker parallel milestone orchestration            |
+| Reporting            | None                         | Self-contained HTML reports with metrics and dep graphs |
+| Parallel execution   | None                         | Multi-worker parallel milestone orchestration           |
 
 ### Migrating from v1
 
@@ -372,45 +407,47 @@ On first run, GSD launches a branded setup wizard that walks you through LLM pro
 
 ### Commands
 
-| Command                 | What it does                                                    |
-| ----------------------- | --------------------------------------------------------------- |
-| `/gsd`                  | Step mode — executes one unit at a time, pauses between each    |
-| `/gsd next`             | Explicit step mode (same as bare `/gsd`)                        |
-| `/gsd auto`             | Autonomous mode — researches, plans, executes, commits, repeats |
-| `/gsd quick`            | Execute a quick task with GSD guarantees, skip planning overhead |
-| `/gsd stop`             | Stop auto mode gracefully                                       |
-| `/gsd steer`            | Hard-steer plan documents during execution                      |
-| `/gsd discuss`          | Discuss architecture and decisions (works alongside auto mode)  |
-| `/gsd rethink`          | Conversational project reorganization                           |
-| `/gsd mcp`              | MCP server status and connectivity                              |
-| `/gsd status`           | Progress dashboard                                              |
-| `/gsd queue`            | Queue future milestones (safe during auto mode)                 |
-| `/gsd prefs`            | Model selection, timeouts, budget ceiling                       |
-| `/gsd migrate`          | Migrate a v1 `.planning` directory to `.gsd` format             |
-| `/gsd help`             | Categorized command reference for all GSD subcommands           |
-| `/gsd mode`             | Switch workflow mode (solo/team) with coordinated defaults      |
-| `/gsd forensics`        | Full-access GSD debugger for auto-mode failure investigation    |
-| `/gsd cleanup`          | Archive phase directories from completed milestones             |
+| Command                 | What it does                                                                  |
+| ----------------------- | ----------------------------------------------------------------------------- |
+| `/gsd`                  | Step mode — executes one unit at a time, pauses between each                  |
+| `/gsd next`             | Explicit step mode (same as bare `/gsd`)                                      |
+| `/gsd auto`             | Autonomous mode — researches, plans, executes, commits, repeats               |
+| `/gsd quick`            | Execute a quick task with GSD guarantees, skip planning overhead              |
+| `/gsd stop`             | Stop auto mode gracefully                                                     |
+| `/gsd steer`            | Hard-steer plan documents during execution                                    |
+| `/gsd discuss`          | Discuss architecture and decisions (works alongside auto mode)                |
+| `/gsd rethink`          | Conversational project reorganization                                         |
+| `/gsd mcp`              | MCP server status and connectivity                                            |
+| `/gsd status`           | Progress dashboard                                                            |
+| `/gsd queue`            | Queue future milestones (safe during auto mode)                               |
+| `/gsd prefs`            | Model selection, timeouts, budget ceiling                                     |
+| `/gsd migrate`          | Migrate a v1 `.planning` directory to `.gsd` format                           |
+| `/gsd help`             | Categorized command reference for all GSD subcommands                         |
+| `/gsd mode`             | Switch workflow mode (solo/team) with coordinated defaults                    |
+| `/gsd workflow`         | Unified workflow plugins — list, run `<name>`, install, info, validate        |
+| `/gsd start <template>` | Launch a bundled or custom workflow template (bugfix, release, etc.)          |
+| `/gsd forensics`        | Full-access GSD debugger for auto-mode failure investigation                  |
+| `/gsd cleanup`          | Archive phase directories from completed milestones                           |
 | `/gsd doctor`           | Runtime health checks — issues surface across widget, visualizer, and reports |
-| `/gsd keys`             | API key manager — list, add, remove, test, rotate, doctor       |
-| `/gsd logs`             | Browse activity, debug, and metrics logs                        |
-| `/gsd export --html`    | Generate HTML report for current or completed milestone         |
-| `/worktree` (`/wt`)     | Git worktree lifecycle — create, switch, merge, remove          |
-| `/voice`                | Toggle real-time speech-to-text (macOS, Linux)                  |
-| `/exit`                 | Graceful shutdown — saves session state before exiting          |
-| `/kill`                 | Kill GSD process immediately                                    |
-| `/clear`                | Start a new session (alias for `/new`)                          |
-| `Ctrl+Alt+G`            | Toggle dashboard overlay                                        |
-| `Ctrl+Alt+V`            | Toggle voice transcription                                      |
-| `Ctrl+Alt+B`            | Show background shell processes                                 |
-| `Alt+V`                 | Paste clipboard image (macOS)                                   |
-| `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 --worktree` (`-w`) | Launch an isolated worktree session for the active milestone    |
-| `gsd sessions`          | Interactive session picker — browse and resume any saved session |
+| `/gsd keys`             | API key manager — list, add, remove, test, rotate, doctor                     |
+| `/gsd logs`             | Browse activity, debug, and metrics logs                                      |
+| `/gsd export --html`    | Generate HTML report for current or completed milestone                       |
+| `/worktree` (`/wt`)     | Git worktree lifecycle — create, switch, merge, remove                        |
+| `/voice`                | Toggle real-time speech-to-text (macOS, Linux)                                |
+| `/exit`                 | Graceful shutdown — saves session state before exiting                        |
+| `/kill`                 | Kill GSD process immediately                                                  |
+| `/clear`                | Start a new session (alias for `/new`)                                        |
+| `Ctrl+Alt+G`            | Toggle dashboard overlay                                                      |
+| `Ctrl+Alt+V`            | Toggle voice transcription                                                    |
+| `Ctrl+Alt+B`            | Show background shell processes                                               |
+| `Alt+V`                 | Paste clipboard image (macOS)                                                 |
+| `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 --worktree` (`-w`) | Launch an isolated worktree session for the active milestone                  |
+| `gsd sessions`          | Interactive session picker — browse and resume any saved session              |
 
 ---
 
@@ -497,7 +534,7 @@ version: 1
 models:
   research: claude-sonnet-4-6
   planning:
-    model: claude-opus-4-6
+    model: claude-opus-4-7
     fallbacks:
       - openrouter/z-ai/glm-5
       - openrouter/minimax/minimax-m2.5
@@ -519,24 +556,24 @@ auto_report: true
 
 **Key settings:**
 
-| Setting                | What it controls                                                                                      |
-| ---------------------- | ----------------------------------------------------------------------------------------------------- |
-| `models.*`             | Per-phase model selection — string for a single model, or `{model, fallbacks}` for automatic failover |
-| `skill_discovery`      | `auto` / `suggest` / `off` — how GSD finds and applies skills                                         |
-| `auto_supervisor.*`    | Timeout thresholds for auto mode supervision                                                          |
-| `budget_ceiling`       | USD ceiling — auto mode pauses when reached                                                           |
-| `uat_dispatch`         | Enable automatic UAT runs after slice completion                                                      |
-| `always_use_skills`    | Skills to always load when relevant                                                                   |
-| `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`        | `none` (default), `worktree`, or `branch` — enable worktree or branch isolation for milestone work               |
-| `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)                                               |
-| `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)                                 |
+| Setting                           | What it controls                                                                                      |
+| --------------------------------- | ----------------------------------------------------------------------------------------------------- |
+| `models.*`                        | Per-phase model selection — string for a single model, or `{model, fallbacks}` for automatic failover |
+| `skill_discovery`                 | `auto` / `suggest` / `off` — how GSD finds and applies skills                                         |
+| `auto_supervisor.*`               | Timeout thresholds for auto mode supervision                                                          |
+| `budget_ceiling`                  | USD ceiling — auto mode pauses when reached                                                           |
+| `uat_dispatch`                    | Enable automatic UAT runs after slice completion                                                      |
+| `always_use_skills`               | Skills to always load when relevant                                                                   |
+| `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`                   | `none` (default), `worktree`, or `branch` — enable worktree or branch isolation for milestone work    |
+| `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)                                                    |
+| `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)                                 |
 
 ### Agent Instructions
 
@@ -553,14 +590,14 @@ Start GSD with `gsd --debug` to enable structured JSONL diagnostic logging. Debu
 GSD includes a coordinated token optimization system that reduces usage by 40-60% on cost-sensitive workloads. Set a single preference to coordinate model selection, phase skipping, and context compression:
 
 ```yaml
-token_profile: budget      # or balanced (default), quality
+token_profile: budget # or balanced (default), quality
 ```
 
-| Profile | Savings | What It Does |
-|---------|---------|-------------|
-| `budget` | 40-60% | Cheap models, skip research/reassess, minimal context inlining |
-| `balanced` | 10-20% | Default models, skip slice research, standard context |
-| `quality` | 0% | All phases, all context, full model power |
+| Profile    | Savings | What It Does                                                   |
+| ---------- | ------- | -------------------------------------------------------------- |
+| `budget`   | 40-60%  | Cheap models, skip research/reassess, minimal context inlining |
+| `balanced` | 10-20%  | Default models, skip slice research, standard context          |
+| `quality`  | 0%      | All phases, all context, full model power                      |
 
 **Complexity-based routing** automatically classifies tasks as simple/standard/complex and routes to appropriate models. Simple docs tasks get Haiku; complex architectural work gets Opus. The classification is heuristic (sub-millisecond, no LLM calls) and learns from outcomes via a persistent routing history.
 
@@ -572,44 +609,44 @@ See the full [Token Optimization Guide](./docs/user-docs/token-optimization.md)
 
 GSD ships with 24 extensions, all loaded automatically:
 
-| Extension              | What it provides                                                                                                       |
-| ---------------------- | ---------------------------------------------------------------------------------------------------------------------- |
-| **GSD**                | Core workflow engine, auto mode, commands, dashboard                                                                   |
+| Extension              | What it provides                                                                                                                                                                                                                                                                     |
+| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| **GSD**                | Core workflow engine, auto mode, commands, dashboard                                                                                                                                                                                                                                 |
 | **Browser Tools**      | Playwright-based browser with form intelligence, intent-ranked element finding, semantic actions, PDF export, session state persistence, network mocking, device emulation, structured extraction, visual diffing, region zoom, test code generation, and prompt injection detection |
-| **Search the Web**     | Brave Search, Tavily, or Jina page extraction                                                                          |
-| **Google Search**      | Gemini-powered web search with AI-synthesized answers                                                                  |
-| **Context7**           | Up-to-date library/framework documentation                                                                             |
-| **Background Shell**   | Long-running process management with readiness detection                                                               |
-| **Async Jobs**         | Background bash commands with job tracking and cancellation                                                            |
-| **Subagent**           | Delegated tasks with isolated context windows                                                                          |
-| **GitHub**             | Full-suite GitHub issues and PR management via `/gh` command                                                           |
-| **Mac Tools**          | macOS native app automation via Accessibility APIs                                                                     |
-| **MCP Client**         | Native MCP server integration via @modelcontextprotocol/sdk                                                            |
-| **Voice**              | Real-time speech-to-text transcription (macOS, Linux — Ubuntu 22.04+)                                                  |
-| **Slash Commands**     | Custom command creation                                                                                                |
-| **Ask User Questions** | Structured user input with single/multi-select                                                                         |
-| **Secure Env Collect** | Masked secret collection without manual .env editing                                                                   |
-| **Remote Questions**   | Route decisions to Slack/Discord when human input is needed in headless/CI mode                                         |
-| **Universal Config**   | Discover and import MCP servers and rules from other AI coding tools                                                    |
-| **AWS Auth**           | Automatic Bedrock credential refresh for AWS-hosted models                                                              |
-| **Ollama**             | First-class local LLM support via Ollama                                                                                |
-| **Claude Code CLI**    | External provider extension for Claude Code CLI                                                                         |
-| **cmux**               | Claude multiplexer integration — desktop notifications, sidebar metadata, visual subagent splits                        |
-| **GitHub Sync**        | Auto-sync milestones to GitHub Issues, PRs, and Milestones                                                              |
-| **LSP**                | Language Server Protocol — diagnostics, definitions, references, hover, rename                                          |
-| **TTSR**               | Tool-triggered system rules — conditional context injection based on tool usage                                         |
+| **Search the Web**     | Brave Search, Tavily, or Jina page extraction                                                                                                                                                                                                                                        |
+| **Google Search**      | Gemini-powered web search with AI-synthesized answers                                                                                                                                                                                                                                |
+| **Context7**           | Up-to-date library/framework documentation                                                                                                                                                                                                                                           |
+| **Background Shell**   | Long-running process management with readiness detection                                                                                                                                                                                                                             |
+| **Async Jobs**         | Background bash commands with job tracking and cancellation                                                                                                                                                                                                                          |
+| **Subagent**           | Delegated tasks with isolated context windows                                                                                                                                                                                                                                        |
+| **GitHub**             | Full-suite GitHub issues and PR management via `/gh` command                                                                                                                                                                                                                         |
+| **Mac Tools**          | macOS native app automation via Accessibility APIs                                                                                                                                                                                                                                   |
+| **MCP Client**         | Native MCP server integration via @modelcontextprotocol/sdk                                                                                                                                                                                                                          |
+| **Voice**              | Real-time speech-to-text transcription (macOS, Linux — Ubuntu 22.04+)                                                                                                                                                                                                                |
+| **Slash Commands**     | Custom command creation                                                                                                                                                                                                                                                              |
+| **Ask User Questions** | Structured user input with single/multi-select                                                                                                                                                                                                                                       |
+| **Secure Env Collect** | Masked secret collection without manual .env editing                                                                                                                                                                                                                                 |
+| **Remote Questions**   | Route decisions to Slack/Discord when human input is needed in headless/CI mode                                                                                                                                                                                                      |
+| **Universal Config**   | Discover and import MCP servers and rules from other AI coding tools                                                                                                                                                                                                                 |
+| **AWS Auth**           | Automatic Bedrock credential refresh for AWS-hosted models                                                                                                                                                                                                                           |
+| **Ollama**             | First-class local LLM support via Ollama                                                                                                                                                                                                                                             |
+| **Claude Code CLI**    | External provider extension for Claude Code CLI                                                                                                                                                                                                                                      |
+| **cmux**               | Claude multiplexer integration — desktop notifications, sidebar metadata, visual subagent splits                                                                                                                                                                                     |
+| **GitHub Sync**        | Auto-sync milestones to GitHub Issues, PRs, and Milestones                                                                                                                                                                                                                           |
+| **LSP**                | Language Server Protocol — diagnostics, definitions, references, hover, rename                                                                                                                                                                                                       |
+| **TTSR**               | Tool-triggered system rules — conditional context injection based on tool usage                                                                                                                                                                                                      |
 
 ### Bundled Agents
 
 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      |
-| **JavaScript Pro**  | JavaScript-specialized execution and debugging               |
-| **TypeScript Pro**  | TypeScript-specialized execution and debugging               |
+| 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               |
 
 ---
 
@@ -756,7 +793,7 @@ In your preferences (`/gsd prefs`), assign different models to different phases:
 models:
   research: openrouter/deepseek/deepseek-r1
   planning:
-    model: claude-opus-4-6
+    model: claude-opus-4-7
     fallbacks:
       - openrouter/z-ai/glm-5
   execution: claude-sonnet-4-6
@@ -769,8 +806,8 @@ Use expensive models where quality matters (planning, complex execution) and che
 
 ## Ecosystem
 
-| Project | Description |
-| ------- | ----------- |
+| Project                                                         | Description                                                                         |
+| --------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
 | [GSD2 Config Utility](https://github.com/jeremymcs/gsd2-config) | Standalone configuration tool for managing GSD preferences, providers, and API keys |
 
 ---

package/dist/claude-cli-check.d.ts

@@ -1,3 +1,13 @@
+/**
+ * Platform-correct binary name for the Claude Code CLI.
+ *
+ * On Windows, npm-global binaries are installed as `.cmd` shims and
+ * `execFileSync` does not auto-resolve the extension — calling bare
+ * `claude` would fail with ENOENT even when the CLI is installed and
+ * authenticated. Mirrors the `NPM_COMMAND` pattern in
+ * `src/resources/extensions/gsd/pre-execution-checks.ts`.
+ */
+export declare const CLAUDE_COMMAND: string;
 /**
  * Check if the `claude` binary is installed (regardless of auth state).
  */

package/dist/claude-cli-check.js

@@ -2,12 +2,22 @@
 // Lightweight check used at onboarding time (before extensions load).
 // The full readiness check with caching lives in the claude-code-cli extension.
 import { execFileSync } from 'node:child_process';
+/**
+ * Platform-correct binary name for the Claude Code CLI.
+ *
+ * On Windows, npm-global binaries are installed as `.cmd` shims and
+ * `execFileSync` does not auto-resolve the extension — calling bare
+ * `claude` would fail with ENOENT even when the CLI is installed and
+ * authenticated. Mirrors the `NPM_COMMAND` pattern in
+ * `src/resources/extensions/gsd/pre-execution-checks.ts`.
+ */
+export const CLAUDE_COMMAND = process.platform === 'win32' ? 'claude.cmd' : 'claude';
 /**
  * Check if the `claude` binary is installed (regardless of auth state).
  */
 export function isClaudeBinaryInstalled() {
     try {
-        execFileSync('claude', ['--version'], { timeout: 5_000, stdio: 'pipe' });
+        execFileSync(CLAUDE_COMMAND, ['--version'], { timeout: 5_000, stdio: 'pipe' });
         return true;
     }
     catch {
@@ -19,13 +29,13 @@ export function isClaudeBinaryInstalled() {
  */
 export function isClaudeCliReady() {
     try {
-        execFileSync('claude', ['--version'], { timeout: 5_000, stdio: 'pipe' });
+        execFileSync(CLAUDE_COMMAND, ['--version'], { timeout: 5_000, stdio: 'pipe' });
     }
     catch {
         return false;
     }
     try {
-        const output = execFileSync('claude', ['auth', 'status'], { timeout: 5_000, stdio: 'pipe' })
+        const output = execFileSync(CLAUDE_COMMAND, ['auth', 'status'], { timeout: 5_000, stdio: 'pipe' })
             .toString()
             .toLowerCase();
         return !(/not logged in|no credentials|unauthenticated|not authenticated/i.test(output));

package/dist/headless-events.d.ts

@@ -47,4 +47,4 @@ export declare function isInteractiveHeadlessTool(toolName: string | undefined):
 export declare function shouldArmHeadlessIdleTimeout(toolCallCount: number, interactiveToolCount: number): boolean;
 export declare const FIRE_AND_FORGET_METHODS: Set<string>;
 export declare const QUICK_COMMANDS: Set<string>;
-export declare function isQuickCommand(command: string): boolean;
+export declare function isQuickCommand(command: string, commandArgs?: readonly string[]): boolean;

package/dist/headless-events.js

@@ -100,6 +100,9 @@ export const QUICK_COMMANDS = new Set([
     'cleanup', 'migrate', 'doctor', 'remote', 'help', 'steer',
     'triage', 'visualize',
 ]);
-export function isQuickCommand(command) {
-    return QUICK_COMMANDS.has(command);
+const QUICK_WORKFLOW_SUBCOMMANDS = new Set(['list', 'validate']);
+export function isQuickCommand(command, commandArgs = []) {
+    if (QUICK_COMMANDS.has(command))
+        return true;
+    return command === 'workflow' && QUICK_WORKFLOW_SUBCOMMANDS.has(commandArgs[0] ?? '');
 }

package/dist/headless.js

@@ -606,7 +606,7 @@ async function runHeadlessOnce(options, restartCount) {
             }
         }
         // Quick commands: resolve on first agent_end
-        if (eventObj.type === 'agent_end' && isQuickCommand(options.command) && !completed) {
+        if (eventObj.type === 'agent_end' && isQuickCommand(options.command, options.commandArgs) && !completed) {
             completed = true;
             resolveCompletion();
             return;
@@ -622,10 +622,9 @@ async function runHeadlessOnce(options, restartCount) {
         // Kill child process — don't await, just fire and exit.
         // The main flow may be awaiting a promise that resolves when the child dies,
         // which would race with this handler. Exit synchronously to ensure correct exit code.
-        try {
-            client.stop().catch(() => { });
-        }
-        catch { }
+        void client.stop().catch((error) => {
+            process.stderr.write(`[headless] Warning: failed to stop child process: ${error instanceof Error ? error.message : String(error)}\n`);
+        });
         if (timeoutTimer)
             clearTimeout(timeoutTimer);
         if (idleTimer)
@@ -707,7 +706,7 @@ async function runHeadlessOnce(options, restartCount) {
         process.stdin.resume();
     }
     // Detect child process crash (read-only exit event subscription — not stdin access)
-    const internalProcess = client.process;
+    const internalProcess = Reflect.get(client, 'process');
     if (internalProcess) {
         internalProcess.on('exit', (code) => {
             if (!completed) {

package/dist/onboarding.d.ts

@@ -10,6 +10,20 @@
  * All steps are skippable. All errors are recoverable. Never crashes boot.
  */
 import type { AuthStorage } from '@gsd/pi-coding-agent';
+type ClackModule = typeof import('@clack/prompts');
+type PicoModule = {
+    cyan: (s: string) => string;
+    green: (s: string) => string;
+    yellow: (s: string) => string;
+    dim: (s: string) => string;
+    bold: (s: string) => string;
+    red: (s: string) => string;
+    reset: (s: string) => string;
+};
+interface RunOnboardingOptions {
+    /** Show logo + intro banner. Disable when onboarding is launched inside an active TUI session. */
+    showIntro?: boolean;
+}
 /**
  * Determine if the onboarding wizard should run.
  *
@@ -36,4 +50,9 @@ export declare function shouldRunOnboarding(authStorage: AuthStorage, settingsDe
  * All steps are skippable. All errors are recoverable.
  * Writes status to stderr during execution.
  */
-export declare function runOnboarding(authStorage: AuthStorage): Promise<void>;
+export declare function runOnboarding(authStorage: AuthStorage, opts?: RunOnboardingOptions): Promise<void>;
+export declare function runLlmStep(p: ClackModule, pc: PicoModule, authStorage: AuthStorage): Promise<boolean>;
+export declare function runWebSearchStep(p: ClackModule, pc: PicoModule, authStorage: AuthStorage, isAnthropicAuth: boolean): Promise<string | null>;
+export declare function runToolKeysStep(p: ClackModule, pc: PicoModule, authStorage: AuthStorage): Promise<number>;
+export declare function runRemoteQuestionsStep(p: ClackModule, pc: PicoModule, authStorage: AuthStorage): Promise<string | null>;
+export {};