@kontextmind/kxm 0.7.94 → 0.7.96

package/docs/templates/runbook.md

@@ -2,9 +2,9 @@
 schema: "kxm.doc.v1"
 id: "RB-0001"
 type: "runbook"
-title: "Operational Runbook Title"
+title: "Operational runbook title"
 project: "kxm"
-status: "approved"
+status: "draft" # draft | in_review | approved | superseded | archived
 owner: "@ops"
 created: "2026-09-08"
 updated: "2026-09-08"
@@ -14,60 +14,68 @@ summary: "Procedures for diagnosing and mitigating <operational incident>."
 tags: ["operations", "runbook", "triage"]
 related: []
 details:
-  service: "hub"
+  service: "hub" # hub | runtime | worker | plugin
   target_environment: "local-or-server"
 ---
 
-# Operational Runbook: <Incident / Procedure Name>
+# Operational runbook: <incident or procedure name>
 
-## Symptoms & Alerts
+## Symptoms and alerts
 
-- **Alert / Observable Signal:** <Describe alert, log error code, or metric spike>
+- **Observable signal:** <alert, log event, error code, or metric>
+- **Impact:** <stuck workflow run, idle worker, refused sync, or failed signal>
 
-- **Impact:** <Worker starvation, stuck approval, or failed signal dispatch>
+## Triage
 
-## Triage & Diagnostic Steps
+Check the hub first, then the Runtime, then the workers.
 
 ```mermaid
 flowchart TD
-    Detect[Alert Detected] --> CheckHub{Is kxm hub running?}
-    CheckHub -->|No| Restart[Run kxm hub start]
-    CheckHub -->|Yes| CheckDB{Is SQLite DB locked?}
-    CheckDB -->|Yes| ClearLocks[Check .git/*.lock & WAL mode]
-    CheckDB -->|No| CheckLogs[Inspect .kxm/logs/telemetry.jsonl]
-
+    Detect[Signal detected] --> Hub{kxm hub view healthy?}
+    Hub -->|No| Start[Restart the hub]
+    Hub -->|Yes| Runtime{kxm runtime status running?}
+    Runtime -->|No| RtStart[kxm runtime start]
+    Runtime -->|Yes| Procs["Inspect workers in kxm dash --screen procs"]
+    Procs --> Logs[Read .kxm/logs/ for the failing component]
 ```
 
-*Triage decision tree: Verify hub daemon health, inspect database locks, and triage worker logs.*
-
-1. **Verify Hub Daemon Status:**
+1. Check hub health and readiness:
 
    ```bash
    kxm hub view
    ```
 
-2. **Inspect Active Worker Processes:**
+2. Check the Runtime supervisor:
 
    ```bash
-   kxm procs --json
+   kxm runtime status
    ```
 
-3. **Check SQLite Integrity:**
+3. Inspect supervised worker processes:
 
    ```bash
-   sqlite3 .kxm/state/kxm.db "PRAGMA integrity_check;"
+   kxm dash --screen procs
    ```
 
-## Safe Mitigation Commands
+4. Check SQLite integrity, read-only, after taking a backup:
 
-| Issue | Remediation Command | Expected Outcome |
-|---|---|---|
-| Orphaned Worktree Lock | `rm -f .git/kxm-worktree.lock` | Restores concurrent worktree creation |
-| Stale Dispatched Effect | `kxm routing unquarantine <routeId>` | Restores model route to roster |
-| Stuck Active Run | `kxm workflow signal <runId> cancel` | Safely aborts and cleans up attempt token |
+   ```bash
+   kxm backup --out <backup-dir>
+   sqlite3 -readonly .kxm/state/kxm.db "PRAGMA integrity_check;"
+   ```
+
+## Safe mitigation commands
 
-## Rollback & Escalation
+| Issue | Command | Expected outcome |
+|---|---|---|
+| Hub unhealthy or wedged | `kxm hub stop`, then `kxm hub start` | Hub restarts; queued messages are pushed again until acknowledged, and delivered messages are not replayed |
+| Runtime run stuck | `kxm runs cancel <run-id>` | A durable cancellation request is recorded for the run |
+| Model route misbehaving | `kxm routes disable --model <provider/model>` | The route moves to the disabled list in `.kxm/routes.yaml`; commit it |
+| Sync rows refused by the hub | Fix the hub-side cause, then `kxm runtime sync-retry` | Refused outbox rows are queued again |
+| Hub workflow waiting on a lost callback | `kxm gate signal <run-id> <signal-key> failed "<summary>"` | The wait settles with a `failed` result; needs the callback secret |
 
-- **Rollback Procedure:** <Exact command to restore previous database backup: `kxm restore <backup>`>
+## Rollback and escalation
 
-- **Escalation Path:** <Primary on-call or human operator contact>
+- **Rollback:** restore the last verified backup with
+  `kxm restore <manifest>` while the hub is stopped.
+- **Escalation:** <primary on-call or human operator contact>

package/docs/templates/test-plan.md

@@ -2,7 +2,7 @@
 schema: "kxm.doc.v1"
 id: "TEST-0001"
 type: "test_plan"
-title: "Test Plan for Feature / Refactor"
+title: "Test plan: <feature or refactor>"
 project: "kxm"
 status: "draft" # draft | in_review | approved | superseded | archived
 owner: "@owner"
@@ -18,9 +18,9 @@ details:
   target_suite: "core" # core | simulations | complete
 ---
 
-# Test Plan: <Feature / Refactor Name>
+# Test plan: <Feature / refactor name>
 
-## Objective & Scope
+## Objective and scope
 
 - **Feature / Change Under Test:** <Link to FEAT-xx, BUG-xx, or ARCH-xx>
 
@@ -28,34 +28,30 @@ details:
 
 - **Excluded Behavior:** <Explicitly list deferred or out-of-scope scenarios>
 
-## Risks & Coverage Strategy
+## Risks and coverage strategy
 
 | Risk / Failure Mode | Test Tier | Rationale for Selected Coverage | Target File |
-
 |---|---|---|---|
 | Race condition on git index | Unit (Concurrency) | Immediate lock failure detection | `test/core/external-effects.test.ts` |
-
 | Context packet token overflow | Unit (Arbiter) | Verifies token pruning order | `test/core/context-packet.test.ts` |
-| Multi-agent peer deadlock | Simulation | Replays multi-turn timeout | `test/simulations/deadlock.test.ts` |
+| Multi-agent peer deadlock | Simulation | Replays multi-turn timeout | `test/simulations/<scenario>.test.ts` |
 
-## Test Environment & Preconditions
+## Test environment and preconditions
 
-- **Runtime:** Node 22.19.0 / Node 24.15.0
+- **Runtime:** Node 22.19 or newer on the 22 line, and Node 24
 
-- **Database Fixture:** In-memory `:memory:` SQLite or isolated `.kxm/tmp/test.db`
+- **Database Fixture:** In-memory `:memory:` SQLite, or a database under a `mkdtemp` directory
 
 - **Harness Preflight:** `kxm harness list` verifying mock or native CLI status
 
-## Detailed Test Cases
+## Detailed test cases
 
 | Case ID | Requirement | Precondition | Test Action | Expected Result |
-
 |---|---|---|---|---|
-| TC-01 | REQ-01 | Clean database | Call `claimEffect()` twice concurrently | One succeeds, one returns `ok: false, conflict: true` |
-
+| TC-01 | REQ-01 | Clean database | Call `claimEffect()` twice for one effect key | The first claim succeeds; the second is refused |
 | TC-02 | REQ-02 | Valid lease | Call `commitEffect()` with effect key | Status transitions to `confirmed` |
 
-## Test Execution Workflow
+## Test execution workflow
 
 ```mermaid
 flowchart LR
@@ -68,20 +64,17 @@ flowchart LR
 
 *Verification flow: Build runtime artifacts, run core tests, enforce types and linting, and verify generated dist files match staged index.*
 
-## Execution Commands
+## Execution commands
 
 | Suite | Command | Expected Output |
-
 |---|---|---|
-| Core Tests | `npm run test:core` | `tests >= 1008, fail 0` |
-
+| Core Tests | `npm run test:core` | `# fail 0` |
 | Typecheck | `npm run typecheck` | Clean exit code 0 |
-| Docs Lint | `npm run lint:docs` | `0 issues in 0 files` |
-
+| Docs Lint | `npm run lint:docs` | `Summary: 0 issues` |
 | Generated Dist | `npm run check:generated` | `generated artifacts are tracked and current` |
 
-## Entry & Exit Criteria
+## Entry and exit criteria
 
 - **Entry Criteria:** Clean git working tree; `npm run build` succeeds without warnings.
 
-- **Exit Criteria:** All test cases pass with zero failures; coverage thresholds met (lines >= 92%, branches >= 80%).
+- **Exit Criteria:** All test cases pass with zero failures; coverage floors met (91% lines, 80% branches, 92% functions for `npm run test:coverage`).

package/docs/templates/test-report.md

@@ -2,7 +2,7 @@
 schema: "kxm.doc.v1"
 id: "REP-0001"
 type: "test_report"
-title: "Test Execution Witness Report"
+title: "Test execution witness report"
 project: "kxm"
 status: "approved" # draft | approved | archived
 owner: "@verifier"
@@ -20,52 +20,49 @@ details:
   branch: "kxm/run-<id>-<description>"
 ---
 
-# Test Execution Witness Report
+# Test execution witness report
 
-## Metadata & Execution Environment
+## Metadata and execution environment
 
 - **Tested Commit:** `<git-sha>`
 
 - **Active Branch:** `kxm/run-<id>-<description>`
 
-- **Test Plan:** [`TEST-0001`](../testing/plans/TEST-0001.md)
+- **Test Plan:** `TEST-0001` (`<path to the test plan>`)
 
 - **Executed At:** `2026-09-08T15:45:00Z`
 
 - **Verifier:** `npm run verify` witness gate runner
 
-- **OS & Runtime:** macOS / Node v24.15.0
+- **OS & Runtime:** `<operating system>` / Node `<version>`
 
-## Summary of Results
+## Summary of results
 
-| Suite | Total Tests | Passed | Failed | Skipped | Duration | Status |
+Replace the example values below with the run's actual counts.
 
+| Suite | Total Tests | Passed | Failed | Skipped | Duration | Status |
 |---|---|---|---|---|---|---|
 | `test:core` | 1008 | 1003 | 0 | 5 (Windows) | 271s | PASS |
-
 | `typecheck` | N/A | N/A | 0 | 0 | 3s | PASS |
 | `lint:docs` | 57 files | 57 | 0 | 0 | 2s | PASS |
-
 | `check:generated` | 14 files | 14 | 0 | 0 | 4s | PASS |
 
-## Test Case Execution Details
+## Test case execution details
 
 | Case ID | Suite File | Result | Duration | Artifact Reference |
-
 |---|---|---|---|---|
 | TC-01 | `test/core/external-effects.test.ts` | PASS | 1.8ms | `artifact:.kxm/assets/witness.log@sha256:...` |
-
 | TC-02 | `test/core/context-packet.test.ts` | PASS | 0.9ms | `artifact:.kxm/assets/witness.log@sha256:...` |
 
-## Test Coverage Metrics
+## Test coverage metrics
 
-- **Line Coverage:** 92.4% (Threshold: >= 92%)
+- **Line Coverage:** 92.4% (floor: 91%)
 
-- **Branch Coverage:** 81.2% (Threshold: >= 80%)
+- **Branch Coverage:** 81.2% (floor: 80%)
 
-- **Function Coverage:** 93.5% (Threshold: >= 93%)
+- **Function Coverage:** 93.5% (floor: 92%)
 
-## Verdict & Recommendation
+## Verdict and recommendation
 
 - **Witness Verdict:** **VERIFIED PASS**
 

package/examples/README.md

@@ -2,7 +2,11 @@
 
 These examples demonstrate the transport without requiring an AI model. Run them from the repository root after `npm ci`.
 
-The [`.kxm/workflows/default.yaml`](../.kxm/workflows/default.yaml) workspace configuration is a production-oriented definition for a long-lived coordinator. It covers reproduction, single-agent or three-agent planning, plan review, implementation, local and repository gates, documentation, push/watch retries, merge, Jira update, and continuous improvement. Follow [Webhook workflows](../docs/webhook-workflows.md) to configure it.
+The [`webhook-workflows/jira-development.json`](webhook-workflows/jira-development.json)
+definition turns a signed Jira `issue_updated` webhook into a five-stage hub
+workflow run for a long-lived coordinator: reproduce, plan, implement, checks,
+and report. Follow [Webhook workflows](../docs/guides/webhook-workflows.md) to
+configure it.
 
 The [`workflow-signal.ts`](workflow-signal.ts) sender demonstrates the signed callback that resumes a coordinator after CI, review, merge, or Jira work completes. The webhook guide documents its required environment and arguments.
 
@@ -12,12 +16,12 @@ one exact run, stage, requirement, and attempt, while demonstrating an optional
 admin-approved one-peer degradation. Its tested topology is project
 `provenance-demo`, coordinator `coordinator`, and reviewers `reviewer-claude`
 and `reviewer-grok`. Follow
-[Peer provenance and quorum gates](../docs/provenance-gates.md) for the complete
+[Peer provenance and quorum gates](../docs/guides/provenance-gates.md) for the complete
 runbook and trust boundary.
 
-The [`runtime`](kxm/README.md) directory is a machine-validated planned-contract
-fixture for the local-first KXM architecture. Production configuration
-loader tests consume it, but no current Runtime executes its workflows.
+The [`project`](project/README.md) directory is a machine-validated project
+fixture for the local-first KXM contracts. The configuration loader and
+workflow compiler tests consume it.
 
 ## Self-contained round trip
 

package/examples/provenance-workflow.json

@@ -11,7 +11,7 @@
       {
         "id": "review",
         "label": "Independent review",
-        "instructions": "Ask both eligible reviewers independently with one kxm_fanout call. Set correlationId to the exact run ID, timeoutMs to 120000, and idempotencyKeyPrefix to the deterministic value provenance-review:<runId>:review:<attempt>. The tool call itself must include workflowContext for this run, stage review, requirement independent peer reviews, and the current attempt; stating that context in a plan is not sufficient. Treat every returned messageId as the durable handle immediately. Use kxm_get to verify each stored message has the exact run, stage, requirement, and attempt binding. For every pending reply, call kxm_await with that messageId and timeoutMs 120000; never replace pending work with a new idempotency prefix. On interruption or uncertain delivery, repeat the exact fanout parameters so the hub returns the same messages. Re-read and verify each durable message after it replies. Compare findings, record contradictions and the chosen resolution, then cite only the bound durable replied message IDs.",
+        "instructions": "Ask both eligible reviewers independently with one kxm_fanout call. Set correlationId to the exact run ID, timeoutMs to 120000, and idempotencyKeyPrefix to the deterministic value provenance-review:<runId>:review:<attempt>. The tool call itself must include workflowContext for this run, stage review, requirement independent peer reviews, and the current attempt; stating that context in a plan is not sufficient. Treat every returned messageId as the durable handle immediately. Use kxm_get to verify each stored message has the exact run, stage, requirement, and attempt binding. For every pending reply, call kxm_await with that messageId and timeoutMs 60000 (its maximum), repeating the call while it stays pending; never replace pending work with a new idempotency prefix. On interruption or uncertain delivery, repeat the exact fanout parameters so the hub returns the same messages. Re-read and verify each durable message after it replies. Compare findings, record contradictions and the chosen resolution, then cite only the bound durable replied message IDs.",
         "requiredEvidence": [
           "independent peer reviews",
           "coordinator decision"

package/examples/webhook-workflows/jira-development.json

@@ -0,0 +1,59 @@
+[
+  {
+    "id": "jira-development",
+    "source": "jira",
+    "project": "product",
+    "target": "coordinator",
+    "secretEnv": "JIRA_WEBHOOK_SECRET",
+    "signalSecretEnv": "WORKFLOW_SIGNAL_SECRET",
+    "event": "jira:issue_updated",
+    "filter": {
+      "path": "issue.fields.status.name",
+      "equals": "In Progress"
+    },
+    "delivery": "followUp",
+    "promptTemplate": "Jira issue {{issue.key}} moved to In Progress: {{issue.fields.summary}}. Deliver a reviewed fix on a branch and a pull request. Do not merge.",
+    "stages": [
+      {
+        "id": "reproduce",
+        "label": "Reproduce",
+        "instructions": "Reproduce the reported behavior with a deterministic failing test or script before changing product code. Cite the test path and the failing command.",
+        "requiredEvidence": ["reproduction"],
+        "maxAttempts": 3,
+        "area": "implementation"
+      },
+      {
+        "id": "plan",
+        "label": "Plan and review",
+        "instructions": "Write a bounded plan with file ownership. Ask one peer to review it with kxm_send, record contradictions and decisions with kxm_workflow_record, and revise the plan before implementing.",
+        "requiredEvidence": ["plan", "plan review"],
+        "maxAttempts": 3,
+        "area": "workflow"
+      },
+      {
+        "id": "implement",
+        "label": "Implement and verify locally",
+        "instructions": "Implement the plan. Run lint, typecheck, and the test suite, and make the reproduction pass. Cite each command and its result.",
+        "requiredEvidence": ["changed files", "local checks"],
+        "maxAttempts": 3,
+        "area": "implementation"
+      },
+      {
+        "id": "checks",
+        "label": "Pull request checks",
+        "instructions": "Push the branch and open or update the pull request. Then call kxm_workflow_wait on this stage with signal key github-pr-<number>-checks and settle your turn. An operator or CI job runs kxm gate github watch, which posts the signed result.",
+        "requiredEvidence": ["github.check:ci"],
+        "maxAttempts": 3,
+        "area": "gates"
+      },
+      {
+        "id": "report",
+        "label": "Update Jira and record lessons",
+        "instructions": "Comment on the Jira issue with the pull request link and the evidence summary, using your own authorized Jira tool. Record at least one lesson with kxm_workflow_record. Do not merge the pull request.",
+        "requiredEvidence": ["jira comment", "lessons"],
+        "maxAttempts": 2,
+        "area": "documentation"
+      }
+    ]
+  }
+]

package/examples/webhook-workflows/jira-issue-updated.json

@@ -0,0 +1,12 @@
+{
+  "webhookEvent": "jira:issue_updated",
+  "issue": {
+    "key": "PROD-123",
+    "fields": {
+      "summary": "Checkout total ignores the discount code",
+      "status": {
+        "name": "In Progress"
+      }
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kontextmind/kxm",
-  "version": "0.7.94",
+  "version": "0.7.96",
   "description": "KXM local-first multi-agent orchestration and operator dashboard",
   "type": "module",
   "author": "KontextMind",
@@ -48,7 +48,7 @@
     "verify": "npm test && npm run check && npm run check:generated",
     "validate:claude": "claude plugin validate . --strict && claude plugin validate plugins/kxm --strict",
     "validate:ci": "npm run test:coverage && npm run check && npm pack --dry-run",
-    "validate:pr": "npm run test:core && npm run check && npm run check:generated",
+    "validate:pr": "npm run build && npm run typecheck && node --disable-warning=ExperimentalWarning --experimental-strip-types --test --test-concurrency=4 test/core/artifacts-exist.test.ts test/core/ci-contract.test.ts test/core/envelope.test.ts test/core/envelope-contract.test.ts test/core/protocol.test.ts test/core/repo-root.test.ts test/core/routes-count.test.ts test/core/smoke.test.ts test/core/version-surfaces.test.ts && npm run check:versions && node scripts/check-generated.mjs",
     "validate": "npm run validate:ci && npm run validate:claude",
     "test:packages": "npx nx run-many -t test --output-style=static",
     "check:packages": "npx nx run-many -t build,test:coverage,typecheck --output-style=static",

package/packages/core/tui/README.md

@@ -5,7 +5,7 @@ one input decoder, one contribution registry, and thin host adapters.
 
 `kxm dash` and every configuration surface draw from here so a field looks,
 keys, and fails the same way across the product. Guide:
-[`docs/tui-components.md`](../../../docs/tui-components.md).
+[`docs/tui-components.md`](../../../docs/contributing/tui-components.md).
 
 ## Layout
 

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

@@ -2,7 +2,7 @@
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "kxm",
   "displayName": "KXM",
-  "version": "0.7.94",
+  "version": "0.7.96",
   "description": "Headless multi-agent orchestration, durable workflows, and a live operator dashboard for Pi and Claude Code",
   "author": {
     "name": "KontextMind",