@kontextmind/kxm 0.7.145 → 0.7.147

package/plugins/kxm/src/workforce-names.mjs

@@ -0,0 +1,317 @@
+/**
+ * Workforce id conventions and rename resolution.
+ *
+ * Role ids are the vocabulary (`planner`, `writer`, `reviewer-arch`,
+ * `reviewer-cli`, `experiment`). Agent ids and agent-step ids use that same
+ * vocabulary. Route ids are `<harness>-<model-slug>[-<provider>]`, with `.`
+ * in the model slug written as `-`. A provider suffix is required when the
+ * model id contains `/`.
+ *
+ * Resolution is bidirectional and only fills a missing side. A commit whose
+ * roles and models still use the old ids keeps matching itself, which is what
+ * the assignment runner reads at one commit. A tree that has already renamed
+ * the files still accepts the old id. A mixed tree accepts either side.
+ * `opus-claude` is not renamed: that route pointed at an unadmitted model and
+ * was removed.
+ */
+
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import YAML from "yaml";
+
+export const ROSTER_EFFORTS = new Set(["off", "minimal", "low", "medium", "high", "xhigh", "max"]);
+
+export const ROLE_IDS = Object.freeze([
+  "writer",
+  "planner",
+  "reviewer-arch",
+  "reviewer-cli",
+  "experiment",
+]);
+
+/** Old id, canonical id. Listed once; lookup tries both directions. */
+export const ROUTE_RENAMES = Object.freeze([
+  ["grok-native", "grok-grok-4-7"],
+  ["qwen-openrouter-pi", "pi-qwen3-coder-plus-openrouter"],
+  ["gemini-agy", "agy-gemini-3-8-flash-high"],
+  ["fable-claude", "claude-fable"],
+  ["sol-codex", "codex-gpt-5-6-sol"],
+  ["grok-default", "grok-grok-4-6"],
+  ["fable-default", "claude-fable"],
+]);
+
+export const AGENT_RENAMES = Object.freeze([
+  ["coordinator", "planner"],
+  ["implementer", "writer"],
+  ["critic-arch", "reviewer-arch"],
+  ["critic-cli", "reviewer-cli"],
+]);
+
+export const WORKFLOW_RENAMES = Object.freeze([
+  ["implement-only", "writer-only"],
+  ["review-arch-only", "reviewer-arch-only"],
+  ["review-cli-only", "reviewer-cli-only"],
+]);
+
+export const STEP_RENAMES = Object.freeze([
+  ["implement", "writer"],
+  ["critic-arch", "reviewer-arch"],
+  ["review-arch", "reviewer-arch"],
+  ["critic-cli", "reviewer-cli"],
+  ["review-cli", "reviewer-cli"],
+]);
+
+const RENAMES = Object.freeze({
+  route: ROUTE_RENAMES,
+  agent: AGENT_RENAMES,
+  workflow: WORKFLOW_RENAMES,
+  step: STEP_RENAMES,
+});
+
+const RESERVED_WORKFLOW_IDS = new Set(["default", "land"]);
+const warned = new Set();
+
+export function noteDeprecatedId(kind, from, to) {
+  const key = `${kind}\0${from}\0${to}`;
+  if (warned.has(key)) return;
+  warned.add(key);
+  if (process.env.KXM_QUIET_ALIASES === "1") return;
+  console.warn(`kxm: deprecated ${kind} id '${from}' resolves to '${to}'`);
+}
+
+export function resetDeprecatedIdWarnings() {
+  warned.clear();
+}
+
+export function resolveRenamedId(requested, knownIds, pairs) {
+  if (typeof requested !== "string" || knownIds.has(requested)) return requested;
+  for (const [oldId, newId] of pairs) {
+    if (requested === oldId && knownIds.has(newId)) return newId;
+    if (requested === newId && knownIds.has(oldId)) return oldId;
+  }
+  return requested;
+}
+
+export function canonicalRouteId(harness, model) {
+  if (typeof harness !== "string" || typeof model !== "string" || !harness || !model) return undefined;
+  const parts = model.split("/").filter((part) => part.length > 0);
+  if (parts.length === 0) return undefined;
+  const slug = parts[parts.length - 1].replaceAll(".", "-").toLowerCase();
+  const provider = parts.length > 1 ? parts[0].replaceAll(".", "-").toLowerCase() : undefined;
+  const id = provider ? `${harness}-${slug}-${provider}` : `${harness}-${slug}`;
+  return /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/u.test(id) && id.length <= 64 ? id : undefined;
+}
+
+function aliasList(value) {
+  return Array.isArray(value) ? value.filter((item) => typeof item === "string") : [];
+}
+
+/**
+ * @param {Iterable<{ id?: string, aliases?: readonly string[] }>} records
+ * @param {string} requested
+ * @param {"route"|"agent"|"workflow"|"step"} kind
+ */
+export function lookupById(records, requested, kind) {
+  const list = [...records].filter((record) => typeof record?.id === "string" && record.id.length > 0);
+  const known = new Set(list.map((record) => record.id));
+  const direct = list.find((record) => record.id === requested);
+  if (direct) return { record: direct, viaAlias: false };
+  for (const record of list) {
+    if (aliasList(record.aliases).includes(requested)) {
+      noteDeprecatedId(kind, requested, record.id);
+      return { record, viaAlias: true };
+    }
+  }
+  const renamed = resolveRenamedId(requested, known, RENAMES[kind] ?? []);
+  if (renamed !== requested) {
+    const record = list.find((item) => item.id === renamed);
+    if (record) {
+      noteDeprecatedId(kind, requested, renamed);
+      return { record, viaAlias: true };
+    }
+  }
+  return undefined;
+}
+
+export function findYamlBasename(directory, requested, kind) {
+  if (typeof requested !== "string" || !requested) return undefined;
+  if (existsSync(join(directory, `${requested}.yaml`))) return requested;
+  if (!existsSync(directory)) return undefined;
+  const found = [];
+  for (const name of readdirSync(directory)) {
+    if (!name.endsWith(".yaml") || name === "inventory.yaml") continue;
+    const id = name.slice(0, -5);
+    let doc;
+    try {
+      doc = YAML.parse(readFileSync(join(directory, name), "utf8"));
+    } catch {
+      continue;
+    }
+    const aliases = doc && typeof doc === "object" ? aliasList(doc.aliases) : [];
+    found.push({ id, aliases });
+  }
+  const hit = lookupById(found, requested, kind);
+  return hit?.record.id;
+}
+
+function readYamlDir(directory, skipInventory) {
+  if (!existsSync(directory)) return [];
+  const docs = [];
+  for (const name of readdirSync(directory)) {
+    if (!name.endsWith(".yaml")) continue;
+    const id = name.slice(0, -5);
+    if (skipInventory && id === "inventory") continue;
+    let doc;
+    try {
+      doc = YAML.parse(readFileSync(join(directory, name), "utf8"));
+    } catch (error) {
+      docs.push({ id, file: `${directory}/${name}`, error: error instanceof Error ? error.message : "invalid YAML" });
+      continue;
+    }
+    if (!doc || typeof doc !== "object" || Array.isArray(doc)) {
+      docs.push({ id, file: `${directory}/${name}`, error: "root must be a mapping" });
+      continue;
+    }
+    docs.push({ id, file: name, doc });
+  }
+  return docs;
+}
+
+function push(bucket, severity, code, file, message) {
+  bucket.push({ severity, code, file, message });
+}
+
+function selectorsFor(doc) {
+  const model = typeof doc.model === "string" ? doc.model : "";
+  const vendor = typeof doc.vendor === "string" ? doc.vendor : "";
+  const harness = typeof doc.harness === "string" ? doc.harness : "";
+  return [model, vendor && model ? `${vendor}/${model}` : "", harness && model ? `${harness}/${model}` : ""].filter(Boolean);
+}
+
+/**
+ * Lint one project's `.kxm` workforce. Errors fail CI. An admitted model with
+ * no route is a warning. Alias declarations are not uses; a roster or step
+ * that still cites an old id is a `deprecated_id` warning.
+ */
+export function lintWorkforce(root) {
+  const errors = [];
+  const warnings = [];
+  const models = readYamlDir(join(root, ".kxm", "models"), true).filter((entry) => !entry.error);
+  for (const entry of readYamlDir(join(root, ".kxm", "models"), true)) {
+    if (entry.error) push(errors, "error", "invalid_yaml", `.kxm/models/${entry.id}.yaml`, entry.error);
+  }
+  const roles = readYamlDir(join(root, ".kxm", "roles"), false).filter((entry) => !entry.error);
+  const agents = readYamlDir(join(root, ".kxm", "agents"), false).filter((entry) => !entry.error);
+  const workflows = readYamlDir(join(root, ".kxm", "workflows"), false).filter((entry) => !entry.error);
+  let admitted = [];
+  const routesFile = join(root, ".kxm", "routes.yaml");
+  if (existsSync(routesFile)) {
+    try {
+      const policy = YAML.parse(readFileSync(routesFile, "utf8"));
+      admitted = Array.isArray(policy?.admitted) ? policy.admitted.filter((item) => typeof item === "string") : [];
+    } catch (error) {
+      push(errors, "error", "invalid_yaml", ".kxm/routes.yaml", error instanceof Error ? error.message : "invalid YAML");
+    }
+  }
+
+  const modelRecords = models.map((entry) => ({ id: entry.id, aliases: aliasList(entry.doc.aliases), entry }));
+  const used = new Set();
+  for (const role of roles) {
+    const purpose = role.doc.purpose;
+    if (typeof purpose === "string" && role.id !== purpose) {
+      push(errors, "error", "role_id_convention", `.kxm/roles/${role.id}.yaml`, `role id '${role.id}' must equal purpose '${purpose}'`);
+    }
+    const roster = Array.isArray(role.doc.roster) ? role.doc.roster : [];
+    for (const item of roster) {
+      if (!item || typeof item !== "object" || Array.isArray(item)) continue;
+      const route = item.route;
+      const effort = item.effort;
+      const routeLabel = typeof route === "string" && route ? route : "(missing route)";
+      if (typeof effort !== "string" || !ROSTER_EFFORTS.has(effort)) {
+        const detail = typeof effort === "string"
+          ? `effort '${effort}' is not one of off, minimal, low, medium, high, xhigh, max`
+          : "has no effort";
+        push(errors, "error", "roster_effort_required", `.kxm/roles/${role.id}.yaml`, `roster route '${routeLabel}' ${detail}`);
+      }
+      if (typeof route !== "string" || !route) continue;
+      const found = lookupById(modelRecords, route, "route");
+      if (!found) {
+        push(errors, "error", "route_unknown", `.kxm/roles/${role.id}.yaml`, `roster route '${route}' does not match a model file`);
+        continue;
+      }
+      used.add(found.record.id);
+      if (found.viaAlias) {
+        push(warnings, "warning", "deprecated_id", `.kxm/roles/${role.id}.yaml`, `roster route '${route}' is a deprecated alias of '${found.record.id}'`);
+      }
+    }
+  }
+
+  const covered = new Set();
+  for (const model of models) {
+    const doc = model.doc;
+    if (typeof doc.id === "string" && doc.id !== model.id) {
+      push(errors, "error", "route_id_convention", `.kxm/models/${model.id}.yaml`, `declared id '${doc.id}' does not match the filename`);
+    }
+    const expected = canonicalRouteId(doc.harness, doc.model);
+    if (!expected || model.id !== expected) {
+      push(errors, "error", "route_id_convention", `.kxm/models/${model.id}.yaml`, `route id '${model.id}' must be '${expected ?? "<harness>-<model-slug>[-<provider>]"}'`);
+    }
+    if (!used.has(model.id)) {
+      push(errors, "error", "route_unused", `.kxm/models/${model.id}.yaml`, `route '${model.id}' is not on any role roster`);
+    }
+    const selectorHit = selectorsFor(doc).find((selector) => admitted.includes(selector));
+    if (!selectorHit) {
+      push(errors, "error", "route_not_admitted", `.kxm/models/${model.id}.yaml`, `model '${doc.model ?? ""}' is not an admitted selector`);
+    } else {
+      covered.add(selectorHit);
+    }
+  }
+  for (const selector of admitted) {
+    if (!covered.has(selector)) {
+      push(warnings, "warning", "admitted_unrouted", ".kxm/routes.yaml", `admitted model '${selector}' is not used by any route`);
+    }
+  }
+
+  const agentRecords = agents.map((entry) => ({ id: entry.id, aliases: aliasList(entry.doc.aliases), entry }));
+  for (const agent of agents) {
+    const role = agent.doc.role;
+    if (typeof role !== "string" || agent.id !== role) {
+      push(errors, "error", "agent_id_convention", `.kxm/agents/${agent.id}.yaml`, `agent id '${agent.id}' must equal its role '${role ?? ""}'`);
+    }
+  }
+  for (const workflow of workflows) {
+    if (!RESERVED_WORKFLOW_IDS.has(workflow.id) && !ROLE_IDS.some((role) => workflow.id === `${role}-only`)) {
+      push(errors, "error", "workflow_id_convention", `.kxm/workflows/${workflow.id}.yaml`, `workflow id '${workflow.id}' must be default, land, or <role>-only`);
+    }
+    const steps = Array.isArray(workflow.doc.steps) ? workflow.doc.steps : [];
+    const realIds = new Set(steps.map((step) => step && typeof step.id === "string" ? step.id : "").filter(Boolean));
+    for (const step of steps) {
+      if (!step || typeof step !== "object" || typeof step.id !== "string") continue;
+      if (step.kind === "agent" || step.kind === "moa") {
+        const agentName = typeof step.agent === "string" ? step.agent : "";
+        const found = agentName ? lookupById(agentRecords, agentName, "agent") : undefined;
+        if (!found) {
+          push(errors, "error", "agent_unknown", `.kxm/workflows/${workflow.id}.yaml`, `step '${step.id}' references unknown agent '${agentName}'`);
+        } else if (found.viaAlias) {
+          push(warnings, "warning", "deprecated_id", `.kxm/workflows/${workflow.id}.yaml`, `step '${step.id}' agent '${agentName}' is a deprecated alias of '${found.record.id}'`);
+        }
+        const role = found?.record.entry.doc.role;
+        if (typeof role === "string" && step.id !== role) {
+          push(errors, "error", "step_id_convention", `.kxm/workflows/${workflow.id}.yaml`, `agent step '${step.id}' must use the role id '${role}'`);
+        }
+      } else if (step.kind === "gate") {
+        const gate = typeof step.gate === "string" ? step.gate : "";
+        const allowed = step.id === "verify" || step.id === gate || step.id.startsWith(`${workflow.id}-`);
+        if (!allowed) {
+          push(errors, "error", "step_id_convention", `.kxm/workflows/${workflow.id}.yaml`, `gate step '${step.id}' must be verify, the gate id, or ${workflow.id}-<name>`);
+        }
+      }
+      for (const alias of aliasList(step.aliases)) {
+        if (realIds.has(alias) && alias !== step.id) {
+          push(errors, "error", "step_id_convention", `.kxm/workflows/${workflow.id}.yaml`, `step alias '${alias}' collides with another step id`);
+        }
+      }
+    }
+  }
+  return { errors, warnings };
+}

package/schemas/agent.schema.json

@@ -13,6 +13,13 @@
     "executor": { "$ref": "common.schema.json#/$defs/identifier" },
     "harness": { "$ref": "common.schema.json#/$defs/identifier" },
     "role": { "$ref": "common.schema.json#/$defs/identifier" },
+    "aliases": {
+      "type": "array",
+      "description": "Deprecated agent ids that still resolve to this file.",
+      "items": { "$ref": "common.schema.json#/$defs/identifier" },
+      "uniqueItems": true,
+      "maxItems": 16
+    },
     "effort": { "enum": ["off", "minimal", "low", "medium", "high", "xhigh", "max"] },
     "skills": {
       "type": "array",

package/schemas/model.schema.json

@@ -14,6 +14,18 @@
       "minLength": 1,
       "maxLength": 64
     },
+    "aliases": {
+      "type": "array",
+      "description": "Deprecated route ids that still resolve to this file. A deprecation warning is printed when one is used.",
+      "items": {
+        "type": "string",
+        "pattern": "^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$",
+        "minLength": 1,
+        "maxLength": 64
+      },
+      "uniqueItems": true,
+      "maxItems": 16
+    },
     "harness": {
       "type": "string",
       "pattern": "^[a-z][a-z0-9]*(?:[-_][a-z0-9]+)*$",

package/schemas/workflow.schema.json

@@ -9,6 +9,13 @@
     "schema": { "const": "kxm.workflow.v1" },
     "description": { "type": "string", "maxLength": 4000 },
     "coordinator": { "$ref": "common.schema.json#/$defs/identifier" },
+    "aliases": {
+      "type": "array",
+      "description": "Deprecated workflow ids that still resolve to this file.",
+      "items": { "$ref": "common.schema.json#/$defs/identifier" },
+      "uniqueItems": true,
+      "maxItems": 16
+    },
     "limits": { "$ref": "#/$defs/workflowLimits" },
     "reproOracle": { "$ref": "#/$defs/oracle" },
     "planHash": { "$ref": "#/$defs/oracle" },
@@ -170,6 +177,13 @@
       "required": ["id", "kind"],
       "properties": {
         "id": { "$ref": "common.schema.json#/$defs/identifier" },
+        "aliases": {
+          "type": "array",
+          "description": "Deprecated step ids that still resolve to this step.",
+          "items": { "$ref": "common.schema.json#/$defs/identifier" },
+          "uniqueItems": true,
+          "maxItems": 16
+        },
         "kind": { "enum": ["agent", "moa", "gate", "approval", "wait"] },
         "description": { "type": "string", "maxLength": 2000 },
         "maxAttempts": { "type": "integer", "minimum": 1, "maximum": 20, "default": 1 },

package/scripts/harness-run.mjs

@@ -153,7 +153,7 @@ export const ROUTES = Object.freeze({
     provider: "anthropic",
     roles: Object.freeze(["planner", "reviewer-arch"]),
     permissions: Object.freeze(["read-only"]),
-    models: Object.freeze(["fable", "opus"]),
+    models: Object.freeze(["fable"]),
     efforts: Object.freeze(["low", "medium", "high", "xhigh", "max"]),
     auth: Object.freeze({ args: ["auth", "status"], loginHint: "claude auth login" }),
   },

package/scripts/native-critic.mjs

@@ -8,12 +8,12 @@ import { buildArgv } from "./harness-run.mjs";
 
 // Launch intent only: these labels are not observed model identity or admission.
 export function nativeCriticLaunch(harness) {
-  if (!["fable", "astra", "opus"].includes(harness)) {
-    throw new Error("usage: native-critic.mjs <fable|astra|opus> <prompt>");
+  if (!["fable", "astra"].includes(harness)) {
+    throw new Error("usage: native-critic.mjs <fable|astra> <prompt>");
   }
-  const model = harness === "fable" ? "fable" : harness === "opus" ? "opus" : "gpt-6-astra";
-  const command = harness === "fable" || harness === "opus" ? "claude" : "codex";
-  const args = harness === "fable" || harness === "opus"
+  const model = harness === "fable" ? "fable" : "gpt-6-astra";
+  const command = harness === "fable" ? "claude" : "codex";
+  const args = harness === "fable"
     ? ["-p", "--model", model, "--effort", "medium", "--output-format", "json", "--no-session-persistence", "--tools", "Read,Glob,Grep", "--setting-sources", "user"]
     : buildArgv({ harness: "codex", model, effort: "low", permission: "read-only", prompt_file: "-" });
   return { model, command, args };

package/scripts/roster-policy.mjs

@@ -6,6 +6,7 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import YAML from 'yaml';
 import { NATIVE_PI_BRAKE_PROVIDERS, PI_ALLOWED_PROVIDERS, PI_ANTIGRAVITY_MODEL_ID, PI_NATIVE_VENDOR_PROVIDERS, ROUTES } from './harness-run.mjs';
+import { lookupById } from '../plugins/kxm/src/workforce-names.mjs';
 
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const MODEL_DIR = '.kxm/models';
@@ -201,12 +202,17 @@ export function assembleRosterPolicy(models, roles) {
     text(role.id, 'role id');
     if (!Array.isArray(role.roster)) refuse('lineup contains unsupported or duplicate values');
     const ids = [];
+    const modelRecords = models
+      .filter((doc) => doc && typeof doc.id === 'string')
+      .map((doc) => ({ id: doc.id, aliases: Array.isArray(doc.aliases) ? doc.aliases : [] }));
     for (const entry of role.roster) {
       record(entry, 'roster entry');
       text(entry.route, 'roster route');
-      ids.push(entry.route);
-      if (!rolesByRoute[entry.route]) rolesByRoute[entry.route] = [];
-      if (!rolesByRoute[entry.route].includes(role.id)) rolesByRoute[entry.route].push(role.id);
+      const resolved = lookupById(modelRecords, entry.route, 'route');
+      const routeId = resolved?.record.id ?? entry.route;
+      ids.push(routeId);
+      if (!rolesByRoute[routeId]) rolesByRoute[routeId] = [];
+      if (!rolesByRoute[routeId].includes(role.id)) rolesByRoute[routeId].push(role.id);
     }
     lineup[role.id] = ids;
   }

package/scripts/workforce-lint.mjs

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+// Fail when this project's workforce ids drift: a route at a non-admitted
+// model, a roster entry with no route file, a route no role uses, or an id
+// that breaks the workforce convention. An admitted model with no route is a
+// warning and does not fail the process.
+
+import { lintWorkforce } from "../plugins/kxm/src/workforce-names.mjs";
+
+const root = process.argv[2] ?? process.cwd();
+const report = lintWorkforce(root);
+for (const item of [...report.errors, ...report.warnings]) {
+  process.stderr.write(`${item.severity} ${item.file}: ${item.code}: ${item.message}\n`);
+}
+if (report.errors.length > 0) {
+  process.stderr.write(`workforce lint failed: ${report.errors.length} error(s), ${report.warnings.length} warning(s)\n`);
+  process.exit(1);
+}
+process.stdout.write(`workforce lint passed (${report.warnings.length} warning(s))\n`);