@mrciphersmith/keryx 0.3.0 → 0.3.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrciphersmith/keryx",
-  "version": "0.3.0",
+  "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/agents/go-code-auditor.md

@@ -1,7 +1,7 @@
 ---
 schema_version: 1
 name: "go-code-auditor"
-description: "Reviews Go code, read-only, for the 6 stack-specific risk patterns this pack's governance gate has confirmed for go (correctness, resource, and security patterns particular to Go). Dispatched for a stack-specific code-quality pass distinct from generic review, gated the same stack_requires-style way review-orchestrator already uses for per-stack reviewers."
+description: "Reviews Go code, read-only, for the 6 stack-specific risk patterns this pack's authors documented for go (correctness, resource, and security patterns particular to Go). Dispatched for a stack-specific code-quality pass distinct from generic review, gated the same stack_requires-style way review-orchestrator already uses for per-stack reviewers."
 role: "A Go-focused code auditor who reads for this stack's known risk patterns without editing anything, and ranks findings by real-world impact rather than listing every theoretical concern equally."
 tools:
   - "read_file"

package/src/gdskills/bundled/agents/python-code-auditor.md

@@ -1,7 +1,7 @@
 ---
 schema_version: 1
 name: "python-code-auditor"
-description: "Reviews Python code, read-only, for the 6 stack-specific risk patterns this pack's governance gate has confirmed for python (correctness, resource, and security patterns particular to Python). Dispatched for a stack-specific code-quality pass distinct from generic review, gated the same stack_requires-style way review-orchestrator already uses for per-stack reviewers."
+description: "Reviews Python code, read-only, for the 6 stack-specific risk patterns this pack's authors documented for python (correctness, resource, and security patterns particular to Python). Dispatched for a stack-specific code-quality pass distinct from generic review, gated the same stack_requires-style way review-orchestrator already uses for per-stack reviewers."
 role: "A Python-focused code auditor who reads for this stack's known risk patterns without editing anything, and ranks findings by real-world impact rather than listing every theoretical concern equally."
 tools:
   - "read_file"

package/src/gdskills/bundled/install-manifest.json

@@ -78,6 +78,44 @@
       ],
       "stackDetectionAware": true
     },
+    "vue": {
+      "description": "Common rules plus the Vue stack pack component (`vue-rules` + `vue-skills`, from src/gdskills/bundled/stacks/vue/), installed when `keryx stack detect` finds a matching tag.",
+      "modules": [
+        "core-common-rules",
+        "skill-lifecycle"
+      ],
+      "components": [
+        "framework:vue",
+        "lang:ts-js-node"
+      ],
+      "stackDetectionAware": true
+    },
+    "angular": {
+      "description": "Common rules plus the Angular stack pack component (`angular-rules` + `angular-skills`, from src/gdskills/bundled/stacks/angular/), installed when `keryx stack detect` finds a matching tag.",
+      "modules": [
+        "core-common-rules",
+        "skill-lifecycle"
+      ],
+      "components": [
+        "framework:angular",
+        "lang:ts-js-node"
+      ],
+      "stackDetectionAware": true
+    },
+    "nextjs-nuxt": {
+      "description": "Common rules plus the Next.js/Nuxt meta-framework stack pack component (`nextjs-nuxt-rules` + `nextjs-nuxt-skills`, from src/gdskills/bundled/stacks/nextjs-nuxt/) alongside its React and Vue bases, installed when `keryx stack detect` finds a matching tag (nextjs or nuxt).",
+      "modules": [
+        "core-common-rules",
+        "skill-lifecycle"
+      ],
+      "components": [
+        "framework:react",
+        "framework:vue",
+        "framework:nextjs-nuxt",
+        "lang:ts-js-node"
+      ],
+      "stackDetectionAware": true
+    },
     "full": {
       "description": "Every registered module and component, unconditionally.",
       "modules": [
@@ -89,8 +127,12 @@
         "react-review-skills",
         "mobx-review-skill",
         "mobx-store-template-rule",
+        "mobx-rules",
+        "mobx-skills",
         "nestjs-review-skill",
         "nestjs-dto-rule",
+        "nestjs-rules",
+        "nestjs-skills",
         "python-rules",
         "python-skills",
         "ts-js-node-rules",
@@ -98,7 +140,13 @@
         "react-rules",
         "react-skills",
         "go-rules",
-        "go-skills"
+        "go-skills",
+        "vue-rules",
+        "vue-skills",
+        "angular-rules",
+        "angular-skills",
+        "nextjs-nuxt-rules",
+        "nextjs-nuxt-skills"
       ],
       "components": [
         "lang:ts-js-node",
@@ -106,7 +154,10 @@
         "capability:mobx",
         "framework:nestjs",
         "lang:python",
-        "lang:go"
+        "lang:go",
+        "framework:vue",
+        "framework:angular",
+        "framework:nextjs-nuxt"
       ]
     }
   },
@@ -441,6 +492,178 @@
       "defaultInstall": true,
       "cost": "medium",
       "stability": "stable"
+    },
+    "nestjs-rules": {
+      "kind": "rule",
+      "description": "NestJS stack pack rules (coding-style, patterns, security, testing; scoped to *.ts) from src/gdskills/bundled/stacks/nestjs/rules/. Complements, does not replace, the existing nestjs-dto-rule.",
+      "paths": [
+        "src/gdskills/bundled/stacks/nestjs/rules/*.mdc"
+      ],
+      "targets": [
+        "claude",
+        "keryx-shell"
+      ],
+      "dependencies": [
+        "ts-js-node-rules"
+      ],
+      "defaultInstall": true,
+      "cost": "light",
+      "stability": "experimental"
+    },
+    "nestjs-skills": {
+      "kind": "skill",
+      "description": "NestJS stack pack skills (implementation, testing, build-fix) from src/gdskills/bundled/stacks/nestjs/skills/. Complements, does not replace, the existing nestjs-review-skill (review-backend).",
+      "paths": [
+        "src/gdskills/bundled/stacks/nestjs/skills/**"
+      ],
+      "targets": [
+        "claude",
+        "keryx-shell"
+      ],
+      "dependencies": [
+        "ts-js-node-skills"
+      ],
+      "defaultInstall": true,
+      "cost": "medium",
+      "stability": "experimental"
+    },
+    "vue-rules": {
+      "kind": "rule",
+      "description": "Vue stack pack rules (coding-style, patterns, security, testing; scoped to *.vue) from src/gdskills/bundled/stacks/vue/rules/.",
+      "paths": [
+        "src/gdskills/bundled/stacks/vue/rules/*.mdc"
+      ],
+      "targets": [
+        "claude",
+        "keryx-shell"
+      ],
+      "dependencies": [
+        "ts-js-node-rules"
+      ],
+      "defaultInstall": true,
+      "cost": "light",
+      "stability": "experimental"
+    },
+    "vue-skills": {
+      "kind": "skill",
+      "description": "Vue stack pack skills (implementation, testing, code review, build-fix, Vue 2 to Vue 3 migration) from src/gdskills/bundled/stacks/vue/skills/.",
+      "paths": [
+        "src/gdskills/bundled/stacks/vue/skills/**"
+      ],
+      "targets": [
+        "claude",
+        "keryx-shell"
+      ],
+      "dependencies": [
+        "ts-js-node-skills"
+      ],
+      "defaultInstall": true,
+      "cost": "medium",
+      "stability": "experimental"
+    },
+    "angular-rules": {
+      "kind": "rule",
+      "description": "Angular stack pack rules (coding-style, patterns, security, testing; scoped to *.ts/*.html) from src/gdskills/bundled/stacks/angular/rules/.",
+      "paths": [
+        "src/gdskills/bundled/stacks/angular/rules/*.mdc"
+      ],
+      "targets": [
+        "claude",
+        "keryx-shell"
+      ],
+      "dependencies": [
+        "ts-js-node-rules"
+      ],
+      "defaultInstall": true,
+      "cost": "light",
+      "stability": "experimental"
+    },
+    "angular-skills": {
+      "kind": "skill",
+      "description": "Angular stack pack skills (implementation, testing, code review, build-fix) from src/gdskills/bundled/stacks/angular/skills/.",
+      "paths": [
+        "src/gdskills/bundled/stacks/angular/skills/**"
+      ],
+      "targets": [
+        "claude",
+        "keryx-shell"
+      ],
+      "dependencies": [
+        "ts-js-node-skills"
+      ],
+      "defaultInstall": true,
+      "cost": "medium",
+      "stability": "experimental"
+    },
+    "nextjs-nuxt-rules": {
+      "kind": "rule",
+      "description": "Next.js/Nuxt meta-framework stack pack rules (coding-style, patterns, security, testing; scoped to *.tsx/*.jsx/*.vue) from src/gdskills/bundled/stacks/nextjs-nuxt/rules/.",
+      "paths": [
+        "src/gdskills/bundled/stacks/nextjs-nuxt/rules/*.mdc"
+      ],
+      "targets": [
+        "claude",
+        "keryx-shell"
+      ],
+      "dependencies": [
+        "react-rules",
+        "vue-rules"
+      ],
+      "defaultInstall": true,
+      "cost": "light",
+      "stability": "experimental"
+    },
+    "nextjs-nuxt-skills": {
+      "kind": "skill",
+      "description": "Next.js/Nuxt meta-framework stack pack skills (implementation, testing, code review, build-fix, upgrade migration) from src/gdskills/bundled/stacks/nextjs-nuxt/skills/.",
+      "paths": [
+        "src/gdskills/bundled/stacks/nextjs-nuxt/skills/**"
+      ],
+      "targets": [
+        "claude",
+        "keryx-shell"
+      ],
+      "dependencies": [
+        "react-skills",
+        "vue-skills"
+      ],
+      "defaultInstall": true,
+      "cost": "medium",
+      "stability": "experimental"
+    },
+    "mobx-rules": {
+      "kind": "rule",
+      "description": "MobX stack pack rules (coding-style, patterns, security, testing; scoped to *.ts/*.tsx) from src/gdskills/bundled/stacks/mobx/rules/. Complements, does not replace, the existing mobx-store-template-rule.",
+      "paths": [
+        "src/gdskills/bundled/stacks/mobx/rules/*.mdc"
+      ],
+      "targets": [
+        "claude",
+        "keryx-shell"
+      ],
+      "dependencies": [
+        "react-rules"
+      ],
+      "defaultInstall": true,
+      "cost": "light",
+      "stability": "experimental"
+    },
+    "mobx-skills": {
+      "kind": "skill",
+      "description": "MobX stack pack skills (store implementation, observable testing) from src/gdskills/bundled/stacks/mobx/skills/. Complements, does not replace, the existing mobx-review-skill (code-mobx-store-review).",
+      "paths": [
+        "src/gdskills/bundled/stacks/mobx/skills/**"
+      ],
+      "targets": [
+        "claude",
+        "keryx-shell"
+      ],
+      "dependencies": [
+        "react-skills"
+      ],
+      "defaultInstall": true,
+      "cost": "medium",
+      "stability": "experimental"
     }
   },
   "components": {
@@ -478,7 +701,9 @@
       "family": "capability",
       "modules": [
         "mobx-review-skill",
-        "mobx-store-template-rule"
+        "mobx-store-template-rule",
+        "mobx-rules",
+        "mobx-skills"
       ],
       "detectionMarkers": [
         "mobx"
@@ -491,7 +716,9 @@
       "family": "framework",
       "modules": [
         "nestjs-review-skill",
-        "nestjs-dto-rule"
+        "nestjs-dto-rule",
+        "nestjs-rules",
+        "nestjs-skills"
       ],
       "detectionMarkers": [
         "nestjs"
@@ -525,6 +752,46 @@
       "provenance": {
         "origin": "authored"
       }
+    },
+    "framework:vue": {
+      "family": "framework",
+      "modules": [
+        "vue-rules",
+        "vue-skills"
+      ],
+      "detectionMarkers": [
+        "vue"
+      ],
+      "provenance": {
+        "origin": "authored"
+      }
+    },
+    "framework:angular": {
+      "family": "framework",
+      "modules": [
+        "angular-rules",
+        "angular-skills"
+      ],
+      "detectionMarkers": [
+        "angular"
+      ],
+      "provenance": {
+        "origin": "authored"
+      }
+    },
+    "framework:nextjs-nuxt": {
+      "family": "framework",
+      "modules": [
+        "nextjs-nuxt-rules",
+        "nextjs-nuxt-skills"
+      ],
+      "detectionMarkers": [
+        "nextjs",
+        "nuxt"
+      ],
+      "provenance": {
+        "origin": "authored"
+      }
     }
   }
 }

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