@kontextmind/kxm 0.6.0

package/docs/templates/adr.md

@@ -0,0 +1,88 @@
+---
+schema: "kxm.doc.v1"
+id: "ADR-0001"
+type: "adr"
+title: "Title of Architecture Decision"
+project: "kxm"
+status: "proposed" # proposed | accepted | superseded | deprecated | rejected
+owner: "@owner"
+created: "2026-09-08"
+updated: "2026-09-08"
+authority: "instruction"
+confidence: "verified"
+summary: "Short decision summary and primary technical consequence."
+tags: ["architecture", "decision"]
+related: []
+details:
+  decision_drivers: ["concurrency-safety", "dependency-minimization"]
+  supersedes: null
+  superseded_by: null
+---
+
+# ADR-0001: <Title of Architecture Decision>
+
+## Context & Problem Statement
+
+<Describe the technical context, operational dilemma, or architectural friction. What forces are compelling this decision?>
+
+## Decision Drivers
+
+1. **Driver 1:** <e.g., Eliminate native compilation failures across Node versions>
+
+2. **Driver 2:** <e.g., Enforce deterministic replay without external network calls>
+
+3. **Driver 3:** <e.g., Maintain fail-closed security invariants without loopback bypasses>
+
+## Considered Options
+
+- **Option A:** <Name of Option A>
+
+- **Option B:** <Name of Option B>
+
+- **Option C:** <Name of Option C>
+
+## Evaluation & Tradeoff Matrix
+
+### Option A: <Name of Option A>
+
+- **Good, because:** <Advantage 1>
+
+- **Good, because:** <Advantage 2>
+
+- **Bad, because:** <Drawback 1>
+
+- **Bad, because:** <Drawback 2>
+
+### Option B: <Name of Option B>
+
+- **Good, because:** <Advantage 1>
+
+- **Bad, because:** <Drawback 1>
+
+## Decision Outcome
+
+**Chosen Option:** **Option A**, because <comprehensive justification referencing drivers>.
+
+### Positive Consequences
+
+- <Favorable outcome 1>
+
+- <Favorable outcome 2>
+
+### Negative Consequences & Accepted Tradeoffs
+
+- <Technical debt, limitation, or operational overhead incurred>
+
+## Confirmation & Verification Strategy
+
+- **Verification Gate:** <Exact test suite or contract check enforcing this decision>
+
+- **Enforcement Mechanism:** <Linter, type-check, or CI rule that prevents regressions>
+
+## Revisit Conditions
+
+This decision should be formally re-evaluated if:
+
+1. <Condition 1, e.g., Upstream Node.js deprecates the built-in API>
+
+2. <Condition 2, e.g., Telemetry reveals unresolvable lock contention under 100+ concurrent workers>

package/docs/templates/architecture.md

@@ -0,0 +1,120 @@
+---
+schema: "kxm.doc.v1"
+id: "ARCH-0001"
+type: "architecture"
+title: "System / Subsystem Architecture Design"
+project: "kxm"
+status: "draft" # draft | in_review | approved | superseded | archived
+owner: "@owner"
+created: "2026-09-08"
+updated: "2026-09-08"
+authority: "instruction"
+confidence: "verified"
+summary: "System boundaries, component responsibilities, and runtime invariants."
+tags: []
+related: []
+details:
+  describes: "proposed" # current | proposed | target
+  baseline_commit: "<git-sha>"
+---
+
+# Architecture: <System / Subsystem Name>
+
+## Purpose & Scope
+
+- **Core Mission:** <What capability does this subsystem deliver?>
+
+- **Audience & Callers:** <Who interacts with this system (interactive operators, workers, external webhooks)?>
+
+- **Architecture State:** <Explicitly state whether this document reflects current, proposed, or target architecture>
+
+## Goals, Quality Attributes & Constraints
+
+| Goal / Constraint | Business or Technical Driver | Measurement Metric / Hard Boundary |
+
+|---|---|---|
+| Fail-Closed Security | Prevent privilege escalation | Reject missing tokens; zero loopback bypasses |
+
+| Deterministic Replay | Forensic debugging & auditability | Folded event stream produces identical state |
+| Low Latency Dispatch | Operator responsiveness | Sub-200ms dispatch P50 |
+
+## Context & Trust Boundaries
+
+```mermaid
+flowchart TB
+    subgraph External ["Untrusted External Perimeter"]
+        Caller["Operator / External Webhook / CI"]
+    end
+
+    subgraph AuthPlane ["Access Control Plane (Trust Boundary)"]
+        TokenVal["Token Validator (Admin / Session / Attempt)"]
+    end
+
+    subgraph Internal ["KXM Core Domain"]
+        Engine["Temporal Workflow Engine"]
+        Memory["5-Layer Memory & Context Arbiter"]
+        Store[("SQLite Store: .kxm/state/kxm.db")]
+    end
+
+    Caller -->|Request + Token| TokenVal
+    TokenVal -->|Authorized Call| Engine
+    Engine --> Memory
+    Engine --> Store
+
+```
+
+*Context flow: External requests enter through the Access Control Plane. Authorized calls interact with the Temporal Engine and Context Arbiter, backed by durable SQLite storage.*
+
+## Component Responsibilities & Ownership
+
+| Component | Responsibility | Public Interface / Contract | Owned State / Tables | Team / Role Owner |
+
+|---|---|---|---|---|
+| Workflow Engine | DAG scheduling & loop transitions | `VnextEngine.drive()` | `run_events`, `workflow_runs` | Engine Lead |
+
+| Context Arbiter | Token budgeting & context compilation | `arbitrate()` | In-memory pool + Git memory | Memory Lead |
+| External Effects Ledger | CAS leasing & idempotency | `ExternalEffectsLedger` | `external_effects` | Platform Lead |
+
+## Runtime Execution Scenarios
+
+### 1. Happy Path Dispatch & Settlement
+
+1. Step dispatch compiles `FormalContextPacket` (`kxm.context-packet.v2`).
+
+2. Worker executes in isolated branch `kxm/run-<id>-<description>`.
+
+3. Worker submits `kxm.handoff-manifest.v1` with witness receipt.
+
+4. Engine commits transition and notifies critics.
+
+### 2. Failure & Rework Path
+
+1. Critic issues structured rejection findings with blocker severity.
+
+2. Engine transitions step to `rejected_rework_required`.
+
+3. Attempts counter increments; router dispatches to next eligible writer.
+
+## Data Contracts, Storage & Invariants
+
+- **Source of Truth:** Local-first SQLite (`.kxm/state/kxm.db`) using native `DatabaseSync` (`node:sqlite`).
+
+- **Journal Mode:** WAL mode with `busy_timeout = 5000ms` and `synchronous = NORMAL`.
+
+- **Branch Naming Invariant:** `kxm/run-<cleanId>-<slug>` generated deterministically.
+
+- **Commit Pinning:** Never fall back to mutable `HEAD`; strictly pin `reviewedCommit`.
+
+## Security & Isolation
+
+- **Token Model:** 3-tier model (AdminToken, SessionToken, AttemptToken).
+
+- **Process Isolation:** Worker processes run as detached children with bounded stdio frames.
+
+- **Git Worktree Lock:** Concurrent worktree mutations acquire `.git/kxm-worktree.lock`.
+
+## Architectural Decisions (ADR Index)
+
+- [`ADR-0001: SQLite Native node:sqlite Engine`](../decisions/ADR-0001.md)
+
+- [`ADR-0002: Deterministic Run Branching`](../decisions/ADR-0002.md)

package/docs/templates/bug-fix.md

@@ -0,0 +1,109 @@
+---
+schema: "kxm.doc.v1"
+id: "BUG-0001"
+type: "bug"
+title: "Observable Failure / Defect Summary"
+project: "kxm"
+status: "draft" # draft | in_review | approved | superseded | archived
+owner: "@owner"
+created: "2026-09-08"
+updated: "2026-09-08"
+authority: "instruction"
+confidence: "verified"
+summary: "Expected behavior, observed failure, and scope of regression."
+tags: []
+related: []
+details:
+  fix_status: "triaged" # triaged | repro_confirmed | in_progress | verified | closed
+  severity: "high" # critical | high | medium | low
+  reproducibility: "always" # always | intermittent | environment_specific
+---
+
+# Bug: <Observable Failure / Defect Summary>
+
+## Impact & Affected Scope
+
+- **User / Operator Impact:** <What fails, crashes, or produces incorrect outputs?>
+
+- **Affected Commands / APIs:** <Specific CLI commands, endpoints, or workflows>
+
+- **Workaround:** <Temporary safe mitigation if available>
+
+## Expected vs. Actual Behavior
+
+- **Expected:** <Precise, observable contract expectation>
+
+- **Actual:** <Exact error message, stack trace, or wrong output>
+
+## Environment & Baseline State
+
+- **Baseline Commit:** `<git-sha-before-fix>`
+
+- **Node / Runtime Version:** `Node 22.19.0 / Node 24.15.0`
+
+- **Active Harness / Model:** `<Harness and model if relevant>`
+
+- **OS:** `macOS / Linux`
+
+## Mandatory Repro Before Fix (Oracle Invariant)
+
+To prevent phantom fixes, a failing reproduction test MUST be established before modifying production code:
+
+- **Failing Test File:** `test/core/<bug-name>.test.ts`
+
+- **Reproduction Command:** `node --test test/core/<bug-name>.test.ts`
+
+- **Baseline Observed Result:** `FAIL` (exit code 1)
+
+- **Repro Failure Receipt:** `artifact:.kxm/assets/repro-fail.log@sha256:...`
+
+## Failure Path Sequence
+
+```mermaid
+sequenceDiagram
+    participant C as Caller / CLI
+    participant H as Hub / Engine
+    participant S as Store / Provider
+
+    C->>H: Execute Action (e.g. claimEffect)
+    H->>S: Mutate State Without Lock
+    S-->>H: SQLite Lock Contention / Collision
+    H-->>C: Unhandled Crash (Expected: Graceful Retry)
+
+```
+
+*Failure sequence: Unhandled contention leads to ungraceful crash instead of deterministic retry or clean fail-closed error.*
+
+## Root Cause Analysis
+
+- **Immediate Cause:** <What line or condition directly triggered the symptom?>
+
+- **Systemic Cause:** <Why did earlier tests, linters, or reviews miss this bug?>
+
+- **Rejected Hypotheses:** <What initial assumptions were investigated and ruled out?>
+
+## Proposed Fix & Contract Changes
+
+- **Code Changes:** <Summary of modifications to code or schemas>
+
+- **Compatibility Impact:** <Does this break existing state or require a database migration?>
+
+- **Security / Isolation:** <Does the fix maintain fail-closed invariants?>
+
+## Verification Witness Matrix
+
+| Verification Check | Target Commit / Tree | Expected Result | Actual Result | Witness Artifact |
+
+|---|---|---|---|---|
+| Repro Test (Before Fix) | `<baseline-commit>` | FAIL | FAIL | `artifact:...@sha256` |
+
+| Repro Test (After Fix) | `<candidate-commit>` | PASS | PASS | `artifact:...@sha256` |
+| Full Core Test Suite | `<candidate-commit>` | 100% PASS | 100% PASS | `npm run test:core` |
+
+| Full Verify Gate | `<candidate-commit>` | PASS | PASS | `npm run verify` |
+
+## Regression Prevention
+
+- **Automated Gate Added:** <New unit test or lint check preventing recurrence>
+
+- **Documentation Updated:** <Link to updated architecture or runbook doc>

package/docs/templates/feature.md

@@ -0,0 +1,108 @@
+---
+schema: "kxm.doc.v1"
+id: "FEAT-0001"
+type: "feature"
+title: "Feature Name"
+project: "kxm"
+status: "draft" # draft | in_review | approved | superseded | archived
+owner: "@owner"
+created: "2026-09-08"
+updated: "2026-09-08"
+authority: "instruction" # policy | instruction | evidence | hypothesis
+confidence: "verified" # verified | probable | uncertain
+summary: "One-sentence problem statement and intended observable outcome."
+tags: []
+related: []
+details:
+  delivery_status: "proposed"
+  target_workflow: "feature-delivery"
+---
+
+# Feature: <Feature Name>
+
+## Problem & Users
+
+- **Who needs this:** <Describe primary user persona or operator role>
+
+- **Current Behavior:** <What happens today without this feature>
+
+- **Evidence / Driver:** <User friction, issue link, or performance data demonstrating the need>
+
+## Goals & Non-Goals
+
+- **Goals:**
+  - <Measurable outcome 1>
+  - <Measurable outcome 2>
+
+- **Non-Goals:**
+  - <Explicitly excluded behavior or deferred capability>
+
+## Requirements & Acceptance Criteria
+
+| ID | Requirement | Acceptance Criterion (Given / When / Then) | Verification Kind |
+
+|---|---|---|---|
+| REQ-01 | <Observable behavior> | Given ..., when ..., then ... | gate / witness |
+
+| REQ-02 | <Error or permission boundary> | Given invalid input, when submitted, then fail closed with ... | gate / witness |
+
+## User & Execution Flow
+
+```mermaid
+flowchart LR
+    User[User / Operator Action] --> Validate{Input & Access Valid?}
+    Validate -->|Yes| Execute[Perform Operation]
+    Validate -->|No| Error[Return Actionable Fail-Closed Error]
+    Execute --> Witness[Run Witness Verification]
+    Witness --> Result[Render Outcome]
+
+```
+
+*Flow description: The request is validated against permissions and schema before execution. Invalid calls fail closed with actionable errors.*
+
+## Behavior & Interface Contracts
+
+- **Inputs & CLI Flags:** <Specify syntax and types>
+
+- **Outputs & Schema:** <JSON schema or return contract>
+
+- **Error Modes:** <List specific error codes and exit status>
+
+- **Concurrency & Idempotency:** <Timeout limits, lock keys, and duplicate dispatch protection>
+
+## Quality & Resource Budgets
+
+| Dimension | Target Budget | Measurement Condition | Verification Method |
+
+|---|---|---|---|
+| Latency P50 | < e.g., 200ms | Local CLI dispatch | Benchmark test |
+
+| Token Budget | < e.g., 8,000 tokens | Context packet compilation | Context Arbiter log |
+| Test Coverage | >= 92% lines, >= 80% branches | `npm run test:core` | Vitest / Node test runner |
+
+## Dependencies & Risks
+
+| Dependency / Risk | Potential Impact | Mitigation Strategy | Owner |
+
+|---|---|---|---|
+| <Dependency> | <Failure mode> | <Fallback or isolation> | <Role> |
+
+## Validation & Verification Gates
+
+- **Unit / Core Suite:** `npm run test:core`
+
+- **Lint & Docs Gate:** `npm run check`
+
+- **Combined Commit Gate:** `npm run verify`
+
+## Rollout & Rollback
+
+- **Rollout Strategy:** <Staged feature flag, CLI release, or workflow gate>
+
+- **Rollback Triggers:** <Observed error spikes, broken witnesses, or test regressions>
+
+- **Rollback Action:** <Git revert or toggle flag>
+
+## Open Questions
+
+1. <Unresolved design question, assigned owner, and target decision milestone>

package/docs/templates/handoff.md

@@ -0,0 +1,72 @@
+---
+schema: "kxm.doc.v1"
+id: "HND-0001"
+type: "handoff"
+title: "Structured Agent / Stage Handoff Manifest"
+project: "kxm"
+status: "approved"
+owner: "@source_role"
+created: "2026-09-08"
+updated: "2026-09-08"
+authority: "evidence"
+confidence: "verified"
+summary: "Formal handoff from <source_role> to <target_role> for workflow <workflow_id>."
+tags: ["handoff", "workflow", "stage-transition"]
+related: []
+details:
+  workflow_run_id: "run-01928abc"
+  handoff_manifest_id: "hnd_01928abcde12"
+  intent: "request_review" # continue | request_review | reject_rework_required | complete
+---
+
+# Structured Handoff Manifest
+
+## Stage Transition Provenance
+
+- **Workflow Run ID:** `run-01928abc`
+
+- **Task ID:** `task-127`
+
+- **Source Role:** `writer` (Harness: `grok`, Model: `grok-4.6`)
+
+- **Target Role:** `reviewer-arch` (Harness: `claude`, Model: `claude-fable-5-1`)
+
+- **Intent:** `request_review`
+
+## Repository & Branch Anchors
+
+- **Base Commit:** `44a7b50f9a2b6e14d3c2a1e09876543210abcdef`
+
+- **Candidate Commit:** `88b6c40a12e34f56789abcdef0123456789abcde`
+
+- **Candidate Tree Hash:** `789abcdef0123456789abcdef0123456789abcde`
+
+- **Deterministic Branch:** `kxm/run-01928abc-fix-issue-127-memory-arbiter`
+
+## Deliverables & Evidence
+
+### 1. Artifacts Created
+
+- `artifact:.kxm/assets/changes.patch@sha256:abc...`
+
+- `artifact:.kxm/assets/witness.log@sha256:def...`
+
+### 2. Witness Receipt
+
+- **Command:** `npm run verify`
+
+- **Exit Code:** `0`
+
+- **Receipt Hash:** `sha256:fedcba0987654321...`
+
+## Transferred Context & Decisions
+
+- **Settled Decisions:**
+  - Used SQLite `external_effects` table for CAS leasing.
+  - Implemented descriptive branch slugification with de-duplication.
+
+- **Assumptions:**
+  - Remote repository branch protection requires PR merge.
+
+- **Open Questions / Notes for Target Role:**
+  - Please verify memory revision hash changes deterministically when files in `.kxm/memory/` are touched.

package/docs/templates/postmortem.md

@@ -0,0 +1,77 @@
+---
+schema: "kxm.doc.v1"
+id: "PM-0001"
+type: "postmortem"
+title: "Incident Postmortem: <Incident Title>"
+project: "kxm"
+status: "approved"
+owner: "@incident-lead"
+created: "2026-09-08"
+updated: "2026-09-08"
+authority: "evidence"
+confidence: "verified"
+summary: "Blameless analysis, timeline, root cause, and action items for <incident>."
+tags: ["incident", "postmortem", "reliability"]
+related: []
+details:
+  incident_date: "2026-09-08"
+  severity: "sev-2" # sev-1 | sev-2 | sev-3
+  time_to_detect_minutes: 5
+  time_to_mitigate_minutes: 20
+---
+
+# Incident Postmortem: <Incident Title>
+
+## Executive Summary
+
+- **Incident Period:** `2026-09-08 14:10 UTC` to `2026-09-08 14:35 UTC` (25 minutes)
+
+- **User Impact:** <Number of workflow runs blocked or delayed>
+
+- **Root Cause:** <One-sentence summary of failure mechanism>
+
+## Incident Timeline (UTC)
+
+| Time | Event Description | Detected By |
+
+|---|---|---|
+| 14:10 | AI worker crashed during git push; CAS effect left in `dispatched` state | Log watcher |
+
+| 14:15 | Subsequent retry attempts blocked due to unexpired CAS lease | `kxm dash` operator |
+| 14:22 | Operator pressed `d` (degrade) to inspect worktree manually | Interactive TUI |
+
+| 14:30 | Fix committed; lease expiration policy patched | Operator |
+| 14:35 | Hub restarted; all queued workflow runs completed | Verifier |
+
+## Root Cause Analysis (5 Whys)
+
+1. **Why did the retry fail?** Because the CAS effect lease was locked in `dispatched` state.
+
+2. **Why was it still locked?** Because the previous worker process exited abnormally without calling abort.
+
+3. **Why did the lease not expire?** Because the lease had no automated heartbeat timeout.
+
+4. **Why was there no timeout?** Because CAS leasing was assumed to be synchronous.
+
+5. **Systemic Root Cause:** Missing failure recovery watchdog for unconfirmed external side-effect leases.
+
+## What Went Well / What Went Wrong
+
+### What Went Well
+
+- The database remained consistent; zero duplicate PRs were created on GitHub.
+
+- Degrade-to-human hotkey (`d`) allowed the operator to take over immediately.
+
+### What Went Wrong
+
+- The error message in `kxm dash` did not explicitly indicate how to force-release an abandoned lease.
+
+## Corrective & Preventive Action Items
+
+| Action Item | Type | Owner | Target Date | Issue Reference |
+
+|---|---|---|---|---|
+| Add 300s automated lease timeout to `ExternalEffectsLedger` | Prevent | Platform Lead | 2026-09-10 | #165 |
+
+| Add `kxm routing unquarantine` CLI command | Mitigate | CLI Lead | 2026-09-12 | #166 |

package/docs/templates/research.md

@@ -0,0 +1,100 @@
+---
+schema: "kxm.doc.v1"
+id: "RES-0001"
+type: "research"
+title: "Research Topic / Spike Question"
+project: "kxm"
+status: "draft" # draft | in_review | approved | superseded | archived
+owner: "@owner"
+created: "2026-09-08"
+updated: "2026-09-08"
+authority: "hypothesis" # policy | instruction | evidence | hypothesis
+confidence: "uncertain" # verified | probable | uncertain
+summary: "The specific architectural or operational decision this research enables."
+tags: []
+related: []
+details:
+  research_status: "planned"
+  target_decision_date: "2026-09-15"
+---
+
+# Research: <Research Topic / Spike Question>
+
+## Decision to Enable
+
+- **Pending Decision:** <What exact architectural, model routing, or product decision depends on this investigation?>
+
+- **Decision Owner:** <Who has authority to accept or reject the findings?>
+
+- **Constraints & Guardrails:** <Budget limits, latency thresholds, security boundaries>
+
+## Questions & Falsifiable Hypotheses
+
+- **Primary Question:** <What are we trying to discover or prove?>
+
+- **Hypothesis 1:** <Clear assertion that can be empirically verified or falsified>
+
+- **Falsification Condition:** <What exact result or metric will prove this hypothesis wrong?>
+
+## Methodology & Verification Setup
+
+```mermaid
+flowchart LR
+    Define[Define Hypotheses] --> Bounds[Set Cost & Scope Bounds]
+    Bounds --> Collect[Gather Empirical Evidence]
+    Collect --> Trial[Run Controlled Side-by-Side Trials]
+    Trial --> Evaluate[Analyze Telemetry & Rework]
+    Evaluate --> Recommend[Produce Actionable Recommendation]
+
+```
+
+*Methodology flow: Establish bounds, execute reproducible trials, analyze telemetry metrics, and recommend concrete next actions.*
+
+- **Harness & Model Arms:** <List evaluated routes, e.g. Grok native vs Pi wrapper vs Claude Fable>
+
+- **Test Fixture / Workload:** <Exact repository task or test suite executed>
+
+- **Budget Ceiling:** <Maximum dollar or token limit for this spike>
+
+## Evidence Register
+
+| Evidence ID | Claim / Finding | Source Artifact / Telemetry Run | Version / Date | Confidence |
+
+|---|---|---|---|---|
+| EV-01 | <Empirical claim> | `artifact:.kxm/logs/telemetry.jsonl@sha256:...` | 2026-09-08 | verified |
+
+| EV-02 | <Model behavior observation> | `run-01928abc` transcript | 2026-09-08 | probable |
+
+## Option Comparison Matrix
+
+| Evaluation Criterion | Weight | Option A (e.g., Native) | Option B (e.g., Wrapper) | Measured Evidence |
+
+|---|---|---|---|---|
+| Verification Pass Rate | High | 84.0% | 40.0% | EV-01 |
+
+| Latency P50 | Medium | 187s | 284s | EV-01 |
+| Cost per Successful Run | High | $0.20 | $1.03 | EV-01 |
+
+| Rework Rate | High | 68% | 100% | EV-01 |
+
+## Findings & Distinctions
+
+### Verified Observations (Backed by Evidence IDs)
+
+- <Direct observation referencing EV-xx>
+
+### Inferences & Working Hypotheses
+
+- <Reasoning or extrapolation; clearly separated from hard evidence>
+
+### Unresolved Unknowns
+
+- <Gaps that remain uncertain or could not be measured>
+
+## Recommendation & Revisit Conditions
+
+- **Recommended Course of Action:** <Specific choice or architectural pattern>
+
+- **Rationale:** <Direct connection between evidence and decision>
+
+- **Revisit When:** <Trigger conditions, such as new vendor model release, 20% price drop, or quota exhaustion>