karajan-code 4.22.0 → 4.23.0

package/README.md

@@ -34,6 +34,7 @@ Your AI agent (Claude Code, Codex, Copilot, Antigravity, Cursor…) writes the c
 - **Nothing personal ships** — every outbound boundary audits before it leaves the machine: the pre-commit rejects a staged diff carrying your denylisted personal data, hardcoded platform tokens (`ghp_`, `sk-`, `AKIA`…) block outright, `verify-pack`-style tarball scans guard the publish, and `kj privacy scan <dir>` audits any build output. Your denylist lives in `~/.karajan/privacy.yml` — the install asks and writes it for you.
 - **Installing IS activating** — `kj env install` performs the enforcement itself (git hooks, verdict gate, tool gate) instead of trusting the agent to run setup steps, and ends by printing the method into the very conversation that installed it. A commit outside the method is rejected, not narrated.
 - **The turn cannot end red — the Sentinel** — a deterministic supervisor (zero LLM) wired into the harness's synchronous hooks records the method state of the session as tools run, and a Stop hook blocks the agent from ending its turn while method violations are open. The program rules, the agent thinks. See [guarantee levels](#guarantee-levels-governed-vs-supervised).
+- **Trust expires — the Steward** — `kj steward sweep` checks the project's declared guarantees against their freshness and answers one of FOUR verdicts per invariant: ok, broken, *unknown* (evidence expired → refresh it) or *not observable* (nowhere to look → instrument it) — because confusing the last two with green is how a project decays for weeks behind a passing facade. The verdict is versioned in the repo, sealed in the decision chain, and every break lands on the board as PROPOSED work that nothing executes unreviewed. Runs on demand, on `kj resume` when stale, or as an opt-in scheduled Action.
 - **The review panel never runs dry** — nine built-in agents (Claude Code, Codex, GitHub Copilot, Antigravity `agy` — the gemini successor —, Kimi Code, Qwen, OpenCode, Aider, Gemini legacy), and when the configured reviewer exhausts its quota, `kj review` switches to an authenticated candidate with a LOUD notice — or hands you the menu of candidates with their tier (free / subscription / local) and the exact login command. Never a silent failure, never the brain reviewing itself.
 
 This repo runs under its own environment: every commit to karajan-code carries a cross-AI verdict.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "karajan-code",
-  "version": "4.22.0",
+  "version": "4.23.0",
   "description": "Local multi-agent coding orchestrator with TDD, SonarQube, and code review pipeline",
   "type": "module",
   "license": "AGPL-3.0",
@@ -123,17 +123,18 @@
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
-    "smol-toml": "^1.7.0",
     "@vitest/coverage-v8": "^4.1.8",
     "esbuild": "^0.28.0",
     "eslint": "^10.4.1",
     "eslint-plugin-import-x": "^4.16.2",
+    "eslint-plugin-node-security": "5.2.2",
     "eslint-plugin-security": "^4.0.0",
     "globals": "^17.6.0",
     "lint-staged": "^17.0.7",
     "postject": "^1.0.0-alpha.6",
     "prettier": "^3.4.2",
     "simple-git-hooks": "^2.13.1",
+    "smol-toml": "^1.7.0",
     "vitest": "^4.1.8"
   }
 }

package/packages/hu-board/src/auth.js

@@ -20,6 +20,8 @@
  *     legacy callers keep working.
  */
 
+import { timingSafeEqual } from "node:crypto";
+
 /** Loopback addresses we trust without auth, regardless of token state. */
 const LOOPBACK_ADDRESSES = new Set([
   "127.0.0.1",
@@ -41,7 +43,7 @@ export function authMiddleware() {
     if (isLoopback(req)) return next();
 
     const token = extractToken(req);
-    if (token === expected) return next();
+    if (tokensMatch(token, expected)) return next();
 
     return res.status(401).json({
       error: "Unauthorized",
@@ -53,6 +55,32 @@ export function authMiddleware() {
   };
 }
 
+/**
+ * Constant-time comparison of a presented token against the expected one.
+ *
+ * `===` on strings stops at the first differing byte, so the time it takes to
+ * reject a token leaks how much of a correct prefix was supplied. Over the
+ * loopback interface that is noise — but this middleware exists precisely for
+ * the case the header above describes, where the board is bound beyond
+ * loopback and the peer is on the LAN. There the difference is measurable, and
+ * the token can be recovered a byte at a time.
+ *
+ * `timingSafeEqual` throws when the buffers differ in length, so the length is
+ * checked first. That is not a leak worth closing: the length of the expected
+ * token is fixed by whatever wrote `~/.karajan/hu-board/token`, and a token of
+ * the wrong length is wrong regardless of its contents.
+ *
+ * @param {string|undefined} presented
+ * @param {string} expected
+ * @returns {boolean}
+ */
+function tokensMatch(presented, expected) {
+  if (typeof presented !== "string") return false;
+  const left = Buffer.from(presented, "utf8");
+  const right = Buffer.from(expected, "utf8");
+  return left.length === right.length && timingSafeEqual(left, right);
+}
+
 /**
  * @param {import('express').Request} req
  * @returns {boolean}

package/src/audit/basal-cost.js

@@ -272,10 +272,14 @@ export async function saveAuditSnapshot(projectDir, metrics) {
 
 export function computeGrowthDelta(current, previous) {
   if (!previous) return null;
+  // AC8 (KJC-TSK-0794): "not measured before" must never read as "unchanged" —
+  // the derivative only exists when BOTH snapshots actually measured it.
+  const bothMeasured = Array.isArray(current.deadExports) && Array.isArray(previous.deadExports);
   return {
     lines: current.totalLines - previous.totalLines,
     files: current.totalFiles - previous.totalFiles,
     deps: current.dependencies.total - (previous.dependencies?.total ?? 0),
+    deadExports: bothMeasured ? current.deadExports.length - previous.deadExports.length : null,
     since: previous.timestamp || null
   };
 }

package/src/audit/dead-exports.js

@@ -16,6 +16,7 @@
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 import { createRequire } from "node:module";
+import os from "node:os";
 import path from "node:path";
 import fs from "node:fs/promises";
 import { filterFalsePositives } from "./issue-filter.js";
@@ -26,6 +27,42 @@ const SCAN_TIMEOUT_MS = 120_000;
 const MAX_DEAD_EXPORTS_REPORTED = 100;
 const MAX_UNUSED_FILES_REPORTED = 50;
 
+// KJC-TSK-0794 AC7: a Firebase callable or a declared global-setup reported as
+// dead is the false positive that gets the inventory switched off. When the
+// project declares nothing itself, kj declares FOR it what it can read.
+const KNIP_OWN_CONFIGS = ["knip.json", "knip.jsonc", ".knip.json", "knip.js", "knip.ts", "knip.config.js", "knip.config.ts"];
+// knip's default root entry patterns, restated because an explicit `entry`
+// REPLACES them (package.json main/bin/exports always count on their own).
+const KNIP_DEFAULT_ENTRY = ["{index,cli,main}.{js,mjs,cjs,jsx,ts,mts,cts,tsx}", "src/{index,cli,main}.{js,mjs,cjs,jsx,ts,mts,cts,tsx}"];
+
+async function hasOwnKnipConfig(projectDir) {
+  for (const f of KNIP_OWN_CONFIGS) {
+    try { await fs.access(path.join(projectDir, f)); return true; } catch { /* keep looking */ }
+  }
+  try { return Boolean(JSON.parse(await fs.readFile(path.join(projectDir, "package.json"), "utf8")).knip); } catch { return false; }
+}
+
+/** Entrypoints kj can vouch for: config.audit.entrypoints (the user's word) and
+ * firebase.json's functions.source (the platform's word). Null when nothing. */
+async function resolveProjectEntrypoints(projectDir, config) {
+  const declared = (config?.audit?.entrypoints || []).filter((e) => typeof e === "string");
+  const firebase = [];
+  try {
+    const fb = JSON.parse(await fs.readFile(path.join(projectDir, "firebase.json"), "utf8"));
+    const fns = Array.isArray(fb.functions) ? fb.functions : fb.functions ? [fb.functions] : [];
+    for (const f of fns) if (typeof f?.source === "string") firebase.push(f.source);
+  } catch { /* no firebase.json — nothing to declare */ }
+  return declared.length || firebase.length ? { declared, firebase } : null;
+}
+
+function buildEphemeralKnipConfig({ declared, firebase }) {
+  const root = { entry: [...KNIP_DEFAULT_ENTRY, ...declared] };
+  if (!firebase.length) return root;
+  const workspaces = { ".": root };
+  for (const src of firebase) workspaces[src] = { entry: ["index.{js,ts}", "src/index.{js,ts}"] };
+  return { workspaces };
+}
+
 function hasJsTsStack(stack) {
   if (!stack) return false;
   const lang = (stack.language || "").toLowerCase();
@@ -78,11 +115,24 @@ export async function collectDeadExports(projectDir, stack, config = {}, logger
     return { available: false, reason: `knip binary not resolvable (${err?.message || err}). In the SEA binary install karajan-code via npm to enable.` };
   }
 
+  const args = [knipBin, "--reporter", "json", "--no-progress", "--no-exit-code"];
+  let declaredEntrypoints = null;
+  try {
+    const eps = await resolveProjectEntrypoints(projectDir, config);
+    // a project with its OWN knip config already decided — it is respected
+    if (eps && !(await hasOwnKnipConfig(projectDir))) {
+      const cfgPath = path.join(await fs.mkdtemp(path.join(os.tmpdir(), "kj-knip-")), "knip.json");
+      await fs.writeFile(cfgPath, JSON.stringify(buildEphemeralKnipConfig(eps)));
+      args.push("--config", cfgPath);
+      declaredEntrypoints = eps;
+    }
+  } catch { /* declaring is best-effort; the default scan still runs */ }
+
   let raw;
   try {
     const { stdout } = await execFileAsync(
       process.execPath,
-      [knipBin, "--reporter", "json", "--no-progress", "--no-exit-code"],
+      args,
       { cwd: projectDir, timeout: SCAN_TIMEOUT_MS, maxBuffer: 16 * 1024 * 1024 },
     );
     raw = stdout;
@@ -163,6 +213,7 @@ export async function collectDeadExports(projectDir, stack, config = {}, logger
     available: true,
     total: kept.length,
     suppressedCount: suppressed.length,
+    declaredEntrypoints,
     exports: keptExports,
     files: keptFiles,
     suppressed,

package/src/audit/deterministic-summary.js

@@ -185,9 +185,20 @@ function formatDeadExportsBlock(deadExports) {
   const lines = ["### Dead Code (knip)"];
   const exportsTotal = (deadExports.exports || []).length;
   const filesTotal = (deadExports.files || []).length;
+  const reported = exportsTotal + filesTotal;
+  const suppressed = deadExports.suppressedCount || 0;
+  // AC8 (KJC-TSK-0794): derivative first; then how many ENTERED and how many
+  // were FILTERED — a shrinking number must never hide a shrinking scan.
+  const prev = deadExports.previous;
+  if (prev && typeof prev.exports === "number") {
+    const d = reported - (prev.exports + (prev.files || 0));
+    lines.push(`- Δ dead code: ${d >= 0 ? "+" : ""}${d} since ${prev.timestamp || "last audit"} (now ${reported})`);
+  }
+  lines.push(`- ${reported + suppressed} entered the scan, ${suppressed} filtered as declared false positives, ${reported} reported`);
+  const eps = deadExports.declaredEntrypoints;
+  if (eps) lines.push(`- Declared entrypoints honored: ${[...eps.declared, ...eps.firebase.map((s) => `${s} (firebase functions)`)].join(", ")}`);
   lines.push(`- Unused exports/types: ${exportsTotal}`);
   lines.push(`- Unused files: ${filesTotal}`);
-  if (deadExports.suppressedCount) lines.push(`- Suppressed (FP filter): ${deadExports.suppressedCount}`);
   const allItems = [...(deadExports.exports || []), ...(deadExports.files || [])];
   if (allItems.length > 0) {
     const groups = groupDeadExportsBySeverity(allItems);
@@ -234,8 +245,12 @@ function formatBasalCostBlock(basalCost, growthDelta) {
   }
 
   const dead = Array.isArray(basalCost.deadExports) ? basalCost.deadExports : [];
+  // AC8 (KJC-TSK-0794): the DERIVATIVE leads — "went from N to M" is what a
+  // reader acts on; the absolute is the secondary datum.
+  const dDelta = growthDelta?.deadExports;
+  const lead = typeof dDelta === "number" ? `${dDelta >= 0 ? "+" : ""}${dDelta} since last audit — ` : "";
   if (dead.length > 0) {
-    lines.push(`- Dead exports: ${dead.length}`);
+    lines.push(`- Dead exports: ${lead}${dead.length} total`);
     for (const de of dead.slice(0, MAX_SAMPLE_DEAD_EXPORTS)) {
       lines.push(`  - \`${de.name}\` in ${de.file}`);
     }
@@ -243,7 +258,7 @@ function formatBasalCostBlock(basalCost, growthDelta) {
       lines.push(`  - ... and ${dead.length - MAX_SAMPLE_DEAD_EXPORTS} more`);
     }
   } else {
-    lines.push("- Dead exports: 0");
+    lines.push(`- Dead exports: ${lead}0`);
   }
 
   if (growthDelta) {

package/src/audit/member-reachability.js

@@ -0,0 +1,158 @@
+/**
+ * Member reachability (KJC-TSK-0794, epic KJC-PCS-0082) — which class members
+ * no entrypoint can reach, said ONLY inside the perimeter validated with known
+ * truth (GREBLA: 31/139 unreachable at dd5a91a checked by hand, 0/108 on their
+ * cleaned main): one file, a recognized framework contract, no dynamic dispatch.
+ * Everything outside comes out NOT OBSERVABLE with its reason, never as clean —
+ * an inflated inventory gets switched off, and then nobody reads the real one.
+ */
+import { parse } from "@babel/parser";
+const plugins = (file) => [
+  ...(/\.(ts|tsx|mts|cts)$/.test(file) ? ["typescript"] : []),
+  ...(/\.(tsx|jsx)$/.test(file) || !/\.(ts|mts|cts)$/.test(file) ? ["jsx"] : []),
+  "decorators",
+];
+// Entrypoints are what the FRAMEWORK calls — declared per framework, VERSIONED
+// (bump on any list change), never a hand-kept list in a run. v1 covers Lit;
+// other frameworks stay NOT OBSERVABLE until their contract is declared here.
+export const ENTRYPOINT_CATALOG = {
+  version: 2, // v2: each list says WHICH slot the framework touches — static and instance are different worlds
+  lit: {
+    instance: ["constructor", "render", "connectedCallback", "disconnectedCallback", "attributeChangedCallback", "adoptedCallback", "firstUpdated", "updated", "willUpdate", "shouldUpdate", "performUpdate", "getUpdateComplete", "createRenderRoot"],
+    static: ["properties", "styles", "observedAttributes"],
+  },
+};
+const BASES = new Map([["LitElement", "lit"]]);
+function walk(node, visit) {
+  if (!node || typeof node.type !== "string") return;
+  visit(node);
+  for (const key of Object.keys(node)) {
+    const child = node[key];
+    if (Array.isArray(child)) child.forEach((c) => walk(c, visit));
+    else if (child && typeof child.type === "string") walk(child, visit);
+  }
+}
+const keyName = (m) => {
+  if (m.key?.type === "PrivateName") return `#${m.key.id.name}`;
+  if (!m.computed && m.key?.type === "Identifier") return m.key.name;
+  return m.key?.type === "StringLiteral" || m.key?.type === "NumericLiteral" ? String(m.key.value) : null;
+};
+const ACCESSOR_KINDS = new Map([["get", "getter"], ["set", "setter"]]);
+const kindOf = (m) => ACCESSOR_KINDS.get(m.kind) ?? (/Method/.test(m.type) ? "method" : "field");
+/** `this.x` / `this['x']` / `this.#x` inside a node, prefixed with the slot the
+ * context can actually reach ("static " inside static members, "" otherwise).
+ * Over-collecting through functions that rebind `this` only makes members MORE
+ * alive — never dead. */
+const thisRefs = (node, prefix = "") => {
+  const refs = new Set();
+  walk(node, (n) => {
+    if (n.type !== "MemberExpression" || n.object?.type !== "ThisExpression") return;
+    if (n.property.type === "PrivateName") refs.add(`${prefix}#${n.property.id.name}`);
+    else if (!n.computed && n.property.type === "Identifier") refs.add(prefix + n.property.name);
+    else if (n.property.type === "StringLiteral" || n.property.type === "NumericLiteral") refs.add(prefix + String(n.property.value));
+  });
+  return refs;
+};
+const notObs = (name, line, reason) => ({ name, line, observable: false, reason, unreachable: [] });
+
+function analyzeClass(node, { staticUses, thisPropCount }) {
+  const name = node.id?.name ?? "(anonymous)";
+  const line = node.loc.start.line;
+  const sup = node.superClass;
+  if (!sup) return notObs(name, line, "no framework contract — members may be called from outside the file");
+  if (sup.type !== "Identifier") return notObs(name, line, "mixin or computed base class — inherited entrypoints cannot be resolved");
+  const framework = BASES.get(sup.name);
+  if (!framework) return notObs(name, line, `unknown base class ${sup.name} — its contract is not in the entrypoint catalog (v${ENTRYPOINT_CATALOG.version})`);
+
+  const cat = ENTRYPOINT_CATALOG[framework];
+  const entries = new Set([...cat.instance, ...cat.static.map((s) => `static ${s}`)]);
+  const members = new Map(); // slot → { refs, spots, entry }
+  // reached at class-definition time (static blocks, static field initializers)
+  // or by ClassName.X anywhere in the file — a use is a use, wherever it sits
+  const roots = new Set([...(staticUses.get(name) ?? [])].map((s) => `static ${s}`));
+  const ctorFields = new Map(); // this._x = v in the constructor: no AST member exists
+  for (const m of node.body.body) {
+    if (m.type === "StaticBlock") { thisRefs(m, "static ").forEach((r) => roots.add(r)); continue; }
+    if (m.type === "TSDeclareMethod" || m.type === "TSIndexSignature") continue;
+    if (m.static && /Property/.test(m.type) && m.value) thisRefs(m.value, "static ").forEach((r) => roots.add(r));
+    const n = keyName(m);
+    if (n === null) return notObs(name, line, `a member name is computed at line ${m.loc.start.line} — the inventory cannot name what it cannot see`);
+    const slot = m.static ? `static ${n}` : n;
+    const refs = thisRefs(m, m.static ? "static " : "");
+    refs.delete(slot); // recursion does not keep itself alive
+    const rec = members.get(slot) ?? { refs: new Set(), spots: [], entry: false };
+    refs.forEach((r) => rec.refs.add(r));
+    rec.spots.push({ line: m.loc.start.line, endLine: m.loc.end.line, kind: kindOf(m) });
+    // a decorated member is registered by the framework: it may call or expose it
+    if (entries.has(slot) || (m.decorators?.length ?? 0) > 0) rec.entry = true;
+    members.set(slot, rec);
+    if (n === "constructor" && !m.static) collectCtorAssignments(m, ctorFields);
+  }
+
+  const alive = new Set();
+  const queue = [...members.keys()].filter((k) => members.get(k).entry || roots.has(k));
+  while (queue.length) {
+    const k = queue.pop();
+    if (alive.has(k) || !members.has(k)) continue;
+    alive.add(k);
+    members.get(k).refs.forEach((r) => { if (members.has(r) && !alive.has(r)) queue.push(r); });
+  }
+  const unreachable = [...members.entries()]
+    .filter(([k]) => !alive.has(k))
+    .flatMap(([k, rec]) => rec.spots.map((s) => ({ name: k, ...s })))
+    .sort((a, b) => a.line - b.line);
+  // HEURISTIC, reported apart (AC5): a constructor field whose name appears in
+  // `this.X` form exactly ONCE in the whole file exists only to be initialized.
+  const constructorFields = [...ctorFields.entries()]
+    .filter(([n]) => !members.has(n) && thisPropCount.get(n) === 1)
+    .map(([n, l]) => ({ name: n, line: l, heuristic: "single this-appearance in file" }));
+  // memberNames: the class's member slots — phantom-coverage (KJC-TSK-0800)
+  // needs to tell "a call to a member of THIS class" from any other call.
+  return { name, line, observable: true, reason: null, framework, catalogVersion: ENTRYPOINT_CATALOG.version, total: members.size, memberNames: [...members.keys()], unreachable, constructorFields };
+}
+
+/** `this.x = …` statements inside the constructor body (first line wins). */
+function collectCtorAssignments(ctor, out) {
+  walk(ctor.body, (n) => {
+    if (n.type !== "AssignmentExpression" || n.left?.type !== "MemberExpression") return;
+    const l = n.left;
+    if (l.object?.type !== "ThisExpression" || l.computed || l.property.type !== "Identifier") return;
+    if (!out.has(l.property.name)) out.set(l.property.name, n.loc.start.line);
+  });
+}
+
+/**
+ * @param {string} source
+ * @param {{file?: string}} [where]
+ * @returns {{file: string, observable: boolean, reason: string|null, classes: Array<object>}}
+ */
+export function analyzeMemberReachability(source, { file = "<source>" } = {}) {
+  let tree;
+  try {
+    tree = parse(source, { sourceType: "unambiguous", allowReturnOutsideFunction: true, plugins: plugins(file) });
+  } catch (err) {
+    return { file, observable: false, reason: `could not be parsed (${err.message}) — not read as clean`, classes: [] };
+  }
+  // String dispatch is the most dangerous false positive: ONE computed access
+  // on `this` that is not a literal makes the whole file not observable — a
+  // list with garbage is worth less than an honest "I do not know".
+  let dynamic = null;
+  const staticUses = new Map(); // ClassName → Set of properties used as ClassName.X
+  const thisPropCount = new Map(); // property → how many `this.X` appearances in the file
+  walk(tree, (n) => {
+    if (n.type !== "MemberExpression") return;
+    if (n.object?.type === "Identifier" && !n.computed && n.property.type === "Identifier") {
+      (staticUses.get(n.object.name) ?? staticUses.set(n.object.name, new Set()).get(n.object.name)).add(n.property.name);
+    }
+    if (n.object?.type !== "ThisExpression") return;
+    if (n.computed && n.property.type !== "StringLiteral" && n.property.type !== "NumericLiteral") { dynamic ??= n.loc.start.line; return; }
+    if (!n.computed && n.property.type === "Identifier") thisPropCount.set(n.property.name, (thisPropCount.get(n.property.name) ?? 0) + 1);
+  });
+  if (dynamic !== null) return { file, observable: false, reason: `computed access on this at line ${dynamic} — string dispatch cannot be followed`, classes: [] };
+
+  const classes = [];
+  walk(tree, (node) => {
+    if (node.type === "ClassDeclaration" || node.type === "ClassExpression") classes.push(analyzeClass(node, { staticUses, thisPropCount }));
+  });
+  return { file, observable: true, reason: null, classes };
+}

package/src/audit/osv-findings.js

@@ -104,6 +104,7 @@ export function parseOsvOutput(raw) {
           aliases: vuln.aliases || [],
           severity: extractSeverity(vuln, groups),
           summary: vuln.summary || vuln.details?.split("\n")[0] || "",
+          publishedAt: vuln.published || null, // the ADVISORY's date — the Steward ages by it (KJC-TSK-0789 AC6)
           package: name,
           version,
           ecosystem,

package/src/claims/cross-check.js

@@ -41,8 +41,13 @@ const SAYS_EMPTY = /(^|\W)(\[\]|\bnone\b|\bno results?\b|\bempty\b|\b0 (results?
  * @returns {{claims: Array<object>, denied: Array<object>, unbacked: Array<object>}}
  */
 export function crossCheck({ text, outputs = [], userSaid = "" }) {
-  const haystack = [...outputs.map(norm), norm(userSaid)];
-  const claims = extractClaims(text).map((claim) => ({ ...claim, status: verdictFor(claim, haystack) }));
+  // Backing can come from an output OR from the user (repeating their datum is not
+  // inventing). The DENIED analysis reads only the OUTPUTS: the user asking "how
+  // many cards are left?" mentions the noun without saying anything about emptiness,
+  // and must not veto a denial — found by the stop-gate wiring test.
+  const sources = outputs.map(norm);
+  const haystack = [...sources, norm(userSaid)];
+  const claims = extractClaims(text).map((claim) => ({ ...claim, status: verdictFor(claim, haystack, sources) }));
   return {
     claims,
     denied: claims.filter((c) => c.status === DENIED),
@@ -50,15 +55,15 @@ export function crossCheck({ text, outputs = [], userSaid = "" }) {
   };
 }
 
-function verdictFor(claim, haystack) {
+function verdictFor(claim, haystack, sources) {
   if (haystack.some((h) => appearsIn(h, claim))) return BACKED;
 
-  // A count stated as non-zero while every source that mentions the same noun says empty:
+  // A count stated as non-zero while every OUTPUT that mentions the same noun says empty:
   // that is the "four cards are waiting" case, and it is the one that blocks.
   if (claim.kind === "count" && Number(claim.value) > 0) {
     const noun = nounAfterCount(claim.sentence, claim.value);
     if (noun) {
-      const mentions = haystack.filter((h) => h.includes(norm(noun)));
+      const mentions = sources.filter((h) => h.includes(norm(noun)));
       if (mentions.length && mentions.every((h) => SAYS_EMPTY.test(h))) return DENIED;
     }
     // Small numbers are prose as often as data ("las dos capas", "3 reglas"): not worth accusing.

package/src/cli/advanced-commands.js

@@ -30,7 +30,7 @@ export const ADVANCED_GROUPS = [
   { title: "Pipeline (piezas sueltas)", commands: ["autorun", "code", "review", "solomon", "agent", "scan", "tournament"] },
   { title: "Análisis pre-run", commands: ["discover", "triage", "researcher", "architect", "onboard", "brief"] },
   { title: "Búsqueda / RAG", commands: ["rag", "qmd", "watch"] },
-  { title: "Calidad / auditoría", commands: ["audit", "check", "mutate", "webperf", "sonar", "privacy", "release", "policy", "claims"] },
+  { title: "Calidad / auditoría", commands: ["audit", "check", "mutate", "webperf", "sonar", "privacy", "release", "policy", "claims", "steward"] },
   { title: "Sesión / board", commands: ["resume", "report", "board", "hu", "adr", "worktree", "undo", "standby", "sentinel", "identity"] },
   { title: "Infra / setup", commands: ["install-tools", "ollama", "skills", "roles", "agents", "env"] },
   { title: "Mantenimiento", commands: ["clean", "sync", "telemetry", "report-issue"] },

package/src/cli/register-meta.js

@@ -6,7 +6,8 @@ import { onboardCommand } from "../commands/onboard.js";
 import { startCommand } from "../commands/start.js";
 import { identityCommand } from "../commands/identity.js";
 import { policyCommand } from "../commands/policy.js";
-import { claimsCommand } from "../commands/claims.js";
+import { claimsCommand, claimsGateCommand } from "../commands/claims.js";
+import { stewardSweepCommand } from "../commands/steward.js";
 import { ragIndexCommand, ragQueryCommand, ragInstallHooksCommand, ragEvalCommand } from "../commands/rag.js";
 import { qmdQueryCommand } from "../commands/qmd.js";
 import { ragMcpCommand } from "../commands/rag-mcp.js";
@@ -314,12 +315,32 @@ export function registerMeta(program, { pkgVersion }) {
 
   // KJC-TSK-0733 PL-A — policy as code: motor determinista en modo warn.
   // CLM-B (KJC-TSK-0802): the data the AI states, checked against what actually ran.
-  program.command("claims").description("Afirmaciones con fuente: comprueba los datos que la IA afirma en un turno contra las salidas de ese turno (ADR claims-with-evidence)")
-    .command("check")
+  const stewardCmd = program.command("steward").description("El Steward: gobierna el ESTADO del proyecto — invariantes con caducidad y cuatro veredictos (épica claims/steward)");
+  stewardCmd.command("sweep")
+    .description("Barrido read-only de los invariantes: deja el informe versionado en .karajan/steward/ (md + json) y sale con 1 solo si algo está ROTO — unknown y not-observable informan con su remedio")
+    .option("--if-stale <days>", "Solo barre si el informe tiene más de N días — retomar trabajo con informe fresco no re-barre")
+    .option("--json", "Machine-readable")
+    .action(async (flags) => {
+      await withConfig(pkgVersion, "steward-sweep", flags, async ({ config }) => {
+        process.exitCode = await stewardSweepCommand({ flags, config });
+      });
+    });
+  const claimsCmd = program.command("claims").description("Afirmaciones con fuente: comprueba los datos que la IA afirma en un turno contra las salidas de ese turno (ADR claims-with-evidence)");
+  claimsCmd.command("check")
     .description("Cruza el mensaje final del turno con sus salidas — exit 2 solo si un dato está DESMENTIDO por su propia fuente; falla abierto si no puede leer el transcript")
     .requiredOption("--transcript <path>", "Ruta del transcript de la sesión (la que pasa el hook)")
+    .option("--file <path>", "Cruza el contenido de este fichero (cuerpo de PR, card) en vez del mensaje final del turno")
     .option("--json", "Machine-readable")
     .action(async (flags) => { process.exitCode = await claimsCommand({ flags }); });
+  claimsCmd.command("gate")
+    .description("El mismo cruce, gobernado por method_gates.claims del proyecto (off|warn|block) — lo invocan los hooks; off = silencio, block = exit 2 solo con un dato desmentido")
+    .requiredOption("--transcript <path>", "Ruta del transcript de la sesión")
+    .option("--file <path>", "Cruza el contenido de este fichero (cuerpo de PR, card) en vez del mensaje final del turno")
+    .action(async (flags) => {
+      await withConfig(pkgVersion, "claims-gate", flags, async ({ config }) => {
+        process.exitCode = await claimsGateCommand({ flags, config });
+      });
+    });
 
   const policyCmd = program.command("policy").description("Policy as code (.karajan/policy.yml, vocabulario cerrado): eval/check deterministas, grant con caducidad, anchor del decision log — deny en commit y CI");
   policyCmd.command("eval")

package/src/commands/claims.js

@@ -9,10 +9,41 @@
  * It fails OPEN. A verifier that cannot read the transcript says so and gets out
  * of the way: a broken check must never hold a session hostage.
  */
+import { readFileSync } from "node:fs";
 import { readTurn } from "../claims/turn.js";
 import { crossCheck, formatClaimReport } from "../claims/cross-check.js";
 
-export async function claimsCommand({ flags = {}, logger = console, readTurnFn = readTurn } = {}) {
+/**
+ * `kj claims gate` — the same check, run by the Stop hook with the PROJECT's
+ * say-so. The hook stays policy-free: kj reads `method_gates.claims` and
+ * decides. "off" (default: adoption is explicit) exits 0 in silence; "warn"
+ * reports and never blocks; "block" refuses only a datum DENIED by its own
+ * source — unbacked data is reported either way, per the accepted ADR:
+ * inform always, block almost never.
+ */
+export async function claimsGateCommand({ flags = {}, config = {}, logger = console, readTurnFn = readTurn, readFileFn = readFileSync } = {}) {
+  const mode = config?.method_gates?.claims ?? "off";
+  if (mode !== "warn" && mode !== "block") return 0;
+  let turn;
+  try {
+    turn = readTurnFn(flags.transcript);
+    // CLM-C: with --file the ARTIFACT is what gets checked — a PR body, a card, a
+    // note — against the same turn's outputs. The final message is what outlives
+    // the turn least; the artifact is what outlives it most.
+    if (flags.file) turn = { ...turn, text: String(readFileFn(flags.file, "utf8")) };
+  } catch {
+    return 0; // not observable: a gate that cannot read its inputs gets out of the way
+  }
+  const result = crossCheck(turn);
+  if (result.denied.length && mode === "block") {
+    logger.error(formatClaimReport(result));
+    return 2;
+  }
+  if (result.denied.length || result.unbacked.length) logger.error(formatClaimReport(result));
+  return 0;
+}
+
+export async function claimsCommand({ flags = {}, logger = console, readTurnFn = readTurn, readFileFn = readFileSync } = {}) {
   const path = flags.transcript;
   if (!path) {
     logger.error("kj claims check: --transcript <path> is required");
@@ -21,6 +52,7 @@ export async function claimsCommand({ flags = {}, logger = console, readTurnFn =
   let turn;
   try {
     turn = readTurnFn(path);
+    if (flags.file) turn = { ...turn, text: String(readFileFn(flags.file, "utf8")) };
   } catch (err) {
     // Not observable: the transcript could not be read. Never reported as clean.
     const note = `kj claims: transcript not readable (${err.message}) — nothing checked`;

package/src/commands/hu.js

@@ -43,7 +43,9 @@ export function findTitleMatches(title, allHus) {
   return { identical, similar };
 }
 
-async function backlogPlan(projectDir) {
+// Exported for the Steward's proposed-work sync (KJC-TSK-0792): broken
+// invariants land in the same backlog the brain already consumes.
+export async function backlogPlan(projectDir) {
   const plans = await listPlans(projectDir);
   const existing = plans.find((p) => p.alias === BACKLOG_NAME || p.name === BACKLOG_NAME);
   if (existing) return loadPlan(projectDir, existing.planId);

package/src/commands/privacy.js

@@ -28,9 +28,12 @@ export async function privacyScanCommand({ paths = [], flags = {}, logger = cons
   const warns = findings.filter((f) => f.severity === "warn");
   const ok = blocks.length === 0;
   process.exitCode = ok ? 0 : 1;
+  // KJC-TSK-0797 AC4: "nothing found" and "found but explained by context"
+  // are different truths — the report says which one it is.
+  const discarded = findings.discardedByContext || 0;
   // --json keeps stdout machine-clean: exactly one JSON document, no prose.
   if (flags.json) {
-    process.stdout.write(`${JSON.stringify({ ok, blocks: blocks.length, warns: warns.length, findings })}\n`);
+    process.stdout.write(`${JSON.stringify({ ok, blocks: blocks.length, warns: warns.length, discardedByContext: discarded, findings })}\n`);
     return { ok, findings };
   }
   for (const f of blocks) logger.error?.(`✗ BLOCK [${f.type}] ${f.source}:${f.line} → ${f.masked}`);
@@ -38,8 +41,9 @@ export async function privacyScanCommand({ paths = [], flags = {}, logger = cons
   if (!list.present) {
     logger.info?.(`hint: no personal denylist found — create ${privacyConfigPath()} (personal: [...], allow: [...]) so YOUR data blocks, not just warns`);
   }
+  const context = discarded > 0 ? `; ${discarded} candidate(s) discarded by context — git SHAs / documentation domains` : "";
   logger.info?.(ok
-    ? `privacy scan: clean of denylist hits (${warns.length} generic warning(s))`
+    ? `privacy scan: clean of denylist hits (${warns.length} generic warning(s)${context})`
     : `privacy scan: ${blocks.length} personal-data hit(s) — this must not ship`);
   return { ok, findings };
 }

package/src/commands/resume.js

@@ -1,5 +1,6 @@
 import { EventEmitter } from "node:events";
 import { resumeFlow } from "../orchestrator.js";
+import { sweepOnResume } from "./steward.js";
 import { createActivityLog } from "../activity-log.js";
 import { printEvent } from "../utils/display/event-handlers.js";
 import { withCliRunLog } from "../utils/cli-run-log.js";
@@ -9,6 +10,9 @@ import { createCliAskQuestion } from "../utils/cli-ask-question.js";
 export async function resumeCommand({ sessionId, answer, config, logger, flags }) {
   const jsonMode = flags?.json;
   const quietMode = config.output?.quiet !== false;
+  // STW-E (KJC-TSK-0793): resuming work is when someone is in front to review
+  // the state — sweep if the report went stale; adoption stays explicit.
+  await sweepOnResume({ config, logger });
 
   // Same wrapper as every other CLI command — without it `.kj/run.log`
   // is never opened during the resume and `kj-tail` stays silent