@kontextmind/kxm 0.7.125 → 0.7.126

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

package/docs/README.md

@@ -114,6 +114,8 @@ KXM connects coding agents through a durable, authenticated [hub](glossary.md#hu
 | [Packages and workspaces](contributing/packages.md) | Maintainers | Workspace layout, Nx targets, Bun task running and the layer gate |
 | [KXM terminal components](contributing/tui-components.md) | Maintainers, integrators | The panel kit behind `kxm dash` |
 | [Repository work delivery skill](contributing/repo-work-delivery.md) | Contributors | The repository-local skill for delivering a change |
+| [Operating rules](contributing/operating-rules.md) | Agents, maintainers | The operator's standing instructions, dated, and where each is enforced |
+| [Learnings](contributing/learnings.md) | Agents, maintainers | Durable lessons from running the writer, landing, and docs loops |
 | [Artifact templates](templates/README.md) | Workflow authors | Document templates and where workflows use them |
 
 The templates: [feature](templates/feature.md) · [bug fix](templates/bug-fix.md) · [ADR](templates/adr.md) · [architecture](templates/architecture.md) · [research](templates/research.md) · [review](templates/review.md) · [test plan](templates/test-plan.md) · [test report](templates/test-report.md) · [runbook](templates/runbook.md) · [postmortem](templates/postmortem.md) · [handoff](templates/handoff.md).

package/docs/architecture/inventory.md

@@ -23,6 +23,10 @@ Read from `plugins/kxm/src/cli.ts`, `scripts/kxm-hub.mjs`, `plugins/kxm/src/hub.
 | Workspace logs | `workspaceDirs` | `.kxm/logs`, or `KXM_LOGS_DIR` | log files | `plugins/kxm/src/cli/types.ts` |
 | Workspace assets | `workspaceDirs` | `.kxm/assets`, or `KXM_ASSETS_DIR` | asset files | `plugins/kxm/src/cli/types.ts` |
 | Workspace state | `workspaceDirs` | `.kxm/state`, or `KXM_STATE_DIR` | `kxm.db` when the hub uses this directory | `plugins/kxm/src/cli/types.ts` |
+| Lane registry | `kxm lane create` | no listener | `lanes.json` under the workspace state dir | `plugins/kxm/src/cli/lanes.ts` |
+| Landing | `kxm land` via `scripts/pr-land.mjs` | no listener | `land-release-context.json` and `land-phases-before.json` under `.kxm/logs` | `scripts/pr-land.mjs` |
+| Assignment runner entry | `kxm assign <verb>` | no listener | none; the runner writes task records | `plugins/kxm/src/cli/assign.ts` |
+| Docs site | `kxm docs serve` via `ops/docs-site/serve.py` | the tailnet IPv4 from `tailscale ip -4` and one port; refuses any other address | none; serves the built `site/` | `ops/docs-site/serve.py` |
 
 On macOS the user state root is `Library/Application Support/KXM` under the
 home directory (`kxmUserStateRoot` in `plugins/kxm/src/bindings.ts`). Windows

package/docs/contributing/learnings.md

@@ -0,0 +1,105 @@
+---
+title: "Learnings"
+description: "Durable lessons from running the writer, critic, and landing loop on this repository. One entry per lesson, with the evidence and where it applies. Pruned when a lesson stops being true."
+audience: "agents and maintainers"
+updated: "2026-09-26"
+---
+
+# Learnings
+
+A lesson earns a line here when it would save a future session more than a
+few minutes. Each entry: the lesson, the evidence, where it applies. An
+entry whose fix has landed is deleted, not archived.
+
+## Dispatch and lanes
+
+- **Branch every lane from the current `origin/main`, and rebase before
+  review, not after.** Three branches cut before #330 and #331 landed each
+  needed a hand rebase with the same additive conflicts (`cli.ts`
+  registrations, skill ownership lists, skill mirrors, changelog, dist).
+  Evidence: kxm-assign, docs-site, run-driver-timeouts on 2026-09-26.
+  Applies to: every brief; `kxm land`'s rebase stage only knows three
+  conflict unions.
+- **After an additive rebase, check the skill frontmatter and heading
+  spacing.** Keeping both sides doubled a `description:` key in a SKILL.md
+  (strict-YAML test) and butted two `##` headings together (MD022).
+  Evidence: kxm-assign verify failures, 2026-09-26. Applies to: any
+  hand-resolved conflict in `plugins/kxm/skills/` or the CLI reference.
+- **Never run more than two `npm run verify` at once on this machine.**
+  Six concurrent runs stretched a seven-minute gate past thirty minutes and
+  starved a landing. Evidence: 2026-09-26, 02:10 to 02:40. Applies to: the
+  supervisor tick and any batch of writers finishing together.
+- **The transport's stdin read can fail with `EAGAIN` under concurrent
+  detached dispatch.** Retry once; the request itself is fine. Evidence:
+  two occurrences on 2026-09-26 (backlog S18). Applies to: `just impl-bg`
+  and `just review-cli` until they retire.
+- **Do not launch a writer under the Bash tool's ten-minute background
+  cap.** It kills the harness mid-run. Use the detached recipe or
+  `kxm lane run`. Evidence: the first lane-cli dispatch, 2026-09-26.
+- **Do not run a standalone `npm run verify` on a branch that `kxm land`
+  will land.** The `verify` stage runs it again, so the standalone run
+  only spends one of the two verify slots twice. Run the critics on the
+  writer's own verify evidence, then go straight to `kxm land`. Evidence:
+  docs-site, 2026-09-26. Applies to: every lane after its writer finishes.
+
+## Engine and runtime
+
+- **The improvement loop is blind while writers bypass `kxm run`.** Every
+  writer this week ran through the harness runner (`just impl-bg` and the
+  critic recipes), which records no engine events, so `kxm improve report`
+  and `kxm routing report` both return zero records and no candidates.
+  Evidence: both reports on 2026-09-26 at 08:14 UTC list the engine store as
+  absent and telemetry as empty. Applies to: dispatch. Once the one-step
+  workflows land, dispatch through `kxm lane run --workflow implement-only`
+  so attempts land in the run-events store; until then the sixth-tick
+  improvement loop reports nothing by design.
+
+- **A live agent step had a hard 120 second timeout with no configuration
+  path.** The supervisor built the one-shot producer without a timeout.
+  Fixed on the run-driver-timeouts branch (step `timeoutMs`, project
+  `limits.agentStepTimeoutMs`, default one hour). Delete this entry when
+  that lands.
+- **A run with an unreconciled executing attempt could not be cancelled or
+  driven again**, and that survived a supervisor restart; deleting the
+  lane's Runtime project store was the only recovery. Fixed on the same
+  branch (`executing_unrecorded`, admission released on a handoff receipt).
+  Delete when it lands.
+- **The engine sends `--reasoning-effort low` on a first attempt regardless
+  of the role's effort.** `engine.ts` hard-codes it. Open; covered by the
+  role alignment plan P2 and P6.
+- **Template provenance is refused when the installed kxm moves ahead of
+  the stamped revision, and a project without the file validates as
+  ready.** Deleting the file is the sanctioned state until `kxm init` can
+  re-stamp. Evidence: every fresh lane on 2026-09-26 until #330 removed it.
+
+## `kxm land`
+
+- **Auto-merge cannot be enabled on a PR that is already `CLEAN`**; the
+  mutation answers "clean status" and the REST squash merge is the path.
+  While CI is paused every PR is clean, so this is the normal path.
+- **The Release workflow's run is titled `Release`, never the PR title.**
+  Match it by time after the Auto-Release run. Fixed on kxm-land-followup;
+  delete when it lands.
+- **A verify failure inside `kxm land` shows only the child's last output
+  line.** Re-run verify by hand to see the cause until backlog S19 lands.
+
+## Reviews
+
+- **A CLI critic reviewing a branch cut from an older base will report
+  main's later additions as deletions.** Say the base commit in the brief
+  and tell the critic to review against it. Evidence: docs-site review,
+  two of five findings were base artifacts.
+- **Usage errors are Commander prose even under `--json` in every group.**
+  Repo-wide, one fix in `mapCommanderError`; on kxm-land-followup. Delete
+  when it lands.
+
+## omp research, kept for the alignment plan
+
+- **omp's roster is `modelRoles` plus `retry.fallbackChains`**, walked on
+  provider errors with a revert policy; KXM's roster is a membership test
+  and never rotates. The passive `kxm.role.v2` draft already has the
+  better shape (routes with status and fallbacks); activate it rather than
+  invent a new v2. Source: `plans/research-omp-config-schema.md`.
+- **omp has no workflow file.** Its `workflowz` is a prompt contract over
+  an eval kernel. Nothing to port; KXM's workflow file is the stronger
+  model.

package/docs/contributing/operating-rules.md

@@ -0,0 +1,107 @@
+---
+title: "Operating rules"
+description: "Standing instructions from the operator that every agent session on this repository follows, with the date each was given. Read before planning, dispatching, landing, or editing the roadmap."
+audience: "agents and maintainers"
+updated: "2026-09-26"
+---
+
+# Operating rules
+
+These are the operator's standing instructions, recorded so a session does
+not have to be told twice. Each rule names the date it was given and where
+it is enforced. A rule that is retired is deleted, not kept beside its
+replacement.
+
+## Roles and routes
+
+- **The planner does not write product code.** Claude plans, reviews, and
+  lands. The default writer is the native Grok CLI (`grok-4.7`), a starting
+  rotation rather than a sole writer. If Grok is logged out, use a relief
+  route the tracker admits or stop and say what was hit. (`CLAUDE.md`,
+  standing.)
+- **One writer per checkout.** Each unit of work runs in its own lane
+  worktree (`kxm lane create <unit>`). Two writers in one tree clobber each
+  other. (2026-09-25.)
+
+## Landing
+
+- **Every PR is landed without asking.** Once a PR is open: monitor it,
+  rebase onto `main` when it falls behind, resolve conflicts and blockers,
+  merge, and follow through to the auto-release tag and the npm publish.
+  Report the outcome; do not stop to ask for the merge. Enforced by
+  `kxm land` (verify, docs, push, pr, rebase, unblock, merge, release,
+  milestone) and, until every stage is proven, by hand. (2026-09-26.)
+- **Documentation is regenerated after a green pipeline and before the
+  merge.** The `docs` stage of `kxm land` runs the roadmap generator and
+  commits the regenerated pages on the branch. (2026-09-26.)
+- **After every phase or milestone, the intense pass runs, not the
+  refresh.** `/reanalyze-roadmap` (the `kxm-roadmap-review` skill with its
+  read-only critic), triggered by the `milestone` stage reporting
+  `deep_review_required`. (2026-09-26.)
+- **`npm run verify` stays the pre-push gate.** It is the first stage of
+  landing and is never replaced by it. CI's validate leg runs the same
+  script. (2026-09-26.)
+- **After every publish, the workflow runs on the improvements it just
+  landed.** `kxm update --kxm`, then `kxm update --extensions`, then
+  `kxm plugin install --all`, so the CLI and the kxm plugin in pi, omp, and
+  Claude Code are current; the Claude Code session then needs
+  `/reload-plugins`, which only the operator can run. The supervisor tick
+  does this after any `PUBLISHED` line. (2026-09-26.)
+
+## Entry points
+
+- **No new just recipes.** The repository is migrating off `just`. A needed
+  entry point is a `kxm` command: a group under `plugins/kxm/src/cli/`,
+  registered in `cli.ts`, owned by a bundled skill so `check:generated`
+  passes, documented in the CLI reference. Existing recipes retire as their
+  `kxm` verbs land; the transport recipes (`impl`, `plan`, `review-*`,
+  `impl-bg`) retire last, after one real unit has run through the one-step
+  workflows. (2026-09-26.)
+
+## Decisions and debt
+
+- **Every option comes with pros and cons and two recommendations**, the
+  solid-product answer and the interim answer. (2026-09-26.)
+- **Every shortcut goes on the backlog the same turn it is taken**, as an
+  item in `plans/backlog-shortcuts.md` with what was skipped and the proper
+  fix. (2026-09-26.)
+
+## Roadmap and plan content
+
+- **No stale data.** A fact that no longer holds is replaced, never kept
+  beside its replacement.
+- **History is brief.** One short line per material change, capped by the
+  generator; never a running narrative.
+- **No stale contacts.** A contact carries a role and a confirmation date;
+  unconfirmed past 90 days is dropped. Empty is fine.
+- **Present and upcoming only.** Superseded material leaves the roadmap.
+- **Progressive detail.** A far-off phase or task is brief but complete
+  (goal, scope, done criterion, evidence needed) and gains detail as it
+  nears implementation. A task cannot be `ready` without a template and a
+  source.
+- **Tasks use the artifact templates** under `docs/templates/`.
+
+All six enforced by the `kxm.roadmap.v1` schema, the generator's semantic
+refusals, and the two roadmap skills. (2026-09-26.)
+
+## Monitoring
+
+- **Background monitors emit progress, not only results**, in this line
+  form: `[{lane}/{agent}]: {phrase}. {No action|Review needed}. -
+  {E}e|{D}d ({M}m{S}s)`. Routine lines are not echoed back in chat.
+  (2026-09-26, formatter at `~/.claude/scripts/evt-monitor.sh`.)
+- **A supervisor tick runs every five minutes** while a session is open:
+  sweep the lanes, act on "Review needed", cap concurrent verifies at two,
+  regenerate the roadmap after a merge, and run the improvement loop every
+  sixth tick. Its prompt is checked in at
+  `plans/kxm-roadmap/supervisor-prompt.md`; a tick that finds the schedule
+  missing or expiring recreates it from that file in the same chat session,
+  never a new one, so the loop continues under the same task. (2026-09-26.)
+
+## Where the same rules live for agents
+
+The session memory under `~/.claude/projects/…/memory/` mirrors these as
+`pr-landing-autonomy`, `pipeline-docs-then-merge`, `no-just-prefer-kxm-cli`,
+`decisions-pros-cons-backlog`, `roadmap-editorial-rules`, and
+`monitor-progress-events`. This page is the checked-in copy; when the two
+disagree, this page is updated and the memory follows.

package/package.json

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

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

@@ -17313,7 +17313,7 @@ function sessionTokenFixHint(policy) {
 }
 
 // plugins/kxm/src/mcp-server.ts
-var VERSION = "0.7.125";
+var VERSION = "0.7.126";
 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.125",
+  "version": "0.7.126",
   "private": true,
   "type": "module",
   "engines": {

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