@mrciphersmith/keryx 0.3.1 → 0.3.3

package/src/gdskills/bundled/skills/planning/brainstorm/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: brainstorm
-description: "Use when exploring architecture decisions, tech choices, feature ideas, or any open-ended problem that benefits from multiple perspectives. NOT for: writing the chosen option up as a formal requirements document (use prd-creator)."
+description: "Use when exploring architecture decisions, tech choices, feature ideas, or any open-ended problem with several options that benefits from multiple perspectives. NOT for: writing the chosen option up as a formal requirements document (use prd-creator)."
 triggers:
   - "brainstorm"
   - "explore options"

package/src/gdskills/bundled/skills/planning/interviewer/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: interviewer
-description: "Use when a request is ambiguous and must be pinned down BEFORE any context is collected — the entry-point interview that turns a vague or expensive ask into a scoped brief. This is the `custom`-intent gate job-orchestrator runs at 0.1.5. NOT for: clarifying implementation specifics AFTER context is already collected — use `interview` instead."
+description: "Use when a request is ambiguous and must be pinned down BEFORE any context is collected — the entry-point interview that clarifies the real requirements and turns a vague or expensive ask into a scoped brief. This is the `custom`-intent gate job-orchestrator runs at 0.1.5. NOT for: clarifying implementation specifics AFTER context is already collected — use `interview` instead."
 triggers:
   - "ask questions"
   - "clarify requirements"

package/src/gdskills/bundled/skills/quality/deploy/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: deploy
-description: "Use when deploying to any environment (staging, production) or when a deployment pipeline needs to run. NOT for the database schema changes a release depends on (use `db-migrate`)."
+description: "Use when deploying a release to any environment (staging, production) or when a deployment pipeline needs to run. NOT for the database schema changes a release depends on (use `db-migrate`)."
 triggers:
   - "deploy"
   - "deployment"

package/src/gdskills/bundled/skills/review/review-jev-comments/SKILL.md

@@ -0,0 +1,184 @@
+---
+name: review-jev-comments
+model_tier: light
+description: |
+  Use when: an ADDITIONAL, machine-scored pass is wanted over open PR review comments
+  already in the existing ledger — never replacing any other reviewer, and never
+  auto-replying or auto-resolving. Dispatched by review-orchestrator in Wave B, via the
+  CLI (`keryx review jev-comments`), when `review.jev.comments: true` in
+  .metaproject/tasks.config.json and a Jev/OpenRouter credential is resolvable. It is not
+  an LLM sub-agent: there is nothing to dispatch through a platform-native agent
+  mechanism, and no prose is generated by a model — Jev only answers a `choice` among
+  resolved-by-fix/still-open/not-actionable/needs-escalation per open comment; keryx
+  writes every word of every finding.
+  NOT for: posting a reply, resolving a thread, or deciding what `keryx review comments
+  reply` sends — this reviewer only ever reads the ledger and labels.
+triggers:
+  - "jev comments"
+  - "open comments"
+  - "review --jev-comments"
+metadata:
+  author: "MrCipherSmith"
+  version: "1.0.0"
+  category: "review"
+  compatible_harnesses: "cursor,codex,zed,opencode,claude"
+  engine: "jev"
+  origin: "authored"
+license: "MIT"
+---
+
+# Review — Jev Comments (open PR comment triage)
+
+An ADDITIONAL orchestrator reviewer, flow 333. It is a **keryx program**, not an
+LLM sub-agent: `review-orchestrator` never dispatches a platform-native agent
+for it, it runs `keryx review jev-comments` and reads the `--json` output.
+Every finding is composed by keryx; Jev ("System One" on OpenRouter) supplies
+only a `choice` label per comment — it never writes prose, and nothing it
+returns is quoted verbatim into a finding.
+
+---
+
+## What it does
+
+1. Reads open comments from the EXISTING ledger
+   (`.metaproject/reviews/pr-comments/*.json`, written by `keryx review
+   comments collect`) — never re-collects from GitHub itself.
+2. Computes deterministic facts per open comment: commits after the comment's
+   timestamp touching its file (local `git log`, capped), the review thread's
+   resolved flag (best-effort, via one read-only GraphQL query — degrades to
+   `"unknown"` on any failure, never a guess), and its replies already on the
+   ledger.
+3. Asks Jev exactly ONE `choice` question per open comment (batched under the
+   vendor's 64k token budget): `resolved-by-fix` / `still-open` /
+   `not-actionable` / `needs-escalation`, given the comment, its replies, and
+   the code's current hunk(s) at that location.
+4. Synthesizes findings for `still-open` (severity `minor`) and
+   `needs-escalation` (severity `major`) only — `resolved-by-fix` and
+   `not-actionable` produce no finding. It never posts a reply and never
+   resolves a thread; the choice for every open comment is also written to an
+   advisory-label cache
+   (`.metaproject/data/review-jev-comments/labels__<repo>__<n>.json`) that
+   `keryx review comments reply` reads back and prints, informationally, next
+   to its own output — it never changes what that command sends.
+
+---
+
+## Input Contract
+
+Not dispatched with a prompt — invoked as a CLI command:
+
+```text
+keryx review jev-comments --pr <n> --repo <owner/repo>
+                          [--model <jev-1.13|jev-latest>] [--fixtures <dir>] [--json]
+```
+
+Requires a comment ledger to already exist for `--repo`/`--pr` (`keryx review
+comments collect` first) — this reviewer refuses, before any read, when it
+does not.
+
+---
+
+## Opt-in and privacy
+
+Refuses before any ledger read or network call unless
+`.metaproject/tasks.config.json` declares:
+
+```json
+{ "review": { "jev": { "comments": true } } }
+```
+
+Every comment body, reply, and hunk sent to Jev is redacted first through
+`src/security/service.ts` — the same floor every other Jev-backed reviewer
+applies. No cache or output file stores a credential.
+
+---
+
+## Output Contract
+
+Emits a `REVIEW_RESULT`-shaped object matching
+`.metaproject/skills/gdskills/review/review-orchestrator/reviewer-finding.schema.json`
+— `status`, `reviewer: "review-jev-comments"`, `summary`, `findings`, `stats`
+— under `--json`. Its findings merge into the consolidated array exactly like
+any other reviewer's: same Quality Gate, same dedup, same Wave C
+verification.
+
+### Class scope — required for `blocker` and `major`
+
+A `needs-escalation` finding is `major` and always carries `class_scope`:
+`sites` is the single `file:line` the comment is anchored to, and
+`enumeration_method` states it is exactly that one comment — there is no
+"class" beyond it, one comment is one finding, never a set to enumerate
+further. `still-open` is `minor` and carries none, matching the schema's own
+rule (`class_scope` required only for `blocker`/`major`).
+
+---
+
+## Orchestrator integration
+
+- `keryx review reviewers --json` lists it under `bundled` with
+  `"engine": "jev"`.
+- `review-orchestrator` dispatches it in **Wave B**, alongside the domain/
+  convention reviewers, when the opt-in is on and a Jev/OpenRouter credential
+  resolves (`resolveJevApiKeyResolution`). When either is false it is
+  **skipped with the stated reason**, recorded in `Skipped reviewers` —
+  never silently absent.
+- It is **ADDITIONAL** and strictly advisory over the comment-reply flow: its
+  label is printed by `keryx review comments reply`, never acted on
+  automatically.
+
+---
+
+## Red Flags
+
+| Rationalization | Why it is wrong |
+|---|---|
+| "Jev said still-open, so post a reply now" | This reviewer never posts anything — a `still-open`/`needs-escalation` finding is a signal for a human or `keryx review comments reply`'s own logic, not an instruction to act |
+| "The thread's resolved flag came back unknown, so treat it as resolved" | `unknown` is a distinct, honest state — it means the read failed, not that the thread is closed |
+| "No findings means every comment was addressed" | Only `still-open`/`needs-escalation` produce findings; `resolved-by-fix` and `not-actionable` are correctly silent, but check `openComments` in `--json` to see how many were actually judged |
+
+---
+
+## Verification
+
+Before trusting a run's findings:
+
+1. Read `openComments` in the `--json` output against the ledger's own
+   `unanswered so far` count from the last `comments collect` — they should
+   agree.
+2. Spot-check a `needs-escalation` finding against the comment text: does it
+   actually block progress, or is it a `still-open` case Jev over-called?
+3. Confirm every finding carries `reviewer: "review-jev-comments"` and a
+   `dedupe_key` — both are required for the orchestrator's Quality Gate and
+   Wave C verification to route it correctly.
+
+---
+
+## Iron Laws
+
+### Shared laws (every reviewer)
+
+1. **A claim of runtime harm with no reproducible path is `info`.** If you cannot
+   name the input, call, or condition that reaches the code, you have an
+   observation, not a finding. Report it as `info` and say what would settle it.
+2. **Never flag the theoretical.** The path you describe must exist in the code
+   under review. Do not report a safe API because it could be misused, or a
+   pattern because it is often wrong elsewhere.
+3. **One finding per class, not one per occurrence.** When the same shape appears
+   at several sites, report it once and list every site. Ten findings that are one
+   finding hide the other nine problems.
+
+Severity levels are defined once, in `review-orchestrator/SKILL.md` →
+**Severity (canonical)**. This reviewer does not restate them: it emits only
+`minor` (`still-open`) or `major` (`needs-escalation`, always with
+`class_scope`) — `blocker` never applies to an unanswered comment.
+
+---
+
+## Scope Boundaries
+
+| Concern | This skill | Use instead |
+|---------|------------|-------------|
+| An open PR comment looks unaddressed or blocking | YES | — |
+| Posting a reply, resolving a thread | NO | `keryx review comments reply`, a human |
+| Judging whether a reported finding is real | NO | `review-verifier` |
+| Collecting comments from GitHub | NO | `keryx review comments collect` |

package/src/gdskills/bundled/skills/review/review-jev-contract/SKILL.md

@@ -0,0 +1,193 @@
+---
+name: review-jev-contract
+model_tier: light
+description: |
+  Use when: an ADDITIONAL, machine-scored check of a PR description's own CLAIMS —
+  and, when a flow is linked, that flow's frozen acceptance criteria — against the diff
+  is wanted, never replacing any other reviewer. Dispatched by review-orchestrator in
+  Wave B, via the CLI (`keryx review jev-contract`), when `review.jev.contract: true` in
+  .metaproject/tasks.config.json and a Jev/OpenRouter credential is resolvable. It is not
+  an LLM sub-agent: there is nothing to dispatch through a platform-native agent
+  mechanism, and no prose is generated by a model — Jev only answers one `noul`
+  probability per claim; keryx writes every word of every finding. Replaces the
+  orchestrator's by-eye Stage 1 "description vs diff" judgement with a scored input when
+  the opt-in is on; the by-eye check stays the fallback when it is off.
+  NOT for: judging a flow's frozen criteria from scratch (that machinery is flow 328's
+  `check-ac.ts`, reused, not duplicated), and not a substitute for a human reviewer
+  reading the claim list it produces.
+triggers:
+  - "jev contract"
+  - "check the PR description against the diff"
+  - "review --jev-contract"
+metadata:
+  author: "MrCipherSmith"
+  version: "1.0.0"
+  category: "review"
+  compatible_harnesses: "cursor,codex,zed,opencode,claude"
+  engine: "jev"
+  origin: "authored"
+license: "MIT"
+---
+
+# Review — Jev Contract (PR-description claims and frozen acceptance criteria vs. the diff)
+
+An ADDITIONAL orchestrator reviewer, flow 335. It is a **keryx program**, not
+an LLM sub-agent: `review-orchestrator` never dispatches a platform-native
+agent for it, it runs `keryx review jev-contract` and reads the `--json`
+output. Every finding is composed by keryx; Jev ("System One" on OpenRouter)
+supplies only one `noul` probability per claim — never prose.
+
+---
+
+## What it does
+
+Two independent tracks, both advisory, both merged into one report:
+
+1. **Claims** — extracted deterministically from the PR description: every
+   bullet/numbered-list item is a claim, plus every prose sentence carrying a
+   verb cue (adds, fixes, removes, "does not change", tests). For each claim,
+   keryx computes deterministic facts FIRST — named files/symbols/flags
+   present in the diff, whether a test file was touched (for a "tests added"
+   claim), whether an EXPORTED symbol changed anywhere in the diff (for a "no
+   API change" claim) — then asks Jev **one `noul`**: "does the diff support
+   this claim?". A claim the facts directly CONTRADICT (e.g. "no API change"
+   with an exported symbol touched) is `major`, with `class_scope`,
+   regardless of what Jev answered — a contradiction is a fact, not an
+   opinion Jev could outvote. A claim scoring below threshold with no
+   contradiction is `minor` ("unsupported"). A claim at/above threshold with
+   no contradiction produces no finding.
+2. **Criteria** — the linked flow's frozen acceptance criteria, when
+   `--flow <id>` names one. This track reuses flow 328's
+   `src/flow/check-ac.ts` **wholesale**, through `runCheckAc`
+   (`src/commands/flow-check-ac.ts`) — the exact same diff acquisition, Jev
+   batching, cache and degrade path `keryx flow check-ac` already uses. No
+   criterion-checking logic is reimplemented for this reviewer.
+
+---
+
+## Input Contract
+
+Not dispatched with a prompt — invoked as a CLI command:
+
+```text
+keryx review jev-contract (--diff <ref> | --pr <n>) [--flow <id>]
+                          [--max-calls <n>] [--threshold <0..1>]
+                          [--repo <owner/repo>] [--model <jev-1.13|jev-latest>]
+                          [--fixtures <dir>] [--json]
+```
+
+`--pr <n>` is required to check claims at all — a `--diff <ref>` target has
+no PR description to extract claims from, so that track reports zero claims
+(honestly, not a refusal). `--flow <id>` is independent of either target: it
+names the flow whose frozen acceptance criteria are checked against the same
+diff, when one is linked.
+
+---
+
+## Opt-in and privacy
+
+Refuses before any read or network call unless `.metaproject/tasks.config.json`
+declares:
+
+```json
+{ "review": { "jev": { "contract": true } } }
+```
+
+Every claim and every matched diff hunk sent to Jev is redacted first through
+`src/security/service.ts` — the same floor `review conform`/`review
+jev-risk`/`review jev-rules` already apply. No cache or output file stores a
+credential.
+
+---
+
+## Output Contract
+
+Emits a `REVIEW_RESULT`-shaped object matching
+`.metaproject/skills/gdskills/review/review-orchestrator/reviewer-finding.schema.json`
+— `status`, `reviewer: "review-jev-contract"`, `summary`, `findings`, `stats`
+— under `--json`, plus two extras: `claims` (every extracted claim, its
+intent, and its `noul` score) and `budget` (`--max-calls`, claims scored,
+claims skipped). When `--flow` names a flow, an `acCheck` object is merged in
+(`flowId`, `verdicts`, `jevAsked`, `summary`) — the same shape `keryx flow
+check-ac` reports. Its findings merge into the consolidated array exactly
+like any other reviewer's: same Quality Gate, same dedup, same Wave C
+verification. A `major` finding always carries a schema-valid `class_scope`
+object (`sites`, `enumeration_method`) — never a bare label.
+
+---
+
+## Orchestrator integration
+
+- `keryx review reviewers --json` lists it under `bundled` with
+  `"engine": "jev"`.
+- `review-orchestrator` dispatches it in **Wave B**, alongside the domain/
+  convention reviewers and the other CLI-engine reviewers, when the opt-in is
+  on and a Jev/OpenRouter credential resolves. When either is false it is
+  **skipped with the stated reason**, recorded in `Skipped reviewers` — never
+  silently absent.
+- It is **ADDITIONAL**: it never replaces any other pass. **When the opt-in is
+  on, it REPLACES the orchestrator's by-eye Stage 1 "description vs diff"
+  judgement with this scored input** — see `review-orchestrator/SKILL.md`'s
+  "This gate owns the description-vs-diff comparison" and `SKILL.detail.md`'s
+  "CLI-engine reviewers" section. When the opt-in is off, the by-eye check
+  stays the fallback, unchanged.
+
+---
+
+### Shared laws (every reviewer)
+
+1. **A claim of runtime harm with no reproducible path is `info`.** If you cannot
+   name the input, call, or condition that reaches the code, you have an
+   observation, not a finding. Report it as `info` and say what would settle it.
+2. **Never flag the theoretical.** The path you describe must exist in the code
+   under review. Do not report a safe API because it could be misused, or a
+   pattern because it is often wrong elsewhere.
+3. **One finding per class, not one per occurrence.** When the same shape appears
+   at several sites, report it once and list every site. Ten findings that are one
+   finding hide the other nine problems.
+
+This reviewer satisfies all three by construction: `evidence` always names the
+matched artefacts/facts and the claim text (never an unreproducible claim); a
+finding is synthesized only against a claim actually extracted from the real
+description, never a hypothetical one; and each claim is its own site, so
+there is no repeated class across claims for this reviewer to collapse — a
+`major` finding's `class_scope` still enumerates every matched region, not
+just the first.
+
+---
+
+## Red Flags
+
+| Rationalization | Why it is wrong |
+|---|---|
+| "Jev said 0.9, so the claim is definitely supported" | A `noul` score is a probability the claim is evidenced, not a verdict — a contradiction detected by the deterministic facts overrides it regardless of the score |
+| "The description doesn't mention an API, so 'no change' can't be contradicted" | The contradiction check only runs when the claim's own text IS API-shaped (mentions api/public/export/interface/signature/contract) — a claim like "no change to behavior for CLI callers" is checked for tokens, but the exported-symbol contradiction path is intentionally narrower |
+| "No claims extracted means the description said nothing" | `--diff` targets have no PR description at all — zero claims there is a target-shape fact, not a description-quality one; check `budget.claimsSkipped` too before reading silence as clean |
+| "The AC track failed, so the whole review failed" | `acCheck` degrades to facts-only (never throws) exactly like `keryx flow check-ac` does — a Jev failure on the criteria track is advisory, same as on the claims track |
+
+---
+
+## Verification
+
+Before trusting a run's findings:
+
+1. Read `budget.claimsSkipped` in the `--json` output — a capped run checked
+   fewer than "every extracted claim" and the report should say so.
+2. Spot-check a `major` finding's `class_scope.sites` against the actual
+   diff: does the named region really touch an exported symbol the claim
+   said would not change?
+3. Confirm every finding carries `reviewer: "review-jev-contract"` and a
+   `dedupe_key` — both are required for the orchestrator's Quality Gate and
+   Wave C verification to route it correctly.
+
+---
+
+## Scope Boundaries
+
+| Concern | This skill | Use instead |
+|---------|------------|-------------|
+| Whether the PR description's own claims match the diff | YES | — |
+| Whether a flow's frozen acceptance criteria are likely met | YES (via `--flow`, reusing `check-ac.ts`) | `keryx flow check-ac` directly, for a standalone advisory run |
+| An actual security/concurrency finding | NO | `review-security-code` / `review-highload` |
+| Judging whether a reported finding is real | NO | `review-verifier` |
+| A ranked risk map of the diff's hunks | NO | `review-jev-risk` |

package/src/gdskills/bundled/skills/review/review-jev-docs/SKILL.md

@@ -0,0 +1,189 @@
+---
+name: review-jev-docs
+model_tier: light
+description: |
+  Use when: an ADDITIONAL, machine-scored pass is wanted over documentation sections that
+  may have gone STALE because of a diff — never replacing any other reviewer. Dispatched
+  by review-orchestrator in Wave B, via the CLI (`keryx review jev-docs`), when
+  `review.jev.docs: true` in .metaproject/tasks.config.json and a Jev/OpenRouter
+  credential is resolvable. It is not an LLM sub-agent: there is nothing to dispatch
+  through a platform-native agent mechanism, and no prose is generated by a model —
+  Jev only answers a `noul` staleness probability per doc section; keryx writes every
+  word of every finding, and one class of finding (a removed/renamed CLI flag still
+  documented) is found with no Jev call at all.
+  NOT for: judging whether documentation is well-written, complete, or accurate about
+  something the diff never touched — this reviewer only ever looks at sections
+  deterministically linked to code the diff changed.
+triggers:
+  - "jev docs"
+  - "stale docs"
+  - "review --jev-docs"
+metadata:
+  author: "MrCipherSmith"
+  version: "1.0.0"
+  category: "review"
+  compatible_harnesses: "cursor,codex,zed,opencode,claude"
+  engine: "jev"
+  origin: "authored"
+license: "MIT"
+---
+
+# Review — Jev Docs (stale-documentation detection)
+
+An ADDITIONAL orchestrator reviewer, flow 333. It is a **keryx program**, not an
+LLM sub-agent: `review-orchestrator` never dispatches a platform-native agent
+for it, it runs `keryx review jev-docs` and reads the `--json` output. Every
+finding is composed by keryx; Jev ("System One" on OpenRouter) supplies only a
+`noul` staleness probability per doc section — it never writes prose, and
+nothing it returns is quoted verbatim into a finding.
+
+---
+
+## What it does
+
+1. Splits every discovered documentation file — the default corpus is
+   USER-FACING docs only: `docs/**`, the root `README*` (never `CHANGELOG*`),
+   and gdwiki pages (`.metaproject/wiki/**`) — into sections by heading,
+   deterministically (`src/review/jev-docs.ts`'s `extractDocSections` — no
+   model call). `--include <glob>` (repeatable) widens the corpus back out
+   (skills, rules, anything project-specific); see Input Contract.
+2. Links each section to code deterministically — an explicit repo-relative
+   path it quotes, a backtick-quoted symbol that appears verbatim in one of
+   the diff's own hunks, or a `keryx <verb>` invocation whose command file the
+   diff changed. Only sections linked to code the diff CHANGES, and that the
+   diff does NOT itself edit, are candidates.
+3. Ranks linked sections by link strength — path mention > symbol mention >
+   verb mention; more distinct links to changed code within the same kind
+   rank higher — and asks Jev exactly ONE `noul` question per selected
+   section, up to `--max-calls` (default 30) and 8 per doc file, batched
+   under the vendor's 64k token budget, with the ranking basis and every drop
+   reported (`selection`), never silent, never alphabetical.
+4. Separately, and with NO Jev call: a CLI flag that disappears from a
+   changed file's diff (present on a removed line, absent from every added
+   line of the same file) and is still mentioned by an untouched doc section
+   is flagged deterministically.
+5. Synthesizes findings deterministically: `problem` names the section
+   (file + heading + line) and the code change that likely outdated it,
+   `suggested_fix` names the update target, `evidence` carries Jev's
+   probability (or, for the flag check, the deterministic reasoning).
+   Severity is always `minor`.
+
+---
+
+## Input Contract
+
+Not dispatched with a prompt — invoked as a CLI command:
+
+```text
+keryx review jev-docs (--diff <ref> | --pr <n>) [--max-calls <n>] [--threshold <0..1>]
+                      [--repo <owner/repo>] [--model <jev-1.13|jev-latest>]
+                      [--fixtures <dir>] [--include <glob>]... [--json]
+```
+
+`review-orchestrator` passes `--diff <ref>` (or `--pr <n>`) matching the same
+target every other reviewer's dispatch checks.
+
+---
+
+## Opt-in and privacy
+
+Refuses before any doc read or network call unless
+`.metaproject/tasks.config.json` declares:
+
+```json
+{ "review": { "jev": { "docs": true } } }
+```
+
+Every doc-section excerpt and hunk sent to Jev is redacted first through
+`src/security/service.ts` — the same floor `review conform`/`review jev-rules`
+already apply. No cache or output file stores a credential.
+
+---
+
+## Output Contract
+
+Emits a `REVIEW_RESULT`-shaped object matching
+`.metaproject/skills/gdskills/review/review-orchestrator/reviewer-finding.schema.json`
+— `status`, `reviewer: "review-jev-docs"`, `summary`, `findings`, `stats` —
+under `--json`. Its findings merge into the consolidated array exactly like
+any other reviewer's: same Quality Gate, same dedup, same Wave C
+verification.
+
+### Class scope — required for `blocker` and `major`
+
+Every finding this reviewer emits is `minor` (`docsFindingStats` caps it by
+construction), so `class_scope` never applies here — `blocker`/`major`
+findings, and the `class_scope` contract that comes with them, belong to the
+reviewers named in `review-orchestrator/SKILL.md`'s own Finding Format
+section.
+
+---
+
+## Orchestrator integration
+
+- `keryx review reviewers --json` lists it under `bundled` with
+  `"engine": "jev"`.
+- `review-orchestrator` dispatches it in **Wave B**, alongside the domain/
+  convention reviewers, when the opt-in is on and a Jev/OpenRouter credential
+  resolves (`resolveJevApiKeyResolution`). When either is false it is
+  **skipped with the stated reason**, recorded in `Skipped reviewers` —
+  never silently absent.
+- It is **ADDITIONAL**: it never replaces any documentation-adjacent finding
+  another reviewer already raises; the dedup pass merges rather than
+  double-counts.
+
+---
+
+## Red Flags
+
+| Rationalization | Why it is wrong |
+|---|---|
+| "Jev said 0.9, so the doc is definitely wrong now" | A `noul` score is a probability, not a verdict — read the linked hunk yourself before editing the doc |
+| "No findings means the docs are current" | The default corpus is `docs/**`/`README*`/gdwiki only — a project's `.metaproject/skills/**`/`rules/**` need `--include` to be scored at all; `--max-calls`/8-per-file also bound what gets scored (`selection.droppedSections`) |
+| "This section wasn't linked, so it's fine" | Linking is deliberately narrow (explicit paths/symbols/verbs) — a section describing behaviour with no explicit code reference is out of this reviewer's reach by design, not proven current |
+
+---
+
+## Verification
+
+Before trusting a run's findings:
+
+1. Read `selection.droppedSections` in the `--json` output — a capped run
+   covered less than every linked section.
+2. Spot-check a finding against the cited hunk: does the section's own text
+   actually conflict with what the diff changed?
+3. Confirm every finding carries `reviewer: "review-jev-docs"` and a
+   `dedupe_key` — both are required for the orchestrator's Quality Gate and
+   Wave C verification to route it correctly.
+
+---
+
+## Iron Laws
+
+### Shared laws (every reviewer)
+
+1. **A claim of runtime harm with no reproducible path is `info`.** If you cannot
+   name the input, call, or condition that reaches the code, you have an
+   observation, not a finding. Report it as `info` and say what would settle it.
+2. **Never flag the theoretical.** The path you describe must exist in the code
+   under review. Do not report a safe API because it could be misused, or a
+   pattern because it is often wrong elsewhere.
+3. **One finding per class, not one per occurrence.** When the same shape appears
+   at several sites, report it once and list every site. Ten findings that are one
+   finding hide the other nine problems.
+
+Severity levels are defined once, in `review-orchestrator/SKILL.md` →
+**Severity (canonical)**. This reviewer does not restate them — it only ever
+emits `minor`, capped by construction (`docsFindingStats`), so the
+`major`/`blocker` shapes never apply here.
+
+---
+
+## Scope Boundaries
+
+| Concern | This skill | Use instead |
+|---------|------------|-------------|
+| A doc section linked to changed code likely went stale | YES | — |
+| Documentation quality/completeness unrelated to this diff | NO | a human, or a dedicated docs review |
+| Judging whether a reported finding is real | NO | `review-verifier` |
+| Editing the documentation itself | NO | a human, following `suggested_fix` |