karajan-code 4.29.1 → 4.31.0

package/src/commands/init.js

@@ -1,3 +1,4 @@
+import { execFileSync } from "node:child_process";
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
@@ -743,6 +744,25 @@ export async function resolveConfigScope({ flags, interactive }) {
   return { configPath: getConfigPath(), scope: "global" };
 }
 
+/**
+ * KJC-BUG-0187: the enforcement gates live in git hooks, so a project without
+ * a repo gets no harness at all. Init creates it, exactly like `kj run` does
+ * (src/orchestrator/config-init.js), and reports failure instead of carrying
+ * on half-installed. No seed commit: that is the bootstrap commit's job.
+ */
+export function ensureGitRepo({ projectDir, logger, gitFn = null }) {
+  if (isGitRepo(projectDir)) return true;
+  const run = gitFn || ((args) => execFileSync("git", args, { cwd: projectDir, stdio: "pipe" }));
+  try {
+    run(["init"]);
+    logger?.info?.("Initialized git repository (no seed commit) — the quality harness needs it");
+    return true;
+  } catch (err) {
+    logger?.warn?.(`git init failed: ${err.message}`);
+    return false;
+  }
+}
+
 export async function initCommand({ logger, flags = {} }) {
   // AB-B (KJC-TSK-0656): with --json, stdout is a machine contract — every
   // human log moves to stderr so the only stdout line is the summary object.
@@ -888,20 +908,29 @@ export async function initCommand({ logger, flags = {} }) {
     }
   }
 
-  await setupSonarQube(config, logger, { interactive });
+  // KJC-BUG-0184: the container is a heavy side effect — opt-out: --no-sonar.
+  // Only the bootstrap is skipped; the review gate still demands Sonar.
+  const skipSonar = flags?.noSonar === true || flags?.sonar === false;
+  if (skipSonar) {
+    logger.info("SonarQube container not started (--no-sonar). Start it later with 'kj sonar start'.");
+  } else {
+    await setupSonarQube(config, logger, { interactive });
+  }
   await scaffoldCiGateway(config, flags, logger);
 
   // Install the quality harness (git hooks, lint/format/commit config, CI
   // quality gates, agent guidelines) through the SAME engine as `kj harden`,
   // so init and harden never drift. Opt-out: --no-harden. Needs a git repo.
   const skipHarden = flags?.noHarden === true || flags?.harden === false;
+  let hardened = false;
   if (skipHarden) {
     logger.info("Quality harness skipped (--no-harden).");
-  } else if (isGitRepo(process.cwd())) {
+  } else if (ensureGitRepo({ projectDir: process.cwd(), logger })) {
     logger.info("Installing quality harness (kj harden)...");
     await hardenCommand({ projectDir: process.cwd(), logger });
+    hardened = true;
   } else {
-    logger.info("Not a git repository — run `kj harden` after `git init` to add the quality harness.");
+    logger.warn("Quality harness NOT installed: this is not a git repository and `git init` failed — Karajan's guarantees live in git hooks. Fix git, then run `kj harden`.");
   }
 
   // Persist any changes setupSonarQube made (token, etc.) back to disk.
@@ -925,7 +954,7 @@ export async function initCommand({ logger, flags = {} }) {
   if (flags.json) {
     console.log(JSON.stringify({
       ok: true, configPath, scope, interactive,
-      skipped: ["ollama", "rtk", "squeezr", "qmd", "harden"].filter((t) => flags[t] === false),
+      skipped: ["ollama", "rtk", "squeezr", "qmd", "sonar", "harden"].filter((t) => flags[t] === false),
     }));
     return;
   }
@@ -933,7 +962,11 @@ export async function initCommand({ logger, flags = {} }) {
   // Clear close so a first-time user knows setup finished and what to do next,
   // instead of being left at the end of a wall of detection logs (KJC-BUG-0088).
   logger.info("");
-  logger.info("✓ Karajan is set up in this project.");
+  // KJC-BUG-0187: never declare a setup that did not happen. Without the
+  // harness there are no gates, and saying otherwise is the worst outcome.
+  logger.info(hardened || skipHarden
+    ? "✓ Karajan is set up in this project."
+    : "⚠ Karajan is set up EXCEPT the quality harness — without it there are no gates.");
   logger.info('  Next:  kj run "describe what to build or fix"');
   logger.info("  More:  kj --help   ·   kj doctor (check your setup)");
 }

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/harness-hooks.js

@@ -16,6 +16,8 @@ const SCRIPT_BODY = `#!/usr/bin/env node
 // kj tool gate (KJC-TSK-0710) — managed by \`kj harden\`. Exit 2 blocks the
 // tool call (stderr explains why); anything unexpected fails OPEN (exit 0)
 // so a gate bug never bricks the session.
+import console from "node:console";
+import process from "node:process";
 import { existsSync } from "node:fs";
 let raw = "";
 process.stdin.on("data", (d) => { raw += d; });

package/src/harden/hook-templates.js

@@ -60,8 +60,9 @@ function chainToGlobal(hook, globalHooksDir) {
 function baseBranchGuard(baseBranch) {
   if (!baseBranch) return [];
   return [
-    "# Branch-first guard — the base branch only moves via PR.",
-    'if [ "$KJ_ALLOW_BASE_COMMIT" != "1" ]; then',
+    "# Branch-first guard — the base branch only moves via PR. KJC-BUG-0186:",
+    "# the bootstrap commit is exempt, there is no commit to branch from yet.",
+    'if [ "$KJ_ALLOW_BASE_COMMIT" != "1" ] && git rev-parse --verify HEAD >/dev/null 2>&1; then',
     '  current_branch=$(git symbolic-ref --short HEAD 2>/dev/null || echo "")',
     `  if [ "$current_branch" = "${baseBranch}" ]; then`,
     `    echo 'kj harden: direct commits on ${baseBranch} are not allowed — create a branch and open a PR (KJ_ALLOW_BASE_COMMIT=1 to override)'; exit 1`,

package/src/harden/sentinel-hooks.js

@@ -28,6 +28,7 @@ export function resolveSentinelRoot(dir = process.cwd()) {
 const LIB_BODY = `// kj sentinel shared lib (KJC-TSK-0714) — managed by \`kj harden\`.
 // Single source for every sentinel script: state, branch, classification,
 // violations, and escape recording.
+import console from "node:console";
 import { readFileSync, writeFileSync } from "node:fs";
 import { execSync, spawnSync } from "node:child_process";
 import { dirname, join } from "node:path";
@@ -71,9 +72,18 @@ export const foreignLane = (targetDir) => {
 // the tracker. The method does not advance until the board is true.
 export const pendingMoves = (s) => (s && Array.isArray(s.pending_moves) ? s.pending_moves : []);
 export const pendingText = (p) => (p.card ? p.card : "card sin identificar") + " (PR #" + p.pr + ") mergeada sin mover en el tracker — muevela a To Validate / Fixed con sus commits (update_card del PG o kj hu move)";
+// KJC-BUG-0185: bootstrap phase = the repo has no commit yet. There is no base
+// branch to protect and no coverage to demand over a tree that does not exist,
+// and \`git diff HEAD\` cannot even run. The phase is a verifiable FACT, never a
+// flag, and it ends at the first commit.
+export const bootstrapPhase = () => {
+  try { execSync("git rev-parse --verify HEAD", { cwd: ROOT, stdio: ["ignore", "ignore", "ignore"] }); return false; }
+  catch { return true; }
+};
 export const violations = (s, branch) => {
   const v = pendingMoves(s).map(pendingText);
   if (!s || !(s.edited_sources || []).length) return v;
+  if (bootstrapPhase()) return v;
   if (BASE_BRANCHES.has(branch)) v.push("Fuentes editadas en la rama base '" + branch + "' — crea una rama: git checkout -b feat/<CARD-ID>-descripcion");
   else if (branch && !CARD.test(branch)) v.push("La rama '" + branch + "' no referencia ninguna card — usa feat/<CARD-ID>-descripcion (y una card VIVA en el board)");
   if (!(s.edited_tests || []).length && sessionAddsCode(s)) v.push("Fuentes editadas sin tocar un solo test (" + s.edited_sources.join(", ") + ") — escribe o actualiza el test que prueba el cambio");
@@ -120,10 +130,11 @@ const POST_BODY = `#!/usr/bin/env node
 // kj sentinel state writer (KJC-TSK-0713) — managed by \`kj harden\`.
 // Records deterministic method facts per session; never blocks, never fails
 // a tool call (PostToolUse, always exit 0).
+import process from "node:process";
 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"];
+import { 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", "KJ_ALLOW_NO_RAG"];
 let raw = "";
 process.stdin.on("data", (d) => { raw += d; });
 process.stdin.on("end", () => {
@@ -146,6 +157,44 @@ 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.
+    // KJC-BUG-0190: an index with nothing in it (a brand new project) answers
+    // every question with silence, so the gate would demand what no query can
+    // deliver. kj says so explicitly, in both its human and json forms.
+    const EMPTY_INDEX = /No chunks indexed yet|"empty"\\s*:\\s*true/;
+    const recordRag = (query, sources, answer = "") => {
+      const state = load();
+      const s = session(state, sid);
+      s.at = Date.now();
+      if (EMPTY_INDEX.test(String(answer))) s.rag_index_empty = true;
+      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 || "")))), parts.map((p) => String(p?.text || "")).join(String.fromCharCode(10)));
+      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 +220,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()))), out);
+        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.
@@ -230,6 +291,8 @@ const STOP_BODY = `#!/usr/bin/env node
 // one with its remediation). Fails OPEN on corrupt state, git errors, or
 // after 3 unresolved blocks — a sentinel bug never bricks the session — and
 // the fail-open is recorded in the state. \`--status\` prints, never blocks.
+import console from "node:console";
+import process from "node:process";
 import { spawnSync } from "node:child_process";
 import { readFileSync } from "node:fs";
 import { homedir } from "node:os";
@@ -250,7 +313,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);
@@ -337,6 +400,8 @@ const PRETOOL_BODY = `#!/usr/bin/env node
 // before the damage, not in the post-mortem. Exit 2 blocks (stderr says the
 // remediation); read-only tools are never wired here; every honored escape
 // is recorded as an auditable event. Fails OPEN on anything unexpected.
+import console from "node:console";
+import process from "node:process";
 import { dirname, join, relative, resolve } from "node:path";
 import { existsSync, readFileSync, realpathSync, statSync } from "node:fs";
 import { spawnSync } from "node:child_process";
@@ -660,7 +725,7 @@ process.stdin.on("end", () => {
         // LITERALES (tambien dentro de sustituciones) los escanea el bucle
         // de tokens de abajo; el residuo (expansion anidada en segmentos
         // runner) queda documentado como en la regla de ficheros PROTECTED.
-        if (/>{1,2}[ \\t]*["']?[\\$\`]/.test(cmd)) {
+        if (/>{1,2}[ \\t]*["']?[$\`]/.test(cmd)) {
           if (escOn("KJ_ALLOW_CROSS_LANE")) { recordEscape(sid, "KJ_ALLOW_CROSS_LANE", tool); }
           else {
             console.error("karajan sentinel: redireccion con destino tras variable/sustitucion — el guard de carriles no puede verificarlo (MONO-0); usa una ruta LITERAL (o KJ_ALLOW_CROSS_LANE=1, queda registrado)." + doc("cross-lane"));
@@ -735,7 +800,7 @@ process.stdin.on("end", () => {
         }
         const SAFE_EXP_SEG = /^([A-Za-z_][A-Za-z0-9_]*=[^ \\t]*[ \\t]*)*((npm|pnpm|yarn|vitest|jest|kj|gh|echo|printf|true|test)\\b|git[ \\t](?![^\\n]*(-C[ \\t]|--git-dir|--work-tree)))[^;|&\\n]*$|^[A-Za-z_][A-Za-z0-9_]*=[^;|&\\n]*$/;
         const segs = cmd.split(/&&|\\|\\||[;|\\n]/).map((s) => s.trim()).filter(Boolean);
-        if (!segs.every((s) => !/[\\$]/.test(s) || SAFE_EXP_SEG.test(s))) {
+        if (!segs.every((s) => !/[$]/.test(s) || SAFE_EXP_SEG.test(s))) {
           if (escOn("KJ_ALLOW_CROSS_LANE")) { recordEscape(sid, "KJ_ALLOW_CROSS_LANE", tool); }
           else {
             console.error("karajan sentinel: expansion de shell en una herramienta generica de fichero/interprete — el objetivo no es verificable por el guard de carriles (MONO-0); usa rutas LITERALES o un runner del toolchain (o KJ_ALLOW_CROSS_LANE=1, queda registrado)." + doc("cross-lane"));
@@ -835,6 +900,28 @@ 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.
+        // KJC-BUG-0190: with nothing indexed, no query can cover anything —
+        // the gate asks for kj rag index instead of denying the impossible.
+        const covered = rel.startsWith("..") || hits.includes(rel) || hits.some((h) => dirOf(h) === dirOf(rel)) || (fresh && (rs.rag_queries || []).length > 0) || rs.rag_index_empty === true;
+        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/identity/bootstrap.js

@@ -28,7 +28,7 @@ export async function ensureIdentity({ projectDir, logger = null, deps = {} }) {
     const why = !gh || !email ? "no active gh session or git email" : "non-interactive run";
     const pending = `identity not declared for this clone (${why}) — run: ${hint}`;
     logger?.warn?.(`kj identity: ${pending}`);
-    return { declared: false, identity: null, pending };
+    return { declared: false, identity: null, pending, command: hint };
   }
 
   const wizard = (deps.makeWizard || createWizard)();
@@ -37,7 +37,7 @@ export async function ensureIdentity({ projectDir, logger = null, deps = {} }) {
     if (!ok) {
       const pending = `identity not declared (declined) — run: ${hint}`;
       logger?.warn?.(`kj identity: ${pending}`);
-      return { declared: false, identity: null, pending };
+      return { declared: false, identity: null, pending, command: hint };
     }
   } finally {
     wizard.close();

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 : [] };
+}