karajan-code 4.16.0 → 4.17.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "karajan-code",
-  "version": "4.16.0",
+  "version": "4.17.0",
   "description": "Local multi-agent coding orchestrator with TDD, SonarQube, and code review pipeline",
   "type": "module",
   "license": "AGPL-3.0",

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

@@ -284,6 +284,31 @@ 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("check")
+    .description("Comprueba el diff STAGED contra la policy (write-deny + invariantes) — siempre warn en PL-A; exit 1 solo si policy.yml es inválido")
+    .option("--role <role>", "Rol del agente", "coder")
+    .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,70 @@
+/**
+ * `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 { checkStagedDiff, evalToolCall, loadPolicy } from "../policy/engine.js";
+
+const execFileAsync = promisify(execFile);
+
+async function stagedFacts(projectDir, gitFn) {
+  const run =
+    gitFn ||
+    (async (args) => (await execFileAsync("git", args, { cwd: projectDir, maxBuffer: 16 * 1024 * 1024 })).stdout);
+  const files = (await run(["diff", "--cached", "--name-only"]))
+    .split("\n")
+    .map((s) => s.trim())
+    .filter(Boolean);
+  let net = 0;
+  for (const line of (await run(["diff", "--cached", "--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;
+  }
+
+  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 — sobre el diff staged (único modo en PL-A), SIEMPRE warn.
+  const facts = await stagedFacts(projectDir, deps.gitFn);
+  const violations = checkStagedDiff(policy, { role: flags.role || "coder", ...facts });
+  if (flags.json) {
+    logger.info?.(JSON.stringify({ mode: "warn", violations }));
+    return 0;
+  }
+  if (violations.length === 0) {
+    logger.info?.("policy check: limpio");
+    return 0;
+  }
+  for (const v of violations) {
+    logger.warn?.(`⚠ policy [${v.rule_id}] ${v.reason}${v.file ? ` (${v.file})` : ""}`);
+  }
+  logger.warn?.(`policy check: ${violations.length} aviso(s) — modo warn (PL-A): no bloquea; PL-B le dará dientes`);
+  return 0;
+}

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;
@@ -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,109 @@ 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);
+        }
+      }
+    }
     if (EDIT_TOOLS.includes(tool)) {
       const file = input.file_path || input.notebook_path;
       const rel = file ? relative(ROOT, String(file)).replaceAll("\\\\", "/") : "";

package/src/policy/engine.js

@@ -0,0 +1,276 @@
+/**
+ * policy engine — PL-A (KJC-TSK-0733, épica KJC-PCS-0074, ADR 0001).
+ * Policy as DATA (`.karajan/policy.yml`, vocabulario CERRADO), engine as
+ * code: módulo puro, determinista, sin red ni LLM. Una regla que el motor
+ * no puede aplicar falla FUERTE al cargar — jamás se ignora en silencio.
+ * Deny gana a allow; una allow-list convierte el exterior en denegación.
+ * Consumidores: kj policy (PL-A) → gates PL-B → CI PL-C → middleware PL-D.
+ */
+import { readFileSync } from "node:fs";
+import { isAbsolute, join, posix, relative } from "node:path";
+import yaml from "js-yaml";
+import { commandPatternToRegExp, matchesAny } from "./glob.js";
+
+// Vocabulario CERRADO e incremental: cada capacidad entra al set EN el PR
+// que trae su evaluación — declararla antes sería una regla que miente.
+const ROLE_CAPS = new Set(["write", "shell"]);
+const INVARIANT_KINDS = new Set(["diff-threshold"]);
+const INVARIANT_METRICS = new Set(["net_lines_added"]);
+const WRITE_TOOLS = new Set(["Write", "Edit", "MultiEdit", "NotebookEdit"]);
+// Registro de tools conocidas (fallo de solomon: lo desconocido no se
+// permite a un rol DECLARADO — crece por PR consciente).
+const READONLY_TOOLS = new Set(["Read", "Grep", "Glob", "LS", "WebFetch", "WebSearch"]);
+export const DEFAULT_POLICY = Object.freeze({ version: 1, roles: {}, invariants: [] });
+
+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 this 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: DEFAULT_POLICY, errors: [`policy.yml: ilegible (${err.code || err.message}) — presente pero no leible NO es "sin policy"`] };
+  }
+  if (raw == null) return { policy: DEFAULT_POLICY, errors: [] };
+
+  const errors = [];
+  let doc;
+  try {
+    doc = yaml.load(raw) || {};
+  } catch (err) {
+    return { policy: DEFAULT_POLICY, errors: [`policy.yml: YAML invalido — ${err.message}`] };
+  }
+  if (typeof doc !== "object" || Array.isArray(doc)) {
+    return { policy: DEFAULT_POLICY, errors: ["policy.yml: la raiz debe ser un objeto"] };
+  }
+  if (doc.version !== 1) {
+    errors.push(`policy.yml: version "${doc.version}" no soportada — este motor habla version 1`);
+  }
+  const roles = doc.roles ?? {};
+  if (typeof roles !== "object" || roles === null || Array.isArray(roles)) {
+    errors.push("policy.yml: roles debe ser un objeto");
+  } else {
+    validateRoles(roles, errors);
+  }
+  const invs = doc.invariants ?? [];
+  if (Array.isArray(invs)) {
+    for (const inv of invs) {
+      if (!INVARIANT_KINDS.has(inv?.kind)) {
+        errors.push(`policy.yml: invariant "${inv?.id}" con kind "${inv?.kind}" no existe en el vocabulario v1`);
+      } else if (!INVARIANT_METRICS.has(inv?.metric) || !Number.isFinite(inv?.max) || typeof inv?.id !== "string") {
+        errors.push(`policy.yml: invariant "${inv?.id}" requiere id string, metric (${[...INVARIANT_METRICS].join(", ")}) y max numérico`);
+      }
+    }
+  } else {
+    errors.push("policy.yml: invariants debe ser una lista");
+  }
+  return { policy: { roles: {}, invariants: [], ...doc }, errors };
+}
+
+function validateRoles(roles, errors) {
+  for (const [role, caps] of Object.entries(roles)) {
+    for (const [cap, spec] of Object.entries(caps || {})) {
+      if (!ROLE_CAPS.has(cap)) {
+        errors.push(`policy.yml: roles.${role}.${cap} no existe en el vocabulario (v1: ${[...ROLE_CAPS].join(", ")})`);
+        continue;
+      }
+      if (typeof spec !== "object" || spec === null || Array.isArray(spec)) {
+        errors.push(`policy.yml: roles.${role}.${cap} debe ser un objeto {allow, deny}`);
+        continue;
+      }
+      for (const key of Object.keys(spec)) {
+        if (key !== "allow" && key !== "deny") {
+          errors.push(`policy.yml: roles.${role}.${cap}.${key} no existe en el vocabulario (v1: allow, deny)`);
+        }
+      }
+      for (const list of ["allow", "deny"]) {
+        const v = spec?.[list];
+        if (v !== undefined && (!Array.isArray(v) || v.some((g) => typeof g !== "string"))) {
+          errors.push(`policy.yml: roles.${role}.${cap}.${list} debe ser una lista de strings (glob)`);
+        }
+      }
+    }
+  }
+}
+
+const deny = (rule_id, reason) => ({ decision: "deny", rule_id, reason });
+const ALLOW = Object.freeze({ decision: "allow" });
+
+// Normaliza el destino a ruta RELATIVA canónica: absolutas se relativizan
+// contra root (sin root ⇒ null), y `..`/escapes ⇒ null (reviewer catch:
+// src/../.env no puede esquivar los globs, ni una absoluta salirse del root).
+function normalizeTarget(filePath, root) {
+  let p = String(filePath).replaceAll("\\", "/");
+  if (isAbsolute(p)) {
+    if (!root) return null;
+    p = relative(root, p).replaceAll("\\", "/");
+  }
+  p = posix.normalize(p).replace(/^\.\//, "");
+  return p.startsWith("..") || isAbsolute(p) ? null : p;
+}
+
+function evalWrite(policy, role, filePath, root) {
+  const write = policy.roles?.[role]?.write;
+  if (!write) return ALLOW;
+  // Rol restringido + destino ausente/no-canonizable = no verificable ⇒ deny
+  // (reviewer catches: tool call malformado, traversal, absoluta sin root).
+  const p = filePath ? normalizeTarget(filePath, root) : null;
+  if (p == null) return deny(`roles.${role}.write`, `destino "${filePath ?? ""}" no verificable contra la policy del rol ${role}`);
+  if (matchesAny(p, write.deny)) {
+    return deny(`roles.${role}.write.deny`, `${p} esta denegado para el rol ${role}`);
+  }
+  if (Array.isArray(write.allow) && !matchesAny(p, write.allow)) {
+    return deny(`roles.${role}.write.allow`, `${p} esta fuera de la allow-list de escritura del rol ${role}`);
+  }
+  return ALLOW;
+}
+
+// Launchers y asignaciones de entorno se PELAN antes de casar patrones
+// (reviewer catch: "sudo git push" o "FOO=1 git add -A" no esquivan la
+// regla del subcomando real); capas excesivas ⇒ opaco ⇒ deny.
+const LAUNCHER_RE = /^(sudo(\s+-\S+)*|command|nohup|time|nice(\s+-n\s*\d+)?|stdbuf\s+\S+|env)\s+|^([A-Za-z_][A-Za-z0-9_]*=\S*\s+)+/;
+function stripLaunchers(seg) {
+  let s = seg;
+  for (let i = 0; i < 5; i++) {
+    const m = s.match(LAUNCHER_RE);
+    if (!m) return s;
+    // Asignaciones que alteran QUÉ ejecutable resuelve (PATH, LD_*, GIT_*,
+    // NODE_OPTIONS) o llevan expansión son opacas — no se pelan, denegan.
+    if (/^(PATH|LD_\w*|NODE_OPTIONS|GIT_\w*)=/.test(m[0]) || m[0].includes("$")) return null;
+    s = s.slice(m[0].length);
+  }
+  return null; // sigue envuelto tras 5 capas: no verificable
+}
+
+// Tokenizador consciente de comillas: separa segmentos SOLO por operadores
+// no entrecomillados (reviewer catch: un ';' dentro de un mensaje no es
+// separador) y canonicaliza tokens sin comillas a la vez. Cualquier
+// construcción que ejecute o redirija texto opaco al análisis — escapes,
+// expansión ($ salvo entre comillas simples), sustitución/backticks,
+// redirecciones, backgrounding, comillas sin cerrar — devuelve null.
+function parseCommand(cmd) {
+  const segs = [];
+  let toks = [];
+  let cur = "";
+  let q = null;
+  const pushTok = () => {
+    if (cur) {
+      toks.push(cur);
+      cur = "";
+    }
+  };
+  const pushSeg = () => {
+    pushTok();
+    if (toks.length > 0) {
+      segs.push(toks.join(" "));
+      toks = [];
+    }
+  };
+  const s = String(cmd);
+  for (let i = 0; i < s.length; i++) {
+    const ch = s[i];
+    if (ch === "\\" || ch === "`") return null;
+    if (ch === "$" && q !== "'") return null;
+    if (q) {
+      if (ch === q) q = null;
+      else cur += ch;
+      continue;
+    }
+    if (ch === '"' || ch === "'") {
+      q = ch;
+      continue;
+    }
+    if (ch === ">" || ch === "<") return null;
+    if (ch === "&" && s[i + 1] === "&") {
+      pushSeg();
+      i++;
+      continue;
+    }
+    if (ch === "|" && s[i + 1] === "|") {
+      pushSeg();
+      i++;
+      continue;
+    }
+    if (ch === "&") return null;
+    if (ch === ";" || ch === "|" || ch === "\n") {
+      pushSeg();
+      continue;
+    }
+    if (/\s/.test(ch)) {
+      pushTok();
+      continue;
+    }
+    cur += ch;
+  }
+  if (q) return null;
+  pushSeg();
+  return segs;
+}
+
+// Envolturas que re-ejecutan texto (lección del guard del Sentinel).
+const WRAPPER_RE = /^(sh|bash|zsh|dash|ksh)\s+(-\S+\s+)*-\S*c(\s|$)|^eval\b|^xargs\b|^source\b|^\.\s/;
+
+// Deny si CUALQUIER segmento casa; con allow-list, CADA segmento debe casar.
+function evalShell(policy, role, command) {
+  const shell = policy.roles?.[role]?.shell;
+  if (!shell) return ALLOW;
+  if (!command) return deny(`roles.${role}.shell`, `comando ausente — no verificable para el rol ${role}`);
+  const segs = parseCommand(command);
+  if (segs == null) {
+    return deny(`roles.${role}.shell`, "construcciones opacas (escapes, expansión, sustitución, redirecciones, backgrounding o comillas sin cerrar) — no verificable");
+  }
+  for (const raw of segs) {
+    const seg = stripLaunchers(raw);
+    if (seg == null) return deny(`roles.${role}.shell`, `el segmento "${raw}" no es canonicalizable — no verificable`);
+    if (WRAPPER_RE.test(seg)) return deny(`roles.${role}.shell`, `el segmento "${seg}" re-ejecuta texto (envoltura/eval) — no verificable`);
+    const hit = Array.isArray(shell.deny) && shell.deny.find((p) => commandPatternToRegExp(p).test(seg));
+    if (hit) return deny(`roles.${role}.shell.deny`, `el segmento "${seg}" casa con el patrón denegado "${hit}"`);
+    if (Array.isArray(shell.allow) && !shell.allow.some((p) => commandPatternToRegExp(p).test(seg))) {
+      return deny(`roles.${role}.shell.allow`, `el segmento "${seg}" está fuera de la allow-list de shell del rol ${role}`);
+    }
+  }
+  return ALLOW;
+}
+
+/** 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;
+  return deny(`roles.${role}.tools`, `tool "${tool}" fuera del registro de la policy — no verificable para el rol declarado ${role}`);
+}
+
+/** El gate del RESULTADO: ficheros del diff + métricas contra rol e invariantes. */
+export function checkStagedDiff(policy, { role = "coder", files = [], netLinesAdded = null } = {}) {
+  const violations = [];
+  for (const f of files) {
+    const r = evalWrite(policy, role, f);
+    if (r.decision === "deny") violations.push({ rule_id: r.rule_id, reason: r.reason, file: f });
+  }
+  for (const inv of policy.invariants || []) {
+    if (inv.kind !== "diff-threshold" || inv.metric !== "net_lines_added") continue;
+    if (!Number.isFinite(netLinesAdded)) {
+      // Métrica ausente con invariante declarado = no verificable, jamás un
+      // pase silencioso (reviewer catch).
+      violations.push({ rule_id: inv.id, reason: "net_lines_added no disponible — el invariante no es verificable sin la métrica" });
+    } else if (netLinesAdded > inv.max) {
+      violations.push({ rule_id: inv.id, reason: `net_lines_added=${netLinesAdded} supera el máximo ${inv.max}` });
+    }
+  }
+  return violations;
+}

package/src/policy/glob.js

@@ -0,0 +1,44 @@
+// glob → RegExp anclada — primitivo de la policy layer (PL-A, KJC-TSK-0733).
+// Semántica: doble asterisco cruza directorios; doble asterisco + barra es
+// prefijo de directorio OPCIONAL (así "**" "/*.env*" casa también con .env
+// en la raíz); "*" no sale de su segmento; "?" es un carácter. Sin
+// dependencias: el vocabulario es pequeño a propósito — una lib general
+// traería semánticas que la policy no declara.
+export function globToRegExp(glob) {
+  let re = "";
+  const s = String(glob);
+  let i = 0;
+  while (i < s.length) {
+    const c = s[i];
+    if (c === "*" && s[i + 1] === "*" && s[i + 2] === "/") {
+      re += "(?:.*/)?";
+      i += 3;
+    } else if (c === "*" && s[i + 1] === "*") {
+      re += ".*";
+      i += 2;
+    } else if (c === "*") {
+      re += "[^/]*";
+      i += 1;
+    } else if (c === "?") {
+      re += "[^/]";
+      i += 1;
+    } else {
+      re += c.replaceAll(/[.+^${}()|[\]\\]/g, String.raw`\$&`);
+      i += 1;
+    }
+  }
+  return new RegExp(`^${re}$`);
+}
+
+/** true si `value` casa con ALGUNO de los globs (lista no-array ⇒ false). */
+export const matchesAny = (value, globs) =>
+  Array.isArray(globs) && globs.some((g) => globToRegExp(g).test(value));
+
+/** Patrón de comando shell → RegExp anclada al INICIO: `*` = cualquier cosa
+ *  (los comandos no son rutas — sin semántica de segmentos). */
+export function commandPatternToRegExp(pattern) {
+  const re = String(pattern)
+    .replaceAll(/[.+^${}()|[\]\\?]/g, String.raw`\$&`)
+    .replaceAll("*", ".*");
+  return new RegExp(`^${re}`);
+}