karajan-code 4.16.0 → 4.18.0

package/README.md

@@ -75,6 +75,16 @@ Karajan **governs** any agent with git gates — the false green is structurally
 
 Synchronous blocking hooks exist today only in Claude Code. That makes the supported setup explicit: **to guarantee a harness that controls the LLM, use Claude Code as the host** — Claude writes, Codex reviews (a review subprocess needs no hooks), and a third CLI arbitrates when available. On any other host Karajan still governs at the full git-gate level and tells you which level is active — it never pretends a supervision it cannot enforce.
 
+With a declared `.karajan/policy.yml`, the policy layer enforces at three tiers, and which tier applies depends on the host:
+
+| Tier | Where | Requires | What it guarantees |
+|---|---|---|---|
+| **A — tool time** | Sentinel PreToolUse → `kj policy eval --strict` | Claude Code as host (synchronous hooks) | The rule fires BEFORE the damage; the acting agent's role travels in `KJ_POLICY_ROLE` |
+| **B — commit time** | `kj review --staged` / pre-commit → deny + evidentiary exceptions | Any host (the gate lives in git) | The violating diff never enters, no matter who wrote it or what host ran it |
+| **C — merge time** | `kj-policy.yml` CI workflow → `kj policy check --range --strict` | GitHub Actions (seeded by `kj harden`) | Covers a tampered local hook: the PR diff is re-checked against the same policy, merge-blocking |
+
+Tier B is the guarantee floor — hosts without hooks lose A, never B; C re-verifies both. Security-class rules and consumer defaults are non-exemptable at every tier: no escape, no arbitration, no grant.
+
 ## Headless mode
 
 The classic multiagent pipeline lives on for CI and automation: `kj run "<task>"` orchestrates coder/reviewer/tester subprocess roles unattended, with the same gates. Agents and CI pass `--non-interactive` (or `KJ_NON_INTERACTIVE=1`): safe gates auto-answer, FAIL findings stop the run with a real exit code. `kj advanced` lists the full surface. [Headless mode docs](https://karajancode.com/docs/v4/headless/).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "karajan-code",
-  "version": "4.16.0",
+  "version": "4.18.0",
   "description": "Local multi-agent coding orchestrator with TDD, SonarQube, and code review pipeline",
   "type": "module",
   "license": "AGPL-3.0",
@@ -37,7 +37,8 @@
   "workspaces": [
     "packages/ai-trash",
     "packages/core",
-    "packages/hu-board"
+    "packages/hu-board",
+    "packages/governance"
   ],
   "imports": {
     "#utils/*": "./src/utils/*",
@@ -100,6 +101,7 @@
   },
   "dependencies": {
     "@babel/parser": "^7.29.7",
+    "@karajan-family/governance": "^0.1.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "better-sqlite3": "^12.10.0",
     "chokidar": "^5.0.0",

package/src/agents/claude-agent.js

@@ -365,6 +365,11 @@ export class ClaudeAgent extends BaseAgent {
   async _runTaskExec(task, model, _role) {
     const args = buildPromptArgs(task);
     if (model) args.push("--model", model);
+    // PL-C (KJC-TSK-0735): el rol del subproceso viaja en KJ_POLICY_ROLE —
+    // si su harness corre hooks (claude -p), el tier A evalúa la policy con
+    // el rol que ACTÚA. El rol del ORQUESTADOR es autoritativo: task.env no
+    // puede spoofearlo (catch de codex: sería un bypass de reglas por rol).
+    const roleEnv = task.role ? { ...task.env, KJ_POLICY_ROLE: task.role } : task.env;
 
     // Use stream-json when onOutput is provided to get real-time feedback
     if (task.onOutput) {
@@ -374,7 +379,7 @@ export class ClaudeAgent extends BaseAgent {
         onOutput: streamFilter,
         silenceTimeoutMs: task.silenceTimeoutMs,
         timeout: task.timeoutMs,
-        env: task.env,
+        env: roleEnv,
         cwd: task.cwd
       }));
       const raw = pickOutput(res);
@@ -385,7 +390,7 @@ export class ClaudeAgent extends BaseAgent {
 
     // Without streaming, use json output to get structured response via stderr
     args.push("--output-format", "json");
-    const res = await this.runCommand(resolveBin("claude"), args, cleanExecaOpts({ env: task.env, cwd: task.cwd }));
+    const res = await this.runCommand(resolveBin("claude"), args, cleanExecaOpts({ env: roleEnv, cwd: task.cwd }));
     const raw = pickOutput(res);
     const output = extractTextFromStreamJson(raw);
     const usage = extractUsageFromStreamJson(raw);

package/src/cli/advanced-commands.js

@@ -30,7 +30,7 @@ export const ADVANCED_GROUPS = [
   { title: "Pipeline (piezas sueltas)", commands: ["autorun", "code", "review", "solomon", "agent", "scan", "tournament"] },
   { title: "Análisis pre-run", commands: ["discover", "triage", "researcher", "architect", "onboard", "brief"] },
   { title: "Búsqueda / RAG", commands: ["rag", "qmd", "watch"] },
-  { title: "Calidad / auditoría", commands: ["audit", "check", "mutate", "webperf", "sonar", "privacy", "release"] },
+  { title: "Calidad / auditoría", commands: ["audit", "check", "mutate", "webperf", "sonar", "privacy", "release", "policy"] },
   { title: "Sesión / board", commands: ["resume", "report", "board", "hu", "adr", "worktree", "undo", "standby", "sentinel"] },
   { title: "Infra / setup", commands: ["install-tools", "ollama", "skills", "roles", "agents", "env"] },
   { title: "Mantenimiento", commands: ["clean", "sync", "telemetry", "report-issue"] },

package/src/cli/register-meta.js

@@ -27,6 +27,7 @@ import { huCommand } from "../commands/hu.js";
 import { worktreeCommand } from "../commands/worktree.js";
 import { addAdr, listAdrs } from "../environment/adr.js";
 import { formatAdvancedIndex } from "../commands/advanced.js";
+import { policyAddCommand } from "../policy/add.js";
 import { withConfig } from "./_shared.js";
 import { existsSync } from "node:fs";
 import { join } from "node:path";
@@ -284,6 +285,61 @@ export function registerMeta(program, { pkgVersion }) {
       });
     });
 
+  // KJC-TSK-0733 PL-A — policy as code: motor determinista en modo warn.
+  const policyCmd = program.command("policy").description("Policy as code (.karajan/policy.yml, vocabulario cerrado) — PL-A: modo warn");
+  policyCmd.command("eval")
+    .description("Evalúa UNA tool call: imprime {decision, rule_id, reason}; --strict devuelve exit 2 en deny (contrato para adaptadores de hooks)")
+    .option("--role <role>", "Rol del agente", "coder")
+    .option("--tool <tool>", "Tool (Write, Edit, Bash…)")
+    .option("--input <json>", "tool_input en JSON")
+    .option("--strict", "Exit 2 si deny")
+    .action(async (flags) => {
+      await withConfig(pkgVersion, "policy-eval", flags, async ({ config }) => {
+        const { policyCommand } = await import("../commands/policy.js");
+        process.exitCode = await policyCommand({ action: "eval", config, flags });
+      });
+    });
+  policyCmd.command("grant")
+    .description("Concede una excepción PERMANENTE con caducidad a una regla NO-security: quién (identidad), regla exacta, justificación y hasta cuándo — GOV-B")
+    .option("--rule <rule_id>", "Regla exacta (p.ej. roles.coder.write.deny)")
+    .option("--until <iso>", "Caducidad ISO-8601 (p.ej. 2026-09-01T00:00:00Z)")
+    .option("--reason <text>", "Justificación escrita en el momento")
+    .action(async (flags) => {
+      await withConfig(pkgVersion, "policy-grant", flags, async ({ config }) => {
+        const { policyCommand } = await import("../commands/policy.js");
+        process.exitCode = await policyCommand({ action: "grant", config, flags });
+      });
+    });
+  policyCmd.command("add")
+    .description("Traduce una regla hablada al vocabulario cerrado de policy.yml — propone el diff y SOLO escribe con --yes (PL-C)")
+    .argument("<text...>", "La regla en lenguaje natural")
+    .option("--yes", "Aplicar el diff propuesto")
+    .action(async (textParts, flags) => {
+      await withConfig(pkgVersion, "policy-add", flags, async ({ config, logger }) => {
+        process.exitCode = await policyAddCommand({ text: textParts.join(" "), config, flags, logger });
+      });
+    });
+  policyCmd.command("anchor")
+    .description("Verifica la cadena del decision log y sella su head-hash en .karajan/policy-anchor.json (trackeado) — anclaje temporal en la historia de git, GOV-C2")
+    .action(async (flags) => {
+      await withConfig(pkgVersion, "policy-anchor", flags, async ({ config }) => {
+        const { policyCommand } = await import("../commands/policy.js");
+        process.exitCode = await policyCommand({ action: "anchor", config, flags });
+      });
+    });
+  policyCmd.command("check")
+    .description("Comprueba el diff (staged, o base...head con --range) contra la policy — warn por defecto; --strict devuelve exit 2 si hay violación enforcement=deny (tier C, merge-blocking)")
+    .option("--role <role>", "Rol del agente", "coder")
+    .option("--range <ref>", "Evalúa un rango git (p.ej. origin/main...HEAD) en vez del staged (CI)")
+    .option("--strict", "Exit 2 si hay violación con enforcement=deny")
+    .option("--json", "Machine-readable")
+    .action(async (flags) => {
+      await withConfig(pkgVersion, "policy-check", flags, async ({ config }) => {
+        const { policyCommand } = await import("../commands/policy.js");
+        process.exitCode = await policyCommand({ action: "check", config, flags });
+      });
+    });
+
   // KJC-TSK-0713 — the Sentinel: the method state the harness hooks record.
   const sentinel = program.command("sentinel").description("Deterministic method supervisor wired into the harness hooks (Claude Code)");
   sentinel.command("status")

package/src/commands/policy.js

@@ -0,0 +1,164 @@
+/**
+ * `kj policy` — PL-A parte 3b (KJC-TSK-0733, épica KJC-PCS-0074). El motor
+ * en modo WARN: eval de una tool call y check del diff staged contra
+ * `.karajan/policy.yml`. En PL-A nada bloquea salvo un fichero de policy
+ * inválido (exit 1: declarar lo inaplicable es error del fichero, no aviso).
+ * `eval --strict` devuelve exit 2 en deny — el contrato para los adaptadores
+ * de hooks de PL-B. Los dientes de check llegan en PL-B/PL-C.
+ */
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { createHash } from "node:crypto";
+import { readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { checkStagedDiff, evalToolCall, loadPolicy } from "../policy/engine.js";
+import { loadStandingExceptions, recordPolicyException } from "../policy/exceptions.js";
+import { verifyDecisionChain } from "@karajan-family/governance";
+
+const execFileAsync = promisify(execFile);
+
+async function stagedFacts(projectDir, gitFn, range = null) {
+  const run =
+    gitFn ||
+    (async (args) => (await execFileAsync("git", args, { cwd: projectDir, maxBuffer: 16 * 1024 * 1024 })).stdout);
+  // PL-C (KJC-TSK-0735): en CI no hay staged — con --range se evalúa
+  // base...head, el MISMO motor sobre el diff del PR (tier C del ADR 0001).
+  const base = range ? ["diff", range] : ["diff", "--cached"];
+  const files = (await run([...base, "--name-only"]))
+    .split("\n")
+    .map((s) => s.trim())
+    .filter(Boolean);
+  let net = 0;
+  for (const line of (await run([...base, "--numstat"])).split("\n")) {
+    const [a, r] = line.trim().split(/\s+/);
+    if (a && a !== "-") net += Number(a) || 0;
+    if (r && r !== "-") net -= Number(r) || 0;
+  }
+  return { files, netLinesAdded: net };
+}
+
+export async function policyCommand({ action, config = {}, flags = {}, logger = console, deps = {} }) {
+  const projectDir = config?.projectDir || process.cwd();
+  const { policy, errors } = loadPolicy({ projectDir, deps });
+  if (errors.length > 0) {
+    for (const e of errors) logger.error?.(`✗ ${e}`);
+    logger.error?.("policy: el fichero declara lo que el motor no puede aplicar — corrígelo (una regla que miente es peor que ninguna)");
+    return 1;
+  }
+
+  // GOV-C2 (KJC-TSK-0749): anclaje temporal sin blockchain — verificar la
+  // cadena ENTERA y sellar su head-hash en un fichero TRACKEADO por git:
+  // reescribir el log de ayer exige reescribir el repo de ayer. Un anchor
+  // previo con más entradas que el log actual = truncado ⇒ no se re-sella.
+  if (action === "anchor") {
+    let raw;
+    try {
+      raw = readFileSync(join(projectDir, ".karajan", "policy-decisions.jsonl"), "utf8");
+    } catch {
+      logger.info?.("policy anchor: sin decisiones que anclar — el log nace con el primer deny/excepción/commit-allow");
+      return 0;
+    }
+    const lines = raw.split("\n").filter((l) => l.trim());
+    // Fichero vacío o solo whitespace = sin decisiones (catch de codex:
+    // lines.at(-1) undefined reventaba el hash en vez de salir limpio).
+    if (lines.length === 0) {
+      logger.info?.("policy anchor: sin decisiones que anclar — el log nace con el primer deny/excepción/commit-allow");
+      return 0;
+    }
+    const chain = verifyDecisionChain(lines);
+    if (!chain.ok) {
+      logger.error?.(`✗ policy anchor: cadena rota en la entrada ${chain.at} (${chain.reason}) — el log ha sido manipulado; NO se sella`);
+      return 1;
+    }
+    const anchorFile = join(projectDir, ".karajan", "policy-anchor.json");
+    try {
+      const prev = JSON.parse(readFileSync(anchorFile, "utf8"));
+      if (Number.isFinite(prev.length) && prev.length > chain.length) {
+        logger.error?.(`✗ policy anchor: el log retrocede (anchor previo=${prev.length} entradas, actual=${chain.length}) — truncado tras el último sello; NO se re-sella`);
+        return 1;
+      }
+    } catch { /* sin anchor previo (o ilegible): primer sello */ }
+    const head = createHash("sha256").update(lines.at(-1), "utf8").digest("hex");
+    writeFileSync(anchorFile, `${JSON.stringify({ head, length: chain.length, ts: new Date().toISOString() }, null, 2)}\n`, "utf8");
+    logger.info?.(`✓ policy anchor: cadena íntegra (${chain.length} decisiones) — head ${head.slice(0, 12)} sellado en .karajan/policy-anchor.json; committéalo para anclarlo en la historia de git`);
+    return 0;
+  }
+
+  // GOV-B (KJC-TSK-0746): conceder una excepción PERMANENTE con el modelo
+  // probatorio completo — quién (identidad), regla exacta, justificación en
+  // el momento y caducidad obligatoria. Los defaults.* del consumidor son
+  // inexcepcionables: no se conceden ni desde aquí.
+  if (action === "grant") {
+    const { rule, until, reason } = flags;
+    if (!rule || !until || !reason?.trim()) {
+      logger.error?.("policy grant: --rule, --until (ISO) y --reason son obligatorios — una excepción sin quién/por qué/hasta cuándo no es una excepción, es un agujero");
+      return 1;
+    }
+    // Inexcepcionable = inexcepcionable TAMBIÉN al conceder (catch de codex):
+    // defaults.*, cualquier cap con class security, y una policy inválida
+    // (sin policy legible no se puede probar que la regla NO es security).
+    const m = /^roles\.([^.]+)\.(write|shell)/.exec(rule);
+    if (rule.startsWith("defaults.") || errors.length > 0 || (m && policy.roles?.[m[1]]?.[m[2]]?.class === "security")) {
+      logger.error?.(`policy grant: "${rule}" es inexcepcionable (default del proyecto o clase security) o la policy no es verificable — no se concede, ni con razón`);
+      return 1;
+    }
+    try {
+      // GOV-E (KJC-TSK-0750, idea del lector): la renovación es SEÑAL — una
+      // regla re-concedida N veces es la política real pidiendo que la
+      // cambien por su cauce. Se cuenta contra TODAS las permanentes previas
+      // (vencidas incluidas: precisamente esas son la sedimentación).
+      const previous = loadStandingExceptions(projectDir).standing.filter((e) => e.rule_id === rule).length;
+      const rec = recordPolicyException({
+        projectDir,
+        entry: { rule_id: rule, justification: reason.trim(), scopeKind: "permanente", expiresAt: until },
+      });
+      logger.info?.(`✓ excepción permanente registrada: [${rec.rule_id}] hasta ${rec.expiresAt} — concedida por ${rec.who?.git ?? "?"} (${rec.who?.grade ?? "?"})`);
+      if (previous >= 1) {
+        logger.warn?.(`⚠ ${previous + 1}ª concesión sobre esta regla — una excepción que se renueva ya no es una excepción: considera cambiar la política por su cauce (PR a .karajan/policy.yml)`);
+      }
+      return 0;
+    } catch (err) {
+      logger.error?.(`policy grant: ${err.message}`);
+      return 1;
+    }
+  }
+
+  if (action === "eval") {
+    let input;
+    try {
+      input = flags.input ? JSON.parse(flags.input) : {};
+    } catch {
+      logger.error?.("policy eval: --input debe ser JSON válido");
+      return 1;
+    }
+    const verdict = evalToolCall(policy, { role: flags.role || "coder", tool: flags.tool, input, root: projectDir });
+    logger.info?.(JSON.stringify(verdict));
+    return verdict.decision === "deny" && flags.strict ? 2 : 0;
+  }
+
+  // check — staged por defecto, base...head con --range (CI). Warn salvo
+  // --strict (PL-C): con --strict, una violación enforcement=deny devuelve
+  // exit 2 nombrando la regla — el contrato merge-blocking del tier C.
+  const facts = await stagedFacts(projectDir, deps.gitFn, flags.range || null);
+  const violations = checkStagedDiff(policy, { role: flags.role || "coder", ...facts });
+  const hard = flags.strict ? violations.filter((v) => v.enforcement === "deny") : [];
+  if (flags.json) {
+    logger.info?.(JSON.stringify({ mode: flags.strict ? "strict" : "warn", violations }));
+    return hard.length > 0 ? 2 : 0;
+  }
+  if (violations.length === 0) {
+    logger.info?.("policy check: limpio");
+    return 0;
+  }
+  for (const v of violations) {
+    const where = v.file ? ` (${v.file})` : "";
+    const mark = flags.strict && v.enforcement === "deny" ? "✗" : "⚠";
+    logger.warn?.(`${mark} policy [${v.rule_id}] ${v.reason}${where}`);
+  }
+  if (hard.length > 0) {
+    logger.error?.(`policy check: ${hard.length} violación(es) con enforcement=deny — el merge no procede (--strict)`);
+    return 2;
+  }
+  logger.warn?.(`policy check: ${violations.length} aviso(s) — check es modo warn, no bloquea; los deny los aplican kj review --staged y el pre-commit (PL-B)`);
+  return 0;
+}

package/src/commands/review-gate.js

@@ -8,7 +8,7 @@
 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";
@@ -16,6 +16,10 @@ import { runSonarPregate, formatSonarFinding } from "../review/sonar-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 +79,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 +148,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 +165,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 +221,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 +288,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;
   }

package/src/harden/sentinel-hooks.js

@@ -49,6 +49,21 @@ export const branchOf = () => {
   try { return execSync("git rev-parse --abbrev-ref HEAD", { cwd: ROOT, stdio: ["ignore", "pipe", "ignore"] }).toString().trim(); }
   catch { return null; }
 };
+const _git = (args, cwd) => {
+  try { return execSync("git " + args, { cwd, stdio: ["ignore", "pipe", "ignore"] }).toString().trim(); } catch { return ""; }
+};
+let _home;
+// MONO-0 (ADR 0002): lane identity = worktree toplevel; repo identity =
+// git-common-dir. Same repo but another toplevel than OUR root => foreign
+// lane (returns its toplevel); anything else => null.
+export const foreignLane = (targetDir) => {
+  const top = _git("rev-parse --show-toplevel", targetDir);
+  if (!top) return null;
+  _home ||= { top: _git("rev-parse --show-toplevel", ROOT), common: _git("rev-parse --path-format=absolute --git-common-dir", ROOT) };
+  if (!_home.top || top === _home.top) return null;
+  const common = _git("rev-parse --path-format=absolute --git-common-dir", targetDir);
+  return common && common === _home.common ? top : null;
+};
 export const violations = (s, branch) => {
   const v = [];
   if (!s || !(s.edited_sources || []).length) return v;
@@ -73,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", () => {
@@ -177,9 +192,10 @@ const PRETOOL_BODY = `#!/usr/bin/env node
 // before the damage, not in the post-mortem. Exit 2 blocks (stderr says the
 // remediation); read-only tools are never wired here; every honored escape
 // is recorded as an auditable event. Fails OPEN on anything unexpected.
-import { relative } from "node:path";
+import { dirname, relative, resolve } from "node:path";
+import { existsSync, realpathSync, statSync } from "node:fs";
 import { spawnSync } from "node:child_process";
-import { CODE, TESTS, ROOT, BASE_BRANCHES, CARD, branchOf, load, violations, recordEscape } from "./sentinel-lib.mjs";
+import { CODE, TESTS, ROOT, BASE_BRANCHES, CARD, branchOf, foreignLane, load, violations, recordEscape } from "./sentinel-lib.mjs";
 const EDIT_TOOLS = ["Write", "Edit", "MultiEdit", "NotebookEdit"];
 const PUBLISH = /\\bnpm\\s+publish\\b|\\bfirebase\\s+deploy\\b|\\bgh\\s+release\\s+create\\b/;
 const PUSH = /\\bgit\\s+push\\b/;
@@ -210,6 +226,144 @@ process.stdin.on("end", () => {
       process.exit(2);
     }
     if (process.env.KJ_SENTINEL_OFF === "1") process.exit(0);
+    // MONO-0 (KJC-TSK-0737, ADR 0002): cada sesion muta solo SU worktree;
+    // otro carril del MISMO repo se deniega ANTES del dano. Lectura libre.
+    const laneOf = (p) => {
+      // Sube al primer ancestro EXISTENTE (un subdir aun no creado escapaba).
+      let d = String(p);
+      if (!(existsSync(d) && statSync(d).isDirectory())) d = dirname(d);
+      while (d && !existsSync(d)) {
+        const up = dirname(d);
+        if (up === d) return null;
+        d = up;
+      }
+      // Canonicaliza (reviewer catch: un symlink local hacia otro carril
+      // esquivaba la clasificacion por ruta literal).
+      try { d = realpathSync(d); } catch { /* se clasifica tal cual */ }
+      return d ? foreignLane(d) : null;
+    };
+    const laneDeny = (what, lane) => {
+      if (process.env.KJ_ALLOW_CROSS_LANE === "1") { recordEscape(sid, "KJ_ALLOW_CROSS_LANE", tool); return false; }
+      console.error("kj sentinel: " + what + " vive en otro carril (" + lane + ") de este repo — cada sesion muta solo SU worktree (MONO-0). Cruce deliberado: KJ_ALLOW_CROSS_LANE=1, queda registrado.");
+      return true;
+    };
+    if (EDIT_TOOLS.includes(tool)) {
+      const target = input.file_path || input.notebook_path;
+      const lane = target ? laneOf(target) : null;
+      if (lane && laneDeny(String(target), lane)) process.exit(2);
+    }
+    if (tool === "Bash") {
+      const cmd = String(input.command || "");
+      // Deny-unless-known-read-only: un allowlist de verbos mutadores era
+      // esquivable (dd, interpretes). Solo un comando SIMPLE de lectura (sin
+      // encadenar ni redirigir) puede nombrar otro carril; leer carriles es
+      // trabajo de las tools Read/Grep, como con los ficheros del supervisor.
+      // Solo LITERALES: expansión/sustitución en un comando "de lectura"
+      // puede ejecutar cualquier cosa (reviewer catch: grep foo $(rm ...)).
+      // (find fuera: -delete/-exec mutan — reviewer catch; sus tokens de
+      // carril los caza el escaner de abajo.)
+      const READONLY = /^[ \\t]*(grep|rg|cat|head|tail|less|ls|wc|diff|stat|file|du|tree|git (log|show|diff|status|blame))\\b[^;|&<>$\`(){}\\n\\r]*$/;
+      if (!READONLY.test(cmd)) {
+        // cd/pushd invalida TODO razonamiento textual de rutas posteriores
+        // (carrera de bypasses confirmada en review: destino bare, con $,
+        // relativas post-cd...): en un comando NO-read-only, cambiar de
+        // directorio se deniega conservadoramente — el remedio es no
+        // necesitarlo (git -C, npm --prefix, rutas absolutas).
+        if (/(^|[;&|(\\s])(cd|pushd)([ \\t]|$)/.test(cmd)) {
+          if (process.env.KJ_ALLOW_CROSS_LANE === "1") { recordEscape(sid, "KJ_ALLOW_CROSS_LANE", tool); }
+          else {
+            console.error("kj sentinel: cd/pushd en un comando mutador — las rutas posteriores no son verificables por el guard de carriles (MONO-0); usa git -C / npm --prefix / rutas ABSOLUTAS sin cd (o KJ_ALLOW_CROSS_LANE=1, queda registrado).");
+            process.exit(2);
+          }
+        }
+        // Absolute AND dot-relative tokens (../lane escapaba al primer scan —
+        // reviewer catch); relative se resuelve contra el cwd de la sesion.
+        // EVERY token (un tope seria un bypass); dedup acota el coste git.
+        // Fallo de solomon (seguridad no arbitrable) + carrera de bypasses:
+        // la expansion ($, backtick) solo se tolera en segmentos que son
+        // asignaciones puras o runners del toolchain propio (npm/pnpm/yarn/
+        // vitest/jest/kj/gh/echo/printf, git sin -C/--git-dir/--work-tree) —
+        // sus argumentos son datos. En herramientas genericas de fichero o
+        // interpretes el objetivo queda oculto al texto => deny. Los paths
+        // LITERALES (tambien dentro de sustituciones) los escanea el bucle
+        // de tokens de abajo; el residuo (expansion anidada en segmentos
+        // runner) queda documentado como en la regla de ficheros PROTECTED.
+        if (/>{1,2}[ \\t]*["']?[\\$\`]/.test(cmd)) {
+          if (process.env.KJ_ALLOW_CROSS_LANE === "1") { recordEscape(sid, "KJ_ALLOW_CROSS_LANE", tool); }
+          else {
+            console.error("kj sentinel: redireccion con destino tras variable/sustitucion — el guard de carriles no puede verificarlo (MONO-0); usa una ruta LITERAL (o KJ_ALLOW_CROSS_LANE=1, queda registrado).");
+            process.exit(2);
+          }
+        }
+        // Sustitucion de comandos ($(...) o backticks) EJECUTA su contenido
+        // 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)) {
+          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).");
+            process.exit(2);
+          }
+        }
+        const SAFE_EXP_SEG = /^([A-Za-z_][A-Za-z0-9_]*=[^ \\t]*[ \\t]*)*((npm|pnpm|yarn|vitest|jest|kj|gh|echo|printf|true|test)\\b|git[ \\t](?![^\\n]*(-C[ \\t]|--git-dir|--work-tree)))[^;|&\\n]*$|^[A-Za-z_][A-Za-z0-9_]*=[^;|&\\n]*$/;
+        const segs = cmd.split(/&&|\\|\\||[;|\\n]/).map((s) => s.trim()).filter(Boolean);
+        if (!segs.every((s) => !/[\\$]/.test(s) || SAFE_EXP_SEG.test(s))) {
+          if (process.env.KJ_ALLOW_CROSS_LANE === "1") { recordEscape(sid, "KJ_ALLOW_CROSS_LANE", tool); }
+          else {
+            console.error("kj sentinel: expansion de shell en una herramienta generica de fichero/interprete — el objetivo no es verificable por el guard de carriles (MONO-0); usa rutas LITERALES o un runner del toolchain (o KJ_ALLOW_CROSS_LANE=1, queda registrado).");
+            process.exit(2);
+          }
+        }
+        // ...incluidas relativas A PELO (los carriles kj viven en
+        // .kj/worktrees/). Un falso token (s/a/b/) resuelve al arbol propio
+        // y foreignLane da null — solo deniega lo que CAE en otro carril.
+        const seen = new Set();
+        for (const m of cmd.matchAll(/(?:^|[\\s"'=;(><])((?:\\.\\.?\\/)[^\\s"'\`;|&)]*|\\/[^\\s"'\`;|&)]+|~\\/[^\\s"'\`;|&)]+|[A-Za-z0-9_.@-]+\\/[^\\s"'\`;|&)]+)/g)) {
+          const t = m[1].startsWith("~/") ? (process.env.HOME || "~") + m[1].slice(1) : m[1];
+          const abs = resolve(t);
+          if (seen.has(abs)) continue;
+          seen.add(abs);
+          const lane = laneOf(abs);
+          if (lane && laneDeny(m[1], lane)) process.exit(2);
+        }
+      }
+    }
+    // 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-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 _ownVersion;
+function ownVersion() {
+  if (_ownVersion === undefined) {
+    try {
+      _ownVersion = JSON.parse(
+        readFileSync(join(dirname(fileURLToPath(import.meta.url)), "..", "..", "package.json"), "utf8"),
+      ).version;
+    } catch {
+      _ownVersion = null;
+    }
+  }
+  return _ownVersion;
+}
 
 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 ?? ownVersion() ?? "latest";
+  const policy = existsSync(join(projectDir, ".karajan", "policy.yml"))
+    ? { file: "kj-policy.yml", blockId: "wf-policy", body: policyWorkflowFor(pinned) }
+    : 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) => [
+  "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 karajan-code@${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/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");
+      },
+    },
+  });
+}

package/src/policy/engine.js

@@ -0,0 +1,82 @@
+/**
+ * karajan-code policy ADAPTER (GOV-A, KJC-TSK-0745, ADR 0003). El motor
+ * vive en @karajan-family/governance (packages/governance): aquí queda SOLO lo
+ * que es de este dominio — dónde vive el fichero de policy, los defaults
+ * inexcepcionables del supervisor del Sentinel, y el mapeo de tools del
+ * harness (Write/Edit/Bash…) a capabilities del kernel. La superficie
+ * pública de este módulo no cambia: loadPolicy/evalToolCall/checkStagedDiff
+ * siguen siendo lo que los gates de PL-B consumen.
+ */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import {
+  ALLOW_VERDICT,
+  checkArtifacts,
+  denyVerdict,
+  evalShell,
+  evalWrite,
+  parsePolicy,
+  DEFAULT_POLICY as KERNEL_DEFAULT_POLICY,
+} from "@karajan-family/governance";
+
+// Defaults inexcepcionables de karajan-code: los ficheros del supervisor
+// (antes hardcodeados en el PRETOOL del Sentinel — PL-B). Misma semántica
+// textual: nombrarlos deniega, con o sin root, y la policy no los debilita.
+export const SUPERVISOR_DEFAULTS = [
+  {
+    id: "defaults.supervisor.write",
+    pattern: /\.claude\/settings\.json\b|\.karajan\/(hooks|harness)\//,
+    message: "nombra ficheros del supervisor — solo el humano los modifica, fuera de la sesión",
+  },
+];
+
+// Tools del harness: mapeo acción → capability del kernel. Registro cerrado
+// (fallo de solomon: lo desconocido no se permite a un rol DECLARADO).
+const WRITE_TOOLS = new Set(["Write", "Edit", "MultiEdit", "NotebookEdit"]);
+const READONLY_TOOLS = new Set(["Read", "Grep", "Glob", "LS", "WebFetch", "WebSearch"]);
+
+export const DEFAULT_POLICY = KERNEL_DEFAULT_POLICY;
+
+function defaultReadFile(projectDir) {
+  try {
+    return readFileSync(join(projectDir, ".karajan", "policy.yml"), "utf8");
+  } catch (err) {
+    // Solo ENOENT es "sin policy"; EACCES/EIO seria un fallback silencioso.
+    if (err.code === "ENOENT") return null;
+    throw err;
+  }
+}
+
+/**
+ * @returns {{policy: object, errors: string[]}} errors non-empty ⇒ the file
+ * declares something the engine cannot enforce — callers must surface it.
+ */
+export function loadPolicy({ projectDir = process.cwd(), deps = {} } = {}) {
+  const { readFile = defaultReadFile } = deps;
+  let raw;
+  try {
+    raw = readFile(projectDir);
+  } catch (err) {
+    return {
+      policy: { ...KERNEL_DEFAULT_POLICY, defaults: SUPERVISOR_DEFAULTS },
+      errors: [`policy.yml: ilegible (${err.code || err.message}) — presente pero no leible NO es "sin policy"`],
+    };
+  }
+  return parsePolicy(raw, { defaults: SUPERVISOR_DEFAULTS });
+}
+
+/** One tool call against the policy. `root` permite evaluar file_path
+ *  absolutos. Un rol DECLARADO solo usa tools del registro: lo desconocido
+ *  es no-verificable ⇒ deny (roles sin declarar quedan como hoy). */
+export function evalToolCall(policy, { role = "coder", tool, input = {}, root = null }) {
+  if (WRITE_TOOLS.has(tool)) return evalWrite(policy, role, input.file_path || input.notebook_path, root);
+  if (tool === "Bash") return evalShell(policy, role, input.command);
+  if (READONLY_TOOLS.has(tool) || !policy.roles?.[role]) return ALLOW_VERDICT;
+  return denyVerdict(`roles.${role}.tools`, `tool "${tool}" fuera del registro de la policy — no verificable para el rol declarado ${role}`);
+}
+
+/** El gate del RESULTADO en este dominio: los artefactos son los ficheros
+ *  del diff staged y la métrica sale de numstat. */
+export function checkStagedDiff(policy, facts) {
+  return checkArtifacts(policy, facts);
+}

package/src/policy/exceptions.js

@@ -0,0 +1,60 @@
+/**
+ * Adaptador de excepciones de karajan-code (GOV-A, KJC-TSK-0745). El
+ * registro vive en el kernel (@karajan-family/governance); aquí solo lo que es de
+ * este dominio: la identidad (git user + usuario del SO — DECLARADA, no
+ * autenticada) y el destino append-only `.karajan/policy-exceptions.jsonl`.
+ */
+import { appendFileSync, mkdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { userInfo } from "node:os";
+import { spawnSync } from "node:child_process";
+import { recordPolicyException as kernelRecord } from "@karajan-family/governance";
+
+function defaultIdentity(projectDir) {
+  const git = (args) => spawnSync("git", ["-C", projectDir, "config", ...args], { encoding: "utf8" }).stdout?.trim() || null;
+  // grade DECLARADA: git+os es atribución, no autenticación — el registro
+  // no debe venderse como más evidencia de la que es (GOV-B).
+  return { git: `${git(["user.name"]) ?? "?"} <${git(["user.email"]) ?? "?"}>`, os: userInfo().username, grade: "declarada" };
+}
+
+/**
+ * Standing exceptions del dominio code: las permanentes del jsonl. Parse
+ * TOLERANTE — una línea corrupta se descarta CONTÁNDOLA (el gate la
+ * reporta), jamás rompe la evaluación. Las puntuales no dan standing.
+ * @returns {{standing: object[], discarded: number}}
+ */
+export function loadStandingExceptions(projectDir) {
+  let raw;
+  try {
+    raw = readFileSync(join(projectDir, ".karajan", "policy-exceptions.jsonl"), "utf8");
+  } catch {
+    return { standing: [], discarded: 0 };
+  }
+  const standing = [];
+  let discarded = 0;
+  for (const line of raw.split("\n")) {
+    if (!line.trim()) continue;
+    try {
+      const rec = JSON.parse(line);
+      // JSON válido pero no-objeto (null, número…) es tan corrupto como el
+      // que no parsea: se descarta contando (catch de codex, explícito).
+      if (typeof rec !== "object" || rec === null) discarded += 1;
+      else if (rec.scopeKind === "permanente") standing.push(rec);
+    } catch {
+      discarded += 1;
+    }
+  }
+  return { standing, discarded };
+}
+
+function defaultAppend(projectDir, line) {
+  const dir = join(projectDir, ".karajan");
+  mkdirSync(dir, { recursive: true });
+  appendFileSync(join(dir, "policy-exceptions.jsonl"), line, "utf8");
+}
+
+/** @returns {object} the recorded entry (with ts + who resolved). */
+export function recordPolicyException({ projectDir, entry, deps = {} }) {
+  const { append = defaultAppend, identity = defaultIdentity } = deps;
+  return kernelRecord({ projectDir, entry, deps: { append, identity } });
+}

package/src/review/policy-gate.js

@@ -0,0 +1,26 @@
+/**
+ * Adaptador del gate de policy en el flujo de review de karajan-code
+ * (GOV-A, KJC-TSK-0745). La decisión warn/deny/inexcepcionable/excepción
+ * vive en el kernel (@karajan-family/governance); aquí solo el dominio: la
+ * excepción se pide con KJ_ALLOW_POLICY=1 + KJ_POLICY_REASON, y el
+ * artefacto de este dominio es el diff staged — por eso el alcance
+ * registrado dice "este diff exacto".
+ */
+import { evaluateGate } from "@karajan-family/governance";
+
+/**
+ * @returns {{ok: boolean, invalid?: boolean, warns: object[], denials: object[], exempted: object[]}}
+ */
+export function evaluatePolicyGate({
+  policy, errors = [], role = "coder", files = [], netLinesAdded = null,
+  diffHashValue = null, env = process.env, recordException = () => {},
+  standingExceptions = [], now = new Date(),
+}) {
+  return evaluateGate({
+    policy, errors, role, files, netLinesAdded,
+    artifactHash: diffHashValue,
+    exemption: { requested: env.KJ_ALLOW_POLICY === "1", justification: env.KJ_POLICY_REASON, hint: 'KJ_POLICY_REASON="por qué"' },
+    recordException: (entry) => recordException({ ...entry, scope: "este diff exacto" }),
+    standingExceptions, now,
+  });
+}