@kontextmind/kxm 0.6.0 → 0.7.10

package/schemas/policy-draft/role.v2.schema.json

@@ -0,0 +1,91 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.kxm.dev/policy-draft/role.v2.schema.json",
+  "title": "KXM policy-draft role",
+  "description": "Passive kxm.role.v2 scaffolding. Specialty identity is separate from purpose. Roster order is configured preference, not a measured ranking. Not live admission or operator settings.",
+  "type": "object",
+  "required": ["schema", "purpose", "permission", "description", "roster"],
+  "additionalProperties": false,
+  "properties": {
+    "schema": { "const": "kxm.role.v2" },
+    "id": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9]*(?:[-_][a-z0-9]+)*$",
+      "minLength": 1,
+      "maxLength": 64
+    },
+    "purpose": {
+      "enum": ["writer", "planner", "reviewer-arch", "reviewer-cli", "experiment"]
+    },
+    "permission": { "enum": ["edit", "read-only"] },
+    "description": { "type": "string", "minLength": 1, "maxLength": 2000 },
+    "roster": {
+      "type": "array",
+      "maxItems": 32,
+      "items": {
+        "type": "object",
+        "required": ["route"],
+        "additionalProperties": false,
+        "properties": {
+          "route": {
+            "type": "string",
+            "pattern": "^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$",
+            "minLength": 1,
+            "maxLength": 64
+          },
+          "effort": {
+            "enum": ["off", "minimal", "low", "medium", "high", "xhigh", "max"]
+          },
+          "mode": { "enum": ["headless", "interactive", "either"] }
+        }
+      }
+    },
+    "skills": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1, "maxLength": 128 },
+      "maxItems": 64
+    },
+    "tools": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "preset": { "type": "string" },
+        "allow": { "type": "array", "items": { "type": "string" } },
+        "deny": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "produces": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["template"],
+        "additionalProperties": false,
+        "properties": {
+          "template": { "type": "string" },
+          "schema": { "type": "string" }
+        }
+      }
+    },
+    "consumes": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["template"],
+        "additionalProperties": false,
+        "properties": {
+          "template": { "type": "string" },
+          "schema": { "type": "string" }
+        }
+      }
+    },
+    "policy": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "vendorIndependenceRequired": { "type": "boolean" },
+        "maxTransitions": { "type": "integer", "minimum": 1 },
+        "requiresGateVerification": { "type": "boolean" }
+      }
+    }
+  }
+}

package/schemas/vnext/modes.schema.json

@@ -0,0 +1,56 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.kxm.dev/vnext/modes.schema.json",
+  "title": "KXM Modes Configuration",
+  "description": "Declarative major modes and domain modules for selective tool loading and context scoping",
+  "type": "object",
+  "required": ["schema", "majorModes"],
+  "properties": {
+    "schema": { "const": "kxm.modes.v1" },
+    "majorModes": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "object",
+        "required": ["baseTools"],
+        "properties": {
+          "description": { "type": "string" },
+          "baseTools": {
+            "type": "array",
+            "items": { "type": "string" }
+          },
+          "contextFiles": {
+            "type": "array",
+            "items": { "type": "string" }
+          },
+          "thinkingLevel": {
+            "type": "string",
+            "enum": ["low", "medium", "high", "xhigh"]
+          },
+          "model": { "type": "string" }
+        },
+        "additionalProperties": false
+      }
+    },
+    "domains": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "object",
+        "required": ["tools"],
+        "properties": {
+          "description": { "type": "string" },
+          "tools": {
+            "type": "array",
+            "items": { "type": "string" }
+          },
+          "contextFiles": {
+            "type": "array",
+            "items": { "type": "string" }
+          },
+          "promptSnippet": { "type": "string" }
+        },
+        "additionalProperties": false
+      }
+    }
+  },
+  "additionalProperties": false
+}

package/schemas/vnext/role.schema.json

@@ -0,0 +1,76 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.kxm.dev/vnext/role.schema.json",
+  "title": "KXM role definition",
+  "description": "The filename determines the role identity unless explicitly declared.",
+  "type": "object",
+  "required": ["schema", "description"],
+  "properties": {
+    "schema": { "const": "kxm.role.v1" },
+    "id": { "$ref": "common.schema.json#/$defs/identifier" },
+    "description": { "type": "string", "minLength": 1, "maxLength": 2000 },
+    "skills": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1, "maxLength": 128 },
+      "maxItems": 64
+    },
+    "tools": {
+      "type": "object",
+      "properties": {
+        "preset": { "type": "string" },
+        "allow": { "type": "array", "items": { "type": "string" } },
+        "deny": { "type": "array", "items": { "type": "string" } }
+      },
+      "additionalProperties": false
+    },
+    "produces": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["template"],
+        "properties": {
+          "template": { "type": "string" },
+          "schema": { "type": "string" }
+        },
+        "additionalProperties": false
+      }
+    },
+    "consumes": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["template"],
+        "properties": {
+          "template": { "type": "string" },
+          "schema": { "type": "string" }
+        },
+        "additionalProperties": false
+      }
+    },
+    "roster": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["harness", "model"],
+        "properties": {
+          "harness": { "$ref": "common.schema.json#/$defs/identifier" },
+          "model": { "$ref": "common.schema.json#/$defs/modelSelector" },
+          "provider": { "type": "string" },
+          "effort": { "enum": ["low", "medium", "high", "xhigh"] },
+          "mode": { "enum": ["headless", "interactive", "either"] }
+        },
+        "additionalProperties": false
+      }
+    },
+    "policy": {
+      "type": "object",
+      "properties": {
+        "vendorIndependenceRequired": { "type": "boolean" },
+        "maxTransitions": { "type": "integer", "minimum": 1 },
+        "requiresGateVerification": { "type": "boolean" }
+      },
+      "additionalProperties": false
+    }
+  },
+  "additionalProperties": false
+}

package/schemas/vnext/run-event.schema.json

@@ -323,6 +323,7 @@
       "properties": {
         "workflowId": { "$ref": "common.schema.json#/$defs/identifier" },
         "displayTitle": { "type": "string", "minLength": 1, "maxLength": 200 },
+        "prompt": { "type": "string", "maxLength": 64000 },
         "promptHash": { "$ref": "common.schema.json#/$defs/sha256" },
         "runPlanHash": { "$ref": "common.schema.json#/$defs/sha256" },
         "capabilityHash": { "$ref": "common.schema.json#/$defs/sha256" },

package/scripts/assignment-run.d.mts

@@ -33,7 +33,7 @@ export function resolveRequiredCritics(policy: unknown): Readonly<Record<string,
   vendor: string;
   route_id?: string;
 }>>>;
-export function getRosterPolicy(deps?: Record<string, unknown>): unknown;
+export function getRosterPolicy(deps?: Record<string, unknown>): import("./roster-policy.mjs").RosterPolicy;
 export const ASSIGNMENT_KINDS: readonly string[];
 export const KIND_ROLES: Readonly<Record<string, string>>;
 export const REVIEW_KINDS: readonly string[];

package/scripts/assignment-run.mjs

@@ -746,30 +746,35 @@ function validateRework(reworkOf, taskDir, taskId, assignmentId, deps) {
   return priorId;
 }
 
-let cachedDiskPolicy = null;
-export function getRosterPolicy(deps = {}) {
-  if (deps.rosterPolicy) {
-    return deps.rosterPolicy.policy ?? deps.rosterPolicy;
+function requireRosterPolicyShape(policy) {
+  if (!policy || typeof policy !== "object" || Array.isArray(policy)) {
+    throw failClosed("roster policy is invalid or unparsed", "route_invalid");
   }
-  if (typeof deps.loadTrustedRosterPolicy === "function") {
-    const loaded = deps.loadTrustedRosterPolicy();
-    return loaded?.policy ?? loaded;
+  if (!policy.routes || typeof policy.routes !== "object" || Array.isArray(policy.routes) || Object.keys(policy.routes).length === 0) {
+    throw failClosed("roster policy is invalid or unparsed", "route_invalid");
   }
+  if (!policy.lineup || typeof policy.lineup !== "object" || Array.isArray(policy.lineup)) {
+    throw failClosed("roster policy is invalid or unparsed", "route_invalid");
+  }
+  return policy;
+}
+
+function unwrapRosterPolicy(loaded) {
+  return requireRosterPolicyShape(loaded?.policy ?? loaded);
+}
+
+export function getRosterPolicy(deps = {}) {
   try {
-    return loadTrustedRosterPolicy().policy;
-  } catch (error) {
-    // When executing in a local development checkout where git status has dirty
-    // uncommitted edits or during unit tests running against in-flight code,
-    // fallback to parsing the local .kxm/roster.json.
-    if (!cachedDiskPolicy) {
-      try {
-        const diskPath = join(fileURLToPath(new URL(".", import.meta.url)), "..", ".kxm/roster.json");
-        cachedDiskPolicy = Object.freeze(JSON.parse(readFileSync(diskPath, "utf8")));
-      } catch {
-        throw failClosed(error?.message ?? "roster policy unavailable", "route_invalid");
-      }
+    if (Object.hasOwn(deps, "rosterPolicy")) {
+      return unwrapRosterPolicy(deps.rosterPolicy);
+    }
+    if (typeof deps.loadTrustedRosterPolicy === "function") {
+      return unwrapRosterPolicy(deps.loadTrustedRosterPolicy());
     }
-    return cachedDiskPolicy;
+    return unwrapRosterPolicy(loadTrustedRosterPolicy());
+  } catch (error) {
+    if (error?.runnerCode === "route_invalid") throw error;
+    throw failClosed(error?.message ?? "roster policy unavailable", "route_invalid");
   }
 }
 
@@ -979,6 +984,15 @@ const MODEL_CLAIM_OVERRIDE_KEYS = Object.freeze([
   "usage",
   "transport",
 ]);
+function injectedPolicyDeps(source = {}) {
+  const deps = {};
+  if (Object.hasOwn(source, "rosterPolicy")) deps.rosterPolicy = source.rosterPolicy;
+  if (typeof source.loadTrustedRosterPolicy === "function") {
+    deps.loadTrustedRosterPolicy = source.loadTrustedRosterPolicy;
+  }
+  return deps;
+}
+
 function ioDeps(deps = {}) {
   return {
     spawnSync: deps.spawnSync ?? spawnSync,
@@ -996,8 +1010,7 @@ function ioDeps(deps = {}) {
     rmSync: deps.rmSync ?? rmSync,
     manifestBytes: deps.manifestBytes,
     now: deps.now,
-    rosterPolicy: deps.rosterPolicy,
-    loadTrustedRosterPolicy: deps.loadTrustedRosterPolicy,
+    ...injectedPolicyDeps(deps),
   };
 }
 
@@ -3374,7 +3387,7 @@ function closedObserved(pr, ci) {
 
 export function resolveRequiredCritics(policy) {
   if (!policy || typeof policy !== "object" || !policy.required_critics || !policy.routes) {
-    return REQUIRED_ACCEPT_CRITICS;
+    throw failClosed("roster policy is invalid or unparsed", "route_invalid");
   }
   const result = {};
   for (const [kind, routeId] of Object.entries(policy.required_critics)) {
@@ -3409,11 +3422,10 @@ function assertEligibleWriter(bound, policy) {
   if (!(transport?.status === "completed" && transport?.ok === true)) {
     throw failClosed("writer transport is not completed/ok", "witness_binding_invalid");
   }
-  if (policy?.lineup?.writer && policy?.routes) {
-    const matched = findLineupRoute(policy, "writer", bound.identity.harness, bound.identity.model);
-    if (!matched) {
-      throw failClosed(`writer ${bound.identity.harness}/${bound.identity.model} is not admitted in lineup`, "witness_binding_invalid");
-    }
+  requireRosterPolicyShape(policy);
+  const matched = findLineupRoute(policy, "writer", bound.identity.harness, bound.identity.model);
+  if (!matched) {
+    throw failClosed(`writer ${bound.identity.harness}/${bound.identity.model} is not admitted in lineup`, "witness_binding_invalid");
   }
 }
 
@@ -3669,12 +3681,7 @@ export async function acceptAssignment(request, deps = {}) {
     const commitValue = request?.commit;
     const writerRecordValue = request?.recordDir ?? request?.record_dir;
     const criticValues = request?.critics;
-    let policy;
-    try {
-      policy = getRosterPolicy(deps);
-    } catch {
-      policy = null;
-    }
+    const policy = getRosterPolicy(deps);
     const criticSpecs = resolveRequiredCritics(policy);
     const requiredKinds = Object.keys(criticSpecs);
     if (!Array.isArray(criticValues) || criticValues.length !== requiredKinds.length) {
@@ -4337,6 +4344,7 @@ export async function main(argv = process.argv, io = { stdin: process.stdin, std
         spawnSync: io.spawnSync ?? spawnSync,
         env: io.env,
         now: io.now,
+        ...injectedPolicyDeps(io),
       });
       io.stdout.write(`${JSON.stringify(accepted, undefined, 2)}\n`);
       process.exitCode = 0;
@@ -4395,6 +4403,7 @@ export async function main(argv = process.argv, io = { stdin: process.stdin, std
         spawnSync: io.spawnSync ?? spawnSync,
         env: io.env,
         now: io.now,
+        ...injectedPolicyDeps(io),
       });
       io.stdout.write(`${JSON.stringify(receipt, undefined, 2)}\n`);
       process.exitCode = receipt.result === "passed" ? 0 : 1;
@@ -4418,7 +4427,7 @@ export async function main(argv = process.argv, io = { stdin: process.stdin, std
   const bytes = readFileSync(manifestPath);
   const manifest = parseJsonFile(manifestPath, bytes, "assignment manifest");
   try {
-    const completion = await runAssignment(manifest, { manifestBytes: bytes });
+    const completion = await runAssignment(manifest, { manifestBytes: bytes, ...injectedPolicyDeps(io) });
     io.stdout.write(`${JSON.stringify(completion, undefined, 2)}\n`);
     process.exitCode = completion.transport?.ok === true && completion.recording?.status === "ok" ? 0 : 1;
     return completion;

package/scripts/check-generated.mjs

@@ -4,8 +4,9 @@ import { existsSync } from "node:fs";
 import { resolve } from "node:path";
 import { spawnSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
+import { listSkillMirrorArtifacts, loadSkillSuiteManifest } from "./emit-codex-artifacts.mjs";
 
-export const GENERATED_ARTIFACTS = [
+export const STATIC_GENERATED_ARTIFACTS = Object.freeze([
   "plugins/kxm/dist/cli.js",
   "plugins/kxm/dist/server.js",
   "plugins/kxm/dist/mcp-server.js",
@@ -14,13 +15,34 @@ export const GENERATED_ARTIFACTS = [
   "plugins/kxm/dist/runtime.js",
   "plugins/kxm/dist/client.js",
   "plugins/kxm/dist/extension.js",
-  ".agents/skills/kxm/SKILL.md",
-  ".agents/skills/kxm/references/protocol.md",
-  ".agents/skills/kxm-session/SKILL.md",
   "AGENTS.md",
   "CLAUDE.md",
   "GEMINI.md",
-];
+]);
+
+/**
+ * Compute the generated artifact list from the committed suite manifest.
+ * The manifest is required; missing or invalid manifests fail closed.
+ *
+ * @param {string} [repository]
+ * @returns {string[]}
+ */
+export function computeGeneratedArtifacts(repository = process.cwd()) {
+  const root = resolve(repository);
+  loadSkillSuiteManifest(root);
+  return Object.freeze([
+    ...STATIC_GENERATED_ARTIFACTS,
+    ...listSkillMirrorArtifacts(root),
+  ]);
+}
+
+/**
+ * Synchronous snapshot for the current repository. Tests that need a
+ * fixture-specific list should call computeGeneratedArtifacts(root).
+ *
+ * @type {readonly string[]}
+ */
+export const GENERATED_ARTIFACTS = computeGeneratedArtifacts();
 
 function runGit(repository, args, allowFailure = false) {
   const result = spawnSync("git", args, {
@@ -39,12 +61,14 @@ export function checkGeneratedArtifacts(repository = process.cwd()) {
   const requestedRoot = resolve(repository);
   const topLevel = runGit(requestedRoot, ["rev-parse", "--show-toplevel"]).stdout.trim();
   const root = resolve(topLevel);
-  const missing = GENERATED_ARTIFACTS.filter((path) => !existsSync(resolve(root, path)));
+  const artifacts = computeGeneratedArtifacts(root);
+
+  const missing = artifacts.filter((path) => !existsSync(resolve(root, path)));
   if (missing.length > 0) {
     throw new Error(`generated artifacts are missing: ${missing.join(", ")}`);
   }
 
-  const untracked = GENERATED_ARTIFACTS.filter((path) => runGit(
+  const untracked = artifacts.filter((path) => runGit(
     root,
     ["--literal-pathspecs", "ls-files", "--error-unmatch", "--", path],
     true,
@@ -58,12 +82,12 @@ export function checkGeneratedArtifacts(repository = process.cwd()) {
     "diff",
     "--name-only",
     "--",
-    ...GENERATED_ARTIFACTS,
+    ...artifacts,
   ]).stdout.trim();
   if (status) {
     throw new Error(`generated artifacts changed after build:\n${status}`);
   }
-  return { root, artifacts: [...GENERATED_ARTIFACTS] };
+  return { root, artifacts: [...artifacts] };
 }
 
 if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {