karajan-code 4.33.0 → 4.34.0

package/src/review/loc-budget.js

@@ -0,0 +1,97 @@
+/**
+ * What counts toward the PR size budget (KJC-BUG-0205).
+ *
+ * The budget exists to cap CODE growth. Two implementations of that rule had
+ * drifted apart: CI excluded lockfiles, build output and the docs tree, while
+ * the local gate summed every line of the diff. A doc-only PR was warned at 234
+ * lines locally and counted 104 in CI, and a gate that cries wolf in one place
+ * and not the other teaches people to believe neither.
+ *
+ * Two rules decide what is exempt, and they are not the same rule:
+ *  - GENERATED output never counts: nobody wrote it, and the reviewer reads the
+ *    source that produced it.
+ *  - HUMAN documentation never counts either. Rationing docs is how a project
+ *    ends up shipping features nobody can discover (which is exactly what
+ *    happened in 4.33.0, see KJC-TSK-0871).
+ *
+ * And one thing that DOES count, on purpose: AI-rule files (CLAUDE.md,
+ * AGENTS.md, templates/**). They enter the agent's context on every run, so
+ * unbounded growth there dilutes the signal the agent receives.
+ */
+
+const EXEMPT = [
+  // Generated or vendored: nobody typed it.
+  /(^|\/)dist\//,
+  /(^|\/)build\//,
+  /(^|\/)coverage\//,
+  /(^|\/)node_modules\//,
+  /(^|\/)\.astro\//,
+  /(^|\/)public\/docs\//,
+  /\.min\.(js|css)$/,
+  /\.map$/,
+  /\.snap(shot)?$/,
+  /(^|\/)(package-lock\.json|pnpm-lock\.yaml|yarn\.lock|npm-shrinkwrap\.json)$/,
+  /\.lock$/,
+  /(^|\/)tests\/_diet\//,
+  // Human documentation, wherever the project keeps it. The landing's docs
+  // moved into the monorepo (MONO-3) and the old root-anchored `docs/` rule
+  // stopped matching them, which is how documenting started costing budget.
+  /(^|\/)docs\/.*\.(md|mdx|txt|rst)$/,
+  /^(CHANGELOG|README|CODE_OF_CONDUCT|CONTRIBUTING|SECURITY)(\.[a-z-]+)?\.md$/,
+  /^(MIGRATION|TODO).*\.md$/,
+];
+
+// The exceptions to the exception: these ARE the agent's context.
+const AI_RULES = [/^CLAUDE\.md$/, /^AGENTS\.md$/, /^GEMINI\.md$/, /(^|\/)templates\//];
+
+/** @param {string} file @returns {boolean} */
+export function countsTowardBudget(file) {
+  if (!file) return false;
+  if (AI_RULES.some((re) => re.test(file))) return true;
+  return !EXEMPT.some((re) => re.test(file));
+}
+
+/**
+ * KJC-BUG-0208 — the policy invariant `net_lines_added` summed the whole
+ * numstat, so the same diff printed 174 in the size gate and 202 in the policy,
+ * two lines apart. One rule, one number: the metric is netted over the files
+ * that count, and what does not count is still said out loud.
+ *
+ * @param {string} numstat output of `git diff --numstat`
+ * @returns {{net: number, exempt: number}}
+ */
+export function budgetedNet(numstat) {
+  let net = 0;
+  let exempt = 0;
+  for (const line of String(numstat || "").split("\n")) {
+    if (!line.trim()) continue;
+    const [a, r, ...rest] = line.split("\t");
+    const added = Number(a);
+    const removed = Number(r);
+    if (!Number.isFinite(added) || !Number.isFinite(removed)) continue; // binary
+    if (!countsTowardBudget(rest.join("\t"))) { exempt += added; continue; }
+    net += added - removed;
+  }
+  return { net, exempt };
+}
+
+/**
+ * @param {string} numstat output of `git diff --numstat`
+ * @returns {{added: number, exempt: number, testAdded: number}}
+ */
+export function budgetedAdded(numstat) {
+  let added = 0;
+  let exempt = 0;
+  let testAdded = 0;
+  for (const line of String(numstat || "").split("\n")) {
+    if (!line.trim()) continue;
+    const [a, , ...rest] = line.split("\t");
+    const n = Number(a);
+    if (!Number.isFinite(n)) continue; // binary files emit '-'
+    const file = rest.join("\t");
+    if (!countsTowardBudget(file)) { exempt += n; continue; }
+    added += n;
+    if (/\/tests?\/|__tests__\/|\.test\.|\.spec\./.test(`/${file}`)) testAdded += n;
+  }
+  return { added, exempt, testAdded };
+}

package/src/roles/audit-role.js

@@ -1,6 +1,9 @@
 import { mkdirSync, writeFileSync } from "node:fs";
 import { dirname } from "node:path";
 import { AgentRole } from "./agent-role.js";
+import { withBrainRecovery } from "../brain/with-brain-recovery.js";
+import { buildRoleFallbackChain } from "../brain/role-fallback-chain.js";
+import { ONE_SHOT_POLICY } from "../brain/one-shot-policy.js";
 import { securityAuditMarkerPath } from "../steward/invariants.js";
 import { buildAuditPrompt, parseAuditOutput, AUDIT_DIMENSIONS } from "../prompts/audit.js";
 import { measureBasalCost, loadPreviousAudit, saveAuditSnapshot, computeGrowthDelta } from "../audit/basal-cost.js";
@@ -193,13 +196,36 @@ export class AuditRole extends AgentRole {
     const runArgs = { prompt, role: "audit" };
     if (onOutput) runArgs.onOutput = onOutput;
     const startedAt = Date.now();
-    const result = await agent.runTask(runArgs);
+    // KJC-BUG-0194: this used to call agent.runTask() directly, which made
+    // audit the ONE role that bypassed the brain. No classification (so an MCP
+    // caller saw a quota wall as category "unknown") and no declared chain
+    // (so roles.audit.fallback was ignored even after KJC-TSK-0859 wired it,
+    // because the wiring lives in AgentRole.execute and audit overrides it).
+    // The one-shot policy matters here: `kj audit` must take the next
+    // candidate at once rather than hibernate for hours inside a command.
+    const result = await withBrainRecovery({
+      agent: { runTask: (args) => agent.runTask(args), provider, model: this.config?.roles?.audit?.model ?? null },
+      taskArgs: runArgs,
+      role: "audit",
+      provider,
+      logger: this.logger,
+      emitter: this.emitter,
+      policy: ONE_SHOT_POLICY,
+      fallback: buildRoleFallbackChain({ config: this.config, role: "audit", createAgentFn: this._createAgent, logger: this.logger }),
+    });
     const durationMs = Date.now() - startedAt;
 
     const usage = extractUsage(result, { provider, durationMs });
 
     if (!result.ok) {
-      return { ok: false, result: { error: result.error || result.output || "Audit failed", provider }, summary: `Audit failed: ${result.error || "unknown error"}`, usage };
+      // The classification and the itinerary travel with the failure, so a
+      // caller (CLI or MCP) can say WHY it stopped and what was tried.
+      return {
+        ok: false,
+        result: { error: result.error || result.output || "Audit failed", provider, recovery: result.recovery || null, tried: result.tried || null },
+        summary: `Audit failed: ${result.recovery?.class ? `${result.recovery.class} — ` : ""}${result.error || "unknown error"}`,
+        usage,
+      };
     }
 
     try {