@kontextmind/kxm 0.7.121 → 0.7.122

package/.claude-plugin/marketplace.json

@@ -11,7 +11,7 @@
       "name": "kxm",
       "source": "./plugins/kxm",
       "description": "Durable workflows, peer agents, and kxm tui",
-      "version": "0.7.121",
+      "version": "0.7.122",
       "category": "development",
       "tags": ["kxm", "multi-agent", "workflows", "mcp"]
     }

package/CHANGELOG.md

@@ -14,6 +14,13 @@ All notable user-facing changes are documented here. The project follows [Semant
   A required review is reported. The `land` workflow in `.kxm/workflows/land.yaml`
   runs the same gates and may be refused until gate-only workflows are supported.
   See the [CLI reference](docs/reference/cli-reference.md#kxm-land).
+- **`kxm assign` is the entry to the developer assignment runner.**
+  `run`, `witness`, `plan-current`, `attribute`, `observe-cost`, `accept` and
+  `change-report` spawn `scripts/assignment-run.mjs` with the same flags as the
+  just recipes. The runner still performs every check and writes every file.
+  The just recipes stay until one real unit has been accepted through
+  `kxm assign`. See the
+  [CLI reference](docs/reference/cli-reference.md#kxm-assign).
 
 - **`kxm lane` keeps one git worktree per unit beside the control checkout.**
   `create`, `list`, `status`, `drop` and `run` store a 0600 record in

package/docs/contributing/assignment-runner.md

@@ -19,9 +19,9 @@ a KXM product feature.
   `origin/main`. The runner loads `.kxm/roster.yaml` only from there.
 - A separate worktree for the writer. `kxm lane create <unit>` creates one from
   `origin/main`.
-- [`just`](https://github.com/casey/just), plus the harness CLIs the roster
-  admits, installed and logged in. `node scripts/kxm.mjs harness list` shows
-  which are.
+- The harness CLIs the roster admits, installed and logged in.
+  `node scripts/kxm.mjs harness list` shows which are. The loop below is
+  `kxm assign`. `just` still runs the transport recipes.
 - A task directory whose final path segment equals the task ID. Every path you
   pass to the runner must be absolute.
 
@@ -80,10 +80,12 @@ Use this slim loop for daily work and for docs. The 13-step `fix` workflow in
 `examples/project/` is a product fixture, not the developer loop.
 
 > [!NOTE]
-> These recipes never load a `.env` file from the working directory. An
+> `kxm assign` never loads a `.env` file from the working directory. An
 > unreviewed file could otherwise set `NODE_OPTIONS` and run code before the
-> runner validates anything. To use one, pass it explicitly:
-> `just --dotenv-path /abs/.env assign /abs/manifest.json`.
+> runner validates anything. The process environment is passed through as it
+> is. Export any variable you need before the command.
+
+The seven `just` assignment recipes remain available and will be removed after one real unit has been accepted through `kxm assign`; until then both forms are equivalent because both call `scripts/assignment-run.mjs` unchanged.
 
 ### 1. Pin the current plan
 
@@ -91,7 +93,7 @@ Every writer assignment binds to the current plan. Stamp the pointer, or advance
 it with a generation check:
 
 ```bash
-just plan-current /abs/task-dir /abs/plan.md <sha256> <base-commit> <expected-generation>
+kxm assign plan-current --task-dir /abs/task-dir --plan /abs/plan.md --sha256 <sha256> --base-commit <base-commit> --expected-generation <expected-generation>
 ```
 
 The runner writes `plan-current.json` (`kxm.plan-pointer.v1`) in the task
@@ -137,7 +139,7 @@ Optional keys are `rework_of`, `timeout_ms` and `max_turns`. Each `inputs`
 entry is `{ "path", "sha256" }`, and the runner checks the hash. Dispatch it:
 
 ```bash
-just assign /abs/tasks/fix-improve-sources/asg-writer-1.json
+kxm assign run --manifest /abs/tasks/fix-improve-sources/asg-writer-1.json
 ```
 
 The runner validates the manifest, the route and the base, writes
@@ -151,7 +153,7 @@ generated files, then run the witness:
 
 ```bash
 git -C /abs/kxm-fix-improve-sources add -A
-just witness /abs/tasks/fix-improve-sources/asg-writer-1
+kxm assign witness --record-dir /abs/tasks/fix-improve-sources/asg-writer-1
 ```
 
 The witness refuses with `dirty_baseline` while anything is unstaged or
@@ -185,17 +187,18 @@ witnessed tree: either the staged index (`base.kind: "staged"` with its
 Commit the exact witnessed tree, then bind the commit and both `PASS` records:
 
 ```bash
-just accept /abs/tasks/fix-improve-sources <commit-sha> \
-  /abs/tasks/fix-improve-sources/asg-writer-1 \
-  /abs/tasks/fix-improve-sources/asg-review-arch-1 \
-  /abs/tasks/fix-improve-sources/asg-review-cli-1
+kxm assign accept \
+  --task-dir /abs/tasks/fix-improve-sources \
+  --commit <commit-sha> \
+  --record-dir /abs/tasks/fix-improve-sources/asg-writer-1 \
+  --critic /abs/tasks/fix-improve-sources/asg-review-arch-1 \
+  --critic /abs/tasks/fix-improve-sources/asg-review-cli-1
 ```
 
-To record an observed pull request or CI run, call the script directly, since
-the recipe does not pass those flags:
+To record an observed pull request or CI run, pass the same flags:
 
 ```bash
-node scripts/assignment-run.mjs accept \
+kxm assign accept \
   --task-dir /abs/tasks/fix-improve-sources \
   --commit <commit-sha> \
   --record-dir /abs/tasks/fix-improve-sources/asg-writer-1 \
@@ -205,7 +208,7 @@ node scripts/assignment-run.mjs accept \
   --observed-ci <ci-id>
 ```
 
-`accept` prints JSON and takes no `--json` flag. It checks, in order, that:
+`accept` prints JSON and takes no `--json` flag, and `kxm assign --json` is not passed through. The runner checks, in order, that:
 
 1. the trusted roster policy loads and validates, before anything is written;
 2. the commit exists and its tree equals the witnessed tree;
@@ -226,7 +229,7 @@ You decide, then dispatch:
 1. Write a new manifest with `"kind": "repair"` and `"rework_of"` set to the
    assignment ID it reworks. The runner checks that the earlier assignment has a
    `completion.json` in the same task directory, with the same task ID.
-2. Dispatch it with `just assign`, then run `just witness` on the new record.
+2. Dispatch it with `kxm assign run`, then run `kxm assign witness` on the new record.
 3. Dispatch fresh critics against the new tree, and accept.
 
 A `BLOCK` stops acceptance only for the tree it judged. A repair that changes
@@ -266,7 +269,7 @@ Record friction or a model regression as a private note, without touching any
 completion:
 
 ```bash
-just attribute /abs/task-dir /abs/record-dir <class> /abs/note.txt
+kxm assign attribute --task-dir /abs/task-dir --record-dir /abs/record-dir --class <class> --explanation-file /abs/note.txt
 ```
 
 The class is `orchestration`, `model`, `environment` or `unclassified`. Each
@@ -277,7 +280,7 @@ Import a cost observation for a run whose native telemetry was not captured,
 such as a subscription session:
 
 ```bash
-just observe-cost /abs/task-dir /abs/observation.json
+kxm assign observe-cost --task-dir /abs/task-dir --input /abs/observation.json
 ```
 
 The record (`kxm.cost-observation.v1`) is cost-only. It cannot mint witness
@@ -286,7 +289,7 @@ proof or authorize acceptance.
 Summarize a task's attempts, rework and spend:
 
 ```bash
-just change-report /abs/task-dir
+kxm assign change-report --task-dir /abs/task-dir
 ```
 
 The report (`kxm.change-report.v1`) keeps provider-reported spend, list-price
@@ -356,7 +359,7 @@ ones:
 |---|---|---|
 | `route_invalid` | Route not in the role's lineup, permission above its ceiling, or the roster policy cannot load | Run from a clean control checkout on `origin/main`; check the lineup |
 | `base_invalid` | `base.commit` is not `HEAD`, the tree is dirty, or a writer targets a staged index | Commit or stash elsewhere; writers need a clean base |
-| `plan_ref_invalid` | The plan hash or path does not match `plan-current.json` | Advance the pointer with `just plan-current` |
+| `plan_ref_invalid` | The plan hash or path does not match `plan-current.json` | Advance the pointer with `kxm assign plan-current` |
 | `rework_invalid` | `rework_of` names no completed assignment in this task | Point it at an existing record directory's assignment ID |
 | `witness_failed` | The fixed gate exited non-zero | Fix the failures and run a repair |
 | `dirty_baseline` | Unstaged or untracked changes when the witness starts | Stage the candidate with `git add -A`, then re-witness |

package/docs/guides/agent-skills.md

@@ -58,7 +58,7 @@ Every top-level `kxm` command is owned by exactly one skill. A skill can own sev
 | `kxm-peer` | `peer` | Delegate to, fan out to, await and answer other agents |
 | `kxm-workflow` | `workflow`, `gate` | Record journal entries, pass checkpoints and wait on signed callbacks |
 | `kxm-definitions` | `role` | Inspect or edit roles, role hosts and model rosters without granting writer admission |
-| `kxm-runs` | `run`, `runs`, `lane` | Create, drive, inspect and cancel runs, manage worktree lanes, or smoke-test a workflow model-free |
+| `kxm-runs` | `run`, `runs`, `lane`, `assign` | Create, drive, inspect and cancel runs, manage worktree lanes, smoke-test a workflow, or call the assignment runner |
 | `kxm-context-memory` | `context`, `memory`, `explain` | Recall what the project knows, explain a context footprint, record memory candidates |
 | `kxm-skill-lifecycle` | `skills` | Turn a repeated practice into a governed skill candidate |
 | `kxm-routing-improve` | `routing`, `improve` | Find what KXM learned and what repeats, and read recorded route spend |

package/docs/reference/cli-reference.md

@@ -14,7 +14,7 @@ Output shown under examples was captured from a source checkout, inside a throwa
 - Setup: [`init`](#kxm-init), [`config`](#kxm-config), [`completion`](#kxm-completion), [`trust`](#kxm-trust)
 - Hub and sessions: [`hub`](#kxm-hub-view), [`session`](#kxm-session), [`dash`](#kxm-dash), [`studio`](#kxm-studio)
 - Harnesses, models, and roles: [`harness`](#kxm-harness), [`auth`](#kxm-auth), [`update`](#kxm-update), [`models`](#kxm-models), [`routes`](#kxm-routes), [`role`](#kxm-role)
-- Running work: [`lane`](#kxm-lane), [`run`](#kxm-run), [`runs`](#kxm-runs), [`runtime`](#kxm-runtime), [`agent`](#kxm-agent), [`workflow`](#kxm-workflow), [`gate`](#kxm-gate), [`peer`](#kxm-peer), [`task`](#kxm-task), [`goal`](#kxm-goal), [`suggest`](#kxm-suggest), [`explain`](#kxm-explain)
+- Running work: [`lane`](#kxm-lane), [`assign`](#kxm-assign), [`run`](#kxm-run), [`runs`](#kxm-runs), [`runtime`](#kxm-runtime), [`agent`](#kxm-agent), [`workflow`](#kxm-workflow), [`gate`](#kxm-gate), [`peer`](#kxm-peer), [`task`](#kxm-task), [`goal`](#kxm-goal), [`suggest`](#kxm-suggest), [`explain`](#kxm-explain)
 - Context and learning: [`context`](#kxm-context), [`memory`](#kxm-memory), [`skills`](#kxm-skills), [`improve`](#kxm-improve), [`routing`](#kxm-routing), [`prices`](#kxm-prices)
 - Operations: [`backup`](#kxm-backup), [`restore`](#kxm-restore), [`tenant`](#kxm-tenant), [`ssh`](#kxm-ssh), [`help`](#kxm-help)
 - [Known behavior gaps](#known-behavior-gaps)
@@ -159,6 +159,7 @@ Exit 2 covers an unknown command or option, a missing argument or required optio
 | Create and drive a run | [`kxm run`](#kxm-run), [`kxm runs drive`](#kxm-runs-drive), [`kxm runtime status`](#kxm-runtime-status) |
 | Work in an isolated checkout | [`kxm lane`](#kxm-lane), [`kxm run --lane`](#kxm-run) |
 | Land the current branch | [`kxm land`](#kxm-land) |
+| Delegate and accept a developer assignment | [`kxm assign`](#kxm-assign) |
 | Inspect runs | [`kxm runs list`](#kxm-runs-list), [`kxm runs status`](#kxm-runs-status), [`kxm runs receipt`](#kxm-runs-receipt), [`kxm tenant status`](#kxm-tenant-status), [`kxm workflow list`](#kxm-workflow-list) |
 | Message peers | [`kxm peer list`](#kxm-peer-list), [`kxm peer send`](#kxm-peer-send), [`kxm peer await`](#kxm-peer-await), [`kxm peer fanout`](#kxm-peer-fanout) |
 | Operate gates and evidence | [`kxm gate validate`](#kxm-gate-validate), [`kxm gate artifacts-exist`](#kxm-gate-artifacts-exist), [`kxm gate signal`](#kxm-gate-signal), [`kxm workflow checkpoint`](#kxm-workflow-checkpoint) |
@@ -1470,6 +1471,97 @@ Outside a KXM project the command refuses `project_required` (exit 1). Unknown a
 
 Refusals (exit 1): `project_required`, `land_dirty_tree`, `land_verify_failed`, `land_docs_failed`, `land_push_rejected`, `land_pr_body_missing`, `land_conflict_manual`, `land_blocked`, `land_merge_failed`, `land_release_failed`, `land_publish_timeout`, `land_milestone_failed`.
 
+## `kxm assign`
+
+`kxm assign` is the entry to this repository's developer assignment runner. Each verb spawns `node scripts/assignment-run.mjs <verb> ...` from the project root with that argument list, `stdio: "inherit"`, and the process environment unchanged. The command returns the child's exit code. It does not load a `.env` file, resolve paths, or repeat any runner check. Every validation rule, refusal code, and file the runner writes stays in [`scripts/assignment-run.mjs`](../../scripts/assignment-run.mjs). The loop, the records, and those codes are documented in [Assignment runner](../contributing/assignment-runner.md).
+
+The command does not start the hub or the Runtime supervisor. It writes nothing itself. `--dry-run` prints the argv that would run and exits 0 without spawning. `--json` formats this command's own refusals and that dry-run plan. The runner's usage text documents no `--json` flag, and `accept` already prints JSON, so `--json` is not forwarded.
+
+Outside a KXM project the command exits 1 with `project_required`. A project that has no `scripts/assignment-run.mjs` exits 1 with `assign_runner_missing`. A missing required flag is a usage error and exits 2. If `node` cannot be started, the command exits 1 with `assign_spawn_failed`.
+
+```text
+kxm assign run --manifest <path>
+kxm assign witness --record-dir <path>
+kxm assign plan-current --task-dir <path> --plan <path> --sha256 <hex> --base-commit <sha> --expected-generation <n>
+kxm assign attribute --task-dir <path> --record-dir <path> --class <class> --explanation-file <path>
+kxm assign observe-cost --task-dir <path> --input <path>
+kxm assign accept --task-dir <path> --commit <sha> --record-dir <path> --critic <path> --critic <path> [--observed-pr <id>] [--observed-ci <id>]
+kxm assign change-report --task-dir <path>
+```
+
+```bash
+kxm assign run --manifest /abs/tasks/fix-improve-sources/asg-writer-1.json
+```
+
+### `kxm assign run`
+
+Dispatches one closed manifest. The runner validates the route, the base, and the plan pointer, then writes the assignment record.
+
+| Option | Argument | Description |
+|---|---|---|
+| `--manifest` | `<path>` | Absolute path to the `kxm.assignment.v1` manifest. Passed through as given |
+
+### `kxm assign witness`
+
+Runs the fixed witness named in the manifest against the staged tree.
+
+| Option | Argument | Description |
+|---|---|---|
+| `--record-dir` | `<path>` | Absolute path to the assignment record directory |
+
+### `kxm assign plan-current`
+
+Stamps or advances `plan-current.json` in the task directory.
+
+| Option | Argument | Description |
+|---|---|---|
+| `--task-dir` | `<path>` | Absolute path to the task directory |
+| `--plan` | `<path>` | Absolute path to the plan file |
+| `--sha256` | `<hex>` | SHA-256 the runner expects for that file |
+| `--base-commit` | `<sha>` | Commit the pointer records |
+| `--expected-generation` | `<n>` | Generation the pointer must currently have |
+
+### `kxm assign attribute`
+
+Attaches one private note under the record's `attribution/` directory. The note is not proof.
+
+| Option | Argument | Description |
+|---|---|---|
+| `--task-dir` | `<path>` | Absolute path to the task directory |
+| `--record-dir` | `<path>` | Absolute path to the assignment record directory |
+| `--class` | `<class>` | `orchestration`, `model`, `environment`, or `unclassified` |
+| `--explanation-file` | `<path>` | Absolute path to the note file |
+
+### `kxm assign observe-cost`
+
+Imports one cost observation. The record is cost-only and cannot authorize acceptance.
+
+| Option | Argument | Description |
+|---|---|---|
+| `--task-dir` | `<path>` | Absolute path to the task directory |
+| `--input` | `<path>` | Absolute path to the observation file |
+
+### `kxm assign accept`
+
+Binds the witnessed commit and two critic records. Optional observation ids are forwarded when present. `accept` prints JSON and takes no `--json` flag.
+
+| Option | Argument | Description |
+|---|---|---|
+| `--task-dir` | `<path>` | Absolute path to the task directory |
+| `--commit` | `<sha>` | Commit whose tree must equal the witnessed tree |
+| `--record-dir` | `<path>` | Absolute path to the writer record directory |
+| `--critic` | `<path>` | Absolute path to a critic record directory. Pass it twice |
+| `--observed-pr` | `<id>` | Observed pull request id. Omitted unless set |
+| `--observed-ci` | `<id>` | Observed CI run id. Omitted unless set |
+
+### `kxm assign change-report`
+
+Prints the task's attempts, rework, and spend. The runner keeps provider-reported, list, unmetered, and unknown cost apart.
+
+| Option | Argument | Description |
+|---|---|---|
+| `--task-dir` | `<path>` | Absolute path to the task directory |
+
 ## `kxm run`
 
 ```text

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kontextmind/kxm",
-  "version": "0.7.121",
+  "version": "0.7.122",
   "description": "KXM local-first multi-agent orchestration and operator dashboard",
   "type": "module",
   "author": "KontextMind",

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.121",
+  "version": "0.7.122",
   "description": "Headless multi-agent orchestration, durable workflows, and a live operator dashboard for Pi and Claude Code",
   "author": {
     "name": "KontextMind",