@kontextmind/kxm 0.7.126 → 0.7.127

package/plugins/kxm/src/role.ts

@@ -1,21 +1,22 @@
 /**
- * KXM Role Management Subsystem (kxm.role.v1).
- * Supports modular per-role YAML files with descriptions, skills, tool permissions, and model rosters.
- * Implements global (~/.config/kxm/roles/) and local (.kxm/roles/) inheritance.
+ * KXM role files (kxm.role.v2).
+ * Global (~/.config/kxm/roles/) and local (.kxm/roles/) files. A local id overrides a global one.
  */
 
 import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
-import { dirname, join, resolve } from "node:path";
+import { join } from "node:path";
 import { parse, stringify } from "yaml";
 import { repoConfigDirectory, userConfigDirectory } from "./config.ts";
 
-export const KXM_ROLE_SCHEMA = "kxm.role.v1" as const;
+export const KXM_ROLE_SCHEMA = "kxm.role.v2" as const;
+
+export type KxmRolePurpose = "writer" | "planner" | "reviewer-arch" | "reviewer-cli" | "experiment";
+export type KxmRolePermission = "edit" | "read-only";
+export type KxmRoleEffort = "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
 
 export interface KxmRosterEntry {
-  harness: string;
-  model: string;
-  provider?: string | undefined;
-  effort?: "low" | "medium" | "high" | "xhigh" | undefined;
+  route: string;
+  effort?: KxmRoleEffort | undefined;
   mode?: "headless" | "interactive" | "either" | undefined;
 }
 
@@ -30,16 +31,26 @@ export interface KxmTemplateContract {
   schema?: string | undefined;
 }
 
+export interface KxmRoleFallback {
+  onError?: Array<"rate_limit" | "transport" | "provider_unavailable"> | undefined;
+  maxSwitches?: number | undefined;
+  revert?: "next_run" | "never" | undefined;
+}
+
 export interface KxmRolePolicy {
   vendorIndependenceRequired?: boolean | undefined;
   maxTransitions?: number | undefined;
   requiresGateVerification?: boolean | undefined;
+  fallback?: KxmRoleFallback | undefined;
 }
 
 export interface KxmRoleDefinition {
   schema: typeof KXM_ROLE_SCHEMA;
   id: string;
+  purpose: KxmRolePurpose;
+  permission: KxmRolePermission;
   description: string;
+  extends?: string | undefined;
   skills?: string[] | undefined;
   tools?: KxmRoleToolPolicy | undefined;
   produces?: KxmTemplateContract[] | undefined;
@@ -50,91 +61,22 @@ export interface KxmRoleDefinition {
 
 export interface KxmRoleSummary {
   id: string;
+  purpose?: KxmRolePurpose | undefined;
+  permission?: KxmRolePermission | undefined;
   description: string;
   scope: "global" | "local" | "overridden";
   filePath: string;
   skills: string[];
   toolsCount: number;
   roster: KxmRosterEntry[];
-  primaryModel?: string | undefined;
-  primaryHarness?: string | undefined;
+  primaryRoute?: string | undefined;
 }
 
-export const DEFAULT_ROLES: Record<string, KxmRoleDefinition> = {
-  writer: {
-    schema: KXM_ROLE_SCHEMA,
-    id: "writer",
-    description: "Primary implementation agent. Writes code, refactors components, and authors unit tests.",
-    skills: ["kxm", "unit-testing"],
-    tools: {
-      preset: "author",
-      allow: ["view_file", "replace_file_content", "write_to_file", "run_command"],
-      deny: ["git push"],
-    },
-    produces: [{ template: "code-patch" }],
-    roster: [
-      { harness: "grok", model: "grok-4.6", effort: "low", mode: "headless" },
-      { harness: "pi", provider: "openrouter", model: "openrouter/qwen/qwen3-coder-plus", effort: "medium" },
-      { harness: "agy", model: "gemini-2.5-pro", effort: "low" },
-    ],
-  },
-  planner: {
-    schema: KXM_ROLE_SCHEMA,
-    id: "planner",
-    description: "Architecture breakdown, requirement decomposition, and safety boundary definition.",
-    skills: ["kxm-session", "architecture-planning"],
-    tools: {
-      preset: "read_only",
-      allow: ["view_file", "grep_search", "find_by_name", "list_dir"],
-      deny: ["write_to_file", "replace_file_content", "run_command"],
-    },
-    produces: [{ template: "implementation-plan" }],
-    roster: [
-      { harness: "claude", model: "fable", effort: "medium" },
-    ],
-  },
-  "critic-arch": {
-    schema: KXM_ROLE_SCHEMA,
-    id: "critic-arch",
-    description: "Independent critic reviewing implementation diffs for architectural integrity and permission boundaries.",
-    policy: { vendorIndependenceRequired: true },
-    tools: {
-      preset: "critic",
-      allow: ["view_file", "grep_search"],
-    },
-    produces: [{ template: "critic-signoff" }],
-    roster: [
-      { harness: "claude", model: "fable", effort: "medium" },
-    ],
-  },
-  "critic-cli": {
-    schema: KXM_ROLE_SCHEMA,
-    id: "critic-cli",
-    description: "CLI, documentation, and developer ergonomics critic.",
-    policy: { vendorIndependenceRequired: true },
-    tools: {
-      preset: "critic",
-      allow: ["view_file", "grep_search"],
-    },
-    produces: [{ template: "critic-signoff" }],
-    roster: [
-      { harness: "codex", model: "gpt-5.6-sol", effort: "low" },
-    ],
-  },
-  verifier: {
-    schema: KXM_ROLE_SCHEMA,
-    id: "verifier",
-    description: "Deterministic gate evaluation runner.",
-    tools: {
-      preset: "verifier",
-      allow: ["run_command"],
-    },
-    produces: [{ template: "verification-receipt" }],
-    roster: [
-      { harness: "pi", model: "evaluator", effort: "low" },
-    ],
-  },
-};
+const ROLE_PURPOSES: readonly KxmRolePurpose[] = ["writer", "planner", "reviewer-arch", "reviewer-cli", "experiment"];
+
+export function rolePurposeForId(id: string): KxmRolePurpose {
+  return (ROLE_PURPOSES as readonly string[]).includes(id) ? id as KxmRolePurpose : "experiment";
+}
 
 export function rolesDirectory(
   scope: "global" | "local",
@@ -159,16 +101,6 @@ export function ensureRolesDirectory(
   return dir;
 }
 
-export function ensureDefaultRoles(userConfigDir?: string): void {
-  const dir = ensureRolesDirectory("global", undefined, userConfigDir);
-  for (const [id, def] of Object.entries(DEFAULT_ROLES)) {
-    const filePath = join(dir, `${id}.yaml`);
-    if (!existsSync(filePath)) {
-      writeFileSync(filePath, stringify(def), "utf8");
-    }
-  }
-}
-
 export function parseRoleFile(filePath: string): KxmRoleDefinition | undefined {
   if (!existsSync(filePath)) return undefined;
   try {
@@ -177,11 +109,16 @@ export function parseRoleFile(filePath: string): KxmRoleDefinition | undefined {
     if (!parsed || typeof parsed !== "object" || parsed.schema !== KXM_ROLE_SCHEMA) {
       return undefined;
     }
-    const id = parsed.id || filePath.replace(/^.*[\\/]/, "").replace(/\.yaml$/i, "");
+    const id = parsed.id || filePath.replace(/^.*[\\/]/, "").replace(/\.ya?ml$/i, "");
+    const purpose = parsed.purpose ?? rolePurposeForId(id);
+    const permission = parsed.permission ?? (purpose === "writer" ? "edit" : "read-only");
     return {
       schema: KXM_ROLE_SCHEMA,
       id,
+      purpose,
+      permission,
       description: parsed.description || "",
+      ...(parsed.extends ? { extends: parsed.extends } : {}),
       skills: Array.isArray(parsed.skills) ? parsed.skills : [],
       tools: parsed.tools,
       produces: parsed.produces,
@@ -238,14 +175,15 @@ export function listRoles(options: {
     const primary = role.roster[0];
     result.push({
       id,
+      purpose: role.purpose,
+      permission: role.permission,
       description: role.description,
       scope: isOverridden ? "overridden" : "local",
       filePath,
       skills: role.skills ?? [],
       toolsCount: (role.tools?.allow?.length ?? 0),
       roster: role.roster,
-      primaryModel: primary?.model,
-      primaryHarness: primary?.harness,
+      primaryRoute: primary?.route,
     });
   }
 
@@ -255,14 +193,15 @@ export function listRoles(options: {
       const primary = role.roster[0];
       result.push({
         id,
+        purpose: role.purpose,
+        permission: role.permission,
         description: role.description,
         scope: "global",
         filePath,
         skills: role.skills ?? [],
         toolsCount: (role.tools?.allow?.length ?? 0),
         roster: role.roster,
-        primaryModel: primary?.model,
-        primaryHarness: primary?.harness,
+        primaryRoute: primary?.route,
       });
     }
   }
@@ -381,342 +320,3 @@ export function modifyRole(
   if (!options.dryRun) writeFileSync(filePath, stringify(updated), "utf8");
   return { id: roleId, role: updated, filePath, scope };
 }
-
-// ---------------------------------------------------------------------------
-// Role Seat & Host Mapping Governance (kxm.role-hosts.v1)
-// ---------------------------------------------------------------------------
-
-export const KXM_ROLE_HOSTS_SCHEMA = "kxm.role-hosts.v1" as const;
-
-export interface RoleSeatDefinition {
-  seatId: string;
-  description?: string | undefined;
-  defaultModel?: string | undefined;
-  defaultHost?: string | undefined;
-  allowedTools?: readonly string[] | undefined;
-  requiredEvidenceKind?: string | undefined;
-}
-
-export interface RoleSeatBinding {
-  model?: string | undefined;
-  host?: string | undefined;
-  effort?: "low" | "medium" | "high" | "xhigh" | undefined;
-}
-
-export interface RoleHostsConfig {
-  schema: typeof KXM_ROLE_HOSTS_SCHEMA;
-  seats?: Record<string, RoleSeatBinding> | undefined;
-  hostProviders?: Record<string, string> | undefined;
-}
-
-export const DEFAULT_ROLE_SEATS: Record<string, RoleSeatDefinition> = {
-  planner: {
-    seatId: "planner",
-    description: "Architecture breakdown, requirement decomposition, and safety boundary definition.",
-    defaultModel: "anthropic/claude-fable-5.1",
-    defaultHost: "pi",
-    allowedTools: ["view_file", "grep_search", "find_by_name", "list_dir"],
-    requiredEvidenceKind: "architecture_review",
-  },
-  writer: {
-    seatId: "writer",
-    description: "Primary implementation agent. Writes code, refactors components, and authors unit tests.",
-    defaultModel: "x-ai/grok-4.6",
-    defaultHost: "grok",
-    allowedTools: ["view_file", "replace_file_content", "write_to_file", "run_command"],
-    requiredEvidenceKind: "git_diff",
-  },
-  "critic-arch": {
-    seatId: "critic-arch",
-    description: "Independent critic reviewing implementation diffs for architectural integrity.",
-    defaultModel: "anthropic/claude-fable-5.1",
-    defaultHost: "pi",
-    allowedTools: ["view_file", "grep_search"],
-    requiredEvidenceKind: "architecture_review",
-  },
-  "critic-cli": {
-    seatId: "critic-cli",
-    description: "CLI, documentation, and developer ergonomics critic.",
-    defaultModel: "openai/gpt-5.6-sol",
-    defaultHost: "pi",
-    allowedTools: ["view_file", "grep_search"],
-    requiredEvidenceKind: "cli_review",
-  },
-  verifier: {
-    seatId: "verifier",
-    description: "Deterministic gate evaluation runner.",
-    defaultModel: "evaluator",
-    defaultHost: "pi",
-    allowedTools: ["run_command"],
-    requiredEvidenceKind: "test_run",
-  },
-};
-
-export function roleHostsFilePath(
-  scope: "global" | "local",
-  repoRoot = process.cwd(),
-  userConfigDir?: string,
-  preferJson = false,
-): string {
-  const dir = scope === "global" ? userConfigDirectory(userConfigDir) : repoConfigDirectory(repoRoot);
-  return join(dir, preferJson ? "role-hosts.json" : "role-hosts.yaml");
-}
-
-export function findExistingRoleHostsFile(
-  scope: "global" | "local",
-  repoRoot = process.cwd(),
-  userConfigDir?: string,
-): { filePath: string; exists: boolean; format: "yaml" | "json" } {
-  const dir = scope === "global" ? userConfigDirectory(userConfigDir) : repoConfigDirectory(repoRoot);
-  const yamlPath = join(dir, "role-hosts.yaml");
-  const ymlPath = join(dir, "role-hosts.yml");
-  const jsonPath = join(dir, "role-hosts.json");
-
-  if (existsSync(yamlPath)) return { filePath: yamlPath, exists: true, format: "yaml" };
-  if (existsSync(ymlPath)) return { filePath: ymlPath, exists: true, format: "yaml" };
-  if (existsSync(jsonPath)) return { filePath: jsonPath, exists: true, format: "json" };
-  return { filePath: yamlPath, exists: false, format: "yaml" };
-}
-
-export function parseRoleHostsFile(filePath: string): RoleHostsConfig | undefined {
-  if (!existsSync(filePath)) return undefined;
-  try {
-    const raw = readFileSync(filePath, "utf8");
-    const parsed = parse(raw) as Partial<RoleHostsConfig>;
-    if (!parsed || typeof parsed !== "object") return undefined;
-    if (parsed.schema && parsed.schema !== KXM_ROLE_HOSTS_SCHEMA) return undefined;
-    return {
-      schema: KXM_ROLE_HOSTS_SCHEMA,
-      seats: parsed.seats && typeof parsed.seats === "object" ? parsed.seats : {},
-      hostProviders: parsed.hostProviders && typeof parsed.hostProviders === "object" ? parsed.hostProviders : {},
-    };
-  } catch {
-    return undefined;
-  }
-}
-
-export function loadRoleHostsConfig(options: {
-  scope?: "all" | "global" | "local" | undefined;
-  repoRoot?: string | undefined;
-  userConfigDir?: string | undefined;
-} = {}): { config: RoleHostsConfig; filePath?: string | undefined; scope: "local" | "global" | "default" } {
-  const scopeFilter = options.scope ?? "all";
-  const repoRoot = options.repoRoot ?? process.cwd();
-
-  let localConfig: RoleHostsConfig | undefined;
-  let localPath: string | undefined;
-  if (scopeFilter !== "global") {
-    const localFound = findExistingRoleHostsFile("local", repoRoot, options.userConfigDir);
-    if (localFound.exists) {
-      localConfig = parseRoleHostsFile(localFound.filePath);
-      localPath = localFound.filePath;
-    }
-  }
-
-  let globalConfig: RoleHostsConfig | undefined;
-  let globalPath: string | undefined;
-  if (scopeFilter !== "local") {
-    const globalFound = findExistingRoleHostsFile("global", repoRoot, options.userConfigDir);
-    if (globalFound.exists) {
-      globalConfig = parseRoleHostsFile(globalFound.filePath);
-      globalPath = globalFound.filePath;
-    }
-  }
-
-  if (scopeFilter === "local") {
-    return {
-      config: localConfig ?? { schema: KXM_ROLE_HOSTS_SCHEMA, seats: {}, hostProviders: {} },
-      filePath: localPath,
-      scope: localPath ? "local" : "default",
-    };
-  }
-
-  if (scopeFilter === "global") {
-    return {
-      config: globalConfig ?? { schema: KXM_ROLE_HOSTS_SCHEMA, seats: {}, hostProviders: {} },
-      filePath: globalPath,
-      scope: globalPath ? "global" : "default",
-    };
-  }
-
-  // Merge: local seats override global seats; local hostProviders merge over global hostProviders
-  const mergedSeats: Record<string, RoleSeatBinding> = {
-    ...(globalConfig?.seats ?? {}),
-    ...(localConfig?.seats ?? {}),
-  };
-  const mergedHostProviders: Record<string, string> = {
-    ...(globalConfig?.hostProviders ?? {}),
-    ...(localConfig?.hostProviders ?? {}),
-  };
-
-  const primaryPath = localPath ?? globalPath;
-  const primaryScope = localPath ? "local" : (globalPath ? "global" : "default");
-
-  return {
-    config: {
-      schema: KXM_ROLE_HOSTS_SCHEMA,
-      seats: mergedSeats,
-      hostProviders: mergedHostProviders,
-    },
-    filePath: primaryPath,
-    scope: primaryScope,
-  };
-}
-
-export function saveRoleHostsConfig(
-  config: RoleHostsConfig,
-  options: {
-    scope?: "global" | "local" | undefined;
-    repoRoot?: string | undefined;
-    userConfigDir?: string | undefined;
-    format?: "yaml" | "json" | undefined;
-    dryRun?: boolean | undefined;
-  } = {},
-): { filePath: string; scope: "global" | "local" } {
-  const scope = options.scope ?? "local";
-  const repoRoot = options.repoRoot ?? process.cwd();
-  const dir = scope === "global" ? userConfigDirectory(options.userConfigDir) : repoConfigDirectory(repoRoot);
-  const format = options.format ?? "yaml";
-  const filePath = join(dir, format === "json" ? "role-hosts.json" : "role-hosts.yaml");
-  if (options.dryRun) return { filePath, scope };
-  if (!existsSync(dir)) {
-    mkdirSync(dir, { recursive: true });
-  }
-
-  const payload: RoleHostsConfig = {
-    schema: KXM_ROLE_HOSTS_SCHEMA,
-    seats: config.seats ?? {},
-    ...(config.hostProviders && Object.keys(config.hostProviders).length > 0 ? { hostProviders: config.hostProviders } : {}),
-  };
-
-  const content = format === "json" ? JSON.stringify(payload, null, 2) + "\n" : stringify(payload);
-  writeFileSync(filePath, content, "utf8");
-  return { filePath, scope };
-}
-
-export function setRoleSeatHost(
-  seatId: string,
-  host: string,
-  options: {
-    model?: string | undefined;
-    effort?: "low" | "medium" | "high" | "xhigh" | undefined;
-    scope?: "global" | "local" | undefined;
-    repoRoot?: string | undefined;
-    userConfigDir?: string | undefined;
-    format?: "yaml" | "json" | undefined;
-    dryRun?: boolean | undefined;
-  } = {},
-): { filePath: string; seatId: string; binding: RoleSeatBinding; scope: "global" | "local" } {
-  const scope = options.scope ?? "local";
-  const current = loadRoleHostsConfig({
-    scope,
-    repoRoot: options.repoRoot,
-    userConfigDir: options.userConfigDir,
-  });
-
-  const seats = { ...(current.config.seats ?? {}) };
-  const existing = seats[seatId] ?? {};
-  const binding: RoleSeatBinding = {
-    ...existing,
-    host,
-    ...(options.model !== undefined ? { model: options.model } : {}),
-    ...(options.effort !== undefined ? { effort: options.effort } : {}),
-  };
-  seats[seatId] = binding;
-
-  const updatedConfig: RoleHostsConfig = {
-    ...current.config,
-    schema: KXM_ROLE_HOSTS_SCHEMA,
-    seats,
-  };
-
-  const saved = saveRoleHostsConfig(updatedConfig, {
-    scope,
-    repoRoot: options.repoRoot,
-    userConfigDir: options.userConfigDir,
-    format: options.format,
-    dryRun: options.dryRun,
-  });
-
-  return { filePath: saved.filePath, seatId, binding, scope };
-}
-
-export function resolveRoleSeat(
-  seatId: string,
-  options: {
-    hostOverride?: string | undefined;
-    modelOverride?: string | undefined;
-    repoRoot?: string | undefined;
-    userConfigDir?: string | undefined;
-  } = {},
-): {
-  seatId: string;
-  host: string;
-  model?: string | undefined;
-  provider?: string | undefined;
-  effort?: "low" | "medium" | "high" | "xhigh" | undefined;
-  source: "override" | "role-hosts" | "seat-default" | "role-roster" | "fallback";
-} {
-  const hostsConfig = loadRoleHostsConfig({
-    scope: "all",
-    repoRoot: options.repoRoot,
-    userConfigDir: options.userConfigDir,
-  }).config;
-
-  const configuredSeat = hostsConfig.seats?.[seatId];
-  const defaultSeat = DEFAULT_ROLE_SEATS[seatId];
-  const roleDef = getRole(seatId, {
-    scope: "all",
-    repoRoot: options.repoRoot,
-    userConfigDir: options.userConfigDir,
-  })?.role ?? DEFAULT_ROLES[seatId];
-  const primaryRoster = roleDef?.roster?.[0];
-
-  // Resolve host
-  let host = "pi";
-  let source: "override" | "role-hosts" | "seat-default" | "role-roster" | "fallback" = "fallback";
-
-  if (options.hostOverride) {
-    host = options.hostOverride;
-    source = "override";
-  } else if (configuredSeat?.host) {
-    host = configuredSeat.host;
-    source = "role-hosts";
-  } else if (defaultSeat?.defaultHost) {
-    host = defaultSeat.defaultHost;
-    source = "seat-default";
-  } else if (primaryRoster?.harness) {
-    host = primaryRoster.harness;
-    source = "role-roster";
-  }
-
-  // Resolve model
-  let model: string | undefined;
-  if (options.modelOverride) {
-    model = options.modelOverride;
-  } else if (configuredSeat?.model) {
-    model = configuredSeat.model;
-  } else if (defaultSeat?.defaultModel) {
-    model = defaultSeat.defaultModel;
-  } else if (primaryRoster?.model) {
-    model = primaryRoster.model;
-  }
-
-  // Resolve provider
-  const provider = hostsConfig.hostProviders?.[host]
-    ?? roleDef?.roster?.find((r) => r.harness === host)?.provider;
-
-  // Resolve effort
-  const effort = configuredSeat?.effort
-    ?? roleDef?.roster?.find((r) => r.harness === host)?.effort;
-
-  return {
-    seatId,
-    host,
-    model,
-    provider,
-    effort,
-    source,
-  };
-}
-

package/plugins/kxm/src/routes.ts

@@ -1,6 +1,7 @@
 import { existsSync, readFileSync, mkdirSync, writeFileSync, readdirSync } from "node:fs";
 import { join } from "node:path";
 import { parse, stringify } from "yaml";
+import { rolePurposeForId } from "./role.ts";
 
 const RETIRED_POLICY = ".kxm/producers.yaml";
 
@@ -32,10 +33,32 @@ export function setRouteState(root: string, model: string, state: "admitted" | "
       if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) roleFile = parsed as Record<string, unknown>;
     }
     const roster = Array.isArray(roleFile.roster) ? roleFile.roster.filter((entry): entry is Record<string, unknown> => Boolean(entry) && typeof entry === "object" && !Array.isArray(entry)) : [];
-    const existing = roster.findIndex((entry) => entry.model === model);
+    const modelsDir = join(root, ".kxm", "models");
+    let routeId: string | undefined;
+    if (existsSync(modelsDir)) {
+      for (const name of readdirSync(modelsDir)) {
+        if (!name.endsWith(".yaml") || name === "inventory.yaml") continue;
+        const parsedModel = parse(readFileSync(join(modelsDir, name), "utf8")) as { vendor?: unknown; model?: unknown; schema?: unknown };
+        if (parsedModel?.schema !== "kxm.model.v2") continue;
+        const vendor = typeof parsedModel.vendor === "string" ? parsedModel.vendor : "";
+        const named = typeof parsedModel.model === "string" ? parsedModel.model : "";
+        if (named === model || (vendor && `${vendor}/${named}` === model)) {
+          routeId = name.slice(0, -5);
+          break;
+        }
+      }
+    }
+    if (!routeId) throw new Error(`unknown route: no v2 model file matches '${model}'`);
+    const existing = roster.findIndex((entry) => entry.route === routeId || entry.model === model);
     if (removeRole) { if (existing >= 0) roster.splice(existing, 1); }
-    else if (existing < 0) roster.push({ model, enabled: true });
-    roleFile.schema ??= "kxm.role.v1"; roleFile.id ??= role; roleFile.roster = roster;
+    else if (existing < 0) roster.push({ route: routeId });
+    const purpose = typeof roleFile.purpose === "string" ? roleFile.purpose : rolePurposeForId(role);
+    roleFile.schema = "kxm.role.v2";
+    roleFile.id ??= role;
+    roleFile.purpose ??= purpose;
+    roleFile.permission ??= purpose === "writer" ? "edit" : "read-only";
+    roleFile.description ??= role;
+    roleFile.roster = roster;
     mkdirSync(join(root, ".kxm", "roles"), { recursive: true });
     writeFileSync(rolePath, stringify(roleFile), "utf8");
   }
@@ -49,8 +72,8 @@ export function listRoleBindings(root: string): Record<string, string[]> {
   const dir = join(root, ".kxm", "roles"); const result: Record<string, string[]> = {};
   if (!existsSync(dir)) return result;
   for (const file of readdirSync(dir).filter((name) => name.endsWith(".yaml"))) {
-    const role = file.slice(0, -5); const value = parse(readFileSync(join(dir, file), "utf8")) as { roster?: Array<{ model?: unknown }> };
-    result[role] = (value.roster ?? []).map((entry) => entry.model).filter((model): model is string => typeof model === "string");
+    const role = file.slice(0, -5); const value = parse(readFileSync(join(dir, file), "utf8")) as { roster?: Array<{ route?: unknown }> };
+    result[role] = (value.roster ?? []).map((entry) => entry.route).filter((route): route is string => typeof route === "string");
   }
   return result;
 }

package/plugins/kxm/src/template.ts

@@ -203,7 +203,40 @@ function coreTemplate(projectId: string, projectName: string, variant: KxmTempla
       updatedAt: "2026-09-23T00:00:00.000Z",
       admitted: ["anthropic/fable", "xai/grok-4.6"],
       disabled: [],
-      roles: { implementer: ["xai/grok-4.6"] },
+    });
+    files.set(".kxm/models/grok-default.yaml", {
+      schema: "kxm.model.v2",
+      id: "grok-default",
+      harness: "grok",
+      model: "grok-4.6",
+      vendor: "xai",
+      status: "admitted",
+      permissions: ["edit"],
+    });
+    files.set(".kxm/models/fable-default.yaml", {
+      schema: "kxm.model.v2",
+      id: "fable-default",
+      harness: "claude",
+      model: "fable",
+      vendor: "anthropic",
+      status: "admitted",
+      permissions: ["read-only"],
+    });
+    files.set(".kxm/roles/writer.yaml", {
+      schema: "kxm.role.v2",
+      id: "writer",
+      purpose: "writer",
+      permission: "edit",
+      description: "Primary implementation agent.",
+      roster: [{ route: "grok-default" }],
+    });
+    files.set(".kxm/roles/planner.yaml", {
+      schema: "kxm.role.v2",
+      id: "planner",
+      purpose: "planner",
+      permission: "read-only",
+      description: "Plans the change before implementation.",
+      roster: [{ route: "fable-default" }],
     });
     files.set(".kxm/gates.yaml", {
       schema: "kxm.gate-registry.v1",

package/schemas/README.md

@@ -8,7 +8,8 @@ Runtime-local records, and JSON events/results for the planned KXM contract.
 | `project.schema.json` | `kxm.project.v1` |
 | `repository.schema.json` | `kxm.repository.v1` |
 | `agent.schema.json` | `kxm.agent.v1` |
-| `model.schema.json` | `kxm.model.v1` |
+| `model.schema.json` | `kxm.model.v2` |
+| `role.schema.json` | `kxm.role.v2` |
 | `environment.schema.json` | `kxm.environment.v1` |
 | `workflow.schema.json` | `kxm.workflow.v1` |
 | `template-provenance.schema.json` | `kxm.template-provenance.v1` |