@kontextmind/kxm 0.7.144 → 0.7.146

package/docs/reference/config-reference.md

@@ -55,7 +55,7 @@ to add.
 .kxm/project.yaml ── repositories[] ──> .kxm/repo/repo.yaml (+ env.yaml) in each repository
    │ defaultWorkflow, defaultHarness, limits
    ▼
-.kxm/workflows/<id>.yaml ── coordinator ──> .kxm/agents/coordinator.yaml
+.kxm/workflows/<id>.yaml ── coordinator ──> .kxm/agents/planner.yaml
    │ steps[]
    ├─ kind agent | moa | approval | wait ──> .kxm/agents/<id>.yaml
    │                                           ├─ role ──> .kxm/roles/<role>.yaml
@@ -361,13 +361,14 @@ 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).
 
-Example (the shape `kxm init` writes for `implementer`):
+Example (the shape `kxm init` writes for `writer`):
 
 ```yaml
-# .kxm/agents/implementer.yaml. The filename is the agent id.
+# .kxm/agents/writer.yaml. The filename is the agent id, and it matches role.
 schema: kxm.agent.v1
 purpose: Implement the approved change within the declared repository scope.
 role: writer                      # .kxm/roles/writer.yaml -> .kxm/models/<route>.yaml
+aliases: [implementer]            # deprecated id; still resolves, with a warning
 tools:
   preset: workspace-writer        # coordinator | read-only | workspace-writer | tests-writer
   allow: [read, edit, write, bash]
@@ -383,9 +384,10 @@ network: provider-only            # none | provider-only | restricted | host
 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
+`kxm init` creates `planner` (`role: planner`, alias `coordinator`) and `writer`
+(`role: writer`, alias `implementer`) without `harness` or `model`, and admits
+`anthropic/fable` and `xai/grok-4.6` in `.kxm/routes.yaml`. The model files are
+`claude-fable` and `grok-grok-4-6`. 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
@@ -408,7 +410,8 @@ bytes.
 | Field | Type and allowed values | Required, default | What reads it |
 |---|---|---|---|
 | `schema` | `kxm.model.v2` | Required | Loader |
-| `id` | Kebab identifier, 1 to 64 characters | Optional; the filename is the id | Loader |
+| `id` | `<harness>-<model-slug>[-<provider>]`, 1 to 64 characters | Optional; the filename is the id | Loader. This repository's workforce lint requires the pattern |
+| `aliases` | Deprecated route ids, at most 16 | Optional | Still resolve to this file; a warning names the canonical id |
 | `harness` | Identifier, 1 to 64 characters | Required | Developer ceilings and dispatch membership |
 | `model` | String, 1 to 200 characters | Required | Dispatch membership (`model`, `vendor/model`, `harness/model`) |
 | `vendor` | String, 1 to 64 characters | Required | The lab that trained the model, not the biller |
@@ -425,7 +428,8 @@ bytes.
 
 ```yaml
 schema: kxm.model.v2
-id: grok-native
+id: grok-grok-4-7          # <harness>-<model-slug>; "." in the model id is "-"
+aliases: [grok-native]     # deprecated id; still resolves, with a warning
 harness: grok
 model: grok-4.7
 vendor: xai
@@ -666,11 +670,11 @@ the reason, field, and detail. The Runtime uses these reasons:
 | `gate_uncertain_blocked` | The run is `blocked_uncertain` and waits for an external signal or an operator |
 
 Example (validated with `kxm init --json` and compiled with
-`compileKxmWorkflow`). Besides the `implementer` and `critic-arch` agents and
-the `critic-claude` profile shown above, it needs a `coordinator` agent, a
-`planner` agent (harness `claude`, model `anthropic/fable`, read access), a
-`critic-cli` agent (harness `codex`, model `openai/gpt-5.6-sol`, read access),
-and a second profile tagged `critic`, `critic-sol` (`openai/gpt-5.6-sol`).
+`compileKxmWorkflow`). Besides the `writer` and `reviewer-arch` agents and
+the `critic-claude` profile shown above, it needs a `planner` agent (the
+workflow coordinator; `coordinator` still resolves as an alias), a
+`reviewer-cli` agent, and a second profile tagged `critic`, `critic-sol`
+(`openai/gpt-5.6-sol`). Routes, not agent files, name the harness and model.
 The two providers among the `critic` candidates satisfy
 `distinctBy: [provider]` with `target: 2`.
 
@@ -678,7 +682,7 @@ The two providers among the `critic` candidates satisfy
 # .kxm/workflows/review.yaml — the filename is the workflow id.
 schema: kxm.workflow.v1
 description: Plan, implement, review with two critics, verify, approve, and wait for CI.
-coordinator: coordinator            # agent id; defaults to "coordinator"
+coordinator: planner               # agent id; omitted value falls back to "coordinator", an alias of planner
 limits:
   maxTransitions: 12                # required once any back-edge exists
   maxRunDurationMs: 14400000
@@ -688,7 +692,7 @@ planHash:                           # capture the approved plan when "plan" pass
   stageId: plan
   evidenceKey: plan
 requirePlanHash:                    # writing steps after "plan" must be listed here
-  - implement
+  - writer
   - verify
 steps:
   - id: plan
@@ -704,19 +708,20 @@ steps:
       - key: plan
         kind: artifact
     on:
-      passed: implement             # shorthand transition: a step id
+      passed: writer                # shorthand transition: a step id
       blocked:
         target: $terminal
         terminalStatus: failed
 
-  - id: implement
+  - id: writer
     kind: agent
-    agent: implementer
+    agent: writer
+    aliases: [implement]
     maxAttempts: 3
     repositories:
       control: write
     assignments:
-      allowedAgents: [implementer]
+      allowedAgents: [writer]
       minimum: 1
       target: 1
       maximum: 1
@@ -734,13 +739,13 @@ steps:
 
   - id: review
     kind: moa                       # panel of agents
-    agent: critic-arch              # primary agent; must be in allowedAgents
+    agent: reviewer-arch            # primary agent; must be in allowedAgents
     model:
       tag: critic                   # intersected with each agent's own model ceiling
     repositories:
       control: read
     assignments:
-      allowedAgents: [critic-arch, critic-cli]
+      allowedAgents: [reviewer-arch, reviewer-cli]
       minimum: 2
       target: 2
       maximum: 2
@@ -754,14 +759,14 @@ steps:
         kind: assignment-result
         producerPolicy:
           minimumProducers: 2
-          eligibleAgents: [critic-arch, critic-cli]
+          eligibleAgents: [reviewer-arch, reviewer-cli]
           acceptedStatuses: [passed]
           degradation:
             minimumProducers: 1
     on:
       passed: verify
       changes-requested:            # back-edge: needs maxTransitions
-        target: implement
+        target: writer
         maxTransitions: 2
 
   - id: verify
@@ -777,7 +782,7 @@ steps:
     on:
       passed: approve
       implementation-failure:
-        target: implement
+        target: writer
         maxTransitions: 2
 
   - id: approve
@@ -807,9 +812,9 @@ steps:
         terminalStatus: failed
 ```
 
-This example validates, but a live drive would be handed off at `implement`
-(write access), at `review` (`critic-arch` uses a profile selector), and at
-`approve` and `ci` (dispatched to `coordinator`, which declares no model). Use
+This example validates, but a live drive would be handed off at `writer`
+(write access), at `review` (`reviewer-arch` uses a profile selector), and at
+`approve` and `ci` (dispatched to `coordinator`, which resolves to `planner`). Use
 it as a field reference; the
 [worked example](#worked-example-a-minimal-two-step-project) is one that runs.
 
@@ -822,7 +827,7 @@ compiles and pins the plan, then drives it live, or without models with
 `kxm workflow add <id>` a one-step scaffold, under `.kxm/workflows/` (or
 `~/.config/kxm/workflows/` with `--scope global`, which the loader never
 reads). Both are valid `kxm.workflow.v1` definitions that use only what
-`kxm init` creates: the `coordinator` and `implementer` agents, the `control`
+`kxm init` creates: the `planner` and `writer` agents (`coordinator` and `implementer` remain aliases), the `control`
 repository, and the `test` gate. The templates route gate failures on
 `implementation-failure`. A local add is checked by the project loader first:
 if the project would not load with the new file, it is refused with
@@ -931,9 +936,9 @@ purpose: writer
 permission: edit
 description: Primary implementation agent.
 roster:
-  - route: grok-native
+  - route: grok-grok-4-7
     effort: medium
-  - route: qwen-openrouter-pi
+  - route: pi-qwen3-coder-plus-openrouter
     effort: medium
 ```
 
@@ -1027,50 +1032,51 @@ independent vendors`, and `retired .kxm/roster.json present`.
 
 ```yaml
 # Assembled by scripts/roster-policy.mjs from .kxm/roles/*.yaml and .kxm/models/*.yaml.
+# Route ids are <harness>-<model-slug>[-<provider>]. The first critic in each
+# lineup is the required critic. Later entries are read-only fallbacks.
 routes:
-  grok-native:                  # route id: lowercase words joined by "-"
+  grok-grok-4-7:
     harness: grok
-    model: grok-4.6             # native harnesses take a bare model id
+    model: grok-4.7             # native harnesses take a bare model id
     vendor: xai
     roles: [writer]
     permissions: [edit]
     status: admitted            # admitted | retired
-  qwen-openrouter-pi:
+  pi-qwen3-coder-plus-openrouter:
     harness: pi
     model: openrouter/qwen/qwen3-coder-plus   # Pi: allowed provider prefix + vendor/model
     vendor: alibaba
     roles: [writer]
     permissions: [edit]
     status: admitted
-  fable-claude:
+  claude-fable:
     harness: claude
     model: fable
     vendor: anthropic
     roles: [planner, reviewer-arch]
     permissions: [read-only]
     status: admitted
-  sol-codex:
+  codex-gpt-5-6-sol:
     harness: codex
     model: gpt-5.6-sol
     vendor: openai
     roles: [reviewer-cli]
     permissions: [read-only]
     status: admitted
-lineup:                         # routes admitted for each role
-  writer: [grok-native, qwen-openrouter-pi, gemini-agy]
-  planner: [fable-claude]
-  reviewer-arch: [fable-claude]
-  reviewer-cli: [sol-codex]
+lineup:                         # routes admitted for each role, preference order
+  writer: [grok-grok-4-7, pi-qwen3-coder-plus-openrouter, agy-gemini-3-8-flash-high, agy-gemini-3-8-flash-medium]
+  planner: [claude-fable, pi-qwen3-8-flash-openrouter]
+  reviewer-arch: [claude-fable, pi-glm-5-3-flash-openrouter]
+  reviewer-cli: [codex-gpt-5-6-sol, pi-qwen3-8-flash-openrouter]
 required_critics:
-  review-arch: fable-claude
-  review-cli: sol-codex
+  review-arch: claude-fable
+  review-cli: codex-gpt-5-6-sol
 model_origins:                  # required for every Pi route model
   openrouter/qwen/qwen3-coder-plus:
     vendor: alibaba
     evidence:
-      source: docs/workflow-guide.md
-      commit: 69341ca200c31b98b5ba2371437398f0ce501089
-      sha256: 358d436dbf1b6f3904252afba167e643d33d597d16148ac1286b1c21b81448a4
+      source: plans/evidence/route-qwen-openrouter-pi.md
+      sha256: b15f8a54adc398b33e75609e959076eee310bf4ff6623d0b8470ea3da95e6c54
 ```
 
 Validated with `validateRosterDocument` from `scripts/roster-policy.mjs`,
@@ -1685,8 +1691,8 @@ Directory layout (inside a Git repository):
 └── .kxm/
     ├── project.yaml
     ├── repo/repo.yaml
-    ├── agents/coordinator.yaml
-    ├── agents/implementer.yaml
+    ├── agents/planner.yaml
+    ├── agents/writer.yaml
     ├── gates.yaml
     ├── routes.yaml
     └── workflows/default.yaml
@@ -1717,11 +1723,13 @@ repositoryId: control
 defaultAccess: write
 ```
 
-`.kxm/agents/coordinator.yaml` (every workflow needs its coordinator agent):
+`.kxm/agents/planner.yaml` (every workflow needs its coordinator agent):
 
 ```yaml
 schema: kxm.agent.v1
 purpose: Coordinate the pinned workflow.
+role: planner
+aliases: [coordinator]
 tools:
   preset: coordinator
 defaultRepositoryAccess: read
@@ -1731,15 +1739,13 @@ network: provider-only
 resultSchema: kxm.assignment-result.v1
 ```
 
-`.kxm/agents/implementer.yaml`:
+`.kxm/agents/writer.yaml`:
 
 ```yaml
 schema: kxm.agent.v1
 purpose: Implement the requested change in the control repository.
-harness: grok
-model:
-  provider: xai
-  model: grok-4.6
+role: writer
+aliases: [implementer]
 tools:
   preset: workspace-writer
 defaultRepositoryAccess: none
@@ -1765,13 +1771,14 @@ gates:
 ```yaml
 schema: kxm.workflow.v1
 description: Implement a change, then run the test suite.
-coordinator: coordinator
+coordinator: planner
 limits:
   maxTransitions: 4
 steps:
-  - id: implement
+  - id: writer
     kind: agent
-    agent: implementer
+    agent: writer
+    aliases: [implement]
     maxAttempts: 2
     repositories:
       control: write
@@ -1798,7 +1805,7 @@ steps:
         target: $terminal
         terminalStatus: completed
       implementation-failure:
-        target: implement
+        target: writer
         maxTransitions: 2
 ```
 
@@ -1814,11 +1821,11 @@ disabled: []
 
 Why each piece is there:
 
-- `implement` routes a failure straight to a terminal `failed` status and
+- `writer` routes a failure straight to a terminal `failed` status and
   declares `failed`, the outcome the producer falls back to.
 - `verify` declares `implementation-failure`, the outcome a failing command
   produces. Routing that edge on `failed` instead is refused when the project
-  loads (`gate_outcome_impossible`). The edge back to `implement` makes it a
+  loads (`gate_outcome_impossible`). The edge back to `writer` makes it a
   back-edge, so it carries `maxTransitions: 2` and the workflow carries
   `limits.maxTransitions`.
 - The gate step lists `control: write`; the Runtime refuses command gate steps
@@ -1841,9 +1848,9 @@ kxm runs drive <runId> --simulated --wait    # model-free drive; runs npm test f
 
 The simulated drive records `passed` for the agent step, runs `npm test` in the
 project root, and settles `completed` when it exits 0. When `npm test` fails,
-the run returns to `implement` and fails with `budget_step_attempts` once
-`implement` has used its two attempts. A live drive of this workflow is refused
-today, because the `implement` step has write access (see
+the run returns to `writer` and fails with `budget_step_attempts` once
+`writer` has used its two attempts. A live drive of this workflow is refused
+today, because the `writer` step has write access (see
 [Steps the Runtime does not execute yet](#steps-the-runtime-does-not-execute-yet)).
 Stop the Runtime afterwards with `kxm runtime stop`.
 

package/docs/reference/harness-routing.md

@@ -117,7 +117,7 @@ role: writer
 
 ### Model file
 
-This is the native route, from `.kxm/models/grok-native.yaml`:
+This is the native route, from `.kxm/models/grok-grok-4-7.yaml` (alias `grok-native`):
 
 ```yaml
 harness: grok
@@ -151,14 +151,15 @@ permission: edit
 description: Primary implementation agent.
 # Rotation priority = order. Effort default: medium for implementation.
 roster:
-  - route: grok-native
+  - route: grok-grok-4-7
     effort: medium
-  - route: qwen-openrouter-pi
+  - route: pi-qwen3-coder-plus-openrouter
     effort: medium
-  - route: gemini-agy
+  - route: agy-gemini-3-8-flash-high
+  - route: agy-gemini-3-8-flash-medium
 ```
 
-`grok-native` resolves to `.kxm/models/grok-native.yaml`: harness `grok`, model `grok-4.7`, vendor `xai`, status `admitted`, permission `edit`. `qwen-openrouter-pi` is harness `pi`, model `openrouter/qwen/qwen3-coder-plus`, vendor `alibaba`. `gemini-agy` is harness `agy`, model `gemini-3.8-flash-high`, vendor `google`. `kxm role list` prints the first route id as the primary, for example `(grok-native)`.
+`grok-grok-4-7` resolves to `.kxm/models/grok-grok-4-7.yaml`: harness `grok`, model `grok-4.7`, vendor `xai`, status `admitted`, permission `edit`. `pi-qwen3-coder-plus-openrouter` is harness `pi`, model `openrouter/qwen/qwen3-coder-plus`, vendor `alibaba`. `agy-gemini-3-8-flash-high` is harness `agy`, model `gemini-3.8-flash-high`, vendor `google`. `kxm role list` prints the first route id as the primary, for example `(grok-grok-4-7)`. The previous ids (`grok-native`, `qwen-openrouter-pi`, `gemini-agy`) are aliases.
 
 Dispatch resolves a step from the agent `role`, then `.kxm/roles/<role>.yaml`, then the selected `.kxm/models/<route>.yaml`. That model file carries `harness`, `model`, `vendor`, `status`, and `permissions`. The engine walks the roster in order and uses the first admitted route whose model file is readable. A missing or unreadable model file is a refusal (`roster_model_unreadable` at load, `producer_route_unsupported` at dispatch), not a skip to the next entry. A route file that names a harness the model cannot run on still fails closed with `harness_unhosted_model`.
 

package/docs/reference/workflow-catalog.md

@@ -1096,9 +1096,9 @@ These three files live in this repository's `.kxm/workflows`. `kxm init` does no
 
 | Workflow | Runs through |
 |---|---|
-| `implement-only` | `kxm lane run`. Replaces a retired transport recipe. |
-| `review-arch-only` | `kxm lane run`. Replaces a retired transport recipe. |
-| `review-cli-only` | `kxm lane run`. Replaces a retired transport recipe. |
+| `writer-only` | `kxm lane run`. `implement-only` still resolves to this file. |
+| `reviewer-arch-only` | `kxm lane run`. `review-arch-only` still resolves to this file. |
+| `reviewer-cli-only` | `kxm lane run`. `review-cli-only` still resolves to this file. |
 
 ## Related
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kontextmind/kxm",
-  "version": "0.7.144",
+  "version": "0.7.146",
   "description": "KXM local-first multi-agent orchestration and operator dashboard",
   "type": "module",
   "author": "KontextMind",
@@ -45,11 +45,11 @@
     "typecheck": "tsc --noEmit",
     "lint:docs": "markdownlint-cli2",
     "check:versions": "node scripts/check-versions.mjs",
-    "check": "npm run typecheck && npm run lint:docs && npm run check:versions",
+    "check": "npm run typecheck && npm run lint:docs && npm run check:versions && node scripts/workforce-lint.mjs",
     "verify": "npm test && npm run check && npm run check:generated",
     "validate:claude": "claude plugin validate . --strict && claude plugin validate plugins/kxm --strict",
     "validate:ci": "npm run test:coverage && npm run check && npm pack --dry-run",
-    "validate:pr": "npm run build && npm run typecheck && node scripts/run-bounded.mjs 1200000 node --disable-warning=ExperimentalWarning --experimental-strip-types --test --test-force-exit --test-concurrency=4 test/core/artifacts-exist.test.ts test/core/ci-contract.test.ts test/core/envelope.test.ts test/core/envelope-contract.test.ts test/core/protocol.test.ts test/core/repo-root.test.ts test/core/routes-count.test.ts test/core/smoke.test.ts test/core/version-surfaces.test.ts && npm run check:versions && node scripts/check-generated.mjs",
+    "validate:pr": "npm run build && npm run typecheck && node scripts/run-bounded.mjs 1200000 node --disable-warning=ExperimentalWarning --experimental-strip-types --test --test-force-exit --test-concurrency=4 test/core/artifacts-exist.test.ts test/core/ci-contract.test.ts test/core/envelope.test.ts test/core/envelope-contract.test.ts test/core/protocol.test.ts test/core/repo-root.test.ts test/core/routes-count.test.ts test/core/smoke.test.ts test/core/version-surfaces.test.ts && npm run check:versions && node scripts/workforce-lint.mjs && node scripts/check-generated.mjs",
     "validate": "npm run validate:ci && npm run validate:claude",
     "test:packages": "npx nx run-many -t test --output-style=static",
     "check:packages": "npx nx run-many -t build,test:coverage,typecheck --output-style=static",

package/plugins/kxm/.claude-plugin/plugin.json

@@ -2,7 +2,7 @@
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "kxm",
   "displayName": "KXM",
-  "version": "0.7.144",
+  "version": "0.7.146",
   "description": "Headless multi-agent orchestration, durable workflows, and a live operator dashboard for Pi and Claude Code",
   "author": {
     "name": "KontextMind",