gsd-pi 2.82.0 → 3.0.0-dev.8b8d129d7

package/README.md

@@ -27,38 +27,120 @@ One command. Walk away. Come back to a built project with clean git history.
 
 ---
 
-## What's New in v2.81
+## What's New in v3.0
 
-### Worktree Safety & Projection
+The v3.0 release closes the single-writer engine v3 control plane, finishes the ADR-013 memory cutover, and adds two new top-level commands. It also lands a long list of dispatch-ordering, recovery, and cross-platform fixes that have been accumulating since the v2.82 cut.
 
-- **Worktree safety is now fail-closed** — write/edit operations enforce the worktree-isolation contract before touching project files. If GSD cannot prove the active worktree is healthy, rooted correctly, and attached to the intended milestone, it stops instead of guessing.
-- **Custom-engine bypasses are explicit** — custom workflow units can opt out of worktree safety checks only through the dedicated path for that runtime. That keeps normal auto-mode writes protected while avoiding false failures for engines that do not use the same worktree lifecycle.
-- **Lifecycle and projection are split into dedicated modules** — worktree entry, exit, root projection, and merge finalization now flow through clearer boundaries. This makes it easier to reason about when state is copied into a milestone worktree, when it is projected back to the project root, and which module owns each step.
-- **Milestone merge closeout is harder to wedge** — stale leases, orphaned preflight stashes, branch-mode drift, reused branches, and wrong-branch merges are detected or recovered more reliably. If GSD finds completed work stranded in a milestone branch or preflight stash, startup and closeout paths now have better recovery hooks.
-- **Projection bypasses were closed** — post-unit and phase flows now route through the Worktree State Projection path instead of ad hoc file movement. That keeps database state, milestone artifacts, and root projections aligned during long-running auto-mode sessions.
+### New Commands
 
-### Memory, Context & Token Control
+- **`/gsd verdict <pass|needs-attention|needs-remediation>`** — manually override the recorded milestone validation verdict when auto-mode pauses with a non-passing verdict. Previously the only recovery path was hand-editing `VALIDATION.md` frontmatter or hand-crafting a seven-field `gsd_validate_milestone` call. The new command resolves the active milestone if `--milestone` is omitted, preserves every other section of the existing validation file, and requires `--rationale` for non-pass verdicts. Paused-state messages now reference the command directly instead of "update the verdict manually."
+- **`/gsd brief <mode>`** — generate a visual HTML brief in one of six modes (`diagram`, `plan`, `diff`, `recap`, `table`, `slides`). The HTML shell is unified with `/gsd export` so both surfaces produce consistent output.
+- **ROADMAP `[sketch]` badges** (ADR-011) — slices that have not been refined past sketch level are now badged in the rendered roadmap, so it's obvious at a glance which slices still need planning work.
 
-- **Memory relevance improved** — artifacts now carry integrity fingerprints, memories track last-hit time, and relevance scoring uses time decay. Recent, repeatedly useful memories can rank higher, while stale or superseded context is less likely to crowd out the current task.
-- **Artifact integrity is easier to preserve** — content hashes are retained through worktree reconciliation, so GSD can detect whether projected artifacts still match the state it expects. This supports safer recovery and reduces accidental drift between root and worktree state.
-- **Fallback memory search is safer** — when FTS5 is unavailable, LIKE-based fallback scans are capped and surfaced with warnings instead of silently becoming expensive. Memory ranking also guards against invalid decay settings producing unusable scores.
-- **Provider tools are scoped per request** — tool availability is narrowed at request time, with provider-boundary token audit support. The model sees the tools relevant to the current provider and task instead of carrying broad tool definitions through every request.
-- **Prompt and workflow context got leaner** — repeated workflow context is capped, prompt templates use portable paths, and many high-volume workflow prompts were compacted. The goal is less repeated instruction text in long sessions without removing the guardrails that keep planning, execution, and closeout on track.
-- **Token accounting is more accurate** — session tokens are reported separately from context in VS Code, the token encoder warms at startup, and provider-boundary audit hooks make it easier to understand where request size is coming from.
+### Auto Orchestration Parity (Single-Writer Engine v3 Control Plane)
+
+The v2.x dispatch layer accumulated parallel code paths between the legacy `auto.ts` loop and the newer Auto Orchestration kernel. v3.0 closes that gap:
+
+- **Dispatch adapter receives full session inputs** — the adapter now gets the same context the orchestrator does, eliminating a class of "the new path is missing X" bugs.
+- **Orchestrator reaches `runPreDispatch` parity** — pre-dispatch validation runs through the orchestrator path with the same checks the legacy path has, so behavior no longer depends on which entry point fired.
+- **Stuck-loop detection moved into Auto Orchestration** — previously partly in the legacy loop; now owned by the orchestrator so stuck detection participates in the same lifecycle as everything else.
+- **`AutoAdvanceResult` widened with `unit` and `action`** — callers can now branch on the actual outcome of an advance without re-deriving it.
+
+### Dispatch & Recovery Reliability
+
+- **State mutations now happen after pre-dispatch validation** — previously, auto-mode would mutate session state and emit journal events before pre-dispatch validation passed, so a failed validation could leave the journal believing a unit had dispatched. State writes now wait until validation succeeds.
+- **Provider 500 errors pause and retry instead of aborting** — auto-mode used to hard-stop the loop when a model provider returned a 5xx. The dispatch path now pauses with a retry budget so transient provider outages don't lose session state.
+- **`needs-attention` and `needs-remediation` verdicts guarded in dispatch** — completing-milestone no longer falsely loops when validation produced a non-pass terminal verdict. Combined with `/gsd verdict`, paused milestones are unstuck-able without hand-editing files.
+- **`validate-milestone` infinite-loop guard** — when an LLM failed to call `gsd_validate_milestone` and the unit ran without an artifact, dispatch would re-fire forever. The unit now fails closed with a recoverable error instead of looping.
+- **Empty milestone worktree recovery** — milestones that were entered, paused, and resumed against an empty/orphaned worktree now recover cleanly instead of stalling.
+- **Stuck-detection key consistency across sessions** — derived keys now match how DB persistence records them (bare `unitId`), so cross-session stuck detection actually fires.
+- **DB-backed stale worker cleanup also covers hook dispatchers** — previously could leave crashed hook-dispatch rows active and poison the next session.
+- **Stale lock detection when worker PID is dead** — `clearLock()` now marks the DB worker as stopping so resume after a crash isn't blocked until the 30-minute stale window expires.
+- **Auto-mode crash on MCP tool resolution failure** — research-slice no longer reports false success when an MCP tool fails to resolve; the dispatch loop catches the failure instead of treating it as a completion.
+- **Auto-commit submodule + empty `keyFiles` handling** — `git add -- (none)` no longer crashes auto-commit, and `keyFiles` that live inside a submodule no longer throw `pathspec is in submodule`.
+
+### Verification & Safety
+
+- **Reject unsafe verify commands before execution** — the verification gate now refuses to run commands that violate the tools policy, instead of executing first and failing the gate afterwards.
+- **Reconcile preflight stash collisions** — milestone-entry stash now reconciles with pre-existing stashes instead of silently overwriting them.
+- **Execute-task verification fails closed** — when verification cannot reach a definitive verdict, it fails the task instead of optimistically passing.
+- **Read-required-before-write in prompts** — prompt contracts now require reading a file before writing it, reducing the rate of clobbered edits.
+- **Doctor blocks snapshots that contain conflict markers** — `/gsd doctor` refuses to take a snapshot of a working tree with unresolved merge conflicts.
+
+### Memory Architecture Cutover (ADR-013)
+
+The v2.77 introduction of the memories table is now fully load-bearing. Decisions and KNOWLEDGE patterns/lessons read from and write to memories first, with `DECISIONS.md` and `KNOWLEDGE.md` projected from that source:
+
+- **Stage 1** — prompt-inline decisions read from memories.
+- **Stage 2a–2c** — `DECISIONS.md` projection sources from memories; `KNOWLEDGE.md` backfill + hybrid projection; `/gsd knowledge` routes patterns and lessons into memories.
+- **Stage 3** — `gsd_save_decision` no longer writes to the legacy decisions table.
+- **Preflight scanner** — detects pre-cutover artifacts and warns before they cause divergence.
+
+### Cross-Platform & Infrastructure
+
+- **gsd.db on WSL2 9p mounts** — WAL+mmap pragmas were corrupting `gsd.db` on `/mnt/c` and `/mnt/d`. The database layer now detects 9p mounts and uses safer pragmas.
+- **Milestone merge on Windows** — silent failure when `gsd.db` held a SQLite WAL lock is now surfaced as a recoverable error instead of an empty merge.
+- **Web UI multi-drive access** — Windows users can now point the web UI at projects outside the `C:` drive.
+- **Bedrock context overflow in `--print` mode** — fixed; long contexts no longer crash headless runs against Bedrock models.
+- **OpenAI Codex 429 retries** — no longer fire inside the provider cooldown window (Gemini path was already correct).
+- **Antigravity model removal** — the misleading 404 from Cloud Code Assist when Antigravity models are removed is now a clear error message.
+- **cmux usability after exit** — GSD no longer leaves cmux in a broken terminal state after exit.
+
+### TUI, Web, and Visualizer
+
+- **Web visualizer tabs updated** — refreshed tab set across the 10-tab visualizer.
+- **Auto resume blocker surface** — when resume is blocked (e.g., needs-remediation + all slices complete), the blocker reason is shown prominently instead of buried.
+- **Pi-coding-agent rendering** — empty reasoning blocks no longer render a blank assistant rail for GPT-5.5 tool-only turns; interactive tool output defaults to expanded.
+- **Step-mode polish** — completion surface preserved across step-mode boundary; next-action guidance clarified after pause.
+- **HTML shell unified across `/gsd export` and `/gsd brief`** — one shared visual language for generated reports.
+
+### Subagent Telemetry
+
+- **Random tracking names** — subagent runs get human-readable random names that show up in dashboards, making it easier to trace a specific run across logs.
+- **Resumable isolated launches** — subagent launch records persist, so a crashed subagent can be resumed instead of restarted from scratch.
+
+See the full [Changelog](./CHANGELOG.md) for the complete v3.0 entry and prior releases.
+
+<details>
+<summary>v2.82 highlights</summary>
+
+### State Reconciliation & Drift Detection (ADR-017)
+
+- **Unified drift-detection framework** — a new state-reconciliation layer replaces ad-hoc recovery checks. Each drift kind (stale worker, unregistered milestone, roadmap divergence, missing completion timestamp, merge-state, stale render) is owned by a focused detector + idempotent repair handler registered in a single registry, with a cap=2 retry contract that ensures repair-then-retry settles cleanly.
+- **Stale session locks no longer block resume** — when a `/gsd auto` process is SIGKILL'd, sleep-killed, or otherwise crashes, the `auto.lock` file is left behind with a dead PID. Previously you had to wait out a 30-minute stale window before `/gsd` would resume. The new `stale-worker` drift handler verifies the PID is alive and clears orphaned locks proactively on startup.
+- **Unregistered milestones get imported automatically** — if you scaffold a milestone directory (with `ROADMAP.md`/`CONTEXT.md`/`SUMMARY.md`) but never re-imported, dispatch couldn't see it. The `unregistered-milestone` handler now imports those rows idempotently before dispatch.
+- **ROADMAP and DB stay in sync** — divergence between `ROADMAP.md` (parsed slice sequence + `depends` declarations) and the corresponding DB slice rows is detected per-milestone and reconciled via importer upserts plus an explicit `syncSliceDependencies` pass.
+- **Missing completion timestamps backfill from disk** — entities marked complete in the DB but with a null `completed_at` are now backfilled from `SUMMARY.md` mtime, deterministically and idempotently. Tasks are checked independently of their parent slice status.
+- **Parallel spawns reconcile before fanning out** — `/gsd parallel start` and slice-parallel-dispatch now run reconciliation at the parent before spawning auto-loop workers. Gate failures surface a typed exit reason (`slice-parallel-reconciliation-failed`) and a user-visible message.
+
+### Worktree Lifecycle Refactor (ADR-016 — final phases)
+
+- **Phase 2 complete** — the worktree-manager module finished absorbing fs primitives, git-CLI primitives, worktree-manager helpers, cache/preferences/paths, and the final `gitServiceFactory`. Lifecycle verbs are now first-class: `adoptOrphanWorktree`, `adoptSessionRoot`, `resumeFromPausedSession`, and `restoreToProjectRoot` are explicit entry points.
+- **Phase 3 closes strict-closure residuals** — dead defensive fallbacks removed from `auto.ts` stop-path catch blocks. The public `WorktreeLifecycleDeps` interface dropped 15 `@deprecated` optional fields; the active dep bag is now three fields.
+
+### Auto-Mode Reliability
+
+- **`complete-slice` closeout is read-only** — closeout prompts can no longer write project files, removing closeout-vs-next-slice races.
+- **Verification retries back off properly** — bounded exponential backoff with stuck detection between attempts; transient failures no longer spin.
+- **Auto-loop exit paths are journaled end-to-end** — post-unit finalize stops, all unit-end exits, and the run-unit failsafe now journal cleanly.
+- **Ghost completions and stale telemetry are guarded** — no stops on ghost completions before milestone stops fire; unmerged-exit telemetry gated on active worktrees.
 
 ### TUI & Operator Experience
 
-- **Compact tool output is more useful** — compact cards show tool targets and low-signal tool output can roll up by phase.
-- **Terminal UI refreshed** — chat/tool cards align with the terminal design, adaptive refresher layouts landed, and the welcome/header lifecycle is more stable.
-- **Auto-mode stays anchored** — bottom anchoring, direct tool execution rollups, and lifecycle hook shutdown behavior were tightened.
+- **Operations console redesign** — auto-mode dashboard, notification overlay, parallel-monitor overlay, health widget, header renderer, and welcome screen rebuilt against a shared `render-kit`.
+- **Milestone completion rollup** — `CompletionDashboardSnapshot` summarizes success criteria, DoD, requirements, deviations, follow-ups, key decisions, key files, lessons, cost, tokens, cache hit rate, and slice progress at milestone boundaries.
+
+</details>
 
-### Reliability, Tests & CI
+<details>
+<summary>v2.81 highlights</summary>
 
-- **Auto-mode recovery tightened** — crash recovery, session handoff, stale milestone completion replay, stale leases, and complete-project restart loops were all hardened.
-- **E2E coverage expanded** — real-process MCP, fake LLM, native ABI, schema migration, Docker runtime, Windows runner, and multi-iteration loop coverage landed.
-- **CI is faster and less noisy** — merge/build gates were simplified, expensive PR jobs are gated, and merge-conflict PRs skip heavy jobs.
+- **Worktree safety is fail-closed** — write/edit operations enforce the worktree-isolation contract; lifecycle and projection split into dedicated modules; milestone merge closeout is harder to wedge.
+- **Memory, context, and token control** — artifact integrity fingerprints, time-decay memory ranking, safer FTS5 fallback, request-time tool scoping, leaner workflow prompts, and more accurate session/context token accounting.
+- **TUI polish** — compact tool output with targets, refreshed chat/tool cards, adaptive refresher layouts, stable welcome/header lifecycle, and bottom-anchored auto-mode rendering.
+- **Reliability, tests, and CI** — auto-mode recovery and session handoff hardened, broad E2E coverage expansion (real-process MCP, fake LLM, native ABI, Docker, Windows), and a faster, less-noisy CI gate setup.
 
-See the full [Changelog](./CHANGELOG.md) for the complete v2.81 entry and prior releases.
+</details>
 
 <details>
 <summary>v2.80 highlights</summary>
@@ -108,7 +190,7 @@ See the full [Changelog](./CHANGELOG.md) for the complete v2.81 entry and prior
 
 - **Context Mode** — dispatch builds task-ready context automatically (artifacts, prior session, milestone/slice signals, execution metadata); enabled by default for new projects
 - **Sandboxed execution tools** — `gsd_exec_search`, `gsd_resume`, and sandboxed tool-output paths for context-mode flows
-- **Memory architecture (ADR-013)** — `memories` table is now authoritative; `structured_fields` adds typed metadata; dual-write migration landed with decisions backfill
+- **Memory architecture (ADR-013)** — `memories` table is now authoritative; `structured_fields` adds typed metadata; decisions and KNOWLEDGE patterns/lessons are memory-backed projections after the cutover
 - **Skill coverage** — 9 gap-closing skills landed plus 6 planning/design skills surfaced
 - **Hook stack** — Layer 0 shell hooks and additional Layer 2 lifecycle events
 - **TUI polish** — dedicated chat-frame style for skill invocations; active-row overflow fixes
@@ -328,7 +410,9 @@ Plan (with integrated research) → Execute (per task) → Complete → Reassess
                                                                               Validate Milestone → Complete Milestone
 ```
 
-**Plan** scouts the codebase, researches relevant docs, and decomposes the slice into tasks with must-haves (mechanically verifiable outcomes). **Execute** runs each task in a fresh context window with only the relevant files pre-loaded — then runs configured verification commands (lint, test, etc.) with auto-fix retries. **Complete** writes the summary, UAT script, marks the roadmap, and commits with meaningful messages derived from task summaries. **Reassess** checks if the roadmap still makes sense given what was learned. **Validate Milestone** runs a reconciliation gate after all slices complete — comparing roadmap success criteria against actual results before sealing the milestone.
+**Plan** scouts the codebase, researches relevant docs, and decomposes the slice into tasks with must-haves (mechanically verifiable outcomes). **Execute** runs each task in a fresh context window with only the relevant files pre-loaded, then runs configured verification commands (lint, test, etc.) with auto-fix retries before the task closeout commit or snapshot is published. Failed or incomplete verification blocks execute-task closeout. **Complete** writes the summary, UAT script, marks the roadmap, and commits with meaningful messages derived from task summaries. **Reassess** checks if the roadmap still makes sense given what was learned. **Validate Milestone** runs a reconciliation gate after all slices complete — comparing roadmap success criteria against actual results before sealing the milestone.
+
+When progressive planning is enabled, the first slice is fully planned up front while later slices may appear in `M###-ROADMAP.md` with a `` `[sketch]` `` badge. A sketch slice has an approved title, dependency shape, demo line, and scope boundary, but it has not yet been expanded into task plans; auto mode runs `refine-slice` just before execution to turn the sketch into a full slice plan using the latest prior-slice summaries.
 
 ### `/gsd auto` — The Main Event
 
@@ -340,7 +424,9 @@ This is what makes GSD different. Run it, walk away, come back to built software
 
 Auto mode is a state machine driven by the GSD database at the project root. It derives the next unit of work from authoritative SQLite state, creates a fresh agent session, injects a focused prompt with all relevant context pre-inlined, and lets the LLM execute. When the LLM finishes, auto mode persists the result to the database, refreshes markdown projections such as `STATE.md`, and dispatches the next unit.
 
-The database is authoritative for milestones, slices, tasks, requirements, decisions, summaries, and completion status. Markdown under `.gsd/` is a rendered projection for review, prompts, and git-friendly history; it is not a runtime fallback unless you explicitly run a recovery/import command. In worktree mode, project-root DB state remains authoritative and worktree markdown projections are not synced back as state.
+The database is authoritative for milestones, slices, tasks, requirements, summaries, and completion status. Durable decisions and project knowledge are stored in the `memories` table: decisions are `architecture` memories, and KNOWLEDGE patterns/lessons are `pattern`/`gotcha` memories. Markdown under `.gsd/` is a rendered projection for review, prompts, and git-friendly history; it is not a runtime fallback unless you explicitly run a recovery/import command. In worktree mode, artifact/projection writes are rendered under the active worktree-local `.gsd/`, while the project-root DB remains authoritative runtime state.
+
+`KNOWLEDGE.md` is hybrid: rules remain file-canonical, while patterns and lessons are stored in the `memories` table and rendered back into `KNOWLEDGE.md` on the next session-start projection. Existing pattern and lesson rows are backfilled into memories before projection, so newly captured patterns and lessons may appear in memory-backed prompt context before the file view refreshes.
 
 **What happens under the hood:**
 
@@ -364,7 +450,7 @@ The database is authoritative for milestones, slices, tasks, requirements, decis
 
 10. **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.
 
-11. **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. Auto-discovered checks from `package.json` run in advisory mode — they log warnings but don't block on pre-existing errors. Configurable via `verification_commands`, `verification_auto_fix`, and `verification_max_retries` preferences.
+11. **Verification enforcement** — Configure simple executable commands (`npm run lint`, `npm run test`, etc.) that run automatically after task execution. Verification commands must not use shell composition or control syntax such as pipes, redirects, semicolons, backticks, or command substitution. Failures trigger auto-fix retries before advancing. Execute-task commits and snapshots are deferred until verification passes; failed or incomplete verification blocks closeout instead of publishing changes. Auto-discovered checks from `package.json` and Python pytest project markers (`python-project`) run in advisory mode — they log warnings but don't block on pre-existing errors. Configurable via `verification_commands`, `verification_auto_fix`, and `verification_max_retries` preferences.
 
 12. **Milestone validation** — After all slices complete, a `validate-milestone` gate compares roadmap success criteria against actual results before sealing the milestone.
 
@@ -490,7 +576,8 @@ On first run, GSD launches a branded setup wizard that walks you through LLM pro
 | `/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 brief <mode>`     | Generate a visual HTML brief (diagram, plan, diff, recap, table, slides)      |
+| `/gsd queue`            | Queue/reorder future milestones (`pending`, `queued`, or legacy `planned`; 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                         |
@@ -534,13 +621,13 @@ Every dispatch is carefully constructed. The LLM never wastes tool calls on orie
 | `gsd.db`           | Authoritative runtime state for hierarchy and completion        |
 | `PROJECT.md`       | Living doc — what the project is right now                      |
 | `REQUIREMENTS.md`  | Project-level capability contract and out-of-scope list         |
-| `DECISIONS.md`     | Append-only register of architectural decisions                 |
-| `KNOWLEDGE.md`     | Cross-session rules, patterns, and lessons learned              |
+| `DECISIONS.md`     | Projected register of memory-backed architectural decisions     |
+| `KNOWLEDGE.md`     | Hybrid knowledge projection: manual Rules plus memory-backed Patterns/Lessons |
 | `RUNTIME.md`       | Runtime context — API endpoints, env vars, services (v2.39)     |
 | `runtime/research-decision.json` | Deep-mode marker for project research vs skip       |
 | `research/*.md`    | Optional deep-mode project research: stack, features, architecture, pitfalls |
 | `STATE.md`         | Quick-glance dashboard rendered from the database                |
-| `M001-ROADMAP.md`  | Milestone plan with slice checkboxes, risk levels, dependencies |
+| `M001-ROADMAP.md`  | Milestone plan with slice checkboxes, risk levels, dependencies, and `` `[sketch]` `` badges for slices awaiting `refine-slice` |
 | `M001-CONTEXT.md`  | User decisions from the discuss phase                           |
 | `M001-RESEARCH.md` | Codebase and ecosystem research                                 |
 | `S01-PLAN.md`      | Slice task decomposition with must-haves                        |
@@ -577,6 +664,12 @@ Every task has must-haves — mechanically checkable outcomes:
 
 The verification ladder: static checks → command execution → behavioral testing → human review (only when the agent genuinely can't verify itself).
 
+### Project Knowledge
+
+`.gsd/KNOWLEDGE.md` remains the human-readable register for durable project knowledge, but the memory store is now authoritative for generated Patterns and Lessons. On startup, GSD backfills existing `## Patterns` and `## Lessons Learned` rows into `gsd.db` memories, then rewrites `KNOWLEDGE.md` as a hybrid projection: the manual `## Rules` section is preserved from the file, while Patterns and Lessons are rendered from the backfilled memory rows.
+
+Keep hand-authored operating rules in `## Rules` or add them with `/gsd knowledge rule`. Patterns and Lessons that agents discover are retrieved through the memory system for prompts and projected back into `KNOWLEDGE.md` for review, reports, and git history.
+
 ### Dashboard
 
 `Ctrl+Alt+G` or `/gsd status` opens a real-time overlay showing:
@@ -651,7 +744,7 @@ auto_report: true
 | `context_mode.exec_stdout_cap_bytes` | Persisted stdout cap for `gsd_exec` output (default: 1048576)                                      |
 | `context_mode.exec_digest_chars`  | Trailing stdout characters returned to the agent context (default: 300)                              |
 | `context_mode.exec_env_allowlist` | Environment variables forwarded to sandboxed `gsd_exec` runs in addition to `PATH` and `HOME`        |
-| `verification_commands`           | Array of shell commands to run after task execution (e.g., `["npm run lint", "npm run test"]`)        |
+| `verification_commands`           | Array of simple executable commands to run after task execution (e.g., `["npm run lint", "npm run test"]`); avoid pipes, redirects, semicolons, backticks, and command substitution |
 | `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                                         |
@@ -821,7 +914,7 @@ gsd (CLI binary)
 - **`pkg/` shim directory** — `PI_PACKAGE_DIR` points here (not project root) to avoid Pi's theme resolution collision with our `src/` directory. Contains only `piConfig` and theme assets.
 - **Two-file loader pattern** — `loader.ts` sets all env vars with zero SDK imports, then dynamic-imports `cli.ts` which does static SDK imports. This ensures `PI_PACKAGE_DIR` is set before any SDK code evaluates.
 - **Always-overwrite sync** — `npm update -g` takes effect immediately. Bundled extensions and agents are synced to `~/.gsd/agent/` on every launch, not just first run.
-- **DB-authoritative state** — the project-root GSD database is the runtime source of truth. `.gsd/` markdown files are rendered projections for review, prompt context, and git history. No in-memory state survives across sessions.
+- **DB-authoritative state** — the project-root GSD database is the runtime source of truth. `.gsd/` markdown files are rendered projections for review, prompt context, and git history. `KNOWLEDGE.md` keeps rules file-canonical and projects patterns/lessons from `memories` at session start. No in-memory state survives across sessions.
 
 ---
 

package/dist/cli.js

@@ -114,6 +114,24 @@ async function reapplyValidatedModelOnFallback(session, modelRegistry, settingsM
         // Provider not ready — leave session on its current model
     }
 }
+/**
+ * Apply the --model CLI flag override to the active session.
+ * Searches available models by exact id or provider/id pattern and warns
+ * on stderr when the requested model is not found in the registry.
+ */
+function applyModelOverride(session, modelRegistry, modelFlag) {
+    if (!modelFlag)
+        return;
+    const available = modelRegistry.getAvailable();
+    const match = available.find((m) => m.id === modelFlag) ||
+        available.find((m) => `${m.provider}/${m.id}` === modelFlag);
+    if (match) {
+        void session.setModel(match);
+    }
+    else {
+        process.stderr.write(`[gsd] Warning: Model "${modelFlag}" not found. Using configured default.\n`);
+    }
+}
 const cliFlags = parseCliArgs(process.argv);
 const isPrintMode = cliFlags.print || cliFlags.mode !== undefined;
 // `gsd [subcommand] --help` / `-h` — print help before any subcommand runs.
@@ -597,15 +615,7 @@ if (isPrintMode) {
     await reapplyValidatedModelOnFallback(session, modelRegistry, settingsManager, modelFallbackMessage);
     printExtensionErrors(extensionsResult.errors);
     printExtensionWarnings(extensionsResult.warnings);
-    // Apply --model override if specified
-    if (cliFlags.model) {
-        const available = modelRegistry.getAvailable();
-        const match = available.find((m) => m.id === cliFlags.model) ||
-            available.find((m) => `${m.provider}/${m.id}` === cliFlags.model);
-        if (match) {
-            session.setModel(match);
-        }
-    }
+    applyModelOverride(session, modelRegistry, cliFlags.model);
     const mode = cliFlags.mode || 'text';
     if (mode === 'rpc') {
         printStartupTimings();
@@ -711,6 +721,7 @@ validateConfiguredModel(modelRegistry, settingsManager);
 await reapplyValidatedModelOnFallback(session, modelRegistry, settingsManager, interactiveFallbackMsg);
 printExtensionErrors(extensionsResult.errors);
 printExtensionWarnings(extensionsResult.warnings);
+applyModelOverride(session, modelRegistry, cliFlags.model);
 // Restore scoped models from settings on startup.
 // The upstream InteractiveMode reads enabledModels from settings when /scoped-models is opened,
 // but doesn't apply them to the session at startup — so Ctrl+P cycles all models instead of

package/dist/headless.js

@@ -410,11 +410,16 @@ async function runHeadlessOnce(options, restartCount) {
     });
     // Idle timeout — fallback completion detection
     let idleTimer = null;
-    const effectiveIdleTimeout = isNewMilestone ? NEW_MILESTONE_IDLE_TIMEOUT_MS : IDLE_TIMEOUT_MS;
+    let effectiveIdleTimeout = isNewMilestone
+        ? NEW_MILESTONE_IDLE_TIMEOUT_MS
+        : isAutoMode
+            ? 0
+            : IDLE_TIMEOUT_MS;
     function resetIdleTimer() {
         if (idleTimer)
             clearTimeout(idleTimer);
-        if (shouldArmHeadlessIdleTimeout(toolCallCount, interactiveToolCallIds.size)) {
+        if (effectiveIdleTimeout > 0 &&
+            shouldArmHeadlessIdleTimeout(toolCallCount, interactiveToolCallIds.size)) {
             idleTimer = setTimeout(() => {
                 completed = true;
                 resolveCompletion();
@@ -814,6 +819,8 @@ async function runHeadlessOnce(options, restartCount) {
         completed = false;
         milestoneReady = false;
         blocked = false;
+        effectiveIdleTimeout = 0;
+        resetIdleTimer();
         const autoCompletionPromise = new Promise((resolve) => {
             resolveCompletion = resolve;
         });

package/dist/resources/.managed-resources-content-hash

@@ -1 +1 @@
-cec78fe13fe69412
+f8af4a31f1e89c7d

package/dist/resources/GSD-WORKFLOW.md

@@ -448,6 +448,13 @@ What differed from the plan and why (or "None").
 
 The one-liner must be substantive: "JWT auth with refresh rotation using jose" not "Authentication implemented."
 
+When `key_files` or `key_decisions` are empty, render them as empty YAML lists:
+
+```yaml
+key_files: []
+key_decisions: []
+```
+
 **Slice summary:** Written when all tasks in a slice complete. Compresses all task summaries. Includes `drill_down_paths` to each task summary. During slice completion, review task summaries for `key_decisions` and ensure any significant ones are captured in `.gsd/DECISIONS.md`.
 
 **Milestone summary:** Updated each time a slice completes. Compresses all slice summaries. This is what gets injected into later slice planning instead of loading many individual summaries.
@@ -560,7 +567,7 @@ In all modes, slices and tasks commit sequentially on the active branch; there a
 
 1. **Milestone starts** → capture the current integration branch.
 2. **Optional isolation** → create `milestone/M001` only when `git.isolation` is `worktree` or `branch`.
-3. **Per-task commits** — atomic, descriptive, bisectable.
+3. **Per-task commits** — atomic, descriptive, bisectable, and published only after execute-task verification passes.
 4. **Slice completes** → write slice summary, UAT script, roadmap checkbox, and milestone summary.
 5. **Milestone completes** → if isolated, squash-merge the milestone branch back to the captured integration branch and clean up the worktree/branch.
 
@@ -574,6 +581,8 @@ fix: handle empty state rebuild
 
 In `none` mode these commits land directly on the current branch. In isolated modes they land on `milestone/<MID>` and are squashed back at milestone completion.
 
+Execute-task closeout is fail-closed: the system writes verification evidence first, defers the task commit or snapshot until verification passes, and pauses instead of publishing changes when verification fails or cannot complete.
+
 ### Commit Conventions
 
 | When | Format | Example |

package/dist/resources/extensions/browser-tools/tools/screenshot.js

@@ -5,6 +5,7 @@ export function registerScreenshotTools(pi, deps) {
         name: "browser_screenshot",
         label: "Browser Screenshot",
         description: "Take a screenshot of the current browser page and return it as an inline image. Uses JPEG for viewport/fullpage (smaller, configurable quality) and PNG for element crops (preserves transparency). Optionally crop to a specific element by CSS selector.",
+        compatibility: { producesImages: true },
         parameters: Type.Object({
             fullPage: Type.Optional(Type.Boolean({ description: "Capture the full scrollable page (default: false)" })),
             selector: Type.Optional(Type.String({

package/dist/resources/extensions/browser-tools/tools/zoom.js

@@ -9,6 +9,7 @@ export function registerZoomTools(pi, deps) {
         description: "Capture and optionally upscale a specific rectangular region of the page for detailed inspection. " +
             "Useful for dense UIs where full-page screenshots have text too small to read. " +
             "Returns the region as an inline image, same as browser_screenshot.",
+        compatibility: { producesImages: true },
         parameters: Type.Object({
             x: Type.Number({ description: "Left coordinate of the region in CSS pixels." }),
             y: Type.Number({ description: "Top coordinate of the region in CSS pixels." }),

package/dist/resources/extensions/claude-code-cli/partial-builder.js

@@ -105,9 +105,10 @@ export function mapUsage(sdkUsage, totalCostUsd) {
         output: sdkUsage.output_tokens,
         cacheRead: sdkUsage.cache_read_input_tokens,
         cacheWrite: sdkUsage.cache_creation_input_tokens,
+        // Claude Agent SDK result usage is cumulative across its internal loop;
+        // repeated cache reads do not represent additional live context.
         totalTokens: sdkUsage.input_tokens +
             sdkUsage.output_tokens +
-            sdkUsage.cache_read_input_tokens +
             sdkUsage.cache_creation_input_tokens,
         cost: {
             input: 0,

package/dist/resources/extensions/claude-code-cli/stream-adapter.js

@@ -16,6 +16,8 @@ import { createRequire } from "node:module";
 import { dirname, join } from "node:path";
 import { PartialMessageBuilder, ZERO_USAGE, mapUsage } from "./partial-builder.js";
 import { buildWorkflowMcpServers } from "../gsd/workflow-mcp.js";
+import { loadProjectGSDPreferences } from "../gsd/preferences.js";
+import { discoverMcpServerNames, computeMcpDisallowedTools } from "../gsd/mcp-filter.js";
 import { showInterviewRound } from "../shared/tui.js";
 /** Resolve the workspace root for local Claude Code process execution. */
 export function resolveClaudeCodeCwd(options) {
@@ -110,9 +112,9 @@ export function normalizeClaudePathForSdk(resolvedPath, platform = process.platf
     if (platform !== "win32")
         return resolvedPath;
     if (/\.exe$/i.test(resolvedPath))
-        return resolvedPath;
+        return resolvedPath.replaceAll("\\", "/");
     if (bundledCliPath)
-        return bundledCliPath;
+        return bundledCliPath.replaceAll("\\", "/");
     return resolvedPath;
 }
 /** Resolve the path passed to `pathToClaudeCodeExecutable`. */
@@ -172,6 +174,18 @@ export function buildPromptFromContext(context) {
         "Respond only to the final user message below. " +
             "Do not emit <user_message>, <assistant_message>, or <prior_system_context> tags in your response.",
     ];
+    // The prior system context lists pi-native tool names (lowercase: bash, read, gsd_exec, etc.)
+    // but this process runs inside Claude Code where tool names differ. Inject a remapping note
+    // before the prior context so the model uses correct names regardless of what the prior
+    // context describes.
+    parts.push("<tool_context>\n" +
+        "You are running inside Claude Code. Use these exact tool names — do not use lowercase or pi-native names:\n" +
+        "- Shell commands: 'Bash' (not 'bash')\n" +
+        "- File operations: 'Read', 'Write', 'Edit', 'Glob', 'Grep' (PascalCase, not lowercase)\n" +
+        "- GSD workflow tools (gsd_exec, gsd_slice_complete, gsd_task_complete, gsd_plan_slice, etc.) " +
+        "are MCP tools — call them as mcp__gsd-workflow__<tool_name> " +
+        "(e.g. mcp__gsd-workflow__gsd_exec, mcp__gsd-workflow__gsd_slice_complete)\n" +
+        "</tool_context>");
     if (context.systemPrompt) {
         parts.push(`<prior_system_context>\n${context.systemPrompt}\n</prior_system_context>`);
     }
@@ -269,7 +283,7 @@ function makeErrorMessage(model, errorMsg) {
 export function isClaudeCodeAbortErrorMessage(message) {
     if (!message)
         return false;
-    return /\b(?:claude code process aborted by user|request aborted by user|process aborted by user)\b/i.test(message);
+    return /\b(?:claude code process aborted by user|request aborted by user|process aborted by user|aborterror)\b/i.test(message);
 }
 function isBareClaudeCodeAbortErrorMessage(message) {
     if (!message)
@@ -1060,13 +1074,37 @@ export function buildSdkOptions(modelId, prompt, overrides, extraOptions = {}) {
     const sdkCwd = typeof cwd === "string" && cwd.trim().length > 0 ? cwd : process.cwd();
     const mcpServers = buildWorkflowMcpServers(sdkCwd);
     const permissionMode = overrides?.permissionMode ?? "bypassPermissions";
+    const preferences = loadProjectGSDPreferences(sdkCwd);
+    const mcpConfig = preferences?.preferences.claude_code_mcp;
+    const workflowServerName = mcpServers ? Object.keys(mcpServers)[0] : undefined;
+    // Always discover project MCPs — needed for both duplicate detection and filtering.
+    const discovered = discoverMcpServerNames(sdkCwd);
+    // If the workflow MCP is already declared in the project's .mcp.json or
+    // .claude/settings.json, do not inject it again via mcpServers. Passing the
+    // same server name from two sources causes a duplicate registration conflict
+    // that prevents the MCP server from loading (tools become unavailable).
+    const workflowAlreadyInProject = workflowServerName !== undefined && discovered.includes(workflowServerName);
+    let filteredMcpServers = workflowAlreadyInProject ? undefined : mcpServers;
+    let extraDisallowedTools = [];
+    let workflowExplicitlyBlocked = false;
+    if (mcpConfig) {
+        extraDisallowedTools = computeMcpDisallowedTools(modelId, mcpConfig, discovered, workflowServerName);
+        if (workflowServerName && extraDisallowedTools.includes(`mcp__${workflowServerName}__*`)) {
+            filteredMcpServers = undefined;
+            workflowExplicitlyBlocked = true;
+        }
+    }
     // Globally unblock the tools GSD expects Claude Code to run. When the
     // workflow MCP server is available, prefer its `ask_user_questions` tool over
     // Claude Code's native `AskUserQuestion`; the MCP path carries stable IDs and
     // routes responses through the GSD elicitation bridge.
     // Opt back into gated mode with GSD_CLAUDE_CODE_PERMISSION_MODE=acceptEdits.
-    const workflowMcpTools = mcpServers ? Object.keys(mcpServers).map((serverName) => `mcp__${serverName}__*`) : [];
-    const disallowedTools = workflowMcpTools.length > 0 ? ["AskUserQuestion"] : [];
+    // Include the workflow pattern in allowedTools whether the server is GSD-injected
+    // or declared in the project config — but not if explicitly blocked by user prefs.
+    const workflowMcpTools = filteredMcpServers
+        ? Object.keys(filteredMcpServers).map((serverName) => `mcp__${serverName}__*`)
+        : (!workflowExplicitlyBlocked && workflowServerName ? [`mcp__${workflowServerName}__*`] : []);
+    const disallowedTools = [...(workflowMcpTools.length > 0 ? ["AskUserQuestion"] : []), ...extraDisallowedTools];
     const allowedTools = [
         "Read",
         "Write",
@@ -1103,7 +1141,7 @@ export function buildSdkOptions(modelId, prompt, overrides, extraOptions = {}) {
         systemPrompt: { type: "preset", preset: "claude_code" },
         disallowedTools,
         ...(allowedTools.length > 0 ? { allowedTools } : {}),
-        ...(mcpServers ? { mcpServers } : {}),
+        ...(filteredMcpServers ? { mcpServers: filteredMcpServers } : {}),
         betas: (modelId.includes("sonnet") || modelId.includes("opus-4-7") || modelId.includes("opus-4.7")) ? ["context-1m-2025-08-07"] : [],
         ...(thinkingConfig ?? {}),
         ...(effort ? { effort } : {}),

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

@@ -319,6 +319,11 @@ export class CmuxClient {
         const stdout = await this.runAsync(["send-surface", "--surface", surfaceId, payload]);
         return stdout !== null;
     }
+    // Send Ctrl-C (ETX) to a surface to interrupt the running command.
+    async sendInterrupt(surfaceId) {
+        const stdout = await this.runAsync(["send-surface", "--surface", surfaceId, "\x03"]);
+        return stdout !== null;
+    }
 }
 export function syncCmuxSidebar(preferences, state) {
     const client = CmuxClient.fromPreferences(preferences);

package/dist/resources/extensions/gsd/auto/infra-errors.js

@@ -6,9 +6,14 @@
  * failures that merit retry.
  */
 /**
- * Error codes indicating infrastructure failures that cannot be recovered by
- * retrying. Each retry re-dispatches the unit at full LLM cost, so we bail
- * immediately rather than burning budget on guaranteed failures.
+ * Error codes indicating infrastructure-level failures from the OS,
+ * filesystem, or network. This set includes permanent resource failures
+ * (ENOSPC, ENOMEM, EROFS), transient resource exhaustion (EAGAIN, ENOBUFS),
+ * and network/offline errors (ECONNREFUSED, ENOTFOUND, ENETUNREACH).
+ *
+ * Transient git failures are retried separately through
+ * TRANSIENT_GIT_RETRY_CODES in native-git-bridge.ts before escalating to the
+ * auto-loop.
  */
 export const INFRA_ERROR_CODES = new Set([
     "ENOSPC", // disk full
@@ -18,6 +23,7 @@ export const INFRA_ERROR_CODES = new Set([
     "EMFILE", // too many open files (process)
     "ENFILE", // too many open files (system)
     "EAGAIN", // resource temporarily unavailable (resource exhaustion)
+    "ENOBUFS", // no buffer space available (transient pipe exhaustion)
     "ECONNREFUSED", // connection refused (offline / local server down)
     "ENOTFOUND", // DNS lookup failed (offline / no network)
     "ENETUNREACH", // network unreachable (offline / no route)