@kontextmind/kxm 0.7.95 → 0.7.97

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

@@ -0,0 +1,192 @@
+# Harness routing internals
+
+This page records how the KXM repository applies [harness routing](../reference/harness-routing.md) to its own work: the routes this checkout admits, its writer roster, its price catalog, and the developer roster policy that `just assign` and the dev helper enforce. It is maintainer material. The snapshots were captured on 2026-09-23 on one operator machine, from a source checkout where `node scripts/kxm.mjs` is the same program as `kxm`; they change whenever an admission changes.
+
+> [!IMPORTANT]
+> The files are the authority, not this page: `.kxm/routes.yaml`, `.kxm/roles/`, `.kxm/roster.yaml` and `.kxm/prices.yaml`. Product routing decisions are recorded under Tracking → Decided in `plans/implementation-plan.md`.
+
+## This checkout's routes and roster
+
+`node scripts/kxm.mjs role get writer`:
+
+```text
+schema: kxm.role.v1
+id: writer
+description: ""
+skills: []
+roster:
+  - model: xai/grok-4.6
+    effort: medium
+    enabled: true
+  - model: openrouter/qwen/qwen3-coder-plus
+    effort: medium
+    enabled: true
+  - model: zai-coding-cn/glm-5.3-flash
+    effort: medium
+    enabled: true
+  - model: qwen-token-plan/qwen3.8-flash
+    effort: medium
+    enabled: true
+  - model: google/gemini-3.8-flash-high
+    enabled: true
+```
+
+The implementer agent declares `harness: grok`, so of this roster only `xai/grok-4.6` can run under it; the Pi selectors need an agent without `harness:`.
+
+`node scripts/kxm.mjs routes list`:
+
+```text
+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.6
+admitted zai-coding-cn/glm-5.3
+admitted zai-coding-cn/glm-5.3-flash
+```
+
+`routes admit --model openrouter/qwen/qwen3-coder-plus --dry-run` exits 2 with `select a model from the refreshed inventory` even though that selector is already admitted, because the inventory never carries `openrouter/…` selectors. Selectors like these are admitted by a Git-reviewed edit of `.kxm/routes.yaml`.
+
+On the capture machine, `kxm harness list` showed `claude` detected but logged out (`dispatch no (not_authenticated)`), `deepseek` not installed, and `grok`, `codex`, `kimi` and `agy` ready.
+
+### Price catalog and inventory
+
+`.kxm/prices.yaml` is dated `2026-09-16`, so every current run records `providerMetadata.priceCatalogStale: true` and no list estimate. The list prices below come from `.kxm/models/inventory.yaml`, fetched `2026-09-16T14:54:53Z`, in USD per 1M tokens. The checkout has no routing records yet, so none of the examples has recorded latency; for latency, run a bounded side-by-side experiment and compare p50 and p95 in `kxm routing report`.
+
+## The developer roster (`.kxm/roster.yaml`)
+
+The issue-127 runner (`just assign`, see the [assignment runner](assignment-runner.md)) uses its own policy file, [`kxm.developer-roster.v1`](../reference/config-reference.md#kxmrosteryaml-kxmdeveloper-rosterv1). Routes there name the harness, the model and the vendor explicitly:
+
+```yaml
+  grok-native:
+    harness: grok
+    model: grok-4.6
+    vendor: xai
+  qwen-openrouter-pi:
+    harness: pi
+    model: openrouter/qwen/qwen3-coder-plus
+    vendor: alibaba
+```
+
+The developer roster policy (`scripts/roster-policy.mjs`) applies these rules:
+
+- A native route uses a bare model id.
+- A Pi route needs an allowlisted prefix: `openrouter`, `nous-portal` or `antigravity` (`scripts/harness-run.mjs`).
+- An aggregator id needs at least three segments.
+- The vendor segment of an aggregator id must not be a native vendor. `x-ai` counts as `xai` and `moonshotai` counts as `moonshot`.
+- `antigravity` ids must be exactly `antigravity/gemini-…`.
+- The writer and both critics must be three different vendors.
+
+Vendor independence has a consequence for Anthropic: the architecture critic is an Anthropic model, so no Anthropic route can be the writer through any harness, and `claude-bridge` stays experiment-only.
+
+### What the developer tools refuse
+
+The product layers are in [What the brake refuses](../reference/harness-routing.md#what-the-brake-refuses). The developer tools add two more:
+
+| Layer | Where | What it refuses | What you see |
+|---|---|---|---|
+| Dev helper | `scripts/harness-run.mjs` | A braked Pi provider, a Pi provider outside the allowlist, a Pi writer other than `openrouter/qwen/qwen3-coder-plus`, or an aggregator id whose vendor segment is a native vendor | `pi brake: xai has a native harness; refusing Pi impersonation`, or `… refusing to bill it through openrouter` |
+| Developer roster | `scripts/roster-policy.mjs` | An aggregator route whose vendor segment is a native vendor | `Roster policy refused: native vendor cannot use Pi` |
+
+The dev helper's allowlist (`openrouter`, `nous-portal`, `antigravity`) is a different list from `PI_ALLOWED_PROVIDERS` in `plugins/kxm/src/harness.ts`, which gates nothing. Which of the two should govern is an open decision (Tracking → Still open). Edit permission exists only in the dev helper, and only for admitted writer or experiment routes. The helper accepts only a ChatGPT login for codex, not an API key.
+
+The product brake, the dev helper and the roster policy now agree on the vendor segment: all three refuse `openrouter/x-ai/…` and `openrouter/anthropic/…`. They refuse the other native-vendor ids for different reasons. The product brake names `openai-codex/…`, `kimi-coding/…`, `claude-bridge/…` and `antigravity/claude-…` as a native vendor's own Pi provider; the helper and `validateRosterDocument` refuse them as unsupported Pi routes, because the provider is off the helper allowlist or `antigravity` is given a non-Gemini id (`unsupported Pi provider/model` in the roster policy). The product brake accepts `qwen-token-plan/…` and `zai-coding-cn/…`, which the developer tools do not allowlist.
+
+## Worked examples on this checkout
+
+These extend the generic examples on the reference page with this checkout's admissions, developer-roster routes, readiness on the capture machine, and inventory prices.
+
+### Grok 4.6
+
+| | Native `grok` | Pi + OpenRouter |
+|---|---|---|
+| Selector | `xai/grok-4.6`: admitted, and first in the writer roster | `openrouter/x-ai/grok-4.6`: not admitted |
+| Developer roster | `grok-native`, the writer route with `edit` | Refused: `native vendor cannot use Pi` |
+| Readiness | `grok` shows auth `yes` | `pi auth check --provider openrouter` returned `not_ready` |
+| Billing | grok.com subscription (OAuth) | $2.00 input, $6.00 output, $0.50 cached input |
+| Context | 500K (Pi's `xai` row; `grok models` does not print one) | 500,000 |
+
+Pi's own `xai` provider reported `ready` (OAuth) on the capture machine. When the grok quota runs out, the next writer in the lineup is `qwen-openrouter-pi`, a different vendor.
+
+### GPT-5.6 Sol
+
+| | Native `codex` | Pi + OpenRouter |
+|---|---|---|
+| Selector | `openai/gpt-5.6-sol`: admitted, the CLI critic | `openrouter/openai/gpt-5.6-sol`: not admitted |
+| Developer roster | `sol-codex`: `reviewer-cli`, `read-only` | Refused |
+| Billing | ChatGPT subscription | $2.00 input, $10.00 output, $0.20 cached input |
+| Context | Pi's `openai-codex` row, the same ChatGPT backend, lists 272K | 1,050,000 |
+
+In the inventory, `openai/gpt-5.6-sol` has sources `openrouter+nous` and carries OpenRouter prices. `pi auth check --provider openai-codex` reported `ready` on the capture machine.
+
+### Claude Fable
+
+| | Native `claude` | Pi + OpenRouter |
+|---|---|---|
+| Selector | `anthropic/fable`: admitted, planner and architecture critic | `openrouter/anthropic/claude-fable-5.1`: not admitted |
+| Developer roster | `fable-claude`: `planner` and `reviewer-arch`, `read-only` | Refused |
+| Readiness | Detected `yes`, auth `no`, dispatch `no (not_authenticated)` | `not_ready` |
+| Billing | claude.ai subscription | $10.00 input, $50.00 output, $0.25 cached input |
+| Context | 1M (Pi's `anthropic` row) | 1,000,000 |
+
+`claude` was logged out on the capture machine, so the native route failed closed. Pi's `anthropic` provider reported `ready` (OAuth). The `anthropic/fable` row in `prices.yaml` gives a list estimate only when the catalog is dated today.
+
+### Gemini 3.8 Flash
+
+| | Native `agy` | `antigravity` Pi provider | Pi + OpenRouter |
+|---|---|---|---|
+| Selector | `google/gemini-3.8-flash-high`: admitted, last in the writer roster | `antigravity/gemini-3.8-flash`: not admitted | `openrouter/google/gemini-3.8-flash`: not admitted |
+| Billing | Google subscription | Google subscription | $0.75 input, $3.75 output, $0.075 cached input |
+| Context | `agy` does not print it; the vendored catalog lists 1,048,576 | 1,048,576 | 1,048,576 |
+
+The admitted runtime route today is the `agy` selector.
+
+## Routing decisions for this repository
+
+### Google through `antigravity`
+
+The decision is that Google models run through the `antigravity` Pi provider, never through a shell-out to the `agy` CLI; `agy` stays a harness catalog and helper entry, not the admission path. Pi's `google/*` provider stays braked, and an `antigravity` route needs a signed-in `/login antigravity` inside Pi before it can be admitted. The dev helper and the roster policy accept only `antigravity/gemini-…`.
+
+The code differs from that decision: `.kxm/routes.yaml` admits `google/gemini-3.8-flash-*`, which can run only through `agy`, and the Runtime's Pi one-shot runs with `--no-extensions`, so it cannot reach `antigravity/…`. Until an antigravity route is admitted, do not add one on your own.
+
+### Vendors with no native harness
+
+| Model | Vendor-plan route | OpenRouter route | Notes |
+|---|---|---|---|
+| Qwen3.8 Flash | `qwen-token-plan/qwen3.8-flash`: admitted, in the writer roster; `ready` (`api_key`) | `openrouter/qwen/qwen3.8-flash`: admitted; $0.15 input, $0.47 output | `prices.yaml` gives both routes the same rates. Prefer the plan when it is authenticated. |
+| Qwen3 Coder Plus | none | `openrouter/qwen/qwen3-coder-plus`: $0.65 input, $3.25 output | The only admitted Pi writer: exact model, `edit` permission. |
+| GLM 5.3 and 5.3 Flash | `zai-coding-cn/glm-5.3` and `…/glm-5.3-flash`: admitted as failover critics and writer | `openrouter/z-ai/glm-5.3-flash`: admitted; $0.09 input, $0.30 output | Z.ai has no native harness. |
+| DeepSeek V4.1 Flash | `qwen-token-plan/deepseek-v4.1-flash`: admitted | `deepseek/deepseek-v4.1-flash` in the OpenRouter feed: $0.15 input, $0.60 output | Bills a DeepSeek model through Alibaba's plan, and passes the product brake because it names no vendor segment. An open admission question, not a precedent. |
+
+The developer runner is stricter. Its only Pi writer is `openrouter/qwen/qwen3-coder-plus`, and it does not allowlist `qwen-token-plan` or `zai-coding-cn`. Today OpenRouter is the right answer here for Qwen3 Coder Plus, Qwen3.8 Flash and GLM 5.3 Flash.
+
+### Nous
+
+`nous-portal/tencent/hy4-preview` is the reviewed experiment example, and it is not a writer. Pi on the capture machine listed `nous-portal/tencent/hy3-preview`, not `hy4-preview`, so check live ids before you use them. The dev helper does not allowlist `nous/…` or `nous-proxy/…`, and the roster policy refuses Portal routes to native vendors, just as it refuses the OpenRouter copies.
+
+## Troubleshooting the developer tools
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| `pi brake: xai has a native harness; refusing Pi impersonation` | A dev-helper request routed a native vendor through Pi. | Use the native harness recipe instead: `just impl`, `just plan`, `just review-arch` or `just review-cli`. |
+| `Roster policy refused: native vendor cannot use Pi` | A `.kxm/roster.yaml` Pi route names a native vendor, as in `openrouter/x-ai/…` or `nous-portal/anthropic/…`. | Remove the route. Only a native harness route is valid for that vendor. |
+| The dev helper refuses a codex route. | `codex` is logged in with an API key. | Run `codex login` with the ChatGPT flow. |
+
+For example, the native writer recipe:
+
+```bash
+just impl brief.md
+```
+
+## Related
+
+- [Harness routing](../reference/harness-routing.md): the rules, the decision procedure and the generic examples
+- [Assignment runner](assignment-runner.md): the loop that enforces the developer roster
+- [Configuration file reference](../reference/config-reference.md#kxmrosteryaml-kxmdeveloper-rosterv1): the `kxm.developer-roster.v1` fields
+- [Routing and cost telemetry contract](../contracts/routing.md): the routing record, cost basis and dev-helper telemetry

package/docs/{packages.md → contributing/packages.md}

@@ -1,10 +1,9 @@
 # Packages and workspaces
 
-Audience: maintainers adding or moving code in this repository.
-
-KXM ships one installable product (`@kontextmind/kxm`, loaded by Pi, the Claude
-Code plugin, and the MCP server) but is developed as a workspace, so a reusable
-component can be built, tested, and cached on its own.
+KXM ships one installable product, `@kontextmind/kxm`, which Pi, the Claude Code
+plugin and the MCP server all load. It is developed as an npm workspace so that a
+reusable component can be built, tested and cached on its own. This page is for
+maintainers who add or move code between packages.
 
 ## Layout
 
@@ -35,7 +34,7 @@ Current packages:
 
 | Package | Role | Consumers |
 |---|---|---|
-| `@kontextmind/tui` (`packages/core/tui`) | Reusable terminal components | `kxm dash`, configuration surfaces, `@kontextmind/kxm/tui` |
+| `@kontextmind/tui` (`packages/core/tui`) | Reusable terminal components | `kxm dash` (its ANSI theme); integrators through `@kontextmind/kxm/tui` |
 
 ## Commands
 
@@ -48,12 +47,10 @@ Current packages:
 | `npx nx run-many -t build,test` | Every package |
 | `npm run verify` | The commit gate: tests, checks, and generated-artifact parity |
 
-Bun runs tasks (`bun run build`, `bun x nx ...`) and is the recommended local
-runner. Installation and CI still resolve through `npm ci` and Node 22.19.0/24,
-because the hub, the CLI, and Pi's extension host are Node runtimes and
-`npm ci` is what the current CI legs execute. Moving the installer itself to Bun
-is a separate change with its own CI evidence; see
-[`plans/implementation-plan.md`](../plans/implementation-plan.md) **Still open**.
+Bun can run tasks locally (`bun run build`, `bun x nx ...`). Installation and CI
+still resolve through `npm ci` on Node 22.19.0 and 24, because the hub, the CLI
+and Pi's extension host are Node runtimes. Moving the installer itself to Bun is
+a separate change that needs its own CI evidence.
 
 ## Rules that keep the shape
 
@@ -86,6 +83,7 @@ These are gates, not preferences:
 
 ## Related
 
-- [Terminal components](tui-components.md) — the kit and its surface contract
-- [Architecture](architecture.md) — component boundaries
-- [Configuration](configuration.md) — what is settings versus shipped code
+- [Terminal components](tui-components.md): the kit and its surface contract
+- [Develop KXM](development.md): the commit gate and generated artifacts
+- [Architecture](../concepts/architecture.md): component boundaries
+- [Configuration](../reference/configuration.md): what is settings versus shipped code

package/docs/{skills → contributing}/repo-work-delivery.md

@@ -1,22 +1,23 @@
-# Repository Work Delivery Skill
+# Repository work delivery skill
 
-## Purpose
+`repo-work-delivery` turns an engineering request into an evidence-based,
+executable delivery prompt. It suits repository work that may need discovery,
+official documentation research, phased delivery, validation, pull requests,
+CI and review follow-through, policy-gated merge, and safe cleanup. This page is
+for contributors who use coding agents on this repository.
 
-`repo-work-delivery` is a reusable skill for converting an engineering request into an evidence-based, executable delivery prompt. It is designed for repository work that may need discovery, official documentation research, phased delivery, validation, pull requests, CI/review follow-through, policy-gated merge, and safe cleanup.
+The skill lives at `.agents/skills/repo-work-delivery/SKILL.md`. It is a
+repository-local skill: it is not part of the bundled suite in
+`plugins/kxm/skills/`, and it ships in neither the npm package nor the Claude
+plugin.
 
-The canonical skill is located at:
-
-```text
-.agents/skills/repo-work-delivery/SKILL.md
-```
-
-## What it does
+## What the skill requires
 
 The skill requires the executor to:
 
 - Inspect repository instructions, architecture, workflow guidance, CI, package manifests, and existing patterns.
 - Identify material ambiguity and ask focused questions only when repository evidence cannot safely resolve it.
-- Select the workflow recommended by the repository’s workflow guide.
+- Select the workflow recommended by the repository's workflow guide.
 - Assign explicit delivery roles, even when one agent performs several roles.
 - Use a one-shot workflow only for genuinely small, low-risk, self-contained changes.
 - Research fresh official documentation for every materially affected package, framework, SDK, platform, or API.
@@ -29,13 +30,10 @@ The skill requires the executor to:
 
 ## Workflow selection
 
-The skill first reads the repository workflow guide. For KXM, that includes:
-
-```text
-.agents/skills/kxm-workflow/SKILL.md
-```
-
-It chooses the least complex safe workflow prescribed by that guidance.
+The skill first reads the repository's workflow guidance. For KXM, that
+includes the `kxm-workflow` skill (`.agents/skills/kxm-workflow/SKILL.md`, the
+generated mirror of `plugins/kxm/skills/kxm-workflow/`). It chooses the least
+complex safe workflow that guidance prescribes.
 
 ### One-shot work
 
@@ -74,7 +72,7 @@ The skill asks the user only when unanswered details would materially affect beh
 
 ## Documentation standard
 
-For material dependencies, research uses official maintainer or other authoritative primary documentation for the repository’s actual version. The plan or PR records the source, version/date where available, retrieval date, and decision supported.
+For material dependencies, research uses official maintainer or other authoritative primary documentation for the repository's actual version. The plan or PR records the source, version/date where available, retrieval date, and decision supported.
 
 ## Merge and cleanup safety
 
@@ -103,5 +101,6 @@ A prompt produced with this skill includes:
 
 ## Related
 
-- [Agent Skills](../agent-skills.md) — bundled command-suite skills
-- [Skill candidate lifecycle](../skills.md) — governed `kxm skills` candidates
+- [Agent skills](../guides/agent-skills.md): the bundled command-suite skills
+- [Governed skills](../guides/governed-skills.md): `kxm skills` candidates
+- [Assignment runner](assignment-runner.md): how maintainers accept delegated work

package/docs/contributing/test-matrix.md

@@ -0,0 +1,208 @@
+# Test matrix
+
+This matrix maps each KXM behavior to the automated test that proves it. Use it
+to find where a behavior is covered before you change it, and add a row in the
+same pull request when you add a behavior. Test files are under `test/core/`
+unless a row names another path.
+
+Run the whole commit gate with `npm run verify`. What CI runs on a pull request,
+on `main` and nightly is described in [CI and release](ci-and-release.md); how
+to run one file is in [Develop KXM](development.md#run-one-file-or-one-test).
+
+## Hub and messaging
+
+| Behavior | Evidence |
+|---|---|
+| Health, readiness, metrics, request IDs and security headers | `hub-api.test.ts` |
+| Shared and per-project authentication, and project isolation | `hub-api.test.ts` |
+| Registration, discovery, presence, stale detection and identity resumption | `hub-api.test.ts`, `hub.test.ts` |
+| SQLite persistence, restart recovery and schema compatibility | `hub-api.test.ts`, `store.test.ts` |
+| Delivery modes, message fields, hop limits and validation | `hub-api.test.ts`, `protocol.test.ts` |
+| Queue, acknowledgement, visibility, reply and authorization | `hub-api.test.ts`, `hub.test.ts` |
+| An unacknowledged (queued) message replays after a recipient restart as the same record | `hub.test.ts`, `extension.test.ts`, `mcp.test.ts` |
+| An `allowOffline` send queues, delivers once on resumption, and expires unread by TTL | `hub-api.test.ts` |
+| TTL expiry, sender cancellation and terminal retention | `hub-api.test.ts` |
+| Exact-retry idempotency, and rejection of a reused key with different content | `hub-api.test.ts` |
+| Fanout to one to three peers: local timeouts, aborts, exact retries, partial errors | `client.test.ts`, `hub-api.test.ts`, `extension.test.ts`, `mcp.test.ts` |
+| Fenced leases: compare-and-set acquire, renew and release; a stale token's shared effect is refused | `hub-api.test.ts`, `store.test.ts`, `external-effects.test.ts` |
+| Rate limiting and retry guidance | `hub-api.test.ts` |
+| Redacted structured logs | `hub-api.test.ts` |
+| Client lifecycle: aborts, timeouts, invalid responses and reconnection | `client.test.ts` |
+| Safe diagnostic classification and redaction | `diagnostics.test.ts`, `extension.test.ts`, `hub-api.test.ts` |
+| Failed MCP inbox notifications stay retryable; delivery deduplicates | `inbox.test.ts` |
+
+## Hub workflows and provenance
+
+| Behavior | Evidence |
+|---|---|
+| Signed Jira webhook verification, filtering, dispatch and retry deduplication | `hub-api.test.ts` |
+| Ordered checkpoints, keyed evidence gates, and warning or failure retry | `hub-api.test.ts`, `workflow.test.ts` |
+| Eligible producers fixed at run start; per-requirement message references; unique-producer quorum; replay rejected | `workflow-provenance.test.ts`, `workflow.test.ts`, `hub-api.test.ts`, `client.test.ts`, `store.test.ts` |
+| Admin degradation of the current attempt: configured minimum, audit journal, idempotency, stale approvals refused | `workflow-provenance.test.ts`, `cli.test.ts` |
+| Durable external waits: evidence accumulation, safe settlement, race rejection, signed callbacks, separate secrets | `hub-api.test.ts`, `workflow.test.ts`, `workflow-provenance.test.ts` |
+| Quorum parser boundaries, and a secret-free definition hash that survives credential rotation | `workflow-quorum.test.ts`, `workflow-definition-hash.test.ts` |
+| Durable workflow and journal recovery; atomic transition commit and rollback | `store.test.ts` |
+| Plans, decisions, contradictions, errors, lessons and improvement reports | `hub-api.test.ts`, `workflow.test.ts` |
+| All ten journal categories and `stageId` through `kxm_workflow_record`, with stage provenance end to end | `journal-evolution.test.ts` ("kxm_workflow_record binds stage provenance and the stage's area end to end, and hub-authored entries carry it too") |
+| Ranked, redacted cross-run signals; retrospectives refreshed by late entries and promotions | `journal-evolution.test.ts`, `workflow.test.ts`, `retrospective.test.ts` |
+| Retrospective export: snapshots, metadata-only provenance audit, body allowlist, degradation records | `retrospective.test.ts` |
+| Typed back-edges, transition budgets, bypass protection and restart recovery | `workflow-transitions.test.ts` |
+| GitHub check watch: pagination, conclusions, retries and per-wait delivery generations | `github-watch.test.ts` |
+
+## Local Runtime and engine
+
+| Behavior | Evidence |
+|---|---|
+| Event-sourced Runtime: singleton supervisor, append-only per-project stores, idempotent commands, projection rebuild, crash recovery | `runtime.test.ts`, `cli.test.ts`, `package-install.test.ts` |
+| A store the build refuses is reported unreadable, never empty | `runtime.test.ts` ("a project whose store the build refuses is reported as unreadable, never as empty") |
+| Supervisor drive: `202` with a poll link, duplicate drives refused, graceful shutdown waits | `runtime-supervisor.test.ts` |
+| Settlement from a structured result only; prose outcomes and undeclared outcomes end as `outcome_unknown` | `pi-producer.test.ts`, `engine.test.ts` |
+| Routing records carry `workflowId`, `askSha256`, `objectiveSha256` and `stepWrites`, and settle only `blocked` or `failed` | `route-admission.test.ts` |
+| Dispatch context: only committed, pinned memory and hash-verified promoted skills reach an agent; the rest is a `dispatch_context_*` gap | `engine.test.ts` ("dispatch context: agents receive only committed, pinned memory and verified skills; anything else is withheld with a gap and the step still completes") |
+| `kxm run` prints the simulated drive command for the new run | `cli.test.ts` ("kxm run prints the simulated drive command for the created run") |
+| `kxm workflow add --template` writes workflows that validate and plan; an impossible gate outcome is refused | `cli-experience.test.ts` ("workflow add templates validate and plan a run, and a gate outcome the step can never produce is refused") |
+| `default.yaml` and the 13-step `fix.yaml` compile deterministically; back edges need budgets | `engine-compile.test.ts` |
+| Artifact gate: non-empty regular files pass; missing, empty, non-file and escaping paths fail | `artifacts-exist.test.ts` |
+| Vision gate: strict verdicts, admitted routes only, unreadable images fail closed | `vision-gate.test.ts` |
+| Tenant read labels hub projection versus Runtime authority and survives either side being down | `studio-layout.test.ts` |
+
+## Context, memory and learning
+
+| Behavior | Evidence |
+|---|---|
+| Packets rank by task relevance, fill the budget first-fit, and deliver every selected item, evidence included | `arbiter.test.ts` ("arbitrate ranks task-relevant candidates first, delivers every selected item in a packet section, orders ties newest first, and reports relevance") |
+| Recall ranks by phrase, then relevance; hub logs carry sizes, not task or query text | `context-surfaces.test.ts`, `arbiter.test.ts` |
+| An agent's state proposal is peer origin, decided by its credential, and capped at evidence | `context-authority.test.ts` ("a state proposal takes its origin from the verified credential, so an agent is peer and capped at evidence") |
+| Promotion needs the configured admin token with no loopback bypass; proposed items never reach a packet | `e5-memory-floor.test.ts` |
+| `kxm memory`: candidates, marker-delimited sync blocks, and one brief across CLI, Pi and the Claude hook | `e5b-harness-agnostic-memory.test.ts` |
+| `kxm improve report` reads Runtime-settled attempts, drops simulated and duplicate ones, and flags only same-ask repeats | `improve.test.ts` ("kxm improve report resolves Runtime-settled attempts from the event log and flags only same-ask cross-run repeats"), `cli.test.ts`, `cli-experience.test.ts`, `commands-policy.test.ts` |
+| Improvement candidates exclude write steps; promotion readiness never authorizes | `improve.test.ts` |
+| Telemetry classification and JSONL recovery | `telemetry.test.ts`, `cli.test.ts` |
+
+The context suites in detail:
+
+| Suite | Covers |
+|---|---|
+| `context.test.ts` | Context schema round trips, hostile input, cross-project refusal, storage upgrade |
+| `state.test.ts` | Temporal state lifecycle, `asOf` queries, supersession, contradictions, restart durability |
+| `context-authority.test.ts` | Authority floor per origin, reserialization escalation, lineage bounds, control-plane smuggling |
+| `arbiter.test.ts` | Role-aware packets, relevance ranking, first-fit budgets, the evidence section, contradiction routing |
+| `context-surfaces.test.ts` | CLI and Pi tool parity for the context API |
+| `journal-evolution.test.ts` | Journal categories, evidence requirements, governed promotion, stage provenance |
+| `wiki.test.ts` | Wiki compilation determinism, lifecycle preservation, contradiction visibility, lint |
+| `skills.test.ts` | Skill candidate lifecycle, quarantine, immutability, CLI |
+| `routing.test.ts` | Behavioral hash, record parsing, comparisons, `kxm routing report` |
+| `improve.test.ts` | Routing-record sources, event-log outcomes, same-ask candidacy, candidate files, promotion readiness |
+
+## Claude Code plugin and MCP
+
+| Behavior | Evidence |
+|---|---|
+| MCP tool catalog, outbound and inbound tools, and channel delivery | `mcp.test.ts` |
+| The MCP server never registers with the persisted admin token | `mcp.test.ts` ("MCP server never registers with the persisted admin token") |
+| Expired disk tokens and invalid `KXM_SESSION_TOKEN` values produce errors that name the user's fix | `mcp.test.ts` |
+| MCP tools, Pi tools and CLI verbs match `AGENT_COMMANDS` exactly, plus the hook-only tools | `commands-drift.test.ts` |
+| The plugin README tool table lists every tool the MCP server publishes | `claude-plugin-docs.test.ts` |
+| `SessionStart` hook: silent outside a project, project-scoped, under 1,500 characters, never prints a session token | `claude-plugin-hooks.test.ts` |
+| Hooks use exec form under `CLAUDE_PLUGIN_ROOT` with bounded timeouts, and run from a copied plugin directory | `claude-plugin-hooks.test.ts` ("plugin hooks use exec form under CLAUDE_PLUGIN_ROOT with bounded timeouts") |
+| Terminal inbound cleanup and next-request activation | `extension.test.ts`, `mcp.test.ts` |
+
+## Pi extension and workers
+
+| Behavior | Evidence |
+|---|---|
+| Pi tools, inbound turns, automatic replies and the status command | `extension.test.ts` |
+| Workflow and journal tools, workflow-context sends, and peer-reference checkpoints and waits | `extension.test.ts`, `mcp.test.ts` |
+| Interrupted-worker continue fallback, run-bound recovery and one-turn durable replay | `worker.test.ts`, `recovery.test.ts`, `extension.test.ts` |
+| Hub-owned workflow affinity, pre-acknowledgement routing, one-child session-directory swap, LRU retention | `hub-api.test.ts`, `extension.test.ts`, `worker.test.ts`, `cli.test.ts` |
+| Provider-error retention, retry ordering, bounded fallback, oversized frames and session-preserving restart | `extension.test.ts`, `worker.test.ts`, `diagnostics.test.ts`, `cli.test.ts` |
+| Tool allowlist, watchdog grace, hung-tool recovery and race-safe ownership claims | `worker.test.ts`, `cli.test.ts`, `hub-autostart.test.ts` |
+| Exact extension and skill sets, discovery isolation, path preflight and Windows argument safety | `worker.test.ts` |
+| Workspace defaults and persisted worker logs under isolated temporary workspaces | `worker.test.ts`, `hub-autostart.test.ts` |
+| Opt-in real-Pi smoke contract and its safe skip paths | `smoke-real-pi.test.ts`, `smoke.test.ts` |
+
+## CLI, configuration and trust
+
+| Behavior | Evidence |
+|---|---|
+| `init`, `validate`, `export` and `watch` in isolated workspaces | `cli.test.ts`, `github-watch.test.ts` |
+| Every mutating command under `--dry-run` leaves the workspace, state root and hub untouched | `cli-experience.test.ts` ("every mutating command under --dry-run leaves the workspace, state root, and hub untouched") |
+| Hub auto-start reuses a healthy or claimed hub, persists one admin key, and fails closed on bad claims | `hub-autostart.test.ts` |
+| Hub-local session brief from SQLite without message bodies; `hub bind` reports on, off or unknown | `session-work.test.ts`, `cli.test.ts` |
+| Session manifests, fail-closed rosters, worker and result envelopes, hub-owned envelope fields | `session.test.ts`, `cli.test.ts`, `envelope.test.ts`, `envelope-contract.test.ts` |
+| Metadata-only dashboard: ops mode, presence-only fallback, observer filtering, keys, body-free local projection | `tui.test.ts`, `hub-api.test.ts` |
+| Restricted loader, deterministic bundle hash, init classification, atomic creation, three-way repair, crash resumption | `project-config.test.ts`, `cli.test.ts`, `package-install.test.ts` |
+| Legacy `.kxm/config` JSON is refused with `legacy_state_unsupported`; `kxm migrate` is unknown; older stores are refused | `project-config.test.ts`, `cli.test.ts`, `e6-backup-restore-migrations.test.ts` |
+| `kxm backup` and `kxm restore` round-trip the hub store and Runtime stores seeded under `.kxm/runtime/`; tampered or newer backups are refused | `e6-backup-restore-migrations.test.ts` |
+| Permission-diff trust: authority lattice, prose neutrality, Git base shadowing, CLI diff and check | `permission.test.ts`, `cli.test.ts`, `contracts.test.ts`, `package-install.test.ts` |
+| KXM schemas, restricted YAML fixtures, cross-resource semantics and sync-safe rejection | `contracts.test.ts`, `restricted-yaml.test.ts` |
+| Harness detection, auth and dispatch for the built-in catalog, including Windows launch rules | `harness.test.ts` |
+| `kxm update`: `update.yaml` validation, GitHub or npm version checks, install-kind detection, `kxm-<v>.tgz` asset selection | `kxm-update.test.ts`, `kxm-update-cli.test.ts`, `kxm-install-kind.test.ts` |
+
+The backup round trip seeds its Runtime stores in a project-local
+`.kxm/runtime/` layout that the Runtime never writes. Production Runtime stores
+live under the user state root, which `kxm backup` does not discover, so no test
+backs up the real Runtime stores.
+
+## Packaging, release and repository gates
+
+| Behavior | Evidence |
+|---|---|
+| The packed CLI and hub run from a clean local install and an isolated global `--omit=peer` install | `package-install.test.ts` |
+| Generated bundles and skill mirrors exist, are tracked and match the staged copy; mirror emit refuses symlinks | `generated-artifacts.test.ts`, `scripts/check-generated.mjs` |
+| Every version surface matches; the bumper writes each workspace manifest and patches the lockfile by key | `scripts/check-versions.mjs`, `version-surfaces.test.ts` |
+| Release packs `kxm-<v>.tgz`, uploads to a draft fail-closed, proves the digest and never clobbers | `kxm-release-github.test.ts`, `ci-contract.test.ts` |
+| npm publish requires a published release and a matching asset digest | `kxm-publish-npm.test.ts` |
+| CI required jobs are unconditional; runner selector, coverage floors and release triggers are pinned | `ci-contract.test.ts` |
+| Skill suite: manifest shape, one owner per command, strict YAML frontmatter, no legacy names, mirror parity | `skill-suite.test.ts` ("every bundled SKILL.md frontmatter parses as strict YAML") |
+| The extension and MCP server never import the hub, store or workflow; library bundles stay host-neutral | `import-boundary.test.ts` |
+| Workspace packages keep their layers, required files and by-name imports | `package-layers.test.ts` |
+| Retired product names stay out of the scanned docs | `docs-copy.test.ts` |
+| Headless harness helper: auth probes, refusals before spawn, typed usage and cost, stdio and timeout handling | `harness-run.test.ts` |
+| `justfile` gates: documented `just` verbs exist, runner call sites are pinned, no dotenv auto-load | `harness-run.test.ts` |
+| Developer roster validation: vendors, read-only critics, pinned model-origin evidence | `roster-policy.test.ts` |
+
+The `justfile` gates are drift protection, not a sandbox: anyone who can edit
+the file can already do what it does. They run without the `just` binary and
+skip the real-`just` checks, with a visible reason, when it is absent.
+
+## Examples and fixtures
+
+| Scenario | Location | Verification |
+|---|---|---|
+| Self-contained planner and reviewer round trip | `examples/roundtrip.ts` | Executed by `examples.test.ts` |
+| Long-running deterministic reviewer | `examples/reviewer-agent.ts` | Type-checked |
+| Command-line requester | `examples/requester.ts` | Type-checked |
+| Signed external result callback | `examples/workflow-signal.ts` | Type-checked; the same signed path runs end to end in `hub-api.test.ts` |
+| Peer provenance with optional degradation | `examples/provenance-workflow.json`, `docs/guides/provenance-gates.md` | Parsed and matched to the guide by `examples.test.ts` |
+| Jira development webhook workflow | `examples/webhook-workflows/jira-development.json` | Not parsed by a test; `hub-api.test.ts` and `workflow.test.ts` exercise an inline definition of the same shape |
+| Project fixture with `default.yaml` and `fix.yaml` | `examples/project/` | Compiled by `engine-compile.test.ts`; schema-checked by `contracts.test.ts` |
+| Plan-then-review, separate ownership, delegation, cancellation, safe retry prompts | `examples/README.md` | Documented agent prompts; not executed |
+
+## Coverage floors
+
+| Run | Lines | Branches | Functions |
+|---|---:|---:|---:|
+| `test:coverage:core` (pushes to `main`, releases) | 91% | 80% | 92% |
+| `test:coverage:complete` (nightly) | 93% | 80% | 93% |
+
+Coverage measures `plugins/kxm/src/**/*.ts` and `packages/core/*/src/**/*.ts`,
+excluding the spawned entry points `server.ts`, `mcp-server.ts` and
+`runtime-supervisor.ts`. The generated MCP runtime is exercised as a child
+process, and the packed CLI and hub run from a clean consumer install. The
+floors only move up.
+
+## Behavior without automated coverage
+
+Some behavior can only be checked by hand, for example how a harness UI renders
+a channel event. List it in the manual checks in
+[CI and release](ci-and-release.md#manual-checks-before-announcing-a-release)
+instead of implying automated coverage here. The developer
+[assignment runner](assignment-runner.md#test-coverage-is-thin) has no
+end-to-end tests.
+
+## Related
+
+- [Develop KXM](development.md): test conventions and the commit gate
+- [CI and release](ci-and-release.md): which suites run where
+- [Write KXM documentation](writing-docs.md): doc gates and pinned paths

package/docs/{tui-components.md → contributing/tui-components.md}

@@ -1,14 +1,17 @@
 # KXM terminal components
 
-Audience: maintainers and integrators who draw a KXM surface — the live screens,
-a configuration panel, or a host adapter for another harness.
+The terminal kit gives every KXM surface the same keys, colors and failure
+behavior. This page is for maintainers and integrators who draw a KXM surface: a
+live screen, a configuration panel, or a host adapter for another harness.
 
 The kit is the workspace package
-[`packages/core/tui`](../packages/core/tui) (`@kontextmind/tui`),
-also published on the product as `@kontextmind/kxm/tui`. It is one declarative
+[`packages/core/tui`](../../packages/core/tui) (`@kontextmind/tui`), also
+published on the product as `@kontextmind/kxm/tui`. It is one declarative
 surface model, one renderer, one input decoder, one contribution registry, and
-thin host adapters, so every surface keys, colours, and fails the same way. See
-[Packages and workspaces](packages.md) for the layout convention it follows.
+thin host adapters. Today `kxm dash` uses only its ANSI theme; the panel,
+registry and adapters are exported for integrators, and no shipped `kxm` command
+draws a panel yet. See [Packages and workspaces](packages.md) for the layout
+convention it follows.
 
 ## Package layout
 
@@ -20,7 +23,7 @@ every control in `tui/` is rendered in a test.
 
 ## The surface contract
 
-A surface is **published, not centralised**. An owner (configuration, roster,
+A surface is **published, not centralized**. An owner (configuration, roster,
 routes, gates, roles, workflow) contributes sections and fields; one renderer
 draws them all; the owner still performs every write. The panel never becomes a
 second source of truth for configuration.
@@ -51,11 +54,11 @@ needs selecting and an absent one that needs fetching, without the renderer
 knowing the difference.
 
 Bounds are protocol limits, not suggestions
-([`KXM_TUI_LIMITS`](../packages/core/tui/src/types/surface.ts)). An oversized
+([`KXM_TUI_LIMITS`](../../packages/core/tui/src/types/surface.ts)). An oversized
 or malformed published surface is refused with structured issues and drawn with
 an error notice, so a broken file is still repairable from the panel.
 
-## Fail-closed behaviour
+## Fail-closed behavior
 
 | Situation | What happens |
 |---|---|
@@ -65,7 +68,7 @@ an error notice, so a broken file is still repairable from the panel.
 | A choice is `blocked` | Enter reports `statusText` and sends nothing (an unauthenticated route stays unauthenticated) |
 | Handler for an unknown action or unknown owner | Refused with a message; never guessed |
 | A write resolves after the registry was disposed or re-opened | Discarded as stale |
-| No TTY, or `NO_COLOR` | One plain frame, exit `0`, no escape codes at all |
+| No TTY, or `NO_COLOR` or `KXM_TUI_NO_COLOR` set | One plain frame, exit `0`, no escape codes at all |
 | Contract violation in a published surface | Refused with issues; the panel draws the reason instead of hiding it |
 
 There is deliberately **no local echo**. A field is pending until its owner
@@ -76,18 +79,23 @@ republishes, so anything on screen is a value that exists on disk.
 | Key | Action |
 |---|---|
 | `↑` `↓` / `k` `j` | move within the focused pane |
-| `←` `→` / `Tab` / `h` `l` | switch sections and fields |
+| `←` `→` / `Tab` | switch between the sections pane and the fields pane |
+| `l` | move to the fields pane |
 | `PgUp` `PgDn` | jump sections |
 | `enter` | edit a text field, cycle an enum, open a choice list |
 | type | filter a choice list, or edit a text value |
-| `x` | clear the focused value (writes "unset", not a default) |
+| `x` / `d` | clear the focused value (writes "unset", not a default) |
 | owner keys | any `actions[].key` on the focused field |
 | `esc` | back out of a pane, list, or draft, then quit |
+| `q` | quit |
 | `Ctrl+C` | abort a busy field, else quit |
-| `h` / `?` | help |
+| `h` / `?` | help; `esc` or `enter` closes it |
+
+`h` opens help rather than moving to the sections pane, so use `←` or `Tab` to
+go back.
 
 The reducer is pure
-([`reduceKxmTuiInput`](../packages/core/tui/src/tui/panel.ts)) and returns
+([`reduceKxmTuiInput`](../../packages/core/tui/src/tui/panel.ts)) and returns
 effects; the component layer runs them. That is the same contract that keeps
 `kxm dash` navigation testable, and it is why no key handling needs a terminal.
 
@@ -106,7 +114,7 @@ effects; the component layer runs them. That is the same contract that keeps
 
 Selectable values come from reference sources, not from a model's memory: the
 harness catalog in
-[`harness.ts`](../plugins/kxm/src/harness.ts), admitted routes in
+[`harness.ts`](../../plugins/kxm/src/harness.ts), admitted routes in
 `.kxm/routes.yaml`, the model inventory and price catalog, gate ids in
 `.kxm/gates.yaml`, role ids in `.kxm/roles/`, and workflow ids in
 `.kxm/workflows/`.
@@ -119,13 +127,13 @@ harness catalog in
   definitions stay Git-reviewed changes with a diff and a PR.
 - It is not a third verification gate. `npm run verify` and CI still decide
   whether work is green.
-- It does not replace `kxm dash`. The dashboard keeps its hub and SSE loop and
-  shares this kit's palette and layout maths.
+- It does not replace `kxm dash`. The dashboard keeps its own hub and SSE loop
+  and takes only this kit's ANSI theme.
 
 ## Related
 
-- [Packages and workspaces](packages.md) — the layout convention and its gate
-- [Configuration](configuration.md) — the settings a config surface edits
-- [Architecture](architecture.md) — component boundaries
-- [Test matrix](test-matrix.md) — where a behaviour is proven
-- [KXM contracts](contracts/README.md) — schemas behind the reference files
+- [Packages and workspaces](packages.md): the layout convention and its gate
+- [Configuration](../reference/configuration.md): the settings a config surface edits
+- [Architecture](../concepts/architecture.md): component boundaries
+- [Test matrix](test-matrix.md): where a behavior is proven
+- [KXM contracts](../contracts/README.md): schemas behind the reference files