pi-gauntlet 5.16.1 → 5.16.2

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## v5.16.2 - 2026-09-22
+
+- gatekeep-pr: `SKILL.md` is a flow-ordered body under 250 lines; the assessment phases, finding IDs and dispositions, consent table and courses, and the post-selection loop move to `skills/gatekeep-pr/reference/{assessment,findings,decision-menu,post-selection-loop}.md`, each rule owned once. The CI telemetry-salvage probe reads `reference/post-selection-loop.md`. (#43)
+
 ## v5.16.1 - 2026-09-20
 
 - gauntlet-handoff follows the shipped pi-cohort 7.1.0 `handoff` skill: a skill cannot expand `/skill:handoff`, so step 2 reads cohort's `skills/handoff/SKILL.md` from the session skill list and follows its procedure; the brief path comes from cohort's `Handoff written:` report line (`Handoff not written:` is a STOP) instead of being recomputed; the minimum is stated as pi-cohort >= 7.1.0 in README and the brief contract. (#40)

package/package.json

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

package/skills/gatekeep-pr/SKILL.md

@@ -9,19 +9,19 @@ argument-hint: "<pr> [issue-ref]  (e.g. 123, or 123 gh-45)"
 
 Verify, don't trust. A PR description is a claim, not proof: over-claimed coverage,
 hallucinated references, and "tests pass" that were never rerun are the normal case,
-not the exception - especially on generated code. This skill gathers evidence, accepts green CI on the exact assessed head as
-verification evidence (running the project's own verification command only as
-the fallback), reviews the diff against a rubric, and
-presents a deterministic, authorship-aware menu. Authorship sets which row carries
+not the exception - especially on generated code. Gather evidence, accept green CI on
+the exact assessed head as verification evidence (run the project's own verification
+command only as the fallback), review the diff against a rubric, and present a
+deterministic, authorship-aware menu. Authorship sets which row carries
 `[recommended]`; it never changes which rows are offered.
 
-**Consent gate.** The only actions this skill performs before you pick a menu row are:
+**Consent gate.** The only actions performed before a menu row is picked are:
 read-only gathering, provisioning the worktree, and applying uncommitted, worktree-local
 doc-drift fixes discovered as a blocking finding. Every other action - code fixes,
-pushes, reviews, comments, merges - happens only on your explicit selection.
+pushes, reviews, comments, merges - happens only on explicit selection.
 
 **Residual risk.** Running the verification command executes PR code with the
-operator's ambient credentials. There is no sandbox. Only run this skill against PRs
+operator's ambient credentials. There is no sandbox. Run this skill only against PRs
 you are willing to execute.
 
 ## Arguments
@@ -34,10 +34,10 @@ you are willing to execute.
 
 ## Configuration resolution
 
-Applied per concern, first match wins, evaluated unconditionally - never delegated to
+Apply per concern, first match wins, evaluated unconditionally - never delegated to
 a wrapper skill:
 
-1. **Repo root `REVIEW.md`** (rubric concerns only). Always wins over the shipped
+1. **Repo root `REVIEW.md`** (rubric concerns only). Wins over the shipped
    baseline and reviewer-persona defaults on any conflict.
 2. **Gauntlet overrides file** (3-location discovery, first found wins): the
    `## PR gate` section (verification command, `timeout minutes`, `requires credentials`, issue
@@ -46,8 +46,8 @@ a wrapper skill:
 3. **Repo documentation** - an explicitly documented command or tool (e.g. `AGENTS.md`'s
    canonical test entrypoint, a documented worktree wrapper, a documented tracker CLI,
    or documented merge policy/branch rules). Reading documentation is not inference.
-   Discovery-only: consumers are never told to add gatekeep-pr configuration here.
-4. **Ask the user.** Never guessed from lockfiles, file heuristics, or vibes.
+   Discovery-only: never tell consumers to add gatekeep-pr configuration here.
+4. **Ask the user.** Never guess from lockfiles, file heuristics, or vibes.
 
 The `## PR gate` overrides schema (all keys optional except the verification command,
 which is required unless documented elsewhere):
@@ -70,7 +70,7 @@ in the repo's `REVIEW.md` (rubric) and the gauntlet overrides file's `## PR gate
 section (everything else); anything a wrapper carries beyond trigger phrases is
 misplaced and belongs in one of those two homes instead.
 
-All of the above is read from the **merge-base of the PR's base branch**, never from
+Read the ladder from the **merge-base of the PR's base branch**, never from
 the PR's head tree - a PR cannot weaken its own rubric or swap the command that will
 gate it. Recipe: `MB=$(git merge-base origin/<baseRefName> <headRefOid>)`, then for
 each ladder source `git show "$MB:<path>"` (e.g. `git show "$MB:REVIEW.md"`,
@@ -89,154 +89,17 @@ Use `plan_tracker`, never `phase_tracker`. Init with the first four stages:
 Verifier enumerates them and record each verdict: a matched claim ->
 `complete`, a contradicted claim -> `failed` (shown crossed, error color).
 Once every claim is terminal and `claim-check` is closed, `add` `review` and
-`consent menu` and continue. Stages are never inited ahead of the claims:
-the tracker rejects a verdict recorded behind a still-pending stage. A
+`consent menu` and continue. Never init stages ahead of the claims: the
+tracker rejects a verdict recorded behind a still-pending stage. A
 failed stage or claim stays `failed` while the skill stops at the menu -
 never marked complete to move on. On a harness without the `plan_tracker`
 tool: fall back to a plain checklist (or skip if none is available);
 functionality is unchanged either way.
 
-## Assessment
-
-Four phases, run in order, read-only through Phase 3:
-
-**Phase 1 - Gather.** Run verification-brief.md Section A in full: the fixed `gh`
-command set (`gh pr view`, `gh api user`, `gh pr diff`, both paginated comment
-endpoints, review threads, issue fetch, `git worktree list --porcelain` for
-discovery only), producing the normative gather digest.
-
-**Phase 2 - Provision worktree** (the orchestrator's mutation - a state machine):
-
-- A worktree already exists on the expected branch (`headRefName` for in-repo PRs,
-  a fork-local `pr-<N>` branch for fork PRs), at any path -> reuse it unconditionally.
-  In-repo PRs: `git fetch origin` + `git pull --ff-only` (the local branch tracks
-  `origin/<headRefName>`). Fork PRs: the local `pr-<N>` branch has no upstream, so
-  sync with `git fetch origin pull/<N>/head` + `git merge --ff-only FETCH_HEAD`
-  instead. Either way, on divergence, dirt, or local-only commits -> STOP and surface.
-  Never force, never create a duplicate.
-- The default path `.worktrees/pr-<N>` exists but holds a different branch -> STOP
-  and surface; never repurpose.
-- Nothing exists -> create at `.worktrees/pr-<N>` (an overrides worktree wrapper may
-  relocate it), following `using-git-worktrees` conventions (gitignore-first). In-repo
-  PRs: `git fetch origin` + `git worktree add .worktrees/pr-<N> <headRefName>`. Fork
-  PRs: `git fetch origin pull/<N>/head:pr-<N>` first, then add on that local branch.
-  Verify post-checkout that HEAD == the digest's `headRefOid`.
-
-Record create-vs-reuse; it drives the non-merge teardown rule below.
-
-After provisioning, re-poll `mergeable` once (`gh pr view --json mergeable`) if Section
-A reported `UNKNOWN` - still `UNKNOWN` after this single re-poll is treated as not
-merge-ready and surfaced (see the merge preconditions below).
-
-**Phase 3 - Verify, then Review** (sequential, same worktree - deliberate: the
-verification command may write to the tree while the Reviewer reads it):
-
-- Run verification-brief.md Section B: resolve the verification evidence per its
-  Evidence resolution table (green exact-head CI is the default evidence); run
-  the resolved verification command only when the table selects a fallback or
-  opt-out row, under its safety contract - self-contained and non-interactive (no prompts; run under a
-  non-interactive environment), bounded by a timeout (default 15 minutes, `timeout
-  minutes` override) via the first available mechanism: the harness's own bash
-  timeout parameter, else the `timeout`/`gtimeout` CLI when installed, else a
-  background-and-kill fallback - then material-claim checking against the PR body.
-  After a local run, the orchestrator asserts tracked-only cleanliness (`git status --porcelain
-  --untracked-files=no` empty, equivalently `git diff --quiet && git diff --cached
-  --quiet`; HEAD unmoved) - untracked gate artifacts, including the Verifier's
-  `log_path`, are expected and do not fail this check as long as `log_path` sits
-  under a gitignored path inside the worktree. Any tracked change invalidates the
-  run - re-provision and re-run once.
-- Run verification-brief.md Section C: review the source behind the diff against the
-  merged rubric (shipped `review-baseline.md` overlaid by base-branch `REVIEW.md`),
-  triage existing comments. The Reviewer emits its native output format only - AC
-  coverage is not part of its contract.
-
-**Phase 4 - Integrate** (orchestrator):
-
-- **Provenance:** `worktree_root` matches the provisioned path, every `run_cwd` is
-  inside it, `head_sha` matches the digest's `headRefOid`. On mismatch, re-fetch the
-  PR head once and re-sync + re-run Phase 3 if it advanced; a second mismatch, or any
-  path mismatch, is treated as missing evidence - not merge-ready. The claim stated in output names its source. Local path: precisely "reproduced
-  locally under the project's documented verification command" - nothing
-  stronger; never worded to imply a deployed, staging, or CI environment.
-  CI path (`source: ci`): precisely
-  `verified by CI: <check name(s)> succeeded on <sha> (run <url>)`
-  - never phrased as local reproduction, never implying the local command ran;
-  `<sha>` is the assessed `headRefOid`, `<url>` degrades to `unavailable` when
-  absent. Provenance checks on `worktree_root`/`run_cwd` bind only to the local
-  path.
-- **Telemetry record:** run `node <bin>/gauntlet-telemetry-salvage.mjs --worktree
-  <provisioned path> --base origin/<baseRefName> --check` (`<bin>` = `<directory of
-  this skill's SKILL.md>/../../bin`). Detect-only: it never mutates. `present` / `no
-  telemetry run` / `never written` land in `## Evidence` as one line each. `stripped
-  <path> in <sha>` mints a blocking `P#` (`source_ref`:
-  `gauntlet-telemetry-salvage`) whose drafted fix is "run the salvage without
-  `--check`" - the spec and its telemetry record are deliverables that ship in the
-  squash. On a cell with no push row (fork overlay, report-only states) the same
-  finding is a non-blocking follow-up instead: the record stays recoverable from the
-  PR head ref after merge, and blocking would stop a ship the gate cannot repair.
-  `unfinished <path>` (record still `in_progress` with no ship phase) also lands in `## Evidence` as one line and is non-blocking: pre-landing `in_progress` is normal, and the merge course's salvage run stamps it.
-- **Evidence:** On the CI path, list each satisfying check's name, conclusion, assessed SHA, and run URL - there is no command or raw_tail to paste. On the local path, paste each run's `command` and `raw_tail` verbatim, fenced - never
-  paraphrased. Any authored summary is labeled as a summary and never substitutes for
-  `raw_tail`.
-- **Severity translation:** Critical -> blocking, Moderate -> blocking, Minor ->
-  non-blocking follow-up. A repo `REVIEW.md` severity mapping overrides this; any
-  severity it names but does not map is fail-safe **blocking**, noted in the output.
-- **AC coverage:** the orchestrator computes `met` / `partial` / `missing` per
-  acceptance criterion from the issue's ACs, the diff, and the Reviewer's findings -
-  it is an integration product, not raw persona output. Only `met` is merge-ready;
-  `partial` or `missing` is blocking. Skipped entirely when no issue is linked.
-- **Claims:** a failed local gate is a hard merge failure. A `contradicted` material
-  claim is a blocking finding. An `unverifiable-pre-merge` claim used as merge proof
-  (appears in the PR body's evidence/result/test-plan content) is blocking; stated as
-  an explicit post-merge observation instead, it is a non-blocking follow-up.
-- **CI checks:** any blocking conclusion in the resolved check set (required or
-  not - see the brief's Evidence resolution table) withholds merge from every
-  pre-composed course until the user explicitly dispositions it, and mints a
-  `P#`. Three dispositions: **flaky** (proceed via the custom row), **real** (it
-  blocks until green), **CI-infrastructure-broken** (the checks themselves are
-  untrustworthy: triggers the fallback local run, and merge stays withheld until
-  that fallback produces green evidence). A **pending** required check (still
-  running - the normal case, not a defect) is **wait-until-green, not
-  dispositionable**: it mints no `P#`, is never dispositioned, and the withhold
-  auto-lifts the moment it turns green - or, if it instead fails, converts into
-  an undispositioned failing check with its own `P#` at that point. While
-  pending, the report notes it under Evidence and every merge course simply does
-  not render (a pending-only PR is not a blocking verdict - findings groups can
-  all read "None" - the recommended course falls to `stop` or `review-comment`,
-  never a merge course, until it resolves). The evidence decision is
-  independent: a green check elsewhere in the resolved set still satisfies
-  verification evidence while a pending required check withholds merge. The
-  CI-sufficient path changes no consent surface: still read-only, no auto-merge,
-  no posting, no menu change beyond the third disposition.
-- **Doc drift:** when the review finds committed doc drift as a **blocking** finding,
-  the orchestrator applies the doc fixes itself, in the provisioned worktree (created
-  or reused), as part of assessment - real edits, uncommitted, worktree-local. The
-  result is presented in `## Findings`, the edits themselves under
-  `## Drafted fixes / review`. Pushing them is a separate, later menu selection.
-  Follow-ups alone never trigger doc fixes - only blocking drift does.
-
-## Inline-first execution
-
-> This section is an optional optimization. Delete it and the rest of the skill still
-> works: the orchestrator can run every phase above itself, inline, with no subagent
-> system.
-
-The inline path is primary: the orchestrator runs the brief's sections itself, in
-order, self-contained. When pi-cohort is available, delegation is an optimization
-layered on top, never a hard dependency:
-
-- **Gatherer** -> `scout` builtin, as a prior sync run producing the gather digest.
-- **Verifier** -> `worker` builtin, dispatched with the report-only constraint
-  prepended to its task ("report only - do not edit, fix, or commit anything").
-- **Reviewer** -> the existing `code-reviewer` agent, emitting its native output
-  format (never overridden at call time).
-
-Verifier and Reviewer share the provisioned worktree via `cwd`, dispatched
-**sequentially** (Verify before Review, per Phase 3) - never `worktree: true`, which
-would provision a separate isolated worktree and break the shared-tree contract this
-skill depends on. A subagent that fails, or violates its section's output schema, is
-re-dispatched once demanding the schema; a second failure means that section runs
-inline instead.
+## Assess
+
+Run four phases in order - gather, provision worktree, verify then review, integrate.
+Read `reference/assessment.md` and `reference/findings.md` now.
 
 ## Verdict
 
@@ -245,42 +108,23 @@ merge-proof unverifiable claim, `partial`/`missing` AC coverage, scope creep whe
 issue is linked, committed doc drift, anything the merged rubric maps to blocking),
 **follow-ups only** (never gate merge), or **clean**.
 
-**Merge preconditions** (all must hold): gate green with every blocking finding fixed,
-not deferred; verification evidence present per the brief's Evidence resolution table (a CI claim or a green local run - a table-sanctioned CI skip is evidence, not missing "not run" evidence; result: not run blocks only when the table required a fallback run that didn't happen); `mergeable == MERGEABLE` (`UNKNOWN` after the one post-provision
-re-poll withholds merge, same as `CONFLICTING`); no undispositioned failing check in
-the resolved set, no pending required check; evidence pasted with clean provenance; worktree clean and synced with the remote
-head (fixes pushed first); explicit selection with a head compare-and-swap that
-passes. A merge selection while any precondition fails is refused, naming the failing
-precondition, and the menu re-renders - never a dead end, never a silent merge. Merge
-always executes as `gh pr merge --match-head-commit <assessed-sha>`; push and merge
-are never bundled into one selection, with one scoped exception: the selected merge
-course first runs `node <bin>/gauntlet-telemetry-salvage.mjs --worktree <provisioned
-path> --base origin/<baseRefName>` (no `--check`). `present` -> merge as-is. `restored
-<path> from <sha>` -> push that single `telemetry: restore` commit as part of this
-course, re-fetch `headRefOid`, and pass the new SHA to `--match-head-commit`. A line ending `(marked shipped)` (`present` or `restored`) is handled the same way: push that single `telemetry:` commit, re-fetch `headRefOid`, pass the new SHA. `restore
-failed` -> merge proceeds, the reason is printed, and the follow-up names recovery
-from the PR head ref.
-
-**Consent menu** (deterministic - this table is the golden-scenario oracle):
-
-| Author | State | Offered rows (first = `[recommended]`) |
-|---|---|---|
-| you | clean / follow-ups only | merge (squash); merge (merge-commit); do not merge (leave it); post no-blockers comment |
-| you | blocking | apply code fixes (named finding subset): skill edits in worktree, commits, re-runs gate, pushes - then merge re-offered; push applied doc fixes; do not act; post review-comment of findings |
-| someone else | clean / follow-ups only | approve; merge (squash, offered-unrecommended); post no-blockers comment |
-| someone else | blocking | post request-changes review; apply fixes on their branch (courtesy option 2); reply to existing threads; post comment |
-| bot author | any | someone-else's rows for the same state, review actions recommended |
-| fork (any) | any | post review (request-changes / comment / approve per state) - push and merge rows absent |
-| any | draft PR | assessment rows only; merge and approve rows absent until ready-for-review |
-| any | merged / closed | report-only; no mutation rows |
-
-The consent table above remains the single oracle for what may be offered; the
-Decision rendering section defines how its rows render as actions and numbered
-courses. Rows GitHub would refuse (branch protection, missing permissions,
-`viewerPermission` too low) are listed as unavailable with the reason. Approving
-your own PR is not offered. Nothing executes until explicit selection.
-
-## Output
+**Merge preconditions** (all must hold):
+
+- gate green with every blocking finding fixed, not deferred
+- verification evidence present per the brief's Evidence resolution table (a CI claim
+  or a green local run - a table-sanctioned CI skip is evidence, not missing;
+  "not run" blocks only when the table required a fallback run that didn't happen)
+- `mergeable == MERGEABLE` (`UNKNOWN` after the one post-provision re-poll withholds
+  merge, same as `CONFLICTING`)
+- no undispositioned failing check in the resolved set, no pending required check
+- evidence pasted with clean provenance
+- worktree clean and synced with the remote head (fixes pushed first)
+- explicit selection with a head compare-and-swap that passes
+
+Define `<bin>` = `<directory of this skill's SKILL.md>/../../bin`. Merge execution
+per `reference/post-selection-loop.md` `### Merge course`.
+
+## Report
 
 The rendered report is terse by design: deciding factor, evidence lines, ID'd
 findings, menu. No restating diffs, no narration, no recap prose.
@@ -305,238 +149,23 @@ Requirement/doc drift (linked issue, committed doc drift, or spec conflict):
   F1. **<source_ref>** - <action>. Owner: <pr-author | tracker | human>
 
 ## Decision
-<action vocabulary + numbered courses - see Decision rendering>
+<action vocabulary + numbered courses>
 
 ## Drafted fixes / review
 <payloads, each keyed by its finding ID>
 ```
 
-**ID rules:**
-
-- `<source_ref>` is a `file:line` where one exists, else the disputed thing (a
-  quoted PR-body claim, a failing gate command, a required check name).
-- **Precedence:** Phase 4 and the merged rubric decide blocking vs. follow-up (the
-  severity translation, AC coverage, claims, and required-check rules above); this
-  section only chooses **which namespace** (`P#` / `L#` / `F#`) renders that
-  decision. Category tags and the triage bar below never override an upstream
-  blocking classification - a Phase-4 Moderate is always blocking (`P#` or `L#`
-  per Total mapping), never demoted to `F#` by tag or by judgment call.
-- **Total mapping:** every blocking element of the Verdict maps to a `P#` or `L#` -
-  a blocking verdict with "None" in both groups is a rendering bug. Concretely:
-  failed gate -> `P#` `[test]` referencing the gate command; contradicted or
-  merge-proof-unverifiable material claim -> `P#` `[spec]` referencing the claim;
-  scope creep with a linked issue -> `L#` `spec-conflict`; committed doc drift ->
-  `L#` `doc-drift`; `partial` AC coverage -> `L#` `outdated-AC`; `missing` AC
-  coverage -> `L#` `missing-behavior`. `L#` covers exactly the drift the Verdict
-  already blocks on (committed doc drift, AC coverage, spec conflict); it widens
-  nothing. Code-level spec bugs (the diff contradicts the spec) are `P#` `[spec]`;
-  requirement/doc mismatches (the spec or docs are stale relative to intent) are
-  `L#`.
-- **Failing checks close by disposition, not by fix:** an undispositioned failing check in the resolved set
-  is `P#` `[test]` referencing the check name; it is never a target
-  of a worktree `fix`. The user's Phase-4 disposition annotates the same ID rather
-  than closing it outright: dispositioned **flaky** -> annotate
-  `(dispositioned: flaky)`; this annotation excepts the `P#` from the unfixed-blocker
-  set - it no longer counts against "every `P#` blocks" or the merge precondition
-  "every blocking finding fixed", and the merge path is Phase 4's explicit flaky
-  disposition via the custom row. Dispositioned **real** -> annotate
-  `(dispositioned: real)` and the `P#` keeps blocking until the check is green.
-  Dispositioned **CI-infrastructure-broken** -> annotate
-  `(dispositioned: ci-infrastructure-broken)`; the fallback local run executes,
-  and the `P#` keeps blocking until that fallback is green.
-- **Severity is decided at triage, not by the category tag:** a finding lands in
-  `P#` only when it must be fixed before merge (correctness, security, material
-  performance trap, a convention the repo enforces); improvements that don't
-  change merge correctness are `F#`, whatever their category. `[quality]` on a
-  `P#` is a category, never a downgrade - every `P#` blocks. This triage bar governs
-  findings the orchestrator originates itself; it never re-triages a classification
-  Phase 4 already made (see Precedence above).
-- `C#` replies are verdict-neutral drafts: they never block and never gate merge;
-  nothing posts until selected.
-- `F#` items carry an owner so follow-ups don't evaporate; when no tracker tool
-  resolved, the report itself is their durable home.
-- **IDs are append-only for the run's lifetime:** minted at first assessment,
-  never renumbered, never reused. A resolved finding keeps its ID annotated
-  `(fixed in <sha>)`; later rounds continue each namespace's sequence.
-- Empty groups say "None".
-
-"Drafted fixes / review" holds, per finding ID, the concrete edit (for `fix`), the
-reviewed doc-drift edit (for `push-docs`, keyed to its `L#`), or the reply text
-(for `reply`) - each keyed to its finding ID, one selection mapping 1:1 to its
-payload. A posted review body is not itself a finding: it is composed at post time
-from the ID'd `P#`/`L#` findings being addressed - one summary sentence, then the
-numbered findings, ending on the fix or asked action - and occupies its own
-non-finding slot of this section.
-
-## Decision rendering
-
-`## Decision` has two parts: the action vocabulary, then the numbered courses.
-
-**Action vocabulary** (bare verbs; availability constraints inline):
-
-```markdown
-Actions (compose freely in the custom row):
-  fix <P#s|all>    apply blocking fixes in worktree, re-run gate, push  (in-repo PRs only)
-  push-docs        push already-applied doc-drift edits                 (only when uncommitted
-                                                                        reviewed doc edits exist
-                                                                        in the worktree)
-  merge-squash | merge-commit                                          (preconditions per Verdict;
-                                                                        never bundled with a push,
-                                                                        except the telemetry: restore commit)
-  request-changes | review-comment | approve                           (approve: never own PR)
-  reply <C#s>      post drafted thread replies
-  tracker <act>    tracker action                                      (only when a tracker tool resolved)
-  stop             leave the PR as-is / report-only exit
-```
-
-A `+ tracker <act>` suffix is available on any mutation course when a tracker tool
-resolved.
-
-**Selection grammar:** ID sets accept `all`, ranges (`P1-P4`), comma lists
-(`P1,P3`), and exclusions (`all but P2`).
-
-**Numbered courses** - a normative rendering of the consent table (never a second
-offer source): per author x state cell, exactly one `[recommended]` course first,
-the custom row always last. Courses are **atomic across pushes**: no course,
-pre-composed or custom, bundles a push-producing action (`fix`, `push-docs`) with
-`merge-*`; after a fix wave the menu re-renders with merge as row 1.
-
-| Author | State | Courses (first = `[recommended]`) |
-|---|---|---|
-| you | clean / follow-ups only | 1. merge-squash; 2. merge-commit; 3. stop; 4. review-comment (post no-blockers note) |
-| you | blocking | 1. fix (worktree-fixable P#s only - `all` covers only those) [+ push-docs when uncommitted doc edits exist]; 2. push-docs (alone, when doc edits exist); 3. stop; 4. review-comment (post findings). When no P# is worktree-fixable (blocking is failing-check-only or L#-only), course 1 (fix) is not rendered: push-docs becomes first when doc edits exist, else stop is first |
-| you | blocking, post-fix re-render (gate green, preconditions hold) | 1. merge-squash; 2. merge-commit; 3. stop; 4. review-comment |
-| someone else | clean / follow-ups only | 1. approve; 2. merge-squash (offered-unrecommended); 3. review-comment (no-blockers note) |
-| someone else | blocking | 1. request-changes; 2. fix all (courtesy, their branch - omitted when nothing is worktree-fixable); 3. reply <C#s> (omitted when the `C#` group is None); 4. review-comment |
-| bot author | any | someone-else's rows for the same state; review actions recommended |
-| any | draft | 1. request-changes / review-comment / reply <C#s> (omit the reply course when the `C#` group is None) / stop - `[recommended]` follows the same authorship rule as the non-draft cells, **except** on your own draft PR `request-changes` is never recommended (you cannot request changes on your own PR any more than you can approve it); the fallback recommendation there is `review-comment` when findings exist, else `stop`. Custom present but cannot compose `merge-*`/`approve`/`fix`/`push-docs` until ready-for-review |
-| any | merged / closed | 1. stop; report-only, no other mutation courses at all; Custom present but cannot compose `merge-*`/`approve`/`fix`/`push-docs`/`request-changes`/`review-comment`/`reply`/`tracker` - nothing remains actionable |
-
-**Fork overlay:** the consent-table fork row renders as an overlay on the authorship
-cells (push/merge/fix absent; approve also dropped when the viewer authored the PR) -
-it is not a distinct authorship cell. It overlays whichever authorship row above
-applies (you vs. someone else), removing `fix`, `push-docs`, and `merge-*` (never
-available on a fork). When you authored the fork PR, `approve` is
-also dropped (never offered on your own PR) - fork|you|clean renders
-`review-comment`/`stop` only; fork|you|blocking renders
-`request-changes`/`review-comment`/`stop` (the someone-else courtesy fix-on-their-
-branch course is also absent, since it is your own PR). A fork PR authored by someone
-else uses the someone-else cells above with `fix`/`push-docs`/`merge-*` removed.
-
-**CI-check gate on merge courses:** an undispositioned failing check in the resolved
-set, or a pending **required** check, withholds every pre-composed course containing `merge-*` (per the
-Verdict merge preconditions) - none render, whatever the author/state cell says. A
-pending check mints no `P#` and is wait-until-green, not dispositionable (see Phase
-4); a failing one mints a `P#` and takes a disposition (flaky / real / CI-infrastructure-broken). A **flaky** disposition does
-not restore merge to a pre-composed course; merge proceeds only via the custom row
-naming the disposition explicitly. A **real** disposition, or an unresolved pending
-check, keeps every merge course withheld until the check is green; a **CI-infrastructure-broken** disposition keeps them withheld until the triggered fallback run is green - a pending-only
-render is not itself a blocking verdict (findings groups may all read "None"); the
-recommended course falls to `stop` or `review-comment` in the meantime. This never
-falls through to the clean cell's recommended `merge-squash` - a failing resolved-set
-check or a pending required check means the PR is not in the clean state to begin with.
-
-Rows a cell offers but GitHub would refuse (branch protection, missing permission)
-render listed-but-unavailable with the reason. Zero mutation courses is a legal
-render (merged/closed) - the menu still appears, carrying findings and `stop`.
-
-Example render (golden fixture 1 - own PR, blocking findings including committed doc
-drift, so uncommitted reviewed doc edits exist):
+Consent table and courses per `reference/decision-menu.md`.
 
-```markdown
-Pick one:
-  1. fix all (P1-P10) + push-docs   [recommended]
-  2. push-docs (docs only, hold code fixes)
-  3. stop (leave as-is)
-  4. review-comment (post findings, act later)
-  5. Custom - compose: e.g. "fix P1-P8,P10 + push-docs" or "reply C1 + tracker comment"
-```
+## Decide
 
-Golden fixture 2 - the post-fix re-render after course 1's gate re-run passes:
+Render `## Decision` from the consent table for the PR's author and state. Read
+`reference/decision-menu.md` now.
 
-```markdown
-Pick one:
-  1. merge-squash   [recommended]
-  2. merge-commit
-  3. stop (leave as-is)
-  4. review-comment
-  5. Custom
-```
+## Act
 
-## Post-selection loop
-
-The menu is a state machine, not a one-shot report:
-
-1. **Compare-and-swap before every external write:** re-fetch `headRefOid`, `state`,
-   `mergeable`. Any change since assessment invalidates the current state - re-sync
-   the worktree, re-run Phase 3, re-render the menu. **Exception:** a course's own
-   push updates the assessed head to the pushed SHA as part of that course's
-   execution - this self-inflicted head move does not invalidate the course; the
-   next CAS check runs against the new head on the next external write.
-2. Execute only the selected course. **Fix wave** (`fix <set>`): first filter the
-   selected set to worktree-fixable `P#`s - drop any `P#` closed by disposition
-   (an undispositioned failing-check `P#` is never a `fix` target; a **flaky**
-   disposition already excepts it) - and route file-less `P#`s (a claim or a gate
-   command as `source_ref`, no draft touching a file) to run inline/sequentially,
-   never as part of a parallel file-batch.
-
-   For the remaining worktree-fixable set, batch by the **union of files each
-   finding's drafted edit in `## Drafted fixes / review` touches** (fallback to
-   the `source_ref` file only when a finding has no draft) - findings whose
-   drafts share a file share a batch.
-
-   **Child contract (same for 1 batch or many):** children are `implementer`
-   dispatches - `subagent({ agent: "implementer", context: "fresh", cwd: <PR
-   worktree> })`, matching Inline-first execution's persona-naming style; this is
-   the pi-cohort optimization path, inline is always valid per that section. The
-   orchestrator owns commit, gate, and push - never a child. Every dispatched
-   child gets `cwd` = the PR worktree, **`worktree: true` forbidden** (a separate
-   isolated worktree breaks the shared-tree contract - see Inline-first
-   execution); is **edit-only, no git commands, no verification runs**, and must
-   never delete `.pi/gauntlet/telemetry/**` or anything under the configured
-   telemetry dir (a fix that "cleans up" the run's telemetry record is a defect in
-   the fix - the record is a deliverable); and its task is that batch's `P#` lines
-   **plus the drafted edit already keyed to each
-   ID** in `## Drafted fixes / review` - the child applies the consented payload,
-   it does not re-solve the finding. Below the cutoff (<= 2 worktree-fixable findings), the orchestrator
-   applies inline instead of dispatching - the no-cohort path stays available at
-   any batch count per Inline-first execution. Above the cutoff, when more than
-   one batch results, dispatch the batches' children **in parallel**, all under
-   the same contract.
-
-   Once every dispatched/inline batch returns, the orchestrator commits the golden
-   course as one local commit set - the code fixes plus any already-applied
-   reviewed doc edits selected alongside them (one commit, or one per batch
-   sequentially; subjects name the fixes) - then re-resolves the evidence for the new head **once** (the brief's stale-head row: prior evidence is stale; the local command executes only on a fallback/opt-out resolution). Before the push, run
-   `node <bin>/gauntlet-telemetry-salvage.mjs --worktree <provisioned path> --base
-   origin/<baseRefName>` (no `--check`); a `restored` or `(marked shipped)` commit rides the wave's single
-   push and the pushed SHA becomes the assessed head under the course's-own-push rule
-   in step 1. Print its stdout in the re-rendered report's `## Evidence`. **On
-   green**, push **once**; gate and push are per-wave invariants, never per-fix or
-   per-batch. **On red**, do not push: leave the commit(s) local, re-render with
-   the unresolved `P#`s still open, and warn that unpushed fix commits sit in the
-   worktree exactly like unpushed doc edits (see Teardown). Doc fixes (`push-docs`
-   alone) follow the same green-gate-then-push rule: stage + commit (subject names
-   what is documented), re-run the gate, push only on green. Reviews, replies, and
-   tracker actions -> `gh pr review` / `gh api` / the tracker tool, non-interactive,
-   with the drafted payload for the selected IDs.
-3. After any mutation that can change readiness (fix wave pushed, docs pushed, PR
-   head moved), re-run the claim-check and Review on the synced worktree: claims
-   are re-checked against the new head and findings are re-rendered, but
-   the verification command itself is **not** re-executed here - step 2's evidence re-resolution
-   already was the wave's one and only gate pass. Re-render the report:
-   each selected `P#`/`L#` confirmed resolved is annotated `(fixed in <sha>)`
-   under its original ID; unresolved ones stay open unchanged; new findings
-   continue the sequence. Merge, if now available, renders as row 1.
-4. Loop until the user selects merge or an explicit stop/no-action row.
-
-**Teardown:** merge success -> tear down the worktree, whether it was reused or
-created (the sync precondition guarantees no local-only work is stranded, and the
-branch is gone remotely). A non-merge stop: offer teardown of a **created** worktree
-(never autonomous; warn if unpushed doc edits would be discarded); a **reused**
-worktree is left as found - if unpushed doc edits **or unpushed fix commits from a
-red-gate hold** remain in it, say so explicitly and let the user choose
-leave-or-discard.
+The menu is a state machine that loops until merge or an explicit stop. Read
+`reference/post-selection-loop.md` now.
 
 ## Output done-check
 
@@ -556,33 +185,21 @@ overrides file - see Project overrides.
 
 ## Red flags - STOP
 
-- Approving your own PR
-- Any mutation (fix, push, review, merge) without an explicit menu selection
-- Pasting paraphrased evidence instead of verbatim `raw_tail`
-- A provenance mismatch (worktree, `run_cwd`, or `head_sha`) noticed and ignored
-- Merging around an undispositioned blocking finding or failing-check `P#`
-- Reading configuration (rubric, verification command, or ladder sources) from the
-  PR's head instead of the base branch's merge-base
-- Renumbering or reusing a finding ID between menu rounds
-- Presenting findings without IDs, a blocking verdict with no `P#`/`L#`, or a
-  `## Decision` rendered without its action vocabulary
-- Treating `[quality]` or `[performance]` as a downgrade signal on a `P#` - only
-  an explicit Phase-4 flaky disposition excepts a failing-check `P#` from the
-  unfixed-blocker set, never a category tag
-- A course (pre-composed or custom) bundling a push-producing action with
-  `merge-*`
-- A pre-composed course, or a custom row, composing an action the overlay or the
-  cell lists as unavailable
-- Batching a file-less `P#` (a claim or a gate command as `source_ref`, no draft touching a file)
-  into a parallel dispatch - a claim `P#` with a drafted file edit is
-  worktree-fixable and may batch - dispatching parallel implementers over
-  batches that share a file, or letting a fix-wave child run git commands or a
-  verification pass in the shared worktree, or dispatching a fix-wave child with
-  `worktree: true`
-- A second execution of the verification command, a second push, or pushing fix
-  commits after a red gate, within one fix wave - re-running Verify/Review to
-  re-confirm claims and annotate IDs (step 3) is not a second gate execution
-- Posting or committing an external payload without the output done-check
+- Approving your own PR - owner: `reference/decision-menu.md` `## Consent table`
+- Any mutation (fix, push, review, merge) without an explicit menu selection - owner: **Consent gate** (intro)
+- Pasting paraphrased evidence instead of verbatim `raw_tail` - owner: `reference/assessment.md` `## Phase 4 - Integrate`
+- A provenance mismatch (worktree, `run_cwd`, or `head_sha`) noticed and ignored - owner: `reference/assessment.md` `## Phase 4 - Integrate`
+- Merging around an undispositioned blocking finding or failing-check `P#` - owner: `reference/findings.md` `## Dispositions`
+- Reading configuration (rubric, verification command, or ladder sources) from the PR's head instead of the base branch's merge-base - owner: `## Configuration resolution`
+- Renumbering or reusing a finding ID between menu rounds - owner: `reference/findings.md` `## IDs`
+- Presenting findings without IDs, or a blocking verdict with no `P#`/`L#` - owner: `reference/findings.md` `## IDs`
+- A `## Decision` rendered without its action vocabulary - owner: `reference/decision-menu.md` `## Actions`
+- Treating `[quality]` or `[performance]` as a downgrade signal on a `P#` - only an explicit Phase-4 flaky disposition excepts a failing-check `P#` from the unfixed-blocker set, never a category tag - owner: `reference/findings.md` `## Triage`
+- A course (pre-composed or custom) bundling a push-producing action with `merge-*` - owner: `reference/decision-menu.md` `## Courses`
+- A pre-composed course, or a custom row, composing an action the overlay or the cell lists as unavailable - owner: `reference/decision-menu.md` `## Fork overlay`
+- Batching a file-less `P#` (a claim or a gate command as `source_ref`, no draft touching a file) into a parallel dispatch - a claim `P#` with a drafted file edit is worktree-fixable and batches - dispatching parallel implementers over batches that share a file, or letting a fix-wave child run git commands or a verification pass in the shared worktree, or dispatching a fix-wave child with `worktree: true` - owner: `reference/post-selection-loop.md` `### Fix wave`
+- A second execution of the verification command, a second push, or pushing fix commits after a red gate, within one fix wave - re-running Verify/Review to re-confirm claims and annotate IDs is not a second gate execution - owner: `reference/post-selection-loop.md` `### Fix wave`
+- Posting or committing an external payload without the output done-check - owner: `## Output done-check`
 
 ## Project overrides
 

package/skills/gatekeep-pr/reference/assessment.md

@@ -0,0 +1,129 @@
+# gatekeep-pr: assessment
+
+Read from SKILL.md `## Assess`. Four phases run in order; Phases 1-3 are read-only.
+
+## Phase 1 - Gather
+
+Run `../verification-brief.md` Section A in full: the fixed `gh` command set
+(`gh pr view`, `gh api user`, `gh pr diff`, both paginated comment endpoints,
+review threads, issue fetch, `git worktree list --porcelain` for discovery
+only). It produces the normative gather digest.
+
+## Phase 2 - Provision worktree
+
+The orchestrator's mutation - a state machine.
+
+| State | In-repo PR | Fork PR | On divergence |
+|---|---|---|---|
+| A worktree exists on the expected branch (`headRefName` for in-repo PRs, a fork-local `pr-<N>` branch for fork PRs), at any path | Reuse unconditionally; sync with `git fetch origin` + `git pull --ff-only` (the local branch tracks `origin/<headRefName>`) | Reuse unconditionally; the local `pr-<N>` branch has no upstream - sync with `git fetch origin pull/<N>/head` + `git merge --ff-only FETCH_HEAD` | STOP and surface on divergence, dirt, or local-only commits; never force, never create a duplicate |
+| The default path `.worktrees/pr-<N>` exists but holds a different branch | STOP and surface; never repurpose | STOP and surface; never repurpose | - |
+| Nothing exists (an overrides worktree wrapper can relocate it, following `using-git-worktrees` conventions, gitignore-first) | Create at `.worktrees/pr-<N>`; `git fetch origin` + `git worktree add .worktrees/pr-<N> <headRefName>`; verify post-checkout that HEAD == the digest's `headRefOid` | Create at `.worktrees/pr-<N>`; `git fetch origin pull/<N>/head:pr-<N>` first, then add on that local branch; verify post-checkout that HEAD == the digest's `headRefOid` | - |
+
+Record create-vs-reuse; it drives the non-merge teardown rule in `post-selection-loop.md`
+`### Teardown`.
+
+After provisioning, re-poll `mergeable` once (`gh pr view --json mergeable`) when
+Section A reported `UNKNOWN`. Still `UNKNOWN` after this single re-poll is treated as
+not merge-ready and surfaced (merge preconditions per SKILL.md `## Verdict`).
+
+## Phase 3 - Verify, then review
+
+Sequential, same worktree - deliberate: the verification command can write to the tree
+while the Reviewer reads it.
+
+Run `../verification-brief.md` Section B: resolve the verification evidence per its
+Evidence resolution table (green exact-head CI is the default evidence). Run the
+resolved verification command only when the table selects a fallback or opt-out row,
+under its safety contract: self-contained and non-interactive (no prompts, under a
+non-interactive environment), bounded by a timeout (default 15 minutes, `timeout
+minutes` override) via the first available mechanism - the harness's own bash timeout
+parameter, else the `timeout`/`gtimeout` CLI when installed, else a background-and-kill
+fallback. Then check material claims against the PR body.
+
+After a local run, assert tracked-only cleanliness: `git status --porcelain
+--untracked-files=no` empty, equivalently `git diff --quiet && git diff --cached
+--quiet`; HEAD unmoved. Untracked gate artifacts, including the Verifier's `log_path`,
+are expected and do not fail this check as long as `log_path` sits under a gitignored
+path inside the worktree. Any tracked change invalidates the run: re-provision and
+re-run once.
+
+Run `../verification-brief.md` Section C: review the source behind the diff against
+the merged rubric - shipped `../review-baseline.md` overlaid by base-branch
+`REVIEW.md` - and triage existing comments. The Reviewer emits its native output
+format only; AC coverage is not part of its contract.
+
+## Phase 4 - Integrate
+
+Orchestrator step.
+
+- **Provenance:** `worktree_root` matches the provisioned path, every `run_cwd` sits
+  inside it, `head_sha` matches the digest's `headRefOid`. On mismatch, re-fetch the
+  PR head once and re-sync + re-run Phase 3 when it advanced; a second mismatch, or
+  any path mismatch, counts as missing evidence - not merge-ready. The claim stated
+  in output names its source. Local path: precisely "reproduced locally under the
+  project's documented verification command" - nothing stronger; never worded to
+  imply a deployed, staging, or CI environment. CI path (`source: ci`): precisely
+  `verified by CI: <check name(s)> succeeded on <sha> (run <url>)` - never phrased as
+  local reproduction, never implying the local command ran; `<sha>` is the assessed
+  `headRefOid`, `<url>` degrades to `unavailable` when absent. Provenance checks on
+  `worktree_root`/`run_cwd` bind only to the local path.
+- **Telemetry record:** run
+  `node <bin>/gauntlet-telemetry-salvage.mjs --worktree <provisioned path> --base
+  origin/<baseRefName> --check`. The `--check` flag makes the probe detect-only: it
+  never mutates. `present` / `no telemetry run` / `never written` land in
+  `## Evidence` as one line each. `stripped <path> in <sha>` mints a blocking `P#`
+  (`source_ref`: `gauntlet-telemetry-salvage`) whose drafted fix is "run the salvage
+  without `--check`" - the spec and its telemetry record are deliverables that ship
+  in the squash. On a cell with no push row (fork overlay, report-only states) the
+  same finding is a non-blocking follow-up instead: the record stays recoverable
+  from the PR head ref after merge, and blocking would stop a ship the gate cannot
+  repair. `unfinished <path>` (record still `in_progress` with no ship phase) also
+  lands in `## Evidence` as one line and is non-blocking: pre-landing `in_progress`
+  is normal, and the merge course's salvage run stamps it.
+- **Evidence:** on the CI path, list each satisfying check's name, conclusion,
+  assessed SHA, and run URL - there is no command or `raw_tail` to paste. On the
+  local path, paste each run's `command` and `raw_tail` verbatim, fenced - never
+  paraphrased. Any authored summary is labeled as a summary and never substitutes for
+  `raw_tail`.
+- **Severity translation:** Critical -> blocking, Moderate -> blocking, Minor ->
+  non-blocking follow-up. A repo `REVIEW.md` severity mapping overrides this; any
+  severity it names but does not map is fail-safe **blocking**, noted in the output.
+- **AC coverage:** the orchestrator computes `met` / `partial` / `missing` per
+  acceptance criterion from the issue's ACs, the diff, and the Reviewer's findings -
+  an integration product, not raw persona output. Only `met` is merge-ready;
+  `partial` or `missing` is blocking. Skip entirely when no issue is linked.
+- **Claims:** a failed local gate is a hard merge failure. A `contradicted` material
+  claim is a blocking finding. An `unverifiable-pre-merge` claim used as merge proof
+  (appears in the PR body's evidence/result/test-plan content) is blocking; stated as
+  an explicit post-merge observation instead, it is a non-blocking follow-up.
+- **CI checks:** disposition a failing or pending check per `findings.md`
+  `## Dispositions`.
+- **Doc drift:** when the review finds committed doc drift as a **blocking** finding,
+  apply the doc fixes in the provisioned worktree (created or reused), as part of
+  assessment - real edits, uncommitted, worktree-local. Present the result in
+  `## Findings`, the edits themselves under `## Drafted fixes / review`. Pushing them
+  is a separate, later menu selection. Follow-ups alone never trigger doc fixes; only
+  blocking drift does.
+
+## Inline-first execution
+
+> This section is an optional optimization. Delete it and the rest of the skill still
+> works: the orchestrator can run every phase in this file itself, inline, with no
+> subagent system.
+
+The inline path is primary: the orchestrator runs the brief's sections itself, in
+order, self-contained. When pi-cohort is available, delegation is an optimization
+layered on top, never a hard dependency.
+
+| Phase role | Persona | Detail |
+|---|---|---|
+| Gatherer | `scout` builtin | dispatched as a prior sync run producing the gather digest |
+| Verifier | `worker` builtin | dispatched with the report-only constraint prepended to its task ("report only - do not edit, fix, or commit anything") |
+| Reviewer | the existing `code-reviewer` agent | emits its native output format (never overridden at call time) |
+
+Verifier and Reviewer share the provisioned worktree via `cwd`, dispatched
+**sequentially** (Verify before Review, per `## Phase 3 - Verify, then review`) - never `worktree: true`,
+which would provision a separate isolated worktree and break the shared-tree contract
+this skill depends on. A subagent that fails, or violates its section's output
+schema, is re-dispatched once demanding the schema; a second failure means that
+section runs inline instead.

package/skills/gatekeep-pr/reference/decision-menu.md

@@ -0,0 +1,127 @@
+# gatekeep-pr: decision menu
+
+Read from SKILL.md `## Decide`. `## Decision` in the report has two parts: the
+action vocabulary, then the numbered courses.
+
+## Actions
+
+```markdown
+Actions (compose freely in the custom row):
+  fix <P#s|all>    apply blocking fixes in worktree, re-run gate, push  (in-repo PRs only)
+  push-docs        push already-applied doc-drift edits                 (only when uncommitted
+                                                                        reviewed doc edits exist
+                                                                        in the worktree)
+  merge-squash | merge-commit                                          (preconditions per Verdict;
+                                                                        never bundled with a push,
+                                                                        except the telemetry: restore commit)
+  request-changes | review-comment | approve                           (approve: never own PR)
+  reply <C#s>      post drafted thread replies
+  tracker <act>    tracker action                                      (only when a tracker tool resolved)
+  stop             leave the PR as-is / report-only exit
+```
+
+A `+ tracker <act>` suffix is available on any mutation course when a tracker tool
+resolved.
+
+Selection grammar: ID sets accept `all`, ranges (`P1-P4`), comma lists
+(`P1,P3`), and exclusions (`all but P2`).
+
+## Consent table
+
+Deterministic - this table is the golden-scenario oracle.
+
+| Author | State | Offered rows (first = `[recommended]`) |
+|---|---|---|
+| you | clean / follow-ups only | merge (squash); merge (merge-commit); do not merge (leave it); post no-blockers comment |
+| you | blocking | apply code fixes (named finding subset): skill edits in worktree, commits, re-runs gate, pushes - then merge re-offered; push applied doc fixes; do not act; post review-comment of findings |
+| someone else | clean / follow-ups only | approve; merge (squash, offered-unrecommended); post no-blockers comment |
+| someone else | blocking | post request-changes review; apply fixes on their branch (courtesy option 2); reply to existing threads; post comment |
+| bot author | any | someone-else's rows for the same state, review actions recommended |
+| fork (any) | any | post review (request-changes / comment / approve per state) - push and merge rows absent |
+| any | draft PR | assessment rows only; merge and approve rows absent until ready-for-review |
+| any | merged / closed | report-only; no mutation rows |
+
+This table is the single oracle for what is offered; `## Courses` renders its
+rows as actions and numbered courses. Rows GitHub would refuse (branch protection,
+missing permissions, `viewerPermission` too low) render listed-but-unavailable with
+the reason. Approving your own PR is never offered. Nothing executes until explicit
+selection.
+
+## Courses
+
+A normative rendering of the consent table (never a second offer source): per
+author x state cell, exactly one `[recommended]` course renders first, the custom
+row renders last. Courses are atomic across pushes: no course, pre-composed or
+custom, bundles a push-producing action (`fix`, `push-docs`) with `merge-*`; after
+a fix wave the menu re-renders with merge as row 1.
+
+| Author | State | Courses (first = `[recommended]`) |
+|---|---|---|
+| you | clean / follow-ups only | 1. merge-squash; 2. merge-commit; 3. stop; 4. review-comment (post no-blockers note) |
+| you | blocking | 1. fix (worktree-fixable P#s only - `all` covers only those) [+ push-docs when uncommitted doc edits exist]; 2. push-docs (alone, when doc edits exist); 3. stop; 4. review-comment (post findings). When no P# is worktree-fixable (blocking is failing-check-only or L#-only), course 1 (fix) does not render: push-docs becomes first when doc edits exist, else stop is first |
+| you | blocking, post-fix re-render (gate green, preconditions hold) | 1. merge-squash; 2. merge-commit; 3. stop; 4. review-comment |
+| someone else | clean / follow-ups only | 1. approve; 2. merge-squash (offered-unrecommended); 3. review-comment (no-blockers note) |
+| someone else | blocking | 1. request-changes; 2. fix all (courtesy, their branch - omitted when nothing is worktree-fixable); 3. reply <C#s> (omitted when the `C#` group is None); 4. review-comment |
+| bot author | any | someone-else's rows for the same state; review actions recommended |
+| any | draft | 1. request-changes / review-comment / reply <C#s> (omit the reply course when the `C#` group is None) / stop - `[recommended]` follows the same authorship rule as the non-draft cells, except on your own draft PR `request-changes` is never recommended (you cannot request changes on your own PR any more than you can approve it); the fallback recommendation there is `review-comment` when findings exist, else `stop`. Custom present but cannot compose `merge-*`/`approve`/`fix`/`push-docs` until ready-for-review |
+| any | merged / closed | 1. stop; report-only, no other mutation courses at all; Custom present but cannot compose `merge-*`/`approve`/`fix`/`push-docs`/`request-changes`/`review-comment`/`reply`/`tracker` - nothing remains actionable |
+
+## Fork overlay
+
+The consent-table fork row renders as an overlay on the authorship cells
+(push/merge/fix absent; approve also dropped when the viewer authored the PR) - it
+is not a distinct authorship cell. It overlays the applicable authorship cell (you
+or someone else), removing `fix`, `push-docs`, and `merge-*` (never available on a
+fork). When you authored the fork PR, `approve` is also dropped (never offered on
+your own PR) - fork|you|clean renders `review-comment`/`stop` only; fork|you|blocking
+renders `request-changes`/`review-comment`/`stop` (the someone-else courtesy
+fix-on-their-branch course is also absent, since it is your own PR). A fork PR
+authored by someone else uses the someone-else cells with `fix`/`push-docs`/
+`merge-*` removed.
+
+## CI-check gate
+
+An undispositioned failing check in the resolved set, or a pending required check,
+withholds every pre-composed course containing `merge-*` (merge preconditions per
+SKILL.md `## Verdict`) - none render, whatever the author/state cell says.
+Disposition and pending-check definitions per `findings.md` `## Dispositions`.
+
+| Disposition | Merge courses |
+|---|---|
+| Flaky | Not restored to a pre-composed course; merge proceeds only via the custom row naming the disposition explicitly |
+| Real, or an unresolved pending check | Withheld until the check is green |
+| CI-infrastructure-broken | Withheld until the triggered fallback run is green |
+
+A pending-only render is not itself a blocking verdict (findings groups can all
+read "None"); the recommended course falls to `stop` or `review-comment` in the
+meantime. This never falls through to the clean cell's recommended `merge-squash` -
+a failing resolved-set check or a pending required check means the PR is not in the
+clean state to begin with.
+
+## Fixtures
+
+Refused rows render per `## Consent table`. Zero mutation courses is a legal
+render (merged/closed) - the menu still appears, carrying findings and `stop`.
+
+Example render (golden fixture 1 - own PR, blocking findings including committed
+doc drift, so uncommitted reviewed doc edits exist):
+
+```markdown
+Pick one:
+  1. fix all (P1-P10) + push-docs   [recommended]
+  2. push-docs (docs only, hold code fixes)
+  3. stop (leave as-is)
+  4. review-comment (post findings, act later)
+  5. Custom - compose: e.g. "fix P1-P8,P10 + push-docs" or "reply C1 + tracker comment"
+```
+
+Golden fixture 2 - the post-fix re-render after course 1's gate re-run passes:
+
+```markdown
+Pick one:
+  1. merge-squash   [recommended]
+  2. merge-commit
+  3. stop (leave as-is)
+  4. review-comment
+  5. Custom
+```

package/skills/gatekeep-pr/reference/findings.md

@@ -0,0 +1,93 @@
+# gatekeep-pr: findings
+
+Read from SKILL.md `## Assess`. Phase 4 mints the IDs the report and menu carry.
+
+## IDs
+
+`<source_ref>` is a `file:line` where one exists, else the disputed thing (a
+quoted PR-body claim, a failing gate command, a required check name).
+
+Precedence: Phase 4 and the merged rubric decide blocking vs. follow-up (the
+severity translation, AC coverage, claims, and required-check rules). This
+section only chooses which namespace (`P#` / `L#` / `F#`) renders that
+decision. Category tags and the triage bar never override an upstream
+blocking classification - a Phase-4 Moderate is always blocking (`P#` or `L#`
+per Total mapping), never demoted to `F#` by tag or by judgment call.
+
+Total mapping: every blocking element of the Verdict maps to a `P#` or `L#` -
+a blocking verdict with "None" in both groups is a rendering bug. Map: failed
+gate -> `P#` `[test]` referencing the gate command; contradicted or
+merge-proof-unverifiable material claim -> `P#` `[spec]` referencing the
+claim; scope creep with a linked issue -> `L#` `spec-conflict`; committed doc
+drift -> `L#` `doc-drift`; `partial` AC coverage -> `L#` `outdated-AC`;
+`missing` AC coverage -> `L#` `missing-behavior`. `L#` covers exactly the
+drift the Verdict already blocks on (committed doc drift, AC coverage, spec
+conflict); it widens nothing.
+
+`P#` vs `L#` boundary: code-level spec bugs (the diff contradicts the spec)
+are `P#` `[spec]`; requirement/doc mismatches (the spec or docs are stale
+relative to intent) are `L#`.
+
+`C#` replies are verdict-neutral drafts: they never block and never gate
+merge; nothing posts until selected.
+
+`F#` items carry an owner (pr-author | tracker | human) so follow-ups don't
+evaporate; when no tracker tool resolved, the report itself is their durable
+home.
+
+IDs are append-only for the run's lifetime: minted at first assessment, never
+renumbered, never reused. A resolved finding keeps its ID annotated
+`(fixed in <sha>)`; later rounds continue each namespace's sequence.
+
+Empty groups say "None".
+
+## Triage
+
+A finding lands in `P#` only when it must be fixed before merge (correctness,
+security, material performance trap, a convention the repo enforces);
+improvements that don't change merge correctness are `F#`, whatever their
+category. `[quality]` and `[performance]` on a `P#` are categories, never a
+downgrade - every `P#` blocks. This triage bar governs findings the
+orchestrator originates itself; it never re-triages a classification Phase 4
+already made (see Precedence in `## IDs`).
+
+## Dispositions
+
+Any blocking conclusion in the resolved check set (required or not - per
+`../verification-brief.md` Section B, Evidence resolution table) withholds
+merge from every pre-composed course until the user explicitly dispositions
+it, and mints a `P#`.
+
+An undispositioned failing check in the resolved set is `P#` `[test]`
+referencing the check name; it is never a target of a worktree `fix`. Close
+failing checks by disposition, not by fix: the user's Phase-4 disposition
+annotates the same ID rather than closing it outright.
+
+| Disposition | Annotation on the `P#` | Counts against unfixed-blocker set | Merge course | Fallback local run |
+|---|---|---|---|---|
+| undispositioned failing check | none yet | yes | withheld from every pre-composed course | none |
+| flaky | `(dispositioned: flaky)` | excepted - no longer counts against "every `P#` blocks" or "every blocking finding fixed" | only the custom row naming the disposition explicitly; no pre-composed course restores | none |
+| real | `(dispositioned: real)` | still counts - `P#` keeps blocking | withheld until the check is green | none |
+| CI-infrastructure-broken | `(dispositioned: ci-infrastructure-broken)` | still counts - `P#` keeps blocking; the checks themselves are untrustworthy | withheld until the fallback run is green | triggers the fallback local run, and merge stays withheld until that fallback produces green evidence |
+| pending required check | mints no `P#`, is never dispositioned | not applicable - not dispositionable | withheld; auto-lifts the moment it turns green, or converts to an undispositioned failing check with its own `P#` on failure | none |
+
+A pending required check is wait-until-green, not dispositionable. While
+pending, the report notes it under Evidence.
+
+The evidence decision is independent of the merge decision: a green check
+elsewhere in the resolved set still satisfies verification evidence while a
+pending required check withholds merge. The CI-sufficient path changes no
+consent surface: still read-only, no auto-merge, no posting, no menu change
+beyond the third disposition.
+
+## Payloads
+
+"Drafted fixes / review" holds, per finding ID, the concrete edit (for
+`fix`), the reviewed doc-drift edit (for `push-docs`, keyed to its `L#`), or
+the reply text (for `reply`) - each keyed to its finding ID, one selection
+mapping 1:1 to its payload.
+
+A posted review body is not itself a finding: compose it at post time from
+the ID'd `P#`/`L#` findings being addressed - one summary sentence, then the
+numbered findings, ending on the fix or asked action - and give it its own
+non-finding slot of this section.

package/skills/gatekeep-pr/reference/post-selection-loop.md

@@ -0,0 +1,38 @@
+# gatekeep-pr: post-selection loop
+
+## Post-selection loop
+
+Read from SKILL.md `## Act`. Treat the menu as a state machine: execute only the selected course, re-render, and loop until the user selects merge or an explicit stop/no-action row.
+
+### Compare-and-swap
+
+Before every external write, re-fetch `headRefOid`, `state`, and `mergeable`. Any change since assessment invalidates the current state - re-sync the worktree, re-run Phase 3 per `assessment.md` `## Phase 3 - Verify, then review`, and re-render the menu. Exception: a course's own push updates the assessed head to the pushed SHA as part of that course's execution - this self-inflicted head move does not invalidate the course; the next compare-and-swap check runs against the new head on the next external write.
+
+### Fix wave
+
+For a `fix <set>` selection, filter the selected set to worktree-fixable `P#`s first: drop any `P#` closed by disposition (per `findings.md` `## Dispositions`). Route file-less `P#`s (a claim or a gate command as `source_ref`, no draft touching a file) to run inline and sequentially, never as part of a parallel batch. A claim `P#` with a drafted file edit is worktree-fixable and batches.
+
+Batch the remaining worktree-fixable set by the union of files each finding's drafted edit in `## Drafted fixes / review` touches - fall back to the `source_ref` file only when a finding has no draft. Findings whose drafts share a file share a batch.
+
+Use one child contract for every batch, whether there is one or many: dispatch `implementer` children with `subagent({ agent: "implementer", context: "fresh", cwd: <PR worktree> })`. The orchestrator owns commit, gate, and push - never a child. Every dispatched child gets `cwd` = the PR worktree; `worktree: true` is forbidden per `assessment.md` `## Inline-first execution`. Each child is edit-only - no git commands, no verification runs - and must never delete `.pi/gauntlet/telemetry/**` or anything under the configured telemetry dir (a fix that "cleans up" the run's telemetry record is a defect in the fix, not a cleanup). Each child's task is that batch's `P#` lines plus the drafted edit already keyed to each ID in `## Drafted fixes / review` - the child applies the consented payload, it does not re-solve the finding.
+
+At a cutoff of 2 worktree-fixable findings or fewer, the orchestrator applies the fix inline instead of dispatching - the no-cohort path stays available at any batch count per `assessment.md` `## Inline-first execution`. Past that cutoff, when more than one batch results, dispatch the batches' children in parallel, all under the same contract.
+
+Once every dispatched or inline batch returns, commit the golden course as one local commit set - the code fixes plus any already-applied reviewed doc edits selected alongside them (one commit, or one per batch sequentially; subjects name the fixes). Re-resolve the evidence for the new head once (the brief's stale-head row: prior evidence is stale; the local command executes only on a fallback/opt-out resolution). Before the push, run `node <bin>/gauntlet-telemetry-salvage.mjs --worktree <provisioned path> --base origin/<baseRefName>` (no `--check`); a `restored` or `(marked shipped)` commit rides the wave's single push and the pushed SHA becomes the assessed head under the course's-own-push rule in `### Compare-and-swap`. Print its stdout in the re-rendered report's `## Evidence`. On green, push once - gate and push are per-wave invariants, never per-fix or per-batch. On red, do not push: leave the commit(s) local, re-render with the unresolved `P#`s still open, and warn that unpushed fix commits sit in the worktree exactly like unpushed doc edits (per `### Teardown`).
+
+Doc fixes (`push-docs` alone) follow the same rule: stage and commit (subject names what is documented), re-run the gate, and push only on green. Execute reviews, replies, and tracker actions via `gh pr review` / `gh api` / the tracker tool, non-interactively, with the drafted payload for the selected IDs.
+
+### Merge course
+
+Merge always executes as `gh pr merge --match-head-commit <assessed-sha>`. Push and merge are never bundled into one selection, with one scoped exception: the selected merge course first runs the salvage (no `--check`) via `node <bin>/gauntlet-telemetry-salvage.mjs --worktree <provisioned path> --base origin/<baseRefName>`. `present` -> merge as-is. `restored <path> from <sha>` -> push that single `telemetry: restore` commit as part of this course, re-fetch `headRefOid`, and pass the new SHA to `--match-head-commit`. A line ending `(marked shipped)` (`present` or `restored`) is handled the same way: push that single `telemetry:` commit, re-fetch `headRefOid`, and pass the new SHA. `restore failed` -> merge proceeds, the reason is printed, and the follow-up names recovery from the PR head ref. A merge selection while any precondition (SKILL.md `## Verdict`) fails is refused, naming the failing precondition, and the menu re-renders - never a dead end, never a silent merge.
+
+### Re-render
+
+After any mutation that can change readiness (fix wave pushed, docs pushed, PR head moved), re-run the claim-check and Review on the synced worktree: claims are re-checked against the new head and findings are re-rendered, but do not re-execute the verification command here - the fix wave's evidence re-resolution already was the wave's one gate pass. Annotate each selected `P#`/`L#` confirmed resolved as `(fixed in <sha>)` under its original ID; unresolved ones stay open unchanged; new findings continue the sequence. Merge, if now available, renders as row 1.
+
+### Teardown
+
+| | Created worktree | Reused worktree |
+|---|---|---|
+| Merge success | tear down | tear down (the sync precondition guarantees no local-only work is stranded, and the branch is gone remotely) |
+| Non-merge stop | offer teardown, never autonomous; warn if unpushed doc edits would be discarded | leave as found; say so explicitly when unpushed doc edits or red-gate fix commits remain, and let the user choose leave-or-discard |

package/skills/gatekeep-pr/verification-brief.md

@@ -55,7 +55,7 @@ invent ACs.
 
 `mergeable` is reported as-is, including `UNKNOWN` - the Gatherer runs before
 provisioning, so it never re-polls; the orchestrator re-polls once after
-provisioning the worktree (see SKILL.md Phase 2) and treats a still-`UNKNOWN`
+provisioning the worktree (per `reference/assessment.md` `## Phase 2 - Provision worktree`) and treats a still-`UNKNOWN`
 result as not merge-ready. Bot author noted
 (`author_is_bot`). Capture each status check's `isRequired` where exposed (digest field: `required`).
 
@@ -81,7 +81,7 @@ conclusion, with `ERROR` blocking and `PENDING` pending. Missing `required` is
 treated as non-required. `ci checks:` matches check name, workflow name, or
 status context, trimmed, case-insensitive. What checks mean for verification evidence is owned by
 Section B's Evidence resolution table; what they mean for merge is owned by the
-orchestrator's required-check rule (SKILL.md Phase 4) - two independent
+orchestrator's required-check rule (`reference/findings.md` `## Dispositions`) - two independent
 consumers of the same data.
 
 ## Section B - Verifier