@kontextmind/kxm 0.6.0 → 0.7.10

package/.claude-plugin/marketplace.json

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

package/.kxm/agents/coordinator.yaml

@@ -0,0 +1,9 @@
+schema: kxm.agent.v1
+purpose: Coordinate the pinned workflow and emit schema-validated commands.
+tools:
+  preset: coordinator
+defaultRepositoryAccess: read
+repositories:
+  control: read
+network: provider-only
+resultSchema: kxm.assignment-result.v1

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

@@ -0,0 +1,13 @@
+schema: kxm.agent.v1
+purpose: Architecture critic for the approved workflow change.
+harness: claude
+model:
+  provider: anthropic
+  model: fable
+tools:
+  preset: read-only
+defaultRepositoryAccess: read
+repositories:
+  control: read
+network: provider-only
+resultSchema: kxm.assignment-result.v1

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

@@ -0,0 +1,13 @@
+schema: kxm.agent.v1
+purpose: CLI and verification critic for the approved workflow change.
+harness: codex
+model:
+  provider: openai
+  model: gpt-5.6-sol
+tools:
+  preset: read-only
+defaultRepositoryAccess: read
+repositories:
+  control: read
+network: provider-only
+resultSchema: kxm.assignment-result.v1

package/.kxm/agents/implementer.yaml

@@ -0,0 +1,13 @@
+schema: kxm.agent.v1
+purpose: Implement the approved change within the declared repository scope.
+harness: grok
+model:
+  provider: xai
+  model: grok-4.6
+tools:
+  preset: workspace-writer
+defaultRepositoryAccess: none
+repositories:
+  control: write
+network: provider-only
+resultSchema: kxm.assignment-result.v1

package/.kxm/gates.yaml

@@ -0,0 +1,8 @@
+schema: kxm.gate-registry.v1
+gates:
+  test:
+    kind: command
+    argv:
+      - npm
+      - test
+    timeoutMs: 3600000

package/.kxm/producers.yaml

@@ -0,0 +1,22 @@
+schema: kxm.producers.v1
+updatedAt: 2026-09-10T17:30:00.000Z
+promoted:
+  - anthropic/fable
+  - openai/gpt-5.6-sol
+  - xai/grok-4.6
+  - openrouter/qwen/qwen3-coder-plus
+demoted: []
+enabled:
+  - anthropic/fable
+  - openai/gpt-5.6-sol
+  - xai/grok-4.6
+  - openrouter/qwen/qwen3-coder-plus
+disabled: []
+roles:
+  implementer:
+    - xai/grok-4.6
+    - openrouter/qwen/qwen3-coder-plus
+  critic-arch:
+    - anthropic/fable
+  critic-cli:
+    - openai/gpt-5.6-sol

package/.kxm/project.yaml

@@ -0,0 +1,15 @@
+schema: kxm.project.v1
+id: prj_kxm_project
+name: KXM
+defaultWorkflow: default
+defaultExecutor: local
+defaultHarness: pi
+repositories:
+  - id: control
+    role: control
+    required: true
+    pathHint: .
+workspace:
+  dirtySnapshot:
+    untracked: ask
+    dirtySubmodules: fail

package/.kxm/roles/writer.yaml

@@ -0,0 +1,7 @@
+schema: kxm.role.v1
+id: writer
+roster:
+  - model: xai/grok-4.6
+    enabled: true
+  - model: openrouter/qwen/qwen3-coder-plus
+    enabled: true

package/.kxm/workflows/default.yaml

@@ -0,0 +1,47 @@
+schema: kxm.workflow.v1
+description: Canonical 4-stage KXM delivery workflow
+coordinator: coordinator
+limits:
+  maxTransitions: 8
+steps:
+  - id: implement
+    kind: agent
+    agent: implementer
+    maxAttempts: 3
+    on:
+      passed: review-arch
+      failed:
+        target: $terminal
+        terminalStatus: failed
+  - id: review-arch
+    kind: agent
+    agent: critic-arch
+    maxAttempts: 2
+    on:
+      passed: review-cli
+      failed:
+        target: implement
+        maxTransitions: 2
+  - id: review-cli
+    kind: agent
+    agent: critic-cli
+    maxAttempts: 2
+    on:
+      passed: verify
+      failed:
+        target: implement
+        maxTransitions: 2
+  - id: verify
+    kind: gate
+    gate: test
+    expect: pass
+    repositories:
+      control: write
+    maxAttempts: 2
+    on:
+      passed:
+        target: $terminal
+        terminalStatus: completed
+      failed:
+        target: implement
+        maxTransitions: 2

package/CHANGELOG.md

@@ -4,15 +4,36 @@ All notable user-facing changes are documented here. The project follows [Semant
 
 ## Unreleased
 
+## 0.7.0 - 2026-09-11
+
 ### Added
 
-- **Public npm release automation unlatched (E7):** Unlatched `publish-npm` job
-  in `.github/workflows/release.yml` with `environment: npm-publish`. Added
-  `scripts/kxm-publish-npm.mjs` to enforce fail-closed verification: requires the
-  GitHub release for the tag to be published (`draft: false`), validates the
-  release asset presence and SHA-256 digest against the release manifest, and
-  executes `npm publish --access public`. Added `publishConfig.access: "public"`
-  in root `package.json` and unit test suite `test/core/kxm-publish-npm.test.ts`.
+- **vNext Architecture Engine and Multi-Phase Isolation (Phases 0–4):**
+  - **Dead Route Brake (Phase 0):** Fails closed and asserts 404 on obsolete `/dispatch`
+    endpoint in supervisor API to eliminate legacy unmonitored dispatch routes.
+  - **Objective Propagation (Phase 1):** Propagates accepted run objectives into the producer
+    context packet with cryptographic SHA-256 hash validation against execution drift.
+  - **Dynamic Permission Ceilings (Phase 2):** Dynamically derives sandbox permissions from step
+    repository access declarations (`birthMember`), failing closed immediately on unauthorized
+    live write access outside declared repository scopes.
+  - **Pinned Route Admission & Roster Verification (Phase 3):** Strictly validates producer model
+    resolution (`step.model -> agent.model -> refuse`), enforcing model admission policies and role
+    roster alignment before birth.
+  - **Asynchronous Scheduler & Graceful Lifecycle (Phase 4):** Asynchronous `/drive` execution via
+    `VnextRunScheduler` returning `202 Accepted` with `/v1/runs/:id` poll endpoints, duplicate run
+    rejection (`409 Conflict`), and supervisor graceful shutdown that awaits active drives.
+- **Oneshot Harness Isolation, Pricing Safety & Async Probes:**
+  - Standardized one-shot harness execution across Anthropic Claude, OpenAI Codex, Kimi, and Google AGY
+    with unmetered subscription vs metered cost separation, process stdin piping, and timeout protection.
+- **Universal KontextMind Knowledge-Plane Skill Suite:**
+  - Portable, harness-agnostic skill suite under `.agents/skills/` including repository delivery skills,
+    context memory recall, and lifecycle governance.
+- **Pi Workflow Progress TUI & Studio Dashboard:**
+  - Interactive Pi extension workflow progress terminal user interface with live status bars and web studio layout.
+- **Public npm Release Automation Unlatched (E7):**
+  - Unlatched `publish-npm` job in `.github/workflows/release.yml` with `environment: npm-publish`.
+  - Added `scripts/kxm-publish-npm.mjs` verifying published GitHub release assets, digests, and
+    publishing to npm registry.
 
 ## 0.6.0 - 2026-09-08
 
@@ -109,6 +130,17 @@ All notable user-facing changes are documented here. The project follows [Semant
 
 ### Fixed
 
+- **Windows Claude Code / npm shim detection (issue #168):** `kxm harness list`
+  treated Claude Code as `not_detected` when the CLI was only an npm
+  `claude.cmd` shim (no `claude.exe` on `PATH`). The probe now tries `.exe`,
+  then the allowlisted inner package `claude.exe` next to `claude.cmd`, then
+  `.cmd` on win32. Allowlisted `name.cmd` probes still use `shell: true` and
+  record `windows_shim` when that is what answered. Auth still requires
+  parseable `claude auth status`. Headless assignment (`just assign` /
+  `harness-run`) scans every PATH directory for `name.exe` before any `.cmd`
+  (so a user-bin `codex.cmd` cannot hide `codex.exe`), then unwraps the inner
+  npm `claude.exe` and Pi's `node.exe` plus `cli.js`, without running
+  unverified `.cmd` launchers through a shell.
 - Concurrent Runtime registry and event-store initialization now checks and
   creates the schema under one write transaction, preventing duplicate-table
   failures when a supervisor and status reader first open the same database.

package/README.md

@@ -214,6 +214,7 @@ The hub routes messages; it does not merge contexts, choose tasks, or bypass too
 | Complete a Pi-to-Pi or Pi-to-Claude setup | [Getting started](docs/getting-started.md) |
 | Configure the hub or an agent | [Configuration reference](docs/configuration.md) |
 | Understand components and message flow | [Architecture](docs/architecture.md) |
+| Learn about agent skills | [Agent Skills](docs/agent-skills.md) |
 | Run the hub responsibly | [Operations guide](docs/operations.md) |
 | Fix connection or delivery problems | [Troubleshooting](docs/troubleshooting.md) |
 | See which behaviors and examples are verified | [Test matrix](docs/test-matrix.md) |

package/docs/README.md

@@ -8,6 +8,9 @@ This documentation is organized by task. Start with the guide that matches what
 | [Getting started](getting-started.md) | Pi and Claude Code users | Complete the first successful multi-agent exchange |
 | [Configuration](configuration.md) | Users and operators | Understand every supported setting and default |
 | [Architecture](architecture.md) | Maintainers and integrators | Learn the component boundaries and message lifecycle |
+| [Agent Skills](agent-skills.md) | Users and integrators | Comprehensive skill suite covering all KXM commands with progressive disclosure |
+| [Browser automation](browser-automation.md) | Developers and operators | Self-hosted Steel on DOKS, agent-browser, Playwright, pass-cli, and human takeover |
+| [Skills](skills.md) | Operators and skill authors | Governed candidate lifecycle; also the [repository work delivery](skills/repo-work-delivery.md) skill |
 | [Operations](operations.md) | Hub operators | Run, monitor, secure, and recover the service |
 | [Troubleshooting](troubleshooting.md) | Everyone | Diagnose common installation and delivery failures |
 | [Test matrix](test-matrix.md) | Users and maintainers | Map features and use cases to automated evidence |
@@ -15,8 +18,10 @@ This documentation is organized by task. Start with the guide that matches what
 | [Peer provenance and quorum gates](provenance-gates.md) | Workflow authors and security reviewers | Require durable replies from eligible peer identities without overstating the trust guarantee |
 | [Continuous improvement](continuous-improvement.md) | Product and engineering leads | Turn run evidence into reviewed workflow improvements |
 | [Workflow guide](workflow-guide.md) | Workflow designers and operators | Area -> Workflow -> Stage -> Role taxonomy with documentation slugs, dated research candidates, and selection policy |
+| [Templates](templates/README.md) | Workflow authors | Markdown templates for features, ADRs, reviews, runbooks, and related artifacts |
 | [Agent Envelopes & Quality Gates](agent-communication-envelopes-and-gates.md) | Multi-agent workflow engineers | Production communication envelopes, quality gates, and work loops |
 | [Assignment runner](assignment-runner.md) | Maintainers and developers | Native developer assignments, deterministic witness verification, and multi-vendor dual-critic acceptance |
+| [This host's Pi packages](operator-pi-packages.md) | Maintainers on this development host | Snapshot of operator `pi list` packages and file extensions; not a KXM install requirement |
 | [vNext contract package](vnext/README.md) | Maintainers and reviewers | Review the accepted local-first target architecture and implementation contracts |
 
 Project-level policies live at the repository root:

package/docs/adr/ADR-0002-browser-automation-steel-doks.md

@@ -0,0 +1,103 @@
+---
+schema: "kxm.doc.v1"
+id: "ADR-0002"
+type: "adr"
+title: "Self-Hosted Steel on DOKS for Reusable Browser Automation and Human Takeover"
+project: "kxm"
+status: "accepted"
+owner: "@operator"
+created: "2026-09-14"
+updated: "2026-09-14"
+authority: "decision"
+confidence: "verified"
+summary: "Adopt self-hosted Steel on DigitalOcean Kubernetes (DOKS) with agent-browser and Playwright as KXM's primary browser automation infrastructure."
+tags: ["architecture", "decision", "browser", "steel", "doks", "playwright"]
+related: ["docs/browser-automation.md", "docs/agent-skills.md"]
+details:
+  decision_drivers:
+    - "Eliminate per-minute SaaS browser provider costs"
+    - "Support unified same-session human takeover for MFA and sensitive authentication"
+    - "Provide dual exploratory (agent-browser) and regression (Playwright) interfaces"
+    - "Enforce strict credential isolation via pass-cli"
+  supersedes: null
+  superseded_by: null
+---
+
+# ADR-0002: Self-Hosted Steel on DOKS for Reusable Browser Automation
+
+## Context & Problem Statement
+
+AI coding agents and orchestration workflows in KXM require browser interaction for UI exploration, DOM mapping, bug reproduction, and end-to-end regression testing. Existing approaches suffered from three core issues:
+
+1. **High SaaS Costs**: Commercial cloud providers (e.g. Browserbase) charge steep per-session and per-minute pricing that conflicts with KXM's low-cost operating priority.
+2. **Disconnected Human Takeover**: When login challenges, MFA prompts, or CAPTCHAs occur, local or headless cloud browsers cannot easily hand the live session over to a human operator and seamlessly resume without destroying session state.
+3. **Tool Fragmentation**: Exploratory navigation needs a fast, token-efficient terminal CLI (`agent-browser`), while testing needs durable, assertion-rich frameworks (`Playwright`).
+
+## Decision Drivers
+
+1. **Operating Cost Control**: Keep infrastructure expenses predictable by utilizing our existing DigitalOcean Kubernetes Service (DOKS) cluster (`k8s-agentic-hub`).
+2. **Unified Same-Session Takeover**: Enable a human to interact with the exact same browser tab and session state during authentication gates before handing control back to the agent.
+3. **Dual Automation Interfaces**: Support `agent-browser` for discovery and `Playwright` for permanent regression tests over standard Chrome DevTools Protocol (CDP).
+4. **Authoritative Credential Management**: Ensure `pass-cli` remains the exclusive source of truth for secrets and API keys.
+
+## Considered Options
+
+- **Option A**: Self-hosted Steel (`steel-dev/steel-browser`) deployed on DOKS with Ingress-NGINX and TLS.
+- **Option B**: Paid SaaS browser providers (e.g., Browserbase, Steel Cloud).
+- **Option C**: Local headless Chrome instances spawned on developer workstations.
+
+## Evaluation & Tradeoff Matrix
+
+### Option A: Self-hosted Steel on DOKS (Chosen)
+
+- **Good, because**: Zero marginal per-session fees; fully self-hosted on our Kubernetes cluster.
+- **Good, because**: Built-in REST API, CDP WebSocket proxy, and live session viewer UI (`/ui`).
+- **Good, because**: Both `Playwright` and `agent-browser` connect seamlessly over standard CDP (`wss://steel.kontextmind.com/v1/devtools`).
+- **Good, because**: Dedicated shared memory (`/dev/shm`) and resource limits prevent workstation degradation.
+- **Bad, because**: Requires managing Kubernetes deployment and periodic orphaned session sweeping.
+
+### Option B: Paid SaaS Browser Provider
+
+- **Good, because**: Managed scaling and proxy pools.
+- **Bad, because**: Violates the core cost-efficiency constraint; introduces recurring credit card charges and third-party data transmission risks.
+
+### Option C: Local Chrome Instances
+
+- **Good, because**: No cluster deployment needed.
+- **Bad, because**: High workstation memory and CPU pressure; fragile cross-platform headless setups; cannot easily share live debug sessions across multi-agent environments.
+
+## Decision Outcome
+
+**Chosen Option**: **Option A (Self-hosted Steel on DOKS)**.
+
+### Architecture
+
+```text
+┌─────────────────────────────────────────────────────────────┐
+│                      KXM Agent / Herdr                      │
+│   (kxm-browser-session, kxm-browser-takeover, pass-cli)     │
+└───────────────┬─────────────────────────────┬───────────────┘
+                │ REST API (create/release)   │ CDP WebSocket
+                ▼                             ▼
+┌─────────────────────────────────────────────────────────────┐
+│                 DigitalOcean Kubernetes (DOKS)              │
+│                 https://steel.kontextmind.com               │
+│                                                             │
+│   ┌─────────────────────┐       ┌────────────────────────┐  │
+│   │   Steel API & CDP   │◄─────►│    Chromium Sandbox    │  │
+│   │     (Fastify)       │       │    (/dev/shm 2Gi)      │  │
+│   └──────────┬──────────┘       └────────────────────────┘  │
+│              │                                              │
+│              ▼                                              │
+│   ┌─────────────────────┐                                   │
+│   │   Session Viewer    │ ◄─── Human Takeover (MFA/Auth)    │
+│   │       (/ui)         │                                   │
+│   └─────────────────────┘                                   │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Confirmation & Verification Strategy
+
+- **Verification**: Health endpoint `https://steel.kontextmind.com/v1/health` verified with HTTP 200 and Let's Encrypt TLS.
+- **Integration Test**: `test/core/browser.test.ts` validates session lifecycle, CDP endpoint formatting, takeover transitions, and secret redaction.
+- **Security Check**: `pass-cli` verified as the authoritative store for `STEEL_API_KEY` under vault `AI Provider Keys`.

package/docs/agent-skills.md

@@ -0,0 +1,135 @@
+# KXM Agent Skills
+
+This document describes the bundled KXM Agent Skills suite: focused skills
+that cover current KXM top-level command groups. The suite documents the
+existing CLI. It does **not** land unified YAML role/project/workflow
+authority, admit new writers, or replace trusted `.kxm/roster.json` policy.
+
+## Feature-to-Skill Matrix
+
+| Feature Area | Skill | Commands Covered | Purpose |
+|---|---|---|---|
+| Core Routing | `kxm` | — | Select the right suite skill; state universal safety rules and portable CLI convention |
+| Project Setup | `kxm-project-setup` | `init`, `migrate`, `trust`, `config`, `completion` | Initialize, migrate, review permission changes, configure, and install shell completion |
+| Harness & Auth | `kxm-harness-auth` | `harness`, `auth`, `update`, `runtime`, `agent` | Inspect authenticated harness capability and operate supported runtimes/workers |
+| Hub Operations | `kxm-hub-ops` | `hub`, `backup`, `restore` | Run and protect the local hub and its durable SQLite state |
+| Session Management | `kxm-session` | `session`, `dash`, `studio` | Resume/inspect operator work and use UI capabilities each harness supports |
+| Peer Communication | `kxm-peer` | `peer` | Discover, send, poll/await, cancel, fan out, inbox, and reply safely |
+| Workflow Management | `kxm-workflow` | `workflow`, `gate` | Operate webhook workflows, waits/signals, evidence checkpoints, provenance |
+| Definitions | `kxm-definitions` | `role` | Manage role YAML through configuration commands; role edits do not grant trusted writer admission |
+| Run Management | `kxm-runs` | `run`, `runs` | Create and inspect local vNext runs while preserving execution boundaries |
+| Context & Memory | `kxm-context-memory` | `context`, `memory` | Query role-aware context and manage Git-authored memory proposals |
+| Skill Lifecycle | `kxm-skill-lifecycle` | `skills` | Govern candidate/evaluate/promote/reject/verify lifecycle |
+| Routing & Improve | `kxm-routing-improve` | `routing`, `improve` | Inspect real route quality/cost and propose reviewed improvements |
+| Tasks & Goals | `kxm-tasks` | `suggest`, `goal`, `task` | Recommend workflows and manage goals/tasks with SCM/tracker boundaries |
+
+## Browser Automation Skills
+
+KXM includes dedicated skills for remote browser automation on self-hosted Steel (DOKS), exploratory navigation via `agent-browser`, testing with `Playwright`, and visual feedback. See [Browser Automation Guide](browser-automation.md) and [ADR-0002](adr/ADR-0002-browser-automation-steel-doks.md).
+
+| Feature Area | Skill | Purpose |
+|---|---|---|
+| Browser Sessions | `kxm-browser-session` | Start, attach, inspect, and release Steel sessions on DOKS |
+| Human Takeover | `kxm-browser-takeover` | Handoff protocol for MFA, login, CAPTCHA, and sensitive consent |
+| Credentials & Profiles | `kxm-browser-auth` | Retrieve credentials from `pass-cli` and manage authenticated profiles safely |
+| Exploration | `kxm-browser-explore` | Exploratory navigation, DOM inspection, and workflow mapping via `agent-browser` |
+| Reproduction & Verify | `kxm-browser-verify` | Reproduce UI bugs, gather evidence, and author durable Playwright tests |
+| Diagnostics & Recovery | `kxm-browser-diagnostics` | Investigate Steel connectivity, CDP errors, timeouts, and orphan cleanup |
+| Section Annotation | `kxm-browser-annotate` | Capture DOM sections, attach structured annotations, and feed changes to agents |
+
+## Installation and Discovery
+
+### For Pi Users
+
+Pi automatically discovers skills in the `pi.skills` section of `package.json`. The KXM skills are included in the standard distribution:
+
+```json
+{
+  "pi.skills": [
+    "./plugins/kxm/skills"
+  ]
+}
+```
+
+### For Claude Users
+
+Claude plugins package the authored skills from `plugins/kxm/skills/` during the build process.
+
+### For Other Harnesses
+
+Skills in `.agents/skills/` follow the standard agent skill format. Discovery
+outside Pi and Claude remains harness-specific; do not assume every consumer
+loads this mirror.
+
+## Progressive Disclosure Usage
+
+1. Start with the core `kxm` skill to choose a specialized skill.
+2. Use the named skill for that command group.
+3. Teach only verbs and options that exist in `kxm <group> --help`.
+
+### Example Usage Patterns
+
+```bash
+kxm peer list --json
+kxm peer send --target alice --content "Please review" --json
+kxm workflow list --json
+kxm workflow checkpoint run_123 stage_a passed "Completed stage A" --json
+```
+
+## Verified vs Unverified Harness Limits
+
+### Verified Harnesses
+
+- **Pi**: Discovers `plugins/kxm/skills`
+- **Claude**: Plugin packaging of the authored skills
+- **Codex**: Consumes the generated `.agents/skills` mirror and AGENTS command block
+
+### Unverified Harnesses
+
+The following harnesses have discovery claims that remain explicitly unverified:
+
+- **Kimi**: `.agents/skills` consumer capability unverified
+- **Copilot**: Integration capability unverified
+- **OpenCode**: Compatibility unverified
+- **Other `.agents/skills` consumers**: Capabilities unverified
+
+## Distinguishing Operational vs Governed Skills
+
+### Bundled Operational Skills
+
+The skills in this suite (`kxm-*`) are bundled and operational by default. They map 1:1 with KXM's top-level command groups and are maintained as part of the core KXM distribution.
+
+### Governed Candidates
+
+Separately, `kxm skills` manages community or experimental candidates through
+create/evaluate/promote/reject/verify. Those governed skills are distinct from
+this bundled suite. Telemetry cannot auto-promote a skill. See
+[Skill candidate lifecycle](skills.md) for the full lifecycle, and
+[Repository work delivery](skills/repo-work-delivery.md) for converting a
+repository request into a delivery prompt.
+
+## Development and Maintenance
+
+### Authoring Location
+
+Skills are authored in `plugins/kxm/skills/` as the primary source of truth.
+
+### Generated Mirror
+
+`scripts/emit-codex-artifacts.mjs` copies owned skills byte-for-byte to
+`.agents/skills/` and leaves unrelated skills in that tree untouched. The
+suite manifest `plugins/kxm/skill-suite.json` is required; missing, symlink,
+or malformed manifests fail closed.
+
+### Build Process
+
+1. Validate `plugins/kxm/skill-suite.json`
+2. Replace owned generated skill directories
+3. Preserve foreign skills in `.agents/skills/`
+4. `scripts/check-generated.mjs` requires every owned mirror path
+
+### Testing
+
+- `test/core/skill-suite.test.ts` validates command coverage and mirrors
+- `test/core/commands-policy.test.ts` checks taught verbs against `cli.ts`
+- `test/core/generated-artifacts.test.ts` checks manifest-backed generated paths

package/docs/architecture.md

@@ -163,7 +163,7 @@ Workflow session isolation is a context-routing and accidental-cross-run safety
 
 | Path | Responsibility |
 |---|---|
-| `.kxm/config/` | Tracked workspace workflow and harness configuration |
+| `.kxm/` | Tracked workspace workflow and harness configuration |
 | `.kxm/logs/` | Ignored hub, worker, and Pi process logs |
 | `.kxm/assets/` | Intentional workflow inputs and outputs |
 | `.kxm/state/` | Ignored SQLite and restart-recovery state |

package/docs/assignment-runner.md

@@ -35,6 +35,17 @@ and models are admitted with strict permission and vendor boundaries:
   a requested harness/model is not in the admitted role lineup, or if permissions
   exceed the admitted ceiling (e.g. attempting to give edit permissions to a
   read-only reviewer).
+- **Trusted roster policy:** Dispatch (`assign` / `run`) and accept load
+  `.kxm/roster.json` through the trusted control Git loader
+  (`loadTrustedRosterPolicy`). Loader errors, missing/empty policy, and
+  malformed policy fail closed with `route_invalid`. There is no raw working-tree
+  JSON fallback and no null-policy acceptance. Tests may inject an explicit
+  policy object; that seam is not a CLI or environment bypass. The witness
+  verifies the bound candidate against the fixed gate (`npm run verify`) and
+  does not itself call the policy loader today. Unified YAML
+  role/project/workflow authority is still open and is not this runner's live
+  source. Passive `schemas/policy-draft` / `validatePolicyDraft` scaffolding is
+  not operator settings and is not admission.
 - **Deterministic witness beats extra models:** Implementers run `npm run verify`.
   Root re-runs the fixed witness. Reviewers verify candidate trees; they do not
   replace tests.
@@ -145,14 +156,16 @@ node scripts/assignment-run.mjs accept \
 
 `accept` validates all acceptance invariants:
 
-1. The commit exists and its tree matches the witness index tree.
-2. The writer record matches the latest passed witness.
-3. Both required critic roles (`review-arch` and `review-cli`) are present.
-4. Both critics judged the exact accepted tree and issued `PASS`.
-5. No unresolved `BLOCK` review exists for the tree in the task directory (unless
+1. Trusted roster policy is loaded and valid **before** acceptance artifacts are
+   written. Failure to obtain required policy refuses acceptance.
+2. The commit exists and its tree matches the witness index tree.
+3. The writer record matches the latest passed witness.
+4. Both required critic roles (`review-arch` and `review-cli`) are present.
+5. Both critics judged the exact accepted tree and issued `PASS`.
+6. No unresolved `BLOCK` review exists for the tree in the task directory (unless
    superseded by an unbroken `rework_of` lineage).
-6. The writer and all critics satisfy pairwise vendor independence.
-7. Writes `accepted.json` (`kxm.task-accepted.v1`) into the task directory.
+7. The writer and all critics satisfy pairwise vendor independence.
+8. Writes `accepted.json` (`kxm.task-accepted.v1`) into the task directory.
 
 ---
 
@@ -206,7 +219,7 @@ The runner fails closed with bounded error codes defined in `RUNNER_CODES`:
 
 | Code | Trigger condition | Remedy |
 |---|---|---|
-| `route_invalid` | Harness/model not admitted in lineup for the requested role, or permission exceeds route ceiling. | Check `.kxm/roster.json` lineup and permissions for the role. |
+| `route_invalid` | Harness/model not admitted in lineup for the requested role, permission exceeds route ceiling, or trusted roster policy cannot be loaded/validated. | Use a trusted clean control checkout; do not dispatch from a dirty implementation branch. Check `.kxm/roster.json` lineup and permissions for the role. |
 | `critic_invalid` | Missing required critic role, duplicate roles, wrong model, or vendor collision between writer and critics. | Ensure independent critics (Fable + Sol) from distinct providers. |
 | `critic_block` | An unresolved `BLOCK` verdict exists for the target tree. | Rework the changes, address findings, and pass review with a `rework_of` link. |
 | `commit_tree_mismatch` | Git commit tree does not equal the witnessed tree. | Commit the exact candidate tree verified by the witness before running accept. |