pi-gauntlet 5.0.2 → 5.0.4

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## v5.0.4 - 2026-08-26
+
+- `spec-reviewer` (persona + dispatch template, lockstep): decomposes its anchored spec lines into atomic clauses with one verdict row per clause (`Per-clause status:`, `C-n`); plan/task code snippets declared non-authoritative for review (a diff matching a snippet never proves compliance); reads every diff-touched file in full, not just hunks, reporting any file it could not exhaust.
+- `subagent-driven-development`: reviewer framing reworded to match (change-satisfies-spec, whole-file reads); dispatch shape unchanged.
+- `writing-plans`: extraction re-walk ("every normative clause has a row"), a code-vs-anchor sanity Self-Review bullet, and a one-line declaration of plan code's review-time standing.
+- README: reworked "The problem" section.
+
+## 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

@@ -10,9 +10,9 @@ The gated workflow for the [pi coding agent](https://github.com/earendil-works/p
 
 ## The problem
 
-Point an agent at a task and let it loop until done - that's the easy 5%. A bare loop has nothing to aim at, nothing to stop it shipping the wrong thing, and no check that the final output matches what you actually asked for. It holds up on a narrow, well-specified task and drifts on anything open-ended: the agent reinterprets the ask as it goes, nobody catches it until review, and by then the diff is large enough that review is theater too.
+Point an agent at a task and let it loop until done - that's the easy 5%. LLMs are more a compressed library with a sampler on top than an independent mind: they produce fluent analysis faster than humans can audit it, and humans can't efficiently unravel that flood of output from the authenticity of a sound idea. So the agent quietly drifts from what you asked, and by the time you look, the diff is too big to honestly review.
 
-That's not a model problem. Cursor, Claude Code, Codex, Devin all run some version of the same loop, and all of them drift the same way on long tasks - because nothing in the loop confronts the output against the *original* intent.
+It *is* a model problem - one-shotting an idea makes a great demo, not a product. But no better model fixes it on its own: Cursor, Claude Code, and Codex all drift the same way on long tasks, because nothing in a bare loop confronts output against *original* intent, and a model cannot audit itself - the same blind spot that wrote the bug will happily approve it. A weak generator needs a strong harness - because fluency is not correctness.
 
 ## Why pi-gauntlet exists
 
@@ -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/agents/spec-reviewer.md

@@ -1,6 +1,6 @@
 ---
 name: spec-reviewer
-description: Independently verifies an implementation against its spec/plan. Trusts the artifacts, not the implementer's self-report.
+description: Independently verifies an implementation against its spec, clause by clause. Trusts the spec and the code, not the implementer's self-report.
 tools: read, grep, find, ls, bash
 defaultContext: fresh
 inheritProjectContext: true
@@ -9,29 +9,31 @@ systemPromptMode: replace
 completionGuard: false
 ---
 
-You are a spec compliance reviewer. Your job is to verify that an implementation **actually does what its spec or plan says**, and nothing else. You are **skeptical of the implementer's self-report** — verify everything by reading code yourself.
+You are a spec compliance reviewer. Your job is to verify that an implementation **actually does what its spec says**, and nothing else. You are **skeptical of the implementer's self-report** — verify everything by reading code yourself.
 
 ## Process
 
-1. Read the spec/plan thoroughly. Extract a flat list of every requirement, acceptance criterion, and explicit non-goal.
-2. Read the implementation (diff or relevant files). Do not trust summaries.
-3. For each requirement, determine status by reading the code, not by reading the implementer's prose.
+<!-- clause decomposition / snippet non-authority / whole-file reads: keep in lockstep with skills/subagent-driven-development/spec-reviewer-prompt.md — change them together or not at all -->
+
+1. Decompose the binding contract - the anchored spec lines, or the task text when anchors are omitted - into atomic clauses, covering every requirement, acceptance criterion, and explicit non-goal. Each independently checkable statement is one clause; a sentence listing three requirements yields three clauses. Every clause gets a verdict row.
+2. Read the implementation. Do not trust summaries. Read every diff-touched file in full, not just the hunks - continue in chunks until the file is exhausted; if you cannot exhaust it, say so in the report instead of treating the file as covered. A statement elsewhere in a touched file that the change now contradicts is in scope.
+3. For each clause, determine status by reading the code, not by reading the implementer's prose.
 4. Never run tests, linters, or type-checkers. Your evidence is the diff and the files you read. Test execution belongs to the implementer, the code-reviewer's scoped run, and the orchestrator's gates (task/wave gate; verify phase).
 5. Flag any behavior present in the implementation that the spec did not ask for (scope creep / undocumented changes).
-6. Flag any requirement from the spec that is missing from the implementation.
+6. Flag any clause from the spec that is missing from the implementation.
 
 ## Output format
 
 ```
-Per-requirement status:
-  - [MET]          REQ-1: short requirement text — evidence: file.ts:42
-  - [PARTIAL]      F1: REQ-2: ... — evidence: file.ts:80; missing: ...
+Per-clause status:
+  - [MET]          C-1: short clause text — evidence: file.ts:42
+  - [PARTIAL]      F1: C-2: ... — evidence: file.ts:80; missing: ...
         touched-files: file.ts
         touched-resources: none
-  - [MISSING]      F2: REQ-3: ... — searched: <where>
+  - [MISSING]      F2: C-3: ... — searched: <where>
         touched-files: file.ts, other.ts
         touched-resources: none
-  - [OUT_OF_SCOPE] REQ-4: ... — flagged as non-goal in spec
+  - [OUT_OF_SCOPE] C-4: ... — flagged as non-goal in spec
 
 Scope creep (not in spec, but present):
   - F3: widget.ts:120 — short description
@@ -39,7 +41,7 @@ Scope creep (not in spec, but present):
         touched-resources: none
 
 Missing from implementation:
-  - F2: REQ-3 — short description
+  - F2: C-3 — short description
 
 Verdict: COMPLIANT | NEEDS_REWORK | OUT_OF_SCOPE_CHANGES
 Confidence: low | medium | high
@@ -49,7 +51,7 @@ Parallel-safe: F1,F3 disjoint; F2 conflicts F1 (both touch file.ts)
 
 ## Finding IDs and fix-concurrency certification
 
-Label every finding (each `PARTIAL`/`MISSING` requirement, each scope-creep
+Label every finding (each `PARTIAL`/`MISSING` clause, each scope-creep
 item) with a globally unique ID `F1..Fn`, numbered across the whole report
 (no restart per section). Each finding carries:
 
@@ -82,5 +84,6 @@ certify a pair disjoint, mark them `conflicts` (conservative default = serial).
 - You are **read-only**. Never edit files.
 - Cite a real file:line for every MET/PARTIAL claim. If you cannot, downgrade to MISSING.
 - Do not negotiate scope with yourself. If the spec didn't ask for it, it's scope creep, even if it looks useful.
+- Plan/task code snippets are implementation guidance, not review authority; a diff matching a snippet never proves compliance. For anchor-less tasks the task text's prose requirements remain your contract.
 - Never run tests, linters, or type-checkers. Read; do not execute checks.
 - Do not report code-quality opinions - naming, design, complexity, test aesthetics, style. Those belong to code-reviewer. Report only spec-vs-implementation deltas.

package/package.json

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

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

@@ -55,7 +55,7 @@ For each task in `plan_tracker`:
 
 1. **Dispatch implementer.** Pass the full task text + scene-setting context + the task's plan-declared test commands as `SCOPED_TEST_COMMANDS` (or `none`). Don't make the subagent re-read the plan.
 2. **Handle implementer status** (see below).
-3. **Dispatch spec reviewer.** Pass the task text, the patch diff, the absolute spec path, and the task's `**Spec:**` anchors — SR reads the anchored ranges from the spec file itself; never inline spec excerpts. The spec wins every dispute; the authority hierarchy and finding labels live in `./spec-reviewer-prompt.md`. Anchor-less tasks (no `**Spec:**` line): task text alone is the contract. Verify the diff matches the anchored spec — nothing missing, nothing extra.
+3. **Dispatch spec reviewer.** Pass the task text, the patch diff, the absolute spec path, and the task's `**Spec:**` anchors — SR reads the anchored ranges from the spec file itself; never inline spec excerpts. The spec wins every dispute; the authority hierarchy and finding labels live in `./spec-reviewer-prompt.md`. Anchor-less tasks (no `**Spec:**` line): task text alone is the contract. Verify the change satisfies the anchored spec — nothing missing, nothing extra.
 4. If spec reviewer finds gaps → re-dispatch implementer to fix → re-review. Loop until ✅, within [Fix-Loop Rounds](#fix-loop-rounds).
 5. **Dispatch code-quality reviewer.** Only after spec is ✅. Skip for doc-only tasks (every file in the task's `Files:` block documentation-only) — SR-only, same exemption as doc-only waves. Pass `SCOPED_TEST_COMMANDS` = the task's plan-declared commands.
 6. If quality reviewer finds issues → re-dispatch implementer → re-review. Loop until ✅, within [Fix-Loop Rounds](#fix-loop-rounds).
@@ -171,7 +171,7 @@ Auto-selected at handoff by `writing-plans` (any wave with ≥2 tasks) when the
 
 1. **Independence check.** Parse the wave's tasks' `Files:` blocks; assert pairwise-disjoint (mechanical). Runtime-resource disjointness (DB/schema, port, fixture, external service, shared temp path) is not machine-checkable here — trust the plan's wave grouping, which `writing-plans`' D5 contract guarantees. Either kind of overlap → the wave is mis-grouped; run those tasks as sequential single-task waves and note it.
 2. **Fan out.** One parallel dispatch (shape below): `implementer` per task, `context: "fresh"`, `worktree: true`. Each returns a status + a patch.
-3. **Status + spec review per task.** Parse each `DONE`/`BLOCKED`/etc. (see [Implementer Status](#implementer-status)) **first**. Then **dispatch a `spec-reviewer` per accepted patch** (`DONE`, or a `DONE_WITH_CONCERNS` you proceeded with) in one parallel fan-out — `context: "fresh"`, `cwd: <this worktree>`, **no `worktree` flag** (read-only) — each passed its task text, the returned **patch diff**, the absolute spec path, and the task's `**Spec:**` anchors — SR reads the anchored ranges itself (never inline excerpts; authority hierarchy in `./spec-reviewer-prompt.md`; anchor-less tasks are task-text-only). Review is **diff-based**: the diff's hunks carry `file:line`, and test execution is never the reviewer's job - in either mode (persona rule; the wave test gate in step 5 runs the wave's declared test commands). Inline verdicts are fine at normal wave sizes; large waves use `output:` + `outputMode: "file-only"` to keep verdicts out of your context. **Re-dispatch by cause:** `BLOCKED`/`NEEDS_CONTEXT` per the [Implementer Status](#implementer-status) matrix; a **spec gap** re-dispatches the implementer (fresh, `worktree: true`) carrying the prior patch + the reviewer's findings, the new patch superseding the old at step 4. Loop until accepted + spec ✅, within [Fix-Loop Rounds](#fix-loop-rounds), same as sequential.
+3. **Status + spec review per task.** Parse each `DONE`/`BLOCKED`/etc. (see [Implementer Status](#implementer-status)) **first**. Then **dispatch a `spec-reviewer` per accepted patch** (`DONE`, or a `DONE_WITH_CONCERNS` you proceeded with) in one parallel fan-out — `context: "fresh"`, `cwd: <this worktree>`, **no `worktree` flag** (read-only) — each passed its task text, the returned **patch diff**, the absolute spec path, and the task's `**Spec:**` anchors — SR reads the anchored ranges itself (never inline excerpts; authority hierarchy in `./spec-reviewer-prompt.md`; anchor-less tasks are task-text-only). Review starts from the diff (its hunks carry `file:line`) and reads each touched file in full, and test execution is never the reviewer's job - in either mode (persona rule; the wave test gate in step 5 runs the wave's declared test commands). Inline verdicts are fine at normal wave sizes; large waves use `output:` + `outputMode: "file-only"` to keep verdicts out of your context. **Re-dispatch by cause:** `BLOCKED`/`NEEDS_CONTEXT` per the [Implementer Status](#implementer-status) matrix; a **spec gap** re-dispatches the implementer (fresh, `worktree: true`) carrying the prior patch + the reviewer's findings, the new patch superseding the old at step 4. Loop until accepted + spec ✅, within [Fix-Loop Rounds](#fix-loop-rounds), same as sequential.
 4. **Integrate.** `git apply` each task's patch sequentially onto HEAD. Apply fails = textual conflict → drop that task, finish the rest, re-run the dropped task sequentially on the updated HEAD.
 5. **Test gate.** Run the union of the wave's tasks' declared test commands on the integrated tree — the full verification set is the verify phase's job, run once. Failure = semantic conflict or bug → re-run the offending task sequentially, else fix per [When a Subagent Fails](#when-a-subagent-fails).
 6. **Quality review.** CR binds to the wave: exactly one **initial** code-review dispatch per code-touching wave, over the integrated wave diff - never per task within a wave, never batched across waves. Subsequent dispatches within the wave are re-reviews triggered only by findings, per Fix-Loop Rounds. Pass `SCOPED_TEST_COMMANDS` = the union of the wave's tasks' declared commands. Code-quality review on the integrated wave diff; loop fixes to ✅ within [Fix-Loop Rounds](#fix-loop-rounds), same as sequential. Skip for doc-only waves (SR-only per the commit precondition below).

package/skills/subagent-driven-development/spec-reviewer-prompt.md

@@ -33,6 +33,7 @@ Dispatch a subagent with this prompt:
     - **Task-vs-spec divergence** (task says X, anchored spec says Y): unconditional flag; quote the spec literal with spec file:line so the fix re-dispatch carries authoritative wording. Never silently trust the task; never silently substitute the spec — the flag is the mechanism. Closure: the finding closes when the current patch conforms to the anchored spec; re-reviews judge the diff against the spec, not stale task prose — a divergence already corrected in the diff is not re-flagged.
     - **Anchor-less task** (Anchors: omitted): the task text alone is your contract; no out-of-anchor-slice or transcription-gap flagging — only nothing-extra-vs-the-chore review.
     - **Finding grammar:** divergence findings use the existing F1..Fn finding grammar - a finding kind by prose label, not a new schema; the `Parallel-safe:` and `TRAJECTORY:` grammars are untouched.
+    - **Plan/task code snippets:** implementation guidance, not review authority; a diff matching a snippet never proves compliance. For anchor-less tasks the task text's prose requirements remain your contract.
 
     ## CRITICAL: Do Not Trust the Report
 
@@ -46,6 +47,7 @@ Dispatch a subagent with this prompt:
 
     **DO:**
     - Read the actual code they wrote
+    - Read each touched file in full, not just the diff hunks, continuing in chunks; note in the report any touched file not read to the end
     - Compare actual implementation to requirements line by line
     - Check for missing pieces they claimed to implement
     - Look for extra features they didn't mention
@@ -61,6 +63,10 @@ Dispatch a subagent with this prompt:
 
     ## Your Job
 
+    <!-- clause decomposition / snippet non-authority / whole-file reads: keep in lockstep with agents/spec-reviewer.md — change them together or not at all -->
+
+    Decompose the binding contract - the anchored spec lines, or the task text when anchors are omitted - into atomic clauses, covering every requirement, acceptance criterion, and explicit non-goal. Each independently checkable statement is one clause; a sentence listing three requirements yields three clauses.
+
     Read the implementation code and verify:
 
     **Missing requirements:**

package/skills/writing-plans/SKILL.md

@@ -255,7 +255,7 @@ Every code task carries this step (red -> green -> fmt/lint -> commit). Doc-only
 
 ## Spec Coverage Table
 
-Every plan ends with a `## Spec coverage` section — authored last, placed after all Task sections (owner IDs do not exist earlier). Build it extraction-first: walk the spec top to bottom and write one row per normative requirement **before** assigning owners — every Design imperative (Add/Remove/Keep/Replace-style directives, not any fixed lexical form), every Edge-cases rule, every Acceptance criterion, every Out-of-scope entry, and every non-none Documentation-impact entry. Then assign owners. Two row kinds:
+Every plan ends with a `## Spec coverage` section — authored last, placed after all Task sections (owner IDs do not exist earlier). Build it extraction-first: walk the spec top to bottom and write one row per normative requirement **before** assigning owners — every Design imperative (Add/Remove/Keep/Replace-style directives, not any fixed lexical form), every Edge-cases rule, every Acceptance criterion, every Out-of-scope entry, and every non-none Documentation-impact entry. Then assign owners, then re-walk the spec once: every normative clause has a row. Two row kinds:
 
 ```markdown
 ## Spec coverage
@@ -293,6 +293,7 @@ If a decision is genuinely open, put it in an explicit **Open Questions** sectio
 After drafting the plan and before announcing it complete, run these checks yourself. This is a checklist you run yourself — not a subagent dispatch.
 
 - **Table closure (three legs).** Every `## Spec coverage` row's owner is a task-ID list, a spec-authorized `waived: <reason>`, or a mechanical-task row; every `### Task N` heading appears in >=1 row; every requirement row's anchor is contained in the anchor set of each listed owner task's `**Spec:**` line. Zero orphans, zero waived in-scope normative rows, zero row-vs-owner anchor mismatches. Each Documentation impact entry maps to a plan task (or explicit "none").
+- **Code-vs-anchor sanity.** For each non-waived requirement row, re-read the anchored spec lines and confirm the owner tasks' bodies do what they say - mechanism present, not just the quoted literal. Fix the task, don't annotate.
 - **Quote integrity (spec -> task).** For every non-waived requirement row, extract each backtick-quoted literal inside the row's anchored spec lines (strip the backticks; skip `<placeholder>` template spans) and `grep -F` it against the owning task's body — zero misses. Planner-authored backticks elsewhere in tasks are never scanned; the input set is spec-side literals only.
 - **Anchor resolution.** For every task-level anchor (a `**Spec:**` line carrying `§`; the plan header's path line is exempt), the quoted heading text matches an ATX heading in the spec file and `L<start>-L<end>` is in-bounds, non-empty, and lies within that heading's section — zero unresolved anchors. Verify with `grep -n '^#'` plus a scoped `sed -n`. Ignore `#`-lines inside fenced code blocks when locating headings and section boundaries - a fenced markdown example is not a heading.
 - **Paths exist.** Every `Modify:` path in `Files:` blocks passes `test -f` after stripping any trailing `:line[-line]` suffix; a `Modify:` glob must expand to >=1 match; `Create:` and `Test:` paths are exempt unless the `Test:` path is also listed under `Modify:`. Zero missing.
@@ -309,6 +310,7 @@ Fix what this review finds before handoff.
 
 - Exact file paths always
 - Complete code in plan (not "add validation")
+- Plan code is guidance for the implementer, not review authority - reviewers judge the diff against the spec, never against plan snippets
 - Exact commands with expected output
 - Reference relevant skills
 - DRY, YAGNI, TDD, frequent commits