@kontextmind/kxm 0.7.91 → 0.7.93

package/docs/kxm-handbook.md

@@ -353,6 +353,8 @@ The complete variable reference, limits, and examples are in
 
 ## Complete CLI guide
 
+This section summarizes the most-used commands. The [CLI reference](cli-reference.md) documents every command and subcommand with its options, JSON output, and examples.
+
 Global options can appear on the root or a command group:
 
 ```text
@@ -431,14 +433,26 @@ posts an exact failed signal and exits `4` on timeout.
 ### Improvement command
 
 ```text
-kxm improve [--target cli|project]
+kxm improve [report] [--file <path>] [--out-dir <path>]
 ```
 
-This groups redacted `.kxm/logs/telemetry.jsonl` records into a proposed-only
-report. Named project/workflow activity is classified as `project`; unscoped
-operator activity is `cli`. `KXM_IMPROVE_TARGET=cli|project` explicitly
-overrides that classification. The command does not automatically modify code,
-configuration, gates, or the workflow journal.
+This looks for agent steps a script, test or workflow `gate` could do instead of a
+model. Run it from the project root. It reads the project's Runtime event store
+read-only (the checkout's own `run-events.db` under the user state root) and then
+`.kxm/logs/telemetry.jsonl`; `--file` reads only the named file. The output starts
+with the sources it read and their counts, and an unreadable store exits 1 with
+`improve_source_unreadable`. Each Runtime attempt's outcome is resolved from the
+event log (`accepted` only when its run completed and the step was not re-entered).
+
+Records group by workflow, step, agent role and ask. A group is a coded-repeat
+candidate only when the same ask was decided in at least two runs, at least 0.75 of
+its decided attempts were accepted, and its step writes no repository; otherwise the
+row says why (`writes-repository` or `ask-not-repeated`). Candidates are written as
+proposed JSON and diff files under `.kxm/candidates/` (not with `--dry-run`), and
+each gets a promotion readiness line under `improvement.promotionPolicy`. Readiness
+never authorizes: the command does not modify code, configuration, gates, or the
+workflow journal, and activation is a reviewed Git change. See
+[Continuous improvement](continuous-improvement.md#coded-repeats-kxm-improve).
 
 ### Context commands
 
@@ -669,8 +683,8 @@ These tools are available in Pi and Claude MCP:
 | `kxm_workflow_get` | Read stages, evidence policies, waits, and journal |
 | `kxm_workflow_checkpoint` | Submit a stage result with keyed evidence and verified message references |
 | `kxm_workflow_wait` | Save evidence and pause until an authenticated callback |
-| `kxm_workflow_record` | Record a plan, decision, contradiction, error, or lesson |
-| `kxm_improvement_report` | Summarize learning by improvement area |
+| `kxm_workflow_record` | Record journal knowledge in one of ten categories, optionally bound to a stage with `stageId` |
+| `kxm_improvement_report` | Summarize learning by improvement area, plus ranked, redacted signals merged across runs |
 
 Claude MCP also exposes:
 
@@ -741,7 +755,7 @@ For every active stage:
 
 1. call `kxm_workflow_get`;
 2. follow only `currentStage`;
-3. record material plans, decisions, contradictions, errors, and lessons;
+3. record material knowledge in the journal categories below, passing the stage's `stageId`;
 4. gather exact required evidence;
 5. send peer-policy work with exact `workflowContext` when required;
 6. checkpoint or enter an external wait; and
@@ -759,10 +773,20 @@ compute until the callback creates a fresh message.
 | `decision` | Selected option and rationale |
 | `contradiction` | Incompatible evidence, claims, requirements, or tests |
 | `error` | Failed tools, assumptions, integrations, or gates |
-| `lesson` | Evidence-supported reusable improvement |
+| `lesson` | Evidence-supported reusable improvement (evidence required) |
+| `observation` | Notable behavior without a causal claim |
+| `hypothesis` | A falsifiable claim; keep it when disproven |
+| `experiment` | A trial and its outcome, including failures |
+| `state-change` | An authoritative project fact changed |
+| `skill-candidate` | A reusable procedure backed by verified run or receipt evidence (evidence required) |
 
 Areas are `harness`, `gates`, `implementation`, `workflow`, `documentation`,
-`security`, or `other`.
+`security`, or `other`. Pass `stageId` (`--stage-id` on the CLI) to bind an entry to
+its stage: the hub derives the attempt (the current one for an active or waiting
+stage, the last one consumed for a finished stage), and `area` may be omitted when the
+stage declares one. An entry with neither an area nor such a stage is refused with
+`invalid_improvement_area`. The journal covers hub webhook runs; a `kxm run` id is
+refused with `workflow_not_found`.
 
 ---
 
@@ -888,16 +912,79 @@ through `kxm_context`, `kxm_recall`, `kxm_state`, `kxm_episode`, and
 
 `kxm context get <project> --role <role> --task <task>` assembles a
 token-budgeted packet. Roles shape selection: repro agents get prior
-reproductions and incidents; planners get state and decisions; critics get
-contradictions and failed approaches; implementers get the approved plan and
-skills; verifiers get acceptance evidence. Superseded and rejected records
-are excluded by default, and every packet is project-isolated.
+reproductions, incidents and evidence; planners get state and decisions; critics
+get contradictions and failed approaches; implementers get the approved plan,
+skills and evidence; verifiers get acceptance evidence. Superseded and rejected
+records are excluded by default, and every packet is project-isolated.
+
+Selection is deterministic: no model, clock or randomness is involved, so the same
+records and request give the same packet. An item is eligible when it is an open
+contradiction or a requested kind that is not an inert proposal (non-current state
+and proposed skills are never selected). Eligible items are ordered by nine keys, in
+this order:
+
+1. open contradictions first;
+2. the requested project before `_shared` defaults;
+3. items that share a word with the task before items that do not;
+4. the role's kind priority;
+5. a lexical BM25 relevance score over the item's summary and state key (fixed English
+   stopword list, plural folding);
+6. confidence;
+7. authority;
+8. recency, newest first, from the item's own timestamps;
+9. id, by code unit.
+
+The budget is filled first-fit: an item that does not fit is skipped and smaller
+items keep filling it, and a gap such as `budget of 4000 tokens reached; 2 candidates
+deferred` reports what was left out. The packet has `currentState`, `knowledge`,
+`evidence`, `episodes`, `skills` and `contradictions` sections, so every selected
+item is delivered in one of them. The response's `audit.relevance` holds numbers only:
+`taskTokens` (distinct task words), `matchedCandidates` (eligible items sharing a
+task word) and `selected` (each selected item's rounded score, in `selectedIds`
+order). The hub log records the task's size, never its text.
 
 `kxm context recall <project> --query <text>` searches durable context records
-and returns metadata only. `kxm context episode <project>` lists episodic
-learning records from workflow journals (`--run` limits to one run).
-`kxm context explain <project> <itemId>` explains which evidence and lineage
-back a context item.
+and returns metadata only, with a numeric `relevance` per item. Items whose summary or
+state key contains the query (ignoring case) come first, then items that share a word
+with it ranked by relevance, then id; items with neither are left out.
+`kxm context episode <project>` lists episodic learning records from workflow
+journals (`--run` limits to one run). `kxm context explain <project> <itemId>`
+explains which evidence and lineage back a context item.
+
+### Context for Runtime-dispatched agents
+
+When `kxm run` dispatches an agent step, the Runtime gives the agent the project's
+authored memory (active `.kxm/memory/*.md` records in project or operator scope) and
+its promoted skills whose content hash verifies, selected by the same arbiter for the
+agent's role with the step instructions and prompt as the task, within 4,000 tokens
+(or the role's budget when lower). The prompt renders them under **Environment &
+Memory**, with promoted skills under **Active Skills**; at most five project items are
+delivered because the prompt renders five.
+
+Only committed content is delivered: the memory and promoted-skill files must be
+tracked and clean at `HEAD` (`git status` over those paths), and the memory revision
+must still match the one the run pinned when it was created. Otherwise the context is
+withheld and the packet records a gap instead:
+
+| Gap | Meaning |
+|---|---|
+| `dispatch_context_withheld:uncommitted` | A memory or promoted-skill file is modified, untracked or ignored |
+| `dispatch_context_withheld:git_unavailable` | `git status` failed or timed out (5 s) |
+| `dispatch_context_withheld:memory_revision_drift` | Memory or skills changed since the run pinned its revision |
+| `dispatch_context_memory_unreadable` | A memory file does not parse |
+| `dispatch_context_memory_rejected:<id>` | One record could not become a context item |
+| `dispatch_context_skill_unverified:<id>` | A promoted skill's content does not match its hash |
+| `dispatch_context_skills_unreadable` | The promoted skills could not be listed |
+| `dispatch_context_render_deferred:<n>` | More project items were selected than the prompt renders |
+| `dispatch_context_not_loaded` | The context could not be loaded for this step before dispatch |
+| `dispatch_context_failed` | Loading or assembly failed unexpectedly |
+
+Gaps go in the packet's `budget.unresolvedGaps`, never in the prompt, and a gap never
+blocks dispatch: the step runs without the withheld context. Memory with `agent` or
+`run` scope is not delivered, because nothing binds it to an agent or run. No hub
+source (journal, stored state, contradictions) is read at dispatch, so a Runtime run
+works with the hub down. A project with no memory and no promoted skill dispatches
+exactly as before.
 
 ### Temporal state and promotion
 

package/docs/templates/README.md

@@ -10,7 +10,7 @@ This directory contains standardized Markdown documentation templates adapted fo
 
 3. **Immutable Evidence Chains:** Every test or review report must reference an exact commit pin (`git rev-parse HEAD`), deterministic branch (`kxm/run-<id>-<description>`), and content-addressed artifact reference (`artifact:<path>@sha256:<digest>`).
 
-4. **Context Arbiter Integration:** Frontmatter fields (`authority`, `confidence`, `summary`, `tags`) directly inform token budgeting and relevance pruning in `kxm.context-packet.v2`.
+4. **Context Arbiter Integration:** Frontmatter fields (`authority`, `confidence`, `summary`, `tags`) inform token budgeting in `kxm.context-packet.v2`: layer pruning plus lexical task-relevance ordering in the arbiter.
 
 ---
 

package/docs/test-matrix.md

@@ -2,8 +2,9 @@
 
 The release gate executes every test, measures the core source directly, type-checks strict TypeScript, lints documentation, verifies package versions, validates Claude manifests, rebuilds the generated runtimes, and installs and executes the npm artifact outside the repository.
 
-Run the commit gate with `npm run verify`. CI PR legs run `validate:ci` plus
-`check:generated`. Plugin validation is a hosted CI job.
+Run the commit gate with `npm run verify`. CI PR legs run `validate:pr` plus
+`check:generated`; pushes to main run `validate:ci`. Plugin validation is a hosted CI
+job.
 
 ```powershell
 npm run verify
@@ -35,13 +36,18 @@ npm run verify
 | Claude MCP catalog, outbound and inbound tools, channel delivery | `test/core/mcp.test.ts` |
 | Responsive metadata-only TUI, authenticated ops mode, presence-only fallback, observer filtering, key controls, and local body-free projection | `test/core/tui.test.ts`, `test/core/hub-api.test.ts` |
 | Session manifest creation, fail-closed rosters, shared worker/result envelopes, and hub-owned envelope fields | `test/core/session.test.ts`, `test/core/cli.test.ts`, `test/core/envelope.test.ts`, `test/core/envelope-contract.test.ts` |
-| Generic CLI/project telemetry classification, JSONL recovery, and proposed `kxm improve` output | `test/core/telemetry.test.ts`, `test/core/cli.test.ts` |
+| Generic CLI/project telemetry classification, JSONL recovery, and proposed `kxm improve` output | `test/core/telemetry.test.ts`, `test/core/cli.test.ts`, `test/core/improve.test.ts` |
+| `kxm improve` and `kxm routing report` read the project's Runtime event store read-only plus telemetry, resolve each attempt's outcome from the event log, drop simulated attempts and duplicate attempts, flag only same-ask repeats across runs, exclude write steps, and report promotion readiness that never authorizes | `test/core/improve.test.ts` (`kxm improve report resolves Runtime-settled attempts from the event log and flags only same-ask cross-run repeats`), `test/core/cli.test.ts`, `test/core/cli-experience.test.ts`, `test/core/commands-policy.test.ts` |
+| Engine routing records carry the engine-reserved `workflowId`, `askSha256`, `objectiveSha256` and `stepWrites` keys (stable across runs), default `agentRole` to the agent, and record only `blocked` or `failed` at settlement | `test/core/route-admission.test.ts` |
+| Runtime dispatch context: only committed, pinned project memory and hash-verified promoted skills reach a dispatched agent; malformed, drifted or uncommitted content is withheld with a `dispatch_context_*` gap outside the prompt, and the step still completes | `test/core/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`) |
 | Signed Jira webhook verification, filtering, dispatch, and retry deduplication | `test/core/hub-api.test.ts` |
 | Ordered workflow checkpoints, normalized keyed evidence gates, unrelated-volume rejection, and warning/failure retry | `test/core/hub-api.test.ts`, `test/core/workflow.test.ts` |
 | Run-start eligible-producer resolution, immutable workflow context, per-requirement message-reference verification, unique-producer quorum, and replay/cross-context rejection | `test/core/workflow-provenance.test.ts`, `test/core/workflow.test.ts`, `test/core/hub-api.test.ts`, `test/core/client.test.ts`, `test/core/store.test.ts` |
 | Explicit current-attempt admin degradation, configured lower minimum, audit journal, idempotency, and forbidden or stale approvals | `test/core/workflow-provenance.test.ts`, `test/core/cli.test.ts` |
 | Durable external waits, local/callback evidence accumulation, safe settlement, checkpoint/expiry race rejection, minimal signed responses, retry/conflict deduplication, separate secrets, and timeout notification | `test/core/hub-api.test.ts`, `test/core/workflow.test.ts`, `test/core/workflow-provenance.test.ts` |
 | Plans, decisions, contradictions, errors, lessons, and improvement reports | `test/core/hub-api.test.ts`, `test/core/workflow.test.ts` |
+| All ten journal categories and `stageId` through the shared `kxm_workflow_record` tool, hub-derived attempt, stage-default area, stage-bound hub-authored entries, ranked redacted cross-run signals, and retrospectives refreshed by late entries and promotions | `test/core/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`), `test/core/workflow.test.ts`, `test/core/retrospective.test.ts`, `test/core/hub-api.test.ts` |
+| Context packets rank by deterministic task relevance, fill the budget first-fit, deliver every selected item (including evidence) in a packet section, order ties newest first, and report numeric `audit.relevance`; recall ranks by phrase then relevance; hub logs carry sizes, not task or query text | `test/core/arbiter.test.ts` (`arbitrate ranks task-relevant candidates first, delivers every selected item in a packet section, orders ties newest first, and reports relevance`), `test/core/context-surfaces.test.ts` |
 | Safe diagnostic classification and redaction | `test/core/diagnostics.test.ts`, `test/core/extension.test.ts`, `test/core/hub-api.test.ts` |
 | Operator CLI init/validate/export/watch | `test/core/cli.test.ts`, `test/core/github-watch.test.ts` |
 | Local and isolated-global packed npm CLI plus hub runtimes | `test/core/package-install.test.ts` |
@@ -115,12 +121,12 @@ When adding a feature, add executable coverage and update this matrix in the sam
 | `test/core/context.test.ts` | Context schema round-trips, hostile input, cross-project fail-closed, storage upgrade |
 | `test/core/state.test.ts` | Temporal state lifecycle, asOf queries, supersession, contradictions, restart durability |
 | `test/core/context-authority.test.ts` | Authority grant floor, reserialization escalation, lineage bounds, control-plane smuggling |
-| `test/core/arbiter.test.ts` | Role-aware packet assembly, budgets, contradiction routing, journal conversion, hub surfaces |
+| `test/core/arbiter.test.ts` | Role-aware packet assembly, task-relevance ranking, first-fit budgets, the evidence section, contradiction routing, journal conversion, hub surfaces |
 | `test/core/context-surfaces.test.ts` | CLI and Pi tool parity for the context API |
-| `test/core/journal-evolution.test.ts` | New journal categories, evidence requirements, governed promotion |
+| `test/core/journal-evolution.test.ts` | New journal categories, evidence requirements, governed promotion, stage provenance through the shared tool |
 | `test/core/wiki.test.ts` | Wiki compilation determinism, lifecycle preservation, contradiction visibility, lint |
 | `test/core/workflow-transitions.test.ts` | Typed back-edges, budgets, bypass protection, restart recovery |
 | `test/core/fix-workflow.test.ts` | /fix end-to-end, independent repro-review oracle, wrong-seam invalidation, failed self-retry, plan-hash gating, exhaustion |
 | `test/core/skills.test.ts` | Skill candidate lifecycle, quarantine, immutability, CLI |
 | `test/core/routing.test.ts` | Behavioral hash, record parsing, comparisons, routing report |
-| `test/core/migration.test.ts` | v0.4 → v0.5 database upgrade fixture |
+| `test/core/improve.test.ts` | Routing-record sources, event-log outcome resolution, same-ask candidacy, candidate files, promotion readiness |

package/docs/troubleshooting.md

@@ -24,7 +24,7 @@ KXM waits until Pi has exhausted its own automatic retries. It then keeps the in
 
 ### A worker heartbeat is healthy but one tool never finishes
 
-Set `KXM_WORKER_TOOL_TIMEOUT_MS` above the longest legitimate tool call. Its 31-minute default intentionally gives a 30-minute `kxm_await` or `kxm_fanout` time to return durable pending handles before supervision intervenes. When that bound is exceeded, the structured worker log records `worker_tool_timeout` with only the allowlisted tool name and diagnostic class, the delivered hub request stays recoverable, and the RPC process is restarted. If the stuck worker was supposed to be read-only, also set `KXM_WORKER_TOOLS=read,grep,find,ls`; prompt wording alone does not remove shell or write capabilities.
+Set `KXM_WORKER_TOOL_TIMEOUT_MS` above the longest legitimate tool call. Its 31-minute default intentionally gives a 30-minute `kxm_fanout` wait time to return durable pending handles before supervision intervenes. When that bound is exceeded, the structured worker log records `worker_tool_timeout` with only the allowlisted tool name and diagnostic class, the delivered hub request stays recoverable, and the RPC process is restarted. If the stuck worker was supposed to be read-only, also set `KXM_WORKER_TOOLS=read,grep,find,ls`; prompt wording alone does not remove shell or write capabilities.
 
 ### A hub or worker PID claim is stale
 
@@ -148,7 +148,7 @@ If the work is obsolete, the sender can call `kxm_cancel`. This changes hub stat
 
 ### `kxm_await` times out
 
-The default timeout is 30 minutes. Use `kxm_get` to inspect the state. `cancelled`, `expired`, and `error` are terminal outcomes. Resend only when the task is safe to repeat, and use an idempotency key when retrying after an uncertain network result.
+`kxm_await` waits at most 60 seconds; that is both its default and its maximum. A timeout does not end the request. Use `kxm_get` to inspect the state, or `kxm_workflow_wait` for long external work. `cancelled`, `expired`, and `error` are terminal outcomes. Resend only when the task is safe to repeat, and use an idempotency key when retrying after an uncertain network result.
 
 ### A message disappears after completion
 

package/examples/project/.kxm/workflows/fix.yaml

@@ -329,7 +329,7 @@ steps:
     timeoutMs: 1800000
     on:
       passed: ci-watch
-      failed:
+      implementation-failure:
         target: $terminal
         terminalStatus: failed
       blocked:

package/examples/project/.kxm/workflows/improve.yaml

@@ -34,7 +34,7 @@ steps:
     timeoutMs: 1800000
     on:
       passed: ready
-      failed:
+      implementation-failure:
         target: $terminal
         terminalStatus: failed
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kontextmind/kxm",
-  "version": "0.7.91",
+  "version": "0.7.93",
   "description": "KXM local-first multi-agent orchestration and operator dashboard",
   "type": "module",
   "author": "KontextMind",

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

@@ -2,7 +2,7 @@
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "kxm",
   "displayName": "KXM",
-  "version": "0.7.91",
+  "version": "0.7.93",
   "description": "Headless multi-agent orchestration, durable workflows, and a live operator dashboard for Pi and Claude Code",
   "author": {
     "name": "KontextMind",
@@ -19,11 +19,10 @@
         "hooks": [
           {
             "type": "command",
-            "command": "kxm session brief --status"
-          },
-          {
-            "type": "command",
-            "command": "kxm memory brief"
+            "command": "node",
+            "args": ["${CLAUDE_PLUGIN_ROOT}/dist/claude-hook.js", "session-start"],
+            "timeout": 5,
+            "statusMessage": "KXM brief"
           }
         ]
       }
@@ -38,21 +37,21 @@
     "server_url": {
       "type": "string",
       "title": "KXM server URL",
-      "description": "URL of the running KXM hub",
+      "description": "URL of the KXM hub (the operator starts it with kxm hub start)",
       "default": "http://127.0.0.1:7331",
       "required": true
     },
     "auth_token": {
       "type": "string",
       "title": "Authentication token",
-      "description": "Project bearer token for this agent",
+      "description": "Project token for this project from the hub KXM_PROJECT_TOKENS. Leave blank on the machine that runs the hub to use the project token the hub saved for this project. The hub admin token is never used",
       "sensitive": true,
       "required": false
     },
     "agent_name": {
       "type": "string",
       "title": "Agent name",
-      "description": "Unique name shown to other agents in the project",
+      "description": "Name other agents see. The first active session in a project keeps it; a later concurrent session registers as <name>-<pid>",
       "default": "claude",
       "required": true
     },
@@ -66,7 +65,7 @@
     "project": {
       "type": "string",
       "title": "Project",
-      "description": "Optional project namespace; defaults to the current directory name",
+      "description": "Hub project key; must match a key in the hub KXM_PROJECT_TOKENS. Blank uses the package.json name, then the directory name",
       "required": false
     }
   }