karajan-code 4.39.0 → 4.40.0

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,49 @@
+/**
+ * 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) => (rule.kind === "out-of-scope" ? `reason: ${rule.reason}` : `when: ${JSON.stringify(rule.when)}`);
+
+/** 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,108 @@
+/**
+ * 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)];
+  if ("reason" in rule) errors.push(`reason belongs to ${OUT_OF_SCOPE} rules only`);
+  // `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)) };
+}

package/src/rules/evaluate.js

@@ -0,0 +1,60 @@
+/**
+ * The deterministic evaluator of compiled rules (KJC-TSK-0944, MDR-B1, ADR 0016):
+ * one tool call against the rules parseRules accepted, with no model.
+ *
+ * A rule says when to deny. A condition over an argument the call does not
+ * carry, or cannot be read as the operator needs (a date, a number), does not
+ * hold: the rule states a fact about the call, and that fact is not there.
+ */
+import { isObject, toolsOf } from "./compiled.js";
+
+const DAY_MS = 86_400_000;
+
+/** A tool glob: `*` stands for any run of characters, the rest is literal. */
+const toolMatches = (glob, tool) => {
+  const literal = glob.split("*").map((part) => part.replaceAll(/[.+?^${}()|[\]\\]/g, String.raw`\$&`));
+  return new RegExp(`^${literal.join(".*")}$`).test(String(tool));
+};
+
+/** The value at a dotted path of the tool input, own properties only. */
+const at = (input, dotted) =>
+  dotted.split(".").reduce((node, key) => (isObject(node) && Object.hasOwn(node, key) ? node[key] : undefined), input);
+
+/** Calendar days (UTC) from one date to another: the same day is 0, whatever the hour. */
+const daysBetween = (from, to) => Math.floor(Date.parse(to) / DAY_MS) - Math.floor(Date.parse(from) / DAY_MS);
+
+function holds(cond, input) {
+  let value = at(input, cond.arg);
+  const present = value !== undefined && value !== null;
+  if ("exists" in cond) return present === cond.exists;
+  if (!present) return false;
+  if ("days_from" in cond) value = daysBetween(at(input, cond.days_from), value);
+  if ("equals" in cond) return value === cond.equals;
+  if ("in" in cond) return cond.in.includes(value);
+  if ("matches" in cond) return typeof value === "string" && new RegExp(cond.matches).test(value);
+  if (typeof value !== "number" || Number.isNaN(value)) return false;
+  return "gt" in cond ? value > cond.gt : value < cond.lt;
+}
+
+const applies = (rule, tool, input) =>
+  toolsOf(rule.when).some((glob) => toolMatches(glob, tool))
+  && (rule.when.all ?? []).every((cond) => holds(cond, input))
+  && (!rule.when.any?.length || rule.when.any.some((cond) => holds(cond, input)));
+
+/**
+ * @param {object[]} rules what parseRules returned
+ * @param {{tool: string, input?: object}} call
+ * @returns {{decision: "allow"} | {decision: "deny", rule_id: string, source: string|null, text: string|null, message: string}}
+ */
+export function evalRules(rules, { tool, input }) {
+  const args = isObject(input) ? input : {};
+  const hit = rules.find((rule) => rule.kind === "deterministic" && applies(rule, tool, args));
+  if (!hit) return { decision: "allow" };
+  return {
+    decision: "deny",
+    rule_id: hit.id,
+    source: hit.source ?? null,
+    text: hit.text ?? null,
+    message: hit.message ?? hit.text ?? `rule ${hit.id}`,
+  };
+}

package/src/rules/inventory.js

@@ -0,0 +1,118 @@
+/**
+ * Rule inventory (KJC-TSK-0937, MDR-A, ADR 0016). Every rule written in the MD
+ * files that govern a session, with a stable id, its literal text and where it
+ * lives, so each one can get a gate and a deny can cite it.
+ *
+ * A rule is a markdown block (a list item with the lines that continue it, or a
+ * paragraph), outside code blocks, that carries a normative marker. The id hashes
+ * the normalized text, so a rule keeps its id when it moves or is wrapped anew.
+ */
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+const NORMATIVE = /\b(nunca|siempre|prohibido|obligatorio|jam[aá]s|never|always|must|forbidden|required|do not|don't)\b/i;
+
+// Emphasis delimiters only: a marker opens after a blank and closes before one (or
+// punctuation), so snake_case names and globs (docs/**/*.md) keep their characters.
+const stripEmphasis = (text) => text
+  .replaceAll(/(^|[\s(])\*\*(\S[^*]*)\*\*(?=[\s).,;:!?]|$)/g, "$1$2")
+  .replaceAll(/(^|[\s(])__(\S[^_]*)__(?=[\s).,;:!?]|$)/g, "$1$2")
+  .replaceAll(/(^|[\s(])\*(\S[^*]*)\*(?=[\s).,;:!?]|$)/g, "$1$2")
+  .replaceAll(/(^|[\s(])_(\S[^_]*)_(?=[\s).,;:!?]|$)/g, "$1$2");
+
+const LIST_ITEM = /^\s*(?:[-*+]|\d+[.)])\s+/;
+
+const HELD =""; // private-use char: stands in for a code span while emphasis is stripped
+
+/**
+ * The text of a markdown line without its list marker, emphasis or code ticks.
+ * What sits inside a code span is kept as written, whatever characters it holds.
+ */
+const plain = (line) => {
+  const spans = [];
+  const held = line
+    .replace(LIST_ITEM, "")
+    .replaceAll(/`([^`]*)`/g, (_m, code) => `${HELD}${spans.push(code) - 1}${HELD}`);
+  return stripEmphasis(held)
+    .replaceAll(new RegExp(`${HELD}(\\d+)${HELD}`, "g"), (_m, n) => spans[Number(n)])
+    .replaceAll(/\s+/g, " ")
+    .trim();
+};
+
+const ruleId = (text) => "R-" + createHash("sha256").update(text.toLowerCase()).digest("hex").slice(0, 10);
+
+/**
+ * @param {string} markdown
+ * @param {string} file
+ * @returns {{id: string, text: string, file: string, line: number}[]}
+ */
+export function extractRules(markdown, file) {
+  const rules = [];
+  let fence = null; // the open code fence (``` or ~~~, any length), closed by one as long
+  let comment = false; // inside an HTML comment that has not closed yet
+  let block = null; // the list item or paragraph being read: { line, parts }
+  const flush = () => {
+    const text = block ? plain(block.parts.join(" ")) : "";
+    if (text && NORMATIVE.test(text)) rules.push({ id: ruleId(text), text, file, line: block.line });
+    block = null;
+  };
+  const lines = markdown.split("\n");
+  // A memory file's YAML frontmatter is metadata, not rules.
+  const frontmatterEnd = lines[0]?.trim() === "---" ? lines.indexOf("---", 1) : -1;
+  lines.forEach((raw, i) => {
+    if (i <= frontmatterEnd) return;
+    const mark = /^\s*(`{3,}|~{3,})/.exec(raw)?.[1];
+    if (mark && !fence) { flush(); fence = mark; return; }
+    if (mark && mark[0] === fence[0] && mark.length >= fence.length && raw.trim() === mark) { fence = null; return; }
+    if (fence) return;
+    if (comment || /^\s*<!--/.test(raw)) { flush(); comment = !raw.includes("-->"); return; }
+    if (!raw.trim() || /^\s*#/.test(raw) || /^\s*\|/.test(raw)) { flush(); return; }
+    // KJC-BUG-0271: the unit is the markdown block. A list marker opens a new
+    // one; any other line continues the block it follows (a wrapped rule).
+    if (LIST_ITEM.test(raw)) flush();
+    block ??= { line: i + 1, parts: [] };
+    block.parts.push(raw.trim());
+  });
+  flush();
+  return rules;
+}
+
+/**
+ * The MD files that govern a session in projectDir (KJC-TSK-0942): its CLAUDE.md
+ * and AGENTS.md, the global ~/.claude/CLAUDE.md and the project's feedback memories.
+ * @param {string} projectDir
+ * @param {{home?: string}} [opts]
+ */
+export function ruleSources(projectDir, { home = os.homedir() } = {}) {
+  // Claude Code names a project's folder after its path, every non-alphanumeric char as "-".
+  const memory = path.join(home, ".claude", "projects", path.resolve(projectDir).replaceAll(/[^A-Za-z0-9]/g, "-"), "memory");
+  let feedback = [];
+  try {
+    feedback = fs.readdirSync(memory).filter((f) => /^feedback_.*\.md$/.test(f)).sort().map((f) => path.join(memory, f));
+  } catch { /* no memories for this project */ }
+  return [
+    path.join(projectDir, "CLAUDE.md"),
+    path.join(projectDir, "AGENTS.md"),
+    path.join(home, ".claude", "CLAUDE.md"),
+    ...feedback,
+  ].filter((f) => fs.existsSync(f));
+}
+
+/** Whether an MD file is part of the project, and so as public as the repo is. */
+export const inProject = (file, projectDir) => {
+  const rel = path.relative(projectDir, file);
+  return !rel.startsWith("..") && !path.isAbsolute(rel);
+};
+
+/** A source as a rules file can carry it: from the project's root, or from `~`. */
+export const shownSource = (file, projectDir, home = os.homedir()) => {
+  if (inProject(file, projectDir)) return path.relative(projectDir, file);
+  return inProject(file, home) ? path.join("~", path.relative(home, file)) : file;
+};
+
+/** Every rule of every governing MD file, in source order. */
+export function listRules(projectDir, opts = {}) {
+  return ruleSources(projectDir, opts).flatMap((file) => extractRules(fs.readFileSync(file, "utf8"), file));
+}