karajan-code 4.26.0 → 4.27.0

package/package.json

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

package/src/cli/register-meta.js

@@ -783,10 +783,13 @@ export function registerMeta(program, { pkgVersion }) {
     .option("--interactive", "Adopt the kj standard piece by piece (default keeps yours)")
     .option("--dry-run", "Show what would change without writing")
     .option("--json", "Emit machine-readable JSON")
+    .option("--commit", "Versiona la regeneración del supervisor con procedencia sellada (acto humano, ADR 0009)")
     .action(async (flags) => {
       await withConfig(pkgVersion, "harden", flags, async ({ logger }) => {
         await hardenCommand({
           profile: flags.profile,
+          commitSupervisor: flags.commit === true,
+          kjVersion: pkgVersion,
           config: flags.config !== false,
           ci: flags.ci !== false,
           guidelines: flags.guidelines !== false,

package/src/commands/harden.js

@@ -14,6 +14,7 @@ import { resolveTestOnPush } from "../harden/test-on-push.js";
 import { compareHarden, formatAdvisoryReport } from "../harden/advisory.js";
 import { interactiveHarden } from "../harden/interactive.js";
 import { createWizard, isTTY } from "../utils/wizard.js";
+import { commitSupervisorRegeneration } from "../harden/supervisor-commit.js";
 import { installConfigsForRoots } from "../harden/config-engine.js";
 import { installGuidelines } from "../harden/guidelines-engine.js";
 import { commandsForLanguage } from "../harden/hook-commands.js";
@@ -88,6 +89,8 @@ export async function hardenCommand({
   interactive = false,
   only = [],
   exclude = [],
+  commitSupervisor = false,
+  kjVersion = null,
   logger = console,
 } = {}) {
   const repoCfg = readHardenConfig(projectDir);
@@ -199,5 +202,24 @@ export async function hardenCommand({
     out.identity = id.declared ? id.identity : null;
     if (id.pending) out.identityPending = id.pending;
   }
+  // KJC-BUG-0161 / ADR 0009 (opción A): --commit versiona la regeneración
+  // del supervisor con procedencia sellada. Acto humano — el guard vive en
+  // commitSupervisorRegeneration y rechaza sesiones de agente.
+  if (commitSupervisor && !dryRun) {
+    try {
+      out.supervisorCommit = commitSupervisorRegeneration({
+        projectDir,
+        kjVersion: kjVersion ?? "unknown",
+        generation: result.generation ?? { profile },
+        logger,
+      });
+    } catch (err) {
+      // Fallar ALTO (catch de codex): un --commit que no commitea no puede
+      // devolver ok — quien lo pidió debe verlo, no descubrirlo después.
+      logger.error?.(`kj harden: ${err.message}`);
+      out.supervisorCommit = { committed: false, reason: err.message };
+      out.ok = false;
+    }
+  }
   return out;
 }

package/src/commands/policy.js

@@ -12,6 +12,7 @@ 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 { liftSealedSupervisorViolations } from "../policy/supervisor-verify.js";
 import { loadExceptionRecords, loadGlobalExceptionRecords, loadStandingExceptions, recordPolicyException } from "../policy/exceptions.js";
 import { buildPolicyReport } from "../policy/report.js";
 import { policyFileHash, recordGateDecision } from "../policy/decisions.js";
@@ -231,7 +232,14 @@ export async function policyCommand({ action, config = {}, flags = {}, logger =
   // --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 });
+  let violations = checkStagedDiff(policy, { role: flags.role || "coder", ...facts });
+  // ADR 0009 (KJC-BUG-0161): en CI la misma exención estructural que en la
+  // review — supervisor respaldado por provenance sellada + render canónico.
+  const sup = liftSealedSupervisorViolations({ projectDir, violations });
+  if (sup.lifted > 0) {
+    logger.info?.(`✓ policy: ${sup.lifted} fichero(s) de supervisor verificados contra la provenance sellada (ADR 0009)`);
+    violations = sup.violations;
+  }
   const hard = flags.strict ? violations.filter((v) => v.enforcement === "deny") : [];
   if (flags.json) {
     logger.info?.(JSON.stringify({ mode: flags.strict ? "strict" : "warn", violations }));

package/src/commands/review-gate.js

@@ -15,6 +15,7 @@ import { ensureGateTrackable } from "../review/gate-gitignore.js";
 import { runSonarPregate, formatSonarFinding, addedLinesByFile } from "../review/sonar-pregate.js";
 import { runMutationPregate, formatSurvivor } from "../review/mutation-pregate.js";
 import { checkCardFirst } from "../review/card-first.js";
+import { liftSealedSupervisorViolations } from "../policy/supervisor-verify.js";
 import { checkTestsWithCode } from "../review/tests-with-code.js";
 import { loadPrivacyList, scanText } from "../privacy/scan.js";
 import { checkStagedDiff, loadPolicy } from "../policy/engine.js";
@@ -262,6 +263,17 @@ export async function reviewGateCommand({ config, logger = null, flags = {} }) {
     recordException: (entry) => recordPolicyException({ projectDir, entry }),
     standingExceptions: std.standing,
   });
+  // ADR 0009 (KJC-BUG-0161): la exención ESTRUCTURAL del supervisor — un
+  // diff de .karajan/hooks respaldado por la provenance sellada Y el render
+  // canónico no es una edición: es la regeneración de kj harden --commit.
+  {
+    const res = liftSealedSupervisorViolations({ projectDir, violations: gate.denials });
+    if (res.lifted > 0) {
+      console.log(`✓ policy: ${res.lifted} fichero(s) de supervisor verificados contra la provenance sellada (ADR 0009) — regeneración, no edición`);
+      gate.denials = res.violations;
+      gate.ok = gate.denials.length === 0 && !gate.invalid;
+    }
+  }
   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(formatExempted(e));

package/src/harden/harden-engine.js

@@ -22,6 +22,24 @@ export function isGitRepo(projectDir) {
   return existsSync(join(projectDir, ".git"));
 }
 
+/**
+ * KJC-BUG-0161 / ADR 0009: el contenido CANÓNICO de un hook para una
+ * generación dada — exactamente lo que installHooks escribiría partiendo
+ * de cero. La verificación estructural del supervisor recomputa esto y
+ * compara por hash: un fichero con una sola coma manual ya no coincide.
+ */
+export function renderCanonicalHook(hook, generation = {}) {
+  const { cmds = {}, baseBranch = null, globalHooksDir = null } = generation;
+  const { content } = upsertManagedBlock({
+    source: HOOK_PREAMBLE,
+    blockId: `hook:${hook}`,
+    version: BLOCK_VERSION,
+    body: hookBody(hook, cmds, { globalHooksDir, baseBranch }),
+    style: "hash",
+  });
+  return content;
+}
+
 /**
  * Install (or refresh) the profile's hooks under `.karajan/hooks/` and point
  * `core.hooksPath` there. Idempotent. `dryRun` computes actions without
@@ -76,5 +94,7 @@ export async function installHooks({
     await runCommand("git", ["config", "core.hooksPath", HOOKS_DIR], { cwd: projectDir });
   }
 
-  return { profile, hooksPath: HOOKS_DIR, dryRun, hooks: results };
+  // KJC-BUG-0161: los parámetros con los que SE GENERÓ — lo que la
+  // provenance necesita registrar para que CI pueda recomputar y comparar.
+  return { profile, hooksPath: HOOKS_DIR, dryRun, hooks: results, generation: { profile, cmds, baseBranch, globalHooksDir } };
 }

package/src/harden/hook-templates.js

@@ -8,6 +8,8 @@
  * is imposed on non-JS repos. See docs/specs/quality-harness.md §5.
  */
 
+import { homedir } from "node:os";
+
 const CONVENTIONAL_TYPES = "feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert";
 const AI_ATTRIBUTION = "co-authored-by:.*(claude|gpt|copilot|gemini)|(generated|written) (by|with) .*(claude|gpt|copilot)";
 
@@ -27,10 +29,18 @@ export const PROFILE_HOOKS = {
 // guarded, so machines without it are unaffected.
 function chainToGlobal(hook, globalHooksDir) {
   if (!globalHooksDir) return [];
+  // KJC-BUG-0161 (ADR 0009): a committed hook must not bake a machine's
+  // absolute home path — resolve through $HOME at runtime so the same
+  // generated content is valid on every machine and its provenance stays
+  // verifiable (and no local filesystem layout leaks into a public repo).
+  const home = homedir();
+  const dir = globalHooksDir === home || globalHooksDir.startsWith(`${home}/`)
+    ? `$HOME${globalHooksDir.slice(home.length)}`
+    : globalHooksDir;
   return [
     "# Chain the machine's previous global hook (kj harden keeps it active).",
-    `if [ -x "${globalHooksDir}/${hook}" ]; then`,
-    `  "${globalHooksDir}/${hook}" "$@"; rc=$?`,
+    `if [ -x "${dir}/${hook}" ]; then`,
+    `  "${dir}/${hook}" "$@"; rc=$?`,
     '  [ "$rc" -eq 0 ] || exit "$rc"',
     "fi",
   ];

package/src/harden/sentinel-hooks.js

@@ -371,6 +371,20 @@ process.stdin.on("end", () => {
       console.error("karajan sentinel: los ficheros del supervisor no se tocan desde Bash — consultalos con la tool Read/Grep; solo el humano los modifica, fuera de la sesion." + doc("supervisor"));
       process.exit(2);
     }
+    // ADR 0009 (KJC-BUG-0161): kj harden --commit es un ACTO HUMANO — la
+    // sesion ni lo intenta. Sin escape (superficie de supervisor). includes()
+    // a proposito: cero ambiguedad de escapes en plantilla, y fail-closed
+    // (mencionarlo en un argumento tambien bloquea: preferible a un hueco).
+    // ANTES de KJ_SENTINEL_OFF a proposito, como el guard PROTECTED de
+    // arriba: un env var lo pone tambien un agente — el supervisor no se
+    // apaga con interruptores al alcance del supervisado.
+    {
+      const kjCmd = String(input.command || "");
+      if (tool === "Bash" && kjCmd.includes("harden") && kjCmd.includes("--commit")) {
+        console.error("karajan sentinel: kj harden --commit es un acto humano (ADR 0009) — pideselo a tu usuario; ninguna sesion de agente lo ejecuta." + doc("supervisor"));
+        process.exit(2);
+      }
+    }
     if (process.env.KJ_SENTINEL_OFF === "1") process.exit(0);
     // KJC-BUG-0142: cada deny anuncia su escape como prefijo del comando
     // (KJ_ALLOW_X=1 cmd), pero el hook corre con el env del HOST — el

package/src/harden/supervisor-commit.js

@@ -0,0 +1,147 @@
+/**
+ * KJC-BUG-0161 / ADR 0009 (opción A) — `kj harden --commit`, el cauce
+ * sancionado del supervisor: ACTO HUMANO que versiona la regeneración con
+ * provenance trackeada (versión, parámetros, sha256), sello en el acta y
+ * commit quirúrgico. El --no-verify es a conciencia: lo que salta en local
+ * lo re-verifica CI contra la provenance (pieza 3).
+ */
+import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { closeSync, existsSync, openSync, readFileSync, readSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { recordGateDecision } from "../policy/decisions.js";
+import { readIdentity } from "../identity/store.js";
+
+export const PROVENANCE_FILE = ".karajan/supervisor-provenance.json";
+const HOOKS_PREFIX = ".karajan/hooks/";
+
+const sha256 = (abs) => createHash("sha256").update(readFileSync(abs)).digest("hex");
+
+// Capa 3 del acto humano (test adversarial del 6-sep): un pty falso engaña a
+// isTTY y `env -u` borra CLAUDECODE, pero el kj que lanza un agente DESCIENDE
+// de su proceso — y eso está en /proc lo falsifique quien lo falsifique.
+const AGENT_PROC = /claude|codex|copilot|gemini|opencode|\bagy\b/i;
+export function agentAncestry({ pid = process.pid, readProc = null, maxDepth = 40 } = {}) {
+  const read = readProc || ((p) => {
+    const stat = readFileSync(`/proc/${p}/stat`, "utf8");
+    const ppid = Number(stat.slice(stat.lastIndexOf(")") + 2).split(" ")[1]);
+    let cmd = "";
+    try { cmd = readFileSync(`/proc/${p}/cmdline`).toString("utf8").replaceAll("\0", " "); } catch { /* gone */ }
+    return { ppid, cmd };
+  });
+  let cur = pid;
+  for (let i = 0; i < maxDepth && cur > 1; i += 1) {
+    let info;
+    try { info = read(cur); } catch { return { agent: false, unknown: true }; }
+    if (info?.cmd && AGENT_PROC.test(info.cmd)) return { agent: true, match: info.cmd.slice(0, 80) };
+    if (!Number.isFinite(info?.ppid) || info.ppid === cur) break;
+    cur = info.ppid;
+  }
+  return { agent: false };
+}
+
+// Lee la respuesta del nonce de la TTY REAL del proceso (no de stdin, que un
+// atacante alimenta por pipe): /dev/tty solo existe con terminal de control.
+function defaultConfirm(nonce) {
+  process.stdout.write(`harden --commit: teclea "${nonce}" para confirmar que eres humano: `);
+  try {
+    const buf = Buffer.alloc(64);
+    const fd = openSync("/dev/tty", "r");
+    const n = readSync(fd, buf, 0, 64);
+    closeSync(fd);
+    return buf.toString("utf8", 0, n).trim();
+  } catch {
+    return null;
+  }
+}
+
+/** Ficheros de supervisor TRACKEADOS con cambios (staged o no). */
+export function supervisorDrift({ projectDir, gitFn }) {
+  const run = gitFn || ((args) => execFileSync("git", args, { cwd: projectDir, encoding: "utf8" }));
+  // Un rename sale como "R  old -> new" (catch de codex): ambas rutas son
+  // drift — la vieja se versiona como borrado y la nueva con su hash.
+  return run(["status", "--porcelain", "--", ".karajan/hooks"])
+    .split("\n")
+    .flatMap((l) => l.slice(3).trim().split(" -> "))
+    .filter((f) => f.startsWith(HOOKS_PREFIX));
+}
+
+/**
+ * @returns {{committed: boolean, reason?: string, files?: object[]}}
+ */
+export function commitSupervisorRegeneration({
+  projectDir,
+  kjVersion,
+  generation,
+  logger = console,
+  gitFn = null,
+  env = process.env,
+  tty = process.stdout.isTTY,
+  deps = {},
+}) {
+  // El cauce es humano por diseño (ADR 0009): una sesión de agente no lo usa.
+  if (env.CLAUDECODE || env.KJ_NON_INTERACTIVE === "1" || !tty) {
+    throw new Error(
+      "harden --commit es un acto humano: córrelo desde TU terminal, fuera de una sesión de agente (ADR 0009)",
+    );
+  }
+  const anc = agentAncestry(deps.ancestry ?? {});
+  if (anc.agent) {
+    throw new Error(
+      `harden --commit es un acto humano y este proceso desciende de un agente (${anc.match}) — ni con pty falso ni con el entorno limpio (ADR 0009)`,
+    );
+  }
+  // Capa 4 (test adversarial 6-sep: un huérfano a init con pty falso y
+  // prompts a ciegas llegó hasta aquí): nonce aleatorio tecleado de vuelta.
+  // Un alimentador ciego no conoce el código; automatizar su lectura exige
+  // un driver expect — premeditación inequívoca, no un descuido.
+  const nonce = createHash("sha256").update(String(Math.random())).digest("hex").slice(0, 6);
+  const answer = (deps.confirm ?? defaultConfirm)(nonce);
+  if (answer !== nonce) {
+    throw new Error(`harden --commit: confirmación humana fallida (esperaba "${nonce}") — ADR 0009`);
+  }
+  const run = gitFn || ((args) => execFileSync("git", args, { cwd: projectDir, encoding: "utf8" }));
+  const files = supervisorDrift({ projectDir, gitFn: run });
+  if (files.length === 0) {
+    logger.info?.("harden --commit: sin drift en el supervisor — nada que versionar");
+    return { committed: false, reason: "sin drift" };
+  }
+  // Borrados/renombrados también son drift (catch de codex): ausente ⇒ deleted.
+  const hashed = files.map((file) => {
+    const abs = join(projectDir, file);
+    return existsSync(abs) ? { file, sha256: sha256(abs) } : { file, deleted: true };
+  });
+  const who = readIdentity(projectDir);
+  const provenance = {
+    kj_version: kjVersion,
+    generated_at: new Date().toISOString(),
+    generation,
+    who: who ? { gh: who.gh_user ?? null, git: who.git_email ?? null, grade: "declarada" } : null,
+    files: hashed,
+  };
+  writeFileSync(join(projectDir, PROVENANCE_FILE), `${JSON.stringify(provenance, null, 2)}\n`, "utf8");
+  recordGateDecision(projectDir, {
+    decision: "exempt",
+    chokepoint: "supervisor",
+    kind: "supervisor-regeneration",
+    kj_version: kjVersion,
+    files: hashed,
+    who: provenance.who,
+  });
+  // Por DIRECTORIO, no por fichero: un rename ya staged deja la ruta vieja
+  // sin existir y `git add -- <vieja>` falla; `-A` sobre el dir del
+  // supervisor versiona altas, cambios, borrados y renombrados por igual.
+  run(["add", "-A", "--", PROVENANCE_FILE, ".karajan/hooks"]);
+  run([
+    "commit",
+    "--no-verify",
+    "-m",
+    `chore(harden): supervisor regenerated and sealed by kj harden v${kjVersion}`,
+    "--",
+    PROVENANCE_FILE,
+    ".karajan/hooks",
+  ]);
+  logger.info?.(`harden --commit: ${files.length} fichero(s) de supervisor versionados con procedencia sellada`);
+  return { committed: true, files: hashed };
+}

package/src/policy/engine.js

@@ -25,7 +25,9 @@ import {
 export const SUPERVISOR_DEFAULTS = [
   {
     id: "defaults.supervisor.write",
-    pattern: /\.claude\/settings\.json\b|\.karajan\/(hooks|harness)\//,
+    // ADR 0009: la provenance del supervisor es superficie de supervisor —
+    // un agente no la escribe; solo kj harden --commit (humano) la produce.
+    pattern: /\.claude\/settings\.json\b|\.karajan\/(hooks|harness)\/|\.karajan\/supervisor-provenance\.json\b/,
     message: "nombra ficheros del supervisor — solo el humano los modifica, fuera de la sesión",
   },
 ];

package/src/policy/supervisor-verify.js

@@ -0,0 +1,79 @@
+/**
+ * KJC-BUG-0161 / ADR 0009, pieza 3 — exención ESTRUCTURAL del supervisor:
+ * un fichero de .karajan/hooks solo deja de ser violación si su contenido
+ * coincide (sha256) con la provenance sellada Y con el render canónico
+ * recomputado. No confía: recomputa. Una coma manual sigue denegada.
+ */
+import { createHash } from "node:crypto";
+import { lstatSync, readFileSync } from "node:fs";
+import { resolve, sep } from "node:path";
+
+import { renderCanonicalHook } from "../harden/harden-engine.js";
+import { PROVENANCE_FILE } from "../harden/supervisor-commit.js";
+
+const HOOKS_PREFIX = ".karajan/hooks/";
+// globalHooksDir es el único texto libre que se interpola en el render:
+// vocabulario cerrado de ruta o la provenance no verifica NADA.
+const SAFE_DIR = /^(\$HOME)?(\/[\w.@%+~-]+)+$/;
+
+const sha256 = (buf) => createHash("sha256").update(buf).digest("hex");
+
+/**
+ * @returns {{files: Set<string>, reason?: string}} rutas repo-relativas de
+ * supervisor cuyo estado actual está respaldado por la provenance sellada.
+ */
+export function verifiedSupervisorFiles({ projectDir }) {
+  let prov;
+  try {
+    prov = JSON.parse(readFileSync(resolve(projectDir, PROVENANCE_FILE), "utf8"));
+  } catch {
+    return { files: new Set(), reason: "sin provenance" };
+  }
+  const gen = prov?.generation ?? {};
+  if (gen.globalHooksDir != null && !SAFE_DIR.test(gen.globalHooksDir)) {
+    return { files: new Set(), reason: "globalHooksDir no verificable en la provenance" };
+  }
+  const ok = new Set();
+  const entries = Array.isArray(prov?.files) ? prov.files : [];
+  const hooksRoot = resolve(projectDir, HOOKS_PREFIX);
+  for (const entry of entries) {
+    if (typeof entry?.file !== "string" || !entry.file.startsWith(HOOKS_PREFIX)) continue;
+    // Contención por resolución, no por prefijo textual (catch de codex).
+    const abs = resolve(projectDir, entry.file);
+    if (!abs.startsWith(hooksRoot + sep)) continue;
+    let st = null;
+    try { st = lstatSync(abs); } catch { /* no hay objeto en la ruta */ }
+    if (entry.deleted === true) {
+      if (st === null) ok.add(entry.file);
+      continue;
+    }
+    if (typeof entry.sha256 !== "string" || !st?.isFile()) continue;
+    if (sha256(readFileSync(abs)) !== entry.sha256) continue;
+    let canonical;
+    try {
+      canonical = renderCanonicalHook(entry.file.slice(HOOKS_PREFIX.length), gen);
+    } catch {
+      continue;
+    }
+    if (sha256(Buffer.from(canonical, "utf8")) === entry.sha256) ok.add(entry.file);
+  }
+  // `complete` = CADA entrada verificó: solo entonces la provenance se
+  // describe con honestidad y su propio diff puede alzarse.
+  const complete = entries.length > 0 && entries.every((e) => typeof e?.file === "string" && ok.has(e.file));
+  return { files: ok, complete };
+}
+
+/** Filtra violaciones de supervisor respaldadas — {violations, lifted}. */
+export function liftSealedSupervisorViolations({ projectDir, violations }) {
+  const RULE = "defaults.supervisor.write";
+  if (!violations.some((v) => v.rule_id === RULE && v.file)) return { violations, lifted: 0 };
+  const sealed = verifiedSupervisorFiles({ projectDir });
+  // La violación sobre la PROPIA provenance solo se alza si la provenance
+  // entera verificó — a medias no describe la verdad y sigue denegada.
+  const liftable = (v) =>
+    v.rule_id === RULE
+    && v.file
+    && (sealed.files.has(v.file) || (v.file === PROVENANCE_FILE && sealed.complete === true));
+  const kept = violations.filter((v) => !liftable(v));
+  return { violations: kept, lifted: violations.length - kept.length };
+}