@mrciphersmith/keryx 0.3.1 → 0.3.2

package/dist/core.js

@@ -8179,6 +8179,18 @@ var init_catalog = __esm(() => {
       "Dispatch specialized review passes conceptually or as separate skill loads.",
       "Report findings first, ordered by severity, with concrete file references."
     ]),
+    skill("review-jev-docs", "review", ["recommended", "full"], "Find documentation sections that went stale because of a diff, scored by Jev.", [
+      "Split every discovered documentation source into sections by heading, deterministically.",
+      "Link a section to changed code by an explicit path/symbol/verb it mentions.",
+      "Ask Jev one noul question per linked section; keryx writes every word of the finding.",
+      "Flag a removed/renamed CLI flag still mentioned in docs with no Jev call at all."
+    ]),
+    skill("review-jev-comments", "review", ["recommended", "full"], "Check whether open PR review comments were addressed, scored by Jev.", [
+      "Read open comments from the existing ledger, never re-collect from GitHub.",
+      "Compute commits-after-comment, thread-resolved, and reply facts deterministically.",
+      "Ask Jev one choice question per open comment; keryx writes every word of the finding.",
+      "Never post a reply or resolve a thread \u2014 the label is advisory only."
+    ]),
     skill("review-logic", "review", ["recommended", "full"], "Review logic correctness, contracts, edge cases, nullability, and async behavior.", [
       "Trace behavior through call sites and affected context.",
       "Look for incorrect assumptions, missing branches, race conditions, and error paths.",
@@ -8263,6 +8275,16 @@ var init_catalog = __esm(() => {
       "Fall back to confirming the class_scope sites exist; reasoning alone is capped at unverifiable.",
       "Emit one verdict per finding checked; never add a finding, raise a severity, or edit a finding's text."
     ]),
+    skill("review-jev-risk", "review", ["recommended", "full"], "Risk map of a diff's hunks \u2014 deterministic facts plus one Jev noul per risk dimension, ranked, with a routing hint for security/concurrency.", [
+      "Score every retained hunk on security, data/migration, public-API, concurrency, and error-handling.",
+      "Emit a finding only above threshold and with no nearby test; severity capped at info/minor.",
+      "Feed a routing hint for review-security-code/review-highload when a hunk crosses threshold on that dimension."
+    ]),
+    skill("review-jev-scenarios", "review", ["recommended", "full"], "Functional review \u2014 which user scenarios a diff likely changes, from gdwiki/PRD/README sources plus one Jev noul per touched scenario.", [
+      "Discover scenarios from gdwiki user-scenario pages, PRD requirement sections, and README/docs how-to sections.",
+      "Ask only scenarios whose linked code this diff touches.",
+      "Emit the ranked manual-check list, and a minor finding for a likely-affected scenario with no covering test."
+    ]),
     skill("review-frontend-conventions", "review", ["recommended", "full"], "Review frontend code against repository-local frontend conventions and agent entrypoints.", [
       "Load local AGENTS.md/CLAUDE.md and matched frontend rules.",
       "Check component, state, styling, i18n, error, and Storybook conventions.",
@@ -8632,7 +8654,11 @@ var init_skill_length_ceilings = __esm(() => {
     "review/review-frontend": 634,
     "review/review-frontend-conventions": 213,
     "review/review-highload": 550,
+    "review/review-jev-comments": 184,
+    "review/review-jev-docs": 189,
+    "review/review-jev-risk": 190,
     "review/review-jev-rules": 267,
+    "review/review-jev-scenarios": 187,
     "review/review-layout": 238,
     "review/review-logic": 377,
     "review/review-orchestrator": 1723,
@@ -37127,12 +37153,36 @@ var HELP_GROUPS = [
     group: "Managed work",
     summary: "Check a PR, a review report, or a diff against a reference document's clauses, with Jev."
   },
+  {
+    kind: "slash",
+    name: "/risk",
+    group: "Managed work",
+    summary: "Risk map of the working diff's hunks \u2014 deterministic facts plus Jev per risk dimension, ranked, highest risk first."
+  },
+  {
+    kind: "slash",
+    name: "/scenarios",
+    group: "Managed work",
+    summary: "Which user scenarios the working diff likely changes \u2014 deterministic scenario/code links plus Jev, ranked."
+  },
   {
     kind: "slash",
     name: "/jevrules",
     group: "Managed work",
     summary: "Check the working diff's hunks against every applicable project rule clause, with Jev, grouped by rule."
   },
+  {
+    kind: "slash",
+    name: "/staledocs",
+    group: "Managed work",
+    summary: "List doc sections that likely went stale because of the working diff, with Jev."
+  },
+  {
+    kind: "slash",
+    name: "/opencomments",
+    group: "Managed work",
+    summary: "List open PR review comments with a Jev resolved/still-open/escalation label \u2014 /opencomments <owner/repo> <pr>."
+  },
   {
     kind: "slash",
     name: "/guard",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrciphersmith/keryx",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "description": "Version-controlled project context for AI coding agents: code graph, architecture wiki, project memory, relevant tests, quality signals, and task flows.",
   "private": false,
   "publishConfig": {

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-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` |

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

@@ -0,0 +1,190 @@
+---
+name: review-jev-risk
+model_tier: light
+description: |
+  Use when: an ADDITIONAL, machine-scored RISK MAP is wanted over every changed hunk —
+  never replacing any other reviewer. Dispatched by review-orchestrator in Wave B, via
+  the CLI (`keryx review jev-risk`), when `review.jev.risk: 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 (hunk, risk dimension) pair; keryx writes every word of every finding.
+  NOT for: judgement calls a risk dimension does not state (style, architecture beyond
+  risk-flagging — those stay with the reviewers that already cover them), and not a
+  substitute for a human reviewer reading the ranked map it produces.
+triggers:
+  - "jev risk"
+  - "risk map"
+  - "review --jev-risk"
+metadata:
+  author: "MrCipherSmith"
+  version: "1.0.0"
+  category: "review"
+  compatible_harnesses: "cursor,codex,zed,opencode,claude"
+  engine: "jev"
+  origin: "authored"
+license: "MIT"
+---
+
+# Review — Jev Risk (deterministic risk map of the diff)
+
+An ADDITIONAL orchestrator reviewer, flow 332. 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-risk` and reads the `--json` output.
+Every finding is composed by keryx; Jev ("System One" on OpenRouter) supplies
+only five `noul` probabilities per hunk — one per risk dimension — never
+prose.
+
+---
+
+## What it does
+
+1. Takes every changed hunk from `keryx review scope`/`buildReviewScope`
+   (mechanical bulk already dropped).
+2. Computes deterministic facts FIRST, per hunk: a path class (auth/
+   permissions, crypto, migrations, schema, public API, config, concurrency
+   primitives, IO), the exported symbols it touches, its changed-line count,
+   and whether a test file elsewhere in the diff touches the same module.
+3. Asks Jev **one `noul` per risk dimension** per hunk — security-sensitive,
+   data/migration, public-API/contract change, concurrency, error-handling —
+   batched under the vendor's 64k token budget, capped at `--max-calls`
+   (default 150, counted as hunk x dimension pairs), with every drop
+   reported.
+4. Ranks hunks by combined risk (the MAX across its five dimensions — one
+   high-risk dimension is enough to draw attention) so a human reviewer knows
+   where to look first.
+5. Emits a finding ONLY for a hunk above threshold (default 0.7) AND with no
+   test touched nearby in the same diff (a fact) — severity capped at
+   `info`/`minor`, never higher: this flags attention, it does not assert a
+   defect.
+6. Additionally emits a **routing hint**: hunks above threshold with a
+   security or concurrency dimension are listed with a suggested reviewer
+   (`review-security-code`/`review-highload`) for the orchestrator to
+   consider dispatching — see "Orchestrator integration" below.
+
+---
+
+## Input Contract
+
+Not dispatched with a prompt — invoked as a CLI command:
+
+```text
+keryx review jev-risk (--diff <ref> | --pr <n> | --scope <scope.json>)
+                      [--max-calls <n>] [--threshold <0..1>]
+                      [--repo <owner/repo>] [--model <jev-1.13|jev-latest>]
+                      [--fixtures <dir>] [--json]
+```
+
+`review-orchestrator` passes `--scope <scope.json>` — the same `keryx review
+scope --json` file every other reviewer's dispatch already reads — so this
+reviewer checks exactly the same hunks as everyone else in the round.
+
+---
+
+## Opt-in and privacy
+
+Refuses before any read or network call unless `.metaproject/tasks.config.json`
+declares:
+
+```json
+{ "review": { "jev": { "risk": true } } }
+```
+
+Every hunk sent to Jev is redacted first through `src/security/service.ts` —
+the same floor `review conform`/`review ci-triage`/`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-risk"`, `summary`, `findings`, `stats` —
+under `--json`, plus two orchestrator-facing extras: `ranked` (every scored
+hunk, highest risk first) and `routingHints` (see above). Its findings merge
+into the consolidated array exactly like any other reviewer's: same Quality
+Gate, same dedup, same Wave C verification.
+
+---
+
+## 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 flow 330's `review-jev-rules`, 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 `review-security-code`,
+  `review-highload`, or any other pass.
+- **Routing hint**: read `routingHints` from its `--json` output. Each entry
+  names a hunk location, the dimension that crossed threshold
+  (`security`/`concurrency`) and a `suggestedReviewer`
+  (`review-security-code`/`review-highload`). When that reviewer was not
+  already selected for the round, dispatch it too — the hint is advisory,
+  not a hard requirement, and the orchestrator's own path-based selection
+  always takes precedence when it already covers the same hunk.
+
+---
+
+### 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
+hunk location, quotes the changed line, and states every dimension's
+probability (never an unreproducible claim); a finding is synthesized only
+against the hunk actually scored, never a hypothetical pattern; and each
+hunk is a distinct site with its own probabilities, so there is no repeated
+class across sites for this reviewer to collapse — the routing hint follows
+the same discipline, naming the exact hunk and dimension that crossed
+threshold rather than a general warning.
+
+---
+
+## Red Flags
+
+| Rationalization | Why it is wrong |
+|---|---|
+| "Jev said 0.9, so this hunk is definitely dangerous" | A `noul` score is a probability across one dimension, not a verdict — severity stays capped at `info`/`minor` precisely because Jev alone is not authoritative |
+| "No nearby test means nobody tested this at all" | `hasNearbyTest` requires the nearby test's OWN diff text to mention a touched symbol or import the hunk's module (`testHunkEvidence`), tightened after a live-check false negative — still a regex heuristic, not proof of coverage through an indirection it cannot see |
+| "This hunk touches a .md file, so 'no nearby test' is a meaningful finding" | Docs (`.md`/`.txt`) hunks are excluded before scoring (`isNonCodeHunk`) after a live check where prose scored `public-api` — this cannot happen; `selection.hunksNotCode` reports the count |
+| "No findings means the diff is low risk" | `--max-calls` bounds how many hunks are scored; a capped run reports `selection.hunksSkipped` for exactly this reason — read the selection stats before treating silence as clean |
+
+---
+
+## Verification
+
+Before trusting a run's findings:
+
+1. Read `selection.hunksSkipped` in the `--json` output — a capped run
+   covered fewer than "every retained hunk" and the report should say so.
+2. Spot-check a handful of `ranked` entries against the actual hunk: does the
+   file/line range and the top dimension make sense for what actually
+   changed there? Docs (`.md`/`.txt`) hunks never reach `ranked` at all —
+   `selection.hunksNotCode` should account for every one of them in the
+   diff.
+3. Confirm every finding carries `reviewer: "review-jev-risk"` 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 |
+|---------|------------|-------------|
+| A ranked risk map of the diff's hunks | YES | — |
+| An actual security/concurrency finding | NO (routing hint only) | `review-security-code` / `review-highload` |
+| Judging whether a reported finding is real | NO | `review-verifier` |
+| Which user scenarios changed | NO | `review-jev-scenarios` |