pi-gauntlet 5.9.1 → 5.10.0

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## v5.10.0 - 2026-09-18
+
+- Council provenance: member findings (except `over-spec`) end with `probed: <source or check> - <result> | none`; the chair tags each suggested edit `grounded:` or `hypothesis:` (`external-ref:` and `over-spec:` clusters stay untagged); `roasting-the-spec` probes `hypothesis` data-shape claims once (bounded, read-only, artifact at hand) before applying, else lands them as one grouped Open Question per artifact; `Applied:` audit lines carry the probe.
+- Standing amend approval: a chat instruction that waives per-diff review ("auto-apply amends, stop only for redraws") lets brainstorming's amendment step render the diff and continue; redraws and the spec gate still stop; the grant is quoted in each amendment commit body. Limitation: back-to-back amendments with no user input between them count as one in telemetry `derived.amendments` (coalesced until the next input event).
+- `skills/brainstorming/SKILL.md` states each rule once; Checklist and all 12 Red Flags link to owning sections, with no gate, step, red flag, or dispatch field removed.
+- CI pins the new persona and skill tokens.
+
 ## v5.9.1 - 2026-09-17
 
 - Process in primary, work by path: `plan_check` roots at the plan's checkout, settings load from the session cwd's checkout toplevel, the branch-switch guard evaluates the command's `-C`/`cd` target, telemetry commits on the spec's checkout, and ship detection accepts `git -C <worktree> push` / `merge --squash`. Stage skills carry the worktree path as a value (dispatch `cwd`, `git -C`, subshell) - a new CI lint keeps them that way; `finishing-a-development-branch` takes `<worktree-path>` as a mandatory argument. Requires git >= 2.31. ([#37](https://github.com/jjuraszek/pi-gauntlet/issues/37))

package/README.md

@@ -63,7 +63,7 @@ flowchart LR
 
 <!-- TODO GIF: a real gauntlet run end to end -->
 
-Everything between gate 1 and gate 2 - task breakdown, implementation, both review passes - runs without you in the loop. Changing an approved spec later is a conditional diff-approval stop (brainstorming's `Amending an approved spec`), not a third numbered gate. That's the mechanism. What follows is the machinery behind it.
+Everything between gate 1 and gate 2 - task breakdown, implementation, both review passes - runs without you in the loop. Changing an approved spec later is a conditional diff-approval stop (brainstorming's `Amending an approved spec`) - or, under a standing grant, a diff render that continues - not a third numbered gate. That's the mechanism. What follows is the machinery behind it.
 
 ## Architecture
 

package/agents/spec-council-member.md

@@ -16,7 +16,7 @@ You receive a problem statement and the artifact under review, as defined by you
 
 You are read-only: you never modify the repository or any input artifact; your only write is your findings file at the dispatched output path.
 
-When your dispatching task asks for codebase verification, verify - do not trust assertions about existing files, APIs, or conventions - but bounded: prefer `rg` (it respects `.gitignore`) over recursive `grep`, use `rg`-native bounds (`--max-count`, explicit paths); scope every scan to explicit paths, never a repository root; bound each scan with `timeout` (or `gtimeout`) when available, and do not run it unbounded when neither exists. A scan that times out or cannot be bounded is reported as unverified - never retried broader.
+When your dispatching task asks for codebase verification, verify - do not trust assertions about existing files, APIs, or conventions - but bounded: prefer `rg` (it respects `.gitignore`) over recursive `grep`, use `rg`-native bounds (`--max-count`, explicit paths); scope every scan to explicit paths, never a repository root; bound each scan with `timeout` (or `gtimeout`) when available, and do not run it unbounded when neither exists. A scan that times out or cannot be bounded is reported as unverified - never retried broader. End every finding with `probed:`; `none` is a normal answer.
 
 Assess the spec on five axes:
 
@@ -43,12 +43,14 @@ Emit exactly this markdown and nothing else:
 verdict: sound | needs-work | unsound
 addresses-problem: yes | partial | no — <why>
 findings:
-- [blocker|major|minor] <kind> @ <section or quote> — <problem> → <suggested edit>
+- [blocker|major|minor] <kind> @ <section or quote> — <problem> → <suggested edit> — probed: <source or check> - <observed result> | none
 lean: nothing to cut | <N> over-spec findings above
 ```
 
 `<kind>` is one of: gap, oversimplification, ambiguity, scope, not-actionable, external-ref, other, over-spec. `scope` = too little or the wrong problem. `over-spec` = too much. No findings -> keep the `findings:` header, no bullets. `lean:` is always the last line; `<N>` = number of `over-spec` bullets. `lean: nothing to cut` is a normal answer.
 
+`probed:` names what you read or ran and what it showed (`probed: rg 'source IN' migrations/ - CHECK lists 3 values`); `probed: none` when the edit rests on the spec text alone. The `over-spec` bullet form below carries no `probed:`.
+
 **`over-spec`.** Flag a clause only when all three are true:
 
 1. It is clearly outside the stated problem.

package/agents/spec-council-synthesizer.md

@@ -30,13 +30,15 @@ Emit exactly this markdown and nothing else:
 consensus: <one-line overall verdict, e.g. needs-work — 2 of 3 members flagged blockers>
 lean: <k> of <n> members found nothing to cut
 clusters:
-- [blocker|major|minor] <theme> — raised-by: [<model>, <model>] — <consolidated finding> → <suggested edit>
+- [blocker|major|minor] <theme> — raised-by: [<model>, <model>] — <consolidated finding> → grounded|hypothesis: <suggested edit>
 resolved:
 - <contested point> → sided with <position> (<one-clause why>)
 ```
 
 Every cluster must be pre-resolved — never emit a raw "members disagree" item. Leave `resolved` as a header with no bullets if no members conflicted.
 
+Tag every suggested edit: `grounded:` when the raising members' `probed:` results support every factual assertion the edit makes; otherwise `hypothesis:`. A missing `probed:` reads as `none`. Never probe to upgrade a label - the tag records what members checked, not what you could check. `external-ref:` and `over-spec:` clusters carry no tag.
+
 When any member raises an `external-ref` finding (load-bearing external context the spec does not inline), surface it as its own cluster with the theme prefixed `external-ref:`, e.g. `- [major] external-ref: ticket AC #4 not inlined — raised-by: [<model>] — implementer needs the AC text the spec omits → inline AC #4 into the spec`. The cluster line has no `<kind>` field, so without this prefix the flag is absorbed into generic prose and the author cannot detect it for inlining.
 
 `over-spec` findings get their own cluster, theme prefixed `over-spec:` (the author branches on that prefix, as with `external-ref:`). Rules:

package/package.json

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

@@ -15,38 +15,23 @@ Identify the target project → set up an isolated worktree → understand curre
 
 ## HARD CONSTRAINT
 
-While this skill is active, do **not** take any implementation action until you have presented a design and the user has approved it. This applies to **every** change regardless of perceived simplicity. An implementation-heavy request ("test it end-to-end", "push a request to rabbit", "run the service") does not lift this gate — it just tells you what the spec must cover.
+Do **not** implement until the design is presented and approved, regardless of simplicity. Implementation-heavy requests define spec scope; they do not lift this gate.
 
-You **may**:
+You **may** read code/docs, run the existing system to observe current behavior, write under `doc/specs/`, and `edit` a predecessor spec there to add a [supersession banner](reference/superseding.md).
 
-- Read code and docs
-- Run the existing system to observe its **current** behaviour — this is research and feeds the spec (boot a local service, replay a sample request, capture a baseline classification, etc.)
-- Write to the project's `doc/specs/` directory
-- `edit` a predecessor spec in the project's spec directory to add a supersession banner (see [Marking superseded specs](reference/superseding.md)) — the `edit` prohibition at spec-writing binds the spec being written, not a predecessor file
+You may **not** write outside `doc/specs/`; build, deploy, validate, or exercise the proposed change; run implementation skills; commit the spec on `main`; or start `/skill:writing-plans`.
 
-You may **not**:
-
-- Write or edit code outside `doc/specs/`
-- Scaffold a project, or take any action that builds, deploys, or validates the **proposed change** — running new/edited code, exercising behaviour that doesn't exist yet, or "testing the fix" before there is one
-- Run implementation skills (`/skill:test-driven-development`, `/skill:subagent-driven-development`, etc.)
-- Commit the spec directly on `main` in the primary checkout — it must land inside the worktree (see [Worktree First](#worktree-first))
-- Start writing the plan (that's `/skill:writing-plans` — separate phase)
-
-The line: exercising the system **as it is today** is research; exercising the **change you're proposing** is implementation and waits for the gate.
-
-This skill ends with a **written, user-reviewed spec inside a worktree**. Nothing else.
+The line: current-system observation is research; exercising the proposed change waits for approval.
 
 ## Foreground dispatch policy
 
-Flow-owned execution dispatches run in the foreground: set top-level `async: false` on gather, critique, council, summary, implementation, review, conformance, and retry calls. `forceTopLevelAsync` must remain unset or false; it is incompatible with this flow. See [pi-cohort dispatch configuration](https://github.com/jjuraszek/pi-cohort/blob/main/doc/configuration.md). If a dispatch returns an async handle despite `async: false`, stop and report the configuration error: do not poll it, relaunch work, or advance the flow. A child that detached from the foreground run is likewise incomplete work; use the existing coordination path and never accept or duplicate it.
-
-Foreground does not serialize independent work: preserve existing isolated parallel `tasks` batches and await their terminal results before acceptance or tracker/phase advancement.
+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.
 
 ## 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, setting up the worktree, or answering the user, reset **both** trackers and then start the phase. A new brainstorm is a new flow, so it owns a clean slate — clear any stale phases *and* tasks left in the session by earlier work:
+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):
 
    ```
    phase_tracker({ action: "reset" })   // clears all phases
@@ -54,149 +39,74 @@ Work through the items below **in order**. This is your own checklist to follow,
    phase_tracker({ action: "start", phase: "brainstorm" })
    ```
 
-   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. **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;
-   then state the chat premise note (section 3) before approaches
-5. **Propose 2-3 approaches** — with trade-offs and a recommendation
-6. **Present the design** — in two rounds, one approval each
-7. **Write the spec** — to `doc/specs/` (see [Filename Convention](#filename-convention)); then mark any known superseded predecessor(s) per [Marking superseded specs](reference/superseding.md), at the exact-order position defined in [Spec Self-Review](#spec-self-review-before-user-review-gate)
-8. **Spec self-review (lint)** — placeholder scan + internal consistency + documentation named, run inline
-9. **Critique pass (auto-dispatched)** — scope + ambiguity; the spec council via `/skill:roasting-the-spec` when `gauntlet_setting` returns verdict `council` (it applies its apply-set, including any external-ref inlining, to the spec before returning — see [Spec Council](#spec-council-optional)), else a fresh `worker` that applies its own fixes in place
-10. **Re-run placeholder scan** — after the critique pass returns, re-scan the **applied** spec for placeholders its edits may have introduced; if a predecessor banner exists, confirm its `<scope>` still matches the applied spec (critique edits can change what is superseded); surface any ambiguity the critique could not safely resolve at the user gate
-11. **Generate spec summary** — dispatch a fresh, spec-only `spec-summarizer` over the **final (post-apply)** spec, writing to an absolute temp-dir path via `outputMode: "file-only"`, then `Read` that file back as the **last content-producing** tool call before composing the gate and render its contents **verbatim** at the top of the gate message — do not paraphrase, condense, re-section, or rewrite it (see [User Review Gate](#user-review-gate)); this is part of the existing gate, not a new one
-12. **User review gate** — user reviews the applied spec's verbatim summary plus the council audit (Applied/Deferred/Rejected), with a revert valve for any applied council edit
-13. **Transition** — only after approval, invoke `/skill:writing-plans`
+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).
+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-4.
+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).
+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).
+13. **Transition** - after approval, invoke `/skill:writing-plans` per [User Review Gate](#user-review-gate).
 
 ## Project Routing
 
-Before brainstorming, identify the target project. The match drives the spec directory, AGENTS.md to read, and verification commands.
+Identify the target project before brainstorming; this determines the spec directory, instructions, and verification commands. Read top-level and relevant service `AGENTS.md`; follow documented routing, otherwise use repository conventions.
 
-Read the repo's top-level `AGENTS.md` (already in pi's context) and any service-level `AGENTS.md` for the area the user mentioned. If the project documents a routing table mapping subprojects to spec directories and verification commands, follow it. Otherwise rely on the conventions you find.
-
-Detection order:
-
-1. Issue tracker reference (Linear, Jira, GitHub Issues) → infer from labels, description, or mentioned file paths
-2. cwd inside a service / package directory → use that area
-3. Unclear → ask the developer
-
-If the project's `AGENTS.md` calls out additional reading for a specific area (e.g. a TDD workflow doc), read it before brainstorming work in that area.
+Detection order: (1) infer from ticket labels, description, or paths; (2) use the service/package containing cwd; (3) ask if unclear. Read any area-specific material required by `AGENTS.md` before brainstorming.
 
 ## Worktree First
 
-The spec is the **first commit in a dedicated worktree**, not a separate commit on `main`. Before drafting any spec content:
-
-1. Invoke `/skill:using-git-worktrees`. Worktrees live under `.worktrees/` at the repo root, or wherever a project-native worktree script places them.
-2. Carry the worktree path from the `using-git-worktrees` Step 4 report (`Worktree ready at <full-path>`) as a value: the spec path is `<full-path>/doc/specs/<filename>.md`, every dispatch below sets `cwd: "<full-path>"`, and git runs as `git -C <full-path> ...`. The process cwd stays where pi was launched.
-3. Write the spec at that path, run self-review, commit with `git -C <full-path>`, hand off.
+The spec is the first commit in a dedicated worktree, never a separate commit on `main`.
 
-Spec doc, plan doc, and implementation are all developed in the same worktree; the squash ships the spec and the implementation, with the ephemeral plan stripped before landing (see `/skill:finishing-a-development-branch`).
+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>/doc/specs/<filename>.md`; every dispatch uses that `cwd`; git uses `git -C <full-path>`. Keep the process cwd unchanged.
+3. Write, review, and commit there.
 
-**Exception:** trivial one-off edits the user explicitly asks for outside this skill flow (e.g. "fix this typo") do not require a worktree.
+Spec, plan, and implementation share this worktree; finishing strips the ephemeral plan before squash. Explicit trivial one-off edits outside this flow need no worktree.
 
 ## The Process
 
 ### 1. Check git state
 
-Check git state in the primary checkout (the process cwd; no worktree exists yet):
-
-```bash
-git status
-git --no-pager log --oneline -5
-```
-
-If on a feature branch with uncommitted or unmerged work, ask:
-
-> "You're on `<branch>` with uncommitted changes. Want to finish/merge that first, stash it, or continue here?"
-
-Require one of: finish prior work, stash, or explicit "continue here". If the topic is new, set up the worktree per [Worktree First](#worktree-first) before continuing.
+In the primary checkout run `git status` and `git --no-pager log --oneline -5`. On a feature branch with uncommitted or unmerged work, ask whether to finish/merge, stash, or continue; require one choice. For a new topic, create the worktree before continuing.
 
 ### 2. Scope check
 
-One spec is the default. If the request looks like multiple independent concerns (e.g., "CSV import for operators, plus a partner-facing status API" - different actors, different problem statements), test each candidate slice against `../shape-ticket/reference/split-axes.md` (identity test, outcome test, closed axis list, release-timing precondition). A multi-spec offer renders the three-line justification per proposed spec - root cause / outcome / axis:
+One spec is default. Test seemingly independent concerns against `../shape-ticket/reference/split-axes.md` (identity, outcome, closed axis, release timing). For every proposed split render exactly:
 
     root cause: <the precipitating failure or missing capability this slice remedies>
     outcome: <what a user observes once it ships>
     axis: <one item from the closed list>
 
-a slice failing any part -> one spec, and the failed split is not offered:
+If any test fails, offer no split. Never split by service, package, repo, layer, or team. If all pass, ask whether to brainstorm the independent specs separately or explain their coupling.
 
-> "This looks like 2 independent specs to me - A (axis: <axis>), B (axis: <axis>). Should we brainstorm each separately, or is there a tight coupling I'm missing?"
+### 3. Understand the idea
 
-Never split on service, package, repo, layer, or team boundaries - a single feature, bug, or improvement routinely cuts through many layers, and one spec covers it. A genuinely multi-concern request designed as one spec is still wrong; decompose it, but only along a passing axis.
+`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.
 
-### 3. Understand the idea
+Ask one question per message, preferably multiple choice, about purpose, constraints, success, and affected actors. Before asking, check code, docs, and tracker: look up current-state facts (dispatch a subagent when costly); ask desired-behavior decisions even when a ticket recorded one. Every questionary question, including acceptance of a corrected fact, ends `Recommendation: <answer> - <why>`; other approvals retain their wording.
 
-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. Before asking, check whether the code, the docs, or the issue tracker
-  already answer it: a fact about the current state is looked up, not asked (dispatch
-  a subagent when the lookup is costly); a decision about what should happen is asked,
-  even when a ticket recorded one earlier. Every questionary question, including the
-  ask to accept a corrected fact, ends with the line `Recommendation: <answer> - <why>`
-  (the answer, then " - ", then the reason); approvals elsewhere in this skill (git
-  state, design rounds, the spec gate) keep their own wording.
-- **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.)
-
-Before proposing approaches, state the premise note in chat: what the design depends
-on, which of those claims the sources support and where you saw it (a file and line,
-a doc, a ticket), which they disprove - give the corrected fact and where you found
-it - and which remain unverified, naming the lookup you tried. Write it as a note a
-person can act on: full sentences, no status-keyword lists, no template; when the
-design depends on no claims at all, one sentence saying so is enough. An unverified
-claim is not a stop - it enters the spec as an Open Question or a stated assumption.
-If a claim the design depends on was contradicted, the note is your next message -
-even as questionary question one - and it ends by asking the user to accept the
-corrected fact or explicitly override it; nothing else continues - no other questions,
-no approaches - until they answer, and the outcome is recorded in the draft's
-`## Appended during questionary` so spec-writing carries it into `## Problem` or the
-relevant `## Design` decision.
+Append only citable findings - schemas, hard constraints, contradictions, and scope-changing answers - to `## Appended during questionary` using `edit`.
+
+Before approaches, state in chat the supported, disproved, corrected, and unverified premises with sources and attempted lookups. Put unverified claims in Open Questions or assumptions. If a load-bearing claim is contradicted, the premise note is your next message - even as question one - and asks the user to accept the corrected fact or override it; ask nothing else and propose nothing until answered. Record the outcome in the draft for `## Problem` or the relevant design decision.
 
 ### 4. Explore approaches
 
-- Propose 2-3 different approaches with trade-offs.
-- Lead with your recommended option and explain why.
-- Present conversationally — don't dump a comparison table unless the user asks.
+Propose 2-3 approaches with trade-offs; lead with the recommendation and explain it. Use conversational prose unless the user asks for a table.
 
 ### 5. Design for clarity and isolation
 
-When sketching the design, prefer:
-
-- **Clear boundaries** — clean interfaces between components, easy to test in isolation.
-- **YAGNI ruthlessly** — every component you add is a component you must maintain.
-- **Match existing patterns** — if a service has a convention, follow it. Reference the service's `AGENTS.md` and neighboring code.
-- **Single source of truth** — point at the schema/contract that owns the data (the migration, type definition, or API contract that defines it); don't invent parallel state.
-- **Explicit error and edge cases** — name them. "Out of scope" is a valid answer, but it has to be stated.
+Prefer clear testable boundaries, YAGNI, existing conventions, the owning schema/contract rather than parallel state, and explicit errors and edge cases.
 
 ### 6. Present the design in two rounds
 
-Two rounds, one approval each. Target 300-500 words per round. A revisit after feedback stays inside the same approval point.
+Use two 300-500-word rounds 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`.
 
-- Round 1: architecture overview, components / responsibilities, data flow, and `supersedes <path>, <scope>` when the draft names a predecessor. Ask once. Approval without correction confirms the predecessor.
-- Round 2: error handling and edge cases, testing approach, `## Documentation impact`. Ask once.
-
-The `## Documentation impact` section is required. Cite the materiality bar in `reference/documentation-impact.md` by relative path rather than restating its categories, and reproduce its template block verbatim:
+`## 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
@@ -205,41 +115,25 @@ The `## Documentation impact` section is required. Cite the materiality bar in `
   - Derived / memory docs invalidated: <routers / AGENTS.md sections / topic guides / indexes, or "none">
   ```
 
-  Each entry answers with a doc name, "none", or "deferred: <trigger>". A new standalone `.md` appears only where no existing doc already owns the topic. Project-specific doc taxonomy goes in a `## documentation` block in the gauntlet overrides file (see Project overrides) (no new settings key; guidance only). Doc updates ship in the same commit and are verified against the spec by the conformance gate.
-
-Be ready to go back and clarify when something doesn't make sense.
+Use doc names, `none`, or `deferred: <trigger>`. Apply `reference/documentation-impact.md`; amend an owner before creating a standalone file. Put project taxonomy in the overrides file's `## documentation` block. Ship doc updates with code and verify them at conformance. Clarify when needed.
 
 ## Ticket Handling
 
-When a ticket ID is given, fetch the ticket and treat it as **guidance, not the sole source of truth**. Propose changes to scope, approach, or acceptance criteria when they don't align with the codebase. Surface deviations in the spec doc.
+A ticket is guidance, not sole truth. Fetch it; propose scope, approach, or acceptance changes when code disagrees, and record deviations in the spec.
 
 ## First-Feature Oversight (Early Project Stages)
 
-For the **first two features** of a new initiative (a new top-level module/package, long-lived component, persistence/schema area, or any pattern that will repeat), round 1 lists these decisions explicitly so the user can correct them there: directory and module structure; naming conventions (public types, files, routes, identifiers); new shared abstractions (location, responsibility, boundary); persistence/schema design (entity names, field types, indexing); proposed additions to AGENTS.md or doc/ files. No separate confirmation. After the first two features establish patterns, follow them.
+For the first two features of a new module, long-lived component, schema area, or repeatable pattern, round 1 explicitly covers structure, naming, shared abstractions, persistence/schema, and proposed AGENTS.md/docs changes. Use no separate confirmation; later features follow established patterns.
 
 ## Anti-Pattern: "Too simple to need a design"
 
-Watch for the rationalization "this is just a small change, let's skip the spec and code it":
-
-- Small changes that touch shared schemas, contracts, or invariants need a spec.
-- "Small" often hides assumptions that the spec process would surface.
-- A 5-minute spec saves an hour of rework when the assumption was wrong.
-
-If the change truly is mechanical and contained (rename, formatter run, dependency bump), say so explicitly and skip brainstorming. Otherwise: spec first.
+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.
 
 ## Filename Convention
 
-Spec lives in the project's `doc/specs/` (see [Project Routing](#project-routing)) with one of:
-
-- With ticket: `YYYY-MM-DD-<ticket-id>-<topic>.md` — `<ticket-id>` is a filename-safe slug of the tracker reference (e.g. `E-12345` for Linear, used verbatim; `gh-123` for GitHub issue `#123`). Plan headers and commit messages use the tracker's native reference form, not the filename slug.
-- Without ticket: `YYYY-MM-DD-<topic>.md`
-
-`<topic>` is a short kebab-case slug (3–6 words). Do **not** append `-design` or any other suffix.
+Write under the routed `doc/specs/`: ticketed `YYYY-MM-DD-<ticket-id>-<topic>.md`, otherwise `YYYY-MM-DD-<topic>.md`. Use a filename-safe tracker slug (`E-12345`, `gh-123`), but native references in plan headers and commits. `<topic>` is 3-6 kebab-case words without `-design` or another 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).
+Mint the slug once during gather and reuse it. If questionary invalidates it, write to the new path and delete the uncommitted draft.
 
 ## Spec Self-Review (Before User Review Gate)
 
@@ -259,7 +153,7 @@ Spec-writing replaces the context draft, in this exact order:
    [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:** 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.
+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.
@@ -267,35 +161,32 @@ After writing the spec to `<project>/doc/specs/<filename>.md` (per [Filename Con
 - **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 three checks — **placeholder scan**, **internal consistency**, and **documentation named** — are the inline **lint**: run them here at the main loop and fix what they surface. The last two — **scope** and **ambiguity** — are **not** run inline; they are the **critique pass**, auto-dispatched (per [Spec Council](#spec-council-optional)):
+The first three 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).
 
-- **Council** (`gauntlet_setting({ key: "specCouncil" })` returns verdict `council`) → invoke `/skill:roasting-the-spec`; it runs the critique, derives dispositions, and **applies the apply-set to the spec** (including inlining any `external-ref:` cluster it has context for) **before returning** — see that skill for apply mechanics. It returns a structured audit: `Applied:` / `Deferred:` / `Rejected:`.
-- **Otherwise** → 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. Apply two checks and\n" +
-    "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." })
-  ```
+## Spec Council (Optional)
 
-  `worker`'s model resolves from `subagents.agentOverrides.worker.model` in `settings.json` (unset → inherits the main loop); the dispatch passes no `model:`.
+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, 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`.
 
-Both paths apply their fixes **before returning** — the council auto-applies inside `/skill:roasting-the-spec`, the worker edits the spec file directly. After the critique pass returns, re-run the placeholder scan over the **applied** spec to catch anything the edits introduced, and — if a predecessor banner was written — confirm its `<scope>` still matches the applied spec, reconciling the banner if critique edits changed what is superseded. If the worker flagged ambiguities it could not safely resolve, surface them in the [User Review Gate](#user-review-gate) message so the user decides - the worker auto-applies fixes but never silently swallows an open question.
+When `verdict` is `"worker"`, dispatch one fresh `worker` that applies the scope + ambiguity checks and fixes them in place:
 
-## Spec Council (Optional)
+```
+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. Apply two checks and\n" +
+  "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." })
+```
 
-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, 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"`, run the fresh-`worker` critique instead (see [Spec Self-Review](#spec-self-review-before-user-review-gate)). 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`.
+`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. This is the **same** single human gate - the summary is folded into it, not a new 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`):
 
@@ -320,7 +211,7 @@ Then commit the spec — staging any predecessor spec edited per [Marking supers
 
 Either way — summary rendered or degraded — then `rm "$SUMMARY_PATH"` (unconditional cleanup; harmless if the file was never created, since it lives outside the worktree under the OS temp dir).
 
-Render the temp file's contents **verbatim** first — paste it as-is, do **not** paraphrase, condense, re-section, drop sections, or merge it with the council audit. "Fold into the gate" means *place it inside the gate message*, not *rewrite it*. This summary is of the **final (post-apply)** spec, since both critique paths already applied before this dispatch. After the verbatim block, append the commit confirmation, then — as their **own** adjacent lines, not edits to the summary — the council audit (if the council path ran: `Coverage:` when present - omitted at full coverage - then `Applied:` / `Deferred:` / `Rejected:`, one line each), critique-pass-unresolved ambiguities, and every entry from the summarizer's gap/external-context footer (surface **all** of them, not just the top risk):
+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>
@@ -357,7 +248,7 @@ phase_tracker({ action: "complete", phase: "brainstorm" })
 Execute this section in place from any later phase. Do not invoke `/skill:brainstorming` (its entry resets both trackers). Worktree, spec commits, and plan survive.
 
 1. Edit the spec. Show `git -C <abs worktree path> --no-pager diff -- <spec path>` and one line of impact (affected plan tasks / waves, or "no plan yet").
-2. Wait for approval. Change request -> revise, re-show.
+2. Render the diff and impact line. A user instruction in this flow that waives per-diff review for later amends ("auto-apply amends, stop only for redraws", "apply spec fixes without asking") is the approval: quote it in the amendment commit body and continue. Otherwise wait for approval; change request -> revise, re-show. Redraws always wait. A grant never satisfies the spec gate; a grant given with or before spec approval applies to later amends in the same flow; a new brainstorm and a fresh-session resume start with no grant.
 3. No plan yet -> commit the spec; continue. Plan exists -> update affected anchors and tasks: `plan_tracker` `add` for new tasks; anchor-changed completed tasks are reopened as `in_progress` and re-run the task loop (`update` never sets `pending`). A removed task is deleted from the plan; then re-`init` the tracker with `{ name, status }` elements: preserved tasks keep their order and statuses, reopened tasks are `in_progress` in place, every still-`pending` task (including newly added ones, whatever wave label they carry) trails the non-pending ones, removed tasks are the only deletions (the only permitted `init` after handoff; never `clear`). Re-run `plan_check` until it passes, commit spec + plan together; continue. A task reopened while `verify` or `ship` is in progress: `phase_tracker({ action: "skip", phase: "<current>", reason: "amendment reopened Task N" })`, then `phase_tracker({ action: "start", phase: "implement", force: true })`; later phases re-enter with `force: true` and rerun in full.
 
 Redraw test: the diff changes 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 in the same message as the diff; the user overrides either way.
@@ -366,27 +257,22 @@ Redraw: keep the worktree and the approved spec file. `plan_tracker({ action: "c
 
 ## Key Principles
 
-- **One question at a time.**
-- **Multiple choice preferred** when possible.
-- **YAGNI ruthlessly.**
-- **Design for testability** — clear boundaries enable TDD.
-- **Explore 2-3 approaches** before settling.
-- **Two design rounds** — one approval per round.
-- **Be flexible** — go back and clarify when something doesn't make sense.
+One question at a time, YAGNI, 2-3 approaches, two design rounds, clarify freely - all owned by [The Process](#the-process).
 
 ## Red Flags — STOP
 
-- Writing or editing anything outside `doc/specs/` while this skill is active.
-- Overwriting the draft without reading it in full in the same turn, or using `edit` for the spec-writing overwrite.
-- Dispatching lint, critique, council, or summarizer while the spec file's line 1 is the context-draft marker.
-- Running the scope or ambiguity checks inline instead of dispatching the critique pass.
-- Reaching the gate after a failed or skipped critique pass, or without re-running the placeholder scan on the applied spec.
-- Composing the gate without the summary `Read` as the last content-producing call, or paraphrasing the summary instead of pasting it verbatim.
-- Inserting a human stop between gather dispatch and questionary question one.
-- Running, deploying, or validating the proposed change before approval.
-- Proceeding to `/skill:writing-plans` before the user approves the spec, or invoking `/skill:brainstorming` to amend an approved spec.
-- Writing a replacement spec without the known predecessor's banner, or offering a multi-spec split that fails `../shape-ticket/reference/split-axes.md`.
-- Proposing approaches while a contradicted claim is unresolved.
+- Writes outside `doc/specs/` ([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)).
+- 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](#the-process)).
+- Proposed-change execution before approval ([owner](#hard-constraint)).
+- Plan before approval; brainstorming invocation for an amend ([owner](#user-review-gate)).
+- Missing predecessor banner; invalid multi-spec split ([owner](#spec-self-review-before-user-review-gate); [owner](#2-scope-check)).
+- Approaches while a contradicted premise remains unresolved ([owner](#3-understand-the-idea)).
+- Waiting after an amend grant; auto-applying a redraw ([owner](#amending-an-approved-spec)).
 
 ## Project overrides
 

package/skills/roasting-the-spec/SKILL.md

@@ -119,6 +119,8 @@ For each cluster in the chair's report, decide one of:
 - **defer** — out of scope for this spec; name where it belongs. Do not edit the spec.
 - **reject** — one-line reason. Do not edit the spec.
 
+**`hypothesis` clusters that assert data shape, ordering, or semantics** (a parsing rule, a field's meaning, a sort or date order, an identity key) are applied only after a probe. Search once for the artifact: one `rg --max-count` under `timeout` over `<abs worktree path>` and its docs, config, and script directories, for the artifact or for how it is obtained. At hand -> one bounded read-only check: a read, an `rg` over explicit paths, or a project script whose source you read and which only reads local files. Confirmed -> apply as fact. Anything else (not found, inconclusive, timed out, contradicted) -> write the edit into `## Open questions` (create the section if absent) with the probe run, its outcome, the obtain-hint if found, and the settlement path: the user supplies the fact at the gate, or the first plan task that obtains the artifact settles it via brainstorming's [Amending an approved spec](../brainstorming/SKILL.md#amending-an-approved-spec). One Open Question per artifact, listing every edit it settles - never one per assertion. Never fetch, build, or run the proposed change to obtain the artifact. A cluster without a tag is read as `hypothesis`; a `hypothesis` cluster that asserts nothing about data applies as any other.
+
 Also inline any `external-ref:` cluster you have context for (e.g. a ticket fetched during brainstorming) as part of the apply-set — this is your call, same as any other cluster.
 
 An `over-spec:` cluster decided **apply** is executed as deletion or shrink of the quoted clause **and** any acceptance-criteria or testing-approach line that exists only for it. Its audit line reads `Applied: over-spec: <clause> -> cut (was adds: M files / N tests / K ACs)` or `Applied: over-spec: <clause> -> shrunk to <replacement> (was adds: ...)`, so the gate shows what was removed. `defer`/`reject` are unchanged.
@@ -130,7 +132,7 @@ You are the advocate — decide on scope grounds — and, unlike a dispatched su
 Return a structured audit, gate-only (not a committed spec section) — a coverage line plus three labelled lists:
 
 - `Coverage:` — `N of M members reported; <slug>: <reason>` — present only when member coverage was partial; omitted at full coverage.
-- `Applied:` — cluster -> the concrete edit made.
+- `Applied:` — one of `Applied: <cluster> -> <edit> (grounded: <member probe>)`, `Applied: <cluster> -> <edit> (probed: <check> - <result>)` for a confirmed hypothesis, `Applied: <cluster> -> open question (<not found | inconclusive: <check> | contradicted: <result>>)`. The probe rides on the audit line because member files are removed in section 5.
 - `Deferred:` — cluster -> where it belongs.
 - `Rejected:` — cluster -> one-line reason.