karajan-code 4.21.0 → 4.23.0

package/src/privacy/scan.js

@@ -52,12 +52,25 @@ const SECRET_HEURISTICS = [
   { type: "conn-string", re: /\b[a-z][a-z0-9+.-]*:\/\/[^\s:@/]+:([^\s@/]+)@/gi },
 ];
 
+// KJC-TSK-0797 (epic KJC-PCS-0082) — context BEFORE generics, measured twice:
+// GREBLA's pinned Actions reported as phone numbers, and this repo's own
+// workflow pinning flagged twelve times in one PR. A git object id is not a
+// phone; an email on an RFC 2606 documentation domain is not a person. Both
+// are blanked before redactPII and COUNTED, so a clean result can say
+// "nothing found" or "found and discarded by context" — never the same thing.
+// The personal denylist runs before this: the user's own datum always blocks.
+const CONTEXT_DISCARDS = [
+  { type: "git-sha", re: /\b(?:[0-9a-f]{64}|[0-9a-f]{40})\b/g },
+  { type: "doc-domain-email", re: /\b[A-Za-z0-9._%+-]+@(?:[A-Za-z0-9-]+\.)*(?:example\.(?:com|org|net)|test|invalid|localhost|example)\b/g },
+];
+
 /**
  * Scan a text. Returns findings — denylist hits as `severity:"block"`
  * (masked value), generic PII as `severity:"warn"` (line already redacted).
  */
 export function scanText(text, { list = loadPrivacyList(), source = "<text>" } = {}) {
   const findings = [];
+  let discarded = 0;
   String(text).split("\n").forEach((line, i) => {
     let probe = line;
     for (const a of list.allow) probe = probe.split(a).join(" ");
@@ -86,6 +99,10 @@ export function scanText(text, { list = loadPrivacyList(), source = "<text>" } =
         re.lastIndex = m.index + m[0].length;
       }
     }
+    for (const { re } of CONTEXT_DISCARDS) {
+      re.lastIndex = 0;
+      probe = probe.replace(re, (m) => { discarded += 1; return " ".repeat(m.length); });
+    }
     const red = redactPII(probe);
     if (red.total > 0) {
       for (const [type, n] of Object.entries(red.counts)) {
@@ -93,12 +110,14 @@ export function scanText(text, { list = loadPrivacyList(), source = "<text>" } =
       }
     }
   });
+  findings.discardedByContext = discarded;
   return findings;
 }
 
 /** Scan files/dirs recursively (skips node_modules/.git, binaries, big files). */
 export function scanPaths(paths, { list = loadPrivacyList() } = {}) {
   const findings = [];
+  let discarded = 0;
   const visit = (p) => {
     if (!existsSync(p)) return;
     // Skip symlinks: an ancestor link recurses forever; an outside link ships nothing.
@@ -113,8 +132,11 @@ export function scanPaths(paths, { list = loadPrivacyList() } = {}) {
     if (BINARY_EXT.has(extname(p).toLowerCase()) || st.size > MAX_FILE_BYTES) return;
     const content = readFileSync(p);
     if (content.includes(0)) return; // binary sniff: NUL byte
-    findings.push(...scanText(content.toString("utf8"), { list, source: p }));
+    const fileFindings = scanText(content.toString("utf8"), { list, source: p });
+    discarded += fileFindings.discardedByContext || 0;
+    findings.push(...fileFindings);
   };
   for (const p of paths) visit(p);
+  findings.discardedByContext = discarded;
   return findings;
 }

package/src/review/card-first.js

@@ -14,7 +14,10 @@ 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;
+// The lookahead keeps a version tail from reading as a card (KJC-BUG-0154):
+// `chore/release-4.22.0` matched "release-4" at the dot's word boundary, and
+// the board-sync gate then demanded moving a card that exists nowhere.
+export const CARD_REF_RE = /\b[a-z][a-z0-9]{1,9}(?:-[a-z][a-z0-9]{1,9})*-\d{1,6}\b(?!\.\d)/i;
 const DEFAULT_EXEMPT_PREFIXES = ["chore/release-"];
 
 // Token-boundary match: BB-002 must not satisfy a branch that actually

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

@@ -12,9 +12,10 @@ 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 } from "./parser.js";
+import { parseMaybeJsonString, normalizeReviewPayload } from "./parser.js";
 import { detectAvailableAgents, detectHostAgent } from "../utils/agent-detect.js";
-import { saveVerdict } from "./verdict-store.js";
+import { saveVerdict, diffHash } from "./verdict-store.js";
+import { reportUnparseableVerdict } from "./unparseable-verdict.js";
 import { detectWorkspace } from "./workspace.js";
 import { isQuotaExhausted, candidateStatus, pickQuotaFallback, formatCandidateMenu } from "./reviewer-fallback.js";
 
@@ -103,9 +104,14 @@ export async function runOneShotReview({
     throw new Error(`reviewer ${activeReviewer} failed: ${result?.error || "no output"}`);
   }
 
-  const parsed = parseMaybeJsonString(result.output);
+  // KJC-BUG-0146, second half: parseMaybeJsonString only PARSES — it returns whatever JSON came
+  // 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));
   if (!parsed || typeof parsed.approved !== "boolean") {
-    throw new Error(`reviewer ${activeReviewer} returned no parseable verdict`);
+    // 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) }));
   }
 
   return saveVerdict(projectDir, diff, {

package/src/review/parser.js

@@ -33,10 +33,19 @@ export function normalizeReviewPayload(payload) {
   if (isReviewPayload(payload)) return payload;
   if (Array.isArray(payload)) return findReviewInArray(payload);
 
+  // KJC-BUG-0146 — the verdict often arrives WRAPPED by the CLI that produced it:
+  // {"ok":true,"result":{approved,...}}. Only the string form was unwrapped, so a
+  // perfectly good approval from codex was thrown away as "no parseable verdict"
+  // eight times in three days. The evidence came from the raw answer this bug's
+  // first fix started saving.
   if (typeof payload.result === "string") {
     const parsedResult = parseMaybeJsonString(payload.result);
     if (parsedResult?.approved !== undefined) return parsedResult;
   }
+  if (payload.result && typeof payload.result === "object") {
+    const inner = normalizeReviewPayload(payload.result);
+    if (inner) return inner;
+  }
 
   return null;
 }

package/src/review/sonar-pregate.js

@@ -28,13 +28,38 @@ export function formatSonarFinding(issue) {
   return `(${issue.severity}) [${issueFile(issue)}${line}] ${issue.rule} — ${issue.message}`;
 }
 
+/**
+ * KJC-TSK-0795 AC3: the NEW line numbers each file gains in a unified diff
+ * (`git diff --unified=0`). Only what the diff ADDS can be the author's fault.
+ * @param {string} diffText @returns {Map<string, Set<number>>}
+ */
+export function addedLinesByFile(diffText) {
+  const map = new Map();
+  let current = null;
+  for (const raw of String(diffText || "").split("\n")) {
+    if (raw.startsWith("+++ ")) {
+      const p = raw.slice(4).trim();
+      current = p.startsWith("b/") ? p.slice(2) : p === "/dev/null" ? null : p;
+      continue;
+    }
+    const h = current ? /^@@ [^+]*\+(\d+)(?:,(\d+))? @@/.exec(raw) : null;
+    if (!h) continue;
+    const start = Number(h[1]);
+    const count = h[2] === undefined ? 1 : Number(h[2]);
+    if (count === 0) continue;
+    const set = map.get(current) ?? map.set(current, new Set()).get(current);
+    for (let i = 0; i < count; i++) set.add(start + i);
+  }
+  return map;
+}
+
 /**
  * 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 }) {
+export async function runSonarPregate({ config, stagedFiles = [], touchedLines = null, logger = null }) {
   if (config?.review_gate?.sonar === false) {
     return { available: false, reason: "disabled in config (review_gate.sonar: false)" };
   }
@@ -42,16 +67,26 @@ export async function runSonarPregate({ config, stagedFiles = [], logger = null
   try {
     lock = await acquireToolLock("sonar-scanner", { timeoutMs: 300_000 });
     const scan = await runSonarScan(config);
+    if (scan.note) logger?.warn?.(scan.note); // KJC-BUG-0156: precedence is said, never silent
     if (!scan.ok) {
       return { available: false, reason: (scan.stderr || scan.stdout || "sonar scan failed").trim() };
     }
+    // The scan above ALWAYS runs before issues are read (single-flight): the
+    // verdict is about the code as it is now, never a stale server analysis
+    // (KJC-TSK-0795 AC2 — that failure mode has no route here, by design).
     const res = await getOpenIssues(config, scan.projectKey);
     const staged = new Set(stagedFiles);
     const onStaged = (res.issues || []).filter((i) => staged.has(issueFile(i)));
+    // KJC-TSK-0795 AC3: with the diff's line map, only issues on lines the PR
+    // ADDS can veto — a 3-line PR must not answer for 30 preexisting issues.
+    // No line, or an untouched line, is the file's TREND: reported, never a block.
+    const isTouched = (i) => !touchedLines || (i.line != null && touchedLines.get(issueFile(i))?.has(Number(i.line)));
+    const own = onStaged.filter(isTouched);
     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())),
+      blocking: own.filter((i) => BLOCKING_SEVERITIES.has(String(i.severity).toUpperCase())),
+      advisory: own.filter((i) => !BLOCKING_SEVERITIES.has(String(i.severity).toUpperCase())),
+      preexisting: touchedLines ? onStaged.filter((i) => !isTouched(i)) : [],
       totalProject: res.total ?? (res.issues || []).length,
     };
   } catch (err) {

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

@@ -11,7 +11,7 @@
 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 }) {
+export function checkTestsWithCode({ config = {}, stagedFiles = [], numstat = null, env = process.env }) {
   if (env.KJ_ALLOW_NO_TESTS === "1") {
     return { ok: true, mode: "exempt", reason: "KJ_ALLOW_NO_TESTS=1 (explicit escape hatch)" };
   }
@@ -24,6 +24,17 @@ export function checkTestsWithCode({ config = {}, stagedFiles = [], env = proces
   const hasTests = stagedFiles.some(isTest);
 
   if (sources.length === 0 || hasTests) return { ok: true, mode: "pass" };
+  // KJC-TSK-0795 AC1 (epic KJC-PCS-0082): deleting code adds no behavior to
+  // test. When the caller hands the numbers and EVERY touched source only
+  // removed lines, the gate stands down — demanding a test here is the false
+  // positive that teaches people to skip the gate (measured in GREBLA's two
+  // cleanup PRs). Callers that only know names keep the old behavior.
+  if (Array.isArray(numstat)) {
+    const bySource = numstat.filter((n) => sources.includes(n.file));
+    if (bySource.length === sources.length && bySource.every((n) => (n.added || 0) === 0)) {
+      return { ok: true, mode: "delete-only", sources, reason: "every touched source only removes lines — deleting is not new behavior" };
+    }
+  }
 
   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`;

package/src/review/unparseable-verdict.js

@@ -0,0 +1,50 @@
+/**
+ * KJC-BUG-0146 — when a reviewer answers something the parser cannot read.
+ *
+ * Until now that answer was thrown away: the error said "no parseable verdict"
+ * and not one byte of what the reviewer actually replied survived. Eight
+ * occurrences produced zero evidence, which is why the bug stayed undiagnosed
+ * for two days. A failure nobody can inspect is a failure nobody can fix.
+ *
+ * So the raw answer is written next to the verdicts and an excerpt travels in
+ * the error. Nothing else changes: an unreadable answer is still a refusal,
+ * never a pass — it COULD be a rejection in the wrong shape, and switching to
+ * another reviewer would turn it into an approval.
+ */
+import fs from "node:fs/promises";
+import path from "node:path";
+
+const DIR = path.join(".karajan", "reviews");
+const EXCERPT = 400;
+
+/** One line about what came back, so the shape is visible without opening anything. */
+export function describeOutput(output) {
+  if (output === undefined || output === null) return "no output at all";
+  if (typeof output !== "string") return `${typeof output}, not a string`;
+  if (output.trim() === "") return "empty output";
+  return `${output.length} chars, starts with ${JSON.stringify(output.slice(0, 60))}`;
+}
+
+/**
+ * Writes the raw answer for inspection and returns the error message to raise.
+ * A failure to write is never allowed to hide the original problem.
+ * @param {{projectDir?: string, reviewer: string, output: unknown, hash: string, writeFile?: Function}} args
+ */
+export async function reportUnparseableVerdict({ projectDir = process.cwd(), reviewer, output, hash, writeFile = fs.writeFile }) {
+  const file = path.join(projectDir, DIR, `${hash}.unparseable.txt`);
+  const body = typeof output === "string" ? output : JSON.stringify(output ?? null, null, 2);
+  let saved = null;
+  try {
+    await fs.mkdir(path.dirname(file), { recursive: true });
+    await writeFile(file, `reviewer: ${reviewer}\n\n${body}\n`, "utf8");
+    saved = file;
+  } catch {
+    // Could not save it — the excerpt below still travels, and the message says so.
+  }
+  const excerpt = typeof output === "string" && output.trim() ? `\n--- what ${reviewer} answered (first ${EXCERPT} chars) ---\n${output.slice(0, EXCERPT)}\n---` : "";
+  return [
+    `reviewer ${reviewer} returned no parseable verdict (${describeOutput(output)})`,
+    saved ? `full answer saved to ${path.relative(projectDir, saved)}` : "the full answer could NOT be saved to disk",
+    "an unreadable answer is a refusal, not a pass: it may be a rejection in the wrong shape (KJC-BUG-0146)",
+  ].join("\n") + excerpt;
+}

package/src/roles/audit-role.js

@@ -1,4 +1,7 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
 import { AgentRole } from "./agent-role.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";
 import { detectProjectStack } from "../utils/stack-detect.js";
@@ -123,6 +126,12 @@ export class AuditRole extends AgentRole {
     if (!noKnip) {
       try {
         deadExports = await collectDeadExports(projectDir, stack, this.config, this.logger);
+        // AC8 (KJC-TSK-0794): the report leads with the derivative — hand the
+        // block its previous measurement, if one was ever recorded.
+        if (deadExports?.available) {
+          const prev = await loadPreviousAudit(projectDir);
+          deadExports.previous = prev?.knipDeadExports ? { ...prev.knipDeadExports, timestamp: prev.timestamp || null } : null;
+        }
       } catch { /* knip is best-effort */ }
     }
     if (!noInjectionScan) {
@@ -145,6 +154,12 @@ export class AuditRole extends AgentRole {
         aiSlop = await collectAiSlop(projectDir);
       } catch { /* ai-slop scan is best-effort */ }
     }
+    // STW-A (KJC-TSK-0789 AC5): record that the security surface was looked
+    // at, so the Steward can age it — GREBLA went 79 days with "never".
+    try {
+      mkdirSync(dirname(securityAuditMarkerPath(projectDir)), { recursive: true });
+      writeFileSync(securityAuditMarkerPath(projectDir), JSON.stringify({ at: new Date().toISOString(), mode: securityOnly ? "security" : "full" }));
+    } catch { /* recording is best-effort — the audit itself already ran */ }
     return { projectDir, basalCost, growthDelta, stack, sonarFindings, webperf, osvFindings, semgrepFindings, circularDeps, deadExports, injectionFindings, infraFindings, aiSlop };
   }
 
@@ -183,7 +198,10 @@ export class AuditRole extends AgentRole {
       if (!parsed) {
         return { ok: true, result: { raw: result.output, provider }, summary: "Audit complete (unstructured output)", usage };
       }
-      if (basalCost) { try { await saveAuditSnapshot(projectDir, basalCost); } catch { /* best-effort */ } }
+      if (basalCost) {
+        const knipDeadExports = deadExports?.available ? { exports: (deadExports.exports || []).length, files: (deadExports.files || []).length } : null;
+        try { await saveAuditSnapshot(projectDir, { ...basalCost, knipDeadExports }); } catch { /* best-effort */ }
+      }
 
       return {
         ok: true,

package/src/sonar/scanner.js

@@ -181,11 +181,27 @@ async function resolveSonarTokenWithFallback(config, apiHost) {
   return null;
 }
 
-async function ensureSonarProjectProperties(cwd = process.cwd()) {
+/**
+ * KJC-BUG-0156 (issue #1543): the repo's sonar-project.properties is the
+ * CANONICAL layout — kj's -D opts override it on the scanner CLI, so when the
+ * file exists kj's layout opts must stand down. The ignore rules stay: those
+ * are kj's own policy, not project layout.
+ */
+export function respectRepoProperties(scanner = {}, props = {}) {
+  if (!props.existed) return scanner;
+  const kept = { ...scanner };
+  for (const k of ["sources", "exclusions", "test_inclusions", "coverage_exclusions", "javascript_lcov_report_paths"]) delete kept[k];
+  return kept;
+}
+
+/** @returns {Promise<{existed: boolean, declaredKey: string|null}>} */
+export async function ensureSonarProjectProperties(cwd = process.cwd()) {
   const propsPath = path.join(cwd, "sonar-project.properties");
   try {
-    await fsPromises.access(propsPath);
-    return; // already exists
+    const raw = await fsPromises.readFile(propsPath, "utf8");
+    // the repo's declared key is what the server will know — kj must query THAT
+    const declaredKey = raw.split("\n").map((l) => /^\s*sonar\.projectKey\s*=\s*(.+)$/.exec(l)).find(Boolean)?.[1]?.trim() ?? null;
+    return { existed: true, declaredKey };
   } catch {
     // Auto-generate based on project structure
     let pkg = {};
@@ -205,6 +221,7 @@ async function ensureSonarProjectProperties(cwd = process.cwd()) {
       `sonar.exclusions=**/node_modules/**,**/dist/**,**/build/**,**/coverage/**`,
     ].join("\n");
     await fsPromises.writeFile(propsPath, props + "\n", "utf8");
+    return { existed: false, declaredKey: null };
   }
 }
 
@@ -241,7 +258,9 @@ export async function runSonarScan(config, projectKey = null) {
       exitCode: start.exitCode
     };
   }
-  await ensureSonarProjectProperties();
+  // KJC-BUG-0156: kj's -Dsonar.projectKey stays (scan and query must use the
+  // SAME key), but the repo's properties own the LAYOUT from here on.
+  const repoProps = await ensureSonarProjectProperties();
   const token = await resolveSonarTokenWithFallback(config, apiHost);
   if (!token) {
     return {
@@ -262,10 +281,16 @@ export async function runSonarScan(config, projectKey = null) {
       exitCode: coverage.exitCode || 1
     };
   }
-  const scannerConfig = normalizeScannerConfig({
-    ...sonarConfig.scanner,
-    ...coverage.scannerPatch
-  });
+  const scannerConfig = respectRepoProperties(
+    normalizeScannerConfig({
+      ...sonarConfig.scanner,
+      ...coverage.scannerPatch
+    }),
+    repoProps
+  );
+  const note = repoProps.existed && sonarConfig.scanner?.sources
+    ? "sonar: the repo's sonar-project.properties wins over sonarqube.scanner.sources — kj passed only its ignore rules"
+    : null;
 
   const pick = await pickSonarScanner(sonarConfig.scanner);
   const env = {
@@ -300,6 +325,7 @@ export async function runSonarScan(config, projectKey = null) {
     ok: result.exitCode === 0,
     projectKey: effectiveProjectKey,
     scanner: pick.type,
+    note,
     stdout: result.stdout,
     stderr: result.stderr,
     exitCode: result.exitCode

package/src/steward/invariants.js

@@ -0,0 +1,190 @@
+/**
+ * Steward invariants — the verdict kernel (STW-A, KJC-TSK-0789, epic
+ * KJC-PCS-0081). Trust expires like permission does: a green that nobody has
+ * re-earned is not a green. Every invariant answers ONE of four things:
+ *
+ *   ok             — evidence exists, fresh, and holds
+ *   broken         — evidence exists and says it does not hold
+ *   unknown        — the evidence EXPIRED or cannot be read → remedy: refresh
+ *   not-observable — there was never anywhere to look → remedy: instrument
+ *
+ * The last two are the point (GREBLA: workflows fire ONLY on pull_request, so
+ * "how many days has main been red" had no possible answer — and 21 days of
+ * red E2E hid a 17-day production bug). Confusing either with ok is the false
+ * green Karajan exists to prevent.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { parse as parseYaml } from "yaml";
+export const VERDICTS = { OK: "ok", BROKEN: "broken", UNKNOWN: "unknown", NOT_OBSERVABLE: "not-observable" };
+// Defaults CALIBRATED with GREBLA's measured decay (79 days without a security
+// audit; 21 days of red suite; 17 of them hiding a production bug). A project
+// can declare its own under steward.freshness — and AC8: when the defaults
+// apply, the report says so and says which values they are.
+export const DEFAULT_FRESHNESS = { main_ci_red_days: 3, security_audit_days: 14, critical_vuln_days: 7, high_vuln_days: 30 };
+/** @returns {{values: object, declared: boolean}} */
+export function resolveFreshness(config = {}) {
+  const declared = config?.steward?.freshness && typeof config.steward.freshness === "object" ? config.steward.freshness : null;
+  return { values: { ...DEFAULT_FRESHNESS, ...(declared || {}) }, declared: Boolean(declared) };
+}
+/** Does any workflow run ON PUSH to the base branch? Reading the repo decides
+ * observability — a remote API cannot tell "green" from "nobody looked". */
+function pushWorkflows(projectDir, baseBranch) {
+  const dir = path.join(projectDir, ".github", "workflows");
+  let names;
+  try { names = fs.readdirSync(dir).filter((f) => /\.ya?ml$/.test(f)); } catch { return []; }
+  const hits = [];
+  for (const name of names) {
+    let wf;
+    try { wf = parseYaml(fs.readFileSync(path.join(dir, name), "utf8")); } catch { continue; }
+    // YAML 1.1 quirk: `on:` may parse as boolean true key.
+    const on = wf?.on ?? wf?.[true];
+    const push = Array.isArray(on) ? (on.includes("push") ? {} : null) : typeof on === "string" ? (on === "push" ? {} : null) : (on?.push ?? null);
+    if (push === null || push === undefined) continue;
+    const branches = push?.branches;
+    if (!branches || (Array.isArray(branches) && branches.includes(baseBranch))) hits.push(wf?.name || name);
+  }
+  return hits;
+}
+const days = (ms) => Math.floor(ms / 86_400_000);
+const plural = (n) => `${n} day${n === 1 ? "" : "s"}`;
+/**
+ * Invariant #1 — the base branch has CI of its own and it is green.
+ * `runsFn(workflows)` is injected (the sweep wires `gh run list`); it returns
+ * [{workflow, conclusion, createdAt}] newest-first for push runs on the base.
+ */
+export function evaluateMainCi({ projectDir, baseBranch = "main", freshness = DEFAULT_FRESHNESS, runsFn = null, nowMs = Date.now() }) {
+  const instrumented = pushWorkflows(projectDir, baseBranch);
+  if (instrumented.length === 0) {
+    return { verdict: VERDICTS.NOT_OBSERVABLE, evidence: `no workflow runs on push to ${baseBranch} — "how long has it been red" has no possible answer`, remedy: `instrument: add a push trigger for ${baseBranch} to at least one workflow` };
+  }
+  let runs;
+  try { runs = runsFn ? runsFn(instrumented) : null; } catch { runs = null; }
+  if (!Array.isArray(runs) || runs.length === 0) {
+    return { verdict: VERDICTS.UNKNOWN, evidence: `instrumented (${instrumented.join(", ")}) but the runs could not be read`, remedy: "refresh: run the sweep where gh can list the runs" };
+  }
+  const sorted = [...runs].sort((a, b) => Date.parse(b.createdAt) - Date.parse(a.createdAt));
+  const latest = sorted[0];
+  if (latest.conclusion === "success") {
+    return { verdict: VERDICTS.OK, evidence: `green on ${baseBranch} since ${latest.createdAt}`, remedy: null };
+  }
+  // The streak starts at the FIRST red after the last green — not at the green.
+  const greenIdx = sorted.findIndex((r) => r.conclusion === "success");
+  const firstRed = greenIdx === -1 ? sorted.at(-1) : sorted[greenIdx - 1];
+  const redDays = days(nowMs - Date.parse(firstRed.createdAt));
+  if (redDays > freshness.main_ci_red_days) {
+    return { verdict: VERDICTS.BROKEN, evidence: `${baseBranch} red for ${plural(redDays)} (tolerance ${freshness.main_ci_red_days}) — a suite this red stops meaning anything`, remedy: "fix or revert to green; a red suite is the project's #1 invariant" };
+  }
+  return { verdict: VERDICTS.OK, evidence: `red for ${plural(redDays)}, inside the ${freshness.main_ci_red_days}-day tolerance — a fresh failure is work, not decay`, remedy: null };
+}
+/** Where `kj audit` records its last run for the Steward to age. */
+export const securityAuditMarkerPath = (projectDir) => path.join(projectDir, ".karajan", "steward", "security-audit.json");
+/**
+ * AC5 — how long since `kj audit --security` last ran. "Never" is GREBLA's
+ * real case: 79 days with an open redirect and untouched dependencies.
+ * No record is BROKEN, not unknown: running the audit fixes both "never"
+ * and "before recording existed", so the remedy is the same either way.
+ */
+export function evaluateSecurityAudit({ projectDir, freshness = DEFAULT_FRESHNESS, nowMs = Date.now() }) {
+  let marker;
+  try { marker = JSON.parse(fs.readFileSync(securityAuditMarkerPath(projectDir), "utf8")); } catch { marker = null; }
+  if (!marker?.at) {
+    return { verdict: VERDICTS.BROKEN, evidence: "no security audit on record — never run, or run before recording existed", remedy: "run kj audit --security (zero tokens) and remediate what it finds" };
+  }
+  const age = days(nowMs - Date.parse(marker.at));
+  if (age > freshness.security_audit_days) {
+    return { verdict: VERDICTS.BROKEN, evidence: `last security audit ${plural(age)} ago (freshness ${freshness.security_audit_days})`, remedy: "run kj audit --security" };
+  }
+  return { verdict: VERDICTS.OK, evidence: `security audit ${plural(age)} ago (${marker.at})`, remedy: null };
+}
+/**
+ * AC6 — vulnerable dependencies age by the ADVISORY's published date, never
+ * the discovery's: the clock started when the world knew. A critical with no
+ * date counts as overdue — unknown age is not youth.
+ */
+export function evaluateVulnAging({ vulns, freshness = DEFAULT_FRESHNESS, nowMs = Date.now() }) {
+  if (!Array.isArray(vulns)) {
+    return { verdict: VERDICTS.UNKNOWN, evidence: "no vulnerability scan handed to the invariant", remedy: "refresh: run kj audit so osv-scanner reports the dependencies" };
+  }
+  const windowFor = (sev) => (sev === "CRITICAL" ? freshness.critical_vuln_days : sev === "HIGH" ? freshness.high_vuln_days : null);
+  const overdue = vulns.filter((v) => {
+    const win = windowFor(String(v.severity || "").toUpperCase());
+    if (win === null) return false;
+    if (!v.publishedAt) return true;
+    return days(nowMs - Date.parse(v.publishedAt)) > win;
+  });
+  if (overdue.length > 0) {
+    const items = overdue.map((v) => `${v.id} (${v.severity}, advisory ${v.publishedAt || "date unknown — unknown age is not youth"})`).join("; ");
+    return { verdict: VERDICTS.BROKEN, evidence: `${overdue.length} vulnerable dependencies past their advisory-age window: ${items}`, remedy: "update or replace the affected packages" };
+  }
+  return { verdict: VERDICTS.OK, evidence: `${vulns.length} known vulnerabilities, all inside their advisory-age windows`, remedy: null };
+}
+/**
+ * AC4 — dead code informs by DERIVATIVE and carries NO security weight: in
+ * GREBLA the sensitive functions stayed in the bundle, but the backend rules
+ * kept protecting them — removing UI neither widened nor closed any surface.
+ * Growth is the decay signal; the absolute is somebody else's report.
+ */
+export function evaluateDeadCodeTrend({ current, previous }) {
+  if (!current || typeof current.deadExports !== "number") {
+    return { verdict: VERDICTS.UNKNOWN, evidence: "no dead-code measurement on record", remedy: "refresh: run kj audit so the inventory is measured" };
+  }
+  if (!previous || typeof previous.deadExports !== "number") {
+    return { verdict: VERDICTS.OK, evidence: `${current.deadExports} dead exports — first measurement, the trend starts here`, remedy: null };
+  }
+  const delta = current.deadExports - previous.deadExports;
+  if (delta > 0) {
+    return { verdict: VERDICTS.BROKEN, evidence: `dead code grew +${delta} since ${previous.timestamp || "the last audit"} (now ${current.deadExports}; no security weight — dead code is debt, not attack surface)`, remedy: "delete what the inventory names, or declare the false positives" };
+  }
+  return { verdict: VERDICTS.OK, evidence: `dead code ${delta === 0 ? "flat" : delta} since the last audit (now ${current.deadExports})`, remedy: null };
+}
+const COVERAGE_CONFIGS = ["vitest.config.js", "vitest.config.ts", "vitest.config.mjs", "jest.config.js", "jest.config.ts", "jest.config.json", "package.json"];
+/**
+ * AC7 — coverage is an invariant of CONFIGURATION, not of value: no 80% is
+ * demanded here. Either something measures the level (CI's job), or nothing
+ * does — and "nothing measures it" is the definition of not observable.
+ */
+export function evaluateCoverageConfig({ projectDir }) {
+  for (const name of COVERAGE_CONFIGS) {
+    let text;
+    try { text = fs.readFileSync(path.join(projectDir, name), "utf8"); } catch { continue; }
+    if (/coverage[\s\S]{0,400}?(thresholds?|lines|branches|functions|statements)\s*[:=]/.test(text)) {
+      return { verdict: VERDICTS.OK, evidence: `coverage thresholds configured in ${name} — the level itself is CI's job`, remedy: null };
+    }
+  }
+  return { verdict: VERDICTS.NOT_OBSERVABLE, evidence: "no coverage threshold configured anywhere — nothing measures the level", remedy: "instrument: configure a coverage threshold (any value the team stands behind — no 80% is demanded)" };
+}
+/** AC3 — phantom coverage: the two detectors exist (KJC-TSK-0800) but the
+ * sweep does not yet discover test↔source pairs, so their output is INJECTED.
+ * No output → not observable: never ok by absence of the detector's run. */
+export function evaluatePhantomCoverage({ phantoms } = {}) {
+  if (!Array.isArray(phantoms)) {
+    return { verdict: VERDICTS.NOT_OBSERVABLE, evidence: "the phantom detectors were not run", remedy: "instrument: run the detectors (steward/phantom-coverage) over the suite's test↔source pairs and feed their output" };
+  }
+  if (phantoms.length > 0) {
+    return { verdict: VERDICTS.BROKEN, evidence: `${phantoms.length} phantom test(s): ${phantoms.map((p) => p.literal || p.member).join(", ")} — they add to the count and cover nothing`, remedy: "rewrite each test against the live UI, or delete it with the dead code it exercised" };
+  }
+  return { verdict: VERDICTS.OK, evidence: "no phantom tests in the detectors' output", remedy: null };
+}
+/**
+ * Run a list of invariants. A child whose `dependsOn` parent came out
+ * not-observable INHERITS it — an invariant built on an unobserved one must
+ * never report ok. A probe that throws is unknown: never a green light.
+ */
+export function runInvariants(invariants, ctx = {}) {
+  const results = [];
+  const byId = new Map();
+  for (const inv of invariants) {
+    const parent = inv.dependsOn ? byId.get(inv.dependsOn) : null;
+    let res;
+    if (parent && parent.verdict === VERDICTS.NOT_OBSERVABLE) {
+      res = { verdict: VERDICTS.NOT_OBSERVABLE, evidence: `depends on ${inv.dependsOn}, which is not observable`, remedy: `instrument ${inv.dependsOn} first (${parent.remedy || "no remedy stated"})` };
+    } else {
+      try { res = inv.evaluate(ctx); } catch (err) { res = { verdict: VERDICTS.UNKNOWN, evidence: `the probe itself failed (${err.message})`, remedy: "fix the probe — a broken probe is never a green light" }; }
+    }
+    const row = { id: inv.id, ...res };
+    byId.set(inv.id, row);
+    results.push(row);
+  }
+  return results;
+}