mure-role-variant-matrix

MURE Role × Model Variant Matrix

Purpose

One MURE role, several model variants — each variant tuned to a specific model's profile (tools / thinking / max_tokens / system sections) without changing the role's core function. Lets the orchestrator pick the right model for the right job while staying inside the role's contract.

Schema

The authoritative source is .openclaw/mure-agent-catalog.json — every role entry and its variants: list lives there. .openclaw/agents/ is a catalog-generated projection for OpenClaw-native config consumption. Repo-local .omp/agents/ is a deterministic generated projection for OMP discovery, never hand-edited. Each variant:

variants:
  - id: "<role>-sonnet5"
    model: anthropic/claude-sonnet-5
    thinkingLevel: medium
    tools: [read, grep, glob, edit, write, bash]
    max_tokens: 16384
    systemSections: ["coding-excellence", "agentic-clean-tool-use"]
    eligibilityFlags: ["default-prime"]
    costTier: medium

  - id: "<role>-opus48"
    model: anthropic/claude-opus-4-8
    thinkingLevel: high
    tools: [read, grep, glob, edit, write, bash]
    max_tokens: 32768
    systemSections: ["apex-judgment", "narrow-prompt-reserved"]
    eligibilityFlags: ["heavy", "require-explicit-call"]
    costTier: heavy

  - id: "<role>-haiku"
    model: anthropic/claude-haiku-4-5
    thinkingLevel: low
    tools: [read, grep, glob]
    max_tokens: 4096
    systemSections: ["minimalist"]
    eligibilityFlags: ["cheap", "auto-eligible", "recon-eligible", "cheap-research-only"]
    costTier: cheap

The role's top-level model:, thinkingLevel:, tools: fields remain for backwards compatibility and act as the role baseline; variants[] overrides take precedence when populated.

Backwards compatibility

If variants is absent, MURE falls back to the legacy single-binding (model: + thinkingLevel: + tools:). Existing single-model roles keep working without modification.

Variant frontmatter (schema preservation)

A variant's ID, model binding, thinking level, tools, and token budget are core control fields — these appear in variant frontmatter (id, model, thinkingLevel, tools, max_tokens, systemSections, eligibilityFlags, costTier, quota). The role's top-level description is preserved across all variants; it captures the role's invariant mission and appears inherited in each variant. The explanatory tuning note — why this variant exists, what model behavior it optimizes for, how it differs from the base role — lives in body documentation, not in frontmatter. Never rewrite a role's description to document a single variant's tuning; that belongs in the body and the variant's field choices.

Per-variant fields (full set)

Field	Type	Required	Notes
id	string	yes	unique within the role; <role>-<model-shortname> convention
model	string	yes	exact provider/model string
thinkingLevel	enum	yes	off / low / medium / high / xhigh (model-specific meaning). max is not an OpenClaw value.
tools	string[]	yes	subset of the role's allowed tools
max_tokens	int	yes	maximum output tokens for this variant
systemSections	string[]	yes	which role-body sections apply to this variant
eligibilityFlags	string[]	no	cheap, default-prime, medium, heavy, require-explicit-call, security-only, auto-eligible, recon-eligible, cheap-research-only, etc.
costTier	enum	yes	cheap / medium / heavy / apex — used by selector
quota	enum	no	subscription-quota binding (e.g. claude-pro-x5, z-ai-coding-plan, minimax-ultra, direct-deepseek-capped)

reasoningDefault is not a second effort field in OpenClaw. It controls reasoning visibility (on / off / stream); effort belongs in thinkingLevel and projects to agents.list[].thinkingDefault.

Projections

OpenClaw native

The catalog is the role × variant authority; OpenClaw supplies execution primitives:

• agents.list[] projects stable role identities and their baseline model/fallbacks.
• sessions_spawn({agentId, model, thinking}) selects a configured role and an explicit variant model for one run.
• subagents.allowAgents controls which configured role identities can be targeted.
• Each target agentId resolves auth from its own agentDir; static API-key/token profiles may be seeded, but OAuth refresh credentials must not be copied between role stores. OpenAI OAuth model overrides run under the authenticated Yuri agent scope unless that target role has completed its own OAuth login.
• OpenClaw-specific: nested variants[] are routing metadata, not automatically separate native agents. Do not multiply OpenClaw dashboard agents merely to represent every model binding. OpenClaw is one projection surface, not the only runtime.

OMP projection

OMP projects each variant to an explicit agent card. .omp/agents/ is generated deterministically from the catalog — every catalog variant produces a projected OMP agent card for discovery. This is the opposite of the OpenClaw model: OMP variants ARE separate agent cards because OMP's dispatch model requires one-card-per-binding. Being projected is not the same as being executable; only canary-proven cards with passing latest canary are dispatch-eligible (see Provider route eligibility below). Never edit .omp/agents/ by hand; regenerate from the catalog on seed.

MURE task/session-level sparse expert routing remains catalog-driven. It does not turn any runtime into a token-level neural MoE. Candidate scoring, policy gates, quota features, calibration, and the MLP remain MURE logic; the runtime performs the selected dispatch and lifecycle management.

Provider route eligibility

The MURE agent catalog is the sole authority for role-variant bindings. Catalog presence alone is insufficient for dispatch eligibility. Every variant's model binding must satisfy both conditions:

1. Admission history: Resolvable to a canary-proven entry in _SYSTEM/config/provider-route-registry.json.
2. Live gate: The variant's latest canary must have passed; no later failed canary exists. A failed canary (quota exhaustion, provider drift, API change) blocks that route immediately until re-canary succeeds.

Acceptable evidence is exactly one of:

• Exact source-route match (e.g. zai/glm-5.2) in the registry with canary-proven status and passing latest canary.
• Normalized selector match (provider-scoped shorthand like minimax-code → minimax-code/MiniMax-M3) backed by canary-proven registry evidence and passing latest canary.

Missing admission history OR latest canary failure → route fails closed.

Routes with blocked-schema, unresolved, or owner-excluded status are known disqualifications — they fail closed regardless of catalog or model-list appearance.

Discoverability vs. executability

All catalog cards are projected — every variant and role binding appears in generated .omp/agents/ for discovery. But being projected is not the same as being executable. Unproven, blocked, and excluded cards are listed in the generated project config's task.disabledAgents and must never inherit the parent or default model binding. Only cards meeting Provider route eligibility criteria (canary-proven admission history and passing latest canary) are dispatch-eligible.

Card-level stale-session backstop

task.disabledAgents is the primary steady-state gate after session startup. disabled/mure-route-unavailable is the card-level stale-session backstop that blocks parent/default model inheritance. Project-config changes require a fresh OMP session — there is no hot reload; do not rely on settings-layer enforcement until the session has restarted.

The MLP and fallback chain skip ineligible variants automatically.

Provider status and pilot rollout

Sol (openai/gpt-5.6-sol) is catalogued but currently unproven — no successful exact OMP canary exists. It was Yuri's experimental variant and carried sol-pilot flag; later hardening tasks targeted different routes. Sol remains blocked until a fresh canary succeeds and meets dispatch eligibility criteria.

Terra (openai/gpt-5.6-terra) is a normalization example only. Currently quota-blocked after provider drift; routes configured for Terra dispatch will fail closed. Terra re-proves only when liveness is confirmed by passing canary.

Fallback defaults are seeded from routes with canary-proven admission history, subject to dispatch eligibility criteria (see Provider route eligibility), depending on role and cost tier. No role is currently promoted to Sol or Terra dispatch until their latest canaries pass.

Cost tier semantics (binding)

Each costTier maps to an explicit placement rule:

• cheap — eligible for auto-selection on cheap sub-tasks. Fallback chain advance lands here first. Examples: haiku, deepseek-v4-flash, glm-5-turbo, m2.7-highspeed.
• medium — eligible for auto-prime or surfaced-default depending on role. Examples: sonnet-5, glm-5.1, m2.7.
• heavy — surfaced-default with operator override. Examples: opus-4-8, dvp-pro-think-max, glm-5.2, m3.
• apex — require-explicit-call only; not auto-prime. Examples: fable-5 (when accessible).

Haiku's lane (clarification, 2026-07-09)

Per owner: Haiku's role is recon + cheap-research only. Eligible contexts for Haiku variants:

• mure-scout (research / census)
• mure-envoy (ops / brain-dump decode)
• mure-chronicler cheap-tier (technical writing where fine-tuning not needed)
• mure-advisor watcher Tier 1 fallback

NOT eligible for heavy-advisor fallback. NOT eligible for sentinel / adjudicator / architect. The heavy-tier fallback chain for any role is role-dependent but never falls through to Haiku.

System sections (harness diff)

The role body's section names are indexed and referencable per-variant. Convention (composable, reusable):

• minimalist — bare essentials; for cheap / fast models
• coding-excellence — code-quality emphasis (type hints, tests, edge cases)
• agentic-clean-tool-use — strict tool-call discipline (no spurious calls, return clean JSON)
• apex-judgment — adversarial-ally contract, weight caveats, refutation default
• narrow-prompt-reserved — short context, narrow scope; used by heavy-tiers when scope is bounded
• security-strict — protected-path emphasis, no exceptions; used by sentinel / adjudicator
• vision-cross-modal — instructions for image / video understanding
• recon-breadth — read-heavy, scan-friendly; used by cheap recon roles
• cheap-research — minimal-but-complete; used by cheap research-tier
• orchestrator-peer — full fleet doctrine + dispatch rules + 6-gate charter; used by helmsman / architect / helmsman-glm
• governance-strict — protected paths + autonomy-class + finalize-never; used by owner-gated lanes

A variant's systemSections chooses which named sections apply. The role body must explicitly mark each section heading so a tool can extract + concat.

Seeding (must be deterministic cold-start)

Variants MUST seed from the model-audit relevance cells:

• ★ = PRIMARY — eligible for auto-selection as the default-prime variant.
• ● = SECONDARY — eligible for surfaced-default with manual override; not auto-prime.
• — = DO NOT INCLUDE — model is unfit for the role; do not add as a variant.
• ? = UNVERIFIED — verification needed before inclusion.

The MLP cannot introduce NEW variants. Its job is to re-rank within the seeded set using prediction-ledger features.

This prevents the MLP from cold-pruning out a great model the owner invested quota in.

Selection (cheap auto + heavy surfaced)

Cheap variants (costTier: cheap / medium)

AUTO. The dispatcher picks the cheapest reachable variant matching the role + task shape, with predicted-success from the MLP. Operator-visible via the GUI afterwards + override-next-round via slash command (/use sonnet-5 next).

Heavy variants (costTier: heavy / apex)

Surfaced-default + operator override. The dispatcher proposes a default (ranked #1 by MLP score); the operator sees the choice in the GUI + can override next round. Per-dispatch prompts are NOT used (would wear thin over a long session).

Security rule (hard)

For security-relevant turns (sentinel, adjudicator, parts of architect), the variant picked MUST be Opus 4.8 (or equivalent apex-tier if Opus is gated). The dispatcher enforces; deepseek-v4-pro may be added when audit confirms capability parity.

Harness diff (binding rule)

A variant's diff from the role baseline MAY include:

• model (binding)
• thinkingLevel
• tools (subset)
• max_tokens
• systemSections (which sections apply)
• quota (which subscription)

A variant MUST NOT change:

• Role mission / description / capabilities
• Role autonomy class (self-governable / owner-gated)
• Role independence set (structural independence between roles)
• The RESULT_LABEL grammar at turn-end

If a role's function needs to change, that's a NEW role — not a variant.

Telemetry (feeds back into MLP)

Per-dispatch logs to _SYSTEM/state/role-variant-ledger.jsonl:

• role ID
• variant ID picked
• selection mechanism (auto / surfaced-default / override)
• tokens in / out (precise, for cost accounting)
• success criterion outcome (success / partial / fail, from role's RESULT_LABEL)
• time-to-first-token (latency)
• escalation count if heavy advisor was triggered

Feeds:

• mure-calibrator for Brier scoring
• Role-variant MLP for re-ranking within the seeded set
• Operator dashboard for cost / latency dashboards

Fallback chain

Per role, an ordered fallback chain: cheapest eligible variant first; on quota / failure, advance. MLP learns the chain ordering over time.

Static defaults at first, MLP-updated post-warmup (role-dependent but never includes Haiku at heavy tier):

1. costTier cheap variants (auto-prime if eligible)
2. medium costTier (auto-prime)
3. heavy costTier (surface default)
4. apex costTier (explicit-call only)

Haiku placement reminder: cheap tier (recon + cheap-research lanes only). At heavy tier, the chain is role-defined but never includes Haiku.

Operator command surface

• mure.mjs --list — every role + every variant + current ranking + last 24h outcome histogram.
• mure.mjs --variants <role> — role + variants + current ranking + per-tier cost.
• mure.mjs --pick <role> <variant> — next-round override for the role.
• mure.mjs --seed-from-audit — re-seed the variants[] from current _SYSTEM/research/model-audit*.md cells (manual / scheduled).
• GUI equivalent for visibility + intervention.

Anti-patterns

• A variant that CHANGES the role's mission (that's a new role).
• The MLP pruning outside its seeded set (cold-prune of expensive-but-critical).
• Operator getting prompted per heavy-dispatch (chatter burns focus).
• Variants without telemetry (silent untested variants rot the routing).
• Variants missing max_tokens (silently expensive / short on long outputs).
• Haiku appearing in a heavy-tier role's fallback chain.
• Adding a variant from an audit — cell without a verification pass.

Related

• Source audit: _SYSTEM/research/model-audit-2026-07-09.md (★/● cells are seed source).
• Rene recon: _SYSTEM/research/rene-branch-patterns-2026-07-09.md (compose-with-MURE-YAML recommendation).
• mure-advisor (the tiered per-turn advisor consumes role×variant telemetry + emits watchdog notes).
• Cloud fleet roster: _SYSTEM/config/cloud-fleet-models.json (provider mapping; needs an update pass).
• Substrate dispatch: _SYSTEM/Scripts/{glm,ollama}-fleet.mjs + Opus fleet substrate.

Versioned authority

v1.0.0 — created 2026-07-09. Revision incorporated: Haiku lane clarification. Pending Skill Workshop approval.

Change log

• 2026-07-09 — initial draft per grill round + Opus 4.8 adversarial review (HV03).
• 2026-07-09 (rev 1) — clarified Haiku's lane (recon + cheap-research only, never heavy-tier fallback); added recon-eligible, cheap-research-only, orchestrator-peer, governance-strict to the systemSections vocabulary.