karajan-code 4.22.0 → 4.23.0

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

package/src/steward/phantom-coverage.js

@@ -0,0 +1,137 @@
+/**
+ * Phantom coverage (KJC-TSK-0800, epic KJC-PCS-0081) — a phantom test is
+ * worse than no test: it adds to the count, feels like a net, and covers
+ * nothing. TWO detectors, because one is not enough: the call graph catches
+ * a unit test that only exercises unreachable members, and LITERAL crossing
+ * catches the case the graph cannot see — GREBLA's hierarchy.spec called no
+ * dead method, it looked for an aria-label that only existed inside one.
+ * Both inherit the reachability perimeter: a NOT OBSERVABLE analysis makes
+ * the detector not observable — no test is accused on an unreliable basis.
+ */
+import { parse } from "@babel/parser";
+
+const parseLoose = (source, file) =>
+  parse(source, {
+    sourceType: "unambiguous", allowReturnOutsideFunction: true,
+    plugins: [...(/\.(ts|tsx|mts|cts)$/.test(file) ? ["typescript"] : []), ...(/\.(tsx|jsx)$/.test(file) || !/\.(ts|mts|cts)$/.test(file) ? ["jsx"] : []), "decorators"],
+  });
+
+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 notObservable = (sourceAnalysis) => {
+  if (!sourceAnalysis?.observable) return sourceAnalysis?.reason || "the reachability analysis is not observable";
+  const classes = (sourceAnalysis.classes || []).filter((c) => c.observable);
+  if (classes.length === 0) return "no class in the source is observable — the analysis cannot vouch for anything";
+  return null;
+};
+const observableClasses = (a) => (a.classes || []).filter((c) => c.observable);
+const bareName = (slot) => slot.replace(/^static /, "");
+
+/**
+ * Unit detector: of the test's member CALLS that belong to an analyzed class,
+ * do all of them land on unreachable members? One live call absolves.
+ * @returns {{observable: boolean, reason?: string, phantoms: Array<{member: string, className: string}>}}
+ */
+export function detectPhantomUnit({ sourceAnalysis, testSource, file = "<test>" }) {
+  const why = notObservable(sourceAnalysis);
+  if (why) return { observable: false, reason: `not observable: ${why}`, phantoms: [] };
+  let tree;
+  try { tree = parseLoose(testSource, file); } catch (err) {
+    return { observable: false, reason: `the test could not be parsed (${err.message})`, phantoms: [] };
+  }
+  // Calls grouped by RECEIVER (weak binding, reviewer's catch): a receiver is
+  // tied to a class only when EVERY member it calls belongs to that class —
+  // mixing two objects under one name must not get a test accused.
+  const byReceiver = new Map();
+  walk(tree, (n) => {
+    if (n.type !== "CallExpression" || n.callee?.type !== "MemberExpression" || n.callee.computed || n.callee.property?.type !== "Identifier") return;
+    const recv = n.callee.object?.type === "Identifier" ? n.callee.object.name : n.callee.object?.type === "ThisExpression" ? "this" : "(expr)";
+    (byReceiver.get(recv) ?? byReceiver.set(recv, new Set()).get(recv)).add(n.callee.property.name);
+  });
+  const phantoms = [];
+  for (const c of observableClasses(sourceAnalysis)) {
+    const members = new Set(c.memberNames.map(bareName));
+    const dead = new Set(c.unreachable.map((u) => bareName(u.name)));
+    for (const [, names] of byReceiver) {
+      const touched = [...names].filter((n) => members.has(n));
+      // bound to this class, and everything it touches is dead → phantom;
+      // one live call — or a call outside the class — absolves the receiver.
+      if (touched.length > 0 && touched.length === names.size && touched.every((n) => dead.has(n))) {
+        for (const n of touched) phantoms.push({ member: n, className: c.name, file });
+      }
+    }
+  }
+  return { observable: true, phantoms };
+}
+
+const literalsOf = (tree, minLength) => {
+  const out = [];
+  walk(tree, (n) => {
+    if (n.type === "StringLiteral" && n.value.trim().length >= minLength) out.push({ value: n.value, line: n.loc.start.line });
+    if (n.type === "TemplateElement" && n.value.cooked && n.value.cooked.trim().length >= minLength) out.push({ value: n.value.cooked, line: n.loc.start.line });
+  });
+  return out;
+};
+
+/**
+ * E2E detector: literals the test looks for that ONLY exist inside
+ * unreachable spans of the source. A literal also present in reachable code
+ * is never reported — that test does cover something.
+ * @returns {{observable: boolean, reason?: string, phantoms: Array<{literal: string, line: number}>}}
+ */
+export function detectPhantomE2E({ sourceText, sourceAnalysis, testSource, file = "<spec>", minLength = 4 }) {
+  const why = notObservable(sourceAnalysis);
+  if (why) return { observable: false, reason: `not observable: ${why}`, phantoms: [] };
+  let sourceTree, testTree;
+  try {
+    sourceTree = parseLoose(sourceText, sourceAnalysis.file || "<source>");
+    testTree = parseLoose(testSource, file);
+  } catch (err) {
+    return { observable: false, reason: `could not be parsed (${err.message})`, phantoms: [] };
+  }
+  const deadSpans = observableClasses(sourceAnalysis).flatMap((c) => c.unreachable.map((u) => [u.line, u.endLine]));
+  const inDead = (line) => deadSpans.some(([a, b]) => line >= a && line <= b);
+  const onlyInDead = new Map(); // literal → line where it lives
+  for (const lit of literalsOf(sourceTree, minLength)) {
+    if (inDead(lit.line)) { if (!onlyInDead.has(lit.value)) onlyInDead.set(lit.value, lit.line); }
+    else onlyInDead.set(lit.value, -1); // seen reachable — poisoned, never reportable
+  }
+  const wanted = new Set(literalsOf(testTree, minLength).map((l) => l.value));
+  const phantoms = [...wanted]
+    .filter((v) => onlyInDead.get(v) !== undefined && onlyInDead.get(v) !== -1)
+    .map((v) => ({ literal: v, line: onlyInDead.get(v), file }));
+  return { observable: true, phantoms };
+}
+
+/**
+ * The temporal signature — zero static analysis, and it would have been
+ * enough for GREBLA: a bug gets fixed or reverted; a phantom fails the SAME
+ * way indefinitely because it proves something that no longer exists.
+ * kj holds no per-test history, so the source is INJECTED and said:
+ * failures = [{test, reason, at}] from whoever owns the CI history.
+ */
+export function assessTemporalSignature({ failures, thresholdDays = 7 } = {}) {
+  if (!Array.isArray(failures)) {
+    return { observable: false, reason: "no per-test failure history handed in — kj holds none; inject it from the CI that owns it", suspects: [] };
+  }
+  const byTest = new Map();
+  for (const f of failures) (byTest.get(f.test) ?? byTest.set(f.test, []).get(f.test)).push(f);
+  const suspects = [];
+  for (const [test, rows] of byTest) {
+    const reasons = new Set(rows.map((r) => String(r.reason || "").trim().toLowerCase()));
+    if (reasons.size !== 1) continue; // changing reasons look like a bug being worked
+    const times = rows.map((r) => Date.parse(r.at)).filter(Number.isFinite);
+    if (times.length < 2) continue;
+    const days = Math.floor((Math.max(...times) - Math.min(...times)) / 86_400_000);
+    if (days >= thresholdDays) suspects.push({ test, reason: rows[0].reason, days, firstAt: new Date(Math.min(...times)).toISOString(), lastAt: new Date(Math.max(...times)).toISOString() });
+  }
+  return { observable: true, suspects };
+}

package/src/steward/proposed-work.js

@@ -0,0 +1,68 @@
+/**
+ * Proposed work (STW-D, KJC-TSK-0792, epic KJC-PCS-0081) — every broken
+ * invariant becomes a CARD in the channel the Brain already consumes, as a
+ * PROPOSAL: evidence, since-when, and a remedy plan that nothing executes
+ * without review (the user's decision, 22-aug: an unreviewed generated plan
+ * can do more harm than the decay itself). The same break UPDATES its card —
+ * a daily sweep must never flood the board with twins — and a green
+ * invariant resolves it with the green evidence.
+ *
+ * kj only writes the board it owns (hu-board). planning-game and external
+ * boards are never mirrored (KJC-TSK-0684: a half-empty parallel board is
+ * worse than none): there the sweep reports synced:false LOUDLY, and the
+ * Sentinel's inevitable notice (STW-C) pushes the host agent — who does
+ * have the board's MCP — to card them.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { addHu, updateHu, updateHuStatus } from "../plan/plan-hu-ops.js";
+import { savePlan } from "../plan/plan-store.js";
+import { backlogPlan } from "../commands/hu.js";
+
+const mapPath = (projectDir) => path.join(projectDir, ".karajan", "steward", "cards.json");
+const readMap = (projectDir) => { try { return JSON.parse(fs.readFileSync(mapPath(projectDir), "utf8")); } catch { return {}; } };
+
+const cardText = (r, brokenSince) => [
+  `Steward invariant BROKEN since ${brokenSince}.`,
+  `Evidence: ${r.evidence || "(none recorded)"}`,
+  `Proposed remedy plan: ${r.remedy || r.renew || "kj steward sweep"}.`,
+  "This plan is a PROPOSAL — review before executing: nothing in it runs unreviewed.",
+].join("\n");
+
+/**
+ * @returns {Promise<{synced: boolean, reason?: string, created?: number, updated?: number, resolved?: number}>}
+ */
+export async function syncProposedWork({ projectDir, config = {}, results = [], sweptAt }) {
+  const backend = config.state_backend || "hu-board";
+  if (backend !== "hu-board") {
+    return { synced: false, reason: `the board lives in ${backend} — kj never mirrors a board it does not own; card the broken invariants through your agent's board tools` };
+  }
+  const map = readMap(projectDir);
+  const broken = results.filter((r) => r.verdict === "broken");
+  const okAgain = results.filter((r) => r.verdict === "ok" && map[r.id]);
+  if (broken.length === 0 && okAgain.length === 0) return { synced: true, created: 0, updated: 0, resolved: 0 };
+
+  const plan = await backlogPlan(projectDir);
+  let created = 0, updated = 0, resolved = 0;
+  for (const r of broken) {
+    const known = map[r.id];
+    if (known) {
+      updateHu(plan, known.huId, { scope: cardText(r, known.brokenSince) });
+      updated += 1;
+    } else {
+      const hu = addHu(plan, { title: `steward: ${r.id} broken — proposed remedy (review before executing)`, scope: cardText(r, sweptAt), created_by: "steward" });
+      map[r.id] = { huId: hu.id, brokenSince: sweptAt };
+      created += 1;
+    }
+  }
+  for (const r of okAgain) {
+    updateHu(plan, map[r.id].huId, { scope: `Resolved: the invariant is green again (${r.evidence || "no evidence text"}) — validation stays with the user.` });
+    updateHuStatus(plan, map[r.id].huId, "done");
+    delete map[r.id];
+    resolved += 1;
+  }
+  await savePlan(projectDir, plan);
+  fs.mkdirSync(path.dirname(mapPath(projectDir)), { recursive: true });
+  fs.writeFileSync(mapPath(projectDir), `${JSON.stringify(map, null, 2)}\n`);
+  return { synced: true, created, updated, resolved };
+}