@kontextmind/kxm 0.7.94 → 0.7.96

package/plugins/kxm/skills/kxm-project-setup/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: kxm-project-setup
-description: Set up KXM in a new or existing Git repository and run a first workflow, especially with Claude Code. The agent runs kxm init, kxm trust diff and check, writes a first workflow, and drives a model-free first run, while the user starts the hub, installs the kxm Claude Code plugin, and reviews and commits .kxm permission changes. Use when asked to install, set up, onboard, initialize, upgrade, or get started with KXM.
+description: Set up KXM in a new or existing Git repository and run a first workflow, especially with Claude Code. The agent runs kxm init, adds a first workflow from the spec-and-plan template, runs kxm trust diff and check, and drives a model-free first run, while the user starts the hub, installs the kxm Claude Code plugin, and reviews and commits .kxm permission changes. Use when asked to install, set up, onboard, initialize, upgrade, or get started with KXM.
 ---
 
 # KXM project setup and first workflow
 
 One guide from a Git repository to a completed first run. Run the agent steps
-in order and stop where a phase says STOP. Everything under Operator steps is
-the user's to run in their own terminal or in Claude Code.
+in order and stop at every STOP. Everything under Operator steps is the user's
+to run in their own terminal or in Claude Code.
 
 - Read `kxm <group> <verb> --help` before a mutation; flags differ per command.
 - Never commit `.kxm` changes yourself. The user's reviewed commit is the trust
@@ -16,7 +16,7 @@ the user's to run in their own terminal or in Claude Code.
 
 ## Agent steps
 
-### Phase 1: initialize
+### Initialize the project
 
 1. `kxm init --dry-run --json` plans without writing. `mode` is `create`,
    `ready`, `repair`, or `legacy`, and `issues` lists anything to fix first.
@@ -31,51 +31,22 @@ the user's to run in their own terminal or in Claude Code.
 3. Add `.kxm/state/` and `.kxm/logs/` to `.gitignore`. `kxm init` writes no
    ignore rules.
 4. `kxm hub view` reads hub health. It exits 1 with `hub health=false` until
-   the user has started a hub; that does not block phases 2 and 3.
+   the user has started a hub; that does not block the first workflow or the
+   first run.
 5. STOP. Ask the user to review `.kxm/` and `.gitignore` and commit them.
    Until they do, `kxm trust diff` fails with `resource_missing` for
    `.kxm/project.yaml` at base `HEAD`.
 
-### Phase 2: write a first workflow
+### Add a first workflow from a template
 
 After the user's commit:
 
-1. Write `.kxm/workflows/first.yaml`, a slim agent-only workflow the Runtime
-   can drive end to end:
-
-   ```yaml
-   schema: kxm.workflow.v1
-   description: Plan, then implement. A first workflow you can drive end to end.
-   coordinator: coordinator
-   limits:
-     maxTransitions: 6
-   steps:
-     - id: plan
-       kind: agent
-       agent: coordinator
-       maxAttempts: 2
-       repositories:
-         control: read
-       on:
-         passed: implement
-         failed:
-           target: $terminal
-           terminalStatus: failed
-     - id: implement
-       kind: agent
-       agent: implementer
-       maxAttempts: 2
-       repositories:
-         control: write
-       on:
-         passed:
-           target: $terminal
-           terminalStatus: completed
-         failed:
-           target: $terminal
-           terminalStatus: failed
-   ```
-
+1. `kxm workflow add first --template spec-and-plan` prints
+   `Added workflow 'first' to local (<root>/.kxm/workflows/first.yaml)`. Add
+   `--dry-run` first to see the path without writing. The template has two
+   steps, `plan` then `review-arch`, both run by the `coordinator` agent with
+   `repositories: control: read`. It writes nothing and runs no test command,
+   and a failed review goes back to `plan` at most twice.
 2. `kxm init` validates it and prints `validated KXM project at <root>`.
 3. `kxm workflow definitions` lists `default` and `first`.
 4. `kxm trust diff`, then `kxm trust check`. Both print
@@ -83,32 +54,37 @@ After the user's commit:
    `1 expansion(s) require explicit reviewed trust action`. `kxm trust check`
    adds `trust check failed: review every expansion above before merging` and
    exits 1.
-5. STOP. Show the user each EXPANSION line, ask them to review it and commit
-   the file themselves, and wait. The `implement` step gets
-   `repositories: control: write`. Never commit `.kxm` changes yourself; the
+5. STOP. Show the user each EXPANSION line, ask them to review the file and
+   commit it themselves, and wait. Never commit `.kxm` changes yourself; the
    reviewed commit is the trust approval.
 
-### Phase 3: drive a model-free first run
+### Drive a model-free first run
 
 After the user's commit:
 
 1. `kxm trust check` prints `no authority-bearing or prose changes` and exits 0.
 2. `kxm run first "<prompt>" --dry-run` prints
-   `run plan: workflow first at sha256:… (no run created)`.
+   `run plan: workflow first at sha256:… (no run created)`. Keep secrets out of
+   the prompt: its full text is kept on disk (`kxm-runs`).
 3. `kxm run first "<prompt>"` prints `run created: run_<id> …` and starts the
    Runtime supervisor.
 4. `kxm runs status <runId>` prints `created`.
 5. `kxm runs drive <runId> --simulated --wait --timeout-ms 60000` prints a
    `kxm.drive-receipt.v1` whose settlement is terminal `completed`, and exits 0.
-   Always pass `--simulated`; without it, drive calls live harnesses.
+   The run moves from `plan` to `review-arch` to `completed`. Always pass
+   `--simulated`; without it, drive calls live harnesses.
 6. `kxm runs status <runId>` prints `completed … (receipt verified)`.
 7. `kxm runs receipt <runId>` and `kxm runs list`. Cancel a stuck run with
    `kxm runs cancel <runId>`.
 8. `kxm runtime stop` when you are done.
 
-To add more workflows, write the YAML by hand as in phase 2, or see
-`kxm workflow add --help`. Validate any new definition with
-`kxm init --dry-run --json`, then repeat the phase 2 trust review.
+To add more workflows, run `kxm workflow add <id> --template <name>` with
+`implement-and-verify` (an `implement` step with write access, then the `test`
+gate) or `dual-critic-review` (`implement`, two reviews, then the `test` gate),
+or write the YAML by hand; see `kxm workflow add --help`. A gate step runs its
+command from `.kxm/gates.yaml` even in a simulated drive. Validate any new
+definition with `kxm init --dry-run --json`, then repeat the trust review and
+the user's commit.
 
 ## Operator steps
 
@@ -119,7 +95,8 @@ or store the admin or project token in the conversation. The user enters
 1. Create a project token and export `KXM_PROJECT_TOKENS` before starting the
    hub. The map must list every project's token, because it replaces the saved
    map rather than merging with it. When a hub already serves other projects,
-   use the merge command in the KXM README.
+   use the merge command in the KXM documentation's Claude Code quick start
+   (docs/start/quickstart-claude-code.md, section "Start the hub").
 2. `kxm hub start` in a second terminal. It generates and persists an admin
    credential in `hub-env.json` under the user state root; that token never
    goes to an agent.
@@ -127,8 +104,8 @@ or store the admin or project token in the conversation. The user enters
 4. In Claude Code, `/plugin marketplace add kontextmind/kxm`,
    `/plugin install kxm@kxm`, then `/plugin configure kxm@kxm` for
    `server_url`, `auth_token`, `agent_name`, `agent_purpose`, and `project`.
-5. Review and commit `.kxm/` and `.gitignore` after phase 1, and every
-   `kxm trust diff` EXPANSION after phase 2, for example
+5. Review and commit `.kxm/` and `.gitignore` after `kxm init`, and every
+   `kxm trust diff` EXPANSION after adding a workflow, for example
    `git add .kxm .gitignore && git commit`.
 6. `kxm session token --clear` when kxm_* tools report `tool_policy_denied`
    for an expired or malformed session token file.

package/plugins/kxm/skills/kxm-projects/SKILL.md

@@ -24,7 +24,7 @@ A project is a mind repo (`repos` row). Pages bind to the caller namespace. Ther
 | `km_projects` | any authorized caller | `{projects[], active, count}` + freshness |
 | `km_project_add` | steward/owner | `name`, optional `path` (local git, indexed now), optional `github_full` |
 | `km_reindex` | authorized | `project` as id or `github_full`. Idempotent reconcile vs HEAD. Returns `{head_sha, indexed_sha, drifted, repaired}` |
-| `km_invite` | steward/owner | `email`, `role` member/steward/owner. Link-only delivery (`accept_url`, expiry). No SMTP in v0.1 |
+| `km_invite` | steward/owner | `email`, `role` member/steward/owner. Link-only delivery (`accept_url`, expiry). No SMTP |
 
 If the tool returns a role error, stop and tell the user they need steward/owner. Do not retry as a different identity.
 

package/plugins/kxm/skills/kxm-protocol/SKILL.md

@@ -15,7 +15,7 @@ metadata:
 
 Canonical docs live in `kontextmind/mind` — `docs/protocol.md`, `docs/session-spine.md`, `docs/consistency-contract.md`, `docs/webhooks.md`, `docs/hosted-auth.md`, `docs/trust-modes.md`, `docs/secret-gates.md`, `docs/authz-matrix.md`, `docs/threat-model.md`.
 
-Protocol status — v0.1 pre-freeze. Additive changes only within a major.
+Protocol status — pre-freeze. Additive changes only within a major.
 
 ## Transports
 

package/plugins/kxm/skills/kxm-routing-improve/SKILL.md

@@ -41,10 +41,12 @@ exits 1 with `improve_source_unreadable`. Simulated drives are excluded, and a
 Runtime attempt is `accepted` only when its run completed without the step
 being re-entered.
 
-- Grouping is by workflow, step, agent role and ask.
-- A coded-repeat candidate needs the same ask decided in at least 2 runs, an
-  accepted share of at least 0.75, and a step that writes no repository. A
-  passing group that misses says `writes-repository` or `ask-not-repeated`.
+- Grouping is by workflow, step, agent role and ask. The ask is a digest of
+  the step's definition, so one step keeps one ask across runs.
+- A coded-repeat candidate needs the same objective decided in at least 2
+  runs (`askRecurrence`), an accepted share of at least 0.75, and a step that
+  writes no repository. A passing group that misses says `writes-repository`
+  or `ask-not-repeated`.
 - Each candidate has kind `gate`, `skill`, or `workflow-step` and status
   `proposed`.
 - Without `--dry-run` it writes `<candidateId>.diff` and `<candidateId>.json`
@@ -77,6 +79,12 @@ Never apply a candidate diff yourself or treat `readyForReview` as approval.
 fixed placeholder figures in this build; never cite them as measured cost or
 quality. Use `kxm routing report` for recorded spend.
 
+`--equivalent-list-cost` loads the price catalog (`.kxm/prices.yaml`, or
+`--prices <path>`) without a freshness check, so an old catalog quotes old
+prices. A missing or invalid catalog leaves the equivalent list cost empty
+(`-` in text). Check the catalog's `date` before citing an equivalent list
+cost.
+
 ```bash
 kxm routing report --json
 kxm routing report --equivalent-list-cost --json
@@ -84,6 +92,6 @@ kxm improve report --dry-run --json
 ```
 
 Do not invent list, get, compare, or top-models verbs, prices, or a ranking
-from missing cost. A stale price catalog must not silently underquote.
-Improvement candidates still need Git-reviewed activation; telemetry cannot
-grant tools or skip a gate.
+from missing cost. Never present an equivalent list cost from an old catalog
+as current. Improvement candidates still need Git-reviewed activation;
+telemetry cannot grant tools or skip a gate.

package/plugins/kxm/skills/kxm-runs/SKILL.md

@@ -14,13 +14,18 @@ the Runtime supervisor. A created run stays `created` until
 
 | Command | Purpose | Options / arguments |
 |---|---|---|
-| `kxm run [workflow] [prompt...]` | Create a run; the prompt is hashed, never stored raw | `--dry-run` (plan only), `--json` |
+| `kxm run [workflow] [prompt...]` | Create a run; the full prompt is kept on disk (see below) | `--dry-run` (plan only), `--json` |
 | `kxm runs drive <runId>` | Drive a run; with `--wait`, exits 0 only for a verified completed settlement | `--simulated`, `--wait`, `--timeout-ms <n>` (default 60000, max 600000), `--json` |
 | `kxm runs status <runId>` | Projected run status plus drive receipt state (open, receipt verified, unsettled, orphaned) | `--json` |
 | `kxm runs receipt <runId>` | Newest drive receipt for a run | `--all`, `--json` |
 | `kxm runs cancel <runId>` | Durably request cancellation | `--json` |
 | `kxm runs list` | Recent runs for the current project | `--json` |
 
+The run record and its events keep only the prompt's hash, but the full
+prompt text is kept in a local `run-events.db.run-prompts.json` file (mode
+`0600`) next to the project's run store under the user state root. Keep
+secrets out of run prompts.
+
 `kxm runs drive <runId> --simulated --wait [--timeout-ms <n>]` executes the run
 with the model-free simulation producer. Always pass `--simulated`; without it,
 drive calls live harnesses. When you are finished, stop the supervisor with
@@ -29,12 +34,13 @@ drive calls live harnesses. When you are finished, stop the supervisor with
 ## Smoke-test the first workflow
 
 Run this only after the user has reviewed and committed
-`.kxm/workflows/first.yaml` (`kxm-project-setup`, phase 2), so
-`kxm trust check` exits 0.
+`.kxm/workflows/first.yaml`, which `kxm-project-setup` adds with
+`kxm workflow add first --template spec-and-plan`, so `kxm trust check`
+exits 0.
 
 ```bash
-kxm run first "add a hello script" --dry-run
-kxm run first "add a hello script" --json
+kxm run first "Plan a hello script" --dry-run
+kxm run first "Plan a hello script" --json
 kxm runs status run_12345
 kxm runs drive run_12345 --simulated --wait --timeout-ms 60000 --json
 kxm runs status run_12345

package/plugins/kxm/skills/kxm-session/SKILL.md

@@ -65,7 +65,7 @@ paste it into a conversation.
 
 | Command | Purpose | Options |
 |---|---|---|
-| `kxm session brief` | Recent hub tasks (workflow runs) and plans (journal `plan` rows) from the local hub store; every form saves the session token | `--status` (status line only), `--json` |
+| `kxm session brief` | Recent tasks (hub workflow runs from the local hub store and Runtime runs under the user state root) and plans (journal `plan` rows); every form saves the session token | `--status` (status line only), `--json` |
 | `kxm session token --status` | Report the active session token | `--json` |
 | `kxm session token --clear` | Delete the session token file | `--json` |
 | `kxm session stop` | Request managed hub and worker shutdown | `--wait-ms <ms>` |

package/plugins/kxm/skills/kxm-tasks/SKILL.md

@@ -1,13 +1,14 @@
 ---
 name: kxm-tasks
-description: Recommend workflows and manage goals and tasks with explicit SCM and tracker boundaries. Use when asked what workflow fits, to plan work as goals and tasks, or to sync with GitHub or Jira. Run a kxm suggest workflow ID only after kxm workflow definitions lists it.
+description: Recommend workflows and manage goals and tasks, recording a GitHub issue or Jira key on a task without contacting either tracker. Use when asked what workflow fits, to plan work as goals and tasks, or to link a task to a GitHub or Jira issue. Run a kxm suggest workflow ID only after kxm workflow definitions lists it.
 ---
 
 # KXM suggest, goals, and tasks
 
-Bind SCM and issue trackers from this repo's conventions. Implemented today:
-GitHub and Jira. An unimplemented tracker fails closed. Do not invent
-`suggest workflows` or extra task verbs.
+A task can record a GitHub issue or Jira key, but no command contacts either
+tracker: `kxm task sync` marks only the local task record synced, and
+`--tracker` is not validated. Do not invent `suggest workflows` or extra task
+verbs.
 
 ## Commands
 
@@ -20,7 +21,7 @@ GitHub and Jira. An unimplemented tracker fails closed. Do not invent
 | `kxm task list` | List project tasks | `--goal`, `--status todo\|in_progress\|blocked\|in_review\|done` |
 | `kxm task get <taskId>` | Task details and linked workflow status | `--json` |
 | `kxm task run <taskId>` | Launch a workflow run driven by this task | `--json` |
-| `kxm task sync <taskId>` | Sync status and evidence with the linked issue board | `--json` |
+| `kxm task sync <taskId>` | Mark the local task record synced; contacts no tracker | `--json` |
 
 ```bash
 kxm suggest "implement trusted roster policy brakes" --json
@@ -41,5 +42,6 @@ one with the user (`kxm-project-setup`).
 
 `--issue` on `kxm task create` is a tracker issue number or Jira key, not a
 credential. In this build `kxm task sync` marks only the local task record
-synced; it does not contact GitHub or Jira. Do not silently use GitHub when
-the operator picked an unimplemented tracker.
+synced; it does not contact GitHub or Jira. `kxm task create` accepts any
+`--tracker` value and records it unchecked, so pass only `github` or `jira`,
+and never report a task as synced with a tracker.

package/plugins/kxm/skills/kxm-workflow/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: kxm-workflow
-description: Work inside a durable KXM workflow run. Read it, record plan, decision, contradiction, error and lesson journal entries, pass stage checkpoints with keyed evidence and peer evidence refs, wait for signed CI or review callbacks, start webhook workflows, and export retrospectives (kxm_workflow_get, kxm_workflow_record, kxm_workflow_checkpoint, kxm_workflow_wait). Use when a workflow run ID is involved or the user asks to checkpoint, gate, or wait on CI.
+description: Work inside a durable KXM workflow run. Read it, record journal entries in any of the ten categories (plan, decision, contradiction, error, lesson, observation, hypothesis, experiment, state-change, skill-candidate) bound to a stageId, pass stage checkpoints with keyed evidence and peer evidence refs, wait for signed CI or review callbacks, start webhook workflows, and export retrospectives (kxm_workflow_get, kxm_workflow_record, kxm_workflow_checkpoint, kxm_workflow_wait). Use when a workflow run ID is involved or the user asks to checkpoint, gate, or wait on CI.
 ---
 
 # KXM workflow and gates
@@ -31,10 +31,18 @@ with `kxm run` are Runtime runs; inspect them with `kxm runs list`
 | `kxm workflow start [definitionId]` | POST a signed workflow-start webhook | `--payload <json\|@file>`, `--delivery-id`, `--event` |
 | `kxm workflow export <runId>` | Export a proposed retrospective | `--input`, `--out-dir` |
 | `kxm workflow definitions` | List project and global workflow definitions | `--scope all\|global\|local` |
-| `kxm workflow add [workflowId]` | Add a definition | `--file`, `--description`, `--scope`, `--overwrite`, `--pick` |
+| `kxm workflow add [workflowId]` | Add a definition | `--template spec-and-plan\|implement-and-verify\|dual-critic-review`, `--file`, `--description`, `--scope`, `--overwrite`, `--pick` |
 | `kxm workflow remove [workflowId]` | Remove a definition | `--scope`, `--pick` |
 | `kxm workflow modify [workflowId]` | Modify a definition | `--description`, `--scope`, `--pick` |
 
+`kxm workflow add <id> --template <spec-and-plan|implement-and-verify|dual-critic-review>`
+writes a complete definition to `.kxm/workflows/<id>.yaml` (the default local
+scope); the file name is the workflow ID. `spec-and-plan` only reads (`plan`,
+then `review-arch`). `implement-and-verify` and `dual-critic-review` add an
+`implement` step with write access and the `test` gate. Validate with
+`kxm init`, then have the user review the `kxm trust diff` expansion and
+commit it (`kxm-project-setup`).
+
 ```bash
 kxm workflow get run_12345 --json
 kxm workflow checkpoint run_12345 implement passed "Implementation complete" --evidence '{"tests":"npm test passed"}' --json

package/plugins/kxm/src/cli/system.ts

@@ -853,7 +853,7 @@ export async function maybeOfferGuideSetup(runtime: Runtime): Promise<void> {
     runtime.io.stdout(`skipped; set ${GUIDE_SETUP_OPT_OUT_ENV}=1 to suppress this offer, or re-run on a fresh project\n`);
     return;
   }
-  const lines = ["", "Workflow-guide software-engineering workflows (docs/workflow-guide.md):"];
+  const lines = ["", "Workflow-guide software-engineering workflows (docs/reference/workflow-catalog.md):"];
   GUIDE_WORKFLOWS.forEach((workflow, index) => {
     lines.push(`  ${index + 1}) ${workflow.slug.padEnd(32)} ${workflow.summary}`);
   });

package/plugins/kxm/src/cli.ts

@@ -402,7 +402,7 @@ function createProgram(ctx: CliContext, result: { code: number }): Command {
       });
     });
 
-  addGlobalOptions(program.command("backup").description("Create a verified SQLite backup of all stores with a hashed manifest"))
+  addGlobalOptions(program.command("backup").description("Create a verified SQLite backup of the project hub store with a hashed manifest (Runtime stores under the user state root are not included)"))
     .option("--out <dir>", "Directory to write backup and manifest")
     .action(async function backupAction(this: Command, options: { out?: string }) {
       result.code = await cmdBackup(runtimeFrom(ctx, this), options);
@@ -415,7 +415,7 @@ function createProgram(ctx: CliContext, result: { code: number }): Command {
 
   addGlobalOptions(program.command("run").description("Create a KXM run (offline-first; kxm runs drive <runId> --simulated executes it model-free)")
     .argument("[workflow]", "Workflow id to run")
-    .argument("[prompt...]", "Run prompt (hashed, never stored raw)")
+    .argument("[prompt...]", "Run prompt (events keep its hash; the full text is kept in a local 0600 sidecar file)")
     .action(async function runAction(this: Command, workflow: string | undefined, promptParts: string[]) {
       result.code = await cmdKxmRun(runtimeFrom(ctx, this), workflow, promptParts);
     }));
@@ -426,7 +426,7 @@ function createProgram(ctx: CliContext, result: { code: number }): Command {
     .action(async function runStatusAction(this: Command, runId: string) {
       result.code = await cmdKxmRunStatus(runtimeFrom(ctx, this), runId);
     });
-  addGlobalOptions(runCmd.command("drive").description("Drive a run with an explicit model-free simulation"))
+  addGlobalOptions(runCmd.command("drive").description("Drive a run with live harness calls, or with the model-free simulation when --simulated is passed"))
     .argument("<runId>", "Run id")
     .option("--simulated", "Use the model-free simulation producer")
     .option("--wait", "Wait until a drive receipt is recorded; exits 0 only for a VERIFIED COMPLETED settlement")

package/plugins/kxm/src/init-guide-setup.ts

@@ -1,7 +1,7 @@
 /**
  * Interactive post-init setup for workflow-guide agents and workflows.
  *
- * Source of truth: `docs/workflow-guide.md`. The catalog below transcribes the
+ * Source of truth: `docs/reference/workflow-catalog.md`. The catalog below transcribes the
  * software-engineering area (workflows, stages, role slugs, and the guide's
  * ordered candidate lists). Guide candidates are dated research; each role's
  * first candidate whose harness is installed AND authenticated wins. No

package/plugins/kxm/src/mcp-server.ts

@@ -11,7 +11,7 @@ import { deliverInboxNotification } from "./inbox.ts";
 import type { HubEvent, MessageRecord } from "./protocol.ts";
 import { sessionTokenFixHint } from "./session-token-hint.ts";
 
-const VERSION = "0.7.94";
+const VERSION = "0.7.96";
 const CONFIGURE_PLUGIN = "/plugin configure kxm@kxm";
 const inbox = new Map<string, MessageRecord>();
 const notifiedInbox = new Set<string>();

package/plugins/kxm/src/modes.ts

@@ -99,7 +99,7 @@ export const DEFAULT_MODES_CONFIG: ModesConfig = Object.freeze({
     browser: {
       description: "Web application exploration, screenshotting, and UI testing",
       baseTools: ["read", "bash"],
-      contextFiles: ["docs/browser-automation.md"],
+      contextFiles: ["docs/guides/browser-automation.md"],
       thinkingLevel: "medium" as const,
       model: "grok/grok-4.6",
     },

package/schemas/README.md

@@ -28,7 +28,7 @@ Runtime-local records, and JSON events/results for the planned KXM contract.
 one validation layer; cross-file references, state-machine semantics,
 permission diffs, model diversity, path portability, and snapshot reproduction
 are deterministic semantic checks described in
-[`docs/contracts/validation.md`](../../docs/contracts/validation.md).
+[`docs/contracts/validation.md`](../docs/contracts/validation.md).
 
 Unknown fields fail closed. A new field requires a reviewed schema revision;
 do not add generic metadata escape hatches to event or synchronization payloads.