@kontextmind/kxm 0.6.0

package/plugins/kxm/src/studio-layout.ts

@@ -0,0 +1,268 @@
+/**
+ * KXM Web Studio Layout Engine (Phase 10 / Decision D14)
+ * Generates form/stepper metadata, ELK/React Flow-derived DAG nodes/edges,
+ * and Temporal swimlane activity timelines from compiled plans and run states.
+ */
+
+import type { VnextCompiledPlan, VnextCompiledStep } from "./vnext-engine-compile.ts";
+import type { VnextRunState } from "./vnext-engine-fold.ts";
+
+export const STUDIO_LAYOUT_SCHEMA = "kxm.studio-layout.v1" as const;
+
+export interface StudioDagNode {
+  id: string;
+  type: "agentStep" | "gateStep" | "approvalStep" | "waitStep";
+  data: {
+    label: string;
+    kind: string;
+    role?: string | undefined;
+    gate?: string | undefined;
+    status: "pending" | "preparing" | "running" | "passed" | "failed" | "waiting" | "cancelled";
+    stepAttempt?: number | undefined;
+    description?: string | undefined;
+    outcomes: readonly string[];
+  };
+  position: { x: number; y: number };
+}
+
+export interface StudioDagEdge {
+  id: string;
+  source: string;
+  target: string;
+  label?: string | undefined;
+  animated?: boolean | undefined;
+  style?: { stroke?: string } | undefined;
+}
+
+export interface TemporalSwimlaneActivity {
+  stepId: string;
+  attemptId?: string | undefined;
+  status: string;
+  startOffsetMs: number;
+  durationMs: number;
+  stepAttempt: number;
+}
+
+export interface TemporalSwimlane {
+  role: string;
+  agentId?: string | undefined;
+  activities: TemporalSwimlaneActivity[];
+}
+
+export interface StudioStepperStage {
+  id: string;
+  label: string;
+  kind: string;
+  status: "pending" | "active" | "completed" | "failed" | "skipped";
+}
+
+export interface StudioLayoutPayload {
+  schema: typeof STUDIO_LAYOUT_SCHEMA;
+  workflowId: string;
+  runId?: string | undefined;
+  generatedAt: string;
+  stepper: StudioStepperStage[];
+  dag: {
+    nodes: StudioDagNode[];
+    edges: StudioDagEdge[];
+  };
+  temporalSwimlanes: TemporalSwimlane[];
+}
+
+/**
+ * Computes deterministic layered DAG coordinates (ELK-style hierarchical ranking)
+ * without requiring any manual layout coordinates in the YAML workflow file.
+ */
+export function generateStudioLayout(
+  plan: VnextCompiledPlan,
+  state?: VnextRunState | undefined,
+): StudioLayoutPayload {
+  const generatedAt = new Date().toISOString();
+  const stepIds = Object.keys(plan.steps);
+
+  // 1. Calculate topological rank/level for each step
+  const inDegree: Record<string, number> = {};
+  const adj: Record<string, string[]> = {};
+  for (const id of stepIds) {
+    inDegree[id] = 0;
+    adj[id] = [];
+  }
+
+  for (const [sourceId, step] of Object.entries(plan.steps)) {
+    for (const transition of Object.values(step.transitions)) {
+      if (transition.to && plan.steps[transition.to]) {
+        adj[sourceId]!.push(transition.to);
+        inDegree[transition.to] = (inDegree[transition.to] ?? 0) + 1;
+      }
+    }
+  }
+
+  // Assign levels (x coordinate columns)
+  const levels: Record<string, number> = {};
+  const queue: string[] = [];
+
+  if (plan.entryStepId && plan.steps[plan.entryStepId]) {
+    queue.push(plan.entryStepId);
+    levels[plan.entryStepId] = 0;
+  } else {
+    for (const id of stepIds) {
+      if ((inDegree[id] ?? 0) === 0) {
+        queue.push(id);
+        levels[id] = 0;
+      }
+    }
+  }
+
+  while (queue.length > 0) {
+    const current = queue.shift()!;
+    const curLevel = levels[current] ?? 0;
+    for (const neighbor of adj[current] ?? []) {
+      const nextLevel = Math.max(levels[neighbor] ?? 0, curLevel + 1);
+      levels[neighbor] = nextLevel;
+      queue.push(neighbor);
+    }
+  }
+
+  // Default any unassigned step to 0
+  for (const id of stepIds) {
+    if (levels[id] === undefined) levels[id] = 0;
+  }
+
+  // Group steps by level to determine y positions
+  const byLevel: Record<number, string[]> = {};
+  for (const [id, lvl] of Object.entries(levels)) {
+    if (!byLevel[lvl]) byLevel[lvl] = [];
+    byLevel[lvl]!.push(id);
+  }
+
+  const nodes: StudioDagNode[] = [];
+  const edges: StudioDagEdge[] = [];
+  const X_SPACING = 240;
+  const Y_SPACING = 120;
+
+  for (const [lvlStr, idsInLevel] of Object.entries(byLevel)) {
+    const lvl = Number(lvlStr);
+    const x = lvl * X_SPACING;
+    const startY = -(idsInLevel.length - 1) * (Y_SPACING / 2);
+
+    idsInLevel.forEach((stepId, index) => {
+      const step = plan.steps[stepId]!;
+      const y = startY + index * Y_SPACING;
+
+      let status: StudioDagNode["data"]["status"] = "pending";
+      let stepAttempt: number | undefined = undefined;
+
+      if (state) {
+        if (state.currentStep?.stepId === stepId) {
+          status = state.currentStep.status === "running" ? "running" : "preparing";
+          stepAttempt = state.currentStep.stepAttempt;
+        } else if (state.stepAttempts[stepId] !== undefined) {
+          status = "passed";
+          stepAttempt = state.stepAttempts[stepId];
+        }
+      }
+
+      let type: StudioDagNode["type"] = "agentStep";
+      let role: string | undefined = undefined;
+      let gate: string | undefined = undefined;
+
+      if (step.kind === "agent" || step.kind === "moa") {
+        type = "agentStep";
+        role = step.agent;
+      } else if (step.kind === "gate") {
+        type = "gateStep";
+        gate = step.gate;
+      } else if (step.kind === "approval") {
+        type = "approvalStep";
+      } else if (step.kind === "wait") {
+        type = "waitStep";
+      }
+
+      nodes.push({
+        id: stepId,
+        type,
+        data: {
+          label: step.description ?? stepId,
+          kind: step.kind,
+          role,
+          gate,
+          status,
+          stepAttempt,
+          description: step.instructions,
+          outcomes: step.outcomes,
+        },
+        position: { x, y },
+      });
+
+      // Build edges
+      for (const [outcome, transition] of Object.entries(step.transitions)) {
+        if (transition.to && plan.steps[transition.to]) {
+          edges.push({
+            id: `e_${stepId}_to_${transition.to}_${outcome}`,
+            source: stepId,
+            target: transition.to,
+            label: outcome !== "passed" && outcome !== "completed" ? outcome : undefined,
+            animated: status === "running",
+            style: {
+              stroke: outcome === "failed" ? "#ef4444" : outcome === "warning" ? "#f59e0b" : "#64748b",
+            },
+          });
+        }
+      }
+    });
+  }
+
+  // 2. Stepper stages (linear path)
+  const stepper: StudioStepperStage[] = plan.order.map((stepId) => {
+    const step = plan.steps[stepId];
+    let status: StudioStepperStage["status"] = "pending";
+    if (state) {
+      if (state.currentStep?.stepId === stepId) {
+        status = "active";
+      } else if (state.stepAttempts[stepId] !== undefined) {
+        status = "completed";
+      }
+    }
+    return {
+      id: stepId,
+      label: step?.description ?? stepId,
+      kind: step?.kind ?? "unknown",
+      status,
+    };
+  });
+
+  // 3. Temporal Swimlanes
+  const swimlanesByRole: Record<string, TemporalSwimlaneActivity[]> = {};
+  let currentOffset = 0;
+
+  for (const stepId of plan.order) {
+    const step = plan.steps[stepId];
+    const role = step && (step.kind === "agent" || step.kind === "moa") ? step.agent : "engine-coordinator";
+    if (!swimlanesByRole[role]) swimlanesByRole[role] = [];
+
+    const duration = step?.timeoutMs ? Math.min(step.timeoutMs, 5000) : 3000;
+    swimlanesByRole[role]!.push({
+      stepId,
+      status: state?.currentStep?.stepId === stepId ? "running" : "completed",
+      startOffsetMs: currentOffset,
+      durationMs: duration,
+      stepAttempt: state?.stepAttempts[stepId] ?? 1,
+    });
+    currentOffset += duration;
+  }
+
+  const temporalSwimlanes: TemporalSwimlane[] = Object.entries(swimlanesByRole).map(([role, activities]) => ({
+    role,
+    activities,
+  }));
+
+  return {
+    schema: STUDIO_LAYOUT_SCHEMA,
+    workflowId: plan.workflowId,
+    runId: state ? "active-run" : undefined,
+    generatedAt,
+    stepper,
+    dag: { nodes, edges },
+    temporalSwimlanes,
+  };
+}

package/plugins/kxm/src/suggest.ts

@@ -0,0 +1,162 @@
+export interface RoleSpec {
+  harness: string;
+  model: string;
+  role: string;
+}
+
+export interface SuggestionResult {
+  workflowId: string;
+  area: string;
+  confidence: number;
+  reasons: string[];
+  suggestedSkills: string[];
+  roles: {
+    planner: RoleSpec;
+    writer: RoleSpec;
+    critics: RoleSpec[];
+    verifier: { kind: "witness"; command: string };
+  };
+  suggestedCommand: string;
+}
+
+interface WorkflowPattern {
+  id: string;
+  area: string;
+  keywords: string[];
+  skills: string[];
+  defaultCommand: (prompt: string) => string;
+}
+
+const WORKFLOW_PATTERNS: WorkflowPattern[] = [
+  {
+    id: "software-engineering/bug-fix",
+    area: "software-engineering",
+    keywords: ["fix", "bug", "flaky", "failure", "timeout", "error", "repro", "crash", "broken", "hang"],
+    skills: ["troubleshooting", "memory-leak-debugging"],
+    defaultCommand: (p) => `kxm run software-engineering/bug-fix "${p}"`,
+  },
+  {
+    id: "software-engineering/feature-implementation",
+    area: "software-engineering",
+    keywords: ["feature", "implement", "add", "build", "create", "develop", "support", "endpoint", "ui", "tui"],
+    skills: ["modern-web-guidance", "kxm"],
+    defaultCommand: (p) => `kxm run software-engineering/feature-implementation "${p}"`,
+  },
+  {
+    id: "software-engineering/refactoring",
+    area: "software-engineering",
+    keywords: ["refactor", "cleanup", "reorganize", "modularize", "deduplicate", "split", "simplify", "deprecate"],
+    skills: ["kxm"],
+    defaultCommand: (p) => `kxm run software-engineering/refactoring "${p}"`,
+  },
+  {
+    id: "security-reliability/vulnerability-remediation",
+    area: "security-reliability",
+    keywords: ["cve", "vulnerability", "security", "exploit", "sanitize", "leak", "secret", "injection", "redact", "auth"],
+    skills: ["kxm"],
+    defaultCommand: (p) => `kxm run security-reliability/vulnerability-remediation "${p}"`,
+  },
+  {
+    id: "security-reliability/reliability-hardening",
+    area: "security-reliability",
+    keywords: ["idempotency", "retry", "circuit-breaker", "cas", "lock", "concurrency", "deadlock", "race", "crash-recovery"],
+    skills: ["kxm"],
+    defaultCommand: (p) => `kxm run security-reliability/reliability-hardening "${p}"`,
+  },
+  {
+    id: "data-analytics/pipeline-migration",
+    area: "data-analytics",
+    keywords: ["database", "sqlite", "migration", "pipeline", "schema", "transform", "table", "wal", "foreign", "cascading"],
+    skills: ["kxm"],
+    defaultCommand: (p) => `kxm run data-analytics/pipeline-migration "${p}"`,
+  },
+  {
+    id: "research-strategy/architecture-spike",
+    area: "research-strategy",
+    keywords: ["spike", "investigate", "prototype", "research", "feasibility", "benchmark", "explore", "evaluate"],
+    skills: ["kxm-session"],
+    defaultCommand: (p) => `kxm run research-strategy/architecture-spike "${p}"`,
+  },
+];
+
+export function suggestWorkflowAndRoles(
+  prompt: string,
+  options: {
+    availableHarnesses?: Array<{ harness: string; auth?: string | undefined }> | 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[] = [];
+
+  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;
+      bestPattern = pattern;
+      matchedReasons.length = 0;
+      matchedReasons.push(`Matched keywords: ${matchedWords.join(", ")}`);
+    }
+  }
+
+  if (bestScore <= 0) {
+    // Default fallback to feature-implementation
+    bestPattern = WORKFLOW_PATTERNS[1]!;
+    matchedReasons.push("Default fallback: general feature implementation workflow");
+  }
+
+  // Determine active harnesses
+  const activeHarnesses = new Set(
+    (options.availableHarnesses ?? [])
+      .filter((h) => h.auth === "active" || h.auth === "ready" || h.auth === "configured")
+      .map((h) => h.harness.toLowerCase()),
+  );
+
+  // If none specified or active, assume standard default rotation
+  const hasClaude = activeHarnesses.size === 0 || activeHarnesses.has("claude");
+  const hasGrok = activeHarnesses.size === 0 || activeHarnesses.has("grok");
+  const hasCodex = activeHarnesses.size === 0 || activeHarnesses.has("codex");
+
+  // Planner
+  const planner: RoleSpec = hasClaude
+    ? { harness: "claude", model: "fable", role: "planner" }
+    : { harness: "codex", model: "gpt-5.6-sol", role: "planner" };
+
+  // Writer (Starting rotation: Grok 4.6 headless)
+  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" });
+
+  // Critics (Vendor independent: Fable Arch + Codex CLI)
+  const critics: RoleSpec[] = [
+    { harness: "claude", model: "fable", role: "reviewer-arch" },
+    { harness: "codex", model: "gpt-5.6-sol", role: "reviewer-cli" },
+  ];
+
+  return {
+    workflowId: bestPattern.id,
+    area: bestPattern.area,
+    confidence: bestScore > 0 ? Math.min(1, 0.5 + bestScore * 0.15) : 0.5,
+    reasons: matchedReasons,
+    suggestedSkills: bestPattern.skills,
+    roles: {
+      planner,
+      writer,
+      critics,
+      verifier: { kind: "witness", command: "npm run verify" },
+    },
+    suggestedCommand: bestPattern.defaultCommand(prompt.replace(/"/g, '\\"')),
+  };
+}

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

@@ -0,0 +1,244 @@
+import { randomUUID } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { parse, stringify } from "yaml";
+
+export const GOAL_SCHEMA = "kxm.goal.v1" as const;
+export const TASK_SCHEMA = "kxm.task.v1" as const;
+
+export type GoalStatus = "active" | "achieved" | "abandoned";
+export type TaskStatus = "todo" | "in_progress" | "blocked" | "in_review" | "done";
+export type TrackerType = "github" | "jira" | "gitlab" | "none";
+
+export interface GoalRecord {
+  schema: typeof GOAL_SCHEMA;
+  id: string;
+  title: string;
+  area: string;
+  status: GoalStatus;
+  successMetrics: string[];
+  targetDate?: string;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface TaskAcceptanceCriterion {
+  id?: string;
+  description: string;
+  required: boolean;
+}
+
+export interface TaskTrackerSync {
+  tracker: TrackerType;
+  issueKey: string;
+  syncStatus: "synced" | "pending" | "failed";
+  lastSyncedAt?: string;
+}
+
+export interface TaskRecord {
+  schema: typeof TASK_SCHEMA;
+  id: string;
+  goalId?: string;
+  title: string;
+  objective: string;
+  acceptanceCriteria: TaskAcceptanceCriterion[];
+  status: TaskStatus;
+  assignedWorkflow?: string;
+  workflowRunId?: string;
+  trackerSync?: TaskTrackerSync;
+  createdAt: string;
+  updatedAt: string;
+}
+
+function goalsDirectory(repoRoot: string): string {
+  return resolve(repoRoot, ".kxm", "goals");
+}
+
+function tasksDirectory(repoRoot: string): string {
+  return resolve(repoRoot, ".kxm", "tasks");
+}
+
+export function createGoal(
+  repoRoot: string,
+  input: {
+    title: string;
+    area?: string | undefined;
+    successMetrics?: string[] | undefined;
+    targetDate?: string | undefined;
+  },
+): GoalRecord {
+  const dir = goalsDirectory(repoRoot);
+  mkdirSync(dir, { recursive: true });
+
+  const id = `goal_${randomUUID().replaceAll("-", "").slice(0, 12)}`;
+  const now = new Date().toISOString();
+  const record: GoalRecord = {
+    schema: GOAL_SCHEMA,
+    id,
+    title: input.title,
+    area: input.area ?? "software-engineering",
+    status: "active",
+    successMetrics: input.successMetrics ?? [],
+    ...(input.targetDate ? { targetDate: input.targetDate } : {}),
+    createdAt: now,
+    updatedAt: now,
+  };
+
+  const filePath = join(dir, `${id}.yaml`);
+  writeFileSync(filePath, stringify(record).trim() + "\n", "utf8");
+  return record;
+}
+
+export function listGoals(repoRoot: string): GoalRecord[] {
+  const dir = goalsDirectory(repoRoot);
+  if (!existsSync(dir)) return [];
+
+  const goals: GoalRecord[] = [];
+  const entries = readdirSync(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    if (entry.isFile() && (entry.name.endsWith(".yaml") || entry.name.endsWith(".yml"))) {
+      try {
+        const text = readFileSync(join(dir, entry.name), "utf8");
+        const doc = parse(text) as GoalRecord;
+        if (doc && doc.schema === GOAL_SCHEMA) goals.push(doc);
+      } catch {
+        // skip invalid
+      }
+    }
+  }
+
+  return goals.sort((a, b) => a.createdAt.localeCompare(b.createdAt));
+}
+
+export function createTask(
+  repoRoot: string,
+  input: {
+    goalId?: string | undefined;
+    title: string;
+    objective: string;
+    acceptanceCriteria?: TaskAcceptanceCriterion[] | undefined;
+    assignedWorkflow?: string | undefined;
+    trackerSync?: {
+      tracker: TrackerType;
+      issueKey: string;
+    } | undefined;
+  },
+): TaskRecord {
+  const dir = tasksDirectory(repoRoot);
+  mkdirSync(dir, { recursive: true });
+
+  const id = `task_${randomUUID().replaceAll("-", "").slice(0, 12)}`;
+  const now = new Date().toISOString();
+  const record: TaskRecord = {
+    schema: TASK_SCHEMA,
+    id,
+    ...(input.goalId ? { goalId: input.goalId } : {}),
+    title: input.title,
+    objective: input.objective,
+    acceptanceCriteria: input.acceptanceCriteria ?? [],
+    status: "todo",
+    ...(input.assignedWorkflow ? { assignedWorkflow: input.assignedWorkflow } : {}),
+    ...(input.trackerSync
+      ? {
+        trackerSync: {
+          tracker: input.trackerSync.tracker,
+          issueKey: input.trackerSync.issueKey,
+          syncStatus: "pending",
+        },
+      }
+      : {}),
+    createdAt: now,
+    updatedAt: now,
+  };
+
+  const filePath = join(dir, `${id}.yaml`);
+  writeFileSync(filePath, stringify(record).trim() + "\n", "utf8");
+  return record;
+}
+
+export function listTasks(
+  repoRoot: string,
+  options: { goalId?: string | undefined; status?: TaskStatus | undefined } = {},
+): TaskRecord[] {
+  const dir = tasksDirectory(repoRoot);
+  if (!existsSync(dir)) return [];
+
+  const tasks: TaskRecord[] = [];
+  const entries = readdirSync(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    if (entry.isFile() && (entry.name.endsWith(".yaml") || entry.name.endsWith(".yml"))) {
+      try {
+        const text = readFileSync(join(dir, entry.name), "utf8");
+        const doc = parse(text) as TaskRecord;
+        if (doc && doc.schema === TASK_SCHEMA) {
+          if (options.goalId && doc.goalId !== options.goalId) continue;
+          if (options.status && doc.status !== options.status) continue;
+          tasks.push(doc);
+        }
+      } catch {
+        // skip invalid
+      }
+    }
+  }
+
+  return tasks.sort((a, b) => a.createdAt.localeCompare(b.createdAt));
+}
+
+export function getTask(repoRoot: string, taskId: string): TaskRecord | undefined {
+  const dir = tasksDirectory(repoRoot);
+  const filePath = join(dir, `${taskId}.yaml`);
+  if (!existsSync(filePath)) return undefined;
+  try {
+    const text = readFileSync(filePath, "utf8");
+    const doc = parse(text) as TaskRecord;
+    return doc && doc.schema === TASK_SCHEMA ? doc : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+export function updateTaskStatus(
+  repoRoot: string,
+  taskId: string,
+  status: TaskStatus,
+  options: { workflowRunId?: string } = {},
+): TaskRecord {
+  const task = getTask(repoRoot, taskId);
+  if (!task) {
+    throw new Error(`Task ${taskId} not found`);
+  }
+
+  task.status = status;
+  if (options.workflowRunId) task.workflowRunId = options.workflowRunId;
+  task.updatedAt = new Date().toISOString();
+
+  const filePath = join(tasksDirectory(repoRoot), `${taskId}.yaml`);
+  writeFileSync(filePath, stringify(task).trim() + "\n", "utf8");
+  return task;
+}
+
+export function syncTaskWithTracker(
+  repoRoot: string,
+  taskId: string,
+  options: {
+    mockRemoteState?: string;
+    commentReceipt?: string;
+  } = {},
+): TaskRecord {
+  const task = getTask(repoRoot, taskId);
+  if (!task) {
+    throw new Error(`Task ${taskId} not found`);
+  }
+  if (!task.trackerSync) {
+    throw new Error(`Task ${taskId} does not have an associated issue board tracker`);
+  }
+
+  const now = new Date().toISOString();
+  task.trackerSync.syncStatus = "synced";
+  task.trackerSync.lastSyncedAt = now;
+  task.updatedAt = now;
+
+  const filePath = join(tasksDirectory(repoRoot), `${taskId}.yaml`);
+  writeFileSync(filePath, stringify(task).trim() + "\n", "utf8");
+  return task;
+}