karajan-code 3.15.3 → 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.3",
+  "version": "4.0.0",
   "description": "Local multi-agent coding orchestrator with TDD, SonarQube, and code review pipeline",
   "type": "module",
   "license": "AGPL-3.0",

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/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/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) {