@kontextmind/kxm 0.7.91 → 0.7.93

package/plugins/kxm/skills/kxm-session/SKILL.md

@@ -1,53 +1,81 @@
 ---
 name: kxm-session
-description: Set up a local KXM hub session brief — recent tasks/plans, status-line stats, and harness chrome. Use when starting a new session, running kxm init, kxm hub bind, or configuring a status bar. Local-only Runtime insights and SSH/remote hubs are after MVP.
+description: Read KXM session and hub status with kxm session status and kxm hub view, create a session manifest with kxm session start, open kxm dash screens, and lay out workflows with kxm studio layout. Use at the start of a session, when asked what is in flight, or when opening the dashboard. kxm session brief, kxm session stop, and kxm studio serve are operator steps because they save a 24-hour session token, stop the hub, or open a listener.
 ---
 
-# KXM session (hub local)
+# KXM session
 
-MVP is a **local hub** on this machine. Work is agents and workflows. Do not configure hub chrome for local-only init.
+Start a session by reading status. The agent steps below write no token and
+start no process.
 
-## Tracks
+## Agent steps
 
-| Track | When | What this skill does |
+| Command | Purpose | Options / arguments |
 |---|---|---|
-| **Local-only** | `kxm init` (project-only) | Skip hub start, skip session brief, skip status-line chrome |
-| **Hub local (MVP)** | `kxm hub bind <url>` | Bind this host to a running loopback hub; session brief + status line |
-| **SSH / HTTPS remote** | After MVP | Fail closed. Not available |
-
-In-harness Pi can attach to a local hub. Local Runtime workflow insights (`kxm dash` from the KXM event store) are after MVP.
-
-## First run (hub local)
-
-```text
-kxm init
-kxm hub start                 # other terminal
-kxm hub bind <url>
-kxm session brief
-```
-
-Keep `.kxm/config` in Git; do not recopy templates onto an existing project. `KXM_SERVER_URL` still overrides a bound URL.
-
-## Session brief
-
-`kxm session brief` reads the **local hub** SQLite (tasks = workflow runs, plans = journal `plan` rows). No message bodies. `--status` prints the status line for harnesses that have one.
+| `kxm session status` | Session claims and recovery envelopes | `--json` |
+| `kxm hub view` | Hub `/health` and `/ready`; exits 1 when the hub is down | `--json` |
+| `kxm session start` | Create an agent/gate or workflow session manifest; launches nothing | `--id`, `--workflow`, `--mix`, `--json` |
+| `kxm dash` | Live screens for agents, tasks, workflows, and plans | `--screen agents\|tasks\|workflows\|plans\|inbox\|procs\|spend` |
+| `kxm studio layout [workflowPath]` | DAG, stepper, and swimlane layout JSON for a workflow | `--json` |
+
+At the start of a session, run `kxm session status` and `kxm hub view`. In a
+repository with no session token file both leave the user config directory
+and the Git tree unchanged. `kxm session status` prints
+`0 session claim(s), 0 recovery envelope(s)` on a fresh project, and
+`kxm hub view` prints `hub health=false ready=false · loopback hub` and exits 1
+while the hub is down.
+
+## Hub binding
+
+| Track | When | What to do |
+|---|---|---|
+| Local only | `kxm init` without a hub | Work with runs and Git memory; skip hub status chrome |
+| Local hub | The user ran `kxm hub bind http://127.0.0.1:7331` | Read status with `kxm hub view` |
+| Remote hub | The user ran `kxm hub bind <https-url>` | Binds when a credential resolves; otherwise it fails closed with `hub_bind_unauthenticated` |
 
-Interactive **Pi TUI**: on `startup` / `/new` / `/fork`, the kxm extension offers recent tasks/plans and paints the footer + widget (including a `ship` line: dirty vs local commits vs PR after CI). `/kxm` reopens the picker. `/kxm status` refreshes chrome only. `/kxm hub` is hub view. Workers, RPC, and print mode never prompt. `KXM_SESSION_BRIEF=off` disables the picker only.
+`KXM_SERVER_URL` overrides a bound URL. Binding is an operator step owned by
+`kxm-hub-ops`.
 
 ## Harness support (fail closed)
 
-| Harness | Picker | Status line | Setup |
+| Harness | Picker | Status line | First reply |
 |---|---|---|---|
-| Pi TUI | Yes, extension | Yes, `setStatus` + widget | Load the kxm extension (default from the package) |
-| Pi RPC / worker | No | Status only if UI helpers exist; never a picker | Skip |
-| Claude Code | No coded picker | Only if the operator points `statusLine` at `kxm session brief --status` | Do not invent chrome |
-| Codex, Kimi, Gemini, DeepSeek | Unknown | None unless that CLI documents a status command | Skip chrome; first reply may run `kxm session brief` |
+| Pi TUI | Yes, kxm extension | Yes, `setStatus` plus widget | Load the kxm extension (default from the package) |
+| Pi RPC / worker | No | Only if UI helpers exist; never a picker | Skip chrome |
+| Claude Code | No picker | The plugin's SessionStart hook adds a short KXM brief only in projects with `.kxm`; a statusLine is optional and an operator step | Run `kxm session status` and `kxm hub view` |
+| Codex, Kimi, Gemini, DeepSeek | Unknown | None unless that CLI documents a status command | Run `kxm session status` and `kxm hub view` |
+
+Interactive Pi TUI: on `startup`, `/new`, and `/fork`, the kxm extension offers
+recent tasks and plans and paints the footer and widget, including a `ship`
+line (dirty tree, local commits, PR after CI). `/kxm` reopens the picker,
+`/kxm status` refreshes chrome only, and `/kxm hub` is the hub view. Workers,
+RPC, and print mode never prompt. `KXM_SESSION_BRIEF=off` disables the picker
+only.
 
 This skill never grants tools or permissions.
 
-## Operator loop
+## Operator steps
+
+Ask the user to run these in their own terminal.
 
-1. Confirm hub local: `kxm hub view`.
-2. `kxm session brief` or Pi `/kxm`.
-3. Pick a task/plan or start fresh.
-4. Live peek remains `kxm dash` (tasks / plans tabs).
+Until kxm session brief stops minting tokens, running it saves a 24-hour
+operator session token; when that token expires every kxm_* tool fails with
+tool_policy_denied. Its plain output prints a Session token line, so never
+paste it into a conversation.
+
+| Command | Purpose | Options |
+|---|---|---|
+| `kxm session brief` | Recent hub tasks (workflow runs) and plans (journal `plan` rows) from the local hub store; every form saves the session token | `--status` (status line only), `--json` |
+| `kxm session token --status` | Report the active session token | `--json` |
+| `kxm session token --clear` | Delete the session token file | `--json` |
+| `kxm session stop` | Request managed hub and worker shutdown | `--wait-ms <ms>` |
+| `kxm studio serve` | Start the Web Studio listener (default `http://localhost:4242`) | `--port`, `--host`, `--token` |
+
+- `kxm session token --status` reports
+  `No active session token found in env or disk` for an expired or malformed
+  file, even though that file still blocks every kxm_* tool. `--clear` is the
+  fix for such a file.
+- Claude Code statusLine: the user may point `statusLine` at
+  `kxm session brief --status`, which saves the same 24-hour token.
+- Pi operator loop: `kxm hub view`, then `kxm session brief` or Pi `/kxm`, pick
+  a task or plan or start fresh, and keep `kxm dash` open for a live view.

package/plugins/kxm/skills/kxm-skill-lifecycle/SKILL.md

@@ -1,31 +1,60 @@
 ---
 name: kxm-skill-lifecycle
-description: Govern candidate/evaluate/promote/quarantine/reject/verify lifecycle; distinguish this from bundled skills.
+description: Govern KXM skill candidates. Create one from verified runs, journal entries, receipts, or a kxm improve skill candidate, record static-review, sandbox, functional and safety evaluations, and list or verify pinned hashes, while promotion and rejection stay a non-author decision. Use when turning a repeated practice into a reusable skill. Not for editing the bundled kxm-* plugin skills.
 ---
 
-# KXM Governed Skills
+# KXM governed skills
 
-This is the governed candidate lifecycle, not the bundled `plugins/kxm/skills`
-suite. Bundled skills are authored in Git and mirrored to `.agents/skills`.
-Do not invent `candidate`, `quarantine`, `rollback`, `validate`, or `get`.
+This is the governed candidate lifecycle under `.kxm/skills/`, not the bundled
+`plugins/kxm/skills` suite. Bundled skills are authored in Git and mirrored to
+`.agents/skills`. Do not invent `candidate`, `quarantine`, `rollback`,
+`validate`, or `get` verbs.
 
-## Commands
+## Agent steps
 
 | Command | Purpose | Options / arguments |
 |---|---|---|
-| `kxm skills create` | Submit a candidate from verified episodes | `--file`, `--name`, `--description`, `--created-by`, `--run`, `--journal`, `--receipt`, `--harness`, `--models`, `--supersedes` |
+| `kxm skills create` | Submit a candidate from verified episodes | Required `--file`, `--name`, `--created-by`, `--harness`, `--models`; optional `--description`, `--run`, `--journal`, `--receipt`, `--supersedes` |
 | `kxm skills evaluate <skillId>` | Record a protected evaluation | `--kind static-review\|sandbox\|functional\|safety\|optimization`, `--evaluator`, `--fail`, `--score`, `--details` |
-| `kxm skills promote <skillId>` | Promote a candidate that passed required evaluations | `--decided-by`, `--evidence`, `--reason` |
-| `kxm skills reject <skillId>` | Reject a candidate; history is retained | `--decided-by`, `--reason` |
-| `kxm skills list` | List skills by state | `--state candidate\|promoted\|quarantined\|rejected` |
-| `kxm skills verify <skillId>` | Verify pinned content hash | `--state candidate\|promoted\|quarantined\|rejected` |
+| `kxm skills list` | List skills by state (default `promoted`) | `--state candidate\|promoted\|quarantined\|rejected` |
+| `kxm skills verify <skillId>` | Verify the pinned content hash | `--state candidate\|promoted\|quarantined\|rejected` |
 
 ```bash
+kxm skills create --file /tmp/retry-backoff/SKILL.md --name retry-backoff --created-by agent_writer --harness claude-code --models claude/fable --run run_1 --receipt receipt:run_1/verify --dry-run --json
 kxm skills list --state candidate --json
 kxm skills evaluate skill_123 --kind static-review --evaluator eval-1.0.0 --json
-kxm skills promote skill_123 --decided-by agent_reviewer --evidence receipt:run_1/verify --json
-kxm skills verify skill_123 --state promoted --json
+kxm skills verify skill_123 --state candidate --json
 ```
 
-Promotion requires durable evidence and a non-author decision. A candidate
-cannot grant tools, skip review, or auto-promote bundled skills.
+A failed `functional` or `safety` evaluation quarantines the candidate
+automatically. Promotion needs passing `static-review`, `sandbox`,
+`functional`, and `safety` evaluations.
+
+## From an improvement candidate
+
+`kxm improve report` proposes a `skill` candidate as a diff that adds a
+`SKILL.md` draft (`kxm-routing-improve`).
+
+1. Review the proposed `SKILL.md` draft with the user and rewrite it into
+   real instructions.
+2. Save it outside `.kxm/skills`, for example under `/tmp/<name>/SKILL.md`.
+3. Run
+   `kxm skills create --file <draft> --name <name> --created-by <id> --harness claude-code --models <models> --run <ids> --receipt <refs>`.
+4. Record the evaluations above.
+
+Never apply the candidate diff into `.kxm/skills`. `kxm skills list --state candidate`
+ignores a hand-written `.kxm/skills/candidates/<slug>/SKILL.md`; only
+`kxm skills create` registers a candidate with its pinned hash and history.
+
+## Operator steps
+
+Promotion and rejection belong to a non-author: the user or another
+authorized reviewer, never the agent that created the candidate.
+
+| Command | Purpose | Options / arguments |
+|---|---|---|
+| `kxm skills promote <skillId>` | Promote a candidate that passed the required evaluations; writes a patch for review | `--decided-by` (must differ from the author), `--evidence`, `--reason` |
+| `kxm skills reject <skillId>` | Reject a candidate; history is retained | `--decided-by`, `--reason` |
+
+Promotion requires durable evidence. A candidate cannot grant tools, skip
+review, or auto-promote bundled skills.

package/plugins/kxm/skills/kxm-tasks/SKILL.md

@@ -1,9 +1,9 @@
 ---
 name: kxm-tasks
-description: Recommend workflows and manage goals/tasks with explicit SCM/tracker boundaries.
+description: Recommend workflows and manage goals and tasks with explicit SCM and tracker boundaries. Use when asked what workflow fits, to plan work as goals and tasks, or to sync with GitHub or Jira. Run a kxm suggest workflow ID only after kxm workflow definitions lists it.
 ---
 
-# KXM Suggest, Goals, and Tasks
+# KXM suggest, goals, and tasks
 
 Bind SCM and issue trackers from this repo's conventions. Implemented today:
 GitHub and Jira. An unimplemented tracker fails closed. Do not invent
@@ -16,7 +16,7 @@ GitHub and Jira. An unimplemented tracker fails closed. Do not invent
 | `kxm suggest <prompt...>` | Recommend workflow, area, roles, and skills | `--json` |
 | `kxm goal create <title>` | Create a project goal | `--area`, `--metric`, `--target-date` |
 | `kxm goal list` | List project goals | `--json` |
-| `kxm task create <title>` | Create a task | `--goal`, `--objective`, `--workflow`, `--tracker github\|jira`, `--issue` |
+| `kxm task create <title>` | Create a task | `--goal`, `--objective`, `--workflow`, `--tracker github\|jira`, `--issue <number-or-key>` |
 | `kxm task list` | List project tasks | `--goal`, `--status todo\|in_progress\|blocked\|in_review\|done` |
 | `kxm task get <taskId>` | Task details and linked workflow status | `--json` |
 | `kxm task run <taskId>` | Launch a workflow run driven by this task | `--json` |
@@ -24,10 +24,22 @@ GitHub and Jira. An unimplemented tracker fails closed. Do not invent
 
 ```bash
 kxm suggest "implement trusted roster policy brakes" --json
+kxm workflow definitions
 kxm goal create "Land the skills suite" --area software-engineering --json
 kxm task create "Repair trust loader" --goal goal_1 --tracker github --issue 127 --json
 kxm task list --status in_progress --json
 kxm task sync task_1 --json
 ```
 
-Do not silently use GitHub when the operator picked an unimplemented tracker.
+## Suggested workflows
+
+`kxm suggest` picks its workflow ID from a built-in catalog, and that ID may
+not exist in this project. Before running the suggested `kxm run` command,
+confirm that `kxm workflow definitions` lists the ID; otherwise `kxm run`
+fails with `run_workflow_unknown`. Pick a listed workflow instead, or write
+one with the user (`kxm-project-setup`).
+
+`--issue` on `kxm task create` is a tracker issue number or Jira key, not a
+credential. In this build `kxm task sync` marks only the local task record
+synced; it does not contact GitHub or Jira. Do not silently use GitHub when
+the operator picked an unimplemented tracker.

package/plugins/kxm/skills/kxm-triage/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: kxm-triage
-description: Work the KontextMind review queue. Use when asked to triage the mind, review drafts, promote or skip learnings, resolve drift/contradiction/gap/loop items, or call km_review.
+description: KontextMind knowledge plane only, the separate kontext CLI and km_ tools, not KXM or this plugin's kxm_* tools. Works the KontextMind review queue with km_review. Use only when the user names KontextMind, the kontext CLI, or a km_ tool.
 license: Apache-2.0
 compatibility: Any agent that can run a shell or MCP client. No vendor-only tools.
 metadata:

package/plugins/kxm/skills/kxm-work/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: kxm-work
-description: KontextMind work context — tracker read-through, checkpoints, and claimable handoffs. Use when asked what is in flight, what to pick up, checkpoints, handoffs, km_work_current, km_work_update, km_handoff_save, or km_handoff_load.
+description: KontextMind knowledge plane only, the separate kontext CLI and km_ tools, not KXM or this plugin's kxm_* tools. Reads and updates KontextMind tracker work state with the km_work and km_handoff tools. Use only when the user names KontextMind, the kontext CLI, or a km_ tool.
 license: Apache-2.0
 compatibility: Any agent that can run a shell or MCP client. No vendor-only tools.
 metadata:

package/plugins/kxm/skills/kxm-workflow/SKILL.md

@@ -1,45 +1,86 @@
 ---
 name: kxm-workflow
-description: Operate webhook workflows, waits/signals, evidence checkpoints, provenance, and deterministic gates.
+description: Work inside a durable KXM workflow run. Read it, record plan, decision, contradiction, error and lesson journal entries, pass stage checkpoints with keyed evidence and peer evidence refs, wait for signed CI or review callbacks, start webhook workflows, and export retrospectives (kxm_workflow_get, kxm_workflow_record, kxm_workflow_checkpoint, kxm_workflow_wait). Use when a workflow run ID is involved or the user asks to checkpoint, gate, or wait on CI.
 ---
 
-# KXM Workflow and Gates
+# KXM workflow and gates
 
-Use the current CLI. Peer-reply requirements need durable replied message IDs
-in `--evidence-refs`. Caller-authored text never satisfies peer quorum.
+Durable workflow runs live on the hub and start from signed webhooks. Read the
+run first (`kxm_workflow_get` or `kxm workflow get <runId>`), record material
+plans, decisions, contradictions, errors, and lessons as you work, and pass
+every stage checkpoint before replying.
+
+Peer-reply requirements need durable replied message IDs in
+`--evidence-refs` (MCP `evidenceRefs`). Caller-authored text never satisfies
+peer quorum.
+
+`kxm workflow list` and `kxm workflow get` show hub webhook runs. Runs created
+with `kxm run` are Runtime runs; inspect them with `kxm runs list`
+(`kxm-runs`).
 
 ## Workflow
 
 | Command | Purpose | Options / arguments |
 |---|---|---|
-| `kxm workflow list` | List local workflow runs | `--json` |
-| `kxm workflow get <runId>` | Show one run | `--json` |
-| `kxm workflow checkpoint [runId] [stageId] [status] [summary]` | Record a stage result | `--run-id`, `--stage-id`, `--status passed\|warning\|failed`, `--summary`, `--evidence`, `--evidence-refs` |
-| `kxm workflow record [runId] [category] [area] [summary]` | Journal plan/decision/contradiction/error/lesson | `--category`, `--area`, `--severity`, `--details`, `--evidence` |
-| `kxm workflow wait [runId] [stageId] [signalKey] [summary]` | Wait for a signed callback | `--signal-key`, `--timeout-ms`, `--evidence`, `--evidence-refs` |
-| `kxm workflow signal <runId> <signalKey> <status> <summary>` | Resume a wait or KXM run | `[evidence...]`, `--delivery-id` |
-| `kxm workflow start [definitionId]` | POST a signed workflow-start webhook | `--payload`, `--delivery-id`, `--event` |
+| `kxm workflow list` | List hub workflow runs in the local store | `--json` |
+| `kxm workflow get <runId>` | Show one run with its stages and journal | `--json` |
+| `kxm workflow checkpoint [runId] [stageId] [status] [summary]` | Record a stage result | `--run-id`, `--stage-id`, `--status passed\|warning\|failed`, `--summary`, `--evidence <json>`, `--evidence-refs <json>` |
+| `kxm workflow record [runId] [category] [area] [summary]` | Journal one of ten categories | `--category`, `--area`, `--stage-id`, `--severity info\|warning\|error`, `--summary`, `--details`, `--evidence <items...>`, `--related-entry-ids <ids...>` |
+| `kxm workflow wait [runId] [stageId] [signalKey] [summary]` | Wait for a signed callback | `--signal-key`, `--summary`, `--timeout-ms`, `--evidence <json>`, `--evidence-refs <json>` |
+| `kxm workflow signal <runId> <signalKey> <status> <summary>` | Resume a wait or unblock a KXM run | `[evidence...]` as `required-key=evidence`, `--delivery-id` |
+| `kxm workflow start [definitionId]` | POST a signed workflow-start webhook | `--payload <json\|@file>`, `--delivery-id`, `--event` |
 | `kxm workflow export <runId>` | Export a proposed retrospective | `--input`, `--out-dir` |
-| `kxm workflow definitions` | List definitions | `--scope all\|global\|local` |
+| `kxm workflow definitions` | List project and global workflow definitions | `--scope all\|global\|local` |
 | `kxm workflow add [workflowId]` | Add a definition | `--file`, `--description`, `--scope`, `--overwrite`, `--pick` |
 | `kxm workflow remove [workflowId]` | Remove a definition | `--scope`, `--pick` |
 | `kxm workflow modify [workflowId]` | Modify a definition | `--description`, `--scope`, `--pick` |
 
+```bash
+kxm workflow get run_12345 --json
+kxm workflow checkpoint run_12345 implement passed "Implementation complete" --evidence '{"tests":"npm test passed"}' --json
+kxm workflow wait run_12345 verify github-pr-42-checks "CI running on PR 42" --json
+```
+
+## Journal
+
+Categories are `plan`, `decision`, `contradiction`, `error`, `lesson`,
+`observation`, `hypothesis`, `experiment`, `state-change`, and
+`skill-candidate`. A `lesson` or `skill-candidate` requires `--evidence`; the
+hub refuses one without it. Pass `--stage-id` to bind an entry to its stage:
+the hub derives the attempt, and area defaults to the stage's declared area,
+so `kxm workflow record <runId> <category> <summary> --stage-id <id>` works
+without an area. Never supply an attempt. Link a decision or lesson that
+resolves a contradiction with `--related-entry-ids`. The journal covers hub
+webhook runs; a `kxm run` ID is `workflow_not_found`.
+
+```bash
+kxm workflow record run_12345 lesson "Flaky test hid a race" --stage-id verify --severity warning --evidence https://ci.example.com/run/42 --json
+kxm workflow record run_12345 decision "Serialize the fixture setup" --stage-id verify --related-entry-ids je_123 --json
+```
+
 ## Gates
 
 | Command | Purpose | Options / arguments |
 |---|---|---|
-| `kxm gate validate` | Parse workflow definitions without printing secrets | `--file` |
-| `kxm gate artifacts-exist` | Verify a non-empty workspace artifact | `--path` (required) |
+| `kxm gate validate` | Parse JSON webhook workflow definitions without printing secrets | `--file <path>` |
+| `kxm gate artifacts-exist` | Verify a non-empty file under workspace assets | `--path` (required) |
 | `kxm gate degrade <runId> <stageId>` | Approve a configured lower peer quorum | `--requirement`, `--reason` |
-| `kxm gate signal <runId> <signalKey> <status> <summary>` | Post a signed callback | `[evidence...]`, `--delivery-id` |
+| `kxm gate signal <runId> <signalKey> <status> <summary>` | Post a signed callback | `[evidence...]`, `--delivery-id`, `--recovery-action retry\|fail\|cancel\|unblock` |
 | `kxm gate github watch` | Poll required GitHub checks and signal | `--run-id`, `--stage-id`, `--signal-key`, `--repo`, `--pr`, `--required`, `--timeout-ms`, `--interval-ms`, `--delivery-id` |
 
+`kxm gate validate` reads the hub's webhook definitions (`--file`, else
+`KXM_WEBHOOK_WORKFLOWS_FILE` or `KXM_WEBHOOK_WORKFLOWS`), which are JSON. It
+does not read project `.kxm/workflows/*.yaml`; validate those with
+`kxm init --dry-run --json`.
+
+`kxm gate signal` on a KXM run ID (`run_` plus 32 hex digits) goes to the
+Runtime and passes `--recovery-action` through; on a hub webhook run it posts a
+signed callback that needs `KXM_WORKFLOW_ID` and the definition's signal
+secret. Reuse `--delivery-id` to retry one unchanged callback.
+
 ```bash
-kxm workflow list --json
-kxm workflow get run_12345 --json
-kxm workflow checkpoint run_12345 stage_abc passed "Implementation complete" --evidence '{"code_changes":"added feature"}' --json
-kxm gate validate --file workflows/default.yaml --json
+kxm gate validate --file workflows.json --json
+kxm gate signal run_0123456789abcdef0123456789abcdef verify passed "operator verified" --recovery-action unblock --dry-run
 ```
 
 Do not invent `gate list`, `gate run`, or `gate status`.

package/plugins/kxm/src/arbiter.ts

@@ -1,6 +1,7 @@
 import {
   DEFAULT_CONTEXT_BUDGET_TOKENS,
   MAX_CONTEXT_ITEMS,
+  contextItemCharacters,
   estimateContextTokens,
   parseContextItem,
   parseContextRequest,
@@ -15,6 +16,13 @@ import {
   type ContextSourceType,
 } from "./context.ts";
 import { ProtocolError } from "./protocol.ts";
+import {
+  compareCodeUnitIds,
+  contextItemRelevanceText,
+  relevanceTokens,
+  roundRelevance,
+  scoreRelevance,
+} from "./relevance.ts";
 import type { SkillLifecycle } from "./skills.ts";
 import type { JournalCategory, WorkflowJournalEntry } from "./workflow.ts";
 import type { MemoryRecord } from "./memory.ts";
@@ -44,7 +52,7 @@ export const ROLE_POLICIES: readonly RoleContextPolicy[] = [
   {
     role: "repro",
     label: "Reproduction specialist",
-    kinds: ["episode", "knowledge"],
+    kinds: ["episode", "knowledge", "evidence"],
     journalCategories: ["error", "lesson", "observation", "contradiction"],
     budgetTokens: 8_000,
   },
@@ -65,7 +73,7 @@ export const ROLE_POLICIES: readonly RoleContextPolicy[] = [
   {
     role: "implementer",
     label: "Implementer",
-    kinds: ["knowledge", "state", "skill", "episode"],
+    kinds: ["knowledge", "state", "skill", "episode", "evidence"],
     journalCategories: ["plan", "decision", "lesson", "state-change"],
     budgetTokens: 16_000,
   },
@@ -97,8 +105,9 @@ export interface ArbiterOptions {
   /** Pool item IDs that represent open contradictions; they are routed to the
    * packet's contradictions section instead of their kind's section. */
   contradictionIds?: string[];
-  /** Governed skill lifecycle to read and verify promoted skills by hash. */
-  skillLifecycle?: SkillLifecycle;
+  /** Governed skill lifecycle (or a pre-verified snapshot of one) to read and
+   * verify promoted skills by hash. */
+  skillLifecycle?: Pick<SkillLifecycle, "list" | "verify">;
 }
 
 export interface ArbiterOutcome {
@@ -114,12 +123,19 @@ export interface ArbiterOutcome {
     candidateCount: number;
     excludedSuperseded: number;
     unresolvedGaps: string[];
+    /** Numbers only: distinct task tokens, eligible candidates sharing a task
+     * token, and each selected item's rounded BM25 score (index-aligned with
+     * selectedIds). */
+    relevance: { taskTokens: number; matchedCandidates: number; selected: number[] };
   };
 }
 
 /** Deterministically assemble a role-aware context packet. Superseded and
  * rejected records are excluded by default; cross-project content fails
- * closed; the token budget is enforced on the serialized selection. */
+ * closed; eligible candidates are ranked by contradiction, project-first,
+ * task match, role kind priority, BM25 task relevance, confidence,
+ * authority, recency (newest first), then id by code unit; the token budget
+ * is filled first-fit on the serialized selection. */
 export function arbitrate(
   requestInput: unknown,
   pool: ContextItem[],
@@ -180,38 +196,62 @@ export function arbitrate(
     return rank === undefined ? requestedKinds.length : rank;
   };
 
-  const ordered = [...candidates].sort((left, right) =>
+  // Eligibility: open contradictions always compete; everything else must be
+  // a requested kind and not an inert proposal (a non-current state or a
+  // proposed skill), so proposals never consume budget.
+  const allowedKinds = new Set<ContextItemKind>(requestedKinds);
+  const inertProposal = (item: ContextItem): boolean =>
+    (item.kind === "state" && item.status !== undefined && item.status !== "current")
+    || (item.kind === "skill" && item.status === "proposed");
+  const eligible = candidates.filter((item) =>
+    contradictions.has(item.id) || (allowedKinds.has(item.kind) && !inertProposal(item)));
+
+  const scoreList = scoreRelevance(request.task, eligible.map(contextItemRelevanceText));
+  const scores = new Map<ContextItem, number>();
+  eligible.forEach((item, index) => scores.set(item, scoreList[index] ?? 0));
+  const scoreOf = (item: ContextItem): number => scores.get(item) ?? 0;
+  // Recency from the item's own timestamps; never reads the clock.
+  const when = (item: ContextItem): number => {
+    const parsed = Date.parse(item.observedAt ?? item.validFrom ?? "");
+    return Number.isFinite(parsed) ? parsed : 0;
+  };
+
+  const ordered = [...eligible].sort((left, right) =>
     (contradictions.has(right.id) ? 1 : 0) - (contradictions.has(left.id) ? 1 : 0)
     || (left.project === request.project ? 0 : 1) - (right.project === request.project ? 0 : 1)
+    || (scoreOf(right) > 0 ? 1 : 0) - (scoreOf(left) > 0 ? 1 : 0)
     || kindPreference(left) - kindPreference(right)
+    || scoreOf(right) - scoreOf(left)
     || CONFIDENCE_RANK[right.confidence] - CONFIDENCE_RANK[left.confidence]
     || AUTHORITY_WEIGHT[right.authority] - AUTHORITY_WEIGHT[left.authority]
-    || left.id.localeCompare(right.id),
+    || when(right) - when(left)
+    || compareCodeUnitIds(left.id, right.id),
   );
 
-  const kindAllowed = (item: ContextItem): boolean =>
-    (request.includeKinds ?? policy.kinds).includes(item.kind)
-    || contradictions.has(item.id);
-
+  // First-fit: an item that does not fit is deferred and smaller items keep
+  // filling the budget.
   const selected: ContextItem[] = [];
   const unresolvedGaps: string[] = [];
+  let characters = 0;
+  let deferredForBudget = 0;
   for (const item of ordered) {
     if (selected.length >= MAX_CONTEXT_ITEMS) {
       unresolvedGaps.push("context item limit reached; refine the task or kinds");
       break;
     }
-    if (!kindAllowed(item)) continue;
-    const nextTokens = estimateContextTokens([...selected, item]);
-    if (nextTokens > budget) {
-      if (selected.length === 0) {
-        unresolvedGaps.push(`budget of ${budget} tokens cannot fit any selected context`);
-        break;
-      }
-      unresolvedGaps.push(`budget of ${budget} tokens reached; ${ordered.length - selected.length} candidates deferred`);
-      break;
+    const itemCharacters = contextItemCharacters(item);
+    if (Math.ceil((characters + itemCharacters) / 4) > budget) {
+      deferredForBudget += 1;
+      continue;
     }
+    characters += itemCharacters;
     selected.push(item);
   }
+  if (deferredForBudget > 0) {
+    unresolvedGaps.push(selected.length === 0
+      ? `budget of ${budget} tokens cannot fit any selected context`
+      : `budget of ${budget} tokens reached; ${deferredForBudget} candidates deferred`);
+  }
   if (candidates.length === 0) {
     unresolvedGaps.push("no context records exist for this project yet");
   }
@@ -223,6 +263,7 @@ export function arbitrate(
     workingState: options.workingState ?? {},
     currentState: bySection("state").filter((item) => item.status === "current" || item.status === undefined),
     knowledge: bySection("knowledge"),
+    evidence: bySection("evidence"),
     episodes: bySection("episode"),
     skills: bySection("skill").filter((item) => item.status !== "proposed"),
     contradictions: selected.filter((item) => contradictions.has(item.id)),
@@ -249,6 +290,11 @@ export function arbitrate(
       candidateCount: candidates.length,
       excludedSuperseded,
       unresolvedGaps,
+      relevance: {
+        taskTokens: new Set(relevanceTokens(request.task)).size,
+        matchedCandidates: scoreList.filter((score) => score > 0).length,
+        selected: selected.map((item) => roundRelevance(scoreOf(item))),
+      },
     },
   };
 }
@@ -273,12 +319,11 @@ export function journalEntryToContextItem(entry: WorkflowJournalEntry, project:
     },
     authority: entry.category === "decision" || entry.category === "plan" ? "evidence" : "evidence",
     confidence: entry.severity === "error" ? "probable" : "probable",
-    ...(entry.stageId !== undefined ? { observedAt: entry.createdAt } : {}),
+    observedAt: entry.createdAt,
     evidenceRefs: entry.evidence
       .filter((ref) => ref.length > 0 && ref.length <= 200)
       .slice(0, 16),
   };
-  if (entry.stageId !== undefined) item.observedAt = entry.createdAt;
   if (kind === "skill") item.status = "proposed";
   return parseContextItem(item);
 }

package/plugins/kxm/src/autocomplete.ts

@@ -145,7 +145,7 @@ _kxm() {
     'peer:Peer agent messaging and coordination'
     'workflow:Start and inspect workflow runs'
     'gate:Validate definitions and operate evidence gates'
-    'improve:Propose CLI or project improvements'
+    'improve:Propose coded-repeat candidates from routing records'
     'context:KXM context operating-system queries'
     'skills:Governed skill candidate lifecycle'
     'memory:Harness-agnostic Git memory operations'