karajan-code 4.38.0 → 4.40.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "karajan-code",
-  "version": "4.38.0",
+  "version": "4.40.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/destructive-parser.js

@@ -35,14 +35,43 @@ function classifyMv(tokens) {
   return { destructive: true, kind: "mv-overwrite", paths: positional.slice(-1), reason: "mv may overwrite destination" };
 }
 
+// KJC-BUG-0240 (#1886): checkout and restore drop uncommitted work file by file,
+// and a bundle keeps commits only, so the named files are kept as files and a
+// discard of the whole tree marks it (worktree) for the hook to keep every dirty file.
+function classifyDiscard(tokens, sub) {
+  const args = tokens.slice(2);
+  const has = (...flags) => flags.some((f) => args.includes(f));
+  const SAFE = { destructive: false, kind: "git-safe", paths: [] };
+  if (sub === "restore" && has("--staged", "-S") && !has("--worktree", "-W")) return { ...SAFE, reason: "restore --staged only unstages" };
+  // -B resets an existing branch: its commits need the bundle.
+  if (sub === "checkout" && has("-B")) return { destructive: true, kind: "git-checkout-reset-branch", bundle: true, paths: [], reason: "git checkout -B resets an existing branch" };
+  if (sub === "checkout" && has("-b", "--orphan")) return { ...SAFE, reason: "checkout -b creates a branch" };
+  const dd = args.indexOf("--");
+  const named = [];
+  let sourceValue = false;
+  args.forEach((a, i) => {
+    if (sourceValue) sourceValue = false;
+    else if (a === "-s" || a === "--source") sourceValue = true;
+    else if ((dd >= 0 && i > dd) || !a.startsWith("-")) named.push(a);
+  });
+  if (!named.length && !has("-f", "--force")) return { ...SAFE, reason: `${sub} with nothing to discard` };
+  const whole = has("-f", "--force") || named.includes(".") || named.includes(":/");
+  return { destructive: true, kind: `git-${sub}-discard`, paths: named.filter((p) => p !== "." && p !== ":/"), ...(whole ? { worktree: "tracked" } : {}), reason: `git ${sub} discards local edits` };
+}
+
 function classifyGit(tokens) {
   const sub = tokens[1];
   const has = (...flags) => flags.some((f) => tokens.includes(f));
-  if (sub === "reset" && has("--hard")) return { destructive: true, kind: "git-reset-hard", paths: [], reason: "git reset --hard drops working tree" };
-  if (sub === "clean" && has("-f", "-fd", "-xdf")) return { destructive: true, kind: "git-clean", paths: [], reason: "git clean -f removes untracked files" };
-  if (sub === "branch" && has("-D")) return { destructive: true, kind: "git-branch-D", paths: [], reason: "git branch -D drops unmerged branch" };
-  if (sub === "push" && has("--force", "-f", "--force-with-lease")) return { destructive: true, kind: "git-push-force", paths: [], reason: "git push --force rewrites remote history" };
-  if (sub === "checkout" && has("--", ".")) return { destructive: true, kind: "git-checkout-discard", paths: [], reason: "git checkout -- discards local edits" };
+  if (sub === "reset" && has("--hard")) return { destructive: true, kind: "git-reset-hard", bundle: true, worktree: "tracked", paths: [], reason: "git reset --hard drops working tree" };
+  if (sub === "clean" && tokens.some((t) => t === "--force" || /^-[a-zA-Z]*f/.test(t))) {
+    // -x / -X also remove ignored files.
+    const ignored = tokens.some((t) => /^-[a-zA-Z]*[xX]/.test(t));
+    return { destructive: true, kind: "git-clean", bundle: true, worktree: ignored ? "untracked+ignored" : "untracked", paths: [], reason: "git clean -f removes untracked files" };
+  }
+  if (sub === "branch" && has("-D")) return { destructive: true, kind: "git-branch-D", bundle: true, paths: [], reason: "git branch -D drops unmerged branch" };
+  if (sub === "push" && has("--force", "-f", "--force-with-lease")) return { destructive: true, kind: "git-push-force", bundle: true, paths: [], reason: "git push --force rewrites remote history" };
+  if (sub === "checkout" || sub === "restore") return classifyDiscard(tokens, sub);
+  if (sub === "switch" && has("-f", "--force", "--discard-changes")) return { destructive: true, kind: "git-switch-discard", worktree: "tracked", paths: [], reason: "git switch --discard-changes drops local edits" };
   return { destructive: false, kind: "git-safe", paths: [], reason: "git op without destructive flags" };
 }
 

package/packages/ai-trash/src/hook.js

@@ -4,6 +4,7 @@
 // throws, deny the op so Claude never destroys without a recovery copy.
 
 import { promises as fs } from "node:fs";
+import { spawnSync } from "node:child_process";
 import { isAbsolute, resolve } from "node:path";
 import process from "node:process";
 import { classifyCommand } from "./destructive-parser.js";
@@ -47,6 +48,29 @@ async function snapshotExistingPaths(root, paths, cwd, command) {
   return snapshots;
 }
 
+// KJC-BUG-0240 (#1886): the dirty files a whole-tree discard would drop, kept as
+// files (a bundle keeps commits only). `which`: "tracked" changes, "untracked"
+// files, or "untracked+ignored" (git clean -x/-X removes ignored files too).
+async function snapshotDirtyFiles(root, cwd, command, which) {
+  if (!cwd) return [];
+  const top = spawnSync("git", ["-C", cwd, "rev-parse", "--show-toplevel"], { encoding: "utf8" });
+  if (top.status !== 0) return [];
+  const withIgnored = which === "untracked+ignored";
+  // traditional + all: every file inside an ignored directory is listed one by one.
+  const st = spawnSync("git", ["-C", cwd, "status", "--porcelain", "-z", "--untracked-files=all", ...(withIgnored ? ["--ignored=traditional"] : [])], { encoding: "utf8" });
+  if (st.status !== 0) throw new Error(`git status failed: ${st.stderr.trim()}`);
+  const wanted = (rec) => (which === "tracked" ? !rec.startsWith("??") && !rec.startsWith("!!") : rec.startsWith("??") || (withIgnored && rec.startsWith("!!")));
+  const files = [];
+  let renameSource = false; // a rename or copy record is followed by its source path
+  for (const rec of st.stdout.split("\0")) {
+    if (renameSource) { renameSource = false; continue; }
+    if (rec.length < 4) continue;
+    if (wanted(rec)) files.push(rec.slice(3));
+    renameSource = "RC".includes(rec[0]);
+  }
+  return snapshotExistingPaths(root, files, top.stdout.trim(), command);
+}
+
 async function snapshotGitRepo(root, cwd, command, kind) {
   if (!cwd) return { snapshots: [], skipped: "no cwd" };
   try {
@@ -86,11 +110,9 @@ export async function handleHookPayload(payload, { root, stdin }) {
     await assertOwnedByCurrentUser(root);
     let snapshots = [];
     let skipped = null;
-    if (verdict.kind.startsWith("git-")) {
-      ({ snapshots, skipped } = await snapshotGitRepo(root, data.cwd, command, verdict.kind));
-    } else {
-      snapshots = await snapshotExistingPaths(root, verdict.paths, data.cwd, command);
-    }
+    if (verdict.bundle) ({ snapshots, skipped } = await snapshotGitRepo(root, data.cwd, command, verdict.kind));
+    snapshots.push(...(await snapshotExistingPaths(root, verdict.paths, data.cwd, command)));
+    if (verdict.worktree) snapshots.push(...(await snapshotDirtyFiles(root, data.cwd, command, verdict.worktree)));
     if (snapshots.length) {
       const m = await loadManifest(root);
       for (const s of snapshots) m.entries.push(s);
@@ -106,7 +128,7 @@ export async function handleHookPayload(payload, { root, stdin }) {
     if (snapshots.length) {
       return reply(
         "allow",
-        `ai-trash: snapshotted ${snapshots.length} ${verdict.kind.startsWith("git-") ? "git bundle" : "path(s)"} before ${verdict.kind}`
+        `ai-trash: snapshotted ${snapshots.length} ${snapshots.some((s) => s.type === "git-bundle") ? "item(s), git bundle included," : "path(s)"} before ${verdict.kind}`
       );
     }
     return reply(

package/src/audit/ai-slop-findings.js

@@ -8,9 +8,11 @@ import path from "node:path";
 
 const FILE_EXTS = new Set([".js", ".mjs", ".cjs", ".ts", ".tsx", ".jsx"]);
 const IGNORE_DIRS = new Set([
-  "node_modules", "dist", "build", "coverage",
+  "node_modules", "dist", "build", "coverage", "vendor",
   ".git", ".karajan", "public", ".next", ".nuxt", ".vercel", ".cache",
 ]);
+// KJC-BUG-0254 (#1902): a minified bundle is third-party output, not the project's prose.
+const isMinified = (name) => /\.min\.[cm]?js$/.test(name);
 const VERB = "(?:returns?|gets?|sets?|fetches?|loads?|saves?|creates?|builds?|makes?|computes?|handles?|checks?|validates?)";
 const LINE_PATTERNS = {
   "banner-separators": /\/[/*]\s*[=*\-_#~]{5,}/,
@@ -70,7 +72,7 @@ function listSourceFiles(root) {
       if (e.isDirectory()) {
         if (IGNORE_DIRS.has(e.name) || e.name.startsWith(".")) continue;
         stack.push(full);
-      } else if (FILE_EXTS.has(path.extname(e.name))) out.push(full);
+      } else if (FILE_EXTS.has(path.extname(e.name)) && !isMinified(e.name)) out.push(full);
     }
   }
   return out;

package/src/audit/circular-deps.js

@@ -44,11 +44,12 @@ async function findTsConfig(projectDir) {
   return undefined;
 }
 
-function pickEntrypoint(projectDir) {
-  // madge needs an entrypoint. We prefer common conventions; if none
-  // exists we fall back to scanning `src/` which covers ~95% of JS/TS
-  // projects we've seen.
-  return path.join(projectDir, "src");
+async function pickEntrypoint(projectDir) {
+  // madge needs an entrypoint: `src/` covers most JS/TS projects. KJC-BUG-0267:
+  // a project with no src/ (a static site with its scripts in js/ or at the
+  // root) is scanned whole; excludeRegExp keeps node_modules and build output out.
+  const src = path.join(projectDir, "src");
+  try { await fs.access(src); return src; } catch { return projectDir; }
 }
 
 /**
@@ -65,9 +66,9 @@ export async function collectCircularDeps(projectDir, stack, config = {}, logger
     return { available: false, reason: "no JS/TS sources detected — circular-dep scan skipped" };
   }
 
-  const entry = pickEntrypoint(projectDir);
+  const entry = await pickEntrypoint(projectDir);
   try { await fs.access(entry); } catch {
-    return { available: false, reason: `entrypoint ${path.relative(projectDir, entry)} not found` };
+    return { available: false, reason: `project directory ${entry} not found` };
   }
 
   let madge;

package/src/audit/webperf-input.js

@@ -93,7 +93,9 @@ export function collectWebPerfInput(stack, config = {}) {
   // a frontend layer to audit. Backend-only projects get nothing.
   const isFrontendish = !stack || stack.isFrontend === true || stack.isFullstack === true;
   if (!isFrontendish) {
-    return { available: false, reason: "project is backend-only — no frontend-perf hints to give" };
+    // KJC-BUG-0267: no tier detected is not "backend-only"; say what was (not) seen.
+    const why = stack.isBackend ? "project is backend-only" : "no frontend layer detected (no frontend framework and no index.html)";
+    return { available: false, reason: `${why} — no frontend-perf hints to give` };
   }
 
   return { available: true, mode: "static-hints" };

package/src/checks/method.js

@@ -36,7 +36,7 @@ export async function collectMethodStats({ projectDir, run = runCommand, sample
   const blocks = blocksRes.exitCode === 0
     ? blocksRes.stdout.split(/^@.*$/m).map((b) => b.split("\n").map((l) => l.trim()).filter(Boolean)).filter((b) => b.length > 0)
     : [];
-  const offenders = blocks.filter((files) => checkTestsWithCode({ config: {}, stagedFiles: files, env: {} }).mode !== "pass").length;
+  const offenders = blocks.filter((files) => checkTestsWithCode({ config: {}, stagedFiles: files }).mode !== "pass").length;
 
   const verdicts = recentVerdicts(projectDir, sample);
   const stamped = verdicts.filter((v) => v.workspace);

package/src/checks/release-check.js

@@ -34,7 +34,9 @@ async function policyRangeCheck(projectDir) {
     // protects the supervisor. `kj review` and `kj policy check` already lift
     // what the sealed provenance backs; without this the release check blocked
     // every version cut after a human `kj harden --commit`, by its own seal.
-    const sup = liftSealedSupervisorViolations({ projectDir, violations: raw });
+    // KJC-BUG-0259: the history is judged on what is versioned (hooks, provenance);
+    // the machine-local guards were verified when the seal was reviewed.
+    const sup = liftSealedSupervisorViolations({ projectDir, violations: raw, trackedOnly: true });
     const violations = sup.violations;
     const hard = violations.filter((v) => v.enforcement === "deny");
     const skipped = prScoped.size > 0 ? `; ${prScoped.size} diff-threshold invariant(s) skipped (PR-scoped)` : "";

package/src/cli/advanced-commands.js

@@ -34,7 +34,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", "policy", "claims", "steward", "pr-size"] },
+  { title: "Calidad / auditoría", commands: ["audit", "check", "mutate", "webperf", "sonar", "privacy", "release", "policy", "rules", "claims", "steward", "pr-size"] },
   { title: "Sesión / board", commands: ["resume", "report", "board", "hu", "adr", "worktree", "undo", "standby", "sentinel", "identity"] },
   { 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

@@ -43,6 +43,12 @@ import { verifySentinelScripts, resolveSentinelRoot } from "../harden/sentinel-h
 import { boardGate } from "../review/board-pending.js";
 import { panelDeviation } from "../environment/panel.js";
 import { detectHostAgent } from "../utils/agent-detect.js";
+import { listRules } from "../rules/inventory.js";
+import { PROPOSAL_FILE, readToolInput, rulesCheck, rulesCoverage, rulesEval, rulesTest } from "../commands/rules.js";
+import { rulesApprove } from "../commands/rules-approve.js";
+import { rulesDecide } from "../commands/rules-decide.js";
+import { rulesReview } from "../commands/rules-review.js";
+import { rulesCompileBrief } from "../commands/rules-compile.js";
 
 /**
  * Register the "meta" / single-role / housekeeping commands: pre-pipeline
@@ -296,7 +302,7 @@ export function registerMeta(program, { pkgVersion }) {
     .action(async (title, flags) => {
       await withConfig(pkgVersion, "adr", flags, async ({ config }) => {
         const res = await addAdr(config?.projectDir || process.cwd(), { title, ...flags });
-        console.log(flags.json ? JSON.stringify(res) : `✓ ADR ${res.number} created: ${res.file} — commit it`);
+        console.log(flags.json ? JSON.stringify(res) : `✓ ADR ${res.number} created as ${res.status}: ${res.file} — commit it and ask your user; accepting it is theirs (Status: accepted)`);
       });
     });
   adr.command("list")
@@ -310,6 +316,111 @@ export function registerMeta(program, { pkgVersion }) {
       });
     });
 
+  // MDR-A2 (KJC-TSK-0942, ADR 0016): the rules of the governing MD files, each with an id.
+  const rules = program.command("rules").description("Rules written in the MD files that govern a session (ADR 0016)");
+  rules.command("list")
+    .option("--json", "Machine-readable output")
+    .action(async (flags) => {
+      await withConfig(pkgVersion, "rules", flags, async ({ config }) => {
+        const found = listRules(config?.projectDir || process.cwd());
+        if (flags.json) { console.log(JSON.stringify(found)); return; }
+        for (const r of found) console.log(`${r.id}  ${r.file}:${r.line}  ${r.text}`);
+        console.log(`${found.length} rule(s)`);
+      });
+    });
+  // MDR-B2 (KJC-TSK-0943): the compiled rules (.karajan/rules.yml) against one tool call.
+  rules.command("eval")
+    .description("Evaluate ONE tool call against .karajan/rules.yml: prints the verdict as JSON; exit 2 on deny, 1 if it cannot be evaluated")
+    .option("--tool <tool>", "Tool name (Bash, Edit, mcp__server__tool…)")
+    .option("--input <json>", "tool_input as JSON, or - to read it from stdin", "{}")
+    .action(async (flags) => {
+      await withConfig(pkgVersion, "rules-eval", flags, async ({ config }) => {
+        const res = rulesEval({ projectDir: config?.projectDir || process.cwd(), tool: flags.tool, input: await readToolInput(flags.input) });
+        console.log(JSON.stringify(res.output));
+        process.exitCode = res.code;
+      });
+    });
+  // MDR-B3 (KJC-TSK-0945): a compiled rule proves its compilation with its own examples.
+  rules.command("test")
+    .description("Run every compiled rule's deny/allow examples against the rule itself; exit 1 on any failure")
+    .action(async (flags) => {
+      await withConfig(pkgVersion, "rules-test", flags, async ({ config }) => {
+        const res = rulesTest({ projectDir: config?.projectDir || process.cwd() });
+        for (const line of res.lines) console.log(line);
+        process.exitCode = res.code;
+      });
+    });
+  // MDR-D1 (KJC-TSK-0950): a proposal proves itself before a human reads it.
+  rules.command("check")
+    .description("Check a proposal of compiled rules: every rule is one of the MD files, cites its literal text and passes its own examples; exit 1 otherwise")
+    .option("--file <path>", "The proposal", PROPOSAL_FILE)
+    .action(async (flags) => {
+      await withConfig(pkgVersion, "rules-check", flags, async ({ config }) => {
+        const res = rulesCheck({ projectDir: config?.projectDir || process.cwd(), file: flags.file });
+        for (const line of res.lines) console.log(line);
+        process.exitCode = res.code;
+      });
+    });
+  // MDR-D (KJC-TSK-0940): the brief for whoever compiles the rules with no gate.
+  rules.command("compile")
+    .description("Print the brief to compile the rules with no gate into a proposal (.karajan/rules.proposed.yml); kj calls no model")
+    .action(async (flags) => {
+      await withConfig(pkgVersion, "rules-compile", flags, async ({ config }) => {
+        const res = rulesCompileBrief({ projectDir: config?.projectDir || process.cwd() });
+        for (const line of res.lines) console.log(line);
+        process.exitCode = res.code;
+      });
+    });
+  // MDR-G (KJC-TSK-0969): most rules take no condition; their kind is decided in one go.
+  rules.command("decide <ids...>")
+    .description("Give several rules of the proposal their kind at once: judgment (with --tool) or out-of-scope (with --reason). Deterministic rules are written by hand")
+    .requiredOption("--kind <kind>", "judgment | out-of-scope")
+    .option("--tool <glob...>", "judgment: the tool(s) the rule shows on (Bash, Edit, mcp__server__tool…)")
+    .option("--reason <text>", "out-of-scope: why no tool call breaks the rule")
+    .option("--file <path>", "The proposal", PROPOSAL_FILE)
+    .action(async (ids, flags) => {
+      await withConfig(pkgVersion, "rules-decide", flags, async ({ config }) => {
+        const res = rulesDecide({ projectDir: config?.projectDir || process.cwd(), file: flags.file, ids, kind: flags.kind, tools: flags.tool, reason: flags.reason });
+        for (const line of res.lines) console.log(line);
+        process.exitCode = res.code;
+      });
+    });
+  // MDR-F4 (KJC-TSK-0963): whoever proposes the compilation does not call it good.
+  rules.command("review")
+    .description("A DIFFERENT AI reviews a checked proposal, rule by rule: is each compilation as strong as its text? The verdict is tied to the proposal's exact content")
+    .option("--file <path>", "The proposal", PROPOSAL_FILE)
+    .action(async (flags) => {
+      await withConfig(pkgVersion, "rules-review", flags, async ({ config, logger }) => {
+        const res = await rulesReview({ projectDir: config?.projectDir || process.cwd(), file: flags.file, config, logger });
+        for (const line of res.lines) console.log(line);
+        process.exitCode = res.code;
+      });
+    });
+  // MDR-D3 (KJC-TSK-0952): the proposal becomes rules.yml by a human act only.
+  rules.command("approve")
+    .description("HUMAN act: show a checked and cross-reviewed proposal and install it as the project's rules; no agent session runs it (ADR 0009)")
+    .option("--file <path>", "The proposal", PROPOSAL_FILE)
+    .action(async (flags) => {
+      await withConfig(pkgVersion, "rules-approve", flags, async ({ config }) => {
+        const res = await rulesApprove({ projectDir: config?.projectDir || process.cwd(), file: flags.file });
+        for (const line of res.lines) console.log(line);
+        process.exitCode = res.code;
+      });
+    });
+  // MDR-E (KJC-TSK-0941): which rules of the MD files have a gate, and which do not.
+  rules.command("coverage")
+    .description("Every rule of the MD files against .karajan/rules.yml: deterministic, judgment, out of scope, with no gate; and the stale compiled ones")
+    .option("--strict", "Exit 1 while a rule has no gate or a compiled rule is stale")
+    .option("--json", "Machine-readable output")
+    .action(async (flags) => {
+      await withConfig(pkgVersion, "rules-coverage", flags, async ({ config }) => {
+        const res = rulesCoverage({ projectDir: config?.projectDir || process.cwd(), strict: flags.strict });
+        if (flags.json && res.output) console.log(JSON.stringify(res.output));
+        else for (const line of res.lines) console.log(line);
+        process.exitCode = res.code;
+      });
+    });
+
   // AB-F (KJC-TSK-0655): self-healing — the brain files kj frictions upstream.
   program
     .command("report-issue")

package/src/cli/register-pipeline.js

@@ -201,7 +201,8 @@ export function registerPipeline(program, { pkgVersion }) {
   program
     .command("solomon")
     .description("Ask a third AI to arbitrate a rejected review verdict (brain ≠ reviewer ≠ solomon)")
-    .requiredOption("--position <text>", "Why the brain disagrees with the reviewer")
+    .option("--position <text>", "Why the brain disagrees with the reviewer")
+    .option("--position-file <path>", "Read the position from a file (no quoting to get right)")
     .option("--range <range>", "Arbitrate a git range instead of the staged diff")
     .action(async (flags) => {
       await withConfig(pkgVersion, "solomon", flags, async ({ config, logger }) => {

package/src/commands/init.js

@@ -414,7 +414,7 @@ async function runWizard(config, logger) {
  * @param {object} config
  */
 export async function writeInitConfig(configPath, config) {
-  await writeConfig(configPath, config);
+  return writeConfig(configPath, config);
 }
 
 async function handleConfigSetup({ config, configExists, interactive, configPath, logger }) {
@@ -938,7 +938,11 @@ export async function initCommand({ logger, flags = {} }) {
   // Use writeInitConfig so the deprecated `sonarqube.enabled` key —
   // which setupSonarQube still mutates as an in-memory hint — never
   // reaches the YAML file.
-  await writeInitConfig(configPath, config);
+  const written = await writeInitConfig(configPath, config);
+  // KJC-BUG-0253: said out loud, so nobody looks for the token where it was not written.
+  if (written?.strippedSecrets?.length) {
+    logger.info(`Kept ${written.strippedSecrets.join(", ")} out of ${configPath} (versioned with the repo); it lives in ~/.karajan/kj.config.yml`);
+  }
 
   // Telemetry: anonymous install event (non-blocking)
   const { readFileSync } = await import("node:fs");

package/src/commands/review-gate.js

@@ -42,7 +42,6 @@ async function enforceCardFirst({ config, projectDir }) {
   // 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}`);
     process.exitCode = 1;
@@ -139,6 +138,14 @@ function printVerdict(record) {
  */
 export async function solomonCommand({ config, logger = null, flags = {} }) {
   const projectDir = config?.projectDir || process.cwd();
+  // KJC-BUG-0260: a position is prose with blanks and slashes; from a file it
+  // needs no quoting the lane guard has to tell apart from a path.
+  const position = flags.positionFile ? readFileSync(flags.positionFile, "utf8").trim() : flags.position;
+  if (!position) {
+    console.log("✗ kj solomon: give the brain's position with --position <text> or --position-file <path>");
+    process.exitCode = 1;
+    return { ruling: "reject", reasoning: "no position given" };
+  }
   const diff = await rawDiff(flags.range);
   // KJC-TSK-0734 (PL-B): un hallazgo de policy de clase seguridad no es
   // arbitrable — solomon se niega antes de gastar un token. Y una policy
@@ -162,7 +169,7 @@ export async function solomonCommand({ config, logger = null, flags = {} }) {
     process.exitCode = 1;
     return { ruling: "reject", reasoning: "security-class policy denial — not arbitrable" };
   }
-  const res = await runSolomonArbitration({ diff, position: flags.position, config, logger, projectDir });
+  const res = await runSolomonArbitration({ diff, position, config, logger, projectDir });
   if (res.ruling === "approve") {
     console.log(`⚖ Solomon (${res.solomon}) rules for the brain — verdict recorded, the gate is open.`);
   } else {
@@ -256,10 +263,9 @@ export async function reviewGateCommand({ config, logger = null, flags = {} }) {
       // partitioning is a decision, and it must never split code from its tests.
       const split = testAdded > 0 ? ` (${added - testAdded} source + ${testAdded} accompanying tests — partition by feature, never code from its tests)` : "";
       const sizePolicy = config?.method_gates?.pr_size || "warn";
-      if (process.env.KJ_ALLOW_LARGE_PR === "1") {
-        console.log(`⚠ pr-size exempt: ${added} lines added — KJ_ALLOW_LARGE_PR=1 (explicit escape hatch)`);
-      } else if (sizePolicy === "block") {
-        const reason = `${added} lines added${split} exceeds the ${sizeWarn}-line budget (${sizeSource}; method_gates.pr_size: block) — partition the work, or get your user's explicit OK and re-run with KJ_ALLOW_LARGE_PR=1`;
+      // ADR 0015: no env escape — an exception is the user's label on the PR, judged in CI.
+      if (sizePolicy === "block") {
+        const reason = `${added} lines added${split} exceeds the ${sizeWarn}-line budget (${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 }] };
@@ -269,7 +275,7 @@ export async function reviewGateCommand({ config, logger = null, flags = {} }) {
     }
   }
   // KJC-TSK-0705 (PV-B): the outbound privacy boundary at commit time.
-  // Denylist data rejects (KJ_ALLOW_PII=1 is the named escape); generic PII
+  // 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.
@@ -288,25 +294,19 @@ export async function reviewGateCommand({ config, logger = null, flags = {} }) {
     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) {
-      if (process.env.KJ_ALLOW_PII === "1") {
-        console.log(`⚠ privacy exempt: ${blocks.length} denylist hit(s) — KJ_ALLOW_PII=1 (explicit escape hatch)`);
-      } else {
-        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 (KJ_ALLOW_PII=1 to override consciously)`;
-        console.log(`✗ privacy gate: ${reason}`);
-        process.exitCode = 1;
-        return { verdict: "rejected", reviewer: "privacy", issues: [{ severity: "high", description: reason }] };
-      }
+      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 }] };
     }
   } 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 if (process.env.KJ_ALLOW_PII === "1") {
-      console.log(`⚠ privacy gate errored (${err.message}) — KJ_ALLOW_PII=1 (explicit escape hatch)`);
     } else {
-      const reason = `privacy gate error: ${err.message} — refusing to pass the boundary unchecked (KJ_ALLOW_PII=1 to override consciously)`;
+      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 }] };
@@ -330,9 +330,8 @@ export async function reviewGateCommand({ config, logger = null, flags = {} }) {
 
   // KJC-TSK-0734 (PL-B): la policy declarativa como gate determinista, en
   // --staged Y en --check — el pre-commit hereda los dientes sin regenerar
-  // hooks. enforcement=warn avisa; deny cierra salvo excepción probatoria
-  // (KJ_ALLOW_POLICY=1 + KJ_POLICY_REASON, registrada con identidad y hash
-  // del diff); class=security cierra sin escape y sin arbitraje.
+  // hooks. enforcement=warn avisa; deny cierra sin excepción por diff (ADR
+  // 0015); class=security cierra además sin arbitraje.
   // 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.

package/src/commands/rules-approve.js

@@ -0,0 +1,59 @@
+/**
+ * kj rules approve (KJC-TSK-0952, MDR-D3, ADR 0016): a proposal of compiled rules
+ * becomes .karajan/rules.yml only by a HUMAN act, with the layers of the
+ * supervisor's seal (ADR 0009). The agent the rules will watch may propose how
+ * they are compiled; it does not decide.
+ *
+ * The proposal is read ONCE: what is checked, what is shown and what is
+ * installed are the same rules, whatever happens to the file meanwhile.
+ */
+import fs from "node:fs";
+import path from "node:path";
+
+import yaml from "js-yaml";
+
+import { confirmHuman, refuseAgentSession } from "../harden/human-act.js";
+import { checkVerdict } from "../review/verdict-store.js";
+import { approvalView } from "../rules/approval-view.js";
+import { loadRules, LOCAL_RULES_FILE, PROPOSAL_FILE, RULES_FILE, rulesCheck } from "./rules.js";
+
+const ACT = "kj rules approve";
+
+/**
+ * @param {{projectDir: string, file?: string, home?: string, env?: object, tty?: boolean,
+ *   deps?: {confirm?: Function, ancestry?: object}, log?: (line: string) => void}} opts
+ * @returns {Promise<{code: 0|1, lines: string[]}>}
+ */
+export async function rulesApprove({ projectDir, file = PROPOSAL_FILE, home, env, tty, deps = {}, log = console.log }) {
+  refuseAgentSession(ACT, { env, tty, ancestry: deps.ancestry ?? {} });
+  const proposal = path.resolve(projectDir, file);
+  let text;
+  try { text = fs.readFileSync(proposal, "utf8"); } catch { return { code: 1, lines: [`✗ no ${file}: nothing to approve`] }; }
+  const checked = rulesCheck({ projectDir, home, text });
+  if (checked.code !== 0) return { code: 1, lines: checked.lines };
+  // KJC-TSK-0963: whoever wrote the proposal does not call it good. A different
+  // AI must have approved these exact bytes; a touched proposal is reviewed again.
+  const reviewed = await checkVerdict(projectDir, text);
+  if (!reviewed.ok) {
+    const found = (reviewed.verdict?.issues ?? []).map((issue) => `  - ${issue.description ?? issue.message ?? JSON.stringify(issue)}`);
+    const why = reviewed.verdict ? "rejected by " + reviewed.verdict.reviewer : "none recorded for its exact content";
+    return { code: 1, lines: [`✗ this proposal has no approved cross-AI review (${why}): run \`kj rules review\``, ...found] };
+  }
+  log(`Reviewed by ${reviewed.verdict.reviewer}, a different AI from the one that wrote it: ${reviewed.verdict.summary || "approved"}`);
+  const { rules, local } = checked;
+  // KJC-TSK-0962: read in the order of what can hurt, weakened rules first.
+  const view = approvalView(rules, loadRules(projectDir).rules, local, { versioned: RULES_FILE, unversioned: LOCAL_RULES_FILE });
+  for (const line of view) log(line);
+  confirmHuman(ACT, deps.confirm);
+  // KJC-TSK-0961 (ADR 0017): a rule written only in the user's private MD files
+  // is not versioned. Where it goes is the inventory's word, not the proposal's.
+  const parts = [[RULES_FILE, rules.filter((rule) => !local.has(rule.id))], [LOCAL_RULES_FILE, rules.filter((rule) => local.has(rule.id))]];
+  for (const [name, part] of parts) {
+    const target = path.join(projectDir, name);
+    if (part.length) fs.writeFileSync(target, yaml.dump({ version: 1, rules: part }, { lineWidth: -1 }));
+    else fs.rmSync(target, { force: true }); // no rule left for this file: none stays behind
+  }
+  fs.rmSync(proposal, { force: true });
+  const [[, versioned], [, kept]] = parts;
+  return { code: 0, lines: [`✓ ${versioned.length} rule(s) approved into ${RULES_FILE} (commit it, it travels with the repo) and ${kept.length} into ${LOCAL_RULES_FILE} (not versioned, yours alone)`] };
+}