@kontextmind/kxm 0.7.128 → 0.7.131

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`.
 
@@ -1345,7 +1363,7 @@ dry run: resume workflow run wf_dry_run (stage: review)
 
 ## `kxm lane`
 
-One lane is one git worktree, one branch named the unit, and one recorded base sha. The record lives in the control checkout's state directory, `.kxm/state/lanes.json` (`kxm.lanes.v1`, mode 0600). The worktree path is `../<control-dir-basename>-<unit>`, next to the control checkout. Creating a lane resolves the base ref to a sha and does not fetch. There is no push, merge, pull request, or branch delete. Selecting a lane sets the discovery cwd to that lane's path and rebuilds workspace directories from it; `KXM_WORKDIR` still selects the workspace root when it is set, so the lane path is the workspace root only when `KXM_WORKDIR` is unset.
+One lane is one git worktree, one branch named the unit, and one recorded base sha. The record lives in the control checkout's state directory, `.kxm/state/lanes.json` (`kxm.lanes.v1`, mode 0600). The worktree path is `../<control-dir-basename>-<unit>`, next to the control checkout. Creating a lane resolves the base ref to a sha and does not fetch. There is no push, merge, pull request, or branch delete. Selecting a lane sets the discovery cwd to that lane's path and rebuilds workspace directories from it; `KXM_WORKDIR` still selects the workspace root when it is set, so the lane path is the workspace root only when `KXM_WORKDIR` is unset. A lane worktree of an already registered repository registers in the Runtime registry under that project: the same project id, its own control root and event store, and the same home runtime. A foreign clone with the same id is refused with `project_home_conflict`.
 
 ```text
 kxm lane create <unit> [--base <ref>]
@@ -1375,15 +1393,19 @@ Prints one line per lane: unit, branch, base sha, `dirty` (porcelain line count)
 
 ### `kxm lane status`
 
-The list row for one unit, plus `status` of `lastRunId` when the Runtime supervisor is already running and answers. Otherwise `status=unknown`. `kxm lane status` never starts the Runtime supervisor.
+The list row for one unit, plus `status` of `lastRunId` when the Runtime supervisor is already running and answers. Otherwise `status=unknown`. The text ends with `root=<path>`, the lane root that status read. JSON includes the same path as `root`. `kxm lane status` never starts the Runtime supervisor.
 
 Refusals (exit 1): `lane_missing`, `lane_unit_invalid`, `lanes_unreadable`.
 
 ### `kxm lane drop`
 
-Removes the worktree and the record. Refuses `lane_dirty` when porcelain is nonempty, and `lane_run_open` when `lastRunId` is set and that run is not `completed`, `failed`, or `cancelled`. `--force` overrides both. `git worktree remove --force` is used only with `--force`. The branch is not deleted; the text says so (`branchDeleted: false`). Unless `--force` is set, drop may start the Runtime supervisor to check whether the lane's last run is still open; `--dry-run` only attaches to a supervisor that is already running. `kxm lane status` never starts the supervisor.
+Removes the worktree and the record, and unregisters that lane root from the Runtime registry. When the supervisor is running, drop calls `POST /v1/projects/unregister`. A stopped supervisor is not an error: drop takes the registry write lock, deletes the row when that transaction still sees no live supervisor, and continues when the registry is absent. If the lock finds a live supervisor, drop uses the unregister route instead of editing the file. The route answers 409 `runtime_project_busy` when that root has an unsettled run, and 409 `runtime_project_has_lanes` when the root is the home row and other lanes are still registered, unless the body sets `force` to true. Refuses `lane_dirty` when porcelain is nonempty. Refuses `lane_run_open` when any run in the lane event store is not `completed`, `failed`, or `cancelled`. The text names each unsettled run id, and JSON includes `runIds`. That list is the same read as `kxm runs list` when the supervisor is running, and a direct read of the lane event store when the supervisor is stopped. A lane with no event store keeps the earlier check: `lane_run_open` when `lastRunId` is set and that run is not settled. `--force` overrides both refusals and sends `force: true` on the unregister request. `git worktree remove --force` is used only with `--force`. The branch is not deleted; the text says so (`branchDeleted: false`). Unless `--force` is set, the `lastRunId` check may start the Runtime supervisor. The event-store list only attaches to a supervisor that is already running. `--dry-run` only attaches and does not unregister. `kxm lane status` never starts the supervisor.
 
-Refusals (exit 1): `lane_missing`, `lane_dirty`, `lane_run_open`, `lane_git_failed`.
+`lane_run_open` also uses the detail `lane <unit> runs could not be read: <detail>` when the lane's project or store could not be read, so the drop fails closed and does not remove the worktree. `<detail>` is the error message, cut to 200 characters, or `run list failed` when the thrown value is not an `Error`. The unsettled-run details stay `lane <unit> run <ids> is unsettled` (with `runIds`) and `lane <unit> run <lastRunId> is <status>`.
+
+`lane_unregister_failed` uses the detail `lane <unit> could not be unregistered: <detail>`. `<detail>` is cut to 300 characters. It appears when a live supervisor refused the unregister or the request failed: the error message, `lane root could not be unregistered` when the failure is not an `Error`, or `runtime supervisor is live but could not be reached` when the registry lock finds a live supervisor that drop cannot attach to.
+
+Refusals (exit 1): `lane_missing`, `lane_dirty`, `lane_run_open`, `lane_git_failed`, `lane_unregister_failed`.
 
 ### `kxm lane run`
 
@@ -1638,8 +1660,8 @@ kxm runs status <runId> [--lane <unit>]
 Show the projected status of a run, including durable drive receipt state (open / receipt verified / unsettled / orphaned).
 
 - Arguments: `<runId>`, Run id. `--lane <unit>` discovers the project from that lane's worktree (`lane_missing` when the record or path is absent, `lane_unit_invalid` when the unit is not a KXM identifier, `lanes_unreadable` when the record cannot be read). Reads run state, but starts the supervisor if needed (not under `--dry-run`).
-- Text: `run <id>: <status> (workflow <id>, updated <time>)`, plus a drive line such as `drive <id>: open`, `completed (receipt verified)`, `unsettled <reason>`, `handoff`, `cancelled (<reason>)`, or `no receipt (orphaned)`.
-- JSON keys: `run` (`runId`, `status`, `workflowId`, `configRevision`, `updatedAt`, ...), `drive` (`driveId`, `mode`, `openedAt`, `receipt`, `verified`, `divergence`).
+- Text: `run <id>: <status> (workflow <id>, updated <time>)`, then `root <path>` (the checkout the status read, which is the lane worktree when `--lane` is set), plus a drive line such as `drive <id>: open`, `completed (receipt verified)`, `unsettled <reason>`, `handoff`, `cancelled (<reason>)`, or `no receipt (orphaned)`.
+- JSON keys: `projectRoot` (that same checkout), `run` (`runId`, `status`, `workflowId`, `configRevision`, `updatedAt`, ...), `drive` (`driveId`, `mode`, `openedAt`, `receipt`, `verified`, `divergence`).
 - Errors: `project_required`, `run_status_failed`, `run_status_io_failed` (exit 1).
 
 ```bash
@@ -1648,6 +1670,7 @@ kxm runs status run_a80e84c98f514299b82f0157f4537ea3
 
 ```text
 run run_a80e84c98f514299b82f0157f4537ea3: preparing (workflow default, updated 2026-09-23T17:47:29.682Z)
+root /work/proj
 ```
 
 With no supervisor running:
@@ -1666,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 |
 |---|---|---|---|
@@ -2838,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.
 

package/docs/reference/config-reference.md

@@ -25,13 +25,12 @@ Related pages:
 | `.kxm/project.yaml` | `kxm.project.v1` | Project identity, repositories, defaults, run limits | You; `kxm init` creates it | Yes |
 | `.kxm/repo/repo.yaml` (in each repository) | `kxm.repository.v1` | Per-repository definition | You; `kxm init` creates the control one | Yes, in the repository it describes |
 | `.kxm/project/env.yaml`, `.kxm/repo/env.yaml` | `kxm.environment.v1` | Portable, non-secret environment | You | Yes |
-| `.kxm/agents/<id>.yaml` | `kxm.agent.v1` | Agent harness, model, and permission ceilings | You; `kxm init` creates two | Yes |
+| `.kxm/agents/<id>.yaml` | `kxm.agent.v1` | Agent role and permission ceilings | You; `kxm init` creates two | Yes |
 | `.kxm/models/<id>.yaml` | `kxm.model.v2` | One model route (harness, vendor, status, permissions) | You; `kxm init` | Yes |
 | `.kxm/workflows/<id>.yaml` | `kxm.workflow.v1` | Ordered steps and typed transitions | You; `kxm init` creates `default` | Yes |
 | `.kxm/gates.yaml` | `kxm.gate-registry.v1` | The executable gate registry | You; `kxm init` creates it | Yes |
 | `.kxm/roles/<role>.yaml` | `kxm.role.v2` | Model rosters per role | You, `kxm role`, `kxm models` | Yes |
 | `.kxm/routes.yaml` | `kxm.routes.v2` | Admitted and disabled model routes | You, `kxm routes`, `kxm models` | Yes |
-| `.kxm/roster.yaml` | `kxm.developer-roster.v1` | Developer assignment roster for the KXM source repository | Maintainers | Yes, and it must be committed |
 | `.kxm/prices.yaml` | `kxm.prices.v1` | Dated, hash-pinned list prices | You | Yes |
 | `.kxm/models/inventory.yaml` | `kxm.model-inventory.v1` | Discovered model catalog | `kxm models inventory-refresh` only | Your choice (generated) |
 | `.kxm/config.yaml`, `~/.config/kxm/config.yaml` | `kxm.config.v1` | Personalization and hub auto-start | `kxm config set` | Project file: yes, unless ignored |
@@ -44,6 +43,8 @@ Related pages:
 | Claude Code plugin `userConfig` | Claude plugin manifest | Hub URL, token, agent identity for Claude Code | Claude Code, per user | No |
 | `<state root>/update.yaml` | `kxm.update.v1` | Updater settings | You | No (host-local) |
 
+The developer assignment runner reads `.kxm/roles/*.yaml` and `.kxm/models/*.yaml` at `refs/remotes/origin/main`.
+
 `kxm init` does not write a `.gitignore`. See
 [Workspace layout](#workspace-layout-tracked-ignored-and-state) for the entries
 to add.
@@ -57,17 +58,16 @@ to add.
 .kxm/workflows/<id>.yaml ── coordinator ──> .kxm/agents/coordinator.yaml
    │ steps[]
    ├─ kind agent | moa | approval | wait ──> .kxm/agents/<id>.yaml
-   │                                           ├─ harness ──> pi | claude | codex | grok | agy | kimi | deepseek
-   │                                           ├─ model ────> {provider, model} | {profile} | {tag}
-   │                                           │                                    └─> .kxm/models/<id>.yaml
+   │                                           ├─ role ──> .kxm/roles/<role>.yaml
+   │                                           │              └─ roster[].route ──> .kxm/models/<route>.yaml
+   │                                           │                                    (harness, model, vendor, permissions)
    │                                           └─ tools, repositories, network: permission ceilings
    └─ kind gate ──> .kxm/gates.yaml: command | artifacts-exist | reserved
 
 Live dispatch admission (checked by the Runtime for every attempt):
-   agent model "provider/model" ──> .kxm/routes.yaml: admitted and not disabled
-                                └─> .kxm/roles/<role>.yaml roster, if that file exists
-                                    (role = agent id; "writer" for agent "implementer")
-   developer assignments (scripts/assignment-run.mjs) ──> .kxm/roster.yaml routes + lineup
+   agent.role ──> .kxm/roles/<role>.yaml roster ──> .kxm/models/<route>.yaml
+   .kxm/routes.yaml holds only the admitted and disabled lists
+   developer assignments (scripts/assignment-run.mjs) ──> .kxm/roles/*.yaml and .kxm/models/*.yaml
 
 Cost accounting:
    producer token usage ──> .kxm/prices.yaml (dated today, hash verified) ──> list estimate
@@ -79,13 +79,14 @@ Cost accounting:
 | Check | Files it covers | Where it runs |
 |---|---|---|
 | Project bundle load: restricted YAML, JSON Schema, cross-file semantics | `project.yaml`, every `repo.yaml` and `env.yaml`, `agents/`, `models/`, `workflows/`, `gates.yaml`, `template-provenance.yaml`, plus the `roles/writer.yaml` cross-check | `kxm init` (validate mode), `kxm run` and `kxm run --dry-run`, `kxm trust`, every Runtime request |
+| Retired agent routing fields | `harness` or `model` on `.kxm/agents/<id>.yaml` | Loader refuses the file with `retired_agent_routing_fields` (`routing resolves from role; remove model and harness`) |
 | Workflow compile | `workflows/` | `kxm run` when it creates a run |
-| Runtime acceptance | Workflow steps, gate definitions, agent models, `routes.yaml`, `roles/` | `kxm runs drive` and live drives, per step |
+| Runtime acceptance | Workflow steps, gate definitions, the route selected from `agent.role`, `routes.yaml` (`admitted` and `disabled` only), `roles/` | `kxm runs drive` and live drives, per step |
 | Permission diff | The bundle only | `kxm trust diff`, `kxm trust check` |
 | Revisions pinned on every run | `configRevision` (the bundle), memory revision (`.kxm/memory` without `candidates/`, plus `.kxm/skills/promoted`), executor policy, tool policy (agent and step `tools` plus the gate registry) | `kxm run` |
 
 Nothing validates `routes.yaml`, `roles/` (other than `writer.yaml`),
-`roles`, `roster.yaml`, `prices.yaml`, `inventory.yaml`,
+`roles`, `the role files`, `prices.yaml`, `inventory.yaml`,
 `config.yaml`, `modes.yaml`, memory, tasks, goals, or webhook JSON during
 `kxm init`. Their own readers report problems when they run. None of them are
 part of `configRevision`, and `kxm trust check` does not see them: a change to
@@ -147,7 +148,7 @@ makes a directory a KXM project. Parser: `loadKxmProject` in
 | `description` | String, at most 2,000 characters | Optional | Display only |
 | `defaultWorkflow` | Identifier | Optional, `default` | Loader only: the named workflow must exist (`default_workflow_unknown`). `kxm run` always takes an explicit workflow. |
 | `defaultExecutor` | `local`, `ssh`, or `exe-dev` | Optional | Loader (`executor_unknown`); recorded in the run's executor-policy revision |
-| `defaultHarness` | `pi`, `claude`, `codex`, `grok`, `agy`, `kimi`, or `deepseek` | Optional, `pi` | Loader (`harness_unknown`); harness for agents without `harness`; fallback harness for live dispatch |
+| `defaultHarness` | `pi`, `claude`, `codex`, `grok`, `agy`, `kimi`, or `deepseek` | Optional, `pi` | Loader (`harness_unknown`); project default harness. An agent file does not set `harness`; that field is `retired_agent_routing_fields`. |
 | `repositories` | Array of 1 to 64 entries | Required | Loader, Runtime |
 | `repositories[].id` | Identifier | Required | Must be unique after case folding (`repository_id_collision`) |
 | `repositories[].role` | `control` or `member` | Required | Exactly one `control` (`control_repository_count`) |
@@ -166,8 +167,11 @@ makes a directory a KXM project. Parser: `loadKxmProject` in
 | `limits.maxAgentTimeMs` | Integer, 0 to 31,536,000,000 | Optional | Runtime refuses to drive any run while it is set (`limit_unsupported`); leave it out |
 | `limits.agentStepTimeoutMs` | Integer, 60,000 to 31,536,000,000 | Optional, 3,600,000 | Wall clock for one live agent or moa step when the step omits `timeoutMs`. The supervisor passes it to the one-shot producer. A step `timeoutMs` narrower than this wins; a wider step value is refused (`step_unsupported`, field `timeoutMs`) |
 
-The Runtime binds one project `id` to one control root per state root, so a
-second checkout with the same ID is refused with `project_home_conflict`.
+The Runtime binds a project `id` to one repository. A git worktree of that
+repository registers as a lane: the same id, its own control root, and the
+same home runtime. A foreign clone with the same id is refused with
+`project_home_conflict`. A registered root whose directory is gone is replaced
+when a new root for that id registers.
 
 Example (validated with `kxm init --json`, including a nested member checkout
 at `repositories/api`):
@@ -319,15 +323,21 @@ One file per agent; the filename is the agent ID that workflow steps
 reference. Schema: `schemas/agent.schema.json`; semantic checks in
 `validateBundle` in `plugins/kxm/src/project-config.ts`.
 
+An agent does not name a harness or a model. Routing starts at the agent's
+`role`, continues through `.kxm/roles/<role>.yaml`, and uses the selected
+`.kxm/models/<route>.yaml`. `harness` and `model` on an agent file fail load
+with `retired_agent_routing_fields`.
+
 | Field | Type and allowed values | Required, default | What reads it |
 |---|---|---|---|
 | `schema` | `kxm.agent.v1` | Required | Loader |
 | `purpose` | String, 1 to 2,000 characters | Required | Display; neutral in `kxm trust` |
+| `role` | Identifier | Optional | Loader: `.kxm/roles/<role>.yaml`, then the selected `.kxm/models/<route>.yaml` |
+| `effort` | `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, or `max` | Optional | Recorded on the agent. Dispatch effort comes from the attempt, not this field. |
+| `skills` | Unique identifiers, at most 64 | Optional | Skill names granted to the agent |
 | `instructions` | String, at most 16,000 characters | Optional | Not read by any code path yet. Step `instructions` are what reach the prompt. |
-| `harness` | `pi`, `claude`, `codex`, `grok`, `agy`, `kimi`, or `deepseek` | Optional, the project's `defaultHarness` | Loader (`harness_unknown`, harness and model pairing); live dispatch launches this harness |
-| `model` | One selector: `{provider, model}`, `{profile}`, or `{tag, capabilities}` | Optional | See [Model selectors](#model-selectors) |
 | `executor` | `local`, `ssh`, or `exe-dev` | Optional | Loader (`executor_unknown`); recorded in the executor-policy revision; no dispatch path selects an executor from it yet |
-| `tools.preset` | `coordinator`, `read-only`, `workspace-writer`, or `tests-writer` | Optional | Loader (`tool_preset_unknown`); pinned in the tool-policy revision |
+| `tools.preset` | `coordinator`, `read-only`, `workspace-writer`, or `tests-writer` | Optional | Loader (`tool_preset_unknown`): the preset must be registered. An agent `tools.preset` may only narrow the role preset. Enforcement of that rule is pending (P3). |
 | `tools.allow`, `tools.deny` | Unique identifiers, at most 128 each | Optional | A tool in both lists is `tool_policy_contradiction`; steps may only narrow the ceiling |
 | `defaultRepositoryAccess` | `none`, `read`, or `write` | Optional; the ceiling is `none` when absent | Loader: access ceiling for repositories not listed in `repositories` |
 | `repositories` | Map of repository ID to `none`, `read`, or `write`; at most 64 | Optional | Loader: per-repository access ceiling; IDs must be declared (`repository_unknown`) |
@@ -340,80 +350,24 @@ reference. Schema: `schemas/agent.schema.json`; semantic checks in
 | `session.maxIdleMs` | Integer, 0 to 31,536,000,000 | Optional | Not read by any code path yet |
 
 Tool presets are names checked against a registered list. The live one-shot
-producer launches each harness with a fixed argument set and does not
-translate `tools` into harness flags. A read-only step uses the read-only set
-(`READ_ONLY_ONESHOT_ARGS` in `plugins/kxm/src/harness.ts`). A step with `write`
-access uses the audited writer set (`WRITER_ONESHOT_ARGS`), which exists only
-for `pi` (`-a` with extensions, skills, prompt templates and sessions off) and
-`grok` (`--always-approve` with subagents and web search off). Both approve
-every tool call, shell commands included, and neither confines the process to
-the checkout. A live write step on any other harness is handed off; see
+producer launches the harness named by the selected model file, with a fixed
+argument set, and does not translate `tools` into harness flags. A read-only
+step uses the read-only set (`READ_ONLY_ONESHOT_ARGS` in
+`plugins/kxm/src/harness.ts`). A step with `write` access uses the audited
+writer set (`WRITER_ONESHOT_ARGS`), which exists only for `pi` (`-a` with
+extensions, skills, prompt templates and sessions off) and `grok`
+(`--always-approve` with subagents and web search off). Both approve every
+tool call, shell commands included, and neither confines the process to the
+checkout. A live write step on any other harness is handed off; see
 [Steps the Runtime does not execute yet](#steps-the-runtime-does-not-execute-yet).
 
-### Model selectors
-
-A selector has exactly one of three shapes (`common.schema.json#/$defs/modelSelector`):
-
-| Shape | Fields | Resolves to |
-|---|---|---|
-| Direct | `provider` (identifier), `model` (1 to 200 characters) | That provider and model. The route string is `provider/model`, for example `openrouter/qwen/qwen3-coder-plus`. |
-| Profile | `profile` (identifier) | `.kxm/models/<profile>.yaml` (`model_profile_unknown` if missing) |
-| Tag | `tag` (identifier), optional `capabilities` (identifiers) | Every profile carrying the tag and all listed capabilities (`model_tag_unresolved` if none) |
-
-For live dispatch, only the direct shape works. The Runtime reads the agent's
-`model.provider` and `model.model` and joins them into the route string; a
-profile or tag selector validates at load time but live dispatch refuses the
-step with `producer_route_unsupported: invalid model declaration`. An agent
-with no model is refused too, except that an agent named `implementer`
-without a model falls back to `xai/grok-4.6`.
-
-### Harness and model pairing
-
-The loader checks that the agent's harness can host its model, using
-`validateHarnessModelPair` in `plugins/kxm/src/harness.ts`. It applies this
-check only to models reached through a profile or tag selector. A direct
-`{provider, model}` selector is not checked at load time; the live producer
-checks it when it probes the harness before dispatch.
-
-| Harness | Accepts |
-|---|---|
-| `claude` | Provider `anthropic`; rejects model IDs starting with `gpt-`, `o1-`, `o3-`, `grok-`, `gemini-`, `kimi-`, `moonshot-`, `deepseek-`, or `qwen-` |
-| `codex` | Provider `openai`; rejects `claude-`, `fable-`, `grok-`, `gemini-`, `kimi-`, `moonshot-`, `deepseek-`, and `qwen-` models |
-| `grok` | Provider `xai` and `grok-` models |
-| `agy` | Provider `google` and `gemini-` models |
-| `kimi` | Provider `moonshot` and `kimi`, `moonshot`, or `kimi-for-coding` models |
-| `deepseek` | Provider `deepseek` and `deepseek-` models |
-| `pi` | Refuses a native vendor's model named directly, through the vendor's Pi provider or behind an aggregator, except `antigravity/gemini-…` (`pi_native_impersonation_blocked`); see [the brake](harness-routing.md#what-the-brake-refuses) |
-
-A mismatch is reported as `harness_unhosted_model`. Which route to choose for a
-model that more than one harness can reach is covered in
-[Harness routing](harness-routing.md).
-
-### Live dispatch requirements
-
-Before a live attempt, the Runtime (`resolveProducerRoute` in
-`plugins/kxm/src/engine.ts`) requires all of the following. A failure hands the
-run off with `step_unsupported` and a `producer_route_unsupported` detail.
-
-1. The agent declares a direct `{provider, model}` selector (see above).
-2. `provider/model` is listed in `.kxm/routes.yaml` `admitted` and not in
-   `disabled`.
-3. If `.kxm/roles/<role>.yaml` exists, its roster contains exactly
-   `provider/model`. The role is the agent ID, except that agent
-   `implementer` maps to role `writer`.
-
-Example (validated with `kxm init --json`):
+Example (the shape `kxm init` writes for `implementer`):
 
 ```yaml
-# .kxm/agents/implementer.yaml — the filename is the agent id.
+# .kxm/agents/implementer.yaml. The filename is the agent id.
 schema: kxm.agent.v1
 purpose: Implement the approved change within the declared repository scope.
-instructions: Keep changes inside the files named by the approved plan.
-harness: grok                     # pi | claude | codex | grok | agy | kimi | deepseek
-model:                            # direct selector: provider + model
-  provider: xai
-  model: grok-4.6
-executor: local                   # local | ssh | exe-dev
+role: writer                      # .kxm/roles/writer.yaml -> .kxm/models/<route>.yaml
 tools:
   preset: workspace-writer        # coordinator | read-only | workspace-writer | tests-writer
   allow: [read, edit, write, bash]
@@ -421,47 +375,26 @@ tools:
 defaultRepositoryAccess: none     # ceiling for repositories not listed below
 repositories:
   control: write
-  api: write
 secrets:
   - ref: npm-token                # secret reference name
     as: NPM_TOKEN                 # environment variable name inside the attempt
     required: false
 network: provider-only            # none | provider-only | restricted | host
 resultSchema: kxm.assignment-result.v1
-session:
-  reuse: compatible-run-scope
-  maxIdleMs: 1800000
 ```
 
-A critic that uses a profile selector:
-
-```yaml
-schema: kxm.agent.v1
-purpose: Architecture critic for the approved change.
-harness: claude
-model:
-  profile: critic-claude          # profile selector: .kxm/models/critic-claude.yaml
-tools:
-  preset: read-only
-defaultRepositoryAccess: read
-network: provider-only
-resultSchema: kxm.assignment-result.v1
-```
+`kxm init` creates `coordinator` (`role: planner`) and `implementer`
+(`role: writer`) without `harness` or `model`, and admits `anthropic/fable`
+and `xai/grok-4.6` in `.kxm/routes.yaml`. An interactive `kxm init` can add
+workflow-guide agents for reviewed pairs whose harness is authenticated, and
+admits their selectors too, but skips Google guide candidates because the
+Runtime cannot reach the `antigravity` Pi provider yet. `kxm run` and the
+Runtime read the agents. `kxm trust` diffs them.
 
-Error codes: `executor_unknown`, `harness_unknown`, `tool_preset_unknown`,
-`tool_policy_contradiction`, `repository_unknown`, `model_profile_unknown`,
-`model_tag_unresolved`, `harness_unhosted_model`,
-`pi_native_impersonation_blocked`, the path codes under
-[Rules shared by the project bundle](#rules-shared-by-the-project-bundle), and
-`role_roster_conflicts_with_agent` (see [Roles](#kxmrolesroleyaml-kxmrolev2)).
-
-Commands: `kxm init` creates `coordinator` (`claude`, `anthropic/fable`) and
-`implementer` (`grok`, `xai/grok-4.6`) and admits both selectors in
-`.kxm/routes.yaml`; an interactive `kxm init` can add workflow-guide agents for
-reviewed harness/model pairs whose harness is authenticated, and admits their
-selectors too, but skips Google guide candidates because the Runtime cannot
-reach the `antigravity` Pi provider yet; `kxm run` and the Runtime read them;
-`kxm trust` diffs them.
+Error codes: `retired_agent_routing_fields`, `executor_unknown`,
+`tool_preset_unknown`, `tool_policy_contradiction`, `repository_unknown`, and
+the path codes under
+[Rules shared by the project bundle](#rules-shared-by-the-project-bundle).
 
 ## `.kxm/models/<id>.yaml` (`kxm.model.v2`)
 
@@ -500,11 +433,11 @@ status: admitted
 permissions:
   - edit
 origin:
-  source: .kxm/roster.yaml
-  sha256: b2bd628604e8fec5afdff2a1f2c104ed14ff785686bb1f38272bc972a310c806
+  source: docs/reference/harness-routing.md
+  sha256: 321c821ed6dbce7b2e98309fdc29387671577049619b6979c685a7ba60c63337
 ```
 
-Commands: `kxm init`, `kxm run`, and `kxm trust` load these files. `kxm role modify --add-route` refuses a route id that has no file here (exit 1). Dispatch membership for a role reads `harness`, `model`, and `vendor`. The developer assignment runner still reads `.kxm/roster.yaml` until P2.
+Commands: `kxm init`, `kxm run`, and `kxm trust` load these files. `kxm role modify --add-route` refuses a route id that has no file here (exit 1). Dispatch membership for a role reads `harness`, `model`, and `vendor`. The developer assignment runner reads `.kxm/roles/*.yaml` and `.kxm/models/*.yaml` at `refs/remotes/origin/main`.
 
 ## `.kxm/workflows/<id>.yaml` (`kxm.workflow.v1`)
 
@@ -692,9 +625,8 @@ these, the run is handed off (`step_unsupported`, `gate_unsupported`, or
 - A live (non-simulated) step with `write` access to any repository when its
   agent's harness has no audited writer profile (only `pi` and `grok` have
   one), when `assignments.maximum` is above 1, when the project's
-  `limits.maxConcurrentRuns` is above 1, or when `.kxm/roster.yaml` exists and
-  is not a `kxm.developer-roster.v1` whose writer lineup admits that harness
-  and model with `edit` permission. The checkout witness can attribute a
+  `limits.maxConcurrentRuns` is above 1, or when `.kxm/roles/writer.yaml` does not
+  admit that route with `edit` permission. The checkout witness can attribute a
   change only to one writer at a time.
 - Gate steps with `assignments.allowedAgents`, any assignment count or
   `maxAttemptsPerAssignment` other than 1, `distinctBy`,
@@ -962,12 +894,10 @@ not this registry.
 One role. The filename is the role id. `kxm config` validation checks the file
 against `schemas/role.schema.json`.
 
-`listRoleBindings` reads `roster[].route`. Dispatch treats `implementer` as
-`writer` and requires the agent selector to be one of the selectors named by
-those route files (`model`, `vendor/model`, or `harness/model`). The writer
-cross-check (`role_roster_conflicts_with_agent`) does the same comparison
-against the `implementer` agent's model, or the `writer` agent when there is
-no implementer. `kxm role` reads and writes these files. A file without
+`listRoleBindings` reads `roster[].route`. An agent binds `role`, and dispatch
+resolves harness, model, and effort from that role's roster and the matching
+`.kxm/models/<route-id>.yaml` (`model`, `vendor/model`, or `harness/model`).
+`kxm role` reads and writes these files. A file without
 `schema: kxm.role.v2` is skipped by `kxm role`. A local file overrides a
 global one with the same id.
 
@@ -989,9 +919,10 @@ global one with the same id.
 | `policy.vendorIndependenceRequired`, `policy.maxTransitions`, `policy.requiresGateVerification` | Boolean, or a positive integer for `maxTransitions` | Optional | Recorded on the role |
 
 Roster order is preference. `kxm role list` shows the first route as the
-primary. The Runtime checks membership. The model that runs still comes from
-the agent file. The developer assignment runner still reads `.kxm/roster.yaml`
-until P2.
+primary. The Runtime checks membership. Harness, model, and effort resolve
+from the agent's `role` roster and that route's `.kxm/models/<route-id>.yaml`,
+never from the agent file. The developer assignment runner reads
+`.kxm/roles/*.yaml` and `.kxm/models/*.yaml` at `refs/remotes/origin/main`.
 
 ```yaml
 schema: kxm.role.v2
@@ -1026,11 +957,10 @@ unknown keys are ignored).
 | `schema` | `kxm.routes.v2` | Required | Anything else fails with `invalid .kxm/routes.yaml` |
 | `admitted` | Array of route strings | Required | Runtime route check; `kxm routes list`, `kxm routes count`; `kxm models` |
 | `disabled` | Array of route strings | Optional, `[]` | Runtime: a disabled route is refused even if admitted |
-| `roles` | Map of name to route strings | Optional, `{}` | Not read by any code path yet; shown only by `kxm routes list --json`, and preserved on rewrite. Role rosters live in `.kxm/roles/` |
 | `updatedAt` | ISO timestamp string | Optional | Rewritten by every CLI change |
 
-A route string is exactly the agent's `model.provider`, a slash, and
-`model.model`: `xai/grok-4.6`, `anthropic/fable`,
+A route string is derived from the selected model file's `vendor` and
+`model`, joined by a slash: `xai/grok-4.6`, `anthropic/fable`,
 `openrouter/qwen/qwen3-coder-plus`. When the file is missing, nothing is
 admitted and every live attempt is refused (`producer_route_unsupported`, or
 `producer_route_not_admitted` from the live producer). A leftover
@@ -1054,31 +984,29 @@ admitted:
   - xai/grok-4.6
   - openrouter/qwen/qwen3-coder-plus
 disabled: []
-roles:
-  implementer:
-    - xai/grok-4.6
 ```
 
-Validated with `kxm routes list --json` and `kxm routes count --json`.
+Validated with `kxm routes list --json` and `kxm routes count --json`. `policy` has `admitted` and `disabled`. Membership comes from `.kxm/roles/*.yaml`, not from this file.
 
 Commands: `kxm routes list|count|admit|disable` (`--dry-run` supported for
 changes), `kxm models` (interactive), the Runtime, and the live producer.
 Route changes are not part of `configRevision` and `kxm trust check` does not
 report them; review them in the pull request diff.
 
-## `.kxm/roster.yaml` (`kxm.developer-roster.v1`)
+## Developer assignment policy
 
-The developer roster for `scripts/assignment-run.mjs` (the `just` assignment
-recipes; see [Assignment runner](../contributing/assignment-runner.md)). It applies to the KXM
-source repository itself: the loader in `scripts/roster-policy.mjs` reads the
-copy committed at `HEAD` of the repository that contains the script, and
-refuses unless the worktree is clean, `HEAD` is an ancestor of
-`origin/main`, and the working file is byte-identical to the committed one.
-It has no dispatch authority in the project Runtime.
+The developer roster for `scripts/assignment-run.mjs` (`kxm assign`; see
+[Assignment runner](../contributing/assignment-runner.md)). It applies to the KXM
+source repository itself: the loader in `scripts/roster-policy.mjs` reads
+`.kxm/roles/*.yaml` and `.kxm/models/*.yaml` committed at `HEAD` of the
+repository that contains the script, and refuses unless the worktree is clean,
+`HEAD` is an ancestor of `origin/main`, and each working file is byte-identical
+to the committed one. It has no dispatch authority in the project Runtime.
+The assembled object has `routes`, `lineup`, `required_critics`, and `model_origins`.
 
 | Field | Type and allowed values | Notes |
 |---|---|---|
-| `schema` | `kxm.developer-roster.v1` | The five top-level keys are all required and no others are allowed |
+| source files | `.kxm/roles/*.yaml` (`kxm.role.v2`), `.kxm/models/*.yaml` (`kxm.model.v2`) | The loader assembles the object below from these files |
 | `routes.<id>` | Route ID matching `^[a-z0-9]+(?:-[a-z0-9]+)*$` | At least one route |
 | `routes.<id>.harness` | `grok`, `agy`, `claude`, `codex`, or `pi` | Other harnesses are refused (`unsupported harness`) |
 | `routes.<id>.model` | Token without whitespace | Native harnesses: a bare model ID. Pi: `openrouter/<vendor>/<model>`, `nous-portal/<vendor>/<model>`, or `antigravity/gemini-<id>` |
@@ -1098,8 +1026,7 @@ only`, `Pi critic/planner cannot edit`, `writer and critics must have
 independent vendors`, and `retired .kxm/roster.json present`.
 
 ```yaml
-# .kxm/roster.yaml — developer roster policy for scripts/assignment-run.mjs.
-schema: kxm.developer-roster.v1
+# Assembled by scripts/roster-policy.mjs from .kxm/roles/*.yaml and .kxm/models/*.yaml.
 routes:
   grok-native:                  # route id: lowercase words joined by "-"
     harness: grok
@@ -1130,7 +1057,7 @@ routes:
     permissions: [read-only]
     status: admitted
 lineup:                         # routes admitted for each role
-  writer: [grok-native, qwen-openrouter-pi]
+  writer: [grok-native, qwen-openrouter-pi, gemini-agy]
   planner: [fable-claude]
   reviewer-arch: [fable-claude]
   reviewer-cli: [sol-codex]
@@ -1688,7 +1615,7 @@ Everything under `.kxm/` at the project root falls into one of three groups.
 | Path | Group | Written by |
 |---|---|---|
 | `project.yaml`, `repo/`, `project/env.yaml`, `agents/`, `models/*.yaml` (except `inventory.yaml`), `workflows/`, `gates.yaml`, `template-provenance.yaml` | Tracked configuration (the bundle) | You and `kxm init` |
-| `roles/`, `routes.yaml`, `prices.yaml`, `modes.yaml`, `roster.yaml` | Tracked configuration outside the bundle | You and their commands |
+| `roles/`, `routes.yaml`, `prices.yaml`, `modes.yaml`, `the role files` | Tracked configuration outside the bundle | You and their commands |
 | `config.yaml` | Tracked if the project wants shared preferences; otherwise ignore it | `kxm config set` |
 | `memory/`, `skills/`, `candidates/`, `goals/` | Tracked durable records | Their commands |
 | `models/inventory.yaml` | Generated; track it if you want a reviewed snapshot | `kxm models inventory-refresh` |
@@ -1883,7 +1810,6 @@ updatedAt: '2026-09-23T00:00:00.000Z'
 admitted:
   - xai/grok-4.6
 disabled: []
-roles: {}
 ```
 
 Why each piece is there:
@@ -1899,8 +1825,8 @@ Why each piece is there:
   without a writable repository.
 - The workflow omits `limits.maxAgentTimeMs`; with it, the Runtime refuses to
   drive the run.
-- There is no `.kxm/roles/writer.yaml`. If you add one, it must list
-  `xai/grok-4.6`, or the loader reports `role_roster_conflicts_with_agent`.
+- `kxm init` writes `.kxm/roles/writer.yaml`. The role file is the writer
+  roster. An agent model is not checked against it.
 
 Validate and run it: