@kontextmind/kxm 0.7.120 → 0.7.122

package/plugins/kxm/dist/mcp-server.js

@@ -17313,7 +17313,7 @@ function sessionTokenFixHint(policy) {
 }
 
 // plugins/kxm/src/mcp-server.ts
-var VERSION = "0.7.120";
+var VERSION = "0.7.122";
 var CONFIGURE_PLUGIN = "/plugin configure kxm@kxm";
 var inbox = /* @__PURE__ */ new Map();
 var notifiedInbox = /* @__PURE__ */ new Set();

package/plugins/kxm/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-plugin",
-  "version": "0.7.120",
+  "version": "0.7.122",
   "private": true,
   "type": "module",
   "engines": {

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

@@ -20,7 +20,8 @@ writers, or replace `.kxm/roster.yaml` trusted policy.
 | Delegate to or answer another agent | `kxm-peer` | `peer` (`peer await` is capped at 60 seconds) |
 | Work inside a durable workflow run, gates, signed callbacks | `kxm-workflow` | `workflow`, `gate` |
 | Role definitions, role hosts, model rosters | `kxm-definitions` | `role` |
-| Create, drive, inspect, or cancel a run, or use a worktree lane | `kxm-runs` | `run`, `runs`, `lane` |
+| Create, drive, inspect, or cancel a run, use a worktree lane, or land a branch | `kxm-runs` | `run`, `runs`, `lane`, `land` |
+| Create, drive, inspect, or cancel a run, use a worktree lane, or run the developer assignment loop | `kxm-runs` | `run`, `runs`, `lane`, `assign` |
 | What we know or decided, recall, context footprint, Git memory | `kxm-context-memory` | `context`, `memory`, `explain` |
 | Turn a repeated practice into a governed skill | `kxm-skill-lifecycle` | `skills` |
 | What KXM learned, repeated asks, recorded route spend | `kxm-routing-improve` | `routing`, `improve` |

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

@@ -1,6 +1,6 @@
 ---
 name: kxm-runs
-description: Create, drive, and inspect local KXM runs, and manage worktree lanes. kxm runs drive with --simulated executes a run model-free and settles it with a verified receipt. Use when asked to start a workflow run, check its status, read its receipt, cancel it, smoke-test a workflow, or create a lane.
+description: Create, drive, and inspect local KXM runs, manage worktree lanes, land a branch, and run the developer assignment loop. kxm runs drive with --simulated executes a run model-free and settles it with a verified receipt. Use when asked to start a workflow run, check its status, read its receipt, cancel it, smoke-test a workflow, create a lane, land the current branch, or call kxm assign (run, witness, plan-current, attribute, observe-cost, accept, change-report).
 ---
 
 # KXM runs
@@ -26,6 +26,14 @@ create, or logs verbs under `runs`.
 | `kxm lane status <unit>` | One lane plus its last run status, or unknown when the supervisor is not answering | `--json` |
 | `kxm lane drop <unit>` | Remove the worktree and the record. The branch is not deleted | `--force`, `--json` |
 | `kxm lane run <unit>` | Create the lane if needed, start a run from a brief, and drive it | `--brief <file>` (required), `--workflow <id>`, `--base <ref>`, `--wait`, `--timeout-ms <n>`, `--json` |
+| `kxm land` | Verify, regenerate docs, push, open or reuse a pull request, rebase, unblock, squash-merge, watch the release, and note a milestone | `--pr <n>`, `--stage <name>`, `--body-file <path>`, `--json`, `--dry-run` |
+| `kxm assign run` | Dispatch one assignment manifest. The runner performs every check | `--manifest <path>` |
+| `kxm assign witness` | Run the fixed witness for an existing record | `--record-dir <path>` |
+| `kxm assign plan-current` | Stamp or advance the current-plan pointer | `--task-dir <path>`, `--plan <path>`, `--sha256 <hex>`, `--base-commit <sha>`, `--expected-generation <n>` |
+| `kxm assign attribute` | Attach a private note. It is not proof | `--task-dir <path>`, `--record-dir <path>`, `--class <class>`, `--explanation-file <path>` |
+| `kxm assign observe-cost` | Import one cost-only observation | `--task-dir <path>`, `--input <path>` |
+| `kxm assign accept` | Bind a witnessed commit and two critic records | `--task-dir <path>`, `--commit <sha>`, `--record-dir <path>`, `--critic <path>` twice, optional `--observed-pr <id>`, `--observed-ci <id>` |
+| `kxm assign change-report` | Report attempts, rework, and spend | `--task-dir <path>` |
 
 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
@@ -65,6 +73,22 @@ file. `kxm run --lane <unit>` and `kxm runs status|drive|receipt|cancel --lane`
 discover the project from the lane worktree. `kxm lane run <unit> --brief <file>`
 creates the lane when it is missing, starts the run, and drives it.
 
+`kxm land` lands the current branch. With no `--stage` it runs these stages in
+order: `verify`, `docs`, `push`, `pr`, `rebase`, `unblock`, `merge`,
+`release`, `milestone`. `verify` runs `npm run verify` on a clean tree and is
+not replaced by the later stages. `docs` regenerates the roadmap when
+`plans/kxm-roadmap/update-dashboard.mjs` is present and commits only those
+generated pages. `push` publishes the branch. `pr` reuses the open pull
+request or creates one from `--body-file`. `rebase` rebases onto
+`origin/main` for at most five rounds, resolving only the dist rebuild, the
+CHANGELOG Unreleased union, and the tracker "Landed in this tree" union.
+`unblock` reruns one failed check and reports a required review. `merge`
+squash-merges. `release` waits for the tag and the npm publish. `milestone`
+reports `deep_review_required` when a phase flips to done or the body contains
+a `Milestone:` line, and does not run the review. `--dry-run` prints each
+stage's plan and does not mutate.
+`kxm assign` spawns `node scripts/assignment-run.mjs` from the project root and returns the child's exit code. Paths are passed through as given. `--dry-run` prints that argv and does not spawn. `--json` formats this command's own output and is not forwarded. The group does not load a working-directory `.env`. A project without `scripts/assignment-run.mjs` is refused with `assign_runner_missing`. Outside a KXM project the refusal is `project_required`. Witness, roster, and acceptance checks belong to the runner, documented in `docs/contributing/assignment-runner.md`.
+
 ## Refusals
 
 - `run_workflow_unknown`: the workflow ID is not a project workflow. Run only

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

@@ -0,0 +1,144 @@
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { discoverKxmProjectRoot } from "../project-config.ts";
+import { CLI_RESULT_SCHEMA, print, type Runtime } from "./types.ts";
+
+export interface AssignSpawnOptions {
+  cwd: string;
+  stdio: "inherit";
+  env: NodeJS.ProcessEnv;
+}
+
+export interface AssignSpawnResult {
+  status: number | null;
+  error?: Error;
+}
+
+/** Test seam. Production leaves `spawn` unset and uses `spawnSync`. */
+export const kxmAssignCliSeams: {
+  spawn?: (command: string, args: readonly string[], options: AssignSpawnOptions) => AssignSpawnResult;
+} = {};
+
+export type AssignVerb =
+  | "run"
+  | "witness"
+  | "plan-current"
+  | "attribute"
+  | "observe-cost"
+  | "accept"
+  | "change-report";
+
+export interface AssignArgs {
+  manifest?: string;
+  recordDir?: string;
+  taskDir?: string;
+  plan?: string;
+  sha256?: string;
+  baseCommit?: string;
+  expectedGeneration?: string;
+  classification?: string;
+  explanationFile?: string;
+  input?: string;
+  commit?: string;
+  critics?: readonly string[];
+  observedPr?: string;
+  observedCi?: string;
+}
+
+const RUNNER_REL = "scripts/assignment-run.mjs";
+
+function refuse(runtime: Runtime, command: string, error: string, text: string): number {
+  print(runtime.io, runtime.json, { ok: false, command, error }, text);
+  return 1;
+}
+
+function flag(value: string | undefined): string {
+  if (value === undefined) throw new Error("assign invocation missing a parsed flag");
+  return value;
+}
+
+/** Argv after `node scripts/assignment-run.mjs`, in the recipe's flag order.
+ * The runner's usage text documents no `--json` flag. `accept` prints JSON
+ * and takes none, so the global `--json` flag stays on this command. */
+function runnerArgv(subcommand: AssignVerb, args: AssignArgs): string[] {
+  switch (subcommand) {
+    case "run":
+      return ["run", "--manifest", flag(args.manifest)];
+    case "witness":
+      return ["witness", "--record-dir", flag(args.recordDir)];
+    case "plan-current":
+      return [
+        "plan-current",
+        "--task-dir", flag(args.taskDir),
+        "--plan", flag(args.plan),
+        "--sha256", flag(args.sha256),
+        "--base-commit", flag(args.baseCommit),
+        "--expected-generation", flag(args.expectedGeneration),
+      ];
+    case "attribute":
+      return [
+        "attribute",
+        "--task-dir", flag(args.taskDir),
+        "--record-dir", flag(args.recordDir),
+        "--class", flag(args.classification),
+        "--explanation-file", flag(args.explanationFile),
+      ];
+    case "observe-cost":
+      return ["observe-cost", "--task-dir", flag(args.taskDir), "--input", flag(args.input)];
+    case "accept": {
+      const argv = [
+        "accept",
+        "--task-dir", flag(args.taskDir),
+        "--commit", flag(args.commit),
+        "--record-dir", flag(args.recordDir),
+      ];
+      for (const critic of args.critics ?? []) argv.push("--critic", critic);
+      if (args.observedPr !== undefined) argv.push("--observed-pr", args.observedPr);
+      if (args.observedCi !== undefined) argv.push("--observed-ci", args.observedCi);
+      return argv;
+    }
+    case "change-report":
+      return ["change-report", "--task-dir", flag(args.taskDir)];
+    default: {
+      const unreachable: never = subcommand;
+      throw new Error(`unknown assign verb ${String(unreachable)}`);
+    }
+  }
+}
+
+export async function cmdAssign(runtime: Runtime, subcommand: AssignVerb, args: AssignArgs): Promise<number> {
+  const command = `assign ${subcommand}`;
+  const root = discoverKxmProjectRoot(runtime.cwd);
+  if (!root) return refuse(runtime, command, "project_required", `${command} requires a KXM project (run kxm init first)`);
+  if (!existsSync(join(root, "scripts", "assignment-run.mjs"))) {
+    return refuse(runtime, command, "assign_runner_missing", `${command} requires scripts/assignment-run.mjs in the project root`);
+  }
+  const argv = ["node", RUNNER_REL, ...runnerArgv(subcommand, args)];
+  if (runtime.dryRun) {
+    // print() redacts every 64-hex string. plan-current passes a plan sha256
+    // through unchanged, so the dry-run argv is written directly.
+    const payload = { schema: CLI_RESULT_SCHEMA, ok: true, command, dryRun: true, argv };
+    runtime.io.stdout(runtime.json ? `${JSON.stringify(payload)}\n` : `${argv.join(" ")}\n`);
+    return 0;
+  }
+  // Never load a `.env` from the working directory. The justfile keeps
+  // `set dotenv-load` off for the same reason: a gitignored `.env` could set
+  // `NODE_OPTIONS`, and that value runs before the runner validates identity,
+  // tree, or roster. Pass the process environment through unchanged.
+  const spawn = kxmAssignCliSeams.spawn ?? ((commandName: string, commandArgs: readonly string[], options: AssignSpawnOptions): AssignSpawnResult => {
+    const result = spawnSync(commandName, commandArgs, {
+      cwd: options.cwd,
+      stdio: options.stdio,
+      env: options.env,
+      windowsHide: true,
+    });
+    return { status: result.status, ...(result.error ? { error: result.error } : {}) };
+  });
+  const result = spawn("node", argv.slice(1), { cwd: root, stdio: "inherit", env: runtime.env });
+  if (result.status === null) {
+    const detail = result.error?.message ?? "the assignment runner could not be started";
+    return refuse(runtime, command, "assign_spawn_failed", detail);
+  }
+  return result.status;
+}

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

@@ -0,0 +1,48 @@
+import { spawn } from "node:child_process";
+import { join } from "node:path";
+import { discoverKxmProjectRoot } from "../project-config.ts";
+import { findKxmRepoRoot } from "../repo-root.ts";
+import { print, type Runtime } from "./types.ts";
+
+export interface LandOptions {
+  pr?: string;
+  stage?: string;
+  bodyFile?: string;
+}
+
+function childEnv(): NodeJS.ProcessEnv {
+  const env: NodeJS.ProcessEnv = {};
+  for (const [name, value] of Object.entries(process.env)) {
+    if (value === undefined) continue;
+    if (name.toUpperCase().startsWith("GIT_")) continue;
+    env[name] = value;
+  }
+  return env;
+}
+
+function refuse(runtime: Runtime, error: string, text: string): number {
+  print(runtime.io, runtime.json, { ok: false, command: "land", error }, text);
+  return 1;
+}
+
+/** Spawn scripts/pr-land.mjs and stream its JSON lines. The exit code is the script's. */
+export function cmdLand(runtime: Runtime, options: LandOptions = {}): Promise<number> {
+  const root = discoverKxmProjectRoot(runtime.cwd);
+  if (!root) {
+    return Promise.resolve(refuse(runtime, "project_required", "land requires a KXM project (run kxm init first)"));
+  }
+  const script = join(findKxmRepoRoot(import.meta.url), "scripts", "pr-land.mjs");
+  const args = [script];
+  if (options.pr) args.push("--pr", options.pr);
+  if (options.stage) args.push("--stage", options.stage);
+  if (options.bodyFile) args.push("--body-file", options.bodyFile);
+  if (runtime.json) args.push("--json");
+  if (runtime.dryRun) args.push("--dry-run");
+  return new Promise((resolveExit) => {
+    const child = spawn(process.execPath, args, { cwd: root, env: childEnv(), windowsHide: true });
+    child.stdout.on("data", (chunk: Buffer) => runtime.io.stdout(chunk.toString("utf8")));
+    child.stderr.on("data", (chunk: Buffer) => runtime.io.stderr(chunk.toString("utf8")));
+    child.once("error", () => resolveExit(1));
+    child.once("close", (code) => resolveExit(code ?? 1));
+  });
+}

package/plugins/kxm/src/cli.ts

@@ -131,6 +131,9 @@ import {
   cmdLaneStatus,
 } from "./cli/lanes.ts";
 
+import { cmdLand } from "./cli/land.ts";
+import { cmdAssign } from "./cli/assign.ts";
+
 import {
   cmdStatus,
   cmdDash,
@@ -197,6 +200,9 @@ const USAGE_ERROR_CODES = new Set([
 const DRY_RUN_COMMANDS: ReadonlySet<string> = new Set([
   "init", "backup", "restore", "run", "explain", "suggest", "update", "dash", "completion", "completion install",
   "lane create", "lane list", "lane status", "lane drop", "lane run",
+  "land",
+  "assign run", "assign witness", "assign plan-current", "assign attribute",
+  "assign observe-cost", "assign accept", "assign change-report",
   "plugin install", "plugin",
   "runs status", "runs drive", "runs receipt", "runs cancel", "runs list",
   "tenant status", "models inventory-refresh", "harness list", "auth token",
@@ -485,6 +491,86 @@ function createProgram(ctx: CliContext, result: { code: number }): Command {
       });
     });
 
+  addGlobalOptions(program.command("land").description("Land the current branch: verify, regenerate docs, push, pull request, rebase, unblock, squash-merge, release, and milestone"))
+    .option("--pr <n>", "Existing pull request number")
+    .option("--stage <name>", "Run one stage: verify, docs, push, pr, rebase, unblock, merge, release, or milestone")
+    .option("--body-file <path>", "Pull request body file used when creating a pull request")
+    .action(async function landAction(this: Command, options: { pr?: string; stage?: string; bodyFile?: string }) {
+      result.code = await cmdLand(runtimeFrom(ctx, this), {
+        ...(options.pr !== undefined ? { pr: options.pr } : {}),
+        ...(options.stage !== undefined ? { stage: options.stage } : {}),
+        ...(options.bodyFile !== undefined ? { bodyFile: options.bodyFile } : {}),
+      });
+    });
+  const assignCmd = addGlobalOptions(program.command("assign").description("Run this repository's developer assignment runner"));
+  assignCmd.helpCommand("help", "Show assign help");
+  addGlobalOptions(assignCmd.command("run").description("Dispatch a bound assignment manifest"))
+    .requiredOption("--manifest <path>", "Absolute path to the assignment manifest")
+    .action(async function assignRunAction(this: Command, options: { manifest: string }) {
+      result.code = await cmdAssign(runtimeFrom(ctx, this), "run", { manifest: options.manifest });
+    });
+  addGlobalOptions(assignCmd.command("witness").description("Run the fixed verification witness for an existing assignment"))
+    .requiredOption("--record-dir <path>", "Absolute path to the assignment record directory")
+    .action(async function assignWitnessAction(this: Command, options: { recordDir: string }) {
+      result.code = await cmdAssign(runtimeFrom(ctx, this), "witness", { recordDir: options.recordDir });
+    });
+  addGlobalOptions(assignCmd.command("plan-current").description("Stamp or advance the current-plan pointer"))
+    .requiredOption("--task-dir <path>", "Absolute path to the task directory")
+    .requiredOption("--plan <path>", "Absolute path to the plan file")
+    .requiredOption("--sha256 <hex>", "SHA-256 of the plan file")
+    .requiredOption("--base-commit <sha>", "Base commit the pointer records")
+    .requiredOption("--expected-generation <n>", "Generation the pointer must currently have")
+    .action(async function assignPlanCurrentAction(this: Command, options: { taskDir: string; plan: string; sha256: string; baseCommit: string; expectedGeneration: string }) {
+      result.code = await cmdAssign(runtimeFrom(ctx, this), "plan-current", {
+        taskDir: options.taskDir,
+        plan: options.plan,
+        sha256: options.sha256,
+        baseCommit: options.baseCommit,
+        expectedGeneration: options.expectedGeneration,
+      });
+    });
+  addGlobalOptions(assignCmd.command("attribute").description("Attach a private attribution note"))
+    .requiredOption("--task-dir <path>", "Absolute path to the task directory")
+    .requiredOption("--record-dir <path>", "Absolute path to the assignment record directory")
+    .requiredOption("--class <class>", "orchestration, model, environment, or unclassified")
+    .requiredOption("--explanation-file <path>", "Absolute path to the note file")
+    .action(async function assignAttributeAction(this: Command, options: { taskDir: string; recordDir: string; class: string; explanationFile: string }) {
+      result.code = await cmdAssign(runtimeFrom(ctx, this), "attribute", {
+        taskDir: options.taskDir,
+        recordDir: options.recordDir,
+        classification: options.class,
+        explanationFile: options.explanationFile,
+      });
+    });
+  addGlobalOptions(assignCmd.command("observe-cost").description("Import one historical cost observation as cost-only"))
+    .requiredOption("--task-dir <path>", "Absolute path to the task directory")
+    .requiredOption("--input <path>", "Absolute path to the observation file")
+    .action(async function assignObserveCostAction(this: Command, options: { taskDir: string; input: string }) {
+      result.code = await cmdAssign(runtimeFrom(ctx, this), "observe-cost", { taskDir: options.taskDir, input: options.input });
+    });
+  addGlobalOptions(assignCmd.command("accept").description("Bind an exact witnessed commit and two critic PASS records"))
+    .requiredOption("--task-dir <path>", "Absolute path to the task directory")
+    .requiredOption("--commit <sha>", "Commit to accept")
+    .requiredOption("--record-dir <path>", "Absolute path to the writer record directory")
+    .requiredOption("--critic <path>", "Absolute path to a critic record directory; pass twice", (value: string, previous: string[]) => previous.concat(value), [] as string[])
+    .option("--observed-pr <id>", "Observed pull request id")
+    .option("--observed-ci <id>", "Observed CI run id")
+    .action(async function assignAcceptAction(this: Command, options: { taskDir: string; commit: string; recordDir: string; critic: string[]; observedPr?: string; observedCi?: string }) {
+      result.code = await cmdAssign(runtimeFrom(ctx, this), "accept", {
+        taskDir: options.taskDir,
+        commit: options.commit,
+        recordDir: options.recordDir,
+        critics: options.critic,
+        ...(options.observedPr !== undefined ? { observedPr: options.observedPr } : {}),
+        ...(options.observedCi !== undefined ? { observedCi: options.observedCi } : {}),
+      });
+    });
+  addGlobalOptions(assignCmd.command("change-report").description("Report attempts, rework, costs, and retained verification history"))
+    .requiredOption("--task-dir <path>", "Absolute path to the task directory")
+    .action(async function assignChangeReportAction(this: Command, options: { taskDir: string }) {
+      result.code = await cmdAssign(runtimeFrom(ctx, this), "change-report", { taskDir: options.taskDir });
+    });
+
   addGlobalOptions(program.command("run").description("Create a KXM run without executing steps; follow its prerequisites, then kxm runs drive <runId> --wait")
     .argument("[workflow]", "Workflow id to run")
     .argument("[prompt...]", "Run prompt (events keep its hash; the full text is kept in a local 0600 sidecar file)")

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.120";
+const VERSION = "0.7.122";
 const CONFIGURE_PLUGIN = "/plugin configure kxm@kxm";
 const inbox = new Map<string, MessageRecord>();
 const notifiedInbox = new Set<string>();

package/scripts/pr-land.d.mts

@@ -0,0 +1,2 @@
+export function unionChangelogUnreleased(ours: string, theirs: string): string;
+export function unionLandedTracker(ours: string, theirs: string): string;