karajan-code 4.0.0 → 4.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "karajan-code",
-  "version": "4.0.0",
+  "version": "4.1.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

@@ -27,13 +27,13 @@ export const META_COMMANDS = ["advanced", "help"];
  * so a newly-registered command can never silently vanish from `kj advanced`.
  */
 export const ADVANCED_GROUPS = [
-  { title: "Pipeline (piezas sueltas)", commands: ["autorun", "code", "review", "scan"] },
-  { title: "Análisis pre-run", commands: ["discover", "triage", "researcher", "architect", "onboard"] },
+  { title: "Pipeline (piezas sueltas)", commands: ["autorun", "code", "review", "solomon", "agent", "scan"] },
+  { title: "Análisis pre-run", commands: ["discover", "triage", "researcher", "architect", "onboard", "brief"] },
   { 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", "env"] },
-  { title: "Mantenimiento", commands: ["clean", "sync", "telemetry"] },
+  { title: "Mantenimiento", commands: ["clean", "sync", "telemetry", "report-issue"] },
 ];
 
 /** Flat set of every advanced command name (for fast lookup / filtering). */

package/src/cli/register-meta.js

@@ -19,7 +19,9 @@ 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 { envInstallCommand, briefCommand } from "../commands/env.js";
+import { agentRunCommand } from "../commands/agent-run.js";
+import { reportIssueCommand } from "../commands/report-issue.js";
 import { formatAdvancedIndex } from "../commands/advanced.js";
 import { withConfig } from "./_shared.js";
 
@@ -126,8 +128,8 @@ export function registerMeta(program, { pkgVersion }) {
   // 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")
+    .description("Install/refresh the Karajan playbook for any host agent (CLAUDE.md, AGENTS.md, GEMINI.md)")
+    .option("--target <target>", "claude | codex | gemini | all", "all")
     .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 }) => {
@@ -135,6 +137,45 @@ export function registerMeta(program, { pkgVersion }) {
       });
     });
 
+  // AB-D (KJC-TSK-0654): the brain's inter-agent bus.
+  const agentCmd = program.command("agent").description("Delegate work to another AI agent (the brain's bus)");
+  agentCmd.command("run <agent> <task>")
+    .description("Run a task on the named agent and print its output (exit 0/1)")
+    .option("--json", "Machine-readable output: {ok, agent, output, usage}")
+    .option("--timeout-minutes <n>", "Hard timeout for the delegated task")
+    .action(async (agent, task, flags) => {
+      await withConfig(pkgVersion, "agent-run", flags, async ({ config, logger }) => {
+        await agentRunCommand({ agent, task, config, logger, flags });
+      });
+    });
+
+  // AB-F (KJC-TSK-0655): self-healing — the brain files kj frictions upstream.
+  program
+    .command("report-issue")
+    .description("Report a kj bug/friction to the public repo (sanitized; publishing needs --publish)")
+    .requiredOption("--title <text>", "One-line summary")
+    .option("--description <text>", "What happened and what you expected")
+    .option("--command <cmd>", "The kj command involved")
+    .option("--error <text>", "The error output (it will be sanitized)")
+    .option("--publish", "Create the issue via the gh CLI (confirm with your user first)")
+    .option("--force", "Skip the similar-issues check")
+    .option("--json", "Machine-readable output")
+    .action(async (flags) => {
+      await reportIssueCommand({ logger: console, flags });
+    });
+
+  // AB-C (KJC-TSK-0652): role briefs for the brain (any host agent).
+  program
+    .command("brief")
+    .description("Show the distilled method of a pipeline role (for the host agent to execute)")
+    .argument("[role]", "triage | planner | researcher | architect | tester | security | audit")
+    .option("--json", "Machine-readable output")
+    .action(async (role, flags) => {
+      await withConfig(pkgVersion, "brief", flags, async ({ config }) => {
+        briefCommand({ config, flags, role });
+      });
+    });
+
   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")

package/src/cli/register-pipeline.js

@@ -3,6 +3,7 @@ import { ollamaStartCommand, ollamaStopCommand, ollamaStatusCommand, ollamaPullC
 import { configCommand } from "../commands/config.js";
 import { codeCommand } from "../commands/code.js";
 import { reviewCommand } from "../commands/review.js";
+import { reviewGateCommand, solomonCommand } from "../commands/review-gate.js";
 import { scanCommand } from "../commands/scan.js";
 import { installToolsCommand } from "../commands/install-tools.js";
 import { doctorCommand } from "../commands/doctor.js";
@@ -31,6 +32,7 @@ export function registerPipeline(program, { pkgVersion }) {
     .option("--no-squeezr", "Skip the Squeezr auto-install (context compression). Karajan still runs but burns more tokens")
     .option("--no-qmd", "Skip the QMD auto-install + collection registration (semantic wiki over docs/, .reviews/ and plans/)")
     .option("--no-harden", "Skip the quality harness (git hooks, lint/commit config, CI gates, agent guidelines)")
+    .option("--json", "Emit a machine-readable summary of what init did (AB-B: for host agents)")
     .action(async (flags) => {
       await withConfig(pkgVersion, "init", flags, async ({ config: _config, logger }) => {
         await initCommand({ logger, flags });
@@ -181,6 +183,18 @@ export function registerPipeline(program, { pkgVersion }) {
       });
     });
 
+  // AB-E (KJC-TSK-0651): third-AI arbitration for the v4 environment.
+  program
+    .command("solomon")
+    .description("Ask a third AI to arbitrate a rejected review verdict (brain ≠ reviewer ≠ solomon)")
+    .requiredOption("--position <text>", "Why the brain disagrees with the reviewer")
+    .option("--range <range>", "Arbitrate a git range instead of the staged diff")
+    .action(async (flags) => {
+      await withConfig(pkgVersion, "solomon", flags, async ({ config, logger }) => {
+        await solomonCommand({ config, logger, flags });
+      });
+    });
+
   program
     .command("review")
     .description("Run only reviewer (--staged/--check: v4 cross-AI gate with recorded verdict)")
@@ -198,7 +212,6 @@ export function registerPipeline(program, { pkgVersion }) {
         // 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;
         }

package/src/commands/agent-run.js

@@ -0,0 +1,63 @@
+/**
+ * `kj agent run <agent> "<task>"` (AB-D, KJC-TSK-0654) — the brain's
+ * inter-agent bus. The host agent decides WHO does WHAT; kj provides the
+ * plumbing it shouldn't have to fight: binary detection, subprocess
+ * workarounds (CLAUDECODE strip, stdin, silence timeouts), usage capture.
+ * The brain reads the output and decides — kj never interprets it.
+ */
+import { createAgent, getAvailableAgents } from "../agents/index.js";
+import { detectAvailableAgents } from "../utils/agent-detect.js";
+
+export async function agentRunCommand({ agent, task, config = {}, logger = null, flags = {} }) {
+  if (!task || !task.trim()) {
+    throw new Error("kj agent run requires a task: kj agent run <agent> \"<task>\"");
+  }
+  const known = getAvailableAgents().map((a) => a.name);
+  const detected = await detectAvailableAgents();
+  const up = detected.filter((a) => a.available).map((a) => a.name).join(", ") || "none";
+  if (!known.includes(agent)) {
+    throw new Error(`unknown agent "${agent}" — supported: ${known.join(", ")}; available on this machine: ${up}`);
+  }
+  const entry = detected.find((a) => a.name === agent);
+  if (!entry?.available) {
+    throw new Error(`agent "${agent}" is not available on this machine (available: ${up}) — install its CLI or pick another`);
+  }
+
+  let timeoutMs;
+  if (flags.timeoutMinutes !== undefined) {
+    const minutes = Number(flags.timeoutMinutes);
+    if (!Number.isFinite(minutes) || minutes <= 0) {
+      throw new Error(`--timeout-minutes must be a positive number, got "${flags.timeoutMinutes}"`);
+    }
+    timeoutMs = minutes * 60000;
+  }
+
+  // --json must emit ONLY the serialized result — no informational lines,
+  // and a crash of the delegated subprocess still yields one JSON payload.
+  if (!flags.json) logger?.info?.(`kj agent run: delegating to ${agent}`);
+  const instance = createAgent(agent, config, logger);
+  let result;
+  try {
+    result = await instance.runTask({ prompt: task, role: "delegate", timeoutMs });
+  } catch (err) {
+    result = { ok: false, output: "", error: err.message };
+  }
+
+  const res = {
+    ok: Boolean(result?.ok),
+    agent,
+    output: result?.output || "",
+    error: result?.error || null,
+    usage: result?.tokens_out != null
+      ? { tokens_in: result.tokens_in ?? null, tokens_out: result.tokens_out, cached_tokens: result.cached_tokens ?? null }
+      : null,
+  };
+  if (flags.json) {
+    console.log(JSON.stringify(res));
+  } else {
+    if (res.output) console.log(res.output);
+    if (!res.ok && res.error) console.error(res.error);
+  }
+  process.exitCode = res.ok ? 0 : 1;
+  return res;
+}

package/src/commands/env.js

@@ -5,6 +5,7 @@
  * has no RAG index yet, build it (default ON, `--no-rag` opts out).
  */
 import { installPlaybook } from "../environment/playbook.js";
+import { renderBrief, listBriefs } from "../environment/briefs.js";
 import { openVecStore, projectSlug, getLastIndexedCommit } from "../rag/vec-store.js";
 import { ragIndexCommand } from "./rag.js";
 
@@ -14,10 +15,28 @@ function hasRagIndex(config, projectDir) {
   finally { db.close(); }
 }
 
+/**
+ * `kj brief [role]` (AB-C, KJC-TSK-0652) — the distilled method of a role,
+ * for the brain to execute or delegate. No role → list them.
+ */
+export function briefCommand({ config = null, flags = {}, role = null }) {
+  if (!role) {
+    const list = listBriefs();
+    if (flags.json) { console.log(JSON.stringify(list, null, 2)); return list; }
+    console.log("Available role briefs (kj brief <role>):");
+    for (const { role: r, purpose } of list) console.log(`  ${r.padEnd(11)} ${purpose}`);
+    return list;
+  }
+  const text = renderBrief(role, config || {});
+  if (flags.json) { console.log(JSON.stringify({ role, brief: text })); return { role, brief: text }; }
+  console.log(text);
+  return { role, brief: text };
+}
+
 export async function envInstallCommand({ config = null, logger = null, flags = {} }) {
   const projectDir = config?.projectDir || process.cwd();
   const result = await installPlaybook({
-    projectDir, target: flags.target || "both",
+    projectDir, target: flags.target || "all",
     stateBackend: config?.state_backend || "hu-board",
   });
   console.log(`✓ Karajan playbook installed in: ${result.files.join(", ")}`);

package/src/commands/harden.js

@@ -9,6 +9,7 @@
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 
+import { loadConfig } from "../config.js";
 import { compareHarden, formatAdvisoryReport } from "../harden/advisory.js";
 import { interactiveHarden } from "../harden/interactive.js";
 import { createWizard, isTTY } from "../utils/wizard.js";
@@ -120,9 +121,16 @@ export async function hardenCommand({
 
   const roots = detectStackRoots(projectDir, { only: onlyDirs, exclude: excludeDirs });
   const cmds = await resolveCmds(projectDir, roots[0]?.language ?? null);
+  // KJC-TSK-0648: branch-first guard — the base branch only moves via PR.
+  // Resolved from the project's kj config (default "main"); best-effort so
+  // harden keeps working on repos that never ran kj init.
+  let baseBranch = "main";
+  try {
+    baseBranch = (await loadConfig(projectDir))?.base_branch || "main";
+  } catch { /* no kj config — default stands */ }
   let result;
   try {
-    result = await installHooks({ projectDir, profile, cmds, dryRun });
+    result = await installHooks({ projectDir, profile, cmds, dryRun, baseBranch });
   } catch (err) {
     if (json) logger.info?.(JSON.stringify({ ok: false, error: err.message }));
     else logger.error?.(`kj harden: ${err.message}`);

package/src/commands/init.js

@@ -736,11 +736,23 @@ export async function resolveConfigScope({ flags, interactive }) {
 }
 
 export async function initCommand({ logger, flags = {} }) {
+  // AB-B (KJC-TSK-0656): with --json, stdout is a machine contract — every
+  // human log moves to stderr so the only stdout line is the summary object.
+  if (flags.json) {
+    const toStderr = (...args) => console.error(...args);
+    logger = { ...logger, info: toStderr, warn: toStderr, error: toStderr };
+  }
   const karajanHome = getKarajanHome();
   await ensureDir(karajanHome);
   logger.info(`Ensured ${karajanHome} exists`);
 
   const interactive = flags.noInteractive !== true && isTTY();
+  // AB-B (KJC-TSK-0656): the agent is the UI. When there is no TTY the
+  // wizard silently used defaults — say so, so a brain (or a CI log
+  // reader) knows WHY nothing was asked and which flags override what.
+  if (!interactive && flags.noInteractive !== true) {
+    logger.info("No TTY detected — running non-interactive with defaults (pass flags to override; see kj init --help)");
+  }
   const { configPath, scope } = await resolveConfigScope({ flags, interactive });
   logger.info(`Config scope: ${scope} → ${configPath}`);
   const karajanDir = path.join(process.cwd(), ".karajan");
@@ -900,6 +912,16 @@ export async function initCommand({ logger, flags = {} }) {
     sendTelemetryEvent("install", { version }, config).catch(() => {});
   } catch { /* non-blocking */ }
 
+  // AB-B (KJC-TSK-0656): machine contract for brains — one JSON object with
+  // what init actually did, instead of parsing the human log.
+  if (flags.json) {
+    console.log(JSON.stringify({
+      ok: true, configPath, scope, interactive,
+      skipped: ["ollama", "rtk", "squeezr", "qmd", "harden"].filter((t) => flags[t] === false),
+    }));
+    return;
+  }
+
   // Clear close so a first-time user knows setup finished and what to do next,
   // instead of being left at the end of a wall of detection logs (KJC-BUG-0088).
   logger.info("");

package/src/commands/report-issue.js

@@ -0,0 +1,77 @@
+/**
+ * `kj report-issue` (AB-F 2/2, KJC-TSK-0655) — the brain files kj
+ * frictions to the public repo. Default output is a sanitized preview
+ * plus a prefilled new-issue URL: publishing stays a human decision.
+ * `--publish` uses the gh CLI; the playbook orders the brain to confirm
+ * with its user before passing it.
+ */
+import os from "node:os";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { resolve } from "node:path";
+import { runCommand } from "../utils/process.js";
+import { composeIssue, findSimilarIssues, newIssueUrl, REPO } from "../environment/issue-report.js";
+
+function kjVersion() {
+  try {
+    const pkg = resolve(fileURLToPath(import.meta.url), "../../../package.json");
+    return JSON.parse(readFileSync(pkg, "utf8")).version;
+  } catch { return "unknown"; }
+}
+
+export async function reportIssueCommand({ logger: _logger = null, flags = {}, deps = {} }) {
+  if (!flags.title || !flags.title.trim()) {
+    throw new Error("kj report-issue requires --title \"<one-line summary>\"");
+  }
+  const { fetchFn = globalThis.fetch, runCmd = runCommand } = deps;
+
+  const { title, body } = composeIssue({
+    title: flags.title,
+    description: flags.description || "",
+    command: flags.command || "",
+    error: flags.error || "",
+    env: { kjVersion: kjVersion(), nodeVersion: process.version, platform: `${os.platform()}-${os.arch()}` },
+  });
+  const url = newIssueUrl({ title, body });
+
+  const similar = await findSimilarIssues(title, { fetchFn });
+  if (similar.length > 0 && !flags.force) {
+    const res = { published: false, title, body, similar, url };
+    if (flags.json) console.log(JSON.stringify(res));
+    else {
+      console.log(`✗ ${similar.length} similar open issue(s) — comment there instead of duplicating (or re-run with --force):`);
+      for (const s of similar) console.log(`  #${s.number} ${s.title}\n     ${s.html_url}`);
+    }
+    process.exitCode = 1;
+    return res;
+  }
+
+  if (flags.publish) {
+    try {
+      const gh = await runCmd("gh", ["issue", "create", "--repo", REPO, "--title", title, "--body", body]);
+      if (gh.exitCode !== 0) throw new Error(gh.stderr?.trim() || `gh exited ${gh.exitCode}`);
+      const issueUrl = gh.stdout.trim().split("\n").pop();
+      const res = { published: true, title, url: issueUrl, similar };
+      if (flags.json) console.log(JSON.stringify(res));
+      else console.log(`✓ issue published: ${issueUrl}`);
+      process.exitCode = 0;
+      return res;
+    } catch (err) {
+      const res = { published: false, title, body, similar, url, error: err.message };
+      if (flags.json) console.log(JSON.stringify(res));
+      else console.log(`✗ could not publish via gh (${err.message}) — open it manually:\n${url}`);
+      process.exitCode = 1;
+      return res;
+    }
+  }
+
+  const res = { published: false, title, body, similar, url };
+  if (flags.json) console.log(JSON.stringify(res));
+  else {
+    console.log(`--- issue preview (sanitized) ---\n# ${title}\n\n${body}\n---`);
+    console.log(`Open (and edit) it here:\n${url}`);
+    console.log("Or publish directly with --publish (requires gh; confirm with your user first).");
+  }
+  process.exitCode = 0;
+  return res;
+}

package/src/commands/review-gate.js

@@ -8,6 +8,7 @@
 import { runCommand } from "../utils/process.js";
 import { checkVerdict } from "../review/verdict-store.js";
 import { runOneShotReview } from "../review/one-shot-review.js";
+import { runSolomonArbitration } from "../review/solomon-arbitration.js";
 
 // Raw git always — never a wrapped/compressing runner (KJC-BUG-0115).
 async function rawDiff(range) {
@@ -34,6 +35,25 @@ function printVerdict(record) {
   console.log("Fix the issues and run `kj review --staged` again — the verdict is tied to the exact diff.");
 }
 
+/**
+ * `kj solomon --position "<why>"` (AB-E, KJC-TSK-0651) — the brain asks a
+ * third AI to arbitrate a rejected verdict it disagrees with. Exit 0 =
+ * approve (gate opens), 1 = reject (obey the reviewer and fix).
+ */
+export async function solomonCommand({ config, logger = null, flags = {} }) {
+  const projectDir = config?.projectDir || process.cwd();
+  const diff = await rawDiff(flags.range);
+  const res = await runSolomonArbitration({ diff, position: flags.position, config, logger, projectDir });
+  if (res.ruling === "approve") {
+    console.log(`⚖ Solomon (${res.solomon}) rules for the brain — verdict recorded, the gate is open.`);
+  } else {
+    console.log(`⚖ Solomon${res.solomon ? ` (${res.solomon})` : ""} rules for the reviewer — obey and fix:`);
+  }
+  if (res.reasoning) console.log(`  ${res.reasoning}`);
+  process.exitCode = res.ruling === "approve" ? 0 : 1;
+  return res;
+}
+
 export async function reviewGateCommand({ config, logger = null, flags = {} }) {
   const projectDir = config?.projectDir || process.cwd();
 

package/src/environment/briefs.js

@@ -0,0 +1,109 @@
+/**
+ * Role briefs (AB-C, KJC-TSK-0652; outcome-first rewrite AB-C2,
+ * KJC-TSK-0653) — the method of each role, exposed to the brain via
+ * `kj brief <role>`.
+ *
+ * Format is Mission + Invariants + Deliverable, never step scripts:
+ * frontier models choose better paths than a script would force, but they
+ * need the hard limits explicit. The real guarantee lives in the git
+ * gates, not in this text. Subprocess prompts stay in headless.
+ */
+
+const brief = (title, mission, invariants, deliverable) => [
+  `# ${title} brief`, "",
+  `Mission: ${mission}`, "",
+  "Invariants:",
+  ...invariants.map((i) => `- ${i}`), "",
+  `Deliverable: ${deliverable}`,
+].join("\n");
+
+const B = {
+  triage: {
+    purpose: "Size the task before touching anything",
+    render: () => brief("Triage",
+      "before any code exists, the task has a type (sw|infra|doc|add-tests|refactor), an honest size, its risk surfaces named (auth, persistence, external I/O, money, PII), and a DONE-statement that is falsifiable.",
+      [
+        "The RAG answers before you assume (`kj rag query`) — never size from guesses.",
+        "A task too big for one ~150-net-line PR is split into HUs BEFORE coding starts.",
+      ],
+      "type, size, risks, done-statement — or the HU split."),
+  },
+  planner: {
+    purpose: "Turn the task into an ordered, committable plan",
+    render: () => brief("Planner",
+      "the smallest ordered plan whose steps each fit one commit, name their files, and reach the done-statement — with an explicit out-of-scope list.",
+      [
+        "Behavior changes carry their test in the same step.",
+        "Data-model or API changes never share a step with anything else.",
+        "No PR beyond ~150 net lines — partition upfront, not at the gate.",
+      ],
+      "numbered-free plan: steps {description, files}, risks, out-of-scope."),
+  },
+  researcher: {
+    purpose: "Ground the task in how the codebase actually works",
+    render: () => brief("Researcher",
+      "the design starts from how this codebase actually does things: the existing pattern for this kind of change is found and mimicked, the load-bearing files and the tests that pin them are known.",
+      [
+        "Facts carry file:line references — a claim without one is a guess.",
+        "Unknowns are listed explicitly, never papered over.",
+      ],
+      "grounded facts with references + the open unknowns."),
+  },
+  architect: {
+    purpose: "Decide structure before code when the change is cross-cutting",
+    render: () => brief("Architect",
+      "for medium/complex changes, one design is chosen over named alternatives, existing ADRs and module boundaries are respected, and any data-model/API change has a migration and compatibility story.",
+      [
+        "Check the ADRs before deciding — never against an accepted one.",
+        "Prefer the design that deletes code over the one that adds layers.",
+      ],
+      "chosen design, discarded alternatives with reasons, affected boundaries."),
+  },
+  tester: {
+    purpose: "Prove the change does what DONE says",
+    render: (config) => {
+      const tdd = config?.development?.methodology !== "standard";
+      return brief("Tester",
+        "every behavior change is pinned by a test that fails without it, sad paths included (invalid input, empty state, boundaries), and the FULL suite is green.",
+        [
+          ...(tdd ? ["TDD is ON: the failing test exists FIRST, then the code."] : []),
+          "The suite is never left red, and never goes green by deleting or skipping tests.",
+        ],
+        "green suite + the list of new/changed tests and what each one pins.");
+    },
+  },
+  security: {
+    purpose: "The security pass the brain absorbs — non-negotiable",
+    render: () => brief("Security",
+      "when you finish, no user-controlled data reaches HTML, shell, SQL or file paths unsanitized; no secret, key or credential lives in code, config, logs or commits; and every new endpoint/action checks identity AND permission.",
+      [
+        "These findings are never overridable — not even by Solomon arbitration.",
+        "PII is never logged; new dependencies need a reason and a pinned version.",
+      ],
+      "findings with severity, category and file:line — or an explicit 'no security surface touched'."),
+  },
+  audit: {
+    purpose: "Final look before shipping — does the whole thing hold?",
+    render: () => brief("Audit",
+      "the done-statement from triage is literally true, the diff carries no debug leftovers or card-less TODOs, user-visible behavior changes have their minimal doc, and suite + lint + review gate are verified green.",
+      [
+        "Verified means you ran it — never assumed from an earlier state.",
+        "There is no 'ship with caveats': it ships or it has a must-fix list.",
+      ],
+      "SHIP, or the concrete must-fix list."),
+  },
+};
+
+export const BRIEF_ROLES = Object.keys(B);
+
+export function listBriefs() {
+  return BRIEF_ROLES.map((role) => ({ role, purpose: B[role].purpose }));
+}
+
+export function renderBrief(role, config = {}) {
+  const entry = B[role];
+  if (!entry) {
+    throw new Error(`unknown role "${role}" — available: ${BRIEF_ROLES.join(", ")}`);
+  }
+  return entry.render(config);
+}

package/src/environment/issue-report.js

@@ -0,0 +1,72 @@
+/**
+ * Issue reporting core (AB-F, KJC-TSK-0655) — the self-healing loop: any
+ * user's brain diagnoses a kj friction and reports it to the public repo,
+ * so field feedback reaches the maintainer's board without a human relay.
+ *
+ * A public issue is a privacy boundary. sanitize() strips home paths,
+ * usernames and emails; the composer only ever includes what the brain
+ * explicitly passed (command, error, description) plus kj/node/platform
+ * metadata — never project code.
+ */
+
+export const REPO = "manufosela/karajan-code";
+
+export function sanitize(text) {
+  return String(text || "")
+    // any /home/<user>/ or /Users/<user>/ prefix collapses to ~/
+    .replaceAll(/\/(?:home|Users)\/[^/\s]+/g, "~")
+    // emails never belong in a public issue
+    .replaceAll(/[\w.+-]+@[\w-]+\.[\w.]+/g, "[redacted-email]");
+}
+
+export function composeIssue({ title, description = "", command = "", error = "", env = {} }) {
+  const body = [
+    sanitize(description),
+    command ? `\n**Command:** \`${sanitize(command)}\`` : "",
+    error ? `\n**Error:**\n\`\`\`\n${sanitize(error)}\n\`\`\`` : "",
+    "\n**Environment:**",
+    `- kj ${env.kjVersion || "unknown"}`,
+    `- node ${env.nodeVersion || "unknown"}`,
+    `- ${env.platform || "unknown"}`,
+    "\n---",
+    "_Reported via `kj report-issue` (sanitized: no project code, paths or personal data)._",
+  ].filter(Boolean).join("\n");
+  return { title: sanitize(title), body };
+}
+
+const STOPWORDS = new Set(["the", "a", "an", "is", "are", "from", "with", "for", "and", "not", "kj", "karajan"]);
+
+function meaningfulWords(title) {
+  return title.toLowerCase().split(/[^a-z0-9-]+/)
+    .filter((w) => w.length > 3 && !STOPWORDS.has(w));
+}
+
+/**
+ * Look for open issues that share meaningful title words (≥2 overlaps, or
+ * 1 when the title is short). Read-only public API — no auth needed. Any
+ * failure degrades to [] : dedup must never block reporting.
+ */
+export async function findSimilarIssues(title, { fetchFn = globalThis.fetch } = {}) {
+  try {
+    const res = await fetchFn(`https://api.github.com/repos/${REPO}/issues?state=open&per_page=100`, {
+      headers: { accept: "application/vnd.github+json" },
+    });
+    if (!res.ok) return [];
+    const issues = await res.json();
+    const words = meaningfulWords(title);
+    const needed = Math.min(2, Math.max(1, words.length));
+    return issues.filter((issue) => {
+      const theirs = new Set(meaningfulWords(issue.title || ""));
+      const overlap = words.filter((w) => theirs.has(w)).length;
+      return overlap >= needed;
+    }).map(({ number, title: t, html_url }) => ({ number, title: t, html_url }));
+  } catch {
+    return [];
+  }
+}
+
+/** Prefilled new-issue URL — publishing stays a human click by default. */
+export function newIssueUrl({ title, body }) {
+  const params = new URLSearchParams({ title, body });
+  return `https://github.com/${REPO}/issues/new?${params.toString().replaceAll("+", "%20")}`;
+}

package/src/environment/playbook.js

@@ -13,39 +13,56 @@ 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"];
+// AB-A (KJC-TSK-0650): any agent can be the brain. AGENTS.md is the
+// emerging standard (Codex, Cursor and most new CLIs read it); GEMINI.md
+// covers Gemini CLI. "both" is kept as a legacy alias of claude+codex.
+export const PLAYBOOK_TARGETS = ["claude", "codex", "gemini", "both", "all"];
 
-const TARGET_FILES = { claude: ["CLAUDE.md"], codex: ["AGENTS.md"], both: ["CLAUDE.md", "AGENTS.md"] };
+const TARGET_FILES = {
+  claude: ["CLAUDE.md"],
+  codex: ["AGENTS.md"],
+  gemini: ["GEMINI.md"],
+  both: ["CLAUDE.md", "AGENTS.md"],
+  all: ["CLAUDE.md", "AGENTS.md", "GEMINI.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.
+// ENV-D1 (KJC-TSK-0642): the tracking invariant names the CHOSEN state
+// backend — a playbook that says "board or PG" makes the host guess.
 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).",
+  "hu-board": "Every piece of work has a tracked story/bug in the HU Board (`kj board`) before it starts.",
+  "planning-game": "Every piece of work has a tracked card in the Planning Game MCP before it starts (In Progress while you work it).",
 };
 
+// AB-C2 (KJC-TSK-0653): outcome-first — invariants over step scripts.
+// Frontier models choose their own path best; what they need explicit are
+// the limits. The git gates enforce these regardless of what any brain does.
 const playbookBody = (stateBackend) => `# Karajan method (v4)
 
-You are the orchestrator; Karajan governs the method. Follow this on every task:
+You are the orchestrator; Karajan governs. A task is DONE when its
+done-statement is literally true, the full suite is green, and every commit
+carries a cross-AI verdict.
+
+Invariants (the git gates enforce these — they are not suggestions):
+
+- The project RAG answers before you assume: \`kj rag query\` — never guess
+  what the codebase does.
+- ${BACKEND_TRACKING[stateBackend] || BACKEND_TRACKING["hu-board"]}
+- Tests prove behavior: the failing test exists first (TDD), and the suite
+  is never left red.
+- Every diff is reviewed by a DIFFERENT AI before it is committed
+  (\`kj review --staged\`): verdicts bind to the exact diff — change the code
+  and it must be reviewed again. Disagree with a rejection? \`kj solomon\`.
+- Security findings are never overridable — not even by arbitration. You
+  absorb the security role: \`kj brief security\` states what must be true.
+- Branch first: never commit on the base branch — every change reaches it
+  through an atomic PR (~150 net lines, Conventional Commits).
 
-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.
+Commands: \`kj rag query\` · \`kj brief <role>\` (triage, planner, researcher,
+architect, tester, security, audit) · \`kj review --staged\` · \`kj review --check\` ·
+\`kj solomon --position\` · \`kj agent run <agent>\` · \`kj report\` · \`kj check\`
 
-Useful commands: \`kj rag query\` · \`kj review --staged\` · \`kj review --check\` ·
-\`kj report\` · \`kj check\`
+Hit a kj bug or friction? Diagnose it and file it upstream with
+\`kj report-issue\` (sanitized; ask your user before \`--publish\`).
 `;
 
 export function renderPlaybook({ stateBackend = "hu-board" } = {}) {
@@ -56,7 +73,7 @@ export function renderPlaybook({ stateBackend = "hu-board" } = {}) {
  * 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" }) {
+export async function installPlaybook({ projectDir, target = "all", version = "1", stateBackend = "hu-board" }) {
   if (!PLAYBOOK_TARGETS.includes(target)) {
     throw new Error(`unknown target "${target}" — use one of: ${PLAYBOOK_TARGETS.join(", ")}`);
   }

package/src/harden/harden-engine.js

@@ -33,11 +33,25 @@ export async function installHooks({
   profile = "standard",
   cmds = {},
   dryRun = false,
+  baseBranch = null,
 } = {}) {
   if (!isGitRepo(projectDir)) throw new Error(`Not a git repository: ${projectDir}`);
   const hooks = PROFILE_HOOKS[profile];
   if (!hooks) throw new Error(`Unknown harden profile: ${profile}`);
 
+  // KJC-TSK-0645: setting a repo-local hooksPath ECLIPSES the machine's
+  // global hooks dir — personal guards (AI-attribution commit-msg, protected
+  // branch pre-push) would silently stop applying here. Detect the previous
+  // global dir and have every generated hook chain to it. `~` is emitted as
+  // `$HOME` so the committed hook stays portable across machines (the -x
+  // guard silences it where the dir doesn't exist).
+  let globalHooksDir = null;
+  const globalCfg = await runCommand("git", ["config", "--global", "core.hooksPath"], { cwd: projectDir });
+  const rawGlobal = globalCfg.exitCode === 0 ? globalCfg.stdout.trim() : "";
+  if (rawGlobal && rawGlobal !== HOOKS_DIR) {
+    globalHooksDir = rawGlobal.startsWith("~") ? `$HOME${rawGlobal.slice(1)}` : rawGlobal;
+  }
+
   const absHooksDir = join(projectDir, HOOKS_DIR);
   const results = [];
   for (const hook of hooks) {
@@ -47,7 +61,7 @@ export async function installHooks({
       source,
       blockId: `hook:${hook}`,
       version: BLOCK_VERSION,
-      body: hookBody(hook, cmds),
+      body: hookBody(hook, cmds, { globalHooksDir, baseBranch }),
       style: "hash",
     });
     results.push({ hook, target, action });

package/src/harden/hook-templates.js

@@ -21,10 +21,42 @@ export const PROFILE_HOOKS = {
 };
 
 /** Build the managed body for a single hook. */
-export function hookBody(hook, cmds = {}) {
+// KJC-TSK-0645: `core.hooksPath .karajan/hooks` eclipses the user's global
+// hooks dir, silently disabling personal guards. When a previous global dir
+// is known, every generated hook ends by chaining its namesake there —
+// guarded, so machines without it are unaffected.
+function chainToGlobal(hook, globalHooksDir) {
+  if (!globalHooksDir) return [];
+  return [
+    "# Chain the machine's previous global hook (kj harden keeps it active).",
+    `if [ -x "${globalHooksDir}/${hook}" ]; then`,
+    `  "${globalHooksDir}/${hook}" "$@"; rc=$?`,
+    '  [ "$rc" -eq 0 ] || exit "$rc"',
+    "fi",
+  ];
+}
+
+// KJC-TSK-0648: branch-first, enforced. The first external session of the
+// v4 environment committed on local main following literal instructions —
+// the playbook now orders "branch first" and this guard backs it up.
+function baseBranchGuard(baseBranch) {
+  if (!baseBranch) return [];
+  return [
+    "# Branch-first guard — the base branch only moves via PR.",
+    'if [ "$KJ_ALLOW_BASE_COMMIT" != "1" ]; then',
+    '  current_branch=$(git symbolic-ref --short HEAD 2>/dev/null || echo "")',
+    `  if [ "$current_branch" = "${baseBranch}" ]; then`,
+    `    echo 'kj harden: direct commits on ${baseBranch} are not allowed — create a branch and open a PR (KJ_ALLOW_BASE_COMMIT=1 to override)'; exit 1`,
+    "  fi",
+    "fi",
+  ];
+}
+
+export function hookBody(hook, cmds = {}, { globalHooksDir = null, baseBranch = null } = {}) {
+  const chain = chainToGlobal(hook, globalHooksDir);
   switch (hook) {
     case "pre-commit": {
-      const lines = ["# Lint + format the working tree with the project's native tools."];
+      const lines = [...baseBranchGuard(baseBranch), "# Lint + format the working tree with the project's native tools."];
       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)");
@@ -38,7 +70,7 @@ export function hookBody(hook, cmds = {}) {
         "  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");
+      return [...lines, ...chain].join("\n");
     }
     case "commit-msg":
       // Pure POSIX — Conventional Commits header, length cap, AI-attribution.
@@ -52,6 +84,7 @@ export function hookBody(hook, cmds = {}) {
         `if grep -qiE '${AI_ATTRIBUTION}' "$msg_file"; then`,
         "  echo 'kj harden: AI attribution is not allowed in commit messages'; exit 1",
         "fi",
+        ...chain,
       ].join("\n");
     case "pre-push": {
       const lines = [
@@ -64,7 +97,7 @@ export function hookBody(hook, cmds = {}) {
       ];
       if (cmds.test) lines.push(`${cmds.test} || { echo 'kj harden: tests failed'; exit 1; }`);
       else lines.push("# (no test command detected for this stack)");
-      return lines.join("\n");
+      return [...lines, ...chain].join("\n");
     }
     case "post-merge":
       return [
@@ -72,6 +105,7 @@ export function hookBody(hook, cmds = {}) {
         "if command -v kj >/dev/null 2>&1; then",
         "  kj rag index --since auto >/dev/null 2>&1 || true",
         "fi",
+        ...chain,
       ].join("\n");
     default:
       throw new Error(`Unknown hook: ${hook}`);

package/src/prompts/reviewer.js

@@ -52,7 +52,7 @@ export async function buildReviewerPromptLayout({ task, diff, reviewRules, mode,
     section("Only block approval for issues IN THE DIFF that are bugs, security vulnerabilities, or clear violations of the review rules.", STABLE),
     section("Return only one valid JSON object and nothing else.", STABLE),
     section("JSON schema:", STABLE),
-    section('{"approved":boolean,"blocking_issues":[{"id":string,"severity":"critical|high|medium|low","file":string,"line":number,"description":string,"suggested_fix":string}],"non_blocking_suggestions":[string],"summary":string,"confidence":number}', STABLE),
+    section('{"approved":boolean,"blocking_issues":[{"id":string,"severity":"critical|high|medium|low","category":"security|correctness|performance|style|other","file":string,"line":number,"description":string,"suggested_fix":string}],"non_blocking_suggestions":[string],"summary":string,"confidence":number}', STABLE),
     section(serenaEnabled ? SERENA_INSTRUCTIONS : null, STABLE),
     section(rtkSnippet, STABLE),
     section(productContext ? `## Product Context\n${productContext}` : null, STABLE),

package/src/review/solomon-arbitration.js

@@ -0,0 +1,102 @@
+/**
+ * Solomon arbitration (AB-E, KJC-TSK-0651) — when the brain (host agent)
+ * disagrees with the reviewer's verdict, a THIRD AI arbitrates and its
+ * ruling is recorded in the verdict store, tied to the exact diff.
+ *
+ * Hard rules:
+ *  - brain ≠ reviewer ≠ solomon. Two-agent machines get an actionable
+ *    error — self-arbitration would void the whole point.
+ *  - Security issues from the reviewer are NEVER overridable (inherited
+ *    from the pipeline's Solomon): the arbiter is not even consulted.
+ *  - An approve ruling writes an approved verdict (`solomon:<agent>`) for
+ *    the same diff hash, so the pre-commit gate opens structurally; a
+ *    reject keeps it closed. Both record the full conflict for audit.
+ */
+import { createAgent } from "../agents/index.js";
+import { parseMaybeJsonString } from "./parser.js";
+import { detectAvailableAgents, detectHostAgent } from "../utils/agent-detect.js";
+import { diffHash, loadVerdict, saveVerdict } from "./verdict-store.js";
+
+const SECURITY_PATTERN = /injection|xss|csrf|secret|credential|password|token leak|auth(entication|orization)?|crypt|session|sanitiz|traversal|rce\b/i;
+
+// Structured signal first (`category: "security"` — part of the reviewer's
+// JSON schema since AB-E); the free-text pattern stays as a fail-closed net
+// for verdicts recorded before the schema carried categories.
+function isSecurityIssue(issue) {
+  return issue.category === "security"
+    || SECURITY_PATTERN.test(`${issue.id || ""} ${issue.description || ""}`);
+}
+
+export async function pickThirdParty({ config, hostAgent, reviewerAgent, detectAgents = detectAvailableAgents }) {
+  const excluded = new Set([hostAgent, reviewerAgent]);
+  const configured = config?.roles?.solomon?.provider;
+  const agents = await detectAgents();
+  const candidates = agents.filter((a) => a.available && !excluded.has(a.name)).map((a) => a.name);
+  if (configured && candidates.includes(configured)) return configured;
+  return candidates[0] || null;
+}
+
+export async function runSolomonArbitration({
+  diff, position, config, logger, projectDir,
+  hostAgent = detectHostAgent(),
+  createAgentFn = createAgent,
+  detectAgents = detectAvailableAgents,
+}) {
+  if (!position || !position.trim()) {
+    throw new Error("kj solomon requires --position \"<why you disagree with the reviewer>\"");
+  }
+  const verdict = await loadVerdict(projectDir, diffHash(diff));
+  if (!verdict || verdict.verdict !== "rejected") {
+    throw new Error("nothing to arbitrate — there is no rejected verdict for the current diff (run `kj review --staged` first)");
+  }
+
+  // ABSOLUTE RULE: security findings are never overridable.
+  const securityIssues = (verdict.issues || []).filter(isSecurityIssue);
+  if (securityIssues.length > 0) {
+    const record = await saveVerdict(projectDir, diff, {
+      ...verdict,
+      arbitration: { position, ruling: "reject", reasoning: "security issues from the reviewer are never overridable", solomon: null },
+    });
+    return { ruling: "reject", reasoning: "security issues are never overridable — fix them", solomon: null, record };
+  }
+
+  const solomon = await pickThirdParty({ config, hostAgent, reviewerAgent: verdict.reviewer, detectAgents });
+  if (!solomon) {
+    throw new Error(
+      `arbitration requires a third AI distinct from the brain (${hostAgent || "unknown"}) and the reviewer (${verdict.reviewer}) — install a third agent CLI`
+    );
+  }
+
+  const prompt = [
+    "You are Solomon, the neutral arbiter between two AIs in a coding workflow.",
+    "The reviewer REJECTED a diff; the orchestrating brain DISAGREES. Decide who is right.",
+    "Never approve to save time or effort — only if the reviewer's objections are genuinely wrong or immaterial for this diff.",
+    'Return only one JSON object: {"ruling":"approve"|"reject","reasoning":string}. "approve" = the brain is right, the diff may ship as-is. "reject" = the reviewer is right, the brain must fix the issues.',
+    "", "## Reviewer's blocking issues",
+    JSON.stringify(verdict.issues || [], null, 2),
+    "", "## Brain's position", position,
+    "", "## The diff under dispute", diff,
+  ].join("\n");
+
+  logger?.info?.(`kj solomon: brain=${hostAgent || "?"} vs reviewer=${verdict.reviewer} → arbiter=${solomon}`);
+  const agent = createAgentFn(solomon, config, logger);
+  const result = await agent.reviewTask({ prompt, role: "solomon" });
+  if (!result?.ok) throw new Error(`solomon ${solomon} failed: ${result?.error || "no output"}`);
+  const parsed = parseMaybeJsonString(result.output);
+  if (!parsed || !["approve", "reject"].includes(parsed.ruling)) {
+    throw new Error(`solomon ${solomon} returned no parseable ruling`);
+  }
+
+  const arbitration = {
+    position, ruling: parsed.ruling, reasoning: parsed.reasoning || "", solomon,
+    originalVerdict: { reviewer: verdict.reviewer, issues: verdict.issues },
+  };
+  const record = parsed.ruling === "approve"
+    ? await saveVerdict(projectDir, diff, {
+      verdict: "approved", reviewer: `solomon:${solomon}`, host: hostAgent || null,
+      issues: [], summary: `Arbitration overrode ${verdict.reviewer}'s rejection: ${parsed.reasoning || ""}`.trim(), arbitration,
+    })
+    : await saveVerdict(projectDir, diff, { ...verdict, arbitration });
+
+  return { ruling: parsed.ruling, reasoning: parsed.reasoning || "", solomon, record };
+}