karajan-code 4.17.0 → 4.19.0

package/src/commands/review-gate.js

@@ -8,14 +8,19 @@
 import { existsSync } from "node:fs";
 import { isAbsolute, join } from "node:path";
 import { runCommand } from "../utils/process.js";
-import { checkVerdict } from "../review/verdict-store.js";
+import { checkVerdict, diffHash } from "../review/verdict-store.js";
 import { runOneShotReview } from "../review/one-shot-review.js";
 import { runSolomonArbitration } from "../review/solomon-arbitration.js";
 import { ensureGateTrackable } from "../review/gate-gitignore.js";
 import { runSonarPregate, formatSonarFinding } from "../review/sonar-pregate.js";
+import { runMutationPregate, formatSurvivor } from "../review/mutation-pregate.js";
 import { checkCardFirst } from "../review/card-first.js";
 import { checkTestsWithCode } from "../review/tests-with-code.js";
 import { loadPrivacyList, scanText } from "../privacy/scan.js";
+import { checkStagedDiff, loadPolicy } from "../policy/engine.js";
+import { loadStandingExceptions, recordPolicyException } from "../policy/exceptions.js";
+import { policyFileHash, recordGateDecision } from "../policy/decisions.js";
+import { evaluatePolicyGate } from "../review/policy-gate.js";
 
 // KJC-TSK-0686 (MG-A): card-first is a gate, not a habit. Runs on --staged
 // (before spending sonar/reviewer effort) AND on --check — the pre-commit
@@ -75,6 +80,28 @@ function printVerdict(record) {
 export async function solomonCommand({ config, logger = null, flags = {} }) {
   const projectDir = config?.projectDir || process.cwd();
   const diff = await rawDiff(flags.range);
+  // KJC-TSK-0734 (PL-B): un hallazgo de policy de clase seguridad no es
+  // arbitrable — solomon se niega antes de gastar un token. Y una policy
+  // inválida cierra el arbitraje en vez de abrirlo (fail closed, catch de
+  // codex: un `sec` vacío por error de carga NO puede significar "adelante").
+  const files = (await rawDiff(flags.range, ["--name-only"])).split("\n").map((f) => f.trim()).filter(Boolean);
+  const pol = loadPolicy({ projectDir });
+  if (pol.errors.length > 0) {
+    for (const e of pol.errors) console.log(`✗ ${e}`);
+    console.log("⚖ Solomon no arbitra con policy.yml inválida — corrígela primero: una regla que miente es peor que ninguna.");
+    process.exitCode = 1;
+    return { ruling: "reject", reasoning: "invalid policy.yml — arbitration refused (fail closed)" };
+  }
+  const sec = checkStagedDiff(pol.policy, { files, netLinesAdded: 0 }).filter((v) => v.class === "security" && v.enforcement === "deny");
+  if (sec.length > 0) {
+    for (const v of sec) {
+      const where = v.file ? ` (${v.file})` : "";
+      console.log(`✗ policy [${v.rule_id}] ${v.reason}${where}`);
+    }
+    console.log("⚖ Solomon no arbitra hallazgos de clase seguridad — resuélvelos; la regla no es negociable.");
+    process.exitCode = 1;
+    return { ruling: "reject", reasoning: "security-class policy denial — not arbitrable" };
+  }
   const res = await runSolomonArbitration({ diff, position: flags.position, config, logger, projectDir });
   if (res.ruling === "approve") {
     console.log(`⚖ Solomon (${res.solomon}) rules for the brain — verdict recorded, the gate is open.`);
@@ -122,7 +149,15 @@ export async function reviewGateCommand({ config, logger = null, flags = {} }) {
   // Field case: a 522-line PR sailed past the warning with a
   // rationalization — where the project wants teeth, pr_size: "block"
   // rejects deterministically with a NAMED escape. Default stays warn.
-  const sizeWarn = config?.method_gates?.pr_size_warn ?? 150;
+  // PL-C (KJC-TSK-0735), fuente única de umbrales: si la policy declara el
+  // invariante net_lines_added, SU max es el umbral — el mismo número que
+  // aplican kj policy check y el tier C de CI; method_gates queda de fallback.
+  const pol = loadPolicy({ projectDir });
+  const locInv = pol.errors.length === 0
+    ? (pol.policy.invariants || []).find((i) => i.kind === "diff-threshold" && i.metric === "net_lines_added")
+    : null;
+  const sizeWarn = locInv?.max ?? config?.method_gates?.pr_size_warn ?? 150;
+  const sizeSource = locInv ? `policy [${locInv.id}]` : "method_gates";
   if (sizeWarn > 0) {
     const numstat = await rawDiff(flags.range, ["--numstat"]);
     const added = numstat.split("\n").reduce((acc, l) => acc + (Number(l.split("\t")[0]) || 0), 0);
@@ -131,12 +166,12 @@ export async function reviewGateCommand({ config, logger = null, flags = {} }) {
       if (process.env.KJ_ALLOW_LARGE_PR === "1") {
         console.log(`⚠ pr-size exempt: ${added} lines added — KJ_ALLOW_LARGE_PR=1 (explicit escape hatch)`);
       } else if (sizePolicy === "block") {
-        const reason = `${added} lines added exceeds the ${sizeWarn}-line budget (method_gates.pr_size: block) — partition the work, or get your user's explicit OK and re-run with KJ_ALLOW_LARGE_PR=1`;
+        const reason = `${added} lines added exceeds the ${sizeWarn}-line budget (${sizeSource}; method_gates.pr_size: block) — partition the work, or get your user's explicit OK and re-run with KJ_ALLOW_LARGE_PR=1`;
         console.log(`✗ pr-size gate: ${reason}`);
         process.exitCode = 1;
         return { verdict: "rejected", reviewer: "pr-size", issues: [{ severity: "high", description: reason }] };
       } else {
-        console.log(`⚠ pr-size: ${added} lines added (guideline ~${sizeWarn}) — an oversized warning is not an opinion: partition, or ask your user (method_gates.pr_size: block to harden)`);
+        console.log(`⚠ pr-size: ${added} lines added (guideline ~${sizeWarn}, source: ${sizeSource}) — an oversized warning is not an opinion: partition, or ask your user (method_gates.pr_size: block to harden)`);
       }
     }
   }
@@ -187,6 +222,54 @@ export async function reviewGateCommand({ config, logger = null, flags = {} }) {
     return { verdict: "rejected", reviewer: "tests-with-code", issues: [{ severity: "high", description: tests.reason }] };
   }
 
+  // KJC-TSK-0734 (PL-B): la policy declarativa como gate determinista, en
+  // --staged Y en --check — el pre-commit hereda los dientes sin regenerar
+  // hooks. enforcement=warn avisa; deny cierra salvo excepción probatoria
+  // (KJ_ALLOW_POLICY=1 + KJ_POLICY_REASON, registrada con identidad y hash
+  // del diff); class=security cierra sin escape y sin arbitraje.
+  let net = 0;
+  for (const l of (await rawDiff(flags.range, ["--numstat"])).split("\n")) {
+    const [a, r] = l.trim().split(/\s+/);
+    if (a && a !== "-") net += Number(a) || 0;
+    if (r && r !== "-") net -= Number(r) || 0;
+  }
+  // GOV-B (KJC-TSK-0746): las permanentes concedidas (kj policy grant)
+  // eximen su regla mientras viven; el descarte de líneas corruptas se dice.
+  const std = loadStandingExceptions(projectDir);
+  if (std.discarded > 0) console.log(`⚠ policy: ${std.discarded} línea(s) corruptas descartadas en policy-exceptions.jsonl — revísalo`);
+  const gate = evaluatePolicyGate({
+    policy: pol.policy, errors: pol.errors, files: changedFiles, netLinesAdded: net,
+    diffHashValue: diffHash(diff),
+    recordException: (entry) => recordPolicyException({ projectDir, entry }),
+    standingExceptions: std.standing,
+  });
+  const at = (v) => (v.file ? ` (${v.file})` : "");
+  for (const w of gate.warns) console.log(`⚠ policy [${w.rule_id}] ${w.reason}${at(w)}`);
+  for (const e of gate.exempted) {
+    console.log(e.standing
+      ? `⚠ policy standing [${e.rule_id}] — excepción permanente viva hasta ${e.standing.expiresAt} (${e.standing.justification || "sin justificación"})`
+      : `⚠ policy exempt [${e.rule_id}] — excepción registrada en .karajan/policy-exceptions.jsonl (${e.justification})`);
+  }
+  // GOV-C (KJC-TSK-0747): las decisiones de chokepoint dejan rastro
+  // hash-encadenado — cada deny, cada excepción, y el allow del commit.
+  const chokepoint = flags.check ? "commit" : "review";
+  const seal = (decision, extra = {}) =>
+    recordGateDecision(projectDir, { decision, chokepoint, policy_hash: policyFileHash(projectDir), artifact_hash: diffHash(diff), ...extra });
+  if (gate.exempted.length > 0) seal("exempt", { rule_ids: gate.exempted.map((e) => e.rule_id) });
+  if (!gate.ok) {
+    for (const d of gate.denials) {
+      const sec = d.class === "security" ? " [security — sin escape ni arbitraje]" : "";
+      console.log(`✗ policy [${d.rule_id}]${sec} ${d.reason}${at(d)}`);
+    }
+    seal("deny", { rule_ids: gate.denials.map((d) => d.rule_id) });
+    const reason = gate.invalid
+      ? "policy.yml inválida — una regla que miente es peor que ninguna: corrígela"
+      : `${gate.denials.length} violación(es) de policy con enforcement=deny — el diff no entra`;
+    console.log(`✗ policy gate: ${reason}`);
+    process.exitCode = 1;
+    return { verdict: "rejected", reviewer: "policy", issues: gate.denials.map((d) => ({ severity: "high", file: d.file, description: `[${d.rule_id}] ${d.reason}` })) };
+  }
+
   if (flags.check) {
     // KJC-BUG-0132 (issue #1344): a PURE merge commit stages no content of
     // its own — everything it brings reached the parent branches already
@@ -206,6 +289,8 @@ export async function reviewGateCommand({ config, logger = null, flags = {} }) {
     console.log(res.ok
       ? `✓ verdict ok — approved by ${res.verdict.reviewer} (diff ${res.verdict.diffHash.slice(0, 12)})`
       : `✗ ${res.reason}`);
+    // GOV-C: el allow del chokepoint de COMMIT es evidencia — se sella.
+    if (res.ok) seal("allow");
     process.exitCode = res.ok ? 0 : 1;
     return res;
   }
@@ -241,6 +326,28 @@ export async function reviewGateCommand({ config, logger = null, flags = {} }) {
     }
   }
 
+  // MUT-A (KJC-TSK-0716): mutation pre-gate — opt-in (method_gates.mutation),
+  // SOLO en --staged (jamás en pre-commit: cuesta minutos; y jamás en --range:
+  // el scope es el ÍNDICE y anotaría trabajo ajeno — catch de codex). block
+  // cierra ANTES de gastar reviewer; warn viaja como advisory en su task.
+  const mut = flags.staged && !flags.range ? await runMutationPregate({ config, projectDir }) : { enabled: false, ok: true };
+  if (mut.enabled) {
+    if (mut.available === false) {
+      console.log(`⚠ mutation pre-gate no disponible: ${mut.reason} — degradado avisando (method_gates.mutation)`);
+    } else if (mut.survived.length > 0) {
+      console.log(`Mutantes supervivientes en el diff — score ${mut.score ?? "n/a"}%:`);
+      for (const m of mut.survived) console.log(`  ✗ ${formatSurvivor(m)}`);
+      if (!mut.ok) {
+        console.log("✗ mutation gate: la suite verde no PRUEBA el cambio — mata los supervivientes antes del review (method_gates.mutation: block).");
+        process.exitCode = 1;
+        return { verdict: "rejected", reviewer: "mutation", issues: mut.survived.map((m) => ({ severity: "high", file: m.file, description: formatSurvivor(m) })) };
+      }
+      task = `${task || "Review the following diff for correctness, security and maintainability."}\n\n`
+        + `Surviving mutants on the changed lines (weak asserts — fold into your review):\n`
+        + mut.survived.map((m) => `- ${formatSurvivor(m)}`).join("\n");
+    }
+  }
+
   const record = await runOneShotReview({ diff, task, config, logger, projectDir });
   printVerdict(record);
   process.exitCode = record.verdict === "approved" ? 0 : 1;

package/src/environment/briefs.js

@@ -71,6 +71,9 @@ const B = {
         [
           ...(tdd ? ["TDD is ON: the failing test exists FIRST, then the code."] : []),
           "The suite is never left red, and never goes green by deleting or skipping tests.",
+          ...(config?.method_gates?.mutation
+            ? ["Green is not proof: run `kj mutate --since <base>` after the suite passes and BEFORE review — kill surviving mutants (weak asserts) first."]
+            : []),
         ],
         "green suite + the list of new/changed tests and what each one pins.");
     },

package/src/environment/playbook.js

@@ -61,7 +61,9 @@ Invariants (the git gates enforce these — they are not suggestions):
   \`kj_rag_query\` tool: reach for it before grepping by hand.
 - ${trackingLine(stateBackend, boardName)}
 - Tests prove behavior: the failing test exists first (TDD), and the suite
-  is never left red.
+  is never left red. Green is not proof: with \`method_gates.mutation\`
+  declared, run \`kj mutate --since <base>\` after green and BEFORE the
+  review — a surviving mutant is a weak assert; kill it first.
 - Every diff is reviewed by a DIFFERENT AI before it is committed
   (\`kj review --staged\`): verdicts bind to the exact diff — change the code
   and it must be reviewed again. Disagree with a rejection? \`kj solomon\`.

package/src/harden/sentinel-hooks.js

@@ -88,7 +88,7 @@ const POST_BODY = `#!/usr/bin/env node
 // a tool call (PostToolUse, always exit 0).
 import { relative } from "node:path";
 import { CODE, TESTS, ROOT, load, save, session } from "./sentinel-lib.mjs";
-const ESCAPES = ["KJ_ALLOW_WRITE", "KJ_ALLOW_REWRITE", "KJ_ALLOW_NO_CARD", "KJ_ALLOW_NO_TESTS", "KJ_ALLOW_PII"];
+const ESCAPES = ["KJ_ALLOW_WRITE", "KJ_ALLOW_REWRITE", "KJ_ALLOW_NO_CARD", "KJ_ALLOW_NO_TESTS", "KJ_ALLOW_PII", "KJ_ALLOW_POLICY"];
 let raw = "";
 process.stdin.on("data", (d) => { raw += d; });
 process.stdin.on("end", () => {
@@ -299,7 +299,62 @@ process.stdin.on("end", () => {
         // en cualquier posicion, y una ruta entrecomillada con espacios es
         // invisible al tokenizador: ambas => deny conservador (endpoint
         // pedido por el reviewer; friccion asumida, el remedio es literal).
-        if (/\\$\\(|\`/.test(cmd) || /["'][^"'\\n]*\\/[^"'\\n]* [^"'\\n]*["']/.test(cmd)) {
+        // KJC-BUG-0140: pares de comillas REALES, no regex sobre el texto —
+        // la comilla de CIERRE de un string + un redirect literal + la de
+        // apertura del siguiente creaban la ilusion de ruta con espacios y
+        // denegaban el flujo estandar commit -m "..." > log && echo "ok".
+        // Se recorre alternando estado (doctrina del parseCommand del motor):
+        // solo el CONTENIDO realmente entrecomillado con slash y espacio
+        // deniega — incluidas comillas a mitad de token (scp host:"/a b/x")
+        // y la comilla sin cerrar (no verificable).
+        // ...y por TOKEN completo, no por span: spans adyacentes concatenan
+        // ("dir with"" spaces/file" es UNA ruta) — catch de codex.
+        const quotedPathWithSpaces = (s) => {
+          // Un backslash pegado a comilla o blanco (comilla escapada,
+          // espacio escapado) altera donde CIERRA el string o esconde
+          // espacios: opaco => deny (doctrina del motor) — catch de codex.
+          // Caracteres construidos con fromCharCode: CERO escaping en este
+          // template — fuente y artefacto identicos, nada que malinterpretar
+          // (el doble-escaping confundio cuatro reviews; solomon desestimo
+          // la primera y las demas se volvieron ilegibles igual).
+          // El punto escapado de un sed y similares siguen libres.
+          const BS = String.fromCharCode(92);
+          const TAB = String.fromCharCode(9);
+          const NL = String.fromCharCode(10);
+          for (let i = s.indexOf(BS); i !== -1; i = s.indexOf(BS, i + 1)) {
+            const n = s[i + 1] || "";
+            if (n === '"' || n === "'" || n === " " || n === TAB) return true;
+          }
+          let q = null;
+          let tok = "";
+          let hadQuote = false;
+          const flush = () => {
+            const bad = hadQuote && tok.includes("/") && tok.includes(" ");
+            tok = "";
+            hadQuote = false;
+            return bad;
+          };
+          for (const ch of s) {
+            if (q) {
+              if (ch === q) q = null;
+              else tok += ch;
+              continue;
+            }
+            if (ch === '"' || ch === "'") {
+              q = ch;
+              hadQuote = true;
+              continue;
+            }
+            if (ch === " " || ch === TAB || ch === NL || ch === ";" || ch === "|" || ch === "&" || ch === "<" || ch === ">" || ch === "(" || ch === ")") {
+              if (flush()) return true;
+              continue;
+            }
+            tok += ch;
+          }
+          if (q !== null) return true; // comilla sin cerrar: no verificable
+          return flush();
+        };
+        if (/\\$\\(|\`/.test(cmd) || quotedPathWithSpaces(cmd)) {
           if (process.env.KJ_ALLOW_CROSS_LANE === "1") { recordEscape(sid, "KJ_ALLOW_CROSS_LANE", tool); }
           else {
             console.error("kj sentinel: sustitucion de comandos o ruta entrecomillada con espacios en un comando mutador — no verificable por el guard de carriles (MONO-0); usa valores/rutas LITERALES sin sustitucion (o KJ_ALLOW_CROSS_LANE=1, queda registrado).");
@@ -329,6 +384,41 @@ process.stdin.on("end", () => {
         }
       }
     }
+    // KJC-TSK-0734 (PL-B): con .karajan/policy.yml presente, la evaluacion
+    // la hace el MOTOR via kj policy eval --strict (exit 2 = deny, contrato
+    // PL-A); los defaults del supervisor viven en el motor y el check
+    // PROTECTED inline de arriba queda como red fail-closed si kj falta.
+    // Fail CLOSED por defecto (catches de codex; doctrina KJC-BUG-0095: un
+    // gate no se cae en silencio): solo exit 0 permite. kj inejecutable =
+    // deny duro (el remedio es restaurar kj); cualquier otro fallo de
+    // evaluacion = deny con escape humano registrable — la sesion no queda
+    // presa de un typo de YAML, pero abrirla es decision del usuario.
+    if ((EDIT_TOOLS.includes(tool) || tool === "Bash") && existsSync(resolve(ROOT, ".karajan", "policy.yml"))) {
+      // PL-C: el rol que ACTÚA (KJ_POLICY_ROLE, sembrado por los runners de
+      // kj run en los subprocesos) — el anfitrión-brain evalúa como coder.
+      const actorRole = process.env.KJ_POLICY_ROLE || "coder";
+      const pres = spawnSync("kj", ["policy", "eval", "--strict", "--role", actorRole, "--tool", tool, "--input", JSON.stringify(input)], { cwd: ROOT, encoding: "utf8" });
+      if (pres.error || pres.status === null) {
+        console.error("kj sentinel: .karajan/policy.yml declara enforcement pero kj no es ejecutable — la policy no se puede evaluar; restaura kj en el PATH (npm i -g @karajan-family/code, o el nombre legacy karajan-code) o retira la policy conscientemente.");
+        process.exit(2);
+      }
+      if (pres.status === 2) {
+        let v = null;
+        try { v = JSON.parse(String(pres.stdout || "").trim().split("\\n").pop()); } catch { /* mensaje generico */ }
+        const secure = !!(v && v.class === "security");
+        if (!secure && process.env.KJ_ALLOW_POLICY === "1") { recordEscape(sid, "KJ_ALLOW_POLICY", tool); }
+        else {
+          console.error("kj sentinel: policy deny [" + ((v && v.rule_id) || "policy") + "] " + ((v && v.reason) || "la tool call viola la policy del proyecto") + (secure ? " [security — sin escape ni arbitraje]" : " (KJ_ALLOW_POLICY=1 = excepcion consciente, queda registrada; el commit exigira ademas KJ_POLICY_REASON)"));
+          process.exit(2);
+        }
+      } else if (pres.status !== 0) {
+        if (process.env.KJ_ALLOW_POLICY === "1") { recordEscape(sid, "KJ_ALLOW_POLICY", tool); }
+        else {
+          console.error("kj sentinel: kj policy eval fallo (exit " + pres.status + ") — la policy declarada no se pudo evaluar, deny por defecto; diagnostica con kj policy check y corrige .karajan/policy.yml fuera de la sesion (o KJ_ALLOW_POLICY=1 = excepcion consciente, queda registrada).");
+          process.exit(2);
+        }
+      }
+    }
     if (EDIT_TOOLS.includes(tool)) {
       const file = input.file_path || input.notebook_path;
       const rel = file ? relative(ROOT, String(file)).replaceAll("\\\\", "/") : "";

package/src/harden/workflow-engine.js

@@ -9,8 +9,29 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 
+import { fileURLToPath } from "node:url";
+import { dirname } from "node:path";
+
 import { upsertManagedBlock } from "../utils/managed-markers.js";
-import { extraWorkflowsFor, mutationWorkflowFor, qualityWorkflowFor, WORKFLOWS } from "./workflow-templates.js";
+import { extraWorkflowsFor, mutationWorkflowFor, qualityWorkflowFor, policyWorkflowFor, WORKFLOWS } from "./workflow-templates.js";
+
+// La versión del kj que corre harden — es la que se pinea en el fallback
+// npx del workflow de policy (jamás @latest en CI). Lectura LAZY: en el
+// bundle SEA no hay package.json junto al módulo y una lectura eager a
+// nivel de módulo tumbaba el binario entero al cargar (ENOENT /package.json).
+let _ownPkg;
+function ownPkg() {
+  if (_ownPkg === undefined) {
+    try {
+      _ownPkg = JSON.parse(
+        readFileSync(join(dirname(fileURLToPath(import.meta.url)), "..", "..", "package.json"), "utf8"),
+      );
+    } catch {
+      _ownPkg = null;
+    }
+  }
+  return _ownPkg;
+}
 
 const BLOCK_VERSION = 1;
 const WORKFLOWS_DIR = join(".github", "workflows");
@@ -50,13 +71,21 @@ export function installWorkflows({
   profile = "standard",
   mutation = false,
   dryRun = false,
+  kjVersion = null,
 } = {}) {
   const dir = join(projectDir, WORKFLOWS_DIR);
   const pm = detectPackageManager(projectDir);
   const quality = qualityWorkflowFor(language, pm, hasLintScript(projectDir));
   const extras = extraWorkflowsFor({ profile, publishable: isPublishableNpm(projectDir), pm });
   const mut = mutation ? mutationWorkflowFor(language, pm) : null;
-  const all = [...WORKFLOWS, ...(quality ? [quality] : []), ...extras, ...(mut ? [mut] : [])];
+  // PL-C: el tier C solo existe donde el proyecto DECLARA policy. Versión a
+  // pinear: la plumbeada por el CLI (SEA) o la propia; "latest" es último
+  // recurso inalcanzable en los caminos reales.
+  const pinned = kjVersion ?? ownPkg()?.version ?? "latest";
+  const policy = existsSync(join(projectDir, ".karajan", "policy.yml"))
+    ? { file: "kj-policy.yml", blockId: "wf-policy", body: policyWorkflowFor(pinned, ownPkg()?.name ?? "karajan-code") }
+    : null;
+  const all = [...WORKFLOWS, ...(quality ? [quality] : []), ...extras, ...(mut ? [mut] : []), ...(policy ? [policy] : [])];
   const results = [];
   for (const wf of all) {
     const target = join(dir, wf.file);
@@ -76,7 +105,10 @@ export function installWorkflows({
     });
     if (!dryRun && action !== "unchanged") {
       mkdirSync(dir, { recursive: true });
-      writeFileSync(target, content);
+      // Newline final SIEMPRE: prettier (y POSIX) lo exigen y el bloque
+      // gestionado no lo garantiza — sin esto, el format-check del propio
+      // pre-commit rechaza el fichero recién generado.
+      writeFileSync(target, content.endsWith("\n") ? content : `${content}\n`);
     }
     results.push({ file: label, action });
   }

package/src/harden/workflow-templates.js

@@ -54,6 +54,34 @@ export const WORKFLOWS = [
   { file: "kj-no-ai-attribution.yml", blockId: "wf-no-ai", body: NO_AI_ATTRIBUTION_WORKFLOW },
 ];
 
+// PL-C (KJC-TSK-0735) — tier C del ADR 0001: re-check merge-blocking en CI
+// (cubre el hook local manipulado). Solo se siembra con policy declarada;
+// npx PINEADO a la versión del kj que corrió harden — jamás @latest en CI.
+export const policyWorkflowFor = (kjVersion, kjName = "karajan-code") => [
+  "name: Policy",
+  "on:",
+  "  pull_request:",
+  "permissions:",
+  "  contents: read",
+  "jobs:",
+  "  policy-check:",
+  "    runs-on: ubuntu-latest",
+  "    steps:",
+  `      - uses: ${PINNED_ACTIONS.checkout}`,
+  "        with:",
+  "          fetch-depth: 0",
+  `      - uses: ${PINNED_ACTIONS.setupNode}`,
+  "        with:",
+  "          node-version: 22",
+  "      - name: kj policy check (strict) on the PR diff",
+  "        env:",
+  "          BASE_REF: ${{ github.base_ref }}",
+  "        run: |",
+  `          if [ -f bin/kj.js ]; then npm ci --ignore-scripts && KJ="node bin/kj.js"; else KJ="npx --yes ${kjName}@${kjVersion}"; fi`,
+  '          $KJ policy check --range "origin/${BASE_REF}...HEAD" --strict',
+  "", // línea en blanco pre-marcador: prettier la exige tras un block scalar
+].join("\n");
+
 const header = (steps) =>
   [
     "name: Quality",

package/src/mutate/diff-scope.js

@@ -89,8 +89,12 @@ export function buildScope({ language, files, ranges }) {
  * the injectable git runner (defaults to `runCommand`).
  * @param {{since: string, language: string, toRef?: string, run?: Function}} params
  */
-export async function getDiffScope({ since, language, toRef = "HEAD", run = runCommand }) {
-  const result = await run("git", ["diff", "--unified=0", `${since}..${toRef}`]).catch(
+export async function getDiffScope({ since, language, toRef = "HEAD", staged = false, run = runCommand }) {
+  // MUT-A (KJC-TSK-0716): staged=true scopea al ÍNDICE (git diff --cached) —
+  // lo que el review gate evalúa. since..HEAD con since=HEAD sería un diff
+  // VACÍO y el pre-gate no mutaría nada (catch de codex, agravado).
+  const args = staged ? ["diff", "--unified=0", "--cached"] : ["diff", "--unified=0", `${since}..${toRef}`];
+  const result = await run("git", args).catch(
     () => null,
   );
   if (!result || result.exitCode !== 0) {

package/src/policy/add.js

@@ -0,0 +1,111 @@
+/**
+ * `kj policy add "<regla hablada>"` (PL-C, KJC-TSK-0735) — el usuario habla,
+ * kj escribe: un agente traduce a UNA regla candidata del vocabulario
+ * CERRADO, parsePolicy valida el merge (lo intraducible se RECHAZA, jamás
+ * se inventa — el YAML es artefacto, no interfaz), se propone el diff y NO
+ * se aplica sin confirmación explícita (--yes).
+ */
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import yaml from "js-yaml";
+import { parsePolicy } from "@karajan-family/governance";
+import { createAgent } from "../agents/index.js";
+import { resolveRole } from "../config/role-resolver.js";
+
+const PROMPT = (text) => `Traduce esta regla de proyecto hablada a un FRAGMENTO YAML del vocabulario
+cerrado v1 de policy de Karajan. Vocabulario COMPLETO (nada fuera de esto):
+roles.<rol>.write|shell con allow/deny (listas de globs o patrones de
+comando), enforcement (warn|deny), class (security); invariants con
+{id, kind: diff-threshold, metric: net_lines_added, max, enforcement}.
+Responde SOLO el fragmento YAML (claves raíz: roles y/o invariants), sin
+explicación ni fences. Si la regla NO cabe en el vocabulario, responde
+exactamente: NO_TRADUCIBLE.
+
+Regla: ${text}`;
+
+async function defaultTranslate({ text, config, logger }) {
+  const role = resolveRole(config, "reviewer");
+  const res = await createAgent(role.provider, config, logger).reviewTask({ prompt: PROMPT(text), role: "reviewer" });
+  if (!res?.ok) throw new Error(`el agente traductor (${role.provider}) falló: ${res?.error || "sin salida"}`);
+  return String(res.output || "").replace(/^```[a-z]*\n?|```\s*$/g, "").trim();
+}
+
+// Merge conservador: las listas se CONCATENAN (añadir jamás borra), los
+// escalares nuevos solo entran donde no había valor.
+function mergeFragment(doc, frag) {
+  const out = { version: 1, ...doc };
+  for (const [role, caps] of Object.entries(frag.roles || {})) {
+    out.roles ||= {};
+    out.roles[role] ||= {};
+    for (const [cap, spec] of Object.entries(caps || {})) {
+      const cur = (out.roles[role][cap] ||= {});
+      for (const [k, v] of Object.entries(spec || {})) {
+        cur[k] = Array.isArray(v) ? [...new Set([...(cur[k] || []), ...v])] : (cur[k] ?? v);
+      }
+    }
+  }
+  if (frag.invariants) out.invariants = [...(doc.invariants || []), ...frag.invariants];
+  return out;
+}
+
+const naiveDiff = (oldText, newText) => {
+  const oldLines = new Set(oldText.split("\n"));
+  const newLines = new Set(newText.split("\n"));
+  return [
+    ...[...oldLines].filter((l) => l.trim() && !newLines.has(l)).map((l) => `- ${l}`),
+    ...[...newLines].filter((l) => l.trim() && !oldLines.has(l)).map((l) => `+ ${l}`),
+  ].join("\n");
+};
+
+export async function policyAddCommand({ text, config = {}, flags = {}, logger = console, deps = {} }) {
+  const projectDir = config?.projectDir || process.cwd();
+  if (!text?.trim()) {
+    logger.error?.('policy add: falta la regla — kj policy add "el coder no toca los workflows"');
+    return 1;
+  }
+  const { translateFn = defaultTranslate } = deps;
+  const raw = await translateFn({ text, config, logger });
+  if (raw.includes("NO_TRADUCIBLE")) {
+    logger.error?.("policy add: la regla no cabe en el vocabulario cerrado v1 — no se inventa nada; exprésala como write/shell/diff-threshold o queda como instrucción de prompt");
+    return 1;
+  }
+  let frag;
+  try {
+    frag = yaml.load(raw);
+  } catch (err) {
+    logger.error?.(`policy add: el agente no devolvió YAML válido (${err.message}) — nada que aplicar`);
+    return 1;
+  }
+  if (typeof frag !== "object" || frag === null || Object.keys(frag).some((k) => !["roles", "invariants"].includes(k))) {
+    logger.error?.("policy add: el fragmento solo puede declarar roles y/o invariants — rechazado (vocabulario cerrado)");
+    return 1;
+  }
+
+  const file = join(projectDir, ".karajan", "policy.yml");
+  let current = "";
+  try {
+    current = readFileSync(file, "utf8");
+  } catch { /* sin policy previa: se propone crearla */ }
+  const merged = mergeFragment(current ? yaml.load(current) || {} : {}, frag);
+  const proposed = yaml.dump(merged, { lineWidth: 100 });
+  const { errors } = parsePolicy(proposed);
+  if (errors.length > 0) {
+    for (const e of errors) logger.error?.(`✗ ${e}`);
+    logger.error?.("policy add: la regla traducida no valida contra el vocabulario del motor — rechazada, no se inventa");
+    return 1;
+  }
+
+  logger.info?.(`policy add — diff propuesto para .karajan/policy.yml:\n${naiveDiff(current, proposed)}`);
+  if (current.includes("#")) {
+    logger.warn?.("⚠ policy add: el fichero actual tiene comentarios y el rewrite NO los preserva — revisa el diff antes de confirmar");
+  }
+  if (!flags.yes) {
+    logger.info?.("policy add: NADA aplicado — re-ejecuta con --yes para escribir (la confirmación es tuya, no del agente)");
+    return 0;
+  }
+  // Primer run sin .karajan/ (catch de codex): crear el padre, no reventar.
+  mkdirSync(join(projectDir, ".karajan"), { recursive: true });
+  writeFileSync(file, proposed, "utf8");
+  logger.info?.("✓ policy add: regla aplicada — los gates (review, pre-commit, tier C) la aplican desde ya");
+  return 0;
+}

package/src/policy/decisions.js

@@ -0,0 +1,42 @@
+/**
+ * Adaptador del registro de decisiones para karajan-code (GOV-C,
+ * KJC-TSK-0747): almacén `.karajan/policy-decisions.jsonl`; policy_hash =
+ * sha256 del policy.yml CRUDO (null sin policy — la decisión lo dice, no
+ * lo inventa). Append no atómico entre procesos: aceptado, el chokepoint
+ * de commit es secuencial.
+ */
+import { appendFileSync, mkdirSync, readFileSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { join } from "node:path";
+import { recordDecision } from "@karajan-family/governance";
+
+const filePath = (projectDir) => join(projectDir, ".karajan", "policy-decisions.jsonl");
+
+export function policyFileHash(projectDir) {
+  try {
+    return createHash("sha256").update(readFileSync(join(projectDir, ".karajan", "policy.yml"), "utf8"), "utf8").digest("hex");
+  } catch {
+    return null;
+  }
+}
+
+/** @returns {object} the sealed record. */
+export function recordGateDecision(projectDir, entry) {
+  return recordDecision({
+    entry,
+    deps: {
+      lastLine: () => {
+        try {
+          const lines = readFileSync(filePath(projectDir), "utf8").split("\n").filter((l) => l.trim());
+          return lines.at(-1) ?? null;
+        } catch {
+          return null;
+        }
+      },
+      append: (line) => {
+        mkdirSync(join(projectDir, ".karajan"), { recursive: true });
+        appendFileSync(filePath(projectDir), `${line}\n`, "utf8");
+      },
+    },
+  });
+}