@mrciphersmith/keryx 0.2.109 → 0.2.111

package/dist/core.js

@@ -23887,7 +23887,7 @@ async function createProjectSkill(projectRoot, options) {
         name: skillName,
         target: options.target,
         path: relativeSkillPath,
-        version: VERSION,
+        version: options.version ?? VERSION,
         status: "active",
         updatedAt: new Date().toISOString()
       });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrciphersmith/keryx",
-  "version": "0.2.109",
+  "version": "0.2.111",
   "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/rules/core/model-selection.mdc

@@ -155,17 +155,33 @@ The rules `assignTier` applies, in the order it applies them:
 Floors are applied after downgrades, so "at least `deep`" means at least: a
 blast-radius round over a twelve-line diff is still a blast-radius round.
 
-The session's provider/model come from the selection `keryx shell` persisted, and
-the candidate set from live provider detection. A caller that already holds
-either passes `--session-provider`/`--session-model` and `--catalog` instead of
-paying for the lookup. **There is no `--tier` flag, and there will not be**:
-accepting a hand-written tier would put the arithmetic straight back in the
-caller's head.
-
-When nothing can be worked out — no persisted session, an unrankable catalogue,
-an unrankable session model — the block says `inherit: true` and the dispatch
-runs on the **caller's own model**. Exit status is still 0: a fallback is an
-answer, not a failure.
+The session's provider/model come from the **caller**: `--session-provider`/
+`--session-model`, else `KERYX_SESSION_PROVIDER`/`KERYX_SESSION_MODEL` exported by
+the host (`keryx shell` exports its live session to every `shell_exec` command). The selection `keryx shell` persisted is read only with
+`--from-shell-config`: it is whatever `keryx shell` was last pointed at, not the
+session running the orchestrator, and as a silent default it pinned a `keryx
+shell` model into dispatches authored from Claude Code. The candidate set comes
+from live provider detection (`--catalog` to supply it). **There is no `--tier`
+flag, and there will not be**: accepting a hand-written tier would put the
+arithmetic straight back in the caller's head.
+
+## Adaptive: `inherit: true`
+
+A model is named only when discovery assigned one **other than** the session's
+(`tier_resolution: discovered`). In every other case — no session named, ranking
+refused, or the tier resolving to the session's own model — the block carries the
+tier and `inherit: true`, and the **host** resolves it against the models its own
+dispatch tool offers:
+
+| Tier | Host dispatches on |
+|---|---|
+| `standard` | its session model |
+| `deep` | its most capable model class, else the session model |
+| `light` | its lighter/faster model class, else the session model |
+
+This is how the tier reaches runtimes keryx cannot enumerate (a Claude Code
+`Agent`, a Codex subagent). `light` there is the tier the signals assigned, not a
+fallback. Exit status is always 0.
 
 ## Recording the decision
 
@@ -201,5 +217,6 @@ recording them is one copy rather than four decisions.
   the resolution code.
 - Take the candidate set from runtime detection. Never from a literal list of
   what exists.
-- When the candidates cannot be ranked, keep the session model. Never substitute
-  a cheaper one.
+- When the candidates cannot be ranked, the block is adaptive (`inherit: true`).
+  The host never goes below its session model for `standard` or `deep`, and takes
+  a lighter class only for a `light` tier.

package/src/gdskills/bundled/skills/orchestration/job-orchestrator/SKILL.md

@@ -1349,7 +1349,7 @@ FOR iteration in [1, 2, 3]:
 
 AFTER THE LAST ROUND ONLY — answer every inbound PR comment, once:
   keryx review comments reply --repo <owner/repo> --pr <n> --outcomes <file> \
-                             --sha <head-sha> --final [--flow-link <url>]
+                             --review <review-id> --sha <head-sha> --final [--flow-link <url>]
 
 IF still NEEDS_FIX after max iterations, or the stuck check broke the loop:
   Log "Unresolved after <N> iterations" with finding list, and say WHICH of the

package/src/gdskills/bundled/skills/orchestration/job-orchestrator/orchestrator-prompt.md

@@ -189,7 +189,7 @@ If `blocker` or `major` findings exist:
 
 After the LAST round only:
 ```bash
-keryx review comments reply --repo <owner/repo> --pr <n> --outcomes <file> --sha <sha> --final
+keryx review comments reply --repo <owner/repo> --pr <n> --outcomes <file> --review <review-id> --sha <sha> --final
 ```
 
 ### Step: REPORT — Generate Final Report

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

@@ -0,0 +1,45 @@
+# Review Orchestrator — detail
+
+Overflow reference for `review/review-orchestrator`, linked from its SKILL.md.
+Read the section SKILL.md points you to; nothing here overrides SKILL.md.
+
+## Project-local reviewers
+
+`keryx review reviewers --json` returns every project-skill under module
+`review`. The routing tables in SKILL.md cannot name a project reviewer's
+triggers, so each `project` entry carries its own. Use them; do not re-derive
+them from the reviewer's prose.
+
+### Selecting project reviewers — the same two filters, from the inventory
+
+| Field | Use |
+|---|---|
+| `flags` | A flag the user passed that is in this list selects the reviewer **explicitly** — it is then never path-gated, like any flag-selected reviewer. `--all` selects every project reviewer. |
+| `paths` | Its path triggers for the **path gate**. No file in scope A matches → `Skipped reviewers`, reason `no-matching-paths`. |
+| `pathsSource` | `metadata` (declared `metadata.paths`) or `description` (globs read out of its description). `none` means there is nothing to gate on: **dispatch it** — ambiguity includes. |
+| `stackRequires` | Apply stack scoping exactly as for a bundled reviewer carrying `metadata.stack_requires`. |
+| `unresolvedRules` | Rules it cites that the project does not have. Dispatch it anyway, tell it in the prompt which rules are absent, and name them once in the report with the fix (`keryx review import --from <overlay>` copies them). Never a finding against the code. |
+
+A description saying another entry point dispatches it ("Dispatched by
+vantage-review …") is its author's routing note, not a restriction: this
+orchestrator dispatches it through the fields above.
+
+### `drift` — the source moved, the reviewer did not
+
+A project reviewer built from an external file — a rules file, a review profile,
+a conventions doc — records where it came from and the hash of that file at
+import. `keryx review reviewers` re-reads the source and reports:
+
+| `drift` | Meaning | What to do this round |
+|---|---|---|
+| `none` | No external source; written here | Nothing |
+| `clean` | Source matches the import | Nothing |
+| `changed` | Source has moved on since import | Dispatch it, and say so in the report |
+| `missing` | Source can no longer be read | Dispatch it, and say so in the report |
+
+**A drifted reviewer still runs.** It is a reviewer built from an older version
+of its source, which is a fact about provenance, not a defect in its findings —
+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.

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

@@ -46,7 +46,7 @@ Review Orchestrator Progress:
 - [ ] Step 11: Sort by severity, deduplicate, emit unified report
 - [ ] Step 12: Emit the machine-readable `keryx:findings` block alongside the report
 - [ ] Step 13: Report the stage counts: dropped by pre-filter, refuted by the verifier, retained
-- [ ] Step 14: AFTER THE FINAL ROUND ONLY — answer every external comment once, `keryx review comments reply --final` — never against a pull request the dispatch named as the caller's
+- [ ] Step 14: MANAGED rounds only (NEVER in `lightweight`, which is report-only), AFTER THE FINAL ROUND, on an OPEN pull request at the head you reviewed — answer every external comment once, `keryx review comments reply --final` — never against a pull request the dispatch named as the caller's
 ```
 
 Step 0 runs on **every** round. Step 14 runs **once**, after the last one. They are
@@ -66,12 +66,12 @@ Working it out in your head is exactly the mechanical step that rule moves into
 code — and it is the step that was documented as running for a whole release
 while nothing called it.
 
-The command names no model. It ranks whatever your provider reports at runtime
-and places the tiers relative to your own model; when ranking fails it still
-names the session's own provider and model as a fallback. Only when the session
-itself has no provider/model to name does it print `inherit: true` and exit 0,
-which means the dispatch runs on the session model. That is a correct answer,
-not a failure — never "fix" it by writing a model id into a dispatch.
+It names a model only if you gave it your session (`--session-provider`/
+`--session-model` or `KERYX_SESSION_*`) and discovery found another. Otherwise it prints
+`inherit: true` with the tier — **adaptive**: pick your own runtime's model for
+that tier (`standard` = your session model; `light`/`deep` = your runtime's
+lighter/most capable class if its dispatch tool offers one, else the session
+model). Never "fix" it by writing a model id into a dispatch.
 
 ---
 
@@ -236,7 +236,7 @@ what happened", and it is the single reason the precision figure cannot be read.
 
 Managed modes:
 
-- `lightweight`: report-only; no flow or managed review artifacts are created.
+- `lightweight`: report-only; no flow or managed review artifacts are created, and nothing is posted — no `comments reply`.
 - `attach-review`: write under
   `.metaproject/flows/<flow-dir>/reviews/<review-id>/`.
 - `review-flow`: write under `.metaproject/reviews/<review-id>/`.
@@ -274,7 +274,7 @@ here.
 keryx review comments collect --repo <owner/repo> --pr <n> --sha <head-sha>
                               [--self <login>] [--round <n>] [--out <findings.json>] [--json]
 keryx review comments reply   --repo <owner/repo> --pr <n> --outcomes <file|->
-                              --sha <head-sha> --final [--dry-run]
+                              --review <review-id> --sha <head-sha> --final [--dry-run]
                               [--max-replies <n>] [--max-sentences <n>] [--max-chars <n>]
                               [--flow-link <url>]
 ```
@@ -283,12 +283,11 @@ Add `--fixtures <dir>` to either to run the whole loop against JSON on disk —
 no token, no network, nothing posted. Use it to see what a reply pass would say
 before it says it.
 
-`--sha` is the commit you collected against, and it is required. The completion
-gate compares it to the pull request's head: a collection that ran before the
-comments arrived is **stale**, and a gate that could not tell the difference
-would pass a flow with unanswered reviewers on it while printing
-`0 outstanding`. A record with no SHA reads as "cannot be shown current", never
-as "fresh".
+`--sha` is the pull request's **current head**, and it is required. `collect`
+prints the PR's state and head and warns when they disagree; `reply` **refuses** a
+closed or merged PR (`--allow-closed-pr` overrides), an unreadable one, and a `--sha`
+that is not its head. The completion gate compares the recorded SHA as well; a
+record with no SHA reads as "cannot be shown current", never as "fresh".
 
 ### What collection does, so you do not do it by hand
 
@@ -650,7 +649,7 @@ whether it is computed:
 
 Rules:
 - Never write a model id into a dispatch by hand — paste the `model` block `keryx review tier` printed.
-- When the session has no provider/model to name it prints `inherit: true` and exits 0; that means the dispatch runs on the session model. Record that as `model_assignment: unsupported`, not as a failure.
+- `inherit: true` is the adaptive answer: dispatch on your runtime's model for the block's `tier` (Step 6). Record `model_assignment: adaptive` and the model you actually chose — not a failure.
 - With `model_strategy: ask`, present the model plan once before dispatch, then proceed with the computed model.
 
 ---
@@ -1035,25 +1034,14 @@ Two things it does NOT get:
 - **No self-verification.** The never-self-verify rule is about the actor, not
   the origin.
 
-#### `drift` — the source moved, the reviewer did not
-
-A project reviewer built from an external file — a rules file, a review profile,
-a conventions doc — records where it came from and the hash of that file at
-import. `keryx review reviewers` re-reads the source and reports:
-
-| `drift` | Meaning | What to do this round |
-|---|---|---|
-| `none` | No external source; written here | Nothing |
-| `clean` | Source matches the import | Nothing |
-| `changed` | Source has moved on since import | Dispatch it, and say so in the report |
-| `missing` | Source can no longer be read | Dispatch it, and say so in the report |
-
-**A drifted reviewer still runs.** It is a reviewer built from an older version
-of its source, which is a fact about provenance, not a defect in its findings —
-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.
+**Select them with the fields the inventory returns, not by reading prose.**
+Each `project` entry carries `flags` (a passed flag selects it explicitly),
+`paths` + `pathsSource` (the path gate; `none` → dispatch), `stackRequires`
+(stack scoping), `unresolvedRules` (dispatch, name the missing rules once in the
+report) and `drift` (dispatch, name it once in the report). What each means and
+what to do with it: `SKILL.detail.md` beside this file, section "Project-local
+reviewers". A description saying another entry point dispatches it is its
+author's routing note, not a restriction.
 
 ### Convention Reviewer Confirmation
 
@@ -1545,15 +1533,15 @@ Severity ordering for sort: `blocker` > `major` > `minor` > `info`.
 
 ### Model Metadata Rules
 
-`unsupported` is a model-assignment outcome recorded when `keryx review tier` has no session provider/model to name (it prints `inherit: true`), not a model name. Never render it as `model: unsupported` or as the PR comment `Model` value.
+`adaptive` is a model-assignment outcome recorded when `keryx review tier` printed `inherit: true` and the host picked the model for the tier, not a model name. Never render it as `model: adaptive` or as the PR comment `Model` value.
 
 When writing review report metadata or a PR comment:
 1. Read `review_context.token_policy.model_plan`.
 2. Set `Model strategy` from `model_plan.strategy` (`ask` or `adaptive`).
 3. Set `Current model` from the first available value: `model_plan.current_model`, detected tool output, current runtime model shown by the platform, or `unknown`.
 4. Record the model actually assigned per reviewer — the `tier` and (`provider`+`model` or `inherit`) from the `model` block `keryx review tier` printed for that dispatch — rather than a fixed set of classes; include `complex_model`, `normal_model`, and `simple_model` too when `model_plan` reports them.
-5. If model assignment is unsupported (the dispatch's `model` block carried `inherit: true`), write `Model assignment: unsupported` and still write `Current model: <actual model or unknown>`.
-6. If the actual model is unknown, write `unknown`; do not substitute `unsupported` or `inherit`.
+5. If the dispatch's `model` block carried `inherit: true`, write `Model assignment: adaptive` and the model the host actually dispatched on for that tier (or `unknown`).
+6. If the actual model is unknown, write `unknown`; do not substitute `adaptive` or `inherit`.
 
 ---
 

package/src/gdskills/bundled/skills/review/review-pr-feedback/SKILL.md

@@ -65,7 +65,7 @@ review-pr-feedback Progress:
 - [ ] Step 7: Explain each comment and name the concrete fix
 - [ ] Step 8: Build the fix plan — one item per class, ordered, each with an acceptance criterion
 - [ ] Step 9: --fix only — confirm, then dispatch `flow-orchestrator` with the plan as frozen AC
-- [ ] Step 10: --fix only — after the merge, answer every comment once: `keryx review comments reply --final`
+- [ ] Step 10: --fix only — after the FIX merges into the reviewed PR's branch (the reviewed PR itself still OPEN, at its new head), answer every comment once: `keryx review comments reply --final --result <file>`
 - [ ] Step 11: Learning proposal for configured authors — propose, never apply
 ```
 

package/src/gdskills/contracts/subagent-dispatch.schema.json

@@ -143,7 +143,7 @@
           }
         },
         "inherit": {
-          "description": "Run this dispatch on the caller's own model. `keryx review tier` writes it — in place of `provider`/`model`, never alongside them — when the environment could not be worked out: no persisted session selection, an unrankable catalogue, or an unrankable session model. It is the recorded form of \"never a downgrade\": the alternative is an empty `provider`/`model` pair, which is schema-invalid and still reads like an answer. A `tier` and `tier_reasons` may accompany it, because the tier was assigned from signals even when no model could be named for it.",
+          "description": "Adaptive: the host picks the model. `keryx review tier` writes it — in place of `provider`/`model`, never alongside them — whenever it does not name a model other than the session's: no session was named by the caller (flags or KERYX_SESSION_PROVIDER/KERYX_SESSION_MODEL), the catalogue or the session model could not be ranked, or the tier resolved to the session's own model. The host resolves the accompanying `tier` against the models its own dispatch tool offers: `standard` on its session model, `deep` on its most capable class, `light` on its lighter class — each falling back to the session model when the host offers no choice. The alternative, an empty or stale `provider`/`model` pair, is schema-invalid or pins a model the runner may not have.",
           "type": "boolean"
         }
       }