karajan-code 1.31.1 → 1.32.1

package/README.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <img src="docs/karajan-code-logo-small.png" alt="Karajan Code" width="200">
+  <img src="docs/karajan-code-logo.svg" alt="Karajan Code" width="180">
 </p>
 
 <h1 align="center">Karajan Code</h1>
@@ -46,6 +46,7 @@ Use Karajan when you want:
 - **Zero-config operation** — auto-detects test frameworks, starts SonarQube, simplifies pipeline for trivial tasks
 - **Composable role architecture** — define agent behaviors as plain markdown files that travel with your project
 - **Local-first** — your code, your keys, your machine, no data leaves unless you say so
+- **Zero API costs** — Karajan uses AI agent CLIs (Claude Code, Codex, Gemini CLI), not APIs. You pay your existing subscription (Claude Pro, ChatGPT Plus), not per-token API fees. No surprise bills.
 
 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.
 
@@ -64,6 +65,8 @@ That's it. No Docker required (SonarQube uses Docker, but Karajan auto-manages i
 kj run "Create a utility function that validates Spanish DNI numbers, with tests"
 ```
 
+[**▶ Watch the full pipeline demo**](https://karajancode.com#demo) — HU certification, triage, architecture, TDD, SonarQube, code review, Solomon arbitration, security audit.
+
 Karajan will:
 1. Triage the task complexity and activate the right roles
 2. Write tests first (TDD)

package/package.json

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

package/src/orchestrator/post-loop-stages.js

@@ -1,6 +1,7 @@
 import { TesterRole } from "../roles/tester-role.js";
 import { SecurityRole } from "../roles/security-role.js";
 import { ImpeccableRole } from "../roles/impeccable-role.js";
+import { AuditRole } from "../roles/audit-role.js";
 import { addCheckpoint, saveSession } from "../session-store.js";
 import { emitProgress, makeEvent } from "../utils/events.js";
 import { invokeSolomon } from "./solomon-escalation.js";
@@ -290,5 +291,113 @@ export async function runImpeccableStage({ config, logger, emitter, eventBase, s
   return { action: "ok", stageResult: { ok: impeccableOutput.ok, verdict, summary: impeccableOutput.summary || "No frontend design issues found" } };
 }
 
+export async function runFinalAuditStage({ config, logger, emitter, eventBase, session, coderRole, trackBudget, iteration, task, diff }) {
+  logger.setContext({ iteration, stage: "audit" });
+  emitProgress(
+    emitter,
+    makeEvent("audit:start", { ...eventBase, stage: "audit" }, {
+      message: "Final audit — verifying code quality"
+    })
+  );
+
+  const auditStart = Date.now();
+  const { output: auditOutput, provider, attempts } = await runRoleWithFallback(
+    AuditRole,
+    { roleName: "audit", config, logger, emitter, eventBase, task, iteration, diff }
+  );
+  const totalDuration = Date.now() - auditStart;
+
+  trackBudget({
+    role: "audit",
+    provider: provider || coderRole.provider,
+    model: config?.roles?.audit?.model || coderRole.model,
+    result: auditOutput,
+    duration_ms: totalDuration
+  });
+
+  await addCheckpoint(session, {
+    stage: "audit",
+    iteration,
+    ok: auditOutput.ok,
+    provider: provider || coderRole.provider,
+    model: config?.roles?.audit?.model || coderRole.model || null,
+    attempts: attempts.length > 1 ? attempts : undefined
+  });
+
+  if (!auditOutput.ok) {
+    // Audit agent failed to run — treat as advisory, don't block pipeline
+    logger.warn(`Audit agent error (advisory): ${auditOutput.summary}`);
+    emitProgress(
+      emitter,
+      makeEvent("audit:end", { ...eventBase, stage: "audit" }, {
+        status: "warn",
+        message: `Audit: agent error (advisory), continuing — ${auditOutput.summary}`
+      })
+    );
+    return { action: "ok", stageResult: { ok: false, summary: auditOutput.summary || "Audit agent error (advisory)", auto_continued: true } };
+  }
+
+  // Parse findings from audit result
+  const result = auditOutput.result || {};
+  const summary = result.summary || {};
+  const overallHealth = summary.overallHealth || "fair";
+  const criticalCount = summary.critical || 0;
+  const highCount = summary.high || 0;
+
+  // Collect critical and high findings for feedback
+  const actionableFindings = [];
+  if (result.dimensions) {
+    for (const [dimName, dim] of Object.entries(result.dimensions)) {
+      for (const finding of (dim.findings || [])) {
+        if (finding.severity === "critical" || finding.severity === "high") {
+          actionableFindings.push({
+            dimension: dimName,
+            ...finding
+          });
+        }
+      }
+    }
+  }
+
+  const hasActionableIssues = (overallHealth === "poor" || overallHealth === "critical") && (criticalCount > 0 || highCount > 0);
+
+  if (hasActionableIssues) {
+    // Build feedback string for the coder
+    const feedbackLines = actionableFindings.map(f => {
+      const loc = f.file ? `${f.file}${f.line ? `:${f.line}` : ""}` : "";
+      return `[${f.severity.toUpperCase()}] ${loc} ${f.description}${f.recommendation ? ` — Fix: ${f.recommendation}` : ""}`;
+    });
+    const feedback = `Audit found ${criticalCount + highCount} critical/high issue(s) that must be fixed:\n${feedbackLines.join("\n")}`;
+
+    logger.warn(`Audit: ${criticalCount + highCount} actionable issues found, sending back to coder`);
+    emitProgress(
+      emitter,
+      makeEvent("audit:end", { ...eventBase, stage: "audit" }, {
+        status: "fail",
+        message: `Audit: ${criticalCount + highCount} issue(s) found, sending back to coder`
+      })
+    );
+
+    return { action: "retry", feedback, stageResult: { ok: false, summary: auditOutput.summary || `${criticalCount + highCount} actionable issues` } };
+  }
+
+  // Audit passed (good/fair or no critical/high findings)
+  const hasAdvisory = (summary.medium || 0) + (summary.low || 0) > 0;
+  const certifiedMsg = hasAdvisory
+    ? `Audit: CERTIFIED (with ${(summary.medium || 0) + (summary.low || 0)} advisory warning(s))`
+    : "Audit: CERTIFIED";
+
+  logger.info(certifiedMsg);
+  emitProgress(
+    emitter,
+    makeEvent("audit:end", { ...eventBase, stage: "audit" }, {
+      status: "ok",
+      message: certifiedMsg
+    })
+  );
+
+  return { action: "ok", stageResult: { ok: true, summary: certifiedMsg } };
+}
+
 // Exported for testing
 export { buildFallbackChain, isAgentFailure, runRoleWithFallback };

package/src/orchestrator.js

@@ -32,10 +32,11 @@ import { invokeSolomon } from "./orchestrator/solomon-escalation.js";
 import { PipelineContext } from "./orchestrator/pipeline-context.js";
 import { runTriageStage, runResearcherStage, runArchitectStage, runPlannerStage, runDiscoverStage, runHuReviewerStage } from "./orchestrator/pre-loop-stages.js";
 import { runCoderStage, runRefactorerStage, runTddCheckStage, runSonarStage, runSonarCloudStage, runReviewerStage } from "./orchestrator/iteration-stages.js";
-import { runTesterStage, runSecurityStage, runImpeccableStage } from "./orchestrator/post-loop-stages.js";
+import { runTesterStage, runSecurityStage, runImpeccableStage, runFinalAuditStage } from "./orchestrator/post-loop-stages.js";
 import { waitForCooldown, MAX_STANDBY_RETRIES } from "./orchestrator/standby.js";
 import { detectTestFramework } from "./utils/project-detect.js";
 import { runPreflightChecks } from "./orchestrator/preflight-checks.js";
+import { detectRtk } from "./utils/rtk-detect.js";
 
 
 // --- Extracted helper functions (pure refactoring, zero behavior change) ---
@@ -70,8 +71,8 @@ async function handleDryRun({ task, config, flags, emitter, pipelineFlags }) {
   const projectDir = config.projectDir || process.cwd();
   const { rules: reviewRules } = await resolveReviewProfile({ mode: config.review_mode, projectDir });
   const coderRules = await loadFirstExisting(resolveRoleMdPath("coder", projectDir));
-  const coderPrompt = buildCoderPrompt({ task, coderRules, methodology: config.development?.methodology, serenaEnabled: Boolean(config.serena?.enabled) });
-  const reviewerPrompt = buildReviewerPrompt({ task, diff: "(dry-run: no diff)", reviewRules, mode: config.review_mode, serenaEnabled: Boolean(config.serena?.enabled) });
+  const coderPrompt = buildCoderPrompt({ task, coderRules, methodology: config.development?.methodology, serenaEnabled: Boolean(config.serena?.enabled), rtkAvailable: Boolean(config.rtk?.available) });
+  const reviewerPrompt = buildReviewerPrompt({ task, diff: "(dry-run: no diff)", reviewRules, mode: config.review_mode, serenaEnabled: Boolean(config.serena?.enabled), rtkAvailable: Boolean(config.rtk?.available) });
 
   const summary = {
     dry_run: true,
@@ -669,6 +670,22 @@ async function handlePostLoopStages({ config, session, emitter, eventBase, coder
     }
   }
 
+  // Final audit — last quality gate before declaring success
+  const auditResult = await runFinalAuditStage({
+    config, logger, emitter, eventBase, session, coderRole, trackBudget,
+    iteration: i, task, diff: postLoopDiff
+  });
+  if (auditResult.stageResult) {
+    stageResults.audit = auditResult.stageResult;
+    await tryBecariaComment({ config, session, logger, agent: "Audit", body: `Final audit: ${auditResult.stageResult.summary || "completed"}` });
+  }
+  if (auditResult.action === "retry") {
+    // Audit found actionable issues — loop back to coder
+    session.last_reviewer_feedback = auditResult.feedback;
+    await saveSession(session);
+    return { action: "continue" };
+  }
+
   return { action: "proceed" };
 }
 
@@ -1071,6 +1088,17 @@ async function initFlowContext({ task, config, logger, emitter, askQuestion, pgT
   ctx.budgetSummary = budgetSummary;
   ctx.trackBudget = trackBudget;
 
+  // --- RTK detection ---
+  const rtkResult = await detectRtk();
+  if (rtkResult.available) {
+    config = { ...config, rtk: { available: true, version: rtkResult.version } };
+    logger.info(`RTK detected (${rtkResult.version}) — instructing agents to prefix Bash commands with rtk`);
+    emitProgress(emitter, makeEvent("rtk:detected", ctx.eventBase, {
+      message: "RTK detected — agent commands will use token optimization",
+      detail: { version: rtkResult.version }
+    }));
+  }
+
   ctx.session = await initializeSession({ task, config, flags, pgTaskId, pgProject });
   ctx.eventBase.sessionId = ctx.session.id;
 
@@ -1199,7 +1227,7 @@ export async function runFlow({ task, config, logger, flags = {}, emitter = null
   const checkpointIntervalMs = (ctx.config.session.checkpoint_interval_minutes ?? 5) * 60 * 1000;
   let lastCheckpointAt = Date.now();
   let checkpointDisabled = false;
-  let lastCheckpointSnapshot = null;
+  let lastCheckpointSnapshot = takeCheckpointSnapshot(ctx.session);
 
   let i = 0;
   while (i < ctx.config.max_iterations) {

package/src/prompts/coder.js

@@ -1,3 +1,5 @@
+import { RTK_INSTRUCTIONS } from "./rtk-snippet.js";
+
 const SUBAGENT_PREAMBLE = [
   "IMPORTANT: You are running as a Karajan sub-agent.",
   "Do NOT ask about using Karajan, do NOT mention Karajan, do NOT suggest orchestration.",
@@ -29,7 +31,7 @@ const SERENA_INSTRUCTIONS = [
   "Fall back to reading files only when Serena tools are not sufficient."
 ].join("\n");
 
-export function buildCoderPrompt({ task, reviewerFeedback = null, sonarSummary = null, coderRules = null, methodology = "tdd", serenaEnabled = false, deferredContext = null }) {
+export function buildCoderPrompt({ task, reviewerFeedback = null, sonarSummary = null, coderRules = null, methodology = "tdd", serenaEnabled = false, rtkAvailable = false, deferredContext = null }) {
   const sections = [
     serenaEnabled ? SUBAGENT_PREAMBLE_SERENA : SUBAGENT_PREAMBLE,
     `Task:\n${task}`,
@@ -42,6 +44,10 @@ export function buildCoderPrompt({ task, reviewerFeedback = null, sonarSummary =
     sections.push(SERENA_INSTRUCTIONS);
   }
 
+  if (rtkAvailable) {
+    sections.push(RTK_INSTRUCTIONS);
+  }
+
   if (coderRules) {
     sections.push(`Coder rules (MUST follow):\n${coderRules}`);
   }

package/src/prompts/reviewer.js

@@ -1,3 +1,5 @@
+import { RTK_INSTRUCTIONS } from "./rtk-snippet.js";
+
 const SUBAGENT_PREAMBLE = [
   "IMPORTANT: You are running as a Karajan sub-agent.",
   "Do NOT ask about using Karajan, do NOT mention Karajan, do NOT suggest orchestration.",
@@ -20,7 +22,7 @@ const SERENA_INSTRUCTIONS = [
   "Fall back to reading files only when Serena tools are not sufficient."
 ].join("\n");
 
-export function buildReviewerPrompt({ task, diff, reviewRules, mode, serenaEnabled = false }) {
+export function buildReviewerPrompt({ task, diff, reviewRules, mode, serenaEnabled = false, rtkAvailable = false }) {
   const truncatedDiff = diff.length > 12000 ? `${diff.slice(0, 12000)}\n\n[TRUNCATED]` : diff;
 
   const sections = [
@@ -37,6 +39,10 @@ export function buildReviewerPrompt({ task, diff, reviewRules, mode, serenaEnabl
     sections.push(SERENA_INSTRUCTIONS);
   }
 
+  if (rtkAvailable) {
+    sections.push(RTK_INSTRUCTIONS);
+  }
+
   sections.push(
     `Task context:\n${task}`,
     `Review rules:\n${reviewRules}`,

package/src/prompts/rtk-snippet.js

@@ -0,0 +1,15 @@
+/**
+ * RTK (Rust Token Killer) prompt instruction snippet.
+ * Injected into coder/reviewer prompts when RTK is detected.
+ */
+export const RTK_INSTRUCTIONS = [
+  "## Token Optimization (RTK detected)",
+  "RTK is installed. Prefix ALL Bash tool calls with `rtk` to reduce token usage:",
+  "- Use `rtk git status` instead of `git status`",
+  "- Use `rtk git diff` instead of `git diff`",
+  "- Use `rtk ls` instead of `ls`",
+  "- Use `rtk find` instead of `find`",
+  "- Use `rtk grep` instead of `grep`",
+  "- Use `rtk cat` instead of `cat`",
+  "This does NOT apply to non-Bash tools (Read, Write, Edit, Glob, Grep)."
+].join("\n");

package/src/roles/coder-role.js

@@ -41,7 +41,8 @@ export class CoderRole extends BaseRole {
       deferredContext: deferredContext || null,
       coderRules: this.instructions,
       methodology: this.config?.development?.methodology || "tdd",
-      serenaEnabled: Boolean(this.config?.serena?.enabled)
+      serenaEnabled: Boolean(this.config?.serena?.enabled),
+      rtkAvailable: Boolean(this.config?.rtk?.available)
     });
 
     const coderArgs = { prompt, role: "coder" };

package/src/roles/reviewer-role.js

@@ -1,5 +1,6 @@
 import { BaseRole } from "./base-role.js";
 import { createAgent as defaultCreateAgent } from "../agents/index.js";
+import { RTK_INSTRUCTIONS } from "../prompts/rtk-snippet.js";
 
 const MAX_DIFF_LENGTH = 12000;
 
@@ -24,7 +25,7 @@ function truncateDiff(diff) {
     : diff;
 }
 
-function buildPrompt({ task, diff, reviewRules, reviewMode, instructions }) {
+function buildPrompt({ task, diff, reviewRules, reviewMode, instructions, rtkAvailable = false }) {
   const sections = [];
 
   sections.push(SUBAGENT_PREAMBLE);
@@ -41,6 +42,10 @@ function buildPrompt({ task, diff, reviewRules, reviewMode, instructions }) {
     `Task context:\n${task}`
   );
 
+  if (rtkAvailable) {
+    sections.push(RTK_INSTRUCTIONS);
+  }
+
   if (reviewRules) {
     sections.push(`Review rules:\n${reviewRules}`);
   }
@@ -78,7 +83,8 @@ export class ReviewerRole extends BaseRole {
       diff: diff || "",
       reviewRules: reviewRules || null,
       reviewMode: this.config?.review_mode || "standard",
-      instructions: this.instructions
+      instructions: this.instructions,
+      rtkAvailable: Boolean(this.config?.rtk?.available)
     });
 
     const reviewArgs = { prompt, role: "reviewer" };

package/src/utils/rtk-detect.js

@@ -0,0 +1,18 @@
+import { runCommand } from "./process.js";
+
+/**
+ * Detect whether RTK (Rust Token Killer) is installed and available.
+ * @returns {Promise<{ available: boolean, version: string|null }>}
+ */
+export async function detectRtk() {
+  try {
+    const result = await runCommand("rtk", ["--version"]);
+    if (result.exitCode === 0) {
+      const version = (result.stdout || "").trim() || null;
+      return { available: true, version };
+    }
+    return { available: false, version: null };
+  } catch {
+    return { available: false, version: null };
+  }
+}