karajan-code 4.51.1 → 4.53.0

package/src/review/branch-overlap.js

@@ -0,0 +1,40 @@
+/**
+ * KJC-TSK-1052 (TEAM-F): a team on one repo collides in the merge when two
+ * branches change the same files. kj warns at review time: the remote branches
+ * still in progress (commits outside origin/<base>, active in the last days)
+ * whose changes share files with what the commit stages. A warning, never a block.
+ */
+import { runCommand } from "../utils/process.js";
+
+const MAX_AGE_DAYS = 14;
+const MAX_BRANCHES = 20;
+
+/**
+ * @returns {Promise<{branch: string, author: string, files: string[]}[]>}
+ */
+export async function branchOverlaps({ projectDir, stagedFiles, base = "main", now = Date.now(), run = runCommand }) {
+  const git = async (args) => {
+    const res = await run("git", ["-C", projectDir, ...args]);
+    return res.exitCode === 0 ? res.stdout.trim() : null;
+  };
+  const baseRef = `origin/${base}`;
+  if (stagedFiles.length === 0 || (await git(["rev-parse", "--verify", "--quiet", baseRef])) === null) return [];
+  const current = await git(["rev-parse", "--abbrev-ref", "HEAD"]);
+  const refs = (await git(["for-each-ref", "--sort=-committerdate", "--format=%(refname:short)|%(committerdate:unix)|%(authorname)", "refs/remotes/origin"])) ?? "";
+  const staged = new Set(stagedFiles);
+  const candidates = refs.split("\n").filter(Boolean)
+    .map((line) => { const [branch, when, author] = line.split("|"); return { branch, when: Number(when) * 1000, author }; })
+    .filter((r) => r.branch !== baseRef && r.branch !== "origin/HEAD" && r.branch !== `origin/${current}`)
+    .filter((r) => now - r.when < MAX_AGE_DAYS * 86_400_000)
+    .slice(0, MAX_BRANCHES);
+  const overlaps = [];
+  for (const { branch, author } of candidates) {
+    if (Number(await git(["rev-list", "--count", `${baseRef}..${branch}`])) === 0) continue;
+    const files = ((await git(["diff", "--name-only", `${baseRef}...${branch}`])) ?? "").split("\n").filter((f) => staged.has(f));
+    if (files.length > 0) overlaps.push({ branch, author, files });
+  }
+  return overlaps;
+}
+
+/** The kj review warning, one line per branch. */
+export const formatOverlaps = (overlaps) => overlaps.map((o) => `⚠ ${o.branch} (${o.author}) also changes ${o.files.join(", ")}: coordinate before the merge collides`);

package/src/review/correction-rounds.js

@@ -0,0 +1,40 @@
+/**
+ * KJC-TSK-1017: a rejection followed by an approval is the method working: the
+ * second AI exists to catch what the first one misses, by how models work, not
+ * because the coder did it badly. kj names it a review correction with its
+ * round count, never a coder error.
+ */
+import fs from "node:fs/promises";
+import path from "node:path";
+import { runCommand } from "../utils/process.js";
+
+export const correctionNote = (rounds) => (rounds > 0
+  ? `review correction: ${rounds} round(s) before this approval, the cross-AI method working`
+  : "");
+
+/** Rejections on the branch since its last approval, the current record aside. */
+export function rejectionsBeforeApproval(records, { branch, hash }) {
+  const mine = records
+    .filter((r) => r.branch === branch && r.diffHash !== hash)
+    .toSorted((a, b) => String(a.timestamp).localeCompare(String(b.timestamp)));
+  let rounds = 0;
+  for (const r of mine) rounds = r.verdict === "approved" ? 0 : rounds + 1;
+  return rounds;
+}
+
+export async function branchOf(projectDir, run = runCommand) {
+  const res = await run("git", ["-C", projectDir, "rev-parse", "--abbrev-ref", "HEAD"]);
+  return res.exitCode === 0 ? res.stdout.trim() : null;
+}
+
+export async function reviewCorrectionRounds(projectDir, record) {
+  if (!record?.branch) return 0;
+  const dir = path.join(projectDir, ".karajan", "reviews");
+  const names = await fs.readdir(dir).catch(() => []);
+  const records = [];
+  for (const name of names.filter((n) => n.endsWith(".json"))) {
+    // A report, not a gate: an unreadable verdict file is left out of the count.
+    try { records.push(JSON.parse(await fs.readFile(path.join(dir, name), "utf8"))); } catch { /* see above */ }
+  }
+  return rejectionsBeforeApproval(records, { branch: record.branch, hash: record.diffHash });
+}

package/src/review/dep-cooldown.js

@@ -0,0 +1,87 @@
+/**
+ * KJC-TSK-0722 (step 1): supply-chain campaigns (Shai-Hulud, CanisterWorm) are
+ * caught in their first hours, so a dependency published minutes ago is the
+ * riskiest one to take. kj reads what a package-lock.json diff installs and
+ * asks npm how old each version is. A signal, never a crash: without the
+ * registry, the package is listed as unverified with the reason.
+ */
+import { runCommand } from "../utils/process.js";
+
+export const DEFAULT_COOLDOWN_HOURS = 72;
+// npm view per package: a lockfile refresh of hundreds is said, not queried one by one.
+const MAX_QUERIES = 40;
+
+const KEY = /^[ +]\s*"(?:[^"]*\/)?node_modules\/((?:@[^/"]+\/)?[^/"]+)":\s*\{/;
+const VERSION = /^\+\s*"version":\s*"([^"]+)"/;
+
+/** The packages a diff of package-lock.json adds or moves to another version. */
+export function lockfileChanges(diff) {
+  const changes = [];
+  for (const chunk of String(diff ?? "").split(/^diff --git /m)) {
+    if (!/^a\/(?:\S*\/)?package-lock\.json /.test(chunk)) continue;
+    let current = null;
+    for (const line of chunk.split("\n")) {
+      const key = KEY.exec(line);
+      if (key) { current = key[1]; continue; }
+      const version = VERSION.exec(line);
+      if (version && current) { changes.push({ name: current, version: version[1] }); current = null; }
+    }
+  }
+  return changes;
+}
+
+async function publishedAt({ name, version }, run) {
+  const res = await run("npm", ["view", `${name}@${version}`, "time", "--json"]);
+  if (res.exitCode !== 0) throw new Error((res.stderr || res.stdout || "npm view failed").trim());
+  const when = Date.parse(JSON.parse(res.stdout || "{}")[version]);
+  if (Number.isNaN(when)) throw new Error(`npm gives no publish time for ${version}`);
+  return when;
+}
+
+export const COOLDOWN_RULE_ID = "method.dep_cooldown";
+
+/**
+ * KJC-TSK-1056: with method_gates.dep_cooldown: block, a young dependency stops
+ * the review; only a live human grant on method.dep_cooldown lifts it. What
+ * could not be verified (no registry) never blocks: a false positive would
+ * stop legitimate work for a network blip.
+ */
+export function cooldownGate({ result, mode, standingExceptions = [], now = new Date() }) {
+  if (mode !== "block" || result.young.length === 0) return { block: false };
+  const grant = standingExceptions.find((e) => e.rule_id === COOLDOWN_RULE_ID && new Date(e.expiresAt).getTime() > now.getTime());
+  if (grant) return { block: false, grant };
+  const list = result.young.map((p) => `${p.name}@${p.version} (${p.hours} h)`).join(", ");
+  return { block: true, reason: `${result.young.length} dependency(ies) under the cooldown: ${list} (method_gates.dep_cooldown: block). Wait it out, pin an older version, or a human lifts it: kj policy grant --rule ${COOLDOWN_RULE_ID} --until <iso> --reason "<why>"` };
+}
+
+/** What kj review prints, and the note the reviewer gets; empty when there is nothing to say. */
+export function formatCooldown({ young, unverified, skipped = 0 }, thresholdHours = DEFAULT_COOLDOWN_HOURS) {
+  const lines = [
+    ...young.map((p) => `⚠ supply-chain cooldown: ${p.name}@${p.version} was published ${p.hours} h ago (under ${thresholdHours} h): campaigns are caught in their first hours`),
+    ...unverified.map((p) => `⚠ supply-chain cooldown: ${p.name}@${p.version} unverified (${p.reason})`),
+    ...(skipped > 0 ? [`⚠ supply-chain cooldown: ${skipped} packages changed (a regenerated lockfile?), too many to check one by one: none was checked`] : []),
+  ];
+  const note = young.length === 0 ? "" : `Dependencies published under ${thresholdHours} h ago (weigh them as a supply-chain risk): ${young.map((p) => `${p.name}@${p.version} (${p.hours} h)`).join(", ")}`;
+  return { lines, note };
+}
+
+/**
+ * Over MAX_QUERIES changed packages (a regenerated lockfile) none is queried:
+ * one line says so, instead of a line per package and a call per package.
+ * @returns {Promise<{young: {name, version, hours}[], unverified: {name, version, reason}[], skipped?: number}>}
+ */
+export async function cooldownAdvisories(diff, { thresholdHours = DEFAULT_COOLDOWN_HOURS, run = runCommand, now = Date.now() } = {}) {
+  const changes = lockfileChanges(diff);
+  if (changes.length > MAX_QUERIES) return { young: [], unverified: [], skipped: changes.length };
+  const young = [];
+  const unverified = [];
+  for (const pkg of changes) {
+    try {
+      const hours = Math.floor((now - await publishedAt(pkg, run)) / 3_600_000);
+      if (hours < thresholdHours) young.push({ ...pkg, hours });
+    } catch (err) {
+      unverified.push({ ...pkg, reason: err.message });
+    }
+  }
+  return { young, unverified };
+}

package/src/review/one-shot-review.js

@@ -12,12 +12,13 @@ import { createAgent } from "../agents/index.js";
 import { resolveRole } from "../config/role-resolver.js";
 import { buildReviewerPrompt } from "../prompts/reviewer.js";
 import { resolveReviewProfile } from "./profiles.js";
-import { parseMaybeJsonString, normalizeReviewPayload } from "./parser.js";
+import { parseReviewVerdict } from "./parser.js";
 import { detectAvailableAgents, detectHostAgent } from "../utils/agent-detect.js";
 import { saveVerdict, diffHash } from "./verdict-store.js";
 import { summarizeGeneratedFiles } from "./prompt-diff.js";
 import { reportUnparseableVerdict } from "./unparseable-verdict.js";
 import { detectWorkspace } from "./workspace.js";
+import { branchOf } from "./correction-rounds.js";
 import { isQuotaExhausted, candidateStatus, pickQuotaFallback, formatCandidateMenu } from "./reviewer-fallback.js";
 
 // Cross-AI preference when the configured reviewer IS the host.
@@ -116,7 +117,7 @@ export async function runOneShotReview({
   // back, wrapper and all. Yesterday's fix taught normalizeReviewPayload to unwrap {ok, result},
   // but this path never called it, so the bug survived with a green test on the wrong function.
   // A test can only prove the code it actually exercises.
-  const parsed = normalizeReviewPayload(parseMaybeJsonString(result.output));
+  const parsed = parseReviewVerdict(result.output);
   if (!parsed || typeof parsed.approved !== "boolean") {
     // KJC-BUG-0146: keep the answer. Throwing it away is what left eight occurrences undiagnosed.
     throw new Error(await reportUnparseableVerdict({ projectDir, reviewer: activeReviewer, output: result.output, hash: diffHash(diff) }));
@@ -128,6 +129,8 @@ export async function runOneShotReview({
     host: hostAgent || null,
     // KJC-TSK-0680: where the review ran — makes any isolation claim auditable.
     workspace: await detectWorkspace(projectDir),
+    // KJC-TSK-1017: the branch lets an approval count the corrections before it.
+    branch: await branchOf(projectDir),
     issues: parsed.blocking_issues || [],
     suggestions: parsed.non_blocking_suggestions || [],
     summary: parsed.summary || parsed.raw_summary || "",

package/src/review/parser.js

@@ -10,6 +10,27 @@ export function parseMaybeJsonString(value) {
   return extractFirstJson(value);
 }
 
+/**
+ * KJC-BUG-0357 (#2151): claude's reviewTask answers with its whole stream-json
+ * event stream, which opens with hook and init events, so its first JSON is no
+ * answer. The answer is the text of the final `result` event; any other output
+ * is returned as it came.
+ */
+export function agentAnswerText(raw) {
+  if (typeof raw !== "string") return raw;
+  const lines = raw.trim().split("\n");
+  for (let i = lines.length - 1; i >= 0; i -= 1) {
+    const event = extractFirstJson(lines[i]);
+    if (event?.type === "result" && typeof event.result === "string") return event.result;
+  }
+  return raw;
+}
+
+/** The review verdict in an agent's answer, or null: the one path kj review reads it by. */
+export function parseReviewVerdict(output) {
+  return normalizeReviewPayload(parseMaybeJsonString(agentAnswerText(output)));
+}
+
 function isReviewPayload(obj) {
   return obj?.approved !== undefined && obj?.blocking_issues !== undefined;
 }

package/src/review/publish-pr.js

@@ -0,0 +1,54 @@
+/**
+ * KJC-TSK-0913: the cross-AI verdict kj holds for each commit of a PR, published
+ * on the PR as ONE GitHub review (event COMMENT), so the review that already
+ * happened counts in reviews.totalCount instead of looking like a blind merge.
+ * A loose conversation comment does not count, so it is never used.
+ */
+import { runCommand } from "../utils/process.js";
+import { diffHash, loadVerdict } from "./verdict-store.js";
+
+const MARKER = (head) => `<!-- kj-review head=${head} -->`;
+
+// gh runs in the project's own directory, so it reads and writes the same repo the verdicts belong to.
+async function json(run, cmd, args, cwd) {
+  const res = await run(cmd, args, { cwd });
+  if (res.exitCode !== 0) throw new Error(`${cmd} ${args.slice(0, 3).join(" ")} failed: ${(res.stderr || res.stdout || "").trim()}`);
+  return JSON.parse(res.stdout || "null");
+}
+
+/** The verdict of a commit: the one recorded for the diff it brought, staged byte for byte. */
+async function verdictOf(projectDir, sha, run) {
+  const res = await run("git", ["-C", projectDir, "diff", `${sha}^`, sha]);
+  return res.exitCode === 0 && res.stdout ? loadVerdict(projectDir, diffHash(res.stdout)) : null;
+}
+
+/**
+ * @returns {Promise<{published: boolean, commits?: number, reason?: string}>}
+ */
+export async function publishPrReview({ projectDir, pr, run = runCommand }) {
+  const info = await json(run, "gh", ["pr", "view", String(pr), "--json", "headRefOid,commits"], projectDir);
+  const rows = [];
+  const uncovered = [];
+  for (const c of info.commits ?? []) {
+    const v = await verdictOf(projectDir, c.oid, run);
+    if (v?.verdict === "approved") rows.push({ ...c, v });
+    else uncovered.push(`${c.oid.slice(0, 7)} (${c.messageHeadline})`);
+  }
+  if (uncovered.length > 0) throw new Error(`PR #${pr}: ${uncovered.length} commit(s) without an approved verdict of their exact diff, nothing published: ${uncovered.join(", ")}`);
+  const reviews = await json(run, "gh", ["api", `repos/{owner}/{repo}/pulls/${pr}/reviews`], projectDir);
+  if ((reviews ?? []).some((r) => String(r.body ?? "").includes(MARKER(info.headRefOid)))) {
+    return { published: false, reason: `a kj review for head ${info.headRefOid.slice(0, 7)} is already published` };
+  }
+  const body = [
+    `Cross-AI review by Karajan, one verdict per commit, each bound to the exact diff it brought.`,
+    "",
+    ...rows.map((r) => {
+      const summary = r.v.summary ? ". " + r.v.summary : "";
+      return `- \`${r.oid.slice(0, 7)}\` ${r.messageHeadline}: approved by ${r.v.reviewer} (diff ${r.v.diffHash.slice(0, 12)})${summary}`;
+    }),
+    "",
+    MARKER(info.headRefOid),
+  ].join("\n");
+  await json(run, "gh", ["api", "-X", "POST", `repos/{owner}/{repo}/pulls/${pr}/reviews`, "-f", "event=COMMENT", "-f", `commit_id=${info.headRefOid}`, "-f", `body=${body}`], projectDir);
+  return { published: true, commits: rows.length };
+}

package/src/review/solomon-arbitration.js

@@ -13,7 +13,7 @@
  *    reject keeps it closed. Both record the full conflict for audit.
  */
 import { createAgent } from "../agents/index.js";
-import { parseMaybeJsonString } from "./parser.js";
+import { parseMaybeJsonString, agentAnswerText } from "./parser.js";
 import { detectAvailableAgents, detectHostAgent } from "../utils/agent-detect.js";
 import { diffHash, loadVerdict, saveVerdict } from "./verdict-store.js";
 import { summarizeGeneratedFiles } from "./prompt-diff.js";
@@ -95,7 +95,7 @@ export async function runSolomonArbitration({
       : `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);
+  const parsed = parseMaybeJsonString(agentAnswerText(result.output));
   if (!parsed || !["approve", "reject"].includes(parsed.ruling)) {
     throw new Error(`solomon ${solomon} returned no parseable ruling`);
   }

package/src/review/verdict-store.js

@@ -14,6 +14,7 @@ import fs from "node:fs/promises";
 import path from "node:path";
 import { runCommand } from "../utils/process.js";
 import { kjStamp, stampDiffers, stampLabel } from "./kj-provenance.js";
+import { sourceFilesOf } from "./tests-with-code.js";
 
 const STORE_DIR = path.join(".karajan", "reviews");
 
@@ -107,13 +108,15 @@ export async function stampStagedVerdict({ projectDir, reviewer, summary = "", s
   }
   // KJC-BUG-0294: the pipeline commits by path (`--only`); the verdict must bind
   // to that diff, not to other files the person had staged.
-  const res = await runCommand("git", ["diff", "--cached", ...(paths?.length ? ["--", ...paths] : [])], { cwd: dir });
+  const pathArgs = paths?.length ? ["--", ...paths] : [];
+  const res = await runCommand("git", ["diff", "--cached", ...pathArgs], { cwd: dir });
   if (res.exitCode !== 0 || !res.stdout?.trim()) return { stamped: false };
+  // A deleted file cannot be indexed, so it never counts as a source to prove.
+  const names = sonar?.indexed ? (await runCommand("git", ["diff", "--cached", "--name-only", "--diff-filter=ACMR", ...pathArgs], { cwd: dir })).stdout.split("\n").filter(Boolean) : [];
   await saveVerdict(dir, res.stdout, {
     verdict: "approved", reviewer, host: "kj-pipeline", issues: [], summary,
-    // KJC-TSK-0838: what the pipeline's sonar stage saw, so --check can tell
-    // a run whose gate ran from one that skipped it.
-    ...(sonar ? { sonar } : {}),
+    // KJC-TSK-0838/0839: what the pipeline's sonar stage saw, proved per staged source.
+    ...(sonar ? { sonar: coverageFor(sonar, names) } : {}),
   });
   return { stamped: true };
 }
@@ -122,8 +125,8 @@ export async function stampStagedVerdict({ projectDir, reviewer, summary = "", s
  * KJC-TSK-0838: the pipeline sonar stage result as a verdict sonar block.
  * SKIPPED (no remote, no key) or absent is `ran:false` WITH the reason — the
  * pre-commit check then refuses code, as it would for any other diff.
- * Coverage lists stay empty: the pipeline scans the whole project, and the
- * per-file proof (verbose index) is not wired into SonarRole yet.
+ * KJC-TSK-0839: a stage that ran carries the files its verbose scan indexed;
+ * stampStagedVerdict turns them into covered/uncovered for the staged sources.
  */
 export function pipelineSonarBlock(stageResult) {
   if (!stageResult) return { ran: false, source: "pipeline", reason: "the pipeline recorded no sonar stage" };
@@ -131,10 +134,19 @@ export function pipelineSonarBlock(stageResult) {
     return { ran: false, source: "pipeline", reason: stageResult.reason || stageResult.error || "the sonar stage did not run" };
   }
   return {
-    ran: true, source: "pipeline", projectKey: stageResult.projectKey || null, gateStatus: stageResult.gateStatus, covered: [], uncovered: [],
+    ran: true, source: "pipeline", projectKey: stageResult.projectKey || null, gateStatus: stageResult.gateStatus, indexed: stageResult.indexedFiles ?? [],
   };
 }
 
+/** KJC-TSK-0839: the per-source proof of a pipeline block, against the files this commit stages. */
+function coverageFor(sonar, stagedNames) {
+  if (!sonar?.ran || !Array.isArray(sonar.indexed)) return sonar;
+  const { indexed, ...block } = sonar;
+  const seen = new Set(indexed);
+  const { sources } = sourceFilesOf({}, stagedNames);
+  return { ...block, covered: sources.filter((f) => seen.has(f)), uncovered: sources.filter((f) => !seen.has(f)) };
+}
+
 /**
  * Is there an APPROVED verdict for exactly this diff?
  * @returns {Promise<{ok: boolean, verdict?: object, reason?: string}>}

package/src/roles/sonar-role.js

@@ -1,5 +1,5 @@
 import { BaseRole } from "./base-role.js";
-import { runSonarScan } from "../sonar/scanner.js";
+import { indexedFilesFrom, runSonarScan } from "../sonar/scanner.js";
 import { getQualityGateStatus, getOpenIssues } from "../sonar/api.js";
 import { shouldBlockByProfile, summarizeIssues } from "../sonar/enforcer.js";
 
@@ -20,7 +20,8 @@ export class SonarRole extends BaseRole {
   }
 
   async execute(_input) {
-    const scan = await runSonarScan(this.config);
+    // KJC-TSK-0839: verbose, so the scanner names every file it indexed.
+    const scan = await runSonarScan(this.config, null, { verbose: true });
 
     if (!scan.ok) {
       return {
@@ -53,6 +54,7 @@ export class SonarRole extends BaseRole {
       ok: !blocking,
       result: {
         projectKey: scan.projectKey,
+        indexedFiles: [...indexedFilesFrom(scan.stdout)],
         gateStatus: gate.status,
         conditions: gate.conditions || [],
         issues,

package/src/sonar/api.js

@@ -124,6 +124,13 @@ export async function getQualityGateStatus(config, projectKey = null) {
   }
 }
 
+/** KJC-TSK-1051 (TEAM-E): the names of the quality profiles the project runs on. */
+export async function getProjectQualityProfiles(config, projectKey = null) {
+  const effectiveProjectKey = await resolveSonarProjectKey(config, { projectKey, cwd: queryCwd(config) });
+  const body = await sonarFetch(config, `/api/qualityprofiles/search?project=${encodeURIComponent(effectiveProjectKey)}`);
+  return (JSON.parse(body).profiles ?? []).map((p) => p.name);
+}
+
 export async function getOpenIssues(config, projectKey = null) {
   const effectiveProjectKey = await resolveSonarProjectKey(config, { projectKey, cwd: queryCwd(config) });
   // KJC-BUG-0339 (#2099): current SonarQube ignores projectKeys and answered with

package/src/utils/injection-guard.js

@@ -8,52 +8,52 @@
  * @module utils/injection-guard
  */
 
-/** Phrases that attempt to override system/reviewer instructions. */
-const DIRECTIVE_PATTERNS = [
-  /ignore\s+(all\s+)?(previous|prior|above|earlier)\s+(instructions?|rules?|prompts?|guidelines?)/i,
-  /disregard\s+(all\s+)?(previous|prior|above|earlier)\s+(instructions?|rules?|prompts?)/i,
-  /forget\s+(all\s+)?(previous|prior|your)\s+(instructions?|rules?|context)/i,
-  /override\s+(the\s+)?(system|reviewer|review)\s+(prompt|instructions?|rules?)/i,
-  /do\s+not\s+follow\s+(the\s+)?(above|previous|system)\s+(instructions?|rules?)/i,
-  /new\s+instructions?\s*:/i,
-  /system\s*:\s*you\s+are/i,
-  /\bact\s+as\s+(a\s+)?(different|new|my|an?\s+)/i,
-  /you\s+are\s+now\s+(a\s+)?/i,
-  /from\s+now\s+on\s*(,|\s)?\s*you\s+(will|should|must|are)/i,
-  /pretend\s+(you\s+are|to\s+be)/i,
-  /respond\s+(only\s+)?with\s+["']?approved["']?/i,
-  /always\s+(return|respond|output)\s+.*approved/i,
-  /set\s+approved\s*[=:]\s*true/i,
-  /\bapproved["']?\s*:\s*true\b.*ignore/i,
-  /output\s+the\s+following\s+json/i,
-  /return\s+this\s+exact\s+(json|response|output)/i,
-];
-
-/** Unicode categories that can hide or disguise content. */
-const UNICODE_PATTERNS = [
-  /[\u200B-\u200F]/,   // zero-width spaces, LTR/RTL marks
-  /[\u202A-\u202E]/,   // bidi embedding/override
-  /[\u2066-\u2069]/,   // bidi isolate
-  /[\uFEFF]/,          // BOM mid-text
-  /[\u00AD]{3,}/,      // repeated soft hyphens
-  /[\u2060-\u2064]/,   // invisible operators
-  /[\u{E0000}-\u{E007F}]/u, // tag characters
-];
-
-/** Maximum comment block size (chars) before flagging. */
-const MAX_COMMENT_BLOCK = 2000;
+import { readFileSync } from "node:fs";
 
 /**
- * Comment block patterns for common languages.
- * Each regex captures the full block content.
+ * KJC-TSK-0703: the patterns live in injection-patterns.json, the family's
+ * versioned catalog (karajan-radar reads it from Python). Only constructs both
+ * JavaScript RegExp and Python re understand are accepted.
  */
-const COMMENT_BLOCK_RE = [
-  /\/\*[\s\S]{0,20000}?\*\//g,        // C-style /* ... */
-  /<!--[\s\S]{0,20000}?-->/g,         // HTML <!-- ... -->
-  /"""\s*[\s\S]{0,20000}?\s*"""/g,    // Python docstrings
-  /'''\s*[\s\S]{0,20000}?\s*'''/g,    // Python docstrings (single)
-  /=begin[\s\S]{0,20000}?=end/g,      // Ruby block comments
+const NON_PORTABLE = [
+  [/\\u\{/, "\\u{...} escapes (put the literal character in the JSON instead)"],
+  [/\\[pP]\{/, "\\p{...} property escapes"],
+  [/\(\?<(?![=!])/, "a named group (Python spells it (?P<name>)"],
+  [/\\k</, "a named backreference"],
 ];
+const PORTABLE_FLAGS = new Set(["i", "m", "s", "u"]);
+
+/** Throws, naming the pattern, when an entry would not work outside JavaScript. */
+export function assertPortable({ id, expression, flags = "" }) {
+  for (const flag of flags) {
+    if (!PORTABLE_FLAGS.has(flag)) throw new Error(`${id}: flag "${flag}" is not portable (only i, m, s, u)`);
+  }
+  for (const [construct, what] of NON_PORTABLE) {
+    if (construct.test(expression)) throw new Error(`${id}: ${what} is not portable: ${expression}`);
+  }
+  return new RegExp(expression, flags);
+}
+
+/** The catalog compiled per type; a missing or broken catalog fails loudly, never scans empty. */
+// The SEA bundle has no sibling files: scripts/esbuild-sea.config.mjs inlines this exact read.
+const readCatalog = () => readFileSync(new URL("./injection-patterns.json", import.meta.url), "utf8");
+
+export function loadInjectionCatalog() {
+  const catalog = JSON.parse(readCatalog());
+  const compiled = { directive: [], unicode: [], comment_block: [], maxCommentBlock: catalog.max_comment_block, version: catalog.version };
+  for (const entry of catalog.patterns) {
+    const re = assertPortable(entry);
+    // Comment blocks are walked match by match: the global flag is the engine's, not the catalog's.
+    compiled[entry.type].push(entry.type === "comment_block" ? new RegExp(re.source, `${re.flags}g`) : re);
+  }
+  return compiled;
+}
+
+const CATALOG = loadInjectionCatalog();
+const DIRECTIVE_PATTERNS = CATALOG.directive;
+const UNICODE_PATTERNS = CATALOG.unicode;
+const MAX_COMMENT_BLOCK = CATALOG.maxCommentBlock;
+const COMMENT_BLOCK_RE = CATALOG.comment_block;
 
 /**
  * @typedef {Object} InjectionFinding
@@ -118,7 +118,7 @@ export function scanForInjection(text, opts = {}) {
   for (const re of COMMENT_BLOCK_RE) {
     let m;
     while ((m = re.exec(text)) !== null) {
-      if (m[0].length > maxBlock) {
+      if (proseLength(m[0]) > maxBlock) {
         findings.push({
           type: "comment_block",
           pattern: `block ${m[0].length} chars (max ${maxBlock})`,
@@ -175,6 +175,22 @@ export function scanDiff(diff, opts = {}) {
 
 // --- Helpers ---
 
+/**
+ * KJC-TSK-0743: the size of a comment block that counts against the limit. In a
+ * JSDoc block (`/**`), tag lines (`* @typedef`, `* @property`...) are structure,
+ * not prose: they are left out unless a single one runs past 300 chars. Any
+ * instruction inside a tag line is still caught by the directive patterns.
+ */
+const JSDOC_TAG_LINE = /^\s*\*\s*@[A-Za-z]+/;
+const MAX_TAG_LINE = 300;
+function proseLength(block) {
+  if (!block.startsWith("/**")) return block.length;
+  return block
+    .split("\n")
+    .filter((line) => !(JSDOC_TAG_LINE.test(line) && line.length <= MAX_TAG_LINE))
+    .join("\n").length;
+}
+
 function excerpt(text, index) {
   const start = Math.max(0, index - 20);
   const end = Math.min(text.length, index + 100);

package/src/utils/injection-patterns.json

@@ -0,0 +1,36 @@
+{
+  "$comment": "KJC-TSK-0703: the canonical prompt-injection catalog of the karajan family. Data, not code: each language keeps only its small scanning engine. Expressions must stay portable (JavaScript RegExp and Python re): invisible characters go as literal characters (JSON escapes), never as regex escapes like \\u{...}; flags are only i, m, s, u. Bump version on any change.",
+  "version": "1.0.0",
+  "max_comment_block": 2000,
+  "patterns": [
+    { "id": "directive-ignore-previous", "type": "directive", "expression": "ignore\\s+(all\\s+)?(previous|prior|above|earlier)\\s+(instructions?|rules?|prompts?|guidelines?)", "flags": "i", "severity": "high", "why": "Tells the model to drop the instructions it was given, the classic override." },
+    { "id": "directive-disregard-previous", "type": "directive", "expression": "disregard\\s+(all\\s+)?(previous|prior|above|earlier)\\s+(instructions?|rules?|prompts?)", "flags": "i", "severity": "high", "why": "Same override as ignore-previous, worded to slip past a single keyword." },
+    { "id": "directive-forget-instructions", "type": "directive", "expression": "forget\\s+(all\\s+)?(previous|prior|your)\\s+(instructions?|rules?|context)", "flags": "i", "severity": "high", "why": "Asks the model to wipe its context or rules before obeying new ones." },
+    { "id": "directive-override-system", "type": "directive", "expression": "override\\s+(the\\s+)?(system|reviewer|review)\\s+(prompt|instructions?|rules?)", "flags": "i", "severity": "high", "why": "Names the system or reviewer prompt as something to replace." },
+    { "id": "directive-do-not-follow", "type": "directive", "expression": "do\\s+not\\s+follow\\s+(the\\s+)?(above|previous|system)\\s+(instructions?|rules?)", "flags": "i", "severity": "high", "why": "Negates the instructions above it, steering the model away from its task." },
+    { "id": "directive-new-instructions", "type": "directive", "expression": "new\\s+instructions?\\s*:", "flags": "i", "severity": "medium", "why": "Announces a fresh instruction block inside content that should carry none." },
+    { "id": "directive-system-you-are", "type": "directive", "expression": "system\\s*:\\s*you\\s+are", "flags": "i", "severity": "high", "why": "Forges a system message that redefines who the model is." },
+    { "id": "directive-act-as", "type": "directive", "expression": "\\bact\\s+as\\s+(a\\s+)?(different|new|my|an?\\s+)", "flags": "i", "severity": "medium", "why": "Role reassignment: asks the model to become another persona." },
+    { "id": "directive-you-are-now", "type": "directive", "expression": "you\\s+are\\s+now\\s+(a\\s+)?", "flags": "i", "severity": "medium", "why": "Role reassignment phrased as a fact the model should accept." },
+    { "id": "directive-from-now-on", "type": "directive", "expression": "from\\s+now\\s+on\\s*(,|\\s)?\\s*you\\s+(will|should|must|are)", "flags": "i", "severity": "medium", "why": "Installs a standing behaviour change for the rest of the conversation." },
+    { "id": "directive-pretend", "type": "directive", "expression": "pretend\\s+(you\\s+are|to\\s+be)", "flags": "i", "severity": "medium", "why": "Role-play framing used to step around the model's instructions." },
+    { "id": "directive-respond-approved", "type": "directive", "expression": "respond\\s+(only\\s+)?with\\s+[\"']?approved[\"']?", "flags": "i", "severity": "high", "why": "Dictates the reviewer's verdict instead of letting it judge the change." },
+    { "id": "directive-always-approved", "type": "directive", "expression": "always\\s+(return|respond|output)\\s+.*approved", "flags": "i", "severity": "high", "why": "Fixes the output to approved whatever the content says." },
+    { "id": "directive-set-approved", "type": "directive", "expression": "set\\s+approved\\s*[=:]\\s*true", "flags": "i", "severity": "high", "why": "Tries to write the verdict field directly." },
+    { "id": "directive-approved-true-ignore", "type": "directive", "expression": "\\bapproved[\"']?\\s*:\\s*true\\b.*ignore", "flags": "i", "severity": "high", "why": "A forged approved verdict next to an instruction to ignore something." },
+    { "id": "directive-output-json", "type": "directive", "expression": "output\\s+the\\s+following\\s+json", "flags": "i", "severity": "medium", "why": "Hands the model a ready answer to emit instead of its own." },
+    { "id": "directive-return-exact", "type": "directive", "expression": "return\\s+this\\s+exact\\s+(json|response|output)", "flags": "i", "severity": "medium", "why": "Same as output-json: a scripted response smuggled into the content." },
+    { "id": "unicode-zero-width", "type": "unicode", "expression": "[\u200B-\u200F]", "flags": "", "severity": "high", "why": "Zero-width spaces and LTR/RTL marks hide text a human reviewer cannot see." },
+    { "id": "unicode-bidi-embedding", "type": "unicode", "expression": "[\u202A-\u202E]", "flags": "", "severity": "high", "why": "Bidi embedding and override characters reorder what is displayed (Trojan Source)." },
+    { "id": "unicode-bidi-isolate", "type": "unicode", "expression": "[\u2066-\u2069]", "flags": "", "severity": "high", "why": "Bidi isolates, the other half of the Trojan Source trick." },
+    { "id": "unicode-bom-midtext", "type": "unicode", "expression": "[\uFEFF]", "flags": "", "severity": "medium", "why": "A byte order mark in the middle of text is invisible and has no honest use there." },
+    { "id": "unicode-soft-hyphens", "type": "unicode", "expression": "[\u00AD]{3,}", "flags": "", "severity": "low", "why": "Runs of soft hyphens split words so keyword filters miss them." },
+    { "id": "unicode-invisible-operators", "type": "unicode", "expression": "[\u2060-\u2064]", "flags": "", "severity": "medium", "why": "Word joiner and invisible operators carry no visible glyph." },
+    { "id": "unicode-tag-characters", "type": "unicode", "expression": "[\uDB40\uDC00-\uDB40\uDC7F]", "flags": "u", "severity": "high", "why": "Unicode tag characters (U+E0000 to U+E007F) can encode a whole hidden instruction." },
+    { "id": "comment-block-c", "type": "comment_block", "expression": "/\\*[\\s\\S]{0,20000}?\\*/", "flags": "", "severity": "low", "why": "An oversized C-style comment can hide a payload addressed to the model." },
+    { "id": "comment-block-html", "type": "comment_block", "expression": "<!--[\\s\\S]{0,20000}?-->", "flags": "", "severity": "low", "why": "An oversized HTML comment is invisible when rendered but read by the model." },
+    { "id": "comment-block-docstring-double", "type": "comment_block", "expression": "\"\"\"\\s*[\\s\\S]{0,20000}?\\s*\"\"\"", "flags": "", "severity": "low", "why": "An oversized Python docstring can carry instructions as prose." },
+    { "id": "comment-block-docstring-single", "type": "comment_block", "expression": "'''\\s*[\\s\\S]{0,20000}?\\s*'''", "flags": "", "severity": "low", "why": "Same as the double-quoted docstring, with single quotes." },
+    { "id": "comment-block-ruby", "type": "comment_block", "expression": "=begin[\\s\\S]{0,20000}?=end", "flags": "", "severity": "low", "why": "An oversized Ruby block comment, the same hiding place." }
+  ]
+}