@karajan-family/code 4.21.0

package/src/review/scope-filter.js

@@ -0,0 +1,152 @@
+/**
+ * Scope filter — auto-defers reviewer blocking issues that reference
+ * files NOT present in the diff.  This prevents reviewer scope drift
+ * (flagging missing features, unchanged code, future tasks) from
+ * stalling the pipeline.
+ *
+ * Deferred issues are NOT forgotten — they are tracked in the session
+ * as technical debt that should be resolved in future iterations or
+ * follow-up tasks.  The coder and planner receive context about what
+ * was deferred and why.
+ */
+
+/**
+ * Extract the set of changed file paths from a unified diff string.
+ */
+export function extractDiffFiles(diff) {
+  const files = new Set();
+  for (const line of (diff || "").split("\n")) {
+    // Match "+++ b/path" lines in unified diff
+    const m = /^\+\+\+ b\/(.+)/.exec(line);
+    if (m) files.add(m[1]);
+  }
+  return files;
+}
+
+/**
+ * Determine whether a blocking issue is within scope of the diff.
+ *
+ * An issue is considered IN scope when:
+ * - It has no `file` field (general concern about the diff)
+ * - Its `file` matches one of the changed files (exact or suffix match)
+ * - It references a pattern present in the diff content itself
+ *
+ * An issue is OUT of scope when:
+ * - It explicitly references a file NOT in the diff
+ */
+export function isIssueInScope(issue, diffFiles, diffContent) {
+  const file = (issue.file || "").trim();
+
+  // No file specified — the reviewer is commenting on the diff generally
+  if (!file) return true;
+
+  // Direct match
+  if (diffFiles.has(file)) return true;
+
+  // Suffix match (reviewer might use full path vs relative)
+  for (const df of diffFiles) {
+    if (df.endsWith(file) || file.endsWith(df)) return true;
+  }
+
+  // Check if the file path appears anywhere in the diff content
+  // (covers cases where the file is referenced in imports/requires)
+  if (diffContent?.includes(file)) return true;
+
+  return false;
+}
+
+/**
+ * Filter a review result, demoting out-of-scope blocking issues to
+ * non-blocking suggestions.
+ *
+ * Returns { review, demoted, deferred, allDemoted } where:
+ * - review: the filtered review (may flip approved to true)
+ * - demoted: array of original issues that were demoted
+ * - deferred: structured deferred issues with metadata for session tracking
+ * - allDemoted: true if ALL blocking issues were out of scope
+ */
+export function filterReviewScope(review, diff) {
+  if (!review || review.approved) {
+    return { review, demoted: [], deferred: [], allDemoted: false };
+  }
+
+  const diffFiles = extractDiffFiles(diff);
+
+  // If we can't parse diff files, don't filter (safety)
+  if (diffFiles.size === 0) {
+    return { review, demoted: [], deferred: [], allDemoted: false };
+  }
+
+  const inScope = [];
+  const demoted = [];
+
+  for (const issue of review.blocking_issues || []) {
+    if (isIssueInScope(issue, diffFiles, diff)) {
+      inScope.push(issue);
+    } else {
+      demoted.push(issue);
+    }
+  }
+
+  if (demoted.length === 0) {
+    return { review, demoted: [], deferred: [], allDemoted: false };
+  }
+
+  const demotedSuggestions = demoted.map(
+    (issue) => `[auto-demoted] ${issue.file || "unknown"}: ${issue.description || issue.id || "no description"}`
+  );
+
+  const filtered = {
+    ...review,
+    blocking_issues: inScope,
+    non_blocking_suggestions: [
+      ...(review.non_blocking_suggestions || []),
+      ...demotedSuggestions
+    ]
+  };
+
+  // If no in-scope blocking issues remain, auto-approve
+  const allDemoted = inScope.length === 0;
+  if (allDemoted) {
+    filtered.approved = true;
+    filtered.summary = `${review.summary || ""} [Auto-approved: ${demoted.length} out-of-scope issue(s) demoted to suggestions]`.trim();
+  }
+
+  // Build structured deferred issues for session tracking
+  const deferred = demoted.map((issue) => ({
+    id: issue.id || null,
+    file: issue.file || null,
+    severity: issue.severity || "medium",
+    description: issue.description || "no description",
+    suggested_fix: issue.suggested_fix || null,
+    deferred_at: new Date().toISOString(),
+    reason: "out_of_scope"
+  }));
+
+  return { review: filtered, demoted, deferred, allDemoted };
+}
+
+/**
+ * Build a human-readable summary of deferred issues for injection
+ * into coder/planner prompts so they are aware of the tech debt.
+ */
+export function buildDeferredContext(deferredIssues) {
+  if (!deferredIssues?.length) return "";
+
+  const lines = [
+    "## Deferred reviewer concerns (technical debt)",
+    "The following issues were flagged by the reviewer but deferred because they are outside the current diff scope.",
+    "You do NOT need to fix them now, but be aware of them:",
+    ""
+  ];
+
+  for (const issue of deferredIssues) {
+    const file = issue.file ? `\`${issue.file}\`` : "general";
+    const fix = issue.suggested_fix ? ` — Suggestion: ${issue.suggested_fix}` : "";
+    lines.push(`- [${issue.severity}] ${file}: ${issue.description}${fix}`);
+  }
+
+  lines.push("", "If your current changes naturally address any of these, great. Otherwise, they will be tracked for future resolution.");
+
+  return lines.join("\n");
+}

package/src/review/snapshot-diff.js

@@ -0,0 +1,122 @@
+/**
+ * Git-free diff generation using filesystem snapshots.
+ *
+ * Takes a snapshot of project files (path → content hash), then compares
+ * a later snapshot to generate a unified diff. Works on any OS, no git needed.
+ */
+
+import { readdir, readFile, stat } from "node:fs/promises";
+import { join, relative } from "node:path";
+import { createHash } from "node:crypto";
+
+const DEFAULT_IGNORE = new Set([
+  "node_modules", ".git", ".kj", ".karajan", "dist", "build",
+  ".next", ".nuxt", ".svelte-kit", "__pycache__", ".venv",
+  "coverage", ".nyc_output", ".reviews"
+]);
+
+const MAX_FILE_SIZE = 512 * 1024; // 512KB — skip large files
+
+/**
+ * Scan a directory recursively and return a Map of relative path → content hash.
+ * @param {string} rootDir
+ * @returns {Promise<Map<string, string>>} path → sha256 hash
+ */
+export async function takeSnapshot(rootDir) {
+  const snapshot = new Map();
+  await scanDir(rootDir, rootDir, snapshot);
+  return snapshot;
+}
+
+async function scanDir(dir, rootDir, snapshot) {
+  let entries;
+  try {
+    entries = await readdir(dir, { withFileTypes: true });
+  } catch { return; }
+
+  for (const entry of entries) {
+    if (DEFAULT_IGNORE.has(entry.name) || entry.name.startsWith(".")) continue;
+
+    const fullPath = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      await scanDir(fullPath, rootDir, snapshot);
+    } else if (entry.isFile()) {
+      try {
+        const s = await stat(fullPath);
+        if (s.size > MAX_FILE_SIZE) continue;
+        const content = await readFile(fullPath);
+        const hash = createHash("sha256").update(content).digest("hex");
+        snapshot.set(relative(rootDir, fullPath), hash);
+      } catch { /* skip unreadable files */ }
+    }
+  }
+}
+
+/**
+ * Compare two snapshots and generate a unified diff string.
+ * @param {Map<string, string>} before — snapshot before coder
+ * @param {Map<string, string>|null} after — snapshot after coder (null = read from disk)
+ * @param {string} rootDir — project root (for reading file contents)
+ * @returns {Promise<string>} unified diff text
+ */
+export async function generateSnapshotDiff(before, after, rootDir) {
+  if (!after) {
+    after = await takeSnapshot(rootDir);
+  }
+
+  const lines = [];
+
+  // New files (in after but not before)
+  for (const [path, _hash] of after) {
+    if (!before.has(path)) {
+      const content = await safeRead(join(rootDir, path));
+      if (content !== null) {
+        lines.push(`diff --snapshot a/${path} b/${path}`);
+        lines.push("new file");
+        lines.push(`--- /dev/null`);
+        lines.push(`+++ b/${path}`);
+        for (const line of content.split("\n")) {
+          lines.push(`+${line}`);
+        }
+        lines.push("");
+      }
+    }
+  }
+
+  // Modified files (in both, different hash)
+  for (const [path, hash] of after) {
+    if (before.has(path) && before.get(path) !== hash) {
+      const content = await safeRead(join(rootDir, path));
+      if (content !== null) {
+        lines.push(`diff --snapshot a/${path} b/${path}`);
+        lines.push("modified file");
+        lines.push(`--- a/${path}`);
+        lines.push(`+++ b/${path}`);
+        // Show full new content (we don't have the old content)
+        for (const line of content.split("\n")) {
+          lines.push(`+${line}`);
+        }
+        lines.push("");
+      }
+    }
+  }
+
+  // Deleted files (in before but not after)
+  for (const [path] of before) {
+    if (!after.has(path)) {
+      lines.push(`diff --snapshot a/${path} b/${path}`);
+      lines.push("deleted file");
+      lines.push(`--- a/${path}`);
+      lines.push(`+++ /dev/null`);
+      lines.push("");
+    }
+  }
+
+  return lines.join("\n");
+}
+
+async function safeRead(filePath) {
+  try {
+    return await readFile(filePath, "utf-8");
+  } catch { return null; }
+}

package/src/review/solomon-arbitration.js

@@ -0,0 +1,113 @@
+/**
+ * Solomon arbitration (AB-E, KJC-TSK-0651) — when the brain (host agent)
+ * disagrees with the reviewer's verdict, a THIRD AI arbitrates and its
+ * ruling is recorded in the verdict store, tied to the exact diff.
+ *
+ * Hard rules:
+ *  - brain ≠ reviewer ≠ solomon. Two-agent machines get an actionable
+ *    error — self-arbitration would void the whole point.
+ *  - Security issues from the reviewer are NEVER overridable (inherited
+ *    from the pipeline's Solomon): the arbiter is not even consulted.
+ *  - An approve ruling writes an approved verdict (`solomon:<agent>`) for
+ *    the same diff hash, so the pre-commit gate opens structurally; a
+ *    reject keeps it closed. Both record the full conflict for audit.
+ */
+import { createAgent } from "../agents/index.js";
+import { parseMaybeJsonString } from "./parser.js";
+import { detectAvailableAgents, detectHostAgent } from "../utils/agent-detect.js";
+import { diffHash, loadVerdict, saveVerdict } from "./verdict-store.js";
+
+const SECURITY_PATTERN = /injection|xss|csrf|secret|credential|password|token leak|auth(entication|orization)?|crypt|session|sanitiz|traversal|rce\b/i;
+
+// Structured signal first (`category: "security"` — part of the reviewer's
+// JSON schema since AB-E); the free-text pattern stays as a fail-closed net
+// for verdicts recorded before the schema carried categories.
+function isSecurityIssue(issue) {
+  return issue.category === "security"
+    || SECURITY_PATTERN.test(`${issue.id || ""} ${issue.description || ""}`);
+}
+
+export async function pickThirdParty({ config, hostAgent, reviewerAgent, detectAgents = detectAvailableAgents }) {
+  const excluded = new Set([hostAgent, reviewerAgent]);
+  const configured = config?.roles?.solomon?.provider;
+  const agents = await detectAgents();
+  const candidates = agents.filter((a) => a.available && !excluded.has(a.name)).map((a) => a.name);
+  if (configured && candidates.includes(configured)) return configured;
+  return candidates[0] || null;
+}
+
+export async function runSolomonArbitration({
+  diff, position, config, logger, projectDir,
+  hostAgent = detectHostAgent(),
+  createAgentFn = createAgent,
+  detectAgents = detectAvailableAgents,
+}) {
+  if (!position || !position.trim()) {
+    throw new Error("kj solomon requires --position \"<why you disagree with the reviewer>\"");
+  }
+  const verdict = await loadVerdict(projectDir, diffHash(diff));
+  if (!verdict || verdict.verdict !== "rejected") {
+    throw new Error("nothing to arbitrate — there is no rejected verdict for the current diff (run `kj review --staged` first)");
+  }
+
+  // ABSOLUTE RULE: security findings are never overridable.
+  const securityIssues = (verdict.issues || []).filter(isSecurityIssue);
+  if (securityIssues.length > 0) {
+    const record = await saveVerdict(projectDir, diff, {
+      ...verdict,
+      arbitration: { position, ruling: "reject", reasoning: "security issues from the reviewer are never overridable", solomon: null },
+    });
+    return { ruling: "reject", reasoning: "security issues are never overridable — fix them", solomon: null, record };
+  }
+
+  const solomon = await pickThirdParty({ config, hostAgent, reviewerAgent: verdict.reviewer, detectAgents });
+  if (!solomon) {
+    throw new Error(
+      `arbitration requires a third AI distinct from the brain (${hostAgent || "unknown"}) and the reviewer (${verdict.reviewer}) — install a third agent CLI`
+    );
+  }
+
+  const prompt = [
+    "You are Solomon, the neutral arbiter between two AIs in a coding workflow.",
+    "The reviewer REJECTED a diff; the orchestrating brain DISAGREES. Decide who is right.",
+    "Never approve to save time or effort — only if the reviewer's objections are genuinely wrong or immaterial for this diff.",
+    'Return only one JSON object: {"ruling":"approve"|"reject","reasoning":string}. "approve" = the brain is right, the diff may ship as-is. "reject" = the reviewer is right, the brain must fix the issues.',
+    "", "## Reviewer's blocking issues",
+    JSON.stringify(verdict.issues || [], null, 2),
+    "", "## Brain's position", position,
+    "", "## The diff under dispute", diff,
+  ].join("\n");
+
+  logger?.info?.(`kj solomon: brain=${hostAgent || "?"} vs reviewer=${verdict.reviewer} → arbiter=${solomon}`);
+  const agent = createAgentFn(solomon, config, logger);
+  const result = await agent.reviewTask({ prompt, role: "solomon" });
+  if (!result?.ok) {
+    // KJC-BUG-0121 layer 3: a binary on PATH is not an OPERATIONAL arbiter
+    // (dead account tier, auth, trust). Fail with the way out, not just the
+    // wreckage: name the other agents that could arbitrate instead.
+    const others = (await detectAgents())
+      .filter((a) => a.available && a.name !== solomon && a.name !== hostAgent && a.name !== verdict.reviewer)
+      .map((a) => a.name);
+    const hint = others.length > 0
+      ? `If ${solomon} is not operational on this machine (account tier, auth, workspace trust), set roles.solomon.provider in your kj config to another agent: ${others.join(", ")}.`
+      : `No other agent CLI on this machine can arbitrate (needs one distinct from brain "${hostAgent}" and reviewer "${verdict.reviewer}") — install a third agent CLI or fix ${solomon}.`;
+    throw new Error(`solomon ${solomon} failed: ${String(result?.error || "no output").slice(0, 400)}\n${hint}`);
+  }
+  const parsed = parseMaybeJsonString(result.output);
+  if (!parsed || !["approve", "reject"].includes(parsed.ruling)) {
+    throw new Error(`solomon ${solomon} returned no parseable ruling`);
+  }
+
+  const arbitration = {
+    position, ruling: parsed.ruling, reasoning: parsed.reasoning || "", solomon,
+    originalVerdict: { reviewer: verdict.reviewer, issues: verdict.issues },
+  };
+  const record = parsed.ruling === "approve"
+    ? await saveVerdict(projectDir, diff, {
+      verdict: "approved", reviewer: `solomon:${solomon}`, host: hostAgent || null,
+      issues: [], summary: `Arbitration overrode ${verdict.reviewer}'s rejection: ${parsed.reasoning || ""}`.trim(), arbitration,
+    })
+    : await saveVerdict(projectDir, diff, { ...verdict, arbitration });
+
+  return { ruling: parsed.ruling, reasoning: parsed.reasoning || "", solomon, record };
+}

package/src/review/sonar-pregate.js

@@ -0,0 +1,63 @@
+/**
+ * Sonar pre-gate for `kj review --staged` (KJC-TSK-0676, user request
+ * 2026-07-23). With the brain outside the core (v4), skipping sonar is one
+ * decision away — proven the day the brain itself shipped 3 sonar issues in
+ * new code. Hung off the review gate, it becomes a gate, not discipline:
+ * deterministic findings on the STAGED files come back before any AI
+ * verdict, and BLOCKER/CRITICAL ones reject without spending reviewer
+ * tokens. Unavailable sonar degrades loudly ({available:false, reason}) —
+ * a laptop without Docker still commits.
+ */
+
+import { runSonarScan } from "../sonar/scanner.js";
+import { getOpenIssues } from "../sonar/api.js";
+import { acquireToolLock } from "../utils/tool-governor.js";
+
+const BLOCKING_SEVERITIES = new Set(["BLOCKER", "CRITICAL"]);
+
+/** Repo-relative path of a sonar issue (component is "<projectKey>:<path>"). */
+export function issueFile(issue) {
+  const component = String(issue?.component || "");
+  const idx = component.indexOf(":");
+  return idx === -1 ? component : component.slice(idx + 1);
+}
+
+/** One printable line per finding: (SEVERITY) [file:line] rule — message. */
+export function formatSonarFinding(issue) {
+  const line = issue.line ? `:${issue.line}` : "";
+  return `(${issue.severity}) [${issueFile(issue)}${line}] ${issue.rule} — ${issue.message}`;
+}
+
+/**
+ * Scan the project (single-flight via the tool governor) and return the
+ * open issues that live on the staged files, split by blocking severity.
+ * Every failure path degrades to {available:false, reason} — the pre-gate
+ * never breaks the review, it only refuses to stay silent.
+ */
+export async function runSonarPregate({ config, stagedFiles = [], logger = null }) {
+  if (config?.review_gate?.sonar === false) {
+    return { available: false, reason: "disabled in config (review_gate.sonar: false)" };
+  }
+  let lock = null;
+  try {
+    lock = await acquireToolLock("sonar-scanner", { timeoutMs: 300_000 });
+    const scan = await runSonarScan(config);
+    if (!scan.ok) {
+      return { available: false, reason: (scan.stderr || scan.stdout || "sonar scan failed").trim() };
+    }
+    const res = await getOpenIssues(config, scan.projectKey);
+    const staged = new Set(stagedFiles);
+    const onStaged = (res.issues || []).filter((i) => staged.has(issueFile(i)));
+    return {
+      available: true,
+      blocking: onStaged.filter((i) => BLOCKING_SEVERITIES.has(String(i.severity).toUpperCase())),
+      advisory: onStaged.filter((i) => !BLOCKING_SEVERITIES.has(String(i.severity).toUpperCase())),
+      totalProject: res.total ?? (res.issues || []).length,
+    };
+  } catch (err) {
+    logger?.warn?.(`[sonar-pregate] ${err.message}`);
+    return { available: false, reason: err.message };
+  } finally {
+    lock?.release?.();
+  }
+}

package/src/review/tdd-discipline.js

@@ -0,0 +1,90 @@
+// TDD discipline gate (KJC-TSK-0398 PR1).
+// PR1 ships the pure decision logic with injected runTests/stashFiles
+// helpers. PR2 ships the real surgical stash. PR3 wires the gate into
+// the pipeline behind `development.require_red_then_green`.
+
+const PARSERS = {
+  vitest: parseVitestFailures,
+  jest: parseVitestFailures,
+  pytest: parsePytestFailures,
+};
+
+function parseVitestFailures(output) {
+  const failures = new Set();
+  for (const line of String(output || "").split("\n")) {
+    const m = line.match(/^\s*(?:FAIL|×|✖)\s+(\S+)/);
+    if (m) failures.add(m[1].trim());
+  }
+  return failures;
+}
+
+function parsePytestFailures(output) {
+  const failures = new Set();
+  for (const line of String(output || "").split("\n")) {
+    const m = line.match(/^FAILED\s+(\S+)/);
+    if (m) failures.add(m[1].trim());
+  }
+  return failures;
+}
+
+function anyNewTestIn(failures, testFiles) {
+  return [...failures].some((f) => testFiles.some((t) => f.includes(t) || t.includes(f)));
+}
+
+export async function verifyTddDiscipline({
+  projectDir,
+  sourceFiles = [],
+  testFiles = [],
+  framework = null,
+  runTests,
+  stashFiles,
+  restoreFiles,
+} = {}) {
+  if (sourceFiles.length === 0) {
+    return { ok: true, reason: "no_source_changes", sourceFiles, testFiles };
+  }
+  if (testFiles.length === 0) {
+    return { ok: true, reason: "no_test_changes", sourceFiles, testFiles };
+  }
+
+  const parser = framework ? PARSERS[framework] : null;
+  if (!parser) {
+    return {
+      ok: true,
+      reason: "framework_unsupported",
+      sourceFiles,
+      testFiles,
+      warning: `tdd-discipline: framework "${framework || "unknown"}" has no failure parser; gate skipped`,
+    };
+  }
+
+  let stashToken = null;
+  try {
+    stashToken = await stashFiles(sourceFiles);
+    const before = await runTests(projectDir);
+    if (!anyNewTestIn(parser(before.output), testFiles)) {
+      return {
+        ok: false,
+        reason: "tests_pass_without_impl",
+        sourceFiles,
+        testFiles,
+        message:
+          "TDD discipline violation: new tests pass without the implementation. Tests must fail first (red), then pass (green).",
+      };
+    }
+  } finally {
+    if (stashToken) await restoreFiles(stashToken);
+  }
+
+  const after = await runTests(projectDir);
+  if (anyNewTestIn(parser(after.output), testFiles)) {
+    return {
+      ok: false,
+      reason: "tests_fail_with_impl",
+      sourceFiles,
+      testFiles,
+      message: "TDD discipline violation: new tests still fail with the implementation present.",
+    };
+  }
+  return { ok: true, reason: "red_then_green_verified", sourceFiles, testFiles };
+}

package/src/review/tdd-policy.js

@@ -0,0 +1,69 @@
+function extractChangedFiles(diff) {
+  const files = new Set();
+  const lines = String(diff || "").split("\n");
+  for (const line of lines) {
+    // Support both git diff and snapshot diff formats
+    if (!line.startsWith("diff --git ") && !line.startsWith("diff --snapshot ")) continue;
+    const parts = line.split(" ");
+    const b = parts[3] || "";
+    if (b.startsWith("b/")) files.add(b.slice(2));
+  }
+  return [...files];
+}
+
+function isTestFile(file, patterns = []) {
+  const normalized = `/${file}`;
+  return patterns.some((pattern) => normalized.includes(pattern));
+}
+
+function isSourceFile(file, extensions = []) {
+  return extensions.some((ext) => file.endsWith(ext));
+}
+
+const SKIP_TDD_TASK_TYPES = new Set(["doc", "infra", "no-code"]);
+
+const DEFAULT_TEST_PATTERNS = ["/tests/", "/__tests__/", ".test.", ".spec.", "/src/test/", "/test/", "Test.java", "Test.kt", "test_", "_test.py", "_test.go", "Test.cs", "_spec.rb", "Test.php", "_test.dart", "Tests.swift"];
+const DEFAULT_SOURCE_EXTENSIONS = [".js", ".jsx", ".ts", ".tsx", ".py", ".go", ".java", ".kt", ".rb", ".php", ".cs", ".rs", ".swift", ".dart"];
+
+export function evaluateTddPolicy(diff, developmentConfig = {}, untrackedFiles = [], taskType = null) {
+  if (taskType && SKIP_TDD_TASK_TYPES.has(taskType)) {
+    return { ok: true, reason: "tdd_not_applicable_for_task_type", sourceFiles: [], testFiles: [] };
+  }
+
+  const requireTestChanges = developmentConfig.require_test_changes !== false;
+  const patterns = developmentConfig.test_file_patterns || DEFAULT_TEST_PATTERNS;
+  const extensions = developmentConfig.source_file_extensions || DEFAULT_SOURCE_EXTENSIONS;
+
+  const diffFiles = extractChangedFiles(diff);
+  const extra = Array.isArray(untrackedFiles) ? untrackedFiles : [];
+  const files = [...new Set([...diffFiles, ...extra])];
+  const sourceFiles = files.filter((f) => isSourceFile(f, extensions) && !isTestFile(f, patterns));
+  const testFiles = files.filter((f) => isTestFile(f, patterns));
+
+  if (!requireTestChanges) {
+    return {
+      ok: true,
+      reason: "test_changes_not_required",
+      sourceFiles,
+      testFiles
+    };
+  }
+
+  if (sourceFiles.length === 0) {
+    const reason = files.length === 0 ? "no_diff_available" : "no_source_changes";
+    return { ok: true, reason, sourceFiles, testFiles };
+  }
+
+  if (testFiles.length === 0) {
+    return {
+      ok: false,
+      reason: "source_changes_without_tests",
+      sourceFiles,
+      testFiles,
+      message:
+        "TDD policy violation: source code changed without test changes. Add/adjust tests first, then implementation."
+    };
+  }
+
+  return { ok: true, reason: "tests_present", sourceFiles, testFiles };
+}

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 };
+}