karajan-code 4.39.0 → 4.40.0

package/src/commands/rules.js

@@ -0,0 +1,169 @@
+/**
+ * kj rules eval (KJC-TSK-0943, MDR-B2, ADR 0016): the hook's contract, the same
+ * as `kj policy eval --strict`. One tool call in, a JSON verdict out, exit
+ * 0 = allow, 2 = deny, 1 = it could not be evaluated (invalid or unreadable
+ * rules.yml, unreadable input).
+ */
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+import { isObject, parseRules } from "../rules/compiled.js";
+import { coverage, NO_GATE } from "../rules/coverage.js";
+import { evalRules } from "../rules/evaluate.js";
+import { inProject, listRules, shownSource } from "../rules/inventory.js";
+
+export const RULES_FILE = path.join(".karajan", "rules.yml");
+/** ADR 0017: rules whose source is outside the project. Never versioned. */
+export const LOCAL_RULES_FILE = path.join(".karajan", "rules.local.yml");
+
+/**
+ * The compiled rules of a project. A file that does not exist is no rules; a
+ * file that exists and cannot be read is an error (rules silently off would be
+ * every call allowed).
+ */
+function loadRulesFile(projectDir, file) {
+  let text;
+  try {
+    text = fs.readFileSync(path.resolve(projectDir, file), "utf8");
+  } catch (err) {
+    if (err.code === "ENOENT") return { present: false, rules: [], errors: [] };
+    return { present: true, rules: [], errors: [`cannot read ${file}: ${err.code || err.message}`] };
+  }
+  return { present: true, ...parseRules(text) };
+}
+
+/**
+ * With a `file`, that file alone (a proposal). Without one, what governs the
+ * project (KJC-TSK-0954, ADR 0017): the versioned rules and the local ones, as
+ * one rule set. An error in either leaves no rules; a rule lives in one file.
+ */
+export function loadRules(projectDir, file) {
+  if (file) return loadRulesFile(projectDir, file);
+  const loaded = [RULES_FILE, LOCAL_RULES_FILE].map((name) => ({ name, ...loadRulesFile(projectDir, name) }));
+  const errors = loaded.flatMap(({ name, errors: found }) => found.map((e) => `${name}: ${e}`));
+  const rules = loaded.flatMap((part) => part.rules);
+  const ids = rules.map((rule) => rule.id);
+  errors.push(...new Set(ids.filter((id, i) => ids.indexOf(id) !== i).map((id) => `${id}: in both ${RULES_FILE} and ${LOCAL_RULES_FILE}, a rule lives in one file`)));
+  return { present: loaded.some((part) => part.present), rules: errors.length ? [] : rules, errors };
+}
+
+const failed = (...errors) => ({ code: 1, output: { errors } });
+
+/**
+ * KJC-TSK-0946: `--input -` reads the tool input from stdin. The hook passes it
+ * that way, because a large Write does not fit in one argument. Read as a
+ * stream: a synchronous read of a pipe fails (EAGAIN) once the input is large.
+ */
+export async function readToolInput(flag, stdin = process.stdin) {
+  if (flag !== "-") return flag;
+  let text = "";
+  for await (const chunk of stdin) text += chunk;
+  return text;
+}
+
+/** @returns {{code: 0|1|2, output: object}} */
+export function rulesEval({ projectDir, tool, input = "{}" }) {
+  if (typeof tool !== "string" || !tool) return failed("--tool is required");
+  let args;
+  try { args = JSON.parse(input); } catch { return failed("--input must be valid JSON"); }
+  if (!isObject(args)) return failed("--input must be a JSON object (the tool input)");
+  const { rules, errors } = loadRules(projectDir);
+  if (errors.length) return failed(...errors);
+  const output = evalRules(rules, { tool, input: args });
+  return { code: output.decision === "deny" ? 2 : 0, output };
+}
+
+const isCall = (c) => isObject(c) && typeof c.tool === "string" && c.tool !== "" && (c.input === undefined || isObject(c.input));
+const isCallList = (list) => Array.isArray(list) && list.length > 0 && list.every(isCall);
+
+/** What a rule's examples say against the rule itself, alone. */
+function exampleFailures(rule) {
+  const { deny, allow } = isObject(rule.examples) ? rule.examples : {};
+  if (!isCallList(deny) || !isCallList(allow)) return [`${rule.id}: needs examples.deny and examples.allow, each a list of { tool, input } calls`];
+  const verdict = (call) => evalRules([rule], call).decision;
+  return [
+    ...deny.flatMap((call, i) => (verdict(call) === "deny" ? [] : [`${rule.id}: deny example #${i + 1} was allowed`])),
+    ...allow.flatMap((call, i) => (verdict(call) === "deny" ? [`${rule.id}: allow example #${i + 1} was denied`] : [])),
+  ];
+}
+
+/**
+ * kj rules test (KJC-TSK-0945, MDR-B3): every deterministic rule against its own
+ * deny/allow examples. A rule with no examples is untested, and that fails too.
+ * @returns {{code: 0|1, lines: string[]}}
+ */
+export function rulesTest({ projectDir }) {
+  const { present, rules, errors } = loadRules(projectDir);
+  if (errors.length) return { code: 1, lines: errors.map((e) => `✗ ${e}`) };
+  if (!present) return { code: 0, lines: [`no ${RULES_FILE}: nothing to test`] };
+  const tested = rules.filter((rule) => rule.kind === "deterministic");
+  const failures = tested.flatMap(exampleFailures);
+  if (failures.length) return { code: 1, lines: failures.map((f) => `✗ ${f}`) };
+  const examples = tested.reduce((n, rule) => n + rule.examples.deny.length + rule.examples.allow.length, 0);
+  return { code: 0, lines: [`✓ ${tested.length} rule(s), ${examples} example(s)`] };
+}
+
+export const PROPOSAL_FILE = path.join(".karajan", "rules.proposed.yml");
+
+/**
+ * What a proposed rule says against the MD files: it is one of their rules, word
+ * for word, and its source is where they write it (KJC-TSK-0961: the source
+ * decides whether a rule is versioned, so the proposal does not get to choose it).
+ * @param {object} rule
+ * @param {object[]|undefined} written every place the inventory found this rule
+ * @param {(file: string) => string} shown
+ */
+function inventoryFailures(rule, written, shown) {
+  if (!written) return [`${rule.id}: no rule of the MD files has this id (kj rules list)`];
+  const [first] = written;
+  if (rule.text !== first.text) return [`${rule.id}: text is not what the MD says (${first.file}:${first.line}): ${first.text}`];
+  const sources = written.map((found) => shown(found.file));
+  return sources.includes(rule.source) ? [] : [`${rule.id}: source is not where the MD files write it (${sources.join(", ")})`];
+}
+
+/**
+ * kj rules check (KJC-TSK-0950, MDR-D1): a proposal of compiled rules proves
+ * itself before a human reads it. Every rule is one of the MD files and cites
+ * its literal text; every deterministic one passes its own examples.
+ * With `text`, that content is checked and the file is not read again: whoever
+ * installs a proposal installs the bytes that were checked.
+ * `local` holds the ids written in no file of the project: those are not versioned.
+ * @returns {{code: 0|1, lines: string[], rules?: object[], local?: Set<string>}}
+ */
+export function rulesCheck({ projectDir, file = PROPOSAL_FILE, home = os.homedir(), text }) {
+  const { present, rules, errors } = text === undefined ? loadRules(projectDir, file) : { present: true, ...parseRules(text) };
+  if (!present) return { code: 1, lines: [`✗ no ${file}: nothing to check`] };
+  if (errors.length) return { code: 1, lines: errors.map((e) => `✗ ${e}`) };
+  const inventory = Map.groupBy(listRules(projectDir, { home }), (rule) => rule.id);
+  const shown = (found) => shownSource(found, projectDir, home);
+  const failures = rules.flatMap((rule) => [
+    ...inventoryFailures(rule, inventory.get(rule.id), shown),
+    ...(rule.kind === "deterministic" ? exampleFailures(rule) : []),
+  ]);
+  if (failures.length) return { code: 1, lines: failures.map((f) => `✗ ${f}`) };
+  const count = (kind) => rules.filter((rule) => rule.kind === kind).length;
+  const local = new Set(rules.filter((rule) => !inventory.get(rule.id).some((found) => inProject(found.file, projectDir))).map((rule) => rule.id));
+  return { code: 0, rules, local, lines: [`✓ ${rules.length} rule(s) hold: ${count("deterministic")} deterministic, ${count("judgment")} judgment, ${count("out-of-scope")} out of scope`] };
+}
+
+/**
+ * kj rules coverage (KJC-TSK-0941, MDR-E): every rule of the governing MD files
+ * against rules.yml. `strict` fails while a rule has no gate or a compiled rule
+ * is stale, so a rule nobody decided about cannot go unseen.
+ * @returns {{code: 0|1, lines: string[], output?: object}}
+ */
+export function rulesCoverage({ projectDir, strict = false, home }) {
+  const { rules, errors } = loadRules(projectDir);
+  if (errors.length) return { code: 1, lines: errors.map((e) => `✗ ${e}`) };
+  const { rows, stale } = coverage(listRules(projectDir, home ? { home } : {}), rules);
+  const count = (status) => rows.filter((row) => row.status === status).length;
+  const counts = { deterministic: count("deterministic"), judgment: count("judgment"), "out-of-scope": count("out-of-scope"), [NO_GATE]: count(NO_GATE), stale: stale.length };
+  const ungated = rows.filter((row) => row.status === NO_GATE);
+  const lines = [
+    ...ungated.map((r) => `✗ no gate  ${r.id}  ${r.file}:${r.line}  ${r.text}`),
+    ...stale.map((r) => `✗ stale    ${r.id}  ${r.source ?? "?"}  ${r.text ?? ""} (its text is in no MD any more: compile it again)`),
+    `${rows.length} rule(s): ${counts.deterministic} deterministic, ${counts.judgment} judgment, ${counts["out-of-scope"]} out of scope, ${ungated.length} with no gate; ${stale.length} stale`,
+  ];
+  return { code: strict && ungated.length + stale.length > 0 ? 1 : 0, lines, output: { counts, rows, stale } };
+}

package/src/config/loader.js

@@ -194,10 +194,32 @@ function stripRuntimeOnlyKeys(config) {
   return out;
 }
 
+// KJC-BUG-0253: a project's .karajan/kj.config.yml is versioned with the repo,
+// so the SonarQube credentials never go there; they live in the global config
+// (~/.karajan), where the token bootstrap already saves them.
+const SECRET_KEYS = ["token", "admin_password"];
+const isProjectConfig = (configPath) =>
+  path.basename(configPath) === "kj.config.yml"
+  && path.basename(path.dirname(configPath)) === ".karajan"
+  && path.resolve(configPath) !== path.resolve(getConfigPath());
+
+function stripSecrets(config) {
+  if (!config?.sonarqube || typeof config.sonarqube !== "object") return { out: config, stripped: [] };
+  const stripped = SECRET_KEYS.filter((k) => config.sonarqube[k] != null);
+  if (!stripped.length) return { out: config, stripped };
+  const sonarqube = { ...config.sonarqube };
+  for (const k of stripped) delete sonarqube[k];
+  return { out: { ...config, sonarqube }, stripped: stripped.map((k) => `sonarqube.${k}`) };
+}
+
+/** @returns {Promise<{strippedSecrets: string[]}>} the secret keys kept out of a project config */
 export async function writeConfig(configPath, config) {
   await ensureDir(path.dirname(configPath));
-  const sanitized = stripRuntimeOnlyKeys(config);
+  let sanitized = stripRuntimeOnlyKeys(config);
+  let strippedSecrets = [];
+  if (isProjectConfig(configPath)) ({ out: sanitized, stripped: strippedSecrets } = stripSecrets(sanitized));
   await fs.writeFile(configPath, yaml.dump(sanitized, { lineWidth: 120 }), "utf8");
+  return { strippedSecrets };
 }
 
 // Declarative mappings for applyRunOverrides to reduce cognitive complexity.

package/src/environment/adr.js

@@ -8,6 +8,9 @@ import fs from "node:fs/promises";
 import path from "node:path";
 
 const ADR_DIR = path.join(".karajan", "adrs");
+// KJC-BUG-0272: whoever records a decision proposes it. Accepting is the user's:
+// they set `Status: accepted` in the file. Born accepted, nobody had decided.
+const NEW_STATUS = "proposed";
 
 const slugify = (t) => t.toLowerCase().replaceAll(/[^a-z0-9]+/g, "-").replaceAll(/^-|-$/g, "").slice(0, 60);
 
@@ -34,12 +37,12 @@ export async function addAdr(projectDir, { title, decision, context = "", conseq
   const file = path.join(ADR_DIR, `${String(number).padStart(4, "0")}-${slugify(title)}.md`);
   const body = [
     `# ${title}`, "",
-    `Status: accepted`, `Date: ${new Date().toISOString().slice(0, 10)}`, "",
+    `Status: ${NEW_STATUS}`, `Date: ${new Date().toISOString().slice(0, 10)}`, "",
     ...(context ? ["## Context", "", context, ""] : []),
     "## Decision", "", decision, "",
     ...(consequences ? ["## Consequences", "", consequences, ""] : []),
   ].join("\n");
   await fs.mkdir(path.join(projectDir, ADR_DIR), { recursive: true });
   await fs.writeFile(path.join(projectDir, file), body);
-  return { number, file, title };
+  return { number, file, title, status: NEW_STATUS };
 }

package/src/harden/config-templates.js

@@ -42,6 +42,9 @@ export const COMMITLINT_BODY = [
 // project has no eslint config of its own.
 export const ESLINT_BODY = [
   "export default [",
+  // KJC-BUG-0254 (#1902): third-party and generated code is not the project's to
+  // lint (a vendored tf.min.js gave 6607 false no-var errors).
+  '  { ignores: ["vendor/**", "dist/**", "build/**", "coverage/**", ".scannerwork/**", "**/*.min.{js,mjs,cjs}"] },',
   "  {",
   '    files: ["**/*.{js,mjs,cjs,ts,mts,cts,jsx,tsx}"],',
   '    languageOptions: { ecmaVersion: 2025, sourceType: "module" },',

package/src/harden/human-act.js

@@ -0,0 +1,70 @@
+/**
+ * The layers that make a command a HUMAN act (ADR 0009), out of the supervisor's
+ * seal so that other human-only commands use the very same ones (KJC-TSK-0951).
+ *
+ *  1-2. the environment and the terminal: an agent session declares itself;
+ *  3.   the process ancestry: a kj launched by an agent DESCENDS from it, and
+ *       that is in /proc whoever fakes the pty or cleans the environment;
+ *  4.   a random nonce typed back, read from the real controlling terminal.
+ */
+import { randomBytes } from "node:crypto";
+import { closeSync, openSync, readFileSync, readSync } from "node:fs";
+
+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 };
+}
+
+/** Layers 1 to 3: throws when `what` runs inside an agent session. */
+export function refuseAgentSession(what, { env = process.env, tty = process.stdout.isTTY, ancestry = {} } = {}) {
+  if (env.CLAUDECODE || env.KJ_NON_INTERACTIVE === "1" || !tty) {
+    throw new Error(`${what} es un acto humano: córrelo desde TU terminal, fuera de una sesión de agente (ADR 0009)`);
+  }
+  const anc = agentAncestry(ancestry);
+  if (anc.agent) {
+    throw new Error(`${what} es un acto humano y este proceso desciende de un agente (${anc.match}) — ni con pty falso ni con el entorno limpio (ADR 0009)`);
+  }
+}
+
+// The answer comes from the process's REAL tty (not stdin, which an attacker
+// feeds through a pipe): /dev/tty only exists with a controlling terminal.
+function readTty(what, nonce) {
+  process.stdout.write(`${what}: 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;
+  }
+}
+
+/**
+ * Layer 4: a random nonce typed back. A blind feeder does not know the code;
+ * automating its reading takes an expect driver, which is premeditation.
+ * @param {string} what
+ * @param {(nonce: string) => string|null} [confirm] test seam
+ */
+export function confirmHuman(what, confirm = null) {
+  const nonce = randomBytes(3).toString("hex");
+  const answer = confirm ? confirm(nonce) : readTty(what, nonce);
+  if (answer !== nonce) throw new Error(`${what}: confirmación humana fallida (esperaba "${nonce}") — ADR 0009`);
+}

package/src/harden/phone-sign.js

@@ -132,6 +132,32 @@ export function verifyPhoneSignature({ payload, signature, publicKey }) {
   return verify(null, Buffer.from(payload, "utf8"), key, Buffer.from(signature, "base64"));
 }
 
+/**
+ * KJC-TSK-0964 (HUM-A, ADR 0018): the seal's signature, checked where the
+ * machine that made it has no say. With signers in the versioned roster, a
+ * provenance must be signed by one of them over the very files it declares.
+ * With no roster nothing is required: the guarantee is local only.
+ * @returns {{required: boolean, ok: boolean, reason?: string}}
+ */
+export function provenanceSignature({ projectDir, provenance }) {
+  const roster = readSigners({ projectDir });
+  if (roster.length === 0) return { required: false, ok: true };
+  const fail = (reason) => ({ required: true, ok: false, reason });
+  const sig = provenance?.signature;
+  if (typeof sig?.signature !== "string" || typeof sig?.signer !== "string") return fail("el padrón tiene firmantes y la procedencia no lleva firma");
+  if (!roster.includes(sig.signer)) return fail("la clave que firma la procedencia no está en el padrón");
+  // The files as the phone signed them: {file, sha256}, a deletion with no hash.
+  // A provenance is read from the project: a malformed one is rejected, it does not crash.
+  const entries = Array.isArray(provenance.files) ? provenance.files : [];
+  if (entries.some((entry) => typeof entry?.file !== "string")) return fail("la procedencia declara ficheros mal formados");
+  const files = entries.map(({ file, sha256 }) => ({ file, sha256: sha256 ?? "" }));
+  let good = false;
+  try {
+    good = verifyPhoneSignature({ payload: canonicalPayload({ ...sig, files }), signature: sig.signature, publicKey: sig.signer });
+  } catch { /* a malformed key or signature is a signature that does not verify */ }
+  return good ? { required: true, ok: true } : fail("la firma no corresponde a los ficheros que la procedencia declara");
+}
+
 /**
  * Publica la petición en Firestore, enseña QR + URL, pollea el doc y verifica
  * la firma. Sin fallbacks silenciosos: red caída o HTTP no-ok ⇒ throw. Firma

package/src/harden/sentinel/pretooluse-rules.mjs

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+// kj sentinel rules hook (KJC-TSK-0946, MDR-C2, ADR 0016), managed by `kj harden`.
+// PreToolUse with NO matcher: every tool call, MCP ones included, passes the rules
+// of the MD files (compiled into .karajan/rules.yml) before it runs. Exit 2 blocks
+// the call and stderr says which rule. The decision is the gate's (sentinel-rules.mjs).
+// Copied byte for byte into .karajan/harness.
+import console from "node:console";
+import process from "node:process";
+import { spawnSync } from "node:child_process";
+import { ROOT, doc } from "./sentinel-lib.mjs";
+import { rulesGate } from "./sentinel-rules.mjs";
+
+let raw = "";
+process.stdin.on("data", (d) => { raw += d; });
+process.stdin.on("end", () => {
+  let call;
+  try { call = JSON.parse(raw); } catch { process.exit(0); } // not a tool call: nothing to judge
+  // The user's switch for the whole Sentinel, set in the host's environment.
+  if (process.env.KJ_SENTINEL_OFF === "1") process.exit(0);
+  const verdict = rulesGate({ root: ROOT, tool: call?.tool_name, input: call?.tool_input, run: spawnSync });
+  if (!verdict.deny) process.exit(0);
+  console.error("karajan sentinel: " + verdict.message + doc("rules"));
+  console.error("karajan: Karajan gobierna y se le obedece. No rodees el gate ni cambies la regla para pasarlo; si te parece injusta, díselo a tu usuario o usa kj report-issue.");
+  process.exit(2);
+});

package/src/harden/sentinel/sentinel-bash-write.mjs

@@ -5,7 +5,7 @@
 import { existsSync, realpathSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join, relative, resolve } from "node:path";
-import { headIndex, shellSegments } from "./sentinel-shell.mjs";
+import { headIndex, shellSegments, withoutRedirections } from "./sentinel-shell.mjs";
 
 const WRITES = ["tee", "touch", "truncate", "cp", "mv", "install", "ln", "sed", "perl", "dd", "sh", "bash", "zsh", "dash", "eval"];
 const RUNNERS = ["xargs", "find", "node", "python3", "python", "ruby", "php", "deno", "bun"];
@@ -56,11 +56,7 @@ export const shellWrites = (words) => {
   // xargs / find -exec run a writer on targets that arrive at run time.
   if (["xargs", "find"].includes(head) && words.slice(i + 1).some((w) => WRITES.includes(w.split("/").at(-1)))) out.push(`$(${head})`);
   // Arguments without redirections (< << <<< > >> and a detached operand).
-  const rest = [];
-  for (let k = i + 1; k < words.length; k++) {
-    if (!/^\d*[<>]/.test(words[k])) rest.push(words[k]);
-    else if (/^\d*(<{1,3}|>>?|>[|&])$/.test(words[k])) k++;
-  }
+  const rest = withoutRedirections(words.slice(i + 1));
   // Operands: words that are not options, and EVERY word after "--" (touch -- -file).
   const cut = rest.includes("--") ? rest.indexOf("--") : rest.length;
   const plain = [...rest.slice(0, cut).filter((w) => !w.startsWith("-")), ...rest.slice(cut + 1)];

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

@@ -4,7 +4,7 @@
 import { spawnSync } from "node:child_process";
 import { isAbsolute, relative, resolve } from "node:path";
 import process from "node:process";
-import { headIndex, shortOpts } from "./sentinel-shell.mjs";
+import { headIndex, shortOpts, withoutRedirections } from "./sentinel-shell.mjs";
 
 export const DISCARD_VERBS = ["checkout", "restore", "reset", "stash", "switch", "clean"];
 
@@ -16,7 +16,9 @@ export const DISCARD_VERBS = ["checkout", "restore", "reset", "stash", "switch",
  * @param {string[]} words
  * @param {string} root
  */
-export const discardOf = (words, root) => {
+export const discardOf = (command, root) => {
+  // KJC-BUG-0268: `git checkout main 2>&1` names a branch, not a branch and a path.
+  const words = withoutRedirections(command);
   let i = headIndex(words, ["git"]); // /usr/bin/git is git
   // A $variable in command position beside a discard verb ($g checkout) cannot be read.
   if (words[i]?.startsWith("$") && words.some((w) => DISCARD_VERBS.includes(w))) return { unknown: true };

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

@@ -0,0 +1,86 @@
+// The Sentinel's rules gate (KJC-TSK-0939, MDR-C, ADR 0016). A real module with
+// no dependencies: kj harden copies it byte for byte into .karajan/harness as
+// sentinel-rules.mjs, and this code is unit-tested.
+//
+// The rules written in the MD files, compiled into .karajan/rules.yml, are asked
+// to kj before EVERY tool call. kj decides (exit 0 allow, 2 deny); whatever
+// cannot be evaluated is denied, because rules silently off would be every call
+// allowed. With no rules.yml the gate does not exist and costs nothing.
+import { existsSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const RULES_FILE = join(".karajan", "rules.yml");
+// KJC-TSK-0954 (ADR 0017): the rules from the user's private sources, out of git.
+// Either file is rules: a project with only local ones is gated just the same.
+const LOCAL_RULES_FILE = join(".karajan", "rules.local.yml");
+const hasRules = (root, exists) => exists(join(root, RULES_FILE)) || exists(join(root, LOCAL_RULES_FILE));
+const EDIT_TOOLS = new Set(["Write", "Edit", "MultiEdit", "NotebookEdit"]);
+const KJ_DOES_NOT_START = /SyntaxError|ReferenceError|Cannot find module|ERR_MODULE_NOT_FOUND|ERR_REQUIRE_ESM/;
+
+/**
+ * KJC-BUG-0207: a kj that does not start (a linked tree with a syntax error) is
+ * not a verdict. Returns the file its stack names, "" when it names none, or
+ * null when kj did start.
+ * @param {string} stderr
+ */
+export const brokenKjFile = (stderr) => {
+  const text = String(stderr || "");
+  if (!KJ_DOES_NOT_START.test(text)) return null;
+  // The location line node prints: a path or file: URL (blanks allowed), then :line.
+  const at = text.split("\n").map((line) => line.trim()).find((line) => /^(file:|\/|[A-Za-z]:\\).*\.(m?js|cjs|ts):\d+$/.test(line)) || "";
+  const file = at.slice(0, at.lastIndexOf(":"));
+  return file.startsWith("file:") ? fileURLToPath(file) : file;
+};
+
+const lastJson = (stdout) => {
+  try { return JSON.parse(String(stdout || "").trim().split("\n").pop()); } catch { return null; }
+};
+const deny = (message) => ({ deny: true, message });
+
+/**
+ * KJC-TSK-0949 (MDR-E2): an MD changed and what was compiled no longer covers
+ * it. One line for the session's start, or "" when every rule is decided, there
+ * is no rules.yml, or kj cannot tell (a notice never fails a session).
+ * @param {{root: string, run: Function, exists?: Function}} opts
+ * @returns {string}
+ */
+export function rulesDriftNotice({ root, run, exists = existsSync }) {
+  if (!hasRules(root, exists)) return "";
+  const res = run("kj", ["rules", "coverage", "--json"], { cwd: root, encoding: "utf8" });
+  const counts = res.error || res.status !== 0 ? null : lastJson(res.stdout)?.counts;
+  const none = Number(counts?.none) || 0;
+  const stale = Number(counts?.stale) || 0;
+  if (none + stale === 0) return "";
+  return none + " sin gate y " + stale + " desfasada(s) entre las reglas de tus MD (" + RULES_FILE + "). Ejecuta kj rules compile, "
+    + "escribe la propuesta y pide a tu usuario que la apruebe (kj rules approve); kj rules coverage las nombra.";
+}
+
+/**
+ * @param {{root: string, tool: string, input?: object, run: Function, exists?: Function}} call
+ *   `run` is spawnSync (injected so the gate is testable without a process).
+ * @returns {{deny: boolean, message?: string}}
+ */
+export function rulesGate({ root, tool, input, run, exists = existsSync }) {
+  if (!hasRules(root, exists)) return { deny: false };
+  // The input goes on stdin: a large Write does not fit in an argument.
+  const res = run("kj", ["rules", "eval", "--tool", String(tool), "--input", "-"], { cwd: root, encoding: "utf8", input: JSON.stringify(input ?? {}) });
+  if (res.error || res.status === null) {
+    return deny(RULES_FILE + " declara reglas pero kj no es ejecutable, así que no se pueden evaluar: restaura kj en el PATH.");
+  }
+  if (res.status === 0) return { deny: false };
+  const out = lastJson(res.stdout);
+  if (res.status === 2) {
+    const source = out?.source ? " (" + out.source + ")" : "";
+    const what = String(out?.message ?? "la acción rompe una regla de los MD").replace(/[.\s]+$/, "");
+    return deny("regla " + (out?.rule_id ?? "sin identificar") + source + ": " + what + ". Sin escape (ADR 0016): si la regla está mal compilada, la corrige tu usuario.");
+  }
+  const broken = brokenKjFile(res.stderr);
+  if (broken !== null) {
+    const target = input?.file_path || input?.notebook_path || "";
+    if (EDIT_TOOLS.has(tool) && broken && target && resolve(String(target)) === resolve(broken)) return { deny: false };
+    return deny("kj no arranca" + (broken ? " (" + broken + ")" : "") + ", así que las reglas no se pueden evaluar y nada más pasa: arregla ese fichero.");
+  }
+  const why = Array.isArray(out?.errors) ? out.errors.join("; ") : "exit " + res.status;
+  return deny(RULES_FILE + " no se puede evaluar (" + why + "): lo corrige tu usuario, fuera de la sesión.");
+}

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 };