@kontextmind/kxm 0.7.145 → 0.7.147

package/plugins/kxm/src/project-config.ts

@@ -11,6 +11,7 @@ import {
 } from "./restricted-yaml.mjs";
 import { pathToFileURL } from "node:url";
 import { validatePolicyDraft } from "./policy-draft.mjs";
+import { findYamlBasename, lintWorkforce, lookupById, noteDeprecatedId, STEP_RENAMES } from "./workforce-names.mjs";
 import { resolveKxmTemplateBaseline } from "./template.ts";
 import { findKxmRepoRoot } from "./repo-root.ts";
 import { BUILTIN_HARNESS_IDS, DEFAULT_HARNESS } from "./harness.ts";
@@ -590,6 +591,20 @@ function names(value: JsonValue | undefined): string[] {
   return Array.isArray(value) ? value.filter((candidate): candidate is string => typeof candidate === "string") : [];
 }
 
+/** Resolve an agent, workflow, or route, including a deprecated alias. */
+export function lookupKxmResource<T extends { id?: string; value: JsonObject }>(
+  resources: Iterable<T>,
+  requested: string,
+  kind: "agent" | "workflow" | "route",
+): T | undefined {
+  const records = [...resources].map((resource) => ({
+    id: resource.id,
+    aliases: names(resource.value.aliases),
+    resource,
+  }));
+  return lookupById(records, requested, kind)?.record.resource;
+}
+
 function mapResource(resource: KxmResource, map: Map<string, KxmResource>, issues: KxmConfigIssue[]): void {
   const id = resource.id;
   if (!id) return;
@@ -872,14 +887,31 @@ function validateWorkflow(
 ): void {
   const file = workflow.logicalPath;
   const coordinator = stringValue(workflow.value.coordinator) ?? "coordinator";
-  if (!agents.has(coordinator)) issues.push(issue("reference", "coordinator_unknown", file, `coordinator ${coordinator} does not exist`));
+  if (!lookupKxmResource(agents.values(), coordinator, "agent")) issues.push(issue("reference", "coordinator_unknown", file, `coordinator ${coordinator} does not exist`));
   const steps = valuesOf(workflow.value, "steps").map((candidate) => objectValue(candidate)).filter((candidate): candidate is JsonObject => Boolean(candidate));
   const stepIndex = new Map<string, number>();
+  const primarySteps = new Set<string>();
   for (const [index, step] of steps.entries()) {
     const id = stringValue(step.id);
     if (!id) continue;
     if (stepIndex.has(id)) issues.push(issue("semantic", "step_id_duplicate", file, `step ${id} is duplicated`));
-    else stepIndex.set(id, index);
+    else {
+      stepIndex.set(id, index);
+      primarySteps.add(id);
+    }
+  }
+  for (const [index, step] of steps.entries()) {
+    const id = stringValue(step.id);
+    if (!id) continue;
+    const aliases = new Set(names(step.aliases));
+    for (const [oldId, newId] of STEP_RENAMES) {
+      if (id === newId) aliases.add(oldId);
+      if (id === oldId) aliases.add(newId);
+    }
+    for (const alias of aliases) {
+      if (alias === id || primarySteps.has(alias) || stepIndex.has(alias)) continue;
+      stepIndex.set(alias, index);
+    }
   }
 
   for (const field of ["reproOracle", "planHash"] as const) {
@@ -910,7 +942,7 @@ function validateWorkflow(
     const kind = stringValue(step.kind);
     validateToolPolicy(workflow, objectValue(step.tools), `${stepId}.tools`, issues);
     const primaryAgentId = stringValue(step.agent);
-    if ((kind === "agent" || kind === "moa") && primaryAgentId && !agents.has(primaryAgentId)) {
+    if ((kind === "agent" || kind === "moa") && primaryAgentId && !lookupKxmResource(agents.values(), primaryAgentId, "agent")) {
       issues.push(issue("reference", "agent_unknown", file, `${stepId} references unknown agent ${primaryAgentId}`));
     }
     const gate = stringValue(step.gate);
@@ -938,7 +970,7 @@ function validateWorkflow(
     const declaredAgents = assignment ? names(assignment.allowedAgents) : [];
     const allowedAgents = declaredAgents.length > 0 ? declaredAgents : primaryAgentId ? [primaryAgentId] : [];
     for (const agentId of allowedAgents) {
-      const agent = agents.get(agentId);
+      const agent = lookupKxmResource(agents.values(), agentId, "agent");
       if (!agent) issues.push(issue("reference", "assignment_agent_unknown", file, `${stepId} allows unknown agent ${agentId}`));
       else {
         validateAgentScope(agent, step, repositories, file, stepId, issues);
@@ -1003,7 +1035,7 @@ function validateWorkflow(
       const producerMinimum = numberValue(policy.minimumProducers, 1);
       if (producerMinimum > target || producerMinimum > eligible.length) issues.push(issue("semantic", "producer_minimum_impossible", file, `${stepId}.${String(key)} producer minimum exceeds its eligible or target pool`));
       for (const agentId of eligible) {
-        if (!agents.has(agentId)) issues.push(issue("reference", "producer_agent_unknown", file, `${stepId}.${String(key)} references unknown producer ${agentId}`));
+        if (!lookupKxmResource(agents.values(), agentId, "agent")) issues.push(issue("reference", "producer_agent_unknown", file, `${stepId}.${String(key)} references unknown producer ${agentId}`));
         if (allowedAgents.length > 0 && !allowedAgents.includes(agentId)) issues.push(issue("semantic", "producer_agent_ineligible", file, `${stepId}.${String(key)} producer ${agentId} is outside allowedAgents`));
       }
       const degradation = objectValue(policy.degradation);
@@ -1026,6 +1058,10 @@ function validateWorkflow(
         if (parsed.terminalStatus === "completed") completedTerminalSources.add(index);
         continue;
       }
+      if (parsed.target && parsed.target !== "$terminal" && !primarySteps.has(parsed.target) && stepIndex.has(parsed.target)) {
+        const canonical = stringValue(steps[stepIndex.get(parsed.target) ?? -1]?.id);
+        if (canonical) noteDeprecatedId("step", parsed.target, canonical);
+      }
       const targetIndex = parsed.target === undefined ? undefined : stepIndex.get(parsed.target);
       if (targetIndex === undefined) {
         issues.push(issue("reference", "transition_target_unknown", file, `${stepId}.${outcome} references unknown target ${String(parsed.target)}`));
@@ -1195,7 +1231,7 @@ function validateBundle(
   validateModelReferences(models, issues);
 
   const defaultWorkflow = stringValue(project.value.defaultWorkflow) ?? "default";
-  if (!workflows.has(defaultWorkflow)) issues.push(issue("reference", "default_workflow_unknown", project.logicalPath, `default workflow ${defaultWorkflow} does not exist`));
+  if (!lookupKxmResource(workflows.values(), defaultWorkflow, "workflow")) issues.push(issue("reference", "default_workflow_unknown", project.logicalPath, `default workflow ${defaultWorkflow} does not exist`));
   for (const workflow of workflows.values()) validateWorkflow(workflow, agents, models, repositoryIds, gates, issues);
 
   // Developer policy is the role files under .kxm/roles/ (with the model
@@ -1220,8 +1256,9 @@ function rosterModelIssues(projectRoot: string, roles: ReadonlyMap<string, KxmRe
     for (const entry of valuesOf(role.value, "roster")) {
       const route = stringValue(objectValue(entry)?.route);
       if (!route) continue;
-      const logical = `.kxm/models/${route}.yaml`;
-      const file = join(projectRoot, ".kxm", "models", `${route}.yaml`);
+      const resolved = findYamlBasename(join(projectRoot, ".kxm", "models"), route, "route") ?? route;
+      const logical = `.kxm/models/${resolved}.yaml`;
+      const file = join(projectRoot, ".kxm", "models", `${resolved}.yaml`);
       let harness: string | undefined;
       try {
         if (existsSync(file)) harness = stringValue(parseRestrictedYaml(readFileSync(file, "utf8"), logical).harness);
@@ -1305,6 +1342,7 @@ function developerRolePolicyIssues(projectRoot: string): KxmConfigIssue[] {
   // is this package's developer policy, so it runs when the loaded project
   // is that package.
   if (resolve(projectRoot) !== findKxmRepoRoot(import.meta.url)) return [];
+  const lintIssues = lintWorkforce(projectRoot).errors.map((entry) => issue("semantic", entry.code, entry.file, entry.message));
   const rolesDir = join(projectRoot, ".kxm", "roles");
   const modelsDir = join(projectRoot, ".kxm", "models");
   const roles: Record<string, JsonObject> = {};
@@ -1340,7 +1378,7 @@ function developerRolePolicyIssues(projectRoot: string): KxmConfigIssue[] {
   }
   const ceilings = developerCeilings();
   if (!ceilings.ok) {
-    return [...parseIssues, issue("semantic", "developer_ceilings_unavailable", ".kxm/models", `developer ceilings could not be loaded: ${ceilings.detail}`)];
+    return [...parseIssues, ...lintIssues, issue("semantic", "developer_ceilings_unavailable", ".kxm/models", `developer ceilings could not be loaded: ${ceilings.detail}`)];
   }
   const result = validatePolicyDraft({ models, roles, evidence }, {
     ceilings: ceilings.ROUTES,
@@ -1349,8 +1387,8 @@ function developerRolePolicyIssues(projectRoot: string): KxmConfigIssue[] {
     piNativeVendorProviders: ceilings.PI_NATIVE_VENDOR_PROVIDERS,
     vendorAliases: { "x-ai": "xai", moonshotai: "moonshot", "google-ai": "google", qwen: "alibaba" },
   });
-  if (result.ok) return parseIssues;
-  return [...parseIssues, ...result.issues.map((entry) => issue(entry.phase, entry.code, entry.file, entry.message))];
+  if (result.ok) return [...parseIssues, ...lintIssues];
+  return [...parseIssues, ...lintIssues, ...result.issues.map((entry) => issue(entry.phase, entry.code, entry.file, entry.message))];
 }
 
 export function kxmCanonicalJson(value: JsonValue): string {

package/plugins/kxm/src/runtime-service.ts

@@ -5,6 +5,7 @@ import type { ContextItem } from "./context.ts";
 import {
   KxmConfigError,
   loadKxmProject,
+  lookupKxmResource,
   kxmCanonicalJson,
   type JsonObject,
   type JsonValue,
@@ -402,7 +403,7 @@ export function acceptKxmRun(
   const now = options.now ?? new Date().toISOString();
   const monotonicNs = options.monotonicNs ?? kxmMonotonicNs();
 
-  const workflow = bundle.workflows.get(request.workflowId);
+  const workflow = lookupKxmResource(bundle.workflows.values(), request.workflowId, "workflow");
   if (!workflow) {
     throw runtimeError("run_workflow_unknown", ".kxm/workflows", `workflow ${request.workflowId} does not exist in this project`);
   }

package/plugins/kxm/src/template.ts

@@ -175,35 +175,64 @@ function coreTemplate(projectId: string, projectName: string, variant: KxmTempla
   ]);
   if (variant === "v4-registry") {
     const coordinator = files.get(".kxm/agents/coordinator.yaml");
-    if (coordinator) files.set(".kxm/agents/coordinator.yaml", { ...coordinator, role: "planner" });
+    if (coordinator) {
+      files.delete(".kxm/agents/coordinator.yaml");
+      files.set(".kxm/agents/planner.yaml", { ...coordinator, role: "planner", aliases: ["coordinator"] });
+    }
     const implementer = files.get(".kxm/agents/implementer.yaml");
-    if (implementer) files.set(".kxm/agents/implementer.yaml", { ...implementer, role: "writer" });
+    if (implementer) {
+      files.delete(".kxm/agents/implementer.yaml");
+      files.set(".kxm/agents/writer.yaml", { ...implementer, role: "writer", aliases: ["implementer"] });
+    }
     const workflow = files.get(".kxm/workflows/default.yaml");
     if (workflow) {
       const limits = { ...(workflow.limits as JsonObject) };
       delete limits.maxAgentTimeMs;
-      files.set(".kxm/workflows/default.yaml", { ...workflow, limits });
+      const steps = (workflow.steps as JsonObject[]).map((step) => {
+        if (step.id === "plan") {
+          const on = { ...(step.on as JsonObject), passed: "writer" };
+          return { ...step, agent: "planner", on };
+        }
+        if (step.id === "implement") {
+          const assignments = { ...(step.assignments as JsonObject), allowedAgents: ["writer"] };
+          return { ...step, id: "writer", aliases: ["implement"], agent: "writer", assignments };
+        }
+        if (step.id === "verify") {
+          const on = { ...(step.on as JsonObject) };
+          const failure = on["implementation-failure"];
+          if (failure && typeof failure === "object" && !Array.isArray(failure)) {
+            on["implementation-failure"] = { ...(failure as JsonObject), target: "writer" };
+          }
+          return { ...step, on };
+        }
+        return step;
+      });
+      files.set(".kxm/workflows/default.yaml", { ...workflow, coordinator: "planner", limits, steps });
     }
     // The two models the template names, and nothing else. A fresh project can
     // be driven without falling through to an unadmitted default model.
+    // Route ids follow <harness>-<model-slug>. grok-default and fable-default
+    // remain aliases so an existing --route flag still resolves.
     files.set(".kxm/routes.yaml", {
       schema: "kxm.routes.v2",
-      updatedAt: "2026-09-23T00:00:00.000Z",
+      updatedAt: "2026-09-27T00:00:00.000Z",
       admitted: ["anthropic/fable", "xai/grok-4.6"],
       disabled: [],
     });
-    files.set(".kxm/models/grok-default.yaml", {
+    files.set(".kxm/models/grok-grok-4-6.yaml", {
       schema: "kxm.model.v2",
-      id: "grok-default",
+      id: "grok-grok-4-6",
+      aliases: ["grok-default"],
       harness: "grok",
       model: "grok-4.6",
       vendor: "xai",
       status: "admitted",
       permissions: ["edit"],
     });
-    files.set(".kxm/models/fable-default.yaml", {
+    files.set(".kxm/models/claude-fable.yaml", {
       schema: "kxm.model.v2",
-      id: "fable-default",
+      id: "claude-fable",
+      aliases: ["fable-default"],
       harness: "claude",
       model: "fable",
       vendor: "anthropic",
@@ -216,7 +245,7 @@ function coreTemplate(projectId: string, projectName: string, variant: KxmTempla
       purpose: "writer",
       permission: "edit",
       description: "Primary implementation agent.",
-      roster: [{ route: "grok-default" }],
+      roster: [{ route: "grok-grok-4-6", effort: "medium" }],
     });
     files.set(".kxm/roles/planner.yaml", {
       schema: "kxm.role.v2",
@@ -224,7 +253,7 @@ function coreTemplate(projectId: string, projectName: string, variant: KxmTempla
       purpose: "planner",
       permission: "read-only",
       description: "Plans the change before implementation.",
-      roster: [{ route: "fable-default" }],
+      roster: [{ route: "claude-fable", effort: "medium" }],
     });
     files.set(".kxm/gates.yaml", {
       schema: "kxm.gate-registry.v1",

package/plugins/kxm/src/workflow-manager.ts

@@ -63,23 +63,25 @@ function verifyStep(retryStep: string): Record<string, unknown> {
 /**
  * Built-in `kxm workflow add --template` definitions. Each is a complete
  * kxm.workflow.v1 document (the file name is the workflow id) that uses only
- * what `kxm init` creates: the coordinator and implementer agents, the control
+ * what `kxm init` creates: the planner and writer agents, the control
  * repository, and the `test` gate. Agent steps declare `failed` because the
- * producer falls back to it.
+ * producer falls back to it. `coordinator` and `implementer` still resolve
+ * as aliases of `planner` and `writer`.
  */
 export const WORKFLOW_TEMPLATES: Record<string, Record<string, unknown>> = {
   "implement-and-verify": {
     schema: "kxm.workflow.v1",
-    description: "Implement a change, then run the project's test gate; a failing gate sends the work back to implement.",
-    coordinator: "coordinator",
+    description: "Implement a change, then run the project's test gate; a failing gate sends the work back to writer.",
+    coordinator: "planner",
     limits: {
       maxTransitions: 8,
     },
     steps: [
       {
-        id: "implement",
+        id: "writer",
+        aliases: ["implement"],
         kind: "agent",
-        agent: "implementer",
+        agent: "writer",
         maxAttempts: 3,
         repositories: { control: "write" },
         on: {
@@ -87,57 +89,60 @@ export const WORKFLOW_TEMPLATES: Record<string, Record<string, unknown>> = {
           failed: failed(),
         },
       },
-      verifyStep("implement"),
+      verifyStep("writer"),
     ],
   },
   "dual-critic-review": {
     schema: "kxm.workflow.v1",
-    description: "Implement, review twice, then run the project's test gate. Both reviews run as the coordinator agent; for independent critics, add agents under .kxm/agents and point review-arch and review-cli at them.",
-    coordinator: "coordinator",
+    description: "Write, review twice, then run the project's test gate. Both reviews run as the planner agent; for independent reviewers, add reviewer-arch and reviewer-cli agents and point the review steps at them.",
+    coordinator: "planner",
     limits: {
       maxTransitions: 12,
     },
     steps: [
       {
-        id: "implement",
+        id: "writer",
+        aliases: ["implement"],
         kind: "agent",
-        agent: "implementer",
+        agent: "writer",
         maxAttempts: 3,
         repositories: { control: "write" },
         on: {
-          passed: "review-arch",
+          passed: "reviewer-arch",
           failed: failed(),
         },
       },
       {
-        id: "review-arch",
+        id: "reviewer-arch",
+        aliases: ["review-arch", "critic-arch"],
         kind: "agent",
-        agent: "coordinator",
+        agent: "planner",
         maxAttempts: 3,
         repositories: { control: "read" },
         on: {
-          passed: "review-cli",
-          failed: { target: "implement", maxTransitions: 2 },
+          passed: "reviewer-cli",
+          failed: { target: "writer", maxTransitions: 2 },
         },
       },
       {
-        id: "review-cli",
+        id: "reviewer-cli",
+        aliases: ["review-cli", "critic-cli"],
         kind: "agent",
-        agent: "coordinator",
+        agent: "planner",
         maxAttempts: 3,
         repositories: { control: "read" },
         on: {
           passed: "verify",
-          failed: { target: "implement", maxTransitions: 2 },
+          failed: { target: "writer", maxTransitions: 2 },
         },
       },
-      verifyStep("implement"),
+      verifyStep("writer"),
     ],
   },
   "spec-and-plan": {
     schema: "kxm.workflow.v1",
-    description: "Plan a change, then review the plan. Both steps run as the coordinator agent and only read the repository.",
-    coordinator: "coordinator",
+    description: "Plan a change, then review the plan. Both steps run as the planner agent and only read the repository.",
+    coordinator: "planner",
     limits: {
       maxTransitions: 8,
     },
@@ -145,18 +150,19 @@ export const WORKFLOW_TEMPLATES: Record<string, Record<string, unknown>> = {
       {
         id: "plan",
         kind: "agent",
-        agent: "coordinator",
+        agent: "planner",
         maxAttempts: 3,
         repositories: { control: "read" },
         on: {
-          passed: "review-arch",
+          passed: "reviewer-arch",
           failed: failed(),
         },
       },
       {
-        id: "review-arch",
+        id: "reviewer-arch",
+        aliases: ["review-arch", "critic-arch"],
         kind: "agent",
-        agent: "coordinator",
+        agent: "planner",
         maxAttempts: 3,
         repositories: { control: "read" },
         on: {
@@ -173,13 +179,13 @@ export function scaffoldWorkflowDefinition(description: string): Record<string,
   return {
     schema: "kxm.workflow.v1",
     description,
-    coordinator: "coordinator",
+    coordinator: "planner",
     limits: { maxTransitions: 8 },
     steps: [
       {
         id: "step-1",
         kind: "agent",
-        agent: "implementer",
+        agent: "writer",
         repositories: { control: "write" },
         on: { passed: completed(), failed: failed() },
       },

package/plugins/kxm/src/workforce-names.d.mts

@@ -0,0 +1,38 @@
+export const ROLE_IDS: readonly string[];
+export const ROUTE_RENAMES: readonly (readonly [string, string])[];
+export const AGENT_RENAMES: readonly (readonly [string, string])[];
+export const WORKFLOW_RENAMES: readonly (readonly [string, string])[];
+export const STEP_RENAMES: readonly (readonly [string, string])[];
+
+export function noteDeprecatedId(kind: string, from: string, to: string): void;
+export function resetDeprecatedIdWarnings(): void;
+export function resolveRenamedId(
+  requested: string,
+  knownIds: ReadonlySet<string>,
+  pairs: readonly (readonly [string, string])[],
+): string;
+export function canonicalRouteId(harness: string, model: string): string | undefined;
+
+export function lookupById<T extends { id?: string | undefined; aliases?: readonly string[] | undefined }>(
+  records: Iterable<T>,
+  requested: string,
+  kind: "route" | "agent" | "workflow" | "step",
+): { record: T; viaAlias: boolean } | undefined;
+
+export function findYamlBasename(
+  directory: string,
+  requested: string,
+  kind: "route" | "agent" | "workflow" | "step",
+): string | undefined;
+
+export interface WorkforceLintIssue {
+  severity: "error" | "warning";
+  code: string;
+  file: string;
+  message: string;
+}
+
+export function lintWorkforce(root: string): {
+  errors: WorkforceLintIssue[];
+  warnings: WorkforceLintIssue[];
+};