karajan-code 4.70.4 → 5.0.0

package/src/commands/review-gate.js

@@ -8,7 +8,7 @@
 import { existsSync, readFileSync } from "node:fs";
 import { isAbsolute, join } from "node:path";
 import { runCommand } from "../utils/process.js";
-import { checkVerdict, diffHash, pruneVerdicts } from "../review/verdict-store.js";
+import { checkVerdict, diffHash, pruneVerdicts, saveVerdict } from "../review/verdict-store.js";
 import { runOneShotReview } from "../review/one-shot-review.js";
 import { runSolomonArbitration } from "../review/solomon-arbitration.js";
 import { ensureGateTrackable } from "../review/gate-gitignore.js";
@@ -188,119 +188,102 @@ export async function solomonCommand({ config, logger = null, flags = {} }) {
   return res;
 }
 
-export async function reviewGateCommand({ config, logger = null, flags = {} }) {
-  const projectDir = config?.projectDir || process.cwd();
-
-  if (flags.installGate) {
-    const fs = await import("node:fs/promises");
-    const marker = join(projectDir, ".karajan", "review-gate");
-    await fs.mkdir(join(projectDir, ".karajan"), { recursive: true });
-    await fs.writeFile(marker, "# Cross-AI review gate enabled (ENV-C1). Commit this file so the whole team inherits the gate.\n");
-    // KJC-BUG-0447 (#2655): the marker declares the gate; only a pre-commit that runs it enforces it.
-    const hook = gateHookStatus(projectDir);
-    if (hook.enforced) console.log("✓ review gate enabled — commits now require an approved cross-AI verdict (kj review --staged)");
-    else {
-      console.log(`✗ review gate declared (.karajan/review-gate) but NOT enforced: ${hook.reason} — run \`kj harden\` so the pre-commit hook runs it`);
-      process.exitCode = 1;
-    }
-    // KJC-TSK-0646: a `.karajan/` dir-exclude would silently keep the
-    // contract out of git — rewrite it so the team actually inherits it.
-    const gi = await ensureGateTrackable(projectDir);
-    if (gi.changed) {
-      console.log("✓ .gitignore adjusted: the gate contract (.karajan/review-gate, hooks) is now trackable — commit it");
-    }
-    return { installed: true, enforced: hook.enforced };
+async function installGateAction(projectDir) {
+  const fs = await import("node:fs/promises");
+  const marker = join(projectDir, ".karajan", "review-gate");
+  await fs.mkdir(join(projectDir, ".karajan"), { recursive: true });
+  await fs.writeFile(marker, "# Cross-AI review gate enabled (ENV-C1). Commit this file so the whole team inherits the gate.\n");
+  // KJC-BUG-0447 (#2655): the marker declares the gate; only a pre-commit that runs it enforces it.
+  const hook = gateHookStatus(projectDir);
+  if (hook.enforced) console.log("✓ review gate enabled — commits now require an approved cross-AI verdict (kj review --staged)");
+  else {
+    console.log(`✗ review gate declared (.karajan/review-gate) but NOT enforced: ${hook.reason} — run \`kj harden\` so the pre-commit hook runs it`);
+    process.exitCode = 1;
   }
-
-  // KJC-BUG-0173: manual GC of the verdict store. Opportunistic pruning runs
-  // on every saved verdict; this lets a human sweep on demand, with --dry-run
-  // to see what would go without deleting.
-  if (flags.prune) {
-    const dryRun = Boolean(flags.dryRun || flags.checkOnly);
-    const days = Number(flags.pruneDays);
-    const res = await pruneVerdicts({ projectDir, dryRun, ...(Number.isFinite(days) && days > 0 ? { maxAgeDays: days } : {}) });
-    console.log(
-      dryRun
-        ? `kj review --prune (dry run): ${res.expired.length} of ${res.scanned} verdict(s) older than ${res.maxAgeDays}d would be removed`
-        : `kj review --prune: removed ${res.removed} verdict(s) older than ${res.maxAgeDays}d (${res.scanned - res.removed} kept)`,
-    );
-    return { pruned: res.removed, dryRun };
+  // KJC-TSK-0646: a `.karajan/` dir-exclude would silently keep the
+  // contract out of git — rewrite it so the team actually inherits it.
+  const gi = await ensureGateTrackable(projectDir);
+  if (gi.changed) {
+    console.log("✓ .gitignore adjusted: the gate contract (.karajan/review-gate, hooks) is now trackable — commit it");
   }
+  return { installed: true, enforced: hook.enforced };
+}
 
-  const diff = await rawDiff(flags.range);
-
-  const card = await enforceCardFirst({ config, projectDir });
-  if (!card.ok) return { verdict: "rejected", reviewer: "card-first", issues: [{ severity: "high", description: card.reason }] };
-
-  // KJC-TSK-1086: the Steward's block at commit too, not only where Edit starts work.
-  const steward = stewardBlocking({ projectDir, config });
-  if (steward) {
-    console.log(`✗ ${steward.reason}`);
-    process.exitCode = 1;
-    return { verdict: "rejected", reviewer: "steward", issues: [{ severity: "high", description: steward.reason }] };
-  }
+// KJC-BUG-0173: manual GC of the verdict store. Opportunistic pruning runs
+// on every saved verdict; this lets a human sweep on demand, with --dry-run
+// to see what would go without deleting.
+async function pruneAction(projectDir, flags) {
+  const dryRun = Boolean(flags.dryRun || flags.checkOnly);
+  const days = Number(flags.pruneDays);
+  const res = await pruneVerdicts({ projectDir, dryRun, ...(Number.isFinite(days) && days > 0 ? { maxAgeDays: days } : {}) });
+  console.log(
+    dryRun
+      ? `kj review --prune (dry run): ${res.expired.length} of ${res.scanned} verdict(s) older than ${res.maxAgeDays}d would be removed`
+      : `kj review --prune: removed ${res.removed} verdict(s) older than ${res.maxAgeDays}d (${res.scanned - res.removed} kept)`,
+  );
+  return { pruned: res.removed, dryRun };
+}
 
-  // KJC-TSK-0687 (MG-B): the verifiable half of TDD — sources without a
-  // single test change warn (block via method_gates.tests_with_code).
-  const changedFiles = (await rawDiff(flags.range, ["--name-only"])).split("\n").map((f) => f.trim()).filter(Boolean);
-  // KJC-BUG-0229: un fichero BORRADO no es una fuente que el scan pueda indexar
-  // ni sobre la que el RAG pueda responder, asi que exigirlo era pedir lo
-  // imposible: una PR que retiraba 45 ficheros se paro dos veces y acumulo tres
-  // excepciones por la misma causa mecanica. Los requisitos de Sonar y de RAG
-  // se evaluan sobre lo que sigue VIVO tras el cambio (A, C, M, R); policy, LOC
-  // y tests-with-code siguen viendo el diff entero, porque ahi un borrado si
-  // cuenta. El borrado danino lo cubre la review cruzada, que lee todo el diff.
-  const liveFiles = (await rawDiff(flags.range, ["--name-only", "--diff-filter=ACMR"])).split("\n").map((f) => f.trim()).filter(Boolean);
+/** A gate's rejection: said, exit 1, and the record the caller returns (KJC-TSK-1257). */
+function rejected(reviewer, issues) {
+  process.exitCode = 1;
+  return { verdict: "rejected", reviewer, issues };
+}
 
-  // KJC-TSK-0688 (MG-C) + KJC-TSK-0691 (MG-E): oversized-diff policy.
-  // Field case: a 522-line PR sailed past the warning with a
-  // rationalization — where the project wants teeth, pr_size: "block"
-  // rejects deterministically with a NAMED escape. Default stays warn.
-  // PL-C (KJC-TSK-0735), fuente única de umbrales: si la policy declara el
-  // invariante net_lines_added, SU max es el umbral — el mismo número que
-  // aplican kj policy check y el tier C de CI; method_gates queda de fallback.
-  // KJC-BUG-0326 (#2085): two tiers. ~150 is the ideal (method_gates.pr_size_warn);
-  // up to the limit (the policy's net_lines_added max, else method_gates.pr_size_max,
-  // 200) is allowed without asking; above the limit, partition. KJC-TSK-1076: one
-  // source, shared with the third-party PR checks.
-  const pol = loadPolicy({ projectDir });
+/**
+ * KJC-TSK-0688 (MG-C) + KJC-TSK-0691 (MG-E): oversized-diff policy.
+ * Field case: a 522-line PR sailed past the warning with a
+ * rationalization — where the project wants teeth, pr_size: "block"
+ * rejects deterministically with a NAMED escape. Default stays warn.
+ * PL-C (KJC-TSK-0735), fuente única de umbrales: si la policy declara el
+ * invariante net_lines_added, SU max es el umbral — el mismo número que
+ * aplican kj policy check y el tier C de CI; method_gates queda de fallback.
+ * KJC-BUG-0326 (#2085): two tiers. ~150 is the ideal (method_gates.pr_size_warn);
+ * up to the limit (the policy's net_lines_added max, else method_gates.pr_size_max,
+ * 200) is allowed without asking; above the limit, partition. KJC-TSK-1076: one
+ * source, shared with the third-party PR checks.
+ * @returns {Promise<object|null>} the rejection, or null to go on
+ */
+async function prSizeGate({ projectDir, config, range }) {
   const { ideal: sizeIdeal, limit: sizeWarn, source: sizeSource } = prSizeLimit({ projectDir, config });
-  if (sizeWarn > 0) {
-    const numstat = await rawDiff(flags.range, ["--numstat"]);
-    // KJC-BUG-0205: the budget caps CODE growth, so generated output and human
-    // documentation are exempt — the same rule CI applies. Counting everything
-    // here warned 234 lines on a doc-only PR that CI counted at 104, and two
-    // implementations of one rule that disagree teach people to trust neither.
-    // KJC-BUG-0434: measured NET, as CI and the policy's net_lines_added do — a rewrite in place is not growth.
-    const { added, testAdded } = budgetedAdded(numstat);
-    const { net, exempt } = budgetedNet(numstat);
-    // Said out loud: an exemption nobody sees is indistinguishable from a gate
-    // that is not looking.
-    if (exempt > 0) console.log(`ℓ pr-size: ${exempt} line(s) exempt from the budget (generated output and human docs; AI-rule files always count)`);
-    if (net > sizeIdeal && net <= sizeWarn) {
-      console.log(`ℓ pr-size: ${net} net lines, over the ~${sizeIdeal} ideal, within the ${sizeWarn} limit: allowed, nothing to ask`);
-    }
-    if (net > sizeWarn) {
-      // KJC-TSK-0795 AC5: say how much of the weight is the module's OWN tests —
-      // partitioning is a decision, and it must never split code from its tests.
-      const split = testAdded > 0 ? ` (${added - testAdded} source + ${testAdded} test lines added — partition by feature, never code from its tests)` : "";
-      const sizePolicy = config?.method_gates?.pr_size || "warn";
-      // ADR 0015: no env escape — an exception is the user's label on the PR, judged in CI.
-      if (sizePolicy === "block") {
-        const reason = `${net} net lines${split} is over the ${sizeWarn}-line limit (${sizeSource}; method_gates.pr_size: block) — partition the work; an exception is your user's large-pr-justified label on the PR`;
-        console.log(`✗ pr-size gate: ${reason}`);
-        process.exitCode = 1;
-        return { verdict: "rejected", reviewer: "pr-size", issues: [{ severity: "high", description: reason }] };
-      } else {
-        console.log(`⚠ pr-size: ${net} net lines${split}, over the ${sizeWarn}-line limit (ideal ~${sizeIdeal}, source: ${sizeSource}) — partition the work before committing (method_gates.pr_size: block to harden)`);
-      }
-    }
+  if (sizeWarn <= 0) return null;
+  const numstat = await rawDiff(range, ["--numstat"]);
+  // KJC-BUG-0205: the budget caps CODE growth, so generated output and human
+  // documentation are exempt — the same rule CI applies. Counting everything
+  // here warned 234 lines on a doc-only PR that CI counted at 104, and two
+  // implementations of one rule that disagree teach people to trust neither.
+  // KJC-BUG-0434: measured NET, as CI and the policy's net_lines_added do — a rewrite in place is not growth.
+  const { added, testAdded } = budgetedAdded(numstat);
+  const { net, exempt } = budgetedNet(numstat);
+  // Said out loud: an exemption nobody sees is indistinguishable from a gate
+  // that is not looking.
+  if (exempt > 0) console.log(`ℓ pr-size: ${exempt} line(s) exempt from the budget (generated output and human docs; AI-rule files always count)`);
+  if (net > sizeIdeal && net <= sizeWarn) {
+    console.log(`ℓ pr-size: ${net} net lines, over the ~${sizeIdeal} ideal, within the ${sizeWarn} limit: allowed, nothing to ask`);
   }
-  // KJC-TSK-0705 (PV-B): the outbound privacy boundary at commit time.
-  // Denylist data rejects with no escape (ADR 0015: false positives go in the allow list); generic PII
-  // warns (privacy.generic: "block" hardens). Added lines only — deletions
-  // don't publish. In the SEA binary the privacy module is stubbed and
-  // throws: the gate degrades with a note instead of crashing.
+  if (net <= sizeWarn) return null;
+  // KJC-TSK-0795 AC5: say how much of the weight is the module's OWN tests —
+  // partitioning is a decision, and it must never split code from its tests.
+  const split = testAdded > 0 ? ` (${added - testAdded} source + ${testAdded} test lines added — partition by feature, never code from its tests)` : "";
+  // ADR 0015: no env escape — an exception is the user's label on the PR, judged in CI.
+  if ((config?.method_gates?.pr_size || "warn") === "block") {
+    const reason = `${net} net lines${split} is over the ${sizeWarn}-line limit (${sizeSource}; method_gates.pr_size: block) — partition the work; an exception is your user's large-pr-justified label on the PR`;
+    console.log(`✗ pr-size gate: ${reason}`);
+    return rejected("pr-size", [{ severity: "high", description: reason }]);
+  }
+  console.log(`⚠ pr-size: ${net} net lines${split}, over the ${sizeWarn}-line limit (ideal ~${sizeIdeal}, source: ${sizeSource}) — partition the work before committing (method_gates.pr_size: block to harden)`);
+  return null;
+}
+
+/**
+ * KJC-TSK-0705 (PV-B): the outbound privacy boundary at commit time.
+ * Denylist data rejects with no escape (ADR 0015: false positives go in the allow list); generic PII
+ * warns (privacy.generic: "block" hardens). Added lines only — deletions
+ * don't publish. In the SEA binary the privacy module is stubbed and
+ * throws: the gate degrades with a note instead of crashing.
+ * @returns {object|null} the rejection, or null to go on
+ */
+function privacyGate({ diff, config }) {
   try {
     // KJC-BUG-0203: per file, so a finding can name where it lives and so
     // build output is judged as what it is. Generic heuristics are silenced
@@ -315,53 +298,56 @@ export async function reviewGateCommand({ config, logger = null, flags = {} }) {
     const warns = findings.filter((f) => f.severity === "warn");
     for (const f of warns) console.log(`⚠ privacy: [${f.type}] ${f.source}:${f.line} → ${f.masked} — personal data? move it out before it ships`);
     const hardened = config?.privacy?.generic === "block" && warns.length > 0;
-    if (blocks.length > 0 || hardened) {
-      for (const f of blocks) console.log(`✗ privacy: [${f.type}] ${f.source}:${f.line} → ${f.masked}`);
-      const reason = `${blocks.length || warns.length} personal-data finding(s) in the staged diff — this must not reach the repo (a confirmed false positive goes in the allow list of ~/.karajan/privacy.yml)`;
-      console.log(`✗ privacy gate: ${reason}`);
-      process.exitCode = 1;
-      return { verdict: "rejected", reviewer: "privacy", issues: [{ severity: "high", description: reason }] };
-    }
+    if (blocks.length === 0 && !hardened) return null;
+    for (const f of blocks) console.log(`✗ privacy: [${f.type}] ${f.source}:${f.line} → ${f.masked}`);
+    const reason = `${blocks.length || warns.length} personal-data finding(s) in the staged diff — this must not reach the repo (a confirmed false positive goes in the allow list of ~/.karajan/privacy.yml)`;
+    console.log(`✗ privacy gate: ${reason}`);
+    return rejected("privacy", [{ severity: "high", description: reason }]);
   } catch (err) {
     // Known degradation: the SEA stub throws its install-from-npm message.
     // Anything else fails CLOSED — a silent skip would defeat the guarantee.
     if (/standalone binary/i.test(err?.message || "")) {
       console.log("⚠ privacy gate unavailable in this build — skipping");
-    } else {
-      const reason = `privacy gate error: ${err.message} — refusing to pass the boundary unchecked`;
-      console.log(`✗ ${reason}`);
-      process.exitCode = 1;
-      return { verdict: "rejected", reviewer: "privacy", issues: [{ severity: "high", description: reason }] };
+      return null;
     }
+    const reason = `privacy gate error: ${err.message} — refusing to pass the boundary unchecked`;
+    console.log(`✗ ${reason}`);
+    return rejected("privacy", [{ severity: "high", description: reason }]);
   }
+}
 
-  // KJC-TSK-0795 AC1: hand the gate the numbers so a delete-only diff is
-  // exempt — deleting code adds no behavior to test.
-  const numstat = (await rawDiff(flags.range, ["--numstat"])).split("\n").map((l) => l.trim()).filter(Boolean)
+/**
+ * KJC-TSK-0795 AC1: hand the gate the numbers so a delete-only diff is
+ * exempt — deleting code adds no behavior to test.
+ * @returns {Promise<object|null>} the rejection, or null to go on
+ */
+async function testsWithCodeGate({ config, projectDir, range, changedFiles }) {
+  const numstat = (await rawDiff(range, ["--numstat"])).split("\n").map((l) => l.trim()).filter(Boolean)
     .map((l) => { const [a, r, ...f] = l.split(/\s+/); return { file: f.join(" "), added: a === "-" ? 1 : Number(a) || 0, removed: r === "-" ? 0 : Number(r) || 0 }; });
-  await markCommentOnlyAdditions(numstat, { range: flags.range, projectDir });
+  await markCommentOnlyAdditions(numstat, { range, projectDir });
   const tests = checkTestsWithCode({ config, stagedFiles: changedFiles, numstat });
   if (tests.mode === "delete-only") console.log(`⚠ tests-with-code: exempt — ${tests.reason}`);
   if (tests.mode === "warn") console.log(`⚠ tests-with-code: ${tests.reason}`);
   if (tests.mode === "exempt") console.log(`⚠ tests-with-code exempt: ${tests.reason}`);
-  if (!tests.ok) {
-    console.log(`✗ tests-with-code gate: ${tests.reason}`);
-    process.exitCode = 1;
-    return { verdict: "rejected", reviewer: "tests-with-code", issues: [{ severity: "high", description: tests.reason }] };
-  }
+  if (tests.ok) return null;
+  console.log(`✗ tests-with-code gate: ${tests.reason}`);
+  return rejected("tests-with-code", [{ severity: "high", description: tests.reason }]);
+}
 
-  // KJC-TSK-0734 (PL-B): la policy declarativa como gate determinista, en
-  // --staged Y en --check — el pre-commit hereda los dientes sin regenerar
-  // hooks. enforcement=warn avisa; deny cierra sin excepción por diff (ADR
-  // 0015); class=security cierra además sin arbitraje.
+const atFile = (v) => (v.file ? ` (${v.file})` : "");
+
+/**
+ * KJC-TSK-0734 (PL-B): la policy declarativa como gate determinista, en
+ * --staged Y en --check — el pre-commit hereda los dientes sin regenerar
+ * hooks. enforcement=warn avisa; deny cierra sin excepción por diff (ADR
+ * 0015); class=security cierra además sin arbitraje.
+ * @returns {Promise<{rejection: object|null, gate: object, seal: Function}>} `seal` records the chokepoint's decisions
+ */
+async function policyGate({ projectDir, diff, pol, changedFiles, std, range, check }) {
   // KJC-BUG-0208: el mismo modulo que decide el presupuesto decide el metrico
   // del invariante. Sumar aqui el numstat entero daba dos cifras para la misma
   // regla en dos lineas seguidas del mismo comando.
-  const { net } = budgetedNet(await rawDiff(flags.range, ["--numstat"]));
-  // GOV-B (KJC-TSK-0746): las permanentes concedidas (kj policy grant)
-  // eximen su regla mientras viven; el descarte de líneas corruptas se dice.
-  const std = loadStandingExceptions(projectDir);
-  if (std.discarded > 0) console.log(`⚠ policy: ${std.discarded} línea(s) corruptas descartadas en policy-exceptions.jsonl — revísalo`);
+  const { net } = budgetedNet(await rawDiff(range, ["--numstat"]));
   const gate = evaluatePolicyGate({
     policy: pol.policy, errors: pol.errors, files: changedFiles, netLinesAdded: net,
     diffHashValue: diffHash(diff),
@@ -371,195 +357,222 @@ export async function reviewGateCommand({ config, logger = null, flags = {} }) {
   // 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 lifted = liftSealedSupervisorViolations({ projectDir, violations: gate.denials });
+  if (lifted.lifted > 0) {
+    console.log(`✓ policy: ${lifted.lifted} fichero(s) de supervisor verificados contra la provenance sellada (ADR 0009) — regeneración, no edición`);
+    gate.denials = lifted.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 w of gate.warns) console.log(`⚠ policy [${w.rule_id}] ${w.reason}${atFile(w)}`);
   for (const e of gate.exempted) console.log(formatExempted(e));
   // GOV-C (KJC-TSK-0747): las decisiones de chokepoint dejan rastro
   // hash-encadenado — cada deny, cada excepción, y el allow del commit.
-  const chokepoint = flags.check ? "commit" : "review";
+  const chokepoint = check ? "commit" : "review";
   const seal = (decision, extra = {}) =>
     recordGateDecision(projectDir, { decision, chokepoint, policy_hash: policyFileHash(projectDir), artifact_hash: diffHash(diff), ...extra });
   if (gate.exempted.length > 0) seal("exempt", { rule_ids: gate.exempted.map((e) => e.rule_id) });
-  if (!gate.ok) {
-    for (const d of gate.denials) {
-      const sec = d.class === "security" ? " [security — sin escape ni arbitraje]" : "";
-      console.log(`✗ policy [${d.rule_id}]${sec} ${d.reason}${at(d)}`);
-    }
-    seal("deny", { rule_ids: gate.denials.map((d) => d.rule_id) });
-    const reason = gate.invalid
-      ? "policy.yml inválida — una regla que miente es peor que ninguna: corrígela"
-      : `${gate.denials.length} violación(es) de policy con enforcement=deny — el diff no entra`;
-    console.log(`✗ policy gate: ${reason}`);
-    process.exitCode = 1;
-    return { verdict: "rejected", reviewer: "policy", issues: gate.denials.map((d) => ({ severity: "high", file: d.file, description: `[${d.rule_id}] ${d.reason}` })) };
+  if (gate.ok) return { rejection: null, gate, seal };
+  for (const d of gate.denials) {
+    const sec = d.class === "security" ? " [security — sin escape ni arbitraje]" : "";
+    console.log(`✗ policy [${d.rule_id}]${sec} ${d.reason}${atFile(d)}`);
   }
+  seal("deny", { rule_ids: gate.denials.map((d) => d.rule_id) });
+  const reason = gate.invalid
+    ? "policy.yml inválida — una regla que miente es peor que ninguna: corrígela"
+    : `${gate.denials.length} violación(es) de policy con enforcement=deny — el diff no entra`;
+  console.log(`✗ policy gate: ${reason}`);
+  const rejection = rejected("policy", gate.denials.map((d) => ({ severity: "high", file: d.file, description: `[${d.rule_id}] ${d.reason}` })));
+  return { rejection, gate, seal };
+}
 
-  if (flags.check) {
-    // KJC-BUG-0132 (issue #1344): a PURE merge commit stages no content of
-    // its own — everything it brings reached the parent branches already
-    // reviewed, and there is no diff to bind a verdict to, so demanding one
-    // deadlocks the merge. A merge WITH conflict resolutions stages real
-    // content and still requires its verdict below.
-    if (!flags.range && !diff.trim()) {
-      const gitDirRaw = (await runCommand("git", ["rev-parse", "--git-dir"])).stdout?.trim();
-      const gitDir = gitDirRaw && !isAbsolute(gitDirRaw) ? join(projectDir, gitDirRaw) : gitDirRaw;
-      if (gitDir && existsSync(join(gitDir, "MERGE_HEAD"))) {
-        console.log("✓ pure merge commit — empty staged diff, parents already reviewed; gate passes with trail");
-        process.exitCode = 0;
-        return { ok: true, merge: true, reason: "pure merge commit (MERGE_HEAD, empty staged diff)" };
-      }
-    }
-    let res = await checkVerdict(projectDir, diff);
-    if (res.note) console.log(`ℹ ${res.note}`);
-    // KJC-TSK-0838: a reviewed diff with code enters only if the verdict's
-    // sonar block proves the analysis ran and covered every staged source.
-    // The headless pipeline stamps its verdict after its own sonar stage and
-    // carries no block yet (step 3 of the card) — said, never assumed silent.
-    if (res.ok && res.verdict.host === "kj-pipeline") {
-      // The pipeline scans the whole project (no per-file proof yet), so its
-      // stamp must at least show the stage RAN; no block or a skipped stage
-      // is refused like any other unanalysed code.
-      const stage = res.verdict.sonar;
-      if (!stage?.ran) {
-        const why = stage ? `the pipeline's sonar stage did not run: ${stage.reason || "unknown reason"}` : "the pipeline verdict carries no sonar block";
-        res = { ok: false, verdict: res.verdict, reason: `Sonar is mandatory for code — ${why}` };
-      }
-    } else if (res.ok) {
-      const req = checkSonarRequirement({ config, stagedFiles: liveFiles, sonar: res.verdict.sonar, standingExceptions: std.standing });
-      if (!req.ok) res = { ok: false, verdict: res.verdict, reason: req.reason };
-      else if (req.mode === "granted") console.log(formatSonarGrant(req.grant));
-    }
-    // KJC-TSK-0849 (ADR 0010, RAG-C): the verdict's rag block is the evidence
-    // that the session consulted the RAG about every staged source. The one
-    // place the rule cannot be verified is a pipeline verdict: the headless
-    // pipeline keeps no session ledger yet. It WARNS and the allow seals the
-    // warn under the rule id, so the exception is auditable (kj policy report)
-    // and gains teeth with data — never accepted in silence.
-    const warnIds = gate.warns.map((w) => w.rule_id);
-    if (res.ok && res.verdict.host === "kj-pipeline") {
-      console.log(`⚠ rag [${RAG_RULE_ID}]: the pipeline verdict carries no session ledger — the headless pipeline does not consult the RAG yet; sealed as a warn`);
-      if (!warnIds.includes(RAG_RULE_ID)) warnIds.push(RAG_RULE_ID);
-    } else if (res.ok) {
-      const { harness, verified, mismatched, drift } = readRagLedger(projectDir);
-      const rreq = checkRagVerdict({ config, stagedFiles: liveFiles, rag: res.verdict.rag, harness, verified, mismatched, drift, standingExceptions: std.standing });
-      if (!rreq.ok) res = { ok: false, verdict: res.verdict, reason: rreq.reason };
-      else if (rreq.mode === "granted" && rreq.grant) console.log(formatRagGrant(rreq.grant));
-    }
-    console.log(res.ok
-      ? `✓ verdict ok — approved by ${res.verdict.reviewer} (diff ${res.verdict.diffHash.slice(0, 12)})`
-      : `✗ ${res.reason}`);
-    // GOV-C: el allow del chokepoint de COMMIT es evidencia — se sella. PL-E
-    // (KJC-TSK-0767): con las reglas que AVISARON, para que "nace avisando y
-    // gana dientes" se decida con datos (kj policy report), no a ciegas.
-    if (res.ok) seal("allow", warnIds.length > 0 ? { warn_rule_ids: warnIds } : {});
-    process.exitCode = res.ok ? 0 : 1;
+/**
+ * KJC-BUG-0132 (issue #1344): a PURE merge commit stages no content of
+ * its own — everything it brings reached the parent branches already
+ * reviewed, and there is no diff to bind a verdict to, so demanding one
+ * deadlocks the merge. A merge WITH conflict resolutions stages real
+ * content and still requires its verdict.
+ */
+async function isPureMerge({ projectDir, diff, range }) {
+  if (range || diff.trim()) return false;
+  const gitDirRaw = (await runCommand("git", ["rev-parse", "--git-dir"])).stdout?.trim();
+  const gitDir = gitDirRaw && !isAbsolute(gitDirRaw) ? join(projectDir, gitDirRaw) : gitDirRaw;
+  return Boolean(gitDir && existsSync(join(gitDir, "MERGE_HEAD")));
+}
+
+/**
+ * KJC-TSK-0838: a reviewed diff with code enters only if the verdict's
+ * sonar block proves the analysis ran and covered every staged source.
+ * The headless pipeline stamps its verdict after its own sonar stage and
+ * carries no block yet (step 3 of the card) — said, never assumed silent.
+ */
+function withSonarProof(res, { config, liveFiles, std }) {
+  if (res.verdict.host === "kj-pipeline") {
+    // The pipeline scans the whole project (no per-file proof yet), so its
+    // stamp must at least show the stage RAN; no block or a skipped stage
+    // is refused like any other unanalysed code.
+    const stage = res.verdict.sonar;
+    if (stage?.ran) return res;
+    const why = stage ? `the pipeline's sonar stage did not run: ${stage.reason || "unknown reason"}` : "the pipeline verdict carries no sonar block";
+    return { ok: false, verdict: res.verdict, reason: `Sonar is mandatory for code — ${why}` };
+  }
+  const req = checkSonarRequirement({ config, stagedFiles: liveFiles, sonar: res.verdict.sonar, standingExceptions: std.standing });
+  if (!req.ok) return { ok: false, verdict: res.verdict, reason: req.reason };
+  if (req.mode === "granted") console.log(formatSonarGrant(req.grant));
+  return res;
+}
+
+/**
+ * KJC-TSK-0849 (ADR 0010, RAG-C): the verdict's rag block is the evidence
+ * that the session consulted the RAG about every staged source. The one
+ * place the rule cannot be verified is a pipeline verdict: the headless
+ * pipeline keeps no session ledger yet. It WARNS and the allow seals the
+ * warn under the rule id, so the exception is auditable (kj policy report)
+ * and gains teeth with data — never accepted in silence.
+ */
+function withRagProof(res, { config, liveFiles, std, projectDir, warnIds }) {
+  if (res.verdict.host === "kj-pipeline") {
+    console.log(`⚠ rag [${RAG_RULE_ID}]: the pipeline verdict carries no session ledger — the headless pipeline does not consult the RAG yet; sealed as a warn`);
+    if (!warnIds.includes(RAG_RULE_ID)) warnIds.push(RAG_RULE_ID);
     return res;
   }
+  const { harness, verified, mismatched, drift } = readRagLedger(projectDir);
+  const rreq = checkRagVerdict({ config, stagedFiles: liveFiles, rag: res.verdict.rag, harness, verified, mismatched, drift, standingExceptions: std.standing });
+  if (!rreq.ok) return { ok: false, verdict: res.verdict, reason: rreq.reason };
+  if (rreq.mode === "granted" && rreq.grant) console.log(formatRagGrant(rreq.grant));
+  return res;
+}
 
-  // KJC-TSK-0676: deterministic pre-gate — sonar findings on the changed
-  // files come back BEFORE any AI opinion. Blocking severities reject
-  // without spending reviewer tokens; the rest travel with the task so
-  // the cross-AI reviewer weighs them. Unavailable sonar degrades loudly.
-  let task = flags.task;
-  // KJC-TSK-0838: what sonar saw travels INSIDE the verdict, bound to the
-  // diff hash — a reviewed diff and a reviewed AND analysed diff must be
-  // distinguishable by --check and by the method report.
-  let sonarRecord = { ran: false, reason: "--no-sonar: the pre-gate was skipped by flag" };
-  if (flags.sonar !== false) {
-    // KJC-TSK-0795 AC3: only issues on lines this diff ADDS may veto.
-    const touchedLines = addedLinesByFile(await rawDiff(flags.range, ["--unified=0"]));
-    const pre = await runSonarPregate({ config, stagedFiles: liveFiles, touchedLines, logger });
-    if (!pre.available) {
-      // KJC-BUG-0156 (issue #1543): a scan that FAILED must not read like one
-      // more config warning — it hid a dead quality gate for 8 straight PRs.
-      // Still fail-open (a laptop without Docker still commits), but SAID.
-      const chosen = /disabled in config/.test(pre.reason || "");
-      console.log(chosen
-        ? `⚠ sonar pre-gate skipped: ${pre.reason}`
-        : `✗ sonar pre-gate UNAVAILABLE — the quality gate did NOT run on this diff: ${pre.reason}`);
-      sonarRecord = { ran: false, reason: pre.reason };
-    } else {
-      sonarRecord = {
-        ran: true, projectKey: pre.projectKey, covered: pre.covered ?? [], uncovered: pre.uncovered ?? [],
-        blocking: pre.blocking.length, advisory: pre.advisory.length,
-      };
-      if (sonarRecord.uncovered.length > 0) {
-        console.log(`⚠ sonar coverage: ${sonarRecord.uncovered.length} staged source(s) were NOT in the analysis (${sonarRecord.uncovered.slice(0, 5).join(", ")}${sonarRecord.uncovered.length > 5 ? "…" : ""}) — the scan did not see them`);
-      }
-      const found = [...pre.blocking, ...pre.advisory];
-      if (found.length > 0) {
-        console.log(`Sonar on the changed lines — ${pre.blocking.length} blocking, ${pre.advisory.length} advisory (project total: ${pre.totalProject}):`);
-        for (const f of found) console.log(`  - ${formatSonarFinding(f)}`);
-      }
-      if ((pre.preexisting || []).length > 0) {
-        console.log(`⚠ sonar trend: ${pre.preexisting.length} preexisting issue(s) on untouched lines of these files — not this PR's veto, but the debt is real`);
-      }
-      if (pre.blocking.length > 0) {
-        console.log("✗ REJECTED by sonar (deterministic) — fix the blocking findings; the cross-AI reviewer was not invoked.");
-        process.exitCode = 1;
-        return {
-          verdict: "rejected", reviewer: "sonar",
-          issues: pre.blocking.map((i) => ({ severity: i.severity, file: undefined, description: formatSonarFinding(i) })),
-        };
-      }
-      if (pre.advisory.length > 0) {
-        task = `${task || "Review the following diff for correctness, security and maintainability."}\n\n`
-          + `Deterministic Sonar findings on these files (fold them into your review):\n`
-          + pre.advisory.map((f) => `- ${formatSonarFinding(f)}`).join("\n");
-      }
-    }
+/** --check (the pre-commit): the staged diff enters only with an approved verdict that carries its proofs. */
+async function checkPath({ projectDir, config, diff, range, liveFiles, std, gate, seal }) {
+  if (await isPureMerge({ projectDir, diff, range })) {
+    console.log("✓ pure merge commit — empty staged diff, parents already reviewed; gate passes with trail");
+    process.exitCode = 0;
+    return { ok: true, merge: true, reason: "pure merge commit (MERGE_HEAD, empty staged diff)" };
   }
+  let res = await checkVerdict(projectDir, diff);
+  if (res.note) console.log(`ℹ ${res.note}`);
+  if (res.ok) res = withSonarProof(res, { config, liveFiles, std });
+  const warnIds = gate.warns.map((w) => w.rule_id);
+  if (res.ok) res = withRagProof(res, { config, liveFiles, std, projectDir, warnIds });
+  console.log(res.ok
+    ? `✓ verdict ok — approved by ${res.verdict.reviewer} (diff ${res.verdict.diffHash.slice(0, 12)})`
+    : `✗ ${res.reason}`);
+  // GOV-C: el allow del chokepoint de COMMIT es evidencia — se sella. PL-E
+  // (KJC-TSK-0767): con las reglas que AVISARON, para que "nace avisando y
+  // gana dientes" se decida con datos (kj policy report), no a ciegas.
+  if (res.ok) seal("allow", warnIds.length > 0 ? { warn_rule_ids: warnIds } : {});
+  process.exitCode = res.ok ? 0 : 1;
+  return res;
+}
 
-  // KJC-TSK-0838: fail-CLOSED for code. Sonar disabled, down, skipped by
-  // flag, or blind to a staged source — the diff does not reach the reviewer.
-  // Docs-only diffs pass; a live human grant on the rule is the only escape.
-  const sonarReq = checkSonarRequirement({ config, stagedFiles: liveFiles, sonar: sonarRecord, standingExceptions: std.standing });
-  if (!sonarReq.ok) {
-    console.log(`✗ ${sonarReq.reason}`);
-    process.exitCode = 1;
-    return { verdict: "rejected", reviewer: "sonar", issues: [{ severity: "high", file: undefined, description: sonarReq.reason }] };
+const DEFAULT_REVIEW_TASK = "Review the following diff for correctness, security and maintainability.";
+/** Appends a gate's finding for the reviewer to the task (the default task when there is none). */
+const withNote = (task, note) => (note ? `${task || DEFAULT_REVIEW_TASK}\n\n${note}` : task);
+const listed = (items) => `${items.slice(0, 5).join(", ")}${items.length > 5 ? "…" : ""}`;
+
+/**
+ * KJC-TSK-0676: deterministic pre-gate — sonar findings on the changed
+ * files come back BEFORE any AI opinion. Blocking severities reject
+ * without spending reviewer tokens; the rest travel with the task so
+ * the cross-AI reviewer weighs them. Unavailable sonar degrades loudly.
+ * KJC-TSK-0838: what sonar saw travels INSIDE the verdict (`record`), bound to the
+ * diff hash — a reviewed diff and a reviewed AND analysed diff must be
+ * distinguishable by --check and by the method report.
+ */
+async function sonarPregate({ config, logger, range, liveFiles, enabled }) {
+  if (!enabled) return { record: { ran: false, reason: "--no-sonar: the pre-gate was skipped by flag" } };
+  // KJC-TSK-0795 AC3: only issues on lines this diff ADDS may veto.
+  const touchedLines = addedLinesByFile(await rawDiff(range, ["--unified=0"]));
+  const pre = await runSonarPregate({ config, stagedFiles: liveFiles, touchedLines, logger });
+  if (!pre.available) {
+    // KJC-BUG-0156 (issue #1543): a scan that FAILED must not read like one
+    // more config warning — it hid a dead quality gate for 8 straight PRs.
+    // Still fail-open (a laptop without Docker still commits), but SAID.
+    const chosen = /disabled in config/.test(pre.reason || "");
+    console.log(chosen
+      ? `⚠ sonar pre-gate skipped: ${pre.reason}`
+      : `✗ sonar pre-gate UNAVAILABLE — the quality gate did NOT run on this diff: ${pre.reason}`);
+    return { record: { ran: false, reason: pre.reason } };
   }
-  if (sonarReq.mode === "granted") console.log(formatSonarGrant(sonarReq.grant));
-  // The verdict says on what grounds the requirement was met (proof, docs-only,
-  // human grant) — the method report reads it back.
-  sonarRecord.mode = sonarReq.mode;
-
-  // KJC-TSK-0849 (ADR 0010, RAG-C): the session's RAG ledger must show the
-  // RAG answered about every staged source (file or sibling), and the TWINS
-  // it returned that the diff does not touch travel to the reviewer by name —
-  // the 16-sep bugs were exactly the twin nobody touched.
-  const ledger = readRagLedger(projectDir);
-  const newFiles = (await rawDiff(flags.range, ["--name-only", "--diff-filter=A"])).split("\n").map((f) => f.trim()).filter(Boolean);
-  const ragReq = checkRagRequirement({ config, stagedFiles: liveFiles, newFiles, ledger, standingExceptions: std.standing });
-  if (!ragReq.ok) {
-    console.log(`✗ ${ragReq.reason}`);
-    process.exitCode = 1;
-    return { verdict: "rejected", reviewer: "rag-first", issues: [{ severity: "high", file: undefined, description: ragReq.reason }] };
+  const record = {
+    ran: true, projectKey: pre.projectKey, covered: pre.covered ?? [], uncovered: pre.uncovered ?? [],
+    blocking: pre.blocking.length, advisory: pre.advisory.length,
+  };
+  printSonarPregate(pre, record);
+  if (pre.blocking.length > 0) {
+    console.log("✗ REJECTED by sonar (deterministic) — fix the blocking findings; the cross-AI reviewer was not invoked.");
+    return { record, rejection: rejected("sonar", pre.blocking.map((i) => ({ severity: i.severity, file: undefined, description: formatSonarFinding(i) }))) };
+  }
+  const findings = pre.advisory.map((f) => `- ${formatSonarFinding(f)}`).join("\n");
+  const note = pre.advisory.length > 0 ? `Deterministic Sonar findings on these files (fold them into your review):\n${findings}` : null;
+  return { record, note };
+}
+
+function printSonarPregate(pre, record) {
+  if (record.uncovered.length > 0) {
+    console.log(`⚠ sonar coverage: ${record.uncovered.length} staged source(s) were NOT in the analysis (${listed(record.uncovered)}) — the scan did not see them`);
+  }
+  const found = [...pre.blocking, ...pre.advisory];
+  if (found.length > 0) {
+    console.log(`Sonar on the changed lines — ${pre.blocking.length} blocking, ${pre.advisory.length} advisory (project total: ${pre.totalProject}):`);
+    for (const f of found) console.log(`  - ${formatSonarFinding(f)}`);
   }
-  if (ragReq.mode === "granted") console.log(formatRagGrant(ragReq.grant));
-  if (ragReq.mode === "no-harness") console.log("⚠ rag: no Sentinel harness in this tree — no session ledger to check (kj harden installs it)");
-  const ragRecord = ragBlock(ragReq, ledger);
-  if (ragRecord.twinsUntouched.length > 0) {
-    const twins = ragRecord.twinsUntouched;
-    console.log(`ℹ rag twins: this session's queries also returned ${twins.length} file(s) the diff does not touch — ${twins.slice(0, 5).join(", ")}${twins.length > 5 ? "…" : ""}`);
-    task = `${task || "Review the following diff for correctness, security and maintainability."}\n\n`
-      + "The session's RAG queries also returned these files, which the diff does NOT touch — the same concept may live there, so check the change is complete, not only correct:\n"
-      + twins.map((t) => `- ${t}`).join("\n");
+  if ((pre.preexisting || []).length > 0) {
+    console.log(`⚠ sonar trend: ${pre.preexisting.length} preexisting issue(s) on untouched lines of these files — not this PR's veto, but the debt is real`);
+  }
+}
+
+/**
+ * KJC-TSK-0838: fail-CLOSED for code. Sonar disabled, down, skipped by
+ * flag, or blind to a staged source — the diff does not reach the reviewer.
+ * Docs-only diffs pass; a live human grant on the rule is the only escape.
+ * The verdict says on what grounds the requirement was met (proof, docs-only,
+ * human grant): `record.mode`, read back by the method report.
+ */
+function sonarRequirementGate({ config, liveFiles, std, record }) {
+  const req = checkSonarRequirement({ config, stagedFiles: liveFiles, sonar: record, standingExceptions: std.standing });
+  if (!req.ok) {
+    console.log(`✗ ${req.reason}`);
+    return rejected("sonar", [{ severity: "high", file: undefined, description: req.reason }]);
   }
+  if (req.mode === "granted") console.log(formatSonarGrant(req.grant));
+  record.mode = req.mode;
+  return null;
+}
 
-  // BOOT-D (KJC-TSK-0863): green is not proof for what a person SEES. kj does
-  // not drive the browser (the host has it); it demands the walkthrough and
-  // records it in the verdict, bound to the diff like sonar and rag. It WARNS:
-  // the last proof, never the only one, and a gate that fires often teaches
-  // people to skip gates.
+/**
+ * KJC-TSK-0849 (ADR 0010, RAG-C): the session's RAG ledger must show the
+ * RAG answered about every staged source (file or sibling), and the TWINS
+ * it returned that the diff does not touch travel to the reviewer by name —
+ * the 16-sep bugs were exactly the twin nobody touched.
+ */
+async function ragGate({ config, projectDir, range, liveFiles, std }) {
+  const ledger = readRagLedger(projectDir);
+  const newFiles = (await rawDiff(range, ["--name-only", "--diff-filter=A"])).split("\n").map((f) => f.trim()).filter(Boolean);
+  const req = checkRagRequirement({ config, stagedFiles: liveFiles, newFiles, ledger, standingExceptions: std.standing });
+  if (!req.ok) {
+    console.log(`✗ ${req.reason}`);
+    return { rejection: rejected("rag-first", [{ severity: "high", file: undefined, description: req.reason }]) };
+  }
+  if (req.mode === "granted") console.log(formatRagGrant(req.grant));
+  if (req.mode === "no-harness") console.log("⚠ rag: no Sentinel harness in this tree — no session ledger to check (kj harden installs it)");
+  const record = ragBlock(req, ledger);
+  const twins = record.twinsUntouched;
+  if (twins.length === 0) return { record };
+  console.log(`ℹ rag twins: this session's queries also returned ${twins.length} file(s) the diff does not touch — ${listed(twins)}`);
+  const note = "The session's RAG queries also returned these files, which the diff does NOT touch — the same concept may live there, so check the change is complete, not only correct:\n"
+    + twins.map((t) => `- ${t}`).join("\n");
+  return { record, note };
+}
+
+/**
+ * BOOT-D (KJC-TSK-0863): green is not proof for what a person SEES. kj does
+ * not drive the browser (the host has it); it demands the walkthrough and
+ * records it in the verdict, bound to the diff like sonar and rag. It WARNS:
+ * the last proof, never the only one, and a gate that fires often teaches
+ * people to skip gates.
+ */
+function uiEvidence({ changedFiles, flags, std }) {
   const walked = Array.isArray(flags.walked) ? flags.walked : [];
   const uiReq = checkUiEvidence({
     stagedFiles: changedFiles,
@@ -567,51 +580,118 @@ export async function reviewGateCommand({ config, logger = null, flags = {} }) {
     standingExceptions: std.standing,
   });
   if (uiReq.warn) console.log(`⚠ ${uiReq.reason}`);
-  const uiRecord = uiBlock(uiReq);
+  return uiBlock(uiReq);
+}
 
-  // MUT-A (KJC-TSK-0716): mutation pre-gate — opt-in (method_gates.mutation),
-  // SOLO en --staged (jamás en pre-commit: cuesta minutos; y jamás en --range:
-  // el scope es el ÍNDICE y anotaría trabajo ajeno — catch de codex). block
-  // cierra ANTES de gastar reviewer; warn viaja como advisory en su task.
+/**
+ * MUT-A (KJC-TSK-0716): mutation pre-gate — opt-in (method_gates.mutation),
+ * SOLO en --staged (jamás en pre-commit: cuesta minutos; y jamás en --range:
+ * el scope es el ÍNDICE y anotaría trabajo ajeno — catch de codex). block
+ * cierra ANTES de gastar reviewer; warn viaja como advisory en su task.
+ */
+async function mutationGate({ config, projectDir, flags }) {
   const mut = flags.staged && !flags.range ? await runMutationPregate({ config, projectDir }) : { enabled: false, ok: true };
-  if (mut.enabled) {
-    if (mut.available === false) {
-      console.log(`⚠ mutation pre-gate no disponible: ${mut.reason} — degradado avisando (method_gates.mutation)`);
-    } else if (mut.survived.length > 0) {
-      console.log(`Mutantes supervivientes en el diff — score ${mut.score ?? "n/a"}%:`);
-      for (const m of mut.survived) console.log(`  ✗ ${formatSurvivor(m)}`);
-      if (!mut.ok) {
-        console.log("✗ mutation gate: la suite verde no PRUEBA el cambio — mata los supervivientes antes del review (method_gates.mutation: block).");
-        process.exitCode = 1;
-        return { verdict: "rejected", reviewer: "mutation", issues: mut.survived.map((m) => ({ severity: "high", file: m.file, description: formatSurvivor(m) })) };
-      }
-      task = `${task || "Review the following diff for correctness, security and maintainability."}\n\n`
-        + `Surviving mutants on the changed lines (weak asserts — fold into your review):\n`
-        + mut.survived.map((m) => `- ${formatSurvivor(m)}`).join("\n");
-    }
+  if (!mut.enabled) return {};
+  if (mut.available === false) {
+    console.log(`⚠ mutation pre-gate no disponible: ${mut.reason} — degradado avisando (method_gates.mutation)`);
+    return {};
   }
-
-  // KJC-TSK-1052 (TEAM-F): another branch in progress touching the same files is said, never blocks.
-  if (flags.staged && !flags.range) {
-    for (const line of formatOverlaps(await branchOverlaps({ projectDir, stagedFiles: changedFiles, base: config?.base_branch || "main" }))) console.log(line);
+  if (mut.survived.length === 0) return {};
+  console.log(`Mutantes supervivientes en el diff — score ${mut.score ?? "n/a"}%:`);
+  for (const m of mut.survived) console.log(`  ✗ ${formatSurvivor(m)}`);
+  if (!mut.ok) {
+    console.log("✗ mutation gate: la suite verde no PRUEBA el cambio — mata los supervivientes antes del review (method_gates.mutation: block).");
+    return { rejection: rejected("mutation", mut.survived.map((m) => ({ severity: "high", file: m.file, description: formatSurvivor(m) }))) };
   }
+  const survivors = mut.survived.map((m) => `- ${formatSurvivor(m)}`).join("\n");
+  return { note: `Surviving mutants on the changed lines (weak asserts — fold into your review):\n${survivors}` };
+}
 
-  // KJC-TSK-0722: a dependency published under the cooldown is said, and weighed by the reviewer.
+/**
+ * KJC-TSK-0722: a dependency published under the cooldown is said, and weighed by the reviewer.
+ * KJC-TSK-1056: method_gates.dep_cooldown: block stops it here, before any reviewer token.
+ */
+async function cooldownStep({ diff, config, std }) {
   const cooldownHours = config?.supply_chain?.cooldown_hours ?? DEFAULT_COOLDOWN_HOURS;
   const cooldownResult = await cooldownAdvisories(diff, { thresholdHours: cooldownHours });
   const cooldown = formatCooldown(cooldownResult, cooldownHours);
   for (const line of cooldown.lines) console.log(line);
-  // KJC-TSK-1056: method_gates.dep_cooldown: block stops it here, before any reviewer token.
-  const cooldownStop = cooldownGate({ result: cooldownResult, mode: config?.method_gates?.dep_cooldown, standingExceptions: std.standing });
-  if (cooldownStop.grant) console.log(`⚠ dep_cooldown lifted by a HUMAN grant [method.dep_cooldown] until ${cooldownStop.grant.expiresAt}`);
-  if (cooldownStop.block) {
-    console.log(`✗ ${cooldownStop.reason}`);
+  const stop = cooldownGate({ result: cooldownResult, mode: config?.method_gates?.dep_cooldown, standingExceptions: std.standing });
+  if (stop.grant) console.log(`⚠ dep_cooldown lifted by a HUMAN grant [method.dep_cooldown] until ${stop.grant.expiresAt}`);
+  if (stop.block) {
+    console.log(`✗ ${stop.reason}`);
+    return { rejection: rejected("dep-cooldown", cooldownResult.young.map((p) => ({ severity: "high", description: `${p.name}@${p.version} published ${p.hours} h ago` }))) };
+  }
+  return { note: cooldown.note || null };
+}
+
+export async function reviewGateCommand({ config, logger = null, flags = {} }) {
+  const projectDir = config?.projectDir || process.cwd();
+  if (flags.installGate) return installGateAction(projectDir);
+  if (flags.prune) return pruneAction(projectDir, flags);
+
+  const diff = await rawDiff(flags.range);
+
+  const card = await enforceCardFirst({ config, projectDir });
+  if (!card.ok) return { verdict: "rejected", reviewer: "card-first", issues: [{ severity: "high", description: card.reason }] };
+
+  // KJC-TSK-1086: the Steward's block at commit too, not only where Edit starts work.
+  const steward = stewardBlocking({ projectDir, config });
+  if (steward) {
+    console.log(`✗ ${steward.reason}`);
     process.exitCode = 1;
-    return { verdict: "rejected", reviewer: "dep-cooldown", issues: cooldownResult.young.map((p) => ({ severity: "high", description: `${p.name}@${p.version} published ${p.hours} h ago` })) };
+    return { verdict: "rejected", reviewer: "steward", issues: [{ severity: "high", description: steward.reason }] };
+  }
+
+  // KJC-TSK-0687 (MG-B): the verifiable half of TDD — sources without a
+  // single test change warn (block via method_gates.tests_with_code).
+  const changedFiles = (await rawDiff(flags.range, ["--name-only"])).split("\n").map((f) => f.trim()).filter(Boolean);
+  // KJC-BUG-0229: un fichero BORRADO no es una fuente que el scan pueda indexar
+  // ni sobre la que el RAG pueda responder, asi que exigirlo era pedir lo
+  // imposible: una PR que retiraba 45 ficheros se paro dos veces y acumulo tres
+  // excepciones por la misma causa mecanica. Los requisitos de Sonar y de RAG
+  // se evaluan sobre lo que sigue VIVO tras el cambio (A, C, M, R); policy, LOC
+  // y tests-with-code siguen viendo el diff entero, porque ahi un borrado si
+  // cuenta. El borrado danino lo cubre la review cruzada, que lee todo el diff.
+  const liveFiles = (await rawDiff(flags.range, ["--name-only", "--diff-filter=ACMR"])).split("\n").map((f) => f.trim()).filter(Boolean);
+
+  const pol = loadPolicy({ projectDir });
+  // KJC-TSK-1257: the pre-gates in their order; the first rejection ends the review.
+  const preRejection = await prSizeGate({ projectDir, config, range: flags.range })
+    ?? privacyGate({ diff, config })
+    ?? await testsWithCodeGate({ config, projectDir, range: flags.range, changedFiles });
+  if (preRejection) return preRejection;
+
+  // GOV-B (KJC-TSK-0746): las permanentes concedidas (kj policy grant)
+  // eximen su regla mientras viven; el descarte de líneas corruptas se dice.
+  const std = loadStandingExceptions(projectDir);
+  if (std.discarded > 0) console.log(`⚠ policy: ${std.discarded} línea(s) corruptas descartadas en policy-exceptions.jsonl — revísalo`);
+  const { rejection: policyRejection, gate, seal } = await policyGate({ projectDir, diff, pol, changedFiles, std, range: flags.range, check: flags.check });
+  if (policyRejection) return policyRejection;
+  if (flags.check) return checkPath({ projectDir, config, diff, range: flags.range, liveFiles, std, gate, seal });
+
+  // KJC-TSK-1257: the review path's gates in their order; each may reject, and what they found
+  // that does not reject travels to the reviewer inside the task. KJC-BUG-0423 (#2665): --check
+  // does not run these, so their rejection is recorded for the diff, replacing an earlier APPROVED.
+  const recorded = (rejection) => saveVerdict(projectDir, diff, rejection).then(() => rejection);
+  const sonar = await sonarPregate({ config, logger, range: flags.range, liveFiles, enabled: flags.sonar !== false });
+  if (sonar.rejection) return recorded(sonar.rejection);
+  const sonarRejection = sonarRequirementGate({ config, liveFiles, std, record: sonar.record });
+  if (sonarRejection) return recorded(sonarRejection);
+  const rag = await ragGate({ config, projectDir, range: flags.range, liveFiles, std });
+  if (rag.rejection) return recorded(rag.rejection);
+  const uiRecord = uiEvidence({ changedFiles, flags, std });
+  const mutation = await mutationGate({ config, projectDir, flags });
+  if (mutation.rejection) return recorded(mutation.rejection);
+  // KJC-TSK-1052 (TEAM-F): another branch in progress touching the same files is said, never blocks.
+  if (flags.staged && !flags.range) {
+    for (const line of formatOverlaps(await branchOverlaps({ projectDir, stagedFiles: changedFiles, base: config?.base_branch || "main" }))) console.log(line);
   }
-  if (cooldown.note) task = `${task || "Review the following diff for correctness, security and maintainability."}\n\n${cooldown.note}`;
+  const cooldown = await cooldownStep({ diff, config, std });
+  if (cooldown.rejection) return recorded(cooldown.rejection);
+  const task = [sonar.note, rag.note, mutation.note, cooldown.note].reduce(withNote, flags.task);
 
-  const record = await runOneShotReview({ diff, task, config, logger, projectDir, sonar: sonarRecord, rag: ragRecord, ui: uiRecord });
+  const record = await runOneShotReview({ diff, task, config, logger, projectDir, sonar: sonar.record, rag: rag.record, ui: uiRecord });
   printVerdict(record, record.verdict === "approved" ? await reviewCorrectionRounds(projectDir, record) : 0);
   process.exitCode = record.verdict === "approved" ? 0 : 1;
   return record;