karajan-code 3.15.2 → 4.0.0

package/README.md

@@ -23,10 +23,20 @@
 
 ---
 
-> **v3.7.1 released** — Patch: fixes a `kj init` crash when configuring the Plan B fallback, and makes pnpm installs safe — `kj doctor` now flags when pnpm skipped `better-sqlite3`'s native build and tells you exactly how to fix it (`pnpm approve-builds better-sqlite3`). The release gate checks pnpm too. Built on **v3.7.0 — Autonomous delivery**: `kj autorun <spec>` chains spec → plan → run every user story → outcome in one command, unattended, with an **Arbiter** that resolves agent conflicts by picking the least-bad call; autonomy is opt-in, interactive runs are unchanged. Full notes in [CHANGELOG.md](CHANGELOG.md).
+> **v4.0.0 released — Karajan Environment.** The host agent orchestrates, Karajan governs. Work with Claude Code or Codex as your orchestrator; Karajan installs the method (`kj env install`), routes every diff through a review by a DIFFERENT AI (`kj review --staged`), and enforces it with a git pre-commit gate: without an approved cross-AI verdict tied to the exact staged diff, **the commit does not enter**. A false green becomes structurally impossible. The classic subprocess pipeline continues as the headless mode with the same gates. Full notes in [CHANGELOG.md](CHANGELOG.md).
 
 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.
 
+## v4: the Karajan Environment
+
+Since v4, Karajan attaches to the agent you already work with instead of driving everything by subprocess:
+
+1. **`kj env install`** — writes the Karajan method into your agent's rule file (CLAUDE.md for Claude Code, AGENTS.md for Codex, same single source): query the project RAG before coding, card first, TDD, cross-AI review before committing, security checklist. It also builds the project's RAG index if missing.
+2. **`kj review --staged`** — your diff is reviewed by an AI **different from your orchestrator** (Claude orchestrates → Codex reviews, and vice versa). The verdict is recorded, tied to the sha256 of the exact diff: change the code and it must be reviewed again.
+3. **`kj review --install-gate`** — enables the pre-commit gate. From then on, commits without an approved cross-AI verdict are rejected by git itself. The marker is tracked, so the whole team inherits the contract.
+
+This repo runs under its own environment: every commit to karajan-code carries a cross-AI verdict.
+
 ## What is Karajan?
 
 Karajan is a local coding orchestrator. It runs on your machine, uses your existing AI providers (Claude, Codex, Gemini, Aider, OpenCode), and coordinates a pipeline of specialized agents that work together on your code.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "karajan-code",
-  "version": "3.15.2",
+  "version": "4.0.0",
   "description": "Local multi-agent coding orchestrator with TDD, SonarQube, and code review pipeline",
   "type": "module",
   "license": "AGPL-3.0",
@@ -85,7 +85,8 @@
     "mcp": "node src/mcp/server.js",
     "audit:test-diet": "node scripts/audit-test-diet.mjs",
     "verify-pack": "node scripts/verify-pack.mjs",
-    "prepublishOnly": "node scripts/verify-pack.mjs"
+    "prepublishOnly": "node scripts/verify-pack.mjs",
+    "verify-quickstart": "node scripts/quickstart-gate.mjs"
   },
   "simple-git-hooks": {
     "pre-commit": "npx lint-staged"

package/scripts/quickstart-gate.mjs

@@ -0,0 +1,97 @@
+#!/usr/bin/env node
+/**
+ * Quickstart gate (KJC-TSK-0635) — the landing's Quick Start, end to end,
+ * against the PACKED tarball, with a REAL coder run.
+ *
+ * Run manually before a release (`npm run verify-quickstart`). Opt-in
+ * because the coder run spends real subscription quota (~$0.5-1.5, 5-8
+ * minutes). What it catches that unit tests and verify-pack cannot:
+ * the exact first-contact sequence a new user follows — install → init →
+ * `kj run` on a no-remote repo → playable artifact (2026-07-19: that
+ * sequence surfaced KJC-BUG-0111/0112/0113 in one afternoon).
+ *
+ * Asserts: run exits 0 · report says approved · index.html exists with
+ * game markers · "skipping push/PR" logged · ZERO Solomon escalations.
+ */
+import { execFileSync, spawnSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+const repoRoot = path.resolve(path.dirname(new URL(import.meta.url).pathname), "..");
+const TASK = "Create a tic-tac-toe game in a single self-contained index.html — vanilla HTML, CSS and JavaScript, no server and no build step. The human plays X, the bot plays O and blocks or takes a winning move when it can. Detect wins and draws, and add a New Game button. Opening index.html in a browser must be enough to play.";
+
+function fail(msg, detail) {
+  console.error(`\n✗ quickstart-gate: ${msg}`);
+  if (detail) console.error(String(detail).slice(-1200));
+  process.exitCode = 1;
+  throw new Error(msg);
+}
+
+let work = null;
+try {
+  console.log("quickstart-gate: packing…");
+  const packOut = execFileSync("npm", ["pack", "--json", "--silent"], { cwd: repoRoot, encoding: "utf8" });
+  const tgz = path.join(repoRoot, JSON.parse(packOut)[0].filename);
+
+  work = fs.mkdtempSync(path.join(os.tmpdir(), "kj-qs-gate-"));
+  const prefix = path.join(work, "npm");
+  const project = path.join(work, "project");
+  fs.mkdirSync(project, { recursive: true });
+
+  console.log("quickstart-gate: installing the tarball (isolated prefix)…");
+  execFileSync("npm", ["install", "-g", tgz, "--no-audit", "--no-fund", "--silent", "--prefix", prefix], { encoding: "utf8" });
+  const kj = path.join(prefix, "bin", "kj");
+  fs.rmSync(tgz, { force: true });
+
+  // Isolated KARAJAN_HOME: faithful to a brand-new user (no global
+  // config) and never touches the maintainer's real ~/.karajan.
+  const env = { ...process.env, KARAJAN_HOME: path.join(work, "karajan-home") };
+  delete env.CLAUDECODE;
+  // If the maintainer's machine has a SonarQube server running, preflight
+  // (correctly) demands a token the isolated home doesn't have. Forward the
+  // maintainer's token so the gate exercises the sonar stage instead of
+  // dying in preflight. A machine with no sonar server is unaffected.
+  if (!env.KJ_SONAR_TOKEN) {
+    try {
+      const cfg = fs.readFileSync(path.join(os.homedir(), ".karajan", "kj.config.yml"), "utf8");
+      const m = cfg.match(/^\s*token:\s*(sqa_[A-Za-z0-9]+|squ_[A-Za-z0-9]+)\s*$/m);
+      if (m) env.KJ_SONAR_TOKEN = m[1];
+    } catch { /* no global config — brand-new machine, nothing to forward */ }
+  }
+
+  console.log("quickstart-gate: git init + kj init (unattended)…");
+  execFileSync("git", ["init", "-q", "-b", "main"], { cwd: project });
+  const init = spawnSync(kj, ["init", "--no-interactive", "--no-ollama", "--no-rtk", "--no-squeezr", "--no-qmd"], {
+    cwd: project, env, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], timeout: 300000,
+  });
+  if (init.status !== 0) fail("kj init failed", init.stderr || init.stdout);
+
+  console.log("quickstart-gate: kj run (REAL coder — this spends quota, ~5-8 min)…");
+  const runRes = spawnSync(kj, ["run", "-y", TASK], {
+    cwd: project, env, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], timeout: 20 * 60 * 1000,
+  });
+  const runOut = `${runRes.stdout || ""}${runRes.stderr || ""}`;
+  fs.writeFileSync(path.join(work, "run.log"), runOut);
+
+  if (runRes.status !== 0) fail(`kj run exited ${runRes.status} (log: ${work}/run.log)`, runOut);
+  if (/escalating to Solomon/i.test(runOut)) fail(`Solomon escalation detected — the happy path must not consult Solomon (log: ${work}/run.log)`);
+  // KJC-BUG-0112 regression: a remote-less repo must never attempt (and
+  // fail) push/fetch automation. With init's defaults (auto_push: false)
+  // the "skipping push/PR" line is legitimately absent, so assert the
+  // absence of failure symptoms rather than the presence of the skip line.
+  if (/failed to push|fatal: .*origin|couldn't find remote/i.test(runOut)) fail(`push/fetch against a missing remote detected (log: ${work}/run.log)`);
+
+  const html = path.join(project, "index.html");
+  if (!fs.existsSync(html)) fail("index.html was not created");
+  const htmlText = fs.readFileSync(html, "utf8");
+  if (!/new game/i.test(htmlText)) fail("index.html has no New Game control — not the requested game");
+
+  const report = spawnSync(kj, ["report"], { cwd: project, env, encoding: "utf8", timeout: 60000 });
+  if (!/approved/i.test(`${report.stdout || ""}`)) fail("kj report does not say approved", report.stdout);
+
+  console.log("\n✓ quickstart-gate: install → init → run → playable index.html → approved. Ship it.");
+} finally {
+  if (work && process.exitCode !== 1 && fs.existsSync(work)) fs.rmSync(work, { recursive: true, force: true });
+  if (work && process.exitCode === 1) console.error(`quickstart-gate: workdir kept for inspection: ${work}`);
+}

package/scripts/verify-pack.mjs

@@ -52,6 +52,7 @@ let tgzPath = null;
 let tmpDir = null;
 let gTmp = null;
 let pnpmTmp = null;
+let qsTmp = null;
 try {
   console.log(`verify-pack: packing karajan-code@${expectedVersion}…`);
   // --json gives us the exact filename without parsing human output.
@@ -146,6 +147,42 @@ try {
   }
   console.log(`verify-pack: global install + kj --version → ${gVersion} ✓`);
 
+  // 5.5 Quickstart smoke (KJC-TSK-0635) — the landing's Getting Started
+  // sequence against the INSTALLED tarball, no LLM involved. Born from
+  // 2026-07-19: following the docs to the letter caught 3 field bugs
+  // (silent 2.34.0 install, Solomon loop on no-remote repos, retired
+  // gemini CLI) that 6000 unit tests never saw. Aux bootstraps (ollama,
+  // rtk, squeezr, qmd, harden) are skipped — this validates kj's own
+  // init + config on the canonical no-remote scenario, not the network.
+  qsTmp = fs.mkdtempSync(path.join(os.tmpdir(), "kj-verify-qs-"));
+  console.log(`verify-pack: quickstart smoke (init on a no-remote repo) in ${qsTmp}…`);
+  run("git", ["init", "-q", "-b", "main"], { cwd: qsTmp });
+  // KARAJAN_HOME points at an isolated dir: faithful to a brand-new user
+  // (no pre-existing global config — `--local` without one is rejected by
+  // design, which is exactly what this smoke caught on its first CI run)
+  // AND hermetic (never touches the real ~/.karajan).
+  const qsEnv = { ...childEnv, KARAJAN_HOME: path.join(qsTmp, "karajan-home") };
+  delete qsEnv.CLAUDECODE;
+  const initRes = spawnSync(gBin, ["init", "--no-interactive", "--no-ollama", "--no-rtk", "--no-squeezr", "--no-qmd", "--no-harden"], {
+    encoding: "utf8", cwd: qsTmp, env: qsEnv, timeout: 180000,
+  });
+  if (initRes.status !== 0) {
+    fail("`kj init --no-interactive` failed on a fresh no-remote repo", (initRes.stderr || initRes.stdout || "").slice(-800));
+  }
+  const qsCfgLocal = path.join(qsTmp, ".karajan", "kj.config.yml");
+  const qsCfgGlobal = path.join(qsTmp, "karajan-home", "kj.config.yml");
+  const qsCfg = fs.existsSync(qsCfgLocal) ? qsCfgLocal : qsCfgGlobal;
+  if (!fs.existsSync(qsCfg)) fail(`kj init did not write ${qsCfg}`);
+  if (!/coder:\s*\S+/.test(fs.readFileSync(qsCfg, "utf8"))) {
+    fail("generated kj.config.yml has no coder assignment");
+  }
+  const reportRes = spawnSync(gBin, ["report"], { encoding: "utf8", cwd: qsTmp, env: qsEnv, timeout: 60000 });
+  const reportOut = `${reportRes.stdout || ""}${reportRes.stderr || ""}`;
+  if (reportRes.status !== 0 && !/no session|sin sesi|not found/i.test(reportOut)) {
+    fail("`kj report` crashed on a project with no sessions", reportOut.slice(-400));
+  }
+  console.log("verify-pack: quickstart smoke (init + report, no-remote repo) ✓");
+
   // 6. pnpm install smoke (KJC-TSK-0580). pnpm's layout differs from npm's
   // (a symlinked virtual store), so it can break resolution of the bundled
   // karajan-core the way npm packaging breakage did before (KJC-BUG-0082/0086).
@@ -195,4 +232,5 @@ try {
   if (tmpDir && fs.existsSync(tmpDir)) fs.rmSync(tmpDir, { recursive: true, force: true });
   if (gTmp && fs.existsSync(gTmp)) fs.rmSync(gTmp, { recursive: true, force: true });
   if (pnpmTmp && fs.existsSync(pnpmTmp)) fs.rmSync(pnpmTmp, { recursive: true, force: true });
+  if (qsTmp && fs.existsSync(qsTmp)) fs.rmSync(qsTmp, { recursive: true, force: true });
 }

package/src/cli/advanced-commands.js

@@ -32,7 +32,7 @@ export const ADVANCED_GROUPS = [
   { title: "Búsqueda / RAG", commands: ["rag", "qmd", "watch"] },
   { title: "Calidad / auditoría", commands: ["audit", "check", "mutate", "webperf", "sonar"] },
   { title: "Sesión / board", commands: ["resume", "report", "board", "undo", "standby"] },
-  { title: "Infra / setup", commands: ["install-tools", "ollama", "skills", "roles", "agents"] },
+  { title: "Infra / setup", commands: ["install-tools", "ollama", "skills", "roles", "agents", "env"] },
   { title: "Mantenimiento", commands: ["clean", "sync", "telemetry"] },
 ];
 

package/src/cli/register-meta.js

@@ -19,6 +19,7 @@ import { checkCommand } from "../commands/check.js";
 import { mutateCommand } from "../commands/mutate.js";
 import { hardenCommand } from "../commands/harden.js";
 import { telemetryPreviewCommand, telemetryStatusCommand } from "../commands/telemetry.js";
+import { envInstallCommand } from "../commands/env.js";
 import { formatAdvancedIndex } from "../commands/advanced.js";
 import { withConfig } from "./_shared.js";
 
@@ -121,6 +122,19 @@ export function registerMeta(program, { pkgVersion }) {
       });
     });
 
+  // ENV-A1 (KJC-TSK-0639) — Karajan Environment v4: the host agent
+  // orchestrates, Karajan installs the method it must follow.
+  const env = program.command("env").description("Karajan Environment (v4) — playbook for host agents");
+  env.command("install")
+    .description("Install/refresh the Karajan playbook in CLAUDE.md (Claude) and AGENTS.md (Codex)")
+    .option("--target <target>", "claude | codex | both", "both")
+    .option("--no-rag", "Skip building the RAG index when the project has none (ENV-E1)")
+    .action(async (flags) => {
+      await withConfig(pkgVersion, "env-install", flags, async ({ config, logger }) => {
+        await envInstallCommand({ config, logger, flags });
+      });
+    });
+
   const rag = program.command("rag").description("Retrieval-augmented search over Karajan plans, onboarding briefs and project code");
   rag.command("index")
     .description("Index plans + onboarding (and optionally project sources) into the local vector store")
@@ -142,6 +156,7 @@ export function registerMeta(program, { pkgVersion }) {
     });
   rag.command("query <text>")
     .description("Run a semantic query against the indexed RAG corpus")
+    .option("--no-rag-update", "Skip the pre-query drift delta-update (ENV-E1)")
     .option("--scope <scope>", "plans | code | onboarding | all (default: all)", "all")
     .option("--top-k <n>", "Number of hits to return (default: 5)", "5")
     .option("--project <slug>", "Filter by project slug. Pass 'all' to query across every indexed project. Default: cwd basename")

package/src/cli/register-pipeline.js

@@ -183,14 +183,25 @@ export function registerPipeline(program, { pkgVersion }) {
 
   program
     .command("review")
-    .description("Run only reviewer")
+    .description("Run only reviewer (--staged/--check: v4 cross-AI gate with recorded verdict)")
     .argument("[task]", "Task description (REQUIRED — provide as argument or via --task-file)")
     .option("--task-file <path>", "Read the task from a file (e.g. .md)")
     .option("--reviewer <name>")
     .option("--reviewer-model <name>")
     .option("--base-ref <ref>")
+    .option("--staged", "Review the staged diff with a cross-AI reviewer and record the verdict")
+    .option("--check", "Verify the recorded verdict matches the staged diff (exit 0/1, hook-friendly)")
+    .option("--range <range>", "Review a git range (e.g. main..HEAD) instead of the staged diff")
+    .option("--install-gate", "Enable the pre-commit review gate for this project (creates .karajan/review-gate)")
     .action(async (task, flags) => {
       await withConfig(pkgVersion, "review", flags, async ({ config, logger }) => {
+        // ENV-B1 (KJC-TSK-0637): the gate mode records a verdict tied to
+        // the exact diff so the pre-commit hook can enforce cross-AI review.
+        if (flags.staged || flags.check || flags.range || flags.installGate) {
+          const { reviewGateCommand } = await import("../commands/review-gate.js");
+          await reviewGateCommand({ config, logger, flags: { ...flags, task } });
+          return;
+        }
         const { resolveTaskInput } = await import("../utils/task-file.js");
         const resolvedTask = await resolveTaskInput({ task, taskFile: flags.taskFile, projectDir: config.projectDir, logger });
         await reviewCommand({ task: resolvedTask, config, logger, baseRef: flags.baseRef });

package/src/commands/env.js

@@ -0,0 +1,43 @@
+/**
+ * `kj env install` (ENV-A1/E1, KJC-TSK-0639/0640) — install/refresh the
+ * Karajan Environment playbook as a managed block in the host agents' rule
+ * files (CLAUDE.md, AGENTS.md), and make its step 1 real: when the project
+ * has no RAG index yet, build it (default ON, `--no-rag` opts out).
+ */
+import { installPlaybook } from "../environment/playbook.js";
+import { openVecStore, projectSlug, getLastIndexedCommit } from "../rag/vec-store.js";
+import { ragIndexCommand } from "./rag.js";
+
+function hasRagIndex(config, projectDir) {
+  const db = openVecStore({ dim: config?.rag?.embedder?.dim || 768 });
+  try { return Boolean(getLastIndexedCommit(db, projectSlug(projectDir))); }
+  finally { db.close(); }
+}
+
+export async function envInstallCommand({ config = null, logger = null, flags = {} }) {
+  const projectDir = config?.projectDir || process.cwd();
+  const result = await installPlaybook({
+    projectDir, target: flags.target || "both",
+    stateBackend: config?.state_backend || "hu-board",
+  });
+  console.log(`✓ Karajan playbook installed in: ${result.files.join(", ")}`);
+
+  // ENV-E1: RAG-first — the playbook orders "query the RAG before coding",
+  // so installing the environment guarantees the index exists. An indexing
+  // failure is reported but never blocks the playbook install.
+  if (flags.rag !== false) {
+    try {
+      if (hasRagIndex(config, projectDir)) {
+        console.log("✓ RAG index present");
+      } else {
+        console.log("⏳ no RAG index for this project — building it (first time only)…");
+        await ragIndexCommand({ config, logger, flags: { withSources: true } });
+      }
+    } catch (err) {
+      result.ragError = err.message;
+      console.log(`⚠ RAG index could not be built (${err.message}) — run \`kj rag index --with-sources\` later`);
+    }
+  }
+  console.log("  The host agent now follows the method: RAG first, TDD, cross-AI review before commit.");
+  return result;
+}

package/src/commands/rag.js

@@ -6,7 +6,7 @@ import { openVecStore, countChunks, projectSlug, getLastIndexedCommit, setLastIn
 import { makeEmbedder } from "../rag/embedders/factory.js";
 import { indexProject, indexProjectDelta } from "../rag/indexer.js";
 import { query } from "../rag/retriever.js";
-import { installPostMergeHook } from "../rag/auto-update.js";
+import { installPostMergeHook, maybeAutoUpdate } from "../rag/auto-update.js";
 import { loadGoldenQueries, runEval } from "../rag/eval.js";
 import { getKarajanHome } from "../utils/paths.js";
 
@@ -73,6 +73,11 @@ export async function ragInstallHooksCommand({ config, logger, flags = {} }) {
 
 export async function ragQueryCommand({ text, config, logger, flags = {} }) {
   if (!text) throw new Error("kj rag query: text argument required");
+  // ENV-E1 (KJC-TSK-0640): never serve stale code — delta-update on drift
+  // before searching. Same escape hatches as the pre-run check
+  // (--no-rag-update / config.rag.autoUpdate); failures degrade to a warn
+  // inside maybeAutoUpdate and the query proceeds with the current index.
+  await maybeAutoUpdate({ projectDir: config?.projectDir || process.cwd(), config, logger, flags });
   const db = openDb(config);
   try {
     const topK = Math.max(1, Number(flags.topK) || 5);

package/src/commands/report.js

@@ -3,6 +3,7 @@ import path from "node:path";
 import { exists } from "../utils/fs.js";
 import { getSessionRoot } from "../utils/paths.js";
 import { loadConfig } from "../config.js";
+import { DEFAULTS } from "../config/defaults.js";
 
 function parseBudgetFromActivityLog(logText) {
   if (!logText) {
@@ -131,6 +132,14 @@ async function buildReport(dir, sessionId) {
 
   const sonar = summarizeSonar(checkpoints);
   const budget = parseBudgetFromActivityLog(activityLog);
+  // KJC-BUG-0114: activity logs written when max_budget_usd was null carry
+  // a phantom "$0.00" ceiling (Number(null) === 0). Resolve the effective
+  // ceiling from the session's config snapshot, falling back to the
+  // shipped default; an explicit 0 means "no ceiling" and drops the suffix.
+  if (budget.limit_usd === 0) {
+    const snapBudget = session.config_snapshot?.max_budget_usd;
+    budget.limit_usd = snapBudget == null ? DEFAULTS.max_budget_usd : (Number(snapBudget) || null);
+  }
   const commits = summarizeCommits(session, checkpoints);
 
   const budgetTrace = Array.isArray(session.budget?.trace) ? session.budget.trace : [];

package/src/commands/review-gate.js

@@ -0,0 +1,69 @@
+/**
+ * `kj review --staged | --check | --range` (ENV-B1, KJC-TSK-0637) — the v4
+ * cross-AI review gate. Unlike the legacy task-review mode, this reviews a
+ * raw git diff with an AI DIFFERENT from the host agent and records the
+ * verdict tied to the exact diff (verdict-store), so the pre-commit hook
+ * (ENV-C) can verify it. Exit code 0 = approved, 1 = rejected/stale.
+ */
+import { runCommand } from "../utils/process.js";
+import { checkVerdict } from "../review/verdict-store.js";
+import { runOneShotReview } from "../review/one-shot-review.js";
+
+// Raw git always — never a wrapped/compressing runner (KJC-BUG-0115).
+async function rawDiff(range) {
+  const args = range ? ["diff", range] : ["diff", "--cached"];
+  const res = await runCommand("git", args);
+  if (res.exitCode !== 0) {
+    throw new Error(res.stderr?.trim() || `git ${args.join(" ")} failed`);
+  }
+  return res.stdout;
+}
+
+function printVerdict(record) {
+  if (record.verdict === "approved") {
+    console.log(`✓ APPROVED by ${record.reviewer} (diff ${record.diffHash.slice(0, 12)})`);
+    if (record.summary) console.log(`  ${record.summary}`);
+    return;
+  }
+  console.log(`✗ REJECTED by ${record.reviewer} — ${record.issues.length} blocking issue(s):`);
+  for (const issue of record.issues) {
+    const where = issue.file ? ` [${issue.file}${issue.line ? `:${issue.line}` : ""}]` : "";
+    console.log(`  - (${issue.severity || "high"})${where} ${issue.description || issue.id}`);
+    if (issue.suggested_fix) console.log(`    fix: ${issue.suggested_fix}`);
+  }
+  console.log("Fix the issues and run `kj review --staged` again — the verdict is tied to the exact diff.");
+}
+
+export async function reviewGateCommand({ config, logger = null, flags = {} }) {
+  const projectDir = config?.projectDir || process.cwd();
+
+  if (flags.installGate) {
+    const fs = await import("node:fs/promises");
+    const path = await import("node:path");
+    const marker = path.join(projectDir, ".karajan", "review-gate");
+    await fs.mkdir(path.dirname(marker), { recursive: true });
+    await fs.writeFile(marker, "# Cross-AI review gate enabled (ENV-C1). Commit this file so the whole team inherits the gate.\n");
+    console.log("✓ review gate enabled — commits now require an approved cross-AI verdict (kj review --staged)");
+    const hookProbe = await runCommand("git", ["config", "core.hooksPath"]);
+    if (!hookProbe.stdout?.trim()) {
+      console.log("⚠ no core.hooksPath configured — run `kj harden` so the pre-commit hook enforces the gate");
+    }
+    return { installed: true };
+  }
+
+  const diff = await rawDiff(flags.range);
+
+  if (flags.check) {
+    const res = await checkVerdict(projectDir, diff);
+    console.log(res.ok
+      ? `✓ verdict ok — approved by ${res.verdict.reviewer} (diff ${res.verdict.diffHash.slice(0, 12)})`
+      : `✗ ${res.reason}`);
+    process.exitCode = res.ok ? 0 : 1;
+    return res;
+  }
+
+  const record = await runOneShotReview({ diff, task: flags.task, config, logger, projectDir });
+  printVerdict(record);
+  process.exitCode = record.verdict === "approved" ? 0 : 1;
+  return record;
+}

package/src/config/defaults.js

@@ -59,6 +59,9 @@ const DEFAULTS = {
   // runaway run must never drain a subscription quota unattended. Explicit
   // null in the user's config opts out (no cap).
   max_budget_usd: 5,
+  // ENV-D1 (KJC-TSK-0642): where work items live. The HU Board ships with
+  // kj; "planning-game" routes the v4 playbook to the user's PG MCP.
+  state_backend: "hu-board",
   review_rules: "./.karajan/review-rules.md",
   coder_rules: "./.karajan/coder-rules.md",
   base_branch: "main",

package/src/config/schema.js

@@ -235,6 +235,12 @@ export const ConfigSchema = v.looseObject({
     v.number(),
     v.minValue(0, "max_budget_usd must be >= 0")
   ))),
+  // ENV-D1 (KJC-TSK-0642): where work items live — the integrated HU Board
+  // or the user's Planning Game. The v4 playbook renders per backend.
+  state_backend: v.optional(v.picklist(
+    ["hu-board", "planning-game"],
+    "state_backend must be \"hu-board\" or \"planning-game\""
+  )),
   review_rules: v.optional(v.string()),
   coder_rules: v.optional(v.string()),
   base_branch: v.optional(v.string()),

package/src/environment/playbook.js

@@ -0,0 +1,76 @@
+/**
+ * Karajan Environment playbook (ENV-A1, KJC-TSK-0639).
+ *
+ * ONE source renders the method for every host agent: a managed block in
+ * CLAUDE.md (Claude Code) and AGENTS.md (Codex). The body is data here —
+ * not a template file — so it never counts as a repo AI-rule file and can
+ * be parameterized later (rag/gate state, backend) without forking copies.
+ *
+ * The playbook is agent context: every line costs attention on every turn,
+ * so it stays under 60 lines by test. Method over prose.
+ */
+import fs from "node:fs/promises";
+import path from "node:path";
+import { upsertManagedBlock } from "../utils/managed-markers.js";
+
+export const PLAYBOOK_TARGETS = ["claude", "codex", "both"];
+
+const TARGET_FILES = { claude: ["CLAUDE.md"], codex: ["AGENTS.md"], both: ["CLAUDE.md", "AGENTS.md"] };
+
+// ENV-D1 (KJC-TSK-0642): step 2 names the CHOSEN state backend — a playbook
+// that says "board or PG" makes the host guess; the config already knows.
+const BACKEND_TRACKING = {
+  "hu-board": "no work without a tracked story/bug in the HU Board (`kj board`).",
+  "planning-game": "no work without a tracked card in the Planning Game MCP (create it first, move it to In Progress when you start).",
+};
+
+const playbookBody = (stateBackend) => `# Karajan method (v4)
+
+You are the orchestrator; Karajan governs the method. Follow this on every task:
+
+1. **Context first**: before writing code, query the project RAG:
+   \`kj rag query "<what you need to know>"\` — never guess what the codebase does.
+2. **Card first**: ${BACKEND_TRACKING[stateBackend] || BACKEND_TRACKING["hu-board"]}
+3. **TDD**: write or extend the failing test FIRST, then the code. Run the suite
+   after every significant change; never leave it red.
+4. **Cross-AI review before committing**: stage your changes and run
+   \`kj review --staged\` — a DIFFERENT AI reviews the diff and records a verdict.
+   If rejected: fix the issues and review again (the verdict is tied to the exact
+   diff, so any change requires a new one). The pre-commit hook enforces this
+   when the project has the review gate enabled.
+5. **Security checklist** (you absorb the security role): validate all inputs,
+   never commit secrets or keys, no deprecated APIs, parameterized queries,
+   sanitize anything user-controlled before it reaches HTML/shell/SQL.
+6. **Ship small**: Conventional Commits, atomic PRs (~150 net lines), each PR
+   compiles and passes tests on its own.
+
+Useful commands: \`kj rag query\` · \`kj review --staged\` · \`kj review --check\` ·
+\`kj report\` · \`kj check\`
+`;
+
+export function renderPlaybook({ stateBackend = "hu-board" } = {}) {
+  return playbookBody(stateBackend);
+}
+
+/**
+ * Install/refresh the playbook block in the target agent files.
+ * User content outside the managed block is never touched.
+ */
+export async function installPlaybook({ projectDir, target = "both", version = "1", stateBackend = "hu-board" }) {
+  if (!PLAYBOOK_TARGETS.includes(target)) {
+    throw new Error(`unknown target "${target}" — use one of: ${PLAYBOOK_TARGETS.join(", ")}`);
+  }
+  const files = [];
+  for (const file of TARGET_FILES[target]) {
+    const fullPath = path.join(projectDir, file);
+    let source = "";
+    try { source = await fs.readFile(fullPath, "utf8"); } catch { /* new file */ }
+    const { content, action } = upsertManagedBlock({
+      source, blockId: "playbook", version, body: renderPlaybook({ stateBackend }), style: "html",
+      note: "do not edit: regenerated by kj env install",
+    });
+    if (action !== "unchanged") await fs.writeFile(fullPath, content);
+    files.push(file);
+  }
+  return { files, target };
+}

package/src/git/automation.js

@@ -4,6 +4,7 @@
  */
 
 import { addCheckpoint } from "../session/store.js";
+import { stampStagedVerdict } from "../review/verdict-store.js";
 import {
   ensureGitRepo,
   currentBranch,
@@ -268,7 +269,16 @@ export async function finalizeGitAutomation({ config, gitCtx, task, logger, sess
   let committed = false;
   const commits = [];
   if (config.git.auto_commit) {
-    const commitResult = await commitAll(commitMsg);
+    // ENV-F1: this path only runs after the pipeline's reviewer approved,
+    // so stamp that verdict for the staged diff — the v4 pre-commit gate
+    // (when the repo opted in) accepts the pipeline's own commit.
+    const commitResult = await commitAll(commitMsg, null, {
+      beforeCommit: () => stampStagedVerdict({
+        projectDir: config?.projectDir || process.cwd(),
+        reviewer: config?.reviewer || "pipeline-reviewer",
+        summary: `kj run session ${session?.id || ""}: reviewer approved`.trim(),
+      }),
+    });
     committed = commitResult.committed;
     if (commitResult.commit) {
       commits.push(commitResult.commit);

package/src/harden/hook-templates.js

@@ -28,6 +28,16 @@ export function hookBody(hook, cmds = {}) {
       if (cmds.lint) lines.push(`${cmds.lint} || { echo 'kj harden: lint failed'; exit 1; }`);
       if (cmds.format) lines.push(`${cmds.format} || { echo 'kj harden: format check failed'; exit 1; }`);
       if (!cmds.lint && !cmds.format) lines.push("# (no lint/format command detected for this stack)");
+      lines.push(
+        "# v4 review gate (ENV-C1, opt-in via `kj review --install-gate`):",
+        "# a staged diff only enters with a recorded cross-AI approved verdict.",
+        "if [ -f .karajan/review-gate ]; then",
+        "  if ! command -v kj >/dev/null 2>&1; then",
+        "    echo 'kj: review gate is enabled but kj is not installed — see karajancode.com/docs/getting-started/installation'; exit 1",
+        "  fi",
+        "  kj review --check || { echo 'kj: no approved cross-AI verdict for the staged diff — run `kj review --staged`'; exit 1; }",
+        "fi"
+      );
       return lines.join("\n");
     }
     case "commit-msg":

package/src/orchestrator/config-init.js

@@ -12,6 +12,7 @@ import { resolveRole } from "../config.js";
 import { emitProgress, makeEvent } from "../utils/events.js";
 import { getTemplatesRoot } from "../utils/templates-root.js";
 import { BudgetTracker, extractUsageMetrics } from "../utils/budget.js";
+import { DEFAULTS } from "../config/defaults.js";
 import { computeKjComparison } from "../budget/comparison.js";
 import { resolveRoleMdPath, loadFirstExisting } from "../roles/base-role.js";
 import { projectSlug } from "../plan/plan-store.js";
@@ -303,8 +304,13 @@ export async function handleDryRun({ task, config, flags, emitter, pipelineFlags
 
 export function createBudgetManager({ config, emitter, eventBase, getCompressionStats = null }) {
   const budgetTracker = new BudgetTracker({ pricing: config?.budget?.pricing });
-  const budgetLimit = Number(config?.max_budget_usd);
-  const hasBudgetLimit = Number.isFinite(budgetLimit) && budgetLimit >= 0;
+  // KJC-BUG-0114: Number(null) === 0, so a config that reached us with
+  // max_budget_usd: null produced a phantom "$X / $0.00" ceiling (and a
+  // permanent warn state). null/undefined fall back to the shipped
+  // default ceiling; an explicit 0 means "no ceiling".
+  const rawBudget = config?.max_budget_usd;
+  const budgetLimit = rawBudget == null ? DEFAULTS.max_budget_usd : Number(rawBudget);
+  const hasBudgetLimit = Number.isFinite(budgetLimit) && budgetLimit > 0;
   const warnThresholdPct = Number(config?.budget?.warn_threshold_pct ?? 80);
   let stageCounter = 0;
 

package/src/orchestrator/drivers/init-context.js

@@ -21,9 +21,8 @@ import { prepareGitAutomation } from "../../git/automation.js";
 import { CoderRole } from "../../roles/coder-role.js";
 import { PipelineContext } from "../pipeline-context.js";
 import { detectRtk } from "../../utils/rtk-detect.js";
-import { createRtkRunner, RtkSavingsTracker } from "../../utils/rtk-wrapper.js";
-import { setRunner as setDiffRunner, setProjectDir as setDiffProjectDir } from "../../review/diff-generator.js";
-import { setRunner as setGitRunner } from "../../utils/git.js";
+import { RtkSavingsTracker } from "../../utils/rtk-wrapper.js";
+import { setProjectDir as setDiffProjectDir } from "../../review/diff-generator.js";
 import {
   loadProductContext, resolvePipelineFlags, createBudgetManager,
   initializeSession, autoInit,
@@ -116,19 +115,19 @@ export async function initFlowContext({ task, config, logger, emitter, askQuesti
   const rtkResult = await detectRtk();
   if (rtkResult.available) {
     config = { ...config, rtk: { available: true, version: rtkResult.version } };
-    const rtkTracker = new RtkSavingsTracker();
-    const rtkRunner = createRtkRunner(true, rtkTracker);
-    // TSK-0338: install rtkRunner into the per-run context; module-level
-    // setters are the back-compat path for runs outside a withRunContext scope.
-    if (runCtx) runCtx.runner = rtkRunner;
-    else {
-      setDiffRunner(rtkRunner);
-      setGitRunner(rtkRunner);
-    }
-    ctx.rtkTracker = rtkTracker;
-    logger.info(`RTK detected (${rtkResult.version}) — wrapping internal git/diff commands with rtk`);
+    // KJC-BUG-0115: rtk MUST NOT wrap the pipeline's internal git/diff
+    // commands. `rtk git diff` emits a compressed summary without
+    // `diff --git` headers, so every consumer that parses the output
+    // (tdd-policy extractChangedFiles, reviewer diffs, status checks)
+    // sees an empty change set — in the field this made the TDD gate
+    // fail forever with "(2 src, 0 test)" while real tests existed.
+    // RTK still saves tokens where it belongs: inside the coder agent's
+    // own shell, via its Claude Code hook. Detection is kept so the
+    // config advertises availability to agents.
+    ctx.rtkTracker = new RtkSavingsTracker();
+    logger.info(`RTK detected (${rtkResult.version}) — available to agents (internal git/diff stay unwrapped)`);
     emitProgress(emitter, makeEvent("rtk:detected", ctx.eventBase, {
-      message: "RTK detected — internal commands wrapped for token optimization",
+      message: "RTK detected — available to agents",
       detail: { version: rtkResult.version, executorType: "local" }
     }));
   }

package/src/orchestrator/drivers/iteration-loop.js

@@ -253,6 +253,7 @@ export async function runIterationLoop(ctx, { task: loopTask, askQuestion, emitt
     }
     if (iterResult.action === "retry") { i -= 1; }
     else {
+      await ensureIterationRecorded(ctx, i, logger);
       // Iteration gate (KJC-TSK-0628): opt-in pause with a report before the
       // next iteration; free-text answers become directives for the coder.
       const gate = await handleIterationGate({
@@ -306,6 +307,7 @@ export async function runIterationLoop(ctx, { task: loopTask, askQuestion, emitt
       if (iterResult.action === "return") return iterResult.result;
       if (iterResult.action === "retry") { i -= 1; }
       else {
+        await ensureIterationRecorded(ctx, i, logger);
         // Same iteration gate on Solomon-extended iterations (KJC-TSK-0628).
         const gate = await handleIterationGate({
           enabled: ctx.config.session?.iteration_gate === true,
@@ -323,9 +325,56 @@ export async function runIterationLoop(ctx, { task: loopTask, askQuestion, emitt
 
     // Extended iterations also exhausted — final Solomon call
     const finalResult = await handleMaxIterationsReached({ session: ctx.session, budgetSummary: ctx.budgetSummary, emitter, eventBase: ctx.eventBase, config: ctx.config, stageResults: ctx.stageResults, logger, askQuestion, task: loopTask, rtkTracker: ctx.rtkTracker, brainCtx: ctx.brainCtx });
-    return finalResult;
+    return finalizeMaxIterationsApproval(ctx, finalResult, { task: loopTask, askQuestion, emitter, logger, i });
   }
 
-  return maxIterResult;
+  return finalizeMaxIterationsApproval(ctx, maxIterResult, { task: loopTask, askQuestion, emitter, logger, i });
+}
+
+// KJC-BUG-0117: iterations that end before the reviewer (TDD/sonar
+// "continue", guard retries) never reached the recordIteration call at
+// the end of runSingleIteration, so session._journalIterations stayed
+// empty and the journal read "Iterations: 0" after a 5-iteration run.
+export async function ensureIterationRecorded(ctx, i, logger) {
+  if (!ctx.journalIterations) return;
+  if ((ctx.session._journalIterations?.length || 0) >= i) return;
+  try {
+    const { recordIteration, extractIterationData } = await import("../../session/journal/iteration-logger.js");
+    recordIteration(ctx.session, extractIterationData({
+      iteration: i, durationMs: 0, stageResults: ctx.stageResults, session: ctx.session,
+    }));
+  } catch (err) {
+    logger.warn(`Iteration journal record failed (non-blocking): ${err.message}`);
+  }
+}
+
+// KJC-BUG-0116: an "approved" verdict at max_iterations (brain_approved,
+// brain_solomon_approved, solomon_approved) used to be returned as-is,
+// skipping the entire post-loop (tester/security/audit) AND git
+// automation (push/PR) that every reviewer-approved session gets — the
+// session read "approved" with zero verification and zero push. Route it
+// through the same handleApprovedReview path instead.
+export async function finalizeMaxIterationsApproval(ctx, maxIterResult, { task, askQuestion, emitter, logger, i }) {
+  if (maxIterResult?.approved !== true) return maxIterResult;
+
+  const review = {
+    approved: true,
+    raw_summary: `Finalized at max_iterations (${maxIterResult.reason || "approved"})`,
+    blocking_issues: []
+  };
+  const fin = await handleApprovedReview({
+    config: ctx.config, session: ctx.session, emitter, eventBase: ctx.eventBase,
+    coderRole: ctx.coderRole, trackBudget: ctx.trackBudget, i, task,
+    stageResults: ctx.stageResults, pipelineFlags: ctx.pipelineFlags, askQuestion, logger,
+    gitCtx: ctx.gitCtx, budgetSummary: ctx.budgetSummary, pgCard: ctx.pgCard, pgProject: ctx.pgProject,
+    review, rtkTracker: ctx.rtkTracker, brainCtx: ctx.brainCtx
+  });
+  if (fin.action === "return") return fin.result;
+
+  // Post-loop demanded another coder pass but iterations are exhausted —
+  // report honestly instead of a false green.
+  logger.warn("Post-loop stages rejected the work at max_iterations — session NOT approved");
+  await markSessionStatus(ctx.session, "failed");
+  return { approved: false, sessionId: ctx.session.id, reason: "post_loop_rejected_at_max_iterations" };
 }
 

package/src/orchestrator/stages/coder-stage.js

@@ -389,16 +389,19 @@ async function handleTddFailure({ tddEval, config, logger, emitter, eventBase, s
     return { action: "continue" };
   }
 
-  // Brain: when enabled, skip Solomon — Brain handles via max_iterations
+  // Brain: at the sub-loop limit the TDD gate must stop eating iterations.
+  // KJC-BUG-0115: returning "continue" here short-circuited runSingleIteration
+  // before the reviewer gate — 5/5 iterations ended without any review. The
+  // failure is already queued as feedback; "proceed" lets the reviewer run.
   if (brainCtx?.enabled) {
-    logger.info("Brain: TDD sub-loop limit reached — Brain will handle via max_iterations (Solomon bypassed)");
+    logger.info("Brain: TDD sub-loop limit reached — proceeding to reviewer with TDD failure as pending feedback");
     emitProgress(emitter, makeEvent("brain:tdd-retry-limit", { ...eventBase, stage: "tdd" }, {
-      message: `TDD sub-loop limit reached (${session.repeated_issue_count}/${config.session.fail_fast_repeats}) — Brain handling`,
+      message: `TDD sub-loop limit reached (${session.repeated_issue_count}/${config.session.fail_fast_repeats}) — proceeding to reviewer`,
       detail: { subloop: "tdd", retryCount: session.repeated_issue_count, reason: tddEval.reason }
     }));
     resetRetryCount(session, "repeated_issue");
     await saveSession(session);
-    return { action: "continue" };
+    return { action: "proceed" };
   }
 
   emitProgress(

package/src/rag/indexer.js

@@ -119,7 +119,14 @@ async function listFiles(dir, predicate) {
  * it as `--with-sources`.
  */
 export async function indexProject(projectDir, { db, embedder, karajanHome, logger = console, withSources = false } = {}) {
-  const totals = { indexed: 0, failed: 0, files: 0 };
+  // KJC-TSK-0640: a full index must stamp HEAD too — without it,
+  // last_indexed_commit stayed null after the FIRST index, so the drift
+  // delta-update (maybeAutoUpdate) never engaged until a manual --since.
+  const totals = { indexed: 0, failed: 0, files: 0, head: null };
+  try {
+    const { stdout } = await execa("git", ["-C", projectDir, "rev-parse", "HEAD"]);
+    totals.head = stdout.trim();
+  } catch { /* not a git repo (or zero commits) — nothing to stamp */ }
   const slug = projectDir.split("/").pop()?.replace(/[^a-zA-Z0-9._-]/g, "-").toLowerCase() || "project";
   await prepareAdapters(detectAdaptersForProject(projectDir), { logger });
   const planRoot = join(karajanHome, PLANS_DIR, slug);

package/src/review/one-shot-review.js

@@ -0,0 +1,85 @@
+/**
+ * One-shot cross-AI review (ENV-B1, KJC-TSK-0637) — the v4 primitive.
+ *
+ * The HOST agent (Claude Code, Codex) orchestrates the work; Karajan
+ * routes the review to a DIFFERENT AI and records the verdict tied to
+ * the exact diff (verdict-store). No cross-AI reviewer available is an
+ * error, never a silent fallback to the host: without a second pair of
+ * eyes there is no verdict, and without a verdict the pre-commit gate
+ * (ENV-C) keeps the commit out.
+ */
+import { createAgent } from "../agents/index.js";
+import { resolveRole } from "../config/role-resolver.js";
+import { buildReviewerPrompt } from "../prompts/reviewer.js";
+import { resolveReviewProfile } from "./profiles.js";
+import { parseMaybeJsonString } from "./parser.js";
+import { detectAvailableAgents, detectHostAgent } from "../utils/agent-detect.js";
+import { saveVerdict } from "./verdict-store.js";
+
+// Cross-AI preference when the configured reviewer IS the host.
+const CROSS_ORDER = ["codex", "claude", "gemini", "opencode", "aider"];
+
+/**
+ * Pick a reviewer that is NOT the host agent.
+ * @returns {Promise<string|null>} provider name, or null if none exists.
+ */
+export async function pickCrossReviewer({ config, hostAgent, detectAgents = detectAvailableAgents }) {
+  const configured = resolveRole(config, "reviewer").provider;
+  if (configured && configured !== hostAgent) return configured;
+
+  const agents = await detectAgents();
+  const candidates = agents
+    .filter((a) => a.available && a.name !== hostAgent)
+    .map((a) => a.name);
+  return CROSS_ORDER.find((name) => candidates.includes(name)) || candidates[0] || null;
+}
+
+/**
+ * Review a raw diff with a cross-AI reviewer and persist the verdict.
+ * @returns {Promise<object>} the stored verdict record.
+ */
+export async function runOneShotReview({
+  diff, task, config, logger, projectDir,
+  hostAgent = detectHostAgent(),
+  createAgentFn = createAgent,
+  detectAgents = detectAvailableAgents,
+}) {
+  if (!diff || !diff.trim()) {
+    throw new Error("nothing to review — the diff is empty (stage your changes or pass --range)");
+  }
+
+  const reviewer = await pickCrossReviewer({ config, hostAgent, detectAgents });
+  if (!reviewer) {
+    throw new Error(
+      `cross-AI review requires an agent other than the host (${hostAgent || "unknown"}) — install codex, claude or another supported CLI`
+    );
+  }
+
+  const { rules } = await resolveReviewProfile({ mode: "standard", projectDir });
+  const prompt = await buildReviewerPrompt({
+    task: task || "Review the following diff for correctness, security and maintainability.",
+    diff, reviewRules: rules, mode: "standard", provider: reviewer, projectDir,
+  });
+
+  logger?.info?.(`kj review: host=${hostAgent || "none"} → reviewer=${reviewer} (cross-AI)`);
+  const agent = createAgentFn(reviewer, config, logger);
+  const result = await agent.reviewTask({ prompt, role: "reviewer" });
+  if (!result?.ok) {
+    throw new Error(`reviewer ${reviewer} failed: ${result?.error || "no output"}`);
+  }
+
+  const parsed = parseMaybeJsonString(result.output);
+  if (!parsed || typeof parsed.approved !== "boolean") {
+    throw new Error(`reviewer ${reviewer} returned no parseable verdict`);
+  }
+
+  return saveVerdict(projectDir, diff, {
+    verdict: parsed.approved ? "approved" : "rejected",
+    reviewer,
+    host: hostAgent || null,
+    issues: parsed.blocking_issues || [],
+    suggestions: parsed.non_blocking_suggestions || [],
+    summary: parsed.summary || parsed.raw_summary || "",
+    confidence: parsed.confidence ?? null,
+  });
+}

package/src/review/verdict-store.js

@@ -0,0 +1,87 @@
+/**
+ * Verdict store (ENV-B1, KJC-TSK-0637) — persists cross-AI review verdicts
+ * keyed by the sha256 of the RAW diff they reviewed.
+ *
+ * The hash is the contract: a verdict only counts for byte-identical
+ * content, so any change after the review voids it and forces a new one
+ * (resolve-until-pass by construction). The pre-commit hook (ENV-C)
+ * calls checkVerdict() with the staged diff to decide whether the
+ * commit may enter. Diffs must be raw git output — never rtk-compressed
+ * (KJC-BUG-0115).
+ */
+import crypto from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { runCommand } from "../utils/process.js";
+
+const STORE_DIR = path.join(".karajan", "reviews");
+
+export function diffHash(diff) {
+  // trimEnd: runners differ on the final newline (execa strips it, raw
+  // git keeps it) — trailing whitespace must not void a verdict.
+  return crypto.createHash("sha256").update(diff.trimEnd(), "utf8").digest("hex");
+}
+
+function verdictPath(projectDir, hash) {
+  return path.join(projectDir, STORE_DIR, `${hash}.json`);
+}
+
+export async function saveVerdict(projectDir, diff, verdict) {
+  const hash = diffHash(diff);
+  const record = {
+    ...verdict,
+    diffHash: hash,
+    timestamp: new Date().toISOString(),
+  };
+  const file = verdictPath(projectDir, hash);
+  await fs.mkdir(path.dirname(file), { recursive: true });
+  await fs.writeFile(file, `${JSON.stringify(record, null, 2)}\n`);
+  return record;
+}
+
+export async function loadVerdict(projectDir, hash) {
+  try {
+    return JSON.parse(await fs.readFile(verdictPath(projectDir, hash), "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * ENV-F1 (KJC-TSK-0643): headless pipeline sessions call this after staging
+ * and before committing. Their reviewer ALREADY cross-AI-reviewed the work,
+ * so the verdict is recorded for the staged diff and the v4 pre-commit gate
+ * accepts the pipeline's commit. No gate marker → no-op (zero overhead for
+ * repos that never opted in). Raw git only — never a wrapped runner
+ * (KJC-BUG-0115).
+ * @returns {Promise<{stamped: boolean}>}
+ */
+export async function stampStagedVerdict({ projectDir, reviewer, summary = "" }) {
+  const dir = projectDir || process.cwd();
+  try {
+    await fs.access(path.join(dir, ".karajan", "review-gate"));
+  } catch {
+    return { stamped: false };
+  }
+  const res = await runCommand("git", ["diff", "--cached"], { cwd: dir });
+  if (res.exitCode !== 0 || !res.stdout?.trim()) return { stamped: false };
+  await saveVerdict(dir, res.stdout, {
+    verdict: "approved", reviewer, host: "kj-pipeline", issues: [], summary,
+  });
+  return { stamped: true };
+}
+
+/**
+ * Is there an APPROVED verdict for exactly this diff?
+ * @returns {Promise<{ok: boolean, verdict?: object, reason?: string}>}
+ */
+export async function checkVerdict(projectDir, diff) {
+  const verdict = await loadVerdict(projectDir, diffHash(diff));
+  if (!verdict) {
+    return { ok: false, reason: "no verdict recorded for the current diff — run `kj review`" };
+  }
+  if (verdict.verdict !== "approved") {
+    return { ok: false, verdict, reason: `review was rejected by ${verdict.reviewer} — fix the issues and run \`kj review\` again` };
+  }
+  return { ok: true, verdict };
+}

package/src/roles/commiter-role.js

@@ -1,4 +1,5 @@
 import { BaseRole } from "./base-role.js";
+import { stampStagedVerdict } from "../review/verdict-store.js";
 import {
   ensureGitRepo,
   currentBranch,
@@ -57,7 +58,15 @@ export class CommiterRole extends BaseRole {
     }
 
     const msg = commitMessage || buildCommitMessage(task);
-    await commitAll(msg);
+    // ENV-F1 (KJC-TSK-0643): CommiterRole runs after the HU review passed —
+    // stamp the pipeline's verdict so the v4 gate accepts this commit.
+    await commitAll(msg, null, {
+      beforeCommit: () => stampStagedVerdict({
+        projectDir: this.config?.projectDir || process.cwd(),
+        reviewer: this.config?.reviewer || "pipeline-reviewer",
+        summary: "kj pipeline (commiter role): review passed",
+      }),
+    });
     const commitHash = await revParse("HEAD");
 
     // KJC-BUG-0112: no `origin` remote (quickstart scenario) → skip

package/src/utils/git.js

@@ -229,11 +229,15 @@ function isNothingToCommit(message) {
   return NOTHING_TO_COMMIT_PATTERNS.some((re) => re.test(m));
 }
 
-export async function commitAll(message, cwd = null) {
+export async function commitAll(message, cwd = null, { beforeCommit = null } = {}) {
   const opts = cwd ? { cwd } : {};
   await runGit(["add", "-A"], opts);
   const changed = await hasChanges(cwd);
   if (!changed) return { committed: false };
+  // ENV-F1 (KJC-TSK-0643): runs between staging and committing — the only
+  // window where the staged diff is exactly what the commit will contain
+  // (used to stamp the pipeline's review verdict for the v4 gate).
+  if (beforeCommit) await beforeCommit();
   try {
     await runGit(["commit", "-m", message], opts);
   } catch (err) {

package/src/utils/role-assigner.js

@@ -15,7 +15,13 @@ const CAPABILITY_TIERS = {
 // Role requirements: what capability level is ideal for each role
 const ROLE_PREFERENCES = {
   brain: { minTier: 4, prefer: "claude", description: "Karajan Brain (orchestrator)" },
-  solomon: { minTier: 3, prefer: "gemini", description: "Solomon (judge/arbiter)" },
+  // KJC-BUG-0113: Solomon preferred gemini, but Google retired the Gemini
+  // Code Assist CLI for individuals — a binary that answers --version yet
+  // dies with IneligibleTierError on every real call. Any machine with the
+  // stale CLI on PATH got a judge that could never rule. Claude matches
+  // the brain default; diversifyReviewer still picks a different agent
+  // when more than one healthy option exists.
+  solomon: { minTier: 3, prefer: "claude", description: "Solomon (judge/arbiter)" },
   coder: { minTier: 2, prefer: "claude", description: "Coder" },
   reviewer: { minTier: 3, prefer: "codex", description: "Reviewer" },
   planner: { minTier: 4, prefer: "claude", description: "Planner" },