pi-gauntlet 6.2.0 → 7.0.0

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## v7.0.0 - 2026-10-01
+
+### Changed
+
+- **gatekeep-pr judges mechanism, not delivery.** Each acceptance criterion splits into a mechanism half (code, tests, docs at the assessed head - `covered` or `gap`) and an observation half that is checked after merge, not here, and never blocks. A `gap` is a blocker; `partial`/`missing` AC coverage and the merge-proof claim rule are gone, so a "verified on staging" line in a PR body no longer withholds merge - the untested-path rubric row does. An AC no repository change can satisfy becomes a drafted ticket change (`drafted` -> `proposed` -> `resolved`) that withholds merge until a human edits the ticket or picks `merge anyway - accept AC<n> as impossible`. `/skill:check-delivery` states it takes no input from the gate and re-derives ACs and the shipped SHA itself.
+- **Blocker or nit, nothing else.** The follow-up category, the `F#` namespace, and the owner column are removed. Doc drift beyond wording blocks; wording-only drift and style are nits. Doc fixes are drafted payloads applied only on a `fix` pick - the worktree is clean at every menu render and `push-docs` is gone.
+- **Compact bottom-up report.** Sections render `Delivers` -> `Ticket changes` -> `PR comments` -> `Nits` -> `Blockers` -> one verdict line (`mergeable - <evidence>` | `fixable - <N> blockers` | `fixable - <withhold reason>`) -> menu, so the verdict is what a terminal shows. Items are one or two whole sentences with trailing locators; empty sections are omitted; verbatim output, payloads, and covered ACs print only under `show evidence`.
+- **`fix` on every open-PR menu, whoever authored the PR.** Fork PRs apply it to the local `pr-<N>` worktree with `push` and `merge` `(not available: fork)`; authorship moves only `[recommended]`. Rows are `<n>. <verb> - <consequence>`; composed forms (`fix 2`, `fix nits`, `check <name> flaky | real | ci-broken`) live in the hint line.
+- **Seven-step orchestrator.** `skills/gatekeep-pr/SKILL.md` is 69 lines: step table, wording rules, red flags. Each closed topic has one sibling owner: `reference/assessment.md` (step 2: worktree, config ladder, ticket fetch after the ladder resolves), `reference/findings.md` (step 5 integration), new `reference/report.md`, `reference/decision-menu.md` (two tables: consent and overlays), `reference/post-selection-loop.md` (fix wave, re-render, wait, merge preconditions, done-check, teardown); `verification-brief.md` keeps the three delegate sections. The static oracle `scripts/gatekeep-comment-reconcile.test.mjs` grows from 4 to 12 tests. Consumer `REVIEW.md` files that map Minor to "non-blocking follow-up" now read as nits.
+
+## v6.2.1 - 2026-10-01
+
+### Changed
+
+- **Brainstorming entry is explicit opt-in.** `/skill:brainstorming` is the reliable discovery-and-entry path; explicit prose requesting brainstorming/the gauntlet also supplies consent when the skill is already loaded or an available instruction or route identifies it. Ordinary implementation requests and agent recommendations do not authorize tracker resets or worktree creation. Enforcement starts once opted in, and spec approval still automatically chains into planning and implementation.
+- **Brainstorming instructions are shorter without dropping workflow rules.** Ticket handling and spec finalization now have two required-read reference owners; the main skill keeps entry consent, questionary, and named entry points. Existing ticket dispositions, critique verdict branches, summary degradation, approval, and amend/redraw contracts remain in place.
+
 ## v6.2.0 - 2026-09-30
 
 ### Changed

package/README.md

@@ -36,11 +36,11 @@ pi-gauntlet's only hard dependency is pi-cohort - every gate that dispatches a r
 Concretely, one change through the gauntlet:
 
 0. *(Optional)* Before there's even a spec, `/skill:shape-ticket` can create or repair a single tracker issue - shaping a raw ask into a Context/Problem/Idea/Acceptance Criteria ticket, gated by an AC integrity check, a cheap council roast, and one human-confirmed write that may include one optional gated Reporter-note comment. A failed roast is retried once, then surfaced inline at the gate if it fails again. It's a tool, not a phase: no worktree, no plan/phase tracker, runs from any repo state. It never activates on its own (`disable-model-invocation: true`) - invoke it explicitly. Similarly, `/skill:chase-bug` triages a raw bug report into an evidenced verdict - and can hand off to shape-ticket, brainstorming, or a bounded hotfix - before any spec exists.
-1. You describe the change. **`brainstorming`** sets up an isolated worktree, explores the codebase, and turns your description into a written spec; when the run starts from a ticket, the spec carries the ticket's acceptance criteria verbatim, each with a disposition (`in-scope`, `deviates:`, `deferred:`, `venue:`), the conformance gate checks the in-scope ones, and `/skill:check-delivery` verifies `venue:` rows after deploy. A multi-model critique runs on it automatically. If the spec replaces a known prior spec, brainstorming marks the predecessor with a `> **Superseded by:**` banner under its title (default format, syntax overridable via `.pi/gauntlet-overrides.md`; candidates come from brainstorming's scout recon, never a mechanical sweep). **You read and approve the spec - human gate 1.** No implementation code exists yet.
+1. Opt in with `/skill:brainstorming` and describe the change. The command is the reliable discovery-and-entry path; explicit prose requesting brainstorming/the gauntlet also supplies consent when the skill is already loaded or an available instruction or route identifies it. An ordinary implementation request or an agent recommendation is not consent. **`brainstorming`** sets up an isolated worktree, explores the codebase, and turns your description into a written spec; when the run starts from a ticket, the spec carries the ticket's acceptance criteria verbatim, each with a disposition (`in-scope`, `deviates:`, `deferred:`, `venue:`), the conformance gate checks the in-scope ones, and `/skill:check-delivery` verifies `venue:` rows after deploy. A multi-model critique runs on it automatically. If the spec replaces a known prior spec, brainstorming marks the predecessor with a `> **Superseded by:**` banner under its title (default format, syntax overridable via `.pi/gauntlet-overrides.md`; candidates come from brainstorming's scout recon, never a mechanical sweep). **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. Independent implementation, review, and council batches remain parallel, but their dispatches are foreground: the orchestrator waits for terminal results before accepting work or advancing a phase.
 4. **verify**: the parent first runs the plan's full verification command set; only a passing result permits whole-diff code review, then the **conformance gate**. A review fix invalidates that result, so the parent reruns full verification before the next review or conformance gate. When the overrides file declares a happy path for the touched paths (see [Project-specific overrides](#project-specific-overrides)), the parent runs it once here, between code review and the conformance gate, and the reviewer reads its transcript as runtime evidence - a hang or a failed request shows up in the audit with the transcript quoted - as a gap when an origin clause ties to it, otherwise as a `happy-path: failed - unattributable` line - never as a silent green. The conformance 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. Unauthorized rows - shipped surface no human input asked for, whether it crept in or was laundered through the spec - follow their recommendation like every other row: a contained removal auto-runs, anything another requirement leans on is deferred with a plain-language "I'd cut it / I'd keep it" recommendation. Inside a brainstorming-entered flow this gate is machine-blocked from being skipped. Compatible executable recommendations auto-run through an isolated fix-and-re-audit loop with no prompt; anything still open surfaces as a dense list - one line per decision, plain-language, with its recommended choice inline. Reply `1` to take every recommendation, or `2:` with per-item overrides; a current `CONFORMS` / no-concerns result goes straight to the branch options with no extra conformance sign-off.
-5. **`finishing-a-development-branch`**: PR, draft PR, squash, keep, or discard. Once a PR exists, run `/skill:gatekeep-pr <pr>` to verify it against its issue before merging. **Human gate 2** - the only other decision you make.
+5. **`finishing-a-development-branch`**: PR, draft PR, squash, keep, or discard. Once a PR exists, run `/skill:gatekeep-pr <pr>` to verify it before merging - it judges whether the diff delivers the mechanism each acceptance criterion needs (code, tests, docs) and conforms to the rubric; whatever can be seen only after merge is left to step 6. **Human gate 2** - the only other decision you make.
 6. *(Optional)* Once the merge lands, `/skill:check-delivery <ref>` can prove delivery - default-branch landing, delivery target, per-AC evidence - before the tracker status advances. Explicit invocation only, no auto-chain: deploys commonly lag merges by minutes to hours, so an auto-run would routinely check too early.
 
 Only the machine-owned `plan -> implement` and `verify -> ship` handoffs receive a branch-local one-shot nudge after an unexpected settled stop; it is fire-and-forget, does not bypass either human gate, and older Pi hosts without `agent_settled` retain existing behavior.
@@ -48,7 +48,7 @@ Only the machine-owned `plan -> implement` and `verify -> ship` handoffs receive
 ```mermaid
 flowchart LR
     T["shape-ticket<br/>(optional, explicit)"]
-    R([request]) --> B[brainstorm<br/>+ spec]
+    R([explicit opt-in]) --> B[brainstorm<br/>+ spec]
     T -.-> R
     B --> G1{{human gate 1:<br/>approve spec}}
     G1 --> P[plan]
@@ -69,11 +69,11 @@ Everything between gate 1 and gate 2 - task breakdown, implementation, both revi
 
 pi-gauntlet ships three kinds of pieces, layered on top of pi-cohort's dispatch:
 
-- **20 skills** - the workflow logic. Thirteen 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`, `requesting-code-review`, `receiving-code-review`, `using-git-worktrees`, `finishing-a-development-branch`, `forge-skill`, `linear` (reads/searches/comments on/manages Linear tickets via the `linearis` CLI; owns all linearis mechanics and the `## Issue tracker` overrides schema; tracker-facing skills route to it). Seven more are explicit-invocation-only (`disable-model-invocation: true`): `shape-ticket` creates or repairs one tracker issue per run against a Context/Problem/Idea/Acceptance-Criteria template, gated by an AC integrity check, a cheap council roast, and a single human-confirmed write - run it with `/skill:shape-ticket`. `gatekeep-pr` is consent-gated pre-merge verification of a PR against its issue - read-only gathering, verification evidence resolved CI-first (green checks on the exact assessed head count as evidence; the project's verification command runs only as fallback), a rubric-based review, then a deterministic authorship-aware menu with stable finding IDs (P#/L#/C#/F#) and numbered pre-composed courses (fixes execute as a single parallel-safe wave: one gate run, one re-review, one push); nothing mutates (fixes, pushes, reviews, merges) until you pick a row - run it with `/skill:gatekeep-pr <pr>`. `check-delivery` is a post-merge detective control: proves an issue actually shipped (default-branch landing, delivery target, per-AC evidence) before its tracker status advances; it never writes a terminal status - run it with `/skill:check-delivery <ref>`. `chase-bug` is human-only bug triage: read-only root-cause discovery to an evidenced verdict menu (real bug -> ticket/brainstorm/hotfix/respond; five negative verdicts), then a gated response to the reporter for addressable origins (GitHub issue / tracker ticket) and a rendered verdict summary otherwise - it never fixes during triage; the hotfix row hands off to `skills/chase-bug/hotfix.md` after the menu - run it with `/skill:chase-bug`. `gauntlet-performance` reads the committed run telemetry (current repo by default, `--dir <path>` adds others) through the parse-only `gauntlet-performance` CLI and answers with one example-led recommendation, 3-5 cornerstone numbers, a council assessment when available, and a menu of at most three actions (render a report file, open the recommendation as a ticket via `shape-ticket`, drill into one run); it writes nothing unless you pick render - run it with `/skill:gauntlet-performance [--dir <path>]... [--since <version>]`. `gauntlet-handoff` ends a session whose flow a fresh session will continue: it invokes pi-cohort's `handoff` skill (`--out <path>` or `--key <name>`, default key = the run worktree's branch with `/` flattened to `-`, default file `<tmpdir>/pi-handoff/<key>.md`), then appends the gauntlet process-state section (phase/plan tracker status) per the shared contract `skills/gauntlet-resume/reference/brief-contract.md` - run it with `/skill:gauntlet-handoff [--out <path> | --key <name>]`. `gauntlet-resume` is the only way back into an interrupted flow from a fresh session: it takes a `gauntlet-handoff` brief (a file path, pasted text, or - with no arguments - a pick from the briefs under `<tmpdir>/pi-handoff/`), a bare worktree that already holds a spec, or a spec tracked on main under a configured spec dir (a spec seed: it creates or reuses the worktree through `using-git-worktrees` and pins the spec), restores phase/plan tracker state through the legal arming sequence (`start brainstorm`, `skip` with `resume:` reasons, `plan_check` before implement-or-later), and never infers approval from artifacts - run it with `/skill:gauntlet-resume [<brief-file> | <spec>.md | <worktree-name-or-path>]`.
+- **20 skills** - the workflow logic. Twelve activate automatically when pi sees the matching kind of task, and the workflow skills chain through their gates: `writing-plans`, `roasting-the-spec`, `test-driven-development`, `subagent-driven-development`, `dispatching-parallel-agents`, `verification-before-completion`, `requesting-code-review`, `receiving-code-review`, `using-git-worktrees`, `finishing-a-development-branch`, `forge-skill`, `linear` (reads/searches/comments on/manages Linear tickets via the `linearis` CLI; owns all linearis mechanics and the `## Issue tracker` overrides schema; tracker-facing skills route to it). Eight more require explicit entry (`disable-model-invocation: true`): `brainstorming` starts the gated workflow on explicit consent - use `/skill:brainstorming` for reliable discovery, or opt in through reachable explicit prose or a human-selected handoff; after spec approval, downstream planning and implementation still chain automatically. `shape-ticket` creates or repairs one tracker issue per run against a Context/Problem/Idea/Acceptance-Criteria template, gated by an AC integrity check, a cheap council roast, and a single human-confirmed write - run it with `/skill:shape-ticket`. `gatekeep-pr` is consent-gated pre-merge verification of a PR against its issue's acceptance criteria - read-only gathering, verification evidence resolved CI-first (green checks on the exact assessed head count as evidence; the project's verification command runs only as fallback), a rubric-based review, a compact bottom-up report (what the PR delivers, ticket changes, PR comments, nits, blockers, then a `mergeable` / `fixable` verdict) and a verb menu that always offers `fix` whoever authored the PR; nothing mutates (fixes, pushes, reviews, merges, tracker comments) until you pick a row - run it with `/skill:gatekeep-pr <pr>`. `check-delivery` is a post-merge detective control: proves an issue actually shipped (default-branch landing, delivery target, per-AC evidence) before its tracker status advances; it never writes a terminal status - run it with `/skill:check-delivery <ref>`. `chase-bug` is human-only bug triage: read-only root-cause discovery to an evidenced verdict menu (real bug -> ticket/brainstorm/hotfix/respond; five negative verdicts), then a gated response to the reporter for addressable origins (GitHub issue / tracker ticket) and a rendered verdict summary otherwise - it never fixes during triage; the hotfix row hands off to `skills/chase-bug/hotfix.md` after the menu - run it with `/skill:chase-bug`. `gauntlet-performance` reads the committed run telemetry (current repo by default, `--dir <path>` adds others) through the parse-only `gauntlet-performance` CLI and answers with one example-led recommendation, 3-5 cornerstone numbers, a council assessment when available, and a menu of at most three actions (render a report file, open the recommendation as a ticket via `shape-ticket`, drill into one run); it writes nothing unless you pick render - run it with `/skill:gauntlet-performance [--dir <path>]... [--since <version>]`. `gauntlet-handoff` ends a session whose flow a fresh session will continue: it invokes pi-cohort's `handoff` skill (`--out <path>` or `--key <name>`, default key = the run worktree's branch with `/` flattened to `-`, default file `<tmpdir>/pi-handoff/<key>.md`), then appends the gauntlet process-state section (phase/plan tracker status) per the shared contract `skills/gauntlet-resume/reference/brief-contract.md` - run it with `/skill:gauntlet-handoff [--out <path> | --key <name>]`. `gauntlet-resume` is the only way back into an interrupted flow from a fresh session: it takes a `gauntlet-handoff` brief (a file path, pasted text, or - with no arguments - a pick from the briefs under `<tmpdir>/pi-handoff/`), a bare worktree that already holds a spec, or a spec tracked on main under a configured spec dir (a spec seed: it creates or reuses the worktree through `using-git-worktrees` and pins the spec), restores phase/plan tracker state through the legal arming sequence (`start brainstorm`, `skip` with `resume:` reasons, `plan_check` before implement-or-later), and never infers approval from artifacts - run it with `/skill:gauntlet-resume [<brief-file> | <spec>.md | <worktree-name-or-path>]`.
 - **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.
 - **4 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 push or open a PR without a passing test run since your last edit; a phase-tracker flow guard reminds on implement-phase commits missing spec/code review. In a brainstorming-entered flow, phase-tracker rejects `implement` or `verify` completion while tracker tasks remain pending or in progress; see [its configuration reference](./doc/configuration.md#phase-tracker). phase-tracker also registers `plan_check`, which verifies a plan against its spec and against the grammar in [skills/writing-plans/reference/plan-contract.md](./skills/writing-plans/reference/plan-contract.md), including that each task's `Tests:` commands are selective and never the full suite; a pass stamps the plan for implementation. `telemetry` records one YAML record per gauntlet run (phase timing, models, personas, gate/fix rounds, diff at ship) that ships in the squash beside the spec - it is written only inside a brainstorming-entered flow, kept untracked and git-excluded until `finishing-a-development-branch` seals and commits it once with `gauntlet-telemetry-seal` - and blocks a brainstorm `write` into an already-shipped spec; see [its configuration reference](./doc/configuration.md#telemetry). See [doc/configuration.md](./doc/configuration.md) for the settings each one reads.
 
-pi-gauntlet is **opinionated**: every non-trivial change is *meant* to ride this one pipeline, entered through `brainstorming`. Enforcement is opt-in by entry, not ambient: once brainstorming starts a flow, the phase-tracker extension mechanically blocks a phase from closing before its gate runs, and warns once if the main loop writes code during implement (subagents own implement-phase edits). A change made *without* entering the flow (a typo, a formatting run, a dependency bump - see "When to use / when NOT to use") is not gated; the discipline of routing real work through the pipeline is a convention the tooling supports, not a trap it springs on every edit.
+pi-gauntlet is **opinionated**: it recommends this pipeline for non-trivial changes, but starts `brainstorming` only after explicit user consent. Enforcement is opt-in by entry, not ambient: once brainstorming starts a flow, the phase-tracker extension mechanically blocks a phase from closing before its gate runs, and warns once if the main loop writes code during implement (subagents own implement-phase edits). A change made *without* entering the flow (a typo, a formatting run, a dependency bump - see "When to use / when NOT to use") is not gated; the discipline of routing real work through the pipeline is a convention the tooling supports, not a trap it springs on every edit.
 
 **Worktree contract.** pi runs in the primary checkout; the work happens in `.worktrees/<branch>`. Skills never `cd` there - the worktree path is a value from the `using-git-worktrees` report (or the handoff brief on `gauntlet-resume`), carried as dispatch `cwd: "<path>"`, as `git -C <path>`, or as `(cd "<path>" && <cmd>)` for other cwd-bound commands; the runtime extensions derive the checkout from the artifact path they act on. Requires git >= 2.31; a plain (non-colocated) jj workspace has no `.git`, so the resolver falls back to `jj root` there, reading primary-vs-workspace from `.jj/repo` (a directory in the primary checkout, a pointer file in added workspaces).
 
@@ -106,7 +106,7 @@ Run by a human against pi-cohort >= 7.1.0, before a pi-gauntlet release claims t
 
 ## When to use / when NOT to use
 
-**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.
+**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. Start with `/skill:brainstorming`; a request to implement the change alone does not opt you in.
 
 **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. Between that carve-out and the full pipeline sits one middle tier: `chase-bug`'s hotfix row - a small, evidenced, urgent fix landed as an unpushed squash, entered only through the triage verdict menu.
 
@@ -413,8 +413,8 @@ gate's output.
 ```markdown
 # REVIEW.md
 
-Severity mapping: Critical and Moderate findings block merge; Minor is a
-non-blocking follow-up. Migration-safety findings also block merge.
+Severity mapping: Critical and Moderate findings block merge;
+Minor is a nit. Migration-safety findings also block merge.
 
 Project checks (in addition to the baseline):
 - Schema migrations are additive and reversible - no destructive column drops
@@ -450,8 +450,8 @@ customization lives in two places, never in the wrapper itself:
 An existing `## verification-before-completion` overrides section is an accepted
 equivalent source for the verification command only; all other PR-gate keys
 still live under `## PR gate`. A `## comms style` section in the same overrides
-file extends gatekeep-pr's output done-check (rules applied to review bodies,
-replies, tracker comments, and commit subjects before posting).
+file extends gatekeep-pr's wording rules - the rendered report and menu, and every
+external payload (review bodies, replies, tracker comments, commit subjects) alike.
 
 Anything a wrapper skill contains beyond trigger phrases is misplaced - move it to
 `REVIEW.md` or the overrides file instead.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-gauntlet",
-  "version": "6.2.0",
+  "version": "7.0.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

@@ -1,17 +1,14 @@
 ---
 name: brainstorming
-description: "You MUST use this before any creative work - creating features, building components, adding functionality, or modifying behavior. Explores user intent, requirements and design before implementation."
+description: "Use only when the user explicitly requests brainstorming or selects a handoff into it."
+disable-model-invocation: true
 ---
 
-> **Related skills:** Use `/skill:using-git-worktrees` **before** writing the spec — the spec is the worktree's first artifact. Then `/skill:writing-plans` for implementation planning.
-
 # Brainstorming Ideas Into Designs
 
 ## Overview
 
-Help turn ideas into fully formed designs and specs through natural collaborative dialogue.
-
-Identify the target project → set up an isolated worktree → understand current project context → ask questions one at a time → propose 2-3 approaches with trade-offs → present the design in two rounds → write spec to disk inside the worktree → user reviews before any implementation.
+Collaborate on designs.
 
 ## HARD CONSTRAINT
 
@@ -27,11 +24,17 @@ The line: current-system observation is research; exercising the proposed change
 
 Set top-level `async: false` on every flow-owned dispatch and leave `forceTopLevelAsync` unset or false. If a dispatch still returns an async handle, stop and report; do not poll, relaunch, or advance. A detached child is incomplete work: use the existing coordination path, never accept or duplicate it. Preserve independent parallel `tasks` batches and await all terminal results before acceptance or tracker/phase advancement.
 
+## Entry consent
+
+Start fresh only on `/skill:brainstorming`, explicit prose requesting brainstorming/the gauntlet, or a human-selected handoff. Ordinary implementation requests, discussion about usefulness, and recommendations are not consent: wait for explicit choice before reset or worktree creation.
+
+Treat the flag as discovery control, not harness authorization. The command reliably discovers this skill; honor prose when already loaded or identified by an available route, never promise otherwise unreachable prose discovery. Continue restored state and amend/redraw at their named steps without fresh entry.
+
 ## Checklist
 
 Work through the items below **in order**. This is your own checklist to follow, not a `plan_tracker` plan — brainstorming is open-ended exploration, and `plan_tracker` is execution-only (the implement phase). The terminal state is the user review gate; after approval the **only** next skill is `/skill:writing-plans`. Do not jump to implementation, and do not silently drop the critique pass.
 
-1. **Start brainstorm tracking (fresh epoch)** - as the first action on entry, before reading code, the worktree, or answering the user, reset both trackers and start the phase. A new brainstorm owns a clean slate, so stale phases and tasks from earlier work are cleared; re-entering mid-brainstorm is safe (nothing to lose, same clean slate):
+1. **Start brainstorm tracking (fresh epoch)** - as the first action on authorized fresh entry, before reading code, the worktree, or answering the user, reset both trackers and start the phase. A new brainstorm owns a clean slate, so stale phases and tasks from earlier work are cleared; re-entering mid-brainstorm is safe (nothing to lose, same clean slate):
 
    ```
    phase_tracker({ action: "reset" })   // clears all phases
@@ -40,13 +43,13 @@ Work through the items below **in order**. This is your own checklist to follow,
    ```
 
 2. **Set up the worktree** - see [Worktree First](#worktree-first).
-3. **Gather context** - follow [`gatherer.md`](gatherer.md) without a human stop.
-4. **Understand the idea against the draft** - see [Understand the idea](#3-understand-the-idea).
+3. **Gather context** - read [Ticket Handling](#ticket-handling), then follow [`gatherer.md`](gatherer.md) without a human stop.
+4. **Understand the idea against the draft** - read [Ticket Handling](#ticket-handling), then see [Understand the idea](#3-understand-the-idea).
 5. **Propose 2-3 approaches** - see [Explore approaches](#4-explore-approaches).
 6. **Present the design** - see [Present the design in two rounds](#6-present-the-design-in-two-rounds).
-7. **Write the spec** - follow [Spec Self-Review](#spec-self-review-before-user-review-gate) steps 1-5.
-8. **Spec self-review (lint)** - run the inline checks in [Spec Self-Review](#spec-self-review-before-user-review-gate).
-9. **Critique pass (auto-dispatched)** - use [Spec Council](#spec-council-optional).
+7. **Write the spec** - read [Spec Self-Review](#spec-self-review-before-user-review-gate) before writing; follow steps 1-5.
+8. **Spec self-review (lint)** - read [Ticket Handling](#ticket-handling), then run the inline checks in [Spec Self-Review](#spec-self-review-before-user-review-gate).
+9. **Critique pass (auto-dispatched)** - use [Spec Council](#spec-council).
 10. **Re-run placeholder scan** - follow [Spec Self-Review](#spec-self-review-before-user-review-gate).
 11. **Generate spec summary** - follow [User Review Gate](#user-review-gate).
 12. **User review gate** - follow [User Review Gate](#user-review-gate).
@@ -62,9 +65,7 @@ Detection order: (1) infer from ticket labels, description, or paths; (2) use th
 
 The spec is the first commit in a dedicated worktree, never a separate commit on `main`.
 
-1. Invoke `/skill:using-git-worktrees`; use `.worktrees/` or the project-native location.
-2. Carry its `Worktree ready at <full-path>` value: spec path `<full-path>/<spec dir>/<filename>.md`; every dispatch uses that `cwd`; git uses `git -C <full-path>`. Keep the process cwd unchanged.
-3. Write, review, and commit there.
+Invoke `/skill:using-git-worktrees`; use `.worktrees/` or the project-native location. Carry its `Worktree ready at <full-path>` value: spec path `<full-path>/<spec dir>/<filename>.md`; every dispatch uses that `cwd`; git uses `git -C <full-path>`. Keep the process cwd unchanged.
 
 Spec, plan, and implementation share this worktree. The spec and its telemetry record (`<telemetry.dir>/<spec path with .md -> .yaml>`, default `.pi/gauntlet/telemetry/doc/specs/<spec>.yaml`) are deliverables and ship in the squash; only the plan is stripped. `/skill:finishing-a-development-branch` strips the plan, then seals and commits the record before landing. Explicit trivial one-off edits outside this flow need no worktree.
 
@@ -86,6 +87,8 @@ If any test fails, offer no split. Never split by service, package, repo, layer,
 
 ### 3. Understand the idea
 
+Clarify freely.
+
 `Read` the gathered draft unconditionally before question one. Treat it as a helper, not a fence: verify load-bearing claims from primary code, and confirm whether the codebase or ecosystem already solves the problem.
 
 Ask one question per message, about purpose, constraints, success, and affected actors. Every questionary question offers 2-4 labeled options (`A)`, `B)`, ...), each a different outcome, and ends `Recommendation: <letter> - <why>`; when more outcomes are plausible, the last option is `other - name it` or the question splits in two. This format overrides chat-style rules in `AGENTS.md` (one paragraph, no Options/Recommendation layout). A decision that would be a yes/no or "may I" question is not asked: make it, state it as an assumption in the message that carries the next question or the premise note, and record it in the draft. Before asking, check code, docs, and tracker: look up current-state facts (dispatch a subagent when costly); adopt a ticket-recorded decision and cite the ticket, asking it only when a cited code or API contradiction, or conflicting recorded outcomes, prevents adopting it. Other approvals retain their wording.
@@ -107,37 +110,11 @@ Prefer clear testable boundaries, YAGNI, existing conventions, the owning schema
 
 ### 6. Present the design in two rounds
 
-Use two rounds, targeting 300-500 words each, with one approval each; revisions remain within that approval point. Ask once per round; round-1 approval without correction confirms the predecessor. Round 1 covers architecture, responsibilities, data flow, and `supersedes <path>, <scope>` when applicable. Round 2 covers errors, edges, tests, and `## Documentation impact`. In round 2, cite the draft's `Docs touched:` entries as candidates for "Materially amended existing docs"; admit or drop each by the materiality bar in `reference/documentation-impact.md`, never list them automatically.
-
-`## Documentation impact` is required. Cite `reference/documentation-impact.md` by relative path, do not restate its categories, and reproduce this template verbatim:
-
-  ```markdown
-  ## Documentation impact
-  - Feature / user-facing docs introduced: <list, or "none">
-  - Materially amended existing docs: <list, or "none">
-  - Derived / memory docs invalidated: <routers / AGENTS.md sections / topic guides / indexes, or "none">
-  ```
-
-Use doc names, `none`, or `deferred: <trigger>`. Apply `reference/documentation-impact.md`; amend the existing owner; create a standalone file only where no doc owns the topic. Put project taxonomy in the overrides file's `## documentation` block (guidance only; no settings key). Doc updates ship in the same commit as the code and the conformance gate verifies them against the spec. Clarify when needed.
+Use two rounds, targeting 300-500 words each, with one approval each; revisions remain within that approval point. Ask once per round; round-1 approval without correction confirms the predecessor. Round 1 covers architecture, responsibilities, data flow, and `supersedes <path>, <scope>` when applicable. Round 2 covers errors, edges, tests, and `## Documentation impact`. In round 2, read and apply [Documentation impact](reference/documentation-impact.md), including its verbatim template; cite that portable relative path in the spec; do not restate its categories. Ask the user when doc impact is unclear. Unreadable -> stop the step with a blocking error. Cite the draft's `Docs touched:` entries as candidates for "Materially amended existing docs"; admit or drop each by that owner's materiality bar, never list them automatically.
 
 ## Ticket Handling
 
-A ticket is guidance, not sole truth. Fetch it; propose scope, approach, or acceptance changes when code disagrees, and record deviations in the spec. Implied requirements in the ticket body (Context, Problem, Idea) land in the spec body as any other requirement; the ticket's explicit acceptance criteria land verbatim in the section below.
-
-**Extract the ticket's ACs.** When the ticket body has a heading matching `/acceptance criteria/i`, every list item under it until the next heading is an AC (numbered, bullet, or checkbox) and no other list in the body is. When there is no such heading, every top-level checkbox row in the body is an AC, except rows under a `Post-deployment housekeeping`, `Out of scope`, or `Follow-up` heading. Otherwise the ticket has no ACs. A nested list under an AC row rides with its parent as one row; an AC heading holding prose and no list makes each paragraph one row. Carry checked and unchecked rows alike, all written `- [ ]`. Take the rows from the gather draft's `## Ticket acceptance criteria (verbatim)` heading; when the ticket was not fetched, the gate summary shows the `none` line so the user can paste the rows, which then become rows.
-
-**Write the section in every spec**, after `## Problem`:
-
-```markdown
-## Acceptance criteria
-
-Ticket <ref>, <heading or "checkbox list">, rows verbatim:
-
-- [ ] <row text copied verbatim>
-  <disposition>
-```
-
-The heading `## Acceptance criteria` names the ticket contract only; the spec's own requirements stay in Design. Disposition is exactly one of `in-scope`, `deviates: <why>`, `deferred: <where>`, `venue: <env> - <observation>`; default `in-scope`. Never edit the row text: a wrongly stated row is `deviates: <why>`, an ambiguous row stays `in-scope` with the chosen reading written as a Design clause. Name a `venue:` row's enabling change in Design. An `in-scope` row is a requirement as written; disposition reasons are never normative for the plan or the reviewer, so a `deviates:` reason that adopts part of a row restates that part as a Design clause. Defer a row only when the shipped change operates without it - cost is never a reason; a hard but direct AC stays `in-scope` and ships. Ask a `deviates:`/`deferred:` decision only when it changes what the user observes once the change ships, offering the dispositions themselves as the options (`A) in-scope B) deviates: <why> C) deferred: <where>`); a deviation caused by a workflow artifact (spec, plan, changelog, telemetry file) or a moved path is stated in the disposition, not asked. Name every disposition in the gate summary; `venue:` states where the observation can happen and is not a scope decision. A disposition changes in any later phase - a reviewer finding `recommended: rescope` at the finish gate, a wrong row noticed mid-implementation, or a ticket edited after approval when the user asks - through [Amending an approved spec](#amending-an-approved-spec) (`reference/amendment-surface.md`); the row text still never changes. With no ticket, or a ticket without ACs, the section body is the single line `none - no ticket`, `none - ticket has no acceptance criteria`, or `none - ticket not fetched (<reason>)`. Never author acceptance criteria on the ticket's behalf; that is `/skill:shape-ticket`'s job.
+Read [Ticket Handling](reference/ticket-acceptance.md) before gathering context or step-4/8 entry, even with no ticket; unreadable -> stop with a blocking error, never reconstruct from memory.
 
 ## First-Feature Oversight (Early Project Stages)
 
@@ -145,7 +122,7 @@ For the first two features of a new module, long-lived component, schema area, o
 
 ## Anti-Pattern: "Too simple to need a design"
 
-Shared schemas, contracts, and invariants require a spec. If work is mechanical and contained, such as a rename, formatting, or dependency bump, say so explicitly and skip brainstorming; otherwise spec first.
+Inside an opted-in flow, shared schemas, contracts, and invariants require a spec. If work is mechanical and contained, such as a rename, formatting, or dependency bump, say so explicitly and skip brainstorming; otherwise spec first within that flow.
 
 ## Filename Convention
 
@@ -155,130 +132,15 @@ Mint the slug once during gather and reuse it. If questionary invalidates it, wr
 
 ## 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.
-4. **After the line-1 check**, run the second predecessor pass. Compose a query from
-   the spec's H1 terms, then the terms of every H2 that is not a template heading
-   (Problem, Acceptance criteria, Design, Errors and edge cases, Tests, Documentation
-   impact, Out of scope, Open questions), then the `**Goal:**` line's terms - same
-   token rules as the scout, deduplicated, cut at 15. Run
-   `(cd <abs worktree path> && node <SPEC_INDEX> --query '<terms>' --limit 5 --exclude <spec path relative to the worktree>)`
-   with `<SPEC_INDEX>` resolved as in `gatherer.md`. Take the `live` rows and drop every
-   path the draft's `Predecessor:` line(s) named (retained from the step-1 read). Carry
-   the remainder to the gate as one adjacent line:
-   `New predecessor candidates at spec-writing: <path> (<title>), ... - index rows are a hint; code is the source and an absent row proves nothing.`
-   or `New predecessor candidates at spec-writing: none.` A non-zero exit degrades to
-   `Second predecessor pass unavailable: <first stderr line>`; it never blocks the gate
-   or the commit. "yes, <path> is a predecessor" at the gate is a change request that
-   adds the `supersedes <path>, <scope>` clause and the banner, then re-presents the gate.
-5. **After the second predecessor pass and before the inline lint**, `edit` any known
-   predecessor spec to insert its supersession banner (see
-   [Marking superseded specs](reference/superseding.md)). This position is fixed:
-   the banner is written after any slug rename, so it always cites the final path.
-
-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.
-
-- **Placeholder scan.** Any `TODO`, `TBD`, `<fill in>`, `[example]`, `xxx`? Either resolve them or convert to explicit "Open Questions" with names.
-- **Internal consistency.** Does Section 4 contradict Section 2? Are component names and field names consistent throughout? If the spec replaces a prior design, confirm the predecessor carries the supersession banner and its href resolves to this spec's final filename.
-- **Documentation named.** Does the spec name all three classes (feature/user-facing introduced; materially amended; derived/memory invalidated), or an explicit "none" for each? Enforce the materiality bar in `reference/documentation-impact.md` without restating it: each listed doc names the category it clears, none is a code-mirror, amend-over-create was applied, and skill/agent bodies are implementation surface, not doc-impact entries here.
-- **Ticket contract present.** Does `## Acceptance criteria` exist with either verbatim ticket rows plus dispositions or one `none - <reason>` line? Presence is enforced here, at authoring, and nowhere later.
-- **Scope check.** Does every paragraph serve the goal? Cut filler. If something is out of scope, say it's out of scope.
-- **Ambiguity check.** Is every "we should…" backed by a concrete decision? Replace "we could probably" with "we will" or "we won't".
-
-The first four are the inline **lint**: run them here and fix what they surface. The last two are the **critique pass**, dispatched per [Spec Council](#spec-council-optional). After it returns, re-run the placeholder scan over the applied spec; if a predecessor banner exists, confirm its `<scope>` still matches and reconcile it; carry any ambiguity the critique could not resolve to the [User Review Gate](#user-review-gate).
-
-## Spec Council (Optional)
-
-Before dispatching the worker below, resolve `reference/documentation-impact.md` relative to this loaded skill as one absolute `<DOCUMENTATION_IMPACT_GUIDELINE>` path value. Pass that value in the worker task; do not add it to the spec.
-
-After the inline lint and before the user review gate, **brainstorming owns the critique-pass gate**; council **apply mechanics** live in `/skill:roasting-the-spec` (single source of truth - link, don't restate). Resolve the council with `gauntlet_setting({ key: "specCouncil" })` - the tool returns the merged (repo-over-preset) value as `{ verdict, members, chair, malformed, warning, errors }`. **Do not** hand-roll a settings read. When `verdict` is `"council"`, the council *is* the critique pass - invoke `/skill:roasting-the-spec` automatically (no offer, no prompt), passing `members`/`chair`; also pass the verbatim human input (the original prompt, any ticket AC snapshot - the raw rows under the gather draft's `## Ticket acceptance criteria (verbatim)` heading, never the spec's section, which holds the author's dispositions - and the questionary answers that changed scope) - roasting-the-spec forwards it to members and chair as the `Human input (verbatim; off-limits for over-spec)` block; it applies its apply-set and returns the audit (Applied/Deferred/Rejected). When `verdict` is `"worker"`, dispatch the worker below. If `malformed` is true or `errors` is non-empty, emit the `warning`/error as one line, then branch strictly on `verdict` - `malformed` can accompany *either* verdict (e.g. a bad `chair` with valid `members` still returns `council`), so never infer the worker path from `malformed` alone. If `gauntlet_setting` is unavailable, stop and report - never fall back to a manual bash/JSON settings merge. The already-applied council edits (or the worker's in-place fixes) ride in the same worktree commit. The conceptual precedence rule lives in `verification-before-completion/reference/settings-precedence.md`.
-
-When `verdict` is `"worker"`, dispatch one fresh `worker` that applies the scope + ambiguity checks and fixes them in place:
-
-```
-subagent({ agent: "worker", context: "fresh", async: false, cwd: "<abs worktree path, from the using-git-worktrees Step 4 report>", task:
-  "Problem statement: <the problem the spec addresses + the user's stated intent>.\n" +
-  "Read the spec at <abs path to doc/specs/...>. Edit ONLY that file.\n" +
-  "The portable citation `reference/documentation-impact.md` in the spec is the pi-gauntlet guideline at <DOCUMENTATION_IMPACT_GUIDELINE>, not a consumer doc; do not flag it as an external reference, and preserve it - never remove it as redundant or replace it with the resolved absolute path.\n" +
-  "Apply two checks and fix what you find in place: (1) Scope — does every paragraph serve the goal? Cut filler;\n" +
-  "state out-of-scope explicitly. (2) Ambiguity — is every 'we should' a concrete decision?\n" +
-  "Replace 'we could probably' with 'we will'/'we won't'. Also inline any load-bearing\n" +
-  "external reference (ticket AC, commit SHA, doc) already given to you in the problem\n" +
-  "statement above; if the spec relies on one not provided here, flag it (do NOT fetch) in\n" +
-  "your summary. Return a summary of what you changed, and flag any ambiguity you could NOT\n" +
-  "safely resolve." })
-```
-
-`worker`'s model resolves from `subagents.agentOverrides.worker.model` in `settings.json` (unset → inherits the main loop); the dispatch passes no `model:`.
-
-## User Review Gate
-
-After self-review and the critique pass (council or worker, both already applied to the spec - see [Spec Council](#spec-council-optional)), dispatch the spec-only summarizer over the **applied** spec, then commit the spec on the worktree branch and stop. The summary is folded into the one human gate, not a new gate.
-
-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`):
+Read [Spec Self-Review](reference/spec-finalization.md#spec-self-review-before-user-review-gate) before spec-writing or restored step 8; unreadable -> stop with a blocking error, never reconstruct from memory.
 
-```bash
-SUMMARY_PATH=$(mktemp "${TMPDIR:-/tmp}/gauntlet-spec-summary.XXXXXX")   # absolute, portable across GNU/BSD mktemp
-```
+## Spec Council
 
-```
-subagent({ agent: "spec-summarizer", context: "fresh", async: false, cwd: "<abs worktree path, from the using-git-worktrees Step 4 report>",
-  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." })
-```
+Follow [Spec Council](reference/spec-finalization.md#spec-council) for the mandatory critique pass.
 
-`<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 — staging any predecessor spec edited per [Marking superseded specs](reference/superseding.md) alongside it; a change request at the gate that renames, materially revises, or drops the spec also reconciles the predecessor's banner before recommitting. This commit is **unconditional**: the summary is only a gate aid, so a degraded or missing summary never blocks it. If the council path ran, include its audit (`Coverage:` when present, then `Applied:` / `Deferred:` / `Rejected:`, verbatim from `/skill:roasting-the-spec`'s return) in the **commit message body** - this is the durable, non-contractual record a finish-time revert reads back; the audit is never a committed spec section. 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).
-
-Paste the summary verbatim, unedited in the template below; use adjacent lines for the audit, unresolved ambiguities, and every gap-footer entry:
-
-```
-<spec-only summary read back from the temp file — pasted verbatim, unedited>
-
-Spec written and committed to <project>/doc/specs/<filename>.md (worktree: <path>).
-
-Coverage: <N> of <M> members reported; <slug>: <reason> (line present only when coverage was partial)
-Applied: [<severity>] <cluster> — raised-by: [<slugs>] -> <edit>
-Deferred: [<severity>] <cluster> — raised-by: [<slugs>] -> <where it belongs>
-Rejected: [<severity>] <cluster> — raised-by: [<slugs>] -> <one-line reason>
-(one line per item, exactly as returned by roasting-the-spec - `Applied: none` / `Deferred: none` / `Rejected: none` when a list is empty; omit the audit lines when the worker path ran, not the council)
-
-<unresolved ambiguities; every gap-footer entry from the summary>
-New predecessor candidates at spec-writing: <path> (<title>), ... - index rows are a hint; code is the source and an absent row proves nothing.
-
-Please review. Approve to proceed, tell me what to change in the spec, or say "revert applied council edit <X>" to undo a specific applied edit. Reply "auto-apply amends" - every later amend-class change in this flow then applies without review, scope changes included; redraws and the spec gate still stop. "approve, auto-apply amends" does both.
-```
-
-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.
-
-**Revert valve.** "Revert applied council edit X" is a normal change request: revise the spec to undo edit X, re-dispatch the summarizer with a **fresh** temp path (per the re-dispatch rule below), and re-present the gate. This is cheap here - the spec is not yet plan- or code-bearing.
-
-Wait for the user. On a change request (including a revert), 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 (a grant given at or before approval - "approve, auto-apply amends", or a standalone "auto-apply amends" reply earlier at this gate - is first quoted in the spec commit body via `git -C <abs worktree path> commit --amend --no-edit -q --trailer "Amend-grant: <the sentence>"`, so the worktree history shows when the grant began) — 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.
-
-Post-approval changes follow [Amending an approved spec](#amending-an-approved-spec).
-
-After approval, mark the brainstorm phase complete:
+## User Review Gate
 
-```
-phase_tracker({ action: "complete", phase: "brainstorm" })
-```
+Follow [User Review Gate](reference/spec-finalization.md#user-review-gate) for summary, commit, approval, and automatic planning.
 
 ## Amending an approved spec
 
@@ -286,20 +148,16 @@ Execute in place from any later phase; never invoke `/skill:brainstorming` for i
 
 Classify first. Redraw test: the change alters the problem statement, adds or removes a component, or moves a component boundary -> redraw. A change inside one component (a persistence mechanism, a worker's HTTP client, dropping a fallback and its task) -> amend. State the call; the user overrides either way.
 
-Amend -> load `reference/amendment-surface.md` and follow it (unreadable -> stop with a blocking error; never improvise the grammar): it holds items unapplied, reviews them with a fresh `spec-council-member`, renders one readable batch for escalations, applies accepted items, runs the plan/tracker aftermath, and commits once. A user instruction in this flow that waives per-diff review for later amends ("auto-apply amends", "auto-apply amends, stop only for redraws", "apply spec fixes without asking") skips the review; it never satisfies the spec gate, and a new brainstorm or a fresh-session resume starts with no grant. Redraws always stop.
+Amend -> load `reference/amendment-surface.md` and follow it (unreadable -> stop with a blocking error; never improvise the grammar). Apply its [Standing grants](reference/amendment-surface.md#standing-grants) boundaries.
 
 Redraw: keep the worktree and the approved spec file. `plan_tracker({ action: "clear" })`, `phase_tracker({ action: "reset" })`, `phase_tracker({ action: "start", phase: "brainstorm" })`, delete the plan file, resume at checklist step 4 with the approved spec as the draft (steps 2-3 skipped). Spec-writing overwrites it; the full gate follows.
 
-## Key Principles
-
-One question at a time, YAGNI, 2-3 approaches, two design rounds, clarify freely - all owned by [The Process](#the-process).
-
 ## Red Flags — STOP
 
 - Writes outside the resolved spec dirs ([owner](#hard-constraint)).
 - Draft overwrite without the same-turn full read, or overwrite via `edit` ([owner](#spec-self-review-before-user-review-gate)).
 - Dispatch while line 1 is the context-draft marker ([owner](#spec-self-review-before-user-review-gate)).
-- Inline scope or ambiguity checks ([owner](#spec-council-optional)).
+- Inline scope or ambiguity checks ([owner](#spec-council)).
 - Gate after failed/skipped critique or before placeholder re-scan ([owner](#spec-self-review-before-user-review-gate)).
 - Gate without summary `Read` last, or with a paraphrased summary ([owner](#user-review-gate)).
 - Human stop between gather and question one ([owner](gatherer.md)).

package/skills/brainstorming/gatherer.md

@@ -36,8 +36,9 @@ Absolute `output:` paths are mandatory: relative paths in parallel mode resolve
 against the worktree and would get committed.
 
 `<SPEC_INDEX>` is `<directory of this skill's SKILL.md>/../../bin/gauntlet-spec-index.mjs`,
-resolved to an absolute path by the main loop from the skill's `<location>` in the system prompt
-before pasting the task.
+resolved to an absolute path by the main loop from the loaded brainstorming `SKILL.md` path
+in the command's skill envelope or the absolute path used to read it, before pasting the task.
+Use that SKILL.md directory, never `reference/` as the base.
 
 ## Task templates
 

package/skills/brainstorming/reference/amendment-surface.md

@@ -1,6 +1,12 @@
 # Amendment surface
 
-Loaded by `skills/brainstorming/SKILL.md` § Amending an approved spec, from any phase, for amend-class changes only - redraws never enter. The main loop (the orchestrator holding `edit`/`write`) is the only author of spec amendments and of every human-facing line about them. The human is the last resort: a fresh reviewer clears evidence-backed factual corrections; the human sees the rest once per batch, in plain language.
+Load from `skills/brainstorming/SKILL.md` § Amending an approved spec, from any phase, for amend-class changes; at approval, load only [Standing grants](#standing-grants), not the batch procedure. Keep redraws outside this procedure. Only the main loop holding `edit`/`write` authors amendments and human-facing amendment text. Use the human last: a fresh reviewer clears evidence-backed factual corrections; present the rest to the human once per batch plainly.
+
+## Standing grants
+
+Honor a user sentence in this flow that waives per-diff review for later amends (`auto-apply amends`, `approve, auto-apply amends` at the spec gate, `auto-apply amends, stop only for redraws`, `apply spec fixes without asking`, or the same intent in other words). Apply every later amend-class change without review, scope changes included; redraws always stop and the grant never satisfies the spec gate. Start a new brainstorm or a fresh-session resume with no grant; never infer one from history.
+
+Before proceeding to planning, quote a grant given at or before spec approval in the spec commit body via `git -C <abs worktree path> commit --amend --no-edit -q --trailer "Amend-grant: <the sentence>"`, so the worktree history shows when the grant began.
 
 ## 1. Prepare - never apply yet
 
@@ -18,9 +24,9 @@ Collect every amendment pending at this decision point (same spec-review round,
 | `recommended` | `accept` or `alt-n` |
 | `alternatives` | genuinely different spec edits, zero or more |
 
-The working tree stays at pre-batch HEAD until apply (section 5) - nothing is edited before the reviewer and, where needed, the human have answered. A redraw item stops alone first (`SKILL.md` redraw path); amend items are held and re-batched after it resolves.
+The working tree stays at pre-batch HEAD until apply (section 5) - nothing is edited before the reviewer and, where needed, the human have answered. A redraw item stops alone first (`../SKILL.md` redraw path); amend items are held and re-batched after it resolves.
 
-**Standing grant active** (`v5.10.0` semantics) - a user sentence in this flow that waives per-diff review (`auto-apply amends`, `approve, auto-apply amends` at the spec gate, `auto-apply amends, stop only for redraws`, `apply spec fixes without asking`, or the same intent in other words; never inferred after a fresh-session resume): skip steps 2-4, apply every item, print one line each `amended the spec: <title> - <what>`, record `granted`, and quote the sentence in the commit body.
+**Standing grant active** ([boundaries](#standing-grants)): skip steps 2-4, apply every item, print one line each `amended the spec: <title> - <what>`, record `granted`, and quote the sentence in the commit body.
 
 ## 2. Prefilter - no model call
 

package/skills/brainstorming/reference/documentation-impact.md

@@ -116,11 +116,13 @@ Each entry answers with a doc name, `"none"`, or `"deferred: <trigger>"` (for
 example, `CHANGELOG.md - deferred: release`, when a doc changes on a known
 later event and should not be flagged as missing before that event fires).
 
+Doc updates ship in the same commit as the code and the conformance gate verifies them against the spec.
+
 ## Referenced by
 
 Keep this list in sync with the skills that cite this doc:
 
-- `brainstorming` section 6, its Spec Self-Review check, and its worker dispatch context.
+- `brainstorming` section 6 and `brainstorming/reference/spec-finalization.md` self-review and worker dispatch context.
 - `roasting-the-spec` member and chair dispatch context.
 - `brainstorming/reference/amendment-surface.md` amendment-review dispatch context.
 - `writing-plans` - sources doc-update tasks from the spec's Documentation
@@ -134,4 +136,4 @@ Keep this list in sync with the skills that cite this doc:
 This doc is generic. Project-specific doc taxonomy (which docs a given
 project treats as canonical for which topic) lives in the gauntlet
 overrides file (see Project overrides in `brainstorming/SKILL.md`), in a
-`## documentation` section - not here.
+`## documentation` section (guidance only; no settings key) - not here.