karajan-code 4.5.0 → 4.6.0

package/README.md

@@ -24,12 +24,12 @@
 
 Your AI agent (Claude Code, Codex, Gemini CLI, Cursor…) writes the code. **Karajan governs how it happens**: it installs a method your agent follows on every task, and enforces it with git gates that make a false green structurally impossible.
 
-- **RAG before assuming** — `kj rag query` answers what your codebase does; no agent guesses.
-- **Card first** — every piece of work is tracked (`kj hu add|move|list`) before it starts; architecture decisions live as git-tracked ADRs (`kj adr add|list`).
+- **RAG before assuming** — `kj rag query` answers what your codebase does; no agent guesses. Works out of the box: local Ollama, or the built-in ONNX embedder when nothing can be installed; cloud embedders require an explicit sensitivity declaration and PII-redact every chunk.
+- **Card first, on YOUR board** — every piece of work is tracked before it starts: kj's HU Board (`kj hu add|move|list`), the Planning Game, or the board the project already uses (Linear, Trello, Jira, GitHub Issues) via your agent's own MCP/tools. Declared, verified at install, never optional — Karajan does not run without a board. ADRs live in git (`kj adr add|list`).
 - **Tests prove behavior** — the failing test exists first; the suite is never left red.
-- **Cross-AI review on every commit** — `kj review --staged` binds a verdict from a *different* AI to the sha256 of the exact diff. Change the code and it must be reviewed again. Without an approved verdict, **the commit does not enter** (pre-commit gate).
+- **Deterministic first, then cross-AI review** — `kj review --staged` runs SonarQube on the changed files before any AI opinion (BLOCKER/CRITICAL reject on the spot), then binds a verdict from a *different* AI to the sha256 of the exact diff — stamped with the workspace it ran from. Without an approved verdict, **the commit does not enter** (pre-commit gate).
 - **A third AI arbitrates disputes** — `kj solomon` rules when brain and reviewer disagree. Security findings are never overridable — not even by arbitration.
-- **Branch first** — the base branch only moves through atomic PRs.
+- **Branch first, lanes for parallel work** — the base branch only moves through atomic PRs; `kj worktree start|list|done` gives each concurrent task its own isolated lane.
 
 This repo runs under its own environment: every commit to karajan-code carries a cross-AI verdict.
 
@@ -66,7 +66,7 @@ Full method: [Work with your agent](https://karajancode.com/docs/v4/working-with
 
 ## Headless mode
 
-The classic multiagent pipeline lives on for CI and automation: `kj run "<task>"` orchestrates coder/reviewer/tester subprocess roles unattended, with the same gates. `kj advanced` lists the full surface. [Headless mode docs](https://karajancode.com/docs/v4/headless/).
+The classic multiagent pipeline lives on for CI and automation: `kj run "<task>"` orchestrates coder/reviewer/tester subprocess roles unattended, with the same gates. Agents and CI pass `--non-interactive` (or `KJ_NON_INTERACTIVE=1`): safe gates auto-answer, FAIL findings stop the run with a real exit code. `kj advanced` lists the full surface. [Headless mode docs](https://karajancode.com/docs/v4/headless/).
 
 ## v3 (historical)
 

package/docs/README.es.md

@@ -16,12 +16,12 @@
 
 Tu agente de IA (Claude Code, Codex, Gemini CLI, Cursor…) escribe el código. **Karajan gobierna cómo ocurre**: instala un método que tu agente sigue en cada tarea y lo hace cumplir con gates de git que hacen el falso verde estructuralmente imposible.
 
-- **RAG antes de suponer** — `kj rag query` responde qué hace tu código; ningún agente adivina.
-- **Card primero** — todo trabajo se registra (`kj hu add|move|list`) antes de empezar; las decisiones de arquitectura viven como ADRs en git (`kj adr add|list`).
+- **RAG antes de suponer** — `kj rag query` responde qué hace tu código; ningún agente adivina. Funciona de serie: Ollama local, o el embedder ONNX integrado cuando no se puede instalar nada; los embedders cloud exigen declarar la sensibilidad y redactan PII de cada chunk.
+- **Card primero, en TU board** — todo trabajo se registra antes de empezar: el HU Board de kj (`kj hu add|move|list`), el Planning Game, o el board que el proyecto ya use (Linear, Trello, Jira, GitHub Issues) vía los MCP/tools de tu agente. Declarado, verificado en la instalación, jamás opcional — Karajan no funciona sin board. Los ADRs viven en git (`kj adr add|list`).
 - **Los tests prueban el comportamiento** — el test que falla existe primero; la suite nunca se queda en rojo.
-- **Revisión IA-cruzada en cada commit** — `kj review --staged` liga el veredicto de una IA *distinta* al sha256 del diff exacto. Cambia el código y hay que revisarlo de nuevo. Sin veredicto aprobado, **el commit no entra** (gate pre-commit).
+- **Determinista primero, luego revisión IA-cruzada** — `kj review --staged` pasa SonarQube sobre los ficheros cambiados antes de cualquier opinión de IA (BLOCKER/CRITICAL rechazan en el acto), y después liga el veredicto de una IA *distinta* al sha256 del diff exacto — estampado con el workspace desde el que corrió. Sin veredicto aprobado, **el commit no entra** (gate pre-commit).
 - **Una tercera IA arbitra las disputas** — `kj solomon` decide cuando brain y reviewer discrepan. Los hallazgos de seguridad no los anula nadie — ni siquiera el arbitraje.
-- **Rama primero** — la rama base solo se mueve por PRs atómicas.
+- **Rama primero, carriles para el paralelo** — la rama base solo se mueve por PRs atómicas; `kj worktree start|list|done` da a cada tarea concurrente su carril aislado.
 
 Este repo corre bajo su propio entorno: cada commit de karajan-code lleva un veredicto de IA cruzada.
 
@@ -58,7 +58,7 @@ Método completo: [Trabaja con tu agente](https://karajancode.com/docs/es/v4/wor
 
 ## Modo headless
 
-El pipeline multiagente clásico sigue vivo para CI y automatización: `kj run "<tarea>"` orquesta roles coder/reviewer/tester en subprocesos sin humano delante, con los mismos gates. `kj advanced` lista la superficie completa. [Doc del modo headless](https://karajancode.com/docs/es/v4/headless/).
+El pipeline multiagente clásico sigue vivo para CI y automatización: `kj run "<tarea>"` orquesta roles coder/reviewer/tester en subprocesos sin humano delante, con los mismos gates. Agentes y CI pasan `--non-interactive` (o `KJ_NON_INTERACTIVE=1`): los gates seguros se auto-responden y los findings FAIL paran el run con exit code de verdad. `kj advanced` lista la superficie completa. [Doc del modo headless](https://karajancode.com/docs/es/v4/headless/).
 
 ## v3 (histórico)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "karajan-code",
-  "version": "4.5.0",
+  "version": "4.6.0",
   "description": "Local multi-agent coding orchestrator with TDD, SonarQube, and code review pipeline",
   "type": "module",
   "license": "AGPL-3.0",

package/src/checks/method.js

@@ -0,0 +1,73 @@
+/**
+ * Method report (KJC-TSK-0689, MG-D of épica KJC-PCS-0068). Individual
+ * deviations can each be legitimate — the AGGREGATE trail is the drift
+ * detector. Three measurable signals over the recent history: commit
+ * subjects without a card reference, review verdicts by workspace
+ * ([root] vs lanes), and source commits without a single test change.
+ * Informative by design; only a card-ref drought turns it into a warn.
+ */
+import { readdirSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { runCommand } from "../utils/process.js";
+import { checkTestsWithCode } from "../review/tests-with-code.js";
+import { CARD_REF_RE } from "../review/card-first.js";
+import { STRATEGY } from "./types.js";
+
+function recentVerdicts(projectDir, sample) {
+  try {
+    const dir = path.join(projectDir, ".karajan", "reviews");
+    return readdirSync(dir).filter((f) => f.endsWith(".json"))
+      .map((f) => JSON.parse(readFileSync(path.join(dir, f), "utf8")))
+      .sort((a, b) => String(b.timestamp).localeCompare(String(a.timestamp)))
+      .slice(0, sample);
+  } catch {
+    return [];
+  }
+}
+
+export async function collectMethodStats({ projectDir, run = runCommand, sample = 20 } = {}) {
+  const subjectsRes = await run("git", ["log", `-${sample}`, "--no-merges", "--format=%s"], { cwd: projectDir });
+  const subjects = subjectsRes.exitCode === 0 ? subjectsRes.stdout.split("\n").filter(Boolean) : [];
+
+  // "@%h" carries a % so git treats it as a literal format string — a bare
+  // "@" is rejected as an unknown pretty alias (caught in a live smoke).
+  const blocksRes = await run("git", ["log", `-${Math.min(sample, 10)}`, "--no-merges", "--name-only", "--format=@%h"], { cwd: projectDir });
+  const blocks = blocksRes.exitCode === 0
+    ? blocksRes.stdout.split(/^@.*$/m).map((b) => b.split("\n").map((l) => l.trim()).filter(Boolean)).filter((b) => b.length > 0)
+    : [];
+  const offenders = blocks.filter((files) => checkTestsWithCode({ config: {}, stagedFiles: files, env: {} }).mode !== "pass").length;
+
+  const verdicts = recentVerdicts(projectDir, sample);
+  const stamped = verdicts.filter((v) => v.workspace);
+
+  return {
+    commits: { total: subjects.length, withCard: subjects.filter((s) => CARD_REF_RE.test(s)).length },
+    verdicts: { total: verdicts.length, stamped: stamped.length, root: stamped.filter((v) => v.workspace === "root").length },
+    testless: { sampled: blocks.length, offenders },
+  };
+}
+
+export function formatMethodStats(s) {
+  return `commits with card ref ${s.commits.withCard}/${s.commits.total} · verdict workspaces root ${s.verdicts.root}/${s.verdicts.stamped || 0} stamped (${s.verdicts.total} total) · source commits without tests ${s.testless.offenders}/${s.testless.sampled}`;
+}
+
+function createMethodCheck() {
+  return {
+    name: "method",
+    label: "Method adherence (recent history)",
+    strategy: STRATEGY.NONE,
+    async detect({ config = {}, projectDir = process.cwd(), run = runCommand } = {}) {
+      const stats = await collectMethodStats({ projectDir, run, sample: config.method_gates?.report_sample || 20 });
+      const detail = formatMethodStats(stats);
+      const drought = stats.commits.total >= 5 && stats.commits.withCard / stats.commits.total < 0.5;
+      if (drought) {
+        return { ok: false, severity: "warn", detail: `most recent commits carry no card reference — ${detail}` };
+      }
+      return { ok: true, severity: "info", detail };
+    },
+  };
+}
+
+export function getMethodChecks() {
+  return [createMethodCheck()];
+}

package/src/commands/check.js

@@ -5,17 +5,22 @@
  */
 
 import { checkHarden } from "../harden/check.js";
+import { collectMethodStats, formatMethodStats } from "../checks/method.js";
 
 export async function checkCommand({ projectDir = process.cwd(), profile = "standard", json = false, logger = console } = {}) {
   const result = await checkHarden({ projectDir, profile });
+  // KJC-TSK-0689 (MG-D): method adherence is VISIBILITY, not a gate — it
+  // rides along in check output but never affects the exit code.
+  const method = await collectMethodStats({ projectDir }).catch(() => null);
 
   if (json) {
-    logger.info?.(JSON.stringify(result));
+    logger.info?.(JSON.stringify({ ...result, method }));
     return result.ok ? 0 : 1;
   }
 
   logger.info?.(`kj check (${profile})`);
   for (const c of result.checks) logger.info?.(`  ${c.ok ? "✓" : "✗"} ${c.id}: ${c.detail}`);
+  if (method) logger.info?.(`  method: ${formatMethodStats(method)}`);
   if (!result.ok) logger.info?.("Harness drift detected — run `kj harden` to repair.");
   else logger.info?.("Harness OK.");
   return result.ok ? 0 : 1;

package/src/commands/doctor.js

@@ -36,6 +36,7 @@ import { getDirSetupChecks } from "../checks/dir-setup.js";
 import { getProjectChecks } from "../checks/project-checks.js";
 import { getHardwareChecks } from "../checks/hardware.js";
 import { getOrphanChecks } from "../checks/orphans.js";
+import { getMethodChecks } from "../checks/method.js";
 
 /**
  * Build the list of Check objects applicable to the current config.
@@ -74,6 +75,7 @@ function buildChecks(config, { projectOnly = false } = {}) {
     ...getSqueezrChecks(),
     ...getAiTrashChecks(),
     ...getOrphanChecks(),
+    ...getMethodChecks(),
     ...getQmdChecks(),
     ...getRagHooksChecks({ projectDir }),
     ...getProjectChecks({ projectDir }),

package/src/commands/hu.js

@@ -175,11 +175,13 @@ export async function huCommand({ config = null, action, args = [], flags = {} }
     // silently moving the first hit could move the wrong card.
     const byId = [];
     const byShort = [];
+    const running = [];
     for (const meta of await listPlans(projectDir)) {
       const plan = await loadPlan(projectDir, meta.planId);
       for (const hu of plan.hus || []) {
         if (hu.id === ref) byId.push({ plan, hu });
         else if (hu.short_id === ref) byShort.push({ plan, hu });
+        if (hu.status === "running") running.push(hu);
       }
     }
     const matches = byId.length > 0 ? byId : byShort;
@@ -189,6 +191,16 @@ export async function huCommand({ config = null, action, args = [], flags = {} }
       throw new Error(`"${ref}" is ambiguous (${matches.length} matches: ${ids}) — use the full id`);
     }
     const { plan, hu } = matches[0];
+    // KJC-TSK-0688 (MG-C): the nudge fires AT the deviation — a second
+    // concurrent task belongs in its own lane, not in the shared tree.
+    const others = running.filter((r) => r.id !== hu.id);
+    if (status === "running" && hu.status !== "running" && others.length > 0) {
+      const slug = String(hu.short_id || hu.id).toLowerCase();
+      console.warn(
+        `⚠ ${others.map((r) => r.short_id || r.id).join(", ")} ${others.length === 1 ? "is" : "are"} already running — `
+        + `a second concurrent task should live in its own lane: kj worktree start ${slug}`
+      );
+    }
     updateHuStatus(plan, hu.id, status);
     await savePlan(projectDir, plan);
     return emit({ id: hu.id, status }, `✓ ${hu.short_id || hu.id} → ${status}`);

package/src/commands/review-gate.js

@@ -11,6 +11,25 @@ import { runOneShotReview } from "../review/one-shot-review.js";
 import { runSolomonArbitration } from "../review/solomon-arbitration.js";
 import { ensureGateTrackable } from "../review/gate-gitignore.js";
 import { runSonarPregate, formatSonarFinding } from "../review/sonar-pregate.js";
+import { checkCardFirst } from "../review/card-first.js";
+import { checkTestsWithCode } from "../review/tests-with-code.js";
+
+// KJC-TSK-0686 (MG-A): card-first is a gate, not a habit. Runs on --staged
+// (before spending sonar/reviewer effort) AND on --check — the pre-commit
+// hook already calls --check, so existing projects gain the gate with a
+// simple package update, no hook regeneration.
+async function enforceCardFirst({ config, projectDir }) {
+  const branchRes = await runCommand("git", ["rev-parse", "--abbrev-ref", "HEAD"]);
+  const branch = branchRes.stdout?.trim() || "HEAD";
+  const card = await checkCardFirst({ config, projectDir, branch });
+  if (card.mode === "warn") console.log(`⚠ card-first: ${card.reason}`);
+  if (card.mode === "exempt" && card.reason.includes("KJ_ALLOW_NO_CARD")) console.log(`⚠ card-first exempt: ${card.reason}`);
+  if (!card.ok) {
+    console.log(`✗ card-first gate: ${card.reason}`);
+    process.exitCode = 1;
+  }
+  return card;
+}
 
 // Raw git always — never a wrapped/compressing runner (KJC-BUG-0115).
 async function rawDiff(range, extraArgs = []) {
@@ -87,6 +106,32 @@ export async function reviewGateCommand({ config, logger = null, flags = {} }) {
 
   const diff = await rawDiff(flags.range);
 
+  const card = await enforceCardFirst({ config, projectDir });
+  if (!card.ok) return { verdict: "rejected", reviewer: "card-first", issues: [{ severity: "high", description: card.reason }] };
+
+  // KJC-TSK-0687 (MG-B): the verifiable half of TDD — sources without a
+  // single test change warn (block via method_gates.tests_with_code).
+  const changedFiles = (await rawDiff(flags.range, ["--name-only"])).split("\n").map((f) => f.trim()).filter(Boolean);
+
+  // KJC-TSK-0688 (MG-C): oversized-diff nudge — informative only; the
+  // project's CI owns any hard budget. Sums additions from --numstat.
+  const sizeWarn = config?.method_gates?.pr_size_warn ?? 150;
+  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);
+    if (added > sizeWarn) {
+      console.log(`⚠ pr-size: ${added} lines added (guideline ~${sizeWarn}) — atomic PRs review better; consider splitting (method_gates.pr_size_warn to tune)`);
+    }
+  }
+  const tests = checkTestsWithCode({ config, stagedFiles: changedFiles });
+  if (tests.mode === "warn") console.log(`⚠ tests-with-code: ${tests.reason}`);
+  if (tests.mode === "exempt") console.log(`⚠ tests-with-code exempt: ${tests.reason}`);
+  if (!tests.ok) {
+    console.log(`✗ tests-with-code gate: ${tests.reason}`);
+    process.exitCode = 1;
+    return { verdict: "rejected", reviewer: "tests-with-code", issues: [{ severity: "high", description: tests.reason }] };
+  }
+
   if (flags.check) {
     const res = await checkVerdict(projectDir, diff);
     console.log(res.ok
@@ -102,8 +147,7 @@ export async function reviewGateCommand({ config, logger = null, flags = {} }) {
   // the cross-AI reviewer weighs them. Unavailable sonar degrades loudly.
   let task = flags.task;
   if (flags.sonar !== false) {
-    const files = (await rawDiff(flags.range, ["--name-only"])).split("\n").map((f) => f.trim()).filter(Boolean);
-    const pre = await runSonarPregate({ config, stagedFiles: files, logger });
+    const pre = await runSonarPregate({ config, stagedFiles: changedFiles, logger });
     if (!pre.available) {
       console.log(`⚠ sonar pre-gate skipped: ${pre.reason}`);
     } else {

package/src/config/defaults.js

@@ -67,6 +67,19 @@ const DEFAULTS = {
   // "none": Karajan does not run without a board.
   state_backend: "hu-board",
   board: { name: null },
+  // Method gates (KJC-PCS-0068): rules climb from playbook text to
+  // deterministic enforcement. card_first: "auto" = block with hu-board
+  // (fully verifiable), warn with planning-game/external (presence only);
+  // explicit "warn" | "block" override. Release branches are exempt.
+  method_gates: {
+    card_first: "auto",
+    card_first_exempt_branches: ["chore/release-"],
+    // MG-B: source changes without a test change — "warn" | "block".
+    tests_with_code: "warn",
+    // MG-C: informative nudge when the staged diff exceeds this many
+    // added lines (0 disables). The project's CI owns any hard budget.
+    pr_size_warn: 150
+  },
   review_rules: "./.karajan/review-rules.md",
   coder_rules: "./.karajan/coder-rules.md",
   base_branch: "main",

package/src/review/card-first.js

@@ -0,0 +1,85 @@
+/**
+ * Card-first gate (KJC-TSK-0686, MG-A of épica KJC-PCS-0068): the rule
+ * that work starts from a card moves from playbook text into the gate.
+ * hu-board → the branch must reference a LIVE card (block by default);
+ * planning-game/external → card-shaped reference required (warn default,
+ * block via method_gates.card_first). Exemptions explicit and visible:
+ * base branch, configured prefixes (releases), KJ_ALLOW_NO_CARD=1.
+ */
+import { listPlans, loadPlan } from "../plan/plan-store.js";
+import { escapeRegExp } from "../utils/escape-regexp.js";
+
+const LIVE_STATUSES = new Set(["pending", "running", "failed"]);
+// Card-shaped reference: LIN-123, bb-002 and multi-segment ids like
+// KJC-TSK-0684 (optional middle segments) — tight enough to skip slugs.
+// Shared with the method report (MG-D): one pattern, one truth.
+export const CARD_REF_RE = /\b[a-z][a-z0-9]{1,9}(?:-[a-z][a-z0-9]{1,9})*-\d{1,6}\b/i;
+const DEFAULT_EXEMPT_PREFIXES = ["chore/release-"];
+
+// Token-boundary match: BB-002 must not satisfy a branch that actually
+// references BB-0022 (reviewer catch — substring matching allowed work
+// onto the wrong card).
+function refInBranch(ref, branchLower) {
+  return new RegExp(`(^|[^a-z0-9])${escapeRegExp(String(ref).toLowerCase())}([^a-z0-9]|$)`).test(branchLower);
+}
+
+async function findLiveCardInBranch(projectDir, branch) {
+  const needle = branch.toLowerCase();
+  // Scan EVERY match before deciding: any live reference satisfies the
+  // gate; a closed one is only reported when no live match exists
+  // (reviewer catch — first-match could reject a branch that also
+  // references a live card, depending on plan iteration order).
+  let closedHit = null;
+  for (const meta of await listPlans(projectDir)) {
+    const plan = await loadPlan(projectDir, meta.planId);
+    for (const h of plan.hus || []) {
+      for (const ref of [h.short_id, h.id]) {
+        if (ref && refInBranch(ref, needle)) {
+          if (LIVE_STATUSES.has(h.status)) return { ref, live: true, status: h.status };
+          closedHit = { ref, live: false, status: h.status };
+        }
+      }
+    }
+  }
+  return closedHit;
+}
+
+export async function checkCardFirst({ config = {}, projectDir = process.cwd(), branch, env = process.env }) {
+  if (env.KJ_ALLOW_NO_CARD === "1") {
+    return { ok: true, mode: "exempt", reason: "KJ_ALLOW_NO_CARD=1 (explicit escape hatch)" };
+  }
+  const exempt = config.method_gates?.card_first_exempt_branches || DEFAULT_EXEMPT_PREFIXES;
+  if (exempt.some((p) => branch.startsWith(p))) {
+    return { ok: true, mode: "exempt", reason: `branch prefix exempt (${branch.split("/")[0]}/…)` };
+  }
+  // The base branch belongs to the branch-first gate — card-first here
+  // would only double-report (and HEAD covers detached checkouts in CI).
+  if ([config.base_branch || "main", "main", "master", "HEAD"].includes(branch)) {
+    return { ok: true, mode: "exempt", reason: "base branch — the branch-first gate owns this case" };
+  }
+
+  const backend = config.state_backend || "hu-board";
+  const policy = config.method_gates?.card_first || "auto";
+
+  if (backend === "hu-board") {
+    const hit = await findLiveCardInBranch(projectDir, branch);
+    if (hit?.live) return { ok: true, mode: "pass", ref: hit.ref };
+    const effective = policy === "auto" ? "block" : policy;
+    const reason = hit
+      ? `branch references ${hit.ref} but its card is "${hit.status}" — card-first needs a live card (reopen it or create one: kj hu add)`
+      : `no live card referenced in branch "${branch}" — create it first (kj hu add "…" --id <REF>) and name the branch after it`;
+    return effective === "block"
+      ? { ok: false, mode: "block", reason }
+      : { ok: true, mode: "warn", reason };
+  }
+
+  // planning-game / external: presence check only — liveness lives in the
+  // project's own board, out of local reach.
+  if (CARD_REF_RE.test(branch)) return { ok: true, mode: "pass", ref: branch.match(CARD_REF_RE)[0] };
+  const effective = policy === "auto" ? "warn" : policy;
+  const boardName = config.board?.name || backend;
+  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)`;
+  return effective === "block"
+    ? { ok: false, mode: "block", reason }
+    : { ok: true, mode: "warn", reason };
+}

package/src/review/tests-with-code.js

@@ -0,0 +1,33 @@
+/**
+ * Tests-with-code gate (KJC-TSK-0687, MG-B of épica KJC-PCS-0068). The
+ * verifiable half of TDD is deterministic: a staged diff that touches
+ * source files without touching a single test warns — or blocks, via
+ * `method_gates.tests_with_code`. Test-FIRST remains the reviewer's
+ * judgment; test-PRESENT belongs to the gate. Patterns come from the
+ * project's own `development.*` config (same ones headless enforces).
+ * KJ_ALLOW_NO_TESTS=1 is the explicit escape hatch.
+ */
+
+const DEFAULT_TEST_PATTERNS = ["/tests/", "/__tests__/", ".test.", ".spec."];
+const DEFAULT_SOURCE_EXTS = [".js", ".jsx", ".ts", ".tsx", ".py", ".go", ".java", ".rb", ".php", ".cs"];
+
+export function checkTestsWithCode({ config = {}, stagedFiles = [], env = process.env }) {
+  if (env.KJ_ALLOW_NO_TESTS === "1") {
+    return { ok: true, mode: "exempt", reason: "KJ_ALLOW_NO_TESTS=1 (explicit escape hatch)" };
+  }
+  const patterns = config.development?.test_file_patterns || DEFAULT_TEST_PATTERNS;
+  const exts = config.development?.source_file_extensions || DEFAULT_SOURCE_EXTS;
+  // Staged paths are repo-relative (no leading slash) — normalize so the
+  // "/tests/" style patterns also match the top-level tests directory.
+  const isTest = (f) => patterns.some((p) => `/${f}`.includes(p));
+  const sources = stagedFiles.filter((f) => !isTest(f) && exts.some((e) => f.endsWith(e)));
+  const hasTests = stagedFiles.some(isTest);
+
+  if (sources.length === 0 || hasTests) return { ok: true, mode: "pass" };
+
+  const policy = config.method_gates?.tests_with_code || "warn";
+  const reason = `source changes without any test change (${sources.slice(0, 5).join(", ")}${sources.length > 5 ? "…" : ""}) — the failing test comes first; add one or KJ_ALLOW_NO_TESTS=1 for a deliberate exception`;
+  return policy === "block"
+    ? { ok: false, mode: "block", sources, reason }
+    : { ok: true, mode: "warn", sources, reason };
+}