karajan-code 4.32.0 → 4.34.0

package/src/prompts/card-context.js

@@ -0,0 +1,57 @@
+/**
+ * The coder gets the CARD, not just a sentence (KJC-TSK-0864).
+ *
+ * `kj code` handed the agent a bare task string: no card, no acceptance
+ * criteria, not even the project boundary the pipeline always passed. That is
+ * the gap the user hit, because when the host orchestrates instead of
+ * `kj run`, `kj code` IS the way the declared coder gets invoked, and a coder
+ * without the card writes to a sentence instead of to a contract.
+ *
+ * A local HU is read from the board. A reference kj cannot read (an external
+ * board lives in the host's own MCP, not here) travels as the reference it is
+ * and says so: the coder learns the card exists and where to ask for it,
+ * instead of receiving a silently empty context.
+ */
+import { getHu } from "../hu/store.js";
+
+/** Ids minted by the HU Board; anything else belongs to an external board. */
+const LOCAL_HU = /^HU-/i;
+
+const externalSection = (ref) =>
+  [
+    `## Card ${ref}`,
+    "",
+    `This work is tracked as ${ref} on the project's own board, which kj cannot read from here.`,
+    "Treat the task below as the card's statement, and if something the card should answer is missing, ASK instead of guessing.",
+  ].join("\n");
+
+const localSection = (hu) => {
+  const lines = [`## Card ${hu.id} — ${hu.title}`, ""];
+  if (hu.description?.trim()) lines.push(hu.description.trim(), "");
+  lines.push(`Status on the board: ${hu.status}. The card is the contract: done means its statement is literally true.`);
+  return lines.join("\n");
+};
+
+/**
+ * @param {{projectDir: string, ref: string|null, deps?: {getHu?: Function}}} args
+ * @returns {Promise<null|{huId: string, title: string|null, section: string,
+ *   acceptanceTests: Array|null, external: boolean}>}
+ */
+export async function resolveCardContext({ projectDir, ref, deps = {} }) {
+  if (!ref?.trim()) return null;
+  const id = ref.trim();
+  if (!LOCAL_HU.test(id)) {
+    return { huId: id, title: null, section: externalSection(id), acceptanceTests: null, external: true };
+  }
+  // A missing local HU is an error, never an empty context: the caller asked
+  // for a card by id and kj either delivers it or says it does not exist.
+  const hu = await (deps.getHu || getHu)(projectDir, id);
+  const criteria = hu.acceptanceCriteria?.trim();
+  return {
+    huId: hu.id,
+    title: hu.title,
+    section: localSection(hu),
+    acceptanceTests: criteria ? [{ type: "gherkin", content: criteria }] : null,
+    external: false,
+  };
+}

package/src/prompts/session-context.js

@@ -0,0 +1,68 @@
+/**
+ * What the coder knows before it writes (KJC-TSK-0864).
+ *
+ * The method's first invariant is "the RAG answers before you assume", and
+ * `kj run` honours it through the researcher stage. `kj code` did not: the
+ * declared coder started from a sentence and guessed the codebase. So the
+ * session asks the index on the coder's behalf and hands it what came back.
+ *
+ * Retrieval is best-effort and LOUD: an empty or unreachable index warns and
+ * the coder works without project context, because blocking here would stop
+ * work in a repo that simply has no index yet. What it never does is stay
+ * quiet about it.
+ */
+import { ragQueryCommand } from "../commands/rag.js";
+
+/** Hits to carry and how much of each: the prompt pays for every line. */
+const TOP_K = 5;
+const EXCERPT = 400;
+
+const label = (hit) =>
+  hit.metadata?.symbol || hit.metadata?.hu_id || hit.metadata?.headingPath?.join(" > ") || hit.kind || "block";
+
+/** @returns {string|null} the agent-facing section, or null when there is nothing to say. */
+export function ragSection(hits) {
+  if (!Array.isArray(hits) || hits.length === 0) return null;
+  const lines = [
+    "## What the project's RAG index answers about this task",
+    "",
+    "Retrieved for you, so you do not guess what the codebase does. These are excerpts: open the file before changing it.",
+    "",
+  ];
+  for (const hit of hits) {
+    const text = hit.text || "";
+    lines.push(`### ${hit.source} · ${label(hit)}`);
+    lines.push("```", text.length > EXCERPT ? `${text.slice(0, EXCERPT)}…` : text, "```", "");
+  }
+  return lines.join("\n");
+}
+
+/**
+ * @returns {Promise<null|{section: string|null, sources: string[]}>}
+ */
+export async function resolveRagContext({ task, config, logger, deps = {} }) {
+  const run = deps.ragQueryCommand || ragQueryCommand;
+  // The index warns on stdout in CLI mode; here the hits are the product, so
+  // its narration is swallowed and only OUR verdict reaches the user.
+  const quiet = { info: () => {}, warn: () => {}, error: () => {} };
+  let hits;
+  try {
+    hits = await run({ text: task, config, logger: quiet, flags: { topK: TOP_K } });
+  } catch (err) {
+    logger?.warn?.(`rag context unavailable (${err.message}) — the coder writes without project context`);
+    return null;
+  }
+  if (!hits?.length) {
+    logger?.warn?.("the RAG index returned nothing for this task — the coder writes without project context");
+    return null;
+  }
+  const sources = [...new Set(hits.map((h) => h.source))];
+  logger?.info?.(`RAG context: ${sources.length} file(s) — ${sources.join(", ")}`);
+  return { section: ragSection(hits), sources };
+}
+
+/** The task the coder reads: everything it was given, then its own statement. */
+export function composeTask(task, sections = []) {
+  const kept = sections.filter(Boolean);
+  return kept.length ? `${kept.join("\n\n")}\n\n## Task\n\n${task}` : task;
+}

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/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/agent-role.js

@@ -16,6 +16,7 @@
 import { BaseRole } from "./base-role.js";
 import { createAgent as defaultCreateAgent } from "../agents/index.js";
 import { withBrainRecovery } from "../brain/with-brain-recovery.js";
+import { buildRoleFallbackChain } from "../brain/role-fallback-chain.js";
 
 /**
  * Silence timeout (ms) for an agent subprocess, from
@@ -154,10 +155,18 @@ export class AgentRole extends BaseRole {
     // reviewer usa reviewTask) también funcionan: el wrapper sólo necesita
     // un objeto con la firma `runTask(args) → { ok, output, error, exitCode }`.
     const result = await withBrainRecovery({
-      agent: { runTask: (args) => agent[this.agentMethod](args), provider },
+      agent: { runTask: (args) => agent[this.agentMethod](args), provider, model: this.config?.roles?.[this.name]?.model ?? null },
       taskArgs: runArgs,
       role: this.name,
       provider,
+      // KJC-TSK-0859: the chain the user declared under roles.<role>.fallback.
+      // The schema and the walker existed since KJC-TSK-0415; nobody built it,
+      // so every declared chain was dead config. This is the single point that
+      // covers every role inheriting from AgentRole.
+      fallback: buildRoleFallbackChain({
+        config: this.config, role: this.name, agentMethod: this.agentMethod,
+        createAgentFn: this._createAgent, logger: this.logger,
+      }),
       emitter: this.emitter,
       logger: this.logger,
       // KJC: sessionState lets withBrainRecovery persist a hibernating run
@@ -171,7 +180,7 @@ export class AgentRole extends BaseRole {
       const recoveryNote = result.recovery?.class ? ` [${result.recovery.class}]` : "";
       return {
         ok: false,
-        result: { error: result.error || result.output || `${this.name} failed${recoveryNote}`, provider, recovery: result.recovery, action: result.action, standbyFile: result.standbyFile || null },
+        result: { error: result.error || result.output || `${this.name} failed${recoveryNote}`, provider, recovery: result.recovery, action: result.action, standbyFile: result.standbyFile || null, tried: result.tried || null },
         summary: `${this.name} failed${recoveryNote}: ${result.recovery?.message || result.error || "unknown error"}`,
         usage: result.usage
       };

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 {