karajan-code 4.39.0 → 4.41.0

package/package.json

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

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

@@ -15,12 +15,12 @@
  *    first and a git that cannot run is the end of the line, not a warning.
  */
 
-import { execFileSync } from "node:child_process";
 import { existsSync } from "node:fs";
 import { join } from "node:path";
 import { ensureGitRepo } from "./init.js";
 import { initCommand } from "./init.js";
 import { envInstallCommand } from "./env.js";
+import { commitContract, contractChanges } from "../environment/contract-commit.js";
 import { runStartScript, START_SCRIPT_CONTRACT } from "../start/project-script.js";
 
 const STEP_LABEL = {
@@ -31,25 +31,6 @@ const STEP_LABEL = {
   start: "arranque del proyecto",
 };
 
-/** What kj generates and the whole team must inherit by cloning. */
-const CONTRACT_PATHS = [
-  ".gitignore",
-  ".karajan/hooks",
-  ".karajan/review-gate",
-  ".karajan/adrs",
-  ".karajan/policy.yml",
-  ".claude",
-  "CLAUDE.md",
-  "AGENTS.md",
-  "GEMINI.md",
-  // KJC-TSK-0879: in a Rulesync repo kj's rules live in .rulesync/rules/karajan.md.
-  ".rulesync",
-];
-const CONTRACT_MESSAGE = "chore(bootstrap): el contrato del método, para que quien clone lo herede";
-
-const hasCommits = (projectDir, git) => {
-  try { git(["rev-parse", "--verify", "HEAD"]); return true; } catch { return false; }
-};
 
 /**
  * @returns {Promise<{ok: boolean, pending: string|null, steps: Array<{name: string, status: "done"|"already"|"pending"}>}>}
@@ -75,6 +56,8 @@ export async function bootstrapCommand({ config = {}, logger = console, flags =
     return stop("git", "git no está disponible y las garantías de Karajan viven en sus hooks");
   }
   say("git", hadRepo ? "already" : "done", hadRepo ? "ya existía" : "creado, sin commit todavía");
+  // What is dirty NOW is the person's: kj commits only what it generates below.
+  const before = contractChanges(projectDir);
 
   // 2. The project's own configuration.
   const hasConfig = existsSync(join(projectDir, ".karajan", "kj.config.yml"));
@@ -98,27 +81,15 @@ export async function bootstrapCommand({ config = {}, logger = console, flags =
   // 4. The contract commit. project-new.md asked the USER for it, and it was
   //    the commit their own freshly installed gates rejected: the review gate
   //    (KJC-BUG-0165) and the branch guard (KJC-BUG-0186) both exempt it now,
-  //    so kj can make it itself instead of leaving the person to fight it.
-  //    Only what kj generated, only while the repo has no commit, never the
-  //    person's own code. This is NOT the supervisor seal, which stays a human
-  //    act with its own four layers (ADR 0009).
-  const git = deps.gitRun ?? ((args) => execFileSync("git", args, { cwd: projectDir, encoding: "utf8" }));
-  if (hasCommits(projectDir, git)) say("contract", "already", "el repositorio ya tiene historia");
-  else {
-    const present = CONTRACT_PATHS.filter((p) => existsSync(join(projectDir, p)));
-    if (present.length === 0) say("contract", "already", "no hay contrato que commitear");
-    else {
-      try {
-        git(["add", "--", ...present]);
-        git(["commit", "-m", CONTRACT_MESSAGE]);
-      } catch (err) {
-        // Nunca explotar aquí: lo más probable es que falte la identidad del
-        // clon, y ese cauce ya lo pide el paso anterior (KJC-BUG-0188).
-        return stop("contract", `git no pudo commitear el contrato: ${String(err.message).split("\n")[0]}`);
-      }
-      say("contract", "done", `${present.length} ruta(s) del contrato`);
-    }
-  }
+  //    so kj makes it itself (src/environment/contract-commit.js). Only what
+  //    kj generated, never the person's own code, never on the base branch
+  //    once there is history (KJC-BUG-0273). This is NOT the supervisor seal,
+  //    which stays a human act with its own four layers (ADR 0009).
+  const contract = commitContract({ projectDir, before, baseBranch: config.base_branch || "main" });
+  if (contract.committed) say("contract", "done", `${contract.files.length} ruta(s) del contrato`);
+  else if (contract.reason.startsWith("nothing")) say("contract", "already", "no hay contrato que commitear");
+  // Lo más probable: la identidad del clon (KJC-BUG-0188) o la rama base.
+  else return stop("contract", contract.reason);
 
   // 5. Does the project actually run? kj verified the method; nobody verified
   //    the application (BOOT-C, KJC-TSK-0862). It REPORTS, never blocks: a

package/src/commands/env.js

@@ -21,6 +21,7 @@ import { reviewGateCommand } from "./review-gate.js";
 import { join } from "node:path";
 import { openProjectStore, projectDbPath } from "../rag/project-store.js";
 import { maybeRulesyncGenerate } from "../utils/rulesync.js";
+import { commitContract, contractChanges } from "../environment/contract-commit.js";
 
 function hasRagIndex(config, projectDir) {
   // KJC-BUG-0128: probing must never CREATE the store — openVecStore runs
@@ -52,6 +53,8 @@ export function briefCommand({ config = null, flags = {}, role = null }) {
 
 export async function envInstallCommand({ config = null, logger = null, flags = {} }) {
   const projectDir = config?.projectDir || process.cwd();
+  // KJC-BUG-0273: what is dirty NOW is the person's; kj commits only what it generates below.
+  const dirtyBefore = contractChanges(projectDir);
 
   // KJC-TSK-0709 — the board is chosen BEFORE the playbook renders (its
   // tracking line depends on the backend): interactive installs ask when
@@ -214,6 +217,11 @@ export async function envInstallCommand({ config = null, logger = null, flags =
       wizard?.close();
     } catch { /* privacy onboarding is best-effort */ }
     console.log("  The host agent now follows the method: RAG first, TDD, cross-AI review before commit.");
+    // KJC-BUG-0273: the contract is kj's to commit. Left to the agent, its own
+    // PR-size rules forbid a 1200-line commit of generated files and it stops.
+    const contract = commitContract({ projectDir, before: dirtyBefore, baseBranch: config?.base_branch || "main" });
+    if (contract.committed) console.log(`✓ contract committed by kj: ${contract.files.length} generated file(s), nothing for the agent to commit`);
+    else if (!contract.reason.startsWith("nothing")) console.log(`⚠ the contract kj generated is NOT committed (${contract.reason}): run \`kj env install\` again once that is fixed`);
     // KJC-BUG-0133 (part 2): a mid-session install lands the playbook in
     // CLAUDE.md, but the running session loaded its context BEFORE — nobody
     // re-reads it. Print the method so it enters THIS conversation now.

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/rules-approve.js

@@ -0,0 +1,63 @@
+/**
+ * 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 read these exact bytes; a touched proposal is reviewed again.
+  const { ok, verdict } = await checkVerdict(projectDir, text);
+  if (!verdict) return { code: 1, lines: ["✗ this proposal has no cross-AI review of its exact content (none recorded, or it changed since): run `kj rules review`"] };
+  if (ok) {
+    log(`Reviewed by ${verdict.reviewer}, a different AI from the one that wrote it: ${verdict.summary || "approved"}`);
+  } else {
+    // KJC-TSK-0974 (ADR 0017): a rejection does not decide, the human does. What
+    // the defense asks is that nothing weak is approved UNSEEN: objections first.
+    log(`REJECTED by ${verdict.reviewer}, a different AI from the one that wrote it: ${verdict.summary || "see its objections"}`);
+    log("Its objections, before anything else. Approving installs the proposal as it is, objections included:");
+    for (const issue of verdict.issues ?? []) log(`  - ${issue.description ?? issue.message ?? JSON.stringify(issue)}`);
+  }
+  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)`] };
+}

package/src/commands/rules-compile.js

@@ -0,0 +1,117 @@
+/**
+ * kj rules compile (KJC-TSK-0940, MDR-D, ADR 0016): the brief for whoever
+ * compiles the rules of the MD files that have no gate yet. kj calls no model:
+ * the host agent knows its own tools and their arguments, which is what a
+ * condition has to name. It proposes; `kj rules check` proves the proposal and
+ * the user approves it (`kj rules approve`, a human act).
+ */
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+import yaml from "js-yaml";
+
+import { shownSource } from "../rules/inventory.js";
+import { loadRules, PROPOSAL_FILE, RULES_FILE, rulesCoverage } from "./rules.js";
+
+const FORMAT = `\`\`\`yaml
+version: 1
+rules:
+  - id: R-0a1b2c3d4e          # the id below, as is
+    source: CLAUDE.md          # the MD file the rule is written in
+    text: "Sprints: uno por día."   # the rule's text, word for word
+    kind: deterministic
+    when:                      # WHEN TO DENY the call
+      tool: "mcp__planning-game*__create_sprint"   # a glob, or a list of globs
+      any:                     # all: every condition holds; any: at least one
+        - { arg: allowLongSprint, equals: true }
+        - { arg: endDate, days_from: startDate, gt: 0 }
+    message: "Un sprint dura un día."   # what the denied agent reads
+    examples:                  # the rule is run against them: both lists required
+      deny: [{ tool: mcp__planning-game-x__create_sprint, input: { startDate: "2026-10-05", endDate: "2026-10-11" } }]
+      allow: [{ tool: mcp__planning-game-x__create_sprint, input: { startDate: "2026-10-05", endDate: "2026-10-05" } }]
+  - { id: R-1a2b3c4d5e, source: CLAUDE.md, text: "No preguntes obviedades.", kind: judgment, when: { tool: AskUserQuestion } }
+  - { id: R-2a3b4c5d6e, source: CLAUDE.md, text: "Habla español correcto.", kind: out-of-scope, reason: "no tool call breaks it" }
+\`\`\``;
+
+const HOW = [
+  "A condition reads ONE argument of the tool input (`arg`, a dotted path such as updates.status) with exactly one",
+  "operator: equals, in (a list), matches (a regex), exists (true/false), gt, lt. With days_from, gt/lt compare the",
+  "calendar days from that other argument to `arg`. There is nothing else: no other keys, no free code.",
+  "",
+  "Choose the kind of each rule:",
+  "- deterministic: ONE tool call breaks it and the tool name and its arguments are enough to tell. Name the tools",
+  "  as you see them (MCP tools included). Deny only what the rule forbids: a gate that denies honest calls gets removed.",
+  "- judgment: a tool call breaks it, but telling takes reading what the call says. Give `when.tool`, and a `reason`",
+  "  when a condition looks possible and is not (a reviewer will ask): say what it cannot see or what it would deny.",
+  "- out-of-scope: it is about how you think or answer, and no tool call breaks it. Give the `reason`.",
+  "Do not stretch a rule into a condition it does not state, and do not leave a rule out: every rule gets a kind.",
+];
+
+/**
+ * KJC-TSK-0953: kj writes the skeleton of the proposal, so nobody retypes the
+ * literal texts. It starts from what rules.yml holds minus the stale, lays the
+ * proposal already there over it (what is filled in stays), and adds one entry
+ * per pending rule that is missing, with no kind yet.
+ * @returns {number|null} the entries with no kind, or null when the proposal there is not YAML
+ */
+function writeSkeleton({ projectDir, home, pending, kept, gone }) {
+  const file = path.join(projectDir, PROPOSAL_FILE);
+  let proposed = [];
+  if (fs.existsSync(file)) {
+    try { proposed = yaml.load(fs.readFileSync(file, "utf8"))?.rules; } catch { return null; }
+    if (!Array.isArray(proposed)) return null;
+  }
+  // The approved rules are the base: a proposal that forgot one would remove its
+  // gate on approval. What the proposal says about a rule wins; the stale leave.
+  const byId = new Map(kept.map((rule) => [rule.id, rule]));
+  const loose = []; // entries with no usable id: kept, for kj rules check to name
+  for (const entry of proposed) {
+    if (typeof entry?.id !== "string") loose.push(entry);
+    else if (!gone.has(entry.id)) byId.set(entry.id, entry);
+  }
+  for (const rule of pending) {
+    if (!byId.has(rule.id)) byId.set(rule.id, { id: rule.id, source: shownSource(rule.file, projectDir, home), text: rule.text });
+  }
+  const rules = [...byId.values(), ...loose];
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, yaml.dump({ version: 1, rules }, { lineWidth: -1 }));
+  return rules.filter((entry) => !entry?.kind).length;
+}
+
+/** @returns {{code: 0|1, lines: string[]}} */
+export function rulesCompileBrief({ projectDir, home = os.homedir() }) {
+  const covered = rulesCoverage({ projectDir, home });
+  if (!covered.output) return covered;
+  const pending = covered.output.rows.filter((row) => row.status === "none");
+  const { stale } = covered.output;
+  if (pending.length + stale.length === 0) return { code: 0, lines: ["✓ every rule of the MD files is decided: nothing to compile"] };
+  const gone = new Set(stale.map((rule) => rule.id));
+  const kept = loadRules(projectDir).rules.filter((rule) => !gone.has(rule.id));
+  const undecided = writeSkeleton({ projectDir, home, pending, kept, gone });
+  if (undecided === null) return { code: 1, lines: [`✗ ${PROPOSAL_FILE} is not valid YAML with a rules list: fix it or delete it`] };
+  return {
+    code: 0,
+    lines: [
+      "# Compile the rules of the MD files into gates (ADR 0016)",
+      "",
+      `${PROPOSAL_FILE} is written: what ${RULES_FILE} holds today, as it is, and one entry per rule with no gate,`,
+      `with its id, source and literal text. ${undecided} entr${undecided === 1 ? "y has" : "ies have"} no kind yet: edit each one, give it its kind and`,
+      `what that kind takes. Leave id, source and text as they are. You propose; you cannot write ${RULES_FILE}.`,
+      ...(stale.length ? [`Left out, their text is in no MD any more: ${stale.map((rule) => rule.id).join(", ")}`] : []),
+      "",
+      FORMAT,
+      "",
+      ...HOW,
+      "",
+      "A rule with a condition (deterministic) you write by hand, in its entry. The rest take no condition, and you",
+      "decide many at once: `kj rules decide <id>... --kind judgment --tool <tool>` or",
+      "`kj rules decide <id>... --kind out-of-scope --reason \"<why no tool call breaks it>\"`.",
+      "",
+      "## Then",
+      "Run `kj rules check` and fix the proposal until it holds. Then run `kj rules review`: a different AI judges",
+      "whether each compilation is as strong as its text, and a rule you weakened comes back to you. Only then ask your",
+      "user to read it and run `kj rules approve` from their own terminal: no agent session can.",
+    ],
+  };
+}

package/src/commands/rules-decide.js

@@ -0,0 +1,52 @@
+/**
+ * kj rules decide (KJC-TSK-0969, MDR-G, ADR 0016): a real project has more than
+ * a hundred rules, and most take no condition. Their kind is decided in one go:
+ * judgment with the tool it shows on, or out of scope with the reason. kj writes
+ * the proposal, as it writes its skeleton. A deterministic rule is not decided
+ * here: its condition and its examples are written rule by rule.
+ */
+import fs from "node:fs";
+import path from "node:path";
+
+import yaml from "js-yaml";
+
+import { PROPOSAL_FILE } from "./rules.js";
+
+const failed = (line) => ({ code: 1, lines: [`✗ ${line}`] });
+
+/** What each kind takes, or why it cannot be decided this way. */
+function decision({ kind, tools = [], reason = "" }) {
+  if (kind === "judgment") {
+    if (tools.length === 0) return { error: "a judgment rule names the tool it shows on: --tool <glob> (repeatable)" };
+    // KJC-TSK-0973: why it takes no condition, when there is something to say.
+    return { fields: { kind, when: { tool: tools.length === 1 ? tools[0] : tools }, ...(reason.trim() ? { reason: reason.trim() } : {}) } };
+  }
+  if (kind === "out-of-scope") {
+    if (!reason.trim()) return { error: "an out-of-scope rule says why no tool call breaks it: --reason <text>" };
+    return { fields: { kind, reason: reason.trim() } };
+  }
+  return { error: "--kind is judgment or out-of-scope; a deterministic rule is written by hand, with its condition and its examples" };
+}
+
+/**
+ * @param {{projectDir: string, file?: string, ids: string[], kind: string, tools?: string[], reason?: string}} opts
+ * @returns {{code: 0|1, lines: string[]}}
+ */
+export function rulesDecide({ projectDir, file = PROPOSAL_FILE, ids, kind, tools, reason }) {
+  if (!Array.isArray(ids) || ids.length === 0) return failed("name at least one rule id (R-...)");
+  const { fields, error } = decision({ kind, tools, reason });
+  if (error) return failed(error);
+  const target = path.resolve(projectDir, file);
+  let doc;
+  try { doc = yaml.load(fs.readFileSync(target, "utf8")); } catch { return failed(`no readable ${file}: run \`kj rules compile\` first`); }
+  if (!Array.isArray(doc?.rules)) return failed(`${file} has no rules list`);
+  const wanted = new Set(ids);
+  const known = new Set(doc.rules.map((entry) => entry?.id));
+  const missing = ids.filter((id) => !known.has(id));
+  if (missing.length) return failed(`not in ${file}: ${missing.join(", ")}`);
+  // What identifies the rule stays; what its previous kind took goes.
+  doc.rules = doc.rules.map((entry) => (wanted.has(entry?.id) ? { id: entry.id, source: entry.source, text: entry.text, ...fields } : entry));
+  fs.writeFileSync(target, yaml.dump(doc, { lineWidth: -1 }));
+  const undecided = doc.rules.filter((entry) => !entry?.kind).length;
+  return { code: 0, lines: [`✓ ${wanted.size} rule(s) decided as ${kind}; ${undecided} entr${undecided === 1 ? "y has" : "ies have"} no kind yet`] };
+}