@kontextmind/kxm 0.7.104 → 0.7.106

package/plugins/kxm/dist/mcp-server.js

@@ -17313,7 +17313,7 @@ function sessionTokenFixHint(policy) {
 }
 
 // plugins/kxm/src/mcp-server.ts
-var VERSION = "0.7.104";
+var VERSION = "0.7.106";
 var CONFIGURE_PLUGIN = "/plugin configure kxm@kxm";
 var inbox = /* @__PURE__ */ new Map();
 var notifiedInbox = /* @__PURE__ */ new Set();

package/plugins/kxm/dist/runtime-supervisor.js

@@ -16015,7 +16015,7 @@ function probeEntry(entry, runCommand, timeoutMs, platform, probe = {}) {
   return {
     id: entry.id,
     label: entry.label,
-    default: entry.default,
+    default: entry.id === (probe.defaultHarness ?? DEFAULT_HARNESS),
     mode: entry.mode,
     detected,
     authenticated,
@@ -17151,7 +17151,7 @@ function validateModelReferences(models, issues) {
   };
   for (const id of models.keys()) walk(id, []);
 }
-function validateBundle(project, repositories, agents, models, workflows, environments, options, gateRegistry, projectRoot) {
+function validateBundle(project, repositories, agents, models, workflows, environments, options, gateRegistry, projectRoot, writerRole) {
   const issues = [];
   const entries = valuesOf(project.value, "repositories").map((candidate) => objectValue(candidate)).filter((candidate) => Boolean(candidate));
   const repositoryIds = /* @__PURE__ */ new Set();
@@ -17222,9 +17222,9 @@ function validateBundle(project, repositories, agents, models, workflows, enviro
   if (projectRoot) {
     const writerRolePath = join2(projectRoot, ".kxm", "roles", "writer.yaml");
     const implementerAgent = agents.get("implementer") ?? agents.get("writer");
-    if (existsSync3(writerRolePath) && implementerAgent) {
+    if ((writerRole !== void 0 || existsSync3(writerRolePath)) && implementerAgent) {
       try {
-        const rawRole = parseRestrictedYaml2(readFileSync(writerRolePath, "utf8"));
+        const rawRole = parseRestrictedYaml2(writerRole ?? readFileSync(writerRolePath, "utf8"));
         const roleObj = objectValue(rawRole);
         const rosterEntries = valuesOf(roleObj ?? {}, "roster").map((candidate) => objectValue(candidate)).filter((entry) => Boolean(entry));
         const enabledRosterModels = rosterEntries.filter((entry) => entry.enabled !== false).map((entry) => stringValue(entry.model)).filter((m) => Boolean(m));
@@ -17290,7 +17290,9 @@ function assertNoRegisteredGates(options) {
 function loadKxmProject(projectRoot, options = {}) {
   return loadProjectBundle(projectRoot, options);
 }
-function loadProjectBundle(projectRoot, options, workflowCandidate) {
+function loadProjectBundle(projectRoot, options, candidate) {
+  const workflowCandidate = candidate?.kind === "workflow" ? candidate : void 0;
+  const writerRole = candidate?.kind === "role" && candidate.id.toLocaleLowerCase("en-US") === "writer" ? candidate.document : void 0;
   assertNoRegisteredGates(options);
   const root = resolve(projectRoot);
   const legacyPresent = legacyConfigFilesAt(root);
@@ -17313,7 +17315,7 @@ function loadProjectBundle(projectRoot, options, workflowCandidate) {
       earlyIssues.push(issue2("semantic", "template_provenance_project_mismatch", ".kxm/template-provenance.yaml", "template provenance belongs to a different project identity"));
     }
   }
-  const declaredRepositoryIds = new Set(valuesOf(project.value, "repositories").map((candidate) => stringValue(objectValue(candidate)?.id)).filter((candidate) => candidate !== void 0));
+  const declaredRepositoryIds = new Set(valuesOf(project.value, "repositories").map((candidate2) => stringValue(objectValue(candidate2)?.id)).filter((candidate2) => candidate2 !== void 0));
   for (const repositoryId of Object.keys(options.repositoryBindings ?? {}).sort(compareCodeUnits3)) {
     if (!resourceIdentifier(repositoryId)) {
       earlyIssues.push(issue2("path", "repository_binding_id_invalid", ".kxm/project.yaml", `host-local binding identity ${repositoryId} is invalid`));
@@ -17329,7 +17331,7 @@ function loadProjectBundle(projectRoot, options, workflowCandidate) {
     const { id, document } = workflowCandidate;
     const logicalPath = `.kxm/workflows/${id}.yaml`;
     if (!resourceIdentifier(id)) fail2("path", "resource_id_invalid", logicalPath, `filename-derived identity ${id} is invalid or platform-reserved`);
-    const collision = [...workflows.keys()].find((candidate) => candidate.toLocaleLowerCase("en-US") === id.toLocaleLowerCase("en-US"));
+    const collision = [...workflows.keys()].find((candidate2) => candidate2.toLocaleLowerCase("en-US") === id.toLocaleLowerCase("en-US"));
     if (collision) fail2("path", "resource_id_collision", logicalPath, `${id} case-folds to existing ${collision}`);
     workflows.set(id, { kind: "workflow", id, file: join2(root, logicalPath), logicalPath, value: resourceValue(registry, document, logicalPath, "workflow") });
   }
@@ -17348,8 +17350,8 @@ function loadProjectBundle(projectRoot, options, workflowCandidate) {
     }
   }
   const seenBindings = /* @__PURE__ */ new Map();
-  for (const candidate of valuesOf(project.value, "repositories")) {
-    const entry = objectValue(candidate);
+  for (const candidate2 of valuesOf(project.value, "repositories")) {
+    const entry = objectValue(candidate2);
     const repositoryId = entry && stringValue(entry.id);
     const pathHint = entry && stringValue(entry.pathHint);
     const role = entry && stringValue(entry.role);
@@ -17446,7 +17448,7 @@ function loadProjectBundle(projectRoot, options, workflowCandidate) {
     }
   }
   if (loadIssues.length > 0) throw new KxmConfigError(loadIssues);
-  const issues = validateBundle(project, repositories, agents, models, workflows, environments, options, gateRegistry, root);
+  const issues = validateBundle(project, repositories, agents, models, workflows, environments, options, gateRegistry, root, writerRole);
   if (issues.length > 0) throw new KxmConfigError(issues);
   const resources = [project, ...repositories.values(), ...agents.values(), ...models.values(), ...workflows.values(), ...environments, ...gateRegistry ? [gateRegistry] : []].sort((left, right) => compareCodeUnits3(left.logicalPath, right.logicalPath));
   return {

package/plugins/kxm/dist/runtime.js

@@ -16017,7 +16017,7 @@ function probeEntry(entry, runCommand, timeoutMs, platform, probe = {}) {
   return {
     id: entry.id,
     label: entry.label,
-    default: entry.default,
+    default: entry.id === (probe.defaultHarness ?? DEFAULT_HARNESS),
     mode: entry.mode,
     detected,
     authenticated,
@@ -16038,7 +16038,7 @@ function probeHarnesses(options = {}) {
   const runCommand = options.runCommand ?? defaultRunner(options.env ?? process.env);
   const platform = options.platform ?? process.platform;
   return {
-    defaultHarness: DEFAULT_HARNESS,
+    defaultHarness: options.defaultHarness ?? DEFAULT_HARNESS,
     harnesses: BUILTIN_HARNESSES.map((entry) => probeEntry(entry, runCommand, timeoutMs, platform, options))
   };
 }
@@ -16449,7 +16449,7 @@ function formatHarnessInventory(inventory) {
     ].join(" ");
   });
   return [
-    `default harness: ${inventory.defaultHarness} (omit agent harness: to use headless Pi)`,
+    `default harness: ${inventory.defaultHarness} (used when an agent omits harness:)`,
     "enable/disable = Git YAML (.kxm/agents, .kxm/models) or the harness's own plugin CLI",
     "governed kxm skills are not auto-updated",
     header,
@@ -17321,7 +17321,7 @@ function validateModelReferences(models, issues) {
   };
   for (const id of models.keys()) walk(id, []);
 }
-function validateBundle(project, repositories, agents, models, workflows, environments, options, gateRegistry, projectRoot) {
+function validateBundle(project, repositories, agents, models, workflows, environments, options, gateRegistry, projectRoot, writerRole) {
   const issues = [];
   const entries = valuesOf(project.value, "repositories").map((candidate) => objectValue(candidate)).filter((candidate) => Boolean(candidate));
   const repositoryIds = /* @__PURE__ */ new Set();
@@ -17392,9 +17392,9 @@ function validateBundle(project, repositories, agents, models, workflows, enviro
   if (projectRoot) {
     const writerRolePath = join2(projectRoot, ".kxm", "roles", "writer.yaml");
     const implementerAgent = agents.get("implementer") ?? agents.get("writer");
-    if (existsSync3(writerRolePath) && implementerAgent) {
+    if ((writerRole !== void 0 || existsSync3(writerRolePath)) && implementerAgent) {
       try {
-        const rawRole = parseRestrictedYaml2(readFileSync(writerRolePath, "utf8"));
+        const rawRole = parseRestrictedYaml2(writerRole ?? readFileSync(writerRolePath, "utf8"));
         const roleObj = objectValue(rawRole);
         const rosterEntries = valuesOf(roleObj ?? {}, "roster").map((candidate) => objectValue(candidate)).filter((entry) => Boolean(entry));
         const enabledRosterModels = rosterEntries.filter((entry) => entry.enabled !== false).map((entry) => stringValue(entry.model)).filter((m) => Boolean(m));
@@ -17460,7 +17460,9 @@ function assertNoRegisteredGates(options) {
 function loadKxmProject(projectRoot, options = {}) {
   return loadProjectBundle(projectRoot, options);
 }
-function loadProjectBundle(projectRoot, options, workflowCandidate) {
+function loadProjectBundle(projectRoot, options, candidate) {
+  const workflowCandidate = candidate?.kind === "workflow" ? candidate : void 0;
+  const writerRole = candidate?.kind === "role" && candidate.id.toLocaleLowerCase("en-US") === "writer" ? candidate.document : void 0;
   assertNoRegisteredGates(options);
   const root = resolve(projectRoot);
   const legacyPresent = legacyConfigFilesAt(root);
@@ -17483,7 +17485,7 @@ function loadProjectBundle(projectRoot, options, workflowCandidate) {
       earlyIssues.push(issue2("semantic", "template_provenance_project_mismatch", ".kxm/template-provenance.yaml", "template provenance belongs to a different project identity"));
     }
   }
-  const declaredRepositoryIds = new Set(valuesOf(project.value, "repositories").map((candidate) => stringValue(objectValue(candidate)?.id)).filter((candidate) => candidate !== void 0));
+  const declaredRepositoryIds = new Set(valuesOf(project.value, "repositories").map((candidate2) => stringValue(objectValue(candidate2)?.id)).filter((candidate2) => candidate2 !== void 0));
   for (const repositoryId of Object.keys(options.repositoryBindings ?? {}).sort(compareCodeUnits3)) {
     if (!resourceIdentifier(repositoryId)) {
       earlyIssues.push(issue2("path", "repository_binding_id_invalid", ".kxm/project.yaml", `host-local binding identity ${repositoryId} is invalid`));
@@ -17499,7 +17501,7 @@ function loadProjectBundle(projectRoot, options, workflowCandidate) {
     const { id, document } = workflowCandidate;
     const logicalPath = `.kxm/workflows/${id}.yaml`;
     if (!resourceIdentifier(id)) fail2("path", "resource_id_invalid", logicalPath, `filename-derived identity ${id} is invalid or platform-reserved`);
-    const collision = [...workflows.keys()].find((candidate) => candidate.toLocaleLowerCase("en-US") === id.toLocaleLowerCase("en-US"));
+    const collision = [...workflows.keys()].find((candidate2) => candidate2.toLocaleLowerCase("en-US") === id.toLocaleLowerCase("en-US"));
     if (collision) fail2("path", "resource_id_collision", logicalPath, `${id} case-folds to existing ${collision}`);
     workflows.set(id, { kind: "workflow", id, file: join2(root, logicalPath), logicalPath, value: resourceValue(registry, document, logicalPath, "workflow") });
   }
@@ -17518,8 +17520,8 @@ function loadProjectBundle(projectRoot, options, workflowCandidate) {
     }
   }
   const seenBindings = /* @__PURE__ */ new Map();
-  for (const candidate of valuesOf(project.value, "repositories")) {
-    const entry = objectValue(candidate);
+  for (const candidate2 of valuesOf(project.value, "repositories")) {
+    const entry = objectValue(candidate2);
     const repositoryId = entry && stringValue(entry.id);
     const pathHint = entry && stringValue(entry.pathHint);
     const role = entry && stringValue(entry.role);
@@ -17616,7 +17618,7 @@ function loadProjectBundle(projectRoot, options, workflowCandidate) {
     }
   }
   if (loadIssues.length > 0) throw new KxmConfigError(loadIssues);
-  const issues = validateBundle(project, repositories, agents, models, workflows, environments, options, gateRegistry, root);
+  const issues = validateBundle(project, repositories, agents, models, workflows, environments, options, gateRegistry, root, writerRole);
   if (issues.length > 0) throw new KxmConfigError(issues);
   const resources = [project, ...repositories.values(), ...agents.values(), ...models.values(), ...workflows.values(), ...environments, ...gateRegistry ? [gateRegistry] : []].sort((left, right) => compareCodeUnits3(left.logicalPath, right.logicalPath));
   return {

package/plugins/kxm/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-plugin",
-  "version": "0.7.104",
+  "version": "0.7.106",
   "private": true,
   "type": "module",
   "engines": {

package/plugins/kxm/src/cli/project.ts

@@ -16,6 +16,7 @@ import { initializeKxmProject } from "../init.ts";
 import { diffKxmProjectAgainstRevision, formatKxmPermissionDiff } from "../permission.ts";
 import { readKxmLocalBindings, kxmUserStateRoot } from "../bindings.ts";
 import { loadKxmProject } from "../project-config.ts";
+import { kxmLiveRunPrerequisites, type KxmRunHandoff } from "../engine.ts";
 import {
   attachKxmSupervisor,
   ensureKxmSupervisor,
@@ -115,6 +116,13 @@ export async function cmdKxmInit(
       localStateRoot: kxmUserStateRoot({ env: runtime.env }),
       dryRun: runtime.dryRun,
     });
+    const starterGuidance = initialized.action === "created" || (initialized.action === "planned" && initialized.plan.mode === "create")
+      ? [
+          "defaultHarness: pi and the npm test gate are generic starter settings, not repository detection.",
+          "For Claude, set defaultHarness: claude in .kxm/project.yaml, update any explicit harness overrides in .kxm/agents/*.yaml, and configure compatible agent models.",
+          "For .NET or other non-npm repositories, set gates.test.argv in .kxm/gates.yaml to the repository's actual test runner before driving a workflow.",
+        ]
+      : [];
     const payload = {
       ok: initialized.action !== "planned" || runtime.dryRun,
       command: "init",
@@ -128,9 +136,10 @@ export async function cmdKxmInit(
       ...(initialized.resumePending === undefined ? {} : { resumePending: initialized.resumePending }),
       ...(initialized.transactionKind === undefined ? {} : { transactionKind: initialized.transactionKind }),
       plannedOnly: initialized.action === "planned",
+      ...(starterGuidance.length > 0 ? { guidance: starterGuidance } : {}),
     };
     const finishInit = (code: number, text: string): number => {
-      print(runtime.io, runtime.json, payload, text);
+      print(runtime.io, runtime.json, payload, [text, ...starterGuidance].join("\n"));
       return code;
     };
     if (initialized.action === "created") {
@@ -388,11 +397,16 @@ async function readSupervisor(runtime: Runtime, command: string): Promise<Awaite
   return attached ?? refuseDryRun(runtime.io, runtime.json, command, "the Runtime supervisor is not running and --dry-run will not start it");
 }
 
-export const RUN_ENGINE_PHASE = "pre-3a";
-
-/** The next step `kxm run` prints for the run it just created. */
-export function runEngineNotice(runId: string): string {
-  return `drive it model-free: kxm runs drive ${runId} --simulated --wait (or cancel: kxm runs cancel ${runId})`;
+/** Creation is not execution; local runs are driven and inspected in the runs namespace. */
+export function runEngineNotice(runId: string, defaultHarness: string, prerequisites: readonly KxmRunHandoff[]): string {
+  return [
+    `No steps executed. Project default harness: ${defaultHarness}; per-agent harness settings take precedence.`,
+    ...prerequisites.map((item) => `Live prerequisite${item.stepId ? ` (${item.stepId})` : ""}: ${item.detail}`),
+    "Live execution uses one-shot harness calls; no hub or Pi worker is required. Check installation/authentication with kxm harness list.",
+    `${prerequisites.length > 0 ? "Resolve the prerequisites above, then execute" : "Execute"}: kxm runs drive ${runId} --wait`,
+    `Inspect: kxm runs status ${runId} --json; receipt: kxm runs receipt ${runId} --json; cancel: kxm runs cancel ${runId}`,
+    "These are local Runtime runs, not webhook workflows; use kxm runs, not kxm workflow get.",
+  ].join("\n");
 }
 
 /** Where `kxm run <workflow>` would create its run, or the exit code of the
@@ -400,7 +414,8 @@ export function runEngineNotice(runId: string): string {
 export function resolveKxmRunTarget(
   runtime: Runtime,
   workflow: string | undefined,
-): { projectRoot: string; workflowId: string; configRevision: string } | number {
+  forTask = false,
+): { projectRoot: string; workflowId: string; configRevision: string; defaultHarness: string; prerequisites: KxmRunHandoff[] } | number {
   if (runtime.workspaceFlag !== undefined) {
     print(runtime.io, runtime.json, {
       ok: false,
@@ -409,7 +424,7 @@ export function resolveKxmRunTarget(
     }, "kxm run discovers the authoritative project from the current directory; --workspace is not supported");
     return 2;
   }
-  if (!workflow) {
+  if (!workflow && !forTask) {
     print(runtime.io, runtime.json, { ok: false, command: "run", error: "workflow_required" }, "usage: kxm run <workflow> [prompt]");
     return 2;
   }
@@ -419,16 +434,26 @@ export function resolveKxmRunTarget(
     return 1;
   }
   const bundle = loadKxmProject(projectRoot, {});
-  if (!bundle.workflows.has(workflow)) {
-    print(runtime.io, runtime.json, { ok: false, command: "run", error: "run_workflow_unknown", workflow }, `workflow ${workflow} does not exist in this project`);
+  const workflowId = workflow ?? String(bundle.project.value.defaultWorkflow ?? "default");
+  if (!bundle.workflows.has(workflowId)) {
+    print(runtime.io, runtime.json, { ok: false, command: "run", error: "run_workflow_unknown", workflow: workflowId }, `workflow ${workflowId} does not exist in this project`);
+    return 1;
+  }
+  const defaultHarness = String(bundle.project.value.defaultHarness ?? "pi");
+  const prerequisites = kxmLiveRunPrerequisites(bundle, workflowId, projectRoot);
+  if (forTask && prerequisites.length > 0) {
+    print(runtime.io, runtime.json, {
+      ok: false, command: "task run", error: "run_execution_unavailable", workflowId, defaultHarness,
+      execution: { status: "not_started", mode: "live", prerequisites },
+    }, `task run refused; no run created or task changed (default harness: ${defaultHarness}).\n${prerequisites.map((item) => `${item.stepId ?? workflowId}: ${item.detail}`).join("\n")}`);
     return 1;
   }
-  return { projectRoot, workflowId: workflow, configRevision: bundle.configRevision };
+  return { projectRoot, workflowId, configRevision: bundle.configRevision, defaultHarness, prerequisites };
 }
 
-export async function cmdKxmRun(runtime: Runtime, workflow: string | undefined, promptParts: string[]): Promise<number> {
+export async function cmdKxmRun(runtime: Runtime, workflow: string | undefined, promptParts: string[], forTask = false): Promise<number> {
   try {
-    const target = resolveKxmRunTarget(runtime, workflow);
+    const target = resolveKxmRunTarget(runtime, workflow, forTask);
     if (typeof target === "number") return target;
     const { projectRoot } = target;
     if (runtime.dryRun) {
@@ -451,11 +476,23 @@ export async function cmdKxmRun(runtime: Runtime, workflow: string | undefined,
     print(runtime.io, runtime.json, {
       ok: true,
       command: "run",
-      phase: RUN_ENGINE_PHASE,
+      execution: {
+        status: "not_started",
+        mode: "live",
+        defaultHarness: target.defaultHarness,
+        authentication: "not_checked",
+        prerequisites: target.prerequisites,
+        nextSteps: {
+          harnesses: "kxm harness list",
+          drive: `kxm runs drive ${run.runId} --wait`,
+          status: `kxm runs status ${run.runId} --json`,
+          receipt: `kxm runs receipt ${run.runId} --json`,
+        },
+      },
       idempotent: acceptance.idempotent === true,
       run,
       supervisor: { runtimeId: supervisor.runtimeId, port: supervisor.port, started: supervisor.started },
-    }, `run ${run.status}: ${run.runId} (home ${run.homeRuntimeId.slice(0, 12)}…, config ${run.configRevision.slice(0, 19)}…)\n${runEngineNotice(run.runId)}`);
+    }, `run ${run.status}: ${run.runId} (home ${run.homeRuntimeId.slice(0, 12)}…, config ${run.configRevision.slice(0, 19)}…)\n${runEngineNotice(run.runId, target.defaultHarness, target.prerequisites)}`);
     return 0;
   } catch (error) {
     if (error instanceof KxmConfigError) {
@@ -782,9 +819,20 @@ export async function cmdTenantStatus(runtime: Runtime): Promise<number> {
 }
 
 export async function cmdHarnessList(runtime: Runtime): Promise<number> {
-  const inventory = await probeHarnessesAsync({ env: runtime.env });
-  print(runtime.io, runtime.json, { ok: true, command: "harness list", ...inventory }, formatHarnessInventory(inventory));
-  return 0;
+  try {
+    const projectRoot = discoverKxmProjectRoot(runtime.cwd);
+    const defaultHarness = projectRoot ? String(loadKxmProject(projectRoot).project.value.defaultHarness ?? "pi") : undefined;
+    const inventory = await probeHarnessesAsync({ env: runtime.env, defaultHarness });
+    print(runtime.io, runtime.json, { ok: true, command: "harness list", ...inventory }, formatHarnessInventory(inventory));
+    return 0;
+  } catch (error) {
+    if (error instanceof KxmConfigError) {
+      print(runtime.io, runtime.json, { ok: false, command: "harness list", error: "harness_list_failed", issues: error.issues }, `harness list failed: ${error.message}`);
+      return 1;
+    }
+    print(runtime.io, runtime.json, { ok: false, command: "harness list", error: "harness_list_io_failed" }, "harness list failed because a local operation did not complete");
+    return 1;
+  }
 }
 
 export async function selectInventoryModel(runtime: Runtime, requested?: string | undefined): Promise<string | undefined> {

package/plugins/kxm/src/cli/roles.ts

@@ -15,9 +15,10 @@ import {
   loadRoleHostsConfig,
   setRoleSeatHost,
   resolveRoleSeat,
+  parseRoleFile,
   type KxmRoleDefinition,
 } from "../role.ts";
-import { discoverKxmProjectRoot } from "../project-config.ts";
+import { discoverKxmProjectRoot, kxmRoleWriteIssues } from "../project-config.ts";
 import { ensureKxmSupervisor, kxmRuntimeRequest } from "../runtime-supervisor.ts";
 import { projectRuntimeOwnsRun } from "../runtime-store.ts";
 import { resumeWorkflowFromRuling, type WorkflowRun } from "../workflow.ts";
@@ -156,6 +157,7 @@ export async function cmdRoleAdd(
   },
 ): Promise<number> {
   const scope = options.scope ?? "local";
+  let base: KxmRoleDefinition | undefined;
   if (!roleId || options.pick) {
     const candidates: PickCandidate[] = Object.values(DEFAULT_ROLES).map((r) => ({
       id: r.id,
@@ -166,8 +168,10 @@ export async function cmdRoleAdd(
     if (scope === "local") {
       const globalRoles = listRoles({ scope: "global", userConfigDir: runtime.env.KXM_USER_CONFIG_DIR });
       for (const gr of globalRoles) {
-        if (!candidates.some((c) => c.id === gr.id)) {
-          candidates.push({ id: gr.id, description: gr.description, label: "global", payload: gr });
+        // The listing is a summary; the copy needs the definition, read from the listed file (it may be `.yml`).
+        const definition = parseRoleFile(gr.filePath);
+        if (definition && !candidates.some((c) => c.id === gr.id)) {
+          candidates.push({ id: gr.id, description: gr.description, label: "global", payload: definition });
         }
       }
     }
@@ -179,63 +183,66 @@ export async function cmdRoleAdd(
       }
     } else {
       roleId = picked.id;
-      if (!options.file && picked.payload && DEFAULT_ROLES[picked.id]) {
-        const base = DEFAULT_ROLES[picked.id]!;
-        const roleDef: KxmRoleDefinition = {
-          ...base,
-          description: options.description || base.description,
-          skills: options.skills ? options.skills.split(",").map((s) => s.trim()).filter(Boolean) : base.skills,
-          roster: options.model ? [{ harness: options.harness ?? "pi", model: options.model }] : base.roster,
-        };
-        try {
-          const res = addRole(roleDef, {
-            scope,
-            repoRoot: runtime.cwd,
-            userConfigDir: runtime.env.KXM_USER_CONFIG_DIR,
-            overwrite: options.overwrite,
-            dryRun: runtime.dryRun,
-          });
-          if (runtime.dryRun) {
-            printPlan(runtime, { command: "role add", roleId, ...res }, [{ action: "write", target: res.filePath }], `add role '${roleId}' to ${res.scope}`);
-            return 0;
-          }
-          print(
-            runtime.io,
-            runtime.json,
-            { ok: true, command: "role add", roleId, ...res },
-            `Added role '${roleId}' to ${res.scope} (${res.filePath})\n`,
-          );
-          return 0;
-        } catch (err: unknown) {
-          runtime.io.stderr(`role add failed: ${(err as Error).message}\n`);
-          return 1;
-        }
-      }
+      base = picked.payload as KxmRoleDefinition;
     }
   }
 
+  const skills = options.skills ? options.skills.split(",").map((s) => s.trim()).filter(Boolean) : undefined;
+  const roster = options.model ? [{ harness: options.harness ?? "pi", model: options.model }] : undefined;
   let roleDef: KxmRoleDefinition;
   if (options.file) {
     const filePath = resolve(runtime.cwd, options.file);
     const content = readFileSync(filePath, "utf8");
     roleDef = parseYaml(content) as KxmRoleDefinition;
     roleDef.id = roleId!;
+  } else if (base) {
+    roleDef = {
+      ...base,
+      description: options.description || base.description,
+      skills: skills ?? base.skills,
+      roster: roster ?? base.roster,
+    };
   } else {
-    const skills = options.skills ? options.skills.split(",").map((s) => s.trim()).filter(Boolean) : [];
-    const roster = options.model ? [{ harness: options.harness ?? "pi", model: options.model }] : [];
     roleDef = {
       schema: "kxm.role.v1",
       id: roleId!,
       description: options.description || `Role ${roleId}`,
-      skills,
-      roster,
+      skills: skills ?? [],
+      roster: roster ?? [],
     };
   }
 
+  // A local role file sits in the project the loader reads, and the loader refuses the
+  // whole project over a writer roster it rejects, so the role is checked before it lands.
+  let repoRoot = runtime.cwd;
+  if (scope === "local") {
+    const projectRoot = discoverKxmProjectRoot(runtime.cwd);
+    if (!projectRoot) {
+      print(
+        runtime.io,
+        runtime.json,
+        { ok: false, command: "role add", error: "project_not_found" },
+        "role add failed: local roles belong to a KXM project; run kxm init at the repository root, or pass --scope global",
+      );
+      return 2;
+    }
+    const issues = kxmRoleWriteIssues(projectRoot, roleDef.id, stringifyYaml(roleDef));
+    if (issues.length > 0) {
+      print(
+        runtime.io,
+        runtime.json,
+        { ok: false, command: "role add", error: "role_invalid", issues },
+        `role add failed: with this role the project would not load, so nothing was written\n${issues.map((entry) => `  ${entry.file}: ${entry.code}: ${entry.message}`).join("\n")}`,
+      );
+      return 2;
+    }
+    repoRoot = projectRoot;
+  }
+
   try {
     const res = addRole(roleDef, {
       scope,
-      repoRoot: runtime.cwd,
+      repoRoot,
       userConfigDir: runtime.env.KXM_USER_CONFIG_DIR,
       overwrite: options.overwrite,
       dryRun: runtime.dryRun,

package/plugins/kxm/src/cli/system.ts

@@ -2,10 +2,12 @@ import { spawnSync } from "node:child_process";
 import { createHash } from "node:crypto";
 import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { homedir, tmpdir } from "node:os";
-import { join, resolve } from "node:path";
+import { basename, extname, join, resolve } from "node:path";
 import { createInterface } from "node:readline";
 import { verifyArtifactExists } from "../artifacts-exist.ts";
 import { parseWorkflowDefinitions } from "../workflow.ts";
+import { KxmConfigError, KxmSchemaRegistry, parseRestrictedYaml } from "../project-config.ts";
+import { compileKxmWorkflow } from "../engine-compile.ts";
 import { redactSecrets } from "../redact.ts";
 import {
   telemetryPath,
@@ -478,6 +480,22 @@ export async function cmdValidate(runtime: Runtime, fileFlag?: string | undefine
   }
   try {
     const raw = file ? readFileSync(file, "utf8") : inline!;
+    // Local workflow mappings use the runner's restricted YAML/schema/compiler.
+    // Webhook sources remain JSON arrays with their existing secret checks.
+    if (explicitFile && file && !raw.trimStart().startsWith("[")) {
+      const value = parseRestrictedYaml(raw, file);
+      const issues = new KxmSchemaRegistry().validate("workflow", value, file);
+      if (issues.length > 0) throw new KxmConfigError(issues);
+      const id = basename(file, extname(file));
+      compileKxmWorkflow({ id, value, logicalPath: file });
+      printWorker(
+        runtime,
+        worker,
+        { ok: true, command: "validate", source: "file", file, workflows: [{ id, schema: value.schema }], warnings: [] },
+        `validated local workflow ${id} (schema and transitions); kxm init validates project references`,
+      );
+      return 0;
+    }
     const warnings: string[] = [];
     const definitions = parseWorkflowDefinitions(raw, runtime.env, (message) => warnings.push(message));
     const secretEnvs = definitions.map((definition) => ({