pi-gauntlet 4.4.1 → 4.4.2

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## v4.4.2 - 2026-07-15
+
+Condense the finish-time conformance disposition gate to a dense, human-readable
+decision list - the corrective second pass over v4.4.1's disposition work, which
+delivered the right behavior but bloated the render and the freshness protocol.
+
+- **Finish gate (`finishing-a-development-branch`):** carried-open conformance
+  findings now render as a dense one-line-per-decision list - each line carries a
+  plain-language title, the unresolved point, its question, and an inline recommended
+  choice - with a two-option reply (`1` = every recommendation; `2:` =
+  recommended-except comma-separated `<handle>=<choice>` overrides). Replaces the
+  terse `Gn` tokens and the flat D1-D5 per-gap menu. Single-concern gaps show no
+  `/Cn` symbol; `UNAUTHORIZED` items note availability deviations inline; the
+  zero-gap path still goes straight to branch options with no sign-off.
+- **Freshness (`verification-before-completion/reference/conformance-check.md`,
+  `finishing-a-development-branch`, `subagent-driven-development`):** the four-field
+  audit-identity/hash protocol (duplicated across three files) collapses to a
+  `status`/`audited-base` sentinel plus a two-command working-tree drift check;
+  any change or doubt re-audits. The durable `## Closure / conformance` handoff
+  header drops `audited-spec-path`/`audited-diff-hash`/`audited-spec-hash`.
+- **De-duplication:** the disposition-availability table, the `UNAUTHORIZED`
+  question, the `recommended: none` preflight, and the fix loop now live only in
+  `conformance-check.md`; the finish gate and SDD consume them by link.
+
 ## v4.4.1 - 2026-07-13
 
 Gates ratify, not ceremony: two gauntlet gates now auto-apply mechanical/drafting

package/README.md

@@ -38,7 +38,7 @@ Concretely, one change through the gauntlet:
 1. You describe the change. **`brainstorming`** sets up an isolated worktree, explores the codebase, and turns your description into a written spec. A multi-model critique runs on it automatically. **You read and approve the spec - human gate 1.** No implementation code exists yet.
 2. **`writing-plans`** decomposes the approved spec into atomic, independently-verifiable tasks, grouped into parallel waves where they don't touch the same files.
 3. **`subagent-driven-development`** executes the plan one task at a time, each in a fresh subagent, behind spec-compliance review then code-quality review. TDD-locked: red, green, refactor.
-4. **verify**: a whole-diff code review, then the **conformance gate** - a subagent reads the finished code and docs against your *original words* from step 1, not the plan, and reports per-requirement: delivered, partial, missing, drifted, or unauthorized. This gate is machine-blocked from being skipped. Requirement-restoring gaps (code drifted from the approved spec) auto-close through an isolated fix-and-re-audit loop with no prompt; only decisions that would *rewrite* your approved spec - accept, rescope, or removing unrequested code - are deferred to the finishing gate for your call.
+4. **verify**: a whole-diff code review, then the **conformance gate** - a subagent reads the finished code and docs against your *original words* from step 1, not the plan, and reports per-requirement: delivered, partial, missing, drifted, or unauthorized. This gate is machine-blocked from being skipped. Compatible executable recommendations auto-run through an isolated fix-and-re-audit loop with no prompt; anything still open surfaces as a dense list - one line per decision, plain-language, with its recommended choice inline. Reply `1` to take every recommendation, or `2:` with per-item overrides; a current `CONFORMS` / no-concerns result goes straight to the branch options with no extra conformance sign-off.
 5. **`finishing-a-development-branch`**: squash, PR, keep, or discard. **Human gate 2** - the only other decision you make.
 
 ```mermaid
@@ -74,7 +74,7 @@ pi-gauntlet is **opinionated**: every non-trivial change rides this one pipeline
 | --- | --- |
 | Gate | A machine-enforced checkpoint between phases (e.g. `complete verify` is blocked until conformance review has run). Not a suggestion. |
 | Spec council | Multi-model critique of the spec before you see it (`roasting-the-spec`); falls back to a single-model critique if no council is configured. |
-| Conformance gate | The closing check: does the delivered code + docs match your *original prompt*, not the derived plan? Per-requirement verdict; auto-fixes requirement-restoring gaps, defers spec-rewriting decisions (accept/rescope/unauthorized) to the finishing gate. |
+| Conformance gate | The closing check: does the delivered code + docs match your *original prompt*, not the derived plan? Compatible executable recommendations auto-fix first; anything still open renders as a dense one-line-per-decision list with each recommended choice inline. Reply `1` to accept all recommendations or `2:` with per-item overrides; a current `CONFORMS` / no-concerns handoff goes straight to branch options with no extra sign-off. |
 | Wave | A batch of plan tasks that don't touch the same files, dispatched to implementers in parallel. |
 | Overrides file | `.pi/gauntlet-overrides.md` - where you put project-specific detail the generic skills don't know (CI command, worktree wrapper, routing rules). |
 

package/package.json

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

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

@@ -72,46 +72,91 @@ Or ask: "This branch split from main - is that correct?"
 
 ### Step 3.5: Closure / Conformance Disposition Gate
 
-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.
+This is an **enforced disposition gate**, not a surface-only notice. The user is about to choose how to ship; every carried-open decision 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 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.
+`verification-before-completion/reference/conformance-check.md` is **canonical** for the durable handoff schema, concern-decomposition rules, the single disposition-availability table, the `UNAUTHORIZED` question text, the `recommended: none` preflight, the freshness rule, and the concern-scoped fix projection. This step owns only **render, response, and execute-order** and consumes the rest by link - it does not restate the availability table, the `UNAUTHORIZED` question, or the preflight prose.
 
-**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 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 that reference - it owns the audit-time input rule (stage/commit untracked deliverables before auditing). Closing the loop is cheap relative to shipping unverified intent. Route the raw reviewer verdict through the reference's canonical pipeline (gap/concern partition, auto-fix where eligible, concern decomposition, emission of a durable `## Closure / conformance` block), then consume that block through the branching below exactly as a carried handoff.
 
-**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:
+**Freshness precondition - before any verdict branch, including `CONFORMS`.** The durable block opens with a two-line sentinel: `status: CONFORMS (0 open)` or `status: GAPS (N open)`, then `audited-base: <full HEAD SHA at audit time>`. Read the sentinel, then apply the reference's freshness rule (its `## Closure / conformance` block is the single source): compare `audited-base` to the current working tree; any change, doubt, missing/mismatched sentinel, legacy terse row, or malformed structured reviewer block triggers a fresh audit and replacement of the closure block. Never infer `CONFORMS` from the absence of bullets. Only a clean, valid `status: CONFORMS (0 open)` handoff enters the zero-gap fast path.
 
+**Zero-gap fast path:** print exactly
+
+```
+Closure / conformance: CONFORMS
 ```
-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)
+then continue directly to Step 4. No approval prompt, no menu, no shared options line, no sign-off. If the run auto-applied fixes, surface the flat `auto-applied fix commits: <Gn: SHA>, ...` index from the durable block as **one informational, non-blocking line** with a one-line revert offer (see "Revert semantics") - a gap that auto-converged mid-verify has no bullet, so this index is the only place its fix commit stays revertable. Do not wait for acknowledgment.
+
+**Carried-open render (dense).** Read the `## Closure / conformance` block. Render a header with the decision count, one bullet per decision unit (a gap by default; a `Gn/Cn` concern only where the reference split it), then the shared options line, then the recommended-set reply. Never show durable-card internals (ownership, evidence tokens, identity, hashes) in the render.
+
+Each bullet:
 
-Which option for G<n>?
+`* <handle> - <plain title>: <what's unresolved, one clause>. <short question> Recommended: <choice> (<one-clause why>).`
+
+- `<handle>` leads the bullet and is a short unique human word derived from the title (`Cache coverage` -> `cache`); on collision append a digit. It is the token option 2 targets. When a gap split and no clean word fits, use the bare `Gn/Cn`; a single-concern gap uses its gap ID `Gn`.
+- The shared options line sits below the bullets: `Other options per item: fix-now / accept / rescope / follow-up / custom`, listing the options **generally available across items**. When a specific item's availability deviates - an option unavailable for it, or an `UNAUTHORIZED` item whose `rescope` is unavailable and whose `fix-now` means removal - note that deviation as a short parenthetical on **that item's bullet** (one clause, not a block), e.g. `(rescope N/A: scope creep)`. The shared line appears **only in the carried-open render**, never in the zero-gap path. Full per-option effects only on request, or when option 2 targets an unclear choice.
+- Group items under one recommended line only when they share a disposition and rationale; each grouped handle repeats its title.
+- Availability per concern comes from the reference's single availability table - apply it against current context (worktree state, `maxFixRounds`, ownership, resource accessibility), do not restate it. `UNAUTHORIZED` bullets ask the reference's question verbatim (`Should this unrequested behavior become part of the current workflow?`); `rescope-into-spec` is shown **unavailable** (not dropped) and `fix-now` means **removal** of the unrequested code.
+- `revert conformance fix Gn`, when the gap has an auto-applied fix, renders on the shared options line as a **separate one-off action** - never inside a bullet's recommendation and never in the option-2 list. Name the parent gap and warn that revert undoes the entire gap-level commit (see "Revert semantics").
+
+Representative carried-open render (multi-concern gap split to `e2e`; single-concern gap `cache`; `UNAUTHORIZED` gap `auth`):
+
+```
+Conformance: 3 decisions needed before shipping.
+
+* e2e - Source-image E2E validation: not run; blocked (HYDRA1.png, HTTP 401).
+  Still in scope for this branch? Recommended: rescope (defer until image available) (fix-now N/A: needs HYDRA1.png).
+* cache - Cache coverage: implemented but the spec is silent on it.
+  In scope? Recommended: accept into spec (behavior is intentional).
+* auth - Unrequested admin bypass: adds an unlisted route. Should this unrequested behavior become part of the current workflow? Recommended: fix-now = remove it (rescope N/A: scope creep).
+
+Other options per item: fix-now / accept / rescope / follow-up / custom.
+
+1. Go with recommended
+2. Recommended except <handle>=<choice>   e.g. "2: cache=follow-up"
+```
+
+A single-concern render is identical minus the split: one bullet whose handle is the gap ID or word, no sibling.
+
+#### Response grammar
+
+```
+1                                  -> apply every recommendation
+2: cache=follow-up
+2: e2e=custom(open ticket after image lands), cache=follow-up
 ```
 
-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).
+- `1` (or `apply recommended`) applies all recommendations.
+- `2:` takes a comma-separated override list, each `<handle>=<choice>`; omitted items keep their recommendation. A handle may appear at most once (repeat = invalid).
+- `custom(<concrete effect>)` supplies an inline effect. Manual fix-in-place is expressed only as `custom(...)` where isolated `fix-now` is unavailable.
+- `recommended: none` items follow the reference's preflight (linked, not restated): the item needs a `<handle>=custom(...)` decision, and option 1 is withheld until every open item has an executable recommendation; after the custom decision the menu re-renders for the remainder.
+- `revert conformance fix Gn` is a valid standalone reply, mutually exclusive with `1` and `2:`; it never appears inside a `2:` override list.
+- Invalid handle or choice -> focused reprompt naming only that item, retaining every valid pick and never reopening the gate. Unknown token: list the valid titled handles. Known item, bad choice: repeat its title + its available choices.
 
-**`fix-now` loop scope (worktree finish paths only):**
+#### Execute order
 
-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.
+Take **no** disposition action before the reply. Then, once, in order:
 
-**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`.
+1. **Normalize** every `custom(...)` into explicit operations; classify state-changing (edits code or spec) vs not. Clarify only an ambiguous or unexecutable effect.
+2. **Commit spec edits** (`accept-into-spec`, `rescope-into-spec`, state-changing spec `custom`) - the main session edits the spec directly, before any fix dispatch (a dirty tree rejects `worktree: true`, and the re-audit must read the amended spec).
+3. **Re-audit if step 2 changed the spec**; regenerate the inventory and re-render if it changed. Project `fix-now` only from the refreshed inventory.
+4. **fix-now + code-changing custom:** project the selected concerns per gap into the reference's concern-scoped fix contract (excluding accepted/rescoped/followed-up siblings); run the reference "Fix loop" (unchanged - do not re-describe it). A code-changing `custom` runs the project's tests + `code-reviewer` on its delta before proceeding. Re-run Step 1's canonical tests.
+5. **Re-audit after all state-changing work;** obtain fresh decisions **only if** the refreshed inventory differs from the approved one, else proceed.
+6. **follow-up** from the current inventory: create the item via the project's issue-tracker convention (`.pi/gauntlet-overrides.md`), record the ticket ID/URL; on failure keep the concern open.
+7. **Non-state-changing custom:** execute and record the result.
+8. **revert** (`revert conformance fix Gn`): light-revert the indexed commit, re-run Step 1's canonical tests; on failure stop; on pass re-audit and regenerate.
+9. Re-enter Step 3.5 with the re-audited block if any concern remains open.
 
-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:
+Record every final disposition with its **stable ID** as `Gn/Cn - <title>: <disposition>` (or `Gn - <title>: <disposition>` for a single-concern gap) - ticket ID/URL for `follow-up`, result for `custom`; never relabel a `custom` result as a recommendation. This durable record is the machine/audit surface; the interactive render stays handle-based. Then continue to Step 4:
 
 ```
 Closure / conformance: CONFORMS
-  (or: GAPS — <n> dispositioned: G1 accept-into-spec, G2 fix-now → CONFORMS, ...)
+  (or: GAPS resolved - G1/C1 - Source-image E2E validation: rescope-into-spec;
+       G2 - Cache coverage: follow-up (PROJ-123); ...)
 ```
 
-Then continue to Step 4.
+No auto-proceed: every carried-open decision needs an explicit disposition before Step 4 renders.
 
 ### Revert semantics
 

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`, 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.
+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. Follow that reference for the partition rule, concern decomposition, and 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" })` only when the reference says the handoff is durably complete: either a current `CONFORMS` result, or a current `## Closure / conformance` inventory whose carried-open concerns all come from valid deferred gaps, including `recommended: fix` gaps carried open because a declared precondition made the fix loop unavailable (`maxFixRounds: 0`, or no eligible named-branch worktree). A started positive-cap fix loop that blocks, fails, or exhausts its rounds with an open `fix` gap is escalation, not completion; 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 exactly as defined in `verification-before-completion/reference/conformance-check.md`: it must open with the two-line sentinel (`status: CONFORMS (0 open)` or `status: GAPS (N open)`, then `audited-base: <full HEAD SHA>`), then carry the exact durable concern schema by reference with no renamed or reformatted fields. `finishing-a-development-branch` Step 3.5 consumes that block verbatim.
+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 concerns are resolved there per concern via the `## Closure / conformance` block from step 3. 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
 

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; 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 |
+| Intent delivered (loop closed) | Fresh reviewer audits code+doc vs origin spec + prompt; verify completes only on a current `CONFORMS` result or a current durable carried-open closure inventory permitted by `reference/conformance-check.md` (including declared-precondition-unavailable `recommended: fix` gaps). A started positive-cap fix loop that blocks, fails, or exhausts rounds with an open `fix` gap is escalation, not completion. | Plan-vs-code review, tests passing |
 
 ## Rationalization Prevention
 

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

@@ -101,17 +101,18 @@ No prompt, no menu: this partition is deterministic and exhaustive.
    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: fix` → auto-run the fix loop below — **unless a declared
+     fix-loop precondition is unavailable** (`maxFixRounds: 0`, or no eligible
+     named-branch worktree), in which case carry the gap **OPEN** (see the fix
+     loop's precondition and `maxFixRounds: 0` notes).
    - `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
+So the fast path (all gaps `recommended: fix`, none `UNAUTHORIZED`, cap > 0,
+eligible named-branch worktree) 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
@@ -130,8 +131,10 @@ 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).
+skip this loop, carry every `fix` gap OPEN, and resolve it at finish via the
+canonical Disposition catalog and availability table below. `fix-now` is
+unavailable there; any other disposition is offered only when its table
+prerequisites hold.
 
 Per round:
 
@@ -203,31 +206,262 @@ per-gap dispatch against the **gap block**, not a plan task:
 
 This is a task-framing contract in the dispatch, not a new persona.
 
+## Concern decomposition
+
+The main verification orchestrator — **not** `conformance-reviewer` — decomposes
+each carried-open gap into concerns when it writes the completion summary. A
+**gap** is the reviewer's overall finding; a **concern** (`Gn/Cn`) is one
+consequence within it that could reasonably receive a *different* disposition.
+Observations that necessarily move together stay one concern.
+
+The orchestrator reasons from:
+
+- The final reviewer coverage row and structured gap block.
+- The origin spec and original prompt already supplied to verification.
+- Session-observed blockers, prerequisite checks, and fix-loop outcomes.
+- The round history and current touched-file/resource ownership.
+
+Per gap, apply these rules **in order**:
+
+1. Extract atomic unmet clauses and remediation actions from `origin`,
+   `evidence`, and `remediation`. Add a session-observed blocker **only** when a
+   tool result or fix-loop outcome established it.
+2. **Split** two points when either could be fixed, accepted, rescoped, or
+   followed up without imposing the same disposition on the other.
+3. **Keep together** when one action is meaningful only with the other, or no
+   different disposition could be executed independently.
+4. Map **every** unmet clause, remediation action, and established blocker to at
+   least one concern. Do **not** add a requirement absent from the origin or
+   prompt — invent nothing.
+5. Order concerns by first appearance in the origin/remediation and assign
+   `C1`, `C2`, and so on (source order).
+
+A valid decomposition has no omitted source point, no invented requirement or
+evidence, and a concern-scoped remediation plus ownership estimate for every
+`fix-now` candidate. Shared evidence may appear in multiple concerns. When the
+source cannot support a safe split, the fallback is **one indivisible `Gn/C1`**
+concern carrying the complete gap and the known blocker; decomposition never
+blocks on obtaining richer prose from the unchanged reviewer.
+
+Field derivation is explicit: `title` and `unresolved` summarize the unmet
+clause; `origin` narrows the gap `origin` to this concern's specific clause
+without inventing a new requirement; `remediation` states the concern-scoped
+remediation action drawn from the gap `remediation`; `impact` states the
+consequence already implied by the origin requirement; `evidence` copies
+reviewer evidence plus verified session observations;
+`touched-files`/`touched-resources` narrow the gap ownership where supported,
+otherwise `unknown`/`none`. For an `UNAUTHORIZED` concern there is no origin
+requirement to narrow: keep `origin: none (scope creep)` verbatim — never invent
+an origin clause; derive `unresolved` from the reviewer's `evidence`/`remediation`
+as a plain description of the unrequested behavior; and derive `impact` from the
+consequence of retaining, removing, or ratifying that behavior, not from an origin
+requirement. These per-concern fields persist the exact contract
+the concern-scoped fix projection consumes after pruning. **`evidence: absent`
+is an unmet-delivery fact, not
+an external blocker** — never relabel missing implementation evidence as a
+blocker. A malformed structured reviewer gap block — missing its stable `Gn`
+label or any required field (`verdict`, `origin`, `evidence`, `remediation`,
+`touched-files`, `touched-resources`, `recommended`) — triggers a **fresh
+audit**; a complete structured reviewer gap block does not — the orchestrator
+decomposes it or emits the indivisible fallback.
+
+## Disposition catalog and availability
+
+Each concern lists **every** supported disposition, its concrete effect, and
+current availability. This table is the single availability contract, referenced
+by both this verify gate and `finishing-a-development-branch`:
+
+|Disposition|Ordinary gap effect|`UNAUTHORIZED` effect|Available when|
+|---|---|---|---|
+|`fix-now`|Complete missing implementation or validation.|Remove the unrequested code or behavior.|Named-branch worktree; `maxFixRounds > 0`; concern ownership is known; every required local/external resource is accessible.|
+|`accept-into-spec`|Ratify intentional implemented behavior when the written contract is stale.|Ratify the unrequested behavior as approved scope.|A writable spec exists and there is concrete behavior to ratify.|
+|`rescope-into-spec`|Explicitly remove or defer the origin requirement from this workflow.|Unavailable: scope creep has no origin requirement to defer.|The verdict is not `UNAUTHORIZED` and a writable spec exists.|
+|`follow-up`|Keep the concern valid but transfer it to separately owned work.|Transfer a separately valid decision or removal task.|The concern can stand alone and the project defines an executable issue-tracker convention. Without one, mark unavailable and direct the user to `custom` to name another durable owner.|
+|`custom`|Execute another user-defined disposition after its effect is clarified.|Same.|Always visible; executable only after the user supplies a concrete effect. It is never an automatic recommendation.|
+
+A failed condition leaves the disposition visible and names the exact missing
+prerequisite. `touched-files: unknown` makes `fix-now` unavailable until
+ownership is established. A normal checkout (`GIT_DIR == GIT_COMMON`) or detached
+HEAD cannot dispatch the isolated fix loop at all - it has no named-branch
+worktree to branch fixes from - so `fix-now` stays unavailable there regardless
+of ownership; resolve those concerns manually at finish. `maxFixRounds: 0`
+(audit-only) likewise leaves `fix-now` visible but unavailable — the user
+configured no auto-fix loop, and finish-time selection never bypasses or resets
+that cap; a concrete `custom`/manual-fix disposition remains possible. `UNAUTHORIZED` cards
+replace the primary question with
+`Should this unrequested behavior become part of the current workflow?`, so
+removal and ratification are not presented as missing-feature choices.
+
+Reviewer tokens map to executable concern recommendations:
+
+- `fix` maps to `fix-now`; for `UNAUTHORIZED`, that means removal.
+- `accept` maps to `accept-into-spec`; for `UNAUTHORIZED`, that means ratification.
+- `rescope` maps to `rescope-into-spec` and is invalid for `UNAUTHORIZED`.
+- `follow-up` may replace an unavailable `fix-now`/`rescope-into-spec` **only**
+  when the concern remains valid, has separate ownership, and the issue-tracker
+  action is executable.
+
+The orchestrator may choose another named disposition only when current evidence
+supports its stated effect. If no named executable disposition is available, the
+concern serializes `recommended: none` - the durable state for "no named
+executable choice exists" - and its `rationale` must name the exact missing
+prerequisites plus the concrete custom effect still required. `custom` is never
+auto-recommended, so `none` never silently resolves to `custom`.
+
+A concern with `recommended: none` is excluded from the recommended set. Before
+any exhaustive `Apply recommended set`, the finish gate asks for a targeted
+custom approval that supplies a concrete effect for that one concern (finishing
+owns the exact reply syntax - a per-item `custom(...)` decision - not an `apply
+recommended` variant). That reply approves only that concrete custom effect for
+that concern. Validate and normalize it immediately: if the effect is ambiguous or
+unexecutable, clarify and keep the concern open; if executable, record it as a
+**pending approved custom decision** and remove that concern from the still-open
+inventory used to build the recommended set. If other open concerns remain,
+render the exhaustive recommended set for them and visibly carry the pending
+approved custom decision through the existing action-order and freshness
+barriers; `apply recommended` approves only the remaining recommendations. If no
+other concerns remain, execute the approved custom directly through the existing
+mechanics. The final disposition record keeps this concern as a `custom` result;
+never relabel it as a model recommendation.
+
+**Never recommend an unavailable disposition or an unexecutable `custom`
+placeholder.**
+
+`revert` is a separate action, not a generic concern disposition. The commit
+index stays gap-granular (`conformance fix Gn`). A listed gap-level commit makes
+revert visible on every concern card under that gap, with an explicit warning
+that the **entire gap commit** is reverted. Existing light-revert semantics
+remain: revert the indexed commit, re-audit, and return to the decision gate
+only if a concern remains open.
+
 ## 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.
+(`CONFORMS`) or carried OPEN as a deferred gap - `accept`/`rescope`/`UNAUTHORIZED`,
+or a `recommended: fix` gap carried open because a declared fix-loop precondition
+was unavailable so the loop never started (`maxFixRounds: 0`, or no eligible
+named-branch worktree - normal checkout / detached HEAD). Escalation - a started
+positive-cap loop that exhausted its rounds or blocked/failed with an open `fix`
+gap - is the one non-completing terminal state; the precondition-unavailable
+carried-open `fix` state is valid closure inventory, not escalation.
+
+### Handoff sentinel and freshness anchor - every handoff
+
+Every `## Closure / conformance` block - a `CONFORMS` no-card handoff and a
+carried-open GAPS handoff alike - **opens with a two-line sentinel** that lets
+the finish gate re-verify freshness after context pruning, with no session
+history:
+
+```text
+status: CONFORMS (0 open)      # or: status: GAPS (N open)
+audited-base: <full HEAD SHA at audit time>
+```
 
-For each carried-open gap:
+`N` = count of open concerns (decision units), matching the number of emitted
+concern cards. Record `audited-base` as the full 40-char HEAD SHA at audit time;
+never abbreviate. This block is the **single source** for the freshness rule;
+`finishing-a-development-branch` links here rather than restating it.
 
+**Freshness rule.** The audit-input rule requires deliverables committed before
+auditing, so `audited-base` captures the audited state; freshness compares that
+commit to the **current working tree**, not to HEAD (a commit-to-commit diff
+misses staged/unstaged edits when HEAD has not moved). Run two cheap commands:
+
+```bash
+ROOT=$(git rev-parse --show-toplevel)
+git -C "$ROOT" diff --stat <audited-base> -- .          # tracked changes since the audited commit (staged + unstaged)
+git -C "$ROOT" status --porcelain --untracked-files=all # new/untracked deliverables
 ```
-Gn: <verdict> — recommended: <fix|accept|rescope> — touched-files: <paths>
+
+Any output from either command, any doubt, a missing/mismatched sentinel, or any
+closure block not opening with the two-line sentinel above (e.g. a legacy
+`Gn: PARTIAL - recommended: ...` row) triggers a fresh audit - never infer
+`CONFORMS` from the absence of cards. This is a lightweight freshness check (two
+git commands, no hashing or identity fields).
+
+**Sentinel validation.** `status: CONFORMS` requires `N = 0` and **no** emitted
+concern cards; `status: GAPS` requires `N > 0` exactly matching the emitted card
+count (`Gn/Cn` blocks), not merely gap headers. A mismatch is stale -> re-audit.
+
+**Audit-time input rule.** Stage or commit untracked deliverables before
+auditing, since `git diff <base> -- .` omits untracked files from the reviewer
+payload.
+
+For each carried-open gap, emit a durable gap header plus one card per concern
+(decomposition and derivation rules above). In rendered cards, recommendation
+lists, clarification lists, and final disposition records, every user-facing
+identifier carries both its ID **and** title; bare `Gn`/`Cn` or grouped
+identifier lists without titles are prohibited. The only exceptions are the
+machine/interaction tokens the grammar requires: bare `Gn/Cn` inside typed
+response tokens, the literal `conformance fix Gn` commit/action identifiers, and
+the flat `auto-applied fix commits` index below. The surrounding prompt or list
+must map each token to its titled concern or gap before asking for input.
+
+```text
+G1 - Source-image validation is incomplete
+  verdict: PARTIAL
+  origin: <requirement source and clause>
+  evidence: <current file:line or observed state>
+  blocker: <specific blocker, or none>
+  touched-files: <paths or unknown>
+  touched-resources: <resources or none>
   round history: R1 <verdict/action>, R2 <verdict/action>, ...
+
+  G1/C1 - End-to-end OCR output has not been validated
+    unresolved: <plain statement of the concern>
+    impact: <why it matters to the current workflow>
+    origin: <requirement source and clause, narrowed from the gap origin; or none (scope creep) for UNAUTHORIZED>
+    remediation: <concern-scoped remediation action>
+    evidence: <concern-specific evidence or blocker>
+    touched-files: <concern-scoped paths, narrowed from the gap; or unknown>
+    touched-resources: <concern-scoped resources, narrowed from the gap; or none>
+    available dispositions:
+      fix-now: <effect and availability>
+      accept-into-spec: <effect and availability>
+      rescope-into-spec: <effect and availability>
+      follow-up: <effect and availability>
+      custom: <effect and availability>
+    recommended: <available named disposition, or none>
+    rationale: <why this is the best current choice; for none, the missing prerequisites and the concrete custom effect required>
 ```
 
+All concerns in a gap must be represented.
+
 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
+(a closed gap has no card above, so its commit lives only here) — since the
 finish gate's revert option needs them all:
 
 ```
 auto-applied fix commits: <Gn: SHA>, <Gm: SHA>, ... (revertable)
 ```
 
+## Concern-scoped fix projection
+
+When the finish gate selects `fix-now` on some concerns of a gap, the fix loop
+above runs against a **projected** contract, not the original whole-gap block.
+For each parent gap with selected `fix-now` concerns, project only those
+concerns into one gap-scoped fix contract:
+
+- The parent gap ID.
+- The selected concern IDs and titles.
+- Their origin clauses, concern remediations, and evidence.
+- The **union** of the selected concerns' touched files/resources (ownership
+  boundary).
+
+Rescoped, accepted, and followed-up sibling concerns are **excluded** from the
+projection. The `implementer` and the pre-integration `spec-reviewer` receive
+this projected contract in place of the original whole-gap block.
+
+The projected task runs the existing full loop above: it retains the gap-level
+`conformance fix Gn` commit name, reruns the project's tests, runs
+`code-reviewer`, re-audits against the amended spec, and reenters the gate only
+if concerns remain. Gap-level revert stays available through the flat commit
+index. The gate records the final result by concern ID and title before showing
+branch integration options.
+
 ## Checklist
 
 - [ ] Located canonical requirements (spec → prompt → ticket fallback)