@kontextmind/kxm 0.7.130 → 0.7.131

package/.claude-plugin/marketplace.json

@@ -11,7 +11,7 @@
       "name": "kxm",
       "source": "./plugins/kxm",
       "description": "Durable workflows, peer agents, and kxm tui",
-      "version": "0.7.130",
+      "version": "0.7.131",
       "category": "development",
       "tags": ["kxm", "multi-agent", "workflows", "mcp"]
     }

package/.kxm/README.md

@@ -15,7 +15,6 @@ a `default` workflow, `gates.yaml` and `template-provenance.yaml`.
 | `agents/`, `models/`, `workflows/` | Agents, model profiles and workflows, one YAML file each | Tracked |
 | `gates.yaml` | The executable gate registry | Tracked |
 | `roles/`, `routes.yaml`, `prices.yaml` | Role rosters, admitted model routes, dated list prices | Tracked |
-| `roster.yaml` | The developer assignment roster for this repository | Tracked, and must be committed |
 | `template-provenance.yaml` | Hashes of the template `kxm init` used | Tracked |
 | `models/inventory.yaml` | The discovered model catalog | Generated; track it for a reviewed snapshot |
 | `config.yaml` | Shared personalization settings | Tracked if the project shares them |
@@ -26,6 +25,10 @@ a `default` workflow, `gates.yaml` and `template-provenance.yaml`.
 | `state/` | The hub database `kxm.db`, Pi sessions and restart state | Ignored |
 | `run/` | SSH control sockets from `kxm ssh` | Ignored |
 
+The role files under `.kxm/roles/` and the model files under `.kxm/models/`
+carry the developer policy. The assignment runner reads them at
+`refs/remotes/origin/main`.
+
 The [configuration reference](../docs/reference/config-reference.md#workspace-layout-tracked-ignored-and-state)
 describes every file, the ignore rules to add, and the state KXM keeps outside
 the project.

package/.kxm/agents/coordinator.yaml

@@ -1,5 +1,6 @@
 schema: kxm.agent.v1
 purpose: Coordinate the pinned workflow and emit schema-validated commands.
+role: planner
 tools:
   preset: coordinator
 defaultRepositoryAccess: read

package/.kxm/agents/critic-arch.yaml

@@ -1,9 +1,6 @@
 schema: kxm.agent.v1
 purpose: Architecture critic for the approved workflow change.
-harness: claude
-model:
-  provider: anthropic
-  model: fable
+role: reviewer-arch
 tools:
   preset: read-only
 defaultRepositoryAccess: read

package/.kxm/agents/critic-cli.yaml

@@ -1,9 +1,6 @@
 schema: kxm.agent.v1
 purpose: CLI and verification critic for the approved workflow change.
-harness: codex
-model:
-  provider: openai
-  model: gpt-5.6-sol
+role: reviewer-cli
 tools:
   preset: read-only
 defaultRepositoryAccess: read

package/.kxm/agents/implementer.yaml

@@ -1,9 +1,6 @@
 schema: kxm.agent.v1
 purpose: Implement the approved change within the declared repository scope.
-harness: grok
-model:
-  provider: xai
-  model: grok-4.7
+role: writer
 tools:
   preset: workspace-writer
 defaultRepositoryAccess: none

package/.kxm/workflows/implement-only.yaml

@@ -1,5 +1,5 @@
 schema: kxm.workflow.v1
-description: One implementer step with a drive receipt. Replaces just impl.
+description: One implementer step with a drive receipt.
 coordinator: coordinator
 limits:
   maxTransitions: 2

package/.kxm/workflows/review-arch-only.yaml

@@ -1,5 +1,5 @@
 schema: kxm.workflow.v1
-description: One read-only architecture critic step. Replaces just review-arch.
+description: One read-only architecture critic step.
 coordinator: coordinator
 limits:
   maxTransitions: 2

package/.kxm/workflows/review-cli-only.yaml

@@ -1,5 +1,5 @@
 schema: kxm.workflow.v1
-description: One read-only CLI critic step. Replaces just review-cli.
+description: One read-only CLI critic step.
 coordinator: coordinator
 limits:
   maxTransitions: 2

package/CHANGELOG.md

@@ -138,6 +138,17 @@ All notable user-facing changes are documented here. The project follows [Semant
 
 ### Changed
 
+- **Dispatch reads role and model files, and agents bind a role.**
+  `scripts/roster-policy.mjs` builds the developer policy from
+  `.kxm/models/*.yaml` and `.kxm/roles/*.yaml` at `refs/remotes/origin/main`.
+  The engine resolves harness, model, and effort from the agent's `role`
+  and that role's roster. A step `model` does not override that route.
+  `kxm routes` prints `policy` (`admitted`, `disabled`) and `membership`
+  from the role files. `.kxm/routes.yaml` keeps admitted and disabled
+  selectors. `reviewer-arch` resolves to `fable-claude`. `opus-claude` is
+  admitted and named by no roster, so it is absent from `routes` and the
+  lineups. `gemini-agy` is in the writer lineup. An agent `tools.preset`
+  may only narrow its role preset; that rule is recorded and enforced in P3.
 - **Role and model files are live `kxm.role.v2` and `kxm.model.v2`.**
   `schemas/role.schema.json` and `schemas/model.schema.json` are the files
   `kxm config` validates. Each admitted roster route is a
@@ -153,7 +164,9 @@ All notable user-facing changes are documented here. The project follows [Semant
   in the developer ceilings or the harness inventory can dispatch them:
   `zai-coding-cn/glm-5.3-flash`, `qwen-token-plan/qwen3.8-flash`,
   `qwen-token-plan/qwen3.8-max`, and `zai-coding-cn/glm-5.3`.
-  Dispatch still reads `.kxm/roster.yaml` until P2.
+  Dispatch resolves harness, provider, model, and effort from the role roster.
+  A live request with no harness is refused. A roster entry with no effort
+  leaves thinking unset.
 
 - **Usage errors under `--json` print a `usage_error` envelope and exit 2.**
   A missing required option, unknown command, or other Commander usage error
@@ -418,6 +431,14 @@ All notable user-facing changes are documented here. The project follows [Semant
 
 ### Removed
 
+- **The developer roster file and the transport just recipes.**
+  The single roster document and the `impl`, `plan`, `review-arch`,
+  `review-cli`, `impl-bg`, and `dispatch` recipes are gone. One-step
+  workflows are the transport: `kxm lane run <unit> --brief <file> --workflow implement-only`,
+  and the same command with `review-arch-only` or `review-cli-only`.
+  Transfer policy from `.kxm/roster.yaml` to the role and model files and
+  delete the retired roster before running KXM. KXM refuses a leftover
+  `.kxm/roster.yaml`.
 - **`.kxm/template-provenance.yaml` was removed from this project, a repository
   change rather than a product change,** because the installed kxm no longer
   recognizes its recorded revision and a project without the file validates as

package/docs/concepts/architecture.md

@@ -211,7 +211,7 @@ The package ships a directory of `SKILL.md` suites that Pi and Claude Code both
 Project behavior lives in Git under `.kxm/`: `project.yaml`, `agents/`, `models/`, `workflows/`, `gates.yaml`, `roles/`, `routes.yaml`, `memory/`, and `skills/`. The project bundle (`project.yaml`, `agents/`, `models/`, `workflows/`, and `gates.yaml`) is restricted YAML checked against a JSON Schema. `routes.yaml`, `roles/`, and the front matter in `memory/` and `skills/` are parsed as ordinary YAML with their own checks, and a live drive re-reads an agent file the same way to resolve its route. Git review is the activation boundary:
 
 - Every run pins revision hashes of the project bundle, memory, executor policy, and tool policy. An edit affects only later runs, and a run whose pinned revisions drift is refused.
-- `kxm trust diff` prints a structured permission diff against a base revision (default `HEAD`). `kxm trust check` exits non-zero when the change expands permissions. Neither covers `routes.yaml`, `roles/`, `roster.yaml`, or `prices.yaml`, so admitting a route is not flagged.
+- `kxm trust diff` prints a structured permission diff against a base revision (default `HEAD`). `kxm trust check` exits non-zero when the change expands permissions. Neither covers `routes.yaml`, `roles/`, `the role files`, or `prices.yaml`, so admitting a route is not flagged.
 - Legacy `.kxm/config/*.json` files are refused, never converted.
 
 Webhook workflow definitions are separate JSON that the hub loads at start, with secrets named by environment variable. Personal settings merge built-in defaults, then `~/.config/kxm/config.yaml`, then the project's `.kxm/config.yaml`. See the [configuration file reference](../reference/config-reference.md) and [Configuration](../reference/configuration.md).

package/docs/contracts/routing.md

@@ -130,11 +130,11 @@ just accept /abs/task-dir <commit> /abs/writer-record /abs/arch-review /abs/cli-
 # optional observed PR/CI (direct script; the five-argument just recipe cannot forward them):
 # node scripts/assignment-run.mjs accept --task-dir /abs/task --commit <sha> --record-dir /abs/writer --critic /abs/arch --critic /abs/cli [--observed-pr <id>] [--observed-ci <id>]
 
-just plan-current /abs/task-dir /abs/plan.md <sha256> <base-commit> <expected-generation>
+kxm assign plan-current --task-dir /abs/task-dir --plan /abs/plan.md --sha256 <sha256> --base-commit <base-commit> --expected-generation <expected-generation>
 just change-report /abs/task-dir
 ```
 
-`just impl|plan|review-arch|review-cli` remain harness transport. They do not
+`kxm lane run` remain harness transport. They do not
 create assignment identity, witness receipts, or `accepted.json`.
 
 Distinctions the report and docs must keep:
@@ -161,7 +161,7 @@ learned policy and not a catalog feed. Phase 9 may use this report to
 Per-candidate acceptance requires an actual native writer, the fixed witness,
 and both designated native reviews. PR/CI/merge complete issue 127. This
 document does not assert those gates have passed. Low-level
-`just impl|plan|review-arch|review-cli` recipes remain harness transport.
+`kxm lane run` recipes remain harness transport.
 
 ## Implemented: v2 record
 

package/docs/contributing/assignment-runner.md

@@ -16,24 +16,25 @@ a KXM product feature.
 ## Before you begin
 
 - A clean control checkout of this repository whose `HEAD` is an ancestor of
-  `origin/main`. The runner loads `.kxm/roster.yaml` only from there.
+  `origin/main`. The runner loads `.kxm/roles/*.yaml` and `.kxm/models/*.yaml`
+  only from there.
 - A separate worktree for the writer. `kxm lane create <unit>` creates one from
   `origin/main`.
 - The harness CLIs the roster admits, installed and logged in.
   `node scripts/kxm.mjs harness list` shows which are. The loop below is
-  `kxm assign`. `just` still runs the transport recipes.
+  `kxm assign`. Transport is `kxm lane run <unit> --brief <file> --workflow implement-only`,
+  or the same command with `review-arch-only` or `review-cli-only`.
 - A task directory whose final path segment equals the task ID. Every path you
   pass to the runner must be absolute.
 
 ## Roles and routes
 
-The trusted roster policy in [`.kxm/roster.yaml`](../../.kxm/roster.yaml)
-(`kxm.developer-roster.v1`) admits each route for specific roles and
-permissions:
+The trusted roster policy in `.kxm/roles/*.yaml` and `.kxm/models/*.yaml`
+admits each route for specific roles and permissions:
 
 | Role | Admitted route (harness / model) | Vendor | Permission |
 |---|---|---|---|
-| `writer` | `grok` / `grok-4.7`; relief: `pi` / `openrouter/qwen/qwen3-coder-plus` | `xai`; `alibaba` | `edit` |
+| `writer` | `grok` / `grok-4.7`; relief: `pi` / `openrouter/qwen/qwen3-coder-plus`; `agy` / `gemini-3.8-flash-high` | `xai`; `alibaba`; `google` | `edit` |
 | `planner` | `claude` / `fable` | `anthropic` | `read-only` |
 | `reviewer-arch` | `claude` / `fable` | `anthropic` | `read-only` |
 | `reviewer-cli` | `codex` / `gpt-5.6-sol` | `openai` | `read-only` |
@@ -85,7 +86,7 @@ Use this slim loop for daily work and for docs. The 13-step `fix` workflow in
 > runner validates anything. The process environment is passed through as it
 > is. Export any variable you need before the command.
 
-The seven `just` assignment recipes remain available and will be removed after one real unit has been accepted through `kxm assign`; until then both forms are equivalent because both call `scripts/assignment-run.mjs` unchanged.
+Transport is `kxm lane run <unit> --brief <file> --workflow implement-only`, or the same command with `review-arch-only` or `review-cli-only`. The transport recipes are deleted.
 
 ### 1. Pin the current plan
 
@@ -314,17 +315,15 @@ It writes `recording-resolved.json` in the record directory. It never changes
 ## Transport-only recipes
 
 Drive a one-step workflow in a lane. Each command writes a drive receipt and
-the checkout fingerprint. `just impl`, `just plan`, `just review-arch`,
-`just review-cli`, and `just impl-bg` are retired in favor of these. The
-recipes stay in the justfile until one real unit has been driven this way.
+the checkout fingerprint.
 
 ```bash
-kxm lane run <unit> --workflow implement-only --brief <file>
-kxm lane run <unit> --workflow review-arch-only --brief <file>
-kxm lane run <unit> --workflow review-cli-only --brief <file>
+kxm lane run <unit> --brief <file> --workflow implement-only
+kxm lane run <unit> --brief <file> --workflow review-arch-only
+kxm lane run <unit> --brief <file> --workflow review-cli-only
 ```
 
-`just dispatch` still sends one `kxm.harness-request.v1` envelope through
+`scripts/harness-run.mjs` still accepts one `kxm.harness-request.v1` envelope through
 `scripts/harness-run.mjs` and prints a `kxm.harness-result.v2` envelope. It
 mints no assignment, witness or acceptance proof, so its output cannot be
 accepted. The retired recipes did the same.
@@ -430,4 +429,4 @@ gate-only workflows are supported. See the
 - [Develop KXM](development.md): the commit gate the witness runs
 - [CI and release](ci-and-release.md): what runs after you push
 - [Harness routing](../reference/harness-routing.md): harness and model pairing
-- [Configuration reference](../reference/config-reference.md#kxmrosteryaml-kxmdeveloper-rosterv1): the roster file
+- [Configuration reference](../reference/config-reference.md#developer-assignment-policy): the developer assignment policy

package/docs/contributing/development.md

@@ -13,8 +13,16 @@ extension, the Claude Code plugin, or the bundled skills.
 - Optional tools, needed only for the matching task:
   - [Pi](https://pi.dev) to load the extension from source.
   - The Claude Code CLI to validate the plugin manifests locally.
-  - [`just`](https://github.com/casey/just) for the
-    [assignment runner](assignment-runner.md).
+  - [`just`](https://github.com/casey/just) for the remaining
+    [assignment runner](assignment-runner.md) recipes only:
+    `assign`, `witness`, `accept`, `observe-cost`, `attribute`,
+    `change-report`, and `plan-current`. Those recipes are harness
+    transport for the issue 127 runner. They are not how a unit is
+    dispatched. Do not rename or delete them.
+  - `kxm lane run` to dispatch a unit. A writer unit uses
+    `kxm lane run <unit> --brief <file> --workflow implement-only`.
+    The read-only critic workflows on the same command are
+    `review-arch-only` and `review-cli-only`.
   - Docker for the clean-container install smoke.
 
 ## Set up a checkout
@@ -116,7 +124,7 @@ excluded from the npm package.
 ├── .github/                CI, release, issue and PR templates (not shipped)
 ├── .claude/                Developer harness notes and commands (not shipped)
 ├── plans/                  Internal planning and tracking (not shipped)
-├── justfile                Developer recipes for the assignment runner
+├── justfile                Remaining issue 127 recipes (assign, witness, accept, observe-cost, attribute, change-report, plan-current)
 └── AGENTS.md, CLAUDE.md, GEMINI.md   Agent instructions with generated blocks
 ```
 
@@ -196,8 +204,14 @@ For what each skill covers, see [Agent skills](../guides/agent-skills.md).
 8. Push and open a pull request. The template asks for the slice issue and the
    `npm run verify` result.
 
-Maintainers who delegate work to coding agents use the
-[assignment runner](assignment-runner.md) for steps 2 to 7.
+Maintainers who delegate a unit dispatch it with
+`kxm lane run <unit> --brief <file> --workflow implement-only`.
+Read-only critics use the same command with `review-arch-only` or
+`review-cli-only`. The [assignment runner](assignment-runner.md)
+recipes (`assign`, `witness`, `accept`, `observe-cost`, `attribute`,
+`change-report`, `plan-current`) stay on `just`. They are harness
+transport for the issue 127 runner, not the unit transport, and they
+cover steps 2 to 7 after a lane run.
 
 ## Generated artifacts
 

package/docs/contributing/harness-routing-internals.md

@@ -3,7 +3,7 @@
 This page records how the KXM repository applies [harness routing](../reference/harness-routing.md) to its own work: the routes this checkout admits, its writer roster, its price catalog, and the developer roster policy that `just assign` and the dev helper enforce. It is maintainer material. The snapshots were captured on 2026-09-23 on one operator machine, from a source checkout where `node scripts/kxm.mjs` is the same program as `kxm`; they change whenever an admission changes.
 
 > [!IMPORTANT]
-> The files are the authority, not this page: `.kxm/routes.yaml`, `.kxm/roles/`, `.kxm/roster.yaml` and `.kxm/prices.yaml`. Product routing decisions are recorded under Tracking → Decided in `plans/implementation-plan.md`.
+> The files are the authority, not this page: `.kxm/routes.yaml`, `.kxm/roles/*.yaml`, `.kxm/models/*.yaml`, and `.kxm/prices.yaml`. Product routing decisions are recorded under Tracking → Decided in `plans/implementation-plan.md`.
 
 ## This checkout's routes and roster
 
@@ -59,9 +59,9 @@ On the capture machine, `kxm harness list` showed `claude` detected but logged o
 
 `.kxm/prices.yaml` is dated `2026-09-16`, so every current run records `providerMetadata.priceCatalogStale: true` and no list estimate. The list prices below come from `.kxm/models/inventory.yaml`, fetched `2026-09-16T14:54:53Z`, in USD per 1M tokens. The checkout has no routing records yet, so none of the examples has recorded latency; for latency, run a bounded side-by-side experiment and compare p50 and p95 in `kxm routing report`.
 
-## The developer roster (`.kxm/roster.yaml`)
+## The developer roster
 
-The issue-127 runner (`just assign`, see the [assignment runner](assignment-runner.md)) uses its own policy file, [`kxm.developer-roster.v1`](../reference/config-reference.md#kxmrosteryaml-kxmdeveloper-rosterv1). Routes there name the harness, the model and the vendor explicitly:
+The issue-127 runner (`kxm assign`, see the [assignment runner](assignment-runner.md)) reads `.kxm/roles/*.yaml` and `.kxm/models/*.yaml` at `refs/remotes/origin/main`. See [Developer assignment policy](../reference/config-reference.md#developer-assignment-policy). Routes there name the harness, the model and the vendor explicitly:
 
 ```yaml
   grok-native:
@@ -100,7 +100,7 @@ The product brake, the dev helper and the roster policy now agree on the vendor
 
 ## Worked examples on this checkout
 
-These extend the generic examples on the reference page with this checkout's admissions, developer-roster routes, readiness on the capture machine, and inventory prices.
+These extend the generic examples on the reference page with this checkout's admissions, developer policy routes, readiness on the capture machine, and inventory prices.
 
 ### Grok 4.6
 
@@ -174,19 +174,19 @@ The developer runner is stricter. Its only Pi writer is `openrouter/qwen/qwen3-c
 
 | Symptom | Cause | Fix |
 |---|---|---|
-| `pi brake: xai has a native harness; refusing Pi impersonation` | A dev-helper request routed a native vendor through Pi. | Use the native harness recipe instead: `just impl`, `just plan`, `just review-arch` or `just review-cli`. |
-| `Roster policy refused: native vendor cannot use Pi` | A `.kxm/roster.yaml` Pi route names a native vendor, as in `openrouter/x-ai/…` or `nous-portal/anthropic/…`. | Remove the route. Only a native harness route is valid for that vendor. |
+| `pi brake: xai has a native harness; refusing Pi impersonation` | A dev-helper request routed a native vendor through Pi. | Use the native harness through `kxm lane run <unit> --brief <file> --workflow review-arch-only`. |
+| `Roster policy refused: native vendor cannot use Pi` | A Pi route in `.kxm/models/*.yaml` names a native vendor, as in `openrouter/x-ai/…` or `nous-portal/anthropic/…`. | Remove the route. Only a native harness route is valid for that vendor. |
 | The dev helper refuses a codex route. | `codex` is logged in with an API key. | Run `codex login` with the ChatGPT flow. |
 
 For example, the native writer recipe:
 
 ```bash
-just impl brief.md
+kxm lane run <unit> --brief <file> --workflow implement-only
 ```
 
 ## Related
 
 - [Harness routing](../reference/harness-routing.md): the rules, the decision procedure and the generic examples
 - [Assignment runner](assignment-runner.md): the loop that enforces the developer roster
-- [Configuration file reference](../reference/config-reference.md#kxmrosteryaml-kxmdeveloper-rosterv1): the `kxm.developer-roster.v1` fields
+- [Configuration file reference](../reference/config-reference.md#developer-assignment-policy): the developer assignment policy fields
 - [Routing and cost telemetry contract](../contracts/routing.md): the routing record, cost basis and dev-helper telemetry

package/docs/glossary.md

@@ -423,7 +423,7 @@ A `kxm.role.v2` definition in `.kxm/roles/`, managed with `kxm role`, that descr
 
 ### Roster
 
-A list of allowed models. It means either a [role](#role)'s roster, or the developer roster `.kxm/roster.yaml` that the [assignment runner](contributing/assignment-runner.md) trusts to choose writers and critics. Neither one admits a route; see [admission](#admission).
+A list of allowed models. It means either a [role](#role)'s roster, or the developer roster in `.kxm/roles/*.yaml` and `.kxm/models/*.yaml` that the [assignment runner](contributing/assignment-runner.md) trusts to choose writers and critics. Neither one admits a route; see [admission](#admission).
 
 ### Route
 

package/docs/guides/agent-skills.md

@@ -1,6 +1,6 @@
 # Agent skills
 
-KXM ships a suite of Agent Skills that teach a coding agent how to use the `kxm` CLI and the `kxm_*` tools safely: which command owns a task, which verbs exist, and which steps belong to a person. This page is for anyone running KXM from Claude Code, Pi or Codex, and for contributors who edit the skills. Skills document the CLI; they grant no permission, admit no writer and replace no trusted `.kxm/roster.yaml` policy.
+KXM ships a suite of Agent Skills that teach a coding agent how to use the `kxm` CLI and the `kxm_*` tools safely: which command owns a task, which verbs exist, and which steps belong to a person. This page is for anyone running KXM from Claude Code, Pi or Codex, and for contributors who edit the skills. Skills document the CLI; they grant no permission, admit no writer and replace no trusted policy in `.kxm/roles/*.yaml` and `.kxm/models/*.yaml`.
 
 Governed skills that your own runs produce are a separate lifecycle; see [Governed skills](governed-skills.md).
 

package/docs/operations/backup-and-restore.md

@@ -15,7 +15,7 @@ KXM spreads state over six roots. Some of them move with environment variables,
 ```mermaid
 flowchart TB
   subgraph R["$R checkout root: the Git checkout, never moves"]
-    R1["Project definition: .kxm/project.yaml, config.yaml, agents/, models/, workflows/, gates.yaml, roles/, roles, routes.yaml, roster.yaml, prices.yaml, repo/, project/env.yaml"]
+    R1["Project definition: .kxm/project.yaml, config.yaml, agents/, workflows/, gates.yaml, .kxm/roles/, .kxm/models/, routes.yaml, prices.yaml, repo/, project/env.yaml"]
     R2["Durable records: .kxm/memory/, skills/, goals/, tasks/, candidates/"]
   end
   subgraph D["$D workspace: KXM_WORKSPACE_DIR or --workspace, default $R/.kxm"]
@@ -31,7 +31,7 @@ flowchart TB
     S2["hub-env.json, hub-binding.json, update.yaml, projects/HASH/repository-bindings.json"]
   end
   subgraph C["$C user config: KXM_USER_CONFIG_DIR, default ~/.config/kxm"]
-    C1["config.yaml, roles/, workflows/, roles, session.token"]
+    C1["config.yaml, workflows/, session.token. Checkout routing lives in .kxm/roles/ and .kxm/models/"]
   end
   subgraph T["$T federated telemetry: XDG_CONFIG_HOME/kxm/telemetry"]
     T1["model-metrics.jsonl, not written by any command today"]
@@ -71,13 +71,13 @@ The Runtime registry and the other projects' event stores are shared by every pr
 | `$S/runtime/registry.db` | Runtime registry: projects, their roots and home Runtime, the supervisor identity and claim | Only with `--all-projects` (`registry`) |
 | `$S/projects/<hash>/repository-bindings.json`, `$S/update.yaml` | Member repository paths; updater settings | No |
 | `$S/hub-env.json`, `$S/hub-binding.json`, `$C/session.token` | Credentials and the machine's hub binding | No; prefer regenerating secrets to copying them |
-| `$R/.kxm/` definition files and durable records | Project, roles, routes, prices, roster, memory, skills, goals, tasks, candidates | No; commit them to Git or copy the checkout |
+| `$R/.kxm/` definition files and durable records | Project, `.kxm/roles/`, `.kxm/models/`, routes, prices, memory, skills, goals, tasks, candidates | No; commit them to Git or copy the checkout |
 | Each member repository's `.kxm/repo/*.yaml` | Member definition and environment | No; they live in the member's own checkout |
 | `$W/worker-*.json`, `$W/pi-sessions/` | Worker routing and recovery manifests; Pi model history | No; manifests are required for resumable workers, Pi history is optional |
 | `$D/assets/`, `$D/logs/` | Retrospectives and evidence; logs and local usage accounting (`telemetry.jsonl`) | No |
 | `$C` | User-level roles, workflows and settings | No |
 
-A restore without `roster.yaml`, `routes.yaml` or `prices.yaml` comes back healthy but with different admission and cost behavior, so treat them as part of the backup even though they are plain files. `kxm improve report --out-dir` can write candidates outside `$R/.kxm/candidates/`; include that directory if you use it.
+A restore without `.kxm/roles/`, `.kxm/models/`, `routes.yaml`, or `prices.yaml` comes back healthy but with different admission and cost behavior, so treat them as part of the backup even though they are plain files. `kxm improve report --out-dir` can write candidates outside `$R/.kxm/candidates/`; include that directory if you use it.
 
 These files are disposable and need no backup: `hub.pid`, `hub.stop`, `worker-*.pid`, `session-brief.json`, `update-check.json`, `runtime/supervisor.token`, `runtime/supervisor.error`.
 

package/docs/reference/cli-reference.md

@@ -177,7 +177,7 @@ kxm init [--name <name>] [--project-id <id>] [--repository <id=absolute-path>]..
 
 Creates, validates, repairs, resumes, or joins a KXM project at the Git root that contains the current directory. A new project gets a minimal configuration: one coordinator agent, one implementer agent, a `test` command gate, and a `default` plan-implement-verify workflow. An existing project is validated without rewriting. Conflict-free template updates to non-authority fields are applied; authority changes, overlapping edits, and provenance-free or legacy state stay planning-only. `init` does not start a hub or the Runtime.
 
-The starter `defaultHarness: pi` and `npm test` gate are generic settings, not repository detection. Creation and create-planning output include `guidance`: for Claude, set `defaultHarness: claude` in `.kxm/project.yaml`, update any explicit `harness` overrides in `.kxm/agents/*.yaml`, and configure compatible agent models; for .NET or other non-npm repositories, set `.kxm/gates.yaml` → `gates.test.argv` to the repository's actual test command. Preflight reports an actionable prerequisite for `npm test` without a readable `package.json` test script; `task run` refuses it before creating a run.
+The starter `defaultHarness: pi` and `npm test` gate are generic settings, not repository detection. Initialized agents bind roles. Harness, model, and effort are set in `.kxm/roles/*.yaml` and `.kxm/models/*.yaml`. Creation and create-planning output include `guidance`: for Claude, set `defaultHarness: claude` in `.kxm/project.yaml`; for .NET or other non-npm repositories, set `.kxm/gates.yaml` → `gates.test.argv` to the repository's actual test command. Preflight reports an actionable prerequisite for `npm test` without a readable `package.json` test script; `task run` refuses it before creating a run.
 
 | Option | Argument | Default | Description |
 |---|---|---|---|
@@ -393,7 +393,7 @@ kxm completion install --shell zsh --dry-run
 
 Compares the authority-bearing fields of the project configuration against a base Git revision. The base is materialized into a temporary shadow with a sanitized environment; nothing in the project is written. Both subcommands refuse `--workspace` (exit 2) and need no hub.
 
-The comparison covers the loaded bundle only: `project.yaml`, `agents/`, `models/`, `workflows/`, `gates.yaml`, `project/env.yaml`, and each member repository's `repo.yaml` and `env.yaml`. It does not read `routes.yaml`, `roles/`, `roster.yaml`, or `prices.yaml`, so a new route admission, roster entry, developer-roster route, or price change never counts as an expansion. Review those files by hand.
+The comparison covers the loaded bundle only: `project.yaml`, `agents/`, `models/`, `workflows/`, `gates.yaml`, `project/env.yaml`, and each member repository's `repo.yaml` and `env.yaml`. It does not read `routes.yaml`, `roles/`, `the role files`, or `prices.yaml`, so a new route admission, roster entry, developer policy route, or price change never counts as an expansion. Review those files by hand.
 
 ### `kxm trust diff`
 
@@ -1069,14 +1069,32 @@ Lists admitted and disabled routes.
 
 No command-specific options.
 
-- Reads only. JSON keys: `policy` (`schema`, `updatedAt`, `admitted`, `disabled`, `roles`).
+- Reads only. JSON keys: `policy` (`schema`, `updatedAt`, `admitted`, `disabled`) and `membership` (strings `<role> <route-id>` from `.kxm/roles/*.yaml`). `policy` has no `roles` field. A model file named by no roster, such as `opus-claude`, is absent from `membership`.
 
 ```bash
 kxm routes list
 ```
 
 ```text
-no route decisions
+admitted anthropic/fable
+admitted google/gemini-3.8-flash-high
+admitted google/gemini-3.8-flash-medium
+admitted openai/gpt-5.6-sol
+admitted openrouter/qwen/qwen3-coder-plus
+admitted openrouter/qwen/qwen3.8-flash
+admitted openrouter/z-ai/glm-5.3-flash
+admitted qwen-token-plan/deepseek-v4.1-flash
+admitted qwen-token-plan/qwen3.8-flash
+admitted qwen-token-plan/qwen3.8-max
+admitted xai/grok-4.7
+admitted zai-coding-cn/glm-5.3
+admitted zai-coding-cn/glm-5.3-flash
+planner fable-claude
+reviewer-arch fable-claude
+reviewer-cli sol-codex
+writer grok-native
+writer qwen-openrouter-pi
+writer gemini-agy
 ```
 
 ```bash
@@ -1084,7 +1102,7 @@ kxm routes list --json
 ```
 
 ```text
-{"schema":"kxm.cli-result.v1","ok":true,"command":"routes list","policy":{"schema":"kxm.routes.v2","updatedAt":"2026-09-23T13:50:08.663Z","admitted":[],"disabled":[],"roles":{}}}
+{"schema":"kxm.cli-result.v1","ok":true,"command":"routes list","policy":{"schema":"kxm.routes.v2","updatedAt":"2026-09-24T00:00:00.000Z","admitted":["anthropic/fable","google/gemini-3.8-flash-high","google/gemini-3.8-flash-medium","openai/gpt-5.6-sol","openrouter/qwen/qwen3-coder-plus","openrouter/qwen/qwen3.8-flash","openrouter/z-ai/glm-5.3-flash","qwen-token-plan/deepseek-v4.1-flash","qwen-token-plan/qwen3.8-flash","qwen-token-plan/qwen3.8-max","xai/grok-4.7","zai-coding-cn/glm-5.3","zai-coding-cn/glm-5.3-flash"],"disabled":[]},"membership":["planner fable-claude","reviewer-arch fable-claude","reviewer-cli sol-codex","writer grok-native","writer qwen-openrouter-pi","writer gemini-agy"]}
 ```
 
 ### `kxm routes count`
@@ -1217,7 +1235,7 @@ Adds a role definition. Without a role ID, or with `--pick`, local scope offers
 
 - Writes `.kxm/roles/<id>.yaml` in local scope, or `<KXM_USER_CONFIG_DIR>/roles/<id>.yaml` in global scope. `--dry-run` plans the write and writes nothing.
 - Each `--route` is checked the same way as `kxm role modify --add-route`. If `.kxm/models/<route-id>.yaml` is missing, the command exits 1 and writes `kxm: route '<route-id>' is not a file under .kxm/models/` to stderr. It does not write the role file, including under `--dry-run`. `--file` checks every `roster[].route` the same way before writing, in local scope and in global scope.
-- Local scope belongs to a KXM project: the file lands in the project root's `.kxm/roles/` from any subdirectory, and outside a project the command refuses with `project_not_found` and creates nothing. Before writing, the project loader checks the project with the new role in place of any file of that ID. The loader reads only `writer.yaml`, whose roster must name a route whose model is the `implementer` agent's model (see [Roles](config-reference.md#kxmrolesroleyaml-kxmrolev2)). If the project would not load, the command refuses with `role_invalid`, lists each issue and writes nothing, also under `--dry-run`, and `--overwrite` replaces a `writer.yaml` the loader refuses. Global scope is not checked, because no loader reads it.
+- Local scope belongs to a KXM project: the file lands in the project root's `.kxm/roles/` from any subdirectory, and outside a project the command refuses with `project_not_found` and creates nothing. Before writing, the project loader checks the project with the new role in place of any file of that ID. Validation is the role file schema, and every roster route must exist under `.kxm/models/`. If the project would not load, the command refuses with `role_invalid`, lists each issue and writes nothing, also under `--dry-run`, and `--overwrite` replaces a role file the loader refuses. Global scope is not checked, because no loader reads it.
 - Refusals exit 2 and honor `--json`: `project_not_found` and `role_invalid` (with `issues`, each `{phase, code, file, message}`). A missing `--route` file, and an existing role without `--overwrite`, exit 1 with a plain stderr line, also under `--dry-run` (`kxm: route '<route-id>' is not a file under .kxm/models/`, or `role add failed: role_already_exists: ...`).
 - JSON keys: `roleId`, `id`, `filePath`, `scope`.
 
@@ -1671,7 +1689,7 @@ kxm runs status --dry-run refused: the Runtime supervisor is not running and --d
 kxm runs drive <runId> [--simulated] [--wait] [--timeout-ms <n>] [--lane <unit>]
 ```
 
-Opens a drive of the run. With `--simulated`, a model-free producer reports every agent step as passed. Without `--simulated` the drive runs in live mode: each agent step invokes its harness through a one-shot producer, and the agent's model must be an admitted route (otherwise `producer_route_not_admitted`; there is no fallback model). A read-only step runs with the harness's read-only flags. A step with `write` access runs with an audited writer profile, which only `pi` and `grok` have; it must be a single assignment in a project whose `limits.maxConcurrentRuns` is 1, and, when `.kxm/roster.yaml` exists, its route must be on the roster's writer lineup. Otherwise the drive hands the run off with `step_unsupported`. Around each live attempt the Runtime fingerprints the checkout with `git status` and `git diff`: a write step settles `passed` only when the checkout changed (routing metadata `authored: true`), and a read-only step that changed it settles `failed` (`authoringWitness: readonly_mutated`).
+Opens a drive of the run. With `--simulated`, a model-free producer reports every agent step as passed. Without `--simulated` the drive runs in live mode: each agent step invokes its harness through a one-shot producer, and the agent's model must be an admitted route (otherwise `producer_route_not_admitted`; there is no fallback model). A read-only step runs with the harness's read-only flags. A step with `write` access runs with an audited writer profile, which only `pi` and `grok` have; it must be a single assignment in a project whose `limits.maxConcurrentRuns` is 1, and its route must be on the writer roster in `.kxm/roles/writer.yaml`. Otherwise the drive hands the run off with `step_unsupported`. Around each live attempt the Runtime fingerprints the checkout with `git status` and `git diff`: a write step settles `passed` only when the checkout changed (routing metadata `authored: true`), and a read-only step that changed it settles `failed` (`authoringWitness: readonly_mutated`).
 
 | Option | Argument | Default | Description |
 |---|---|---|---|
@@ -2843,7 +2861,7 @@ Recommends a flat workflow ID backed by a shipped template, with category metada
 
 - Explicit `Claude only`, `Claude-only`, or `only Claude Code` constraints exclude other harnesses. A missing, unauthenticated, or unsupported required harness produces `harness_unavailable`; KXM never silently substitutes Grok or Codex.
 - A write workflow requires an audited writer profile for the selected harness. Only Pi and Grok currently have one; Claude-only bug fixes produce `live_write_unsupported` with direct-Claude implementation guidance, never a Grok substitution. No misleading create/drive command is emitted for an unsupported profile.
-- For supported work, every suggested agent binding uses the selected detected, authenticated, dispatch-ready harness. Configure its compatible admitted model, install the exact template, validate project configuration, then use the separate create/live-drive/status/receipt commands. Writers also require single-assignment/single-run admission, any configured developer-roster writer approval, and the repository's actual verification gate. An already-present recommended workflow ID produces `workflow_already_exists`; KXM will not assume its agents or permissions match the template.
+- For supported work, every suggested agent binding uses the selected detected, authenticated, dispatch-ready harness. Configure its compatible admitted model, install the exact template, validate project configuration, then use the separate create/live-drive/status/receipt commands. Writers also require single-assignment/single-run admission, any configured developer policy writer approval, and the repository's actual verification gate. An already-present recommended workflow ID produces `workflow_already_exists`; KXM will not assume its agents or permissions match the template.
 - Arguments: `<prompt...>`; no command-specific options. No hub needed. `--dry-run` skips native authentication probes to avoid their side effects and does not claim verified availability.
 - JSON keys: `prompt`, `workflowId`, `template`, `area`, `confidence`, `reasons`, `suggestedSkills`, `roles` (an array of `{agent, harness, role}`), `suggestedCommand` (installation only), and `execution`. Supported execution includes `prerequisites`, `shell`, `createCommand`, `driveCommand`, `statusCommand`, and `receiptCommand`; refusal includes `error`, `reason`, and `nextSteps`, sets `ok: false`, and exits 1.