@1aboveio/skills 0.10.0

package/skills/engineering/review-pr/references/review-method.md

@@ -0,0 +1,199 @@
+# Review Method (detail)
+
+How to review, in three layers: a **diff-scoped subject** (what you attack), an **adversarial search across four axes** (how you find issues), and a **calibrated verdict** (what you actually report). The spine names these; this is the detail.
+
+## Diff discipline (the subject of every review)
+
+`review-pr` only ever reviews a change-set, so the diff *is* the subject — establish it before anything else.
+
+> Run `scripts/pr-context.mjs --base <target-branch> > <pr-context.json>` to produce all of this — merge-base, the net three-dot range, changed files, and the commit list — as JSON, so the base/diff is computed correctly every time. **Save the output**: `post-review.mjs --pr-context <pr-context.json>` reuses its `changedFiles` list at post time, so a finding traced into unchanged code (permitted below) can't 422 the whole review just because its file isn't in the diff (#635). `scripts/scan-diff.mjs` then turns the diff into heuristic **leads** (unanchored regex, first-party interception in tests, new branches) — *leads to verify, never findings*; you still construct the counterexample.
+
+- **Compute the review base, then diff against it.** For a PR/branch the unit is the **net diff from the merge-base**, not commit-by-commit:
+  - `base = git merge-base <target-branch> <pr-head>` — use the PR's *actual* target branch from its metadata, not a hardcoded `main`; recompute fresh so a rebase/retarget can't fool you.
+  - Review `git diff <base>...HEAD` (**three-dot** — the changes that would merge, excluding target-side commits that landed meanwhile; this is what GitHub's "Files changed" tab shows). Two-dot `<base>..HEAD` wrongly folds in base-side changes.
+- **Net, not per-commit.** A bug introduced in one commit and fixed in a later one is not in the net diff and must not be flagged — only the cumulative result ships. Per-commit review flags transient states that never merge.
+- **Introduced vs pre-existing, defined against the base.** A line/behavior is *introduced* iff it appears in `base...HEAD`; *pre-existing* iff present at the base. Pre-existing issues unrelated to the change are a **non-blocking note at most, never `NEEDS_CHANGES`** — don't block a PR for sins it didn't commit. A pre-existing weakness the change now *depends on or worsens* may be raised, framed as such.
+- **Attributable, not myopic.** Diff-scoping governs what you *block on*, not what you *read*: trace into unchanged code freely to *prove* a finding (a change can break an unchanged caller), but every blocking finding must be attributable to this change and cite the diff hunk that causes it.
+- **The evidence harness is something the diff depends on.** The sharpest case of "depends on" above, missed because the dependency runs backwards: when a diff **cites a browser/journey lane as proof of an AC**, the fixtures and config producing that evidence are part of what it depends on. A pre-existing harness defect that makes a cited lane **vacuous** blocks — the diff claims proof the harness cannot deliver, and that claim is introduced here even though the broken helper is not. Attribute it to the citing AC row. The tell is asymmetric: a lane failing *loudly* is a note (it isn't lying); a lane green-or-timing-out **without ever rendering its subject** is the blocker — the positive-marker row in [e2e-test → reviewing.md](../../e2e-test/references/reviewing.md). (Named incident: `skyee-ai-risk` #1144 — a tenant slug defaulted in four files left authorized journeys 403'ing before any row rendered, and five rounds graded lanes that had exercised nothing, each correctly scoping the helper as pre-existing.)
+- **History is a secondary signal.** Scan the commit list for what the net diff hides: a secret added then removed (a real leak — it lives in history), an unsafe intermediate migration state, or a large unrelated change buried mid-history. Otherwise the net diff governs.
+
+## Spec Compliance Review
+
+Verify whether the PR does what it is supposed to cover:
+
+### Round-1 depth (deep-lane reviews only)
+
+These four checks apply when the caller flags the PR **high-risk**
+(`resolve-issues/references/high-risk.md`) or the diff changes a contract other
+first-party code consumes; on those PRs they are round-1 obligations, not
+optional follow-up work. On a routine lean-lane PR, skip them without ceremony:
+
+- **Live endpoint probing:** exercise each changed live endpoint against the
+  real running surface, including the relevant authorization, boundary,
+  pagination/filter, and failure cases. Record a concrete command/result or
+  return `BLOCKED` when the required live surface cannot be exercised.
+- **Shared-consumer impact:** enumerate every shared first-party consumer of
+  the changed contract/surface, trace the producer's value into each consumer,
+  and exercise the affected consumer path. `Not applicable` is allowed only
+  when there is no live endpoint or no shared first-party consumer, and must
+  include a specific reason and evidence locator. `deferred`, `later`, and an
+  omitted check are not valid statuses.
+- **Invariant enforcement-point inventory:** when the diff declares or relies
+  on an invariant that must hold at more than one place, state the invariant in
+  one sentence, enumerate every point that must enforce it — searching the
+  **tree**, not the diff, since the diff only shows where the author already
+  did — and record enforced/not-enforced plus a locator per point. Every
+  unenforced point is a round-1 finding.
+- **Presentation state matrix:** when the diff changes what a browser surface
+  renders, enumerate the repo's supported presentation dimensions
+  (locale × viewport/input-modality × action state × theme) and record a
+  per-cell result. Touch is a distinct cell from pointer and keyboard.
+
+Obligations 3 and 4 are **sweeps** — enumerate the space, check every cell,
+report per-cell — and they are also where the contract-complete matrix gets
+built, at round 1 rather than on the recurrence § Theme reconciliation below
+waits for. Full method, over-application guard, and the named incidents behind
+each: [round1-depth.md](round1-depth.md).
+
+The reviewer records `completed` or `not-applicable` plus evidence for each
+obligation in the review result. A relevant obligation without evidence blocks
+the verdict; it cannot be silently moved to round 2.
+
+- Compare source requirements and test criteria ACs against the PR's claimed AC coverage.
+- Check every required behavior has implementation, test evidence, and the required test level.
+- **Verify each AC's *outcome*, not the mechanism's *shape*** — the presence of the right call, component, or constant is *not* the AC; the user-visible result for the **real input** is:
+  - **Instantiate the AC with the value the app actually produces at runtime**, not the convenient one a test happens to assert. When a handler branches on one form of a value while the real provider emits another, it fails for every real user — a test pinned to the proxy value is evidence for a case that never occurs.
+  - **Exercise realistic, legacy, and default/empty-state data, not just the happy-path fixture** — migrated, imported, and null-bearing rows are usually the ones the AC exists to protect.
+  - **Trace the value end-to-end to its producer.** A consumer referencing the right field proves nothing if the path that writes it never populates it; forward-tracing only the consumer is the half that hides this.
+- Verify tests are behavior-first and assert outcomes, state, contracts, side effects, permissions, and failures, not just internal functions.
+- Challenge mock/fake claims: mocks must not bypass the core behavior under review.
+- Check for missing edge cases, negative paths, backward compatibility, observability, and migration/backfill requirements.
+- Confirm known gaps are explicit and approved; `None` must be challenged against the diff and tests.
+- **An AC is satisfied only by a test that actually runs and asserts the behavior.** A proving test that is `test.skip()`'d, guarded into a no-op (`if (!data) test.skip()` / `if (!x) return`), or rewritten to assert on a degraded state (a 404 / not-found / empty page where the name promises a real rendered result) is **not evidence** — mark that AC `Missing` / `Unverified`, never PASS, no matter what the AC table or a green CI box says. An AC line in the Review Contract that cites a skipped/guarded test is a failed attestation, not a pass.
+- **A test's `@level` tag is a claim; verify the assertions earn it, not just the label.** Read what the test actually asserts, not the tier it advertises. A spec tagged `@level journey` that only checks the page loads (`response.ok()`) and *a* form element is visible — especially a weak disjunction like `expect(hasEmail || hasPassword || hasButton).toBeTruthy()` with `.catch(() => false)` swallowing locator errors — is a **smoke test wearing a journey label**: mark it `Wrong Level`, not PASS. A journey must drive the multi-step flow it names to a real outcome (log in and land authenticated, place the order and see it persisted), not assert that a control is merely present. The same trap one tier down: a `@level functional` test that only proves render is a smoke test.
+- **CI green is a proxy for coverage, not the goal — challenge how it was achieved.** A PR that turned red tests green by *skipping*, *guarding*, or *weakening assertions* (instead of fixing the cause or **seeding the required state** — `ensure-coverage` → seed-don't-skip) has manufactured the signal; that is `NEEDS_CHANGES`. Tell-tale in the diff: new `test.skip(`, a tightened-then-loosened assertion, or a status/exact-match assertion swapped for a fuzzy body-text match in the same hunk that made CI pass.
+- **Scan for test smells — as leads, not auto-findings** (doctrine + gate-vs-lead rationale: `ensure-coverage` → [`depth/test-smells.md`](../../ensure-coverage/references/depth/test-smells.md)). The decidable ones are already gated (`Erratic`→`no-fixed-timeout`/quarantine; an empty placeholder body→`no-empty-test`); these three need your reading:
+  - **Missing Assertion** — a test with statements but no assertion. The empty-body floor is linted; the rest isn't decidable (it may assert through a helper like `await verifyDashboard(page)`), so *read it* — confirm the helper asserts, or mark the test a no-op. (`depth.asserts-something` checklist row.)
+  - **Obscure** — the name doesn't describe the behavior it asserts (non-DAMP), or the failure message wouldn't point at the cause. A test you must reverse-engineer to understand is a maintenance liability even when green.
+  - **Slow** — slow *for its tier* (a unit test doing real IO, a journey padded with avoidable waits). Not a blocking gate (runtime is environment-sensitive); flag it and push the test down the pyramid or fix the wait.
+
+### Reviewer attestation
+
+You are the attestation point in the coverage chain. A coding agent's self-declared `@level` is a *claim*; ensure-coverage leaves a satisfied-but-uninspected surface at a **blocking `Unverified`**. Promote it to `Covered` only after reading the actual test and confirming it proves the behavior at the required level with acceptable mock use. Classify each AC and changed surface with ensure-coverage's vocabulary — `Covered` / `Partial` / `Missing` / `Wrong Level` / `Over-mocked` / `Unverified` / `Excluded` — not a vague "covered." Name the specific depth traps it defines instead of a generic "mocks are weak": first-party interception (`page.route`/`route.fulfill`/MSW) counted as a journey is `Over-mocked`; a browser route proven only by API tests is uncovered; a write form needs a rendered-form mutation journey (split-contract trap). Full vocabulary + traps: `ensure-coverage` → `references/depth/grading.md`.
+
+## Coverage Breadth Review
+
+This is the only pass that catches a surface **no acceptance criterion mentions** — the un-specced route the AC table is structurally blind to. The doctrine (Coverage Ledger, Surface Baseline Contract, alignment/depth statuses, the validator) lives in the `ensure-coverage` skill; apply it here rather than restating it.
+
+For surfaces the PR adds or changes:
+
+- Run or inspect ensure-coverage's coverage gate — `scripts/coverage-ledger.mjs validate` (or the repo's wrapper) — and reconcile it against the PR's Obligation Impact block. A missing Obligation Impact for a surface-changing PR is itself a defect.
+- Flag `Orphan surface` (a new surface no requirement owns — confirm it still meets its auto-applied baseline floor), unmet baseline / `Missing` / `Wrong Level` / `Over-mocked` on a changed surface, and `Unrealized requirement` / `Stale link`.
+- Check exclusion governance: an exclusion is valid only when gated (a `reachable` `mutation` route can never be excluded), carries a `category` + `reason`, and appears in the census. Reject a blanket "exclude to go green."
+- For changed **browser routes**, confirm the presentation sweep ran (separate gate) and the route has a real-render result — a green functional spec is not the presentation gate. See `e2e-test` → `references/presentation-sweep.md`.
+- A green AC table does not clear this pass. An un-ACed surface that fails its baseline is `NEEDS_CHANGES`.
+- **Require the completed Coverage Checklist where a Review Contract is required** (the method-tagged table in it; `ensure-coverage` → `process/review-contract-template.md`) — a Code-only PR carries no contract and so owes no checklist, but the ledger/baseline gate below still runs, because that answers to the repo rather than to the PR (SKILL.md § Review mode). Run `coverage-checklist.mjs validate <checklist> --diff <merge-base>` on it: every row must be a PASS/FAIL/N-A with a checkable evidence locator (`file:line` / `` `command` `` / #issue), no gate row left `TODO`, every cited `file:line` **resolving in the tree**, and every gate row carrying the gate's *result* rather than its command alone. Pass the `--diff` — it exempts paths the PR deletes, warns on locators outside the net diff, and is what lets a missing cited file block rather than merely warn (without it, a deletion and a stale locator are indistinguishable). A line past the end of an existing file blocks either way. The **gate-lint** rows you can trust as auto-filled; spend your attention on the **lead** rows (adjudicate each surfaced candidate) and **judgment** rows (meaningful assertions, mock acceptability, perceivability) — a row whose "evidence" is prose with no locator is not done, exactly like a finding with no code location.
+
+## Code Correctness Review
+
+### Theme reconciliation and contract-complete fixes (deep lane)
+
+In the deep lane (`resolve-issues/references/high-risk.md`) — and on any
+`state-machine`/`concurrency` finding anywhere — findings carry a stable theme
+id and the general violated contract; `theme` is optional on routine lean-lane
+findings. On a second consecutive finding with the same id, verify that the
+reviewer names the contract and that the requested fix is contract-complete:
+construct the full declared `states × taskKinds` matrix, check a test/evidence
+locator for every cell, and check one evidence-located adjacent-state entry for
+every declared state. A same-theme recurrence is an input to resolve-issues'
+circuit-breaker diagnosis (step 3), not a verdict of its own. Two rounds that
+both say `NEEDS_CHANGES` are not that signal; a different or non-consecutive
+theme is a different signal.
+
+**A same-theme recurrence is also a signal about the round-1 sweeps.** When
+obligation 3 or 4 ([round1-depth.md](round1-depth.md)) applied, the theme was
+enumerable before round 1 and the recurrence means the sweep under-enumerated —
+so build the matrix *and* say which sweep missed it, because the caller's cost
+was already paid in rounds. When neither obligation applied, the recurrence is
+the ordinary discovery signal this section was written for.
+
+Inspect the implementation for bugs independent of contract compliance:
+
+- **Read the code; do not trust the PR's narration of it.** The title, body, commit messages, and inline code comments describe *intent*, not behavior — they are claims to verify, not evidence. "Validates the token", "handles the empty case", "this is backward-compatible" must each be confirmed at the actual call site / branch / signature; a comment can lie or rot. Any divergence between what the change *says* it does and what the code *actually* does is itself a finding (either the description is wrong — fix it — or the code is). The same goes for test names: a test called `rejects expired tokens` proves nothing until you read that it actually drives the expired path and asserts the rejection.
+- Look for incorrect logic, error handling gaps, race conditions, idempotency bugs, retry/recovery issues, and async ordering problems.
+- Check auth, tenant isolation, permissions, data exposure, money movement, irreversible state changes, and auditability where relevant.
+- Review schema/migration safety, backwards compatibility, serialization/API contracts, and failure modes.
+- Check test quality: meaningful assertions, no disabled/weakened tests, no tests that only verify mocks or implementation calls.
+- **Hunt vacuous assertions — the full catalogue of forms that sank the #237 login regressions** (green while the primary button rendered invisible and the QR panel crashed): a rejection swallowed by a chained `.catch(...)` (`expect(...).not.toBeVisible().catch(() => {})`); an assertion guarded by a try/catch that re-passes; a `waitForTimeout` standing in for a real wait condition; a presentation/journey test asserting against a *stubbed* DOM instead of the real rendered surface. The directly-chained `.catch` and fixed timeout are gated by `lint-tests` (`no-swallowed-assertion`, `no-fixed-timeout`) where wired — assume they did not run.
+- **Reject assertions that pass on a degraded page.** A test whose name promises a real rendered result (a checkout form, an order detail) but asserts on a *404 / not-found / empty / error* body is a false pass — it goes green precisely when the feature is broken or the state was never seeded. Two findings hide here: the test (re-point it at the real, seeded path) **and** the degraded response itself — e.g. a route returning HTTP 200 with not-found *content* is a status-code bug to file, not a behavior to assert around. A "store not found" body in a test for an existing merchant usually means the merchant was never seeded, not that not-found is the expected outcome.
+- **Any test the PR skips or disables is `NEEDS_CHANGES`.** The committed suite contains only tests that run — a PR may not add `test.skip` / `xit` / `describe.skip`, a conditional skip, or a disguised `if (!x) return` guard. A missing precondition is **seeded**; an un-sandboxable or genuinely flaky case goes to the **quarantine lane** (non-blocking, still runs and reports, surface graded `Unverified`), never skipped. A `TODO`/issue link does **not** authorize a skip — it's a confession the work was deferred, especially when the text names the seed path (`re-enable when we seed a payment_live merchant via /api/e2e/setup`). (Inherited pre-existing skips are a note, not a blocker, per diff-discipline — but a PR may not add one. Full per-case map: `ensure-coverage` → `process/test-strategy.md`, `e2e-test` → `authoring/test-skipping.md`.) Likewise a *cosmetic* response to a finding (a TODO comment, a case-insensitivity tweak, a renamed reason) does not resolve it — re-verify the behavior changed, not the wording.
+- **A concurrency test proves only the state its fixture starts from.** When a test names itself a race and its fixture reads state an earlier test already created (`plan!.id`, `find*OrThrow`) before the `Promise.all`, every "concurrent" caller takes the already-exists early return and the contended first write is never exercised — green, and the race untested. Read the fixture's starting state, not the test's title: a first-write race needs zero pre-existing rows, independent clients, and a barrier. `scan-diff.mjs` surfaces the shape as the `concurrency-test-preexisting-fixture` lead; it stays a lead because a deliberate post-create *replay* test looks identical — what makes it a defect is an AC citing it as first-write proof. (Named incident: skyee-ai-risk #938, where a test titled "replays and races" started from an already-sealed plan; the real first-seal race rejected the losing caller with Prisma `P2034`, and it took five real-PostgreSQL trials to find what the fixture said outright.)
+- Flag broad unrelated refactors, hidden scope changes, dead code, brittle abstractions, and maintainability risks when they affect correctness or reviewability.
+
+### Narration drift (prose contradicting the code)
+
+The "read the code, don't trust the narration" bullet above, made into a systematic screen — because in a prose-heavy repo *prose contradicting the code it describes* is the single most common blocking finding, and in a skills/doctrine repo the prose **is** the product: a stale rule stated as operative is a live instruction to the next agent, not a cosmetic nit. For the net diff:
+
+- **Comment / docstring / `--help`/USAGE vs the code beneath it.** Read each changed hunk's prose against the behavior it narrates. A comment or USAGE string that states an exit code, a flag's required/optional status, a default, or a rule the code no longer follows is a finding — they disagree; fix the wrong one.
+- **PR-body claim vs the test that asserts it.** For each behavioral claim in the body ("`--stale-only` drops mixed-provenance entries"), find its test. When the test asserts the opposite (the code *keeps* them, the test pins kept), the body inverts tested behavior — a finding against the body.
+- **A superseded/aspirational rule stated as operative.** A section-header comment or doc line stating a rule the code has since replaced — especially in doctrine agents execute — is the reintroduction vector for the removed rule; flag it even when the code is correct, because the prose is a second, wrong instruction. (After a rebase, confirm this by diffing the resolved file against the new base — `git diff <new-base>...HEAD` — not by grepping for the one marker you expected, which hides every *other* change the conflicting side made.)
+
+**Blocking calibration.** Where the prose *is* the product — a skills/doctrine repo, a `--help`/USAGE contract, a comment stating a rule agents follow — a stale-rule-as-operative or a USAGE/flag/exit-code falsehood maps to the **spec-contradiction** blocking class (`NEEDS_CHANGES`). Elsewhere a purely cosmetic comment nit (a typo, a dated example with no behavioral claim) stays a **note inside `PASS`**. The test is behavioral consequence — *would an agent or user act wrongly on the prose?* — not "is the comment stale."
+
+**Decidable floor (pointer-resolution subset only).** One slice of this class is mechanized: that a cited `scripts/*.mjs --help`, a doc `#anchor`, or a reference link *resolves* is guarded by `reference-links.test.mjs` and `help-pointers.test.mjs`, and `scripts/scan-diff.mjs` fails loud rather than stamping a vacuous clean on empty input. Those check only that the **target exists** — not that the prose about it is **true**. The bulk (a comment stating a stale rule, a USAGE misstating an exit code, a body inverting a tested behavior) resolves fine and is still wrong; it is **semantic, and the reviewer's job — no script catches it.** Never record "enforced by the script" for the semantic part: claiming a guard catches narration drift is itself the narration-drift defect this screen exists to catch.
+
+### Adversarial techniques (how to be adversarial, not just "be adversarial")
+
+"Be adversarial" is empty without a method. The unifying move is to **produce the counterexample, not an opinion**: construct the specific artifact that would fail — and cite it — rather than asserting the code "looks fine" or "might be risky." A finding with no concrete trigger is a hunch. Concretely:
+
+- **Diff each new/changed function against its siblings.** Functions rarely live alone — find the family (same module, same naming pattern, same role: a set of `detect*` / `validate*` / `is*` / `parse*` functions) and compare their logic line by line. A function that diverges from its established siblings — handles a case they handle differently, uses a looser or tighter pattern, orders its guards differently, omits a branch the others all have — is a defect until the divergence is justified. Name the sibling and the exact divergence (e.g. "`detectOverMockedEvidence` matches `route.fulfill` but its sibling `detectTier1UiOnlyEvidence` also matches `page.route(` — the first will miss that vector"). Two functions that *should* behave alike but quietly don't is one of the most common real bugs a green test suite hides.
+- **Break patterns with boundary inputs.** For any regex, glob, string match, or parser the diff adds or changes, construct the input that breaks it before trusting it: prefix/substring leakage (does `/foo` also match `/foobar`? is the match anchored `^…$`?), word boundaries, empty/whitespace, case, escaping/metacharacters, unicode, and very long input. Over-broad or under-anchored patterns are a classic silent bug. Put the concrete failing string in the finding.
+- **Name a test for every new branch.** For each conditional, `else`, early return, ternary, switch case, and error path in the diff, identify the test that drives it. A branch with no test is unproven even when the line shows as "covered" — line coverage is not branch coverage. List each untested branch as a gap (this is the depth-axis check applied to the PR's own logic; classify with ensure-coverage's vocabulary).
+
+These are model-independent: a less meticulous model still has to run the checklist, so the rigor comes from the skill, not from getting lucky with a careful reviewer.
+
+## Standards Review
+
+Review documented repository standards separately from spec compliance and code correctness. Do not invent standards; cite documented sources.
+
+Look for standards sources such as:
+
+- `AGENTS.md`, `CLAUDE.md`, `CONTRIBUTING.md`, `README.md`, `STYLE.md`, `STANDARDS.md`, `STYLEGUIDE.md`.
+- Architecture docs, ADRs, context docs, or design conventions under `/docs/`.
+- Machine-enforced configs like `eslint.config.*`, `biome.json`, `.editorconfig`, `prettier.config.*`, and `tsconfig.json`; note them but do not duplicate checks that CI/tooling already enforces.
+
+Report only standards violations grounded in a cited source. Distinguish hard violations from judgment calls. If no standards source is available, state `Standards: Not assessed — no documented standards found`.
+
+## Mock & Integration Review Rules
+
+The boundary doctrine — *real internals, faked externals, nothing in between* — is owned by `ensure-coverage` → `references/depth/mock-policy.md`. Apply it here; the review-facing essence:
+
+- **Accept** mocks for: external provider failure injection (timeout/decline/malformed), isolating pure logic, asserting an external side effect was *not* called, and deterministic replacement of systems not under test.
+- **Reject mock-only** for: DB transactions, idempotency/duplicate delivery, concurrency/races, event/outbox/retry/recovery, auth/tenant isolation, serialization/schema/API compatibility, orchestrator crash recovery, and money/irreversible state. Money movement, auth, and idempotency can never be mock-only even with approval. (This is the broader mock-only *judgment*; the approval path here never extends to the internal-seam case below.)
+- **Mocking a first-party internal seam is zero-tolerance — not your call to approve.** A `vi.mock`/`jest.mock` of a first-party seam module is gate 5 (`mock-internal-seam`, ensure-coverage `references/depth/mock-policy.md`): default-on, **no `@mock-ok` waiver, no reviewer approval.** Do not bless one "with justification." Your residual role is the over-mock the lint *can't* decide (cross-file: does a real-boundary sibling actually exist?) — and you judge that by the same rule, not a softer one. A confirmed internal-seam over-mock on a changed surface is a **blocker**, and the only resolutions are: make it real, fake only the external, or **delete the test** (over-mock is worse than no test). A false positive is fixed by correcting topology in `coverage.config.json`, never waived.
+- Prefer integration evidence with real app code, real DB/migrations or test containers, broker emulator where practical, fake external adapters, and assertions on final durable state plus emitted events.
+
+## Calibration — the finding bar (the verdict)
+
+Adversarial in the *search*, calibrated in the *report*. The techniques above are tuned to surface problems; this bar keeps the verdict signal rather than noise — it is the deliberate counterweight to the adversarial stance, not a softening of it.
+
+- **Defensible and provable.** Every finding cites the diff hunk (and, for ripple effects, the *provably affected* code) — not a speculation that something "might" break elsewhere. If a conclusion rests on an inference, say so and keep the confidence honest.
+- **Discrete and actionable.** One finding = one concrete, fixable issue — not a bundle, not a general grievance about the codebase. Each answers: what can go wrong, why this path is vulnerable, the likely impact, and the concrete change that reduces it.
+- **The author would fix it.** Flag what the original author would plausibly act on; don't flag intentional changes, and don't rely on unstated assumptions about their intent.
+- **Rigor proportional to the codebase.** Don't demand prod-grade validation or comments in a repo of one-off scripts — match the bar the surrounding code already holds.
+- **Prefer a few strong findings over many weak ones.** Don't dilute a serious issue with filler; order findings by severity. If the change looks safe, say so plainly and return no findings — "no blocking issues" is a valid, valuable verdict.
+
+Attack hard while searching; then report only what survives this bar.
+
+### What not to flag (per-check guards)
+
+The adversarial techniques are tuned to surface candidates; each has a matching over-flag trap. A threshold or pattern crossing is a *hint, not a verdict* — check context, intent, and blast radius before it becomes a finding. Do **not** raise:
+
+- **Sibling divergence that is justified** — a function differing from its family because its case genuinely differs (documented or self-evident from the inputs). Flag the *unexplained* divergence, not every difference.
+- **An unanchored pattern whose inputs are bounded** — a regex without `^…$` is fine when it matches against a closed, validated set where leakage cannot occur. Produce the boundary input that actually breaks it, or drop it.
+- **A branch with coverage elsewhere** — an "untested" branch already exercised by an integration/E2E test, or a trivial guard whose failure is inert. Name branches whose failure is *observable and unproven*.
+- **A mock at a real external boundary** — a fake/stub for a third-party API, clock, email/SMS, or randomness is correct, not Mock Abuse. Reject mock-only only for the owned-internal list (DB/idempotency/concurrency/events/auth/money).
+- **Pre-existing issues unrelated to the diff** — a non-blocking note at most (diff discipline), never `NEEDS_CHANGES`.
+- **Style/structure below the repo's own bar** — don't demand prod-grade rigor in a one-off-scripts repo, or comments/validation the surrounding code doesn't hold.
+
+The throughline: a finding must clear *both* the search (it's real) and these guards (it's worth the author's attention). When unsure, lower the confidence and say what you couldn't rule out — don't inflate a guard-tripping candidate into a blocker.

package/skills/engineering/review-pr/references/review-mode.md

@@ -0,0 +1,30 @@
+# Review mode: Spec'd or Code-only
+
+The one decision that changes what is in scope — and the long list of things it
+deliberately does not change. Indexed from [SKILL.md](../SKILL.md#routing).
+Inputs feeding this decision: [inputs-and-discovery.md](inputs-and-discovery.md).
+
+## Review mode: Spec'd or Code-only
+
+Decided once, here, before any axis runs. The mode selects **what is in scope** — never how hard you look at what is.
+
+- **Spec'd** — Source Discovery found a requirement artifact that *constrains this diff*: a Review Contract, ACs in the issue or PR body, a PRD/design doc, or test criteria. Run all four axes, enumerate every AC individually, and check [contract-revision ancestry](#contract-freshness-and-precedence).
+- **Code-only** — it found none. Review the code and its tests. **Exactly one thing leaves scope: the spec-compliance axis** — the ACs, their evidence table, and revision ancestry. Record it once in the output header — `Mode: Code-only — no requirement artifact found; spec compliance not assessed` — so a reader can tell "not checked" from "checked and clean", then never raise it again: no finding, no note, no effect on the verdict.
+
+**Deciding between them.** An artifact counts only if it constrains the diff enough to be *checkable*: a title-only issue, a PR body that narrates what the diff obviously does, or a design doc the diff merely touches are **not** specs — reviewing against them manufactures ACs nobody wrote. Prefer Code-only when the artifact would not let you *write* a single AC row at all — judge the **artifact's** specificity, never whether the PR happens to satisfy it. A spec'd PR with no tests still writes its rows and fails them; if unmet ACs could flip the mode, the axis would switch off exactly when it was about to fail, which is BLOCK-3's shape inverted. Say which artifact selected Spec'd, so the choice is auditable rather than a vibe.
+
+**A missing spec is never a verdict.** Not `FAIL`, not `NEEDS_CHANGES`, not a request to go write a contract. Most repos and most PRs have no spec, and a review that stops to demand paperwork has spent a round without reading the code — which is the opposite of the job. If a *caller* requires a contract, enforcing that is the caller's gate, upstream, before it spends a review: `resolve-issues` does exactly this pre-spawn and bounces a contract-less handoff without paying for a review. A reviewer handed a diff reviews the diff.
+
+**What does not vary with mode:** the [four non-negotiable principles](../SKILL.md#non-negotiable-principles--you-are-the-first-line-of-enforcement), code correctness, domain hazards on high-risk surfaces, standards, `scan-diff`'s findings channel, [round-1 depth](review-posture.md#round-1-depth--runs-in-both-modes), the presentation/`visual-gate` check, golden-path smoke, the self-weakening rule, and any **baseline/ledger floor the repo wires** — that last one is per-*repo*, so it never went missing with the PR's spec.
+
+The dividing line is **what the check is defined against**. Anything judged against the *diff* survives — an over-mocked test, a skip-to-green, a vacuous assertion, a bug fix with no fails-without-fix test, a shared-contract change. Anything judged against the repo's *baseline* survives, because the baseline is still there. Only what is judged against *this PR's spec* can go missing, because only that artifact is absent. Reach for the mode gate solely when a check has no meaning without the ACs — and if you find yourself gating something else, that is the over-scoping this section exists to prevent.
+
+
+### Contract freshness and precedence
+
+**Trigger for the *ancestry* check: Spec'd mode, and the caller supplied a contract-revision SHA** — that is what makes ancestry checkable, and Code-only mode has nothing to be stale against. Full precedence rules: [references/contract-freshness.md](contract-freshness.md).
+
+**The two conduct rules below are not part of that trigger and run in *both* modes.** They are about what the PR does, not about a revision, and one of them is why: **an implementation PR cannot make itself compliant by weakening its own source or test criteria** unless that source change is itself explicitly approved — the self-weakening gaming vector, and the one a standalone review is most likely to face. Read that together with mode selection and the reason it cannot be mode-gated is plain: **mode is computed from the PR's own HEAD, so a PR that deletes its test criteria would select Code-only and switch off the very rule written to catch the deletion.** A diff that removes or weakens a spec artifact is a finding in either mode — and in Code-only it is worth *more* attention, since the deletion may be why Source Discovery found nothing. The second rule: **do not silently combine incompatible contracts**; say which one governs.
+
+The blocking rule: **verify PR HEAD contains that revision before any approval can count** — ancestry failure is `NEEDS_CHANGES`, and pre-revision verdicts, CI and runtime evidence are historical only.
+

package/skills/engineering/review-pr/references/review-posture.md

@@ -0,0 +1,53 @@
+# Review posture and the four axes
+
+The adversarial stance, the subject of review, the four axes kept separate, and the
+round-1 depth trigger. Indexed from [SKILL.md](../SKILL.md#routing). The full method
+behind the axes is [review-method.md](review-method.md); the depth obligations are
+[round1-depth.md](round1-depth.md).
+
+## Review Posture
+
+Be adversarial but fair: try to disprove readiness. A PR is not correct because the contract says it is; it is correct only when the contract, source spec, test criteria, tests, and diff agree. Look for contradictions, missing behavior, untested edge cases, weak mocks, implementation bugs, and hidden scope changes.
+
+When the runtime supports a dedicated review subagent, use `references/adversarial-reviewer-prompt.md`. If subagents are unavailable, apply that stance inline.
+
+**The subject is the diff.** Review the net change-set — `git diff $(git merge-base <target> HEAD)...HEAD` (three-dot; the changes that would merge, reviewed cumulatively, not per-commit). Scope findings to what the change *introduces*: a pre-existing issue is a note, never a `NEEDS_CHANGES`; a blocking finding must be attributable to this diff (trace into unchanged code only to *prove* impact). Then, across the axes in scope for your mode, be **adversarial in the search and calibrated in the verdict**. Subject → search → verdict is the whole method; detail in [references/review-method.md](review-method.md).
+
+Do not stop at style review. Keep the **four axes** separate so one does not mask another — **Code-only mode runs the last three; only spec compliance switches off** (detail: [references/review-method.md](review-method.md)):
+
+- **Spec compliance** — **Spec'd mode only; in Code-only mode this axis does not run, and its absence is not a finding.** Does the PR implement and test what it was supposed to cover? You are the **attestation point**: a self-declared `@level` is a claim; promote a `Unverified` surface to `Covered` only after reading the actual test. Classify with ensure-coverage's vocabulary, not a vague "covered." **When the source — issue, PR body, Review Contract, or test criteria — states acceptance criteria, enumerate every one and verify it individually**: one row per AC in the [Acceptance Criteria Review table](output-format.md), each resolved to the `file:line` of a test that *runs and asserts* that behavior (a skipped/guarded/degraded test is not evidence — [review-method.md](review-method.md)). An AC with no such evidence is `Missing`/`Unverified` and **blocks `PASS`**, regardless of a green CI box, a passing-looking test name, or a self-declared AC table. Never collapse multiple ACs into one "looks covered" judgment.
+
+  **Verify each AC's *outcome*, not the mechanism's *shape*** — the deeper trust failure than trusting the narration. The presence of the right call, component, or constant is *not* the AC; the user-visible result for the **real runtime input** is — instantiated with the value the app actually produces, exercised against realistic/legacy/empty-state data, and traced end-to-end to its producer (the three checks: [review-method.md](review-method.md) § Spec Compliance). Shape-matching the implementation against the claim is how code that is *present* still produces the *wrong* outcome.
+- **Coverage breadth** — **gated on whether the repo wires a baseline, not on the review mode.** The two are different artifacts and conflating them is the trap: mode comes from a *per-PR* spec, while the Surface Baseline Contract is *per-repo*. `ensure-coverage` → [breadth/surface-baseline.md](../../ensure-coverage/references/breadth/surface-baseline.md) opens by settling it — *"A requirement source (ADR/PRD/spec) is **not** a precondition for a test obligation; every surface carries a minimum floor the instant it is discovered"* — and closes with *"the baseline test obligation is the hard gate."* So where a ledger/baseline **is** wired, run it in **both** modes: a spec-less PR adding a reachable mutation route still owes its floor, and skipping the gate because nobody wrote a PRD is exactly the weakening § Coordination With ensure-coverage forbids. Where **no** baseline is wired, there is no completeness bar to fail and you do not invent one — that is the honest gap, in either mode.
+
+  Run/inspect `coverage-ledger.mjs validate` and reconcile against the Obligation Impact block. A green AC table does not clear this pass; an un-ACed surface that fails its baseline is `NEEDS_CHANGES`. What **is** Spec'd-mode-only here is the reconciliation *against ACs* — with no ACs there is nothing to reconcile, but the floor still stands.
+
+  Honesty runs in both modes regardless — principle 3's per-route line: a route with no test is a tolerable gap either way; a route whose test is over-mocked/skipped/weakened is a blocker either way.
+
+  - **Presentation sweep and `visual-gate` — both modes.** For changed browser routes, confirm the presentation sweep ran; for a surface that opted into `presentation:visual`, confirm the `visual-gate` result is present and any baseline change is a declared intended UI change. This is **principle 2**, which § Review mode lists among the things that do not vary — a bare `--update-snapshots` to green is a blocker with or without a spec.
+
+  - **Golden-path smoke — trigger: the diff touches a critical do-not-ship journey. Both modes.** The trigger is read off the diff, like round-1 depth's, so it does not switch off with the spec. Confirm `smoke.manifest.json` covers it and the gate ran. [references/golden-path-smoke.md](golden-path-smoke.md)
+
+
+- **Code correctness** — logic, error handling, races, idempotency, auth/tenant isolation, money/irreversible state, schema/migration safety, test quality. Five distinct rules, named separately because a reviewer who skips one cannot otherwise tell which:
+  - **Hunt the domain hazards** when the diff touches a **high-risk** surface — auth/authz/token, money/tax, tenancy/org-scope, migration ([references/domain-hazards.md](domain-hazards.md), plus the repo's own hazards file). Scoped, not universal: applying the hazard catalogue to every diff is the process-weight direction, not rigor.
+  - **Every blocking domain-semantic finding carries a `hazard_candidate`** — the ready-to-paste hazards-file row, or `covered_by: <id>`. You are read-only; the fix commit writes the row and the re-review verifies it.
+  - **Changed behaviour owes a characterization test** pinning what it did before — or a declared intended change **with its AC and the assertion delta visible in the diff**. Resolve `depth.characterization` against a `file:line`, never against narration: "the change is intended" asserted in a PR body is the claim, not the evidence.
+  - **Narration drift is a defect**: a PR body, comment or test name describing behaviour the code does not have is a finding, not a nitpick.
+  - **Be concrete** — every finding needs a real `file:line` and the input that breaks it. A finding you cannot produce a failing case for is a note, not a blocker.
+
+  Full rationale for each: [references/code-correctness.md](code-correctness.md).
+
+- **Standards** — documented repo standards only, cited; distinguish hard violations from judgment calls.
+
+Mock boundary for the breadth/spec passes: *real internals, faked externals* — reject mock-only for DB/idempotency/concurrency/events/auth/money; accept for external failure injection. Full rules: [references/review-method.md](review-method.md) (owned by `ensure-coverage` → `references/depth/mock-policy.md`).
+
+
+### Round-1 depth — runs in **both** modes
+
+**Trigger: the caller flagged `highRisk`, *or* the diff changes a contract other first-party code consumes, *or* the delta stands up an enforcement point of an invariant (validator, verifier, guard, promotion check) — that third at whatever round it is born, re-reviews included.** No disjunct needs a spec — one is a caller flag, the other two are read off the diff you already have — so this is **not** part of the spec axis and does not switch off in Code-only mode. A high-risk PR with no written spec is if anything the case that most needs it. The last two are yours to detect, not the caller's to pass: both are visible in the diff you are already reading.
+
+Before the first verdict: probe each changed live endpoint against the real running surface; trace the changed contract through every shared first-party consumer; **inventory every enforcement point of any invariant the diff declares** (validators, boundary guards, promotion checks — the set is larger than the consumers); and **enumerate the presentation state matrix** for any changed browser surface (locale × viewport/input-modality × action state × theme). Record concrete evidence for each, or `not-applicable` with a specific reason — **never a silent deferral to a later round**. Full obligations: [references/round1-depth.md](round1-depth.md).
+
+The last two are **sweeps**: enumerate the space, check every cell, report per-cell. **Enumerating first is what makes rounds 2..N fixing rather than discovering** — the reasoning and the named incidents are in [references/round1-depth.md](round1-depth.md).
+

package/skills/engineering/review-pr/references/round1-depth.md

@@ -0,0 +1,62 @@
+# Round-1 depth obligations
+
+**Trigger: the caller flagged the PR `highRisk`** (auth/money/tenancy/migration), **or the diff changes a contract other first-party code consumes** — the second is detected by reading the diff, not passed by the caller. Units meeting neither do not run this — applying it broadly is the process-weight regression `resolve-issues` row 7 names.
+
+**Round-1 depth obligations (deep-lane reviews only).** When the caller flags the PR **high-risk** (auth/money/tenancy/migration — `resolve-issues/references/high-risk.md`), or the diff changes a contract other first-party code consumes, or the delta stands up or changes an **enforcement point of an invariant** (validator, verifier, guard, promotion check), the four obligations below are owed **before returning the first verdict**. On that third trigger read "first verdict" as *the first verdict that sees this component* — an enforcement point born in a fix round owes obligation 3 at that round, or it is sampled by every review and swept by none. `Not applicable` needs an explicit reason; `deferred` is not an applicability result, and `BLOCKED` is the honest verdict when the required surface can't be exercised. On a routine lean-lane PR, skip this without ceremony — applying deep-lane depth everywhere is mis-spent review budget, not thoroughness.
+
+### 1. Live endpoint probing
+
+Probe each changed live endpoint against the real running surface, including the relevant authorization, boundary, pagination/filter, and failure cases. Record a concrete command and result.
+
+### 2. Shared-consumer impact
+
+Trace the changed contract through every shared first-party consumer: enumerate them, trace the producer's value into each, and exercise the affected consumer path. Record concrete evidence.
+
+## Enumerate the space before the first verdict
+
+Obligations 3 and 4 are **sweeps**: the defect does not live at one location, it lives at *some subset of a space you can write down*. For those, the round-1 obligation is not "look hard" — it is **enumerate the space, check every cell, and record a per-cell result in the first verdict.**
+
+Why this is a round-1 obligation and not diligence: a reviewer who samples the space finds one cell per round, and every cell costs the caller a full fix + re-review + CI round. The finding list converges on the code only as fast as it converges on *coverage of the space*. Enumerating first makes round 1's list complete over the space, so rounds 2..N are **fixing, not discovering**.
+
+**This is also where the contract-complete matrix gets built.** `review-method.md` § Theme reconciliation constructs the full declared matrix on the *second* same-theme finding; when obligation 3 or 4 applies, that construction is owed in round 1 instead, because the space was knowable before any finding existed. Recurrence-triggered construction is the fallback for a theme these sweeps did not cover, not the normal path — and a same-theme recurrence at round N>1 is the tell that the round-1 sweep under-enumerated (it is also what the orchestrator's circuit-breaker counts, `resolve-issues` step 3).
+
+**The over-application guard.** A space with one cell is not a sweep; say so in one line and move on. Do not manufacture a matrix for a diff that changes one function at one call site, and do not enumerate dimensions the repo does not actually support (no second locale, no dark theme, no mobile breakpoint ⇒ those are not cells). The sweep is scoped by the same trigger as the rest of this file.
+
+### 3. Invariant enforcement-point inventory
+
+**Applies when the diff declares, changes, or relies on an invariant that must hold at more than one place** — an all-or-none field contract, a canonical grammar for a wire value, a validation rule, a required-provenance rule, a promotion/admission precondition.
+
+Obligation 2 traces a *value* into its consumers. This traces an *invariant* into its **enforcement points**, which are usually a different and larger set: producers, serializers/exporters, validators, boundary guards on the request path, promotion/admission checks, the schema layer on the far side of the wire, and the tests that pin each. A consumer that merely reads the value is not an enforcement point; a validator that never sees a consumer is.
+
+Before the first verdict:
+
+- **Write the invariant as one sentence**, in the form the code must satisfy — not the story it came from.
+- **Enumerate every enforcement point** by searching for the fields/rules the invariant names across the whole tree, not just the diff. The diff shows where the author *did* enforce it; the tree shows where it *must* be enforced.
+- **Check the invariant at each**, and record one row per point: location, enforced/not-enforced, evidence locator.
+- Points found unenforced are **findings in round 1**, individually and all of them — never "and similar issues may exist elsewhere," which is a sample presented as a sweep.
+- **When the component under review *is* the enforcement machinery** — a verifier, a gate, a daily checker — the points are the checks *inside* it, and the invariant is what it exists to guarantee, which for this shape is almost always *fail closed on any drift*. Enumerate the dimensions of the state it inspects (identity, completeness of the set it compares, the read-model differences it must normalize, the thresholds it asserts) and ask of each: what value here makes this pass when it should fail? A fail-open hole per dimension is one round per dimension otherwise, because each names a different space and no per-finding rule spans them.
+
+*Named incident: skyee-ai-risk #1124 / PR #1138. One invariant — every expanded snapshot row carries the complete required contract, all-or-none. It was enforced at six places: a shared contract validator, the service query path, the export job, the promotion/refresh script, the far-side schema layer, and the contract tests. Review rounds 4, 5, 6, and 7 each found it unenforced at two or three of those files — eleven blockers, one invariant, four rounds, because each round searched rather than enumerated.*
+
+*Named incident (the enforcement-machinery shape, and why this obligation is not round-1-only): forex #87. A deployment verifier was stood up in a fix round, so it never existed at round 1 and every later review saw it only through a delta scope. Rounds 4–7 returned exactly one theme each — `alert-verifier.quota-policy-name`, `alert-artifacts.canonical-completeness`, `alert-verifier.gcp-read-model-normalization`, `alert-verifier.notification-channel-drift` — against rounds 1 and 3, which returned four and eight. Each named a different space, so the fix side's re-run-every-cell rule spanned none of them; what they shared was the component's own property, that it must fail closed on any drift. Four rounds, one property, ~85 minutes of fix time, because the component whose whole job was to fail closed was the one component nobody enumerated.*
+
+### 4. Presentation state matrix
+
+**Applies when the diff changes what a browser surface renders** — a component's rendered states, an interaction affordance, an enabled/disabled treatment, a dialog/tooltip host. Not for a diff that only changes server code behind an unchanged surface.
+
+A rendered state is a point in a product space, and presentation defects live in cells, not in components. Before the first verdict, write down the dimensions **the repo actually supports** and check every cell. The dimensions that usually apply:
+
+- **locale** — each supported language (copy presence, overflow, truncation)
+- **viewport + input modality** — desktop pointer, keyboard focus, mobile touch. *Touch is its own cell, not a narrow viewport:* a tooltip primitive that shows on hover and focus can still suppress touch-origin focus, so pointer and keyboard passing proves nothing about tap.
+- **action/interaction state** — enabled, disabled, pending, denied-with-reason, error
+- **theme** — light and dark, including contrast ratios for any changed color token
+
+Record a per-cell result. Cells that fail are round-1 findings; cells the repo does not support are struck from the matrix with a one-line reason, not carried as `not-applicable` rows.
+
+*Named incident: skyee-ai-risk #1144 / PR #1148. Disabled row-action denial reasons had to be perceivable. Round 7 found pointer-hover/focus hidden; round 8 found the touch cell still hidden after the pointer fix; a later pass found the destructive-button contrast cell failing in both themes. Three cells of one matrix, three rounds — and the matrix was never larger than two locales × three input modalities × two action states × two themes for one component.*
+
+## Recording the sweeps
+
+Each sweep records, in the round-1 verdict: the space as enumerated (dimensions or point list), the per-cell/per-point result, and the evidence locator for each checked cell. A sweep whose output is a prose paragraph rather than an enumeration did not run — same bar as a finding with no `file:line`.
+
+`Not applicable` requires the specific reason (obligation 3: the invariant holds at exactly one place, named; obligation 4: the diff changes no rendered state). As above, `deferred` is not an applicability result, and a sweep that cannot be executed against a real surface is `BLOCKED` for the part it covers, never a silent pass.

package/skills/engineering/review-pr/references/scripts.md

@@ -0,0 +1,17 @@
+# Scripts — mechanics
+
+The three bundled scripts and what each guarantees. Indexed from
+[SKILL.md](../SKILL.md#routing), which keeps the two rules that are *judgment* rather
+than mechanics: resolving a script against this skill's own directory, and the fact
+that `blocking` is derived rather than set.
+
+**Blocking is *derived*, not a flag you set: `blocking == in_scope && priority <= 1`.** The reviewer's job is the *judgment* — pick the finding's `priority` (`0–3`, the one severity scale) and whether it is `in_scope` (about this diff, default true), and confirm every `priority ≤ 1` maps to a named blocking class above. The *mechanism* is `post-review.mjs`: it renders the label (in-scope `p0–1` → `BLOCK-n`; everything else → `NOTE-n`), derives the verdict (`NEEDS_CHANGES` iff ≥1 `BLOCK-n`, else `PASS`; `FAIL`/`BLOCKED` unchanged), and routes non-blocking findings to tracked issues — the in-scope/out-of-scope `p2–3` notes batched into one `refactor-later` issue, and an **out-of-scope `p0–1`** (a real defect in code this PR didn't change) to its own critical/security issue plus a loud warning, *without* blocking the PR. Do not emit a free `blocking` field; a finding still carrying one is read-tolerated (warned) and its stored value is ignored in favor of the derivation.
+
+Mechanics are scripted so the deterministic, error-prone glue is reliable; judgment stays in the prose above.
+
+- **`scripts/pr-context.mjs --base <target>`** — compute merge-base + net three-dot diff + changed files + commits (diff-discipline as code). Language-agnostic.
+- **`scripts/scan-diff.mjs`** (`git diff <range> | …`) — two channels. **`leads`** (heuristic, "look here and verify"): unanchored regex, first-party interception in tests, new branches, weak assertions, `modifies-existing-behavior`. **`findings`** (decidable **blockers**): `over-mock-internal-seam` — a `vi`/`jest`/`vitest.mock` of a first-party seam, via a **vendored** copy of `ensure-coverage`'s classifier so review-pr is fully standalone (no dependency on `ensure-coverage` being wired). Zero-config; reads `coverage.config.json` topology if present. Best-effort/JS-TS-oriented. *The vendored classifier tracks `ensure-coverage` (`references/depth/mock-policy.md`), which stays canonical; drift isn't honor-system — `scripts/vendor-sync.test.mjs` runs both copies through the full classification decision tree and fails on any divergence (it skips when `ensure-coverage` isn't installed), so resync the vendored copy when that test fires.*
+- **Whole-tree inherited over-mock** (beyond this PR's diff) is an **audit** concern, not a PR-review one (diff-discipline: pre-existing issues are notes, not blockers); `ensure-coverage`'s `lint-tests --rules mock-internal-seam` run whole-tree covers it when available.
+- **`scripts/post-review.mjs --findings <json> --pr <n> [--pr-context <file>]`** — validate findings (reject location-less ones), render the `BLOCK-n`/`NOTE-n` label + derive the verdict from `{priority, in_scope}`, self-authored downgrade, post the single review. `--pr-context` reuses `pr-context.mjs`'s own `changedFiles` (never recomputed here) to keep a finding whose path isn't actually in the diff off `comments` even when `in_scope: true` (#635) — omitted/unreadable fails toward posting (falls back to the `in_scope`-only check, never drops a finding or blocks the post). Routes non-blocking notes to a batched `refactor-later` issue and each out-of-scope critical to its own issue — but only under `--file-issues` (default OFF prints what it would open; the out-of-scope-critical warning prints either way). Language-agnostic.
+
+Tests: `node --test scripts/*.test.mjs`.

package/skills/engineering/review-pr/references/workflow.md

@@ -0,0 +1,16 @@
+# Review workflow — the eight steps
+
+The order the review runs in. Indexed from [SKILL.md](../SKILL.md#routing). Each step
+names the reference that owns its detail.
+
+## Review Workflow
+
+
+1. Establish the subject and collect evidence: fetch the target branch; run `scripts/pr-context.mjs --base <target-branch> > <pr-context.json>` to get the merge-base, the net `base...HEAD` diff, changed files, and the commit list in one shot (this is diff-discipline as code — no two-dot/wrong-base mistakes) — **save its stdout to a file**; step 8 reuses that same `changedFiles` list (`--pr-context <file>`) so posting never re-derives the diff from a possibly-drifted checkout. Pipe the diff through `scripts/scan-diff.mjs`, which returns **two channels**: heuristic `leads` (unanchored regex, first-party interception, new branches) — *leads to verify, never findings* — and the decidable `findings` channel (`over-mock-internal-seam`), whose hits are **blockers** to carry into the verdict (principle 1), standalone and zero-config. Then gather the PR body, Review Contract, linked issues/specs/test criteria, comments, tests, CI evidence, and documented standards.
+2. Select the [review mode](review-mode.md) — it gates the step below, so it is settled first. Then resolve contract freshness and precedence (the ancestry half runs in Spec'd mode only; the two conduct rules run in both). Verify supplied contract-revision ancestry, discover any newer approved target-branch revision affecting the PR, and switch to a full-scope review when the authoritative revision differs from the one used by the last verdict.
+3. Extract the claims to verify. In Spec'd mode: source requirements, ACs, test-criteria expectations, contract mappings, mock policy, known gaps, standards. In Code-only: the same list minus the spec-derived entries, plus the diff's own claims — PR body, comments, test names — which remain checkable against the code and are where narration drift shows up.
+5. Review the axes in scope for the mode, separately ([review-method.md](review-method.md)); run/inspect the coverage gate for changed surfaces **wherever the repo wires one — both modes**, per the Coverage breadth axis. The gate answers to the repo's baseline, not to this PR's spec.
+6. Cross-check contradictions between claims, implementation, tests, mocks, CI, and standards.
+7. Return `PASS` / `NEEDS_CHANGES` / `FAIL` / `BLOCKED` with per-AC status and required changes, in the [output format](output-format.md) — **every finding must cite a diff `file:line` + a confidence; no code location ⇒ it's `Unverified`, not a finding.** (This is what enforces "verify the code" — you can't form a finding without locating it.)
+8. If the review target is a real GitHub PR, post the verdict and findings back to GitHub ([github-posting.md](github-posting.md)).
+