@kontextmind/kxm 0.7.94 → 0.7.96

package/docs/provenance-gates.md

@@ -1,295 +0,0 @@
-# Peer provenance and quorum gates
-
-Peer provenance gates let a workflow require replies from a named, snapshotted
-set of agents before a stage can pass. The hub—not the coordinator—derives the
-producer identity, reply status, workflow scope, and content hashes from the
-durable message record.
-
-Use this feature when a gate means “two eligible reviewers replied for this
-exact review attempt.” Do not describe it as proof that the reviews are true,
-independent, high quality, or free from collusion.
-
-## What is bound and verified
-
-At workflow start, every `eligibleAgents` selector is resolved to a durable
-agent ID and name. The resolved set is copied into the run. The start fails
-closed if an agent is unknown, the coordinator is selected, or fewer unique
-agents resolve than `minProducers` requires.
-
-For a peer request to count, the assigned coordinator must send it to an
-eligible producer with an exact `workflowContext`:
-
-```json
-{
-  "runId": "run_123",
-  "stageId": "review",
-  "requirementKey": "independent peer reviews",
-  "attempt": 1
-}
-```
-
-The hub authorizes the context against the current run, active stage, canonical
-requirement key, 1-based attempt, coordinator identity, project, and target.
-It stores the canonical `pi-mesh.workflow-message-context.v1` context and binds
-the message correlation ID to the run. A caller cannot turn an ordinary or old
-message into workflow evidence by choosing an idempotency prefix or correlation
-ID.
-
-At checkpoint or wait, the coordinator cites message IDs rather than describing
-the replies itself:
-
-```json
-{
-  "evidenceRefs": {
-    "independent peer reviews": {
-      "messageIds": ["msg_reviewer_a", "msg_reviewer_b"]
-    }
-  }
-}
-```
-
-The hub accepts only durable `replied` messages with non-empty replies, coherent
-timestamps, the exact immutable context, the same project and coordinator, an
-eligible producer, and the run correlation ID. Quorum counts unique stable
-producer IDs, not messages. Duplicate replies from one producer still count as
-one producer. Missing, pending, cancelled, expired, wrong-attempt, cross-run,
-cross-stage, cross-project, coordinator-authored, and ineligible messages fail
-closed.
-
-After verification, the run stores a metadata-only snapshot containing:
-
-- message ID and stable producer ID/name;
-- exact run, stage, requirement, and attempt context;
-- `replied` status and lifecycle timestamps;
-- SHA-256 hashes of the request and reply;
-- the verification timestamp.
-
-The snapshot contains no request or reply body. It remains with the workflow
-run after the source message reaches the terminal-message retention limit and
-is purged. The hashes show which content the hub observed during verification;
-they do not reveal the content or prove its correctness.
-
-Retrospective quorum summaries are attempt-specific. For a passed or failed
-stage they report the terminal attempt; for an active stage they report the
-current attempt. Stored references from an earlier retry never inflate the
-applied producer count.
-
-## Configure a policy
-
-`evidencePolicies` keys must match canonical entries in `requiredEvidence`.
-Only the `peer-reply` policy and `replied` status are currently supported.
-
-| Field | Constraint |
-|---|---|
-| `kind` | Exact value `peer-reply` |
-| `minProducers` | Integer from 1 through 8 and no greater than the selector count |
-| `eligibleAgents` | 1–16 non-empty, case-insensitively unique names or IDs |
-| `acceptedStatuses` | Exact array `["replied"]`; omission uses the same value |
-| `degradation.minProducers` | Optional integer at least 1 and lower than `minProducers` |
-
-```json
-{
-  "id": "review",
-  "label": "Independent review",
-  "instructions": "Collect independent reviews, resolve contradictions, and record the decision.",
-  "requiredEvidence": [
-    "independent peer reviews",
-    "coordinator decision"
-  ],
-  "evidencePolicies": {
-    "independent peer reviews": {
-      "kind": "peer-reply",
-      "minProducers": 2,
-      "eligibleAgents": ["reviewer-claude", "reviewer-grok"],
-      "acceptedStatuses": ["replied"],
-      "degradation": {
-        "minProducers": 1
-      }
-    }
-  },
-  "maxAttempts": 3,
-  "area": "gates"
-}
-```
-
-Register the coordinator and every eligible peer at least once before starting
-the workflow. Names are resolved once at run creation; later configuration edits
-do not rewrite an active run's eligible-producer snapshot.
-
-The complete command-first example is
-[`examples/provenance-workflow.json`](../examples/provenance-workflow.json).
-It uses project `provenance-demo`, coordinator `coordinator`, and the two
-eligible reviewers `reviewer-claude` and `reviewer-grok`.
-
-## Execute a strict quorum
-
-Start with separate project and administrative credentials:
-
-```powershell
-$env:KXM_AUTH_TOKEN = "replace-with-the-admin-token"
-$env:KXM_PROJECT_TOKENS = '{"provenance-demo":"replace-with-the-project-token"}'
-$env:KXM_WEBHOOK_WORKFLOWS_FILE = "examples/provenance-workflow.json"
-kxm hub start
-```
-
-Give the coordinator and peer workers only the project token. Start all three
-before starting the workflow:
-
-```powershell
-$env:KXM_AUTH_TOKEN = "replace-with-the-project-token"
-kxm agent worker --name coordinator --project provenance-demo --session-isolation workflow
-kxm agent worker --name reviewer-claude --project provenance-demo --model openrouter/qwen/qwen3-coder-plus --session-isolation workflow
-kxm agent worker --name reviewer-grok --project provenance-demo --model openrouter/z-ai/glm-5.3-flash --session-isolation workflow
-```
-
-The reviewer ids are names, not routes. Workers are Pi, and Pi may not run a model whose
-vendor has its own harness, so these two independent reviewers use admitted Pi routes from
-different vendors rather than Claude and Grok.
-
-In an operator terminal, supply the workflow-start secret and create a run:
-
-```powershell
-$env:KXM_WORKFLOW_SECRET = "replace-with-the-workflow-start-secret"
-kxm gate validate --file examples/provenance-workflow.json
-kxm workflow start provenance-review --payload '{"task":{"id":"DEMO-1","summary":"Review the proposed change"}}'
-kxm workflow list
-```
-
-The coordinator gets the run ID in its durable prompt. It should read the run,
-calculate the current attempt as `stage.attempts + 1`, and fan out with one
-shared context:
-
-```json
-{
-  "targets": ["reviewer-claude", "reviewer-grok"],
-  "content": "Review this change independently. Return findings with evidence.",
-  "idempotencyKeyPrefix": "review-attempt-1",
-  "workflowContext": {
-    "runId": "run_123",
-    "stageId": "review",
-    "requirementKey": "independent peer reviews",
-    "attempt": 1
-  }
-}
-```
-
-`idempotencyKeyPrefix` makes an exact transport retry safe; it does not create
-provenance. After both results are `replied`, checkpoint with their returned
-message IDs and ordinary evidence for the non-peer requirement:
-
-```json
-{
-  "runId": "run_123",
-  "stageId": "review",
-  "status": "passed",
-  "summary": "Compared both reviews and resolved the material contradiction.",
-  "evidence": {
-    "coordinator decision": "decision:docs/review-decision.md"
-  },
-  "evidenceRefs": {
-    "independent peer reviews": {
-      "messageIds": ["msg_reviewer_a", "msg_reviewer_b"]
-    }
-  }
-}
-```
-
-Caller-authored `evidence` strings never satisfy a requirement that declares a
-peer policy. `warning` and `failed` checkpoints cannot submit `evidenceRefs`.
-After either result consumes an attempt, send fresh peer requests with the new
-attempt number; old references cannot satisfy the retry.
-
-## Degrade only through an explicit admin decision
-
-Degradation is optional and must be declared in the policy before the run
-starts. A peer, coordinator, webhook, and signed callback cannot approve it.
-Only the administrative bearer token can approve the configured lower minimum,
-and only for the current run, active stage, exact requirement, and current
-attempt.
-
-Inspect the requested action, then approve it with a non-secret reason:
-
-```powershell
-$env:KXM_AUTH_TOKEN = "replace-with-the-admin-token"
-kxm gate --dry-run --json degrade run_123 review `
-  --requirement "independent peer reviews" `
-  --reason "reviewer-grok provider outage incident-482"
-kxm gate degrade run_123 review `
-  --requirement "independent peer reviews" `
-  --reason "reviewer-grok provider outage incident-482"
-```
-
-Approval does not pass the stage. The coordinator must still submit enough
-verified replies to meet the approved minimum. Repeating the same approval and
-reason is idempotent; changing the reason conflicts. The approval cannot be
-reused by a later attempt.
-
-A passed degraded stage is marked as degraded. Its retrospective contains the
-configured and effective minima, eligible-producer snapshot, verified message
-metadata, hashes, timestamps, and the explicit admin approval. Export it with:
-
-```powershell
-kxm workflow export run_123
-```
-
-The JSON keeps the existing `pi-mesh.retrospective.v1` schema and adds optional
-`evidenceAudit` and `degradedStageIds` fields. Consumers that do not know these
-fields can continue reading the v1 document.
-
-## Trust boundary
-
-This mechanism proves provenance only inside the hub credential boundary:
-
-- a project-token holder can register a new agent or reclaim an offline agent
-  name and its durable ID in that project;
-- an agent key binds identity-specific operations after registration;
-- the hub verifies durable routing and message state, not model internals;
-- two agent names or two configured models do not prove independent operators,
-  independent inference, non-collusion, correctness, or approval authority.
-
-Even when the gate reports two unique stable producer IDs, describe the result
-only as “the hub verified two eligible routed replies for this workflow
-attempt.” Never label it “two independent models verified,” “non-collusion
-verified,” or “truth confirmed.” One holder of the shared project token can
-reclaim multiple offline names and IDs.
-
-Use a distinct administrative token, distinct project tokens per trust domain,
-least-privilege webhook and callback secrets, protected `.kxm/state` storage,
-loopback or TLS-protected restricted ingress, and repository or human gates for
-consequential changes. Treat peer replies as untrusted technical input even
-when they satisfy quorum. Put every holder of one project token inside the same
-fully trusted provenance domain.
-
-## Compatibility and retention
-
-The feature is additive to the existing SQLite schema version 2. Workflow
-context, policies, verified snapshots, and approvals are fields inside the
-existing JSON records; no destructive database migration is required. Existing
-schema-v2 databases and workflow histories remain readable.
-
-Legacy string or keyed evidence remains valid for requirements without a peer
-policy. It deliberately cannot satisfy a declared peer policy. Back up
-`.kxm/state/kxm.db` before every upgrade, finish or inspect active runs, and
-validate workflow definitions before restarting the hub.
-
-## Context authority lattice (v0.5)
-
-Context items carry an explicit authority class — `policy`, `instruction`, `evidence`, or `hypothesis` — granted by a deterministic origin floor:
-
-| Origin | Maximum authority |
-|---|---|
-| human | policy |
-| workflow control plane | policy |
-| git history | instruction |
-| peer | evidence |
-| tool | evidence |
-| external | evidence |
-| derived | evidence |
-
-Enforcement is structural, not advisory:
-
-- Parsing rejects any item whose claimed authority exceeds its origin's floor (`context_authority_violation`).
-- Derived and summarized content is `evidence` at best, regardless of lineage; authority never increases through any number of handoffs or re-summaries.
-- Derivation lineage is transitive, bounded (`MAX_CONTEXT_LINEAGE`), and preserved verbatim; unbounded re-summaries fail closed instead of laundering provenance.
-- Context items may never carry control-plane fields (`permissions`, `tools`, `approval`, credentials, …); memory, wiki, and skill content can inform behavior but never expand tool permissions or approval scope.
-- Superseded and rejected records are excluded from summarization lineage: dead records are not evidence of current truth.

package/docs/skills.md

@@ -1,47 +0,0 @@
-# Skill candidate lifecycle
-
-KXM turns verified episodes and lessons into reusable Agent Skills through a governed lifecycle. Runtime experience never becomes promoted skill content automatically, and promoted skills never grant tool or permission authority.
-
-This page is the governed `kxm skills` lifecycle. For the bundled command-suite skills, see [Agent Skills](agent-skills.md). For converting a repository request into a delivery prompt, see [Repository work delivery](skills/repo-work-delivery.md).
-
-## Lifecycle
-
-```text
-verified episode(s)  →  skill candidate  →  static/provenance review
-  →  sandbox execution  →  protected functional + safety eval
-  →  promote / quarantine / reject
-```
-
-## Storage
-
-```text
-.kxm/skills/
-├── candidates/<id>/SKILL.md + metadata.json
-├── promoted/<id>/SKILL.md + metadata.json
-├── quarantined/<id>/SKILL.md + metadata.json
-└── history/<id>.jsonl
-```
-
-Skill IDs are content-addressed (`<slug>.<hash-prefix>`): changed behavior means changed content means a new candidate. Identical resubmissions are rejected as duplicates.
-
-## Rules
-
-- A candidate must cite at least one source run, journal entry, or evidence receipt.
-- Candidate metadata records explicit cross-model/cross-harness compatibility (`harness`, `models`).
-- Promotion requires passing `static-review`, `sandbox`, `functional`, and `safety` evaluations, durable evidence references, and a decision by someone other than the author.
-- A failed functional or safety evaluation quarantines the candidate automatically; the evaluator records the decision and a human may later reject fully.
-- Rejected and quarantined candidates remain queryable in `history/` for future learning.
-- Promoted skills are hash-pinned and immutable: `kxm skills verify` detects out-of-band edits (`skill_integrity_violation`), and behavior changes require a new candidate/eval cycle (optionally `supersedes`-linked).
-- Skill content is redacted of secret material at creation; evaluation details are redacted and bounded.
-- Optimization evaluations (skillopt/WikiSkill-style) are a gated hook, disabled unless explicitly enabled.
-
-## CLI
-
-```text
-kxm skills create --file SKILL.md --name <name> --created-by <id> --harness pi --models <models> --run <ids> --journal <ids>
-kxm skills evaluate <id> --kind static-review|sandbox|functional|safety --evaluator <version> [--fail]
-kxm skills promote <id> --decided-by <id> --evidence <refs>
-kxm skills reject <id> --decided-by <id>
-kxm skills list --state candidate|promoted|quarantined|rejected
-kxm skills verify <id> --state promoted
-```

package/docs/test-matrix.md

@@ -1,132 +0,0 @@
-# Test matrix
-
-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:pr` plus
-`check:generated`; pushes to main run `validate:ci`. Plugin validation is a hosted CI
-job.
-
-```powershell
-npm run verify
-```
-
-## Product features
-
-| Feature | Automated evidence |
-|---|---|
-| Portal tenant read composes two labelled authorities: hub runs carry `hub-projection`, Runtime runs carry `runtime-authoritative`; a down hub leaves runtime state readable and vice versa with stable reasons; projection/authoritative disagreements surface as `discrepancies`; binding scope is labelled loopback/remote | `test/core/studio-layout.test.ts` |
-| Structured-result settlement only: outcome words in prose, empty replies, and outcomes outside the step's declared set all fail closed; a declared JSON object and a JSON result block inside prose both settle, and the engine records `outcome_unknown` and terminates `failed` | `test/core/pi-producer.test.ts`, `test/core/engine.test.ts` |
-| Health, readiness, metrics, request IDs, security headers | `test/core/hub-api.test.ts` |
-| Shared and per-project authentication, project isolation | `test/core/hub-api.test.ts` |
-| Registration, discovery, presence, stale detection, identity resumption | `test/core/hub-api.test.ts`, `test/core/hub.test.ts` |
-| SQLite persistence, restart recovery, schema compatibility | `test/core/hub-api.test.ts`, `test/core/store.test.ts` |
-| All delivery modes, message fields, hop limits, and validation | `test/core/hub-api.test.ts`, `test/core/protocol.test.ts` |
-| Queue, acknowledgement, visibility, reply, and authorization | `test/core/hub-api.test.ts`, `test/core/hub.test.ts` |
-| Queued/delivered replay after recipient restart reuses one message record | `test/core/hub.test.ts`, `test/core/extension.test.ts`, `test/core/mcp.test.ts` |
-| Known-offline peer send with `allowOffline` queues, delivers once on resumption, and expires unread by TTL | `test/core/hub-api.test.ts` |
-| Fenced hub leases: CAS acquire/renew/release, monotonic token on takeover only, hub-clocked expiry, and a shared external effect refused at commit under a superseded token | `test/core/hub-api.test.ts`, `test/core/store.test.ts`, `test/core/external-effects.test.ts` |
-| One-to-three-peer fanout, recoverable local timeouts/aborts, exact retries, and partial-error collection | `test/core/client.test.ts`, `test/core/hub-api.test.ts`, `test/core/extension.test.ts`, `test/core/mcp.test.ts` |
-| TTL expiry, sender cancellation, and terminal retention | `test/core/hub-api.test.ts` |
-| Terminal inbound cleanup and next-request activation | `test/core/extension.test.ts`, `test/core/mcp.test.ts` |
-| Exact-retry idempotency and conflicting-key rejection | `test/core/hub-api.test.ts` |
-| Rate limiting and retry guidance | `test/core/hub-api.test.ts` |
-| Redacted structured logs | `test/core/hub-api.test.ts` |
-| Client lifecycle, aborts, timeouts, invalid responses, reconnection | `test/core/client.test.ts` |
-| Pi tools, inbound turns, automatic replies, status command | `test/core/extension.test.ts` |
-| 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`, `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` |
-| Required generated runtimes are present, tracked, and match the staged copy after build | `scripts/check-generated.mjs`, `test/core/generated-artifacts.test.ts` |
-| Tag release packs `kxm-<v>.tgz`, fail-closed draft GitHub upload, 404-then-list draft discovery, digest proof, no clobber | `scripts/kxm-release-github.mjs`, `test/core/kxm-release-github.test.ts`, `test/core/ci-contract.test.ts` |
-| Retrospective export snapshots, metadata-only provenance audit, body allowlisting, degradation records, and v1 compatibility | `test/core/retrospective.test.ts` |
-| Interrupted-worker continue fallback, exact run-bound recovery, unbound telemetry isolation, and one-turn durable replay | `test/core/worker.test.ts`, `test/core/recovery.test.ts`, `test/core/extension.test.ts` |
-| Hub-owned workflow affinity; integrated hub→extension→supervisor→replacement replay; pre-ack default/run/cross-run routing; one-child session-dir swapping; stable ordinary context; LRU retention; and corrupt-state/link containment | `test/core/hub-api.test.ts`, `test/core/extension.test.ts`, `test/core/worker.test.ts`, `test/core/cli.test.ts` |
-| Final provider-error retention, built-in retry ordering, metadata-only journaling, bounded fallback exhaustion, oversized-frame classification, and session-preserving restart | `test/core/extension.test.ts`, `test/core/worker.test.ts`, `test/core/diagnostics.test.ts`, `test/core/cli.test.ts` |
-| Tool capability allowlist, watchdog grace, bounded hung-tool recovery, oversized completed-tool cancellation, and race-safe hub/worker ownership claims | `test/core/worker.test.ts`, `test/core/cli.test.ts`, `test/core/server.test.ts` |
-| Exact worker extension/skill sets, discovery isolation, path preflight, multi-path ordering, and Windows argument safety | `test/core/worker.test.ts` |
-| Opt-in real-Pi smoke contract and safe skip paths | `test/core/smoke-real-pi.test.ts`, `test/core/smoke.test.ts` |
-| Durable workflow and journal recovery | `test/core/store.test.ts` |
-| Atomic workflow transition commit and rollback | `test/core/store.test.ts` |
-| Pi and Claude workflow/journal tools, workflow-context sends, and peer-reference checkpoints/waits | `test/core/extension.test.ts`, `test/core/mcp.test.ts` |
-| Package and marketplace version consistency | `scripts/check-versions.mjs` |
-| Planned KXM schemas, restricted YAML fixtures, cross-resource semantics, and sync-safe rejection | `test/core/contracts.test.ts` |
-| Production KXM restricted loader, deterministic bundle hashing, Git discovery, fail-closed semantics, init classification, provenance-tracked atomic creation, exact three-way repair, authority-change blocking, pinned crash resumption, shadow validation, explicit join, Runtime-local bindings, CLI isolation, and idempotence | `test/core/project-config.test.ts`, `test/core/cli.test.ts`, `test/core/package-install.test.ts` |
-| Legacy state is refused, never converted: a tree with `.kxm/config` JSON fails project load with `legacy_state_unsupported`, `kxm init` classifies it `mode: "legacy"` without writing, `kxm migrate` is an unknown command, and an older stamped store is refused without advancing `user_version` | `test/core/project-config.test.ts`, `test/core/cli.test.ts`, `test/core/e6-backup-restore-migrations.test.ts` |
-| Permission-diff trust workflow: structured authority projections, conservative lattice classification (access, network, budgets, quorums, snapshots, secrets, transitions, shapes), prose neutrality, Git base shadowing, CLI diff/check gating, and packed-consumer round trips | `test/core/permission.test.ts`, `test/core/cli.test.ts`, `test/core/contracts.test.ts`, `test/core/package-install.test.ts` |
-| Event-sourced local Runtime: supervisor singleton with stable logical identity, immutable home bindings, append-only per-project event stores, idempotent acceptance/cancel, projection rebuild equivalence, token-authenticated local API, auto-start, SIGKILL crash recovery, offline CLI, packed consumer | `test/core/runtime.test.ts`, `test/core/cli.test.ts`, `test/core/package-install.test.ts` |
-
-The CI minimums are 93% lines, 80% branches, and 93% functions across
-`plugins/kxm/src/**/*.ts` (excludes `server.ts` and `mcp-server.ts`). Those
-floors may only ratchet up. The generated MCP runtime is exercised as a child
-process, while the packed CLI and hub are installed in a clean consumer and
-exercised from `node_modules`.
-
-## Executable examples and use cases
-
-| Scenario | Location | Verification |
-|---|---|---|
-| Self-contained planner/reviewer round trip | `examples/roundtrip.ts` | Executed by `test/core/examples.test.ts` |
-| Long-running deterministic reviewer | `examples/reviewer-agent.ts` | Type-checked and documented |
-| Command-line requester | `examples/requester.ts` | Type-checked and documented |
-| Plan then review | `examples/README.md` | Uses discovery, send, and wait |
-| Separate file ownership | `examples/README.md` | Documents non-overlapping writers |
-| Non-blocking delegation | `examples/README.md` | Uses send, independent work, and get |
-| Obsolete-work cancellation | `examples/README.md` | Uses cancel and states rollback boundary |
-| Safe network retry | `examples/README.md` | Uses stable idempotency keys |
-| Jira issue-to-merge workflow | `.kxm/workflows/default.yaml` | Parsed, type-checked through workflow tests, and exercised end to end with representative configuration |
-| `.kxm` workspace defaults and persisted hub/worker logs | `.kxm/`, `test/core/server.test.ts`, `test/core/worker.test.ts` | Executed with isolated temporary workspaces |
-| Signed external result callback | `examples/workflow-signal.ts` | Type-checked; equivalent signed callback path is exercised end to end in `test/core/hub-api.test.ts` |
-| Peer provenance and optional explicit degradation | `examples/provenance-workflow.json`, `.kxm/workflows/default.yaml`, `docs/provenance-gates.md` | Both definitions are parser-checked in `test/core/examples.test.ts`; adversarial evidence and degradation behavior is automated in `test/core/workflow-provenance.test.ts` |
-| Quorum parser boundaries and definition identity | `plugins/kxm/src/workflow.ts`, `test/core/workflow-quorum.test.ts`, `test/core/workflow-definition-hash.test.ts` | Rejects impossible peer pools, verifies degradation bounds, and proves secret-free semantic hash stamping plus credential-rotation invariance |
-| Artifact existence and containment gate | `plugins/kxm/src/artifacts-exist.ts`, `test/core/artifacts-exist.test.ts` | Non-empty regular files pass; missing, empty, non-file, lexical escape, and real-path escape cases fail closed (host-permitted symlink coverage) |
-| Harness inventory probe | `plugins/kxm/src/harness.ts`, `test/core/harness.test.ts` | Detect/auth/dispatch for the builtin catalog; win32 `.exe` / inner npm-package `.exe` / `.cmd` candidate order for npm shims (issue #168); `windows_shim` issue only when the shim answered; allowlisted `name.cmd` shell spawn only; rejected metacharacter commands; Linux still `not_detected` when the bare command is missing. |
-| Headless harness helper | `scripts/harness-run.mjs`, `justfile`, `test/core/harness-run.test.ts` | Offline auth success/logout/garbage, role/mode/pair/provider refusals before spawn, missing brief/schema fail closed with zero spawn, invocation-cwd relative `prompt_file`/`output_schema` vs `request.cwd` (absolute argv tokens; Claude/Codex stdin matches the brief), Pi JSONL multi-`message_end` sums, Claude auxiliary usage, native error-on-exit-0, timeout/empty payload, sidecar-only stderr/answer/error, shell:false argv metacharacters, win32 `.cmd` rejection, and win32 npm inner `claude.exe` / Pi `node.exe`+`cli.js` unwrap. Result v2 transport vs closed model claims, dispatch-before-spawn, grok/codex isolation flags, `max_turns` validation, obsolete v1 diagnosis without rewrite or unknown-schema echo, partial usage on fail/interrupt, signaled null `exitCode` plus exact `signal`, exit-before-stdio-close drain vs bounded linger, type-closed usage/cost (no object leak or zero-coercion), malformed optional text as run-stage failure with retained spend, stdin/pid-record write failures not completed, bounded timeout settle without descendant-death claims, spawn/write-failure stage and spend, and capability-fixture parser evidence (Codex `--ignore-user-config` is not invented in top-level help; captured help bytes are not rescrubbed). Recipe quoting is covered from the justfile body without a just binary (POSIX `sh` + positional argv; Windows uses the recipe's `node -e` / argv shape). The developer entry points are gated three ways: docs-to-recipe parity (a documented `just` verb in command form, across inline code or a fenced line with an optional `#`, tolerant of stray whitespace, pipe-separated alternations, leading interpreter options and `~~~` fences, reading a shell pipe as one command rather than an alternation, skipping a glob family like `review-*` instead of demanding a recipe, and *not* parsing prose, headings or captured listing output); per-recipe boundaries (**the load-bearing gate parses nothing**: every line that mentions `assignment-run.mjs` must be one of the seven pinned proof bodies and there must be exactly seven, so a header form no parser recognises still cannot hide a call site; column-0 comments are documentation and excluded), plus a normalized-text pass (`\`-continuations folded, comments stripped) and a second pass over `just --dump`, the interpreter's own rendering, skipped with a visible reason without the binary; the recipe name set must equal a pinned list, duplicate headers and duplicate `run :=` bindings are refused, `set allow-duplicate*`, `import`/`mod` in any spelling and `alias` are refused, `run :=` and `dispatch` are asserted exactly, and non-proof bodies are token-checked against raw text because comment-stripping first hid an executable suffix that `--dump` reproduced verbatim. Stated limit: drift protection, not a sandbox — a body can assemble its command at runtime, and anyone who can edit the file can already do what it does. Auto-loading a working-directory dotenv file is refused by a brake on any `set dotenv*` spelling, plus a real-`just` probe whose preload module writes a marker file itself — so the assertion is that injected code executed — paired with controls on the same entry point: explicit `--dotenv-path`, a justfile with the setting re-added, and a real `witness` recipe run both ways. Real just integration is optional and skipped when the binary is absent. No live paid smoke. |
-| Long-lived headless coordinator | `scripts/kxm-worker.mjs` | Restart limits, spawn failure, collision-resistant ownership, exact resource and tool loading, raw-output isolation, bounded RPC framing, bounded drain, hung-tool recovery, provider/model fallback, and `--continue` fallback are automated; the opt-in real-Pi gate verifies two workers, discovery, request/reply, fanout, durable restart/resume, journal, and checkpoint |
-| GitHub check signal adapter | `plugins/kxm/src/github-watch.ts` | Deterministic pagination, conclusion, retry, and per-wait delivery-generation states in `test/core/github-watch.test.ts` |
-| Operator CLI | `scripts/kxm.mjs` | Isolated workspace commands in `test/core/cli.test.ts`; the packed artifact is installed locally and with the documented global `--omit=peer` path by `test/core/package-install.test.ts` |
-| Hub-local session brief | `plugins/kxm/src/session-work.ts`, `test/core/session-work.test.ts`, `test/core/cli.test.ts` | Status line and task/plan lists from hub SQLite without message bodies; `init --hub` is an unknown option; `hub bind` reports on/off/unknown |
-| Native-free package install and Windows `pi.cmd` worker launch | `package.json`, `test/core/store.test.ts`, `test/core/worker.test.ts` | CI runs on Linux at Node 22.19 and Node 24; the Windows `pi.cmd` fixture stays in `test/core/worker.test.ts` and runs locally on Windows or when the paused Windows legs resume. |
-
-## Manual release checks
-
-Automation cannot prove that a third-party harness UI renders perfectly. Before a release, connect two current Pi sessions, run `/kxm hub`, complete one inbound round trip, install the marketplace plugin in a clean Claude Code profile, and verify `kxm_list`. Exercise preview channel delivery only when the target Claude Code version supports community channels.
-
-Create the versioned tarball with `npm pack`, attach it to the matching GitHub
-release, and verify the authenticated `gh release download` plus
-`npm install --global --omit=peer <local-tarball>` path before publishing the
-operator installation instructions. For version `<release-version>`, the required asset is
-`kxm-<release-version>.tgz`.
-
-When adding a feature, add executable coverage and update this matrix in the same change. If a behavior can only be verified manually, state why and add it to the release checklist instead of implying automated coverage.
-
-## v0.5 context suites
-
-| Suite | Covers |
-|---|---|
-| `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, 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, 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/improve.test.ts` | Routing-record sources, event-log outcome resolution, same-ask candidacy, candidate files, promotion readiness |