@mrciphersmith/keryx 0.3.111 → 0.3.112

package/package.json

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

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

@@ -689,3 +689,42 @@ Use it to understand:
 - Architectural decisions already agreed upon, and acceptance criteria driving the Stage 1 spec compliance gate
 
 If absent, proceed normally — context is optional and non-blocking.
+
+## The mutation pass — `keryx review mutate`
+
+Attended, the pass is not optional once mutants were proposed. The testing reviewer writes
+each proposed mutant to `<review-dir>/research-evidence/mutants.json`:
+`{ "mutants": [{ "id", "file", "anchor", "replacement" }] }`. `anchor` is exact text that
+occurs once in `file`; `"runnable": false` at the top level says the suite cannot run here.
+
+Run `keryx review mutate --test "<the nearest suite command>" --package <review-dir>`. It
+applies each mutant in a scratch copy of the worktree (never in the worktree), refuses to
+start when the baseline is red, and writes the table to `research-evidence/mutation-<n>.md`
+and `.json`. A mutant is `killed` (the suite went red), `survived` (nothing pins that
+behaviour), `timeout`, or `invalid` (anchor missing or not unique, file outside the copy).
+A survivor is evidence for the finding that names it.
+
+`keryx review complete` refuses while proposed mutants are unrun, unless
+`dispatch.mutationWaiver = { operatorQuote, reason }` carries the operator's own words.
+`keryx review run --autonomous` is unchanged: it records `Not run: mutation pass` as before.
+
+### Severity audit — `keryx review severity-audit`
+
+A reviewer that argues a finding from a mutant writes `mutant:<id>` in the finding's `evidence`.
+After the mutation pass run `keryx review severity-audit --package <review-dir>`: a cited mutant
+that survived on a file the review changed raises a minor finding to major and records
+`severity_audit {from, to, evidence: "mutation-<n>.json#<id>"}`. A finding that cites a mutant no
+run executed stays minor (a major is capped at minor) and gets the label `unproven`. The audit
+never deletes a finding and never touches a blocker; it is a separate pass from the verifier,
+which can only delete. `--dry-run` prints the changes without writing `findings.json`.
+
+### Pull request context — `keryx review context-collect`
+
+A pull-request review starts with `keryx review context-collect --repo <o/r> --pr <n> --package <review-dir>`.
+It writes `pr-context.json` and `pr-context.md` into the package: every review comment in full (the
+800-character cut applies only to a finding's `problem`), the round-1 intent (kept when a later round
+collects a new head), the CI status (`--checks <file>` or `gh pr checks`; `unknown` when neither is
+available) and the backend pins the pull request names (refs on lines that talk about the backend).
+Set `pr_context` in every reviewer payload to the `.md` path; reviewers read it before the diff.
+`keryx review dispatch-check --payload <file> --pr-context` refuses a payload without it
+(`REVIEWER_INPUT_NO_PR_CONTEXT`).

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

@@ -1102,7 +1102,7 @@ whoever reads the merge commit a year later reads the body. When `review.jev.con
 
 **Dispatch integrity is a completion prerequisite.** Use one distinct execution per selected reviewer role; do not combine multiple roles in one child or count sections of one response as independent runs. When budgets are tight, use sequential waves, not role batching. Resolve every project-rule anchor before dispatch; missing rules require context recovery or a blocked result, never silently skipped checks. A read-only pass cannot discharge executable obligations: dispatch a capable execution pass and retain its evidence. Partial scope and NEEDS_CONTEXT remain incomplete until rerun over the outstanding scope.
 
-**The reviewer set is not yours to shrink.** Run `keryx review required --mode all|diff --scope <scope.json>` (`all` for `--all` or no narrowing flag; `diff` only when the operator named a narrower mode), dispatch every reviewer it prints, and declare `mode` in `dispatch`; pass the same `--scope` to `keryx review start|ingest` so the package keeps the file list. Closure refuses a smaller set unless `dispatch.override = { operatorQuote, reason }` carries the operator's own words. New managed packages declare `reviewerDispatch: "research.json"`. Alongside the research ledger, provide `dispatch: { version: 1, mode: "all"|"diff", selected: [...], unresolvedRules: [], runs: [...] }`. Preserve the actual computed reviewer inventory. Each run has `reviewer`, unique `executionId`, `status: "complete"`, `scopeComplete: true`, `rawEvidence`, nonempty `ruleEvidence`, and boolean `executionRequired`. Required execution needs nonempty `executionEvidence` (command/output references); a source-only scope requires `executionReason`. Do not fabricate IDs or mark truncated responses complete. Runtime validates these declarations at closure and the flow gate, not their truth: independently audit evidence and inventory before freezing. Legacy artifact absence is compatibility, not proof of a correct launch. Research closure is mandatory: see [Runtime research-completion ledger](SKILL.detail.md#runtime-research-completion-ledger).
+**The reviewer set is not yours to shrink.** Run `keryx review required --mode all|diff --scope <scope.json>` (`all` for a pull request, for `--all` and for no narrowing flag; `diff` only when the operator named a narrower mode — pass their words as `--operator-quote` and record them as `dispatch.operatorQuote`, without which the dispatch is refused), dispatch every reviewer it prints, and declare `mode` in `dispatch`; pass the same `--scope` to `keryx review start|ingest` so the package keeps the file list. Closure refuses a smaller set unless `dispatch.override = { operatorQuote, reason }` carries the operator's own words. New managed packages declare `reviewerDispatch: "research.json"`. Alongside the research ledger, provide `dispatch: { version: 1, mode: "all"|"diff", selected: [...], unresolvedRules: [], runs: [...] }`. Preserve the actual computed reviewer inventory. Each run has `reviewer`, unique `executionId`, `status: "complete"`, `scopeComplete: true`, `rawEvidence`, nonempty `ruleEvidence`, and boolean `executionRequired`. Required execution needs nonempty `executionEvidence` (command/output references); a source-only scope requires `executionReason`. Do not fabricate IDs or mark truncated responses complete. Runtime validates these declarations at closure and the flow gate, not their truth: independently audit evidence and inventory before freezing. Legacy artifact absence is compatibility, not proof of a correct launch. Research closure is mandatory: see [Runtime research-completion ledger](SKILL.detail.md#runtime-research-completion-ledger).
 
 Dispatch selected reviewers in parallel when independent — this engine dispatches them itself (see "How to spawn"); a host without a dispatch tool returns `STATUS: BLOCKED` (`nested_dispatch_unavailable`) and never reviews alone — Preflight 1. Waves follow the diff domains in "Control" and keep their dependency order:
 
@@ -1124,7 +1124,7 @@ finding class is unreachable for the entire round, and no amount of verification
 downstream recovers it. When a testing reviewer returns without a mutation table,
 treat it the way you would treat a reviewer that returned without findings *and*
 without evidence: ask once, then record that the pass did not run. Unattended: record
-`Not run: mutation pass` without asking.
+`Not run: mutation pass` without asking. Attended: run `keryx review mutate` ([The mutation pass](SKILL.detail.md#the-mutation-pass-keryx-review-mutate)).
 
 ### Wave C — verification, and what it replaced
 

package/src/gdskills/bundled/skills/review/review-orchestrator/reviewer-input.schema.json

@@ -160,6 +160,13 @@
         "null"
       ]
     },
+    "pr_context": {
+      "type": [
+        "string",
+        "null"
+      ],
+      "description": "Path of the `pr-context.md` that `keryx review context-collect` wrote into the review package: every review comment in full, the round-1 intent, the CI status and the backend pins the pull request names. Required of a pull-request review by `keryx review dispatch-check --pr-context <package>`; a reviewer reads it before the diff."
+    },
     "round": {
       "type": "integer",
       "minimum": 1,