karajan-code 3.10.2 → 3.12.0

package/package.json

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

package/scripts/esbuild-sea.config.mjs

@@ -192,6 +192,9 @@ const ragStubPlugin = {
           // reached from \`kj rag install-hooks\`, so it degrades like the rest.
           maybeAutoUpdate: async () => ({ skipped: true }),
           installPostMergeHook: notAvailable,
+          // KJC-BUG-0100 — the doctor rag-hooks check imports this; it throws
+          // here and the check swallows it (degrades to a benign info result).
+          resolveHooksDir: notAvailable,
           default: notAvailable,
         };
       `,

package/scripts/install-binary.sh

@@ -36,17 +36,8 @@ esac
 target="${os}-${arch}"
 case "$target" in
   linux-x64) ;;
-  darwin-arm64)
-    # The macOS standalone binary is not published yet (tracked in
-    # KJC-BUG-0096: the darwin-arm64 SEA build crashes under smoke-test).
-    # Degrade gracefully to the npm install path instead of trying to
-    # download an asset that does not exist.
-    echo "kj-install: the macOS standalone binary is not available yet." >&2
-    echo "kj-install: install with npm instead (requires Node 18+):" >&2
-    echo "  npm install -g karajan-code" >&2
-    exit 0
-    ;;
-  *) die "no prebuilt binary for '$target'. Available: linux-x64. On macOS use npm instead: npm install -g karajan-code" ;;
+  darwin-arm64) ;;
+  *) die "no prebuilt binary for '$target'. Available: linux-x64, darwin-arm64. Use npm instead: npm install -g karajan-code" ;;
 esac
 
 # --- Resolve the download URL for the requested version (or latest). ---

package/src/checks/rag-hooks.js

@@ -0,0 +1,54 @@
+/**
+ * RAG post-merge hook wiring check (KJC-BUG-0100).
+ *
+ * `kj rag install-hooks` used to write the hook into `.git/hooks/post-merge`,
+ * but when a repo is hardened `git config core.hooksPath` points at
+ * `.karajan/hooks` and git ignores `.git/hooks/` entirely — so the RAG index
+ * silently never refreshes after a merge. This check resolves the *effective*
+ * hooks dir and reports whether the post-merge hook there reindexes the RAG.
+ * The pre-run drift check in `kj run` already covers the gap, so a missing
+ * hook is advisory (info), not a failure — it surfaces the state without
+ * nagging every repo that never ran `kj rag install-hooks`.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { STRATEGY } from "./types.js";
+import { resolveHooksDir } from "../rag/auto-update.js";
+
+export function createRagHooksCheck({ projectDir } = {}) {
+  return {
+    name: "rag-hooks",
+    label: "RAG post-merge refresh",
+    strategy: STRATEGY.MANUAL,
+    async detect() {
+      const dir = projectDir || process.cwd();
+      let hooks;
+      try {
+        hooks = await resolveHooksDir(dir);
+      } catch {
+        return { ok: true, severity: "info", detail: "not a git repository — no post-merge hook to wire" };
+      }
+      const target = join(hooks.dir, "post-merge");
+      const wired = existsSync(target) && /kj\s+rag\s+index/.test(readFileSync(target, "utf8"));
+      if (wired) {
+        return {
+          ok: true,
+          severity: "info",
+          detail: `post-merge reindexes the RAG (${hooks.hooksPath || ".git/hooks"})`,
+        };
+      }
+      const where = hooks.hooksPath ? ` — core.hooksPath=${hooks.hooksPath}` : "";
+      return {
+        ok: false,
+        severity: "info",
+        detail: `RAG index won't auto-refresh after merges${where}; pre-run drift check still covers \`kj run\``,
+        fix: "Wire the post-merge hook: `kj rag install-hooks`",
+      };
+    },
+  };
+}
+
+export function getRagHooksChecks({ projectDir } = {}) {
+  return [createRagHooksCheck({ projectDir })];
+}

package/src/cli/register-pipeline.js

@@ -226,7 +226,7 @@ export function registerPipeline(program, { pkgVersion }) {
 
   program
     .command("install-tools")
-    .description("Install external audit tools (semgrep, osv-scanner, lighthouse, docker, sonar) using the package manager available on your system")
+    .description("Install the tools kj needs (git, agent CLI: claude+codex) plus the external audit tools (semgrep, osv-scanner, lighthouse, docker, sonar) using the package manager available on your system")
     .option("--only <tools>", "Comma-separated subset (e.g. \"semgrep,osv-scanner\"). Bypasses stack-gating.")
     .option("-y, --yes", "Auto-accept all prompts (non-interactive)")
     .option("--dry-run", "Show what would be installed without running anything")

package/src/commands/doctor.js

@@ -25,6 +25,7 @@ import { getRtkChecks } from "../checks/rtk.js";
 import { getSqueezrChecks } from "../checks/squeezr.js";
 import { getAiTrashChecks } from "../checks/ai-trash.js";
 import { getQmdChecks } from "../checks/qmd.js";
+import { getRagHooksChecks } from "../checks/rag-hooks.js";
 import { getNodeChecks } from "../checks/node.js";
 import { getNativeBuildChecks } from "../checks/native-build.js";
 import { getPortChecks } from "../checks/ports.js";
@@ -72,6 +73,7 @@ function buildChecks(config, { projectOnly = false } = {}) {
     ...getSqueezrChecks(),
     ...getAiTrashChecks(),
     ...getQmdChecks(),
+    ...getRagHooksChecks({ projectDir }),
     ...getProjectChecks({ projectDir }),
   ];
 }

package/src/commands/install-tools.js

@@ -14,15 +14,29 @@
 import readline from "node:readline";
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
+import os from "node:os";
 import path from "node:path";
 import fs from "node:fs/promises";
 import { checkBinary } from "../utils/agent-detect.js";
-import { getInstallHint, detectPackageManagers, appliesToStack } from "../utils/install-hints.js";
+import { getInstallHint, detectPackageManagers, appliesToStack, gitInstallPlan } from "../utils/install-hints.js";
 import { detectProjectStack } from "../utils/stack-detect.js";
+import { resolveStandalone } from "../utils/binary-sources.js";
+import { downloadBinary, binDir, runInstallCommand } from "../utils/tool-installer.js";
+import { dockerInstallPlan } from "../utils/docker-install.js";
 
 const execFileAsync = promisify(execFile);
 
-const ALL_TOOLS = ["semgrep", "osv-scanner", "lighthouse", "docker", "sonar"];
+// git and the agent CLI lead the list: both are `kj doctor` *required* tools,
+// so a blank machine wants them before the optional audit tools.
+const ALL_TOOLS = ["git", "agent-cli", "semgrep", "osv-scanner", "lighthouse", "docker", "sonar"];
+
+// The default pipeline is coder=claude, reviewer=codex, so `agent-cli` installs
+// exactly those two. gemini stays out of the default: it is a supported
+// reviewer, not a required one. Both ship as global npm packages.
+const AGENT_CLIS = [
+  { bin: "claude", pkg: "@anthropic-ai/claude-code", url: "https://docs.anthropic.com/en/docs/claude-code" },
+  { bin: "codex", pkg: "@openai/codex", url: "https://github.com/openai/codex" },
+];
 
 function parseOnlyList(raw) {
   if (!raw) return null;
@@ -52,11 +66,100 @@ async function isInstalled(tool) {
   // sonar is a Docker container, not a binary. We check it separately
   // by looking at running containers via `docker ps`.
   if (tool === "sonar") return checkSonarRunning();
+  // agent-cli is "installed" only when BOTH default-pipeline CLIs are present;
+  // a partial install (one of two) still routes to handleAgentCli.
+  if (tool === "agent-cli") {
+    const present = await Promise.all(AGENT_CLIS.map(async (c) => (await checkBinary(c.bin)).ok));
+    return present.every(Boolean);
+  }
   if (tool === "lighthouse") return (await checkBinary("lighthouse")).ok;
   if (tool === "docker") return (await checkBinary("docker")).ok;
   return (await checkBinary(tool)).ok;
 }
 
+/**
+ * Agent-CLI handler. Installs whichever of the default-pipeline CLIs
+ * (coder=claude, reviewer=codex) are missing, via global npm. Opt-in with the
+ * exact command shown first. When npm itself is absent we surface the manual
+ * commands + URLs rather than failing silently.
+ */
+async function handleAgentCli({ available, dryRun, yes, logger }) {
+  const missing = [];
+  for (const cli of AGENT_CLIS) {
+    if (!(await checkBinary(cli.bin)).ok) missing.push(cli);
+  }
+  if (missing.length === 0) return { tool: "agent-cli", action: "already-installed" };
+
+  if (!available.npm) {
+    const commands = missing.map((c) => `npm install -g ${c.pkg}`);
+    logger.warn?.(`✗ agent-cli: npm not found — install manually: ${commands.join(" ; ")}`);
+    return { tool: "agent-cli", action: "manual", reason: "npm not available", missing: missing.map((c) => c.bin), commands, manualUrls: missing.map((c) => c.url) };
+  }
+
+  const installed = [];
+  for (const cli of missing) {
+    const command = `npm install -g ${cli.pkg}`;
+    if (dryRun) {
+      logger.info?.(`▸ ${cli.bin}: would run \`${command}\``);
+      installed.push({ bin: cli.bin, action: "dry-run", command });
+      continue;
+    }
+    const proceed = yes || await promptYesNo(`Install ${cli.bin} with: ${command}?`);
+    if (!proceed) {
+      logger.info?.(`⊘ ${cli.bin}: declined`);
+      installed.push({ bin: cli.bin, action: "declined", command });
+      continue;
+    }
+    logger.info?.(`▸ ${cli.bin}: running \`${command}\`...`);
+    const r = await runInstallCommand(command, { interactive: false });
+    if (r.ok) { logger.info?.(`✓ ${cli.bin}: installed`); installed.push({ bin: cli.bin, action: "installed", command }); }
+    else { const err = r.error || `exit ${r.code}`; logger.warn?.(`✗ ${cli.bin}: install failed (${err})`); installed.push({ bin: cli.bin, action: "failed", command, error: err }); }
+  }
+
+  const action = dryRun ? "dry-run"
+    : installed.some((r) => r.action === "failed") ? "failed"
+    : installed.some((r) => r.action === "installed") ? "installed"
+    : "declined";
+  return { tool: "agent-cli", action, installed };
+}
+
+/**
+ * git handler. git installs through the OS package manager; on Linux that
+ * needs root, so those runs go through the interactive (tty-inherited) path
+ * where sudo prompts the user directly — kj never captures the password. The
+ * exact command is shown first and the install is opt-in, defaulting to NO for
+ * the privileged case. When no package manager matches, we surface the manual
+ * download URL instead of failing silently.
+ */
+async function handleGit({ available, dryRun, yes, logger }) {
+  const plan = gitInstallPlan(available);
+  if (!plan.command) {
+    logger.warn?.(`✗ git: no supported package manager here — install manually: ${plan.manualUrl}`);
+    return { tool: "git", action: "manual", reason: "no supported package manager found", manualUrl: plan.manualUrl };
+  }
+  if (dryRun) {
+    logger.info?.(`▸ git: would run \`${plan.command}\` (manager: ${plan.manager}${plan.needsSudo ? ", needs sudo" : ""})`);
+    return { tool: "git", action: "dry-run", command: plan.command, manager: plan.manager };
+  }
+  if (plan.needsSudo) {
+    logger.warn?.("git: this step needs sudo — you'll be prompted for your password on your own terminal (kj never sees it).");
+  }
+  const proceed = yes || await promptYesNo(`Install git with: ${plan.command}?`, !plan.needsSudo);
+  if (!proceed) {
+    logger.info?.("⊘ git: declined");
+    return { tool: "git", action: "declined", command: plan.command };
+  }
+  logger.info?.(`▸ git: running \`${plan.command}\`...`);
+  const r = await runInstallCommand(plan.command, { interactive: plan.needsSudo });
+  if (r.ok) {
+    logger.info?.(`✓ git: installed via ${plan.manager}`);
+    return { tool: "git", action: "installed", manager: plan.manager };
+  }
+  const err = r.error || `exit ${r.code}`;
+  logger.warn?.(`✗ git: install failed (${err})`);
+  return { tool: "git", action: "failed", command: plan.command, error: err };
+}
+
 async function checkSonarRunning() {
   try {
     const { stdout } = await execFileAsync("docker", ["ps", "--format", "{{.Names}}", "--filter", "name=sonarqube"], { timeout: 5000 });
@@ -85,7 +188,7 @@ async function handleSonar({ available, dryRun }) {
     return {
       tool: "sonar",
       action: "manual",
-      reason: "docker not available — sonar needs docker. Install docker first.",
+      reason: "SonarQube runs as a Docker container — install Docker first (kj install-tools --only docker), then re-run.",
       manualUrl: "https://docs.docker.com/get-docker/",
     };
   }
@@ -104,17 +207,80 @@ async function handleSonar({ available, dryRun }) {
 }
 
 /**
- * Docker handler: never auto-install (platform-specific, invasive).
- * Always point at the official docs.
+ * Docker handler. On macOS/Windows we never auto-install — point at the docs.
+ * On Linux we offer the distro package manager (apt/dnf) or, failing that, the
+ * official convenience script downloaded to a file. The install runs through
+ * `sudo` on the user's own tty (kj never sees the password) and is opt-in,
+ * defaulting to NO, with the exact command shown first.
  */
-function handleDocker(available) {
-  return {
-    tool: "docker",
-    action: "manual",
-    reason: "Docker install is platform-specific — see official docs.",
-    manualUrl: "https://docs.docker.com/get-docker/",
-    suggested: available.brew ? "brew install --cask docker" : null,
-  };
+async function handleDocker({ available, dryRun, yes, logger }) {
+  const plan = dockerInstallPlan(process.platform, available);
+  if (plan.kind === "manual") {
+    logger.info?.(`▸ docker: ${plan.suggested || plan.manualUrl}`);
+    return { tool: "docker", action: "manual", reason: "Docker install is platform-specific — see official docs.", manualUrl: plan.manualUrl, suggested: plan.suggested };
+  }
+
+  const shownCommand = plan.kind === "package" ? plan.command : `sudo sh <get-docker.sh from ${plan.url}>`;
+  if (dryRun) {
+    logger.info?.(`▸ docker: would run \`${shownCommand}\` (invasive, needs sudo)`);
+    return { tool: "docker", action: "dry-run", command: shownCommand, via: plan.kind };
+  }
+
+  logger.warn?.("docker: this step is invasive and needs sudo — you'll be prompted for your password on your own terminal (kj never sees it).");
+  const proceed = yes || await promptYesNo(`Install Docker with: ${shownCommand}?`, false);
+  if (!proceed) {
+    logger.info?.("⊘ docker: declined");
+    return { tool: "docker", action: "declined", command: shownCommand };
+  }
+
+  if (plan.kind === "package") {
+    logger.info?.(`▸ docker: running \`${plan.command}\`...`);
+    const r = await runInstallCommand(plan.command, { interactive: true });
+    if (r.ok) { logger.info?.(`✓ docker: installed via ${plan.manager}`); return { tool: "docker", action: "installed", via: "package", manager: plan.manager }; }
+    const err = r.error || `exit ${r.code}`;
+    logger.warn?.(`✗ docker: install failed (${err})`);
+    return { tool: "docker", action: "failed", via: "package", error: err };
+  }
+
+  // script route: download to a temp file, then run with sudo — never `curl | sh`.
+  const dl = await downloadBinary({ url: plan.url, name: "get-docker.sh", dir: os.tmpdir() });
+  if (!dl.ok) { logger.warn?.(`✗ docker: script download failed (${dl.error})`); return { tool: "docker", action: "failed", via: "script", error: dl.error }; }
+  logger.info?.(`▸ docker: running \`sudo sh ${dl.dest}\`...`);
+  const r = await runInstallCommand(`sudo sh ${dl.dest}`, { interactive: true });
+  if (r.ok) { logger.info?.("✓ docker: installed via get.docker.com"); return { tool: "docker", action: "installed", via: "script", dest: dl.dest }; }
+  const err = r.error || `exit ${r.code}`;
+  logger.warn?.(`✗ docker: install failed (${err})`);
+  return { tool: "docker", action: "failed", via: "script", error: err };
+}
+
+/**
+ * Standalone route when no package manager matched: download a static binary
+ * (osv-scanner) or surface a concrete command to run (semgrep).
+ */
+async function handleStandalone({ tool, standalone, manualUrl, dryRun, yes, logger }) {
+  if (standalone.kind === "command") {
+    logger.warn?.(`✗ ${tool}: no package manager here. Try: ${standalone.command}  ·  \`kj doctor\` shows what's missing (docs: ${manualUrl})`);
+    return { tool, action: "manual", reason: "no package manager — suggested route below", suggested: standalone.command, via: standalone.via, manualUrl };
+  }
+  // kind === "binary"
+  const { url, name } = standalone;
+  if (dryRun) {
+    logger.info?.(`▸ ${tool}: would download ${url} → ${binDir()}`);
+    return { tool, action: "dry-run", command: `download ${url}`, via: "binary" };
+  }
+  const proceed = yes || await promptYesNo(`Download ${tool} from ${url} into ${binDir()}?`);
+  if (!proceed) {
+    logger.info?.(`⊘ ${tool}: declined`);
+    return { tool, action: "declined", command: `download ${url}` };
+  }
+  logger.info?.(`▸ ${tool}: downloading static binary...`);
+  const r = await downloadBinary({ url, name });
+  if (r.ok) {
+    logger.info?.(`✓ ${tool}: installed → ${r.dest} (ensure ${binDir()} is on PATH)`);
+    return { tool, action: "installed", via: "binary", dest: r.dest };
+  }
+  logger.warn?.(`✗ ${tool}: download failed (${r.error})`);
+  return { tool, action: "failed", via: "binary", error: r.error };
 }
 
 /**
@@ -156,7 +322,8 @@ export async function installToolsCommand(opts = {}) {
     if (tool === "sonar") {
       const result = await handleSonar({ available, dryRun });
       results.push(result);
-      logger.info?.(`▸ sonar: ${result.command || result.manualUrl}`);
+      if (result.action === "manual") logger.warn?.(`✗ sonar: ${result.reason}`);
+      else logger.info?.(`▸ sonar: ${result.command}`);
       if (!dryRun && result.action === "ready") {
         const proceed = yes || await promptYesNo(`Start SonarQube with: ${result.command}?`);
         if (proceed) {
@@ -168,18 +335,37 @@ export async function installToolsCommand(opts = {}) {
       continue;
     }
 
+    if (tool === "git") {
+      const result = await handleGit({ available, dryRun, yes, logger });
+      results.push(result);
+      continue;
+    }
+
+    if (tool === "agent-cli") {
+      const result = await handleAgentCli({ available, dryRun, yes, logger });
+      results.push(result);
+      continue;
+    }
+
     if (tool === "docker") {
-      const result = handleDocker(available);
+      const result = await handleDocker({ available, dryRun, yes, logger });
       results.push(result);
-      logger.info?.(`▸ docker: ${result.suggested || result.manualUrl}`);
       continue;
     }
 
     // semgrep / osv-scanner / lighthouse — package-manager driven.
     const hint = await getInstallHint(tool, available);
     if (!hint.command || !hint.manager) {
+      // No package manager matched — try a standalone route (static binary
+      // for osv-scanner, a concrete command for semgrep) before giving up.
+      const standalone = resolveStandalone(tool, available);
+      if (standalone) {
+        const result = await handleStandalone({ tool, standalone, manualUrl: hint.manualUrl, dryRun, yes, logger });
+        results.push(result);
+        continue;
+      }
       results.push({ tool, action: "manual", reason: "no compatible package manager found", manualUrl: hint.manualUrl, suggested: hint.command });
-      logger.warn?.(`✗ ${tool}: no compatible package manager. Manual: ${hint.manualUrl}`);
+      logger.warn?.(`✗ ${tool}: no automatic install route here. Run \`kj doctor\` for options, or install manually: ${hint.manualUrl}`);
       continue;
     }
     if (dryRun) {

package/src/commands/rag.js

@@ -64,9 +64,10 @@ export async function ragIndexCommand({ config, logger, flags = {} }) {
 // who never run it.
 export async function ragInstallHooksCommand({ config, logger, flags = {} }) {
   const projectDir = config?.projectDir || process.cwd();
-  const res = installPostMergeHook({ projectDir, logger });
+  const res = await installPostMergeHook({ projectDir, logger });
   if (flags.json) process.stdout.write(`${JSON.stringify(res)}\n`);
-  else if (res.installed) logger.info(`[rag] installed post-merge hook at ${res.target}`);
+  else if (res.installed) logger.info(`[rag] installed post-merge hook at ${res.target}${res.hooksPath ? ` (core.hooksPath=${res.hooksPath})` : ""}`);
+  else if (res.covered) logger.info(`[rag] ${res.target} already reindexes the RAG (kj-managed); nothing to do`);
   return res;
 }
 

package/src/rag/auto-update.js

@@ -2,7 +2,7 @@
 // Keeps the local RAG index aligned with HEAD so retrieval never serves
 // stale code without the user having to run `kj rag index` by hand.
 import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { join, resolve } from "node:path";
+import { isAbsolute, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { execa } from "execa";
 
@@ -34,17 +34,39 @@ export async function maybeAutoUpdate({ projectDir, config, logger = console, fl
   } finally { db.close(); }
 }
 
-export function installPostMergeHook({ projectDir, logger = console } = {}) {
-  const hooksDir = join(projectDir, ".git", "hooks");
+// KJC-BUG-0100 — Resolve the hooks dir git actually honours. When a repo is
+// hardened `git config core.hooksPath` points at `.karajan/hooks` and git
+// ignores `.git/hooks/` entirely, so a hook written there never fires.
+export async function resolveHooksDir(projectDir) {
   if (!existsSync(join(projectDir, ".git"))) throw new Error(`Not a git repository: ${projectDir}`);
+  let hooksPath = "";
+  try {
+    const r = await execa("git", ["-C", projectDir, "config", "--local", "core.hooksPath"]);
+    hooksPath = r.stdout.trim();
+  } catch { /* unset → git uses .git/hooks */ }
+  if (hooksPath) {
+    return { dir: isAbsolute(hooksPath) ? hooksPath : join(projectDir, hooksPath), hooksPath };
+  }
+  return { dir: join(projectDir, ".git", "hooks"), hooksPath: "" };
+}
+
+export async function installPostMergeHook({ projectDir, logger = console } = {}) {
+  const { dir: hooksDir, hooksPath } = await resolveHooksDir(projectDir);
   if (!existsSync(hooksDir)) mkdirSync(hooksDir, { recursive: true });
   const target = join(hooksDir, "post-merge");
   const src = readFileSync(HOOK_SRC, "utf8");
-  if (existsSync(target) && !readFileSync(target, "utf8").includes("KJC-TSK-0455")) {
-    logger.warn?.(`[rag] ${target} already exists and was not installed by kj; leaving untouched`);
-    return { skipped: true, target };
+  if (existsSync(target)) {
+    const current = readFileSync(target, "utf8");
+    // Another kj-managed hook (e.g. harden's post-merge) already reindexes.
+    if (!current.includes("KJC-TSK-0455") && /kj\s+rag\s+index/.test(current)) {
+      return { skipped: true, covered: true, target, hooksPath };
+    }
+    if (!current.includes("KJC-TSK-0455")) {
+      logger.warn?.(`[rag] ${target} already exists and was not installed by kj; leaving untouched`);
+      return { skipped: true, target, hooksPath };
+    }
   }
   writeFileSync(target, src);
   chmodSync(target, 0o755);
-  return { installed: true, target };
+  return { installed: true, target, hooksPath };
 }

package/src/utils/binary-sources.js

@@ -0,0 +1,64 @@
+// Standalone install routes for tools with no package manager available
+// (KJC-TSK-0607). On a machine with no pipx/brew/go, `kj install-tools`
+// still needs a way to install osv-scanner and semgrep.
+//
+//  · osv-scanner ships a single static binary per platform on its GitHub
+//    releases — we build the /latest/download URL for the current platform.
+//  · semgrep has no single static binary; we offer the most viable concrete
+//    command (Docker image if docker exists, otherwise bootstrapping pipx).
+
+const OSV_BASE = "https://github.com/google/osv-scanner/releases/latest/download";
+
+function osvOs(platform) {
+  if (platform === "linux") return "linux";
+  if (platform === "darwin") return "darwin";
+  if (platform === "win32") return "windows";
+  return null;
+}
+
+function osvArch(arch) {
+  if (arch === "x64") return "amd64";
+  if (arch === "arm64") return "arm64";
+  return null;
+}
+
+/**
+ * Build the osv-scanner static-binary download source for a platform+arch,
+ * or null when the combination has no published asset.
+ *
+ * @returns {{ url: string, name: string }|null}
+ */
+export function osvScannerSource(platform = process.platform, arch = process.arch) {
+  const os = osvOs(platform);
+  const a = osvArch(arch);
+  if (!os || !a) return null;
+  const ext = os === "windows" ? ".exe" : "";
+  return { url: `${OSV_BASE}/osv-scanner_${os}_${a}${ext}`, name: `osv-scanner${ext}` };
+}
+
+/**
+ * Most viable concrete route to install semgrep without a package manager.
+ * Returns a command the user sees before it runs — never a bare docs URL.
+ *
+ * @returns {{ via: "docker"|"pipx", command: string }}
+ */
+export function semgrepFallback(available = {}) {
+  if (available.docker) return { via: "docker", command: "docker pull semgrep/semgrep" };
+  return { via: "pipx", command: "python3 -m pip install --user pipx && pipx install semgrep" };
+}
+
+/**
+ * Resolve the standalone route for a tool when no package manager matched.
+ *  · binary  → download a static binary into ~/.local/bin.
+ *  · command → run/show a concrete install command.
+ *
+ * @returns {{ kind: "binary", url: string, name: string }|{ kind: "command", via: string, command: string }|null}
+ */
+export function resolveStandalone(tool, available = {}, platform = process.platform, arch = process.arch) {
+  if (tool === "osv-scanner") {
+    const src = osvScannerSource(platform, arch);
+    return src ? { kind: "binary", ...src } : null;
+  }
+  if (tool === "semgrep") return { kind: "command", ...semgrepFallback(available) };
+  return null;
+}

package/src/utils/docker-install.js

@@ -0,0 +1,34 @@
+// How `kj install-tools` installs Docker, resolved per platform (KJC-TSK-0609,
+// absorbing the sudo+apt/dnf primitive of KJC-TSK-0608).
+//
+//  · Linux: prefer the distro package manager (apt → docker.io, dnf → docker)
+//    run through `sudo` on the user's own tty — kj never sees the password.
+//    When neither is present, fall back to Docker's official convenience
+//    script, which the caller downloads to a file and runs (never `curl | sh`).
+//  · macOS / Windows: never auto-install (platform-specific, invasive) — point
+//    at the official docs, suggesting the brew cask on macOS.
+
+const GET_DOCKER_URL = "https://get.docker.com";
+const DOCKER_DOCS_URL = "https://docs.docker.com/get-docker/";
+
+/**
+ * Resolve the Docker install plan for a platform + available managers.
+ *
+ * @param {string} platform - process.platform value (linux/darwin/win32).
+ * @param {Record<string, boolean>} available - detected package managers.
+ * @returns {{ kind: "package", manager: string, command: string }
+ *          | { kind: "script", url: string }
+ *          | { kind: "manual", manualUrl: string, suggested: string|null }}
+ */
+export function dockerInstallPlan(platform = process.platform, available = {}) {
+  if (platform !== "linux") {
+    return {
+      kind: "manual",
+      manualUrl: DOCKER_DOCS_URL,
+      suggested: available.brew ? "brew install --cask docker" : null,
+    };
+  }
+  if (available.apt) return { kind: "package", manager: "apt", command: "sudo apt-get install -y docker.io" };
+  if (available.dnf) return { kind: "package", manager: "dnf", command: "sudo dnf install -y docker" };
+  return { kind: "script", url: GET_DOCKER_URL };
+}

package/src/utils/install-hints.js

@@ -116,8 +116,36 @@ const MANUAL_URLS = {
   "osv-scanner": "https://google.github.io/osv-scanner/installation/",
   lighthouse: "https://github.com/GoogleChrome/lighthouse#using-the-cli",
   docker: "https://docs.docker.com/get-docker/",
+  git: "https://git-scm.com/downloads",
 };
 
+// git is a `kj doctor` *required* tool. Unlike the audit tools it is installed
+// through the OS package manager, and on Linux that needs root — so the plan
+// carries a `needsSudo` flag and the caller runs those through the interactive
+// (tty-inherited) path, where sudo prompts the user directly and kj never sees
+// the password. brew/scoop/choco install at user scope, no sudo.
+const GIT_CANDIDATES = [
+  { manager: "brew", command: "brew install git", needsSudo: false },
+  { manager: "apt", command: "sudo apt-get install -y git", needsSudo: true },
+  { manager: "dnf", command: "sudo dnf install -y git", needsSudo: true },
+  { manager: "choco", command: "choco install git -y", needsSudo: false },
+  { manager: "scoop", command: "scoop install git", needsSudo: false },
+];
+
+/**
+ * Pick a git install plan for the current machine. Returns a manual plan
+ * (command null + URL) when no supported package manager is present.
+ *
+ * @param {Record<PackageManager, boolean>} available
+ * @returns {{ command: string|null, manager: PackageManager|null, needsSudo: boolean, manualUrl: string }}
+ */
+export function gitInstallPlan(available = {}) {
+  for (const { manager, command, needsSudo } of GIT_CANDIDATES) {
+    if (available[manager]) return { command, manager, needsSudo, manualUrl: MANUAL_URLS.git };
+  }
+  return { command: null, manager: null, needsSudo: false, manualUrl: MANUAL_URLS.git };
+}
+
 /**
  * Tools whose hint depends on the project stack. lighthouse is only
  * relevant for frontend projects; suppressing the hint elsewhere keeps

package/src/utils/tool-installer.js

@@ -0,0 +1,93 @@
+// Executor primitives for `kj install-tools` (KJC-TSK-0606).
+//
+// Two ways to run an install step:
+//  · runInstallCommand(cmd)                 — captured: stdout/stderr collected,
+//                                             for non-privileged commands.
+//  · runInstallCommand(cmd, {interactive})  — tty inherited: the child owns the
+//                                             terminal so `sudo` prompts the user
+//                                             directly. kj NEVER sees the password.
+//
+// And a downloader for tools shipped as a single static binary (osv-scanner,
+// semgrep) when no package manager is available: fetch → temp file → chmod +x →
+// atomic rename into ~/.local/bin. On any failure it leaves no partial file.
+
+import { execFile, spawn } from "node:child_process";
+import { promisify } from "node:util";
+import os from "node:os";
+import path from "node:path";
+import fs from "node:fs/promises";
+
+const execFileAsync = promisify(execFile);
+
+/** Directory where downloaded standalone binaries are placed. */
+export function binDir() {
+  return path.join(os.homedir(), ".local", "bin");
+}
+
+/**
+ * Run an install command. Commands here are simple (no nested quoting), so we
+ * tokenize on whitespace.
+ *
+ * @param {string} command
+ * @param {{ interactive?: boolean }} [opts]
+ *   interactive → inherit the parent's stdio so sudo can prompt for the password
+ *   on the user's own terminal; kj never captures or logs it.
+ */
+export async function runInstallCommand(command, opts = {}) {
+  const [bin, ...args] = command.split(/\s+/);
+  if (opts.interactive) return runInherited(bin, args);
+  try {
+    const { stdout, stderr } = await execFileAsync(bin, args, {
+      timeout: 300_000,
+      maxBuffer: 32 * 1024 * 1024,
+    });
+    return { ok: true, stdout, stderr };
+  } catch (err) {
+    return { ok: false, error: err?.shortMessage || err?.message || String(err), stderr: err?.stderr };
+  }
+}
+
+function runInherited(bin, args) {
+  return new Promise((resolve) => {
+    let child;
+    try {
+      child = spawn(bin, args, { stdio: "inherit", timeout: 600_000 });
+    } catch (err) {
+      resolve({ ok: false, error: err?.message || String(err) });
+      return;
+    }
+    child.on("error", (err) => resolve({ ok: false, error: err?.message || String(err) }));
+    child.on("close", (code) => resolve({ ok: code === 0, code }));
+  });
+}
+
+/**
+ * Download a single static binary and place it (executable) into `dir`.
+ * Writes to a temp file first and renames atomically; on any failure the temp
+ * file is removed so no partial artifact is left behind.
+ *
+ * @param {{ url: string, name: string, dir?: string }} args
+ */
+export async function downloadBinary({ url, name, dir = binDir() }) {
+  let res;
+  try {
+    res = await fetch(url);
+  } catch (err) {
+    return { ok: false, error: `download failed: ${err?.message || String(err)}` };
+  }
+  if (!res.ok) return { ok: false, error: `download failed: HTTP ${res.status}` };
+
+  await fs.mkdir(dir, { recursive: true });
+  const dest = path.join(dir, name);
+  const tmp = path.join(dir, `.${name}.download`);
+  try {
+    const buf = Buffer.from(await res.arrayBuffer());
+    await fs.writeFile(tmp, buf);
+    await fs.chmod(tmp, 0o755);
+    await fs.rename(tmp, dest);
+    return { ok: true, dest };
+  } catch (err) {
+    await fs.rm(tmp, { force: true }).catch(() => {});
+    return { ok: false, error: `install failed: ${err?.message || String(err)}` };
+  }
+}

package/templates/roles/coder.md

@@ -8,10 +8,44 @@ You are the **Coder** in a multi-role AI pipeline. Your job is to write code and
 - Write tests BEFORE implementation when using TDD.
 - Keep changes minimal and focused on the task.
 - "Minimal" means no unnecessary changes — it does NOT mean avoiding new files. If the task requires creating new files (pages, components, modules, tests), you MUST create them. Updating references/links without creating the actual files is an incomplete implementation.
-- Do not modify code unrelated to the task.
+- Change only the code the task requires; leave everything else as it is.
 - Before creating a new utility or helper, check if a similar one already exists in the codebase. Reuse existing code over creating duplicates.
 - Follow existing code conventions and patterns in the repository.
 
+## Constructive dissent (raise real blockers before you code)
+
+You are an Active Partner, not a silent contractor. Before implementing, if you
+detect a genuine problem with the task, surface it FIRST instead of quietly
+coding around it:
+
+- A contradiction between two requirements that cannot both hold.
+- A false or impossible premise — the task assumes a fact, file, or API that
+  does not exist, or forces an outcome that cannot be correct.
+- A concrete security or maintainability risk in what is being asked.
+
+Report it concisely in `result.concerns` (an array of short strings). When a
+blocker makes the task unworkable as stated, stop and report instead of guessing.
+
+Keep the bar high. Proceed silently when the task is clear and coherent — do NOT
+object to trivial or stylistic details, and do NOT manufacture doubts to look
+thorough. Relevance is the test: raise only what would derail the result.
+
+## Check alignment (moderate or complex tasks only)
+
+When the task has moderate or high scope — it spans several files, touches
+architecture, security or testing, or leaves any real doubt about the goal —
+state your understanding BEFORE writing code:
+
+- One or two sentences on what you understood the task to be.
+- Any open questions whose answer would change the implementation.
+
+Report this in `result.alignment` (`{ "understood": "…", "open_questions": [] }`).
+Surfacing a misread here is far cheaper than discovering it after the diff.
+
+Do NOT add this step for trivial or small, unambiguous tasks — proceed straight
+to the code. This gate is for tasks big enough that a wrong assumption is costly,
+not a ritual for every change.
+
 ## PR atomicity (hard project rule)
 
 Karajan projects MAY enforce a CI gate that fails any PR whose net delta exceeds **200 lines added** (the karajan-code repo itself enforces this since 2026-05-08). Plan before writing:
@@ -35,7 +69,7 @@ Before reporting done, verify that ALL parts of the task are addressed:
 - If the task says "create X", create the complete working implementation, not a skeleton.
 - If tests exist, the implementation MUST make all tests pass.
 - If you write tests first (TDD), the implementation MUST make those tests pass.
-- Do NOT commit code that doesn't compile or doesn't pass tests.
+- Commit only code that compiles and passes the full test suite.
 
 ## Test file location (MANDATORY convention)
 
@@ -105,7 +139,9 @@ Return a JSON object:
     "files_modified": ["path/to/file.js"],
     "files_created": ["path/to/new-file.js"],
     "tests_added": ["path/to/test.js"],
-    "approach": "Brief description of what was done"
+    "approach": "Brief description of what was done",
+    "concerns": [],
+    "alignment": null
   },
   "summary": "Human-readable summary of changes"
 }

package/templates/roles/reviewer.md

@@ -4,7 +4,7 @@ You are the **Reviewer** in a multi-role AI pipeline. Your job is to review code
 
 ## Scope constraint
 
-- **ONLY review files present in the diff.** Do not flag issues in files that were not changed.
+- **Review only the files present in the diff.** Keep every finding scoped to what this change touched.
 - If you notice problems in untouched files, mention them as `non_blocking_suggestions` with a note that they are outside the current scope — never as `blocking_issues`.
 - Your job is to review THIS change, not audit the entire codebase.
 
@@ -21,7 +21,7 @@ You are the **Reviewer** in a multi-role AI pipeline. Your job is to review code
 - Focus on security, correctness, and tests first.
 - Only raise blocking issues for concrete production risks in the changed files.
 - Keep non-blocking suggestions separate.
-- Style preferences NEVER block approval.
+- Let style preferences pass; reserve blocking for concrete production risks.
 - Confidence threshold: reject only if < 0.70.
 
 ## File overwrite detection (BLOCKING)

package/templates/roles/spec-reviewer.md

@@ -11,6 +11,11 @@ user's spec (prompt or `.md`) for deficiencies. You do NOT execute or plan.
 - **assumptions** — depends on unstated context.
 - **out_of_scope** — asks for things outside what Karajan can do.
 
+A spec can also carry a **false premise**: it forces an answer that cannot be
+correct (asks for N options when only one is valid, assumes a fact/API that does
+not exist). Surface these as `contradiction` or `out_of_scope` — never rationalise
+them into a plausible-looking answer.
+
 ## Severity
 
 `info` (nuance), `warn` (real gap), `fail` (unworkable). Top-level `severity`