@mrciphersmith/keryx 0.2.69 → 0.2.71

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

@@ -1,53 +1,206 @@
 ---
-description: "Model selection workflow for sub-agents. Detects available models and allows user to choose."
+description: "Adaptive model selection for sub-agent dispatches. Skills declare a tier; the tier is resolved against the models the active provider actually reports at runtime, without asking."
 alwaysApply: false
 ---
 
 # Model Selection for Sub-Agents
 
 ## Purpose
-When launching a sub-agent or skill, detect available models in the current environment and allow the user to choose.
 
-## Trigger
-When you need to launch a sub-agent/skill and want to use a different model than the current one.
+Match the model to the work. A reviewer scanning a twelve-line diff and a
+regression reviewer reasoning across a forty-file blast radius should not run on
+the same model: the cheap work pays flagship prices, and the hard work gets no
+more capability than the trivial.
 
-## Available Models Detection
+## Tiers, not model names
 
-Run to detect available models:
+A skill declares a **tier**. It never declares a model.
+
+A model name in a skill is wrong the day the provider changes and unusable for
+anyone on a different provider. There are three tiers:
+
+| Tier | For |
+|---|---|
+| `light` | mechanical, verifiable work — pre-filter, `class_scope` existence checks, comment collection, formatting a reply |
+| `standard` | ordinary reviewing and implementation — the default |
+| `deep` | genuinely hard reasoning — regression review across the blast radius, a strategy change after a failed loop, synthesis across many findings |
+
+Declared in SKILL.md frontmatter:
+
+```yaml
+---
+name: review-architecture
+model_tier: deep
+---
+```
+
+An undeclared skill runs at `standard`. A skill that writes a model name into
+`model_tier` fails the guard in `src/gdskills/model-tier.test.ts`.
+
+## Resolving a tier: discover, rank, fall back
+
+There is **no table of models** anywhere in the resolution, and there must not
+be. A fixed list of model ids is stale the day a provider ships anything, and it
+is wrong for every operator whose environment differs from the one it was written
+in. The candidate set is discovered at runtime.
+
+`src/commands/select.ts` already detects providers and every `DetectedProvider`
+carries `models: string[]`. That list — for the **session's own provider**, so a
+child never resolves onto a provider the parent holds no grant for — is the whole
+candidate set. `src/gdskills/model-tier.ts` then:
+
+1. **discovers** the candidates (passed in, never looked up: the module reads no
+   network, no filesystem, no environment);
+2. **ranks** them by size markers in their names — `MODEL_RANK_HINTS`;
+3. **places the tiers relative to the session's own model**:
+
+| 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 |
+
+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.
+
+## What the hints are, and what they are not
+
+Capability cannot be derived from a bare string — `haiku` is smaller than `opus`
+and nothing about the two strings says so. `MODEL_RANK_HINTS` is that irreducible
+residue, and it is kept in the smallest shape that works:
+
+- it names **size words** (`mini`, `lite`, `flash`, `haiku`, `pro`, `opus`,
+  `max`, `ultra`, …), never models, so it claims nothing about what exists and
+  cannot go stale;
+- it is applied to whatever detection reported, so an unfamiliar vendor is still
+  ranked if its names use those words;
+- a model matching **no** hint is *unranked*, which is not the same as ranked
+  zero — it is simply not placed;
+- it is one array, overridable per call.
+
+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.
+
+## Falling back
+
+Ranking is **refused**, and every tier keeps the session's provider and model,
+when:
+
+- nothing was discovered, or the session's provider is absent from the catalogue
+  (an external CLI runtime, or detection that has not run);
+- the provider reported no models;
+- the hints cannot place the **session's own** model — with no anchor, no
+  candidate can be called larger or smaller.
+
+A refusal **never** fails a dispatch and **never** causes a silent downgrade.
+Degrading capability because discovery failed is the worst of the three outcomes.
+
+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.
+
+## Where this actually runs
+
+Two places, and they are not the same shape:
+
+- **`spawn_subagent`** (`src/harness/tool/builtin/spawn-subagent-tool.ts`) takes an
+  optional `model_tier` input and does the rest 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.
+  Omitting `model_tier` inherits the parent's model, exactly as before the field
+  existed.
+- **An orchestrator authoring a dispatch document** *runs a command*:
+  `keryx review tier`. It takes the signals below as flags and prints the `model`
+  block ready to paste — the tier, the ordered rule ids that produced it, the
+  resolved provider/model, `tier_resolution` and `model_discovery`. `--json`
+  prints the block alone.
+
+That second bullet used to say the orchestrator "calls `decideDispatchModel`".
+An orchestrator is an agent following prose and **cannot call a TypeScript
+function**, so what actually happened was a model reading a table of signals and
+doing the arithmetic in its head — the exact mechanical work this programme moves
+out of skills and into the code that consumes them. `keryx review tier` is that
+code's entry point; `decideDispatchModel` is what it calls.
+
+Nothing reads a recorded resolution back and checks it. These fields explain a
+finished run; they do not gate one.
+
+## Choosing the tier
+
+The tier is **computed, not judged**. Run:
 
 ```bash
-.metaproject/scripts/detect-models.sh
+keryx review tier --scope blast-radius --findings 12 --diff-lines 340 \
+                  --verifier execution --fix-attempt 2 --security \
+                  --forced-strategy-change --json
 ```
 
-## Current Environment Models
+Every flag is a signal the orchestrator already holds before it dispatches: the
+round's scope, its own attempt counter, the diff it computed, the findings it is
+holding, the verification method it is about to ask for. None of them is a
+model's self-report — no model is ever asked to rate its own difficulty.
+
+The rules `assignTier` applies, in the order it applies them:
+
+| Signal | Flag | Effect |
+|---|---|---|
+| scope is `blast-radius` | `--scope blast-radius` | at least `deep` |
+| fix attempt >= 2 on the same finding | `--fix-attempt <n>` | raise one tier |
+| forced strategy change after the loop cap | `--forced-strategy-change` | `deep` |
+| finding count <= 3 **and** diff <= 50 lines | `--findings <n> --diff-lines <n>` | allow `light` |
+| verification method is `execution` or `site-check` | `--verifier <method>` | `light` — the evidence comes from running something, not from reasoning |
+| any security finding in scope | `--security` | never below `standard` |
+
+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.
 
-### Codex
-- `gpt-5.2-codex` - Frontier agentic coding model (recommended)
-- `gpt-5.3-codex` - Latest frontier agentic coding model
-- `gpt-5.1-codex-max` - Codex-optimized flagship for deep reasoning
-- `gpt-5.1-codex-mini` - Cheaper, faster, less capable
-- `gpt-5.2` - Latest frontier model
+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.
 
-### Cursor
-Uses OpenAI models (GPT-4, GPT-4o, etc.)
+## Recording the decision
 
-### Antigravity
-Check configuration in `~/.antigravity/`
+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
+`model.model_discovery` in
+`.metaproject/core/gdskills/contracts/subagent-dispatch.schema.json`.
 
-### OpenCode
-Check configuration in `~/.config/opencode/`
+`tier_resolution` distinguishes three facts that must not be flattened:
 
-### Zed
-Uses AI models configured in Zed settings
+| 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 |
 
-## Workflow
+"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
+what these fields exist to prevent. Record them on every dispatch that resolves
+a tier — `keryx review tier` prints all four together as one pasteable block, so
+recording them is one copy rather than four decisions.
 
-1. **Detect available models** - Run `detect-models.sh` or check known configurations
-2. **Present options** - Show user available models with descriptions
-3. **Get confirmation** - Ask user which model to use
-4. **Launch sub-agent** - Use selected model for the sub-agent
+## Mandatory behavior
 
-## Mandatory Behavior
-- Always ask user before changing model for sub-agents
-- Show model descriptions to help user decide
-- Default to current model unless user explicitly chooses otherwise
+- Declare a tier in the skill; resolve the model at dispatch time.
+- **Run `keryx review tier` — do not work the tier out by hand.** Assigning it
+  from the table above by reading is the mechanical step this rule exists to
+  remove.
+- **Do not ask the operator which model to use per dispatch.** Asking every time
+  is what made adaptive selection impossible.
+- Never write a concrete model name into a skill, a rule, a dispatch template, or
+  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.

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

@@ -29,6 +29,42 @@ Before creating or editing a skill, ask and confirm:
 
 `SKILL.md` is always required. Platform variants are optional — if absent, `keryx update` installs `SKILL.md` as fallback.
 
+## Frontmatter Fields (Agent Skills spec alignment)
+
+`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
+editing a skill:
+
+- **`version` lives in `metadata.version` only.** The spec has no top-level
+  `version` field — its own example nests it under `metadata`. Do not
+  reintroduce a top-level `version:` key; nothing in this codebase reads one.
+- **`compatibility` carries the spec's meaning, not ours.** The spec defines
+  `compatibility` as environment requirements written in prose (e.g. "Requires
+  git, docker, jq, and access to the internet"). Our machine-readable CSV of
+  supported harnesses (`cursor,codex,zed,opencode,claude`) lives instead at
+  `metadata.compatible_harnesses`. Do not put a harness CSV back into
+  `compatibility` — if a skill genuinely needs to declare environment
+  requirements, write them there as prose, per the spec.
+
+Two divergences are deliberate and stay — a later pass must not "fix" them
+back toward the spec:
+
+- **`triggers`** — a list of trigger phrases. Not in the spec, and absent from
+  every skill collection surveyed while building this convention; the spec's
+  only discovery mechanism is semantic matching on `description`. `triggers`
+  gives the router a cheap, deterministic first-pass match before falling back
+  to semantic matching. It is additive and costs nothing as long as
+  `description` stays self-sufficient on its own — never let `triggers` carry
+  meaning `description` lacks.
+- **Per-skill `input-contract.schema.json` / `output-contract.schema.json`**
+  (sibling files, not frontmatter keys) — genuinely unique to this codebase.
+  Nothing in the spec or any surveyed collection defines one, because the spec
+  assumes a single agent reading a single skill file. This project dispatches
+  typed payloads to subagent workers instead, which the spec does not attempt
+  to address.
+
 ## Global Sync Mapping
 - `SKILL.cursor.md` (or `SKILL.md`) → `~/.cursor/skills/<skill-name>/SKILL.md`
 - `SKILL.codex.md` (or `SKILL.md`) → `${CODEX_HOME:-~/.codex}/skills/<skill-name>/SKILL.md`

package/src/gdskills/bundled/rules/core/subagent-status-protocol.md

@@ -32,7 +32,11 @@ If the first line is not `STATUS: <STATUS>`, the orchestrator MUST treat the res
 
 ---
 
-## The Four Statuses
+## The Five Statuses
+
+Four of them are for **skill workers** — the subagents an orchestrator dispatches
+from `.metaproject/skills/`. The fifth, `FAILED`, belongs to a different worker
+family and is documented at the end of this section.
 
 ### `DONE`
 Task fully complete. All acceptance criteria met. Orchestrator can continue the pipeline.
@@ -66,6 +70,28 @@ Use when:
 - The task references files or components that don't exist and no context explains them
 - Acceptance criteria use terms not defined anywhere in the provided context
 
+### `FAILED` — harness child workers only
+
+**Do not emit `FAILED` as a skill worker.** A skill worker that cannot finish
+reports `BLOCKED`; `task-implementer` maps its own internal `failed` to
+`STATUS: BLOCKED` for exactly this reason.
+
+`FAILED` exists in `subagent-result.schema.json` because a **different** worker
+family uses it: external child processes launched through the harness. Their
+`STATUS:` line is parsed by `parseChildResult` in `src/harness/child/contract.ts`
+— which mirrors this enum as `CanonicalSubagentStatus` — and is wired into
+production at `src/harness/extension/execute.ts`. `spawn.test.ts` pins the
+behaviour it guarantees: a `FAILED` child disposition must reach the parent's
+gate as a *failed* completion, **never as a false `completed`**.
+
+So the enum has five values and this document previously described four, which
+made `FAILED` look unreachable. It is not. It is unreachable *from a skill
+worker*, and load-bearing for the child-process layer.
+
+Orchestrators dispatching skill workers may therefore treat a `FAILED` reply as
+a protocol violation and re-request. Orchestrators reading harness child results
+must handle it as a real terminal failure.
+
 ---
 
 ## Exact Response Formats

package/src/gdskills/bundled/skills/orchestration/code-verifier/SKILL.codex.md

@@ -10,8 +10,8 @@ metadata:
   author: "MrCipherSmith"
   version: "1.0.0"
   category: "verification"
+  compatible_harnesses: "cursor,codex,zed,opencode"
 license: "MIT"
-compatibility: "cursor,codex,zed,opencode"
 ---
 
 # Code Verifier

package/src/gdskills/bundled/skills/orchestration/code-verifier/SKILL.cursor.md

@@ -11,8 +11,8 @@ metadata:
   author: "MrCipherSmith"
   version: "1.0.0"
   category: "verification"
+  compatible_harnesses: "cursor,codex,zed,opencode"
 license: "MIT"
-compatibility: "cursor,codex,zed,opencode"
 ---
 
 # Code Verifier

package/src/gdskills/bundled/skills/orchestration/code-verifier/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: code-verifier
+model_tier: light
 description: "Use when running a full quality gate after implementation — lint, type-check, tests, and import validation. Mandatory step in job-orchestrator after task-implementer and after fix iterations. Use standalone when you need a structured verification report."
 triggers:
   - "Run verification"
@@ -13,8 +14,8 @@ metadata:
   version: "1.0.0"
   category: "verification"
   agent_worthy: true
+  compatible_harnesses: "cursor,codex,zed,opencode"
 license: "MIT"
-compatibility: "cursor,codex,zed,opencode"
 ---
 
 # Code Verifier

package/src/gdskills/bundled/skills/orchestration/code-verifier/SKILL.opencode.md

@@ -11,8 +11,8 @@ metadata:
   author: "MrCipherSmith"
   version: "1.0.0"
   category: "verification"
+  compatible_harnesses: "cursor,codex,zed,opencode"
 license: "MIT"
-compatibility: "cursor,codex,zed,opencode"
 ---
 
 # Code Verifier

package/src/gdskills/bundled/skills/orchestration/code-verifier/SKILL.zed.md

@@ -10,8 +10,8 @@ metadata:
   author: "MrCipherSmith"
   version: "1.0.0"
   category: "verification"
+  compatible_harnesses: "cursor,codex,zed,opencode"
 license: "MIT"
-compatibility: "cursor,codex,zed,opencode"
 ---
 
 # Code Verifier

package/src/gdskills/bundled/skills/orchestration/context-collector/SKILL.codex.md

@@ -13,8 +13,8 @@ metadata:
   author: "MrCipherSmith"
   version: "1.0.0"
   category: "context"
+  compatible_harnesses: "cursor,codex,zed,opencode"
 license: "MIT"
-compatibility: "cursor,codex,zed,opencode"
 ---
 
 # Context Collector

package/src/gdskills/bundled/skills/orchestration/context-collector/SKILL.cursor.md

@@ -13,8 +13,8 @@ metadata:
   author: "MrCipherSmith"
   version: "1.0.0"
   category: "context"
+  compatible_harnesses: "cursor,codex,zed,opencode"
 license: "MIT"
-compatibility: "cursor,codex,zed,opencode"
 ---
 
 # Context Collector

package/src/gdskills/bundled/skills/orchestration/context-collector/SKILL.md

@@ -14,8 +14,8 @@ metadata:
   version: "1.1.0"
   category: "context"
   agent_worthy: true
+  compatible_harnesses: "cursor,codex,zed,opencode"
 license: "MIT"
-compatibility: "cursor,codex,zed,opencode"
 ---
 
 <SUBAGENT-STOP>

package/src/gdskills/bundled/skills/orchestration/context-collector/SKILL.opencode.md

@@ -13,8 +13,8 @@ metadata:
   author: "MrCipherSmith"
   version: "1.0.0"
   category: "context"
+  compatible_harnesses: "cursor,codex,zed,opencode"
 license: "MIT"
-compatibility: "cursor,codex,zed,opencode"
 ---
 
 # Context Collector

package/src/gdskills/bundled/skills/orchestration/context-collector/SKILL.zed.md

@@ -13,8 +13,8 @@ metadata:
   author: "MrCipherSmith"
   version: "1.0.0"
   category: "context"
+  compatible_harnesses: "cursor,codex,zed,opencode"
 license: "MIT"
-compatibility: "cursor,codex,zed,opencode"
 ---
 
 # Context Collector

package/src/gdskills/bundled/skills/orchestration/feature-analyzer/SKILL.codex.md

@@ -13,8 +13,8 @@ metadata:
   author: "MrCipherSmith"
   version: "2.4.0"
   category: "analysis"
+  compatible_harnesses: "cursor,codex,zed,opencode"
 license: "MIT"
-compatibility: "cursor,codex,zed,opencode"
 ---
 
 # Feature Analyzer

package/src/gdskills/bundled/skills/orchestration/feature-analyzer/SKILL.cursor.md

@@ -13,8 +13,8 @@ metadata:
   author: "MrCipherSmith"
   version: "2.4.0"
   category: "analysis"
+  compatible_harnesses: "cursor,codex,zed,opencode"
 license: "MIT"
-compatibility: "cursor,codex,zed,opencode"
 ---
 
 # Feature Analyzer

package/src/gdskills/bundled/skills/orchestration/feature-analyzer/SKILL.md

@@ -13,8 +13,8 @@ metadata:
   author: "MrCipherSmith"
   version: "2.4.0"
   category: "analysis"
+  compatible_harnesses: "cursor,codex,zed,opencode"
 license: "MIT"
-compatibility: "cursor,codex,zed,opencode"
 ---
 
 <SUBAGENT-STOP>

package/src/gdskills/bundled/skills/orchestration/feature-analyzer/SKILL.opencode.md

@@ -13,8 +13,8 @@ metadata:
   author: "MrCipherSmith"
   version: "2.4.0"
   category: "analysis"
+  compatible_harnesses: "cursor,codex,zed,opencode"
 license: "MIT"
-compatibility: "cursor,codex,zed,opencode"
 ---
 
 # Feature Analyzer

package/src/gdskills/bundled/skills/orchestration/feature-analyzer/SKILL.zed.md

@@ -13,8 +13,8 @@ metadata:
   author: "MrCipherSmith"
   version: "2.4.0"
   category: "analysis"
+  compatible_harnesses: "cursor,codex,zed,opencode"
 license: "MIT"
-compatibility: "cursor,codex,zed,opencode"
 ---
 
 # Feature Analyzer

package/src/gdskills/bundled/skills/orchestration/feature-dev/SKILL.codex.md

@@ -11,8 +11,8 @@ metadata:
   author: "MrCipherSmith"
   version: "1.0.0"
   category: "workflow"
+  compatible_harnesses: "cursor,codex,zed,opencode,claude"
 license: "MIT"
-compatibility: "cursor,codex,zed,opencode,claude"
 ---
 
 # Feature Development (7-Phase)

package/src/gdskills/bundled/skills/orchestration/feature-dev/SKILL.cursor.md

@@ -11,8 +11,8 @@ metadata:
   author: "MrCipherSmith"
   version: "1.0.0"
   category: "workflow"
+  compatible_harnesses: "cursor,codex,zed,opencode,claude"
 license: "MIT"
-compatibility: "cursor,codex,zed,opencode,claude"
 ---
 
 # Feature Development (7-Phase)

package/src/gdskills/bundled/skills/orchestration/feature-dev/SKILL.md

@@ -11,8 +11,8 @@ metadata:
   author: "MrCipherSmith"
   version: "2.0.0"
   category: "workflow"
+  compatible_harnesses: "cursor,codex,zed,opencode,claude"
 license: "MIT"
-compatibility: "cursor,codex,zed,opencode,claude"
 ---
 
 <SUBAGENT-STOP>