pi-gauntlet 4.3.0 → 4.4.0

package/CHANGELOG.md

@@ -1,5 +1,69 @@
 # Changelog
 
+## v4.4.0 - 2026-07-12
+
+Add an unconditional parallel context-gather step to `/skill:brainstorming`. Step 3's
+inline exploration (raw whole-file reads polluting the main session, pruned by
+pi-condense right before spec-writing, serialized for no reason) is replaced by a
+recon fan-out whose output persists on disk as a context draft at the spec path,
+fully overwritten by the real spec at spec-writing.
+
+- **`brainstorming/gatherer.md` (new):** the gather procedure - one parallel-tasks
+  `subagent` call: `scout` always, `context-builder` only when the request carries
+  external refs (URL, tracker ID with a fetch path, GitHub issue ref). Outputs land
+  in a temp dir; the main loop assembles them into a draft headed by a line-1
+  marker (`# CONTEXT DRAFT - NOT A SPEC - fully replaced at spec-writing`) with
+  `## Codebase recon` / `## External context` / `## Appended during questionary`
+  sections. Builder failure degrades to a noted thin draft, never blocks, never
+  surfaces at gather time. Foreground, no user interaction - the first thing the
+  operator sees after gather is questionary question one.
+- **`brainstorming/SKILL.md`:** checklist gains the gather step; step 3 rewritten
+  around the draft (unconditional `Read` before question one; helper-not-fence -
+  load-bearing claims still verified against real code; append bar for citable
+  findings); spec-writing gains a 3-step overwrite discipline (re-read draft
+  immediately before, `write`-tool full replacement, line-1 marker-gone check
+  before any downstream dispatch); slug minted once at gather, rename-with-delete
+  at spec-writing; 4 new Red Flags.
+- **`phase-tracker.ts`:** new `substep` action - `phase_tracker({ action: "substep",
+  phase, substep })` labels an `in_progress` phase in the widget
+  (`brainstorm(gather)`), `null`/omitted clears, any transition drops it. New
+  marker commit guard between the branch-op block and the mutation warning: during
+  brainstorm, `git commit` (incl. `git -C` / `cd X &&` forms) is blocked while any
+  file under `flowGuards.specDirs` still begins with the marker line; skipped
+  entirely when `piGauntlet.flowGuards.enforce` is `false`.
+- **`extensions/lib/phase-tracker-helpers.ts` (new):** pure, injected-fs logic for
+  the above (commit-form parsing, repo-dir resolution, line-1 marker scan, substep
+  transition contract) with 17 `node --test` cases registered in `scripts/ci.mjs`.
+- **`doc/configuration.md`:** documents the `substep` action and the third flow
+  guard.
+
+## v4.3.1 - 2026-07-06
+
+Fix spec-summary pruning at the brainstorming user-review gate. The gate's
+`spec-summarizer` dispatch now writes to a temp file via `outputMode: "file-only"`
+and the main loop reads it back verbatim, so the ~9KB summary survives pi-condense
+instead of being pruned to a paraphrase before render.
+
+- **`brainstorming` gate transport:** dispatch `spec-summarizer` with an absolute
+  temp-dir `output:` path + `outputMode: "file-only"`, `Read` it back as the last
+  content-producing tool call before the gate, and degrade to a one-line note on a
+  stub / truncated / missing file. The temp path is outside the worktree, so it is
+  never committed.
+- **`spec-summarizer` persona:** stays `tools: read`; a directive tells it not to
+  attempt the injected "write your findings" instruction (the harness persists its
+  final text for it), dodging the documented stub/stall failure on weaker models.
+  Adds a length-proportionality directive so summaries scale with spec size.
+- **`AGENTS.md`:** `outputMode` added to the call-site-overridable knobs list.
+
+Restore the per-task spec gate in `subagent-driven-development` Parallel-Wave mode.
+Wave-mode step 3 reviewed spec compliance inline instead of dispatching the
+`spec-reviewer` agent (sequential mode already dispatched it), silently collapsing
+the gate.
+
+- **`subagent-driven-development` wave step 3:** fan out one `spec-reviewer` per
+  accepted patch (fresh context, `cwd` worktree, diff-based); pin the two-stage
+  line to "dispatched spec-reviewer - not inline"; add a Red Flag.
+
 ## v4.3.0 - 2026-07-06
 
 DRY gauntlet settings resolution. All `piGauntlet.*` settings reads now route

package/README.md

@@ -6,77 +6,94 @@
 
 [![Buy Me A Coffee](https://img.shields.io/badge/Buy%20Me%20A%20Coffee-donate-yellow?logo=buymeacoffee&logoColor=black)](https://buymeacoffee.com/jjurasszek)
 
-A workflow library for the [pi coding agent](https://github.com/earendil-works/pi): opinionated skills, ready-to-use subagent personas, and three runtime extensions that turn "run the agent in a loop" into a gated pipeline from idea to merge.
+The gated workflow for the [pi coding agent](https://github.com/earendil-works/pi): brainstorm, plan, implement, verify, ship - each stage a gate the next can't open until it closes.
 
-## Why
+## The problem
 
-The agentic loop everyone's excited about - point an agent at a problem, let it iterate until done - is the easy part. A bare loop has nothing to aim at, nothing to stop it shipping the wrong thing, and no check that the output matches the ask. It holds up on narrow tasks and falls apart on everything open-ended.
+Point an agent at a task and let it loop until done - that's the easy 5%. A bare loop has nothing to aim at, nothing to stop it shipping the wrong thing, and no check that the final output matches what you actually asked for. It holds up on a narrow, well-specified task and drifts on anything open-ended: the agent reinterprets the ask as it goes, nobody catches it until review, and by then the diff is large enough that review is theater too.
 
-pi-gauntlet is the scaffolding that makes the loop hold: **brainstorm → plan → implement → verify → ship**, each stage a gate the next one can't open until it closes.
+That's not a model problem. Cursor, Claude Code, Codex, Devin all run some version of the same loop, and all of them drift the same way on long tasks - because nothing in the loop confronts the output against the *original* intent.
 
-**A gate here is an automated check, not a signature to collect.** Most are machine-enforced - a multi-model spec critique, an adversarial code review, a conformance check that confronts the finished diff against your original ask, and an extension that blocks a commit or push until verification has actually passed. The agent can't wave itself through, and you're not rubber-stamping each step. Human judgment is spent on the two decisions that need it - *what to build* up front and *how to land it* at the end - while the middle (plan → execution, task → task) runs without pausing for you.
+## Why pi-gauntlet exists
 
-The spec and docs it produces get committed to the repo, so the next change starts from ground truth, not a blank slate. The loop is the easy 5%; the gated system around it is the whole job - that's what this is.
+pi-gauntlet is the scaffolding that makes the loop hold: **brainstorm → plan → implement → verify → ship**. Gates between phases are automated checks, not signatures to collect - a multi-model spec critique, an adversarial code review, and a closing conformance check that confronts the finished diff **and docs** against your **original verbatim prompt**, not the plan that got derived from it. The agent can't wave itself through a gate, and you're not rubber-stamping each step by hand.
 
-Rebuilt for pi with enforced gates, a spec council, conformance review, and parallel execution waves. Inspired by [obra/superpowers](https://github.com/obra/superpowers) (Claude Code), by way of [coctostan/pi-superpowers-plus](https://github.com/coctostan/pi-superpowers-plus); see [Lineage](#lineage).
+Human judgment is spent on the two decisions that need it - *what to build*, up front, and *how to land it*, at the end. The middle runs without pausing for you. The spec and docs get committed to the repo, so the next change starts from ground truth, not a blank slate.
 
-## The workflow
+## Part of the pi agent toolkit
 
-pi-gauntlet is **opinionated**: every non-trivial change rides one pipeline, idea to merge. There is no separate "just edit a file and commit" path — the skills gate each other, so the next phase can't open until the current one closes.
+Four independent extensions for the [pi coding agent](https://github.com/earendil-works/pi), each owning one concern of running agents seriously:
 
-```
-brainstorm → plan → implement → verify → ship
+- [pi-quiver](https://github.com/jjuraszek/pi-quiver) - capabilities (ground-truth ingestion: fetch, doc conversion, session tools)
+- [pi-cohort](https://github.com/jjuraszek/pi-cohort) - coordination (delegate to focused child agents)
+- [pi-condense](https://github.com/jjuraszek/pi-condense) - context economy (prune context, keep it recoverable)
+- **pi-gauntlet - process (this repo: the gated brainstorm→ship workflow)**
+
+pi-gauntlet's only hard dependency is pi-cohort - every gate that dispatches a reviewer or an implementer does it through pi-cohort's `subagent()`. pi-condense is not required, but a long gated run generates a lot of tool output; pruning it as you go is what keeps that run affordable.
+
+## What a run looks like
+
+Concretely, one change through the gauntlet:
+
+1. You describe the change. **`brainstorming`** sets up an isolated worktree, explores the codebase, and turns your description into a written spec. A multi-model critique runs on it automatically. **You read and approve the spec - human gate 1.** No implementation code exists yet.
+2. **`writing-plans`** decomposes the approved spec into atomic, independently-verifiable tasks, grouped into parallel waves where they don't touch the same files.
+3. **`subagent-driven-development`** executes the plan one task at a time, each in a fresh subagent, behind spec-compliance review then code-quality review. TDD-locked: red, green, refactor.
+4. **verify**: a whole-diff code review, then the **conformance gate** - a subagent reads the finished code and docs against your *original words* from step 1, not the plan, and reports per-requirement: delivered, partial, missing, drifted, or unauthorized. This gate is machine-blocked from being skipped.
+5. **`finishing-a-development-branch`**: squash, PR, keep, or discard. **Human gate 2** - the only other decision you make.
+
+```mermaid
+flowchart LR
+    R([request]) --> B[brainstorm<br/>+ spec]
+    B --> G1{{human gate 1:<br/>approve spec}}
+    G1 --> P[plan]
+    P --> I[implement<br/>waves + reviews]
+    I --> V[verify]
+    V --> M{{machine gate:<br/>conformance vs<br/>original words}}
+    M --> S[ship]
+    S --> G2{{human gate 2:<br/>merge / PR / discard}}
+    G2 --> D([done])
 ```
 
-1. **`brainstorming`** — every change starts here. Sets up an isolated worktree, explores the codebase, and turns the idea into a written spec under `doc/specs/`. A multi-model critique runs automatically before you read it (`roasting-the-spec` when a council is configured, else one fresh `worker`). **Hard gate:** no implementation code is written until you approve the spec.
-2. **`writing-plans`** — derives an implementation plan from the approved spec, decomposed into atomic, independently-verifiable tasks (grouped into parallel waves when they're file- and resource-disjoint). Auto-chains into execution.
-3. **`subagent-driven-development`** — executes the plan one atomic task at a time, each in a **fresh subagent**, behind a **two-stage review**: spec compliance first (`spec-reviewer`), then code quality (`code-reviewer`). The `implementer` persona is TDD-locked (RED→GREEN→REFACTOR). You orchestrate; you never hand-write the code.
-4. **verify** — after the last task: a whole-diff review (`requesting-code-review`), then the `conformance-reviewer` closing-loop gate that confronts the delivered code **and** docs against the *origin* (spec + your verbatim original prompt), not the plan. The phase-tracker **blocks `complete verify`** until a conformance dispatch has run, and on a successful `complete verify` (ship still pending) injects an advisory to invoke `finishing-a-development-branch` immediately without a redundant "ready to finish?" prompt - or to reopen verify if a requirement decision is still open.
-5. **`finishing-a-development-branch`** — squash / PR / keep / discard. This menu is the single human decision gate at the end, mirroring spec approval at the start.
+<!-- TODO GIF: a real gauntlet run end to end -->
 
-Spec, plan, and implementation are all developed in the **same worktree**. The squash commit ships spec and implementation; the plan is ephemeral and is stripped before any landing path.
+Everything between gate 1 and gate 2 - task breakdown, implementation, both review passes - runs without you in the loop. That's the mechanism. What follows is the machinery behind it.
 
-**Supporting skills** slot in as the pipeline needs them: `using-git-worktrees` (isolation, before the spec), `test-driven-development` (inside every implementer), `dispatching-parallel-agents` (wave fan-out), `systematic-debugging` (when something breaks), `receiving-code-review` (when you get feedback), `writing-skills` (authoring more of these).
+## Architecture
 
-**The gates are enforced, not suggested.** Brainstorming refuses to write code before spec approval; the phase-tracker refuses to close verify before the conformance gate runs; `verify-before-ship` warns on any commit/push/PR without a passing test run since your last edit. Reach for a shortcut and a gate stops you — that is the design, not a side effect.
+pi-gauntlet ships three kinds of pieces, layered on top of pi-cohort's dispatch:
 
-## What you get
+- **13 skills** - the workflow logic. They activate automatically when pi sees the matching kind of task, and each one gates the next: `brainstorming`, `writing-plans`, `roasting-the-spec`, `test-driven-development`, `subagent-driven-development`, `dispatching-parallel-agents`, `verification-before-completion`, `systematic-debugging`, `requesting-code-review`, `receiving-code-review`, `using-git-worktrees`, `finishing-a-development-branch`, `writing-skills`.
+- **7 subagent personas** - the specialized child agents the skills dispatch via pi-cohort: `implementer`, `code-reviewer`, `spec-reviewer`, `conformance-reviewer`, `spec-summarizer`, `spec-council-member`, `spec-council-synthesizer`. See [doc/personas.md](./doc/personas.md) for what each one does and why its permissions are scoped the way they are.
+- **3 runtime extensions** - the enforcement layer. `plan-tracker` and `phase-tracker` are tools skills call to track progress (with a TUI widget); `verify-before-ship` is a hook that warns if you commit/push without a passing test run since your last edit. See [doc/configuration.md](./doc/configuration.md) for the settings each one reads.
 
-**13 skills** that activate automatically when pi sees the right kind of task:
+pi-gauntlet is **opinionated**: every non-trivial change rides this one pipeline. There's no separate "just edit a file and commit" path - the skills gate each other, so the phase-tracker extension mechanically blocks a phase from closing before its gate runs. Reach for a shortcut and a gate stops you; that's the design, not friction.
 
-- **Design & planning** — `brainstorming`, `writing-plans`, `roasting-the-spec`
-- **Implementation** — `test-driven-development`, `subagent-driven-development`, `dispatching-parallel-agents`
-- **Verification** — `verification-before-completion`, `systematic-debugging`
-- **Review** — `requesting-code-review`, `receiving-code-review`
-- **Worktree lifecycle** — `using-git-worktrees`, `finishing-a-development-branch`
-- **Meta** — `writing-skills`
+## Key concepts
 
-**7 subagent personas** dispatchable via [pi-cohort](https://github.com/jjuraszek/pi-cohort):
+| Term | Meaning |
+| --- | --- |
+| Gate | A machine-enforced checkpoint between phases (e.g. `complete verify` is blocked until conformance review has run). Not a suggestion. |
+| Spec council | Multi-model critique of the spec before you see it (`roasting-the-spec`); falls back to a single-model critique if no council is configured. |
+| Conformance gate | The closing check: does the delivered code + docs match your *original prompt*, not the derived plan? Per-requirement verdict, no auto-fix. |
+| Wave | A batch of plan tasks that don't touch the same files, dispatched to implementers in parallel. |
+| Overrides file | `.pi/gauntlet-overrides.md` - where you put project-specific detail the generic skills don't know (CI command, worktree wrapper, routing rules). |
 
-- `implementer` — strict RED→GREEN→REFACTOR TDD, completion-guarded.
-- `code-reviewer` — read-only review, Critical/Moderate/Minor severity.
-- `spec-reviewer` — verifies an implementation against its plan/spec, per-requirement table.
-- `conformance-reviewer` — closing-loop intent gate; confronts the delivered code+docs against the *origin* (spec + verbatim prompt), skipping the plan, and emits a per-requirement coverage verdict. Read-only; proposes remediation, never fixes or decides. Ships model-free — pin its model per preset (see [Conformance gate](#conformance-gate-model)).
-- `spec-summarizer` - produces a tight, spec-only human summary for the brainstorming user review gate. Fresh context, read-only (`tools: read`), reads only the spec it is given; output is ephemeral (rendered at the gate, never committed). Dispatched only by `brainstorming`; not for direct dispatch. Ships model-free - set `subagents.agentOverrides.spec-summarizer.model` per preset to override (unset -> inherits the main loop).
-- `spec-council-member` — adversarial single-model spec critic; one per configured council model. Dispatched only by `roasting-the-spec`.
-- `spec-council-synthesizer` — neutral chair that consolidates and adjudicates member critiques. Dispatched only by `roasting-the-spec`.
+## When to use / when NOT to use
 
-**3 runtime extensions**:
+**Use it** for any change with more than one moving part: a feature, a refactor across files, anything where "what did we actually agree to build" matters by the time it's done.
 
-- `plan-tracker` — persistent task list with a TUI widget. Use the `plan_tracker` tool from skills.
-- `phase-tracker` — tracks workflow phase (brainstorm → plan → implement → verify → ship) with a TUI widget. Use the `phase_tracker` tool from skills. Distinct from `plan-tracker` which tracks per-task progress within the implement phase.
-- `verify-before-ship` — advisory warning if you run `git commit` / `git push` / `gh pr create` without passing tests since your last source edit.
+**Don't use it** for a one-line fix, a typo, or a throwaway spike you're going to discard. The gates have real overhead - a spec, a plan, a conformance check - and that overhead isn't worth paying for a change trivial enough to just make.
 
 ## Requirements
 
 - [pi-coding-agent](https://github.com/earendil-works/pi) ≥ 0.1.0
-- [pi-cohort](https://github.com/jjuraszek/pi-cohort) ≥ 1.4.5 — required peer package. Skills that dispatch agents (`requesting-code-review`, `subagent-driven-development`, `dispatching-parallel-agents`, `writing-plans`, `writing-skills`) call `subagent({})`, which is provided by pi-cohort. pi-gauntlet does not vendor the dispatch tool; without pi-cohort those skills have nothing to call.
+- [pi-cohort](https://github.com/jjuraszek/pi-cohort) ≥ 1.4.5 - required peer package. Skills that dispatch agents (`requesting-code-review`, `subagent-driven-development`, `dispatching-parallel-agents`, `writing-plans`, `writing-skills`) call `subagent({})`, which pi-cohort provides. pi-gauntlet does not vendor the dispatch tool; without pi-cohort those skills have nothing to call.
 
-Both packages must be listed in your `.pi/settings.json#packages` array (pi adds them automatically when you `pi install`). pi-gauntlet and pi-cohort are versioned independently but release together whenever dispatch semantics change — pin compatible versions of both.
+Both packages must be listed in your `.pi/settings.json#packages` array (pi adds them automatically when you `pi install`). pi-gauntlet and pi-cohort are versioned independently but release together whenever dispatch semantics change - pin compatible versions of both.
 
 ## Install
 
-**Project scope** (recommended — committable via the repo's `.pi/settings.json`; `-l` writes to project settings):
+**Project scope** (recommended - committable via the repo's `.pi/settings.json`; `-l` writes to project settings):
 
 ```bash
 pi install -l npm:pi-cohort
@@ -90,45 +107,19 @@ pi install npm:pi-cohort
 pi install npm:pi-gauntlet
 ```
 
-Pin an exact release with `npm:pi-gauntlet@X.Y.Z`. Pi clones the package, runs `npm install --omit=dev`, which triggers the `postinstall` script. Where personas land depends on the install location:
-
-- **User install** (package under `<home>/.pi/<profile>/...`): symlinks the seven agent files into `getAgentDir()/agents` — i.e. `$PI_CODING_AGENT_DIR/agents`, defaulting to `~/.pi/agent/agents`. This is pi-cohort's profile-scoped user dir, so each pi profile (`agent`, `agent.anthropic`, …) gets its own personas instead of sharing the machine-global `~/.agents/`. Earlier releases installed into the machine-global `~/.agents/`; on upgrade the postinstall removes stale `~/.agents/<name>.md` symlinks that point into a pi-gauntlet package (which would otherwise shadow the profile-scoped copy) and leaves your own files there alone.
-- **Project install** (package under `<repo>/.pi/...`): copies the seven agent files into `<repo>/.pi/agents/` (the project-scope discovery path). Copy, not symlink, so the files stay valid if you commit them; gitignore `.pi/agents/` if you'd rather keep them install-managed. Project scope wins over user scope on name collisions, so each repo's personas are independent of the user dir and of other repos.
-
-## Upgrading from v3.x
+Pin an exact release with `npm:pi-gauntlet@X.Y.Z`. See [doc/install-internals.md](./doc/install-internals.md) for what the postinstall step actually does (symlink vs copy, `PI_GAUNTLET_AGENT_DIR`, upgrading from the pre-rename package).
 
-v4.0.0 is the first public release and is a **breaking rename** (no behavior change). If you ran the package under its old identity:
-
-- Reinstall under the new name: `pi install -l npm:pi-gauntlet` (was `@jjuraszek/pi-superpowers`).
-- Rename settings namespace `piSuperpowers.*` -> `piGauntlet.*` in every preset's `settings.json` (a preset still on the old key silently gets defaults).
-- Rename your override file `.pi/superpowers-overrides.md` -> `.pi/gauntlet-overrides.md`.
-- Rename the env override `PI_SUPERPOWERS_AGENT_DIR` -> `PI_GAUNTLET_AGENT_DIR` if you set it.
-
-See [CHANGELOG.md](CHANGELOG.md) for the full v4.0.0 entry.
-
-## Install (local development)
+For local development against a checkout instead of npm:
 
 ```bash
 git clone git@github.com:jjuraszek/pi-gauntlet.git ~/repos/pi-gauntlet
-cd ~/path/to/your/repo
-pi install -l ~/repos/pi-gauntlet
-# Local-path installs skip `npm install`; run the symlink step manually:
-cd ~/repos/pi-gauntlet && npm run link-agents
+cd ~/path/to/your/repo && pi install -l ~/repos/pi-gauntlet
+cd ~/repos/pi-gauntlet && npm run link-agents   # local-path installs skip npm install; run this once
 ```
 
-After that, edits in `~/repos/pi-gauntlet/` are picked up on next pi launch.
-
 ## Project-specific overrides
 
-The skills shipped here are generic on purpose — they describe *how* to TDD, brainstorm, debug, request review, etc., without naming your services, your CI command, or your worktree wrapper. When you need that level of detail, drop a file at:
-
-```
-.pi/gauntlet-overrides.md
-```
-
-…in your repo. The skills read it at runtime and merge sections that match the skill's name or topic.
-
-### Example `.pi/gauntlet-overrides.md`
+The skills shipped here are generic on purpose - they describe *how* to TDD, brainstorm, debug, request review, etc., without naming your services, your CI command, or your worktree wrapper. When you need that level of detail, drop a file at `.pi/gauntlet-overrides.md` in your repo. The skills read it at runtime and merge sections that match the skill's name or topic:
 
 ```markdown
 ## verification-before-completion
@@ -140,152 +131,21 @@ the gate — it skips integration tests.
 
 Use the project's wrapper: `script/worktree create <name>`. It provisions an isolated
 database and copies `.env.local`. Never call `git worktree add` directly.
-
-## brainstorming
-
-Project routing: dashboard work → `dashboard/AGENTS.md`. Compliance work → `compliance/AGENTS.md`.
-Spec docs land in `doc/specs/`, plans in `doc/plans/`, both sibling to each other.
-```
-
-Two notes:
-
-- The override file is read by the **skill instructions** at runtime — not by the pi runtime itself. So adding a section here doesn't load anything; the skill that's currently active reads the file and pulls in the matching section.
-- Section headers should match skill names (`## verification-before-completion`) or skill topics (`## worktrees`, `## routing`). Skills look for both.
-
-## Subagent personas
-
-On a user install the seven personas in `agents/` are symlinked into `getAgentDir()/agents` (profile-scoped user dir — `$PI_CODING_AGENT_DIR/agents`, default `~/.pi/agent/agents`). On a project install they are copied into `<repo>/.pi/agents/` (project scope, isolated per repo). Override precedence is `project > user > builtin`, so a project install always shadows the user personas for that repo, and you can hand-edit or drop your own `.pi/agents/<name>.md` to shadow them further.
-
-Target dir override: set `PI_GAUNTLET_AGENT_DIR` to force symlinking into a specific dir (leading `~` expanded; always symlink mode).
-
-### Thinking budgets
-
-`implementer`, `code-reviewer`, and `spec-reviewer` ship without `thinking:` in their frontmatter — pi-cohort `agentOverrides` only fill frontmatter-unset fields, so leaving it unset makes the budget a per-preset config knob. Set it in each preset's `settings.json` (use `false` on non-thinking models → provider default):
-
-```json
-{
-  "subagents": {
-    "agentOverrides": {
-      "implementer": { "thinking": "medium" },
-      "code-reviewer": { "thinking": "high" },
-      "spec-reviewer": { "thinking": "medium" }
-    }
-  }
-}
-```
-
-Unset → provider default thinking for that model. `conformance-reviewer` and the two `spec-council-*` personas stay frontmatter-pinned at `xhigh` and are not configurable — the gate and the council must run at max budget even when they inherit the session's model.
-
-### Conformance gate model
-
-`conformance-reviewer` ships without a `model:` in its frontmatter — like the spec-council personas, its model is supplied per preset so each profile points the last correctness gate at the strongest reasoning model its providers can reach. The verify-step skills resolve `piGauntlet.closureReview.model` **repo-local first** (a repo's `.pi/settings.json` overrides the preset whole-object - defining `closureReview` there replaces the preset's entire block, so set every leaf you need together) and inject it **call-site** on the conformance dispatch (the same mechanism the spec-council chair uses). Add it to each preset's `settings.json` (or a repo's `.pi/settings.json` to override per repo):
-
-```json
-{
-  "piGauntlet": {
-    "closureReview": { "model": "<provider/model>", "enforce": true, "maxFixRounds": 2 }
-  }
-}
 ```
 
-Frontmatter pins `thinking: xhigh` and `defaultContext: fresh` (the gate always runs cold, with max reasoning) and `thinking` is not call-site overridable, so the config supplies only `model`. If `closureReview.model` is unset the dispatch omits `model:` and the gate inherits the parent's model; if the configured model is unreachable it retries once inherited.
-
-When `closureReview.model` **is** set, the phase-tracker match-checks call-site injection: a `subagent` dispatch of `conformance-reviewer` that omits `model:` is **blocked at tool-call time** (before it runs) so the gate can never silently degrade to the parent's builder model, and a dispatch whose `model:` **differs** from the configured value gets a non-blocking **warning** appended to the result (drift is surfaced, not blocked). The documented one-retry fallback still works - pass an explicit model and it runs (with a warning if it differs). Disabling `closureReview.enforce` disables this guard too.
-
-`closureReview.enforce` (default `true`) controls the phase-tracker gate that
-blocks `complete verify` until the conformance-reviewer has run; set `false` to
-disable enforcement for a preset.
-
-`closureReview.maxFixRounds` (default `2`) caps the conformance **remediation loop**: when a `GAPS` verdict's gaps are dispositioned `fix`, the orchestrator dispatches isolated fix waves and re-audits the delta, up to this many rounds before escalating to the user with the per-gap history. Missing or non-integer -> `2`; `< 0` clamps to `0`; `0` disables fix dispatch (the gap menu offers accept / rescope only). Enforced by the protocol prose in `verification-before-completion/reference/conformance-check.md`, not by the phase-tracker extension.
-
-If you want to know what's in each persona before using it, see [`agents/`](./agents/). The frontmatter (tools, thinking level, context mode) is documented in [`AGENTS.md`](./AGENTS.md#agents).
-
-## Spec council
-
-`/skill:roasting-the-spec` runs a multi-model critique of a spec before the brainstorming user-review gate. It is the **critique half** of brainstorming's self-review: when a council is configured in the active preset's `settings.json`, brainstorming **auto-dispatches** it (no prompt); when none is configured, brainstorming runs a single fresh-`worker` critique instead. Each member runs on a different model (divergent critiques), a neutral chair consolidates and adjudicates, and you approve what gets applied.
-
-```json
-{
-  "piGauntlet": {
-    "specCouncil": {
-      "members": ["<provider/model>", "<provider/model>", "<provider/model>"],
-      "chair": "<provider/model>"
-    }
-  }
-}
-```
-
-- `members` (required) — roster of `provider/model` strings; council size = array length, one critique per model. Empty or absent → the council never runs; brainstorming falls back to a single fresh-`worker` critique (scope + ambiguity, auto-applied).
-- `chair` (optional) — model for the consolidating synthesizer; defaults to the inherited model when omitted.
-
-Rosters resolve **repo-local first**: a repo's `.pi/settings.json` overrides the preset (whole-object — the first file that defines `specCouncil` wins), otherwise each pi profile (`agent`, `agent.anthropic`, `agent.bedrock`, …) reads its own `settings.json`. List only models the resolving config's providers can reach. The two personas it dispatches — `spec-council-member` and `spec-council-synthesizer` — are model-free; their model is injected per task from this config.
-
-## Extensions
-
-### `plan-tracker`
+Section headers should match skill names (`## verification-before-completion`) or skill topics (`## worktrees`, `## routing`). The override file is read by the skill instructions at runtime, not by the pi runtime itself, so adding a section only matters once the matching skill is active.
 
-A tool, not a hook. Skills call `plan_tracker({ action: "init" | "update" | "status" | "clear", ... })` to manage a task list; a TUI widget above the editor shows progress (✓/→/○). State branches with the session, no config needed.
+## Configuring the gates
 
-### `phase-tracker`
+The conformance gate's model, the spec council's roster, and the phase-tracker's flow guards are all configured per pi preset (or per repo, via `.pi/settings.json`). See [doc/configuration.md](./doc/configuration.md) for every setting, its default, and how repo-local config overrides a preset.
 
-A tool, not a hook. Skills call `phase_tracker({ action: "start" | "complete" | "skip" | "status" | "reset", phase?, reason? })` to track workflow phase progress. A TUI widget shows the five-phase pipeline: `○ brainstorm → ○ plan → ○ implement → ○ verify → ○ ship`. State branches with the session, no config needed. Phases are entered **explicitly** by the phase-owning skills, so outside a gauntlet flow the widget stays dormant. The `brainstorming` skill resets both trackers on entry (new flow, clean slate); `implement` auto-completes from `plan-tracker` once a skill has started it.
+## Relationship to the other repos
 
-Distinct from `plan-tracker`: `phase-tracker` answers "what stage of the workflow am I in?"; `plan-tracker` answers "which task within the current stage am I on?"
+pi-gauntlet is the process layer: it enforces the workflow, but every reviewer and implementer it dispatches runs through [pi-cohort](https://github.com/jjuraszek/pi-cohort)'s `subagent()` - that's a hard dependency, not an integration you can skip. [pi-condense](https://github.com/jjuraszek/pi-condense) is optional but keeps a long gated run's context (and cost) from growing unbounded across all those dispatches. [pi-quiver](https://github.com/jjuraszek/pi-quiver) is complementary - if a brainstorm or implementation step needs to pull in a real doc or web page, that's what ingests it safely.
 
-**`gauntlet_setting` tool.** `phase-tracker` also registers `gauntlet_setting({ key: "specCouncil" | "closureReview" })`, a gauntlet-internal tool through which skills resolve merged `piGauntlet.*` settings (repo `.pi/settings.json` over the agent preset, via pi's own `SettingsManager`). It returns the resolved value as a JSON block in the tool result — `specCouncil` yields the council-vs-worker verdict, `closureReview` yields the conformance-gate `model`/`enforce`/`maxFixRounds`. It introduces no new settings key. Every `piGauntlet.*` read — the skills via this tool, both extensions directly — routes through one shared helper (`extensions/lib/gauntlet-settings*.ts`); no code reads `pi.settings` by hand.
-
-**Closure-review gate.** `complete verify` is rejected unless a successful
-`conformance-reviewer` dispatch (a `subagent` result whose `results[]` contains
-`agent: "conformance-reviewer"` with `exitCode: 0`) has been observed since the
-last `reset`. Management calls (`action: "list"` etc.) and async dispatches never
-qualify. A user waiver is recorded via `skip` with a reason — there is no `force`
-bypass on `complete`. Disable per preset with
-`settings.json#piGauntlet.closureReview.enforce: false` (default: enforced).
-
-**Flow guards.** Two guards, on by default, disabled per
-preset with `settings.json#piGauntlet.flowGuards.enforce: false`:
-
-- **Worktree discipline (blocks).** During `brainstorm`/`plan`/`implement`, an in-place
-  `git switch` / `git checkout -b`/`-B` is blocked — the bash call does not run.
-  Active **only when pi was launched in the primary checkout** (not a linked
-  worktree); `git worktree ...` and plain `git checkout <file>` never trip it.
-  Override via `piGauntlet.flowGuards.enforce: false`.
-- **Spec-phase confinement (advisory).** During `brainstorm`, a `write`/`edit` (or a bash
-  mutation: `>`/`>>`/`tee`/`sed -i`/`git apply`) outside the spec dir warns that
-  brainstorming may only touch the spec. Spec dirs come from
-  `flowGuards.specDirs` (default `["doc/specs"]`). Redirects to scratch paths
-  (`/tmp`, `/var/folders`, `/dev`) are exempt. Warns once per brainstorm.
-
-### `verify-before-ship`
-
-A hook on `git commit` / `git push` / `gh pr create`. If you haven't run a passing test command since your last source-file write in this session, an advisory warning is injected into the tool result. The warning clears automatically after a passing test run.
-
-Default test-command regex matches: `make ci`, `make test`, `npm test`, `pnpm test`, `yarn test`, `pytest`, `rspec`, `cargo test`, `go test`.
-
-Override in `.pi/settings.json`:
-
-```json
-{
-  "piGauntlet": {
-    "verifyBeforeShip": {
-      "testCommands": ["make ci", "bundle exec rspec"],
-      "warningReference": "doc/testing.md"
-    }
-  }
-}
-```
-
-`testCommands` entries are regex fragments (anchored with `\b` automatically). `warningReference` is a doc path appended to the warning text — useful for pointing engineers at your testing conventions.
-
-## Versioning
-
-Bump explicitly:
-
-```bash
-pi install -l npm:pi-gauntlet@X.Y.Z
-```
+## Roadmap
 
-See [`CHANGELOG.md`](./CHANGELOG.md) for what changed in each release. Semver: minor for new skill/agent/extension, major for renames or breaking config changes. pi-gauntlet and its dispatch peer [pi-cohort](https://github.com/jjuraszek/pi-cohort) version independently but ship together whenever dispatch semantics change; pin compatible versions of both.
+Nothing committed beyond what's shipped. Changes land via [CHANGELOG.md](./CHANGELOG.md).
 
 ## Lineage
 

package/agents/spec-summarizer.md

@@ -19,6 +19,7 @@ Your output is judged on whether a busy supervisor can decide from it alone. A t
 
 Optimize for "what does a supervisor need to approve **this** spec." The list below is a recommended checklist, not a rigid template:
 
+- **Scale length to the spec.** The summary is proportional to the spec's size and complexity - a short or simple spec gets a short summary. Do not expand every recommended section to full depth to look thorough; the summary should be a fraction of the spec, not a near-copy of it. This is proportionality, **not** aggressive compression - never drop a decision-relevant point, rejected-alternative, risk, or gap-footer entry to hit a length target. When in doubt, keep the point and cut the words around it.
 - **Omit any section that is empty.** A bugfix has no new endpoint; a refactor has no algorithm. Write nothing for an empty section - never "N/A" or filler.
 - **Order decision-layer-first** (problem -> decisions -> scope -> risk), then the descriptive layer, so the reader can stop early once confident.
 - **Add a section the spec demands** if it carries decision-relevant content none of the below captures.
@@ -39,4 +40,4 @@ Recommended sections:
 
 Tight, human-readable, no obvious statements. If the topic is complex, an example with explanation beats prose.
 
-Output the summary as your final text response. Do not write any file.
+Output the summary as your final text response. You have no write tool. If your task instructs you to write your findings to a file path, do **not** attempt to write, create, or edit any file and do **not** treat the inability to write as a failure - just emit the full summary as your final text response. The harness persists that response to the requested path for you.

package/extensions/lib/phase-tracker-helpers.test.ts

@@ -0,0 +1,120 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import {
+  CONTEXT_DRAFT_MARKER,
+  checkSubstep,
+  phaseLabel,
+  parseGitCommit,
+  resolveRepoDir,
+  findMarkerFile,
+  markerBlockReason,
+  transitionPhaseState,
+  markerGuardApplies,
+} from "./phase-tracker-helpers.ts";
+
+test("checkSubstep: in_progress -> ok", () => {
+  assert.deepEqual(checkSubstep("in_progress"), { ok: true });
+});
+
+test("checkSubstep: non-in_progress statuses -> error naming actual status", () => {
+  for (const s of ["pending", "complete", "skipped"]) {
+    const r = checkSubstep(s);
+    assert.equal(r.ok, false);
+    if (!r.ok) assert.match(r.error, new RegExp(s));
+  }
+});
+
+test("phaseLabel: with and without substep", () => {
+  assert.equal(phaseLabel("brainstorm", "gather"), "brainstorm(gather)");
+  assert.equal(phaseLabel("brainstorm", undefined), "brainstorm");
+});
+
+test("parseGitCommit: plain, -am, chained after &&", () => {
+  assert.ok(parseGitCommit('git commit -m "x"'));
+  assert.ok(parseGitCommit("git commit -am 'x'"));
+  assert.ok(parseGitCommit('git add -A && git commit -m "x"'));
+});
+
+test("parseGitCommit: -C path and cd prefix are captured", () => {
+  assert.deepEqual(parseGitCommit('git -C /wt commit -m "x"'), { cPath: "/wt", cdPath: undefined });
+  assert.deepEqual(parseGitCommit('cd /wt && git commit -m "x"'), { cPath: undefined, cdPath: "/wt" });
+});
+
+test("parseGitCommit: non-commit git and non-git -> undefined", () => {
+  assert.equal(parseGitCommit("git log --oneline"), undefined);
+  assert.equal(parseGitCommit("git commitish"), undefined);
+  assert.equal(parseGitCommit('echo "git commit"'), undefined); // statement-start anchor: a quote is not a statement boundary
+  assert.equal(parseGitCommit("npm test"), undefined);
+});
+
+test("parseGitCommit: -c config flags between git and commit don't bypass the guard", () => {
+  assert.deepEqual(parseGitCommit('git -c user.email=x commit -m "y"'), { cPath: undefined, cdPath: undefined });
+  assert.deepEqual(parseGitCommit("git -C /wt -c user.email=x commit"), { cPath: "/wt", cdPath: undefined });
+});
+
+test("parseGitCommit: commit-graph / commit-tree are not commit", () => {
+  assert.equal(parseGitCommit("git commit-graph write"), undefined);
+  assert.equal(parseGitCommit("git commit-tree HEAD^{tree}"), undefined);
+});
+
+test("parseGitCommit: cd path in subshell (cd /a) captures /a without trailing paren", () => {
+  assert.deepEqual(parseGitCommit("(cd /a) && git commit -m x"), { cPath: undefined, cdPath: "/a" });
+});
+
+test("parseGitCommit: last cd before the commit wins over an earlier one", () => {
+  assert.deepEqual(parseGitCommit("cd /a && cd /b && git commit -m x"), { cPath: undefined, cdPath: "/b" });
+});
+
+test("parseGitCommit: cd recognized before non-&& statement separators", () => {
+  assert.deepEqual(parseGitCommit("cd /wt; git commit -m x"), { cPath: undefined, cdPath: "/wt" });
+  assert.deepEqual(parseGitCommit("cd /wt\ngit commit -m x"), { cPath: undefined, cdPath: "/wt" });
+  assert.deepEqual(parseGitCommit("cd /wt || git commit -m x"), { cPath: undefined, cdPath: "/wt" });
+});
+
+test("resolveRepoDir: -C wins over cd, cd wins over session cwd, relative -C resolves against cd", () => {
+  assert.equal(resolveRepoDir({ cPath: "/b", cdPath: "/a" }, "/s"), "/b");
+  assert.equal(resolveRepoDir({ cPath: undefined, cdPath: "/a" }, "/s"), "/a");
+  assert.equal(resolveRepoDir({ cPath: undefined, cdPath: undefined }, "/s"), "/s");
+  assert.equal(resolveRepoDir({ cPath: "wt", cdPath: "/a" }, "/s"), "/a/wt");
+});
+
+test("findMarkerFile: line-1 hit found, quoted-in-body miss, missing dir -> undefined", () => {
+  const files: Record<string, string> = {
+    "/r/doc/specs/a.md": CONTEXT_DRAFT_MARKER + "\n\nbody",
+    "/r/doc/specs/b.md": "# Real spec\n\n`" + CONTEXT_DRAFT_MARKER + "` quoted in body",
+  };
+  const listFiles = (dir: string) =>
+    dir === "/r/doc/specs" ? Object.keys(files) : [];
+  const readFirstLine = (f: string) => files[f]?.split("\n", 1)[0];
+  assert.equal(findMarkerFile("/r", ["doc/specs"], listFiles, readFirstLine), "/r/doc/specs/a.md");
+  delete files["/r/doc/specs/a.md"];
+  assert.equal(
+    findMarkerFile("/r", ["doc/specs"], (d) => (d === "/r/doc/specs" ? Object.keys(files) : []), readFirstLine),
+    undefined,
+  );
+  assert.equal(findMarkerFile("/r", ["nope"], () => [], readFirstLine), undefined);
+});
+
+test("markerBlockReason names the file and the enforce escape hatch", () => {
+  const r = markerBlockReason("/r/doc/specs/a.md");
+  assert.match(r, /\/r\/doc\/specs\/a\.md/);
+  assert.match(r, /flowGuards\.enforce/);
+});
+
+test("transitionPhaseState: complete/skipped/pending drop any prior substep", () => {
+  for (const status of ["complete", "skipped", "pending"]) {
+    const r = transitionPhaseState(status);
+    assert.equal(r.status, status);
+    assert.ok(!("substep" in r));
+  }
+});
+
+test("transitionPhaseState: reason propagates when provided", () => {
+  assert.deepEqual(transitionPhaseState("skipped", "why"), { status: "skipped", reason: "why" });
+});
+
+test("markerGuardApplies: gated by flowGuards.enforce and brainstorm in_progress", () => {
+  assert.equal(markerGuardApplies(false, "in_progress"), false);
+  assert.equal(markerGuardApplies(true, "in_progress"), true);
+  assert.equal(markerGuardApplies(true, "pending"), false);
+});

package/extensions/lib/phase-tracker-helpers.ts

@@ -0,0 +1,97 @@
+/**
+ * Pure logic for phase-tracker's substep action and marker commit guard.
+ * No fs/git access here — file access is injected so node --test covers it
+ * (registered in scripts/ci.mjs alongside the settings resolvers).
+ */
+
+import { resolve } from "node:path";
+
+export const CONTEXT_DRAFT_MARKER = "# CONTEXT DRAFT - NOT A SPEC - fully replaced at spec-writing";
+
+export type SubstepCheck = { ok: true } | { ok: false; error: string };
+
+export function checkSubstep(phaseStatus: string): SubstepCheck {
+  if (phaseStatus === "in_progress") return { ok: true };
+  return { ok: false, error: `substep requires an in_progress phase (status is ${phaseStatus})` };
+}
+
+export function phaseLabel(name: string, substep?: string): string {
+  return substep ? `${name}(${substep})` : name;
+}
+
+// Same statement-start anchor as the branch guards in phase-tracker.ts. Exported
+// so Wave 2 wiring in phase-tracker.ts can drop its duplicate copy.
+export const STMT_START = "(?:^|[\\n;&|(])\\s*";
+// `git commit`, tolerating any global flags between `git` and `commit` (e.g.
+// `-c user.email=x`, common in CI per-commit identity). Group 1 captures the
+// whole flags span as ONE opaque block rather than -C directly: nesting a
+// capture inside a repeated alternation resets it to undefined on iterations
+// that take the other branch (JS regex semantics), so -C after a later flag
+// (e.g. `-C /wt -c user.email=x commit`) would silently lose its capture.
+// DASH_C below re-extracts -C from that span once, outside any repetition.
+// `commit` must be followed by whitespace or end-of-string, not just a word
+// boundary, so `commit-graph` / `commit-tree` don't false-positive.
+const GIT_COMMIT = new RegExp(
+  STMT_START + "git\\s+((?:-\\S+(?:\\s+\\S+)?\\s+)*)commit(?=\\s|$)",
+);
+const DASH_C = /(?:^|\s)-C\s+(\S+)/;
+// Global, lookaround-delimited (not consuming) so adjacent `cd a && cd b &&`
+// statements don't eat each other's anchor/`&&` and hide the second match.
+// parseGitCommit picks the LAST cd before the matched git-commit position, so
+// `cd /a && cd /b && git commit` resolves against /b, not the first cd found.
+const LEADING_CD = /(?<=^|[\n;&|(])\s*cd\s+([^\s)]+)\s*(?=&&|\|\||[;)\n]|$)/g;
+
+export interface CommitForm {
+  cPath: string | undefined;
+  cdPath: string | undefined;
+}
+
+// Textual match anchored at statement starts (^ ; & | ( or newline). Quoted text
+// can still match when preceded by such a char (e.g. sh -c 'x; git commit') —
+// accepted heuristic, same tolerance as the existing Guard 3 mutation checks.
+export function parseGitCommit(command: string): CommitForm | undefined {
+  const m = GIT_COMMIT.exec(command);
+  if (!m) return undefined;
+  let cdPath: string | undefined;
+  for (const cd of command.matchAll(LEADING_CD)) {
+    if (cd.index! < m.index!) cdPath = cd[1];
+  }
+  return { cPath: DASH_C.exec(m[1])?.[1], cdPath };
+}
+
+export function resolveRepoDir(form: CommitForm, sessionCwd: string): string {
+  const base = form.cdPath ? resolve(sessionCwd, form.cdPath) : sessionCwd;
+  return form.cPath ? resolve(base, form.cPath) : base;
+}
+
+// Line-1 anchoring prevents false positives on specs that QUOTE the marker.
+// Working-tree read (not index) is an accepted false-negative window for a
+// backstop whose primary check lives in the brainstorming skill.
+export function findMarkerFile(
+  repoDir: string,
+  specDirs: string[],
+  listFiles: (dir: string) => string[],
+  readFirstLine: (file: string) => string | undefined,
+): string | undefined {
+  for (const dir of specDirs) {
+    for (const file of listFiles(resolve(repoDir, dir))) {
+      if (readFirstLine(file) === CONTEXT_DRAFT_MARKER) return file;
+    }
+  }
+  return undefined;
+}
+
+// Transitions always build fresh state: a substep never survives start/complete/skip/reset.
+export function transitionPhaseState(status: string, reason?: string): { status: string; reason?: string } {
+  return reason === undefined ? { status } : { status, reason };
+}
+
+export function markerGuardApplies(flowGuardsEnforced: boolean, brainstormStatus: string): boolean {
+  return flowGuardsEnforced && brainstormStatus === "in_progress";
+}
+
+export const markerBlockReason = (file: string): string =>
+  `Blocked: ${file} still begins with the context-draft marker - the spec-writing ` +
+  `overwrite has not happened. Overwrite the draft with the real spec (write tool, ` +
+  `full replacement) before committing. ` +
+  `To override, set piGauntlet.flowGuards.enforce: false.`;

package/extensions/phase-tracker.ts

@@ -10,6 +10,8 @@
  */
 
 import { execSync } from "node:child_process";
+import { readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
 import { StringEnum } from "@earendil-works/pi-ai";
 import type { ExtensionAPI, ExtensionContext, Theme } from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
@@ -21,6 +23,16 @@ import {
   settingsErrorWarning,
 } from "./lib/gauntlet-settings.ts";
 import { loadGauntletSettings } from "./lib/gauntlet-settings-loader.ts";
+import {
+  checkSubstep,
+  findMarkerFile,
+  markerBlockReason,
+  parseGitCommit,
+  phaseLabel,
+  resolveRepoDir,
+  STMT_START,
+  transitionPhaseState,
+} from "./lib/phase-tracker-helpers.ts";
 
 const PHASES = ["brainstorm", "plan", "implement", "verify", "ship"] as const;
 type Phase = (typeof PHASES)[number];
@@ -29,12 +41,13 @@ type PhaseStatus = "pending" | "in_progress" | "complete" | "skipped";
 interface PhaseState {
   status: PhaseStatus;
   reason?: string;
+  substep?: string;
 }
 
 type PhaseMap = Record<Phase, PhaseState>;
 
 interface PhaseTrackerDetails {
-  action: "start" | "complete" | "skip" | "status" | "reset";
+  action: "start" | "complete" | "skip" | "status" | "reset" | "substep";
   phases: PhaseMap;
   error?: string;
 }
@@ -72,7 +85,6 @@ const GUARD_PHASES: Phase[] = ["brainstorm", "plan", "implement"];
 // Guard 2 — branch ops in place. `git switch` never targets a file path;
 // `git checkout -b/-B` is explicit branch creation. Bare `git checkout <x>`
 // is excluded (ambiguous with file checkout). `git worktree ...` is exempt.
-const STMT_START = "(?:^|[\\n;&|(])\\s*";
 const BRANCH_SWITCH = new RegExp(STMT_START + "git\\s+switch\\b");
 const BRANCH_CHECKOUT = new RegExp(STMT_START + "git\\s+checkout\\s+-[bB]\\b");
 const GIT_WORKTREE = /\bgit\s+worktree\b/;
@@ -155,7 +167,7 @@ const pathInSpecDirs = (rawPath: string, specDirs: string[]): boolean => {
 };
 
 const PhaseTrackerParams = Type.Object({
-  action: StringEnum(["start", "complete", "skip", "status", "reset"] as const, {
+  action: StringEnum(["start", "complete", "skip", "status", "reset", "substep"] as const, {
     description: "Action to perform",
   }),
   phase: Type.Optional(
@@ -173,6 +185,11 @@ const PhaseTrackerParams = Type.Object({
       description: "Reset and re-start a phase that is already complete or skipped (rare; default false)",
     }),
   ),
+  substep: Type.Optional(
+    Type.Union([Type.String(), Type.Null()], {
+      description: "Substep label for action=substep on an in_progress phase; null or omitted clears it",
+    }),
+  ),
 });
 
 export type PhaseTrackerInput = Static<typeof PhaseTrackerParams>;
@@ -201,7 +218,8 @@ function hasActivity(phases: PhaseMap): boolean {
 function formatWidget(phases: PhaseMap, theme: Theme): string {
   const parts = PHASES.map((p) => {
     const icon = phaseIcon(phases[p].status, theme);
-    const name = phases[p].status === "skipped" ? theme.fg("dim", p) : p;
+    const labeled = phaseLabel(p, phases[p].status === "in_progress" ? phases[p].substep : undefined);
+    const name = phases[p].status === "skipped" ? theme.fg("dim", labeled) : labeled;
     return `${icon} ${name}`;
   });
   return `${theme.fg("muted", "Phases:")} ${parts.join(theme.fg("dim", " → "))}`;
@@ -213,7 +231,7 @@ function formatStatus(phases: PhaseMap): string {
     const s = phases[p];
     const icon = s.status === "complete" ? "✓" : s.status === "in_progress" ? "→" : s.status === "skipped" ? "⊘" : "○";
     const suffix = s.reason ? ` (${s.reason})` : "";
-    lines.push(`  ${icon} ${p}${suffix}`);
+    lines.push(`  ${icon} ${phaseLabel(p, s.status === "in_progress" ? s.substep : undefined)}${suffix}`);
   }
   return lines.join("\n");
 }
@@ -386,6 +404,41 @@ export default function (pi: ExtensionAPI) {
       return { block: true, reason: branchBlockReason(gphase) };
     }
 
+    // Marker commit guard — the context draft (brainstorming gather step) must be
+    // overwritten by the real spec before any commit lands. Backstop to the skill's
+    // own post-write check. Blocked, like Guard 2; skipped entirely when
+    // flowGuards.enforce is false (checked above).
+    // gating contract: markerGuardApplies (see helpers) - enforce checked once above
+    // (flowGuardsEnforced()); re-checking it here would be belt-and-suspenders.
+    if (phases.brainstorm.status === "in_progress") {
+      const commit = parseGitCommit(command);
+      if (commit) {
+        const repoDir = resolveRepoDir(commit, ctx.cwd);
+        const listFiles = (dir: string): string[] => {
+          const walk = (d: string): string[] => {
+            return readdirSync(d, { withFileTypes: true }).flatMap((e) => {
+              const p = join(d, e.name);
+              return e.isDirectory() ? walk(p) : e.isFile() ? [p] : [];
+            });
+          };
+          try {
+            return walk(dir);
+          } catch {
+            return [];
+          }
+        };
+        const readFirstLine = (file: string): string | undefined => {
+          try {
+            return readFileSync(file, "utf8").split("\n", 1)[0];
+          } catch {
+            return undefined;
+          }
+        };
+        const hit = findMarkerFile(repoDir, specDirs(), listFiles, readFirstLine);
+        if (hit) return { block: true, reason: markerBlockReason(hit) };
+      }
+    }
+
     // Guard 3 — bash mutation outside the spec dir during brainstorm.
     if (phases.brainstorm.status === "in_progress" && !firedGuards.get("brainstorm-write")) {
       // Redirect target is cleanly extractable: judge it directly against the spec dirs,
@@ -474,7 +527,7 @@ export default function (pi: ExtensionAPI) {
     description:
       "Track workflow phase progress (brainstorm → plan → implement → verify → ship). " +
       "Actions: start (mark phase in_progress), complete (mark phase complete), " +
-      "skip (mark phase skipped with reason), status (show all phases), reset (clear all phases).",
+      "skip (mark phase skipped with reason), status (show all phases), reset (clear all phases), substep (set/clear a substep label on an in_progress phase).",
     parameters: PhaseTrackerParams,
 
     async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
@@ -518,7 +571,7 @@ export default function (pi: ExtensionAPI) {
               } as PhaseTrackerDetails,
             };
           }
-          phases = { ...phases, [params.phase]: { status: "in_progress" } };
+          phases = { ...phases, [params.phase]: transitionPhaseState("in_progress") as PhaseState };
           firedGuards.clear();
           updateWidget(ctx);
           return {
@@ -559,7 +612,7 @@ export default function (pi: ExtensionAPI) {
               } as PhaseTrackerDetails,
             };
           }
-          phases = { ...phases, [params.phase]: { status: "complete" } };
+          phases = { ...phases, [params.phase]: transitionPhaseState("complete") as PhaseState };
           firedGuards.clear();
           updateWidget(ctx);
           const advisory =
@@ -591,7 +644,7 @@ export default function (pi: ExtensionAPI) {
             };
           }
           const reason = params.reason;
-          phases = { ...phases, [params.phase]: { status: "skipped", reason } };
+          phases = { ...phases, [params.phase]: transitionPhaseState("skipped", reason) as PhaseState };
           firedGuards.clear();
           updateWidget(ctx);
           return {
@@ -602,6 +655,33 @@ export default function (pi: ExtensionAPI) {
           };
         }
 
+        case "substep": {
+          if (!params.phase) {
+            return {
+              content: [{ type: "text", text: "Error: phase required for substep" }],
+              details: { action: "substep", phases: { ...phases }, error: "phase required" } as PhaseTrackerDetails,
+            };
+          }
+          const check = checkSubstep(phases[params.phase].status);
+          if (!check.ok) {
+            return {
+              content: [{ type: "text", text: `Error: phase "${params.phase}": ${check.error}` }],
+              details: { action: "substep", phases: { ...phases }, error: check.error } as PhaseTrackerDetails,
+            };
+          }
+          const entry: PhaseState = { status: "in_progress" };
+          if (typeof params.substep === "string" && params.substep.trim()) entry.substep = params.substep.trim();
+          phases = { ...phases, [params.phase]: entry };
+          updateWidget(ctx);
+          const label = entry.substep
+            ? `Phase "${params.phase}" substep → ${entry.substep}`
+            : `Phase "${params.phase}" substep cleared`;
+          return {
+            content: [{ type: "text", text: `${label}\n${formatStatus(phases)}` }],
+            details: { action: "substep", phases: { ...phases } } as PhaseTrackerDetails,
+          };
+        }
+
         case "status": {
           return {
             content: [{ type: "text", text: formatStatus(phases) }],
@@ -610,7 +690,9 @@ export default function (pi: ExtensionAPI) {
         }
 
         case "reset": {
-          phases = emptyPhases();
+          phases = Object.fromEntries(
+            PHASES.map((p) => [p, transitionPhaseState("pending")]),
+          ) as PhaseMap;
           conformanceDispatched = false;
           firedGuards.clear();
           updateWidget(ctx);
@@ -667,6 +749,11 @@ export default function (pi: ExtensionAPI) {
           );
         case "skip":
           return new Text(theme.fg("dim", "⊘ ") + theme.fg("muted", "phase skipped"), 0, 0);
+        case "substep": {
+          const active = PHASES.find((ph) => p[ph].status === "in_progress");
+          const label = active ? phaseLabel(active, p[active].substep) : "";
+          return new Text(theme.fg("warning", "→ ") + theme.fg("muted", label), 0, 0);
+        }
         case "status": {
           let text = theme.fg("muted", "Phases:");
           for (const ph of PHASES) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-gauntlet",
-  "version": "4.3.0",
+  "version": "4.4.0",
   "description": "Opinionated, gated workflow skills, subagent personas, and runtime extensions for the pi coding agent.",
   "author": "Jacek Juraszek",
   "type": "module",

package/skills/brainstorming/SKILL.md

@@ -49,15 +49,19 @@ Work through the items below **in order**. This is your own checklist to follow,
 
    Re-entering while a brainstorm is already in progress is safe: mid-brainstorm there are no tasks or later phases to lose, so the reset just re-establishes the same clean slate.
 2. **Set up the worktree** — see [Worktree First](#worktree-first)
-3. **Explore project context** — files, docs, recent commits, current behaviour
-4. **Ask clarifying questions** — one at a time
+3. **Gather context** — follow `gatherer.md` (same directory): set substep `gather`,
+   dispatch the builders, assemble the context draft at the spec path, clear the
+   substep. Unconditional, foreground, no user interaction — the next thing the user
+   sees is a questionary question. This produces the draft; the step below consumes it.
+4. **Understand the idea against the draft** — `Read` the draft, verify load-bearing
+   claims against real code, ask questions one at a time, append citable findings
 5. **Propose 2-3 approaches** — with trade-offs and a recommendation
 6. **Present the design** — in sections, get approval after each
 7. **Write the spec** — to `doc/specs/` (see [Filename Convention](#filename-convention))
 8. **Spec self-review (lint)** — placeholder scan + internal consistency + documentation named, run inline
 9. **Critique pass (auto-dispatched)** — scope + ambiguity; the spec council via `/skill:roasting-the-spec` when `gauntlet_setting` returns verdict `council`, else a fresh `worker` (see [Spec Council](#spec-council-optional))
 10. **Re-run placeholder scan** — after the critique pass returns, first inline any `external-ref:` flags it raised (see [Spec Self-Review](#spec-self-review-before-user-review-gate)), then re-scan for placeholders its edits may have introduced; surface any ambiguity the worker could not safely resolve at the user gate
-11. **Generate spec summary** — dispatch a fresh, spec-only `spec-summarizer` and render its returned text **verbatim** at the top of the gate message — do not paraphrase, condense, re-section, or rewrite it (see [User Review Gate](#user-review-gate)); this is part of the existing gate, not a new one
+11. **Generate spec summary** — dispatch a fresh, spec-only `spec-summarizer` writing to an absolute temp-dir path via `outputMode: "file-only"`, then `Read` that file back as the **last content-producing** tool call before composing the gate and render its contents **verbatim** at the top of the gate message — do not paraphrase, condense, re-section, or rewrite it (see [User Review Gate](#user-review-gate)); this is part of the existing gate, not a new one
 12. **User review gate** — user reviews the committed spec
 13. **Transition** — only after approval, invoke `/skill:writing-plans`
 
@@ -112,12 +116,26 @@ Don't try to design a multi-subsystem monolith in one spec doc.
 
 ### 3. Understand the idea
 
-- Check the current project state first: files, docs, recent commits, neighboring services.
-- **Check if the codebase or ecosystem already solves this** before designing from scratch. Grep, read existing AGENTS.md, look at `doc/` and `doc/specs/`.
-- Ask questions **one at a time** to refine the idea.
-- Prefer multiple-choice questions; open-ended is fine when needed.
-- One question per message. If a topic needs more exploration, split into multiple turns.
-- Focus on: purpose, constraints, success criteria, who/what it touches.
+The gather step (see `gatherer.md`) has already assembled a context draft at the spec
+path.
+
+- `Read` the draft **unconditionally before composing question one**. The on-disk
+  copy is canonical — this one rule defeats both a turn-boundary prune after assembly
+  and a session restart.
+- The draft is a **helper, not a fence**: judgment still drives exploration. Verify
+  load-bearing claims (schemas, contracts, the code being changed) against real code
+  via targeted reads (`read_symbol`-grade, not scout's paraphrase) before designing
+  against them.
+- **Check if the codebase or ecosystem already solves this** — the draft's recon
+  section starts that answer; confirm it before designing from scratch.
+- Ask questions **one at a time** to refine the idea. Prefer multiple-choice; one
+  question per message. Focus on: purpose, constraints, success criteria, who/what
+  it touches.
+- **Append bar:** append to the draft's `## Appended during questionary` only
+  findings the spec will cite — schema shapes, hard constraints, ticket-vs-code
+  contradictions, user answers that changed scope. Not a log of every grep.
+  (Appending uses `edit`; the `edit` prohibition in the spec-writing step applies
+  only there.)
 
 ### 4. Explore approaches
 
@@ -197,8 +215,25 @@ Spec lives in the project's `doc/specs/` (see [Project Routing](#project-routing
 
 `<topic>` is a short kebab-case slug (3–6 words). Do **not** append `-design` or any other suffix.
 
+The slug is minted **once, at gather time**, from the initial prompt; the spec-writing
+overwrite reuses the path. If the questionary invalidated the slug, rename at
+spec-writing: write the spec at the new path **and delete the old draft file**
+(nothing was committed, so this is free).
+
 ## Spec Self-Review (Before User Review Gate)
 
+Spec-writing replaces the context draft, in this exact order:
+
+1. `Read` the draft in full — **immediately before** the overwrite. Without this, a
+   pruned questionary plus a full-replacement `write` destroys the only copy of the
+   gathered context at the moment it feeds the spec.
+2. Write the spec with the `write` tool (**full replacement**) at the spec path.
+   Using `edit` at this step is a red flag.
+3. **Immediately after the write**, confirm line 1 of the file is no longer
+   `# CONTEXT DRAFT - NOT A SPEC - fully replaced at spec-writing` — before
+   dispatching lint, critique, council, or summarizer. The phase-tracker commit
+   guard is a backstop, not the primary check.
+
 After writing the spec to `<project>/doc/specs/<filename>.md` (per [Filename Convention](#filename-convention)) and before showing it to the user, run a self-review pass. **Read all five bullets first, then act:** only the **first three** run here at the main loop (the inline lint); the **last two** (scope + ambiguity) do **not** run inline — they are the dispatched critique pass (checklist item 9). Do not apply scope/ambiguity edits yourself.
 
 - **Placeholder scan.** Any `TODO`, `TBD`, `<fill in>`, `[example]`, `xxx`? Either resolve them or convert to explicit "Open Questions" with names.
@@ -236,19 +271,33 @@ After the inline lint and before the user review gate, **brainstorming owns the
 
 After self-review (and council review, if configured) and after inlining any external-ref flags, dispatch the spec-only summarizer, then commit the spec on the worktree branch and stop. This is the **same** single human gate - the summary is folded into it, not a new gate.
 
-Dispatch the summarizer on a fresh context, reading only the spec (no `output:` path - capture the return inline; no `model:` - it inherits the main loop unless a preset sets `subagents.agentOverrides.spec-summarizer.model`):
+Mint an absolute temp path outside the worktree (so it is never committed), then dispatch the summarizer on a fresh context, reading only the spec, writing to that path via file-only output (no `model:` - it inherits the main loop unless a preset sets `subagents.agentOverrides.spec-summarizer.model`):
+
+```bash
+SUMMARY_PATH=$(mktemp "${TMPDIR:-/tmp}/gauntlet-spec-summary.XXXXXX")   # absolute, portable across GNU/BSD mktemp
+```
 
 ```
-subagent({ agent: "spec-summarizer", context: "fresh", cwd: "<abs worktree path, from git rev-parse --show-toplevel>", task:
+subagent({ agent: "spec-summarizer", context: "fresh", cwd: "<abs worktree path, from git rev-parse --show-toplevel>",
+  output: "<SUMMARY_PATH>", outputMode: "file-only", task:
   "Summarize the spec at <abs path to doc/specs/...> for the user review gate. Read ONLY that file." })
 ```
 
-If the dispatch fails, reach the gate anyway with a one-line "summary generation failed" note - the summary is an aid, not a gate.
+`<SUMMARY_PATH>` above is a placeholder in the dispatch object; it means substitute the value of the shell variable `$SUMMARY_PATH` set above. The steps below use `$SUMMARY_PATH` (the shell form) once the value is in hand.
+
+Then commit the spec — this commit is **unconditional**: the summary is only a gate aid, so a degraded or missing summary never blocks it. Evaluate the summary in two stages (the **Degrade path** referenced in each is defined just below):
+
+1. **From the dispatch tool result, before the `Read`.** If the result is **not** an `"Output saved to: <path> (<N> KB, <M> lines)"` reference (e.g. an exit-0 save error returns the full inline output plus an "Output file error" line — the prunable shape, no file to read), or the reference reports under ~500 bytes, or a size grossly disproportionate to the spec (under ~2% of its byte size), or over ~45 KB (the `Read` truncates at 50KB / 2000 lines, so a larger file cannot render whole) — skip the `Read` and take the degrade path. Use the reference's reported figures; do not re-derive them.
+2. **The `Read` itself, as the last content-producing tool call before composing the gate.** `Read` `$SUMMARY_PATH` and paste its contents verbatim at the top of the gate. If the `Read` fails, returns 0 bytes, or reports truncation — take the degrade path. The `Read` must be last: pi-condense does not protect a `/tmp` read, so any turn boundary between the `Read` and the render lets the ~9KB read result be pruned, reproducing the bug.
+
+**Degrade path** — reach the gate with a one-line "summary generation failed" note; never paraphrase from the file-only reference, never render a stub as the canonical summary.
+
+Either way — summary rendered or degraded — then `rm "$SUMMARY_PATH"` (unconditional cleanup; harmless if the file was never created, since it lives outside the worktree under the OS temp dir).
 
-Render the summarizer's returned text **verbatim** first — paste it as-is, do **not** paraphrase, condense, re-section, drop sections, or merge it with council output. "Fold into the gate" means *place it inside the gate message*, not *rewrite it*. After the verbatim block, append the commit confirmation, then — as their **own** adjacent lines, not edits to the summary — any council outcome, critique-pass-unresolved ambiguities, and every entry from the summarizer's gap/external-context footer (surface **all** of them, not just the top risk):
+Render the temp file's contents **verbatim** first — paste it as-is, do **not** paraphrase, condense, re-section, drop sections, or merge it with council output. "Fold into the gate" means *place it inside the gate message*, not *rewrite it*. After the verbatim block, append the commit confirmation, then — as their **own** adjacent lines, not edits to the summary — any council outcome, critique-pass-unresolved ambiguities, and every entry from the summarizer's gap/external-context footer (surface **all** of them, not just the top risk):
 
 ```
-<spec-only summary from spec-summarizer — pasted verbatim, unedited>
+<spec-only summary read back from the temp file — pasted verbatim, unedited>
 
 Spec written and committed to <project>/doc/specs/<filename>.md (worktree: <path>).
 
@@ -259,7 +308,7 @@ Please review. Approve to proceed, or tell me what to change in the spec.
 
 If you believe the summary needs correcting, do **not** silently rewrite it — re-dispatch the summarizer or note the discrepancy as an adjacent line beneath the verbatim block.
 
-Wait for the user. On a change request, revise and re-present. On approval, proceed immediately to `/skill:writing-plans` with no further prompt — the plan and execution mode are mechanical derivatives, so the only human gate here is spec approval itself. Don't land the spec on `main`; it stays in the worktree and ships in the same squash commit as the implementation.
+Wait for the user. On a change request, revise the spec and re-present — mint a **fresh** temp path for the re-dispatched summarizer (never reuse a prior round's path, so stale content can never be mistaken for the new summary). On approval, proceed immediately to `/skill:writing-plans` with no further prompt — the plan and execution mode are mechanical derivatives, so the only human gate here is spec approval itself. Don't land the spec on `main`; it stays in the worktree and ships in the same squash commit as the implementation.
 
 After approval, mark the brainstorm phase complete:
 
@@ -280,11 +329,16 @@ phase_tracker({ action: "complete", phase: "brainstorm" })
 ## Red Flags — STOP
 
 - About to write code or start a non-spec edit while this skill is active
+- About to dispatch lint, critique, council, or summarizer while the spec file's line 1 is still the context-draft marker
+- About to run the spec-writing overwrite without re-reading the draft in the same turn
+- About to use `edit` instead of `write` for the spec-writing overwrite
+- About to insert a human gate, announcement, or question between gather dispatch and questionary question one
 - About to run, deploy, or validate the **proposed change** (vs. observing current behaviour) before the user approved the design
 - About to skip the critique pass (council if configured, else fresh worker)
 - Critique dispatch (council or worker) failed to complete and you proceeded to the gate anyway
 - About to reach the user gate without re-running the placeholder scan after the critique returned
-- About to reach the user gate without rendering the spec-only summary (dispatch `spec-summarizer` first; a failed dispatch degrades to a one-line note, it is not silently skipped)
+- About to reach the user gate without rendering the spec-only summary (dispatch `spec-summarizer` to a temp file first; a failed/stub/truncated read degrades to a one-line note, it is not silently skipped)
+- About to compose the gate message when the summary `Read` was not the last content-producing tool call before it (a following `rm` of the temp file is fine) — a turn boundary between the `Read` and the render lets pi-condense prune the ~9KB read result, reproducing the original bug
 - About to present a paraphrased, condensed, or re-sectioned version of the summarizer's output instead of pasting its returned text verbatim — rewriting the summary counts as not rendering it
 - About to run the scope or ambiguity checks inline yourself instead of dispatching them (those two are the critique pass, not the inline lint)
 - About to skip the self-review pass

package/skills/brainstorming/gatherer.md

@@ -0,0 +1,117 @@
+# Context Gather (brainstorming supplementary)
+
+Consumed only by `SKILL.md` in this directory. Runs unconditionally between worktree
+setup and the questionary. **Foreground, no user interaction** — the first thing the
+operator sees after gather is questionary question one. Do not announce, do not ask.
+
+## Dispatch
+
+Mint a temp dir outside the worktree (never committed):
+
+```bash
+GATHER_DIR=$(mktemp -d)
+```
+
+Set the substep, then dispatch one parallel-tasks `subagent` call (foreground — no
+`async:`; no `model:` — pi-cohort `agentOverrides` owns builder models):
+
+```
+phase_tracker({ action: "substep", phase: "brainstorm", substep: "gather" })
+subagent({
+  tasks: [
+    { agent: "scout", cwd: "<abs worktree path>", phase: "context-gather",
+      output: "<GATHER_DIR>/scout.md",
+      task: "<scout task, template below>" },
+    // include ONLY when the trigger rule below fires:
+    { agent: "context-builder", cwd: "<abs worktree path>", phase: "context-gather",
+      output: "<GATHER_DIR>/external.md",
+      task: "<context-builder task, template below>" }
+  ]
+})
+```
+
+Absolute `output:` paths are mandatory: relative paths in parallel mode resolve
+against the worktree and would get committed.
+
+## Task templates
+
+Scout (always dispatched):
+
+> Recon for an upcoming design discussion. The request: `<initial prompt verbatim>`.
+> Map the territory this change touches: relevant files with line ranges, existing
+> patterns and conventions the change must match, test conventions, integration
+> points, and whether the codebase or ecosystem already solves any of this. Cite
+> exact paths and line ranges. End with an "Open questions that matter for the spec"
+> section. Compact handoff, not a dump.
+
+Context-builder (conditional):
+
+> Extract external context for an upcoming design discussion. The request:
+> `<initial prompt verbatim>`. Fetch and distill these references:
+> `<detected refs, one per line>`. For each: acceptance criteria, hard constraints,
+> linked discussion that changes scope, and contradictions with the request as
+> stated. Write ONLY the context handoff to your output path; do NOT produce a
+> meta-prompt file. End with an "Open questions that matter for the spec" section.
+> If a ref is unreadable, say so explicitly and continue.
+
+(The meta-prompt exclusion matters: in chain mode context-builder emits two files —
+`context.md` + `meta-prompt.md`; this flow consumes only the context handoff.)
+
+## Context-builder trigger rule
+
+Dispatch context-builder when the initial prompt (or a file it explicitly references)
+contains any of:
+
+- an `http(s)://` URL;
+- a tracker-style ID matching `[A-Z][A-Z0-9]+-\d+` (Linear/Jira form) **when a fetch
+  path exists** (a tracker tool/MCP, or a URL pattern in `.pi/gauntlet-overrides.md`);
+- a GitHub-style ref `owner/repo#N`, or a bare `#N` when the repo's tracker is
+  GitHub Issues.
+
+Examples: "implement ABC-123" with a Linear tool available → trigger; "add rate
+limiting like https://example.com/rfc" → trigger; "rename the settings resolver" →
+scout only. An opaque ID with **no** fetch path → do not dispatch; list it in the
+draft's `## External context` as an unfetched ref instead of guessing.
+
+## Failure and degradation
+
+A builder **failed** when its task errored **or** its output file is missing or
+empty (0 bytes). Degradation never blocks and never surfaces to the user at gather
+time:
+
+- scout failed → `## Codebase recon` reads: `Scout recon failed (<one-line reason>).
+  Draft is thin; exploration falls to the questionary.` followed by the initial prompt.
+- context-builder failed → `## External context` reads: `External refs not fetched
+  (<one-line reason>):` followed by the ref list — the critique pass later surfaces
+  them as external-ref candidates.
+
+## Draft assembly
+
+Read the temp files and write the draft **to the spec path** (normal filename
+convention; slug minted from the initial prompt):
+
+```markdown
+# CONTEXT DRAFT - NOT A SPEC - fully replaced at spec-writing
+
+## Codebase recon
+<scout output, or the degraded text>
+
+## External context
+<context-builder output, degraded text, or unfetched-ref list; omit this section
+only when the trigger rule never fired>
+
+## Appended during questionary
+<starts empty>
+```
+
+The marker line is **line 1, verbatim**. Then clean up and clear the substep:
+
+```bash
+rm -rf "$GATHER_DIR"
+```
+
+```
+phase_tracker({ action: "substep", phase: "brainstorm", substep: null })
+```
+
+The questionary runs under plain `brainstorm`.

package/skills/subagent-driven-development/SKILL.md

@@ -141,13 +141,13 @@ Auto-selected at handoff by `writing-plans` (any wave with ≥2 tasks) when the
 
 1. **Independence check.** Parse the wave's tasks' `Files:` blocks; assert pairwise-disjoint (mechanical). Runtime-resource disjointness (DB/schema, port, fixture, external service, shared temp path) is not machine-checkable here — trust the plan's wave grouping, which `writing-plans`' D5 contract guarantees. Either kind of overlap → the wave is mis-grouped; run those tasks as sequential single-task waves and note it.
 2. **Fan out.** One parallel dispatch (shape below): `implementer` per task, `context: "fresh"`, `worktree: true`. Each returns a status + a patch.
-3. **Status + spec review per task.** Parse each `DONE`/`BLOCKED`/etc. (see [Implementer Status](#implementer-status)); spec-review each returned patch against its task (read-only, parallelizable). Re-dispatch incomplete tasks (fresh, `worktree: true`) until `DONE` + spec ✅.
+3. **Status + spec review per task.** Parse each `DONE`/`BLOCKED`/etc. (see [Implementer Status](#implementer-status)) **first**. Then **dispatch a `spec-reviewer` per accepted patch** (`DONE`, or a `DONE_WITH_CONCERNS` you proceeded with) in one parallel fan-out — `context: "fresh"`, `cwd: <this worktree>`, **no `worktree` flag** (read-only) — each passed its task text, the returned **patch diff**, and the absolute spec path. Review is **diff-based**: the diff's hunks carry `file:line`, and test execution is not the reviewer's job here (the wave test gate in step 5 runs the suite). Inline verdicts are fine at normal wave sizes; large waves use `output:` + `outputMode: "file-only"` to keep verdicts out of your context. **Re-dispatch by cause:** `BLOCKED`/`NEEDS_CONTEXT` per the [Implementer Status](#implementer-status) matrix; a **spec gap** re-dispatches the implementer (fresh, `worktree: true`) carrying the prior patch + the reviewer's findings, the new patch superseding the old at step 4. Loop until accepted + spec ✅.
 4. **Integrate.** `git apply` each task's patch sequentially onto HEAD. Apply fails = textual conflict → drop that task, finish the rest, re-run the dropped task sequentially on the updated HEAD.
 5. **Test gate.** Run the suite on the integrated tree. Failure = semantic conflict or bug → re-run the offending task sequentially, else fix per [When a Subagent Fails](#when-a-subagent-fails).
 6. **Quality review.** Code-quality review on the integrated wave diff; loop fixes to ✅.
 7. **Commit the wave.** Leaves a clean tree; the next wave's children branch from this commit and so see the integrated work.
 
-**Two-stage review is preserved:** spec review per task (pre-integration), quality review per wave (post-integration). Both gates required before the wave commits.
+**Two-stage review is preserved:** spec review per task (pre-integration, dispatched `spec-reviewer` — not inline), quality review per wave (post-integration). Both gates required before the wave commits.
 
 **Dependent context across waves:** wave N+1 tasks branch from a HEAD containing wave N, so they see the code; still forward wave N's task summaries into wave N+1 prompts.
 
@@ -203,6 +203,7 @@ For the fan-out + worktree + patch-integration + conflict mechanics, see `dispat
 - Starting code-quality review before spec compliance is ✅
 - Moving to next task with either review still showing issues
 - Letting implementer self-review replace external review (both needed)
+- Spec-reviewing wave patches inline instead of dispatching `spec-reviewer` per patch — sequential mode's step 3 dispatches it; wave mode must too
 - Pausing to "check in" between tasks (continuous execution rule)
 - Skipping the `Implementer Status` parse — treating every response as DONE
 - Starting on main without explicit user consent