karajan-code 4.29.0 → 4.30.0

package/package.json

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

package/scripts/postinstall.js

@@ -27,12 +27,32 @@ async function writeJson(file, obj) {
   await fs.writeFile(file, `${JSON.stringify(obj, null, 2)}\n`, "utf8");
 }
 
-function resolveKjHome() {
-  if (process.env.KJ_HOME) return process.env.KJ_HOME;
-  return path.join(ROOT_DIR, ".karajan");
+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.
+// 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) {
+  const previous = entry?.env?.KARAJAN_HOME || entry?.env?.KJ_HOME;
+  return previous && !isPackageDirHome(previous) ? previous : null;
 }
 
-async function resolveKjHomeFromRegistry() {
+/**
+ * Precedence: KARAJAN_HOME → KJ_HOME (deprecated) → the existing entry's home
+ * → the instances registry → `~/.karajan` (where the CLI defaults, KJC-BUG-0179).
+ */
+async function resolveKjHome(existingEntry) {
+  if (process.env.KARAJAN_HOME) return process.env.KARAJAN_HOME;
+  if (process.env.KJ_HOME) return process.env.KJ_HOME;
+  const previous = homeFromExistingEntry(existingEntry);
+  if (previous) return previous;
   try {
     const registry = await readJson(REGISTRY_PATH);
     const names = Object.keys(registry.instances || {});
@@ -43,28 +63,31 @@ async function resolveKjHomeFromRegistry() {
   } catch {
     // No registry yet — use default
   }
-  return resolveKjHome();
+  return path.join(os.homedir(), ".karajan");
 }
 
-async function setupClaudeMcp(kjHome) {
-  const claudeJsonPath = path.join(os.homedir(), ".claude.json");
-  let config = {};
+async function readClaudeConfig() {
   try {
-    config = await readJson(claudeJsonPath);
+    return await readJson(CLAUDE_JSON_PATH);
   } catch {
-    config = {};
+    return {};
   }
+}
 
+async function setupClaudeMcp(config, kjHome) {
   config.mcpServers = config.mcpServers || {};
+  // Keep every env key the user added to the entry; only the home is ours,
+  // and it is written under the current name (KJ_HOME is deprecated).
+  const { KJ_HOME: _stale, ...userEnv } = config.mcpServers["karajan-mcp"]?.env || {};
   config.mcpServers["karajan-mcp"] = {
     type: "stdio",
     command: "node",
     args: [path.join(ROOT_DIR, "src", "mcp", "server.js")],
     cwd: ROOT_DIR,
-    env: { KJ_HOME: kjHome }
+    env: { ...userEnv, KARAJAN_HOME: kjHome }
   };
 
-  await writeJson(claudeJsonPath, config);
+  await writeJson(CLAUDE_JSON_PATH, config);
 }
 
 function upsertCodexMcpBlock(toml, block) {
@@ -96,7 +119,7 @@ async function setupCodexMcp(kjHome) {
     `args = [${tomlPath(path.join(ROOT_DIR, "src", "mcp", "server.js"))}]`,
     `cwd = ${tomlPath(ROOT_DIR)}`,
     '[mcp_servers."karajan-mcp".env]',
-    `KJ_HOME = ${tomlPath(kjHome)}`
+    `KARAJAN_HOME = ${tomlPath(kjHome)}`
   ].join("\n");
 
   const updated = upsertCodexMcpBlock(toml, block);
@@ -105,9 +128,10 @@ async function setupCodexMcp(kjHome) {
 }
 
 async function main() {
-  const kjHome = await resolveKjHomeFromRegistry();
+  const claudeConfig = await readClaudeConfig();
+  const kjHome = await resolveKjHome(claudeConfig.mcpServers?.["karajan-mcp"]);
 
-  await setupClaudeMcp(kjHome);
+  await setupClaudeMcp(claudeConfig, kjHome);
   await setupCodexMcp(kjHome);
 
   console.log("karajan-mcp registered in Claude Code and Codex.");

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/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/review-gate.js

@@ -14,6 +14,8 @@ import { runSolomonArbitration } from "../review/solomon-arbitration.js";
 import { ensureGateTrackable } from "../review/gate-gitignore.js";
 import { runSonarPregate, formatSonarFinding, addedLinesByFile } from "../review/sonar-pregate.js";
 import { checkSonarRequirement, SONAR_RULE_ID } from "../review/sonar-requirement.js";
+import { checkRagRequirement, checkRagVerdict, ragBlock, RAG_RULE_ID } from "../review/rag-requirement.js";
+import { readRagLedger } from "../review/rag-ledger.js";
 import { runMutationPregate, formatSurvivor } from "../review/mutation-pregate.js";
 import { checkCardFirst } from "../review/card-first.js";
 import { liftSealedSupervisorViolations } from "../policy/supervisor-verify.js";
@@ -62,6 +64,13 @@ const formatSonarGrant = (g) => {
   return `⚠ sonar requirement lifted by a HUMAN grant [${SONAR_RULE_ID}]${scope} until ${g.expiresAt} — ${who}: ${g.justification || "sin justificación"}`;
 };
 
+// KJC-TSK-0849 (ADR 0010): same for the rag requirement.
+const formatRagGrant = (g) => {
+  const scope = g.origin === "global" ? " GLOBAL" : "";
+  const who = g.who?.git ?? "?";
+  return `⚠ rag requirement lifted by a HUMAN grant [${RAG_RULE_ID}]${scope} until ${g.expiresAt} — ${who}: ${g.justification || "sin justificación"}`;
+};
+
 // KJC-TSK-0813 (AC3): la exención dice su PROCEDENCIA — un standing global
 // (concedido para toda la máquina) no pasa por uno del proyecto. El texto
 // de las de proyecto queda EXACTAMENTE como estaba.
@@ -355,13 +364,29 @@ export async function reviewGateCommand({ config, logger = null, flags = {} }) {
       if (!req.ok) res = { ok: false, verdict: res.verdict, reason: req.reason };
       else if (req.mode === "granted") console.log(formatSonarGrant(req.grant));
     }
+    // KJC-TSK-0849 (ADR 0010, RAG-C): the verdict's rag block is the evidence
+    // that the session consulted the RAG about every staged source. The one
+    // place the rule cannot be verified is a pipeline verdict: the headless
+    // pipeline keeps no session ledger yet. It WARNS and the allow seals the
+    // warn under the rule id, so the exception is auditable (kj policy report)
+    // and gains teeth with data — never accepted in silence.
+    const warnIds = gate.warns.map((w) => w.rule_id);
+    if (res.ok && res.verdict.host === "kj-pipeline") {
+      console.log(`⚠ rag [${RAG_RULE_ID}]: the pipeline verdict carries no session ledger — the headless pipeline does not consult the RAG yet; sealed as a warn`);
+      if (!warnIds.includes(RAG_RULE_ID)) warnIds.push(RAG_RULE_ID);
+    } else if (res.ok) {
+      const { harness, verified, mismatched } = readRagLedger(projectDir);
+      const rreq = checkRagVerdict({ config, stagedFiles: changedFiles, rag: res.verdict.rag, harness, verified, mismatched, standingExceptions: std.standing });
+      if (!rreq.ok) res = { ok: false, verdict: res.verdict, reason: rreq.reason };
+      else if (rreq.mode === "granted" && rreq.grant) console.log(formatRagGrant(rreq.grant));
+    }
     console.log(res.ok
       ? `✓ verdict ok — approved by ${res.verdict.reviewer} (diff ${res.verdict.diffHash.slice(0, 12)})`
       : `✗ ${res.reason}`);
     // GOV-C: el allow del chokepoint de COMMIT es evidencia — se sella. PL-E
     // (KJC-TSK-0767): con las reglas que AVISARON, para que "nace avisando y
     // gana dientes" se decida con datos (kj policy report), no a ciegas.
-    if (res.ok) seal("allow", gate.warns.length > 0 ? { warn_rule_ids: gate.warns.map((w) => w.rule_id) } : {});
+    if (res.ok) seal("allow", warnIds.length > 0 ? { warn_rule_ids: warnIds } : {});
     process.exitCode = res.ok ? 0 : 1;
     return res;
   }
@@ -434,6 +459,29 @@ export async function reviewGateCommand({ config, logger = null, flags = {} }) {
   // human grant) — the method report reads it back.
   sonarRecord.mode = sonarReq.mode;
 
+  // KJC-TSK-0849 (ADR 0010, RAG-C): the session's RAG ledger must show the
+  // RAG answered about every staged source (file or sibling), and the TWINS
+  // it returned that the diff does not touch travel to the reviewer by name —
+  // the 16-sep bugs were exactly the twin nobody touched.
+  const ledger = readRagLedger(projectDir);
+  const newFiles = (await rawDiff(flags.range, ["--name-only", "--diff-filter=A"])).split("\n").map((f) => f.trim()).filter(Boolean);
+  const ragReq = checkRagRequirement({ config, stagedFiles: changedFiles, newFiles, ledger, standingExceptions: std.standing });
+  if (!ragReq.ok) {
+    console.log(`✗ ${ragReq.reason}`);
+    process.exitCode = 1;
+    return { verdict: "rejected", reviewer: "rag-first", issues: [{ severity: "high", file: undefined, description: ragReq.reason }] };
+  }
+  if (ragReq.mode === "granted") console.log(formatRagGrant(ragReq.grant));
+  if (ragReq.mode === "no-harness") console.log("⚠ rag: no Sentinel harness in this tree — no session ledger to check (kj harden installs it)");
+  const ragRecord = ragBlock(ragReq, ledger);
+  if (ragRecord.twinsUntouched.length > 0) {
+    const twins = ragRecord.twinsUntouched;
+    console.log(`ℹ rag twins: this session's queries also returned ${twins.length} file(s) the diff does not touch — ${twins.slice(0, 5).join(", ")}${twins.length > 5 ? "…" : ""}`);
+    task = `${task || "Review the following diff for correctness, security and maintainability."}\n\n`
+      + "The session's RAG queries also returned these files, which the diff does NOT touch — the same concept may live there, so check the change is complete, not only correct:\n"
+      + twins.map((t) => `- ${t}`).join("\n");
+  }
+
   // MUT-A (KJC-TSK-0716): mutation pre-gate — opt-in (method_gates.mutation),
   // SOLO en --staged (jamás en pre-commit: cuesta minutos; y jamás en --range:
   // el scope es el ÍNDICE y anotaría trabajo ajeno — catch de codex). block
@@ -456,7 +504,7 @@ export async function reviewGateCommand({ config, logger = null, flags = {} }) {
     }
   }
 
-  const record = await runOneShotReview({ diff, task, config, logger, projectDir, sonar: sonarRecord });
+  const record = await runOneShotReview({ diff, task, config, logger, projectDir, sonar: sonarRecord, rag: ragRecord });
   printVerdict(record);
   process.exitCode = record.verdict === "approved" ? 0 : 1;
   return record;

package/src/harden/sentinel-hooks.js

@@ -123,7 +123,7 @@ const POST_BODY = `#!/usr/bin/env node
 import { relative } from "node:path";
 import { spawnSync } from "node:child_process";
 import { doc, CODE, TESTS, ROOT, CARD, branchOf, load, save, session } from "./sentinel-lib.mjs";
-const ESCAPES = ["KJ_ALLOW_WRITE", "KJ_ALLOW_REWRITE", "KJ_ALLOW_NO_CARD", "KJ_ALLOW_NO_TESTS", "KJ_ALLOW_PII", "KJ_ALLOW_POLICY", "KJ_ALLOW_IDENTITY", "KJ_ALLOW_BOARD"];
+const ESCAPES = ["KJ_ALLOW_WRITE", "KJ_ALLOW_REWRITE", "KJ_ALLOW_NO_CARD", "KJ_ALLOW_NO_TESTS", "KJ_ALLOW_PII", "KJ_ALLOW_POLICY", "KJ_ALLOW_IDENTITY", "KJ_ALLOW_BOARD", "KJ_ALLOW_NO_RAG"];
 let raw = "";
 process.stdin.on("data", (d) => { raw += d; });
 process.stdin.on("end", () => {
@@ -146,6 +146,39 @@ process.stdin.on("end", () => {
       if (cardId && !(s.closed_cards ||= []).includes(cardId)) s.closed_cards.push(cardId);
       save(state);
     };
+    // KJC-TSK-0847 (ADR 0010, RAG-A): the ledger of what the RAG answered in
+    // this session — every kj_rag_query (MCP) and kj rag query (CLI) with the
+    // repo-relative sources it returned. Neither the CLI nor the MCP know the
+    // host's session id: the harness records, they do not. Hits outside the
+    // repo (another indexed project) are not ours and are dropped.
+    const recordRag = (query, sources) => {
+      const state = load();
+      const s = session(state, sid);
+      s.at = Date.now();
+      const hits = [];
+      for (const src of sources) {
+        const rel = relative(ROOT, String(src)).split(String.fromCharCode(92)).join("/");
+        if (!rel || rel.startsWith("..") || rel.startsWith("/") || hits.includes(rel)) continue;
+        hits.push(rel);
+      }
+      (s.rag_queries ||= []).push({ ts: Date.now(), text: String(query || "").slice(0, 200), hits });
+      const all = (s.rag_hits ||= []);
+      for (const h of hits) if (!all.includes(h)) all.push(h);
+      save(state);
+    };
+    // Sources are read STRUCTURALLY, never through the stringified response:
+    // a JSON document (the MCP {content:[{text}]} parts, the CLI --json array)
+    // is parsed and its hits[].source / [].source collected.
+    const sourcesOf = (doc) => {
+      const list = Array.isArray(doc) ? doc : Array.isArray(doc?.hits) ? doc.hits : [];
+      return list.map((h) => h?.source).filter((x) => typeof x === "string");
+    };
+    const parseJson = (t) => { try { return JSON.parse(t); } catch { return null; } };
+    if (/__kj_rag_query$/.test(String(tool)) && /^mcp__/.test(String(tool))) {
+      const parts = Array.isArray(response?.content) ? response.content : [];
+      recordRag(input.text, parts.flatMap((p) => sourcesOf(parseJson(String(p?.text || "")))));
+      process.exit(0);
+    }
     if (/__update_card$/.test(String(tool)) && /^mcp__/.test(String(tool))) {
       // The MCP response reaches the hook as {content:[{text:"<json>"}]}: once
       // stringified, the inner quotes are ESCAPED — match both forms (found live:
@@ -171,6 +204,18 @@ process.stdin.on("end", () => {
     }
     if (tool === "Bash") {
       const cmdText = String(input.command || "");
+      // CLI form of the ledger: the human output lists one hit per line as
+      // "[kind · label · score=…] <path>"; --json prints an array with "source".
+      const ragCmd = /kj +rag +query/.exec(cmdText);
+      if (ragCmd) {
+        const out = typeof response === "string" ? response : String(response.stdout || "") + String(response.stderr || "");
+        const fromLines = out.split(String.fromCharCode(10))
+          .filter((l) => l.includes("score=") && l.includes("] "))
+          .map((l) => l.slice(l.lastIndexOf("] ") + 2).trim())
+          .filter(Boolean);
+        recordRag(cmdText.slice(ragCmd.index), fromLines.concat(sourcesOf(parseJson(out.trim()))));
+        process.exit(0);
+      }
       // gh prints "merged pull request #N" only on a TTY: under a tool call the
       // success line is ABSENT (found live on the first dogfood merge). The
       // authoritative signal is the PR state itself: one gh pr view per merge.
@@ -250,7 +295,7 @@ if (process.argv.includes("--status")) {
   const sessions = Object.entries(st.sessions || {});
   if (!sessions.length) console.log("sentinel: sin actividad registrada en esta sesion");
   for (const [sid, s] of sessions) {
-    console.log("session " + sid + ": sources=[" + (s.edited_sources || []).join(", ") + "] tests=[" + (s.edited_tests || []).join(", ") + "] escapes=[" + (s.escapes || []).join(", ") + "] blocks=" + (s.blocks || 0) + ((s.errors || []).length ? " errors=" + s.errors.length : ""));
+    console.log("session " + sid + ": sources=[" + (s.edited_sources || []).join(", ") + "] tests=[" + (s.edited_tests || []).join(", ") + "] escapes=[" + (s.escapes || []).join(", ") + "] blocks=" + (s.blocks || 0) + ((s.errors || []).length ? " errors=" + s.errors.length : "") + " rag=" + (s.rag_queries || []).length + " queries/" + (s.rag_hits || []).length + " sources");
     for (const x of violations(s, branch)) console.log("  ROJO: " + x);
   }
   process.exit(0);
@@ -835,6 +880,26 @@ process.stdin.on("end", () => {
             : "karajan sentinel: la rama '" + branch + "' no referencia ninguna card — crea/mueve la card a running (kj hu add | kj hu move) y usa una rama feat/<CARD-ID>-descripcion. (KJ_ALLOW_NO_CARD=1 = excepcion consciente, queda registrada)" + doc("card-first"));
           process.exit(2);
         }
+        // KJC-TSK-0848 (ADR 0010, RAG-B): the RAG must have answered about this
+        // zone before the session touches it. Covered = the session ledger
+        // (RAG-A) holds this file or a sibling of its directory; a NEW file only
+        // needs the session to have consulted at all. Same file set as card-first.
+        const rs = load().sessions?.[sid] || {};
+        const hits = rs.rag_hits || [];
+        const dirOf = (p) => (p.includes("/") ? p.slice(0, p.lastIndexOf("/")) : "");
+        const fresh = !existsSync(String(file));
+        // A path outside this tree is another lane's business (the lane guard
+        // above rules on it) and the ledger only holds in-repo paths.
+        const covered = rel.startsWith("..") || hits.includes(rel) || hits.some((h) => dirOf(h) === dirOf(rel)) || (fresh && (rs.rag_queries || []).length > 0);
+        if (!covered) {
+          if (escOn("KJ_ALLOW_NO_RAG")) {
+            // Recorded ONCE per session: the escape is a conscious exception, not a per-edit tax.
+            if (!(rs.escapes || []).includes("KJ_ALLOW_NO_RAG")) recordEscape(sid, "KJ_ALLOW_NO_RAG", tool);
+          } else {
+            console.error("karajan sentinel: rag-first — el RAG no ha respondido sobre " + rel + " en esta sesion; consulta antes de tocarlo: kj_rag_query / kj rag query <que hace " + rel + " y donde mas vive ese concepto>. (KJ_ALLOW_NO_RAG=1 = excepcion consciente, queda registrada)" + doc("rag-first"));
+            process.exit(2);
+          }
+        }
       }
     }
     if (tool === "Bash") {

package/src/harden/workflow-engine.js

@@ -102,11 +102,16 @@ export function installWorkflows({
       results.push({ file: label, action: "skipped" });
       continue;
     }
+    // KJC-BUG-0182: prettier's YAML printer puts a blank line between the last
+    // line of a block scalar (`run: |`) and a comment at column 0 — which is
+    // exactly our closing marker. Every template ends with a blank line, so the
+    // file harden writes is the file prettier would write (the pre-commit's
+    // format:check must accept its own harness).
     const { content, action } = upsertManagedBlock({
       source,
       blockId: wf.blockId,
       version: BLOCK_VERSION,
-      body: wf.body,
+      body: wf.body.endsWith("\n") ? wf.body : `${wf.body}\n`,
       style: "hash",
     });
     if (!dryRun && action !== "unchanged") {

package/src/harden/workflow-templates.js

@@ -89,7 +89,6 @@ export const policyWorkflowFor = (kjVersion, kjName = "karajan-code") => [
   "        run: |",
   `          if [ -f bin/kj.js ]; then npm ci --ignore-scripts && KJ="node bin/kj.js"; else KJ="npx --yes ${kjName}@${kjVersion}"; fi`,
   '          $KJ policy check --range "origin/${BASE_REF}...HEAD" --strict',
-  "", // línea en blanco pre-marcador: prettier la exige tras un block scalar
 ].join("\n");
 
 const header = (steps) =>
@@ -263,7 +262,7 @@ export function mutationWorkflowFor(language, pm = "npm") {
     "name: Mutation (nightly)",
     "on:",
     "  schedule:",
-    "    - cron: '0 4 * * 1'",
+    '    - cron: "0 4 * * 1"',
     "  workflow_dispatch:",
     "permissions:",
     "  contents: read",

package/src/rag/coverage.js

@@ -0,0 +1,48 @@
+/**
+ * KJC-TSK-0850 (ADR 0010, RAG-D) — index coverage as a defect. A gate built
+ * on the RAG protects nothing it cannot see, so the sources the indexer's
+ * OWN matchers would take (src/, scripts/, bin/, packages/*: the walker
+ * takes the whole repo minus the skip segments) are compared against the
+ * chunks the store holds for this project, and against the commit the
+ * index was stamped with. No config declares the directories twice: the
+ * matchers are the single truth, here and in the indexer.
+ */
+import { execa } from "execa";
+import { isAbsolute, relative } from "node:path";
+import { detectAdaptersForProject, buildMatchers } from "../lang/registry.js";
+import { getLastIndexedCommit, projectSlug } from "./vec-store.js";
+
+/**
+ * @param {string} projectDir
+ * @param {{db: object}} deps - an open vec store
+ * @returns {Promise<{project: string, total: number, indexed: number, missing: string[], stale: string[], lastIndexedCommit: string|null, absent: boolean}>}
+ */
+export async function ragIndexCoverage(projectDir, { db }) {
+  const project = projectSlug(projectDir);
+  const matchers = buildMatchers(detectAdaptersForProject(projectDir));
+  const { stdout } = await execa("git", ["-C", projectDir, "ls-files", "-z"]);
+  const sources = stdout.split("\0").filter((p) => p && matchers.isCodeFile(p) && !matchers.shouldSkip(p));
+
+  const rows = db.prepare("SELECT DISTINCT source FROM chunks WHERE kind = 'code' AND project_slug = ?").all(project);
+  const indexed = new Set(rows.map((r) => (isAbsolute(r.source) ? relative(projectDir, r.source) : r.source)));
+  const missing = sources.filter((p) => !indexed.has(p));
+
+  const lastIndexedCommit = getLastIndexedCommit(db, project);
+  let stale = [];
+  if (lastIndexedCommit) {
+    // Files the repo changed after the stamp: the delta update has not seen
+    // them yet, so what the store says about them is old.
+    // The stamp must be an ANCESTOR of HEAD: a commit that still exists but
+    // sits on a rewritten branch would diff fine and report selective
+    // staleness, when in truth freshness is unknown. Fail closed.
+    const ancestor = await execa("git", ["-C", projectDir, "merge-base", "--is-ancestor", lastIndexedCommit, "HEAD"], { reject: false });
+    if (ancestor.exitCode !== 0) {
+      throw new Error(`the RAG index stamp ${lastIndexedCommit.slice(0, 9)} is not reachable from HEAD — kj rag index --with-sources`);
+    }
+    const diff = await execa("git", ["-C", projectDir, "diff", "--name-only", lastIndexedCommit, "HEAD"]);
+    const changed = new Set(diff.stdout.split("\n").filter(Boolean));
+    stale = sources.filter((p) => indexed.has(p) && changed.has(p));
+  }
+
+  return { project, total: sources.length, indexed: sources.length - missing.length, missing, stale, lastIndexedCommit, absent: indexed.size === 0 };
+}

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

@@ -45,6 +45,8 @@ export async function runOneShotReview({
   diff, task, config, logger, projectDir,
   // KJC-TSK-0838: what the sonar pre-gate saw, persisted with the verdict.
   sonar = null,
+  // KJC-TSK-0849 (ADR 0010): what the session's RAG ledger proved, same place.
+  rag = null,
   hostAgent = detectHostAgent(),
   createAgentFn = createAgent,
   detectAgents = detectAvailableAgents,
@@ -126,6 +128,7 @@ export async function runOneShotReview({
     suggestions: parsed.non_blocking_suggestions || [],
     summary: parsed.summary || parsed.raw_summary || "",
     ...(sonar ? { sonar } : {}),
+    ...(rag ? { rag } : {}),
     confidence: parsed.confidence ?? null,
   });
 }

package/src/review/rag-ledger.js

@@ -0,0 +1,41 @@
+/**
+ * KJC-TSK-0849 (ADR 0010, RAG-C) — the session's RAG ledger as the review
+ * sees it. The Sentinel records every RAG consultation per host session
+ * (RAG-A) in `.karajan/harness/sentinel-state.json`. `kj review` runs as a
+ * CLI and does not know the host's session id, so it takes the session with
+ * the most recent activity (`at`): MONO-0 forbids two sessions mutating one
+ * tree, so the last one that acted is the one now reviewing. Said here and
+ * in the verdict (`sessionId`), never assumed in silence.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { verifySentinelScripts } from "../harden/sentinel-hooks.js";
+
+/**
+ * @param {string} projectDir
+ * @returns {{harness: boolean, verified: boolean, mismatched: string[], available: boolean, reason?: string, sessionId?: string, queries: object[], hits: string[]}}
+ *   `harness` false = no `.karajan/harness` in this tree: no host session can
+ *   keep a ledger, so the requirement does not apply (said, not assumed).
+ *   `verified` = the scripts on disk are byte-identical to what the INSTALLED
+ *   kj writes (the tamper check's root of trust): an empty directory, an
+ *   edited hook or one that predates the ledger all read as unverified, and
+ *   the requirement fails closed until the human re-runs `kj harden`.
+ */
+export function readRagLedger(projectDir) {
+  const harnessDir = path.join(projectDir, ".karajan", "harness");
+  const harness = existsSync(harnessDir);
+  const check = harness ? verifySentinelScripts({ projectDir }) : { ok: false, mismatched: [] };
+  const base = { harness, verified: harness && check.ok === true, mismatched: check.mismatched || [], queries: [], hits: [] };
+  let state;
+  try {
+    state = JSON.parse(readFileSync(path.join(harnessDir, "sentinel-state.json"), "utf8"));
+  } catch {
+    return { ...base, available: false, reason: harness ? "no session activity recorded by the Sentinel yet" : "no Sentinel harness in this tree (kj harden installs it)" };
+  }
+  const sessions = Object.entries(state?.sessions || {});
+  if (sessions.length === 0) {
+    return { ...base, available: false, reason: "the sentinel state holds no session" };
+  }
+  const [sessionId, s] = sessions.sort((a, b) => (b[1]?.at || 0) - (a[1]?.at || 0))[0];
+  return { ...base, available: true, sessionId, queries: Array.isArray(s?.rag_queries) ? s.rag_queries : [], hits: Array.isArray(s?.rag_hits) ? s.rag_hits : [] };
+}

package/src/review/rag-requirement.js

@@ -0,0 +1,118 @@
+/**
+ * KJC-TSK-0849 (ADR 0010, RAG-C) — a diff that touches source files enters
+ * the review only if the session's RAG ledger (RAG-A) shows the RAG answered
+ * about every staged source: the file itself or a sibling of its directory.
+ * A file NEW in the diff cannot have been returned yet: it counts as covered
+ * once the session consulted at all (the ADR's fallback A, same as the
+ * Sentinel gate). Docs-only diffs are exempt. The only other way through is
+ * a live HUMAN grant on `method.rag.code` — never an env var: an escape the
+ * agent can set for itself is the hole this closes.
+ *
+ * The block also names the TWINS: sources the RAG returned for the same
+ * concepts that are not in the diff. That list travels to the reviewer,
+ * because the bugs of 2026-09-16 were exactly the twin nobody touched.
+ */
+import { sourceFilesOf } from "./tests-with-code.js";
+
+export const RAG_RULE_ID = "method.rag.code";
+
+const GRANT_HINT = `Only a human grant lifts this: kj policy grant --rule ${RAG_RULE_ID} --until <iso> --reason "<why>"`;
+const dirOf = (p) => (p.includes("/") ? p.slice(0, p.lastIndexOf("/")) : "");
+
+function liveGrant(standingExceptions, now) {
+  return standingExceptions.find((e) => e.rule_id === RAG_RULE_ID && new Date(e.expiresAt).getTime() > now.getTime()) || null;
+}
+
+/**
+ * @param {object} args
+ * @param {string[]} args.stagedFiles - every path of the diff
+ * @param {string[]} [args.newFiles] - paths ADDED by the diff (not in HEAD)
+ * @param {{available: boolean, reason?: string, queries: object[], hits: string[]}} [args.ledger]
+ * @returns {{ok: boolean, mode: "docs-only"|"pass"|"granted"|"block", reason?: string, grant?: object, sources?: string[], queries?: number, covered?: string[], uncovered?: string[], twinsUntouched?: string[]}}
+ */
+export function checkRagRequirement({ config = {}, stagedFiles = [], newFiles = [], ledger, standingExceptions = [], now = new Date(), env = {} }) {
+  const { sources } = sourceFilesOf(config, stagedFiles);
+  if (sources.length === 0) return { ok: true, mode: "docs-only" };
+
+  const grant = liveGrant(standingExceptions, now);
+  if (grant) return { ok: true, mode: "granted", grant, sources };
+
+  // An env override is REJECTED here, explicitly: whatever KJ_ALLOW_* the
+  // process carries is named in the reason and changes nothing. The Sentinel
+  // escape opens an edit; it never opens the review.
+  const ignored = Object.keys(env || {}).filter((k) => k.startsWith("KJ_ALLOW_") && env[k] === "1");
+  const overrideNote = ignored.length > 0 ? ` (${ignored.join(", ")} is not honoured here)` : "";
+  const head = `The RAG must have answered about code before it is reviewed (${sources.length} staged source${sources.length === 1 ? "" : "s"})${overrideNote}`;
+  // No Sentinel in this tree = no host session that could keep a ledger: the
+  // requirement does not apply here, and the verdict says so (mode).
+  if (ledger?.harness === false) return { ok: true, mode: "no-harness", sources };
+  // A harness that does not match the installed kj (edited, emptied, or older
+  // than the ledger) cannot vouch for anything: fail closed, like the tamper
+  // check does, until the human regenerates it.
+  if (ledger?.harness === true && ledger?.verified === false) {
+    return { ok: false, mode: "block", sources, reason: `${head} — the Sentinel harness does not match the installed kj (${(ledger.mismatched || []).join(", ") || "scripts missing"}): the human runs \`kj harden\` to regenerate it before code is reviewed. ${GRANT_HINT}` };
+  }
+  if (!ledger?.available) {
+    return { ok: false, mode: "block", sources, reason: `${head} — ${ledger?.reason || "no session ledger"}: consult the RAG about the change (kj_rag_query / kj rag query) and run \`kj review --staged\` again. ${GRANT_HINT}` };
+  }
+  const hits = ledger.hits || [];
+  const queries = (ledger.queries || []).length;
+  const fresh = new Set(newFiles);
+  const answered = (f) => hits.includes(f) || hits.some((h) => dirOf(h) === dirOf(f)) || (fresh.has(f) && queries > 0);
+  const covered = sources.filter(answered);
+  const uncovered = sources.filter((f) => !answered(f));
+  const staged = new Set(stagedFiles);
+  const twinsUntouched = hits.filter((h) => !staged.has(h));
+  const evidence = { queries, covered, uncovered, twinsUntouched };
+  if (uncovered.length > 0) {
+    const list = `${uncovered.slice(0, 5).join(", ")}${uncovered.length > 5 ? "…" : ""}`;
+    return { ok: false, mode: "block", sources, ...evidence, reason: `${head} — no query of this session returned ${uncovered.length} of them (${list}): ask what they do and where else that concept lives, then run \`kj review --staged\` again. ${GRANT_HINT}` };
+  }
+  return { ok: true, mode: "pass", sources, ...evidence };
+}
+
+/**
+ * The pre-commit side (`kj review --check`): the verdict's `rag` block is the
+ * evidence, recomputed against the CURRENT staged sources like the sonar
+ * block — the diff hash pins the file set, so a source missing from
+ * `covered` was never answered about, whatever the block claims.
+ */
+export function checkRagVerdict({ config = {}, stagedFiles = [], rag, harness = true, verified = true, mismatched = [], standingExceptions = [], now = new Date() }) {
+  const { sources } = sourceFilesOf(config, stagedFiles);
+  if (sources.length === 0) return { ok: true, mode: "docs-only" };
+  const grant = liveGrant(standingExceptions, now);
+  if (grant) return { ok: true, mode: "granted", grant, sources };
+  if (!harness) return { ok: true, mode: "no-harness", sources };
+  const head = `The RAG must have answered about code before it is committed (${sources.length} staged source${sources.length === 1 ? "" : "s"})`;
+  if (!verified) {
+    return { ok: false, mode: "block", sources, reason: `${head} — the Sentinel harness does not match the installed kj (${mismatched.join(", ") || "scripts missing"}): the human runs \`kj harden\` to regenerate it. ${GRANT_HINT}` };
+  }
+  if (!rag) {
+    return { ok: false, mode: "block", sources, reason: `${head} — the verdict carries no rag block; run \`kj review --staged\` again. ${GRANT_HINT}` };
+  }
+  // The block's mode is a claim, never an authorization: a grant or a missing
+  // harness only count when they hold NOW (checked above). So the block can
+  // only prove coverage — a "granted" or "no-harness" it recorded has lapsed.
+  if (rag.mode !== "pass" || !Array.isArray(rag.covered)) {
+    return { ok: false, mode: "block", sources, reason: `${head} — the verdict's rag block is malformed (mode ${JSON.stringify(rag.mode ?? null)}, covered ${Array.isArray(rag.covered) ? "list" : typeof rag.covered}); run \`kj review --staged\` again. ${GRANT_HINT}` };
+  }
+  const coveredSet = new Set(rag.covered);
+  const uncovered = sources.filter((f) => !coveredSet.has(f));
+  if (uncovered.length > 0) {
+    const list = `${uncovered.slice(0, 5).join(", ")}${uncovered.length > 5 ? "…" : ""}`;
+    return { ok: false, mode: "block", sources, reason: `${head} — the session ledger never covered ${uncovered.length} of them (${list}); consult the RAG and run \`kj review --staged\` again. ${GRANT_HINT}` };
+  }
+  return { ok: true, mode: "pass", sources };
+}
+
+/** The `rag` block stored in the verdict, bound to the diff hash like `sonar`. */
+export function ragBlock(req, ledger) {
+  return {
+    mode: req.mode,
+    sessionId: ledger?.sessionId || null,
+    queries: req.queries ?? (ledger?.queries || []).length,
+    covered: req.covered || [],
+    uncovered: req.uncovered || [],
+    twinsUntouched: req.twinsUntouched || [],
+  };
+}

package/src/review/solomon-arbitration.js

@@ -102,10 +102,15 @@ export async function runSolomonArbitration({
     position, ruling: parsed.ruling, reasoning: parsed.reasoning || "", solomon,
     originalVerdict: { reviewer: verdict.reviewer, issues: verdict.issues },
   };
+  // KJC-BUG-0183: the arbiter judges the reviewer's objections, not the
+  // evidence bound to the diff (sonar, rag blocks). That evidence was computed
+  // for this exact hash and travels with the overriding verdict — without it
+  // `kj review --check` refuses every arbitrated diff.
+  const evidence = { ...(verdict.sonar ? { sonar: verdict.sonar } : {}), ...(verdict.rag ? { rag: verdict.rag } : {}) };
   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,
+      issues: [], summary: `Arbitration overrode ${verdict.reviewer}'s rejection: ${parsed.reasoning || ""}`.trim(), arbitration, ...evidence,
     })
     : await saveVerdict(projectDir, diff, { ...verdict, arbitration });
 

package/src/roles/audit-role.js

@@ -14,6 +14,7 @@ import { collectCircularDeps } from "../audit/circular-deps.js";
 import { collectDeadExports } from "../audit/dead-exports.js";
 import { collectInjectionFindings } from "../audit/injection-findings.js";
 import { collectAiSlop } from "../audit/ai-slop-findings.js";
+import { collectEnvKeyFindings } from "../audit/env-key-findings.js";
 
 function parseDimensions(dimensionsStr) {
   if (!dimensionsStr || dimensionsStr === "all") return null;
@@ -77,6 +78,7 @@ export class AuditRole extends AgentRole {
     let injectionFindings = null;
     let infraFindings = null;
     let aiSlop = null;
+    let envKeys = null;
     if (!securityOnly) {
       try {
         basalCost = await measureBasalCost(projectDir);
@@ -154,13 +156,20 @@ export class AuditRole extends AgentRole {
         aiSlop = await collectAiSlop(projectDir);
       } catch { /* ai-slop scan is best-effort */ }
     }
+    // KJC-TSK-0845: one key, two resolution rules = a migration left half-way
+    // (KJ_HOME → KARAJAN_HOME). Deterministic, offline, best-effort.
+    if (!securityOnly) {
+      try {
+        envKeys = await collectEnvKeyFindings(projectDir);
+      } catch { /* env-key scan is best-effort */ }
+    }
     // STW-A (KJC-TSK-0789 AC5): record that the security surface was looked
     // at, so the Steward can age it — GREBLA went 79 days with "never".
     try {
       mkdirSync(dirname(securityAuditMarkerPath(projectDir)), { recursive: true });
       writeFileSync(securityAuditMarkerPath(projectDir), JSON.stringify({ at: new Date().toISOString(), mode: securityOnly ? "security" : "full" }));
     } catch { /* recording is best-effort — the audit itself already ran */ }
-    return { projectDir, basalCost, growthDelta, stack, sonarFindings, webperf, osvFindings, semgrepFindings, circularDeps, deadExports, injectionFindings, infraFindings, aiSlop };
+    return { projectDir, basalCost, growthDelta, stack, sonarFindings, webperf, osvFindings, semgrepFindings, circularDeps, deadExports, injectionFindings, infraFindings, aiSlop, envKeys };
   }
 
   /**
@@ -176,7 +185,7 @@ export class AuditRole extends AgentRole {
     const context = typeof input === "object" ? input?.context || null : null;
     const dimensions = typeof rawDimensions === "string" ? parseDimensions(rawDimensions) : rawDimensions;
 
-    const { projectDir, basalCost, growthDelta, stack, sonarFindings, webperf, osvFindings, semgrepFindings, circularDeps, deadExports } = deterministicCtx;
+    const { projectDir, basalCost, growthDelta, stack, sonarFindings, webperf, osvFindings, semgrepFindings, circularDeps, deadExports, envKeys } = deterministicCtx;
 
     const provider = this.resolveProvider();
     const agent = this.createAgentInstance(provider);
@@ -217,6 +226,7 @@ export class AuditRole extends AgentRole {
           semgrepFindings: semgrepFindings?.available ? semgrepFindings : undefined,
           circularDeps: circularDeps?.available ? circularDeps : undefined,
           deadExports: deadExports?.available ? deadExports : undefined,
+          envKeys: envKeys?.available ? envKeys : undefined,
           provider
         },
         summary: buildSummary(parsed),