@mrciphersmith/keryx 0.3.27 → 0.3.28

package/dist/core.js

@@ -9178,12 +9178,19 @@ var init_export = __esm(() => {
   SKILL_RUNTIMES = [...HARNESS_SKILL_RUNTIMES, "plugin"];
 });
 
+// src/gdskills/model-version.ts
+var TRAILING_ALIAS_WORDS;
+var init_model_version = __esm(() => {
+  TRAILING_ALIAS_WORDS = new Set(["latest", "preview"]);
+});
+
 // src/gdskills/model-tier.ts
 function isModelTier(value) {
   return typeof value === "string" && MODEL_TIERS.includes(value);
 }
 var MODEL_TIERS, TIER_ALIASES, SKILL_TIER_KEY = "model_tier", TIER_DECLARATION;
 var init_model_tier = __esm(() => {
+  init_model_version();
   MODEL_TIERS = ["light", "standard", "deep"];
   TIER_ALIASES = new Map([["cheap", "light"]]);
   TIER_DECLARATION = new RegExp(`^\\s*(?:[-*]\\s*)?"?(?:${SKILL_TIER_KEY}|model-tier|modelTier)"?\\s*[:=]\\s*(.+?)\\s*,?\\s*$`, "i");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrciphersmith/keryx",
-  "version": "0.3.27",
+  "version": "0.3.28",
   "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

@@ -57,13 +57,14 @@ candidate set. `src/gdskills/model-tier.ts` then:
 | Tier | Resolves to |
 |---|---|
 | `standard` | the session's model, always |
-| `deep` | the highest-ranked discovered model **strictly above** the session's, else the session's |
-| `light` | the lowest-ranked discovered model **strictly below** the session's, else the session's |
+| `deep` | the best discovered model **above** the session's — a larger size class, or a NEWER generation of the session model's own family — else the session's |
+| `light` | the **next size step below** the session's (an Opus-class session takes the Sonnet class, not the Haiku class), else the session's; the smallest class only when nothing sits between |
 
 Anchoring on the session model is what makes "never a downgrade" checkable
 rather than hoped for: a tier can only move away from the session model in the
 direction its own name points, and a candidate at the session's own rank is a
-lateral move and never taken.
+lateral move and never taken. An OLDER sibling of the session's own family is
+never `light` or `deep` either.
 
 ## What the hints are, and what they are not
 
@@ -83,13 +84,24 @@ 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.
+**Version is a second axis, not a size hint (flow 358).** `rankModelId` still
+never parses a version number out of an id: the size words order size CLASSES.
+Generation is ordered separately, and only within **the same family and
+vendor** — the id with its version tokens removed (`familyKey`) must match. A
+newer release outranks an older one of its own family, so a session on the
+older one resolves `deep` to the newer sibling, and a session on the newer one
+never resolves `light` or `deep` to the older. A version number is **never**
+compared across families: a higher number on one line says nothing about a
+different line.
+
+**A larger class of an older generation is ambiguous, not "above".** When the
+only discovered models above the session are a larger size class whose version is
+older than the session's, size words alone cannot call them stronger, and
+`deep` must not move onto a model that is older-generation and — by the
+profile price — the more expensive one. Without an agent the tier keeps the
+session's model as `session-fallback`, with the reason recorded (reason id
+`kept-older-generation`, or `kept-older-generation-pricier` when the profile
+price shows it costs more). The agent fallback below is the only other way out.
 
 The routing "derived default table" (`deriveDefaultTable`,
 `src/harness/routing/derive-default-table.ts`, flow 327/PRD §6.3) is that
@@ -102,8 +114,9 @@ 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.
+own separate, conservative version parse on top of it. Since flow 358 the tier
+resolution reads the same version parse (`src/gdskills/model-version.ts`, shared
+so neither module imports the other).
 
 That version parse (`parseModelVersion`/`familyKey`, round 2) reads BOTH a
 dotted id (`vendor-opus-5.5`, `gemini-3.8-flash`) and a real
@@ -152,6 +165,35 @@ Do not "fix" a fallback by adding model ids to the code. Add a size word to the
 hints if one genuinely applies, or leave it: running on the session's model is a
 correct answer.
 
+## The agent fallback: comparing candidate models, nothing else
+
+When the ranking is **refused** but the provider did report other models, or a
+tier is **ambiguous** (an older-generation larger class, above), an injected
+agent may be asked to put the candidate models in order. It is a port
+(`TierRankAgent`): `src/gdskills/model-tier.ts` holds no network and no
+filesystem, the caller supplies the real one, and a test supplies a fake.
+
+Its limits are the point:
+
+- **It compares candidate models and never rates a task's own difficulty.** It is
+  shown no task, no diff and no user text — only the discovered ids and the
+  profile prices — and it is asked one question: which of these models is more
+  capable than which. The tier is still computed by `assignTier` from signals
+  the orchestrator holds.
+- It must answer JSON, `{"order": [...]}`, best first, and must place the session's
+  own model. An id that was not discovered is dropped. An agent error, a
+  timeout, a malformed answer, or one that leaves out the session's model
+  resolves to the session's model, exactly as without an agent.
+- It never places `standard` or `deep` below the session: `deep` is only ever taken
+  from above the session in its order, `standard` is never asked. A larger
+  class of an older generation that costs more than the session's model is
+  refused whatever it says.
+- The result is cached by a hash of the candidate catalogue with prices, so an
+  identical catalogue asks once.
+- It runs on the **light** tier of the session's own provider — the cheap step
+  below the session, or the session model itself when nothing sits below.
+- A resolution it produced is recorded `tier_resolution: agent-ranked`.
+
 ## Where this actually runs
 
 Two places, and they are not the same shape:
@@ -236,8 +278,9 @@ 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
+A model is named only when discovery — or, failing that, the agent fallback —
+assigned one **other than** the session's (`tier_resolution: discovered` or
+`agent-ranked`). 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:
@@ -255,18 +298,19 @@ fallback. Exit status is always 0.
 ## Recording the decision
 
 The dispatch carries the tier, the ordered rule ids that produced it, which of
-the three outcomes occurred, and what was on the table when it did —
-`model.tier`, `model.tier_reasons`, `model.tier_resolution` and
+the outcomes occurred, and what was on the table when it did —
+`model.tier`, `model.tier_reasons` (the assignment rule ids, then `resolve:<reason id>` for the resolution), `model.tier_resolution` and
 `model.model_discovery` in
 `.metaproject/core/gdskills/contracts/subagent-dispatch.schema.json`.
 
-`tier_resolution` distinguishes three facts that must not be flattened:
+`tier_resolution` distinguishes four facts that must not be flattened:
 
 | Value | Means |
 |---|---|
 | `discovered` | a discovered model was assigned to this tier |
 | `session-ranked` | ranking worked and placed the tier at the session's model |
-| `session-fallback` | ranking was refused; the session's model is kept |
+| `session-fallback` | ranking was refused or was ambiguous; the session's model is kept |
+| `agent-ranked` | the agent fallback put the candidates in order and its answer was used |
 
 "Fell back to the session model" and "assigned the session model because it
 ranked there" are different facts. A run that cannot be explained afterwards is
@@ -286,6 +330,9 @@ 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.
+- The agent fallback compares candidate models. Never ask any model to rate a
+  task's own difficulty, and never let the fallback place `standard` or `deep`
+  below the session's model.
 - 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/review/review-orchestrator/reviewer-input.schema.json

@@ -79,7 +79,8 @@
           "enum": [
             "discovered",
             "session-ranked",
-            "session-fallback"
+            "session-fallback",
+            "agent-ranked"
           ]
         },
         "model_discovery": {

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

@@ -83,7 +83,7 @@
       }
     },
     "model": {
-      "description": "Which model runs this dispatch. Skills declare a `tier`; at dispatch time src/gdskills/model-tier.ts DISCOVERS the models runtime provider detection reported for the active provider, ranks them by size markers in their names, and places the tier relative to the session's own model — `standard` is the session model, `deep` a discovered model ranked above it, `light` one ranked below. No table of model ids exists anywhere in the resolution. When the candidates cannot be ranked, every tier keeps the session's model. `provider`/`model` remain available for an explicit lateral selection, and an omitted block inherits the parent verbatim. Two things fill this block. The interactive `spawn_subagent` tool does it in code: it builds the tier map with `buildTierMap` from its host's detection result, hands it to `resolveChildModel`, and records the outcome on the dispatch's run trace. An orchestrator authoring a dispatch document RUNS `keryx review tier`, which takes the §4.4 signals as flags and prints exactly the fields below, ready to paste (`--json` prints this object alone). It is a command rather than a documented function call because an orchestrator is an agent following prose and cannot call a TypeScript function: told to `decideDispatchModel`, it computed the tier in its head from a table, which is the mechanical step that belongs in code. When nothing can be worked out the command emits `inherit: true` instead of `provider`/`model` — the dispatch runs on the caller's own model, never a downgrade. Neither path is enforced by a reader — nothing validates a recorded resolution against the model that actually ran — so these fields are a record, not a gate.",
+      "description": "Which model runs this dispatch. Skills declare a `tier`; at dispatch time src/gdskills/model-tier.ts DISCOVERS the models runtime provider detection reported for the active provider, ranks them by size markers in their names, and places the tier relative to the session's own model — `standard` is the session model, `deep` a discovered model above it (a larger size class, or a newer generation of the session model's own family), `light` the next size step below it. When the ranking is refused or ambiguous an injected agent may order the candidate models instead (it compares models, never rates a task); its answer is recorded as `agent-ranked`. No table of model ids exists anywhere in the resolution. When the candidates cannot be ranked, every tier keeps the session's model. `provider`/`model` remain available for an explicit lateral selection, and an omitted block inherits the parent verbatim. Two things fill this block. The interactive `spawn_subagent` tool does it in code: it builds the tier map with `buildTierMap` from its host's detection result, hands it to `resolveChildModel`, and records the outcome on the dispatch's run trace. An orchestrator authoring a dispatch document RUNS `keryx review tier`, which takes the §4.4 signals as flags and prints exactly the fields below, ready to paste (`--json` prints this object alone). It is a command rather than a documented function call because an orchestrator is an agent following prose and cannot call a TypeScript function: told to `decideDispatchModel`, it computed the tier in its head from a table, which is the mechanical step that belongs in code. When nothing can be worked out the command emits `inherit: true` instead of `provider`/`model` — the dispatch runs on the caller's own model, never a downgrade. Neither path is enforced by a reader — nothing validates a recorded resolution against the model that actually ran — so these fields are a record, not a gate.",
       "type": "object",
       "additionalProperties": false,
       "properties": {
@@ -95,14 +95,14 @@
           "enum": ["light", "standard", "deep"]
         },
         "tier_reasons": {
-          "description": "The ordered rule ids `assignTier` applied, e.g. [\"base:standard\", \"floor:blast-radius\"]. Produced by `keryx review tier` from the signals passed as flags, never written by hand: a reason list an author composes records the story they tell about the tier rather than the rules that produced it. Recorded so a tier can be explained after the run instead of re-derived from a state nobody kept. Ids rather than prose, because they are compared across runs.",
+          "description": "The ordered rule ids `assignTier` applied, e.g. [\"base:standard\", \"floor:blast-radius\"], followed by one `resolve:<reason-id>` entry from the model resolution (e.g. `resolve:picked-above`, `resolve:kept-older-generation-pricier`, `resolve:agent-picked-below`). Produced by `keryx review tier` from the signals passed as flags, never written by hand: a reason list an author composes records the story they tell about the tier rather than the rules that produced it. Recorded so a tier can be explained after the run instead of re-derived from a state nobody kept. Ids rather than prose, because they are compared across runs.",
           "type": "array",
           "items": { "type": "string", "minLength": 1 }
         },
         "tier_resolution": {
-          "description": "Which of three outcomes produced the model, as `resolveTierModel` reports it on `TierResolution.source`. `discovered` — a model reported by runtime provider detection was assigned to this tier. `session-ranked` — ranking WORKED and placed the tier at the session's own model (always so for `standard`; for `light`/`deep` when nothing discovered ranks below/above the session). `session-fallback` — ranking was refused, or the ranking carried no rank for the session model, so the session's model is used because nothing could be worked out. Collapsing the last two would hide whether the environment was understood. Recorded, never read back: it explains a finished run and gates nothing.",
+          "description": "Which of four outcomes produced the model, as `resolveTierModel` reports it on `TierResolution.source`. `discovered` — a model reported by runtime provider detection was assigned to this tier. `session-ranked` — ranking WORKED and placed the tier at the session's own model (always so for `standard`; for `light`/`deep` when nothing discovered ranks below/above the session). `session-fallback` — ranking was refused or was ambiguous (a larger size class that is an older generation), or the ranking carried no rank for the session model, so the session's model is used because nothing could be worked out. `agent-ranked` — the ranking was refused or ambiguous and an injected agent, shown only the discovered ids and profile prices, put the candidate models in order and its validated answer picked the model; it compares models and never rates a task. Collapsing these would hide whether the environment was understood. Recorded, never read back: it explains a finished run and gates nothing.",
           "type": "string",
-          "enum": ["discovered", "session-ranked", "session-fallback"]
+          "enum": ["discovered", "session-ranked", "session-fallback", "agent-ranked"]
         },
         "model_discovery": {
           "description": "What was on the table when the tier was resolved: which models runtime detection reported for the active provider, how the size-marker hints ordered them, and — when ranking was refused — why. `tier_resolution` alone says a fallback happened and never says what it fell back FROM.",