@mrciphersmith/keryx 0.3.0 → 0.3.2

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

@@ -0,0 +1,187 @@
+---
+name: review-jev-scenarios
+model_tier: light
+description: |
+  Use when: an ADDITIONAL, machine-scored FUNCTIONAL review is wanted — which user
+  scenarios a PR likely changes — never replacing any other reviewer. Dispatched by
+  review-orchestrator in Wave B, via the CLI (`keryx review jev-scenarios`), when
+  `review.jev.scenarios: 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` "does this change alter this scenario's behaviour?" per
+  scenario whose linked code the diff touches; keryx writes every word of every finding.
+  NOT for: discovering scenarios nobody documented (it reads existing gdwiki
+  user-scenario pages, PRD requirement/scenario sections, and README/docs "how to"
+  sections — a scenario that exists only in someone's head is invisible to it), and not
+  a substitute for manually walking the checklist it produces.
+triggers:
+  - "jev scenarios"
+  - "functional review"
+  - "review --jev-scenarios"
+metadata:
+  author: "MrCipherSmith"
+  version: "1.0.0"
+  category: "review"
+  compatible_harnesses: "cursor,codex,zed,opencode,claude"
+  engine: "jev"
+  origin: "authored"
+license: "MIT"
+---
+
+# Review — Jev Scenarios (deterministic functional review)
+
+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-scenarios` and reads the `--json`
+output. Every finding is composed by keryx; Jev ("System One" on OpenRouter)
+supplies only one `noul` probability per scenario — never prose.
+
+---
+
+## What it does
+
+1. Gathers user scenarios deterministically from three sources: gdwiki pages
+   of type `user-scenario` (`.metaproject/wiki/user-scenarios/**`), PRD
+   requirement/scenario sections (`docs/requirements/**`, any heading
+   matching scenario/requirement/user story/use case), and README/docs "how
+   to" sections (`README.md`, `docs/docs/**`).
+2. Extracts each scenario's own links to code — markdown links and inline
+   code-span file references, the same convention `src/wiki/backlinks.ts`
+   already established for the wiki's own code edges.
+3. Computes, per scenario, which of its linked files the diff actually
+   touches (a fact) and whether a test in the diff covers a touched link (a
+   fact).
+4. For every scenario with at least one touched link, asks Jev **one
+   `noul`**: "does this change alter this scenario's behaviour?" — batched
+   under the vendor's 64k token budget, capped at `--max-calls` (default
+   150), with every drop reported.
+5. Emits a **manual-check list**: every scenario at/above threshold (default
+   0.5), ranked, each with its touched links as evidence — for a human to
+   walk before merge.
+6. Emits a `minor` finding for each likely-affected scenario with **no test
+   in the diff covering it** (a fact) — severity fixed at `minor`: this
+   flags attention over a functional scenario, it does not assert a defect.
+
+---
+
+## Input Contract
+
+Not dispatched with a prompt — invoked as a CLI command:
+
+```text
+keryx review jev-scenarios (--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 file every
+other reviewer's dispatch already reads — so this reviewer's "touched by this
+diff" facts agree with the round's own scope.
+
+---
+
+## Opt-in and privacy
+
+Refuses before any read or network call unless `.metaproject/tasks.config.json`
+declares:
+
+```json
+{ "review": { "jev": { "scenarios": true } } }
+```
+
+Every scenario's text sent to Jev is redacted first through
+`src/security/service.ts` — the same floor every other Jev-backed mode in
+this repository already 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-scenarios"`, `summary`, `findings`,
+`stats` — under `--json`, plus one orchestrator-facing extra: `checklist`
+(the ranked manual-check list described 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`/flow 332's
+  `review-jev-risk`, 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 domain reviewer's own read of
+  the diff.
+- The consolidated report's "Manual verification" section (or equivalent)
+  should surface `checklist` verbatim alongside any findings — a scenario
+  that scored below the finding threshold but above the checklist threshold
+  is still worth a human glance even though it produced no finding.
+
+---
+
+### 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: severity is fixed at
+`minor` — never higher — and `evidence` always names the scenario's linked
+code and the exact files this diff touched (never an unreproducible claim);
+a scenario is only asked about when a real link of its own is in the diff,
+never a hypothetical connection; and each scenario is its own class with its
+own `dedupe_key`, so there is nothing to collapse across sites.
+
+---
+
+## Red Flags
+
+| Rationalization | Why it is wrong |
+|---|---|
+| "Jev said 0.9, so this scenario is definitely broken" | A `noul` score is a probability that behaviour changed, not a verdict — it only ever produces a `minor` finding, and only when paired with the separate "no covering test" fact |
+| "This PRD scenario links to a huge, frequently-touched file, so the match is meaningless" | Down-weighted after a live check (`SCENARIO_LINK_FANOUT_THRESHOLD`): a link to a file referenced by more scenarios than that only still counts as touched when the scenario's own text names one of the diff's touched exported symbols — read the scenario's own text before assuming a surviving entry is still spurious |
+| "No entries in checklist means nothing changed functionally" | Discovery only covers three sources (gdwiki `user-scenario` pages, `docs/requirements/**`, README/docs "how to" sections); a scenario that exists only in someone's head, or in a doc outside those three locations, is invisible to this reviewer |
+| "checklist is empty so scenarioSources must be empty too" | `scenarioSources` lists every discovered scenario; `checklist` lists only those with a touched link at/above threshold — a project can have hundreds of scenarios discovered and zero touched by a given diff |
+
+---
+
+## Verification
+
+Before trusting a run's findings:
+
+1. Read `selection.notApplicable`/`selection.scenariosSkipped` in the
+   `--json` output — a scenario with no touched link was never asked, and a
+   capped run may have skipped some that were.
+2. Spot-check a `checklist` entry against the scenario's own source
+   (`id` names the file, and for a PRD/README section, the heading): does
+   the touched link actually sit inside the part of the diff that matters
+   for that scenario, or did a large, widely-linked file produce a spurious
+   match?
+3. Confirm every finding carries `reviewer: "review-jev-scenarios"` 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 |
+|---------|------------|-------------|
+| Which documented user scenarios a diff likely changes | YES | — |
+| Discovering an undocumented scenario | NO | a human, or write the scenario down first |
+| Judging whether a reported finding is real | NO | `review-verifier` |
+| A risk map of the diff's hunks | NO | `review-jev-risk` |

package/src/gdskills/bundled/skills/review/review-orchestrator/SKILL.detail.md

@@ -43,3 +43,42 @@ suppressing it would trade real coverage for tidiness. Record the drift in
 `review_context` and name it once in the report, so the next person knows the
 profile is due a re-read. Never file it as a finding against the code under
 review: it is a fact about the review, not about the diff.
+
+## CLI-engine reviewers — dispatched as a command, not a sub-agent
+
+`review-jev-rules` (flow 330), `review-jev-risk` and `review-jev-scenarios`
+(both flow 332), and `review-jev-docs` and `review-jev-comments` (flow 333)
+are ADDITIONAL reviewers, never replacing any other, and their dispatch
+mechanism differs from every reviewer named in SKILL.md's Routing Table:
+there is no platform-native agent to invoke, because each is a deterministic
+**keryx program**. Run them with `keryx review jev-rules --scope
+<scope.json> --json`, `keryx review jev-risk --scope <scope.json> --json`,
+and `keryx review jev-scenarios --scope <scope.json> --json` — the SAME
+`scope.json` every other Wave A/B reviewer's dispatch already reads, so each
+checks exactly the same hunks. `review-jev-docs` and `review-jev-comments`
+take a diff/PR target instead: `keryx review jev-docs (--diff <ref>|--pr
+<n>) --json` and `keryx review jev-comments --pr <n> --repo <owner/repo>
+--json`. Read each `--json` output as a `REVIEW_RESULT` and merge its
+`findings` into the consolidated array exactly like a sub-agent reviewer's:
+same Sub-Agent Report Quality Gate, same dedup, same Wave C verification.
+`review-jev-risk` additionally emits `ranked` and `routingHints`;
+`review-jev-scenarios` additionally emits `checklist` — see each reviewer's
+own SKILL.md for what to do with its extra.
+
+Gate each BEFORE running its command, not after: skip it — recorded in
+`Skipped reviewers` with the reason, never silently absent — when its own
+opt-in (`review.jev.rules` / `review.jev.risk` / `review.jev.scenarios` /
+`review.jev.docs` / `review.jev.comments`) is not `true` in
+`.metaproject/tasks.config.json`, or when no Jev/OpenRouter credential is
+resolvable. Either gate failing means the command itself would refuse before
+any read or network call, so checking first saves a doomed dispatch. The
+five opt-ins are independent: any subset may be on. `review-jev-comments`
+additionally needs a comment ledger to already exist (`keryx review comments
+collect` run first) — it refuses, before any read, when there is none.
+
+`keryx review reviewers --json` marks a CLI-engine reviewer with
+`"engine": "jev"` on its `bundled` entry — the field's presence, not its
+absence, is what distinguishes it from the default (an LLM sub-agent
+dispatch). A future engine-backed reviewer follows the same pattern: gate on
+its own opt-in and reachability, dispatch as a command, merge its `--json`
+output the same way.

package/src/gdskills/bundled/skills/review/review-orchestrator/SKILL.md

@@ -1177,7 +1177,7 @@ whoever reads the merge commit a year later reads the body.
 Dispatch selected reviewers in parallel when independent. Use waves when token budget is tight or when one reviewer needs another result:
 
 1. Wave A - core correctness/risk reviewers: logic, architecture, security/highload when selected.
-2. Wave B - domain reviewers: frontend/backend/testing/convention reviewers filtered to relevant files.
+2. Wave B - domain reviewers: frontend/backend/testing/convention reviewers filtered to relevant files. `review-jev-rules` (flow 330), `review-jev-risk`/`review-jev-scenarios` (flow 332), `review-jev-docs`/`review-jev-comments` (flow 333) also run here, CLI-engine not sub-agent, `"engine": "jev"` in `keryx review reviewers --json`, gated on their own opt-in and a resolvable Jev/OpenRouter credential — `SKILL.detail.md` § "CLI-engine reviewers".
 3. Wave C - **verification**: `review-verifier` over the consolidated findings, when blockers/majors
    exist, `--verify` is set, or the PR is high-risk. See below.
 

package/src/gdskills/bundled/stacks/angular/agent-refs.json

@@ -0,0 +1,4 @@
+{
+  "agents": [],
+  "note": "Demoted from stable (R1 review round 2, PR #719, N-M1): a realism sweep found angular-implementation's and angular-testing's positive/negative trigger prompts were trigger-prefix near-copies or scorer-avoidant phrasing rather than genuinely independent realistic requests. Rewritten with natural phrasing per the reviewer's own probes and NOT iterated against the router. Honest result: angular-implementation's trigger accuracy collapsed (TP 1/7) and angular-testing picked up a real false positive (an e2e/staging negative it should not select) -- both accepted as the true routing signal rather than polished back to a passing score. angular-build-fix and angular-code-review still pass cleanly. A pack needs every skill to pass, so angular reverts to stability: \"experimental\"; the generated agent-code-auditor/build-fixer pair is removed."
+}