@kontextmind/kxm 0.7.104 → 0.7.105

package/plugins/kxm/src/engine.ts

@@ -3,7 +3,6 @@ import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { parse } from "yaml";
 import { isRouteAdmitted, listRoleBindings } from "./routes.ts";
-import { oneShotWriterArgs } from "./harness.ts";
 import { applyAuthoringWitness, captureWorktreeWitness } from "./worktree-witness.ts";
 import {
   buildFormalContextPacket,
@@ -14,6 +13,7 @@ import {
   type HandoffManifestV1,
 } from "./context-packet.ts";
 import { compileKxmWorkflow, type KxmCompiledPlan, type KxmCompiledStep } from "./engine-compile.ts";
+import { BUILTIN_HARNESSES, oneShotPermissionArgs, oneShotWriterArgs, validateHarnessModelPair } from "./harness.ts";
 import {
   effectiveRunDurationBudget,
   isTerminalRunStatus,
@@ -2693,7 +2693,83 @@ function armRunDurationBudgetTimer(context: KxmRuntimeContext, runId: string): (
   };
 }
 
-function unsupportedLimit(envelope: KxmRunPlanEnvelope): KxmRunHandoff | undefined {
+/** Read-only admission guidance for a live run, using the same policies as dispatch. */
+export function kxmLiveRunPrerequisites(
+  bundle: KxmProjectBundle,
+  workflowId: string,
+  projectRoot: string,
+): KxmRunHandoff[] {
+  const workflow = bundle.workflows.get(workflowId);
+  if (!workflow) throw runtimeError("run_workflow_unknown", workflowId, `workflow ${workflowId} does not exist in this project`);
+  const plan = compileKxmWorkflow({ id: workflowId, value: workflow.value, logicalPath: workflow.logicalPath });
+  const envelope = { plan, projectLimits: kxmProjectAdmissionLimits(bundle), gates: pinnedGatesForCompiledPlan(plan, bundle, projectRoot) };
+  const prerequisites: KxmRunHandoff[] = [];
+  const limit = unsupportedLimit(envelope);
+  if (limit) prerequisites.push(limit);
+  const visited = new Set<string>();
+  const pending = [plan.entryStepId];
+  while (pending.length > 0) {
+    const stepId = pending.pop()!;
+    if (visited.has(stepId)) continue;
+    visited.add(stepId);
+    const step = plan.steps[stepId]!;
+    for (const transition of Object.values(step.transitions)) {
+      if (transition.to === "step") pending.push(transition.target);
+    }
+    const unsupported = step.kind === "gate"
+      ? unsupportedGateStep(plan, step, envelope, { projectRoot }) ?? starterGatePrerequisite(step, envelope.gates, projectRoot)
+      : unsupportedStep(plan, step, "oneshot");
+    if (unsupported) {
+      prerequisites.push({ ...unsupported, stepId });
+      continue;
+    }
+    if (step.kind !== "agent" && step.kind !== "moa") continue;
+    const agentIds = step.assignments.allowedAgents.length > 0 ? step.assignments.allowedAgents : [step.agent];
+    for (const agentId of agentIds) {
+      const agent = bundle.agents.get(agentId);
+      const harness = String(agent?.value.harness ?? bundle.project.value.defaultHarness ?? "pi");
+      const permission = Object.values(step.repositories).includes("write") ? "edit" : "read-only";
+      if (!BUILTIN_HARNESSES.some((entry) => entry.id === harness && entry.oneShot) || !oneShotPermissionArgs(harness, permission)) {
+        prerequisites.push({ reason: "step_unsupported", stepId, field: "harness", detail: `${agentId}: ${harness} has no audited ${permission} one-shot profile; use a supported workflow or execute this work directly in ${harness}, without substituting another harness` });
+        continue;
+      }
+      const route = resolveProducerRoute(projectRoot, step, agentId);
+      if ("error" in route) {
+        prerequisites.push({ ...route.error, stepId, detail: `${agentId}: ${route.error.detail}; configure its model in .kxm/agents/${agentId}.yaml and admit the installed model with kxm routes admit --model <provider/model>` });
+        continue;
+      }
+      const writeRefusal = unsupportedLiveWrite(projectRoot, step, agentId, route.selector, envelope.projectLimits.maxConcurrentRuns);
+      if (writeRefusal) {
+        prerequisites.push({ ...writeRefusal, stepId });
+        continue;
+      }
+      const compatible = validateHarnessModelPair(harness, route);
+      if (!compatible.valid) {
+        prerequisites.push({ reason: "step_unsupported", stepId, field: "model", detail: `${agentId}: ${compatible.message ?? `${harness} cannot run ${route.selector}`}; configure a model supported by ${harness} in .kxm/agents/${agentId}.yaml` });
+      }
+    }
+  }
+  return prerequisites;
+}
+
+function starterGatePrerequisite(step: KxmCompiledStep & { kind: "gate" }, gates: KxmPinnedGates, projectRoot: string): Omit<KxmRunHandoff, "stepId"> | undefined {
+  const definition = gates.definitions[step.gate];
+  if (!definition || definition.kind !== "command" || definition.argv.length !== 2 || definition.argv[0] !== "npm" || definition.argv[1] !== "test") return undefined;
+  let testScript: unknown;
+  try {
+    const manifest: unknown = JSON.parse(readFileSync(join(projectRoot, "package.json"), "utf8"));
+    if (manifest && typeof manifest === "object" && "scripts" in manifest) {
+      const scripts = manifest.scripts;
+      if (scripts && typeof scripts === "object" && "test" in scripts) testScript = scripts.test;
+    }
+  } catch { /* A missing or unreadable manifest cannot satisfy the starter gate. */ }
+  if (typeof testScript !== "string" || testScript.trim().length === 0) {
+    return { reason: "gate_unsupported", field: `gates.${step.gate}.argv`, detail: `gate ${step.gate} runs npm test but this repository has no readable package.json with scripts.test; configure .kxm/gates.yaml gates.${step.gate}.argv for the repository's actual test runner before driving this workflow` };
+  }
+  return undefined;
+}
+
+function unsupportedLimit(envelope: Pick<KxmRunPlanEnvelope, "plan" | "projectLimits">): KxmRunHandoff | undefined {
   if (envelope.plan.limits.maxAgentTimeMs !== undefined) {
     return { reason: "limit_unsupported", field: "limits.maxAgentTimeMs", detail: "agent-time budget enforcement is not available in this slice" };
   }
@@ -2847,7 +2923,7 @@ function unsupportedLiveWrite(
   return undefined;
 }
 
-function unsupportedGateStep(plan: KxmCompiledPlan, step: KxmCompiledStep & { kind: "gate" }, envelope: KxmRunPlanEnvelope, context?: { projectRoot: string }): Omit<KxmRunHandoff, "stepId"> | undefined {
+function unsupportedGateStep(plan: KxmCompiledPlan, step: KxmCompiledStep & { kind: "gate" }, envelope: Pick<KxmRunPlanEnvelope, "gates">, context?: { projectRoot: string }): Omit<KxmRunHandoff, "stepId"> | undefined {
   if (!step.gate) return { reason: "step_unsupported", field: "gate", detail: "gate step is missing gate id" };
   if (envelope.gates.registry === null) {
     return { reason: "step_unsupported", field: "gate", detail: `step ${step.id} refers to a gate but registry is null` };

package/plugins/kxm/src/harness.ts

@@ -62,6 +62,7 @@ export type HarnessRunCommand = (command: string, args: readonly string[], timeo
 export type HarnessRunCommandAsync = (command: string, args: readonly string[], timeoutMs: number) => HarnessCommandResult | Promise<HarnessCommandResult>;
 
 export interface HarnessProbeOptions {
+  defaultHarness?: string | undefined;
   env?: NodeJS.ProcessEnv | undefined;
   runCommand?: HarnessRunCommand | undefined;
   timeoutMs?: number | undefined;
@@ -96,7 +97,7 @@ export interface HarnessStatus {
 }
 
 export interface HarnessInventory {
-  defaultHarness: typeof DEFAULT_HARNESS;
+  defaultHarness: string;
   harnesses: readonly HarnessStatus[];
 }
 
@@ -958,7 +959,7 @@ function probeEntry(
   runCommand: (command: string, args: readonly string[], timeoutMs: number) => HarnessCommandResult,
   timeoutMs: number,
   platform: NodeJS.Platform,
-  probe: Pick<HarnessProbeOptions, "env" | "existsSync"> = {},
+  probe: Pick<HarnessProbeOptions, "env" | "existsSync" | "defaultHarness"> = {},
 ): HarnessStatus {
   const issues: string[] = [];
   const found = detectHarnessCommand(entry, runCommand, timeoutMs, platform, probe);
@@ -987,7 +988,7 @@ function probeEntry(
   return {
     id: entry.id,
     label: entry.label,
-    default: entry.default,
+    default: entry.id === (probe.defaultHarness ?? DEFAULT_HARNESS),
     mode: entry.mode,
     detected,
     authenticated,
@@ -1009,7 +1010,7 @@ export function probeHarnesses(options: HarnessProbeOptions = {}): HarnessInvent
   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)),
   };
 }
@@ -1508,7 +1509,7 @@ export function formatHarnessInventory(inventory: HarnessInventory): string {
     ].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,

package/plugins/kxm/src/mcp-server.ts

@@ -11,7 +11,7 @@ import { deliverInboxNotification } from "./inbox.ts";
 import type { HubEvent, MessageRecord } from "./protocol.ts";
 import { sessionTokenFixHint } from "./session-token-hint.ts";
 
-const VERSION = "0.7.104";
+const VERSION = "0.7.105";
 const CONFIGURE_PLUGIN = "/plugin configure kxm@kxm";
 const inbox = new Map<string, MessageRecord>();
 const notifiedInbox = new Set<string>();

package/plugins/kxm/src/suggest.ts

@@ -1,156 +1,209 @@
+import { BUILTIN_HARNESS_IDS, oneShotWriterArgs, type HarnessStatus } from "./harness.ts";
+import { WORKFLOW_TEMPLATES } from "./workflow-manager.ts";
+
 export interface RoleSpec {
+  agent: string;
   harness: string;
-  model: string;
   role: string;
 }
 
+export type SuggestionExecution = {
+  supported: true;
+  prerequisites: string[];
+  shell: "powershell" | "posix";
+  createCommand: string;
+  driveCommand: string;
+  statusCommand: string;
+  receiptCommand: string;
+} | {
+  supported: false;
+  error: "harness_unavailable" | "live_write_unsupported" | "workflow_already_exists";
+  reason: string;
+  nextSteps: string[];
+};
+
 export interface SuggestionResult {
   workflowId: string;
+  template: string;
   area: string;
   confidence: number;
   reasons: string[];
   suggestedSkills: string[];
-  roles: {
-    planner: RoleSpec;
-    writer: RoleSpec;
-    critics: RoleSpec[];
-    verifier: { kind: "witness"; command: string };
-  };
+  roles: RoleSpec[];
+  /** Installs a definition; it does not create or execute a run. */
   suggestedCommand: string;
+  execution: SuggestionExecution;
 }
 
 interface WorkflowPattern {
   id: string;
+  template: string;
   area: string;
   keywords: string[];
   skills: string[];
-  defaultCommand: (prompt: string) => string;
 }
 
 const WORKFLOW_PATTERNS: WorkflowPattern[] = [
   {
-    id: "software-engineering/bug-fix",
+    id: "bug-fix",
+    template: "implement-and-verify",
     area: "software-engineering",
     keywords: ["fix", "bug", "flaky", "failure", "timeout", "error", "repro", "crash", "broken", "hang"],
     skills: ["kxm-workflow", "kxm-runs", "kxm-context-memory"],
-    defaultCommand: (p) => `kxm run software-engineering/bug-fix "${p}"`,
   },
   {
-    id: "software-engineering/feature-implementation",
+    id: "feature-implementation",
+    template: "implement-and-verify",
     area: "software-engineering",
     keywords: ["feature", "implement", "add", "build", "create", "develop", "support", "endpoint", "ui", "tui"],
     skills: ["kxm-workflow", "kxm-peer", "kxm-context-memory"],
-    defaultCommand: (p) => `kxm run software-engineering/feature-implementation "${p}"`,
   },
   {
-    id: "software-engineering/refactoring",
+    id: "refactoring",
+    template: "dual-critic-review",
     area: "software-engineering",
     keywords: ["refactor", "cleanup", "reorganize", "modularize", "deduplicate", "split", "simplify", "deprecate"],
     skills: ["kxm-workflow", "kxm-runs"],
-    defaultCommand: (p) => `kxm run software-engineering/refactoring "${p}"`,
   },
   {
-    id: "security-reliability/vulnerability-remediation",
+    id: "vulnerability-remediation",
+    template: "dual-critic-review",
     area: "security-reliability",
     keywords: ["cve", "vulnerability", "security", "exploit", "sanitize", "leak", "secret", "injection", "redact", "auth"],
     skills: ["kxm-workflow", "kxm-definitions"],
-    defaultCommand: (p) => `kxm run security-reliability/vulnerability-remediation "${p}"`,
   },
   {
-    id: "security-reliability/reliability-hardening",
+    id: "reliability-hardening",
+    template: "dual-critic-review",
     area: "security-reliability",
     keywords: ["idempotency", "retry", "circuit-breaker", "cas", "lock", "concurrency", "deadlock", "race", "crash-recovery"],
     skills: ["kxm-workflow", "kxm-peer"],
-    defaultCommand: (p) => `kxm run security-reliability/reliability-hardening "${p}"`,
   },
   {
-    id: "data-analytics/pipeline-migration",
+    id: "pipeline-migration",
+    template: "implement-and-verify",
     area: "data-analytics",
     keywords: ["database", "sqlite", "migration", "pipeline", "schema", "transform", "table", "wal", "foreign", "cascading"],
     skills: ["kxm-runs", "kxm-context-memory"],
-    defaultCommand: (p) => `kxm run data-analytics/pipeline-migration "${p}"`,
   },
   {
-    id: "research-strategy/architecture-spike",
+    id: "architecture-spike",
+    template: "spec-and-plan",
     area: "research-strategy",
     keywords: ["spike", "investigate", "prototype", "research", "feasibility", "benchmark", "explore", "evaluate"],
     skills: ["kxm-session", "kxm-context-memory", "kxm-routing-improve"],
-    defaultCommand: (p) => `kxm run research-strategy/architecture-spike "${p}"`,
   },
 ];
 
+type TemplateStep = { id: string; kind: string; agent?: string; repositories?: Record<string, string> };
+type SuggestionHarness = Pick<HarnessStatus, "id" | "detected" | "authenticated" | "dispatch">;
+
 export function suggestWorkflowAndRoles(
   prompt: string,
-  options: {
-    availableHarnesses?: Array<{ harness: string; auth?: string | undefined }> | undefined;
-  } = {},
+  options: { availableHarnesses?: readonly SuggestionHarness[] | undefined } = {},
 ): SuggestionResult {
   const normalized = prompt.toLowerCase();
   const words = normalized.split(/\W+/).filter(Boolean);
-
-  let bestPattern: WorkflowPattern = WORKFLOW_PATTERNS[0]!;
-  let bestScore = -1;
-  const matchedReasons: string[] = [];
+  const claudeOnly = /\bclaude(?:\s+code)?(?:[\s-]+only|\s+exclusively)\b|\b(?:only|exclusively)(?:\s+(?:use|using|with|via))?\s+claude(?:\s+code)?\b/i.test(prompt);
+  let bestPattern: WorkflowPattern = WORKFLOW_PATTERNS[1]!;
+  let bestScore = 0;
+  const reasons: string[] = [];
 
   for (const pattern of WORKFLOW_PATTERNS) {
-    let score = 0;
-    const matchedWords: string[] = [];
-    for (const keyword of pattern.keywords) {
-      if (words.includes(keyword) || normalized.includes(keyword)) {
-        score += 1;
-        matchedWords.push(keyword);
-      }
-    }
-    if (score > bestScore) {
-      bestScore = score;
+    const matchedWords = pattern.keywords.filter((keyword) => words.includes(keyword) || normalized.includes(keyword));
+    if (matchedWords.length > bestScore) {
+      bestScore = matchedWords.length;
       bestPattern = pattern;
-      matchedReasons.length = 0;
-      matchedReasons.push(`Matched keywords: ${matchedWords.join(", ")}`);
+      reasons.length = 0;
+      reasons.push(`Matched keywords: ${matchedWords.join(", ")}`);
     }
   }
+  if (bestScore === 0) reasons.push("Default fallback: general feature implementation workflow");
+  if (claudeOnly) reasons.push("Explicit Claude-only constraint; other harnesses are excluded");
 
-  if (bestScore <= 0) {
-    bestPattern = WORKFLOW_PATTERNS[1]!;
-    matchedReasons.push("Default fallback: general feature implementation workflow");
-  }
-
-  const activeHarnesses = new Set(
-    (options.availableHarnesses ?? [])
-      .filter((h) => h.auth === "active" || h.auth === "ready" || h.auth === "configured")
-      .map((h) => h.harness.toLowerCase()),
-  );
-
-  const hasClaude = activeHarnesses.size === 0 || activeHarnesses.has("claude");
-  const hasGrok = activeHarnesses.size === 0 || activeHarnesses.has("grok");
-  const hasCodex = activeHarnesses.size === 0 || activeHarnesses.has("codex");
-
-  const planner: RoleSpec = hasClaude
-    ? { harness: "claude", model: "fable", role: "planner" }
-    : { harness: "codex", model: "gpt-5.6-sol", role: "planner" };
-
-  const writer: RoleSpec = hasGrok
-    ? { harness: "grok", model: "grok-4.6", role: "writer" }
-    : (activeHarnesses.has("agy")
-      ? { harness: "agy", model: "gemini-2.5-pro", role: "writer" }
-      : { harness: "pi", model: "qwen/qwen3-coder-plus", role: "writer" });
-
-  const critics: RoleSpec[] = [
-    { harness: "claude", model: "fable", role: "reviewer-arch" },
-    { harness: "codex", model: "gpt-5.6-sol", role: "reviewer-cli" },
-  ];
-
-  return {
+  const template = WORKFLOW_TEMPLATES[bestPattern.template]!;
+  const steps = template.steps as TemplateStep[];
+  const base = {
     workflowId: bestPattern.id,
+    template: bestPattern.template,
     area: bestPattern.area,
     confidence: bestScore > 0 ? Math.min(1, 0.5 + bestScore * 0.15) : 0.5,
-    reasons: matchedReasons,
+    reasons,
     suggestedSkills: bestPattern.skills,
-    roles: {
-      planner,
-      writer,
-      critics,
-      verifier: { kind: "witness", command: "npm run verify" },
+    suggestedCommand: `kxm workflow add ${bestPattern.id} --template ${bestPattern.template}`,
+  };
+  const writeStep = steps.find((step) => step.kind === "agent" && Object.values(step.repositories ?? {}).includes("write"));
+
+  const available = (options.availableHarnesses ?? []).filter((entry) =>
+    BUILTIN_HARNESS_IDS.includes(entry.id) && entry.detected && entry.authenticated === true
+    && entry.dispatch?.supported === true && entry.dispatch.status === "yes"
+    && (!claudeOnly || entry.id === "claude"));
+  const selected = available.find((entry) => entry.id === "claude") ?? available[0];
+  if (!selected) {
+    const relevant = (options.availableHarnesses ?? []).filter((entry) => !claudeOnly || entry.id === "claude");
+    const detail = relevant.map((entry) => `${entry.id}: ${entry.dispatch?.reason ?? (!entry.detected ? "not_detected" : entry.authenticated !== true ? "authentication_unverified" : "dispatch_unavailable")}`).join("; ");
+    return {
+      ...base,
+      roles: [],
+      execution: {
+        supported: false,
+        error: "harness_unavailable",
+        reason: `${claudeOnly ? "Claude-only execution requires Claude Code" : "Execution requires a supported harness"} detected, authenticated, and ready for dispatch. ${detail || "No verified harness inventory is available."}`,
+        nextSteps: claudeOnly
+          ? ["Install Claude Code if missing, authenticate with claude auth login, then confirm claude auth status and kxm harness list. Other harnesses will not be substituted."]
+          : ["Install and authenticate a supported harness, then run kxm harness list to check detection, authentication, and dispatch readiness. Pi requires a configured model/provider auth context."],
+      },
+    };
+  }
+
+  if (writeStep && !oneShotWriterArgs(selected.id)) {
+    return {
+      ...base,
+      roles: [],
+      execution: {
+        supported: false,
+        error: "live_write_unsupported",
+        reason: `${bestPattern.template} requires repository writes at step ${writeStep.id}, but the selected ${selected.id} harness has no audited live writer profile. No other harness will be substituted.`,
+        nextSteps: [
+          `Run the implementation directly in ${claudeOnly ? "Claude Code" : selected.id} in the target worktree, and run the repository's actual verification command.`,
+          `For read-only KXM planning, try kxm suggest "Investigate an architecture spike${claudeOnly ? " using Claude only" : ""}"; the shipped spec-and-plan template does not implement changes.`,
+          "Installing a definition or creating a run does not execute it. Simulation is not evidence of a bug fix or workflow completion.",
+        ],
+      },
+    };
+  }
+
+  const roles: RoleSpec[] = [];
+  for (const step of steps) {
+    if (!step.agent) continue;
+    const role = roles.find((entry) => entry.agent === step.agent);
+    if (role) role.role += `, ${step.id}`;
+    else roles.push({ agent: step.agent, harness: selected.id, role: step.id });
+  }
+  const shell = process.platform === "win32" ? "powershell" : "posix";
+  const quotedPrompt = shell === "powershell"
+    ? `'${prompt.replace(/['\u2018-\u201b]/g, "$&$&")}'`
+    : `'${prompt.replace(/'/g, "'\\''")}'`;
+  return {
+    ...base,
+    roles,
+    execution: {
+      supported: true,
+      prerequisites: [
+        "Run kxm init in the target repository if needed, then install the exact template with the suggested command. If that workflow ID already exists, stop and review it; the commands below apply only to a newly installed template, not an existing definition with potentially different agents or permissions.",
+        ...roles.map((role) => `Set harness: ${role.harness} and model: <your authenticated compatible model selector> in .kxm/agents/${role.agent}.yaml. Admit that exact selector in .kxm/routes.yaml and ensure it is not disabled; this recommendation does not choose a model or change routing.`),
+        ...(writeStep ? [
+          `Keep each writer step at assignments.maximum: 1 and set limits.maxConcurrentRuns: 1 in .kxm/project.yaml; the live ${selected.id} writer profile requires a lone writer in the checkout.`,
+          `If .kxm/roster.yaml exists, it must be readable kxm.developer-roster.v1 with a lineup.writer route matching harness: ${selected.id} and the selected writer model (model or vendor/model), status: admitted, and permissions containing edit.`,
+          "Configure the test gate in .kxm/gates.yaml with kind: command and argv for this repository's actual verification command. A scaffold/example command or simulation is not evidence that the implementation works.",
+        ] : []),
+        `Validate the installed workflow with kxm gate validate --file .kxm/workflows/${bestPattern.id}.yaml and the project configuration with kxm init --dry-run before creating a run.`,
+      ],
+      shell,
+      createCommand: `kxm run ${bestPattern.id} -- ${quotedPrompt}`,
+      driveCommand: "kxm runs drive <runId> --wait",
+      statusCommand: "kxm runs status <runId>",
+      receiptCommand: "kxm runs receipt <runId>",
     },
-    suggestedCommand: bestPattern.defaultCommand(prompt.replace(/"/g, '\\"')),
   };
 }

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

@@ -5,9 +5,28 @@
  */
 
 import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
-import { dirname, join, resolve } from "node:path";
-import { parse, stringify } from "yaml";
+import { join } from "node:path";
+import { stringify } from "yaml";
 import { repoConfigDirectory, userConfigDirectory } from "./config.ts";
+import { compileKxmWorkflow } from "./engine-compile.ts";
+import { KxmConfigError, KxmSchemaRegistry, kxmResourceIdentifier, parseRestrictedYaml } from "./project-config.ts";
+
+function assertWorkflowId(workflowId: string): void {
+  if (!kxmResourceIdentifier(workflowId)) {
+    throw new Error(`workflow_id_invalid: '${workflowId}' must be a flat lowercase slug of at most 64 characters, starting with a letter and using letters, digits, single hyphens or underscores; paths and platform-reserved names are not allowed (use 'bug-fix', not 'software-engineering/bug-fix')`);
+  }
+}
+
+let workflowSchemaRegistry: KxmSchemaRegistry | undefined;
+
+function workflowPayload(workflowId: string, content: Record<string, unknown> | string, filePath: string): string {
+  const payload = typeof content === "string" ? content : stringify(content);
+  const value = parseRestrictedYaml(payload, filePath);
+  const issues = (workflowSchemaRegistry ??= new KxmSchemaRegistry()).validate("workflow", value, filePath);
+  if (issues.length > 0) throw new KxmConfigError(issues);
+  compileKxmWorkflow({ id: workflowId, value, logicalPath: filePath });
+  return payload;
+}
 
 export interface WorkflowDefSummary {
   id: string;
@@ -197,9 +216,7 @@ export function parseWorkflowFile(filePath: string): Record<string, unknown> | u
   if (!existsSync(filePath)) return undefined;
   try {
     const raw = readFileSync(filePath, "utf8");
-    const parsed = parse(raw) as Record<string, unknown>;
-    if (!parsed || typeof parsed !== "object") return undefined;
-    return parsed;
+    return parseRestrictedYaml(raw, filePath);
   } catch {
     return undefined;
   }
@@ -218,11 +235,11 @@ export function listWorkflowDefinitions(options: {
   const localDefs = new Map<string, { def: Record<string, unknown>; filePath: string }>();
   if (scopeFilter !== "global" && existsSync(localDir)) {
     for (const entry of readdirSync(localDir)) {
-      if (entry.endsWith(".yaml") || entry.endsWith(".yml")) {
+      const id = entry.endsWith(".yaml") ? entry.slice(0, -5) : entry.endsWith(".yml") ? entry.slice(0, -4) : undefined;
+      if (id && kxmResourceIdentifier(id)) {
         const filePath = join(localDir, entry);
         const def = parseWorkflowFile(filePath);
         if (def) {
-          const id = (def.id as string) || entry.replace(/\.ya?ml$/i, "");
           localDefs.set(id, { def, filePath });
         }
       }
@@ -232,11 +249,11 @@ export function listWorkflowDefinitions(options: {
   const globalDefs = new Map<string, { def: Record<string, unknown>; filePath: string }>();
   if (scopeFilter !== "local" && existsSync(globalDir)) {
     for (const entry of readdirSync(globalDir)) {
-      if (entry.endsWith(".yaml") || entry.endsWith(".yml")) {
+      const id = entry.endsWith(".yaml") ? entry.slice(0, -5) : entry.endsWith(".yml") ? entry.slice(0, -4) : undefined;
+      if (id && kxmResourceIdentifier(id)) {
         const filePath = join(globalDir, entry);
         const def = parseWorkflowFile(filePath);
         if (def) {
-          const id = (def.id as string) || entry.replace(/\.ya?ml$/i, "");
           globalDefs.set(id, { def, filePath });
         }
       }
@@ -248,7 +265,7 @@ export function listWorkflowDefinitions(options: {
     const steps = Array.isArray(def.steps) ? def.steps : [];
     for (const step of steps) {
       if (step && typeof step === "object") {
-        const role = (step as Record<string, unknown>).role || (step as Record<string, unknown>).agent;
+        const role = (step as Record<string, unknown>).agent;
         if (typeof role === "string" && !roles.includes(role)) {
           roles.push(role);
         }
@@ -298,6 +315,7 @@ export function getWorkflowDefinition(
     userConfigDir?: string | undefined;
   } = {},
 ): { workflow: Record<string, unknown>; scope: "global" | "local"; filePath: string } | undefined {
+  assertWorkflowId(workflowId);
   const scope = options.scope ?? "all";
   const repoRoot = options.repoRoot ?? process.cwd();
 
@@ -331,19 +349,21 @@ export function addWorkflowDefinition(
     dryRun?: boolean | undefined;
   } = {},
 ): { id: string; filePath: string; scope: "global" | "local" } {
+  assertWorkflowId(workflowId);
   const scope = options.scope ?? "local";
   const repoRoot = options.repoRoot ?? process.cwd();
-  const dir = options.dryRun
-    ? workflowsDirectory(scope, repoRoot, options.userConfigDir)
-    : ensureWorkflowsDirectory(scope, repoRoot, options.userConfigDir);
+  const dir = workflowsDirectory(scope, repoRoot, options.userConfigDir);
   const filePath = join(dir, `${workflowId}.yaml`);
 
   if (existsSync(filePath) && !options.overwrite) {
     throw new Error(`workflow_already_exists: workflow '${workflowId}' already exists at ${filePath}`);
   }
 
-  const payload = typeof content === "string" ? content : stringify(content);
-  if (!options.dryRun) writeFileSync(filePath, payload, "utf8");
+  const payload = workflowPayload(workflowId, content, filePath);
+  if (!options.dryRun) {
+    ensureWorkflowsDirectory(scope, repoRoot, options.userConfigDir);
+    writeFileSync(filePath, payload, "utf8");
+  }
   return { id: workflowId, filePath, scope };
 }
 
@@ -356,6 +376,7 @@ export function removeWorkflowDefinition(
     dryRun?: boolean | undefined;
   } = {},
 ): { id: string; removed: boolean; filePath: string; scope: "global" | "local" } {
+  assertWorkflowId(workflowId);
   const scope = options.scope ?? "local";
   const repoRoot = options.repoRoot ?? process.cwd();
   const dir = workflowsDirectory(scope, repoRoot, options.userConfigDir);
@@ -392,11 +413,13 @@ export function modifyWorkflowDefinition(
 
   const scope = options.scope ?? target.scope;
   const repoRoot = options.repoRoot ?? process.cwd();
-  const dir = options.dryRun
-    ? workflowsDirectory(scope, repoRoot, options.userConfigDir)
-    : ensureWorkflowsDirectory(scope, repoRoot, options.userConfigDir);
+  const dir = workflowsDirectory(scope, repoRoot, options.userConfigDir);
   const filePath = join(dir, `${workflowId}.yaml`);
 
-  if (!options.dryRun) writeFileSync(filePath, stringify(updated), "utf8");
+  const payload = workflowPayload(workflowId, updated, filePath);
+  if (!options.dryRun) {
+    ensureWorkflowsDirectory(scope, repoRoot, options.userConfigDir);
+    writeFileSync(filePath, payload, "utf8");
+  }
   return { id: workflowId, workflow: updated, filePath, scope };
 }