karajan-code 2.5.0 → 2.6.1

package/README.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <img src="docs/karajan-code-logo.svg" alt="Karajan Code" width="180">
+  <img src="docs/karajan-orbit.svg" alt="Karajan Code" width="220">
 </p>
 
 <h1 align="center">Karajan Code</h1>
@@ -23,7 +23,7 @@
 
 ---
 
-> **v2.4.0 released** — Executable acceptance tests for HUs: each HU runs shell commands after every coder iteration. All pass → approved. Any fail → Brain diagnoses with exact error output. First version where the full demo completes end-to-end: 6 HUs, 280 tests, 97% coverage, 0 vulnerabilities. Also includes security audit fixes and auto-HU decomposition (v2.1+). See [CHANGELOG.md](./CHANGELOG.md) for full history and [MIGRATION-v2.md](./MIGRATION-v2.md) for v1→v2 breaking changes.
+> **v2.6.0 released** — Modular orchestrator + infrastructure DI + Valibot config validation. `src/orchestrator.js` split into a thin barrel + `flow-runner.js` + new `StageExecutor` contract under `src/orchestrator/stages/`. `FileSystemService` and `CommandRunner` adapters let tests swap in mocks instead of spawning real subprocesses. Config now validated with Valibot (catches `review_mode` typos, `max_iterations: 0`, bad ports at load time). HU Board auto-start gate simplified to `hu_board.auto_start` alone with a prominent cyan URL banner at pipeline init. Plus: budget comparison (With-KJ vs Without-KJ), rich session journal (decisions / iterations / summary / tree), Brain decisor with intent-driven routing, and Karajan-wide JSDoc typedefs. See [CHANGELOG.md](./CHANGELOG.md) for full history and [MIGRATION-v2.md](./MIGRATION-v2.md) for v1→v2 breaking changes.
 
 You describe what you want to build. Karajan orchestrates multiple AI agents to plan it, implement it, test it, review it with SonarQube, and iterate. No babysitting required.
 
@@ -53,6 +53,25 @@ Use Karajan when you want:
 
 If Claude Code is a smart pair programmer, Karajan is the CI/CD pipeline for AI-assisted development. They work great together: Karajan is designed to be used as an MCP server inside Claude Code.
 
+## How Karajan differs from AI frameworks
+
+While Genkit, Mastra, LangChain and Vercel AI SDK call `/v1/messages`, Karajan orchestrates the AI CLIs your developers already use in their terminals.
+
+| Axis | Karajan | Genkit / Mastra / LangChain / Vercel AI SDK |
+|------|---------|---------------------------------------------|
+| Calls provider HTTP API (`/v1/messages`, etc.) | ❌ Delegates to CLIs | ✅ |
+| Orchestrates existing AI CLIs (claude, codex, gemini, aider, opencode) as subprocesses | ✅ | ❌ |
+| Depends on cloud infrastructure | ❌ Fully local | ⚠️ Varies |
+| Vanilla JS (no TypeScript required) | ✅ | ⚠️ TS-first |
+| Token billing | **Uses your existing CLI subscriptions** | Pay per API call |
+
+Two technical facts worth keeping straight:
+
+1. **Subprocess, not PTY.** Karajan spawns each CLI via `execa` / `child_process` with plain `stdin` / `stdout` / `stderr` — see `src/infrastructure/command-runner.js` and `src/agents/*.js`. There is no PTY emulation.
+2. **Fresh subprocess per invocation + state on disk.** Every coder run is a new process; the state lives in `~/.karajan/sessions/` (see `src/session-store.js`) and the per-session journal under `.reviews/<session-id>/`. This is what makes pipelines **reproducible** and **resumable** with `kj resume`.
+
+Full write-up with mental mapping for Genkit / Mastra / LangChain / Vercel AI SDK developers: **[docs/COMPARISON.md](./docs/COMPARISON.md)**.
+
 ## Install
 
 **npm** (recommended):
@@ -107,7 +126,23 @@ kj run "Create a utility function that validates Spanish DNI numbers, with tests
 kj code "Add input validation to the signup form"     # Coder only
 kj review "Check the authentication changes"           # Review current diff
 kj audit "Full health analysis of this codebase"       # Read-only audit
-kj plan "Refactor the database layer"                  # Plan without coding
+
+# Planning workflow (v2.5+)
+kj plan "Refactor the database layer"                  # Generate plan + HUs
+kj plan list                                           # List plans for this project
+kj plan show <planId>                                  # Show plan details + HU table
+kj plan validate <planId>                              # Check structure and deps
+kj plan ready <planId>                                 # Certify all HUs, mark ready
+kj plan add-hu <planId> --title "..." --type feat      # Add HU to plan
+kj plan remove-hu <planId> <huId>                      # Remove HU from plan
+kj plan delete <planId>                                # Delete plan from disk
+kj run --plan <planId> "task"                          # Execute an approved plan
+
+# HU Board dashboard (v1.34.0+)
+kj board start                                         # Start web dashboard (port 4000)
+kj board open                                          # Start + open in browser
+kj board status                                        # Check if running
+kj board stop                                          # Stop the board
 ```
 
 ### 2. MCP: inside your AI agent
@@ -218,7 +253,7 @@ After `npm install -g karajan-code`, the MCP server auto-registers in Claude and
 # command = "karajan-mcp"
 ```
 
-**23 tools** available: `kj_run`, `kj_code`, `kj_review`, `kj_plan`, `kj_audit`, `kj_scan`, `kj_doctor`, `kj_config`, `kj_report`, `kj_resume`, `kj_roles`, `kj_agents`, `kj_preflight`, `kj_status`, `kj_init`, `kj_discover`, `kj_triage`, `kj_researcher`, `kj_architect`, `kj_impeccable`, `kj_hu`, `kj_skills`, `kj_suggest`.
+**24 tools** available: `kj_run`, `kj_code`, `kj_review`, `kj_plan`, `kj_board`, `kj_audit`, `kj_scan`, `kj_doctor`, `kj_config`, `kj_report`, `kj_resume`, `kj_roles`, `kj_agents`, `kj_preflight`, `kj_status`, `kj_init`, `kj_discover`, `kj_triage`, `kj_researcher`, `kj_architect`, `kj_impeccable`, `kj_hu`, `kj_skills`, `kj_suggest`.
 
 Use `kj-tail` in a separate terminal to see what the pipeline is doing in real time (see [Three ways to use Karajan](#three-ways-to-use-karajan)).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "karajan-code",
-  "version": "2.5.0",
+  "version": "2.6.1",
   "description": "Local multi-agent coding orchestrator with TDD, SonarQube, and code review pipeline",
   "type": "module",
   "license": "AGPL-3.0",
@@ -47,6 +47,7 @@
     "test": "vitest run",
     "test:watch": "vitest",
     "lint": "((command -v rg >/dev/null 2>&1 && rg --files src tests | rg '\\.js$') || find src tests -type f -name '*.js') | while IFS= read -r f; do node --check \"$f\"; done",
+    "typecheck": "npx -p typescript@5 tsc --noEmit -p tsconfig.json",
     "validate": "npm run lint && npm test",
     "mcp": "node src/mcp/server.js"
   },
@@ -54,9 +55,11 @@
     "@modelcontextprotocol/sdk": "^1.26.0",
     "commander": "^14.0.0",
     "execa": "^9.6.0",
-    "js-yaml": "^4.1.0"
+    "js-yaml": "^4.1.0",
+    "valibot": "^1.3.1"
   },
   "devDependencies": {
+    "@changesets/cli": "^2.30.0",
     "@vitest/coverage-v8": "^4.0.18",
     "vitest": "^4.0.0"
   }

package/src/agents/aider-agent.js

@@ -1,5 +1,4 @@
 import { BaseAgent } from "./base-agent.js";
-import { runCommand } from "../utils/process.js";
 import { resolveBin } from "./resolve-bin.js";
 
 export class AiderAgent extends BaseAgent {
@@ -28,7 +27,7 @@ export class AiderAgent extends BaseAgent {
   async _exec(task, model) {
     const args = ["--yes", "--message", task.prompt];
     if (model) args.push("--model", model);
-    const res = await runCommand(resolveBin("aider"), args, {
+    const res = await this.runCommand(resolveBin("aider"), args, {
       onOutput: task.onOutput,
       silenceTimeoutMs: task.silenceTimeoutMs,
       timeout: task.timeoutMs

package/src/agents/base-agent.js

@@ -1,3 +1,17 @@
+/**
+ * Base class for provider-specific agent adapters (claude, codex, gemini, ...).
+ * Every concrete agent must implement runTask() and may override reviewTask().
+ *
+ * @typedef {import("../types/config.js").KarajanConfig} KarajanConfig
+ * @typedef {import("../types/stage.js").Logger} Logger
+ * @typedef {import("../types/agent.js").AgentResult} AgentResult
+ * @typedef {import("../infrastructure/environment.js").Environment} Environment
+ * @typedef {import("../infrastructure/command-runner.js").CommandRunResult} CommandRunResult
+ * @typedef {import("../infrastructure/command-runner.js").CommandRunOptions} CommandRunOptions
+ */
+
+import { defaultEnvironment } from "../infrastructure/environment.js";
+
 const MODEL_NOT_SUPPORTED_PATTERNS = [
   /model.{0,30}is not supported/i,
   /model.{0,30}not available/i,
@@ -8,20 +22,58 @@ const MODEL_NOT_SUPPORTED_PATTERNS = [
 ];
 
 export class BaseAgent {
-  constructor(name, config, logger) {
+  /**
+   * @param {string} name                    - agent slug (claude|codex|gemini|aider|opencode)
+   * @param {KarajanConfig} config
+   * @param {Logger} logger
+   * @param {Environment} [environment]      - DI-friendly fs + runner bundle. Defaults
+   *                                           to the native filesystem and execa-based
+   *                                           command runner. Tests pass a mock env to
+   *                                           unit-test agent paths without spawning
+   *                                           real processes.
+   */
+  constructor(name, config, logger, environment = defaultEnvironment) {
     this.name = name;
     this.config = config;
     this.logger = logger;
+    this.environment = environment;
+  }
+
+  /**
+   * Run a shell command through the injected CommandRunner. Subclasses should
+   * call this instead of importing runCommand directly so tests can swap in
+   * MockCommandRunner.
+   * @param {string} command
+   * @param {string[]} [args]
+   * @param {CommandRunOptions} [options]
+   * @returns {Promise<CommandRunResult>}
+   */
+  async runCommand(command, args = [], options = {}) {
+    return this.environment.runner.run(command, args, options);
   }
 
+  /**
+   * Execute a coding/agentic task. Subclasses MUST override.
+   * @param {string|Object} _task
+   * @returns {Promise<AgentResult>}
+   */
   async runTask(_task) {
     throw new Error("runTask not implemented");
   }
 
+  /**
+   * Execute a review task. Subclasses MAY override for different behaviour.
+   * @param {string|Object} _task
+   * @returns {Promise<AgentResult>}
+   */
   async reviewTask(_task) {
     throw new Error("reviewTask not implemented");
   }
 
+  /**
+   * @param {string} role
+   * @returns {string|null}
+   */
   getRoleModel(role) {
     const roleModel = this.config?.roles?.[role]?.model;
     if (roleModel) return roleModel;
@@ -29,11 +81,21 @@ export class BaseAgent {
     return this.config?.coder_options?.model || null;
   }
 
+  /**
+   * @param {string} role
+   * @returns {boolean}
+   */
   isAutoApproveEnabled(role) {
     if (role === "reviewer") return false;
     return Boolean(this.config?.coder_options?.auto_approve);
   }
 
+  /**
+   * Heuristic: does the agent's error look like "model not supported"?
+   * Used by the retry/fallback path.
+   * @param {Partial<AgentResult>} result
+   * @returns {boolean}
+   */
   isModelNotSupportedError(result) {
     const text = [result?.error, result?.output, result?.stderr, result?.stdout]
       .filter(Boolean).join("\n");

package/src/agents/claude-agent.js

@@ -1,5 +1,4 @@
 import { BaseAgent } from "./base-agent.js";
-import { runCommand } from "../utils/process.js";
 import { resolveBin } from "./resolve-bin.js";
 
 /**
@@ -244,7 +243,7 @@ export class ClaudeAgent extends BaseAgent {
     if (task.onOutput) {
       args.push("--output-format", "stream-json", "--verbose");
       const streamFilter = createStreamJsonFilter(task.onOutput);
-      const res = await runCommand(resolveBin("claude"), args, cleanExecaOpts({
+      const res = await this.runCommand(resolveBin("claude"), args, cleanExecaOpts({
         onOutput: streamFilter,
         silenceTimeoutMs: task.silenceTimeoutMs,
         timeout: task.timeoutMs
@@ -257,7 +256,7 @@ export class ClaudeAgent extends BaseAgent {
 
     // Without streaming, use json output to get structured response via stderr
     args.push("--output-format", "json");
-    const res = await runCommand(resolveBin("claude"), args, cleanExecaOpts());
+    const res = await this.runCommand(resolveBin("claude"), args, cleanExecaOpts());
     const raw = pickOutput(res);
     const output = extractTextFromStreamJson(raw);
     const usage = extractUsageFromStreamJson(raw);
@@ -267,7 +266,7 @@ export class ClaudeAgent extends BaseAgent {
   async _reviewTaskExec(task, model) {
     const args = ["-p", task.prompt, "--allowedTools", ...ALLOWED_TOOLS, "--output-format", "stream-json", "--verbose"];
     if (model) args.push("--model", model);
-    const res = await runCommand(resolveBin("claude"), args, cleanExecaOpts({
+    const res = await this.runCommand(resolveBin("claude"), args, cleanExecaOpts({
       onOutput: task.onOutput,
       silenceTimeoutMs: task.silenceTimeoutMs,
       timeout: task.timeoutMs

package/src/agents/codex-agent.js

@@ -1,5 +1,4 @@
 import { BaseAgent } from "./base-agent.js";
-import { runCommand } from "../utils/process.js";
 import { resolveBin } from "./resolve-bin.js";
 
 /**
@@ -45,7 +44,7 @@ export class CodexAgent extends BaseAgent {
     if (model) args.push("--model", model);
     if (role !== "reviewer" && this.isAutoApproveEnabled(role)) args.push("--full-auto");
     args.push("-");
-    const res = await runCommand(resolveBin("codex"), args, {
+    const res = await this.runCommand(resolveBin("codex"), args, {
       onOutput: task.onOutput,
       silenceTimeoutMs: task.silenceTimeoutMs,
       timeout: task.timeoutMs,

package/src/agents/gemini-agent.js

@@ -1,5 +1,4 @@
 import { BaseAgent } from "./base-agent.js";
-import { runCommand } from "../utils/process.js";
 import { resolveBin } from "./resolve-bin.js";
 
 export class GeminiAgent extends BaseAgent {
@@ -29,7 +28,7 @@ export class GeminiAgent extends BaseAgent {
     const args = ["-p", task.prompt];
     if (mode === "review") args.push("--output-format", "json");
     if (model) args.push("--model", model);
-    const res = await runCommand(resolveBin("gemini"), args, {
+    const res = await this.runCommand(resolveBin("gemini"), args, {
       onOutput: task.onOutput,
       silenceTimeoutMs: task.silenceTimeoutMs,
       timeout: task.timeoutMs

package/src/agents/index.js

@@ -26,12 +26,21 @@ export function getAgentMeta(name) {
   return entry ? { ...entry.meta } : null;
 }
 
-export function createAgent(agentName, config, logger) {
+/**
+ * @param {string} agentName
+ * @param {import("../types/config.js").KarajanConfig} config
+ * @param {import("../types/stage.js").Logger} logger
+ * @param {import("../infrastructure/environment.js").Environment} [environment]
+ *   Optional DI environment. Defaults to native fs + execa. Tests pass a mock
+ *   environment built via `buildMockEnvironment()` to exercise agent paths
+ *   without spawning real processes.
+ */
+export function createAgent(agentName, config, logger, environment) {
   const entry = agentRegistry.get(agentName);
   if (!entry) {
     throw new Error(`Unsupported agent: ${agentName}`);
   }
-  return new entry.AgentClass(agentName, config, logger);
+  return new entry.AgentClass(agentName, config, logger, environment);
 }
 
 // Auto-register built-in agents with CLI metadata

package/src/agents/opencode-agent.js

@@ -1,5 +1,4 @@
 import { BaseAgent } from "./base-agent.js";
-import { runCommand } from "../utils/process.js";
 import { resolveBin } from "./resolve-bin.js";
 
 export class OpenCodeAgent extends BaseAgent {
@@ -30,7 +29,7 @@ export class OpenCodeAgent extends BaseAgent {
     if (jsonFormat) args.push("--format", "json");
     if (model) args.push("--model", model);
     args.push(task.prompt);
-    const res = await runCommand(resolveBin("opencode"), args, {
+    const res = await this.runCommand(resolveBin("opencode"), args, {
       onOutput: task.onOutput,
       silenceTimeoutMs: task.silenceTimeoutMs,
       timeout: task.timeoutMs

package/src/brain/decision-tracker.js

@@ -0,0 +1,123 @@
+/**
+ * Tracks every routing decision the Brain makes during a session and enforces
+ * safety limits (max decisions per session, indecision-loop detection).
+ *
+ * Decisions are appended to `session.brainDecisions`. Consumers call
+ * `recordDecision(tracker, decision, context)` after a buildDecision() call
+ * and `checkLimits(tracker)` before making another decision.
+ *
+ * The limits are soft guards, not hard failures: hitting a limit surfaces
+ * a status that the orchestrator can use to escalate to Solomon or pause
+ * the session for human input.
+ */
+
+export const DEFAULT_MAX_DECISIONS = 20;
+export const INDECISION_REPEAT_THRESHOLD = 3; // 3 identical classifications in a row
+
+/**
+ * @typedef {Object} RecordedDecision
+ * @property {number} seq
+ * @property {string} at                            - ISO timestamp
+ * @property {string} intent                        - e.g. "sw:medium" (taskType:level)
+ * @property {string[]} rolesOn
+ * @property {"low"|"medium"|"high"} confidence
+ * @property {string} rationale
+ * @property {string[]} appliedOverrides
+ */
+
+/**
+ * @typedef {Object} TrackerStatus
+ * @property {"ok"|"max-reached"|"indecision"} status
+ * @property {number} decisionCount
+ * @property {string} [detail]
+ */
+
+/**
+ * Initialize a tracker bound to a session. If the session already has a
+ * `brainDecisions` array (e.g. from a resumed session), keep it.
+ *
+ * @param {Object} session
+ * @param {{ max?: number }} [options]
+ * @returns {{ session: Object, max: number }}
+ */
+export function createTracker(session, { max = DEFAULT_MAX_DECISIONS } = {}) {
+  if (!Array.isArray(session.brainDecisions)) {
+    session.brainDecisions = [];
+  }
+  return { session, max };
+}
+
+/**
+ * Append a decision to the tracker.
+ *
+ * @param {{ session: Object, max: number }} tracker
+ * @param {Object} decision                         - output of buildDecision()
+ * @param {{ taskType?: string, level?: string }} intent
+ * @returns {RecordedDecision}
+ */
+export function recordDecision(tracker, decision, intent = {}) {
+  const seq = tracker.session.brainDecisions.length + 1;
+  const entry = {
+    seq,
+    at: new Date().toISOString(),
+    intent: `${intent.taskType || "?"}:${intent.level || "?"}`,
+    rolesOn: Array.isArray(decision.rolesOn) ? [...decision.rolesOn] : [],
+    confidence: decision.confidence || "medium",
+    rationale: decision.rationale || "",
+    appliedOverrides: Array.isArray(decision.appliedOverrides) ? [...decision.appliedOverrides] : [],
+  };
+  tracker.session.brainDecisions.push(entry);
+  return entry;
+}
+
+/**
+ * Compute status of the tracker. Called BEFORE recording a new decision so
+ * the orchestrator can decide to escalate instead of calling the Brain again.
+ *
+ * @param {{ session: Object, max: number }} tracker
+ * @returns {TrackerStatus}
+ */
+export function checkLimits(tracker) {
+  const decisions = tracker.session.brainDecisions || [];
+  const decisionCount = decisions.length;
+
+  if (decisionCount >= tracker.max) {
+    return {
+      status: "max-reached",
+      decisionCount,
+      detail: `Brain made ${decisionCount} decisions (limit ${tracker.max}). Escalate to Solomon or human.`,
+    };
+  }
+
+  // Indecision loop: last N decisions share the exact same intent.
+  const window = decisions.slice(-INDECISION_REPEAT_THRESHOLD);
+  if (window.length >= INDECISION_REPEAT_THRESHOLD && window.every((d) => d.intent === window[0].intent)) {
+    return {
+      status: "indecision",
+      decisionCount,
+      detail: `Brain classified the same intent (${window[0].intent}) ${INDECISION_REPEAT_THRESHOLD} times in a row — loop detected.`,
+    };
+  }
+
+  return { status: "ok", decisionCount };
+}
+
+/**
+ * Build a short summary of all decisions made in the session. Useful for the
+ * final report and for debugging.
+ *
+ * @param {{ session: Object }} tracker
+ * @returns {{ total: number, byIntent: Record<string,number>, lastRationale: string }}
+ */
+export function summarize(tracker) {
+  const decisions = tracker.session.brainDecisions || [];
+  const byIntent = {};
+  for (const d of decisions) {
+    byIntent[d.intent] = (byIntent[d.intent] || 0) + 1;
+  }
+  return {
+    total: decisions.length,
+    byIntent,
+    lastRationale: decisions.at(-1)?.rationale ?? "",
+  };
+}