@mrciphersmith/keryx 0.2.164 → 0.3.1

package/src/gdskills/bundled/rules/core/model-selection.mdc

@@ -83,6 +83,57 @@ residue, and it is kept in the smallest shape that works:
 A model whose name is a codename carrying no size is unrankable by design. That
 is the honest outcome, not a gap to be patched with folklore.
 
+**Version is deliberately not ranked here.** `rankModelId` never parses a
+version number out of an id — two ids in the same size-word family but a
+different generation (an older vs. a newer numbered release of the same
+line) rank IDENTICALLY through this resolution, and a
+`standard`/`light`/`deep` dispatch never distinguishes between them. That
+stays true for `spawn_subagent` and `keryx review tier` after the decision
+below; it is a DIFFERENT consumer's rule, not this one's.
+
+The routing "derived default table" (`deriveDefaultTable`,
+`src/harness/routing/derive-default-table.ts`, flow 327/PRD §6.3) is that
+different consumer: it picks one model per routing category (`review`,
+`subagents`, `quick`, …) from a whole connected catalogue, not a tier
+relative to the session. The operator decided, 2026-09-25 (review of PR #718:
+a session's newer release lost a tie to an older release of the SAME family
+it should have beaten), that WITHIN the same family and vendor a newer
+version ranks higher there — the family word (a size marker from this same
+`MODEL_RANK_HINTS` list) already carries the size class, so version is free
+to order generations within it. That table reuses
+`rankModelId`/`MODEL_RANK_HINTS` UNMODIFIED for the size axis and adds its
+own separate, conservative version parse on top of it — nothing above
+changes for this module's own tier resolution.
+
+That version parse (`parseModelVersion`/`familyKey`, round 2) reads BOTH a
+dotted id (`vendor-opus-5.5`, `gemini-3.8-flash`) and a real
+Anthropic-style HYPHENATED one, where a run of 2-3 adjacent short (1-2
+digit) numeric tokens reads as a dotted version (`vendor-opus-4-8` → `4.8`).
+It still refuses a date/snapshot-shaped token (6-8 bare digits) and more
+than one numeric group in the same id — no version rather than a guess. A
+`gpt-4o`-style id (a short number plus one trailing letter) parses the
+number alone as the version, the letter kept only as an ignored variant
+tag, so `gpt-4o` and `gpt-4.1` compare within the same family instead of
+never comparing at all. Two versions of the same family are never decided
+by alphabetical order — the id-string fallback only applies when neither
+side has a parseable version.
+
+**A parameter-size token is never a version (round 3, review of PR #718).**
+`7b`, `32b`, `70b`, `1.5b`, `8x7b` — a total or MoE "N experts x M billion"
+param count — always stay in `familyKey` and are never fed to
+`parseModelVersion`. Before this fix, the letter-variant shape meant for
+`gpt-4o` (`/^(\d{1,2})([a-z])$/`, any trailing lowercase letter) also
+matched a size token, so `qwen2.5-coder-7b` and `qwen2.5-coder-32b` were
+misread as the SAME family at "version" 7 vs. 32 — merging two genuinely
+different-sized models and ranking the smaller one "newer". The letter
+variant is now restricted to the one real vendor shape that needs it
+(`4o`'s trailing `o`); every other trailing letter after a short digit run
+is a size suffix, so `qwen2.5-coder-7b`/`qwen2.5-coder-32b` and
+`llama-3.3-70b`/`llama-3.3-8b` key to different families and are never
+version-compared against each other. A trailing `-latest`/`-preview` alias
+word is also stripped from `familyKey` only (never from the id itself), so
+`vendor-3-7-sonnet-latest` joins the same family as `vendor-sonnet-5`.
+
 ## Falling back
 
 Ranking is **refused**, and every tier keeps the session's provider and model,

package/src/gdskills/bundled/rules/core/skill-lifecycle.mdc

@@ -1,6 +1,7 @@
 ---
 description: "When and how agents verify and re-learn project-skills during implementation and review. Verify/learn live in the agent loop, not in git hooks."
 alwaysApply: false
+version: 0.2.0
 ---
 
 # Skill Lifecycle — verify & learn in the loop
@@ -52,8 +53,35 @@ a different `review tier` invocation (e.g. `--scope narrow`, which resolves
 heavier than `light`).** The flagship's only job here is to review the
 proposal before apply.
 
+### Passive observation is not mutation
+
+A hook registered under the shell hook runtime may append an
+**observation event** to `.metaproject/data/learning/observations/` — the
+shipped `keryx.learning-observer` hook does exactly this, on
+`tool-start`/`tool-complete`/`tool-failed`/`user-prompt`/`session-start`/
+`turn-stop`/`session-end`. This is explicitly permitted from a hook, unlike
+every other write this rule governs, because it changes no skill, rule,
+agent, or memory entry — it only accumulates evidence (redacted, digest-only)
+that a human will later decide about.
+
+`keryx learn extract`, which turns accumulated observations into a
+`status: candidate` `learned-pattern` record under
+`.metaproject/data/learning/candidates/`, is a separate, **command- or
+schedule-triggered** step — never run inside a hook. It still produces no
+`accepted` state and mutates no skill/rule/agent/memory file by itself.
+
+Everything from `keryx learn accept` onward — Accept, project-skill Apply,
+reviewer-profile Apply, Promote, Graduate apply — remains agent-loop,
+human-triggered work under the rule above, with the same "dispatch as a
+light-tier subagent, review before apply" discipline already specified for
+`skills learn apply`. Each of accept/promote/graduate-apply additionally
+refuses outright outside a real interactive terminal (no bypass flag).
+
 ## Never
 
-- Do not put `learn` (or any mutation) in a hook.
+- Do not put `learn` (or any mutation) in a hook — **passive observation is
+  the single exception** (see above): a hook may append an observation event,
+  nothing more. `keryx learn extract` also never runs inside a hook, even
+  though it produces no `accepted` state.
 - Do not `apply` a proposal without reading it.
 - Do not trust a `stale` / `needs-review` skill as ground truth.

package/src/gdskills/bundled/rules/core/skills-storage-workflow.mdc

@@ -66,8 +66,8 @@ gets reconciled.
 
 `SKILL.md` frontmatter follows the published Agent Skills specification
 (agentskills.io — the format Zed adopted when it dropped its own Rules
-Library), with two deliberate additions. Flow 203 removed two accidental
-divergences that had crept in; keep both fixes intact when authoring or
+Library), with two deliberate additions. Two earlier accidental divergences
+have since been removed; keep both fixes intact when authoring or
 editing a skill:
 
 - **`version` lives in `metadata.version` only.** The spec has no top-level

package/src/gdskills/bundled/skills/review/code-style-review/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: code-style-review
-description: "Use when the legacy code style and architecture review profile (code-style-patterns.mdc) is asked for by name — naming, organization, patterns, and TypeScript usage on the current branch. NOT for: a general style review (review-style) or an architecture review (review-architecture)."
+description: "Use when a caller wants the style/architecture checklist in code-style-patterns.mdc applied by its own name — checks naming, module and file layout, and TypeScript usage patterns against that specific ruleset, over this branch's diff. Narrower than a general style pass, and separate from the correctness-and-security AI review baseline. NOT for: a general style review (review-style) or an architecture review (review-architecture)."
 triggers:
   - "code-style-review"
   - "architecture style"

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 |

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

@@ -43,3 +43,29 @@ 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) is an ADDITIONAL reviewer, never replacing any
+other, and its dispatch mechanism differs from every reviewer named in
+SKILL.md's Routing Table: there is no platform-native agent to invoke,
+because it is a deterministic **keryx program**. Run it with `keryx review
+jev-rules --scope <scope.json> --json` — the SAME `scope.json` every other
+Wave A/B reviewer's dispatch already reads, so it checks exactly the same
+hunks. Read its `--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.
+
+Gate it BEFORE running the command, not after: skip it — recorded in `Skipped
+reviewers` with the reason, never silently absent — when `review.jev.rules`
+is not `true` in `.metaproject/tasks.config.json`, or when no Jev/OpenRouter
+credential is resolvable. Either gate failing means `keryx review jev-rules`
+itself would refuse before any read or network call, so checking first saves
+a doomed dispatch.
+
+`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.