pi-gauntlet 4.3.1 → 4.4.0

package/CHANGELOG.md

@@ -1,5 +1,42 @@
 # 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

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/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.1",
+  "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,8 +49,12 @@ 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))
@@ -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.
@@ -294,6 +329,10 @@ 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

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`.