@1aboveio/skills 0.10.0

package/skills/engineering/review-pr/references/domain-hazards.md

@@ -0,0 +1,123 @@
+# Domain hazards — the high-risk-surface hunt list
+
+A catalog of the **recurring, cross-repo bug classes** that a happy-path implementer ships and CI passes green, so the independent review (or production) is the first thing to catch them. It exists because these are the surfaces whose governing contract is hardest to pin down up front, so a first review most often still finds something to fix: auth, money, tenancy, and migrations. (A low first-pass rate here is a **spec-maturity** signal — a hard surface needs a more explicit contract — not a verdict on the reviewer or the code.) Use it two ways:
+
+- **Reviewer** ([review-pr](../SKILL.md), code-correctness axis) — when the diff touches one of these surfaces, hunt it against the matching section and treat any unhandled item as a blocking finding.
+- **Implementer / self-review** ([implement-and-pr](../../implement-and-pr/SKILL.md#self-review-before-handoff-adversarial-pass)) — hunt your own diff against it *before* opening the PR, so the cheap-to-catch class doesn't consume a review round.
+
+This is the **generic** list — the failure *shape* that recurs everywhere. The **repo-specific values** (which issuer/audience string, which currencies, which tenant column, which migration tool) live in the repo's own **hazards file** — see [The repo hazards file](#the-repo-hazards-file-location-schema-lifecycle) for its location, schema, and how it grows. Hunt against **both**: this catalog for the shape, the repo file for the concrete values. If a repo touches a high-risk surface and has *no* hazards file, that absence is not just a gap to note — the implementer **seeds** it (see the lifecycle below).
+
+The unifying rule for every class below: **decide by a positive allow-list, default to deny/refuse, and prove the outcome for the value the app actually produces at runtime — not the convenient fixture.** Most of these bugs are an `else` branch that permits, a default that's wrong, or a test pinned to a stand-in value the real producer never emits.
+
+---
+
+## 1. Auth / authz / token / session
+
+| Hazard | Failure mode (real cases) | What to prove |
+|---|---|---|
+| **Fail-open guard/verifier** | On error / unknown input / unmatched branch, the code *allows* instead of denying. A signature verifier with an HMAC catch-all fallback; a country/eligibility check that skips the gate for unrecognized spellings. | Every error and `else` path **denies**. The default is deny. Add a test that feeds the unrecognized/garbage input and asserts refusal. |
+| **Token/assertion validation** | Wrong issuer, wrong/defaulted `client_id`, missing audience check, unpinned algorithm (accepts `none` or HMAC where RS/ES expected). POSTing to the wrong endpoint (broker vs OIDC issuer). | `iss` / `aud` / `scope` / `exp` / signature-alg each asserted against the **real IdP contract**, not a literal default. Alg pinned. Target endpoint is the issuer, verified against the discovery doc. |
+| **Replay / single-use / idempotency** | A one-time code (nonce, `jti`, `device_code`, OTP) accepted twice; no brute-force limit. | The code is consumed **atomically** and a second use is rejected; a replay test proves it; sensitive endpoints are rate-limited. |
+| **Clock skew** | Assertion/token lifetime unbounded or with no skew tolerance; `iat`/`nbf`/`exp` mishandled. | Lifetime is clamped to a bounded window; skew tolerance is explicit; a token just inside/outside the window is tested both ways. |
+| **Open redirect / dropped `returnTo`** | Redirect target derived from user input without an allow-list; a centralizing auth refactor drops the deep-link `returnTo` and lands the user on a default page. | Redirect targets pass a **positive allow-list** (`^/(?![/\\])` or exact known routes), and `returnTo` survives the whole flow (characterization test on the deep-link path). |
+| **Privilege on switch** | Org-switch / impersonation / role change doesn't re-scope the session or leaves stale elevated state. | The switch re-derives authorization; a test asserts the post-switch scope, not just that the switch succeeded. |
+
+## 2. Money / tax / pricing
+
+| Hazard | Failure mode (real cases) | What to prove |
+|---|---|---|
+| **Conversion direction** | Divide-vs-multiply inverted; response keyed to the base currency (USD) when the caller asked for the quote currency; daily vs realtime endpoint confused. | Direction asserted with a **known rate and a known expected result**; the response is keyed to the currency actually requested; the endpoint matches the contract. |
+| **Precision & storage range** | Minor-unit integer column too small for the validated max — validation passes, the INSERT overflows and 500s (INT4 column vs a `1e11` Zod cap). | Storage type holds the max plausible value; the validation cap is **≤** the storage range; a max-size input is tested end-to-end through the write, not just through validation. |
+| **Rounding** | Undefined or inconsistent rounding (half-up vs banker's); rounding applied at the wrong step; tax computed on the wrong base. | Rounding mode and step are explicit and tested at the boundary; tax base/order matches the spec. |
+| **Immutability & state** | An issued invoice/number/ledger entry is mutable; a paid/void transition isn't guarded. | Post-issue mutation is rejected; state transitions go through one authoritative guard; the guard is tested for the illegal transition. |
+
+## 3. Tenancy / org-scope / isolation
+
+| Hazard | Failure mode (real cases) | What to prove |
+|---|---|---|
+| **Cross-org leakage** | A read or write not filtered by tenant/org; lineage or join that crosses orgs (cross-org TaskRun lineage leak). | **Every** query is scoped by tenant by default (scoping is not opt-in); a two-org test asserts org A cannot see/mutate org B's rows. |
+| **Authorization scope drift** | Ad-hoc role-string compares that a centralized detector misses (alias forms like `const role = …; return role === 'admin'`); checks in an app the audit doesn't cover. | Authorization is centralized; no inline role-string equality; the detector/audit covers every app, and a real instance is caught by a test. |
+
+## 4. DB migration / schema
+
+| Hazard | Failure mode (real cases) | What to prove |
+|---|---|---|
+| **Type/range vs validation** | Column type can't hold the value the app validates as legal (see money precision). | Column range ≥ the app's accepted range; asserted with a boundary write. |
+| **Migration scope creep** | A migration bundles unrelated changes or an unintended column/table drop; schema drifts from the intended migration. | One concern per migration; the diff contains **only** the intended change; drift is reconciled, not silently regenerated. |
+| **Backfill / nullability / locks** | Adding a NOT NULL column without a default or backfill; a migration that locks a hot table. | New columns are nullable-or-defaulted with a backfill plan; lock-heavy changes are called out; the migration is reversible or the irreversibility is declared. |
+
+## 5. Cross-cutting refactor (the "centralizing drops an edge case" class)
+
+Not a surface — a *move*. Consolidating a cross-cutting concern (auth redirect into a layout, mutation feedback into a shared hook, a loading boundary into a route group) is the single most reliable way to **silently drop a pre-existing edge behavior**: a deep-link `returnTo`, a fail-loud error toast that becomes fail-silent, a sibling route's own skeleton. The hazard shape: *green new tests pass while an edge the old path quietly handled is gone.*
+
+**What to prove:** the pre-existing edges are pinned before the move — the characterization obligation, owned by [ensure-coverage → depth/characterization.md](../../ensure-coverage/references/depth/characterization.md) (`scan-diff.mjs` raises `modifies-existing-behavior` on exactly these diffs).
+
+---
+
+## The repo hazards file (location, schema, lifecycle)
+
+The repo-specific layer is a **standalone file, not a section inside `CLAUDE.md`/`AGENTS.md`** — the agent-instructions file loads into every session, while hazards are only needed when a diff touches a high-risk surface, so the values live out-of-line and the instructions file carries only an index pointer.
+
+### Location & discovery
+
+- **Canonical path: `docs/domain-hazards.md`** at the repo root's `docs/` directory.
+- **Index pointer (required):** the repo's `AGENTS.md` (or `CLAUDE.md`) carries a short `## Domain hazards` section whose only job is to point at the file, e.g.:
+
+  ```markdown
+  ## Domain hazards
+  Repo-specific high-risk rules (auth/money/tenancy/migration): read
+  `docs/domain-hazards.md` before touching any of
+  those surfaces or reviewing a diff that does.
+  ```
+- **Discovery order** (for any skill that hunts): follow the `Domain hazards` heading in `AGENTS.md`/`CLAUDE.md` to its linked file → else try `docs/domain-hazards.md` directly → else the file is **absent** (seed obligation below). A legacy repo with the values inline under that heading still counts — migrate them to the file the next time a hazard row is added.
+
+### File schema
+
+One table per surface class, mirroring this catalog's sections so the generic shape and the repo value line up. Every row is one hazard with a **stable ID**, the repo's **concrete rule**, the **test obligation**, and the **source** that earned it:
+
+```markdown
+# Domain hazards — <repo>
+
+Repo-specific values for the high-risk-surface hunt. Generic bug *shapes* live in
+the skills catalog (review-pr → references/domain-hazards.md); this file holds only
+what is true of THIS repo. One row per hazard. Sections mirror the catalog.
+
+## Auth / authz / token / session
+| ID | Hazard (this repo's rule) | What to prove | Source |
+|---|---|---|---|
+| auth-issuer | Issuer is `https://id.example.com`, never the broker URL; tokens assert `iss` + `aud=<client_id>`. | Token test asserts both against the real discovery doc values. | #231 (2026-06-17) |
+
+## Money / tax / pricing
+| ID | Hazard (this repo's rule) | What to prove | Source |
+|---|---|---|---|
+
+## Tenancy / org-scope / isolation
+…
+
+## DB migration / schema
+…
+
+## Cross-cutting
+…
+```
+
+- **ID** — kebab-case, class-prefixed, stable once assigned (`auth-resume-param`, `money-int4-range`). Findings and dedupe reference it.
+- **Hazard** — one line, imperative, carrying the repo's *concrete values* (the exact issuer, param, column, tool). Never restate a generic shape this catalog already owns.
+- **What to prove** — the test obligation a diff touching this hazard owes (the assertion, the two-org test, the boundary write).
+- **Source** — the PR/finding (and date) that earned the row, so every rule is traceable to a real bug.
+
+### Admission rules (what keeps the file honest and small)
+
+1. **Repo-specific values only** — a generic shape belongs in this catalog, not the repo file; duplicating it there is noise.
+2. **Blocking domain-semantic findings only** — a row is earned by a real bug (an independent-review blocker or a self-review catch on a high-risk surface), not by speculation. Style nits and coverage gaps never earn rows.
+3. **Dedupe by meaning, not wording** — if an existing row already covers the bug, the resolution is "covered by `<id>`", never a near-duplicate row.
+4. **One line per hazard** — a row that needs a paragraph is two hazards or a doc link.
+
+### Lifecycle (how the file grows as a by-product of the loop)
+
+The reviewer **proposes**, the fixer **writes**, the re-reviewer **verifies** — the reviewer is read-only by contract, so it never edits the file itself:
+
+1. **Propose (review-pr):** a blocking domain-semantic finding on a high-risk surface carries a `hazard_candidate` in the findings JSON (`schemas/findings.schema.json`) — a ready-to-paste row (section, id, rule, prove), or `covered_by: <id>` when an existing row already captures it.
+2. **Write (implement-and-pr, fix round):** the fix commit for that finding includes the candidate row in `docs/domain-hazards.md` (creating file + index pointer if absent). A hazard row tied to a finding fixed in the same PR is **in-scope by declaration** — it is never "broad unrelated changes."
+3. **Verify (review-pr, re-review):** a prior finding that carried a `hazard_candidate` is not `Resolved` until **both** the code fix and its hazards-file row (or an explicit `covered by <id>`) are present in the tree.
+4. **Seed (implement-and-pr, self-review):** a high-risk diff in a repo with **no** hazards file creates it — file, index pointer, and the rows for the hazards the self-review actually checked — rather than merely flagging the absence in Known Gaps.

package/skills/engineering/review-pr/references/finding-themes.md

@@ -0,0 +1,7 @@
+# Finding themes (deep lane / state-machine / concurrency)
+
+**Trigger: a high-risk unit, or a state-machine/concurrency finding.** Routine findings may omit `theme` entirely.
+
+### Finding themes (deep lane / state-machine / concurrency)
+
+A finding's optional `theme` (stable kebab-case id + kind + the general violated contract) is the identity that powers same-theme recurrence detection and contract-complete fixes. It is **required only on `state-machine`/`concurrency` findings** (which also declare the full `stateSpace`) and throughout the deep lane (`resolve-issues/references/high-risk.md`); a routine lean-lane finding may omit it. A recurring finding keeps its id — a new counterexample is not a new theme. Detail: [review-method.md](review-method.md) § Theme reconciliation.

package/skills/engineering/review-pr/references/github-posting.md

@@ -0,0 +1,98 @@
+# Posting the Review to GitHub
+
+When the review target **is a real GitHub PR** — you were given a PR number/URL (the PR is the source of truth for the code under review) and `gh` is authenticated — post the review back to GitHub automatically as the final step. Do not wait for confirmation. Still return the full report in the conversation as well.
+
+Do **not** post when there is no real PR to post to: reviewing a local diff, uncommitted working-tree changes, a branch with no open PR, or a Review Contract pasted into the conversation. In those cases return the report only.
+
+## Prefer the script
+
+`scripts/post-review.mjs --findings <findings.json> --pr <number> --pr-context <pr-context.json>` does everything below: it validates the **full review document** (verdict, top-level shape, and canonical findings) against [`schemas/findings.schema.json`](../schemas/findings.schema.json) (**refusing any finding without a `file:line`**), auto-detects the self-authored downgrade (`gh api user` vs PR author), maps verdict→event, and posts the single review via the reviews API. `--pr-context` points at the saved stdout of step 1's `pr-context.mjs --base <target-branch>` run — reusing its `changedFiles` list, never recomputing the diff — so a comment whose `file` isn't actually in the diff is diverted to the review body instead of anchored, even when the reviewer marked it `in_scope: true` (see "Out-of-scope, and off-diff, findings never anchor inline" below). Use `--dry-run` to inspect the payload first. The rest of this file documents *what it does* — the manual fallback and the rules the script encodes.
+
+### Label, verdict, and issue routing are rendered — not written by the reviewer
+
+The reviewer emits JSON only (`{title, priority, in_scope, …}`). `post-review.mjs` derives the rest so any reviewer model maps to one output:
+
+- **Label** — each inline comment is prefixed with a rendered `BLOCK-n`/`NOTE-n` (sequenced per class): in-scope `priority ≤ 1` → `BLOCK-n`; everything else → `NOTE-n`. No `[P1]`/`F-`/`N-` prefixes.
+- **Verdict** — `NEEDS_CHANGES` iff ≥1 `BLOCK-n`, else `PASS`; `FAIL`/`BLOCKED` pass through unchanged. The verdict maps to the review event as below.
+- **Removed `blocking` field** — a finding still carrying `blocking` is read-tolerated (it warns and the value is ignored; blocking is `in_scope && priority ≤ 1`).
+
+### Firing notes as tracked issues (`--file-issues`, default OFF)
+
+Non-blocking findings route to GitHub issues so they are neither lost nor left holding attention on the PR:
+
+| finding | routes to |
+|---|---|
+| in-scope `priority 2–3` | the **one** batched `refactor-later` issue (links the PR) |
+| out-of-scope `priority 2–3` | the same batched `refactor-later` issue |
+| out-of-scope `priority 0–1` | its **own** dedicated issue (`critical`/`security` labels) **plus a loud warning** — it does *not* block the PR |
+| in-scope `priority 0–1` | no issue — it is a `BLOCK-n` that holds the PR |
+
+**Issue creation is an outward action, so it is gated behind `--file-issues` and DEFAULTS OFF** — without the flag the script prints what it *would* open and creates nothing. This keeps normal review runs and tests from opening real issues. The out-of-scope-critical **warning prints regardless of the flag** (a warning is free; opening an issue is not). One `refactor-later` issue per PR — the notes are batched, never one issue per note.
+
+## Submit a single review (inline comments + summary + verdict)
+
+Submit one review that carries the inline/file-specific comments, the top-level summary, and the verdict event together, via the reviews API:
+
+```bash
+gh api --method POST \
+  repos/{owner}/{repo}/pulls/{number}/reviews \
+  -f event='REQUEST_CHANGES' \
+  -f body='<top-level summary: verdict, spec compliance, systemic risks, required changes>' \
+  -f 'comments[][path]=src/foo.ts'  -F 'comments[][line]=42' -f 'comments[][body]=<concrete defect>' \
+  -f 'comments[][path]=src/bar.ts'  -F 'comments[][line]=88' -f 'comments[][body]=<concrete defect>'
+```
+
+If a runtime makes the reviews API awkward, fall back to `gh pr review <number> --approve|--request-changes|--comment --body '<summary>'` for the top-level review plus `gh pr comment` / `gh api .../comments` for inline notes.
+
+## Verdict → review event mapping
+
+| Verdict | GitHub review event |
+|---|---|
+| `PASS` | `APPROVE` |
+| `NEEDS_CHANGES` | `REQUEST_CHANGES` |
+| `FAIL` | `REQUEST_CHANGES` |
+| `BLOCKED` | `COMMENT` |
+
+`APPROVE` and `REQUEST_CHANGES` are formal signals that can gate merge under branch protection — only emit `APPROVE` on a genuine `PASS`. `BLOCKED` posts as a neutral `COMMENT` because the review could not reach a reliable verdict.
+
+## Self-authored PRs
+
+GitHub forbids a user from submitting an `APPROVE` or `REQUEST_CHANGES` review on a PR they authored (`gh`/the API returns "Can not approve/request changes on your own pull request"). In agentic chains the same identity often both opens the PR (`implement-and-pr`) and runs this review, so check before submitting:
+
+```bash
+# reviewer identity vs PR author
+me=$(gh api user --jq .login)
+author=$(gh pr view <number> --json author --jq .author.login)
+```
+
+When `me == author`, **downgrade the event to `COMMENT`** regardless of verdict — it is the only event GitHub permits on your own PR. Do not let the submission fail and silently skip posting. Preserve the real verdict in the review `body` so the signal is not lost, e.g.:
+
+> **Intended verdict: NEEDS_CHANGES** — posted as a comment because the reviewer is the PR author and GitHub disallows self approve/request-changes. Treat the Required Changes below as blocking before merge.
+
+Inline comments still post normally under a `COMMENT` event. When `me != author`, use the standard Verdict → event mapping above.
+
+**Guarantee 2 still holds under self-authored COMMENT** (epic-876 / #941). Mergify/branch protection may never see an `APPROVE` event from this identity; that does not mean the independent review did not run. `post-review.mjs` returns `reviewPostedAs: comment-self-authored` (and prints it on the CLI). The orchestrator records that field on the unit along with the intended verdict and the review model read-back — **transcript + COMMENT body + model diversity is the proof**, not a GitHub APPROVE. Do not re-run review solely because `reviewDecision` stays empty/APPROVED-by-bot-only.
+
+## Comment placement
+
+Leave inline/file-specific comments for concrete code or test defects, anchored to the offending line. Reserve the top-level review `body` for the verdict, spec-compliance summary, systemic risks, and the consolidated Required Changes list. Every inline comment should cite the specific defect (file, line, failing behavior, or contract claim) rather than restating the summary.
+
+### Out-of-scope, and off-diff, findings never anchor inline
+
+GitHub refuses to anchor a review comment on a `path` that isn't in the PR's diff and 422s the **entire** review — losing the verdict, the summary, and every other inline comment with it. Two finding shapes hit this:
+
+- **`in_scope: false`** — by definition about a file the diff didn't touch (#628).
+- **`in_scope: true` whose `file` still isn't in the diff** (#635) — this doctrine's own § Review Posture permits tracing into unchanged code to *prove* impact, so a finding can legitimately be `in_scope: true` and still name a file the diff never touched.
+
+`post-review.mjs` never anchors either shape: it validates every comment's `path` against `--pr-context`'s changed-file list (falling back to the `in_scope`-only check when that list isn't available — never dropping a finding or blocking the post either way) and moves anything it can't anchor into a `## Findings not anchored inline` section of the review body instead, in full detail (why/consequence/fix) — the only place left for it. An out-of-scope **critical** additionally keeps its existing loud warning at the top of the body.
+
+### Writing an inline comment
+
+Each inline comment is one finding. Make it land:
+
+- **State the triggering condition up front.** Name the scenario, input, or environment the bug needs ("when `token` is empty…", "on retry after a partial write…"). The severity often *depends* on that condition, so the reader needs it immediately.
+- **Be severity-accurate.** Don't inflate a minor issue or undersell a serious one. If it's conditional or low-likelihood, say so.
+- **Be brief.** At most one short paragraph; no line breaks mid-sentence unless a code fragment needs it.
+- **Keep code fragments tiny.** No chunk longer than ~3 lines; wrap code in backticks or a fenced block. Keep the anchored line range as short as possible (the smallest subrange that pinpoints the issue, not a 30-line span).
+- **Matter-of-fact tone, no flattery.** Read as a helpful suggestion, not a human-reviewer performance — avoid "Great job…", "Thanks for…", and praise padding.
+- **End with the concrete fix** (or the question, if you genuinely can't tell), so the author can act without re-deriving it.

package/skills/engineering/review-pr/references/golden-path-smoke.md

@@ -0,0 +1,5 @@
+# Golden-path smoke check
+
+**Trigger: the diff touches a critical do-not-ship journey** (sign in → core action → pay). Otherwise there is no golden path at stake and this does not apply.
+
+- **Golden-path smoke:** if the change touches a critical do-not-ship journey (sign in → core action → pay), confirm `smoke.manifest.json` covers it (a new critical flow with no entry is `NEEDS_CHANGES`) and the attached `smoke-results.json` + `smoke-verdict.json` show `ALIVE` against the current HEAD — the per-PR golden-path liveness floor (`ensure-coverage` gate 8 / skill `smoke`); a missing or DEAD verdict blocks regardless of CI color.

package/skills/engineering/review-pr/references/incremental-output.md

@@ -0,0 +1,16 @@
+# Incremental output — compose in the file, not in your context
+
+**Trigger: an output path was configured.** The three rules that survive without this file are in SKILL.md; this is the resume mechanics and the rationale.
+
+## Incremental output: compose in the file, not in your context
+
+When the caller configures an output path, build the review **in that file as you go** — never hold it in context and write it once at the end. Before the first axis, write the identity header (PR, base/head/tree SHAs, scope, `status: in-progress`). Append each finding as you confirm it and each AC row as you decide it. Write the verdict **last**, in the same pass that flips `status: complete`.
+
+Why: a review composed at the end is lost *whole* when the run dies — turn budget, provider quota, a crash — and the replacement restarts from zero on a diff that hasn't changed. (Named incident: on skyee-ai-risk #938, two reviewer runs were killed at 65 and 47 assistant turns against soft limits of 24 and 30, discarding completed review work both times; the run that finally landed had to be hand-told to read the dead run's transcript to avoid redoing it.)
+
+Two rules keep a partial safe to leave on disk:
+
+- **No verdict until complete.** An in-progress artifact carries no verdict field *at all* — not `PENDING`, absent. The verdict is the one thing a caller acts on, so it must never exist before the scan that earns it. A caller reading `status: in-progress` treats the review as **not run**, exactly as it would treat a missing file. Getting this backwards is worse than no artifact: a partial that reads as a verdict is how unreviewed code merges.
+- **The identity header is the resume key.** A resuming or replacement reviewer reads the partial first and continues from it **only if base/head/tree match exactly**. On any mismatch, discard it and start fresh — findings against a different tree are worse than no findings, because they look like coverage.
+
+Resuming is then mechanical: read the partial, take its covered ACs and confirmed findings as done, scan only what's outstanding, finish the verdict. Where no output path is configured, return the review in your final response as before — this is about durability, not format.

package/skills/engineering/review-pr/references/inputs-and-discovery.md

@@ -0,0 +1,31 @@
+# Required inputs, source discovery, and finding themes
+
+What a review needs before it starts, how to look for a spec before declaring one
+missing, and when a finding carries a stable `theme` id. Indexed from
+[SKILL.md](../SKILL.md#routing). What the discovery *finds* selects the mode:
+[review-mode.md](review-mode.md).
+
+## Required Inputs
+
+- Pull request body and diff.
+- Review Contract when required or present (template: `ensure-coverage` → `references/process/review-contract-template.md`).
+- Referenced `/docs/tests/YYYY-MM-DD-...` test criteria or equivalent when present.
+- Referenced source PRD/design doc/spec/bug brief/issue when present (PR body, contract, linked issues, comments, tracker).
+- CI/test evidence referenced by the PR when available.
+
+If the PR lacks a valid Review Contract, run [Source Discovery](#source-discovery) — the PR body, linked issues, comments, branch name, or tracker links may point to the source spec/test criteria. What that finds selects the [review mode](review-mode.md), and finding nothing is a legitimate mode rather than a defect. Distinguish **absent** from **inaccessible**: a spec that is referenced but unreachable, with no approved exception, is `BLOCKED`; a spec that simply does not exist is Code-only mode. Use `NEEDS_CHANGES` for normal implementation/test/coverage defects.
+
+
+### Finding themes (deep lane / state-machine / concurrency)
+
+**Trigger: a high-risk unit, or a state-machine/concurrency finding.** Routine findings may omit `theme` entirely. Shape and stability rules: [references/finding-themes.md](finding-themes.md).
+
+The one that matters to the caller: **a recurrence of the same underlying contract keeps the same `theme.id`** — that identity is what the orchestrator's circuit-breaker counts to tell a unit circling one invariant from a unit discovering an unwritten design.
+
+
+## Source Discovery
+
+Before declaring source material missing: read the PR body + contract refs; open linked issues, comments, tracker links, PRD/spec/design links, and `/docs/tests/` links; follow issue references from branch name, commits, PR title; search likely in-repo spec locations (`/docs/`, `/docs/tests/`, `/specs/`) by title/branch/issue/slug. Use the linked source as the spec-compliance authority even if the PR body only summarizes it. If a link is inaccessible and prevents reliable review, return `BLOCKED` with the recorded link.
+
+Review against whatever requirement artifact this discovery finds (fetch and read it first — linked material counts). Finding **none** selects Code-only mode below. That lowers nothing about how hard you look at the code; it only removes a question you have no authority to answer.
+

package/skills/engineering/review-pr/references/output-format.md

@@ -0,0 +1,99 @@
+# Output Format
+
+## Every finding carries its proof (verification is enforced by the shape, not willpower)
+
+The reliable way to make a reviewer *actually verify* — rather than restate the PR's claims — is to require each finding to cite the code that proves it. **A finding with no code location is not a finding.**
+
+**The reviewer returns JSON only** ([`schemas/findings.schema.json`](../schemas/findings.schema.json)) — a plain `title`, a numeric `priority`, an `in_scope` flag. **It never writes the label or the verdict.** `post-review.mjs` *renders* the `BLOCK-n`/`NOTE-n` label and *derives* the verdict mechanically from `{priority, in_scope}`, so any reviewer model maps to one output. Do **not** prefix titles with `[P1]`, `F-`, `N-`, or any other house-style label — that drift is exactly what this contract removes.
+
+Each finding (every code-correctness issue, and any spec/standards issue specific enough to anchor) must include:
+
+- **`title`** — imperative, ≤80 chars. No label or priority prefix (the label is rendered downstream).
+- **`priority`** *(required — the ONE severity scale)* — integer `0–3`. `0` only for universal issues that don't depend on any assumption about inputs; `0–1` are the blocking band, `2–3` the deferrable band. The label follows from it: **in-scope `priority ≤ 1` renders `BLOCK-n` (holds the PR); everything else renders `NOTE-n`.**
+- **`in_scope`** *(boolean, default true)* — is the finding about *this diff*? `false` for a pre-existing / out-of-scope defect. It changes routing, not truth: an in-scope `p0–1` blocks; an **out-of-scope `p0–1` does NOT block** — it opens its own critical/security issue and fires a loud warning; a `p2–3` (either scope) batches into the one refactor-later issue.
+- **Location** — `path:line-start–line-end` that **overlaps the diff**, the smallest subrange that pinpoints it. Can't point to a line? Then it isn't verified — mark it `Unverified` and state what you'd need to confirm it; do not assert it as a finding.
+- **Why this path is vulnerable** — the concrete trigger/scenario/input, *traced through the code* (not "looks risky").
+- **Subject** *(every finding; `code` when omitted)* — `code` or `evidence`. `evidence` means the fix touches no source file (contract wording, checklist rows, evidence locators). A mis-tagged `@level`/`@covers` is `code` — the tag lives in a test file. Callers route on it; see SKILL.md § Verdicts and the blocking bar.
+- **Theme** *(state-machine/concurrency findings, and throughout the deep lane; optional otherwise)* — stable `theme.id`, `kind`, and the general violated `contract`; state-machine/concurrency themes also carry the complete `stateSpace` (`states × taskKinds`). A recurring theme retains the same identity and contract so the fix loop can reconcile it.
+- **Consequence** *(optional field, non-optional information)* — what actually breaks or degrades if this ships unfixed: the user-visible failure, the corrupted/lost data, the security exposure, the maintenance cost. State the impact, not a restatement of the symptom.
+- **Confidence** — `0.0–1.0`, kept honest; low confidence means you could not fully verify it.
+- **Recommendation** *(optional field, non-optional when the fix isn't obvious)* — the concrete change that reduces the risk.
+
+**A finding whose damage and fix the reader must guess is noise.** The trigger (why-vulnerable) says *what is wrong*; the reader also needs *why it matters* and *what to do*. The schema no longer forces separate `consequence`/`recommendation` fields — a tight `why` that already conveys the damage, on a finding whose fix is self-evident, stands alone — but the information is not optional: when the impact or the fix isn't obvious from the why, fill those fields or the finding cannot be acted on or prioritized. Drop it or complete it.
+
+**Grounding:** every finding must be defensible from code/tests/tool output you actually read — **do not invent files, lines, or code paths**; if a conclusion rests on an inference, say so in the finding body. For a ripple claim ("this breaks X elsewhere"), cite the *provably affected* code, not speculation. Close with an **overall correctness** call (would existing code/tests break?) consistent with the verdict.
+
+Use this format for the review report:
+
+```markdown
+## Verdict: PASS | NEEDS_CHANGES | FAIL | BLOCKED
+
+## Contract Check
+- Review Contract: present/missing/incomplete
+- Source Document: present/missing
+- Test Criteria: present/missing/access issue
+- AC Mapping: complete/incomplete
+- Mock/Fake Policy: acceptable/insufficient
+
+## Spec Compliance Review
+- Mode: `Spec'd` / `Code-only` — on Code-only append `— no requirement artifact found; spec compliance not assessed`, and raise it nowhere else (no finding, no note, no verdict effect)
+- Source/spec alignment: <pass/fail/blocked/not assessable + notes> — always `not assessable` in Code-only mode; it is a scope statement there, not a gap
+- Test criteria alignment: <pass/fail/blocked + notes>
+- Contract claims verified: <yes/no + contradictions>
+
+## Acceptance Criteria Review
+Status uses ensure-coverage classifications: Covered / Partial / Missing / Wrong Level / Over-mocked / Unverified / Excluded.
+| AC | Required Level | PR Evidence | Status | Notes |
+|---|---|---|---|---|
+| AC1 | Integration | test_file::test_name | Covered | attested |
+| AC2 | Unit + API | test_file::test_name | Partial | ... |
+
+**Notes must record the real input each AC was instantiated with** — the actual runtime value and any legacy/empty-state row exercised, not just "attested". An AC verified only against a convenient proxy (a test that asserts a stand-in value the app never actually produces) is `Unverified`, not `Covered`.
+
+## Round-1 Depth Obligations
+- Live endpoint probing: `completed` — concrete running-surface command/result and evidence; or `not-applicable` — specific reason the changed surface has no live endpoint. `deferred`, `later`, and omitted are invalid.
+- Shared-consumer impact: `completed` — concrete trace through every changed contract consumer and evidence; or `not-applicable` — specific reason there are no relevant shared first-party consumers. `deferred`, `later`, and omitted are invalid.
+
+## Coverage Breadth Review
+- Coverage gate: <coverage-ledger.mjs validate result / not run + why>
+- Obligation Impact reconciled: <yes/no + discrepancies>
+- Changed/added surfaces: <surface → alignment + depth status>
+- Orphan surfaces / unmet baselines: <none or list>
+- Exclusions checked: <none / gated + category+reason, or rejected>
+- Presentation sweep (changed browser routes): <result / not run + why>
+
+## Code Correctness Review
+One entry per finding, each carrying its proof (see "Every finding carries its proof"). "No blocking correctness findings." is a valid, clean result — don't manufacture filler. State each finding's `priority` and (when not the default) `in_scope`; the `BLOCK-n`/`NOTE-n` label is rendered by `post-review.mjs`, never written here.
+- **<imperative title>** — `priority 0–3` · `in_scope true|false` · `path:line-start–line-end` (overlaps diff) · confidence 0.0–1.0 · *why this path is vulnerable*: <concrete trigger, traced through the code> · *consequence*: <what breaks/degrades if unfixed> · *fix*: <concrete change> · theme `<theme.id>` / `<theme.contract>` (state-machine/concurrency and deep-lane findings)
+- **<…>** — `priority 2` · `path:line` · confidence … · why … · fix …
+- Test-quality / scope-maintainability findings: same per-finding format where they anchor to a location; otherwise note briefly.
+- Overall correctness: <patch is correct | incorrect> — <1–3 sentences consistent with the verdict>
+
+## Standards Review
+- Standards sources reviewed: <files or none found>
+- Hard violations: <none or list with cited source>
+- Judgment calls: <none or list with cited source>
+
+## Previous Findings — Resolution Status
+Include on **re-reviews only** (a second-or-later review of the same PR). One row per prior finding; resolution is verified against the current tree, not the PR's claim. `Resolved` requires a verifiable locator; a claimed-but-unlocatable or still-present fix stays `Unresolved` and remains a blocking finding. **`Resolved` also requires the invariant *class* closed, not just the cited instance** — an adjacent path/field/state still broken under the same rule is `Partially resolved`; name the unclosed member in the row. A prior finding that carried a `hazard_candidate` needs both locators — the code fix **and** its `docs/domain-hazards.md` row (or `covered by <id>`); code-only is `Partially resolved`. See SKILL.md → "Re-review: reconciling previous findings".
+| # | Prior finding | Claimed | Verified status | Evidence locator |
+|---|---|---|---|---|
+| 1 | <short title> | resolved | Resolved | `path:line` / test / commit that proves it |
+| 2 | <short title> | resolved | **Unresolved** | claim unlocatable / still present at `path:line` |
+
+## Required Changes
+- <blocking issue to fix before merge — includes every prior finding still Unresolved/Partial>
+
+## Non-Blocking Notes
+- <optional improvements>
+
+## Evidence Reviewed
+- PR diff: <summary>
+- Commits/base compared: <base/head or merge-base if available>
+- Source/spec links: <links/files reviewed>
+- Standards docs: <files reviewed>
+- Tests: <files/test names>
+- CI: <links/results if available>
+```
+
+If the output channel does not render markdown tables well, replace the Acceptance Criteria table with one bullet per AC using the same fields.

package/skills/engineering/review-pr/references/over-mock-screen.md

@@ -0,0 +1,7 @@
+# The over-mock screen — what it catches, and what it does not
+
+**Trigger: `scan-diff.mjs` reported a hit, or you need to judge whether a mock is first-party.** The zero-tolerance rule itself is in SKILL.md and does not depend on this file.
+
+   - **What it catches:** `vi.mock`/`jest.mock`/`vitest.mock` of a first-party target (`@/…`, `~/…`, the repo's own package scope, a relative import into source). The complementary `page.route`/`route.fulfill`/MSW interception of your *own* endpoint in a journey is a `scan-diff.mjs` **lead** you adjudicate (legit in a Tier-2 failure-injection test, `Over-mocked` in a journey).
+   - **No waiver path** — no `// @mock-ok`, no "approved with justification" (distinct from the broader mock-only *judgment*, where money/auth/idempotency are never mock-only anyway). The only resolutions: **make it real, fake only the external, or delete the test** — and **over-mock is worse than no test**, so deleting (an honest, tracked gap) is always acceptable.
+   - **Genuine false positive = an external target** → simply *not* a finding (note why; fix durably by declaring topology in `coverage.config.json`). Faking a third-party boundary (clock, randomness, external HTTP/provider) is correct, not a finding. (Diff-scoped here; the whole-tree inherited burndown is `ensure-coverage`'s audit lint, when available.)

package/skills/engineering/review-pr/references/promotion-prs.md

@@ -0,0 +1,16 @@
+# Promotion PRs (e.g. `dev -> main`)
+
+**Trigger: `pr-context.mjs` reports `promotion: true`.** A promotion carries already-reviewed commits between long-lived branches; the review question is different from a feature PR's and most of the four-axis scan does not apply.
+
+## Promotion PRs (e.g. `dev → main`)
+
+A PR whose **base is a production branch** (`main`) and head is the integration branch (`dev`) or a release branch pinned from it (`release/<version>`) is a **promotion, not a feature PR** — `pr-context.mjs` flags `promotion: true`. Prefer the pinned release-branch head: a PR from `dev` itself promotes whatever the tip happens to be at merge time, not the SHA that was validated (`resolve-release` principle 11). Don't re-review the whole accumulated diff; the feature code was already reviewed on its way into `dev`. Two rules:
+
+1. **It must fast-forward.** `pr-context.mjs` reports `fastForwardable`; if `false`, the base has commits the head lacks (almost always hotfixes), so promoting would **silently revert them** (and the merge resolution is unreviewed). → **`NEEDS_CHANGES`**, and the remedy must act on the **promotion head**, which is normally a pinned `release/<version>` branch rather than the integration branch: with an integration branch, back-merge `main → dev` **and then re-cut the release branch from a fresh candidate** (the back-merge alone leaves the already-cut head just as un-fast-forwardable, and rebasing it instead would silently break the SHA-keyed pin); in a single-branch model (GitHub Flow, where no `dev` exists), **rebase the release branch onto `main`** and re-run this review — cheap, because that branch is usually one version-cut commit, and sound because that topology already treats the pin as a pre-filter. Never merge-resolve into the production branch either way. Best enforced upstream as branch protection (require linear history). One topology check; it subsumes the drift + merge-resolution risks.
+2. **Run the release-readiness checklist** on the content — migrations/backfills, secrets & config, feature-flag defaults, version/changelog, rollback, and **candidate validation**: green CI **and** a recorded ALIVE integration-environment smoke verdict on the **exact promoted SHA** (SHA-keyed — a verdict from any other SHA, or "dev looked fine", is not evidence). These are batch/deploy-level risks no per-feature review saw. Then **skip the rest** — re-reading green, already-reviewed feature code adds noise, not safety.
+
+   **Candidate validation is topology-scoped, or it becomes unsatisfiable.** The SHA-keyed rule above assumes the promoted SHA *is* the validated SHA — true when the promotion fast-forwards an integration branch. In a single-branch model the release branch is rebased before merging, so the shipped SHA **by construction** never earned a verdict: demanding one would block every valid release. There the row is satisfied by a verdict on the **candidate the release branch was cut from**, marked as a pre-filter, and the binding gate moves downstream to the pre-exposure check on the 0%-traffic candidate (`resolve-release` principle 11 and step 4a). Record which reading you applied — an unmarked pass hides which gate actually held.
+
+On the test side, a promotion uses the **release lane**, not a re-run: where it fast-forwards, prod is the exact SHA whose PR-lane gates already passed, so gate on that result — plus a read-only smoke against the **0%-traffic candidate, before traffic shifts**, run under a **read-only production profile** (`prod-preview`/`prod-active`) (against production a synthetic tenant is not sufficient). Never the mutating suite on prod (see `ensure-coverage` → `references/enforcement/ci-contract.md`, and `e2e-test`'s CI section).
+
+(For a normal `feature → dev`/`main` PR, ignore this and use the four axes above.)

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

@@ -0,0 +1,18 @@
+# Re-review — reconciling previous findings
+
+**Trigger: prior review findings exist** in any form — review comments, a Required Changes list, a findings ledger. `lastReviewedSha` chooses the scope, not whether this applies; absent one, the re-review is full-scope (see the scope rules below).
+
+## Re-review: reconciling previous findings
+
+A second (or later) review of the same PR is **not** a fresh review — it is a re-review, and its job is to verify that the prior round's required changes were *actually* made. The failure mode this prevents: a producer pushes a commit titled "address review findings," self-asserts done, and the loop exits on the claim while findings remain unfixed. **Resolution is verified against the tree, never accepted on the PR's say-so.**
+
+When prior review findings exist (earlier review comments, a Required Changes list, or a contract's findings ledger):
+
+1. **Enumerate every prior finding** and re-check each against the *current* `base...HEAD` diff and tree — independently, the same way you'd verify a new finding (locate the code; reproduce the concern).
+2. **Classify each** as `Resolved` / `Partially resolved` / `Unresolved`, with the **same evidence bar as a finding**: a `Resolved` claim needs a verifiable locator (the `file:line`/test/commit that proves the fix). **A finding the PR claims resolved but whose fix you cannot locate, or which is still present in the diff, stays `Unresolved`** — do not downgrade it because a commit message or comment says it was handled. **A prior finding that carried a `hazard_candidate` needs two locators to reach `Resolved`: the code fix *and* its row in the repo hazards file (`docs/domain-hazards.md`)** — or an explicit `covered by <id>` pointing at an existing row; code-fixed but row-missing is `Partially resolved` (the lesson wasn't banked — [lifecycle](domain-hazards.md#the-repo-hazards-file-location-schema-lifecycle)).
+3. **A still-present finding does not reset.** It remains a finding at its original (or higher) severity, and a pattern of claimed-but-unfixed items is itself a credibility signal worth noting.
+   - **A fix that closes only the cited instance is still-present.** A finding names an instance; what it obligates is the *rule* — every path, field, state, and interleaving that rule covers. So reconcile against the **class**, not the line you cited: the fix should name the invariant class it closed and the adjacent members it checked, and you verify those members. Serializing the one union you named while the sibling classification stays unserialized is `Partially resolved`, not `Resolved`. This is worth being strict about because the alternative is not a missed bug but a *slow* one: the same invariant returns two rounds later at a wider scope, and each return costs a full fix + re-review + CI round. Size it to the finding, though — a rule that genuinely covers one instance closes in one instance, and demanding an enumeration there is nitpicking priced as a blocker.
+4. **Verdict gate:** the PR cannot reach `PASS` while any prior blocking finding is `Unresolved` or `Partially resolved`. New findings introduced by the fix commits are reviewed normally on top.
+5. **Scope: delta by default.** The fresh four-axis scan of a re-review covers the **delta diff** — `<lastReviewedSha>...HEAD`, where `lastReviewedSha` is the HEAD the prior verdict was rendered against (the caller passes it; `resolve-issues` records it per unit) — plus the prior-findings reconciliation above. The already-reviewed remainder of the PR is not re-read axis by axis: re-running the full adversarial review of an unchanged, already-reviewed diff every round is the single largest cost in the fix loop, and everything that can have changed since the last verdict is the delta plus the findings themselves. Two boundaries keep this safe: the **decidable screens** (`scan-diff.mjs`, `coverage-checklist.mjs validate`) still run over the **full** `base...HEAD` diff — they're cheap, and honesty regressions can hide anywhere — and the **verdict still covers the whole PR** (prior findings + delta findings + full-diff screens). Run a **full-scope** re-review instead when any of these hold: the surface is high-risk (auth/money/tenancy/migration), this is the third round (and every third thereafter — periodic full passes stop drift accumulating in the unreviewed remainder), the delta touches files outside the originally reviewed diff, no `lastReviewedSha` was provided, the branch was rebased **in a way that moved the production diff**, or the authoritative contract revision differs from the one used by the last verdict. (A rebase/restack that leaves the production diff byte-identical is an *evidence* refresh, not a code change: when a review is run over one anyway it is full-scope, but the caller should generally not spend one — `resolve-issues` routes that case to its evidence-only lane, reading each finding's `subject` rather than inferring it — so classify the findings of such a round accordingly. An approved contract revision overrides this and always forces the full review.) In the last case, old-contract findings remain useful history but their resolution table cannot substitute for reviewing the whole current contract.
+
+Emit the **Previous Findings — Resolution Status** table ([output-format.md](output-format.md)) in the report so the reconciliation is auditable. This is the verifier half of the loop discipline in `resolve-issues` (which re-reviews after every fix and exits only on a fresh APPROVE).