@kontextmind/kxm 0.7.120 → 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.120",
+      "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,15 @@ 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

package/docs/contributing/assignment-runner.md

@@ -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/reference/cli-reference.md

@@ -158,6 +158,7 @@ Exit 2 covers an unknown command or option, a missing argument or required optio
 | 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) |
@@ -1433,6 +1434,42 @@ Creates the lane when the record is absent (same rules as `create`), refuses `la
 
 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

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