karajan-code 4.39.0 → 4.41.0

package/src/harden/sentinel/sentinel-shell.mjs

@@ -106,5 +106,22 @@ export const optionValues = (cmd, names) => shellSegments(cmd).flatMap((words) =
   return eq > 0 && names.includes(w.slice(0, eq)) ? [w.slice(eq + 1)] : [];
 }));
 
+/**
+ * KJC-BUG-0268: the words of a simple command without its redirections (2>&1,
+ * >file, < file, >> log...) and the operand a detached operator takes. A
+ * redirection is where output goes, never an argument of the command.
+ * @param {string[]} words
+ */
+export const withoutRedirections = (words) => {
+  const rest = [];
+  let operand = false; // the previous word was a bare operator: this one is its target
+  for (const word of words) {
+    if (operand) operand = false;
+    else if (!/^\d*[<>]/.test(word)) rest.push(word);
+    else operand = /^\d*(<{1,3}|>>?|>[|&])$/.test(word);
+  }
+  return rest;
+};
+
 /** Short flags of a cluster stop at "e": the rest is -e's value (-fen = -f -e n). */
 export const shortOpts = (a) => (/^-[a-zA-Z]/.test(a) ? a.slice(1).split("e")[0] : "");

package/src/harden/sentinel/sessionstart.mjs

@@ -2,10 +2,12 @@
 // kj sentinel SessionStart hook (KJC-TSK-0918, ADR 0014), managed by `kj harden`.
 // A compaction takes exactly what the agent needs most: the rules it read at the
 // start. After a compaction or a resume, this gives them back, short, with the
-// state of the session. A new session gets nothing: CLAUDE.md already brings them.
+// state of the session. A new session gets no rules: CLAUDE.md already brings them.
 // Copied byte for byte into .karajan/harness; never fails a session (exit 0).
 import process from "node:process";
-import { CARD, branchOf, load, pendingMoves } from "./sentinel-lib.mjs";
+import { spawnSync } from "node:child_process";
+import { CARD, ROOT, branchOf, load, pendingMoves } from "./sentinel-lib.mjs";
+import { rulesDriftNotice } from "./sentinel-rules.mjs";
 
 const RULES = [
   "1. Karajan gobierna y se le obedece: no cambies políticas, configuración de gates ni exclusiones para pasar un gate. Si uno parece injusto, díselo a tu usuario o usa kj report-issue.",
@@ -24,13 +26,20 @@ process.stdin.on("data", (d) => { raw += d; });
 process.stdin.on("end", () => {
   try {
     const { session_id: sid = "default", source } = JSON.parse(raw || "{}");
-    if (source !== "compact" && source !== "resume") process.exit(0);
-    const branch = branchOf() || "?";
-    const card = CARD.exec(branch)?.[0]?.toUpperCase() ?? "ninguna en la rama";
-    const pending = pendingMoves(load().sessions?.[sid]).map((p) => `${p.card ?? "?"} (PR #${p.pr})`);
-    const state = `Estado: rama ${branch}, card ${card}${pending.length ? `; cards mergeadas sin mover: ${pending.join(", ")}` : ""}.`;
-    const context = ["Karajan (reglas que la compactación se lleva):", ...RULES, state].join("\n");
-    process.stdout.write(JSON.stringify({ hookSpecificOutput: { hookEventName: "SessionStart", additionalContext: context } }));
+    // KJC-TSK-0949: an MD changed and its compiled rules fell behind. Said at
+    // every start, a new session included: that one gets this line and nothing else.
+    const drift = rulesDriftNotice({ root: ROOT, run: spawnSync });
+    const lines = [];
+    if (source === "compact" || source === "resume") {
+      const branch = branchOf() || "?";
+      const card = CARD.exec(branch)?.[0]?.toUpperCase() ?? "ninguna en la rama";
+      const pending = pendingMoves(load().sessions?.[sid]).map((p) => `${p.card ?? "?"} (PR #${p.pr})`);
+      const unmoved = pending.length ? "; cards mergeadas sin mover: " + pending.join(", ") : "";
+      lines.push("Karajan (reglas que la compactación se lleva):", ...RULES, `Estado: rama ${branch}, card ${card}${unmoved}.`);
+    }
+    if (drift) lines.push(`Karajan: ${drift}`);
+    if (lines.length === 0) process.exit(0);
+    process.stdout.write(JSON.stringify({ hookSpecificOutput: { hookEventName: "SessionStart", additionalContext: lines.join("\n") } }));
   } catch { /* never fails a session */ }
   process.exit(0);
 });

package/src/harden/sentinel-hooks.js

@@ -92,11 +92,22 @@ export const boardGate = (sid, pend) => {
   }
   return { blocking: pend, carried: [] };
 };
+// KJC-BUG-0265: on the base branch what counts is work still there (the session's
+// files dirty, or local commits the remote does not have), not the ledger: after a
+// merged PR and a sync of main the ledger stays full while the base holds nothing.
+// Anything git cannot answer (no upstream, odd path) counts as work: fail closed.
+const baseHoldsWork = (files) => {
+  if (files.some((f) => !/^[A-Za-z0-9._/-]+$/.test(f))) return true;
+  try {
+    if (execSync("git status --porcelain -- " + files.join(" "), { cwd: ROOT, stdio: ["ignore", "pipe", "ignore"] }).toString().trim()) return true;
+    return execSync("git rev-list @{u}..HEAD", { cwd: ROOT, stdio: ["ignore", "pipe", "ignore"] }).toString().trim() !== "";
+  } catch { return true; }
+};
 export const violations = (s, branch, pending = pendingMoves(s)) => {
   const v = pending.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");
+  if (BASE_BRANCHES.has(branch)) { if (baseHoldsWork(s.edited_sources)) 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");
   return v;
@@ -492,7 +503,9 @@ process.stdin.on("end", () => {
       }
       // KJC-TSK-0920 (SNT-E): policies, gate settings and exclusions are the human's,
       // like the supervisor: a session does not loosen the rules that govern it.
-      if ([".karajan/policy.yml", ".karajan/kj.config.yml", ".ragignore"].includes(relT) || relT.endsWith("/.ragignore")) {
+      // .karajan/rules.yml (KJC-TSK-0947, ADR 0016): the compiled rules are the user's to approve.
+      // .karajan/rules.local.yml (KJC-TSK-0954, ADR 0017): the same rules, the ones from private sources.
+      if ([".karajan/policy.yml", ".karajan/kj.config.yml", ".karajan/rules.yml", ".karajan/rules.local.yml", ".ragignore"].includes(relT) || relT.endsWith("/.ragignore")) {
         console.error("karajan sentinel: " + relT + " es configuracion de gobierno (politicas, gates, exclusiones): la cambia tu usuario, no la sesion. Si un gate te parece injusto, proponselo a tu usuario o usa kj report-issue." + doc("governance"));
         process.exit(2);
       }
@@ -1127,6 +1140,9 @@ const SCRIPT_BODIES = {
   "sentinel-bash-write.mjs": readFileSync(new URL("./sentinel/sentinel-bash-write.mjs", import.meta.url), "utf8"),
   "sentinel-reminders.mjs": readFileSync(new URL("./sentinel/sentinel-reminders.mjs", import.meta.url), "utf8"),
   "sessionstart.mjs": readFileSync(new URL("./sentinel/sessionstart.mjs", import.meta.url), "utf8"),
+  // KJC-TSK-0946 (ADR 0016): the rules gate and its hook, for every tool call.
+  "sentinel-rules.mjs": readFileSync(new URL("./sentinel/sentinel-rules.mjs", import.meta.url), "utf8"),
+  "pretooluse-rules.mjs": readFileSync(new URL("./sentinel/pretooluse-rules.mjs", import.meta.url), "utf8"),
 };
 
 /**
@@ -1316,6 +1332,9 @@ export function installSentinelHooks({ projectDir = process.cwd(), logger = cons
     entries: [
       { event: "PreToolUse", matcher: "Write|Edit|MultiEdit|NotebookEdit", script: "pretooluse-sentinel.mjs" },
       { event: "PreToolUse", matcher: "Bash", script: "pretooluse-sentinel.mjs" },
+      // KJC-TSK-0946 (ADR 0016): no matcher. The rules of the MD files are checked
+      // before EVERY tool call, MCP ones included.
+      { event: "PreToolUse", script: "pretooluse-rules.mjs" },
       { event: "PostToolUse", matcher: "Write|Edit|MultiEdit|NotebookEdit", script: "posttooluse.mjs" },
       // KJC-TSK-0765 board-sync: the merge (Bash) and the tracker move (MCP
       // update_card) are observed AFTER the fact — found live: with only the
@@ -1329,6 +1348,8 @@ export function installSentinelHooks({ projectDir = process.cwd(), logger = cons
       // KJC-TSK-0918 (ADR 0014): the critical rules back after a compaction or a resume.
       { event: "SessionStart", matcher: "compact", script: "sessionstart.mjs" },
       { event: "SessionStart", matcher: "resume", script: "sessionstart.mjs" },
+      // KJC-TSK-0949: a new session hears of MD rules with no gate, and nothing else.
+      { event: "SessionStart", matcher: "startup", script: "sessionstart.mjs" },
     ],
   });
   return { scripts: [lib, post, stop, pre], wired, deferred };

package/src/harden/supervisor-commit.js

@@ -7,11 +7,13 @@
  */
 import { execFileSync } from "node:child_process";
 import { createHash } from "node:crypto";
-import { closeSync, existsSync, openSync, readFileSync, readSync, readdirSync, writeFileSync } from "node:fs";
+import { existsSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
 import { basename, join } from "node:path";
 
 import { recordGateDecision } from "../policy/decisions.js";
 import { readIdentity } from "../identity/store.js";
+import { ensureGateTrackable } from "../review/gate-gitignore.js";
+import { confirmHuman, refuseAgentSession } from "./human-act.js";
 import { isPhoneEnrolled, requestPhoneSignature } from "./phone-sign.js";
 
 export const PROVENANCE_FILE = ".karajan/supervisor-provenance.json";
@@ -26,43 +28,7 @@ const HARNESS_PREFIX = ".karajan/harness/";
 
 const sha256 = (abs) => createHash("sha256").update(readFileSync(abs)).digest("hex");
 
-// Capa 3 del acto humano (test adversarial del 6-sep): un pty falso engaña a
-// isTTY y `env -u` borra CLAUDECODE, pero el kj que lanza un agente DESCIENDE
-// de su proceso — y eso está en /proc lo falsifique quien lo falsifique.
-const AGENT_PROC = /claude|codex|copilot|gemini|opencode|\bagy\b/i;
-export function agentAncestry({ pid = process.pid, readProc = null, maxDepth = 40 } = {}) {
-  const read = readProc || ((p) => {
-    const stat = readFileSync(`/proc/${p}/stat`, "utf8");
-    const ppid = Number(stat.slice(stat.lastIndexOf(")") + 2).split(" ")[1]);
-    let cmd = "";
-    try { cmd = readFileSync(`/proc/${p}/cmdline`).toString("utf8").replaceAll("\0", " "); } catch { /* gone */ }
-    return { ppid, cmd };
-  });
-  let cur = pid;
-  for (let i = 0; i < maxDepth && cur > 1; i += 1) {
-    let info;
-    try { info = read(cur); } catch { return { agent: false, unknown: true }; }
-    if (info?.cmd && AGENT_PROC.test(info.cmd)) return { agent: true, match: info.cmd.slice(0, 80) };
-    if (!Number.isFinite(info?.ppid) || info.ppid === cur) break;
-    cur = info.ppid;
-  }
-  return { agent: false };
-}
-
-// Lee la respuesta del nonce de la TTY REAL del proceso (no de stdin, que un
-// atacante alimenta por pipe): /dev/tty solo existe con terminal de control.
-function defaultConfirm(nonce) {
-  process.stdout.write(`harden --commit: teclea "${nonce}" para confirmar que eres humano: `);
-  try {
-    const buf = Buffer.alloc(64);
-    const fd = openSync("/dev/tty", "r");
-    const n = readSync(fd, buf, 0, 64);
-    closeSync(fd);
-    return buf.toString("utf8", 0, n).trim();
-  } catch {
-    return null;
-  }
-}
+const ACT = "harden --commit";
 
 /** Ficheros de supervisor TRACKEADOS con cambios (staged o no). */
 /**
@@ -106,17 +72,8 @@ export async function commitSupervisorRegeneration({
   deps = {},
 }) {
   // El cauce es humano por diseño (ADR 0009): una sesión de agente no lo usa.
-  if (env.CLAUDECODE || env.KJ_NON_INTERACTIVE === "1" || !tty) {
-    throw new Error(
-      "harden --commit es un acto humano: córrelo desde TU terminal, fuera de una sesión de agente (ADR 0009)",
-    );
-  }
-  const anc = agentAncestry(deps.ancestry ?? {});
-  if (anc.agent) {
-    throw new Error(
-      `harden --commit es un acto humano y este proceso desciende de un agente (${anc.match}) — ni con pty falso ni con el entorno limpio (ADR 0009)`,
-    );
-  }
+  // Capas 1 a 3 (entorno, tty y ascendencia de procesos): src/harden/human-act.js.
+  refuseAgentSession(ACT, { env, tty, ancestry: deps.ancestry ?? {} });
   const run = gitFn || ((args) => execFileSync("git", args, { cwd: projectDir, encoding: "utf8" }));
   // KJC-BUG-0244 (grebla #958): el commit sellado solo lleva el supervisor, pero
   // un stage ajeno se quedaba en esta rama y el siguiente commit caía aquí con la
@@ -129,13 +86,7 @@ export async function commitSupervisorRegeneration({
   }
   // Capa 4 (test adversarial 6-sep: un huérfano a init con pty falso y
   // prompts a ciegas llegó hasta aquí): nonce aleatorio tecleado de vuelta.
-  // Un alimentador ciego no conoce el código; automatizar su lectura exige
-  // un driver expect — premeditación inequívoca, no un descuido.
-  const nonce = createHash("sha256").update(String(Math.random())).digest("hex").slice(0, 6);
-  const answer = (deps.confirm ?? defaultConfirm)(nonce);
-  if (answer !== nonce) {
-    throw new Error(`harden --commit: confirmación humana fallida (esperaba "${nonce}") — ADR 0009`);
-  }
+  confirmHuman(ACT, deps.confirm);
   const drift = supervisorDrift({ projectDir, gitFn: run });
   // La provenance describe SIEMPRE el estado COMPLETO del supervisor (cazado
   // en el primer estreno real: un sello parcial pisaba al anterior y dejaba
@@ -207,6 +158,12 @@ export async function commitSupervisorRegeneration({
     files: hashed,
     who: provenance.who,
   });
+  // KJC-BUG-0264: un bloque .karajan antiguo en .gitignore dejaba la procedencia
+  // fuera de git y el add fallaba. Se completa antes el bloque canónico (la misma
+  // migración que kj review --install-gate); el cambio queda para una PR normal.
+  if ((await ensureGateTrackable(projectDir)).changed) {
+    logger.info?.("harden --commit: .gitignore completado con el bloque canónico de .karajan (la procedencia viaja con el repo); súbelo en una PR");
+  }
   // Por DIRECTORIO, no por fichero: un rename ya staged deja la ruta vieja
   // sin existir y `git add -- <vieja>` falla; `-A` sobre el dir del
   // supervisor versiona altas, cambios, borrados y renombrados por igual.

package/src/mcp/handlers/run-handler.js

@@ -132,6 +132,11 @@ export async function handleRunDirect(a, server, extra) {
 
   const projectDir = await resolveProjectDir(server, a.projectDir);
   const runLog = createRunLog(projectDir);
+  // KJC-BUG-0250: two starts racing past the session check, only one takes the lock.
+  if (!runLog.owned) {
+    runLog.close();
+    return failPayload("A pipeline is already running for this project. Wait for it to complete or use kj_status to check progress.");
+  }
   runLog.logText(`[kj_run] started — task="${a.task.slice(0, 80)}..."`);
 
   const emitter = new EventEmitter();

package/src/mcp/sovereignty-guard.js

@@ -7,6 +7,7 @@
 
 import fs from "node:fs";
 import path from "node:path";
+import { isPidAlive } from "../utils/run-log.js";
 
 /** Parameters that the host AI is allowed to pass through without restriction. */
 const ALLOWED_PARAMS = new Set([
@@ -31,33 +32,33 @@ const ALLOWED_PARAMS = new Set([
 
 const MIN_ITERATIONS = 1;
 const MAX_ITERATIONS = 10;
-const ACTIVE_SESSION_THRESHOLD_MS = 60_000;
+
 
 /**
  * Check if a pipeline is already running for this project.
- * Looks at .kj/run.log modification time.
+ * KJC-BUG-0250 (#1897, #1892): the fact is the run lock (.kj/run.lock) held by
+ * a live process. The old signal, a recent write to run.log, also fired after
+ * a run that failed in preflight or any short command, blocking the next run.
  *
  * @param {string} projectDir - Project root directory
  * @returns {{ active: boolean, message?: string }}
  */
 export function checkActiveSession(projectDir) {
   if (!projectDir) return { active: false };
-  const logPath = path.join(projectDir, ".kj", "run.log");
+  let holder;
   try {
-    const stat = fs.statSync(logPath);
-    const ageMs = Date.now() - stat.mtimeMs;
-    if (ageMs < ACTIVE_SESSION_THRESHOLD_MS) {
-      return {
-        active: true,
-        message:
-          "A pipeline is already running for this project. " +
-          "Wait for it to complete or use kj_status to check progress.",
-      };
-    }
+    holder = JSON.parse(fs.readFileSync(path.join(projectDir, ".kj", "run.lock"), "utf8"));
   } catch {
-    // File doesn't exist or can't be read — no active session
+    return { active: false }; // no lock, or unreadable: nothing holds the project
   }
-  return { active: false };
+  if (!isPidAlive(holder?.pid)) return { active: false }; // stale: its process is gone
+  const since = holder.startedAt ? ", since " + holder.startedAt : "";
+  return {
+    active: true,
+    message:
+      `A pipeline is already running for this project (pid ${holder.pid}${since}). ` +
+      "Wait for it to complete or use kj_status to check progress.",
+  };
 }
 
 /**

package/src/orchestrator/preflight-checks.js

@@ -19,6 +19,7 @@ import {
   resolveSonarHost,
   resolveSonarTokenAsync,
   resolveSonarCredentials,
+  sonarTokenSources,
 } from "../sonar/config-resolver.js";
 import { saveSonarToken } from "../sonar/credentials.js";
 import { withDocLink } from "../utils/doc-links.js";
@@ -106,7 +107,7 @@ async function checkSonarAuth(config) {
   const { user: adminUser, passwords } = await resolveSonarCredentials(config);
 
   if (!adminUser || passwords.length === 0) {
-    return { name: "sonar-auth", ok: false, detail: "No Sonar token or admin credentials configured. Set KJ_SONAR_TOKEN, configure sonarqube.token in kj.config.yml, or save credentials in ~/.karajan/sonar-credentials.json." };
+    return { name: "sonar-auth", ok: false, detail: `No Sonar token or admin credentials found. Looked in: ${sonarTokenSources()}. With a custom KARAJAN_HOME/KJ_HOME, the token must be there (or pass kjHome).` };
   }
 
   for (const password of passwords) {
@@ -327,8 +328,8 @@ export async function runPreflightChecks({ config, logger, emitter, eventBase, r
       result.ok = false;
       result.errors.push({
         check: "sonar-auth",
-        message: "SonarQube is running but no authentication token is configured.",
-        fix: withDocLink("Fix: run 'kj init' to configure it, or set KJ_SONAR_TOKEN env var, or add sonarqube.token to ~/.karajan/kj.config.yml.", "sonar_token")
+        message: `SonarQube is running but no authentication token was found. Looked in: ${sonarTokenSources()}.`,
+        fix: withDocLink("Fix: run 'kj init' to configure it, or set KJ_SONAR_TOKEN env var, or add sonarqube.token to the kj.config.yml of the active Karajan home.", "sonar_token")
       });
       logger.error("Preflight: Sonar auth failed");
     }

package/src/policy/supervisor-verify.js

@@ -9,6 +9,7 @@ import { lstatSync, readFileSync } from "node:fs";
 import { resolve, sep } from "node:path";
 
 import { renderCanonicalHook } from "../harden/harden-engine.js";
+import { provenanceSignature } from "../harden/phone-sign.js";
 import { canonicalHarnessBody } from "../harden/sentinel-hooks.js";
 import { PROVENANCE_FILE } from "../harden/supervisor-commit.js";
 
@@ -35,6 +36,9 @@ export function verifiedSupervisorFiles({ projectDir, trackedOnly = false }) {
   if (gen.globalHooksDir != null && !SAFE_DIR.test(gen.globalHooksDir)) {
     return { files: new Set(), reason: "globalHooksDir no verificable en la provenance" };
   }
+  // KJC-TSK-0964 (ADR 0018): with a roster, an unsigned or mis-signed seal backs nothing.
+  const signed = provenanceSignature({ projectDir, provenance: prov });
+  if (!signed.ok) return { files: new Set(), reason: signed.reason };
   const ok = new Set();
   const unjudgeable = new Set();
   // KJC-BUG-0259 (user's decision, option A): history is judged with the kj of
@@ -89,7 +93,7 @@ export function verifiedSupervisorFiles({ projectDir, trackedOnly = false }) {
   // maquina que sello, porque los guardias no viajan con el repo (0212).
   const judged = (e) => ok.has(e.file) || unjudgeable.has(e.file);
   const complete = ok.size > 0 && entries.every((e) => typeof e?.file === "string" && judged(e));
-  return { files: ok, complete, unjudgeable };
+  return { files: ok, complete, unjudgeable, signed: signed.required };
 }
 
 /**
@@ -109,9 +113,15 @@ export function liftSealedSupervisorViolations({ projectDir, violations, tracked
     && (sealed.files.has(v.file) || (v.file === PROVENANCE_FILE && sealed.complete === true));
   const kept = violations.filter((v) => !liftable(v));
   const unjudged = sealed.unjudgeable?.size ?? 0;
+  const notes = [
+    ...(unjudged > 0 ? [`${unjudged} guardia(s) del sello no existen en este checkout y no se han podido comprobar aquí`] : []),
+    // KJC-TSK-0964: what the signature did or did not prove is said, never assumed.
+    ...(sealed.signed === false ? ["proyecto sin padrón de firmantes: el sello no lleva firma verificable y su garantía es solo local"] : []),
+    ...(kept.length === violations.length && sealed.reason ? [sealed.reason] : []),
+  ];
   return {
     violations: kept,
     lifted: violations.length - kept.length,
-    ...(unjudged > 0 ? { note: `${unjudged} guardia(s) del sello no existen en este checkout y no se han podido comprobar aquí` } : {}),
+    ...(notes.length > 0 ? { note: notes.join("; ") } : {}),
   };
 }

package/src/privacy/scan.js

@@ -91,6 +91,13 @@ const CONTEXT_DISCARDS = [
   // (Visa 4, Mastercard 2/5, Amex 3, Discover 6), so a card number cannot
   // occupy that slot at any length.
   { type: "tracker-id", re: /\b[A-Z]{2,6}-1[6-9]\d{11}-\d{1,4}\b/g },
+  // KJC-BUG-0270: a rule id of the inventory (ADR 0016) is `R-` and 10 hex chars
+  // of a hash, and .karajan/rules.yml is versioned: an id with a long run of
+  // digits warned as a phone on every commit. Only the WHOLE shape is discarded:
+  // exactly ten lowercase hex chars with at least one letter. An all-digit id
+  // (about 1 in 100) still warns, because nothing tells it apart from a phone
+  // written after "R-"; the allow list is the way out for that one.
+  { type: "rule-id", re: /\bR-(?=\d*[a-f])[0-9a-f]{10}\b/g },
 ];
 
 /**

package/src/review/gate-gitignore.js

@@ -32,6 +32,14 @@ export const CONTRACT_BLOCK = [
   // ADR 0009 (KJC-BUG-0161): la procedencia del supervisor VIAJA con el
   // repo — es lo que CI verifica. Cazado en el primer harden --commit real.
   "!.karajan/supervisor-provenance.json",
+  // KJC-BUG-0269: the policy is what CI evaluates; its anchor and the signers
+  // roll are what CI verifies. Ignored, a new project ran every clone with none.
+  "!.karajan/policy.yml",
+  "!.karajan/policy-anchor.json",
+  "!.karajan/supervisor-signers.json",
+  // ADR 0016 (KJC-TSK-0947): the rules of the MD files compiled into gates are
+  // governance the whole team inherits, like the hooks.
+  "!.karajan/rules.yml",
 ];
 
 /**

package/src/rules/approval-view.js

@@ -0,0 +1,54 @@
+/**
+ * What the human reads before approving compiled rules (KJC-TSK-0962, MDR-F3,
+ * ADR 0017), in the order of what can hurt. The agent the rules will watch wrote
+ * the proposal, so a weak compilation must not hide among a hundred rules:
+ *
+ *   1. what loses or changes force against what is approved today;
+ *   2. what has no effective gate (judgment and out-of-scope block nothing);
+ *   3. the deterministic gates;
+ *   4. the approved rules that leave.
+ */
+const GATE = "deterministic";
+
+const compiled = (rule) => {
+  if (rule.kind === "out-of-scope") return `reason: ${rule.reason}`;
+  // KJC-TSK-0973: why a judgment rule takes no condition is read next to it.
+  const why = rule.reason ? "  (" + rule.reason + ")" : "";
+  return `when: ${JSON.stringify(rule.when)}${why}`;
+};
+
+/** How a proposed rule weakens or changes the approved one, or "" when it does not. */
+function weakening(rule, approved) {
+  if (approved?.kind !== GATE) return "";
+  if (rule.kind !== GATE) return `was ${GATE}, now ${rule.kind}`;
+  return JSON.stringify(rule.when) === JSON.stringify(approved.when) ? "" : "condition changed";
+}
+
+/**
+ * @param {object[]} proposed the rules of a checked proposal
+ * @param {object[]} current the rules approved today (both files)
+ * @param {Set<string>} local ids that go to the unversioned file
+ * @param {{versioned: string, unversioned: string}} files the two rules files, as shown
+ * @returns {string[]} lines, ready to print
+ */
+export function approvalView(proposed, current, local, files) {
+  const approved = new Map(current.map((rule) => [rule.id, rule]));
+  const where = (rule) => (local.has(rule.id) ? `${files.unversioned}, not versioned` : files.versioned);
+  const shown = (rule) => [`${rule.id}  ${rule.kind}  → ${where(rule)}`, `    ${rule.text}`, `    ${compiled(rule)}`];
+  const weakened = proposed.map((rule) => ({ rule, how: weakening(rule, approved.get(rule.id)) })).filter(({ how }) => how);
+  const seen = new Set(weakened.map(({ rule }) => rule.id));
+  const rest = proposed.filter((rule) => !seen.has(rule.id));
+  const ungated = rest.filter((rule) => rule.kind !== GATE);
+  const gates = rest.filter((rule) => rule.kind === GATE);
+  const ids = new Set(proposed.map((rule) => rule.id));
+  const leaving = current.filter((rule) => !ids.has(rule.id));
+  const block = (title, lines) => (lines.length ? [title, ...lines, ""] : []);
+  return [
+    ...block(`⚠ ${weakened.length} rule(s) LOSE or CHANGE force against what is approved today:`, weakened.flatMap(({ rule, how }) => [
+      `${rule.id}  ${how}  → ${where(rule)}`, `    ${rule.text}`, `    was: ${compiled(approved.get(rule.id))}`, `    now: ${compiled(rule)}`,
+    ])),
+    ...block(`${ungated.length} rule(s) with NO effective gate: nothing is blocked on them.`, ungated.flatMap(shown)),
+    ...block(`${gates.length} ${GATE} gate(s):`, gates.flatMap(shown)),
+    ...block(`${leaving.length} rule(s) LEAVE:`, leaving.map((rule) => `${rule.id}  ${rule.text ?? ""}`)),
+  ];
+}

package/src/rules/compiled.js

@@ -0,0 +1,111 @@
+/**
+ * Compiled rules, the format (KJC-TSK-0938, MDR-B, ADR 0016). A rule from the MD
+ * files, compiled into a condition over a tool call: which tool, which arguments.
+ * The operators are a closed set, so a rule is auditable and runs with no model.
+ * `judgment` rules carry no condition to evaluate: the judge reads them.
+ * `out-of-scope` rules are no gate at all: a decision, with its reason.
+ *
+ * An invalid file yields no rules (a rule that lies is worse than none).
+ */
+import yaml from "js-yaml";
+
+const ID = /^R-[0-9a-f]{10}$/;
+const OUT_OF_SCOPE = "out-of-scope";
+const KINDS = ["deterministic", "judgment", OUT_OF_SCOPE];
+const OPERATORS = ["equals", "in", "matches", "exists", "gt", "lt"];
+
+export const isObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+/** The tool globs a rule names (`when.tool` is one glob or a list). */
+export const toolsOf = (when) => [when?.tool].flat().filter((t) => typeof t === "string" && t);
+
+// The format is closed at every level: a key nobody reads would be a condition
+// the author believes in and the evaluator ignores.
+const RULE_KEYS = ["id", "source", "text", "kind", "when", "message", "examples", "reason"];
+const GATE_KEYS = ["when", "message", "examples"];
+const WHEN_KEYS = ["tool", "all", "any"];
+const CONDITION_KEYS = ["arg", "days_from", ...OPERATORS];
+const unknownKeys = (obj, known) => (isObject(obj) ? Object.keys(obj).filter((k) => !known.includes(k)) : []);
+
+const isRegex = (source) => {
+  try { new RegExp(source); return typeof source === "string"; } catch { return false; }
+};
+/** What each operator takes; anything else invalidates the condition. */
+const OPERAND = {
+  equals: () => true,
+  in: Array.isArray,
+  matches: isRegex,
+  exists: (v) => typeof v === "boolean",
+  gt: Number.isFinite,
+  lt: Number.isFinite,
+};
+
+/** A dotted path into the tool input: non-empty segments (`updates.status`). */
+const isPath = (v) => typeof v === "string" && /^[\w-]+(\.[\w-]+)*$/.test(v);
+
+function conditionErrors(cond) {
+  if (!isObject(cond) || !isPath(cond.arg)) return ["a condition needs an `arg` (dotted path into the tool input)"];
+  const where = `condition on ${cond.arg}`;
+  const unknown = unknownKeys(cond, CONDITION_KEYS);
+  if (unknown.length) return [`${where}: unknown key ${unknown.join(", ")} (operators: ${OPERATORS.join(", ")})`];
+  const ops = OPERATORS.filter((op) => op in cond);
+  if (ops.length !== 1) return [`${where}: exactly one operator of ${OPERATORS.join(", ")}`];
+  const [op] = ops;
+  if (!OPERAND[op](cond[op])) return [`${where}: invalid operand for ${op}${op === "matches" ? " (not a valid regex)" : ""}`];
+  if ("days_from" in cond && (!isPath(cond.days_from) || !["gt", "lt"].includes(op))) {
+    return [`${where}: days_from names another argument and compares with gt or lt`];
+  }
+  return [];
+}
+
+/**
+ * KJC-TSK-0948: a rule about how the agent thinks or answers has no tool call to
+ * gate. It is declared with the reason, and carries nothing to evaluate.
+ */
+function outOfScopeErrors(rule) {
+  const errors = [];
+  if (typeof rule.reason !== "string" || !rule.reason.trim()) errors.push(`an ${OUT_OF_SCOPE} rule needs a reason (text)`);
+  const gate = GATE_KEYS.filter((k) => k in rule);
+  if (gate.length) errors.push(`an ${OUT_OF_SCOPE} rule takes no ${gate.join(", ")}: there is no tool call to gate`);
+  return errors;
+}
+
+function ruleErrors(rule) {
+  if (!isObject(rule)) return ["a rule is a mapping"];
+  const errors = [];
+  const unknown = [...unknownKeys(rule, RULE_KEYS), ...unknownKeys(rule.when, WHEN_KEYS).map((k) => `when.${k}`)];
+  if (unknown.length) errors.push(`unknown key ${unknown.join(", ")}`);
+  if (!ID.test(String(rule.id))) errors.push("id must be an inventory id (R- and 10 hex chars)");
+  if (!KINDS.includes(rule.kind)) errors.push(`kind must be one of ${KINDS.join(", ")}`);
+  const notText = ["source", "text", "message"].filter((k) => k in rule && typeof rule[k] !== "string");
+  if (notText.length) errors.push(`${notText.join(", ")} must be text`);
+  if (rule.kind === OUT_OF_SCOPE) return [...errors, ...outOfScopeErrors(rule)];
+  // KJC-TSK-0973: any rule may say why it is compiled as it is. A judgment rule,
+  // why it takes no condition; a deterministic one, where its condition stops
+  // (what breaks the rest is not in the arguments of one call).
+  if ("reason" in rule && (typeof rule.reason !== "string" || !rule.reason.trim())) errors.push("reason is text");
+  // `examples` are tool calls: the command that runs them checks their shape (kj rules test).
+  const tools = [rule.when?.tool].flat();
+  if (tools.length === 0 || tools.some((t) => typeof t !== "string" || !t)) errors.push("when.tool names the tool: a glob, or a list where every item is one");
+  const lists = [rule.when?.all, rule.when?.any].filter((list) => list !== undefined);
+  if (lists.some((list) => !Array.isArray(list))) errors.push("when.all and when.any are lists of conditions");
+  else for (const cond of lists.flat()) errors.push(...conditionErrors(cond));
+  return errors;
+}
+
+/**
+ * @param {string} text the content of .karajan/rules.yml
+ * @returns {{rules: object[], errors: string[]}} no rules when there is any error
+ */
+export function parseRules(text) {
+  let doc;
+  try { doc = yaml.load(text); } catch (err) { return { rules: [], errors: [`invalid YAML: ${err.message.split("\n")[0]}`] }; }
+  if (!isObject(doc) || doc.version !== 1) return { rules: [], errors: ["version must be 1"] };
+  const unknown = unknownKeys(doc, ["version", "rules"]);
+  if (unknown.length) return { rules: [], errors: [`unknown key ${unknown.join(", ")}`] };
+  if (!Array.isArray(doc.rules)) return { rules: [], errors: ["rules must be a list"] };
+  const errors = doc.rules.flatMap((rule, i) => ruleErrors(rule).map((e) => `rules[${i}] (${rule?.id ?? "no id"}): ${e}`));
+  // One rule, one entry: with two, which one a reader sees is an accident of order.
+  const ids = doc.rules.map((rule) => rule?.id).filter((id) => typeof id === "string");
+  errors.push(...new Set(ids.filter((id, i) => ids.indexOf(id) !== i).map((id) => `${id}: repeated, a rule is compiled once`)));
+  return { rules: errors.length ? [] : doc.rules, errors };
+}

package/src/rules/coverage.js

@@ -0,0 +1,23 @@
+/**
+ * Rule coverage (KJC-TSK-0941, MDR-E, ADR 0016): the inventory of the MD files
+ * against the compiled rules, by id. The id hashes the rule's text, so a rule
+ * whose text changed in its MD is a new rule with no gate, and what was compiled
+ * for the old text is stale: it is in no MD any more.
+ */
+
+export const NO_GATE = "none";
+
+/**
+ * @param {{id: string}[]} inventory what listRules returned
+ * @param {{id: string, kind: string}[]} compiled what parseRules accepted
+ * @returns {{rows: object[], stale: object[]}} one row per inventory rule, with
+ *   its `status` (the kind it was compiled to, or "none"); and the stale compiled rules
+ */
+export function coverage(inventory, compiled) {
+  const kinds = new Map(compiled.map((rule) => [rule.id, rule.kind]));
+  const rows = new Map();
+  for (const rule of inventory) {
+    if (!rows.has(rule.id)) rows.set(rule.id, { ...rule, status: kinds.get(rule.id) ?? NO_GATE });
+  }
+  return { rows: [...rows.values()], stale: compiled.filter((rule) => !rows.has(rule.id)) };
+}