@kontextmind/kxm 0.7.104 → 0.7.106

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 };
 }