karajan-code 4.15.0 → 4.17.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "karajan-code",
-  "version": "4.15.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/packages/ai-trash/src/install.js

@@ -8,7 +8,14 @@ import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 
 export const DEFAULT_SETTINGS_PATH = join(homedir(), ".claude", "settings.json");
-export const HOOK_COMMAND = "kj-trash hook";
+// KJC-BUG-0095: the bare command fails SILENTLY when the bin drops off PATH
+// (nvm switch, global reinstall) — the anti-delete net goes down without
+// notice. The installed line fails CLOSED: a missing bin blocks the tool
+// call (exit 2) naming the net and the remedy, never a quiet pass-through.
+export const LEGACY_HOOK_COMMAND = "kj-trash hook";
+export const HOOK_COMMAND =
+  "if command -v kj-trash >/dev/null 2>&1; then exec kj-trash hook; fi; " +
+  "echo 'kj-trash: bin not on PATH — the anti-delete net is DOWN. Fix: npm i -g karajan-code (or remove this hook from ~/.claude/settings.json).' >&2; exit 2";
 const MATCHER = "Bash";
 
 async function readSettings(path) {
@@ -34,6 +41,20 @@ export function patchSettings(settings, command = HOOK_COMMAND, matcher = MATCHE
     entry = { matcher, hooks: [{ type: "command", command }] };
     preToolUse.push(entry);
     mutated = true;
+  } else if (hasHookCommand(entry, LEGACY_HOOK_COMMAND) && command !== LEGACY_HOOK_COMMAND) {
+    // KJC-BUG-0095 migration: upgrade the silent legacy line in place —
+    // deduped (reviewer catch): an entry already carrying the new line
+    // must end up with a single copy, not legacy-turned-duplicate.
+    let seen = false;
+    entry.hooks = entry.hooks
+      .map((h) => (h.type === "command" && h.command === LEGACY_HOOK_COMMAND ? { ...h, command } : h))
+      .filter((h) => {
+        if (!(h.type === "command" && h.command === command)) return true;
+        if (seen) return false;
+        seen = true;
+        return true;
+      });
+    mutated = true;
   } else if (!hasHookCommand(entry, command)) {
     entry.hooks = [...(entry.hooks ?? []), { type: "command", command }];
     mutated = true;

package/scripts/verify-pack.mjs

@@ -208,7 +208,17 @@ try {
   // better-sqlite3's native build by default, so DB-backed commands need
   // `pnpm approve-builds`; that's surfaced as a doctor warning, KJC-BUG-0092 —
   // not a gate failure, since it's inherent to pnpm.) Auto-skips without pnpm.
-  const hasPnpm = spawnSync("pnpm", ["--version"], { encoding: "utf8", env: childEnv }).status === 0;
+  // KJC-BUG-0135: `npm run` leaks npm_config_* into the child env, and pnpm
+  // maps those variables onto its own config — which can re-anchor it to THIS
+  // repo (7-aug incident: the repo's node_modules converted to pnpm layout,
+  // native bindings wiped, and simple-git-hooks' hook overwrote
+  // .karajan/hooks). The smoke runs with a scrubbed env and a pinned --dir,
+  // and the tripwire below turns any host contamination into a loud gate
+  // failure instead of a silent green.
+  const pnpmEnv = Object.fromEntries(Object.entries(childEnv).filter(([k]) => !/^npm_config_/i.test(k)));
+  const HOST_MARKERS = ["pnpm-lock.yaml", "pnpm-workspace.yaml", path.join("node_modules", ".pnpm")];
+  const hostMarkersBefore = new Set(HOST_MARKERS.filter((m) => fs.existsSync(path.join(repoRoot, m))));
+  const hasPnpm = spawnSync("pnpm", ["--version"], { encoding: "utf8", env: pnpmEnv }).status === 0;
   if (!hasPnpm) {
     console.log("verify-pack: pnpm not installed — skipping pnpm smoke (npm path covered above) ⚠");
   } else {
@@ -224,11 +234,11 @@ try {
     // versions (supply-chain protection), so right after publishing
     // karajan-core it silently resolves an OLD one and this smoke fails on
     // missing subpaths. The gate verifies packaging, not release-age policy.
-    spawnSync("pnpm", ["add", tgzPath, "--store-dir", path.join(pnpmTmp, ".store"), "--config.minimum-release-age=0"], {
-      encoding: "utf8",
-      env: childEnv,
-      cwd: pnpmTmp,
-    });
+    spawnSync(
+      "pnpm",
+      ["add", tgzPath, "--dir", pnpmTmp, "--ignore-workspace", "--store-dir", path.join(pnpmTmp, ".store"), "--config.minimum-release-age=0"],
+      { encoding: "utf8", env: pnpmEnv, cwd: pnpmTmp },
+    );
     const pnpmBin = path.join(pnpmTmp, "node_modules", ".bin", "kj");
     if (!fs.existsSync(pnpmBin)) fail(`kj binary missing after pnpm install: ${pnpmBin}`);
     let pnpmVersion;
@@ -242,6 +252,18 @@ try {
     }
     console.log(`verify-pack: pnpm install + kj --version → ${pnpmVersion} ✓ (DB build needs \`pnpm approve-builds\`)`);
   }
+  // Tripwire (KJC-BUG-0135): the smoke must NEVER touch the host repo. If a
+  // pnpm artifact appeared at the repo root during this run, the gate fails
+  // naming it — never a green over a contaminated tree.
+  const contaminated = HOST_MARKERS.filter(
+    (m) => !hostMarkersBefore.has(m) && fs.existsSync(path.join(repoRoot, m)),
+  );
+  if (contaminated.length > 0) {
+    fail(
+      `pnpm smoke contaminated the host repo: ${contaminated.join(", ")} appeared at the repo root`,
+      "remove the listed files and run `npm ci` to restore the npm layout; then verify .karajan/hooks with `git status`",
+    );
+  }
 
   console.log(`\n✓ verify-pack: karajan-code@${expectedVersion} installs clean and runs.`);
 } finally {

package/src/agents/base-agent.js

@@ -60,7 +60,7 @@ export class BaseAgent {
       // a PATH is a partial overlay and merges over the inherited env first,
       // so an overlay caller can never cost the child PATH/HOME.
       const complete = options.env && ("PATH" in options.env || "Path" in options.env);
-      const base = complete ? options.env : { ...process.env, ...(options.env || {}) };
+      const base = complete ? options.env : { ...process.env, ...options.env };
       options = {
         ...options,
         env: buildAgentEnv(base, {

package/src/checks/release-check.js

@@ -28,9 +28,7 @@ async function genericChecks(projectDir) {
   checks.push({ name: "manifest", ok: Boolean(version), detail: version ? `version ${version}` : "package.json has no version" });
 
   const clPath = join(projectDir, "CHANGELOG.md");
-  if (!existsSync(clPath)) {
-    checks.push({ name: "changelog-current", ok: false, detail: "no CHANGELOG.md — the release story must exist before the release" });
-  } else {
+  if (existsSync(clPath)) {
     const cl = readFileSync(clPath, "utf8");
     const topVersioned = (cl.match(/^## \[(\d+\.\d+\.\d+)\]/m) || [])[1] || null;
     // Content still sitting under [Unreleased] means unpromoted entries —
@@ -39,25 +37,20 @@ async function genericChecks(projectDir) {
     const unreleasedBody = afterUnreleased.split(/^## \[/m)[0] ?? "";
     const pending = /\S/.test(unreleasedBody);
     const ok = topVersioned === version && !pending;
-    checks.push({
-      name: "changelog-current",
-      ok,
-      detail: ok
-        ? `top section is [${version}], Unreleased empty`
-        : pending
-          ? `[Unreleased] still carries content — promote it into [${version}] before releasing`
-          : `top CHANGELOG section is [${topVersioned ?? "none"}] but the manifest says ${version} — promote Unreleased before releasing`,
-    });
+    let detail = `top section is [${version}], Unreleased empty`;
+    if (pending) detail = `[Unreleased] still carries content — promote it into [${version}] before releasing`;
+    else if (!ok) detail = `top CHANGELOG section is [${topVersioned ?? "none"}] but the manifest says ${version} — promote Unreleased before releasing`;
+    checks.push({ name: "changelog-current", ok, detail });
+  } else {
+    checks.push({ name: "changelog-current", ok: false, detail: "no CHANGELOG.md — the release story must exist before the release" });
   }
 
   const tagsOut = await runCommand("git", ["-C", projectDir, "tag", "--list", "v[0-9]*"]);
   const tags = (tagsOut.stdout || "").split("\n").map((t) => t.trim().replace(/^v/, "")).filter((t) => /^\d+\.\d+\.\d+$/.test(t));
   const ahead = version ? tags.filter((t) => semverCmp(t, version) > 0) : [];
-  checks.push({
-    name: "tags",
-    ok: ahead.length === 0,
-    detail: ahead.length ? `tag(s) ahead of the manifest exist: v${ahead.join(", v")}` : (tags.includes(version) ? `v${version} already tagged` : `tag v${version} pending (created after publish)`),
-  });
+  let tagDetail = tags.includes(version) ? `v${version} already tagged` : `tag v${version} pending (created after publish)`;
+  if (ahead.length > 0) tagDetail = `tag(s) ahead of the manifest exist: v${ahead.join(", v")}`;
+  checks.push({ name: "tags", ok: ahead.length === 0, detail: tagDetail });
   return { checks, version, pkg };
 }
 

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/env.js

@@ -62,7 +62,7 @@ export async function envInstallCommand({ config = null, logger = null, flags =
     // The effective backend feeds the render on EVERY non-error path —
     // chosen, declared-in-file or default — so the playbook never falls
     // back to hu-board while the selection said otherwise.
-    config = { ...config, state_backend: sel.backend, board: sel.boardName ? { ...(config?.board || {}), name: sel.boardName } : config?.board };
+    config = { ...config, state_backend: sel.backend, board: sel.boardName ? { ...config?.board, name: sel.boardName } : config?.board };
   } catch (err) {
     console.log(`⚠ board selection failed (${err.message}) — continuing with the configured default`);
   }

package/src/commands/harden.js

@@ -184,7 +184,10 @@ export async function hardenCommand({
   const verb = dryRun ? "would install" : "installed";
   logger.info?.(`kj harden (${profile}) — ${verb} ${result.hooks.length} hook(s) → ${result.hooksPath}`);
   for (const h of result.hooks) logger.info?.(`  • ${h.hook}: ${h.action}`);
-  for (const c of out.configs) logger.info?.(`  • ${c.file}: ${c.action}${c.note ? ` (${c.note})` : ""}`);
+  for (const c of out.configs) {
+    const note = c.note ? ` (${c.note})` : "";
+    logger.info?.(`  • ${c.file}: ${c.action}${note}`);
+  }
   for (const w of out.workflows) logger.info?.(`  • ${w.file}: ${w.action}`);
   for (const g of out.guidelines) logger.info?.(`  • ${g.file}: ${g.action}`);
   if (!dryRun) logger.info?.("core.hooksPath set. Verify later with `kj check`.");

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/commands/rag.js

@@ -98,7 +98,8 @@ export async function ragQueryCommand({ text, config, logger, flags = {} }) {
     // KJC-TSK-0697 — `--library` targets the distilled-canon collection:
     // its own project namespace plus the kind filter.
     const library = Boolean(flags.library);
-    const project = library ? LIBRARY_PROJECT : (flags.project === "all" ? null : (flags.project || detected || null));
+    let project = flags.project === "all" ? null : (flags.project || detected || null);
+    if (library) project = LIBRARY_PROJECT;
     // KJC-BUG-0061 follow-up: align the CLI `--json` shape with the MCP
     // handler. The MCP tool responds `{ hits: [], empty: true, topK, scope }`
     // so agents (and the `/kj-rag-query` skill from Camino B) have a
@@ -115,9 +116,8 @@ export async function ragQueryCommand({ text, config, logger, flags = {} }) {
     // Safe by grammar: parseWhere (core where-parser.js) accepts ONLY
     // AND-joined key=value pairs — an OR or parens never parses, so the
     // composed clause cannot leak past the kind filter; it fails loudly.
-    const where = library
-      ? (flags.where ? `kind=library AND ${flags.where}` : "kind=library")
-      : (flags.where || null);
+    let where = flags.where || null;
+    if (library) where = flags.where ? `kind=library AND ${flags.where}` : "kind=library";
     const rerankOpts = flags.rerank ? { model: flags.rerankModel } : null;
     const hits = await query(db, makeGovernedEmbedder(config), text, { topK, scope, project, mode, alpha, where, rerankOpts });
     if (flags.json) {

package/src/commands/review-gate.js

@@ -26,6 +26,9 @@ async function enforceCardFirst({ config, projectDir }) {
   const branch = branchRes.stdout?.trim() || "HEAD";
   const card = await checkCardFirst({ config, projectDir, branch });
   if (card.mode === "warn") console.log(`⚠ card-first: ${card.reason}`);
+  // KJC-TSK-0732: the verification LEVEL is part of the verdict — a pass on
+  // branch-ref alone must never read as a tracker-verified pass.
+  if (card.note) console.log(`⚠ card-first: ${card.note}`);
   if (card.mode === "exempt" && card.reason.includes("KJ_ALLOW_NO_CARD")) console.log(`⚠ card-first exempt: ${card.reason}`);
   if (!card.ok) {
     console.log(`✗ card-first gate: ${card.reason}`);

package/src/config/defaults.js

@@ -66,7 +66,9 @@ const DEFAULTS = {
   // through the host agent's MCP/tools, never mirrored by kj. There is NO
   // "none": Karajan does not run without a board.
   state_backend: "hu-board",
-  board: { name: null },
+  // verify_cmd (KJC-TSK-0732): user adapter that checks a card ref against
+  // the real tracker — prints {exists, live, status} JSON; {ref} substituted.
+  board: { name: null, verify_cmd: null },
   // Method gates (KJC-PCS-0068): rules climb from playbook text to
   // deterministic enforcement. card_first: "auto" = block with hu-board
   // (fully verifiable), warn with planning-game/external (presence only);

package/src/environment/board-select.js

@@ -53,6 +53,7 @@ export async function pickStateBackend({ projectDir = process.cwd(), home = os.h
   const backend = external ? "external" : value;
   const boardName = external ? value.slice("external:".length) : null;
   await persistStateBackend(projectDir, backend, boardName);
-  logger.info?.(`✓ board: ${backend}${boardName ? ` (${boardName})` : ""} — persisted in .karajan/kj.config.yml`);
+  const suffix = boardName ? ` (${boardName})` : "";
+  logger.info?.(`✓ board: ${backend}${suffix} — persisted in .karajan/kj.config.yml`);
   return { backend, boardName, source: "chosen" };
 }

package/src/harden/hook-templates.js

@@ -109,7 +109,7 @@ export function hookBody(hook, cmds = {}, { globalHooksDir = null, baseBranch =
         "# POSIX-safe extraction (no grep -o): the ref is the leading",
         "# card-shaped token of the branch's last segment (feat/REF-desc).",
         "seg=$(printf '%s' \"$branch\" | tr '[:upper:]' '[:lower:]'); seg=\"${seg##*/}\"",
-        "ref=$(printf '%s' \"$seg\" | sed -nE 's/^([a-z][a-z0-9]{1,9}(-[a-z][a-z0-9]{1,9})*-[0-9]{1,6})(-.*)?$/\\1/p')",
+        String.raw`ref=$(printf '%s' "$seg" | sed -nE 's/^([a-z][a-z0-9]{1,9}(-[a-z][a-z0-9]{1,9})*-[0-9]{1,6})(-.*)?$/\1/p')`,
         'header=$(head -n1 "$msg_file")',
         'if [ -n "$ref" ] && [ -n "$header" ]; then',
         '  case "$header" in',
@@ -122,7 +122,7 @@ export function hookBody(hook, cmds = {}, { globalHooksDir = null, baseBranch =
         "        stamp=$(printf '%s' \"$ref\" | tr '[:lower:]' '[:upper:]')",
         '        new_header="$header ($stamp)"',
         '        if [ "${#new_header}" -le 100 ]; then',
-        "          { printf '%s\\n' \"$new_header\"; tail -n +2 \"$msg_file\"; } > \"$msg_file.kjtmp\" && mv \"$msg_file.kjtmp\" \"$msg_file\"",
+        String.raw`          { printf '%s\n' "$new_header"; tail -n +2 "$msg_file"; } > "$msg_file.kjtmp" && mv "$msg_file.kjtmp" "$msg_file"`,
         "        fi",
         "      fi",
         "      ;;",

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/orchestrator/direct-actions.js

@@ -26,6 +26,17 @@ const ALLOWED_COMMANDS = [
   "bundle install", "composer install", "dotnet restore"
 ];
 
+// KJC-BUG-0099: a dependency install must not be arbitrary code execution —
+// lifecycle hooks (postinstall & friends) run whatever the dependency ships.
+// The allow-list above names the INTENT; execution appends the ecosystem's
+// script-skipping flag. Ecosystems without package hooks run untouched.
+const HARDEN_FLAGS = {
+  npm: ["--ignore-scripts"],
+  pnpm: ["--ignore-scripts"],
+  yarn: ["--ignore-scripts"],
+  composer: ["--no-scripts", "--no-plugins"],
+};
+
 /**
  * True when `target` resolves to a path inside `base` (or is `base` itself).
  * Uses path.relative instead of a string prefix check: a naive
@@ -64,7 +75,7 @@ async function runCommand({ cmd, cwd }) {
     // Even though `cmd` is allow-listed, defense-in-depth: switched to
     // execFileSync with a tokenised arg array so no shell expansion at all.
     const [program, ...args] = cmd.trim().split(/\s+/);
-    const output = execFileSync(program, args, {
+    const output = execFileSync(program, [...args, ...(HARDEN_FLAGS[program] ?? [])], {
       cwd: cwd || process.cwd(),
       encoding: "utf8",
       stdio: ["pipe", "pipe", "pipe"],

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

package/src/review/card-first.js

@@ -8,6 +8,7 @@
  */
 import { listPlans, loadPlan } from "../plan/plan-store.js";
 import { escapeRegExp } from "../utils/escape-regexp.js";
+import { verifyCardAlive } from "./card-verify.js";
 
 const LIVE_STATUSES = new Set(["pending", "running", "failed"]);
 // Card-shaped reference: LIN-123, bb-002 and multi-segment ids like
@@ -44,7 +45,7 @@ async function findLiveCardInBranch(projectDir, branch) {
   return closedHit;
 }
 
-export async function checkCardFirst({ config = {}, projectDir = process.cwd(), branch, env = process.env }) {
+export async function checkCardFirst({ config = {}, projectDir = process.cwd(), branch, env = process.env, deps = {} }) {
   if (env.KJ_ALLOW_NO_CARD === "1") {
     return { ok: true, mode: "exempt", reason: "KJ_ALLOW_NO_CARD=1 (explicit escape hatch)" };
   }
@@ -73,11 +74,24 @@ export async function checkCardFirst({ config = {}, projectDir = process.cwd(),
       : { ok: true, mode: "warn", reason };
   }
 
-  // planning-game / external: presence check only — liveness lives in the
-  // project's own board, out of local reach.
-  if (CARD_REF_RE.test(branch)) return { ok: true, mode: "pass", ref: branch.match(CARD_REF_RE)[0] };
-  const effective = policy === "auto" ? "warn" : policy;
+  // planning-game / external: presence check, upgraded to LIVENESS against
+  // the real tracker when board.verify_cmd declares an adapter
+  // (KJC-TSK-0732, issue #1371). Unverifiable degrades honestly — the
+  // result names its level so nobody mistakes branch-ref for tracker.
   const boardName = config.board?.name || backend;
+  const effective = policy === "auto" ? "warn" : policy;
+  if (CARD_REF_RE.test(branch)) {
+    const ref = branch.match(CARD_REF_RE)[0];
+    const { verifyFn = verifyCardAlive } = deps;
+    const v = await verifyFn({ ref, verifyCmd: config.board?.verify_cmd, projectDir });
+    if (v.verified === false) {
+      const reason = `branch references ${ref} but ${boardName} reports it "${v.status}" — card-first needs a live card in the tracker (create/reopen it there)`;
+      return effective === "block"
+        ? { ok: false, mode: "block", reason, level: v.level }
+        : { ok: true, mode: "warn", reason, level: v.level };
+    }
+    return { ok: true, mode: "pass", ref, level: v.level, ...(v.note ? { note: v.note } : {}) };
+  }
   const reason = `no card reference in branch "${branch}" — card-first on ${boardName}: create the card there and name the branch after it (e.g. feat/ABC-123-summary)`;
   return effective === "block"
     ? { ok: false, mode: "block", reason }

package/src/review/card-verify.js

@@ -0,0 +1,83 @@
+/**
+ * card-verify — KJC-TSK-0732 (issue #1371). With a declared tracker,
+ * card-first upgrades "the branch names a card" to "the tracker says that
+ * card is ALIVE". Transport-agnostic: `board.verify_cmd` is the USER'S
+ * adapter (their CLI/MCP wrapper — credentials never enter kj) printing
+ * {exists, live, status?} JSON on stdout. Unverifiable NEVER blocks: it
+ * degrades to branch-ref level SAYING SO — a gate must not claim a check
+ * it didn't make, in either direction. Definitive verdicts are cached
+ * briefly; degradations never are, so recovery is immediate.
+ */
+import { exec } from "node:child_process";
+import { createHash } from "node:crypto";
+import { promisify } from "node:util";
+import fs from "node:fs";
+import path from "node:path";
+import { extractFirstJson } from "../utils/json-extract.js";
+
+const execAsync = promisify(exec);
+export const VERIFY_TIMEOUT_MS = 4000;
+const CACHE_TTL_MS = 10 * 60 * 1000;
+// The ref lands inside a shell command (the user's adapter template), so it
+// must be inert BY CONSTRUCTION — card-ref alphabet only, anchored (codex
+// catch: same injection class as the tournament coder names).
+const SAFE_REF_RE = /^[a-z0-9][a-z0-9-]{0,63}$/i;
+
+const defaultExec = async (cmd, { cwd }) =>
+  execAsync(cmd, { cwd, timeout: VERIFY_TIMEOUT_MS, maxBuffer: 1024 * 1024 });
+
+function cachePath(projectDir) {
+  return path.join(projectDir, ".kj", "cache", "card-verify.json");
+}
+
+/** @returns {Promise<{level: "tracker"|"branch-ref", verified: boolean|null, status?: string|null, note?: string}>}
+ *  verified: true = alive · false = definitively not · null = degraded. */
+export async function verifyCardAlive({ ref, verifyCmd, projectDir = process.cwd(), deps = {} }) {
+  const { execFn = defaultExec, now = Date.now } = deps;
+  if (!verifyCmd) {
+    return {
+      level: "branch-ref", verified: null,
+      note: "card-first checked the branch reference only — set board.verify_cmd to verify the card against your tracker",
+    };
+  }
+
+  if (!SAFE_REF_RE.test(String(ref))) {
+    return {
+      level: "branch-ref", verified: null,
+      note: `tracker verification skipped — ref "${String(ref).slice(0, 30)}" is outside the card-ref alphabet`,
+    };
+  }
+  let cache = {};
+  try {
+    cache = JSON.parse(fs.readFileSync(cachePath(projectDir), "utf8"));
+  } catch { /* no cache yet */ }
+  // Keyed by adapter AND ref (reviewer catch): a verdict from one
+  // verify_cmd must never answer for a different one.
+  const key = `${createHash("sha256").update(verifyCmd).digest("hex").slice(0, 12)}:${ref}`;
+  const hit = cache[key];
+  if (hit && now() - hit.at < CACHE_TTL_MS) return hit.result;
+
+  const cmd = verifyCmd.includes("{ref}") ? verifyCmd.replaceAll("{ref}", ref) : `${verifyCmd} ${ref}`;
+  try {
+    const { stdout } = await execFn(cmd, { cwd: projectDir });
+    const parsed = extractFirstJson(String(stdout));
+    if (!parsed || typeof parsed.exists !== "boolean") {
+      throw new Error("adapter must print JSON {exists, live, status} on stdout");
+    }
+    const alive = parsed.exists && parsed.live !== false;
+    const result = alive
+      ? { level: "tracker", verified: true, status: parsed.status ?? null }
+      : { level: "tracker", verified: false, status: parsed.status ?? (parsed.exists ? "not-live" : "not-found") };
+    try {
+      fs.mkdirSync(path.dirname(cachePath(projectDir)), { recursive: true });
+      fs.writeFileSync(cachePath(projectDir), JSON.stringify({ ...cache, [key]: { at: now(), result } }));
+    } catch { /* cache is best-effort — the verdict stands without it */ }
+    return result;
+  } catch (err) {
+    const why = String(err.message || err).split("\n")[0].slice(0, 120);
+    return {
+      level: "branch-ref", verified: null,
+      note: `tracker verification degraded to branch-ref (${why}) — fix board.verify_cmd or its credentials`,
+    };
+  }
+}

package/src/sonar/scanner.js

@@ -47,13 +47,17 @@ export function buildScannerOpts(projectKey, scanner = {}) {
     opts.push(`-Dsonar.javascript.lcov.reportPaths=${scanner.javascript_lcov_report_paths}`);
   }
   const rules = scanner.disabled_rules || [];
-  rules.forEach((rule, i) => {
-    opts.push(
-      `-Dsonar.issue.ignore.multicriteria=e${i + 1}`,
-      `-Dsonar.issue.ignore.multicriteria.e${i + 1}.ruleKey=${rule}`,
-      `-Dsonar.issue.ignore.multicriteria.e${i + 1}.resourceKey=**/*`
-    );
-  });
+  if (rules.length > 0) {
+    // KJC-BUG-0139: the list property is declared ONCE — one `multicriteria=`
+    // per rule was last-wins, silently un-ignoring every rule but the final one.
+    opts.push(`-Dsonar.issue.ignore.multicriteria=${rules.map((_, i) => `e${i + 1}`).join(",")}`);
+    rules.forEach((rule, i) => {
+      opts.push(
+        `-Dsonar.issue.ignore.multicriteria.e${i + 1}.ruleKey=${rule}`,
+        `-Dsonar.issue.ignore.multicriteria.e${i + 1}.resourceKey=**/*`
+      );
+    });
+  }
   return opts.join(" ");
 }
 

package/src/tournament/judge.js

@@ -123,9 +123,8 @@ export async function judgeTournament({ tournamentDir, config = {}, logger = con
   let solomon = null;
   if (escalated) {
     if (!solomonFn) {
-      throw new Error(
-        `tournament: ${verdict.tie ? "empate declarado" : `discrepancia juez(${judgeTop}) vs scoreboard(${boardTop})`} y sin árbitro configurado`
-      );
+      const why = verdict.tie ? "empate declarado" : `discrepancia juez(${judgeTop}) vs scoreboard(${boardTop})`;
+      throw new Error(`tournament: ${why} y sin árbitro configurado`);
     }
     solomon = await solomonFn({
       judgeRanking: verdict.ranking,

package/src/tournament/scoreboard.js

@@ -17,7 +17,7 @@ import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 
 const execFileAsync = promisify(execFile);
-const TESTS_RE = /(^|\/)(tests?|__tests__|spec)\/|\.(test|spec)\.[a-z]+$/;
+const TESTS_RE = /(?:(?:^|\/)(?:tests?|__tests__|spec)\/)|(?:\.(?:test|spec)\.[a-z]+$)/;
 const MUTATE_TIMEOUT_MS = 10 * 60 * 1000;
 
 // EXACT unified-diff header forms — an added line whose content starts with

package/src/utils/update-check.js

@@ -17,7 +17,8 @@ const HIGHLIGHT_MAX = 160;
  * ("Minor. **The method, enforced.** …"), bold stripped, truncated. Pure.
  */
 export function parseChangelogHighlight(markdown, version) {
-  const section = String(markdown).split(new RegExp(`^## \\[${version.replaceAll(".", "\\.")}\\][^\\n]*$`, "m"))[1];
+  const escapedVersion = version.replaceAll(".", String.raw`\.`);
+  const section = String(markdown).split(new RegExp(String.raw`^## \[${escapedVersion}\][^\n]*$`, "m"))[1];
   if (!section) return null;
   const firstLine = section.split(/^##|^###/m)[0].split("\n").map((l) => l.trim()).find(Boolean);
   if (!firstLine) return null;