karajan-code 4.39.0 → 4.41.0

package/src/commands/rules-review.js

@@ -0,0 +1,57 @@
+/**
+ * kj rules review (KJC-TSK-0963, MDR-F4, ADR 0017): the agent the rules will
+ * watch wrote the proposal, so it is not the one who calls it good. A DIFFERENT
+ * AI reads it rule by rule, and its verdict is tied to the exact bytes of the
+ * proposal (the same store and the same primitive as `kj review`). Without an
+ * approved verdict for those bytes, `kj rules approve` does not offer it.
+ */
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+import { runOneShotReview } from "../review/one-shot-review.js";
+import { PROPOSAL_FILE, rulesCheck } from "./rules.js";
+
+const TASK = [
+  "This is NOT code: it is a proposal of compiled rules (YAML). Each entry carries the literal `text` of a rule the user",
+  "wrote in their MD files (already verified word for word) and what an agent compiled it into. That agent is the one these",
+  "rules are going to watch, so it gains from a compilation that never fires. Judge every rule on one question: does the",
+  "compilation enforce what the text says?",
+  "- kind deterministic: `when` must deny the tool calls the text forbids. Too narrow a condition (it would rarely fire), or",
+  "  examples picked so that a weak condition passes, is a defect. So is a condition so wide that it denies honest calls.",
+  "- kind judgment or out-of-scope: nothing is blocked on these. If a condition over a tool name and its arguments could",
+  "  have enforced the text, the rule has been weakened.",
+  "Any rule may give a `reason` for how it is compiled: weigh it, do not take it on trust.",
+  "Know what a condition can see before you ask for one (KJC-TSK-0973): the tool name and the arguments of ONE call, with",
+  "the operators equals, in, matches, exists, gt, lt. It cannot read a file a command names (a commit message passed with -F,",
+  "a body file), earlier calls, or the state of the repo. A rule whose breach is only visible there cannot be deterministic,",
+  "and judgment is its honest kind. A condition that would deny honest calls (a word that is also ordinary text, a method",
+  "name, a comment) is a defect too: do not ask for one, and do not ask for more than the text forbids.",
+  "A deterministic rule that enforces every part of its text a condition CAN see is not weak for leaving out the part no",
+  "condition can see: block it only if the visible part is compiled narrower than it could be.",
+  "What blocks is MATERIAL weakness: a form of the forbidden call an agent would plausibly write in ordinary work is let",
+  "through, or a call an agent would plausibly make in honest work is denied. A pattern over shell text is never complete,",
+  "and these gates exist for a rule forgotten or bent in passing; an agent contorting a command to dodge them is stopped at",
+  "the checkpoints it does not reach (git hooks, CI), not here. So an exotic form (a command inside a control structure, a",
+  "rare global option, unusual casing) is a non-blocking suggestion, not a blocking issue.",
+  "Report as a BLOCKING issue every rule materially weaker than its text, naming its id (R-...) and saying what would",
+  "enforce it. Approve when none is.",
+].join("\n");
+
+/**
+ * @param {{projectDir: string, file?: string, home?: string, config: object, logger?: object, deps?: object}} opts
+ *   `deps` are the seams of runOneShotReview (hostAgent, createAgentFn, detectAgents).
+ * @returns {Promise<{code: 0|1, lines: string[]}>}
+ */
+export async function rulesReview({ projectDir, file = PROPOSAL_FILE, home = os.homedir(), config, logger, deps = {} }) {
+  let text;
+  try { text = fs.readFileSync(path.resolve(projectDir, file), "utf8"); } catch { return { code: 1, lines: [`✗ no ${file}: nothing to review`] }; }
+  const checked = rulesCheck({ projectDir, home, text });
+  if (checked.code !== 0) return { code: 1, lines: checked.lines };
+  const record = await runOneShotReview({ diff: text, task: TASK, config, logger, projectDir, ...deps });
+  if (record.verdict === "approved") {
+    return { code: 0, lines: [`✓ APPROVED by ${record.reviewer}: ${record.summary || "the compilation enforces the rules as written"}`, "Now your user reads it and runs `kj rules approve` from their own terminal."] };
+  }
+  const issues = record.issues.map((issue) => `  - ${issue.description ?? issue.message ?? JSON.stringify(issue)}`);
+  return { code: 1, lines: [`✗ REJECTED by ${record.reviewer} — ${issues.length} rule(s) weaker than their text:`, ...issues, "Fix the proposal and run `kj rules review` again: the verdict is tied to its exact content."] };
+}

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/environment/contract-commit.js

@@ -0,0 +1,79 @@
+/**
+ * The contract commit (KJC-TSK-0857, KJC-BUG-0273). What kj generates for a
+ * project (playbook, skills, settings, workflows, gate marker, hooks) the whole
+ * team must inherit by cloning, so it goes into git. Nobody wrote it, and an
+ * agent's own PR-size rules forbid a 1200-line commit, so kj makes the commit
+ * itself: only the files it just generated, never what was already dirty, and
+ * never on the base branch once the repo has history. This is NOT the supervisor
+ * seal (ADR 0009), which stays a human act.
+ */
+import { execFileSync } from "node:child_process";
+
+/** What kj generates and the whole team must inherit by cloning (prefixes). */
+export const CONTRACT_PATHS = [
+  ".gitignore",
+  ".karajan/hooks/",
+  ".karajan/review-gate",
+  ".karajan/adrs/",
+  ".karajan/policy.yml",
+  ".claude/",
+  ".github/workflows/kj-",
+  "CLAUDE.md",
+  "AGENTS.md",
+  "GEMINI.md",
+  // KJC-TSK-0879: in a Rulesync repo kj's rules live in .rulesync/rules/karajan.md.
+  ".rulesync/",
+];
+
+const FRESH_MESSAGE = "chore(bootstrap): el contrato del método, para que quien clone lo herede";
+const REGEN_MESSAGE = "chore(kj): el contrato del método, generado por kj";
+
+const runner = (projectDir, env) => (args) => execFileSync("git", ["-C", projectDir, ...args], { encoding: "utf8", env, stdio: ["ignore", "pipe", "pipe"] });
+const isContract = (file) => CONTRACT_PATHS.some((p) => (p.endsWith("/") || p.endsWith("-") ? file.startsWith(p) : file === p));
+
+/** The contract files git sees as changed, with their porcelain code (`??` untracked). */
+function contractStatus(git) {
+  try {
+    const lines = git(["status", "--porcelain", "--untracked-files=all"]).split("\n").filter(Boolean);
+    return lines.map((line) => [line.slice(3).trim().split(" -> ").at(-1), line.slice(0, 2)]).filter(([file]) => isContract(file));
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * The contract files that differ from HEAD (or are untracked), one by one.
+ * @returns {Set<string>} empty when git cannot answer
+ */
+export function contractChanges(projectDir, git = runner(projectDir, process.env)) {
+  return new Set(contractStatus(git).map(([file]) => file));
+}
+
+const hasCommits = (git) => { try { git(["rev-parse", "--verify", "HEAD"]); return true; } catch { return false; } };
+const branchOf = (git) => { try { return git(["symbolic-ref", "--short", "HEAD"]).trim(); } catch { return ""; } };
+
+/**
+ * @param {{projectDir: string, before?: Set<string>, baseBranch?: string, env?: object}} opts
+ *   `before`: the contract files already dirty BEFORE kj generated anything,
+ *   tracked or not. They may carry the person's words, so they stay out.
+ * @returns {{committed: boolean, files?: string[], reason?: string}}
+ */
+export function commitContract({ projectDir, before = new Set(), baseBranch = "main", env = process.env }) {
+  const git = runner(projectDir, env);
+  const files = contractStatus(git).map(([file]) => file).filter((file) => !before.has(file)).sort();
+  if (files.length === 0) return { committed: false, reason: "nothing of the contract to commit" };
+  const history = hasCommits(git);
+  if (history && branchOf(git) === baseBranch) {
+    // kj never commits on the base branch, and will not switch the person's branch
+    // for them: the files are named so the commit can be made where it belongs.
+    return { committed: false, files, reason: `on the base branch '${baseBranch}', where kj never commits: create a branch and commit these generated files there (git checkout -b chore/kj-contract && git add -- ${files.join(" ")} && git commit -m "chore(kj): el contrato del método")` };
+  }
+  try {
+    git(["add", "--", ...files]);
+    // --only: these paths and nothing else. What the person had staged stays staged.
+    git(["commit", "--only", "-m", history ? REGEN_MESSAGE : FRESH_MESSAGE, "--", ...files]);
+  } catch (err) {
+    return { committed: false, files, reason: `git could not commit the contract: ${String(err.stderr || err.message).trim().split("\n")[0]}` };
+  }
+  return { committed: true, files };
+}

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.");
+}