karajan-code 2.5.0 → 2.6.0

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.
 
@@ -107,7 +107,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 +234,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.0",
   "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 ?? "",
+  };
+}

package/src/brain/decisor.js

@@ -0,0 +1,243 @@
+/**
+ * Brain decisor — intent-driven pipeline routing.
+ *
+ * Takes the triage output + task text + config and produces a Decision that
+ * the orchestrator applies as pipelineFlags overrides. The existing stage
+ * if/else in runFlow continues to drive execution; Brain just tells it which
+ * roles are relevant for this particular task.
+ *
+ * This is an MVP that keeps the current architecture. A future iteration
+ * (Pipeline Sovereignty / KJC-PCS-0022) can promote the Decision into a
+ * true DAG with parallel stage execution.
+ */
+
+/**
+ * @typedef {Object} TriageOutput
+ * @property {"trivial"|"simple"|"medium"|"complex"} level
+ * @property {string[]} roles                       - roles triage suggests running
+ * @property {string} [taskType]                    - sw | infra | doc | add-tests | refactor | no-code | audit
+ * @property {string} [reasoning]
+ * @property {number} [confidence]                  - 0..1, often absent
+ * @property {string[]} [domainHints]
+ */
+
+/**
+ * @typedef {Object} Decision
+ * @property {string[]} rolesOn                     - roles to enable in pipelineFlags
+ * @property {string[]} rolesOff                    - roles to explicitly disable
+ * @property {"low"|"medium"|"high"} confidence
+ * @property {string} rationale                     - human-readable reasoning
+ * @property {boolean} consultSolomon               - true if the Brain is unsure
+ * @property {string} [solomonReason]               - why Solomon is needed
+ * @property {string[]} appliedOverrides            - names of manual overrides respected
+ */
+
+const VALID_ROLES = new Set([
+  "planner", "researcher", "architect", "coder", "reviewer", "refactorer",
+  "tester", "security", "impeccable", "triage", "discover", "hu_reviewer", "solomon",
+]);
+
+/**
+ * Translate triage level → base set of roles. Conservative baseline that the
+ * decisor then adjusts via taskType and domain hints.
+ */
+function baselineForLevel(level) {
+  switch (level) {
+    case "trivial": return new Set(["coder"]);
+    case "simple": return new Set(["coder", "reviewer"]);
+    case "medium": return new Set(["coder", "reviewer", "tester"]);
+    case "complex": return new Set(["researcher", "architect", "planner", "coder", "reviewer", "tester", "security"]);
+    default: return new Set(["coder", "reviewer"]);
+  }
+}
+
+/**
+ * Apply taskType adjustments on top of the baseline set (mutates in place).
+ */
+function applyTaskTypeAdjustments(roles, taskType) {
+  switch (taskType) {
+    case "doc":
+      // Documentation tasks: skip testing and security, keep reviewer for tone/clarity.
+      roles.delete("tester");
+      roles.delete("security");
+      roles.delete("refactorer");
+      break;
+    case "add-tests":
+      // Adding tests: tester is primary, security less relevant.
+      roles.add("tester");
+      roles.delete("security");
+      break;
+    case "refactor":
+      // Refactor: no new behavior; tester verifies nothing broke; reviewer checks structure.
+      roles.add("refactorer");
+      roles.add("tester");
+      break;
+    case "infra":
+      // Infra: architect helps; security critical.
+      roles.add("architect");
+      roles.add("security");
+      break;
+    case "audit":
+      // Audit: no coder; reviewer + security.
+      roles.delete("coder");
+      roles.add("reviewer");
+      roles.add("security");
+      break;
+    case "no-code":
+      // No-code tasks (e.g. running SQL queries): drop coder+reviewer+tester.
+      roles.delete("coder");
+      roles.delete("reviewer");
+      roles.delete("tester");
+      break;
+  }
+}
+
+/**
+ * Apply explicit overrides (CLI flags / config) on top of the decision.
+ * force = add; skip = remove. Tracks what was applied.
+ *
+ * @param {Set<string>} roles
+ * @param {{ forceRoles?: string[], skipRoles?: string[] }} overrides
+ * @returns {string[]} applied override names
+ */
+function applyOverrides(roles, overrides) {
+  const applied = [];
+  for (const r of overrides.forceRoles || []) {
+    if (!VALID_ROLES.has(r)) continue;
+    roles.add(r);
+    applied.push(`force:${r}`);
+  }
+  for (const r of overrides.skipRoles || []) {
+    if (!VALID_ROLES.has(r)) continue;
+    roles.delete(r);
+    applied.push(`skip:${r}`);
+  }
+  return applied;
+}
+
+/**
+ * Build a routing Decision from triage output + task text + config.
+ *
+ * @param {Object} args
+ * @param {TriageOutput} args.triage
+ * @param {string} [args.task]
+ * @param {Object} [args.config]                   - resolved config (for rolesEnabled in pipeline)
+ * @param {{ forceRoles?: string[], skipRoles?: string[] }} [args.overrides]
+ * @returns {Decision}
+ */
+export function buildDecision({ triage, task, config = {}, overrides = {} } = {}) {
+  const level = triage?.level || "simple";
+  const taskType = triage?.taskType || "sw";
+
+  // 1. Baseline by complexity.
+  const roles = baselineForLevel(level);
+
+  // 2. Include triage's own suggested roles (triage already factors domain hints).
+  if (Array.isArray(triage?.roles)) {
+    for (const r of triage.roles) {
+      if (VALID_ROLES.has(r)) roles.add(r);
+    }
+  }
+
+  // 3. Task-type-specific adjustments.
+  applyTaskTypeAdjustments(roles, taskType);
+
+  // 4. Config pipeline.X.enabled=false forces a role off (respect user config).
+  const pipeline = config?.pipeline || {};
+  for (const r of Array.from(roles)) {
+    if (pipeline[r]?.enabled === false) {
+      roles.delete(r);
+    }
+  }
+
+  // 5. Manual CLI/flag overrides (highest priority).
+  const appliedOverrides = applyOverrides(roles, overrides);
+
+  // 6. Invariants: coder is always on unless explicitly audit/no-code AND not force-added.
+  if (taskType !== "audit" && taskType !== "no-code" && !overrides.skipRoles?.includes("coder")) {
+    roles.add("coder");
+  }
+
+  // 7. Confidence + Solomon consultation.
+  const explicitConfidence = typeof triage?.confidence === "number" ? triage.confidence : null;
+  let confidence = "medium";
+  let consultSolomon = false;
+  let solomonReason;
+  if (explicitConfidence !== null) {
+    if (explicitConfidence < 0.6) {
+      confidence = "low";
+      consultSolomon = true;
+      solomonReason = `triage confidence ${explicitConfidence.toFixed(2)} < 0.6`;
+    } else if (explicitConfidence >= 0.85) {
+      confidence = "high";
+    }
+  }
+  // Ambiguous level (absent or off-vocabulary) → low confidence regardless.
+  if (!triage?.level) {
+    confidence = "low";
+    consultSolomon = true;
+    solomonReason = "triage returned no level";
+  }
+
+  const rolesOn = Array.from(roles).sort();
+  const rolesOff = Array.from(VALID_ROLES).filter((r) => !roles.has(r)).sort();
+
+  const rationale = buildRationale({ level, taskType, rolesOn, appliedOverrides, triage });
+
+  return {
+    rolesOn,
+    rolesOff,
+    confidence,
+    rationale,
+    consultSolomon,
+    solomonReason,
+    appliedOverrides,
+  };
+}
+
+function buildRationale({ level, taskType, rolesOn, appliedOverrides, triage }) {
+  const parts = [
+    `level=${level}`,
+    `taskType=${taskType}`,
+    `roles=[${rolesOn.join(",")}]`,
+  ];
+  if (triage?.domainHints?.length) {
+    parts.push(`hints=[${triage.domainHints.slice(0, 3).join(",")}]`);
+  }
+  if (appliedOverrides.length) {
+    parts.push(`overrides=[${appliedOverrides.join(",")}]`);
+  }
+  return parts.join(" | ");
+}
+
+/**
+ * Apply a Decision onto an existing pipelineFlags object. Returns a NEW
+ * object — the input is not mutated. Setting roleEnabled flags via a
+ * consistent naming pattern: `${role}Enabled`.
+ *
+ * Unknown roles are silently ignored; the orchestrator only consumes a
+ * fixed set of *Enabled flags.
+ *
+ * @param {Decision} decision
+ * @param {Object} pipelineFlags
+ * @returns {Object} new flags object
+ */
+export function applyDecisionToFlags(decision, pipelineFlags = {}) {
+  const next = { ...pipelineFlags };
+  const flagFor = (role) => {
+    if (role === "hu_reviewer") return "huReviewerEnabled";
+    return `${role}Enabled`;
+  };
+  for (const role of decision.rolesOn) {
+    next[flagFor(role)] = true;
+  }
+  for (const role of decision.rolesOff) {
+    next[flagFor(role)] = false;
+  }
+  // Coder/security/reviewer aren't always toggled via flags in the current
+  // orchestrator (coder is implicit). Don't touch fields the orchestrator
+  // doesn't know; next simply carries them.
+  return next;
+}
+
+export { VALID_ROLES };