karajan-code 2.6.0 → 2.6.1

package/README.md

@@ -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):

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "karajan-code",
-  "version": "2.6.0",
+  "version": "2.6.1",
   "description": "Local multi-agent coding orchestrator with TDD, SonarQube, and code review pipeline",
   "type": "module",
   "license": "AGPL-3.0",

package/src/brain/solomon-consult.js

@@ -8,6 +8,14 @@
  *
  * This is intentionally conservative. A future iteration can make Solomon a
  * binding arbiter for routing (like it is for pipeline-control decisions).
+ *
+ * Architectural invariant: this module is the ONLY sanctioned path from
+ * Brain to Solomon for routing concerns. Stages / rules / agents must not
+ * bypass Brain to reach Solomon directly — see the note on `invokeSolomon`
+ * in `src/orchestrator/solomon-escalation.js` and docs/ARCHITECTURE.md.
+ *
+ * @typedef {import("../types/solomon.js").Conflict} Conflict
+ * @typedef {import("../types/solomon.js").SolomonResult} SolomonResult
  */
 
 /**
@@ -17,7 +25,7 @@
  * @param {import("./decisor.js").Decision} args.decision
  * @param {Object} args.triage
  * @param {string} args.task
- * @returns {Object} conflict
+ * @returns {Conflict} conflict
  */
 export function buildRoutingConflict({ decision, triage, task }) {
   return {

package/src/orchestrator/solomon-escalation.js

@@ -3,6 +3,23 @@ import { addCheckpoint, pauseSession, saveSession } from "../session-store.js";
 import { emitProgress, makeEvent } from "../utils/events.js";
 import { msg, getLang } from "../utils/messages.js";
 
+/**
+ * @typedef {import("../types/solomon.js").Conflict} Conflict
+ * @typedef {import("../types/solomon.js").SolomonResult} SolomonResult
+ */
+
+/**
+ * Architectural invariant (DO NOT BREAK):
+ * `invokeSolomon` MUST NOT be called directly from stages, rules or agent
+ * code. The only callers should be:
+ *   - Karajan Brain (via `src/brain/solomon-consult.js`)
+ *   - The orchestrator's escalation path (`src/orchestrator/flow-runner.js`)
+ *     on behalf of Brain.
+ * The v2.3.0 audit fixed 21 violations of this rule. Keeping Solomon behind
+ * Brain is what the "Brain-as-gateway, Solomon-as-judge" architecture
+ * depends on — see docs/ARCHITECTURE.md §Brain/Solomon.
+ */
+
 /**
  * Build a human-readable escalation message from raw Solomon conflict data.
  * Replaces the raw JSON dump with structured, plain-text output.
@@ -81,6 +98,23 @@ function extractSolomonHistory(session) {
     }));
 }
 
+/**
+ * Consult Solomon (or fall back to human escalation) for a given conflict.
+ * See the Conflict typedef for the shape of the `conflict` argument and
+ * the invariant above for who is allowed to call this.
+ *
+ * @param {Object}    params
+ * @param {Object}    params.config
+ * @param {Object}    params.logger
+ * @param {Object}    [params.emitter]
+ * @param {Object}    [params.eventBase]
+ * @param {string}    params.stage
+ * @param {Conflict}  params.conflict
+ * @param {Function}  [params.askQuestion]
+ * @param {Object}    [params.session]
+ * @param {number}    [params.iteration]
+ * @returns {Promise<SolomonResult>}
+ */
 export async function invokeSolomon({ config, logger, emitter, eventBase, stage, conflict, askQuestion, session, iteration }) {
   const solomonEnabled = Boolean(config.pipeline?.solomon?.enabled);
 

package/src/roles/agent-role.js

@@ -3,6 +3,15 @@
  * Handles the common execute() flow: resolve provider → create agent → call LLM → parse output.
  * Subclasses override hooks (buildPrompt, parseOutput, buildSuccessResult, buildSummary)
  * instead of reimplementing the full execute() boilerplate.
+ *
+ * Conceptual mapping: `AgentRole` is a Karajan Role that delegates to an AI CLI
+ * subprocess (not to a provider HTTP API). From the outside it plays the same
+ * role as a Genkit Flow — named unit of work with a prompt and a parsed output —
+ * but every invocation spawns a fresh `execa` subprocess (claude, codex, gemini,
+ * aider, opencode) and the state lives in Karajan's session store, not in a
+ * provider-side conversation. See `docs/COMPARISON.md`.
+ *
+ * @alias Flow — similar to Genkit Flow but executed over subprocess CLIs, not API calls.
  */
 import { BaseRole } from "./base-role.js";
 import { createAgent as defaultCreateAgent } from "../agents/index.js";

package/src/roles/base-role.js

@@ -49,6 +49,23 @@ async function loadFirstExisting(paths) {
   return null;
 }
 
+/**
+ * Base class for every pipeline role (coder, reviewer, planner, refactorer,
+ * researcher, architect, triage, discover, tester, security, impeccable,
+ * hu-reviewer, audit, solomon, commiter, karajan-brain, domain-curator).
+ *
+ * Conceptual mapping for developers coming from other ecosystems:
+ * `BaseRole` (and every subclass) is Karajan's equivalent of a **Flow** in the
+ * Genkit sense — a named, composable unit of work with a prompt, an invocation
+ * and a parsed output. The important difference: a Karajan Role executes over
+ * a **subprocess CLI** (`claude`, `codex`, `gemini`, `aider`, `opencode`), not
+ * by calling an HTTP provider API. No PTY, no long-lived session — each run
+ * is a fresh subprocess with state on disk under `~/.karajan/sessions/`.
+ *
+ * See `docs/COMPARISON.md` for the full positioning.
+ *
+ * @alias Flow — similar to Genkit Flow but executed over subprocess CLIs, not API calls.
+ */
 export class BaseRole {
   constructor({ name, config, logger, emitter = null }) {
     if (!name) throw new Error("Role name is required");

package/src/types/index.js

@@ -29,6 +29,10 @@
  *
  * @typedef {import("./policy.js").ResolvedPolicies} ResolvedPolicies
  * @typedef {import("./policy.js").QualityGateResult} QualityGateResult
+ *
+ * @typedef {import("./solomon.js").Conflict} SolomonConflict
+ * @typedef {import("./solomon.js").ConflictHistoryEntry} SolomonConflictHistoryEntry
+ * @typedef {import("./solomon.js").SolomonResult} SolomonResult
  */
 
 export {};

package/src/types/solomon.js

@@ -0,0 +1,87 @@
+/**
+ * Typedefs for Solomon — the AI judge consulted by Brain on genuine dilemmas.
+ *
+ * Architectural invariant (enforced by convention, see docs/ARCHITECTURE.md):
+ *   Solomon is **NEVER** invoked directly from stages, rules or roles.
+ *   The only legitimate entry points are:
+ *     - `src/brain/solomon-consult.js#consultSolomonForRouting`
+ *     - `src/orchestrator/solomon-escalation.js#invokeSolomon`
+ *   Both are called by Brain (or by the orchestrator on Brain's behalf).
+ *   The v2.3.0 audit fixed 21 violations where stages bypassed Brain and
+ *   called Solomon directly. Don't reintroduce that pattern.
+ *
+ * This module is runtime-empty — it only carries JSDoc annotations.
+ *
+ * @module types/solomon
+ */
+
+/**
+ * A single turn of feedback attributed to a pipeline agent. Used to build
+ * `Conflict.history` when Brain escalates a decision to Solomon.
+ *
+ * @typedef {Object} ConflictHistoryEntry
+ * @property {string} agent     - slug of the agent that produced the feedback
+ *                                (e.g. "reviewer", "sonar", "tester",
+ *                                "coder_rate_limit").
+ * @property {string} feedback  - raw textual feedback to be weighted by Solomon.
+ */
+
+/**
+ * The bundle of context Brain hands to Solomon when it cannot decide on its
+ * own. Solomon reads only this object + the stage + task; it never sees
+ * session internals beyond what is packed here.
+ *
+ * Historical shape: this matches the argument already used by
+ * `invokeSolomon({ ..., conflict })` — the typedef formalizes the contract
+ * so future drift is caught by `npm run typecheck`.
+ *
+ * @typedef {Object} Conflict
+ * @property {string} stage
+ *           Pipeline stage that triggered escalation (e.g. "reviewer",
+ *           "sonar", "tester", "init_error", "coder_rate_limit").
+ * @property {string} task
+ *           Original user task (denormalized so Solomon sees what the user
+ *           actually asked for, not just the stage context).
+ * @property {number} iterationCount
+ *           Current iteration number inside the escalating sub-loop.
+ * @property {number} maxIterations
+ *           Configured cap for that sub-loop (reviewer retries, tester
+ *           retries, full pipeline iterations, etc.). Hitting this cap is
+ *           the canonical trigger for Solomon consultation.
+ * @property {string|null} [cooldownUntil]
+ *           ISO timestamp for rate-limit / standby escalations. Null when
+ *           the conflict is not a rate-limit.
+ * @property {number|null} [cooldownMs]
+ *           Remaining cooldown in milliseconds. Null outside rate-limit
+ *           escalations.
+ * @property {ConflictHistoryEntry[]} history
+ *           Ordered list of agent feedback Solomon should weigh. Most
+ *           recent last. Must be non-empty — Solomon should always see at
+ *           least one piece of evidence.
+ */
+
+/**
+ * Solomon's ruling on a `Conflict`. Returned by `invokeSolomon()` and
+ * consumed by the orchestrator to decide what happens next.
+ *
+ * @typedef {Object} SolomonResult
+ * @property {"continue"|"pause"|"subtask"} action
+ *           - `continue`: retry the sub-loop with optional `humanGuidance`
+ *             appended to the next feedback round.
+ *           - `pause`: stop the pipeline and surface a question to the
+ *             human operator (`SolomonResult.question`).
+ *           - `subtask`: bifurcate into a named sub-task defined in
+ *             `SolomonResult.subtask`.
+ * @property {string} [rationale]         - human-readable reasoning for the
+ *                                          chosen action. Logged to the
+ *                                          decisions journal.
+ * @property {string} [humanGuidance]     - text to merge into the next
+ *                                          coder/reviewer prompt when
+ *                                          action === "continue".
+ * @property {string} [question]          - prompt shown to the human when
+ *                                          action === "pause".
+ * @property {Object} [subtask]           - sub-task descriptor when
+ *                                          action === "subtask".
+ */
+
+export {};