karajan-code 4.29.1 → 4.31.0

package/package.json

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

package/scripts/postinstall.js

@@ -32,7 +32,11 @@ const CLAUDE_JSON_PATH = path.join(os.homedir(), ".claude.json");
 // KJC-BUG-0179 (#1730): a home INSIDE the npm package is the old default
 // this script wrote itself — wiped on every reinstall, never where `kj init`
 // stores kj.config.yml. Such a value is stale, not a user choice.
-const isPackageDirHome = (home) => /node_modules[\\/]karajan-code[\\/]\.karajan[\\/]?$/.test(home);
+// KJC-BUG-0181: in a linked install (npm link, source tree) the package does
+// not live under node_modules, so THIS package's own `.karajan` is the same
+// stale default under another path — compared as a path, not a pattern.
+const isPackageDirHome = (home) => /node_modules[\\/]karajan-code[\\/]\.karajan[\\/]?$/.test(home)
+  || path.resolve(home) === path.join(ROOT_DIR, ".karajan");
 
 /** The home a previous registration carried, if the user (not this script) set it. */
 function homeFromExistingEntry(entry) {

package/scripts/verify-pack-mcp.mjs

@@ -0,0 +1,76 @@
+/**
+ * MCP smoke for verify-pack (KJC-TSK-0844) — the karajan-mcp server of the
+ * INSTALLED tarball is started over stdio with the SDK client and exercised
+ * with kj_status, kj_config and kj_review, no LLM involved. The MCP surface
+ * was only proved by tests with every seam mocked and dogfooded by no
+ * development session; KJC-BUG-0175 (taskFile promised, never read) and
+ * KJC-BUG-0176 (kjHome declared, ignored) both shipped through that gap.
+ *
+ * What counts as a failure: the server not answering, a tool missing from
+ * the list, or a handler that never reached its gate — "Missing required
+ * field", "Config file not found", "taskFile read failed", "Unknown tool".
+ * A rejection the gate itself hands back (no reviewer CLI on this machine,
+ * Sonar, base branch) is the expected answer of an agentless runner and is
+ * said explicitly, never hidden.
+ */
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+
+const FATAL = [/Missing required field/i, /Config file not found/i, /taskFile read failed/i, /Unknown tool/i];
+const TOOLS = ["kj_status", "kj_config", "kj_review"];
+
+/** The text of a tool answer, and whether it is a failure of the contract (not of the environment). */
+export function classifyAnswer(tool, text) {
+  const fatal = FATAL.find((re) => re.test(text));
+  if (fatal) return { tool, ok: false, reason: `${tool} answered "${text.match(fatal)[0]}": the handler never reached its gate` };
+  let parsed = null;
+  try { parsed = JSON.parse(text); } catch { /* not JSON: plain text answer */ }
+  if (parsed && parsed.ok === false) return { tool, ok: true, gated: true, reason: String(parsed.error || "").slice(0, 200) };
+  return { tool, ok: true, gated: false };
+}
+
+/**
+ * @param {object} o
+ * @param {string} o.serverPath - src/mcp/server.js of the install under test
+ * @param {string} o.kjHome - a home holding kj.config.yml (passed as the tool's `kjHome` AND as KARAJAN_HOME)
+ * @param {string} o.projectDir - an initialised git repo with a task file
+ * @param {string} o.taskFile - path of the task (.md) relative to projectDir
+ * @returns {Promise<{ok: boolean, findings: string[], answers: object[]}>}
+ */
+export async function mcpSmoke({ serverPath, kjHome, projectDir, taskFile, env = process.env, timeoutMs = 120_000 }) {
+  const findings = [];
+  const answers = [];
+  const transport = new StdioClientTransport({
+    command: process.execPath, args: [serverPath], cwd: projectDir, stderr: "pipe",
+    env: { ...env, KARAJAN_HOME: kjHome },
+  });
+  const client = new Client({ name: "kj-verify-pack", version: "0" });
+  const call = async (name, args) => {
+    const res = await client.callTool({ name, arguments: args }, undefined, { timeout: timeoutMs });
+    const text = (res.content || []).map((c) => c.text || "").join("\n");
+    const verdict = classifyAnswer(name, text);
+    answers.push(verdict);
+    if (!verdict.ok) findings.push(verdict.reason);
+    return verdict;
+  };
+  try {
+    await client.connect(transport);
+    const listed = new Set((await client.listTools()).tools.map((t) => t.name));
+    for (const t of TOOLS) if (!listed.has(t)) findings.push(`${t} is not listed by the server`);
+    if (findings.length > 0) return { ok: false, findings, answers };
+    // A project that never ran has no run log: that answer is the contract, not a refusal.
+    const status = await call("kj_status", { kjHome, projectDir, lines: 5 });
+    if (status.gated && !/no active run log/i.test(status.reason)) findings.push(`kj_status refused: ${status.reason}`);
+    const config = await call("kj_config", { kjHome, json: true });
+    if (config.gated) findings.push(`kj_config refused: ${config.reason}`);
+    // The task travels ONLY as a file: the handler must read it before any
+    // gate. The reviewer is a name no machine has, so the gate stops the call
+    // before a single LLM token, on a laptop with real agents as much as in CI.
+    await call("kj_review", { kjHome, projectDir, taskFile, reviewer: "kj-verify-stub" });
+  } catch (err) {
+    findings.push(`MCP session failed: ${err.message}`);
+  } finally {
+    await client.close().catch(() => {});
+  }
+  return { ok: findings.length === 0, findings, answers };
+}

package/scripts/verify-pack.mjs

@@ -24,6 +24,8 @@ import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 
+import { mcpSmoke } from "./verify-pack-mcp.mjs";
+
 const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 const pkg = JSON.parse(fs.readFileSync(path.join(repoRoot, "package.json"), "utf8"));
 const expectedVersion = pkg.version;
@@ -220,6 +222,33 @@ try {
   }
   console.log("verify-pack: quickstart smoke (init + report, no-remote repo) ✓");
 
+  // 5.6 MCP smoke (KJC-TSK-0844) — the karajan-mcp server of the GLOBAL
+  // install, over stdio, against the quickstart repo and its home: kj_status,
+  // kj_config and kj_review with kjHome + taskFile, no LLM. The MCP surface
+  // shipped KJC-BUG-0175/0176 through tests that mocked every seam.
+  const gServer = path.join(
+    gTmp, ...(process.platform === "win32" ? ["node_modules"] : ["lib", "node_modules"]),
+    ...pkgName.split("/"), "src", "mcp", "server.js",
+  );
+  if (!fs.existsSync(gServer)) fail(`karajan-mcp server missing in the global install: ${gServer}`);
+  // A branch with a staged source and a task file: kj_review must READ the
+  // file and reach its gate (a refusal there is this agentless runner's answer).
+  run("git", ["checkout", "-q", "-b", "smoke/mcp"], { cwd: qsTmp });
+  fs.writeFileSync(path.join(qsTmp, "task.md"), "Add a greeting helper\n");
+  fs.writeFileSync(path.join(qsTmp, "hello.js"), "export const hi = () => 'hi';\n");
+  run("git", ["add", "hello.js"], { cwd: qsTmp });
+  console.log("verify-pack: MCP smoke (kj_status, kj_config, kj_review over stdio)…");
+  const mcp = await mcpSmoke({ serverPath: gServer, kjHome: qsEnv.KARAJAN_HOME, projectDir: qsTmp, taskFile: "task.md", env: qsEnv });
+  if (!mcp.ok) fail("the tarball's karajan-mcp server did not honour its own tool contract", mcp.findings.join("\n"));
+  for (const a of mcp.answers) if (a.gated) console.log(`verify-pack:   ${a.tool} reached its gate and refused (expected here): ${a.reason}`);
+  // KJC-BUG-0179: the tarball's postinstall registered the MCP in the temp
+  // HOME under the current name, never the deprecated KJ_HOME.
+  const registered = JSON.parse(fs.readFileSync(path.join(homeTmp, ".claude.json"), "utf8")).mcpServers?.["karajan-mcp"]?.env || {};
+  if (!registered.KARAJAN_HOME || registered.KJ_HOME) {
+    fail("postinstall registered karajan-mcp without KARAJAN_HOME (or with the deprecated KJ_HOME)", JSON.stringify(registered));
+  }
+  console.log("verify-pack: MCP smoke ✓");
+
   // 6. pnpm install smoke (KJC-TSK-0580). pnpm's layout differs from npm's
   // (a symlinked virtual store), so it can break resolution of the bundled
   // karajan-core the way npm packaging breakage did before (KJC-BUG-0082/0086).

package/src/audit/deterministic-summary.js

@@ -15,6 +15,7 @@ import { groupFindingsBySeverity as groupSemgrepBySeverity } from "./semgrep-fin
 import { groupCyclesBySeverity } from "./circular-deps.js";
 import { groupDeadExportsBySeverity } from "./dead-exports.js";
 import { groupInjectionBySeverity } from "./injection-findings.js";
+import { groupEnvKeyFindingsBySeverity } from "./env-key-findings.js";
 
 const MAX_SAMPLE_DEAD_EXPORTS = 10;
 const MAX_SAMPLE_SONAR_PER_SEVERITY = 5;
@@ -43,11 +44,33 @@ export function formatDeterministicSummary(ctx) {
   if (ctx.deadExports) lines.push(...formatDeadExportsBlock(ctx.deadExports));
   if (ctx.injectionFindings) lines.push(...formatInjectionBlock(ctx.injectionFindings));
   if (ctx.aiSlop) lines.push(...formatAiSlopBlock(ctx.aiSlop));
+  if (ctx.envKeys) lines.push(...formatEnvKeysBlock(ctx.envKeys));
   if (ctx.webperf) lines.push(...formatWebperfBlock(ctx.webperf));
 
   return lines.join("\n");
 }
 
+const MAX_SAMPLE_ENV_KEYS = 8;
+
+// KJC-TSK-0845: the same key resolved with two rules in two modules, and a
+// deprecated key read where its successor never is — every site named.
+function formatEnvKeysBlock(envKeys) {
+  if (!envKeys.available) return ["### Env/config key resolution", `- Status: not available — ${envKeys.reason || "scan failed"}`, ""];
+  const { HIGH, MEDIUM } = groupEnvKeyFindingsBySeverity(envKeys);
+  const lines = ["### Env/config key resolution", `- Files scanned: ${envKeys.scanned ?? 0}`, `- Incomplete migrations: ${HIGH.length} · keys resolved with divergent rules: ${MEDIUM.length}`];
+  for (const i of HIGH.slice(0, MAX_SAMPLE_ENV_KEYS)) {
+    lines.push(`  - HIGH ${i.file}:${i.line} reads \`${i.key}\` and never \`${i.successor}\``);
+  }
+  for (const d of MEDIUM.slice(0, MAX_SAMPLE_ENV_KEYS)) {
+    lines.push(`  - MEDIUM [${d.kind}] \`${d.key}\` resolved ${d.rules.length} ways:`);
+    for (const r of d.rules) lines.push(`    - \`${r.rule}\` ← ${r.sites.join(", ")}`);
+  }
+  const more = HIGH.length + MEDIUM.length - Math.min(HIGH.length, MAX_SAMPLE_ENV_KEYS) - Math.min(MEDIUM.length, MAX_SAMPLE_ENV_KEYS);
+  if (more > 0) lines.push(`  - ... and ${more} more`);
+  lines.push("");
+  return lines;
+}
+
 function formatAiSlopBlock(slop) {
   if (!slop.available) return ["### AI-slop tells (deterministic)", `- Status: not available — ${slop.reason || "scan failed"}`, ""];
   const lines = ["### AI-slop tells (deterministic)", `- Files scanned: ${slop.filesScanned ?? 0}`, `- Score: ${slop.score}/100 (100 = clean)`, `- Findings: ${slop.total ?? 0}`];
@@ -338,5 +361,6 @@ export function deterministicContextHasFindings(ctx) {
   if (ctx.deadExports?.available && (ctx.deadExports.total ?? 0) > 0) return true;
   if (ctx.growthDelta && (Math.abs(ctx.growthDelta.lines || 0) > 100 || Math.abs(ctx.growthDelta.deps || 0) > 0)) return true;
   if (ctx.aiSlop?.available && (ctx.aiSlop.total ?? 0) > 0) return true;
+  if (ctx.envKeys?.available && ((ctx.envKeys.divergent?.length ?? 0) + (ctx.envKeys.incomplete?.length ?? 0)) > 0) return true;
   return false;
 }

package/src/audit/env-key-findings.js

@@ -0,0 +1,162 @@
+/**
+ * Env/config key resolution collector for `kj audit` (KJC-TSK-0845).
+ *
+ * The same key resolved by two modules with two rules is a migration left
+ * half-way: KJ_HOME → KARAJAN_HOME reached the runtime and not the installer
+ * (KJC-BUG-0179), and the MCP resolved the home unlike the CLI (KJC-BUG-0176).
+ * Zero tokens, lexical, best-effort — same shape as injection-findings:
+ *   - divergent: one key, read with an explicit fallback chain (`||` / `??`)
+ *     that differs between files. Plain reads consume a value and resolve
+ *     nothing, so they never count: no false positive on a consumer.
+ *   - incomplete-migration: a file reads a deprecated key and never names its
+ *     successor.
+ */
+import { readdir, readFile } from "node:fs/promises";
+import path from "node:path";
+
+export const DEPRECATED_KEYS = { KJ_HOME: "KARAJAN_HOME" };
+const ROOTS = ["src", "scripts", "bin", "packages"];
+const SKIP_DIRS = new Set(["node_modules", "dist", "build", "coverage", "tests", "test", "__tests__", "docs", "public"]);
+const ENV_READ = /process\.env\.([A-Z][A-Z0-9_]*)|process\.env\[["']([A-Z][A-Z0-9_]*)["']\]/g;
+const CONFIG_START = /\bconfig(?=\??\.[a-z])/g;
+const SEGMENT = /^\??\.([a-z][a-z0-9_]*)/;
+const STOP = new Set([" ", "\t", ";", ",", "|", "?", ":"]);
+
+/** `  || rest` → { op, consumed } with the surrounding blanks, or null when no operator follows. */
+function operatorAt(s) {
+  const t = s.trimStart();
+  const op = ["||", "??"].find((o) => t.startsWith(o)) ?? null;
+  if (!op) return null;
+  const afterOp = t.slice(op.length);
+  return { op, consumed: s.length - afterOp.trimStart().length };
+}
+
+/** `config.a?.b` → { key: "a.b", length } read from just after `config`, or null. */
+function configPath(rest) {
+  const segments = [];
+  let s = rest;
+  for (let m = SEGMENT.exec(s); m; m = SEGMENT.exec(s)) {
+    segments.push(m[1]);
+    s = s.slice(m[0].length);
+  }
+  return segments.length > 0 ? { key: segments.join("."), length: rest.length - s.length } : null;
+}
+
+/** One fallback operand: a quoted literal, or an expression up to the next operator, with balanced brackets. */
+function readOperand(s) {
+  const quote = s[0];
+  if (quote === '"' || quote === "'" || quote === "`") {
+    const end = s.indexOf(quote, 1);
+    return end === -1 ? null : s.slice(0, end + 1);
+  }
+  const n = operandLength(s);
+  return n > 0 ? s.slice(0, n) : null;
+}
+
+/** Length of the expression at the start of `s`: up to the next operator or unbalanced close. */
+function operandLength(s) {
+  // Optional chaining (`a?.b`) is not an operator boundary: flatten it, same length.
+  const flat = s.replaceAll("?.", "..");
+  let depth = 0;
+  for (let i = 0; i < flat.length; i += 1) {
+    const c = flat[i];
+    if (c === "(" || c === "[") {
+      depth += 1;
+    } else if (c === ")" || c === "]") {
+      if (depth === 0) { return i; }
+      depth -= 1;
+    } else if (depth === 0 && STOP.has(c)) {
+      return i;
+    }
+  }
+  return flat.length;
+}
+
+async function listJsFiles(dir, depth = 0) {
+  if (depth > 8) return [];
+  let entries;
+  try { entries = await readdir(dir, { withFileTypes: true }); } catch { return []; }
+  const out = [];
+  for (const e of entries) {
+    const p = path.join(dir, e.name);
+    if (e.isDirectory()) { if (!SKIP_DIRS.has(e.name)) out.push(...(await listJsFiles(p, depth + 1))); }
+    else if (/\.(m?js|cjs)$/.test(e.name)) out.push(p);
+  }
+  return out;
+}
+
+/** The fallback chain written after a subject on the same line, normalized. */
+export function fallbackChain(rest) {
+  const chain = [];
+  let s = rest;
+  for (;;) {
+    const op = operatorAt(s);
+    if (!op) break;
+    const operand = readOperand(s.slice(op.consumed));
+    if (!operand) break;
+    // The operator is part of the rule: `|| "x"` and `?? "x"` resolve differently.
+    chain.push(`${op.op} ${operand.replaceAll(/\s+/g, "")}`);
+    s = s.slice(op.consumed + operand.length);
+  }
+  return chain;
+}
+
+/** Every subject read in one file: { key, kind, line, chain }. */
+export function readsIn(text) {
+  const reads = [];
+  text.split("\n").forEach((line, i) => {
+    if (/^\s*(\/\/|\*)/.test(line)) return;
+    for (const m of line.matchAll(ENV_READ)) {
+      reads.push({ key: m[1] || m[2], kind: "env", line: i + 1, chain: fallbackChain(line.slice(m.index + m[0].length)) });
+    }
+    for (const m of line.matchAll(CONFIG_START)) {
+      const after = m.index + m[0].length;
+      const p = configPath(line.slice(after));
+      if (p) reads.push({ key: p.key, kind: "config", line: i + 1, chain: fallbackChain(line.slice(after + p.length)) });
+    }
+  });
+  return reads;
+}
+
+export async function collectEnvKeyFindings(projectDir, { roots = ROOTS } = {}) {
+  if (!projectDir) return { available: false, reason: "projectDir not provided" };
+  const files = (await Promise.all(roots.map((r) => listJsFiles(path.join(projectDir, r))))).flat();
+  const sites = new Map(); // key → [{ file, line, chain }] (only reads WITH a chain)
+  const incomplete = [];
+  for (const file of files) {
+    const text = await readFile(file, "utf8");
+    const rel = path.relative(projectDir, file);
+    const reads = readsIn(text);
+    for (const r of reads) {
+      if (r.chain.length === 0) continue;
+      // One subject per namespace: process.env.PORT and config.port never compare.
+      const id = `${r.kind}:${r.key}`;
+      if (!sites.has(id)) sites.set(id, []);
+      sites.get(id).push({ file: rel, line: r.line, chain: r.chain });
+    }
+    for (const [old, successor] of Object.entries(DEPRECATED_KEYS)) {
+      // The successor must be READ in the file (a comment naming it is not a migration).
+      const hit = reads.find((r) => r.key === old);
+      if (hit && !reads.some((r) => r.key === successor)) incomplete.push({ key: old, successor, file: rel, line: hit.line });
+    }
+  }
+  const divergent = [];
+  for (const [id, list] of sites) {
+    const [kind, key] = [id.slice(0, id.indexOf(":")), id.slice(id.indexOf(":") + 1)];
+    const rules = new Map();
+    for (const s of list) {
+      const rule = `${key} ${s.chain.join(" ")}`;
+      if (!rules.has(rule)) rules.set(rule, []);
+      rules.get(rule).push(s);
+    }
+    if (rules.size > 1 && new Set(list.map((s) => s.file)).size > 1) {
+      divergent.push({ key, kind, rules: [...rules].map(([rule, at]) => ({ rule, sites: at.map((s) => `${s.file}:${s.line}`) })) });
+    }
+  }
+  divergent.sort((a, b) => a.key.localeCompare(b.key));
+  return { available: true, scanned: files.length, divergent, incomplete };
+}
+
+export function groupEnvKeyFindingsBySeverity({ divergent = [], incomplete = [] } = {}) {
+  return { HIGH: incomplete, MEDIUM: divergent };
+}

package/src/checks/method.js

@@ -12,6 +12,7 @@ import { runCommand } from "../utils/process.js";
 import { checkTestsWithCode } from "../review/tests-with-code.js";
 import { CARD_REF_RE } from "../review/card-first.js";
 import { STRATEGY } from "./types.js";
+import { createRagCoverageCheck } from "./rag-coverage.js";
 
 function recentVerdicts(projectDir, sample) {
   try {
@@ -40,9 +41,12 @@ export async function collectMethodStats({ projectDir, run = runCommand, sample
   const verdicts = recentVerdicts(projectDir, sample);
   const stamped = verdicts.filter((v) => v.workspace);
   const sonar = { proved: 0, docsOnly: 0, granted: 0, unproved: 0 };
+  const rag = { proved: 0, docsOnly: 0, granted: 0, noHarness: 0, unproved: 0 };
   for (const v of verdicts) {
     const kind = sonarProof(v);
     if (kind) sonar[kind] += 1;
+    const asked = ragProof(v);
+    if (asked) rag[asked] += 1;
   }
 
   return {
@@ -50,6 +54,7 @@ export async function collectMethodStats({ projectDir, run = runCommand, sample
     verdicts: { total: verdicts.length, stamped: stamped.length, root: stamped.filter((v) => v.workspace === "root").length },
     testless: { sampled: blocks.length, offenders },
     sonar,
+    rag,
   };
 }
 
@@ -74,9 +79,33 @@ export function sonarProof(v) {
   return "unproved";
 }
 
+/**
+ * KJC-TSK-0849 (ADR 0010, RAG-C): what a verdict's rag block proves — the
+ * session asked the RAG about every source ("proved"), the diff was
+ * "docsOnly", a human "granted" the rule, the tree runs with "noHarness"
+ * (no session ledger can exist), or "unproved": an approved verdict for
+ * code whose block covers nothing, or was never written. A pipeline verdict
+ * carries no block (its warn is sealed at commit) and a verdict older than
+ * the requirement has none either: neither is retroactive.
+ */
+export function ragProof(v) {
+  const r = v?.rag;
+  if (!r || v.verdict !== "approved" || !r.mode) return null;
+  if (r.mode === "docs-only") return "docsOnly";
+  if (r.mode === "granted") return "granted";
+  if (r.mode === "no-harness") return "noHarness";
+  // A pass proves something only with real coverage: both lists present,
+  // at least one source covered, none uncovered. Anything else is a claim.
+  const covered = Array.isArray(r.covered) ? r.covered : null;
+  const uncovered = Array.isArray(r.uncovered) ? r.uncovered : null;
+  if (r.mode === "pass" && covered?.length > 0 && uncovered?.length === 0) return "proved";
+  return "unproved";
+}
+
 export function formatMethodStats(s) {
   const sonar = s.sonar ? ` · sonar proof: ${s.sonar.proved} proved, ${s.sonar.docsOnly} docs-only, ${s.sonar.granted} granted, ${s.sonar.unproved} unproved` : "";
-  return `commits with card ref ${s.commits.withCard}/${s.commits.total} · verdict workspaces root ${s.verdicts.root}/${s.verdicts.stamped || 0} stamped (${s.verdicts.total} total) · source commits without tests ${s.testless.offenders}/${s.testless.sampled}${sonar}`;
+  const rag = s.rag ? ` · rag proof: ${s.rag.proved} proved, ${s.rag.docsOnly} docs-only, ${s.rag.granted} granted, ${s.rag.noHarness} no-harness, ${s.rag.unproved} unproved` : "";
+  return `commits with card ref ${s.commits.withCard}/${s.commits.total} · verdict workspaces root ${s.verdicts.root}/${s.verdicts.stamped || 0} stamped (${s.verdicts.total} total) · source commits without tests ${s.testless.offenders}/${s.testless.sampled}${sonar}${rag}`;
 }
 
 function createMethodCheck() {
@@ -92,6 +121,10 @@ function createMethodCheck() {
       if (stats.sonar.unproved > 0) {
         return { ok: false, severity: "fail", detail: `${stats.sonar.unproved} approved verdict(s) without sonar proof — ${detail}` };
       }
+      // KJC-TSK-0849 (ADR 0010): same for code the session never asked the RAG about.
+      if (stats.rag.unproved > 0) {
+        return { ok: false, severity: "fail", detail: `${stats.rag.unproved} approved verdict(s) without rag proof — ${detail}` };
+      }
       const drought = stats.commits.total >= 5 && stats.commits.withCard / stats.commits.total < 0.5;
       if (drought) {
         return { ok: false, severity: "warn", detail: `most recent commits carry no card reference — ${detail}` };
@@ -102,5 +135,7 @@ function createMethodCheck() {
 }
 
 export function getMethodChecks() {
-  return [createMethodCheck()];
+  // KJC-TSK-0850 (ADR 0010): a source the RAG index cannot see is a defect
+  // of the method, not a preference — same family as sonar proof.
+  return [createMethodCheck(), createRagCoverageCheck()];
 }

package/src/checks/rag-coverage.js

@@ -0,0 +1,50 @@
+/**
+ * KJC-TSK-0850 (ADR 0010, RAG-D) — `kj check` / `kj doctor` item: the RAG
+ * index covers every source of the project and is not older than HEAD.
+ * Red only when an index EXISTS and is incomplete or stale: a machine with
+ * no index yet (CI, a fresh clone) gets the command, not a failure.
+ */
+import { openVecStore } from "../rag/vec-store.js";
+import { ragIndexCoverage } from "../rag/coverage.js";
+import { STRATEGY } from "./types.js";
+
+export function createRagCoverageCheck({ openStore = (dim) => openVecStore({ dim }) } = {}) {
+  return {
+    name: "rag-coverage",
+    label: "RAG index coverage (ADR 0010)",
+    strategy: STRATEGY.NONE,
+    async detect({ config = {}, projectDir = process.cwd() } = {}) {
+      const db = openStore(config?.rag?.embedder?.dim || 768);
+      try {
+        let c;
+        try {
+          c = await ragIndexCoverage(projectDir, { db });
+        } catch (err) {
+          // Corrupt store, unreachable stamp, git failure: a failing check,
+          // never a silent pass. The only tolerated non-red state is "no index".
+          return { ok: false, severity: "fail", detail: `rag coverage could not be evaluated: ${err.message}` };
+        }
+        if (c.absent) {
+          return { ok: true, severity: "info", detail: `no RAG index for ${c.project} yet (${c.total} sources) — kj rag index --with-sources` };
+        }
+        if (!c.lastIndexedCommit) {
+          // Chunks without a commit stamp: nothing says how old they are, so
+          // freshness cannot be established — that is a defect, not a pass.
+          return { ok: false, severity: "fail", detail: `the RAG index of ${c.project} carries no commit stamp, freshness unknown (${c.indexed}/${c.total} sources) — kj rag index --with-sources` };
+        }
+        const gaps = [...c.missing, ...c.stale];
+        if (gaps.length > 0) {
+          // --since only re-embeds files CHANGED since the stamp: a source the
+          // store never saw needs the full walk.
+          const stamp = c.lastIndexedCommit.slice(0, 9);
+          const fix = c.missing.length === 0 ? `kj rag index --since ${stamp}` : "kj rag index --with-sources";
+          const sample = gaps.slice(0, 3).join(", ") + (gaps.length > 3 ? ", …" : "");
+          return { ok: false, severity: "fail", detail: `${c.missing.length} source(s) outside the RAG index, ${c.stale.length} stale (${sample}) — ${fix}` };
+        }
+        return { ok: true, severity: "info", detail: `${c.indexed}/${c.total} sources indexed at ${c.lastIndexedCommit.slice(0, 9)}` };
+      } finally {
+        db.close();
+      }
+    },
+  };
+}

package/src/cli/register-pipeline.js

@@ -34,6 +34,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("--no-sonar", "Do not start the SonarQube container (Docker). The review gate still needs it: start it later with 'kj sonar start'")
     .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 }) => {

package/src/commands/check.js

@@ -6,14 +6,22 @@
 
 import { checkHarden } from "../harden/check.js";
 import { collectMethodStats, formatMethodStats } from "../checks/method.js";
+import { createRagCoverageCheck } from "../checks/rag-coverage.js";
 import { checkAiSurface, formatAiSurface } from "../checks/ai-surface.js";
 import { detectObservedAgents } from "../utils/agent-detect.js";
+import { loadConfig } from "../config.js";
 
 export async function checkCommand({ projectDir = process.cwd(), profile = "standard", json = false, logger = console } = {}) {
   const result = await checkHarden({ projectDir, profile });
   // KJC-TSK-0689 (MG-D): method adherence is VISIBILITY, not a gate — it
   // rides along in check output but never affects the exit code.
   const method = await collectMethodStats({ projectDir }).catch(() => null);
+  // KJC-TSK-0850 (ADR 0010, RAG-D): index coverage IS a gate — an index that
+  // exists but misses or lags a source turns check red; no index = the command.
+  const { config } = await loadConfig(projectDir).catch(() => ({ config: {} }));
+  // An evaluation error (corrupt store, git failure) is a failing check, never
+  // a silent pass: the only tolerated non-red state is the explicit "no index".
+  const ragCoverage = await createRagCoverageCheck().detect({ config, projectDir }).catch((err) => ({ ok: false, severity: "fail", detail: `rag coverage could not be evaluated: ${err.message}` }));
   // KJC-TSK-0694: same deal for the MCP inventory — a nudge, never a gate.
   // KJC-TSK-0728: observed agent CLIs ride the same snapshot as "(cli)"
   // entries, so a newly-appeared agent binary trips the same drift question.
@@ -25,16 +33,19 @@ export async function checkCommand({ projectDir = process.cwd(), profile = "stan
     aiSurface = checkAiSurface({ projectDir, extraSurface: clis });
   } catch { /* inventory is best-effort */ }
 
+  const ok = result.ok && ragCoverage.ok;
   if (json) {
-    logger.info?.(JSON.stringify({ ...result, method, aiSurface }));
-    return result.ok ? 0 : 1;
+    logger.info?.(JSON.stringify({ ...result, ok, method, ragCoverage, aiSurface }));
+    return ok ? 0 : 1;
   }
 
   logger.info?.(`kj check (${profile})`);
   for (const c of result.checks) logger.info?.(`  ${c.ok ? "✓" : "✗"} ${c.id}: ${c.detail}`);
   if (method) logger.info?.(`  method: ${formatMethodStats(method)}`);
+  logger.info?.(`  ${ragCoverage.ok ? "✓" : "✗"} rag-coverage: ${ragCoverage.detail}`);
   if (aiSurface) logger.info?.(`  ${formatAiSurface(aiSurface)}`);
-  if (!result.ok) logger.info?.("Harness drift detected — run `kj harden` to repair.");
-  else logger.info?.("Harness OK.");
-  return result.ok ? 0 : 1;
+  if (ok) logger.info?.("Harness OK.");
+  else if (result.ok) logger.info?.("RAG index drift detected — a gate cannot protect what it cannot see.");
+  else logger.info?.("Harness drift detected — run `kj harden` to repair.");
+  return ok ? 0 : 1;
 }

package/src/commands/env.js

@@ -115,6 +115,18 @@ export async function envInstallCommand({ config = null, logger = null, flags =
     try {
       const h = await hardenCommand({ projectDir, logger: console });
       if (h?.ok === false) throw new Error(h.error || "kj harden failed");
+      // KJC-BUG-0188: a headless harden never binds an identity by itself, and
+      // it must not. Blocking here beats the Sentinel denying every git and gh
+      // call later, with nothing on screen tying that back to this install.
+      if (h?.identityPending) {
+        result.exitCode = PENDING_EXIT_CODE;
+        result.pendingBlock = renderPendingBlock(
+          [{ tool: "identity", action: "needs-user", reason: h.identityPending, command: h.identityCommand }],
+          { retry: "kj env install", why: "this clone has no declared identity, and kj never binds one on its own" },
+        );
+        console.log(result.pendingBlock);
+        return result;
+      }
       await reviewGateCommand({ config, flags: { installGate: true } });
       console.log("✓ enforcement active: git hooks + cross-AI verdict gate — a commit outside the method is rejected, not narrated");
     } catch (err) {

package/src/commands/go.js

@@ -13,6 +13,7 @@ import { spawn } from "node:child_process";
 import { checkBinary } from "../utils/agent-detect.js";
 import { createCliAskQuestion } from "../utils/cli-ask-question.js";
 import { envInstallCommand } from "./env.js";
+import { ensureGitRepo } from "./init.js";
 import { boardCommand } from "./board.js";
 // The interactive launchers a muggle can live inside (v1: the two the epic
 // names). Auth heuristics are the same cheap file checks reviewer-fallback
@@ -44,7 +45,7 @@ export function buildGoPrompt() {
   ].join("\n");
 }
 async function defaultPrepare({ config, logger }) {
-  await envInstallCommand({ config, logger, flags: { yes: true } });
+  return envInstallCommand({ config, logger, flags: { yes: true } });
 }
 export async function defaultBoard({ config, logger, runBoard = boardCommand, openPath = "/?maggle=1" }) {
   const port = config.hu_board?.port || 4000;
@@ -95,7 +96,21 @@ export async function goCommand({ config = {}, logger = console, flags = {}, dep
   // Prepare ONCE: decisions already taken are never re-asked.
   if (!existsSync(path.join(projectDir, ".karajan", "review-gate"))) {
     logger.info?.("Preparando tu proyecto (solo la primera vez)…");
-    await (deps.prepare ?? defaultPrepare)({ config, logger });
+    // KJC-BUG-0191: empezar en una carpeta vacía es lo natural, y kj env
+    // install se niega a correr sin repositorio. Lo creamos nosotros.
+    if (!ensureGitRepo({ projectDir, logger })) {
+      logger.error?.("No he podido preparar el control de versiones de tu proyecto (git). Instálalo y vuelve a escribir: kj go");
+      process.exitCode = 1;
+      return 1;
+    }
+    const prepared = await (deps.prepare ?? defaultPrepare)({ config, logger });
+    // Algo depende de tus manos (arriba tienes el detalle). Sin eso el
+    // proyecto quedaría a medias, así que paramos aquí en vez de seguir.
+    if (prepared?.exitCode) {
+      logger.error?.("Falta una cosa que solo puedes hacer tú, la tienes justo arriba. Cuando la hagas, vuelve a escribir: kj go");
+      process.exitCode = 1;
+      return 1;
+    }
   }
   const prompt = (deps.prompt ?? buildGoPrompt)();
   // --window (MGL-E, ADR 0008): la conversación vive DENTRO del board — el

package/src/commands/harden.js

@@ -200,7 +200,10 @@ export async function hardenCommand({
   if (!dryRun) {
     const id = await ensureIdentity({ projectDir, logger });
     out.identity = id.declared ? id.identity : null;
-    if (id.pending) out.identityPending = id.pending;
+    if (id.pending) {
+      out.identityPending = id.pending;
+      out.identityCommand = id.command;
+    }
   }
   // KJC-BUG-0161 / ADR 0009 (opción A): --commit versiona la regeneración
   // del supervisor con procedencia sellada. Acto humano — el guard vive en

package/src/commands/hu.js

@@ -121,6 +121,13 @@ export async function huCommand({ config = null, action, args = [], flags = {} }
       console.warn(`⚠ possible duplicate${plural} — check before working it:\n${candidates}`);
     }
     const plan = await backlogPlan(projectDir);
+    /** Lowest free HU-#### in this plan — ids are permanent, never reused. */
+    const nextHuRef = (p) => {
+      const taken = new Set((p.hus || []).map((h) => h.short_id).filter(Boolean));
+      let n = 1;
+      while (taken.has(`HU-${String(n).padStart(4, "0")}`)) n += 1;
+      return `HU-${String(n).padStart(4, "0")}`;
+    };
     // KJC-TSK-0669 (absolute rule): cards are permanent. The delete-and-
     // recreate "fix" an agent improvises loses history and duplicates ids —
     // refuse it with the norm spelled out.
@@ -145,7 +152,12 @@ export async function huCommand({ config = null, action, args = [], flags = {} }
       .flatMap((s) => String(s).split("\n")).map((s) => s.trim()).filter(Boolean);
     const hu = addHu(plan, {
       title,
-      short_id: flags.id || null,
+      // KJC-BUG-0189: the card-first gate demands a branch that references a
+      // card, and it is this command the gate sends the agent to. The
+      // canonical plan id (hu_plan-<stamp>-<rand>_001) does not match
+      // CARD_REF_RE, so without an explicit --id the card kj just created
+      // could not satisfy kj's own gate. Sequential HU-#### does.
+      short_id: flags.id || nextHuRef(plan),
       acceptance_criteria: [...splitLines(flags.ac), ...splitLines(flags.criteria)],
       acceptance_tests: splitLines(flags.tests),
       scope: flags.scope || null,