karajan-code 4.21.0 → 4.23.0

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/checks/ai-trash.js

@@ -23,7 +23,7 @@ function createAiTrashCheck() {
         ok: false,
         severity: "warn",
         detail: "kj-trash not found — destructive ops unprotected",
-        fix: "Install karajan-code globally (npm i -g karajan-code) so kj-trash is on PATH, then run `kj-trash install --claude-code`",
+        fix: "Install karajan-code globally (npm i -g @karajan-family/code) so kj-trash is on PATH, then run `kj-trash install --claude-code`",
       };
     },
   };

package/src/checks/mcp-health.js

@@ -109,7 +109,7 @@ export function createKarajanMcpCheck() {
         detail: result.ok
           ? result.detail
           : `karajan-mcp did not respond: ${result.detail} — OPTIONAL in v4: your agent runs kj directly; only shell-less hosts need MCP`,
-        fix: result.ok ? undefined : "Only if you need MCP: install via npm (`npm i -g karajan-code`) — the standalone binary does not bundle it",
+        fix: result.ok ? undefined : "Only if you need MCP: install via npm (`npm i -g @karajan-family/code`) — the standalone binary does not bundle it",
         extra: { binPath },
       };
     },

package/src/checks/native-build.js

@@ -45,7 +45,7 @@ export function createNativeBuildCheck({ loadDb = defaultLoadDb, isPnpm = isPnpm
             ok: false,
             severity: "warn",
             detail: "better-sqlite3 native build was skipped — pnpm blocks dependency build scripts by default",
-            fix: "Approve the build then reinstall: `pnpm approve-builds better-sqlite3` — or install with npm: `npm i -g karajan-code`",
+            fix: "Approve the build then reinstall: `pnpm approve-builds better-sqlite3` — or install with npm: `npm i -g @karajan-family/code`",
           };
         }
         return {
@@ -55,7 +55,7 @@ export function createNativeBuildCheck({ loadDb = defaultLoadDb, isPnpm = isPnpm
           // modules by design — name the consequence (RAG/board/MCP need the
           // npm install) instead of implying the install is broken.
           detail: `better-sqlite3 failed to load: ${firstLine} — DB-backed features (RAG, board, MCP) unavailable; the standalone binary does not bundle native modules`,
-          fix: "Reinstall to rebuild native modules: `npm i -g karajan-code`",
+          fix: "Reinstall to rebuild native modules: `npm i -g @karajan-family/code`",
         };
       }
     },

package/src/checks/release-check.js

@@ -9,6 +9,37 @@ import { existsSync, readFileSync } from "node:fs";
 import { isAbsolute, join } from "node:path";
 import { runCommand } from "../utils/process.js";
 import { loadPrivacyList, scanPaths } from "../privacy/scan.js";
+import { checkStagedDiff, loadPolicy } from "../policy/engine.js";
+
+// KJC-TSK-0769 — the effect boundary: what ships is re-evaluated against the
+// policy IN FORCE now, not the one each PR was merged under. Artifact rules
+// only: diff-threshold invariants are PR-scoped by definition — skipped, and
+// said — so no line metric is needed (without a tag, the whole tree counts).
+async function policyRangeCheck(projectDir) {
+  const { policy, errors } = loadPolicy({ projectDir });
+  if (errors.length > 0) return { name: "policy", ok: false, detail: `policy.yml invalid — ${errors[0]}` };
+  const described = await runCommand("git", ["-C", projectDir, "describe", "--tags", "--abbrev=0", "--match", "v[0-9]*"]);
+  const tag = described.exitCode === 0 ? described.stdout.trim() : null;
+  const scope = tag ? `${tag}..HEAD` : "whole history (no previous tag)";
+  const prScoped = new Set((policy.invariants ?? []).filter((i) => i.kind === "diff-threshold").map((i) => i.id));
+  try {
+    const listed = await runCommand("git", tag
+      ? ["-C", projectDir, "diff", `${tag}..HEAD`, "--name-only"]
+      : ["-C", projectDir, "ls-tree", "-r", "--name-only", "HEAD"]);
+    if (listed.exitCode !== 0) throw new Error((listed.stderr || "git failed").trim());
+    const files = listed.stdout.split("\n").map((s) => s.trim()).filter(Boolean);
+    const violations = checkStagedDiff(policy, { role: "coder", files, netLinesAdded: null }).filter((v) => !prScoped.has(v.rule_id));
+    const hard = violations.filter((v) => v.enforcement === "deny");
+    const skipped = prScoped.size > 0 ? `; ${prScoped.size} diff-threshold invariant(s) skipped (PR-scoped)` : "";
+    if (hard.length > 0) {
+      const list = hard.map((v) => `[${v.rule_id}]${v.file ? ` ${v.file}` : ""}`).join(", ");
+      return { name: "policy", ok: false, detail: `${hard.length} deny violation(s) in ${scope} against the current policy: ${list}` };
+    }
+    return { name: "policy", ok: true, detail: `${scope} clean against the current policy (${violations.length} warning(s))${skipped}` };
+  } catch (err) {
+    return { name: "policy", ok: false, detail: `could not evaluate ${scope}: ${err.message}` };
+  }
+}
 
 const semverCmp = (a, b) => {
   const pa = a.split(".").map(Number), pb = b.split(".").map(Number);
@@ -93,10 +124,39 @@ async function declaredItems(projectDir, config, version) {
   return checks;
 }
 
+/**
+ * MIG-B (KJC-TSK-0752, ADR 0004): while a package dual-publishes under two npm
+ * names, their `latest` dist-tags must move in LOCKSTEP. A torn dual-publish —
+ * one name released, the other not — is invisible from the repo (both installs
+ * "work") and every surface that teaches one name silently diverges from the
+ * other. The pair is read from scripts/dual-publish.mjs, which is the one
+ * place that knows it; no dual script, no check.
+ */
+export async function dualPublishCheck(projectDir, pkg, run = runCommand) {
+  const script = join(projectDir, "scripts", "dual-publish.mjs");
+  if (!pkg?.name || !existsSync(script)) return null;
+  const src = readFileSync(script, "utf8");
+  const legacy = (src.match(/LEGACY_NAME = "([^"]+)"/) || [])[1];
+  const scoped = (src.match(/SCOPED_NAME = "([^"]+)"/) || [])[1];
+  if (!legacy || !scoped || pkg.name !== legacy) return null;
+  const latest = async (name) => {
+    const out = await run("npm", ["view", name, "dist-tags.latest"], { cwd: projectDir });
+    if (out.exitCode !== 0) throw new Error(`npm view ${name} failed`);
+    return (out.stdout || "").trim();
+  };
+  try {
+    const [a, b] = await Promise.all([latest(legacy), latest(scoped)]);
+    const ok = Boolean(a) && a === b;
+    return { name: "dual-publish", ok, detail: ok ? `${legacy} and ${scoped} both at ${a}` : `dist-tags diverge: ${legacy}@${a || "?"} vs ${scoped}@${b || "?"} — a torn dual-publish; publish the missing name before releasing on top` };
+  } catch (err) {
+    return { name: "dual-publish", ok: false, detail: `could not read npm dist-tags (${err.message}) — the lockstep cannot be verified, and unverified is not ok` };
+  }
+}
+
 export async function runReleaseCheck({ projectDir = process.cwd(), config = {} } = {}) {
   const { checks, version, pkg } = await genericChecks(projectDir);
   const pack = await packPrivacyCheck(projectDir, pkg);
-  if (pack) checks.push(pack);
-  checks.push(...await declaredItems(projectDir, config, version));
+  const dual = await dualPublishCheck(projectDir, pkg);
+  checks.push(...(pack ? [pack] : []), ...(dual ? [dual] : []), await policyRangeCheck(projectDir), ...await declaredItems(projectDir, config, version));
   return { ok: checks.every((c) => c.ok), version, checks };
 }

package/src/claims/cross-check.js

@@ -0,0 +1,86 @@
+/**
+ * Crossing what was said against what actually ran (CLM-A, KJC-TSK-0801).
+ *
+ * The transcript is the register of sources: every command, query and read left
+ * its output there, so nothing has to be annotated by hand. A datum that appears
+ * in some output is BACKED; one that appears nowhere came out of the model's
+ * memory (UNBACKED); one whose own source says otherwise is DENIED — and that
+ * is the only verdict that blocks, because it is a proven hallucination and not
+ * a suspicion.
+ *
+ * What cannot be decided is NOT_CHECKABLE, never an accusation: a guard that
+ * cries wolf gets switched off (KJC-PCS-0082).
+ */
+import { extractClaims } from "./extract.js";
+
+export const BACKED = "backed";
+export const UNBACKED = "unbacked";
+export const DENIED = "denied";
+export const NOT_CHECKABLE = "not_checkable";
+
+const norm = (s) => String(s ?? "").toLowerCase();
+const escape = (s) => s.replaceAll(/[.*+?^${}()|[\]\\]/g, "\\$&");
+
+/**
+ * Numbers must match as WHOLE tokens: searching "4" as a substring finds it inside "24.6 kB"
+ * and backs a figure nobody measured. Found while running this over a real message — the
+ * synthetic tests had passed. Ids, paths and versions are distinctive enough as substrings.
+ */
+function appearsIn(output, claim) {
+  const needle = norm(claim.value);
+  if (claim.kind === "path" || claim.kind === "card" || claim.kind === "version") return output.includes(needle);
+  return new RegExp(`(?<![\\w.])${escape(needle)}(?![\\w.])`).test(output);
+}
+
+/** "no cards", "[]", "0 results" — a source that positively states emptiness. */
+const SAYS_EMPTY = /(^|\W)(\[\]|\bnone\b|\bno results?\b|\bempty\b|\b0 (results?|items?|matches|cards?|files?)\b)/i;
+
+/**
+ * @param {{text: string, outputs: string[], userSaid?: string}} input
+ *   outputs: tool outputs of the turn, in order. userSaid: what the user wrote (also a source).
+ * @returns {{claims: Array<object>, denied: Array<object>, unbacked: Array<object>}}
+ */
+export function crossCheck({ text, outputs = [], userSaid = "" }) {
+  // 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),
+    unbacked: claims.filter((c) => c.status === UNBACKED),
+  };
+}
+
+function verdictFor(claim, haystack, sources) {
+  if (haystack.some((h) => appearsIn(h, claim))) return BACKED;
+
+  // 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 = 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.
+    if (Number(claim.value) <= 3) return NOT_CHECKABLE;
+  }
+  return UNBACKED;
+}
+
+function nounAfterCount(sentence, value) {
+  const m = new RegExp(`${value}\\s+([a-zá-ú]{4,})`, "i").exec(sentence);
+  return m ? m[1] : null;
+}
+
+/** One human line per problem; the message is what makes a guard usable. */
+export function formatClaimReport({ denied, unbacked }) {
+  const lines = [];
+  for (const c of denied) lines.push(`✗ "${c.value}" (${c.kind}) is DENIED by the output that should back it — ${c.sentence.slice(0, 100)}`);
+  for (const c of unbacked) lines.push(`? "${c.value}" (${c.kind}) has no backing in this turn — verify it or say it is from memory`);
+  return lines.join("\n");
+}

package/src/claims/extract.js

@@ -0,0 +1,56 @@
+/**
+ * Hard data in what the AI says (CLM-A, KJC-TSK-0801, ADR "claims with evidence").
+ *
+ * A model states an invented figure with the same confidence as a measured one,
+ * and that figure travels to a PR, a card, another session or the user, where
+ * nobody checks it again. This module pulls the CHECKABLE data out of a text —
+ * counts, versions, file paths, card ids, commit SHAs — so it can be crossed
+ * against what actually ran. Prose is left alone: only data is verifiable.
+ *
+ * Deterministic and free: no model in the loop. Verifying must be cheaper than
+ * inventing, or nobody will verify.
+ */
+
+/** Sentences that ALREADY admit they are unverified are respected, never reported. */
+const HEDGES = /\b(de memoria|sin (comprobar|verificar)|no (lo )?he (comprobado|verificado)|creo que|puede que|quizá|quizás|probablemente|from memory|unverified|not checked|i think|probably)\b/i;
+
+// Most specific first: a number already claimed as a PR or a version is not also a bare count.
+// A number with no unit next to it (an OTP, a phone) is deliberately NOT a claim: it is not
+// verifiable from prose, and some of them are secrets that must never travel into a report.
+const PATTERNS = [
+  { kind: "card", re: /\b([A-Z]{3}-(?:TSK|BUG|PCS|SPR|PLA|PRP)-\d{4})\b/g, value: (m) => m[1] },
+  { kind: "path", re: /\b((?:[\w.-]+\/){1,}[\w.-]+\.\w{1,5})\b/g, value: (m) => m[1] },
+  { kind: "version", re: /\bv?(\d+\.\d+\.\d+(?:-[\w.]+)?)\b/g, value: (m) => m[1] },
+  { kind: "pr", re: /(?:^|[\s(])#(\d{2,6})\b/g, value: (m) => m[1] },
+  { kind: "sha", re: /\b([0-9a-f]{7,40})\b/g, value: (m) => m[1] },
+  // A number that means something: "1004 ficheros", "8 ocurrencias", "53 tests".
+  { kind: "count", re: /\b(\d[\d.,]*)\s+(?=[a-záéíóúñ]{3,})/gi, value: (m) => m[1].replaceAll(".", "").replaceAll(",", "") },
+];
+
+/** Splits into sentences so a hedge only covers what it is attached to. */
+const sentences = (text) => String(text || "").split(/(?<=[.!?\n])\s+/).filter(Boolean);
+
+/**
+ * @param {string} text
+ * @returns {Array<{kind: string, value: string, sentence: string}>} unique claims, in order.
+ */
+export function extractClaims(text) {
+  const out = [];
+  const seen = new Set();
+  for (const sentence of sentences(text)) {
+    if (HEDGES.test(sentence)) continue; // saying "I did not check" is the behaviour to encourage
+    const claimedHere = new Set();
+    for (const { kind, re, value } of PATTERNS) {
+      for (const m of sentence.matchAll(re)) {
+        const v = value(m);
+        if (claimedHere.has(v)) continue; // already claimed as something more specific
+        claimedHere.add(v);
+        const key = `${kind}:${v}`;
+        if (seen.has(key)) continue;
+        seen.add(key);
+        out.push({ kind, value: v, sentence: sentence.trim() });
+      }
+    }
+  }
+  return out;
+}

package/src/claims/turn.js

@@ -0,0 +1,54 @@
+/**
+ * Reading one turn out of the transcript (CLM-B, KJC-TSK-0802).
+ *
+ * The transcript is the register of sources: what the AI finally said, what the
+ * user asked, and every tool output in between. Nothing is annotated by hand —
+ * this just reads what the session already wrote.
+ *
+ * A turn = from the user's last real message to the end. A "user" entry whose
+ * content is a tool_result is NOT the user talking: it is the machine answering.
+ */
+import { readFileSync } from "node:fs";
+
+const MAX_OUTPUT = 20_000; // a single huge output must not eat the whole check
+const blocks = (entry) => {
+  const c = entry?.message?.content;
+  return Array.isArray(c) ? c : typeof c === "string" ? [{ type: "text", text: c }] : [];
+};
+const isToolResult = (entry) => blocks(entry).some((b) => b.type === "tool_result");
+const textOf = (value) =>
+  typeof value === "string" ? value : Array.isArray(value) ? value.map((b) => b?.text ?? "").join("\n") : String(value ?? "");
+
+/** Parses the JSONL, ignoring lines that are not valid JSON (a partial write must not throw). */
+export function readEntries(path) {
+  const out = [];
+  for (const line of readFileSync(path, "utf8").split("\n")) {
+    if (!line.trim()) continue;
+    try { out.push(JSON.parse(line)); } catch { /* a half-written line is not a reason to fail */ }
+  }
+  return out;
+}
+
+/**
+ * @param {string} path transcript_path given by the hook
+ * @returns {{text: string, outputs: string[], userSaid: string}}
+ *   text: what the AI says at the end of the turn (its final prose, no thinking).
+ */
+export function readTurn(path) {
+  const entries = readEntries(path);
+  const startedAt = entries.findLastIndex((e) => e.type === "user" && !isToolResult(e));
+  const turn = startedAt >= 0 ? entries.slice(startedAt) : entries;
+
+  const userSaid = startedAt >= 0 ? textOf(entries[startedAt]?.message?.content) : "";
+  const outputs = [];
+  for (const entry of turn) {
+    for (const b of blocks(entry)) {
+      if (b.type === "tool_result") outputs.push(textOf(b.content).slice(0, MAX_OUTPUT));
+    }
+  }
+  // The final message is the last assistant entry that actually says something
+  // (one with tool_use only is the AI working, not the AI reporting).
+  const finals = turn.filter((e) => e.type === "assistant" && blocks(e).some((b) => b.type === "text" && b.text?.trim()));
+  const text = finals.length ? blocks(finals.at(-1)).filter((b) => b.type === "text").map((b) => b.text).join("\n") : "";
+  return { text, outputs, userSaid };
+}

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"] },
+  { 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"] },