karajan-code 4.40.0 → 4.41.0

package/package.json

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

@@ -32,14 +32,18 @@ export async function rulesApprove({ projectDir, file = PROPOSAL_FILE, home, env
   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] };
+  // 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)}`);
   }
-  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 });

package/src/commands/rules-compile.js

@@ -42,7 +42,8 @@ const HOW = [
   "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.",
+  "- 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.",
 ];

package/src/commands/rules-decide.js

@@ -18,7 +18,8 @@ const failed = (line) => ({ code: 1, lines: [`✗ ${line}`] });
 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 } } };
+    // 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>" };

package/src/commands/rules-review.js

@@ -21,8 +21,21 @@ const TASK = [
   "  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.",
+  "Any rule may give a `reason` for how it is compiled: weigh it, do not take it on trust.",
+  "Know what a condition can see before you ask for one (KJC-TSK-0973): the tool name and the arguments of ONE call, with",
+  "the operators equals, in, matches, exists, gt, lt. It cannot read a file a command names (a commit message passed with -F,",
+  "a body file), earlier calls, or the state of the repo. A rule whose breach is only visible there cannot be deterministic,",
+  "and judgment is its honest kind. A condition that would deny honest calls (a word that is also ordinary text, a method",
+  "name, a comment) is a defect too: do not ask for one, and do not ask for more than the text forbids.",
+  "A deterministic rule that enforces every part of its text a condition CAN see is not weak for leaving out the part no",
+  "condition can see: block it only if the visible part is compiled narrower than it could be.",
+  "What blocks is MATERIAL weakness: a form of the forbidden call an agent would plausibly write in ordinary work is let",
+  "through, or a call an agent would plausibly make in honest work is denied. A pattern over shell text is never complete,",
+  "and these gates exist for a rule forgotten or bent in passing; an agent contorting a command to dodge them is stopped at",
+  "the checkpoints it does not reach (git hooks, CI), not here. So an exotic form (a command inside a control structure, a",
+  "rare global option, unusual casing) is a non-blocking suggestion, not a blocking issue.",
+  "Report as a BLOCKING issue every rule materially weaker than its text, naming its id (R-...) and saying what would",
+  "enforce it. Approve when none is.",
 ].join("\n");
 
 /**

package/src/environment/contract-commit.js

@@ -0,0 +1,79 @@
+/**
+ * The contract commit (KJC-TSK-0857, KJC-BUG-0273). What kj generates for a
+ * project (playbook, skills, settings, workflows, gate marker, hooks) the whole
+ * team must inherit by cloning, so it goes into git. Nobody wrote it, and an
+ * agent's own PR-size rules forbid a 1200-line commit, so kj makes the commit
+ * itself: only the files it just generated, never what was already dirty, and
+ * never on the base branch once the repo has history. This is NOT the supervisor
+ * seal (ADR 0009), which stays a human act.
+ */
+import { execFileSync } from "node:child_process";
+
+/** What kj generates and the whole team must inherit by cloning (prefixes). */
+export const CONTRACT_PATHS = [
+  ".gitignore",
+  ".karajan/hooks/",
+  ".karajan/review-gate",
+  ".karajan/adrs/",
+  ".karajan/policy.yml",
+  ".claude/",
+  ".github/workflows/kj-",
+  "CLAUDE.md",
+  "AGENTS.md",
+  "GEMINI.md",
+  // KJC-TSK-0879: in a Rulesync repo kj's rules live in .rulesync/rules/karajan.md.
+  ".rulesync/",
+];
+
+const FRESH_MESSAGE = "chore(bootstrap): el contrato del método, para que quien clone lo herede";
+const REGEN_MESSAGE = "chore(kj): el contrato del método, generado por kj";
+
+const runner = (projectDir, env) => (args) => execFileSync("git", ["-C", projectDir, ...args], { encoding: "utf8", env, stdio: ["ignore", "pipe", "pipe"] });
+const isContract = (file) => CONTRACT_PATHS.some((p) => (p.endsWith("/") || p.endsWith("-") ? file.startsWith(p) : file === p));
+
+/** The contract files git sees as changed, with their porcelain code (`??` untracked). */
+function contractStatus(git) {
+  try {
+    const lines = git(["status", "--porcelain", "--untracked-files=all"]).split("\n").filter(Boolean);
+    return lines.map((line) => [line.slice(3).trim().split(" -> ").at(-1), line.slice(0, 2)]).filter(([file]) => isContract(file));
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * The contract files that differ from HEAD (or are untracked), one by one.
+ * @returns {Set<string>} empty when git cannot answer
+ */
+export function contractChanges(projectDir, git = runner(projectDir, process.env)) {
+  return new Set(contractStatus(git).map(([file]) => file));
+}
+
+const hasCommits = (git) => { try { git(["rev-parse", "--verify", "HEAD"]); return true; } catch { return false; } };
+const branchOf = (git) => { try { return git(["symbolic-ref", "--short", "HEAD"]).trim(); } catch { return ""; } };
+
+/**
+ * @param {{projectDir: string, before?: Set<string>, baseBranch?: string, env?: object}} opts
+ *   `before`: the contract files already dirty BEFORE kj generated anything,
+ *   tracked or not. They may carry the person's words, so they stay out.
+ * @returns {{committed: boolean, files?: string[], reason?: string}}
+ */
+export function commitContract({ projectDir, before = new Set(), baseBranch = "main", env = process.env }) {
+  const git = runner(projectDir, env);
+  const files = contractStatus(git).map(([file]) => file).filter((file) => !before.has(file)).sort();
+  if (files.length === 0) return { committed: false, reason: "nothing of the contract to commit" };
+  const history = hasCommits(git);
+  if (history && branchOf(git) === baseBranch) {
+    // kj never commits on the base branch, and will not switch the person's branch
+    // for them: the files are named so the commit can be made where it belongs.
+    return { committed: false, files, reason: `on the base branch '${baseBranch}', where kj never commits: create a branch and commit these generated files there (git checkout -b chore/kj-contract && git add -- ${files.join(" ")} && git commit -m "chore(kj): el contrato del método")` };
+  }
+  try {
+    git(["add", "--", ...files]);
+    // --only: these paths and nothing else. What the person had staged stays staged.
+    git(["commit", "--only", "-m", history ? REGEN_MESSAGE : FRESH_MESSAGE, "--", ...files]);
+  } catch (err) {
+    return { committed: false, files, reason: `git could not commit the contract: ${String(err.stderr || err.message).trim().split("\n")[0]}` };
+  }
+  return { committed: true, files };
+}

package/src/rules/approval-view.js

@@ -10,7 +10,12 @@
  */
 const GATE = "deterministic";
 
-const compiled = (rule) => (rule.kind === "out-of-scope" ? `reason: ${rule.reason}` : `when: ${JSON.stringify(rule.when)}`);
+const compiled = (rule) => {
+  if (rule.kind === "out-of-scope") return `reason: ${rule.reason}`;
+  // KJC-TSK-0973: why a judgment rule takes no condition is read next to it.
+  const why = rule.reason ? "  (" + rule.reason + ")" : "";
+  return `when: ${JSON.stringify(rule.when)}${why}`;
+};
 
 /** How a proposed rule weakens or changes the approved one, or "" when it does not. */
 function weakening(rule, approved) {

package/src/rules/compiled.js

@@ -79,7 +79,10 @@ function ruleErrors(rule) {
   const notText = ["source", "text", "message"].filter((k) => k in rule && typeof rule[k] !== "string");
   if (notText.length) errors.push(`${notText.join(", ")} must be text`);
   if (rule.kind === OUT_OF_SCOPE) return [...errors, ...outOfScopeErrors(rule)];
-  if ("reason" in rule) errors.push(`reason belongs to ${OUT_OF_SCOPE} rules only`);
+  // KJC-TSK-0973: any rule may say why it is compiled as it is. A judgment rule,
+  // why it takes no condition; a deterministic one, where its condition stops
+  // (what breaks the rest is not in the arguments of one call).
+  if ("reason" in rule && (typeof rule.reason !== "string" || !rule.reason.trim())) errors.push("reason is text");
   // `examples` are tool calls: the command that runs them checks their shape (kj rules test).
   const tools = [rule.when?.tool].flat();
   if (tools.length === 0 || tools.some((t) => typeof t !== "string" || !t)) errors.push("when.tool names the tool: a glob, or a list where every item is one");