@kontextmind/kxm 0.7.119 → 0.7.121

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.119",
+      "version": "0.7.121",
       "category": "development",
       "tags": ["kxm", "multi-agent", "workflows", "mcp"]
     }

package/.kxm/gates.yaml

@@ -6,3 +6,27 @@ gates:
       - npm
       - test
     timeoutMs: 3600000
+  land-verify:
+    kind: command
+    argv: [node, scripts/pr-land.mjs, --stage, verify, --json]
+    timeoutMs: 3900000
+  land-docs:
+    kind: command
+    argv: [node, scripts/pr-land.mjs, --stage, docs, --json]
+    timeoutMs: 900000
+  land-rebase:
+    kind: command
+    argv: [node, scripts/pr-land.mjs, --stage, rebase, --json]
+    timeoutMs: 18600000
+  land-merge:
+    kind: command
+    argv: [node, scripts/pr-land.mjs, --stage, merge, --json]
+    timeoutMs: 1500000
+  land-release:
+    kind: command
+    argv: [node, scripts/pr-land.mjs, --stage, release, --json]
+    timeoutMs: 3300000
+  land-milestone:
+    kind: command
+    argv: [node, scripts/pr-land.mjs, --stage, milestone, --json]
+    timeoutMs: 120000

package/.kxm/workflows/land.yaml

@@ -0,0 +1,95 @@
+# This workflow may be refused by `kxm run` prerequisites until gate-only
+# workflows are supported. Record the dry run with
+# `kxm run land --dry-run --json`.
+schema: kxm.workflow.v1
+description: Land the current branch through verify, docs, rebase, merge, release, and milestone gates.
+coordinator: coordinator
+limits:
+  maxTransitions: 24
+steps:
+  - id: land-verify
+    kind: gate
+    gate: land-verify
+    expect: pass
+    repositories:
+      control: write
+    on:
+      passed: land-docs
+      failed:
+        target: $terminal
+        terminalStatus: failed
+      implementation-failure:
+        target: $terminal
+        terminalStatus: failed
+  - id: land-docs
+    kind: gate
+    gate: land-docs
+    expect: pass
+    repositories:
+      control: write
+    on:
+      passed: land-rebase
+      failed:
+        target: $terminal
+        terminalStatus: failed
+      implementation-failure:
+        target: $terminal
+        terminalStatus: failed
+  - id: land-rebase
+    kind: gate
+    gate: land-rebase
+    expect: pass
+    repositories:
+      control: write
+    on:
+      passed: land-merge
+      failed:
+        target: $terminal
+        terminalStatus: failed
+      implementation-failure:
+        target: $terminal
+        terminalStatus: failed
+  - id: land-merge
+    kind: gate
+    gate: land-merge
+    expect: pass
+    repositories:
+      control: write
+    on:
+      passed: land-release
+      failed:
+        target: land-rebase
+        maxTransitions: 3
+      implementation-failure:
+        target: land-rebase
+        maxTransitions: 3
+  - id: land-release
+    kind: gate
+    gate: land-release
+    expect: pass
+    repositories:
+      control: write
+    on:
+      passed: land-milestone
+      failed:
+        target: $terminal
+        terminalStatus: failed
+      implementation-failure:
+        target: $terminal
+        terminalStatus: failed
+  - id: land-milestone
+    kind: gate
+    gate: land-milestone
+    expect: pass
+    repositories:
+      control: write
+    on:
+      passed:
+        target: $terminal
+        terminalStatus: completed
+      failed:
+        target: $terminal
+        terminalStatus: failed
+      implementation-failure:
+        target: $terminal
+        terminalStatus: failed

package/CHANGELOG.md

@@ -6,6 +6,28 @@ All notable user-facing changes are documented here. The project follows [Semant
 
 ### Added
 
+- **`kxm land` verifies, regenerates docs, and squash-merges the current branch.**
+  The stages are `verify`, `docs`, `push`, `pr`, `rebase`, `unblock`, `merge`,
+  `release`, and `milestone`. `npm run verify` is the first stage and is not
+  replaced. Rebase resolves only the dist rebuild, the CHANGELOG Unreleased
+  union, and the tracker "Landed in this tree" union, for at most five rounds.
+  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 lane` keeps one git worktree per unit beside the control checkout.**
+  `create`, `list`, `status`, `drop` and `run` store a 0600 record in
+  `.kxm/state/lanes.json` keyed by the resolved base sha, and `drop` never
+  deletes the branch. `kxm run --brief <file>` and `--lane <unit>` start that
+  work, and `--lane` is also accepted by `kxm runs status`, `drive`, `receipt`
+  and `cancel`. The `just worktree` and `just worktree-drop` recipes now call
+  those verbs. The refusals a user can see are `lane_exists`, `lane_missing`,
+  `lane_base_unresolved`, `lane_dirty`, `lane_run_open`, `brief_unreadable` and
+  `brief_and_prompt`. A live writer step through `kxm lane run` is still
+  bounded by the Runtime's 120 second one-shot timeout until the configurable
+  limit lands. See the
+  [CLI reference](docs/reference/cli-reference.md#kxm-lane).
+
 - **Claude-only workflow recommendations now fail honestly when execution is unavailable.**
   `suggest` honors explicit harness constraints, uses flat installable IDs and verified
   capability-appropriate routes, refuses unchecked existing definitions, and never substitutes a
@@ -337,6 +359,13 @@ All notable user-facing changes are documented here. The project follows [Semant
   persisting a projection write, so a read cannot mutate run state or surface a
   false `run_projection_divergent`.
 
+### Removed
+
+- **`.kxm/template-provenance.yaml` was removed from this project, a repository
+  change rather than a product change,** because the installed kxm no longer
+  recognizes its recorded revision and a project without the file validates as
+  ready.
+
 ### Fixed
 
 - **A local `kxm workflow add` writes only what the project loader accepts, where it reads

package/docs/contributing/assignment-runner.md

@@ -17,7 +17,7 @@ a KXM product feature.
 
 - A clean control checkout of this repository whose `HEAD` is an ancestor of
   `origin/main`. The runner loads `.kxm/roster.yaml` only from there.
-- A separate worktree for the writer. `just worktree <unit>` creates one from
+- 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
@@ -380,6 +380,37 @@ No test runs `run`, `witness` or `accept` end to end. Treat changes to
 `scripts/assignment-run.mjs` as high risk, and check them by running a real
 unit through the loop.
 
+## Landing
+
+`kxm land` is the entry point after a candidate is ready to merge. It runs
+`npm run verify` first. That gate is not replaced. On a green verify it
+regenerates documentation (`docs`), then runs the GitHub stages: `push`,
+`pr`, `rebase`, `unblock`, `merge`, `release`, and `milestone`.
+
+| Stage | Role |
+|---|---|
+| `verify` | Clean tree, then `npm run verify`, skipped when a receipt for this tree is younger than 30 minutes |
+| `docs` | Regenerate the roadmap after verify and before the merge. Absent generator: pass, skipped |
+| `push` | `git push -u origin <branch>`, with `--force-with-lease` after a rebase in this run |
+| `pr` | Reuse the open pull request, or create one from `--body-file` |
+| `rebase` | Up to five rounds onto `origin/main`. Only the dist rebuild, the CHANGELOG Unreleased union, and the tracker "Landed in this tree" union are resolved automatically |
+| `unblock` | Rerun one failed check. A required review is reported |
+| `merge` | Squash only. Poll until `MERGED`, up to 20 minutes |
+| `release` | Auto-release tag, Release workflow, then npm for 10 minutes. Prints `PUBLISHED <version>` |
+| `milestone` | Report `deep_review_required` when a phase completes or the body has a `Milestone:` line. Does not run the review |
+
+Refusals (exit 1): `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`. Usage errors exit 2.
+`--stage <name>` runs one stage. `--dry-run` prints the plan and does not mutate.
+
+The same stages are command gates in `.kxm/gates.yaml` (`land-verify`,
+`land-docs`, `land-rebase`, `land-merge`, `land-release`, `land-milestone`)
+and steps in `.kxm/workflows/land.yaml`. `kxm run land` may be refused until
+gate-only workflows are supported. See the
+[CLI reference](../reference/cli-reference.md#kxm-land).
+
 ## Related
 
 - [Develop KXM](development.md): the commit gate the witness runs

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` | Create, drive, inspect and cancel runs, or smoke-test a workflow model-free |
+| `kxm-runs` | `run`, `runs`, `lane` | Create, drive, inspect and cancel runs, manage worktree lanes, or smoke-test a workflow model-free |
 | `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: [`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), [`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)
@@ -143,7 +143,7 @@ Exit 2 covers an unknown command or option, a missing argument or required optio
 |---|---|---|
 | Project files under `<project>/.kxm/` (reviewed in Git) | `project.yaml`, `agents/`, `workflows/`, `gates.yaml`, `repo/`, `template-provenance.yaml`, `routes.yaml`, `models/inventory.yaml`, `roles/`, `role-hosts.yaml`, `modes.yaml`, `prices.yaml` | `init`, `trust`, `run`, `models`, `routes`, `role`, `workflow definitions\|add\|remove\|modify`, `explain`, `studio` |
 | Local project records under `<project>/.kxm/` | `config.yaml` (project scope), `goals/`, `tasks/`, `memory/`, `skills/`, `candidates/`, `backups/`, `run/ssh-sockets/` | `config`, `goal`, `task`, `memory`, `skills`, `improve`, `backup`, `ssh` |
-| Workspace directories (`.kxm/state`, `.kxm/logs`, `.kxm/assets`, `.kxm/config`; moved by `--workspace` or `KXM_*_DIR`) | hub SQLite store `state/kxm.db` (or `KXM_DATA_PATH`), `state/hub.pid`, `state/session-brief.json`, `logs/telemetry.jsonl`, `logs/kxm-hub.jsonl`, `assets/sessions/`, `assets/workflows/`, `assets/improvements/`, `assets/retrospectives/`, legacy `config/agents.json` and `config/gates.json` | `hub`, `session`, `dash`, `agent worker`, `workflow list\|get\|export`, `gate`, `improve`, `routing report` |
+| Workspace directories (`.kxm/state`, `.kxm/logs`, `.kxm/assets`, `.kxm/config`; moved by `--workspace` or `KXM_*_DIR`) | hub SQLite store `state/kxm.db` (or `KXM_DATA_PATH`), `state/hub.pid`, `state/session-brief.json`, `state/lanes.json` (mode 0600 lane records), `logs/telemetry.jsonl`, `logs/kxm-hub.jsonl`, `assets/sessions/`, `assets/workflows/`, `assets/improvements/`, `assets/retrospectives/`, legacy `config/agents.json` and `config/gates.json` | `hub`, `session`, `dash`, `lane`, `agent worker`, `workflow list\|get\|export`, `gate`, `improve`, `routing report` |
 | User config directory (`KXM_USER_CONFIG_DIR`, default `~/.config/kxm`) | `config.yaml` (user scope), `session.token`, global `roles/` and `workflows/`, `role-hosts.yaml`, `completions/` | `config --scope user`, `auth token`, `session brief\|token`, `role`/`workflow` with `--scope global`, `studio serve`, `completion install` |
 | User state root (`KXM_STATE_HOME`; macOS `~/Library/Application Support/KXM`; Linux `$XDG_STATE_HOME/kxm` or `~/.local/state/kxm`; Windows `%LOCALAPPDATA%\KXM`) | `hub-env.json` (persisted hub credentials), `hub-binding.json`, `runtime/` (Runtime supervisor registry and per-project run stores), `update.yaml`, repository bindings | `hub start\|bind\|unbind`, every hub client, `run`, `runs`, `runtime`, `tenant status`, `update`, `init --repository`, and (read-only, the project's run store) `improve` and `routing report` |
 
@@ -157,6 +157,8 @@ Exit 2 covers an unknown command or option, a missing argument or required optio
 | Start or bind a hub | [`kxm hub start`](#kxm-hub-start), [`kxm hub bind`](#kxm-hub-bind), [`kxm hub view`](#kxm-hub-view) |
 | Check harness installs and authentication | [`kxm harness list`](#kxm-harness-list), [`kxm update --dry-run`](#kxm-update) |
 | 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) |
 | 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) |
@@ -1382,19 +1384,107 @@ dry run: resume workflow run wf_dry_run (stage: review)
   would write /work/proj/.kxm/state/kxm.db (workflow_runs wf_dry_run, one workflow_journal decision)
 ```
 
+## `kxm lane`
+
+One lane is one git worktree, one branch named the unit, and one recorded base sha. The record lives in the control checkout's state directory, `.kxm/state/lanes.json` (`kxm.lanes.v1`, mode 0600). The worktree path is `../<control-dir-basename>-<unit>`, next to the control checkout. Creating a lane resolves the base ref to a sha and does not fetch. There is no push, merge, pull request, or branch delete. Selecting a lane sets the discovery cwd to that lane's path and rebuilds workspace directories from it; `KXM_WORKDIR` still selects the workspace root when it is set, so the lane path is the workspace root only when `KXM_WORKDIR` is unset.
+
+```text
+kxm lane create <unit> [--base <ref>]
+kxm lane list
+kxm lane status <unit>
+kxm lane drop <unit> [--force]
+kxm lane run <unit> --brief <file> [--workflow <id>] [--base <ref>] [--wait] [--timeout-ms <n>]
+```
+
+```bash
+kxm lane run omp-align-p1 --brief .kxm/briefs/omp-align-p1.md --wait
+```
+
+### `kxm lane create`
+
+Resolves `<ref>` (default `origin/main`) with `git rev-parse --verify <ref>^{commit}` in the control checkout, then `git worktree add -b <unit> <path> <sha>`. The new worktree must contain `.kxm/project.yaml`. Writes the record and prints it.
+
+| Option | Argument | Default | Description |
+|---|---|---|---|
+| `--base` | `<ref>` | `origin/main` | Ref to resolve before adding the worktree |
+
+Refusals (exit 1): `lane_unit_invalid`, `lane_exists` (record, path, or branch already present), `lane_base_unresolved` (the text names `git fetch origin`), `lane_not_project` (worktree removed again), `lane_git_failed`, `lanes_unreadable`.
+
+### `kxm lane list`
+
+Prints one line per lane: unit, branch, base sha, `dirty` (porcelain line count), `ahead` and `behind` against the recorded base sha, and `exists`. JSON key: `lanes`.
+
+### `kxm lane status`
+
+The list row for one unit, plus `status` of `lastRunId` when the Runtime supervisor is already running and answers. Otherwise `status=unknown`. `kxm lane status` never starts the Runtime supervisor.
+
+Refusals (exit 1): `lane_missing`, `lane_unit_invalid`, `lanes_unreadable`.
+
+### `kxm lane drop`
+
+Removes the worktree and the record. Refuses `lane_dirty` when porcelain is nonempty, and `lane_run_open` when `lastRunId` is set and that run is not `completed`, `failed`, or `cancelled`. `--force` overrides both. `git worktree remove --force` is used only with `--force`. The branch is not deleted; the text says so (`branchDeleted: false`). Unless `--force` is set, drop may start the Runtime supervisor to check whether the lane's last run is still open; `--dry-run` only attaches to a supervisor that is already running. `kxm lane status` never starts the supervisor.
+
+Refusals (exit 1): `lane_missing`, `lane_dirty`, `lane_run_open`, `lane_git_failed`.
+
+### `kxm lane run`
+
+Creates the lane when the record is absent (same rules as `create`), refuses `lane_run_open` when the last run is not settled, then runs the same path as `kxm run --lane <unit> --brief <file>` and `kxm runs drive <runId> --lane <unit>`. `--wait` and `--timeout-ms` are passed through. The run id is stored on the record. Prints the run envelope and the drive result. That open-run check may start the Runtime supervisor; `--dry-run` only attaches to a supervisor that is already running. `kxm lane status` never starts the supervisor.
+
+`--brief` is required. `--workflow` defaults to the lane project's `defaultWorkflow`. `--base` applies only when the lane is created. A live writer step through this verb is subject to the Runtime's one-shot process timeout, which is 120 seconds until `limits.agentStepTimeoutMs` lands, so long implementation briefs should use `just impl-bg` until then (see section 4 of `plans/plan-lane-cli.md`).
+
+Refusals (exit 1): `brief_unreadable`, `lane_unit_invalid`, `lane_exists`, `lane_base_unresolved`, `lane_run_open`, `lane_git_failed`, `lane_not_project`, `lanes_unreadable`.
+
+## `kxm land`
+
+Land the current branch. `npm run verify` is the first stage and is not replaced. The command spawns `scripts/pr-land.mjs` from the project root and streams one JSON line per stage. With no `--stage`, the stages run in order and stop at the first refusal. `--dry-run` prints each stage's plan and does not mutate. Squash is the only merge. A required review is reported and not bypassed.
+
+```text
+kxm land [--pr <n>] [--stage <name>] [--body-file <path>]
+```
+
+```bash
+kxm land --stage verify --dry-run
+```
+
+| Option | Argument | Default | Description |
+|---|---|---|---|
+| `--pr` | `<n>` | the open pull request for this branch | Pull request number to reuse |
+| `--stage` | `<name>` | all stages | One of `verify`, `docs`, `push`, `pr`, `rebase`, `unblock`, `merge`, `release`, `milestone` |
+| `--body-file` | `<path>` | none | Body file for `gh pr create`. Required when creating a pull request |
+
+Outside a KXM project the command refuses `project_required` (exit 1). Unknown arguments and an unknown stage exit 2.
+
+### Stages
+
+| Stage | What it does |
+|---|---|
+| `verify` | Refuses `land_dirty_tree` unless `git status --porcelain` is empty. Skips when `.kxm/logs/land-verify-<tree>.json` for `HEAD^{tree}` is younger than 30 minutes. Otherwise runs `npm run verify` and writes that receipt. |
+| `docs` | Runs `plans/kxm-roadmap/update-dashboard.mjs` when that file exists. Commits changes under `docs/roadmap/`, `plans/kxm-roadmap/`, or `docs/architecture/` as `docs(roadmap): regenerate after verify`. Any other path, including `state.json`, is `land_docs_failed`. When the generator is absent the stage passes with `docs: skipped (generator absent)`. |
+| `push` | `git push -u origin <branch>`. After a rebase in this run, the push uses `--force-with-lease`. |
+| `pr` | Reuses the branch's open pull request, or creates one with `gh pr create --body-file`. |
+| `rebase` | When `mergeStateStatus` is `BEHIND` or `DIRTY`: fetch, rebase onto `origin/main`, and resolve only three conflicts (take `plugins/kxm/dist` from main and rebuild; union CHANGELOG Unreleased bullets, ours first; union the tracker "Landed in this tree" list, newest first). Runs `docs` again when the tree changed, re-verifies unless `git merge-tree --write-tree origin/main HEAD` was clean, and pushes with the lease. Five rounds, then `land_conflict_manual`. |
+| `unblock` | Reads `statusCheckRollup` and `reviewDecision`. Reruns one failed check with `gh run rerun --failed`. A second failure or `REVIEW_REQUIRED` is `land_blocked`. |
+| `merge` | Enables auto-merge with `enablePullRequestAutoMerge` and `mergeMethod: SQUASH`. When the response contains "clean status", squash-merges with `PUT /repos/{owner}/{repo}/pulls/{n}/merge` and commit title `<title> (#n)`. Polls `gh pr view --json state` every 30 seconds for up to 20 minutes. |
+| `release` | Records the newest `v*` tag before the merge, waits for the Auto-Release run whose title contains the pull request title, requires a newer tag from `git ls-remote --tags origin`, waits for the Release run created after the merge, then polls `npm view @kontextmind/kxm@<version> version` every 30 seconds for 10 minutes. The success detail is `PUBLISHED <version>`. |
+| `milestone` | Compares `plans/kxm-roadmap/state.json` from before and after `docs`. When a phase goes from an open task to all tasks `done`, or the pull request body contains a `Milestone:` line, prints `deep_review_required: true` and exits 0. The review is the `/reanalyze-roadmap` skill, not this command. An absent state file passes with skipped. |
+
+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 run`
 
 ```text
-kxm run <workflow> [prompt...]
+kxm run <workflow> [--brief <file>] [--lane <unit>] [prompt...]
 ```
 
 Create a KXM run without executing steps. The run pins the project's `homeRuntimeId`, config revision, and executor and tool policy revisions. Events store the prompt's SHA-256; its full text is kept in a local mode-0600 sidecar, `run-events.db.run-prompts.json`, and dispatch refuses a hash mismatch (`run_prompt_mismatch`). The Runtime supervisor starts if needed. Output explicitly reports no execution, live prerequisites, and separate drive/status/receipt commands. Use `kxm runs drive <runId> --wait` for supported live one-shot calls; no hub or Pi worker is required. `--simulated` is a model-free experiment, not evidence that implementation ran. Local runs are inspected with `kxm runs`, not the webhook-only `kxm workflow get`.
 
 - Arguments: `<workflow>`, Workflow id to run (a file under `.kxm/workflows/`); `[prompt...]`, Run prompt (events keep its hash; the full text is kept in a local 0600 sidecar file).
-- No command-specific options. Refuses `--workspace` (exit 2).
+- `--brief <file>` reads that file from the invocation directory, trims it, and uses the text as the prompt. The JSON envelope includes `brief` set to the path as given. `--brief` together with a positional prompt is `brief_and_prompt`. A file that cannot be read is `brief_unreadable`.
+- `--lane <unit>` selects the recorded worktree before project discovery. A missing lane is `lane_missing`. A last run that is not settled is `lane_run_open`.
+- Refuses `--workspace` (exit 2, `workspace_option_unsupported`).
 - Needs a KXM project. Starts and uses the Runtime; no hub needed. Honors `--dry-run`, which validates the project and prints the plan without starting the supervisor.
 - JSON keys: `idempotent`, `run` (`runId`, `homeRuntimeId`, `status`, `configRevision`), `supervisor` (`runtimeId`, `port`, `started`), and `execution` (`status: not_started`, `mode: live`, `defaultHarness`, `authentication: not_checked`, `prerequisites`, `nextSteps`). Dry run: `projectRoot`, `workflowId`, `configRevision`, `defaultHarness`, `prerequisites`. The obsolete `phase: pre-3a` field is no longer returned.
-- Errors: `workflow_required` (exit 2), `project_required`, `run_workflow_unknown`, `run_failed` with `issues` (any invalid file in the project fails the load, for example `gate_outcome_impossible`), `run_io_failed` (exit 1).
+- Errors: `workflow_required` (exit 2), `project_required`, `run_workflow_unknown`, `brief_and_prompt`, `brief_unreadable`, `lane_missing`, `lane_run_open`, `run_failed` with `issues` (any invalid file in the project fails the load, for example `gate_outcome_impossible`), `run_io_failed` (exit 1).
 - The `default` workflow that `kxm init` writes does not set `limits.maxAgentTimeMs`, so it can be driven. A workflow that sets that limit is created, but `kxm runs drive` refuses it with `run_handoff_required` (`limit_unsupported`); projects from older `kxm init` templates carry it on `default`.
 
 ```bash
@@ -1436,12 +1526,12 @@ Reads and drives runs through the Runtime supervisor. Every subcommand needs a K
 ### `kxm runs status`
 
 ```text
-kxm runs status <runId>
+kxm runs status <runId> [--lane <unit>]
 ```
 
 Show the projected status of a run, including durable drive receipt state (open / receipt verified / unsettled / orphaned).
 
-- Arguments: `<runId>`, Run id. No command-specific options. Reads run state, but starts the supervisor if needed (not under `--dry-run`).
+- Arguments: `<runId>`, Run id. `--lane <unit>` discovers the project from that lane's worktree (`lane_missing` when the record or path is absent, `lane_unit_invalid` when the unit is not a KXM identifier, `lanes_unreadable` when the record cannot be read). Reads run state, but starts the supervisor if needed (not under `--dry-run`).
 - Text: `run <id>: <status> (workflow <id>, updated <time>)`, plus a drive line such as `drive <id>: open`, `completed (receipt verified)`, `unsettled <reason>`, `handoff`, `cancelled (<reason>)`, or `no receipt (orphaned)`.
 - JSON keys: `run` (`runId`, `status`, `workflowId`, `configRevision`, `updatedAt`, ...), `drive` (`driveId`, `mode`, `openedAt`, `receipt`, `verified`, `divergence`).
 - Errors: `project_required`, `run_status_failed`, `run_status_io_failed` (exit 1).
@@ -1467,7 +1557,7 @@ kxm runs status --dry-run refused: the Runtime supervisor is not running and --d
 ### `kxm runs drive`
 
 ```text
-kxm runs drive <runId> [--simulated] [--wait] [--timeout-ms <n>]
+kxm runs drive <runId> [--simulated] [--wait] [--timeout-ms <n>] [--lane <unit>]
 ```
 
 Opens a drive of the run. With `--simulated`, a model-free producer reports every agent step as passed. Without `--simulated` the drive runs in live mode: each agent step invokes its harness through a one-shot producer, and the agent's model must be an admitted route (otherwise `producer_route_not_admitted`; there is no fallback model). A read-only step runs with the harness's read-only flags. A step with `write` access runs with an audited writer profile, which only `pi` and `grok` have; it must be a single assignment in a project whose `limits.maxConcurrentRuns` is 1, and, when `.kxm/roster.yaml` exists, its route must be on the roster's writer lineup. Otherwise the drive hands the run off with `step_unsupported`. Around each live attempt the Runtime fingerprints the checkout with `git status` and `git diff`: a write step settles `passed` only when the checkout changed (routing metadata `authored: true`), and a read-only step that changed it settles `failed` (`authoringWitness: readonly_mutated`).
@@ -1477,8 +1567,9 @@ Opens a drive of the run. With `--simulated`, a model-free producer reports ever
 | `--simulated` | none | off | Use the model-free simulation producer |
 | `--wait` | none | off | Wait until a drive receipt is recorded; exits 0 only for a VERIFIED COMPLETED settlement |
 | `--timeout-ms` | `<n>` | `60000` | Wait timeout in milliseconds (default 60000, max 600000) |
+| `--lane` | `<unit>` | none | Discover the project from this lane's worktree |
 
-- Arguments: `<runId>`, Run id.
+- Arguments: `<runId>`, Run id. `--lane` refuses `lane_missing` when the record or path is absent, and also `lane_unit_invalid` and `lanes_unreadable`.
 - `--timeout-ms` applies only with `--wait` and must be an integer from 1 to 600000 (`run_drive_timeout_invalid`, exit 1).
 - Mutates run state. Honors `--dry-run`.
 - JSON keys without `--wait`: `runId`, `driveId`, `poll`, `mode`, `status` (`accepted`). With `--wait`: `receipt`, `verified`; a timeout prints `error: "timeout"`.
@@ -1511,7 +1602,7 @@ Not run: starts the Runtime and writes run events.
 ### `kxm runs receipt`
 
 ```text
-kxm runs receipt <runId> [--all]
+kxm runs receipt <runId> [--all] [--lane <unit>]
 ```
 
 Print the newest drive receipt for a run.
@@ -1519,8 +1610,9 @@ Print the newest drive receipt for a run.
 | Option | Argument | Default | Description |
 |---|---|---|---|
 | `--all` | none | off | Print the capped receipt list for the run |
+| `--lane` | `<unit>` | none | Discover the project from this lane's worktree |
 
-- Arguments: `<runId>`, Run id. Text mode prints the newest receipt's settlement as JSON; `--all` prints the list. Starts the supervisor if needed (not under `--dry-run`).
+- Arguments: `<runId>`, Run id. Text mode prints the newest receipt's settlement as JSON; `--all` prints the list. Starts the supervisor if needed (not under `--dry-run`). `--lane` refuses `lane_missing` when the record or path is absent, and also `lane_unit_invalid` and `lanes_unreadable`.
 - JSON keys: `receipt`, or `receipts` with `--all`. Exit 1 with `no_receipts` when the run was never driven.
 
 ```bash
@@ -1532,12 +1624,12 @@ Not run: starts the Runtime supervisor.
 ### `kxm runs cancel`
 
 ```text
-kxm runs cancel <runId>
+kxm runs cancel <runId> [--lane <unit>]
 ```
 
 Durably request cancellation of a run: records `run.cancel_requested` then `run.status_changed`. Cancelling a terminal run is an idempotent no-op.
 
-- Arguments: `<runId>`, Run id. No command-specific options.
+- Arguments: `<runId>`, Run id. `--lane <unit>` discovers the project from that lane's worktree (`lane_missing` when the record or path is absent, `lane_unit_invalid` when the unit is not a KXM identifier, `lanes_unreadable` when the record cannot be read).
 - Mutates run state. Honors `--dry-run`.
 - JSON keys: `idempotent`, `run` (`runId`, `status`).
 

package/docs/reference/workflow-catalog.md

@@ -14,6 +14,7 @@ This catalog names common multi-agent workflows by area and lists, for each role
 8. [Research & Strategy](#research--strategy)
 9. [Business Operations](#business-operations)
 10. [Security & Reliability](#security--reliability)
+11. [Repository workflow: land](#repository-workflow-land)
 
 ---
 
@@ -1083,6 +1084,12 @@ This cross-reference points each software and security workflow at the KXM pages
 
 ---
 
+## Repository workflow: land
+
+`.kxm/workflows/land.yaml` is a project workflow, not a catalog slug. It runs six command gates in order: `land-verify`, `land-docs`, `land-rebase`, `land-merge`, `land-release`, `land-milestone`. Each gate calls `node scripts/pr-land.mjs --stage <name> --json`. A failed merge returns to `land-rebase` at most three times, then the run fails. `npm run verify` remains the first stage of `kxm land` and is not replaced by this workflow.
+
+`kxm run land --dry-run --json` may be refused by live prerequisites until gate-only workflows are supported. The command `kxm land` runs the same stages without a run receipt.
+
 ## Related
 
 - [Workflow definitions](workflow-definitions.md): write a webhook or Runtime workflow for these stages

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kontextmind/kxm",
-  "version": "0.7.119",
+  "version": "0.7.121",
   "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.119",
+  "version": "0.7.121",
   "description": "Headless multi-agent orchestration, durable workflows, and a live operator dashboard for Pi and Claude Code",
   "author": {
     "name": "KontextMind",