pi-gauntlet 5.0.2 → 5.0.3

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## v5.0.3 - 2026-08-25
+
+- gatekeep-pr defaults to green exact-head CI evidence (gh-14): normative six-path "Evidence resolution" table at the top of verification-brief.md Section B (opt-out / failed-CI / CI-sufficient / pending / fallback / stale-head, top-down); the local verification command runs only on fallback/opt-out rows; source-discriminated Verifier output (`source: ci|local`) with the exact CI claim form `verified by CI: <check name(s)> succeeded on <sha> (run <url>)`; any blocking conclusion in the resolved set mints a `P#` with a third disposition `CI-infrastructure-broken` that triggers the fallback run; two new `## PR gate` keys `local verification: always` and `ci checks:`. Spec: `doc/specs/2026-09-06-gh-14-gatekeep-ci-evidence-default.md` (partially supersedes `doc/specs/2026-08-18-gh-9-gatekeep-pr-skill.md`, verification-evidence scope only).
+
 ## v5.0.2 - 2026-08-24
 
 - Plan fidelity (gh-13): `writing-plans` task template gains a required spec-anchor line (`**Spec:** <path> § "<heading>" L<start>-L<end>`), a verbatim-quote rule for exact-string requirements, an extraction-first `## Spec coverage` table, and four mechanical self-review checks (quote integrity spec->task, anchor resolution, three-leg table closure, paths exist). `subagent-driven-development` spec-reviewer contract becomes spec+task: dispatches pass the spec path + the task's anchors in both modes and the Dispatch sketch, the spec wins every dispute, task-vs-spec divergence is unconditionally flagged with the spec literal, and `spec-reviewer-prompt.md` gains a `## Spec Authority` section plus `plan transcription gap` / `out-of-anchor-slice` finding labels. Spec: `doc/specs/2026-08-23-gh-13-plan-fidelity-anchors.md` (partially supersedes `doc/specs/2026-07-06-parallel-wave-spec-reviewer-dispatch.md`, SR contract scope only).

package/README.md

@@ -69,7 +69,7 @@ Everything between gate 1 and gate 2 - task breakdown, implementation, both revi
 
 pi-gauntlet ships three kinds of pieces, layered on top of pi-cohort's dispatch:
 
-- **16 skills** - the workflow logic. Twelve activate automatically when pi sees the matching kind of task, and each one gates the next: `brainstorming`, `writing-plans`, `roasting-the-spec`, `test-driven-development`, `subagent-driven-development`, `dispatching-parallel-agents`, `verification-before-completion`, `requesting-code-review`, `receiving-code-review`, `using-git-worktrees`, `finishing-a-development-branch`, `writing-skills`. Four more are explicit-invocation-only (`disable-model-invocation: true`): `shape-ticket` creates or repairs one tracker issue per run against a Context/Problem/Idea/Acceptance-Criteria template, gated by an AC integrity check, a cheap council roast, and a single human-confirmed write - run it with `/skill:shape-ticket`. `gatekeep-pr` is consent-gated pre-merge verification of a PR against its issue - read-only gathering, running the project's verification command, a rubric-based review, then a deterministic authorship-aware menu with stable finding IDs (P#/L#/C#/F#) and numbered pre-composed courses (fixes execute as a single parallel-safe wave: one gate run, one re-review, one push); nothing mutates (fixes, pushes, reviews, merges) until you pick a row - run it with `/skill:gatekeep-pr <pr>`. `check-delivery` is a post-merge detective control: proves an issue actually shipped (default-branch landing, delivery target, per-AC evidence) before its tracker status advances; it never writes a terminal status - run it with `/skill:check-delivery <ref>`. `chase-bug` is human-only bug triage: read-only root-cause discovery to an evidenced verdict menu (real bug -> ticket/brainstorm/respond; five negative verdicts), then a gated response to the reporter - it never fixes during triage - run it with `/skill:chase-bug`.
+- **16 skills** - the workflow logic. Twelve activate automatically when pi sees the matching kind of task, and each one gates the next: `brainstorming`, `writing-plans`, `roasting-the-spec`, `test-driven-development`, `subagent-driven-development`, `dispatching-parallel-agents`, `verification-before-completion`, `requesting-code-review`, `receiving-code-review`, `using-git-worktrees`, `finishing-a-development-branch`, `writing-skills`. Four more are explicit-invocation-only (`disable-model-invocation: true`): `shape-ticket` creates or repairs one tracker issue per run against a Context/Problem/Idea/Acceptance-Criteria template, gated by an AC integrity check, a cheap council roast, and a single human-confirmed write - run it with `/skill:shape-ticket`. `gatekeep-pr` is consent-gated pre-merge verification of a PR against its issue - read-only gathering, verification evidence resolved CI-first (green checks on the exact assessed head count as evidence; the project's verification command runs only as fallback), a rubric-based review, then a deterministic authorship-aware menu with stable finding IDs (P#/L#/C#/F#) and numbered pre-composed courses (fixes execute as a single parallel-safe wave: one gate run, one re-review, one push); nothing mutates (fixes, pushes, reviews, merges) until you pick a row - run it with `/skill:gatekeep-pr <pr>`. `check-delivery` is a post-merge detective control: proves an issue actually shipped (default-branch landing, delivery target, per-AC evidence) before its tracker status advances; it never writes a terminal status - run it with `/skill:check-delivery <ref>`. `chase-bug` is human-only bug triage: read-only root-cause discovery to an evidenced verdict menu (real bug -> ticket/brainstorm/respond; five negative verdicts), then a gated response to the reporter - it never fixes during triage - run it with `/skill:chase-bug`.
 - **7 subagent personas** - the specialized child agents the skills dispatch via pi-cohort: `implementer`, `code-reviewer`, `spec-reviewer`, `conformance-reviewer`, `spec-summarizer`, `spec-council-member`, `spec-council-synthesizer`. See [doc/personas.md](./doc/personas.md) for what each one does and why its permissions are scoped the way they are.
 - **3 runtime extensions** - the enforcement layer. `plan-tracker` and `phase-tracker` are tools skills call to track progress (with a TUI widget); `verify-before-ship` is a hook that warns if you push or open a PR without a passing test run since your last edit; a phase-tracker flow guard reminds on implement-phase commits missing spec/code review. See [doc/configuration.md](./doc/configuration.md) for the settings each one reads.
 
@@ -355,6 +355,8 @@ customization lives in two places, never in the wrapper itself:
 - verification command: <command>            # required unless documented elsewhere
 - timeout minutes: 15                        # optional; default 15
 - requires credentials: false                # optional; true => skill reports "not run" as missing evidence
+- local verification: always                 # optional; default (absent) = CI-first; "always" forces the local run even when exact-head CI is green
+- ci checks: <comma-separated check names>   # optional; narrows which checks count as evidence; absent = all checks on the assessed head
 - worktree wrapper: <command>                # optional
 - issue fetch: <command with <ref> placeholder>   # optional, replaces gh issue view
 - merge policy: squash | merge-commit        # optional

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-gauntlet",
-  "version": "5.0.2",
+  "version": "5.0.3",
   "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,8 +9,9 @@ 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, runs
-the project's own verification command, reviews the diff against a rubric, and
+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
 `[recommended]`; it never changes which rows are offered.
 
@@ -40,7 +41,7 @@ a wrapper skill:
    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
-   fetch, worktree wrapper, merge policy). An existing `## verification-before-completion`
+   fetch, worktree wrapper, merge policy, `local verification`, `ci checks`). An existing `## verification-before-completion`
    section is an accepted equivalent source for the verification command.
 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,
@@ -56,6 +57,8 @@ which is required unless documented elsewhere):
 - verification command: <command>            # required unless documented elsewhere
 - timeout minutes: 15                        # optional; default 15
 - requires credentials: false                # optional; true => skill reports "not run" as missing evidence
+- local verification: always                 # optional; default (absent) = CI-first; "always" forces the local run even when exact-head CI is green
+- ci checks: <comma-separated check names>   # optional; narrows which checks count as evidence; absent = all checks on the assessed head
 - worktree wrapper: <command>                # optional
 - issue fetch: <command with <ref> placeholder>   # optional, replaces gh issue view
 - merge policy: squash | merge-commit        # optional
@@ -81,7 +84,7 @@ configuration.
 ## Progress tracking
 
 Use `plan_tracker`, never `phase_tracker`. Init with the stage names: `gather`,
-`provision worktree`, `run verification`, `claim-check`, `review`, `consent menu`.
+`provision worktree`, `resolve evidence`, `claim-check`, `review`, `consent menu`.
 Append one task per material claim as the Verifier enumerates them. A passing stage or
 a matched claim -> `complete`. A failed stage or a contradicted claim -> `failed`
 (shown crossed, error color) and stays failed while the skill stops at the menu -
@@ -124,14 +127,15 @@ 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: the resolved verification command under its
-  safety contract - self-contained and non-interactive (no prompts; run under a
+- 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 the run,
-  the orchestrator asserts tracked-only cleanliness (`git status --porcelain
+  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
@@ -147,11 +151,16 @@ verification command may write to the tree while the Reviewer reads it):
 - **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 is precisely "reproduced locally under the project's documented verification
-  command" - nothing stronger; never worded to imply a deployed, staging, or CI
-  environment.
-- **Evidence:** paste each run's `command` and `raw_tail` verbatim, fenced - never
+  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.
+- **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 ->
@@ -165,18 +174,25 @@ verification command may write to the tree while the Reviewer reads it):
   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.
-- **Required CI checks:** a failing **required** status check withholds merge from
-  every pre-composed course until the user explicitly dispositions it - flaky
-  (proceed via the custom row) or real (it blocks); it mints a `P#`. A **pending**
-  required check (still running - the normal case, not a defect) is **wait-until-
-  green, not dispositionable**: it mints no `P#`, is never flaky/real-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
+- **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). Non-required checks are informational,
-  listed in Evidence only.
+  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
@@ -215,9 +231,9 @@ issue is linked, committed doc drift, anything the merged rubric maps to blockin
 **follow-ups only** (never gate merge), or **clean**.
 
 **Merge preconditions** (all must hold): gate green with every blocking finding fixed,
-not deferred; `mergeable == MERGEABLE` (`UNKNOWN` after the one post-provision
-re-poll withholds merge, same as `CONFLICTING`); no undispositioned failing or
-pending required check; evidence pasted with clean provenance; worktree clean and synced with the remote
+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
@@ -253,7 +269,7 @@ findings, menu. No restating diffs, no narration, no recap prose.
 <one line + the deciding factor>
 
 ## Evidence
-<verbatim command + raw_tail per run; claims checked; CI rollup with required-check disposition>
+<CI path: satisfying check name(s)/conclusion/sha/url; local path: verbatim command + raw_tail per run; claims checked; resolved-set check dispositions>
 
 ## Findings (blocking)
 Blocking findings (P#):
@@ -295,8 +311,8 @@ Requirement/doc drift (linked issue, committed doc drift, or spec conflict):
   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#`.
-- **Required checks close by disposition, not by fix:** an undispositioned failing
-  required check is `P#` `[test]` referencing the check name; it is never a target
+- **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
@@ -304,6 +320,9 @@ Requirement/doc drift (linked issue, committed doc drift, or spec conflict):
   "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
@@ -363,7 +382,7 @@ pre-composed or custom, bundles a push-producing action (`fix`, `push-docs`) wit
 | 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 required-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 | 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 |
@@ -382,18 +401,18 @@ also dropped (never offered on your own PR) - fork|you|clean renders
 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.
 
-**Required-check gate on merge courses:** an undispositioned failing **or pending**
-required check withholds every pre-composed course containing `merge-*` (per the
+**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. A **flaky** disposition does
+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 pending-only
+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 required-check
-failure or pend means the PR is not in the clean state to begin with.
+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
@@ -434,7 +453,7 @@ The menu is a state machine, not a one-shot report:
    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 required-check failure is never a `fix` target; a **flaky**
+   (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.
@@ -463,7 +482,7 @@ The menu is a state machine, not a one-shot report:
    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-runs the gate **once**. **On
+   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). **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
@@ -474,9 +493,9 @@ The menu is a state machine, not a one-shot report:
    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 gate run
-   already was the wave's one and only execution of it. Re-render the report:
+   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.
@@ -512,14 +531,14 @@ overrides file - see Project overrides.
 - 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 required-check failure
+- 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 required-check `P#` from the
+  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-*`

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

@@ -57,7 +57,7 @@ invent ACs.
 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`
 result as not merge-ready. Bot author noted
-(`author_is_bot`). Capture each status check's `isRequired` where exposed.
+(`author_is_bot`). Capture each status check's `isRequired` where exposed (digest field: `required`).
 
 **Gather digest output schema (normative):**
 
@@ -65,7 +65,7 @@ result as not merge-ready. Bot author noted
 - pr: { number, title, body, author, author_is_bot, state, isDraft, headRefName, baseRefName,
         isCrossRepository, mergeable, headRefOid, files, additions, deletions, reviewDecision }
 - viewer: { login, is_author, permission }
-- status_checks: [ { name, status, conclusion, required } ]   # informational except required-failing
+- status_checks: [ { name, status, conclusion, required, url } ]   # evidence semantics: Section B Evidence resolution
 - comments: { inline[], top_level[], review_threads[]? }
 - issue: { ref, title, body, acceptance_criteria[], comments[] } | null
 - worktree_discovery: { expected_path, exists, branch, dirty, ahead, behind }
@@ -73,18 +73,57 @@ result as not merge-ready. Bot author noted
 ```
 
 `viewer_is_author` lives at `viewer.is_author` in the digest, computed as
-`viewer.login == pr.author.login`. `status_checks` splits `required` vs
-non-required per entry - only a failing or pending required check withholds
-merge (see the orchestrator's required-check rule in SKILL.md Phase 4);
-non-required checks are informational.
+`viewer.login == pr.author.login`. Each `status_checks` entry's `url` is the CheckRun `detailsUrl` / StatusContext
+`targetUrl` already present in the fetched payload; when the payload omits it,
+downstream CI claims record `url: unavailable` - absence never disqualifies the
+check. GraphQL enums are case-folded; a StatusContext's `state` is its
+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
+consumers of the same data.
 
 ## Section B - Verifier
 
-Runs the resolved verification command inside the provisioned worktree, then
-claim-checks the PR body against what actually ran. Report only - do not
+Resolves the verification evidence per the table below - green exact-head CI is
+the default evidence; the resolved verification command runs inside the
+provisioned worktree only when the table selects a fallback or opt-out row -
+then claim-checks the PR body. Report only - do not
 edit, fix, or commit anything; you are running a gate and claim-checking,
 not implementing.
 
+**Evidence resolution (normative).** The single rule for whether the local
+command runs. Inputs come from Section A's existing `gh pr view` call - no
+second fetch.
+
+- **Resolved check set** = checks named by `ci checks:` if configured, else all
+  checks on the assessed `headRefOid`.
+- **Conclusion semantics**: `success` satisfies; `failure`/`timed_out`/
+  `action_required`/`error` block; `neutral`/`skipped`/`cancelled`/`stale`/
+  `startup_failure` are inert; a check with `status != completed` is pending; a
+  completed check with a missing/unreadable conclusion cannot satisfy
+  (fail-safe).
+
+Row precedence is top-down: the first matching row wins.
+
+| Path | Trigger | Action | Evidence recorded |
+|---|---|---|---|
+| Opt-out | `local verification: always` in `## PR gate` | Run local command unconditionally; a Failed-CI block below still applies independently | Local, as today |
+| Failed CI | Any blocking conclusion in resolved set | Blocks: mints a `P#` (any resolved-set failure, required or not). A green local run never overrides it. Only an explicit human CI-infrastructure-broken disposition triggers the fallback run; merge stays withheld until the fallback produces green evidence | The disposition; plus the fallback run's result only when CI-infrastructure-broken triggered one |
+| CI-sufficient | >=1 `success` in resolved set | Skip local run | CI claim: check name(s), conclusion, assessed SHA, run URL |
+| Pending | Zero `success` and >=1 pending check in resolved set | Evidence decision waits until the set reaches a completed conclusion - never a fallback trigger, never an evidence-less merge; merge is withheld as missing evidence until the table re-resolves | n/a (waiting) |
+| Fallback | No checks on assessed head, or zero `success` with none pending (all inert / fail-safe) | Run local command (protocol below, unchanged) | Local command + raw tail, existing provenance rules |
+| Stale head | Head advances since evidence was resolved (e.g. a fix-wave push); fires across runs - a single gather is same-head by construction | All prior evidence (CI or local) is stale; re-resolve this table for the new head before merge is offered | Fresh evidence for the new head |
+
+CI-sufficient predicate, stated once (the rows implement exactly this): **>=1
+completed `success`, zero blocking conclusions, no opt-out.** Pending checks are
+excluded from the predicate - they neither satisfy nor veto it. The evidence
+decision ("run local?") and the merge decision ("can this merge?") are separate
+consumers of the same `status_checks` data: a green non-required check satisfies
+evidence even while a pending required check blocks merge under the existing
+wait rule. The only evidence-path wait is the Pending row's zero-success case.
+
 **Safety contract:**
 
 - Timeout default 15 minutes, overridable by the resolved `timeout minutes`
@@ -95,7 +134,9 @@ not implementing.
   non-interactive.
 - If the resolved config states `requires credentials: true`, do not run
   the command; report "verification requires credentials, not run" as
-  missing evidence instead of prompting for secrets.
+  missing evidence instead of prompting for secrets; this arises only when
+  the table selected a fallback or opt-out row - a CI-sufficient resolution
+  needs no credentials.
 - Capture full output to a `log_path` inside the (disposable) worktree, under a
   gitignored path (e.g. `.worktrees/pr-<N>/.gatekeep-logs/`) so it never counts as a
   tracked change; keep only the last ~100 lines verbatim in the digest as `raw_tail`.
@@ -103,19 +144,27 @@ not implementing.
 **Verifier output schema (normative):**
 
 ```text
-- worktree_root: <absolute path>
-- head_sha:      <git rev-parse HEAD at run time>
-- runs: [ { run_cwd, command (verbatim), exit_code, result: pass|fail|not run,
-            raw_tail: <last ~100 lines of combined stdout+stderr, verbatim, fenced>,
-            log_path: <file inside the worktree holding the full captured output> } ]
-- claims: [ { claim, disposition: matched|contradicted|unverifiable-pre-merge, evidence } ]
+- source: ci | local
+- source: ci ->
+    head_sha: <the assessed headRefOid>
+    checks:   [ { name, conclusion, url } ]      # url: unavailable when the payload omits it
+    (no command, no raw_tail - nothing ran locally)
+- source: local ->
+    worktree_root: <absolute path>
+    head_sha:      <git rev-parse HEAD at run time>
+    runs: [ { run_cwd, command (verbatim), exit_code, result: pass|fail|not run,
+              raw_tail: <last ~100 lines of combined stdout+stderr, verbatim, fenced>,
+              log_path: <file inside the worktree holding the full captured output> } ]
+- claims: [ { claim, disposition: matched|contradicted|unverifiable-pre-merge, evidence } ]   # both sources
 ```
 
-`raw_tail` is captured output, not authored prose; anything written in your
+Local provenance and raw-tail rules bind only to source: local. `raw_tail` is captured output, not authored prose; anything written in your
 own words is labeled `summary` and must never be pasted in place of
 `raw_tail`.
 
-**Material-claim check.** After the run, claim-check the PR body -
+**Material-claim check.** Always runs, on both sources - on the CI path,
+dispositions are judged against the recorded CI evidence and the diff; on the
+local path, against the run and the diff. Claim-check the PR body -
 **material claims only** (test/verification/behavior assertions: "added
 X", "tests cover Y", "fixed Z"), not qualitative prose. Disposition each
 claim as one of:
@@ -130,7 +179,7 @@ proof* (it appears in the PR body's evidence/result/test-plan content) is
 blocking; the same claim stated as an explicit post-merge observation is
 non-blocking follow-up only.
 
-After the run, the orchestrator asserts tracked-only cleanliness
+After a local run (`source: local` only), 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 `log_path` itself, provided it sits under a gitignored path
@@ -171,9 +220,12 @@ blocking/follow-up happens later, at integration.
   judges against stated intent only, never inventing ACs; scope-creep findings
   do not apply.
 - No resolvable verification command (ladder exhausted, user asked, user
-  declines): the gate runs without local verification evidence; record
-  `result: not run` in the Verifier output. Missing evidence blocks merge
-  the same as a failed gate - the PR is not merge-ready.
+  declines) **when the Evidence resolution table selected a fallback or opt-out
+  row**: the gate runs without local verification evidence; record
+  `result: not run` in the Verifier output. Missing evidence blocks merge the
+  same as a failed gate - the PR is not merge-ready. A table-sanctioned CI skip
+  (`source: ci`) is evidence, never missing evidence, and needs no command at
+  all.
 - Linked-issue fetch fails (tracker unreachable, bad ref): proceed judging
   against the PR's stated intent, mark `issue: null` in the digest plus a
   truncation/availability note explaining why, and never invent ACs; AC