karajan-code 4.33.0 → 4.35.0

package/src/harden/workflow-templates.js

@@ -196,9 +196,15 @@ export const SHRINK_BUDGET_WORKFLOW = [
   "          BASE_REF: ${{ github.base_ref }}",
   "        run: |",
   // KJC-TSK-0795 AC4 — measured in GREBLA: a 414-line warning that was almost
-  // all pnpm-lock.yaml. Generated files are weight nobody wrote: the generated
-  // gate applies the same exclusions kj's own repo applies.
-  "          d=$(git diff --numstat \"origin/${BASE_REF}...HEAD\" -- . ':!**/*.md' ':!*.lock' ':!package-lock.json' ':!pnpm-lock.yaml' ':!npm-shrinkwrap.json' ':!dist/**' ':!build/**' ':!coverage/**' ':!**/*.snap' ':!**/__snapshots__/**' || true)",
+  // all pnpm-lock.yaml. Generated files are weight nobody wrote.
+  //
+  // KJC-BUG-0205: this line used to exclude `**/*.md` wholesale while claiming
+  // to apply "the same exclusions kj's own repo applies". It did not: kj counts
+  // AI-rule files (CLAUDE.md, AGENTS.md, templates/**) ON PURPOSE, because they
+  // enter the agent's context every run and unbounded growth there dilutes the
+  // signal. Documentation is exempt where documentation lives; markdown that
+  // instructs an agent is code.
+  "          d=$(git diff --numstat \"origin/${BASE_REF}...HEAD\" -- . ':!**/docs/**/*.md' ':!**/docs/**/*.mdx' ':!**/docs/**/*.txt' ':!**/docs/**/*.rst' ':!README.md' ':!README.*.md' ':!CHANGELOG.md' ':!CONTRIBUTING.md' ':!SECURITY.md' ':!CODE_OF_CONDUCT.md' ':!MIGRATION*.md' ':!TODO*.md' ':!*.lock' ':!package-lock.json' ':!pnpm-lock.yaml' ':!npm-shrinkwrap.json' ':!dist/**' ':!build/**' ':!coverage/**' ':!**/*.snap' ':!**/__snapshots__/**' ':!**/*.min.js' ':!**/*.map' || true)",
   '          a=$(printf "%s\\n" "$d" | awk \'$1!="-"{s+=$1}END{print s+0}\')',
   '          r=$(printf "%s\\n" "$d" | awk \'$2!="-"{s+=$2}END{print s+0}\')',
   '          net=$((a - r)); echo "net=$net (limit=$LOC_LIMIT)"',

package/src/orchestrator/config-init.js

@@ -5,7 +5,7 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 import { computeBaseRef, setSnapshot } from "../review/diff-generator.js";
-import { ensureContractBlockPresent } from "../review/gate-gitignore.js";
+import { ensureContractBlockPresent, excludeLocalArtifacts } from "../review/gate-gitignore.js";
 import { revParse } from "../utils/git.js";
 import { buildCoderPrompt } from "../prompts/coder.js";
 import { buildReviewerPrompt } from "../prompts/reviewer.js";
@@ -55,26 +55,18 @@ export async function autoInit(projectDir, logger) {
     }
   }
 
-  // Ensure .gitignore exists with universal entries only (stack-specific added after planner)
-  // KJC-BUG-0123: `.karajan/` is NOT in this list on purpose — a bare
-  // dir-exclude breaks the gate contract (git cannot re-include children);
-  // the canonical block is appended below from its single source.
-  const gitignorePath = path.join(projectDir, ".gitignore");
-  const universalIgnores = [".env", "*.log", ".DS_Store", ".reviews/"];
+  // KJC-BUG-0213 (issue #1734): el .gitignore es del equipo y viaja con el repo.
+  // Ahi solo entra el contrato v4, que el equipo entero hereda; los artefactos
+  // de una ejecucion son nuestros y locales, asi que van a .git/info/exclude.
+  // Lo que kj metia antes (.env, *.log, .DS_Store) era opinion sobre un
+  // proyecto ajeno, y aparecia en el diff de otra persona sin haberlo pedido.
   try {
-    let content = "";
-    if (await exists(gitignorePath)) {
-      content = await fs.readFile(gitignorePath, "utf8");
-    }
-    const missing = universalIgnores.filter(entry => !content.includes(entry));
-    if (missing.length > 0) {
-      const append = (content && !content.endsWith("\n") ? "\n" : "") + missing.join("\n") + "\n";
-      await fs.appendFile(gitignorePath, append, "utf8");
-      logger.info(`Created .gitignore with universal entries`);
-    }
-    await ensureContractBlockPresent(projectDir);
+    const contract = await ensureContractBlockPresent(projectDir);
+    if (contract.changed) logger.info("El contrato v4 se ha anadido a .gitignore (lo hereda quien clone)");
+    const local = await excludeLocalArtifacts(projectDir);
+    if (local.changed) logger.info(`Artefactos de kj excluidos en .git/info/exclude: ${local.added.join(", ")}`);
   } catch (err) {
-    logger.warn(`Failed to create .gitignore: ${err.message}`);
+    logger.warn(`Failed to prepare .gitignore: ${err.message}`);
   }
 
   const karajanDir = path.join(projectDir, ".karajan");
@@ -125,89 +117,11 @@ export async function autoInit(projectDir, logger) {
   }
 }
 
-// Stack-specific .gitignore patterns keyed by language/framework
-const STACK_GITIGNORE = {
-  javascript: ["node_modules/", "dist/", "build/", "coverage/", ".cache/", "*.tsbuildinfo"],
-  typescript: ["node_modules/", "dist/", "build/", "coverage/", ".cache/", "*.tsbuildinfo"],
-  python: ["__pycache__/", "*.pyc", ".venv/", "venv/", "*.egg-info/", ".pytest_cache/", "htmlcov/", ".mypy_cache/"],
-  java: ["target/", "*.class", "*.jar", "*.war", ".gradle/", "build/", ".settings/", ".classpath", ".project"],
-  kotlin: ["target/", "*.class", "build/", ".gradle/", ".kotlin/"],
-  go: ["bin/", "*.exe", "vendor/"],
-  rust: ["target/", "Cargo.lock"],
-  ruby: ["vendor/bundle/", ".bundle/", "coverage/", "tmp/"],
-  php: ["vendor/", ".phpunit.result.cache", "storage/logs/"],
-  csharp: ["bin/", "obj/", "*.suo", "*.user", "packages/", ".vs/"],
-  swift: [".build/", "Packages/", "*.xcodeproj/", "DerivedData/"],
-  dart: [".dart_tool/", "build/", ".packages"],
-};
-
-/**
- * Update .gitignore with stack-specific entries after planner/architect decides the stack.
- * Detects stack from: triage taskType, architect output, planner output, or task keywords.
- */
-export async function updateGitignoreForStack(projectDir, { stageResults, task, logger }) {
-  const gitignorePath = path.join(projectDir, ".gitignore");
-  const detected = new Set();
-
-  // From architect — if it chose layers/patterns, it may hint at the language
-  const arch = stageResults?.architect?.architecture;
-  if (arch) {
-    const archText = JSON.stringify(arch).toLowerCase();
-    for (const lang of Object.keys(STACK_GITIGNORE)) {
-      if (archText.includes(lang)) detected.add(lang);
-    }
-  }
-
-  // From planner — scan plan text for language keywords
-  const planText = (stageResults?.planner?.plan || "").toLowerCase();
-  // From task description
-  const taskText = (task || "").toLowerCase();
-  const combined = `${planText} ${taskText}`;
-
-  const langKeywords = {
-    javascript: ["node", "npm", "express", "react", "vue", "next", "vite", "vitest", "jest", "pnpm", "yarn", "javascript", "js"],
-    typescript: ["typescript", "tsx", "tsc"],
-    python: ["python", "django", "flask", "fastapi", "pip", "pytest", "poetry"],
-    java: ["java", "spring", "maven", "gradle", "junit"],
-    kotlin: ["kotlin", "ktor"],
-    go: ["golang", "go mod", "gin", "fiber"],
-    rust: ["rust", "cargo", "tokio"],
-    ruby: ["ruby", "rails", "gem", "bundler", "rspec"],
-    php: ["php", "laravel", "composer", "symfony"],
-    csharp: ["c#", "csharp", "dotnet", ".net", "aspnet"],
-    swift: ["swift", "swiftui", "vapor"],
-    dart: ["dart", "flutter"],
-  };
-
-  for (const [lang, keywords] of Object.entries(langKeywords)) {
-    if (keywords.some(kw => combined.includes(kw))) detected.add(lang);
-  }
-
-  if (detected.size === 0) return;
-
-  // Collect all entries for detected stacks
-  const entries = [];
-  for (const lang of detected) {
-    entries.push(...(STACK_GITIGNORE[lang] || []));
-  }
-  const unique = [...new Set(entries)];
-
-  try {
-    let content = "";
-    if (await exists(gitignorePath)) {
-      content = await fs.readFile(gitignorePath, "utf8");
-    }
-    const missing = unique.filter(entry => !content.includes(entry));
-    if (missing.length > 0) {
-      const header = `\n# ${[...detected].join(" + ")} project\n`;
-      const append = header + missing.join("\n") + "\n";
-      await fs.appendFile(gitignorePath, append, "utf8");
-      logger.info(`Updated .gitignore for ${[...detected].join(" + ")}: ${missing.join(", ")}`);
-    }
-  } catch (err) {
-    logger.warn(`Failed to update .gitignore for stack: ${err.message}`);
-  }
-}
+// KJC-BUG-0213 (issue #1734): aqui vivia updateGitignoreForStack, que deducia
+// el stack buscando palabras como "ts" o "js" en el texto del plan y de la
+// tarea. Cualquier frase las contiene, asi que un proyecto Laravel acabo con
+// reglas de TypeScript en SU .gitignore. Un acierto por casualidad no vale para
+// escribir en un fichero que no es nuestro: la funcion se retira entera.
 
 /**
  * Load product context from well-known file locations.

package/src/orchestrator/drivers/iteration-phases/guards.js

@@ -24,10 +24,17 @@ export async function runGuardStages({ config, logger, emitter, eventBase, sessi
 
   if (!outputEnabled && !perfEnabled) return { action: "ok" };
 
+  // KJC-BUG-0214 (issue #1733): los guards juzgan LO QUE HA HECHO ESTE RUN, no
+  // la rama entera. Con el merge-base contra la base, cualquier linea anadida
+  // en cualquier momento de la rama contaba como recien escrita, y una
+  // ejecucion se bloqueo por codigo preexistente que el coder no toco. La
+  // sesion ya guarda HEAD al arrancar precisamente para esto.
   const baseBranch = config.base_branch || "main";
+  const runStart = session?.head_at_start || session?.session_start_sha || null;
   let diff;
   try {
-    const baseRef = await computeBaseRef({ baseBranch });
+    const baseRef = runStart || await computeBaseRef({ baseBranch });
+    if (!runStart) logger.warn("Guards: sin punto de arranque del run, se juzga la rama entera contra la base");
     diff = await generateDiff({ baseRef, projectDir: config?.projectDir || null });
   } catch {
     logger.warn("Guards: could not generate diff, skipping");

package/src/orchestrator/drivers/pre-loop.js

@@ -57,7 +57,7 @@ import { maybeGenerateAutoHuBatch } from "./pre-loop-phases/auto-hu-batch.js";
 
 import {
   applyTriageOverrides, applyAutoSimplify, applyFlagOverrides,
-  resolvePipelinePolicies, updateGitignoreForStack,
+  resolvePipelinePolicies,
 } from "../config-init.js";
 import { tryCiComment } from "../ci-integration.js";
 import { getIntegration } from "../integrations.js";
@@ -350,7 +350,6 @@ export async function runPreLoopStages({ config, logger, emitter, eventBase, ses
 
   // --- Update .gitignore with stack-specific entries based on planner/architect output ---
   const projectDir = updatedConfig.projectDir || process.cwd();
-  await updateGitignoreForStack(projectDir, { stageResults, task, logger });
 
   // --- Auto-HU: when triage recommended decomposition and no manual huFile, generate HU batch ---
   await maybeGenerateAutoHuBatch({

package/src/policy/supervisor-verify.js

@@ -9,9 +9,11 @@ import { lstatSync, readFileSync } from "node:fs";
 import { resolve, sep } from "node:path";
 
 import { renderCanonicalHook } from "../harden/harden-engine.js";
+import { canonicalHarnessBody } from "../harden/sentinel-hooks.js";
 import { PROVENANCE_FILE } from "../harden/supervisor-commit.js";
 
 const HOOKS_PREFIX = ".karajan/hooks/";
+const HARNESS_PREFIX = ".karajan/harness/";
 // globalHooksDir es el único texto libre que se interpola en el render:
 // vocabulario cerrado de ruta o la provenance no verifica NADA.
 const SAFE_DIR = /^(\$HOME)?(\/[\w.@%+~-]+)+$/;
@@ -34,36 +36,63 @@ export function verifiedSupervisorFiles({ projectDir }) {
     return { files: new Set(), reason: "globalHooksDir no verificable en la provenance" };
   }
   const ok = new Set();
+  const unjudgeable = new Set();
   const entries = Array.isArray(prov?.files) ? prov.files : [];
-  const hooksRoot = resolve(projectDir, HOOKS_PREFIX);
+  // KJC-BUG-0211: desde KJC-BUG-0197 el sello cubre tambien los guardias del
+  // supervisor, y aqui solo se sabian verificar los hooks. Como `complete`
+  // exige que TODAS las entradas verifiquen, el sello no se podia ni commitear.
+  const ROOTS = [HOOKS_PREFIX, HARNESS_PREFIX].map((p) => [p, resolve(projectDir, p)]);
   for (const entry of entries) {
-    if (typeof entry?.file !== "string" || !entry.file.startsWith(HOOKS_PREFIX)) continue;
+    if (typeof entry?.file !== "string") continue;
+    const kind = ROOTS.find(([prefix]) => entry.file.startsWith(prefix));
+    if (!kind) continue;
+    const [prefix, root] = kind;
     // Contención por resolución, no por prefijo textual (catch de codex).
     const abs = resolve(projectDir, entry.file);
-    if (!abs.startsWith(hooksRoot + sep)) continue;
+    if (!abs.startsWith(root + sep)) continue;
     let st = null;
     try { st = lstatSync(abs); } catch { /* no hay objeto en la ruta */ }
     if (entry.deleted === true) {
       if (st === null) ok.add(entry.file);
       continue;
     }
+    // KJC-BUG-0212: los guardias estan en .gitignore, viven solo en la maquina
+    // que ejecuta kj harden. Que no esten AQUI no es que no verifiquen: es que
+    // este checkout (CI, otro clon) no puede juzgarlos. Un hook ausente si
+    // significa algo, porque los hooks si viajan con el repo.
+    // Pero "no esta aqui" no vale como cheque en blanco: el hash declarado
+    // tiene que ser el de un guardia que kj CONOCE, o una procedencia forjada
+    // colaria entradas ausentes con cualquier hash (catch de la review).
+    if (prefix === HARNESS_PREFIX && st === null) {
+      const body = canonicalHarnessBody(entry.file.slice(prefix.length));
+      if (body != null && typeof entry.sha256 === "string" && sha256(Buffer.from(body, "utf8")) === entry.sha256) unjudgeable.add(entry.file);
+      continue;
+    }
     if (typeof entry.sha256 !== "string" || !st?.isFile()) continue;
     if (sha256(readFileSync(abs)) !== entry.sha256) continue;
+    // No se confia en el hash sellado: se recomputa lo que kj escribiria.
     let canonical;
     try {
-      canonical = renderCanonicalHook(entry.file.slice(HOOKS_PREFIX.length), gen);
+      const name = entry.file.slice(prefix.length);
+      canonical = prefix === HOOKS_PREFIX ? renderCanonicalHook(name, gen) : canonicalHarnessBody(name);
     } catch {
       continue;
     }
-    if (sha256(Buffer.from(canonical, "utf8")) === entry.sha256) ok.add(entry.file);
+    if (canonical != null && sha256(Buffer.from(canonical, "utf8")) === entry.sha256) ok.add(entry.file);
   }
-  // `complete` = CADA entrada verificó: solo entonces la provenance se
-  // describe con honestidad y su propio diff puede alzarse.
-  const complete = entries.length > 0 && entries.every((e) => typeof e?.file === "string" && ok.has(e.file));
-  return { files: ok, complete };
+  // `complete` = ninguna entrada FALLO y alguna verifico. Exigir que todas
+  // verifiquen hacia imposible sellar desde cualquier sitio que no fuera la
+  // maquina que sello, porque los guardias no viajan con el repo (0212).
+  const judged = (e) => ok.has(e.file) || unjudgeable.has(e.file);
+  const complete = ok.size > 0 && entries.every((e) => typeof e?.file === "string" && judged(e));
+  return { files: ok, complete, unjudgeable };
 }
 
-/** Filtra violaciones de supervisor respaldadas — {violations, lifted}. */
+/**
+ * Filtra violaciones de supervisor respaldadas — {violations, lifted, note?}.
+ * `note` dice lo que este sitio NO ha podido juzgar, para que un levantamiento
+ * mas laxo de lo que parece no pase por silencio (KJC-BUG-0212).
+ */
 export function liftSealedSupervisorViolations({ projectDir, violations }) {
   const RULE = "defaults.supervisor.write";
   if (!violations.some((v) => v.rule_id === RULE && v.file)) return { violations, lifted: 0 };
@@ -75,5 +104,10 @@ export function liftSealedSupervisorViolations({ projectDir, violations }) {
     && v.file
     && (sealed.files.has(v.file) || (v.file === PROVENANCE_FILE && sealed.complete === true));
   const kept = violations.filter((v) => !liftable(v));
-  return { violations: kept, lifted: violations.length - kept.length };
+  const unjudged = sealed.unjudgeable?.size ?? 0;
+  return {
+    violations: kept,
+    lifted: violations.length - kept.length,
+    ...(unjudged > 0 ? { note: `${unjudged} guardia(s) del sello no existen en este checkout y no se han podido comprobar aquí` } : {}),
+  };
 }

package/src/rag/coverage.js

@@ -8,7 +8,7 @@
  * matchers are the single truth, here and in the indexer.
  */
 import { execa } from "execa";
-import { isAbsolute, relative } from "node:path";
+import { extname, isAbsolute, normalize, relative } from "node:path";
 import { detectAdaptersForProject, buildMatchers } from "../lang/registry.js";
 import { getLastIndexedCommit, projectSlug } from "./vec-store.js";
 
@@ -46,3 +46,34 @@ export async function ragIndexCoverage(projectDir, { db }) {
 
   return { project, total: sources.length, indexed: sources.length - missing.length, missing, stale, lastIndexedCommit, absent: indexed.size === 0 };
 }
+
+/**
+ * KJC-BUG-0216 (issue #1807) — POR QUE el RAG no puede responder sobre un
+ * fichero. El gate rag-first exigia una respuesta sobre cualquier fichero
+ * tocado, y para un .astro (o .php, o cualquier lenguaje sin adapter) eso es
+ * imposible: el indexador nunca lo toma. La unica salida era KJ_ALLOW_NO_RAG
+ * puesta por costumbre en todos los comandos, y con ella puesta el gate deja de
+ * informar y borra la diferencia entre "no pude consultar" y "no quise".
+ *
+ * `canAnswer` es la respuesta que el gate necesita: solo cuando es true tiene
+ * sentido exigir que el RAG haya hablado de ese fichero.
+ *
+ * @returns {{state: "indexed"|"stale"|"not-indexable"|"index-empty", rel: string, canAnswer: boolean, reason: string}}
+ */
+export function fileIndexState(projectDir, file, { db }) {
+  const project = projectSlug(projectDir);
+  // `./src/a.js` y `src/a.js` son el mismo fichero: sin normalizar, el segundo
+  // salia "stale" estando indexado (catch de la review).
+  const rel = normalize(isAbsolute(file) ? relative(projectDir, file) : file);
+  const matchers = buildMatchers(detectAdaptersForProject(projectDir));
+  const rows = db.prepare("SELECT DISTINCT source FROM chunks WHERE project_slug = ?").all(project);
+  const indexed = new Set(rows.map((r) => normalize(isAbsolute(r.source) ? relative(projectDir, r.source) : r.source)));
+
+  if (indexed.has(rel)) return { state: "indexed", rel, canAnswer: true, reason: `the index holds chunks for ${rel}` };
+  if (indexed.size === 0) return { state: "index-empty", rel, canAnswer: false, reason: `nothing of this project is indexed yet: kj rag index` };
+  if (matchers.shouldSkip(rel)) return { state: "not-indexable", rel, canAnswer: false, reason: `${rel} lives under a path the indexer always skips` };
+  if (!matchers.isCodeFile(rel) && extname(rel).toLowerCase() !== ".md") {
+    return { state: "not-indexable", rel, canAnswer: false, reason: `no language adapter covers ${extname(rel) || "a file with no extension"}, so the indexer never takes ${rel}` };
+  }
+  return { state: "stale", rel, canAnswer: false, reason: `${rel} is indexable but absent from the index: kj rag index --since auto` };
+}

package/src/review/board-pending.js

@@ -0,0 +1,68 @@
+/**
+ * Which pending board moves actually block (KJC-BUG-0198).
+ *
+ * board-sync blocked every advance until a merged PR's card reached a closing
+ * state, which assumes one PR per card while the project's rule splits any card
+ * over ~150 lines. With KJC-BUG-0197 (#1802 and #1803) that demanded a move that
+ * would have been a lie, and the way out was `KJ_ALLOW_BOARD=1`, which switches
+ * the whole gate off. A card still being delivered is not a lying board; a TURN
+ * ending with work nobody recorded is, and that stays the Stop gate's job.
+ *
+ * One verifiable fact carries a pending, never a promise in prose: the same card
+ * has another OPEN pull request. A branch named after the card is not enough,
+ * because the merged branch carries that name too, so accepting it would forgive
+ * every merge made from its own lane.
+ */
+
+import { execFileSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { CARD_REF_RE } from "./card-first.js";
+
+const cardOf = (text) => {
+  const m = CARD_REF_RE.exec(String(text || ""));
+  return m ? m[0].toUpperCase() : null;
+};
+
+/**
+ * `openPrHeads` null means the list could not be read, and then nothing is
+ * forgiven. `openPrNumbers` pairs with it so a pending never forgives itself.
+ *
+ * @returns {{blocking: Array<object>, carried: Array<{card: string, why: string}>, reason?: string}}
+ */
+export function blockingMoves({ pendings = [], openPrHeads = null, openPrNumbers = [] }) {
+  if (pendings.length === 0) return { blocking: [], carried: [] };
+  if (openPrHeads === null) return { blocking: [...pendings], carried: [], reason: "no se pudo comprobar si la card sigue viva en otra PR abierta (gh no respondió) — se bloquea" };
+  const openCards = new Set();
+  for (const [i, head] of openPrHeads.entries()) {
+    // A pending must never forgive itself: the PR it came from is merged, and if
+    // a stale listing still shows it, it does not count as "still open".
+    if (openPrNumbers[i] !== undefined && pendings.some((p) => Number(p.pr) === Number(openPrNumbers[i]))) continue;
+    const card = cardOf(head);
+    if (card) openCards.add(card);
+  }
+  const blocking = [], carried = [];
+  for (const p of pendings) {
+    const card = p.card ? String(p.card).toUpperCase() : null;
+    if (!card) { blocking.push(p); continue; } // nothing to check against
+    if (openCards.has(card)) carried.push({ card, why: "sigue entregándose en una PR abierta" });
+    else blocking.push(p);
+  }
+  return { blocking, carried };
+}
+
+const readJson = (path) => { try { return JSON.parse(readFileSync(path, "utf8")); } catch { return null; } };
+
+/** The decision the guard asks for, gathering the facts here so the rule ships
+ * with npm instead of waiting for the human to reseal the harness. */
+export function boardGate({ projectDir = process.cwd(), sessionId = "default", deps = {} } = {}) {
+  const state = deps.readState?.() ?? readJson(join(projectDir, ".karajan", "harness", "sentinel-state.json"));
+  const pendings = state?.sessions?.[sessionId]?.pending_moves;
+  if (!Array.isArray(pendings) || pendings.length === 0) return { blocking: [], carried: [] };
+  const run = deps.run ?? ((cmd, args) => execFileSync(cmd, args, { cwd: projectDir, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: 5000 }));
+  let open = null;
+  try { open = JSON.parse(run("gh", ["pr", "list", "--state", "open", "--limit", "100", "--json", "number,headRefName"])); } catch { /* fail closed */ }
+  const listed = Array.isArray(open) ? open : null;
+  return blockingMoves({ pendings, openPrHeads: listed?.map((p) => p.headRefName) ?? null, openPrNumbers: listed?.map((p) => Number(p.number)) ?? [] });
+}

package/src/review/card-first.js

@@ -93,6 +93,18 @@ export async function checkCardFirst({ config = {}, projectDir = process.cwd(),
         ? { ok: false, mode: "block", reason, level: v.level }
         : { ok: true, mode: "warn", reason, level: v.level };
     }
+    // KJC-TSK-0878 (issue #1371): "no he podido verificar" y "he verificado y
+    // esta mal" no son lo mismo, y ambas pueden merecer una parada. El proyecto
+    // decide si la primera para, y el mensaje dice cual de las dos es: un gate
+    // que aprueba lo que no ha comprobado da una confianza que no ha ganado.
+    // Sin adaptador declarado no hay nada que bloquear: la opcion no castiga a
+    // quien aun no tiene verify_cmd.
+    if (v.verified === null && config.board?.unverifiable === "block" && config.board?.verify_cmd) {
+      return {
+        ok: false, mode: "block", level: v.level,
+        reason: `branch references ${ref} but the card could not be verified against ${boardName} — ${v.note} (board.unverifiable: block refuses to approve a check kj did not make)`,
+      };
+    }
     return { ok: true, mode: "pass", ref, level: v.level, ...(v.note ? { note: v.note } : {}) };
   }
   const reason = `no card reference in branch "${branch}" — card-first on ${boardName}: create the card there and name the branch after it (e.g. feat/ABC-123-summary)`;

package/src/review/gate-gitignore.js

@@ -12,6 +12,8 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 
+import { runCommand } from "../utils/process.js";
+
 // KJC-BUG-0123 (issue #1268): exported as the SINGLE source of truth — kj
 // init and the orchestrator's autoInit write this same block instead of a
 // bare `.karajan/` exclude (which git cannot re-include children of).
@@ -48,6 +50,37 @@ export async function ensureContractBlockPresent(projectDir) {
   return { changed: true };
 }
 
+/**
+ * KJC-BUG-0213 (issue #1734): lo que kj deja en el repo durante una ejecucion
+ * es suyo y es local, asi que se excluye donde no molesta a nadie:
+ * `.git/info/exclude` no viaja con el repo ni aparece en el diff de otro.
+ * La ruta se pregunta a git para que funcione tambien en un worktree, donde
+ * `.git` es un fichero y no un directorio.
+ */
+const LOCAL_ARTIFACTS = [".reviews/", ".kj/", ".kj-ready.json"];
+
+export async function excludeLocalArtifacts(projectDir, run = runCommand) {
+  let file = path.join(projectDir, ".git", "info", "exclude");
+  try {
+    const res = await run("git", ["-C", projectDir, "rev-parse", "--git-path", "info/exclude"]);
+    const out = res?.stdout?.trim();
+    if (res?.exitCode === 0 && out) file = path.isAbsolute(out) ? out : path.join(projectDir, out);
+  } catch { /* sin git utilizable: se intenta la ruta por defecto */ }
+  let text = "";
+  try { text = (await fs.readFile(file, "utf8")) || ""; } catch { /* aun no existe */ }
+  const lines = new Set(text.split("\n").map((l) => l.trim()));
+  const missing = LOCAL_ARTIFACTS.filter((a) => !lines.has(a));
+  if (missing.length === 0) return { changed: false, added: [] };
+  try {
+    await fs.mkdir(path.dirname(file), { recursive: true });
+    const sep = text && !text.endsWith("\n") ? "\n" : "";
+    await fs.appendFile(file, `${sep}# Karajan run artifacts (local only, never shared)\n${missing.join("\n")}\n`, "utf8");
+    return { changed: true, added: missing };
+  } catch {
+    return { changed: false, added: [] };
+  }
+}
+
 export async function ensureGateTrackable(projectDir) {
   const file = path.join(projectDir, ".gitignore");
   let text;

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 {