@mrciphersmith/keryx 0.3.0 → 0.3.2

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

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

@@ -0,0 +1,267 @@
+---
+name: review-jev-rules
+model_tier: light
+description: |
+  Use when: an ADDITIONAL, machine-scored pass is wanted over every changed hunk against
+  every applicable project rule clause — never replacing any other reviewer. Dispatched
+  by review-orchestrator in Wave B, via the CLI (`keryx review jev-rules`), when
+  `review.jev.rules: 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` violation probability per (hunk, rule clause) pair; keryx
+  writes every word of every finding.
+  NOT for: judgement calls a rule clause does not state (logic bugs, architecture,
+  security, performance — those stay with the reviewers that already cover them), and
+  not a substitute for reading the rules yourself. A finding here says a hunk likely
+  contradicts a clause of a rule this project already wrote down; it says nothing about
+  code that violates no documented rule.
+triggers:
+  - "jev rules"
+  - "rule check"
+  - "review --jev-rules"
+metadata:
+  author: "MrCipherSmith"
+  version: "1.0.0"
+  category: "review"
+  compatible_harnesses: "cursor,codex,zed,opencode,claude"
+  engine: "jev"
+  origin: "authored"
+license: "MIT"
+---
+
+# Review — Jev Rules (deterministic project-rule conformance)
+
+An ADDITIONAL orchestrator reviewer, flow 330. 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-rules` and reads the `--json` output. Every
+finding is composed by keryx; Jev ("System One" on OpenRouter) supplies only a
+`noul` probability per `(hunk, rule clause)` pair — it never writes prose, and
+nothing it returns is quoted verbatim into a finding except the clause text
+keryx already had.
+
+---
+
+## What it does
+
+1. Discovers rule sources deterministically (`src/review/jev-rules.ts`'s
+   module header names the exact scope): every file under
+   `.metaproject/rules/**` and `rules/**`, every project-skill or installed
+   gdskill whose name or `metadata.category` marks it a coding convention, and
+   anything named by `--rules <paths>`. **`--rules` bypass is scoped to ONE
+   FILE**: an entry naming a single document bypasses the category filter
+   below outright; an entry naming a DIRECTORY is walked and its files are
+   filtered exactly like auto-discovery — asking for a whole directory is not
+   the same as naming one document, and the whole point of the filter is lost
+   if it is.
+2. **Category filter, before clause extraction.** Each discovered source
+   (auto-discovered, or a file found by walking a `--rules` DIRECTORY — never
+   a `--rules` entry naming that ONE file explicitly) is classified
+   `code`/`process`/`docs` — explicit frontmatter first (`applies_to:
+   code|process|docs`, or `metadata.category`), else a documented
+   filename/title heuristic (`PROCESS_RULE_HEURISTIC_TERMS`: `commit`, `git`,
+   `tdd`, `workflow`, `definition-of-done`, `documentation`, `requirements`,
+   `plan`, `prompting`, `subagent`, `skill`, `jobs`, `orchestrat`,
+   `review-process`, `release`). A `process`/`docs` source never reaches
+   clause extraction at all — excluded, and reported with its reason under
+   `excludedSources`.
+3. Splits each remaining rule document into clauses with
+   `extractReferenceClauses` (the same deterministic splitter `review
+   conform` uses), drops authoring-template scaffolding
+   (`isPlaceholderClauseText`: an unfilled `[x] <criterion> — verified by
+   <test>` checklist line, text dominated by `<...>` placeholders, or a bare
+   code-fence line — never a real clause, dropped BEFORE tagging so it costs
+   nothing), then TAGS every remaining clause `state_kind:
+   "pr"|"report"|"hunk"` + `checkable` by REUSING `review conform`'s own
+   `applyClauseTags`/`buildClauseTagQuestions`/`clauseTagFromChoice` — an
+   explicit `[state:hunk]`/`[not-checkable: ...]` marker on the clause text
+   when the rule author wrote one, else one Jev `choice` call per doc's
+   untagged clauses (never per clause), cached by the doc's content hash at
+   `.metaproject/data/review-jev-rules/clause-tags.json` (a jev-rules-
+   specific cache file — `review conform` and `review-jev-rules` never race
+   on the same one). Only a clause tagged `state_kind: "hunk"` and
+   `checkable` is ever paired against a hunk; anything else is dropped and
+   reported under `droppedClauses`.
+4. Decides, per `(rule, changed file)` pair, whether an applicable clause
+   applies — by declared path globs (`metadata.paths`) and/or
+   `metadata.stack_requires`, failing toward inclusion exactly like `keryx
+   review stack`/`scope.ts` already do, THEN by file kind: a docs hunk
+   (`.md`/`.mdx`/`.txt`) pairs only with a `docs`-categorised source or a
+   clause explicitly tagged `[docs-applicable]`; a code source never pairs
+   with a docs hunk, and vice versa (`clauseFileKindApplicability`).
+5. Takes every changed hunk from `keryx review scope` (mechanical bulk
+   already dropped) and asks Jev, per applicable `(hunk, hunk-checkable
+   clause)` pair, **one question**: "does this hunk VIOLATE this clause?" —
+   batched under the vendor's 64k token budget, capped at `--max-calls`
+   (default 150). The budget is spread FAIRLY: hunks are ranked code, then
+   tests, then docs, and pairs are allocated round-robin across hunks rather
+   than draining the cap on the first hunk in diff order — every selection,
+   every drop, and per-hunk coverage (`selection.hunkCoverage`, how many
+   hunks were reached vs. never reached) is reported, never silent.
+6. Synthesizes findings deterministically: `problem` quotes the clause,
+   `impact` is the rule's own stated rationale (if it has a `## Rationale`/
+   `## Why` section) or a fixed template, `suggested_fix` names the clause to
+   bring the hunk in line with, `evidence` is the hunk location(s) + Jev's
+   probability. Severity is capped at `minor` unless the rule itself declares
+   a higher one (`[severity: major]` on the clause). One finding per
+   `(clause, file)`, deduped across every hunk of that file with a hunk list.
+
+**Why steps 2-5's filters exist:** a live check of this repository's own
+41-doc `.metaproject/rules/**` corpus against a merged PR hand-labelled ~1/10
+findings correct. Two causes, both fixed here: (a) process/agent-behaviour
+rules (commit-message formatting, TDD workflow, an agent's own prompting
+standard) paired against a code hunk they were never meant to describe,
+because the corpus declares no `metadata.paths`/`stack_requires` and
+applicability fails open to "applies everywhere" — the category and
+file-kind filters (steps 2 and 4); (b) a re-measurement then found the
+`--rules` bypass defeating the category filter for an entire directory, and
+the whole `--max-calls` budget landing on a single docs hunk while no code
+hunk was ever scored — the scoped bypass and fair round-robin budget (steps
+1 and 5). All four are cheap, deterministic, and applied BEFORE any
+violation-scoring Jev call, so they cut cost as well as noise. See
+`.metaproject/flows/330-*/journal.md` for the full before/after numbers.
+
+---
+
+## Input Contract
+
+Not dispatched with a prompt — invoked as a CLI command:
+
+```text
+keryx review jev-rules (--diff <ref> | --pr <n> | --scope <scope.json>)
+                       [--rules <paths>] [--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, with the same mechanical-bulk drops,
+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": { "rules": true } } }
+```
+
+Every hunk, every rule-clause sent for violation scoring, and every clause
+sent for tagging is redacted first through `src/security/service.ts` — the
+same floor `review conform` and `review ci-triage` already apply. No cache or
+output file stores a credential. Two caches, both gitignored and mode `0600`
+under `.metaproject/data/review-jev-rules/`:
+
+- `violation-cache.json`, keyed on the clause text and hunk location, so a
+  re-run over unchanged hunks and unchanged rules costs zero additional Jev
+  calls.
+- `clause-tags.json`, keyed on the rule doc's own content hash — REUSING
+  `review conform`'s own clause-tagging cache module
+  (`src/review/conform-tag-cache.ts`) at this jev-rules-specific path, so a
+  re-run against a DIFFERENT diff but the SAME rule corpus costs zero
+  additional tagging calls even when the hunks (and so the violation cache)
+  miss.
+
+---
+
+## Output Contract
+
+Emits a `REVIEW_RESULT`-shaped object matching
+`.metaproject/skills/gdskills/review/review-orchestrator/reviewer-finding.schema.json`
+— `status`, `reviewer: "review-jev-rules"`, `summary`, `findings`, `stats`,
+plus `tokens` (with `taggingCalls`/`violationCalls` counted separately),
+`selection` (`droppedClauses`'s count, and `hunkCoverage` — one
+`{path, applicablePairs, selectedPairs}` per hunk with something to check,
+plus `hunksWithPairs`/`hunksReached`/`hunksNeverReached`), `ruleSources`
+(each with its `category`), `excludedSources` (category-filtered sources
+with their reason), `droppedClauses` (tag-filtered `(ruleId, clauseId)`
+pairs with their reason), and `droppedPlaceholderClauses`
+(authoring-template clauses dropped before tagging, with their reason) —
+under `--json`. `summary` names how many hunks the budget never reached in
+plain text. 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, 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 `review-style`, the convention
+  reviewers, or any other pass. A rule clause this reviewer flags may also be
+  the exact concern a domain reviewer raises independently; the dedup pass
+  (by `dedupe_key`/`(file, quote, problem)`) merges the two rather than
+  double-counting.
+
+---
+
+### 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 already satisfies all three by construction: `evidence` always
+names the hunk and quotes it (never an unreproducible claim), a finding is
+only synthesized when the hunk itself is checked against the clause (never a
+theoretical pattern), and `synthesizeFindingsFromViolations` dedupes by
+`(clause, file)` with every hunk listed, never one finding per hunk.
+
+---
+
+## Red Flags
+
+| Rationalization | Why it is wrong |
+|---|---|
+| "Jev said 0.9, so this is definitely a violation" | A `noul` score is a probability, not a verdict — severity stays capped at `minor` unless the rule itself declares higher, precisely because Jev alone is not authoritative |
+| "This rule clause doesn't really describe code, but the pair matched anyway" | Applicability defaults to "applies everywhere" when a rule declares no path/stack restriction — the clause-kind filter (step 3), the category filter (step 2), and the file-kind gate (step 4) catch most of this before scoring, but a `state_kind: "hunk"` clause on an off-topic rule can still pass through; that is a property of the rule corpus, not a defect in this reviewer |
+| "No findings means the diff is clean" | `--max-calls` bounds how many pairs are checked; a capped run reports `selection.droppedPairs`/`hunksNeverReached` for exactly this reason — read the selection stats before treating silence as clean |
+| "A rule wasn't checked and I don't know why" | Read `excludedSources` (category filter, at discovery), `droppedClauses` (tag filter, per clause), and `droppedPlaceholderClauses` (template scaffolding, per clause) before assuming a rule was silently skipped — each names the exact reason |
+| "I passed `--rules` at a whole rule directory, so every file in it was checked" | Only a `--rules` entry naming ONE file bypasses the category filter; a directory's files are filtered exactly like auto-discovery — check `excludedSources` |
+| "I'll skip the opt-in check since I trust this project" | The opt-in and credential gates exist because hunk and rule-clause text leaves the machine; skipping them is skipping consent, not a shortcut |
+
+---
+
+## Verification
+
+Before trusting a run's findings:
+
+1. Read `selection.droppedPairs`/`selection.notApplicable`/
+   `selection.droppedClauses`/`selection.hunkCoverage` in the `--json`
+   output — a capped, narrowly-applicable, or tag-filtered run covered less
+   than "every changed hunk against every applicable clause", and
+   `hunksNeverReached` says exactly how many hunks the budget never got to.
+2. Read `excludedSources` — a process/meta rule doc excluded by the category
+   filter is reported by name and reason, never silently absent from
+   `ruleSources`.
+3. Spot-check a handful of findings against the actual hunk: does the quoted
+   line and the cited clause text support the claim? Jev's probability is not
+   evidence a human can inspect; the quote and the clause text are.
+4. Confirm every finding carries `reviewer: "review-jev-rules"` 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 hunk contradicts a documented project rule clause | YES | — |
+| Logic bugs, architecture, security, performance not named by any rule | NO | the matching domain reviewer |
+| Judging whether a reported finding is real | NO | `review-verifier` |
+| Writing or maintaining the rules themselves | NO | a human, or `rules/core/*.mdc` directly |