@kontextmind/kxm 0.6.0

package/docs/operations.md

@@ -0,0 +1,205 @@
+# Operations guide
+
+This guide covers the production envelope for one KXM hub and one SQLite database.
+
+## Deployment classification
+
+Version `0.4.x` is designed for local workstations and controlled trusted-team hosts. It provides durable restart recovery, project authentication, signed webhook workflows, traffic limits, health signals, metrics, structured logs, and graceful shutdown.
+
+It is not a clustered or multi-tenant control plane. Run one writer for each database. Do not place a load balancer across independent hubs and expect shared presence or delivery.
+
+## Start and stop
+
+```powershell
+$env:KXM_HOST = "127.0.0.1"
+$env:KXM_AUTH_TOKEN = "replace-with-a-long-random-token"
+$env:KXM_WORKSPACE_DIR = "D:\work\product\.kxm"
+kxm hub start
+```
+
+These operator commands assume the packed release CLI installation from
+[Getting started](getting-started.md#install-the-operator-command). From a
+source clone, use `npm run hub` instead.
+
+Stop with `Ctrl+C` or `SIGTERM`. The hub stops accepting connections, closes SSE streams, waits for active HTTP connections, and closes SQLite.
+
+For unattended service, use a supervisor that sets a stable working directory, injects secrets, captures stdout, restarts after failure, and allows at least five seconds for graceful shutdown.
+
+Run each long-lived coordinator with `kxm agent worker --name <stable-name> --project <project> [--model <provider/model>] [--fallback-models <provider/model,...>] [--tools <name,...>]` under a separate service-manager unit. Use distinct worktrees for concurrent writers, explicit CPU and memory limits, and restart throttling outside the built-in bounded backoff. Enforce role ownership with the Pi tool allowlist: omit `bash`, `edit`, and `write` from read-only reviewers, even if their prompt also says not to edit. The worker launches Pi RPC mode and retains the most recent session unless configured otherwise. Use `--fresh-start` for a clean first session that may still resume after a later provider failure; reserve `--no-continue` for a worker that must never resume. For release verification, configure the [exact extension and skill sets](configuration.md#long-lived-worker-settings), including every required provider extension; configured categories disable discovery and fail closed on invalid paths. `kxm hub stop` writes a generation-matched control request; the worker asks Pi RPC to abort, waits for confirmation and state flush, and only force-stops the process tree after the bounded drain deadline. A final provider error leaves the inbound hub message delivered, gracefully restarts Pi, rotates to an unused fallback model, and preserves the session; Pi's own automatic retries always finish first. A tool that exceeds `KXM_WORKER_TOOL_TIMEOUT_MS` follows the same durable restart path without changing models. If `--continue` reports an invalid tool-result session, the worker retries once fresh, journals a redacted recovery envelope, and injects a bounded resume instruction for the durable run and stage. Do not copy `pi-agent-*.log` into journals or retrospectives.
+
+### Workflow-specific Pi sessions
+
+Workflow isolation is opt-in during the upgrade-compatible release because the new scoped default directory cannot safely infer which pre-upgrade shared Pi session belonged to a worker. Enable it explicitly for coordinators and peers that may receive durable workflow work:
+
+```powershell
+kxm agent worker --name coordinator --project product --session-isolation workflow
+```
+
+Ordinary peer and operator messages reuse the worker's stable `default` Pi history. Each canonical workflow run uses `.kxm/state/pi-sessions/<workerKey>/runs/<runId>/`; only one Pi RPC child exists at a time. A route-change lifecycle event (`worker_session_routed`) is expected and does not consume restart budget or apply crash backoff. `worker_session_evicted` records bounded LRU cleanup. `worker_session_state_recovered` means a malformed binding manifest was quarantined and routing restarted safely at `default`; inspect the protected `.corrupt-*` file and workflow journal before deleting it. `worker_session_request_rejected` indicates a stale, malformed, mismatched-generation, or mismatched-source request and should be investigated if it repeats.
+
+Back up workflow model histories only if local Pi context is part of your recovery policy; authoritative workflow stages, evidence, and decisions remain in `kxm.db`, assets, and Git. Never use a Pi JSONL as the sole system of record. The first isolated launch starts fresh scoped storage; the previous shared Pi history remains available only in `off` mode and is not copied because a shared directory may contain several agents' sessions. To disable isolation temporarily, stop the exact worker cleanly and restart it with `--session-isolation off`; do not run isolated and shared supervisors concurrently under the same agent identity. Returning to `workflow` resumes the binding recorded in the manifest, subject to the configured retention bound.
+
+For GitHub-backed waits, run `kxm gate github watch` as a separate command. The hub does not poll GitHub. Success, failure, cancellation, and timeout produce the exact signed signal for the waiting run/stage/key; timeout exits `4` after posting `failed`.
+
+## Live observer dashboard
+
+Run the read-only dashboard against the active workspace:
+
+```powershell
+kxm --workspace D:\work\product\.kxm dash
+```
+
+The dashboard uses Pi's `@earendil-works/pi-tui` renderer. With the administrative `KXM_AUTH_TOKEN`, it subscribes to `/v1/ops/events` and refreshes the project-scoped `/v1/ops/snapshot` on each SSE wakeup, keeping agent, open-message, and workflow metadata live without timer polling. Both endpoints omit request/reply bodies. Local process claims remain a local read-only snapshot. If the operations endpoints are unavailable or the supplied credential is project-scoped rather than administrative, the dashboard requests a hub-enforced presence-only agent SSE stream plus local SQLite metadata. It refuses an older/unmarked stream that cannot guarantee this metadata-only mode. Observer registrations are excluded from the dashboard's displayed agent table and counts; they remain ordinary authenticated hub identities while connected.
+
+| Key | Action |
+|---|---|
+| `1`–`6` | Agents, Tasks, Workflows, Plans, Inbox, or Procs |
+| `Tab` / `]` | Next tab |
+| `[` | Previous tab |
+| `←` / `→` | List pane / detail pane |
+| `↑` / `↓` | Select |
+| `PgUp` / `PgDn` | Scroll |
+| `h` | Toggle help |
+| `q` | Quit |
+
+In a non-interactive shell, `kxm dash` prints one ANSI-free snapshot and exits.
+Use `kxm hub view --json` instead when a machine-readable result is required.
+
+## Real multi-Pi release smoke
+
+The opt-in release smoke requires two distinct models that already pass `pi auth check`. It creates a temporary workspace, launches two real Pi RPC workers, and verifies discovery, request/reply, fanout, durable identity plus a post-restart exchange, journal persistence, checkpoint completion, and cleanup.
+
+PowerShell:
+
+```powershell
+$env:KXM_SMOKE = "1"
+$env:KXM_SMOKE_MODELS = "xai/grok-4.6,anthropic/claude-sonnet-4-5"
+node scripts/smoke-multi-pi.mjs
+```
+
+POSIX shell:
+
+```bash
+KXM_SMOKE=1 KXM_SMOKE_MODELS='xai/grok-4.6,anthropic/claude-sonnet-4-5' node scripts/smoke-multi-pi.mjs
+```
+
+For GitHub Actions, smoke runs on the ARC scale set `kontextmind-doks`. Set
+the GitHub repository variable `KXM_SMOKE_RUNNER` (a readiness latch, not a
+process environment variable) exactly to `kontextmind-doks` and
+`KXM_SMOKE_MODELS` to the two model IDs. Any other value skips the job. A
+manual dispatch can override the model variable with its `models` input.
+Readiness means Pi credentials are provisioned to ephemeral ARC pods and
+pass `pi auth check`, not general CI readiness. Credentials are never
+workflow inputs. The variable is currently unset, so the workflow is
+intentionally disabled.
+
+## Health, readiness, and metrics
+
+| Endpoint | Authentication | Meaning |
+|---|---|---|
+| `GET /health` | None | Process is accepting HTTP and reports online agents |
+| `GET /ready` | None | Storage responds and the hub is ready for traffic |
+| `GET /metrics` | Administrative token outside loopback | Prometheus text metrics |
+| `GET /v1/ops/snapshot?project=<name>` | Administrative token | Project-scoped agent, open-message, and workflow metadata; no bodies |
+| `GET /v1/ops/events?project=<name>` | Administrative token | Metadata-only SSE wakeups for live dashboard refresh |
+
+Use `/ready` for service traffic and `/health` for liveness. Metrics include online agents, retained messages, requests, errors, registrations, sends, replies, cancellations, expiries, purges, workflow waits, external signals, wait timeouts, and explicit workflow quorum degradations.
+
+Structured JSON logs are written to `.kxm/logs/kxm-hub.jsonl` and mirrored to stdout. They include request IDs and event metadata but omit prompt and reply bodies. Worker lifecycle events use `.kxm/logs/kxm-worker-<project>-<agent>-<identity>.jsonl`; raw headless Pi stdout and stderr use `.kxm/logs/pi-agent-<project>-<agent>-<identity>.log` and may contain sensitive model or tool output. The collision-resistant suffix separates exact project/agent owners even when display names sanitize identically. Useful hub events include `agent_registered`, `agent_resumed`, `agent_stale`, `message_sent`, `message_replied`, `message_cancelled`, `message_expired`, `message_purged`, `webhook_workflow_started`, `workflow_checkpoint`, `workflow_degradation_approved`, `workflow_wait_started`, `workflow_signal_received`, `workflow_wait_timed_out`, `workflow_journal_recorded`, and `request_error`.
+
+Runtime logs are ignored by Git. Ship them to an approved collector, restrict file access, and apply retention or rotation outside the process before unattended use. Never commit them as workflow evidence; reference a protected log location or sanitized asset instead.
+
+Recommended alerts:
+
+- readiness fails for more than one minute;
+- errors or rate-limit responses rise unexpectedly;
+- the process restarts repeatedly;
+- retained-message count grows despite the retention policy;
+- free disk space approaches the database's expected growth margin.
+- webhook signature rejections, repeated provider retries, premature workflow settlement, or attempt exhaustion increase.
+- waiting-run count or workflow wait timeouts rise beyond the expected external-system latency.
+- quorum degradation approvals occur outside a declared incident or change window.
+
+## Backup and restore
+
+SQLite runs in WAL mode. The safest simple backup is a coordinated copy while the hub is stopped:
+
+1. Stop the hub gracefully.
+2. Copy `.kxm/state/kxm.db` to protected backup storage.
+3. Keep the backup with the application version and configuration used to create it.
+4. Restart the hub and confirm `/ready` returns `ok: true`.
+
+For online backups, use a SQLite-aware backup tool or snapshot the database, `-wal`, and `-shm` files consistently. A plain copy of only `kxm.db` while the service is writing may omit committed WAL data.
+
+To restore, stop the hub, preserve the current files for rollback, place the restored database at `.kxm/state/kxm.db` or the configured `KXM_DATA_PATH`, and start the same or newer compatible release. The runtime refuses a database whose schema version is newer than it supports.
+
+Test restoration periodically. A backup that has never been restored is not a verified recovery path.
+
+## Upgrade and rollback
+
+1. Back up the database and record the current package version.
+2. Run `npm ci` for the target checkout.
+3. Stop the old hub gracefully.
+4. Start the new version against the database and verify `/ready`, `/metrics`, and a test round trip.
+5. Restart agents only if their clients do not reconnect automatically.
+
+For rollback, stop the new version and restore both the earlier application and its pre-upgrade database backup. Do not open a newer-schema database with an older runtime.
+
+Peer provenance fields do not bump the current SQLite schema version 2; they are
+additive fields in existing JSON records. That avoids a destructive migration,
+but it does not replace the backup and rollback steps above. Verified
+metadata-only snapshots remain in workflow runs after their source messages are
+purged by terminal retention, so include workflow data in retention and privacy
+reviews.
+
+## Network and secret security
+
+Loopback is the safest default. Before binding elsewhere, configure an administrative token, assign project tokens, terminate TLS at a trusted proxy, restrict inbound networks, disable proxy buffering for `/v1/events`, and protect the SQLite directory.
+
+The database is not encrypted by the application. Use encrypted storage when messages require encryption at rest. Rotate a disclosed token and reconnect affected agents. Never expose the hub directly to the public internet.
+
+## Capacity and failure behavior
+
+The service uses one Node.js process, long-lived SSE connections, and one SQLite writer. Measure concurrent agents, request rate, event-loop delay, database size, disk latency, and reconnect frequency for your workload. The in-memory rate-limit ledger resets after process restart.
+
+| Failure | Behavior | Recovery |
+|---|---|---|
+| Agent exits | Marked offline after the stale threshold | Restart with the same name to resume its ID |
+| SSE drops | Client reconnects while heartbeats continue | Check network and proxy buffering if repeated |
+| Hub or worker exits | SQLite keeps agents and messages; session binding manifests keep the active Pi scope | Restart; agents reconnect and queued or delivered work replays by the same message ID in the bound Pi session |
+| Token rotates | Requests fail authentication | Restart agents with the new project token |
+| Disk unavailable | Readiness or writes fail | Restore storage, then verify database integrity and readiness |
+| Duplicate live name | Registration returns HTTP 409 | Stop the old session or choose another name |
+| External callback is lost | Run stays `waiting` until its deadline | Retry with the same delivery ID or investigate the provider before timeout |
+| External wait expires | Run and active stage fail; journal records the timeout and the coordinator receives a terminal notification | Fix delivery/routing, review side effects, then start a new safe workflow delivery |
+| Pi executable cannot spawn | Worker records the process error and applies its normal restart/backoff limit | Repair `PATH` or `KXM_PI_COMMAND`; confirm the worker exits nonzero when retries are exhausted |
+| Session binding manifest is corrupt | Worker quarantines it and starts the stable default binding without trusting a guessed run | Inspect `worker_session_state_recovered`, the `.corrupt-*` manifest, `kxm.db`, and workflow journal; re-drive unfinished work from durable message IDs |
+| Session route request is rejected | Candidate remains queued; wrong-scope acknowledgement never occurs | Check worker generation, active scope, canonical run ID, state-directory permissions, and repeated `worker_session_request_rejected` logs |
+
+Durable transport does not make peer execution exactly once. Use idempotent tasks and stable message idempotency keys, and store important artifacts in Git or another system of record.
+
+## Remaining scale boundaries
+
+Broader deployments need shared state and coordination, external identity and fine-grained authorization, distributed traffic controls, defined service-level objectives, load and chaos testing, and a formal long-term schema migration strategy.
+
+## v0.5 context/state storage
+
+The hub database (schema version 3) carries `context_items` alongside
+agents, messages, workflow runs, and the journal. Temporal state, knowledge
+records, and their audit trails live in the same SQLite file and upgrade in
+place from v0.4 databases.
+
+- **Backup and restore**: include the hub database file and, if used, the
+  `.kxm/skills/` and `.kxm/knowledge/` trees. The wiki is a compiled view and
+  can be regenerated (`kxm context wiki-compile`); skills history and state
+  records are authoritative and must be backed up.
+- **Recovery after restart**: runs, journal entries, transitions, captured
+  oracles, and plan hashes reload from SQLite; temporal `asOf` queries are
+  deterministic against the restored validity windows.
+- **Project isolation**: context/state/skill operations are project-scoped.
+  Agents authenticate to their own project; administrative operations require
+  the hub token. Cross-project context requests fail closed
+  (`context_isolation_violation`).
+- **Rollback**: schema downgrades are not supported (a newer database refuses
+  to open on an older runtime). Restore a database backup taken before the
+  upgrade instead.

package/docs/provenance-gates.md

@@ -0,0 +1,291 @@
+# 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 anthropic/claude-opus-4-6 --session-isolation workflow
+kxm agent worker --name reviewer-grok --project provenance-demo --model xai/grok-4.6 --session-isolation workflow
+```
+
+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

@@ -0,0 +1,45 @@
+# 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.
+
+## 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/templates/README.md

@@ -0,0 +1,95 @@
+# KXM Documentation Templates & Workflow Integration Guide
+
+This directory contains standardized Markdown documentation templates adapted for KXM multi-agent orchestration, the 5-layer memory architecture, and the workflow taxonomy defined in [`docs/workflow-guide.md`](../workflow-guide.md).
+
+## Core Principles
+
+1. **Markdown + YAML Frontmatter + Mermaid:** Standardized metadata for automated indexing by the Context Arbiter, paired with human-readable text and conservative Mermaid diagrams.
+
+2. **Separation of Concerns:** Keep **what should happen** (Feature / Architecture / Test Plan), **what was decided** (ADR), and **what actually happened** (Test Report / Witness Receipt / Postmortem) distinct.
+
+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`.
+
+---
+
+## Template Directory
+
+| Template | File | Primary Workflow Stage | Key Outputs |
+
+|---|---|---|---|
+| **Feature Specification** | [`feature.md`](feature.md) | Stage 1: Requirements & Scope | Observable behavior, acceptance criteria table, user flow diagram. |
+
+| **Research Brief** | [`research.md`](research.md) | Stage 1: Discovery & Spike | Falsifiable hypotheses, evidence register, option comparison matrix. |
+| **Bug Investigation & Fix** | [`bug-fix.md`](bug-fix.md) | Stages 1–3: Repro, Fix, Verify | Repro before oracle, sequenceDiagram, exact test command, before/after evidence. |
+
+| **Architecture Design** | [`architecture.md`](architecture.md) | Stage 1: Architecture & System Design | Trust boundaries, component ownership, runtime scenarios, failure modes. |
+| **Architecture Decision Record (ADR)** | [`adr.md`](adr.md) | Ongoing: Technical Decisions | Decision drivers, considered options with pros/cons, consequences, revisit triggers. |
+
+| **Test Plan** | [`test-plan.md`](test-plan.md) | Stage 2: Verification Design | Risk-to-coverage matrix, test cases, environment prerequisites, entry/exit criteria. |
+| **Test Execution Report** | [`test-report.md`](test-report.md) | Stage 3: Witness Verification | Exact build/commit, execution timestamps, case outcomes, coverage diff. |
+
+| **Dual-Critic Review Report** | [`review.md`](review.md) | Stage 4: Critic Quorum | Independent Fable (arch) and Astra/Sol (CLI) findings, severity, quorum verdict. |
+| **Structured Handoff Manifest** | [`handoff.md`](handoff.md) | Inter-stage transitions | `kxm.handoff-manifest.v1` mapping, baseCommit, candidateTreeHash, deliverables. |
+
+| **Operational Runbook** | [`runbook.md`](runbook.md) | Reliability & Ops | Diagnosis steps, safe mitigation commands, rollback triggers, escalation paths. |
+| **Incident Postmortem** | [`postmortem.md`](postmortem.md) | Post-incident Retrospective | Timeline of events, root cause analysis, preventive action items. |
+
+---
+
+## Workflow Guide Integration Matrix
+
+The 12 templates map directly across the 7 Areas and 22 Workflows in [`docs/workflow-guide.md`](../workflow-guide.md):
+
+```mermaid
+flowchart TD
+    subgraph PlanStage ["1. Planning & Design"]
+        F["feature.md"]
+        R["research.md"]
+        A["architecture.md"]
+        ADR["adr.md"]
+    end
+
+    subgraph ExecStage ["2. Implementation & Testing"]
+        B["bug-fix.md"]
+        TP["test-plan.md"]
+        H1["handoff.md (Plan -> Write)"]
+    end
+
+    subgraph VerifyStage ["3. Verification & Review"]
+        TR["test-report.md (Witness)"]
+        REV["review.md (Dual Critics)"]
+        H2["handoff.md (Write -> Critic)"]
+    end
+
+    subgraph OpsStage ["4. Operations & Maintenance"]
+        RB["runbook.md"]
+        PM["postmortem.md"]
+    end
+
+    PlanStage --> ExecStage
+    ExecStage --> VerifyStage
+    VerifyStage --> OpsStage
+
+```
+
+### Mapping by Area
+
+1. **Software Engineering (`software-engineering`)**
+   - `feature-delivery`: [`feature.md`](feature.md) $\rightarrow$ [`architecture.md`](architecture.md) $\rightarrow$ [`test-plan.md`](test-plan.md) $\rightarrow$ [`review.md`](review.md).
+   - `bug-investigation`: [`bug-fix.md`](bug-fix.md) with mandatory reproduction test before oracle.
+   - `refactoring-migration`: [`architecture.md`](architecture.md) + [`adr.md`](adr.md) + [`test-report.md`](test-report.md).
+
+2. **Design & Experience (`design-experience`)**
+   - `ui-ux-design-system`: [`feature.md`](feature.md) (user flows) + [`review.md`](review.md) (a11y audits).
+
+3. **Data & Analytics (`data-analytics`)**
+   - `data-pipeline-etl`: [`architecture.md`](architecture.md) (data flows, contracts) + [`runbook.md`](runbook.md).
+
+4. **Research & Strategy (`research-strategy`)**
+   - `technology-evaluation` / `market-research`: [`research.md`](research.md) with evidence registers and confidence bounds.
+
+5. **Security & Reliability (`security-reliability`)**
+   - `vulnerability-audit`: [`review.md`](review.md) (threat model) + [`bug-fix.md`](bug-fix.md).
+   - `incident-response`: [`runbook.md`](runbook.md) (triage/mitigation) $\rightarrow$ [`postmortem.md`](postmortem.md) (blameless retrospective).