pi-gauntlet 4.3.1 → 4.4.1

package/skills/brainstorming/gatherer.md

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

package/skills/finishing-a-development-branch/SKILL.md

@@ -70,24 +70,61 @@ git merge-base HEAD main 2>/dev/null || git merge-base HEAD master 2>/dev/null
 
 Or ask: "This branch split from main - is that correct?"
 
-### Step 3.5: Surface Closure / Conformance Status
+### Step 3.5: Closure / Conformance Disposition Gate
 
-Before presenting finish options, surface the closing-loop conformance result as **its own section** — the user is about to choose how to ship, and they need to see whether the deliverable matches what was *asked*, not just whether tests pass. Tests prove the code runs; conformance proves it does what was requested. Different gates.
+This is an **enforced per-gap disposition gate**, not a surface-only notice. The user is about to choose how to ship; every carried-open gap must get an explicit disposition here, before Step 4's menu. Tests prove the code runs; conformance proves it does what was requested — different gates.
 
-- **If the execution flow already closed the loop** (the `conformance-reviewer` ran in the `subagent-driven-development` verify gate), restate its verdict here: `CONFORMS`, or the `GAPS` and how each was dispositioned (fixed / accepted-and-recorded-in-spec / rescoped). If any gap is still open, drive it through the remediation loop in `verification-before-completion/reference/conformance-check.md` "When the check finds gaps"; on a normal-repo (`GIT_DIR == GIT_COMMON`) or detached-HEAD finish there is no worktree to dispatch fix waves into, so that menu offers accept / rescope / manual fix-in-place only.
-- **If no conformance check has run in this flow** (e.g., ad-hoc work that landed without an execution skill), say so plainly and offer to run it now — dispatch a fresh-context `conformance-reviewer` against the origin (spec + verbatim prompt + full diff vs base) per `verification-before-completion/reference/conformance-check.md`. Closing the loop is cheap relative to shipping unverified intent.
-- **Unreconciled gaps are a blocker, not a footnote.** Do not bury them inside the options menu. If any gap is still open, resolve it (or get explicit user acceptance recorded in the spec) before offering Option 1 (squash-merge) or Option 2 (PR).
+**If no conformance check has run in this flow** (e.g., ad-hoc work that landed without an execution skill): say so, then dispatch a fresh-context `conformance-reviewer` against the origin (spec + verbatim prompt + full diff vs base) per `verification-before-completion/reference/conformance-check.md`. Closing the loop is cheap relative to shipping unverified intent. Then proceed below with its verdict.
 
-Present it as a distinct line the user reads before choosing:
+**If verdict is `CONFORMS`** (no carried-open gaps): report `Closure / conformance: CONFORMS`. If the run auto-applied any fixes, also surface the flat `auto-applied fix commits: <Gn: SHA>, ...` index from the `## Closure / conformance` block with a one-line revert offer (see "Revert semantics") — a gap that auto-converged to `CONFORMS` mid-verify has no per-gap line above, so this index is the only place its fix commit stays revertable. No per-gap menu. Continue to Step 4.
+
+**If gaps were carried open:** read the `## Closure / conformance` block from the verify completion summary (schema and field names defined once in `verification-before-completion/reference/conformance-check.md` — do not re-derive them here). For each `Gn` line, render it verbatim and offer this ordered menu — the human must pick one entry per gap before Step 4:
+
+```
+G<n>: <verdict> — recommended: <fix|accept|rescope> — touched-files: <paths>
+  round history: R1 ..., R2 ...
+
+D1. Apply now: accept-into-spec — fold a dated decision into the spec now (main session edits the spec directly, never a subagent)
+D2. Apply now: rescope-into-spec — same, recorded as reduced/changed scope
+D3. Apply now: fix-now — run the fix loop now (worktree finish paths only, see below)
+D4. Custom disposition — e.g. capture as a follow-up ticket per this project's issue-tracker convention (see `.pi/gauntlet-overrides.md`)
+D5. Revert an auto-applied change for this gap (see "Revert semantics" below)
+
+Which option for G<n>?
+```
+
+Also surface the flat `auto-applied fix commits: <Gn: SHA>, ...` index from the same block — this is the revert candidate list for D5, covering every `conformance fix Gn` commit this run (open and already-closed gaps alike).
+
+**`fix-now` loop scope (worktree finish paths only):**
+
+1. Commit any `accept-into-spec` / `rescope-into-spec` edits picked in this gate **before** dispatching — a dirty tree rejects `worktree: true`, and the re-audit must read the amended spec.
+2. Run the **full** loop from `verification-before-completion/reference/conformance-check.md` "Fix loop" (implementer → integrate → test → `code-reviewer` → re-audit). Do not re-describe the loop steps here — that file is the single source.
+3. Re-run Step 1's test verification on the result.
+4. Re-enter this step (3.5) with the re-audited `## Closure / conformance` block before re-presenting ship options.
+
+**Non-worktree precondition (unchanged):** on a normal-repo finish (`GIT_DIR == GIT_COMMON`) or detached HEAD there is no worktree to dispatch fix waves into — the menu above offers D1, D2, D4, and D5 (manual fix-in-place substitutes for D3) but never dispatches `fix-now`.
+
+No auto-proceed: every carried-open gap needs an explicit answer from the list above before Step 4 renders. Once all gaps are dispositioned, report the final state as a distinct line:
 
 ```
 Closure / conformance: CONFORMS
-  (or: GAPS — <n> open)
-  - <gap> → proposed remediation: <one line>   [if any open]
+  (or: GAPS — <n> dispositioned: G1 accept-into-spec, G2 fix-now → CONFORMS, ...)
 ```
 
 Then continue to Step 4.
 
+### Revert semantics
+
+Three tiers, increasing cost — name the tier when a revert is requested:
+
+| Tier | What's reverted | Cost | Mechanics |
+|---|---|---|---|
+| Cheap | Council edit, reverted at the `brainstorming` gate | Spec isn't yet plan- or code-bearing | Revise spec, re-present |
+| Light | Conformance fix, reverted at finish | Gap re-opens for a fresh disposition | Revert the `conformance fix Gn` commit(s), re-audit |
+| Heavy | Council edit, reverted at finish | Rewrites the already-ratified contract that drove the plan and code | Amend spec → re-approve → regenerate affected plan/code → re-run verify before ship |
+
+A **heavy** revert is not a menu toggle — say so explicitly to the user before proceeding, and do not present it as equivalent-effort to the light tier. The council audit that lets the human identify revert candidates lives in the `brainstorming` spec commit message body (not a committed spec section).
+
 ### Step 4: Present Options
 
 **Normal repo and named-branch worktree — present exactly these 4 options:**
@@ -300,7 +337,7 @@ phase_tracker({ action: "complete", phase: "ship" })
 - Remove a worktree before confirming merge success
 - Clean up worktrees you didn't create (provenance check)
 - Run `git worktree remove` from inside the worktree
-- Present finish options while a conformance gap is open and undispositioned
+- Auto-proceed past an undispositioned carried-open gap
 - Skip the guarded plan-doc removal before push on Option 2 when a plan doc was committed
 
 **Always:**

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

@@ -1,13 +1,13 @@
 ---
 name: roasting-the-spec
-description: Use after writing a spec, when a spec council is configured (the resolved piGauntlet.specCouncil council, via the gauntlet_setting tool, repo settings over the preset). Auto-dispatched by /skill:brainstorming as the critique pass when members is non-empty (no longer offered). N members on different models critique in parallel, a neutral chair consolidates and adjudicates, the parent proposes dispositions, the user approves.
+description: Use after writing a spec, when a spec council is configured (the resolved piGauntlet.specCouncil council, via the gauntlet_setting tool, repo settings over the preset). Auto-dispatched by /skill:brainstorming as the critique pass when members is non-empty (no longer offered). N members on different models critique in parallel, a neutral chair consolidates and adjudicates, the parent applies its own dispositions and returns an audit for the user to ratify at brainstorming's gate.
 ---
 
 # Roasting the Spec (Spec Council)
 
 ## Overview
 
-A multi-model critique pass for a freshly written spec. Each council **member** runs on a different model and critiques the spec independently — different models surface different angles. A neutral **chair** consolidates the critiques and adjudicates disagreements. The parent proposes what to apply; the **user** approves. The council never decides on its own what changes land.
+A multi-model critique pass for a freshly written spec. Each council **member** runs on a different model and critiques the spec independently — different models surface different angles. A neutral **chair** consolidates the critiques and adjudicates disagreements. The parent decides what to apply and applies it before returning; the **user** ratifies (or reverts) the result at brainstorming's single gate. The council never decides on its own what changes land.
 
 Auto-dispatched from `/skill:brainstorming` as the critique pass, after the inline lint and before the user review gate, **only when a council is configured** (`members` non-empty). brainstorming owns that gate; when no council is configured it runs a single fresh-`worker` critique instead and does not invoke this skill.
 
@@ -19,8 +19,8 @@ This skill may read anything and edit **only** the spec under `doc/specs/`. It d
 
 - **Members** — independent witnesses. One per configured model, fresh context, read-only.
 - **Chair** — judge of the testimony. Fresh context (never saw the spec authored); consolidates and resolves member-vs-member conflicts. Final say on conflicts; no say on what gets applied.
-- **Parent (you)** — advocate. Proposes apply / defer / reject per finding on scope grounds. Cannot suppress findings.
-- **User** — jury. Approves what actually lands, at the existing review gate.
+- **Parent (you)** — advocate, and now also executor. You decide apply / defer / reject per finding on scope grounds, then apply the apply-set yourself (you hold the `edit`/`write` tools; this was always the main-loop model's job, just moved earlier). Cannot suppress findings — every finding lands in the audit as applied, deferred, or rejected.
+- **User** — sole jury. Ratifies (or reverts) the finished spec at brainstorming's one gate — after the apply, not before.
 
 ## Configuration and gating
 
@@ -100,32 +100,41 @@ List the exact member paths in the task text. The `reads:` array injects their c
 
 If the configured `chair` model is unreachable, retry once with the inherited model.
 
-### 3 — Propose dispositions
+### 3 — Decide and apply
 
-For each cluster in the chair's report, decide and state one of:
+For each cluster in the chair's report, decide one of:
 
-- **apply** — with the concrete edit you will make.
-- **defer** — out of scope for this spec; name where it belongs.
-- **reject** — with a one-line reason.
+- **apply** — make the concrete edit to the spec under `doc/specs/` now.
+- **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.
 
-You are the advocate here, not the judge — propose, do not unilaterally apply.
+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.
 
-### 4 — User gate
+You are the advocate — decide on scope grounds — and, unlike a dispatched subagent, also the executor: you hold `edit`/`write` tools directly, so apply the edit yourself instead of proposing it for someone else to make. Do this **before** returning to brainstorming.
 
-Fold the chair's clusters, its `resolved` audit notes, and your proposed dispositions into brainstorming's user review gate. Let the user approve or adjust.
+### 4 — Emit the audit
 
-### 5 — Apply and clean up
+Return a structured audit, gate-only (not a committed spec section) — three labelled lists:
 
-Apply the approved edits to the spec under `doc/specs/`. Re-run brainstorming's placeholder scan. Remove the temp dir (`rm -rf` the `mktemp -d` path). Then continue with brainstorming's normal commit. Nothing council-related (member files) is ever staged.
+- `Applied:` — cluster -> the concrete edit made.
+- `Deferred:` — cluster -> where it belongs.
+- `Rejected:` — cluster -> one-line reason.
 
-Single pass — no automatic re-roast loop. The user can invoke this skill again after edits for another round.
+Hand this audit to brainstorming along with the now-final spec. brainstorming writes it into the **spec commit message body** (git-native, readable pre-squash) so it survives for finish-time revert visibility, then shows it to the user alongside the final spec at its one review gate. The user can revert any applied edit there — that gate, not this skill, is where ratification happens.
+
+### 5 — Clean up
+
+Re-run brainstorming's placeholder scan over the applied result. Remove the temp dir (`rm -rf` the `mktemp -d` path). Nothing council-related (member files) is ever staged.
+
+Single pass — no automatic re-roast loop. The user can invoke this skill again after the gate for another round.
 
 ## Red flags — STOP
 
 - Running the council when `piGauntlet.specCouncil.members` is absent or empty (brainstorming owns the gate and should have used the worker fallback).
 - Reading member critique files yourself instead of routing them through the chair.
 - Writing member files to a relative path (they land in the worktree).
-- Auto-applying findings without the user gate.
+- Applying edits without surfacing the audit at brainstorming's gate — apply-before-the-gate is correct; apply-without-the-gate is not.
+- Suppressing a finding instead of routing it to applied, deferred, or rejected in the audit.
 - Surfacing member-vs-member disagreements to the user instead of letting the chair adjudicate.
 - Editing anything other than the spec under `doc/specs/`.
 

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

@@ -190,9 +190,9 @@ For the fan-out + worktree + patch-integration + conflict mechanics, see `dispat
 
 0. Call `phase_tracker({ action: "start", phase: "verify" })`. (The `implement` phase was started at execution start and auto-completes from `plan_tracker` once all tasks are done; this flow runs its own verify gate instead of `/skill:verification-before-completion`, so it must mark verify itself.)
 1. **Run the whole-diff code review.** Dispatch `/skill:requesting-code-review` against the worktree's full diff vs `main` (already covered in [The Process](#the-process) step "After all tasks"). Address Critical and Moderate findings before handoff. (Consumers wanting an in-flow project-specific audit re-add it as an explicit step in `.pi/gauntlet-overrides.md`, or run `/self-audit` manually.)
-2. **Close the loop — conformance check.** The review in step 1 is plan-vs-code (single-step); it inherits any requirement the plan already dropped. Before marking verify complete, dispatch a fresh-context **`conformance-reviewer`** — its **own** dispatch, never fused into the step-1 review — to confront the deliverable (code **and** docs) against the *origin* — the spec **and** the original prompt — per `verification-before-completion/reference/conformance-check.md`. Pass the spec path, the verbatim original prompt, and the full diff. On `GAPS`, do not auto-fix or auto-proceed: run the remediation loop in `verification-before-completion/reference/conformance-check.md` "When the check finds gaps" (disposition menu → isolated fix waves → bounded delta re-audit, capped by `gauntlet_setting({ key: "closureReview" }).maxFixRounds`). Only when the verdict is `CONFORMS` (or every gap is dispositioned) call `phase_tracker({ action: "complete", phase: "verify" })`.
-3. Summarize what was implemented (tasks completed, files changed, test counts, code-review verdict). Give the closing loop its **own section** — `Closure / conformance: CONFORMS` (or `GAPS` with each gap and its disposition) — so the user sees intent-fidelity as a first-class line before any finishing decision, not buried in the review verdict.
-4. **Proceed to finishing — no confirmation prompt.** When the verdict is `CONFORMS` (or every gap is dispositioned), invoke `/skill:finishing-a-development-branch` immediately. Its Step 4 menu (squash / PR / keep / discard) is the human gate; a separate "ready to finish?" prompt only stacks a second stop in front of it. Open gaps are already owned by step 2, so nothing is left to decide here. Manual testing is a follow-up after the finishing choice (on `<base-branch>` after a squash-merge, or on the PR branch), never a reason to hold this gate.
+2. **Close the loop — conformance check.** The review in step 1 is plan-vs-code (single-step); it inherits any requirement the plan already dropped. Before marking verify complete, dispatch a fresh-context **`conformance-reviewer`** — its **own** dispatch, never fused into the step-1 review — to confront the deliverable (code **and** docs) against the *origin* — the spec **and** the original prompt — per `verification-before-completion/reference/conformance-check.md`. Pass the spec path, the verbatim original prompt, and the full diff. On `GAPS`, this skill does not choose a disposition or stop for one: `conformance-check.md` "When the check finds gaps" auto-runs the fix loop for every `recommended: fix` gap (no menu, no stop) and carries any `accept`/`rescope`/`UNAUTHORIZED` gap OPEN to the finish gate — follow that file for the partition rule and the fix-loop mechanics; do not reimplement them here. The fix loop may drive `plan_tracker` to surface fix-wave progress (task name = `Gn: <short desc>`, lifecycle `pending → in_progress → complete` per gap); it never calls `phase_tracker`. Call `phase_tracker({ action: "complete", phase: "verify" })` once every gap is either fixed (`CONFORMS`) or carried OPEN as a deferred `accept`/`rescope`/`UNAUTHORIZED` gap — escalation (fix-round cap reached with an open `fix` gap) is the sole non-completing terminal state; on escalation, do not complete verify, stop and report.
+3. Summarize what was implemented (tasks completed, files changed, test counts, code-review verdict). Emit the `## Closure / conformance` block verbatim per the schema defined in `verification-before-completion/reference/conformance-check.md` (do not rename or reformat its fields); `finishing-a-development-branch` Step 3.5 consumes it by those exact field names.
+4. **Proceed to finishing — no confirmation prompt.** Once verify is complete per step 2's criterion, invoke `/skill:finishing-a-development-branch` immediately. Its Step 4 menu (squash / PR / keep / discard) is the human gate; a separate "ready to finish?" prompt only stacks a second stop in front of it. Carried-open gaps are resolved at Step 3.5 of that skill via the `## Closure / conformance` block from step 3 — nothing is left to decide here. Manual testing is a follow-up after the finishing choice (on `<base-branch>` after a squash-merge, or on the PR branch), never a reason to hold this gate.
 
 ## Red Flags — STOP
 
@@ -215,7 +215,7 @@ For the fan-out + worktree + patch-integration + conflict mechanics, see `dispat
 - `/skill:using-git-worktrees` — set up isolation first (small changes can branch in place with user approval)
 - `/skill:writing-plans` — creates the plan this skill executes
 - `/skill:requesting-code-review` — review template for reviewer subagents
-- `/skill:finishing-a-development-branch` — invoked automatically once the conformance verdict is `CONFORMS` (or all gaps dispositioned)
+- `/skill:finishing-a-development-branch` — invoked automatically once every gap is fixed (`CONFORMS`) or carried open
 
 **Subagents follow by default:**
 

package/skills/verification-before-completion/SKILL.md

@@ -57,7 +57,7 @@ Skip any step = lying, not verifying
 | Regression test works | Red-green cycle verified | Test passes once |
 | Agent completed | VCS diff shows changes | Agent reports "success" |
 | Requirements met | Line-by-line checklist | Tests passing |
-| Intent delivered (loop closed) | Fresh reviewer audits code+doc vs origin spec + prompt (`reference/conformance-check.md`) | Plan-vs-code review, tests passing |
+| Intent delivered (loop closed) | Fresh reviewer audits code+doc vs origin spec + prompt; verify completes when every gap is `CONFORMS` or carried-open as a deferred `accept`/`rescope`/`UNAUTHORIZED` gap - the sole non-completing terminal state is escalation (cap reached with an unresolved `fix` gap). Partition, fix loop, and `## Closure / conformance` schema: `reference/conformance-check.md` | Plan-vs-code review, tests passing |
 
 ## Rationalization Prevention
 

package/skills/verification-before-completion/reference/conformance-check.md

@@ -89,132 +89,145 @@ The reviewer **proposes, it does not dispose.** It emits structured gap blocks
 the verify gate) drives disposition, fixes, and re-audit. The reviewer never edits,
 dispatches, or re-audits itself.
 
-### CONFORMS
-
-Record the verdict in the completion summary's closure section and proceed.
-
-### GAPS — disposition menu
-
-Do **not** auto-proceed and do **not** auto-fix. Render the enumerated gap list —
-each as `Gn [VERDICT] origin — remediation (recommended: fix|accept|rescope)` — then
-a numbered prompt (a chat turn cannot express a bare keystroke):
+### Disposition — verdict-then-`recommended` partition, no menu
+
+Render the enumerated gap list — each as `Gn [VERDICT] origin — remediation
+(recommended: fix|accept|rescope)` — then partition and act, in this exact order.
+No prompt, no menu: this partition is deterministic and exhaustive.
+
+1. **Verdict `CONFORMS`** (no gaps) → record the verdict in the completion
+   summary's closure section and proceed. No loop.
+2. **Any gap is `UNAUTHORIZED`** → that gap **always** defers to the finish gate,
+   regardless of its `recommended` value. Never auto-remove or auto-accept
+   unrequested code here.
+3. **Every remaining `PARTIAL`/`MISSING`/`DRIFTED` gap**:
+   - `recommended: fix` → auto-run the fix loop below — **unless `maxFixRounds:
+     0`**, in which case carry the gap **OPEN** (see the fix loop's
+     `maxFixRounds: 0` note).
+   - `recommended: accept` or `recommended: rescope` → carry the gap **OPEN**,
+     deferred to the finish gate. Do not apply a spec edit here — the finish
+     gate owns disposition of deferred gaps.
+
+So the fast path (all gaps `recommended: fix`, none `UNAUTHORIZED`, cap > 0)
+therefore auto-runs the fix loop with no menu, stop, or confirmation; any other
+mix carries the `accept`/`rescope`/`UNAUTHORIZED` gaps OPEN while the `fix` gaps
+run. Record every gap's outcome (`CONFORMS`-closed or carried OPEN) in the
+`## Closure / conformance` block (schema below).
+
+**Re-partition after every re-audit.** A re-audit can introduce `Gn+1` or flip a
+carried gap's `recommended`. Re-run steps 1-3 above over the **full current
+open-gap set** each time the reviewer returns a report — never reuse a stale
+partition from an earlier round.
+
+### Fix loop — SDD Parallel-Wave mirror, per round
+
+Mirrors `subagent-driven-development` Parallel-Wave Mode and reuses its
+`plan_tracker` progress surface. Runs entirely inside the gate — it invokes
+**no** `phase_tracker` calls (`phase_tracker({ phase: "implement" })` errors
+while verify is `in_progress`) and does **not** enter SDD's phase machinery.
+Only the fan-out/integrate/review shape and `plan_tracker` are reused.
+
+**Precondition — worktree required.** The loop needs a worktree HEAD to branch
+fixes from. On the ad-hoc `finishing-a-development-branch` paths that run in a
+normal repo (`GIT_DIR == GIT_COMMON`) or detached HEAD, there is no such HEAD:
+skip this loop, carry every `fix` gap OPEN, and resolve manually at finish
+(`accept`/`rescope`/manual fix-in-place only).
+
+Per round:
+
+1. **`plan_tracker` init** with the round's gaps as tasks. Wave-prefix tasks
+   when the reviewer's `Parallel-safe:` line marks a `conflicts` pair (file OR
+   `touched-resources` overlap) — that pair runs in separate serial waves;
+   `disjoint` gaps share one wave. Lifecycle per gap: `pending` →
+   `in_progress` → `complete`. This re-init **replaces** the implement phase's
+   completed task list in the singleton widget — state-safe, since
+   `phase-tracker.ts` `applyPlanActivity` only auto-completes `implement`
+   while it is `in_progress`; the widget now shows fix-wave progress during
+   verify.
+2. **Per gap** (task → `in_progress`): dispatch `implementer` (fresh context,
+   `worktree: true`, `cwd` = the conformance worktree, `touched-files` from the
+   gap block as an explicit ownership boundary) → dispatch `spec-reviewer` on
+   the gap-block reference contract below → task → `complete`.
+3. **Integrate** serially via `git apply` onto the worktree HEAD, one gap's
+   patch at a time. Failure handling is inherited verbatim from
+   `dispatching-parallel-agents` "Review and Integrate": textual conflict →
+   re-run one agent sequentially with the other's integrated changes as
+   context; semantic conflict (applies clean, suite fails) → re-run the
+   offending task sequentially on integrated HEAD; a failed agent → integrate
+   the successes, then retry the failure with fresh context including the
+   integrated changes. A `BLOCKED`/`NEEDS_CONTEXT` return surfaces to the user.
+4. **Test gate** on the integrated tree, using the project's canonical test
+   command. A failure re-enters the failure-handling rules above.
+5. **`code-reviewer` once** on the round's cumulative fix delta (not per gap).
+6. **Re-audit**: re-dispatch `conformance-reviewer` over the fixes **plus** the
+   regression guard (any prior-`DELIVERED` requirement whose `evidence` file
+   the fix diff touched). Pass the full prior conformance report (every row,
+   including DELIVERED rows and their `evidence` `file:line`) and the round's
+   fix diff. Inject `model:` call-site per `gauntlet_setting({ key:
+   "closureReview" }).model` — same mechanism as the initial audit; omit
+   `model:` when it is `undefined` to inherit the parent's model. The
+   phase-tracker closure guard blocks a dispatch that omits `model:` when
+   `closureReview.model` is set, and warns (non-blocking) on one whose model
+   differs.
+7. **Converge or continue**: verdict `CONFORMS` → record it, done. Open gaps
+   within the cap → re-partition (per the rule above) and start the next
+   round. Cap (`gauntlet_setting({ key: "closureReview" }).maxFixRounds`,
+   default `2`, floors negatives at `0`, coerces non-integers to `2`) reached
+   with an open `fix` gap → **escalate to the human** with the per-gap
+   round-by-round verdict trail. Escalation is the sole non-completing
+   terminal state — no silent re-loop, no auto-ship.
+
+Commit each per-gap fix with the message **`conformance fix Gn`** (durable,
+`git log`-readable pre-squash) so the finish gate and any revert can identify
+auto-applied fixes.
+
+**`maxFixRounds: 0`**: skip this loop entirely. Every `recommended: fix` gap
+becomes carried OPEN to the finish gate instead of auto-running — the user
+opted out of auto-fix, so treat `fix` gaps like any other deferred gap. This
+differs from a cap > 0 that is *exhausted*: that case escalates mid-verify
+because the loop tried and could not converge.
+
+### `spec-reviewer` gap-block reference contract
+
+Per-gap `spec-reviewer` in step 2 above is a **pre-integration mechanical
+check**, distinct from the round-level re-audit in step 6 (which still
+references the *origin* — spec + original prompt — unchanged). Frame the
+per-gap dispatch against the **gap block**, not a plan task:
+
+- **Requirement** = the gap's `origin` + `remediation` (what must be true
+  after the fix).
+- **Closure proof** = the patch satisfies that requirement within the gap's
+  `touched-files` — nothing missing, nothing extra.
+- **Output** = `spec-reviewer`'s normal MATCH/DRIFT verdict, referenced to the
+  gap block instead of a plan task.
+
+This is a task-framing contract in the dispatch, not a new persona.
+
+## Closure / conformance
+
+Emit this block in the verify completion summary. It is the durable handoff
+`finishing-a-development-branch` Step 3.5 consumes — parseable even if session
+context was pruned. Verify completes when every gap is either fixed
+(`CONFORMS`) or carried OPEN as a deferred `accept`/`rescope`/`UNAUTHORIZED`
+gap; escalation (cap reached with an open `fix` gap) is the one
+non-completing terminal state.
+
+For each carried-open gap:
 
 ```
-[1] apply all recommended dispositions
-[2] review per-gap (override fix/accept/rescope before applying)
+Gn: <verdict> — recommended: <fix|accept|rescope> — touched-files: <paths>
+  round history: R1 <verdict/action>, R2 <verdict/action>, ...
 ```
 
-`[1]` applies each gap's `recommended` disposition, **except** any gap whose
-`recommended` is `accept` or `rescope`: list those and require an explicit confirming
-reply before their spec edits land (accept/rescope rewrite the origin — never on the
-unconfirmed fast path). `[2]` prompts a per-gap override, then applies.
-
-Disposition semantics:
-
-- `fix` — dispatch a remediation unit (below), then re-audit. For an `UNAUTHORIZED`
-  gap, "fix" = **remove** the unrequested code.
-- `accept` — the **main session** (not a subagent) folds the deviation into the spec as
-  a dated decision (template below). For `UNAUTHORIZED`, accept = keep the behavior,
-  document it as intended.
-- `rescope` — the main session records the requirement in the spec as an explicit
-  out-of-scope / deferred item, dated.
+Then a single flat revert index of **every** `conformance fix Gn` commit the fix
+loop produced this run — including gaps that later converged to `CONFORMS`
+(a closed gap has no block above, so its commit lives only here) — since the
+finish gate's revert option needs them all:
 
-Dated-decision template (append to the spec's decisions/deviations section):
-
-```
-- YYYY-MM-DD accept|rescope Gn: <requirement/behavior> — <one-line rationale> (conformance gate)
 ```
-
-**Commit accept/rescope spec edits BEFORE any fix wave dispatches:** pi-cohort
-rejects a dirty tree on a `worktree: true` dispatch, and the re-audit must read the
-amended spec. If a round has only accept/rescope and no `fix`, the edits land, the
-verdict is recorded, and no re-audit runs.
-
-### Fix dispatch — reuse dispatching-parallel-agents mechanics
-
-Fixes reuse the `dispatching-parallel-agents` fan-out primitive. Invoke **no**
-`phase_tracker` / `plan_tracker` calls and do **not** enter `subagent-driven-development`
-Parallel-Wave Mode (that mode opens with `phase_tracker({ phase: "implement" })`, which
-errors while the verify phase is `in_progress`, and needs a plan the fix loop lacks).
-
-**Precondition — worktree required.** Fix-via-dispatch needs a worktree HEAD to branch
-from. On the ad-hoc `finishing-a-development-branch` paths that run in a normal repo
-(`GIT_DIR == GIT_COMMON`) or detached HEAD, there is no such HEAD: the menu offers
-`accept` / `rescope` and **manual fix-in-place** only; unresolved gaps route to escalation.
-The loop below applies only when the gate already runs inside a worktree.
-
-**Wave grouping** comes from the reviewer's `Parallel-safe:` line: `disjoint` gaps form
-one parallel wave; any `conflicts` pair splits into separate serial waves. A pair conflicts
-on **file OR runtime-resource** overlap - two gaps whose fixes touch disjoint files but whose
-verification shares a `touched-resources` entry (DB/schema, port, fixture, external service,
-shared temp path) are **not** parallel-safe and run in separate serial waves, identical to
-planned-execution wave grouping. This is why the reviewer certifies both axes.
-
-**Dispatch shape** (mirrors `dispatching-parallel-agents`):
-
-```ts
-subagent({
-  context: "fresh",
-  worktree: true,
-  cwd: "<abs worktree path, from git rev-parse --show-toplevel>",
-  tasks: [
-    { agent: "implementer",
-      task: "Close conformance gap G1. Origin requirement: <origin>. What's missing: " +
-            "<remediation>. Satisfy the requirement; do not expand scope. " +
-            "Ownership boundary — modify only: <touched-files>." },
-    // one task per disjoint gap in this wave
-  ],
-})
+auto-applied fix commits: <Gn: SHA>, <Gm: SHA>, ... (revertable)
 ```
 
-- Unit = `implementer`, fresh context, `worktree: true`, `cwd` = the conformance
-  worktree. Pass `touched-files` as an explicit ownership boundary.
-- **Integrate** serially via `git apply` back onto the worktree HEAD — the fix ships in
-  the same worktree and rides `finishing-a-development-branch`'s squash. No new merge machinery.
-- **Failure handling is inherited verbatim** from `dispatching-parallel-agents`
-  "Review and Integrate": textual conflict → re-run one agent sequentially with the
-  other's integrated changes as context; semantic conflict (applies clean, suite fails)
-  → re-run the offending task sequentially on integrated HEAD; a failed agent → integrate
-  the successes, then retry the failure with fresh context including the integrated changes.
-  A `BLOCKED` / `NEEDS_CONTEXT` return surfaces to the user.
-- **`code-reviewer` over the integrated fix delta, once per round** (not per gap) — gap
-  fixes land after the branch's final code review, so review the round's cumulative diff.
-- **`spec-reviewer` is excluded** — plan-vs-code is the wrong reference point; the re-audit
-  checks fixes against the origin.
-- **Test gate** on the integrated tree after the round's waves apply, using the project's
-  canonical test command. A failure re-enters the failure-handling rules above.
-
-One round = dispatch waves → serial integrate → `code-reviewer` on round delta → test
-gate → re-audit.
-
-### Delta re-audit + cap
-
-Re-dispatch `conformance-reviewer` for a delta-scoped re-audit. Pass:
-
-- the **full prior conformance report** — every row including DELIVERED rows and their
-  `evidence` `file:line` (needed for the regression guard), not just gap IDs;
-- the **fix diff** for the round.
-
-The reviewer (not the orchestrator) computes the regression intersection: it re-verifies
-the gaps marked `fix` this round **plus** any previously-DELIVERED requirement whose
-`evidence` file appears in the fix diff. It reuses `G1..Gn`, marking each `DELIVERED`,
-still-open with its prior verdict, or introducing `Gn+1`.
-
-- The re-audit dispatch carries the **same call-site `model:` injection** as the initial
-  audit (when `piGauntlet.closureReview.model` is set, the phase-tracker closure guard
-  blocks a `conformance-reviewer` dispatch that omits `model:`, and warns — non-blocking —
-  on one whose model differs from the configured value).
-- New or still-open gaps within the cap re-enter the menu above.
-- **Cap: `gauntlet_setting({ key: "closureReview" }).maxFixRounds`** (the tool applies the
-  default `2`, floors negatives at `0`, and coerces non-integers to `2`). `0` = audit-only:
-  `GAPS` renders an accept/rescope-only menu and any unresolved gap escalates instead of
-  dispatching a fix.
-- **On non-convergence** (cap reached with open gaps): **escalate to human** with the
-  per-gap round-by-round verdict trail. No silent re-loop, no auto-ship.
-
-No completion claim stands over a gap that is neither fixed, accepted, nor rescoped.
-"Surface, don't auto-fix": the orchestrator presents options, the user decides.
-
 ## Checklist
 
 - [ ] Located canonical requirements (spec → prompt → ticket fallback)