karajan-code 4.39.0 → 4.40.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "karajan-code",
-  "version": "4.39.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/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/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,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)`] };
+}

package/src/commands/rules-compile.js

@@ -0,0 +1,116 @@
+/**
+ * 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` only.",
+  "- 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,51 @@
+/**
+ * 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)" };
+    return { fields: { kind, when: { tool: tools.length === 1 ? tools[0] : tools } } };
+  }
+  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`] };
+}

package/src/commands/rules-review.js

@@ -0,0 +1,44 @@
+/**
+ * kj rules review (KJC-TSK-0963, MDR-F4, ADR 0017): the agent the rules will
+ * watch wrote the proposal, so it is not the one who calls it good. A DIFFERENT
+ * AI reads it rule by rule, and its verdict is tied to the exact bytes of the
+ * proposal (the same store and the same primitive as `kj review`). Without an
+ * approved verdict for those bytes, `kj rules approve` does not offer it.
+ */
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+import { runOneShotReview } from "../review/one-shot-review.js";
+import { PROPOSAL_FILE, rulesCheck } from "./rules.js";
+
+const TASK = [
+  "This is NOT code: it is a proposal of compiled rules (YAML). Each entry carries the literal `text` of a rule the user",
+  "wrote in their MD files (already verified word for word) and what an agent compiled it into. That agent is the one these",
+  "rules are going to watch, so it gains from a compilation that never fires. Judge every rule on one question: does the",
+  "compilation enforce what the text says?",
+  "- kind deterministic: `when` must deny the tool calls the text forbids. Too narrow a condition (it would rarely fire), or",
+  "  examples picked so that a weak condition passes, is a defect. So is a condition so wide that it denies honest calls.",
+  "- kind judgment or out-of-scope: nothing is blocked on these. If a condition over a tool name and its arguments could",
+  "  have enforced the text, the rule has been weakened.",
+  "Report as a BLOCKING issue every rule that is weaker than its text, naming its id (R-...) and saying what would enforce it.",
+  "Approve only when no rule is weaker than its text.",
+].join("\n");
+
+/**
+ * @param {{projectDir: string, file?: string, home?: string, config: object, logger?: object, deps?: object}} opts
+ *   `deps` are the seams of runOneShotReview (hostAgent, createAgentFn, detectAgents).
+ * @returns {Promise<{code: 0|1, lines: string[]}>}
+ */
+export async function rulesReview({ projectDir, file = PROPOSAL_FILE, home = os.homedir(), config, logger, deps = {} }) {
+  let text;
+  try { text = fs.readFileSync(path.resolve(projectDir, file), "utf8"); } catch { return { code: 1, lines: [`✗ no ${file}: nothing to review`] }; }
+  const checked = rulesCheck({ projectDir, home, text });
+  if (checked.code !== 0) return { code: 1, lines: checked.lines };
+  const record = await runOneShotReview({ diff: text, task: TASK, config, logger, projectDir, ...deps });
+  if (record.verdict === "approved") {
+    return { code: 0, lines: [`✓ APPROVED by ${record.reviewer}: ${record.summary || "the compilation enforces the rules as written"}`, "Now your user reads it and runs `kj rules approve` from their own terminal."] };
+  }
+  const issues = record.issues.map((issue) => `  - ${issue.description ?? issue.message ?? JSON.stringify(issue)}`);
+  return { code: 1, lines: [`✗ REJECTED by ${record.reviewer} — ${issues.length} rule(s) weaker than their text:`, ...issues, "Fix the proposal and run `kj rules review` again: the verdict is tied to its exact content."] };
+}