feat(model-roles): add a per-role model map to CE config

.compound-engineering/config.example.yaml

@@ -58,6 +58,52 @@
 # brainstorm_output: html        # md | html (default: md)
 # ideate_output: md              # md | html (default: html -- ideation docs are human-facing, so HTML is the default; set md to opt out)
 
+# --- Model roles ---
+# One map that names the model, and optionally the reasoning effort, that
+# produces each pipeline step's deliverable. An entry governs that deliverable
+# and nothing else. Dialogue with you, orchestration inside the skill, and
+# lfg's hand-offs between steps stay on your session model. The map applies the
+# same way whether you run the skill or lfg does. A role with no entry behaves
+# exactly as it does without this map.
+#
+# An entry is `<model> [<effort>]`, or `inherit` for the session model. The
+# model is an alias or a full id, never a CLI flag or command. The effort scale
+# is low | medium | high | xhigh | max. `doc-review` and `code-review` also
+# take a list. Each item is one seat: an independent reviewer on that model,
+# run beside the skill's own persona review.
+#
+# Layering is role by role, unlike the other maps in this file. An entry in
+# config.local.yaml overrides that one role and leaves the team's other roles
+# in place.
+#
+# An entry in either file replaces the older keys for the same step:
+#   brainstorm                -> brainstorm_model
+#   plan                      -> plan_model
+#   doc-review, code-review   -> cross_model_peer, cross_model_model, cross_model_effort
+#   work                      -> work_engine_mode, work_engine_preferences, work_engine_effort
+# debug, simplify, and compound have no older key.
+#
+# Two opt-outs from a team map go in config.local.yaml. `<role>: inherit` puts
+# that role back on your session model. `work_engine_mode: off` keeps a team
+# `work` entry off external engines.
+#
+# Review seats stay under `cross_model_review_mode` (below) and the
+# CROSS_MODEL_PEERS environment variable. A seat that either one excludes is
+# skipped and reported, never replaced by another model.
+
+# model_roles:
+#   brainstorm: opus high              # the generated approaches
+#   plan: fable low                    # the authored plan
+#   doc-review:                        # each seat reviews the plan independently
+#     - grok-4.7 high
+#     - gpt-6.1-sol
+#     - opus medium
+#   debug: opus high                   # the diagnosis and fix
+#   work: opus medium                  # the code
+#   simplify: sonnet low               # the simplification
+#   code-review: [opus high, sonnet]   # each seat reviews the diff independently
+#   compound: inherit                  # the learning document, on the session model
+
 # --- Model elevation ---
 # Send only the reasoning-heavy step of /ce-plan (interpret research, then author
 # the plan) and /ce-brainstorm (generate approaches) to a model you name. The rest

CONCEPTS.md

@@ -99,6 +99,11 @@ A semantic cost class for a dispatched sub-agent — extraction (cheapest capabl
 
 When a platform cannot select models per agent, every role runs on the inherited model and cost control falls back to structure: read budgets and output caps.
 
+### Model role map
+A per-repository assignment of a model, and optionally a reasoning effort, to each kind of work in the Pipeline — one role per step Skill — so each step produces its deliverable on the developer's choice whether the developer invokes the Skill or an orchestrating Skill does. An entry governs only that step's deliverable: dialogue with the user, orchestration inside the Skill, and sub-agents dispatched at their Model tier are unchanged. A role with no entry behaves as it did before the map existed, and an entry may say to inherit, which means the session model.
+
+An instruction given for the current run outranks an entry, and an entry outranks the older per-step model settings. When the named model or effort cannot be served, a single-model role runs on the nearest option, keeping the named model as long as any route can serve it and ending at the session model. Every governed step reports the requested model, the served model, and the route, so a fallback is visible rather than silent.
+
 ### Evidence dossier
 A bulk evidence artifact — verbatim quotes with source pointers, gathered by a cheap scout agent — written to scratch storage instead of returned inline, so the orchestrator carries only a short gist and downstream agents read the full dossier themselves.
 
@@ -141,6 +146,11 @@ An additive delegated run that sends the host workflow's review or judgment brie
 
 A peer result is usable only after the route reports a successful terminal outcome and the result satisfies that consumer's output contract. Provider-failure retry allowances belong to the route worker and remain inside the original route deadline; once a provider no-review outcome reaches the host, that peer is not restarted. POV position results additionally declare settledness in their output contract: a schema-shaped result not declared final is a placeholder, never a peer voice.
 
+### Review seat
+One independent reviewer that a review role's entry in the Model role map adds to a review, running on the model that entry names. A review role takes a list, and the length of the list sets the number of independent reviews. Seats run in addition to the Skill's own Reviewer persona review, which still runs when every seat is dropped, and where a review role has an entry its seats take the place of the single conditional Cross-model pass.
+
+A seat that cannot be served on its named model is dropped and reported, never filled by another model, because a substituted seat weakens the Independence the panel exists for. A policy that keeps review content from leaving for another provider skips a seat in the same way.
+
 ### Clean skip
 A delegated run that reached its gate, judged the work did not apply, and ended without producing output — a terminal outcome of the workflow rather than a failure of it.
 

docs/guides/README.md

@@ -132,7 +132,7 @@ Invoked when a specific need arises, not part of any chain.
 | [`/ce-dogfood`](./ce-dogfood.md) | Hands-off browser QA of the branch: map flows, fix small breakages, write a report. Manual invoke only. |
 | [`/ce-test-browser`](./ce-test-browser.md) | End-to-end browser tests of the current diff using a host-native browser with `agent-browser` fallback. Does not check out a PR or branch. |
 | [`/ce-test-xcode`](./ce-test-xcode.md) | Build and test an iOS app on the simulator (screenshots, logs, human verification). Not XCUITest. |
-| [`/ce-setup`](./ce-setup.md) | Diagnose optional tool capabilities, create or repair repo `config.yaml`, and scaffold a Compound Pack |
+| [`/ce-setup`](./ce-setup.md) | Diagnose optional tool capabilities, create or repair repo `config.yaml`, scaffold a Compound Pack, and set the model role map |
 | [`/ce-handoff`](./ce-handoff.md) | Write a session handoff, or find and orient from a selected source. Does not auto-continue. |
 
 ---

docs/guides/ce-brainstorm.md

@@ -248,6 +248,12 @@ When you want a specific model for the heavy reasoning step, `ce-brainstorm` can
 
 This works on any harness. The host serves the chosen model natively where it can, otherwise it invokes the Claude CLI (which must be installed and authenticated), otherwise it runs the step on your session model and says which precondition was unmet.
 
+## Model role
+
+`ce-brainstorm` reads the `brainstorm` role from the `model_roles` map in CE config. The entry names the model, and optionally the reasoning effort, that generates the approaches. That is the same step model elevation dispatches, and the entry takes the place of `brainstorm_model`. A model you name in the prompt still wins for that run.
+
+The Claude CLI route serves Claude-family models, at any effort the map accepts. A model from another family is used only where your harness can hand it to a subagent. Otherwise the step runs on your session model and says why. Whenever an entry governs the step, the skill prints one `Model role brainstorm:` line naming what was requested, what served it, and the route. See [Model roles](./configuration.md#model-roles) for entry syntax, precedence, and fallback.
+
 ---
 
 ## See Also

docs/guides/ce-code-review.md

@@ -140,6 +140,12 @@ Each peer runs from the repository root so it can read surrounding code. Its rea
 
 This shares the provider/route kernel with `ce-doc-review` but keeps a narrower scope: adversarial-only, diff/work-tree delivery, not doc-review's judgment trio or whole-doc sweep.
 
+## Model role
+
+`ce-code-review` reads the `code-review` role from the `model_roles` map in CE config. The entry is one model or a list, each with an optional reasoning effort. Every item is a seat: one independent reviewer that gives the diff an adversarial read on that model. Seats run on every full review, beside the persona reviewers, and they take the place of the conditional single-peer pass described above. A lite or focused review dispatches no reviewer team, so it does not apply the role. It says so in Coverage, and `depth:full` applies it. The in-process adversarial reviewer still runs alongside them.
+
+`cross_model_review_mode: off` and `CROSS_MODEL_PEERS` still decide which seats may send review content to another provider. A seat that cannot run is dropped and reported, never filled by another model, and the persona review runs either way. Each seat prints its own `Model role code-review seat <n>:` line naming what was requested, what served it, and the route. See [Model roles](./configuration.md#model-roles) for entry syntax, precedence, and the seat rules.
+
 ## Severity and autofix class are orthogonal
 
 Severity answers urgency (P0 = critical breakage, P3 = user discretion). Autofix class describes follow-up shape, not apply permission:

docs/guides/ce-compound.md

@@ -131,6 +131,12 @@ After capturing the new learning, `ce-compound` checks whether the learning sugg
 
 Phrases like "that worked", "it's fixed", "working now", and "problem solved" identify the completion checkpoint. They do not establish that a learning qualifies. Automatic capture still applies the non-obvious, durable, and material gate above. `/ce-compound [context]` requests immediate evaluation without waiting for a completion phrase; it does not lower the bar.
 
+### Model role
+
+`ce-compound` reads the `compound` role from the `model_roles` map in CE config. The entry names the model that drafts the learning document. In Full mode a subagent on that model writes the body from a hand-off file, while the session still classifies the learning, writes the file, and validates it. Lightweight mode launches no subagents, so it writes the doc on the session model whatever the entry names.
+
+This role is served only by a subagent of your harness. An effort in the entry is reported as not applied where that subagent cannot be given one, and the session drafts the body itself when the harness cannot hand over the model. The report carries one `Model role compound:` line naming what was requested, what served it, and the route. See [Model roles](./configuration.md#model-roles) for entry syntax, precedence, and fallback.
+
 ---
 
 ## Quick example

docs/guides/ce-debug.md

@@ -132,6 +132,12 @@ Concrete signals trigger a `/ce-brainstorm` recommendation rather than a fix: th
 
 `mode:return-to-caller` (set by `lfg` on its defect route) is also non-interactive, but the caller owns everything after the fix. It keeps the full investigation and the convergent-or-defer boundary, creates a feature branch when it starts on the default branch, commits the fix-owned files without pushing, skips the post-fix polish and review steps, and returns a structured result: `fixed`, `diagnosed-no-fix`, `needs-human`, or `blocked`, with the root cause, changed files, verification evidence, residuals, and the issue of record. `lfg` then simplifies, reviews, and ships from that return.
 
+### Model role
+
+`ce-debug` reads the `debug` role from the `model_roles` map in CE config. The entry names the model that produces the diagnosis and the fix. A read-only subagent on that model gathers the evidence and proposes the causal chain, and a second one writes the failing test and the minimal fix. The session keeps the causal-chain gate, the branch, the commit, and the return. Pipeline and return-to-caller runs honor the entry the same way interactive runs do.
+
+This role is served only by a subagent of your harness. An effort in the entry is reported as not applied where that subagent cannot be given one, and the session does the work itself when the harness cannot hand over the model. An interactive run prints one `Model role debug:` line at the end of the Debug Summary. A pipeline or return-to-caller run carries the same line in the optional `model_role` field of its structured result. See [Model roles](./configuration.md#model-roles) for entry syntax, precedence, and fallback.
+
 ---
 
 ## Quick Example

docs/guides/ce-doc-review.md

@@ -169,6 +169,12 @@ Peers run through [acpx](https://github.com/openclaw/acpx), which talks to each
 
 Each peer runs from an empty workspace, and every permission request it makes is denied. This is best effort rather than a sandbox. Claude, the native Grok CLI, and OpenCode cannot read files outside that empty workspace or write files. The native Grok CLI can still search and fetch from the web. Codex and the Cursor routes can still read any file your account can read, because their adapters do not ask permission before a read, and the Codex adapter can still write. Claude peers start in safe mode, so the repository's project settings and hooks do not apply to them. Served models are recorded from what each adapter reports. Codex, Claude, and the native Grok CLI report one; Cursor and OpenCode routes stay unverified.
 
+### Model role
+
+`ce-doc-review` reads the `doc-review` role from the `model_roles` map in CE config. The entry is one model or a list, each with an optional reasoning effort. Every item is a seat: one independent reviewer that reads the whole document on that model. Seats run on every review, beside the persona reviewers, and they take the place of the conditional single-peer pass described above.
+
+`cross_model_review_mode: off` and `CROSS_MODEL_PEERS` still decide which seats may send the document to another provider. A seat that cannot run is dropped and reported, never filled by another model, and the persona review runs either way. Each seat prints its own `Model role doc-review seat <n>:` line naming what was requested, what served it, and the route. See [Model roles](./configuration.md#model-roles) for entry syntax, precedence, and the seat rules.
+
 ---
 
 ## Quick Example

docs/guides/ce-plan.md

@@ -285,6 +285,12 @@ When you want a specific model for the heavy reasoning step, `ce-plan` can autho
 
 This works on any harness. The host serves the chosen model natively where it can, otherwise it invokes the Claude CLI (which must be installed and authenticated), otherwise it runs the step on your session model and says which precondition was unmet.
 
+## Model role
+
+`ce-plan` reads the `plan` role from the `model_roles` map in CE config. The entry names the model, and optionally the reasoning effort, that authors the plan. That is the same step model elevation dispatches, and the entry takes the place of `plan_model`. A model you name in the prompt, or a planning directive `lfg` carries, still wins for that run.
+
+The Claude CLI route serves Claude-family models, at any effort the map accepts. A model from another family is used only where your harness can hand it to a subagent. Otherwise the step runs on your session model and says why. Whenever an entry governs the step, the skill prints one `Model role plan:` line naming what was requested, what served it, and the route. See [Model roles](./configuration.md#model-roles) for entry syntax, precedence, and fallback.
+
 ## See Also
 
 - [`ce-brainstorm`](./ce-brainstorm.md): produce the requirements-only unified plan that `ce-plan` enriches