@kontextmind/kxm 0.7.188 → 0.7.189

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

package/docs/contributing/ci-and-release.md

@@ -39,7 +39,7 @@ together.
 |---|---|---|
 | Before you push | Local | `npm run verify` |
 | Pull request, push to `main`, or manual | `ci.yml` (`required`) | Aggregates the lanes below into one pass/fail check named `CI / required` |
-| Pull request and push | `ci.yml` (Docs lint) | `lint:docs` and `check:versions`, always |
+| Pull request and push | `ci.yml` (Docs lint) | `lint:docs` (markdownlint and the `plans/` relative-link check) and `check:versions`, always |
 | Code pull request and code push | `ci.yml` (Unit engine and Unit, Linux Node 24) | `engine.test.ts` split by test name; `permission.test.ts`, `runtime.test.ts`, and `package-install.test.ts` one file at a time; every other unit file in two light shards. Typecheck and `check-generated` run on `light-1` |
 | Code pull request and code push | `ci.yml` (Python control plane) | Python 3.13 `unittest` contracts from the frozen uv workspace against PostgreSQL 17 started by `scripts/ci-postgres-17.sh` |
 | Platform-sensitive pull request | `ci.yml` (Unit, Windows Node 24) | The same unit lanes on `windows-latest` |

package/docs/contributing/development.md

@@ -255,7 +255,7 @@ It runs three scripts in order:
 | Step | Script | What it checks |
 |---|---|---|
 | 1 | `npm test` | Build, then `test/core/*.test.ts` and `packages/core/*/tests/unit/*.test.ts`. The script passes `--test-force-exit` so a finished run leaves the process even if a handle is still open; a failing test is still reported before that exit |
-| 2 | `npm run check` | `tsc --noEmit`, `markdownlint-cli2`, and version surfaces |
+| 2 | `npm run check` | `tsc --noEmit`, markdownlint, the `plans/` relative-link check, and version surfaces |
 | 3 | `npm run check:generated` | Generated artifacts are tracked and match the staged copy |
 
 Changes to the Python control plane also run its frozen-workspace contract
@@ -303,7 +303,7 @@ Other scripts you will use:
 | `npm run test:simulations` | `test/simulations/*.test.ts` |
 | `npm run test:coverage` | Core suite with coverage floors |
 | `npm run test:coverage:complete` | Core plus simulations with the higher nightly floors |
-| `npm run lint:docs` | Markdown lint only |
+| `npm run lint:docs` | Markdown lint, then the `plans/` relative-link and heading check |
 | `npm run e2e` | Start Obscura if needed, then Playwright in `test/e2e/` (`node --test` does not collect that directory) |
 | `npm run validate:pr` | The three-minute CI gate; see [CI and release](ci-and-release.md) |
 | `npm run validate:ci` | Coverage suite, `check` and a package dry run (not run by CI today) |

package/docs/contributing/writing-docs.md

@@ -297,8 +297,15 @@ exist only in prose, never in command form.
 
 ### Check links
 
-No CI job checks links yet. Before you open a pull request, run this check on
-the files you changed; it prints each relative link whose target is missing:
+`npm run lint:docs` runs markdownlint, then `scripts/check-plan-links.mjs`.
+That script checks every Markdown link under `plans/`. A relative target has
+to exist. A `#heading` on a Markdown file has to match a heading in that
+file. `related` entries in plan front matter are checked the same way, relative
+to the file. Docs lint runs this on every pull request.
+
+For a page outside `plans/`, run this check on the files you changed. It
+prints each relative link whose target is missing, and it does not check
+anchors:
 
 ```bash
 node --input-type=module -e '

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kontextmind/kxm",
-  "version": "0.7.188",
+  "version": "0.7.189",
   "description": "KXM local-first multi-agent orchestration and operator dashboard",
   "type": "module",
   "author": "KontextMind",
@@ -44,7 +44,7 @@
     "test:coverage:complete": "npm run build && node scripts/run-bounded.mjs 2400000 node --disable-warning=ExperimentalWarning --experimental-strip-types --test --test-force-exit --test-concurrency=4 --experimental-test-coverage --test-coverage-lines=93 --test-coverage-branches=80 --test-coverage-functions=93 --test-coverage-include=plugins/kxm/src/**/*.ts --test-coverage-exclude=plugins/kxm/src/server.ts --test-coverage-exclude=plugins/kxm/src/mcp-server.ts --test-coverage-exclude=plugins/kxm/src/runtime-supervisor.ts --test-coverage-include=packages/core/*/src/**/*.ts test/core/*.test.ts test/simulations/*.test.ts packages/core/*/tests/unit/*.test.ts",
     "test:coverage": "npm run test:coverage:core",
     "typecheck": "tsc --noEmit",
-    "lint:docs": "markdownlint-cli2",
+    "lint:docs": "markdownlint-cli2 && node scripts/check-plan-links.mjs",
     "check:versions": "node scripts/check-versions.mjs",
     "check": "npm run typecheck && npm run lint:docs && npm run check:versions && node scripts/workforce-lint.mjs",
     "verify": "npm test && npm run check && npm run check:generated",

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.188",
+  "version": "0.7.189",
   "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

@@ -25462,7 +25462,7 @@ function sessionTokenFixHint(policy) {
 }
 
 // plugins/kxm/src/mcp-server.ts
-var VERSION = "0.7.188";
+var VERSION = "0.7.189";
 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.188",
+  "version": "0.7.189",
   "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.188";
+const VERSION = "0.7.189";
 const CONFIGURE_PLUGIN = "/plugin configure kxm@kxm";
 const inbox = new Map<string, MessageRecord>();
 const notifiedInbox = new Set<string>();

package/scripts/check-plan-links.d.mts

@@ -0,0 +1,4 @@
+export function githubSlug(value: string): string;
+export function headingIds(markdown: string): Set<string>;
+export function checkFile(file: string): string[];
+export function checkPlans(root?: string): string[];

package/scripts/check-plan-links.mjs

@@ -0,0 +1,234 @@
+#!/usr/bin/env node
+
+// Relative links and heading anchors under plans/.
+// Docs lint runs this. It does not call the network.
+
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const repoRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+
+export function githubSlug(value) {
+  return value.toLowerCase().replace(/[^\p{L}\p{M}\p{N}\p{Pc}\- ]/gu, "").replace(/ /g, "-");
+}
+
+function headingText(raw) {
+  let text = raw.trim().replace(/\s+#+\s*$/, "");
+  text = text.replace(/!\[([^\]]*)\]\([^)]*\)/g, "$1");
+  text = text.replace(/\[([^\]]*)\]\([^)]*\)/g, "$1");
+  text = text.replace(/<([^>\s]+)>/g, "$1");
+  text = text.replace(/`([^`]*)`/g, "$1");
+  text = text.replace(/<\/?[^>]+>/g, "");
+  text = text.replace(/&amp;/g, "&").replace(/&lt;/g, "<").replace(/&gt;/g, ">");
+  text = text.replace(/&quot;/g, '"').replace(/&#39;/g, "'");
+  return text;
+}
+
+export function headingIds(markdown) {
+  const lines = markdown.split("\n");
+  const ids = new Set();
+  const occurrences = Object.create(null);
+  const own = Object.hasOwnProperty;
+  let index = 0;
+  let fence = null;
+  if (lines[0]?.trim() === "---") {
+    index = 1;
+    while (index < lines.length && lines[index].trim() !== "---") index += 1;
+    index += 1;
+  }
+  function addSlug(text) {
+    const original = githubSlug(headingText(text));
+    let result = original;
+    while (own.call(occurrences, result)) {
+      occurrences[original] = (occurrences[original] || 0) + 1;
+      result = `${original}-${occurrences[original]}`;
+    }
+    occurrences[result] = 0;
+    ids.add(result);
+  }
+  for (; index < lines.length; index += 1) {
+    const line = lines[index];
+    const opened = line.match(/^ {0,3}(`{3,}|~{3,})/);
+    if (opened && !fence) {
+      fence = opened[1];
+      continue;
+    }
+    if (fence && new RegExp(`^ {0,3}${fence[0]}{${fence.length},}\\s*$`).test(line)) {
+      fence = null;
+      continue;
+    }
+    if (fence) continue;
+    const atx = line.match(/^(#{1,6})\s+(.+?)\s*$/);
+    if (atx) addSlug(atx[2]);
+    for (const match of line.matchAll(/\sid=["']([^"']+)["']/g)) ids.add(match[1]);
+    for (const match of line.matchAll(/\sname=["']([^"']+)["']/g)) ids.add(match[1]);
+  }
+  return ids;
+}
+
+function visibleLines(markdown) {
+  const lines = markdown.split("\n");
+  const visible = [];
+  let fence = null;
+  let comment = false;
+  for (const line of lines) {
+    if (!fence && !comment) {
+      const opened = line.match(/^ {0,3}(`{3,}|~{3,})/);
+      if (opened) {
+        fence = opened[1];
+        visible.push("");
+        continue;
+      }
+    }
+    if (fence) {
+      if (new RegExp(`^ {0,3}${fence[0]}{${fence.length},}\\s*$`).test(line)) fence = null;
+      visible.push("");
+      continue;
+    }
+    let rest = line;
+    let kept = "";
+    while (rest.length > 0) {
+      if (comment) {
+        const end = rest.indexOf("-->");
+        if (end < 0) {
+          rest = "";
+          break;
+        }
+        comment = false;
+        rest = rest.slice(end + 3);
+        continue;
+      }
+      const start = rest.indexOf("<!--");
+      if (start < 0) {
+        kept += rest;
+        rest = "";
+        break;
+      }
+      kept += rest.slice(0, start);
+      rest = rest.slice(start + 4);
+      comment = true;
+    }
+    visible.push(kept);
+  }
+  return visible;
+}
+
+function destinationOf(raw) {
+  let dest = raw.trim();
+  if (dest.startsWith("<") && dest.endsWith(">")) dest = dest.slice(1, -1).trim();
+  dest = dest.replace(/\s+"[^"]*"$/, "").replace(/\s+'[^']*'$/, "");
+  return dest;
+}
+
+function problemsForDestination(file, lineNumber, dest) {
+  if (!dest || /^[a-z][a-z0-9+.-]*:/i.test(dest)) return [];
+  if (dest.startsWith("//")) return [];
+  if (dest.startsWith("/")) {
+    return [`${file}:${lineNumber}: absolute path is not a repository link: ${dest}`];
+  }
+  const hash = dest.indexOf("#");
+  let pathPart = hash >= 0 ? dest.slice(0, hash) : dest;
+  const frag = hash >= 0 ? dest.slice(hash + 1) : "";
+  pathPart = pathPart.split("?")[0];
+  let decodedPath = pathPart;
+  let decodedFrag = frag;
+  try { decodedPath = decodeURIComponent(pathPart); } catch { /* keep raw */ }
+  try { decodedFrag = decodeURIComponent(frag); } catch { /* keep raw */ }
+  if (!decodedPath) {
+    if (!decodedFrag) return [];
+    const ids = headingIds(readFileSync(file, "utf8"));
+    if (!ids.has(decodedFrag)) return [`${file}:${lineNumber}: missing anchor #${decodedFrag}`];
+    return [];
+  }
+  const target = resolve(dirname(file), decodedPath);
+  if (!existsSync(target)) return [`${file}:${lineNumber}: missing ${dest}`];
+  if (decodedFrag && target.endsWith(".md")) {
+    const ids = headingIds(readFileSync(target, "utf8"));
+    if (!ids.has(decodedFrag)) return [`${file}:${lineNumber}: missing anchor ${dest}`];
+  }
+  return [];
+}
+
+function relatedProblems(file, markdown) {
+  if (!markdown.startsWith("---\n")) return [];
+  const end = markdown.indexOf("\n---", 4);
+  if (end < 0) return [];
+  const front = markdown.slice(4, end).split("\n");
+  const problems = [];
+  let inRelated = false;
+  for (let index = 0; index < front.length; index += 1) {
+    const line = front[index];
+    const inline = line.match(/^related:\s*\[(.*)\]\s*$/);
+    if (inline) {
+      for (const item of inline[1].split(",")) {
+        const rel = item.trim().replace(/^["']|["']$/g, "");
+        if (!rel || /^[a-z][a-z0-9+.-]*:/i.test(rel)) continue;
+        if (!existsSync(resolve(dirname(file), rel))) {
+          problems.push(`${file}:${index + 2}: missing related ${rel}`);
+        }
+      }
+      continue;
+    }
+    if (/^related:\s*$/.test(line)) {
+      inRelated = true;
+      continue;
+    }
+    if (inRelated && /^\S/.test(line)) inRelated = false;
+    if (!inRelated) continue;
+    const item = line.match(/^\s+-\s+(.+?)\s*$/);
+    if (!item) continue;
+    const rel = item[1].replace(/^["']|["']$/g, "");
+    if (/^[a-z][a-z0-9+.-]*:/i.test(rel)) continue;
+    if (!existsSync(resolve(dirname(file), rel))) {
+      problems.push(`${file}:${index + 2}: missing related ${rel}`);
+    }
+  }
+  return problems;
+}
+
+const linkRe = /(!?\[[^\]\n]*\])\(([^)\n]+)\)/g;
+// Footnote bodies (`[^id]: prose`) are not link destinations. The URL inside
+// the body is an ordinary inline link.
+const refRe = /^ {0,3}\[([^\]^\n][^\]]*)\]:\s+(\S+)/;
+
+export function checkFile(file) {
+  const markdown = readFileSync(file, "utf8");
+  const problems = relatedProblems(file, markdown);
+  const lines = visibleLines(markdown);
+  for (let index = 0; index < lines.length; index += 1) {
+    const line = lines[index];
+    for (const match of line.matchAll(linkRe)) {
+      problems.push(...problemsForDestination(file, index + 1, destinationOf(match[2])));
+    }
+    const ref = line.match(refRe);
+    if (ref) problems.push(...problemsForDestination(file, index + 1, destinationOf(ref[2])));
+  }
+  return problems;
+}
+
+function walk(dir, out = []) {
+  for (const name of readdirSync(dir)) {
+    const path = join(dir, name);
+    if (statSync(path).isDirectory()) walk(path, out);
+    else if (name.endsWith(".md")) out.push(path);
+  }
+  return out;
+}
+
+export function checkPlans(root = repoRoot) {
+  const dir = join(root, "plans");
+  return walk(dir).flatMap((file) => checkFile(file));
+}
+
+function main() {
+  const problems = checkPlans();
+  for (const problem of problems) console.error(problem);
+  if (problems.length > 0) {
+    console.error(`check-plan-links: ${problems.length} broken`);
+    process.exit(1);
+  }
+}
+
+const invoked = process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+if (invoked) main();