@kontextmind/kxm 0.7.91 → 0.7.93

package/docs/configuration.md

@@ -19,6 +19,27 @@ because it is in the file: an unknown `hub.autoStart` fails closed to the
 default, and an unset `defaults.harness` means Pi rather than the first harness
 in the catalog.
 
+### Improvement settings (`improvement.*`)
+
+`kxm improve` reads these keys from the project it runs in (and the user scope) and
+reports them in its output. They are normalized field by field whenever the
+configuration loads, so a typo falls back to the default instead of changing what the
+report says:
+
+| Key | Default | Accepted values; anything else becomes the default |
+|---|---:|---|
+| `improvement.promotionPolicy` | `manual_pr` | `manual_pr`, `critic_quorum`, or `auto_threshold` |
+| `improvement.telemetryHalfLifeDays` | `14` | A number greater than 0 and at most 3650 |
+| `improvement.autoThreshold.minRuns` | `10` | An integer from 1 to 1,000,000 |
+| `improvement.autoThreshold.minPassRate` | `0.95` | A number from 0 to 1 |
+| `improvement.autoThreshold.minCostSavings` | `0.5` | A number of at least 0 |
+
+None of these values can authorize or activate anything. The policy only selects which
+review-readiness rule `kxm improve` reports for each candidate, and every policy ends at
+an operator PR. The half-life weights report rows (`weightedRecurrence`) and never
+decides whether a group is a candidate. See
+[Continuous improvement](continuous-improvement.md#coded-repeats-kxm-improve).
+
 Project identity and repository bindings are separate, Git-tracked files under
 `.kxm/` (`project.yaml`, `roster.yaml`, `routes.yaml`, `gates.yaml`, `prices.yaml`,
 `roles/`, `workflows/`). They are configuration reviewed in a PR, not personal
@@ -95,6 +116,8 @@ rewrites it.
 | `KXM_WEBHOOK_WORKFLOWS` | None | Inline JSON array of signed webhook workflow definitions |
 | `KXM_WEBHOOK_WORKFLOWS_FILE` | None | Path to the workflow-definition JSON file |
 
+The hub's structured log (`KXM_LOG_PATH`) records the size of a context request, not its text: `context_packet_assembled` carries `taskChars`, `taskTokens` (distinct words after stopword removal) and `matchedCandidates` beside the selected ids, provenance summary and token estimate, and `context_recall` carries `queryChars`, `queryTokens`, `limit` and `results`. The task and query text appear only in the caller's own response.
+
 The hub refuses a non-loopback bind without `KXM_AUTH_TOKEN`. Use a long random administrative token even when project tokens are configured, because administrative endpoints such as `/metrics` require it outside loopback.
 
 When `KXM_AUTH_TOKEN` is unset, `kxm hub start` resolves credentials from the
@@ -190,7 +213,8 @@ read from source; it does not invent defaults.
 | Agent stale threshold | 30 seconds |
 | Client request timeout | 15 seconds |
 | Default message TTL | 24 hours |
-| Default `kxm_await` timeout | 30 minutes |
+| `kxm_await` wait | 60 seconds (default and maximum) |
+| Default `kxm_fanout` local wait | 30 minutes |
 | Default workflow signal wait | 24 hours |
 | Workflow signal wait range | 1 second to 30 days |
 
@@ -300,12 +324,14 @@ The current hub command groups are `agent`, `session`, `workflow`, `gate`, `hub`
 | `kxm dash` | Open the read-only SSE observer dashboard; non-TTY output is one ANSI-free snapshot |
 | `kxm hub start` | Start the KXM hub in the foreground |
 | `kxm hub stop` | Request managed hub and worker shutdown |
-| `kxm improve` | Bucket `.kxm/logs/telemetry.jsonl` events into a proposed-only improvement report; does not read the workflow journal |
+| `kxm improve` | Propose coded-repeat candidates from routing records: the current project's Runtime event store (read-only) and `.kxm/logs/telemetry.jsonl`, or only the file named by `--file`. Prints the sources it read, writes proposed candidates under `.kxm/candidates/`, and reports promotion readiness under `improvement.promotionPolicy`; nothing is applied and no policy authorizes. Does not read the workflow journal |
 | `kxm context get \| recall \| state \| episode \| promote \| explain \| wiki-compile \| wiki-lint` | Context operating system: role-aware packets, metadata search, temporal state, episodes, evidence-backed lineage (`explain`), wiki compile/lint |
 | `kxm skills` | Governed skill candidate lifecycle |
-| `kxm memory sync` | Regenerate the read-only project-memory block — authored facts from `.kxm/memory/` only — between `<!-- kxm:memory:start -->` and `<!-- kxm:memory:end -->` in whichever of `AGENTS.md`, `CLAUDE.md` and `GEMINI.md` already exist in the current directory. Text outside the markers is never rewritten; a file without markers gets the block appended. Missing files are reported as `missing` and **not created** — which harness a project uses is its own choice — and with none present sync exits 1 without writing. `--json` reports `updated`, `unchanged` and `missing` |
+| `kxm memory sync` | Regenerate the read-only project-memory block — authored facts from `.kxm/memory/` only — between `<!-- kxm:memory:start -->` and `<!-- kxm:memory:end -->` in whichever of `AGENTS.md`, `CLAUDE.md` and `GEMINI.md` already exist in the current directory. Text outside the markers is never rewritten; a file without markers gets the block appended. Each file must hold exactly one start marker followed by exactly one end marker, or neither: an orphan marker, an end before its start, or a second block makes sync exit 1 naming the file and the problem, and **no file is written**, the well-formed ones included. Missing files are reported as `missing` and **not created** — which harness a project uses is its own choice — and with none present sync exits 1 without writing. `--json` reports `updated`, `unchanged` and `missing` |
+
+Telemetry events carry a `target` label: `project` whenever a project or workflow identity is present, and `cli` for unscoped operator behavior. `KXM_IMPROVE_TARGET=cli` or `KXM_IMPROVE_TARGET=project` overrides that label when an event is written. No report reads the label, and `kxm improve` has no `--target` option.
 
-Improvement telemetry is classified as `project` whenever a project or workflow identity is present, and as `cli` for unscoped operator behavior. Set `KXM_IMPROVE_TARGET=cli` or `KXM_IMPROVE_TARGET=project` only when an operator needs to override that generic classification; this changes report bucketing, not workflow state.
+Journal entries recorded with `kxm workflow record` or `kxm_workflow_record` take one of ten categories (`plan`, `decision`, `contradiction`, `error`, `lesson`, `observation`, `hypothesis`, `experiment`, `state-change`, `skill-candidate`). `--stage-id` binds the entry to a stage; the hub derives the attempt, and the area defaults to the stage's declared area. The journal covers hub webhook runs only; a `kxm run` id is refused with `workflow_not_found`.
 
 The gate group contains exactly the five implemented gates listed above. Names declared in a workspace `gates.json` that do not map to one of them (for example `quality`, `git-commit`, `jira-fetch`) are records with no runner; there is no `kxm gate run <name>`.
 

package/docs/continuous-improvement.md

@@ -5,11 +5,16 @@ Every workflow run produces two distinct records:
 - operational events for service health and delivery;
 - a structured journal for plans, decisions, contradictions, errors, lessons, observations, hypotheses, experiments, state changes, and skill candidates.
 
-`kxm improve` buckets redacted `.kxm/logs/telemetry.jsonl` events into a
-proposed-only report and does not read the workflow journal. Journal capture
-uses `kxm_workflow_record`. Terminal runs export a bounded retrospective under
-`.kxm/assets/retrospectives`; re-export from durable local state with
-`kxm workflow export`.
+The journal and retrospective loop covers hub webhook runs (signed webhooks and
+`kxm workflow start`). Runs started with `kxm run` on the Runtime have no journal or
+retrospective yet: `kxm_workflow_record` answers `workflow_not_found` for a Runtime
+run id. Journal capture uses `kxm_workflow_record`. Terminal runs export a bounded
+retrospective under `.kxm/assets/retrospectives`; re-export from durable local state
+with `kxm workflow export`.
+
+`kxm improve` is a separate loop. It reads routing records (the Runtime's settled
+attempts and telemetry), not the journal, and proposes coded repeats; see
+[Coded repeats](#coded-repeats-kxm-improve).
 
 Journal entries carry an improvement area, severity, evidence links, relationships to other entries, and (when stage-bound) run/stage/attempt provenance. The design preserves disagreement instead of flattening it into a single final answer.
 
@@ -40,15 +45,25 @@ Use `kxm_workflow_record` during the run, not only in a final retrospective:
 - record a `state-change` when an authoritative project fact changes;
 - record a `skill-candidate` only with verified run/receipt evidence; candidates never become promoted skills without a protected evaluation.
 
+`kxm_workflow_record` (and `kxm workflow record`) accepts all ten categories above.
+Pass `stageId` to bind an entry to the stage it is about. The hub, never the caller,
+derives the attempt from the stage's state: the current attempt for an in-progress or
+waiting stage, the last attempt consumed for a finished stage, and none for a pending
+stage that has not run. When `stageId` names a stage that declares an area, `area` may
+be omitted and defaults to that area; otherwise `area` is required, and a request with
+neither is refused with `invalid_improvement_area`. A `stageId` that is not part of the
+run is refused with `invalid_journal_relation`. `lesson` and `skill-candidate` entries
+still require evidence references.
+
 ## Governed promotion
 
 `skill-candidate`, `hypothesis`, and `experiment` entries participate in a governed lifecycle: `proposed` → `approved` | `rejected` | `quarantined`. Promotion is an append-only, admin-controlled decision (`POST /v1/journal/:id/promotion`) that requires durable evidence references; the author of an entry can never decide its promotion, and terminal states never re-open. Promotion changes the learning lifecycle of an entry — never gates, workflow policy, or permissions.
 
-The native Pi extension automatically records failed tool results while a webhook workflow is active. The hub also records stage warnings/failures, prompt expiry, and premature coordinator settlement. Agents must still record semantic errors such as a false assumption, rejected design, flaky result, or external integration mismatch.
+The native Pi extension automatically records failed tool results while a webhook workflow is active. The hub also records checkpoint warnings and failures, transition-budget exhaustion, signed signal results, external-wait timeouts, prompt expiry, degraded-quorum approvals, and premature coordinator settlement, each bound to its stage and attempt. Agents must still record semantic errors such as a false assumption, rejected design, flaky result, or external integration mismatch.
 
 Never put secrets or unnecessary prompt contents in the journal. Evidence should be durable references such as test names, logs, commits, pull requests, Jira issues, check runs, or documentation paths. Failed tools record an allowlisted diagnostic class, not stdout.
 
-Every terminal workflow automatically exports a bounded retrospective under `.kxm/assets/retrospectives`. Re-export one from durable local state with `kxm workflow export <runId>`; `--input <snapshot.json>` remains available for offline imports. Files stay `reviewDecision=proposed` until a human or coordinator records an explicit decision. Export never edits workflow JSON or weakens gates.
+Every terminal workflow automatically exports a bounded retrospective under `.kxm/assets/retrospectives`, and exports it again when a journal entry is recorded or a promotion decided after the run ended. Re-export one from durable local state with `kxm workflow export <runId>`; `--input <snapshot.json>` remains available for offline imports. `recurringErrorClasses` counts `error` entries only. `proposedImprovements` holds up to 12 of the run's error and lesson entries, merged and ranked the same way as the weekly signals below, each with a success measure that names the signal key. Files stay `reviewDecision=proposed` until a human or coordinator records an explicit decision. Export never edits workflow JSON or weakens gates.
 
 Runs with peer policies add an optional metadata-only evidence audit while
 retaining the `pi-mesh.retrospective.v1` schema. It records each requirement's
@@ -68,13 +83,37 @@ The retrospective stage reviews journal entries, groups contributing causes, and
 
 ### Weekly
 
-Call `kxm_improvement_report` and review the top errors, contradictions, and lessons in each area. Merge duplicates while retaining source run IDs. Rank candidates using:
+Call `kxm_improvement_report`. Besides the per-area counts it returns `signals`: the
+project's errors, contradictions, lessons and skill candidates, already merged across
+runs and ranked. Review the top signals, check that each merge groups entries that
+belong together, and pick what to trial.
+
+- Entries merge when they share a key: first an evidence class (`class:<name>` in the
+  entry's evidence), then, for errors, the workflow definition and stage, then the
+  summary after redaction and normalization (ids, timestamps, hex strings and numbers
+  are folded). Text is redacted before it becomes a key, so a key never carries a raw
+  summary. Each signal keeps up to 16 source run IDs and entry IDs.
+- Only errors, open contradictions (not yet resolved by a related decision or lesson),
+  lessons, and skill candidates still `proposed` count.
+- `frequency` is the number of distinct runs, counted over the runs the hub still
+  retains: terminal runs and their journal are purged 7 days after they end.
 
 ```text
-priority = frequency × severity × workflow cost × confidence
+priority = frequency × severity weight × workflow cost × confidence
 ```
 
-Do not let frequency alone dominate security or data-loss risk.
+- The severity weight is 3 for `error`, 2 for `warning` and 1 for `info`, taken from the
+  most severe entry in the signal.
+- Workflow cost is the mean number of run attempts (stage attempts plus transitions)
+  over the signal's known runs. It is not dollars. When none of the runs is known it
+  counts as 1 and the signal reports `costBasis: "unknown"`.
+- Confidence is 0.5 plus half the share of the signal's entries that cite evidence.
+
+Security signals (area `security`, or evidence class `invalid_auth`,
+`invalid_identity` or `signal_mismatch`) rank ahead of every priority. Remaining ties
+break on frequency, then key, never on entry ID or insertion order. There is no
+data-loss override yet, because no deterministic data-loss marker exists, so review
+data-loss risk by hand rather than trusting the order.
 
 ### Per release
 
@@ -89,9 +128,82 @@ Select a small improvement batch. For each proposal:
 7. Adopt, revise, or roll back the proposal.
 8. Record the decision and result in a subsequent workflow journal.
 
+## Coded repeats (`kxm improve`)
+
+`kxm improve` (the same as `kxm improve report`) looks for agent steps that a script,
+test or workflow `gate` could do as well as a model. It proposes; it never applies.
+
+**Sources.** Inside a KXM project it reads the project's Runtime event store,
+`<state>/runtime/projects/<key>/run-events.db`, and then `.kxm/logs/telemetry.jsonl`.
+The key comes from the checkout's real path, so each checkout and worktree has its own
+store and the report covers only the one it runs in. The store is opened read-only for
+one query over its events table; `kxm improve` never creates, writes or migrates it. A
+telemetry record whose `attemptId` the store already supplied is dropped. `--file
+<path>` reads only that file. Outside a project only telemetry is read. The output lists
+every source with its path, whether it exists, and its counts (`records`,
+`skippedInvalid`, `excludedSimulated`, `undecided`, `duplicatesDropped`). An unreadable
+store stops the command with `improve_source_unreadable` and the path (exit 1).
+
+**Identity.** Records group by workflow, step, agent role and ask. Runtime records carry
+the engine-reserved `workflowId` and `askSha256` keys. The ask digest covers the
+workflow, step, step kind, agent, instructions, outcomes and required evidence keys, so
+it is the same for one step across runs and ignores the run, attempt, model and context
+packet. Records without those keys fall back to a workflow definition digest or the run
+ID, and to `rolePromptSha256`. No prompt text is read or stored: `objectiveSha256` is
+the digest of the run's prompt.
+
+**Outcomes.** A Runtime record stores `finalOutcome` only when settlement already knows
+it: `blocked` for a back edge, and `failed` for a producer error, an undeclared outcome
+or a failing terminal. Everything else is resolved when the report reads the event log,
+and never written back: a later entry into the same step makes the attempt `reworked`, a
+completed run makes it `accepted`, a failed run makes it `failed`, and a cancelled or
+still-running run leaves it undecided. Undecided records are counted and left out of the
+pass rate. Attempts from simulated drives are excluded and counted.
+
+**Candidacy.** A group becomes a coded-repeat candidate only when all three hold:
+
+- the same objective (`objectiveSha256`) was decided in at least 2 runs
+  (`askRecurrence`); records without an objective digest share one bucket;
+- at least 0.75 of its decided records were accepted (`verifyPassRate`), where an
+  attempt superseded by a later retry of the same step in the same run never counts as a
+  pass;
+- its step writes no repository (`writesRepository`, from the engine's `stepWrites` key).
+
+A group that passes but misses reports `excludedReason`: `writes-repository`, or
+`ask-not-repeated` when its runs asked different objectives. `weightedRecurrence`
+weights each record by `2^(-age / improvement.telemetryHalfLifeDays)` (14 days by
+default; an undated record weighs 1 and is counted in `undatedRecords`). It orders the
+rows and never decides candidacy.
+
+**Outputs.** Each candidate is a `kxm.candidate.v1` JSON file and a proposed diff under
+`.kxm/candidates/` (or `--out-dir`); the report is written as
+`kxm.improvement-report.v2` under `<workspace>/assets/improvements/`. `--dry-run` writes
+neither. The candidate kind comes from a Git-reviewed name rule and only picks the
+proposal template: a step or role that verifies, gates, tests, checks or lints proposes a
+`.kxm/gates.yaml` command entry; a planning, review or repro step proposes a governed
+skill, labelled consolidation because it is not a coded step; any other step proposes
+replacing the agent step with a `kind: gate` step plus a `gates.yaml` command entry that
+runs `scripts/<step>.mjs`, which the operator writes. Diffs are proposals with
+placeholder hunks.
+
+**Promotion readiness.** `promotion[]` reports, per candidate, `readyForReview` and a
+reason under `improvement.promotionPolicy`:
+
+- `manual_pr` (default): always ready; the operator reviews and applies the diff in a PR.
+- `critic_quorum`: ready once two distinct critic receipts are cited. `kxm improve`
+  cites none, so every candidate reports not ready under this policy.
+- `auto_threshold`: ready once the group's distinct runs reach
+  `improvement.autoThreshold.minRuns`, its accepted share reaches `minPassRate`, and its
+  mean recorded cost is at least `minCostSavings` over at least one cost sample. A group
+  with no recorded cost is never ready.
+
+No policy authorizes anything. Every policy ends at an operator PR, activation is a
+reviewed Git change for a future run, and telemetry cannot grant tools or skip a gate.
+
 ## Governance safeguards
 
 - Journal content is evidence, not executable policy.
+- Improvement candidates are proposals. Promotion readiness never authorizes, and no `improvement.*` value activates a candidate.
 - An agent may propose a gate change but cannot silently weaken a required gate.
 - A peer-quorum reduction must be declared by policy and explicitly approved by an administrator for the current attempt; record it as a degraded outcome rather than normal success.
 - Contradictions stay open until evidence resolves them; synthesis must not erase minority risks.

package/docs/contracts/routing.md

@@ -7,16 +7,20 @@
 > (`kxm.prices.v1`) is implemented, dated, and hashed. `kxm routing report`
 > is implemented (`plugins/kxm/src/routing.ts`) and ranks routes quality-first,
 > then cost per accepted attempt, never ranking unknown cost cheapest and
-> reporting metered, unmetered, and unknown populations separately. Dev-helper
-> telemetry (`scripts/harness-run.mjs`) and the issue 127 assignment runner
+> reporting metered, unmetered, and unknown populations separately. By default
+> `kxm routing report` and `kxm improve` read two sources: the current project's
+> Runtime event store (read-only) and then `.kxm/logs/telemetry.jsonl`; `--file`
+> reads only the named file (see [Readers](#readers-kxm-routing-report-and-kxm-improve)).
+> Dev-helper telemetry (`scripts/harness-run.mjs`) and the issue 127 assignment runner
 > (`scripts/assignment-run.mjs`, `just assign`) are implemented developer tools.
 
 This document describes what the tree does today versus what Tracking still
 plans. It does not invent prices or close product enums.
 
-## Implemented: v1 record
+## Implemented: v1 record (parse-only)
 
-Schema id: `kxm.routing-record.v1` (`plugins/kxm/src/routing.ts`).
+Schema id: `kxm.routing-record.v1` (`plugins/kxm/src/routing.ts`). v1 is parsed, never
+written by the product: the Runtime writes v2.
 
 Always present or defaulted by `parseRoutingRecord`: `schema`,
 `behavioralHashVersion`, `behavioralSha256`, `skills` (default `[]`),
@@ -36,17 +40,23 @@ retries, outcomes) is outside the hash.
 
 **No built-in product producer.** The worker envelope validates a `routing`
 field when present. Nothing in `plugins/kxm/src` or `scripts/kxm-worker.mjs`
-writes a record. Repo records are test-built. External JSONL can be ingested.
+writes a v1 record. The developer assignment runner (`scripts/assignment-run.mjs`)
+writes v1 records with `finalOutcome: "pending"` and a per-assignment
+`rolePromptSha256`, so the improvement report counts them as undecided and never
+groups two assignments as one ask. Other repo records are test-built. External
+JSONL can be ingested.
 
 v1 has **no dedicated fields** for harness, provider, latency, cost basis,
 cache-write tokens, or context occupancy. Bounded `providerMetadata` may
 carry extra keys (at most 32; values are strings, numbers, or booleans;
-`prompt`/`body`/`content`/`message` keys are rejected), but those keys are
-**not standardized** and `kxm routing report` does not read them.
+a key containing `prompt`, `body`, `content` or `message`, in any case, is
+rejected), but those keys are **not standardized**. The ranked report reads only
+`providerMetadata.harness` from a v1 record, to label its harness column.
 
-`kxm routing report` reads `telemetry.jsonl`, groups by behavioral hash, sorts
-by run count (then hash), and sums missing `costUsd` as **zero**. That silent
-underquote is why the report is **not** a ranking source.
+The `configurations` block of `kxm routing report` groups v1 records by
+behavioral hash, sorts by run count (then hash), and sums missing `costUsd` as
+**zero**. That silent underquote is why the block is **not** a ranking source;
+the ranked table described under [report and price catalog](#implemented-report-and-price-catalog) is.
 
 ## Implemented: dev helper telemetry
 
@@ -166,6 +176,51 @@ Fields carried on `RoutingRecordV2`:
 
 The KXM engine settle transaction appends a `routing.attempt.recorded` event carrying the v2 record and refuses to settle without a valid `costBasis`. Attempt dispatch enforces `limits.maxModelCost` against metered cost before invocation (`budget_model_cost`).
 
+What the engine writes on every settled attempt (`producerRoutingRecord` and the
+failure path in `settleMember`, `plugins/kxm/src/engine.ts`):
+
+- **Engine-reserved `providerMetadata` keys.** Four keys are written after the
+  producer's keys, so a producer key with the same name is dropped and cannot spoof
+  them. A producer keeps at most 28 keys of its own, so the record stays within the
+  32-field limit.
+
+  | Key | Value |
+  |---|---|
+  | `workflowId` | The compiled workflow's id |
+  | `askSha256` | `kxmStepAskSha256`: a digest of the workflow id, step id, step kind, agent id, instructions, declared outcomes and required evidence keys. It is equal across runs for one step and agent, and excludes the run, assignment and attempt ids, the run objective, repositories, model and context packet |
+  | `objectiveSha256` | The run's accepted prompt digest (`sha256:<hex>`); the prompt text is never read here |
+  | `stepWrites` | `true` when the step has any repository with `write` access |
+
+  The key names avoid the parser's refusal (`/prompt|body|content|message/i`), which
+  is why the ask digest is not called a prompt hash.
+- **`agentRole`** is the producer's value when it supplies one, otherwise the
+  dispatched agent id.
+- **Record-time `finalOutcome`** is only ever `blocked` (the declared outcome takes a
+  back edge) or `failed` (a producer error, an outcome the step does not declare, or a
+  terminal that is not `completed`). A forward edge or a completed terminal leaves it
+  unset: acceptance is not known when the attempt settles. The engine never writes
+  `accepted` or `pending`.
+- `retries` is the step attempt minus one. Every record from one step attempt shares
+  it, including panel members and any assignment retried inside that step attempt, so
+  the improvement report's rule that a later retry supersedes an earlier attempt never
+  separates them.
+
+**Read-time resolution.** Readers of the event store resolve each Runtime attempt's
+outcome in memory and never write it back (`readEngineRoutingRecords`,
+`plugins/kxm/src/improve-sources.ts`). The first rule that applies wins:
+
+1. a record-time `blocked` or `failed` stands;
+2. a later `step.entered` for the same step makes it `reworked`;
+3. a `completed` run makes it `accepted`;
+4. a `failed` run makes it `failed`;
+5. anything else (a cancelled or still-running run) is undecided and has no
+   `finalOutcome`.
+
+`reworked` is a read-time value only; it is outside the stored v2 vocabulary.
+Attempts whose `harness` is `driver-simulated` are dropped and counted as
+`excludedSimulated`. Records written before the engine carried these keys are not
+backfilled: they still resolve an outcome, but they group per run.
+
 ## Implemented: report and price catalog
 
 - **Price catalog:** `.kxm/prices.yaml` (`kxm.prices.v1`, dated and hashed) defines input, output, cache-read, cache-write rates, and context tiers for active models. Missing rows or uncataloged models evaluate to `costBasis: "unknown"`.
@@ -174,7 +229,36 @@ The KXM engine settle transaction appends a `routing.attempt.recorded` event car
 - **Underquote prevention:** Routes with unknown cost are flagged (`*`) and **never ranked cheapest**, eliminating silent underquoting.
 - **Population separation:** Reports metered cost, unmetered attempt counts, unknown-cost attempt counts, and quota-exhausted attempt counts as separate metrics rather than a single misleading total.
 - **List prices flag:** Supports `--equivalent-list-cost` / `--list-prices` to display estimated list rates for comparison alongside actual recorded spend.
-- **Post-MVP:** Dynamic catalog price feeds (`kxm update --models`), budget roll-over, and automated promotion of repeat successes into workflow gates.
+- **Rework column:** reads `transitions`, which Runtime records never set, so Runtime rework shows up only as a resolved `reworked` outcome, which the report does not count as a pass.
+- **Post-MVP:** Dynamic catalog price feeds (`kxm update --models`) and budget roll-over. Coded-repeat candidates from `kxm improve` only propose; activation is a reviewed Git change.
+
+## Readers: `kxm routing report` and `kxm improve`
+
+Both commands load routing records the same way (`loadRoutingSources`,
+`plugins/kxm/src/improve-sources.ts`):
+
+1. With `--file <path>`, only that JSONL file is read. It may hold bare v1 or v2
+   records, records nested under `routing` or `envelope.routing`, or
+   `routing.attempt.recorded` events.
+2. Otherwise, when the current directory is inside a KXM project, the project's
+   Runtime event store is read first:
+   `<state root>/runtime/projects/<key>/run-events.db`, where the key is derived from
+   the checkout's real path exactly as the Runtime derives it. It is opened read-only
+   for one `SELECT` over the `events` table (routing, `step.entered` and
+   `run.status_changed` events only); the runs table, run plans and the prompt sidecar
+   are never read, and nothing is created, written or migrated. Outcomes are resolved
+   as described above.
+3. Then `telemetry.jsonl` in the workspace logs directory.
+
+A v2 record whose `attemptId` an earlier source already supplied is dropped and
+counted as `duplicatesDropped` on the later source. Every source is reported in a
+`sources` array with `kind` (`engine`, `telemetry` or `file`), `path`, `exists`,
+`records` and, for the store, `skippedInvalid`, `excludedSimulated` and `undecided`.
+`kxm improve` prints the sources in text and JSON and adds `projectRoot`;
+`kxm routing report` adds `sources` to its JSON only, and keeps `file` set to the
+telemetry path. A store that exists but cannot be read stops either command with exit
+1 and `improve_source_unreadable`, naming the path. Each checkout reads only its own
+store: there is no cross-worktree aggregation.
 
 ## Precedence