karajan-code 4.32.0 → 4.34.0

package/src/commands/review-gate.js

@@ -22,6 +22,8 @@ import { checkCardFirst } from "../review/card-first.js";
 import { liftSealedSupervisorViolations } from "../policy/supervisor-verify.js";
 import { checkTestsWithCode } from "../review/tests-with-code.js";
 import { loadPrivacyList, scanText } from "../privacy/scan.js";
+import { isGeneratedPath, splitAddedByFile } from "../privacy/diff-scope.js";
+import { budgetedAdded, budgetedNet } from "../review/loc-budget.js";
 import { checkStagedDiff, loadPolicy } from "../policy/engine.js";
 import { loadStandingExceptions, recordPolicyException } from "../policy/exceptions.js";
 import { policyFileHash, recordGateDecision } from "../policy/decisions.js";
@@ -202,14 +204,17 @@ export async function reviewGateCommand({ config, logger = null, flags = {} }) {
   const sizeSource = locInv ? `policy [${locInv.id}]` : "method_gates";
   if (sizeWarn > 0) {
     const numstat = await rawDiff(flags.range, ["--numstat"]);
-    const added = numstat.split("\n").reduce((acc, l) => acc + (Number(l.split("\t")[0]) || 0), 0);
+    // KJC-BUG-0205: the budget caps CODE growth, so generated output and human
+    // documentation are exempt — the same rule CI applies. Counting everything
+    // here warned 234 lines on a doc-only PR that CI counted at 104, and two
+    // implementations of one rule that disagree teach people to trust neither.
+    const { added, exempt, testAdded } = budgetedAdded(numstat);
+    // Said out loud: an exemption nobody sees is indistinguishable from a gate
+    // that is not looking.
+    if (exempt > 0) console.log(`ℓ pr-size: ${exempt} line(s) exempt from the budget (generated output and human docs; AI-rule files always count)`);
     if (added > sizeWarn) {
       // KJC-TSK-0795 AC5: say how much of the weight is the module's OWN tests —
       // partitioning is a decision, and it must never split code from its tests.
-      const testAdded = numstat.split("\n").reduce((acc, l) => {
-        const [a, , ...f] = l.split("\t");
-        return acc + (/\/tests?\/|__tests__\/|\.test\.|\.spec\./.test(`/${f.join("\t")}`) ? Number(a) || 0 : 0);
-      }, 0);
       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") {
@@ -230,17 +235,24 @@ export async function reviewGateCommand({ config, logger = null, flags = {} }) {
   // don't publish. In the SEA binary the privacy module is stubbed and
   // throws: the gate degrades with a note instead of crashing.
   try {
-    const added = diff.split("\n").filter((l) => l.startsWith("+") && !l.startsWith("+++")).map((l) => l.slice(1)).join("\n");
-    const findings = scanText(added, { list: loadPrivacyList(), source: "<staged diff>" });
+    // KJC-BUG-0203: per file, so a finding can name where it lives and so
+    // build output is judged as what it is. Generic heuristics are silenced
+    // there (nobody typed a minified bundle); a denylist hit is not, because
+    // the incident behind this scanner was personal data inside a build.
+    const list = loadPrivacyList();
+    const findings = splitAddedByFile(diff).flatMap(({ file, added }) => {
+      const found = scanText(added, { list, source: file });
+      return isGeneratedPath(file) ? found.filter((f) => f.severity === "block") : found;
+    });
     const blocks = findings.filter((f) => f.severity === "block");
     const warns = findings.filter((f) => f.severity === "warn");
-    for (const f of warns) console.log(`⚠ privacy: [${f.type}] added line ${f.line} → ${f.masked} — personal data? move it out before it ships`);
+    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}] on added line ${f.line} → ${f.masked}`);
+        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;
@@ -281,12 +293,10 @@ export async function reviewGateCommand({ config, logger = null, flags = {} }) {
   // 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.
-  let net = 0;
-  for (const l of (await rawDiff(flags.range, ["--numstat"])).split("\n")) {
-    const [a, r] = l.trim().split(/\s+/);
-    if (a && a !== "-") net += Number(a) || 0;
-    if (r && r !== "-") net -= Number(r) || 0;
-  }
+  // KJC-BUG-0208: el mismo modulo que decide el presupuesto decide el metrico
+  // del invariante. Sumar aqui el numstat entero daba dos cifras para la misma
+  // regla en dos lineas seguidas del mismo comando.
+  const { net } = budgetedNet(await rawDiff(flags.range, ["--numstat"]));
   // GOV-B (KJC-TSK-0746): las permanentes concedidas (kj policy grant)
   // eximen su regla mientras viven; el descarte de líneas corruptas se dice.
   const std = loadStandingExceptions(projectDir);

package/src/environment/panel.js

@@ -0,0 +1,85 @@
+/**
+ * The project's panel, said out loud (KJC-TSK-0865).
+ *
+ * The user chooses who writes and who reviews. `kj run` honoured that choice
+ * because it launched the agents itself; since v4 the HOST agent orchestrates,
+ * and nothing carried the choice into the session, so the host wrote the code
+ * and the user found out by accident.
+ *
+ * The panel line travels with the playbook, which is what every host reads at
+ * session start. It ANNOUNCES, it never blocks: the host may still write the
+ * code, and then it says so instead of staying quiet.
+ */
+import { resolveRole } from "../config/role-resolver.js";
+import { policyFileHash, recordGateDecision } from "../policy/decisions.js";
+import { readIdentity } from "../identity/store.js";
+
+/** Roles worth announcing: who writes, who reviews, who arbitrates. */
+export const PANEL_ROLES = ["coder", "reviewer", "solomon"];
+
+/**
+ * @returns {{coder: string|null, reviewer: string|null, solomon: string|null}}
+ *   the provider declared (or inherited) for each panel role.
+ */
+export function resolvePanel(config) {
+  const panel = {};
+  for (const role of PANEL_ROLES) panel[role] = resolveRole(config, role).provider || null;
+  return panel;
+}
+
+/**
+ * One agent-facing line naming the panel, or null when the project declares
+ * no coder and no reviewer. A project without a panel gets no line at all:
+ * announcing "coder: nobody" would spend attention to say nothing.
+ */
+export function panelLine(config) {
+  const { coder, reviewer, solomon } = resolvePanel(config);
+  if (!coder && !reviewer) return null;
+  const parts = [`coder=${coder || "unset"}`, `reviewer=${reviewer || "unset"}`];
+  if (solomon && solomon !== coder) parts.push(`solomon=${solomon}`);
+  return [
+    `- The panel is your user's, not yours: ${parts.join(", ")}.`,
+    "  When the coder is not you, the writing is ITS job; write it yourself",
+    "  anyway and say so in your closing message, never in silence.",
+  ].join("\n");
+}
+
+/**
+ * KJC-TSK-0868: the host writing the code while another coder is declared is
+ * not an offence to block, it is a fact to record. Announcing at session start
+ * is not enough: the user chose who writes and finds out it did not happen by
+ * accident, one turn at a time.
+ *
+ * @returns {{coder: string, host: string}|null} null when there is nothing to
+ *   record: no coder declared, no host detected, or the host IS the coder.
+ */
+export function panelDeviation(config, host) {
+  const { coder } = resolvePanel(config);
+  if (!coder || !host || coder === host) return null;
+  return { coder, host };
+}
+
+/**
+ * KJC-TSK-0873: the log holds both sides. A deviation alone cannot say whether
+ * the panel is honoured almost always or almost never, and those are different
+ * situations. The compliance seat is written where the declared coder is
+ * actually invoked (`kj code`); the deviation one when the turn ends.
+ */
+export function sealPanel({ projectDir, coder, host = null, honoured = false }) {
+  const who = readIdentity(projectDir);
+  return recordGateDecision(projectDir, {
+    decision: honoured ? "ok" : "exempt", chokepoint: "panel", escape: null, tool: null,
+    coder, host: honoured ? coder : host,
+    who: who ? { gh: who.gh_user ?? null, git: who.git_email ?? null, grade: "declarada" } : null,
+    policy_hash: policyFileHash(projectDir),
+  });
+}
+
+/** Human-facing one-liner for `kj check` and friends. */
+export function panelSummary(config) {
+  const { coder, reviewer, solomon } = resolvePanel(config);
+  if (!coder && !reviewer) return "panel: not declared (no coder, no reviewer)";
+  const parts = [`coder ${coder || "unset"}`, `reviewer ${reviewer || "unset"}`];
+  if (solomon && solomon !== coder) parts.push(`solomon ${solomon}`);
+  return `panel: ${parts.join(" · ")}`;
+}

package/src/environment/playbook.js

@@ -12,6 +12,7 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 import { upsertManagedBlock } from "../utils/managed-markers.js";
+import { panelLine } from "./panel.js";
 
 // AB-A (KJC-TSK-0650): any agent can be the brain. AGENTS.md is the
 // emerging standard (Codex, Cursor and most new CLIs read it); GEMINI.md
@@ -48,7 +49,7 @@ function trackingLine(stateBackend, boardName) {
 // AB-C2 (KJC-TSK-0653): outcome-first — invariants over step scripts.
 // Frontier models choose their own path best; what they need explicit are
 // the limits. The git gates enforce these regardless of what any brain does.
-const playbookBody = (stateBackend, boardName) => `# Karajan method (v4)
+const playbookBody = (stateBackend, boardName, panel) => `# Karajan method (v4)
 
 You are the orchestrator; Karajan governs. A task is DONE when its
 done-statement is literally true, the full suite is green, and every commit
@@ -68,7 +69,7 @@ Invariants (the git gates enforce these — they are not suggestions):
 - Every diff is reviewed by a DIFFERENT AI before it is committed
   (\`kj review --staged\`): verdicts bind to the exact diff — change the code
   and it must be reviewed again. Disagree with a rejection? \`kj solomon\`.
-- Security findings are never overridable — not even by arbitration. You
+${panel ? `${panel}\n` : ""}- Security findings are never overridable — not even by arbitration. You
   absorb the security role: \`kj brief security\` states what must be true.
   Task touches auth, user input, secrets, network or deps? Run
   \`kj audit --security\` (zero tokens) and remediate BEFORE the review.
@@ -100,15 +101,15 @@ kj announces a newer version? Tell your user what it brings and ask —
 never run \`kj update\` on your own.
 `;
 
-export function renderPlaybook({ stateBackend = "hu-board", boardName = null } = {}) {
-  return playbookBody(stateBackend, boardName);
+export function renderPlaybook({ stateBackend = "hu-board", boardName = null, config = null } = {}) {
+  return playbookBody(stateBackend, boardName, panelLine(config));
 }
 
 /**
  * Install/refresh the playbook block in the target agent files.
  * User content outside the managed block is never touched.
  */
-export async function installPlaybook({ projectDir, target = "all", version = "1", stateBackend = "hu-board", boardName = null }) {
+export async function installPlaybook({ projectDir, target = "all", version = "1", stateBackend = "hu-board", boardName = null, config = null }) {
   if (!PLAYBOOK_TARGETS.includes(target)) {
     throw new Error(`unknown target "${target}" — use one of: ${PLAYBOOK_TARGETS.join(", ")}`);
   }
@@ -118,7 +119,7 @@ export async function installPlaybook({ projectDir, target = "all", version = "1
     let source = "";
     try { source = await fs.readFile(fullPath, "utf8"); } catch { /* new file */ }
     const { content, action } = upsertManagedBlock({
-      source, blockId: "playbook", version, body: renderPlaybook({ stateBackend, boardName }), style: "html",
+      source, blockId: "playbook", version, body: renderPlaybook({ stateBackend, boardName, config }), style: "html",
       note: "do not edit: regenerated by kj env install",
     });
     if (action !== "unchanged") await fs.writeFile(fullPath, content);

package/src/harden/config-templates.js

@@ -90,9 +90,14 @@ export const GOLANGCI_BODY = [
 ].join("\n");
 
 /** Language-agnostic configs (every stack gets these). */
+// KJC-BUG-0201 (issue #1774, reported from the field): commitlint used to live
+// here, so a Python repo needed a Node runtime just to validate commit
+// messages. The generated commit-msg hook ALREADY enforces that contract in
+// pure sh (Conventional Commits, the 100-char cap, the AI-attribution ban), so
+// nothing is lost by scoping the tool to the stack that already has Node. The
+// GUARANTEE is language-agnostic; the tool does not have to be.
 export const UNIVERSAL_CONFIGS = [
   { file: ".editorconfig", blockId: "editorconfig", style: "hash", body: EDITORCONFIG_BODY },
-  { file: "commitlint.config.js", blockId: "commitlint", style: "slash", body: COMMITLINT_BODY },
 ];
 
 /**
@@ -102,6 +107,7 @@ export const UNIVERSAL_CONFIGS = [
  * tool is decorative, and kj never generates a demand it didn't satisfy.
  */
 export const JS_CONFIGS = [
+  { file: "commitlint.config.js", blockId: "commitlint", style: "slash", body: COMMITLINT_BODY },
   { file: "eslint.config.js", blockId: "eslint", style: "slash", body: ESLINT_BODY, requires: "eslint" },
   { file: ".prettierrc.json", json: true, body: PRETTIER_BODY, requires: "prettier" },
 ];

package/src/harden/guidelines-engine.js

@@ -9,7 +9,7 @@ import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 
 import { upsertManagedBlock } from "../utils/managed-markers.js";
-import { GUIDELINES_BODY } from "./guidelines-templates.js";
+import { guidelinesBody } from "./guidelines-templates.js";
 
 const BLOCK_VERSION = 1;
 const TARGETS = ["AGENTS.md", "CLAUDE.md"];
@@ -28,7 +28,13 @@ export function stripDevHooksBlock(source) {
   return { content: `${before}${joiner}${after}`, migrated: true };
 }
 
-export function installGuidelines({ projectDir = process.cwd(), dryRun = false } = {}) {
+const countLines = (text) => String(text || "").split("\n").filter((l) => l.trim()).length;
+
+export function installGuidelines({ projectDir = process.cwd(), dryRun = false, language = null } = {}) {
+  // KJC-BUG-0199 (issue #1773): the rules that enter the agent's context must
+  // be the rules of THIS project's language. kj harden already detects it for
+  // the configs; the guidelines just never asked.
+  const body = guidelinesBody(language);
   const results = [];
   for (const file of TARGETS) {
     const target = join(projectDir, file);
@@ -38,11 +44,15 @@ export function installGuidelines({ projectDir = process.cwd(), dryRun = false }
       source,
       blockId: "guidelines",
       version: BLOCK_VERSION,
-      body: GUIDELINES_BODY,
+      body,
       style: "html",
     });
+    // KJC-BUG-0206: harden removing rules is a fact worth saying. It silently
+    // dropped six lines from this repo's own files because the detected language
+    // had no block, and "updated" read like an improvement.
+    const shrank = countLines(content) < countLines(raw);
     if (!dryRun && (migrated || action !== "unchanged")) writeFileSync(target, content);
-    results.push({ file, action: migrated ? "migrated" : action });
+    results.push({ file, action: migrated ? "migrated" : action, ...(shrank ? { shrank: true } : {}) });
   }
   return { dryRun, guidelines: results };
 }

package/src/harden/guidelines-templates.js

@@ -7,14 +7,21 @@
  * bloat dilutes the signal. Distilled from the dev-toolkit guidelines.
  */
 
-export const GUIDELINES_BODY = [
+// KJC-BUG-0199 (issue #1773, reported from the field): this used to be ONE
+// fixed text, so a Python project was told to use `const`, target ES2025 and
+// prefer ES modules over require. These rules enter the agent's context on
+// EVERY run, so the noise is not harmless: it dilutes the signal and states
+// things that do not apply. The configs were already language-aware (ruff for
+// Python, golangci for Go); the guidelines had not caught up.
+//
+// Shape: a CORE that holds in any language, plus one block per language. A
+// language kj does not know gets the core ALONE, never another language's
+// rules, which is the failure this fixes.
+const CORE = [
   "# Project guidelines (kj harden)",
   "",
   "## Code",
-  "- SOLID, DRY, KISS, YAGNI. `const` by default; arrow callbacks; template literals.",
-  "- ES2025 target: never `var`, `document.write`, `alert`/`confirm`/`prompt`, `escape`/`unescape`, `substr`.",
-  "  Prefer modern APIs (`structuredClone`, `Object.groupBy`, `Array.at`/`findLast`/`toSorted`, optional chaining, `??`).",
-  "- ES modules (`import`/`export`), never `require` in new code. Names in English, descriptive.",
+  "- SOLID, DRY, KISS, YAGNI. Names in English, descriptive.",
   "- No silent fallbacks: the system works or fails loudly. Validate and sanitize all input.",
   "",
   "## Commits & PRs",
@@ -26,11 +33,63 @@ export const GUIDELINES_BODY = [
   "- Test-first. Run the tests after each meaningful change. Never skip tests.",
   "",
   "## Security",
-  "- Never commit secrets, keys or tokens. Parameterized queries; sanitize output against XSS.",
-  "",
-  "## UI/UX",
-  "- No native `alert`/`confirm`/`prompt` — use the app's modal system. Loading states; accessible; mobile-first.",
+  "- Never commit secrets, keys or tokens. Parameterized queries; sanitize output against injection.",
   "",
   "## Files",
   "- Edit existing files in place; never overwrite a whole file to make a small change.",
-].join("\n");
+];
+
+/** Per-language rules. A language absent from here gets the core alone. */
+export const LANGUAGE_GUIDELINES = {
+  javascript: [
+    "",
+    "## JavaScript / TypeScript",
+    "- `const` by default; arrow callbacks; template literals.",
+    "- ES2025 target: never `var`, `document.write`, `alert`/`confirm`/`prompt`, `escape`/`unescape`, `substr`.",
+    "  Prefer modern APIs (`structuredClone`, `Object.groupBy`, `Array.at`/`findLast`/`toSorted`, optional chaining, `??`).",
+    "- ES modules (`import`/`export`), never `require` in new code. Avoid `any` in TypeScript.",
+    "",
+    "## UI/UX",
+    "- No native `alert`/`confirm`/`prompt` — use the app's modal system. Loading states; accessible; mobile-first.",
+  ],
+  python: [
+    "",
+    "## Python",
+    "- PEP 8, and type hints on every public signature. Prefer `pathlib` over string paths.",
+    "- Never a bare `except:` — catch what you can handle and let the rest fail loudly.",
+    "- f-strings over concatenation or `%`. Comprehensions when they read better than a loop, not by default.",
+    "- Tooling and dependencies declared in `pyproject.toml`; no other language's runtime imposed on the project.",
+  ],
+  go: [
+    "",
+    "## Go",
+    "- `gofmt` is not negotiable. Errors are values: wrap with `%w` and handle them where the caller can decide.",
+    "- No naked returns in long functions; accept interfaces, return structs.",
+    "- Concurrency with a purpose: a goroutine with no way to stop it is a leak.",
+  ],
+  rust: [
+    "",
+    "## Rust",
+    "- `cargo fmt` and `cargo clippy` clean before a commit.",
+    "- No `unwrap()` outside tests: propagate with `?` and let the type say what can fail.",
+    "- `unsafe` needs a comment naming the invariant that makes it sound.",
+  ],
+};
+
+/**
+ * Languages that share another's block (KJC-BUG-0206). TypeScript is the same
+ * ecosystem as JavaScript, and the block already says so in its heading; but the
+ * stack detector reports `typescript` for a repo with a tsconfig, so the lookup
+ * missed and harden ERASED the rules a project already had.
+ */
+const ALIASES = { typescript: "javascript" };
+
+/** The guidelines body for a language (unknown or absent ⇒ the core alone). */
+export function guidelinesBody(language = null) {
+  const key = String(language || "").toLowerCase();
+  const extra = LANGUAGE_GUIDELINES[ALIASES[key] ?? key] ?? [];
+  return [...CORE, ...extra].join("\n");
+}
+
+/** Back-compat for callers that predate the language split. */
+export const GUIDELINES_BODY = guidelinesBody("javascript");

package/src/harden/harness-hooks.js

@@ -44,6 +44,12 @@ process.stdin.on("end", () => {
 `;
 
 /** Write a managed hook script under .karajan/harness/ and return its path. */
+/**
+ * KJC-BUG-0211: el cuerpo canonico de los guardias que instala ESTE modulo,
+ * para que quien verifica un sello pueda RECOMPUTAR en vez de fiarse del hash.
+ */
+export const HARNESS_BODIES = { "pretooluse.mjs": SCRIPT_BODY };
+
 export function writeHarnessScript(projectDir, name, body) {
   const dir = join(projectDir, ".karajan", "harness");
   mkdirSync(dir, { recursive: true });

package/src/harden/hook-templates.js

@@ -126,7 +126,10 @@ export function hookBody(hook, cmds = {}, { globalHooksDir = null, baseBranch =
         "# KJC-BUG-0170: the generated supervisor hooks (.karajan/hooks/pre-commit,",
         "# commit-msg) also CONTAIN the pattern by design — the bootstrap commit",
         "# that versions them must not self-detect in the consumer repo.",
-        `if git diff --cached -- . ':(exclude).github/workflows/kj-no-ai-attribution.yml' ':(exclude)src/harden/hook-templates.js' ':(exclude)src/harden/workflow-templates.js' ':(exclude)src/harden/sentinel-hooks.js' ':(exclude)scripts/ai-attribution-guard.yml' ':(exclude)tests/harden/attribution-guard.test.js' ':(exclude)tests/harden/sentinel-hooks.test.js' ':(exclude).karajan/hooks/pre-commit' ':(exclude).karajan/hooks/commit-msg' | grep '^+' | grep -qiE '${AI_ATTRIBUTION}|generated with \\[?claude'; then`,
+        "# KJC-BUG-0200 (issue #1772): the same is true of .karajan/harness — the",
+        "# whole DIRECTORY is excluded, not one file, so a supervisor script added",
+        "# later cannot bring the bug back.",
+        `if git diff --cached -- . ':(exclude).github/workflows/kj-no-ai-attribution.yml' ':(exclude)src/harden/hook-templates.js' ':(exclude)src/harden/workflow-templates.js' ':(exclude)src/harden/sentinel-hooks.js' ':(exclude)scripts/ai-attribution-guard.yml' ':(exclude)tests/harden/attribution-guard.test.js' ':(exclude)tests/harden/sentinel-hooks.test.js' ':(exclude).karajan/hooks/pre-commit' ':(exclude).karajan/hooks/commit-msg' ':(exclude).karajan/harness/' | grep '^+' | grep -qiE '${AI_ATTRIBUTION}|generated with \\[?claude'; then`,
         "  echo 'kj harden: AI attribution is not allowed in committed content'; exit 1",
         "fi",
         "# v4 review gate (ENV-C1, opt-in via `kj review --install-gate`):",