candor-ts 0.26.0 → 0.28.0

package/query.mjs

@@ -25,7 +25,7 @@ import { fileURLToPath } from "node:url";
 
 import { parsePolicy, scopeMatches, discoverConfigPolicy, parseUnknownAliases, discoverConfigText,
          evaluatePolicy, reportNetClasses, resolveReasonClasses, discoverConfigPath,
-         policyVocabularyAnchor, policyErrorText, policyErrorUnevaluated, policyUnreadable,
+         policyVocabularyAnchor, policyErrorText, policyRefusalUnevaluated, policyUnreadable, policyZeroRules,
          fatalPolicyErrors, refusalVerdict,
          unanswerableScoped } from "./policy.mjs";
 import { hasReport } from "./query-core.mjs";
@@ -42,9 +42,11 @@ import { impact as coreImpact, path as corePath, gains as coreGains,
          containment as coreContainment, diff as coreDiff,
          where as coreWhere, map as coreMap, whatif as coreWhatif,
          fix as coreFix, fixGate as coreFixGate, unverified as coreUnverified,
-         matches as coreMatches, gainsCoverage, parseClassFilter, ClassFilterError,
-         loadReport, loadCallgraph, loadGateReport, reportVersion, reportPackage,
-         reportUnanalyzed, advisoryAnswer } from "./query-core.mjs";
+         matches as coreMatches, gainsCoverage, gainsCompletenessFields, parseClassFilter, ClassFilterError,
+         loadReport, loadCallgraph, reportCallsGraph, loadGateReport, gateReportInputFiles,
+         reportVersion, reportPackage,
+         advisoryAnswer,
+         reportCompleteness, mustHedge, completenessFields, absorbCompleteness } from "./query-core.mjs";
 const emit = (v) => console.log(JSON.stringify(v, null, 1));
 // ⟨0.24⟩ SPEC §3.2 — THE OTHER CHANNEL. `advisoryAnswer` withdraws the claim from the JSON; this withdraws
 // it from the one a human reads, and the spec requires both because a test that reads one channel is
@@ -71,6 +73,79 @@ const advisoryUnevaluatedNote = (verb, unevaluated, tail) => {
   console.error(`  ${tail}`);
 };
 const UNEVAL_TAIL_STRICT = "(`ok` is OMITTED — neither value is a statement this input licenses; no remedy is offered for a boundary the gate could not adjudicate; `--strict` exits 2, the could-not-evaluate code)";
+
+// ---- ⟨0.28⟩ SPEC §2 — AN ADVISORY VERB OVER A CONFIGURED ZERO-RULE POLICY ANSWERS WITH THE CAVEAT
+// DOCUMENT, RESULT KEYS WITHHELD, EXIT UNCHANGED.
+//
+// §6.2 makes the same condition an exit-2 REFUSAL for the GATE, on the ground that `ok: true` is a claim
+// about the code no such run is entitled to make. These verbs share that loader and were not touched by
+// the rung. They are ADVISORY — they set no verdict, so the gate's refusal posture is the wrong import.
+// What they DO produce is an answer *relative to a policy*, and relative to no rules that answer is not a
+// finding, it is an absence of questions. MEASURED here 2026-08-12 over `# no rules yet`:
+//
+//     whatif      {"of":[…],"affected":[…],"violations":[],"ok":true}          exit 0
+//     fix         {"crossing":false,"reason":"not-forbidden"}                  exit 0
+//     fix-gate    {"ok":true,"remedies":[]}                                    exit 0 (also --strict)
+//     unverified  {"ok":true,"unverified":[]}                                  exit 0 (also --strict)
+//
+// `not-forbidden` by a policy that forbids nothing is vacuously true — an all-clear produced by deleting
+// the question. So the result keys are withheld: `unverified` does not emit an empty `unverified` list
+// over a policy that asked nothing, for the same reason ⟨0.27⟩'s refusal document must not carry
+// `violations`. And `fix` emits NO `crossing` KEY — ⟨0.28⟩ pins that key as present exactly when the verb
+// answered, and here it did not.
+//
+// `fix` IS IN THE LIST BECAUSE THE LIST IS A CONDITION, NOT AN ENUMERATION. §2 names `whatif`/`fix-gate`/
+// `unverified` because those were the three in front of the author, and records the divergence that
+// created: candor-rust extended the rule to `fix` and flagged it, candor-swift read the list as closed and
+// did not. Every verb that answers relative to a CONFIGURED policy takes this rule.
+//
+// NO NEW KEY. The document carries `unevaluated` with one entry naming the whole policy, in the EXACT
+// spelling this engine's own gate routes already use for their zero-rule refusal (`policyZeroRules`, one
+// builder, shared) — so the gate and the advisory verbs say the same thing about the same policy in the
+// same words, which is what makes a cross-engine consumer possible at all.
+//
+// A policy that is NOT CONFIGURED is untouched: that remains the honest way to say "I am not gating"
+// (§6.2), and it is exactly why a configured zero-rule policy is never a legitimate expression of it.
+const policyAskedNothing = (pol) => !!pol && !pol.deny.length && !pol.allow.length && !pol.forbid.length;
+const emitZeroRuleCaveat = (verb, policyFile, comp) => {
+  const { unevaluated } = policyZeroRules(policyFile);
+  console.error(`candor-ts: ${verb}: the policy at ${policyFile} yielded NO RULES — every line was ignored `
+    + `(see the \`ignoring policy rule\` warnings above), the file is empty, or it holds only comments. A `
+    + `policy with no rules ASKS NOTHING, so this verb has no answer to give relative to it: the result `
+    + `keys are WITHHELD and this caveat stands in their place (SPEC §2 ⟨0.28⟩). \`gate\` refuses outright `
+    + `over this policy (exit 2). If you did not mean to gate, remove the policy configuration rather than `
+    + `pointing it at a file with no rules in it.`);
+  // The report-completeness caveat rides the SAME document when it applies: the two disclosures are
+  // independent — one says the policy asked nothing, the other that the report could not see everything —
+  // and each says something the other does not.
+  emit({ unevaluated, ...completenessFields(comp) });
+};
+// ⟨0.28⟩ SPEC §2's OTHER cause on the ADVISORY channel — `analyzed.count: 0`, which `advisoryIncompleteNote`
+// above could not say because it is written around an unread FILE and this report names none. Same two
+// channels, different sentence, and the tail is the OPPOSITE one: the gate exits 0 over these bytes
+// (⟨0.24⟩: a disclosure, not an exit code), so `--strict` does not move either and this note is all there is.
+// ⟨0.28⟩ The THIRD cause on the advisory channel — a report file under the locator whose bytes could not
+// be parsed. Its own sentence because the repair differs (fix or re-write that file, not "re-scan the
+// sources"), and the gate tail is the `unanalyzed` one: `gate --report` REFUSES over a corrupt member
+// (measured, exit 2), so `--strict`'s exit is bounded by the gate exactly as for an unread source file.
+const advisoryUnreadableNote = (verb, unreadable) => {
+  console.error(`candor-ts: ${verb} could NOT fully evaluate — ${unreadable.length} report file(s) under this locator could not be parsed, and whatever they say is not in this answer:`);
+  for (const f of unreadable) console.error(`    ${f}`);
+  console.error("  (`ok` is OMITTED — neither value is a statement this input licenses; `gate --report` exits 2 over these bytes. Fix or regenerate the corrupt report.)");
+};
+// ⟨0.28⟩ SPEC §2's THIRD ROW on the ADVISORY channel. Its own sentence beside the judged-nothing one
+// below, for the reason `incompleteAnswerNote` gives: that note asserts `analyzed.count: 0`, which a
+// row-3 report never said, and the repair is a producer that emits a manifest rather than a scan that
+// reaches a conclusion.
+const advisoryNoManifestNote = (verb, files) => {
+  console.error(`candor-ts: ${verb} could NOT fully evaluate — ${files.length} report(s) under this locator carry NO \`analyzed\` manifest at all (SPEC §2 row 3, a pre-⟨0.21⟩ producer), so they make no claim about what was judged and their silence licenses none either:`);
+  for (const f of files) console.error(`    ${f}`);
+  console.error("  (`ok` is OMITTED — neither value is a statement this input licenses. `gate --report` exits 0 over these bytes, so this note is the whole of the warning. Re-scan with a current engine so the report carries its manifest.)");
+};
+const advisoryJudgedNothingNote = (verb) => {
+  console.error(`candor-ts: ${verb} could NOT fully evaluate — the report(s) under this locator say they JUDGED NOTHING (⟨0.24⟩ \`analyzed.count\` is 0, absent with no entries, or unreadable), so absence from \`functions\` licenses no purity claim about any unit and there is nothing here to certify`);
+  console.error("  (`ok` is OMITTED — neither value is a statement this input licenses. NOTHING DOWNSTREAM WILL CATCH THIS FOR YOU: `gate --report` exits 0 over a judged-nothing report and `--strict` does not move either, so this note is the whole of the warning. Re-scan the sources you meant to check.)");
+};
 // The §6 effect vocabulary — used to reject a typo'd effect name in `where` (corpus-audit #3). Kept in step
 // with SPEC §6 / the umbrella's list; an unknown name PRESENT in a report (a spec extension) is still allowed.
 const KNOWN_EFFECTS = ["Net", "Fs", "Db", "Llm", "Exec", "Env", "Clock", "Ipc", "Log", "Rand", "Clipboard", "Unknown"];
@@ -95,26 +170,167 @@ const wantJsonOut = (a) =>
   a.includes("--json") || (!a.includes("--text") && !a.includes("--human") && !process.stdout.isTTY);
 // Emit the pinned JSON, or render prose via proseFn(data). Returns data so the caller can still exit on it.
 const put = (a, data, proseFn) => { if (!proseFn || wantJsonOut(a)) emit(data); else proseFn(data); return data; };
+
+// ---- ⟨0.28⟩ SPEC §2 — THE COMPLETENESS CAVEAT ON A *DESCRIPTIVE* VERB. `advisoryAnswer` +
+// `advisoryIncompleteNote` above are the two channels for a verb that renders a VERDICT; the clause they
+// implement was scoped to verdicts, and ⟨0.28⟩ widens it to "any verb whose output could be read as a
+// negative finding about the code — a verdict, an empty result set, or a zero count". These three helpers
+// are the SAME two channels for an ANSWER. One reader (`reportCompleteness`), one key set
+// (`completenessFields`), one trigger (`mustHedge`) — a second mechanism is how the family ended up with
+// two element rules for the manifest reader, and how one channel goes quiet while the other is asserted on.
+
+// What `gate --report` does over THESE SAME BYTES, as one sentence — a function and not a constant because
+// the two causes get OPPOSITE answers. §3.3 makes an incomplete analysis of the target's own code an exit-2
+// gate cause, so "the gate refuses too" is true of `unanalyzed`; ⟨0.24⟩ ruled count-0 the other way ("a
+// disclosure, not an exit code"), so the gate exits 0 there. A note that sends the reader to a CI job which
+// then passes teaches them the warning is noise — the disclosure discrediting itself. The count-0 sentence
+// is also the more urgent one and says so: nothing downstream fails closed on those bytes.
+const gateLine = (comp) => (comp.unanalyzed.length || comp.unreadable?.length
+  ? "`gate --report` exits 2 over these bytes."
+  : "NOTHING DOWNSTREAM WILL CATCH THIS FOR YOU — `gate --report` exits 0 over a judged-nothing report (⟨0.24⟩: a disclosure, not an exit code), so this note is the whole of the warning.");
+
+// The HUMAN half. A no-op when there is nothing to disclose, so an ordinary run stays byte-identical, and
+// printed BEFORE the answer because it qualifies a NON-EMPTY result as much as an empty one: a function in
+// an unread file performs the effect or does not, and no list below can say which.
+//
+// ON STDOUT, WITH THE ANSWER IT QUALIFIES — this engine had it on stderr, alone against three: java
+// documents stdout as deliberate ("a caveat on the other stream is one `2>/dev/null` from gone"), and
+// swift's log records catching and REVERTING exactly this stderr choice after diffing against rust. The
+// caveat and the answer must travel the same pipe, or a `2>/dev/null` consumer keeps the reassurance and
+// loses its withdrawal. Every caller is on the PROSE branch (`putAnswer`'s else-arm, `tour`'s human arm,
+// `gains`' else-arm), so stdout is never carrying a JSON document when this prints — JSON-mode runs take
+// the machine half (`completenessFields`) instead and this function is not called at all.
+const incompleteAnswerNote = (comp, soWhat, tail) => {
+  if (!mustHedge(comp)) return;
+  // Three causes, one sentence each, and only true ones: `unreadable` is a report file whose BYTES could
+  // not be parsed — not "declared unanalyzed units" and not "judged nothing", both of which would send
+  // the reader to the wrong repair (rust names it separately for the same reason).
+  const causes = [];
+  if (comp.unanalyzed.length)
+    causes.push(`declare ${comp.unanalyzed.length} unit(s) candor could not analyze`);
+  if (comp.judgedNothing.length)
+    causes.push("say they JUDGED NOTHING (`analyzed.count: 0`)");
+  // ⟨0.28⟩ SPEC §2's THIRD ROW, and it gets its OWN sentence because the one above was FALSE for it:
+  // this engine told the reader a row-3 report "says it judged nothing (`analyzed.count: 0`)" when the
+  // report declares nothing at all, and this family rates a false disclosure worse than a missing one.
+  // The repairs differ too — row 1 wants a scan that reaches a conclusion, row 3 wants a producer that
+  // emits a manifest — so a reader given the wrong one goes to the wrong place.
+  if (comp.noManifest?.length)
+    causes.push(`include ${comp.noManifest.length} report(s) carrying NO \`analyzed\` manifest at all`);
+  if (comp.unreadable?.length)
+    causes.push(`include ${comp.unreadable.length} file(s) that could not be parsed at all`);
+  console.log(`candor-ts: ⚠ INCOMPLETE — the report(s) under this locator ${causes.join(", and ")}, so ${soWhat}:`);
+  for (const u of comp.unanalyzed) console.log(`    ${u.path}${u.reason ? `  (${u.reason})` : ""}`);
+  if (comp.judgedNothing.length)
+    console.log("    (a report that judged nothing names no function at all — its silence is not a purity claim about any unit)");
+  for (const f of comp.noManifest ?? [])
+    console.log(`    ${f} — no \`analyzed\` manifest (a pre-⟨0.21⟩ producer): it makes no claim about what was judged, so its silence licenses none either. Re-scan with a current engine.`);
+  for (const f of comp.unreadable ?? [])
+    console.log(`    ${f} — could not be parsed (corrupt or mid-write), so whatever it says is not in this answer`);
+  console.log(`    ${tail} ${gateLine(comp)}`);
+};
+
+// The MACHINE half. Spread LAST so the verb's own pinned key order is untouched (JS objects keep insertion
+// order), and `{}` on a complete report — the whole document is then byte-identical to a pre-⟨0.28⟩ one.
+//
+// THE COLLISION GUARD THIS USED TO CARRY IS GONE, because ⟨0.28⟩ Rung A removed the only shape that could
+// construct it. `map` was the one caller whose top level is a USER NAMESPACE, and it answered by MERGING
+// the hedge over a module literally named `incomplete` and disclosing the loss on stderr — a lost row the
+// operator was told about, which was the best available answer while the caveat had to ride the result.
+// It no longer does: `map` takes `putCaveatInstead` below, where the caveat REPLACES the document and
+// nothing is displaced. Every remaining caller has a FIXED key set of its own (`where`
+// {effect,directly,inherited}, `reachable` {entryPoints,effects}, `containment` {contained,ambient},
+// `blindspots` {sources,totalUnknown}), so a collision here is not constructible from any report.
+// Deleted rather than kept as a dormant guard: a check whose condition cannot arise reads as coverage.
+const withCompleteness = (data, comp) => ({ ...data, ...completenessFields(comp) });
+
+// `put`, plus the caveat on BOTH channels from ONE trigger — a caller cannot get the JSON half and the prose
+// half to disagree, which is exactly the mutant (`ec1a441`) that survived a whole suite in candor-rust.
+// `proseFn` receives the hedge flag as its second argument so it can WITHDRAW its reassuring sentence; the
+// note alone is not enough, because "no Unknown sources ✓" IS the prose spelling of the empty JSON.
+const putAnswer = (a, data, proseFn, comp, soWhat, tail) => {
+  if (!proseFn || wantJsonOut(a)) { emit(withCompleteness(data, comp)); return data; }
+  incompleteAnswerNote(comp, soWhat, tail);
+  proseFn(data, mustHedge(comp));
+  return data;
+};
+
+// ---- ⟨0.28⟩ RUNG A — SPEC §2: "A VERB WHOSE PINNED SHAPE CANNOT CARRY THE CAVEAT MUST EMIT THE CAVEAT
+// DOCUMENT INSTEAD OF ITS RESULT DOCUMENT." Not a result document with the caveat omitted, and not an
+// empty result of the pinned shape. `putAnswer` above SPREADS the caveat into the answer, which works for
+// every verb with a fixed key set; two verbs have no such place:
+//
+//   show   pinned to a TOP-LEVEL ARRAY — nowhere to put a key at all. MEASURED here 2026-08-12 over a
+//          report declaring one `unanalyzed` unit: `[]`, exit 0, no caveat on ANY channel. *Nothing
+//          performs this effect*, asserted about code nobody examined.
+//   map    keyed by the operator's own MODULE names. MEASURED: the caveat keys merged INTO the module
+//          namespace, and the merged shape disclosed the collision loudly while still dropping the row.
+//
+// AND THE RULING NAMES THIS ENGINE FOR WHY THE `@`-PREFIX ESCAPE IS NOT AVAILABLE: §2.2's convention is
+// airtight for a sidecar because a `@`-key cannot collide with a TYPE name — but an npm scoped package is
+// spelled `@scope/name`, so `@incomplete` is a key a real ts module could own. "A convention that is
+// airtight in one namespace and merely unlikely in another is not a convention; it is a deferred
+// collision."
+//
+// THE TYPE CHANGE IS THE POINT. A consumer doing `for (const x of doc)` over `show` gets a TypeError
+// rather than a silent zero-iteration loop — the one case where breaking a consumer is the CORRECT
+// outcome, because the consumer was being lied to. The exit does not move (⟨0.24⟩: a disclosure, not an
+// exit code), and HEALTHY OUTPUT IS BYTE-IDENTICAL: the shape changes only on the hedge path.
+//
+// The PROSE arm is `putAnswer`'s, verbatim — prose has no shape problem, and the clause is about the
+// machine document. Sharing the note + renderer call keeps the two channels from drifting.
+//
+// THE HEALTHY JSON ARM MUST NOT GO THROUGH `withCompleteness`, and the first draft of this helper did:
+// it delegated to `putAnswer`, whose `{ ...data, ...{} }` turned `show`'s ARRAY into `{"0": {…}}` — the
+// pinned top-level array destroyed on the very path this rung promises to leave byte-identical. Caught by
+// the intact-input control before it left the machine. So the healthy arm emits `data` itself.
+const putCaveatInstead = (a, data, proseFn, comp, soWhat, tail) => {
+  if (!proseFn || wantJsonOut(a)) { emit(mustHedge(comp) ? completenessFields(comp) : data); return data; }
+  incompleteAnswerNote(comp, soWhat, tail);
+  proseFn(data, mustHedge(comp));
+  return data;
+};
+// The one sentence every hedged prose arm ends with, so the six cannot drift into six wordings.
+const NOT_A = (claim) => `— but see the INCOMPLETE note above; this is NOT "${claim}"`;
 const csv = (xs) => (xs && xs.length ? xs.join(", ") : "none");
 const rows = (xs, pre = "    ") => { for (const x of xs) console.log(pre + x); };
 // Per-verb prose renderers. Read the SAME shapes query-core returns (so JSON and prose can't drift); kept
 // terse and scannable, in candor's voice (cf. the existing `tour`/`path` human forms).
 const P = {
-  where: (d) => {
+  // ⟨0.28⟩ `hedge` is `mustHedge(comp)` (see `putAnswer`): the report could not support a determined
+  // negative, so the reassuring sentence — which IS the prose spelling of the empty JSON — is withdrawn.
+  // Never a manufactured finding in its place: the answer stands, its STANDING is what changes.
+  where: (d, hedge) => {
     const n = d.directly.length + d.inherited.length;
-    if (n === 0) { console.log(`candor: 0 functions perform ${d.effect} in this report.`); return; }
+    if (n === 0) {
+      console.log(hedge
+        ? `candor: 0 functions candor COULD SEE perform ${d.effect} ${NOT_A(`nothing performs ${d.effect}`)}.`
+        : `candor: 0 functions perform ${d.effect} in this report.`);
+      return;
+    }
     console.log(`candor where ${d.effect} — ${n} function${n === 1 ? "" : "s"}:`);
     if (d.directly.length) { console.log(`  perform it directly (${d.directly.length}):`); rows(d.directly); }
     if (d.inherited.length) { console.log(`  reach it transitively (${d.inherited.length}):`); rows(d.inherited); }
   },
   callers: (d) => {
+    // ⟨0.28⟩ UNREACHABLE FROM THE CLI since the callers verb split the empty-`of` case into its two real
+    // causes below (no graph at all -> `unanswerable`, exit 2; a name absent from a real graph -> "no
+    // function matching", exit 2). Kept as a renderer guard only; do NOT route a new caller through it —
+    // this sentence is a determined negative and is the wrong answer when there is no call graph.
     if (!d.of.length) { console.log("candor: no function in the call graph matches that name."); return; }
     console.log(`candor callers — who reaches \`${d.of.join("`, `")}\`:`);
     console.log(`  direct callers (${d.direct.length}): ${csv(d.direct)}`);
     console.log(`  transitive callers (${d.transitive.length}): ${csv(d.transitive)}`);
   },
-  show: (d) => {
-    if (!d.length) { console.log("candor: no effectful function matches that name (pure functions are omitted from the report)."); return; }
+  show: (d, hedge) => {
+    // ⟨0.28⟩ the empty sentence stops citing the ⟨0.21⟩ purity convention when the report cannot back it:
+    // over these bytes an absent function is not evidence of purity, it is evidence of nothing.
+    if (!d.length) {
+      console.log(hedge
+        ? `candor: no effectful function candor COULD SEE matches that name ${NOT_A("this function is pure")} — absence from this report licenses no purity claim here.`
+        : "candor: no effectful function matches that name (pure functions are omitted from the report).");
+      return;
+    }
     d.forEach((e, i) => {
       if (i) console.log("");
       console.log(`${e.fn}`);
@@ -125,30 +341,54 @@ const P = {
       if (e.tables?.length) console.log(`  tables:  ${e.tables.join(", ")}`);
     });
   },
-  map: (d) => {
+  map: (d, hedge) => {
     const mods = Object.entries(d);
-    if (!mods.length) { console.log("candor: no effectful modules in this report."); return; }
+    if (!mods.length) {
+      console.log(hedge
+        ? `candor: no effectful module candor COULD SEE ${NOT_A("the code performs no effects")}.`
+        : "candor: no effectful modules in this report.");
+      return;
+    }
     console.log("candor map — effects by module:");
     for (const [m, v] of mods) console.log(`  ${m} — ${csv(v.effects)}  (${v.functions} fn${v.functions === 1 ? "" : "s"})`);
   },
-  containment: (d) => {
+  containment: (d, hedge) => {
     if ("leaks" in d) { // ratchet (a baseline was given)
-      if (!d.leaks.length) console.log("candor containment — no boundary effect reached a new layer vs the baseline. ✓");
+      // The ✓ is withdrawn from BOTH directions here, not just the empty one: this answer is a DIFFERENCE,
+      // so a partial side is unsound two ways — a leak in an unread CURRENT file is missed, one in an unread
+      // BASELINE file reads as newly appeared (a fabricated leak, at exit 1).
+      if (!d.leaks.length)
+        console.log(hedge
+          ? `candor containment — no boundary effect candor COULD SEE reached a new layer vs the baseline ${NOT_A("nothing leaked")}.`
+          : "candor containment — no boundary effect reached a new layer vs the baseline. ✓");
       else { console.log(`candor containment — ${d.leaks.length} boundary effect(s) reached a NEW layer (leak):`); rows(d.leaks); }
       if (d.cleanups && d.cleanups.length) { console.log(`  no longer present (${d.cleanups.length}):`); rows(d.cleanups); }
       return;
     }
-    if (!d.contained.length && !Object.keys(d.ambient).length) { console.log("candor containment — no boundary effects in this report."); return; }
+    if (!d.contained.length && !Object.keys(d.ambient).length) {
+      console.log(hedge
+        ? `candor containment — no boundary effect candor COULD SEE ${NOT_A("there are no boundary effects")}.`
+        : "candor containment — no boundary effects in this report.");
+      return;
+    }
     console.log("candor containment — how well each boundary effect stays in one layer:");
     for (const c of d.contained)
       console.log(`  ${c.effect}: ${c.containmentPct}% in \`${c.owner}\` (spread across ${c.layers} layer${c.layers === 1 ? "" : "s"})`);
     const amb = Object.entries(d.ambient);
     if (amb.length) console.log(`  ambient (reported, not scored): ${amb.map(([e, n]) => `${e}×${n}`).join(", ")}`);
   },
-  reachable: (d) => {
+  reachable: (d, hedge) => {
     const effs = Object.entries(d.effects);
     console.log(`candor reachable — what the ${d.entryPoints} entry point${d.entryPoints === 1 ? "" : "s"} do at runtime:`);
-    if (!effs.length) { console.log("  no effect reaches an entry point."); return; }
+    // "the program performs no effect at runtime" is the strongest claim this tool can make, and it stays a
+    // DETERMINED negative on good data (a library has no entry points) — which is exactly why the caveat
+    // must be said, rather than left for a reader to infer from the emptiness.
+    if (!effs.length) {
+      console.log(hedge
+        ? `  no effect reaches an entry point candor COULD SEE ${NOT_A("the program performs no effect at runtime")}.`
+        : "  no effect reaches an entry point.");
+      return;
+    }
     for (const [e, v] of effs) console.log(`  ${e}: ${v.count} (via ${csv(v.via)})`);
   },
   impact: (d) => {
@@ -157,19 +397,38 @@ const P = {
     if (d.affected.length) rows(d.affected);
     if (d.entryPoints.length) { console.log(`  reachable from ${d.entryPoints.length} entry point(s):`); rows(d.entryPoints.map((ep) => `${ep.fn}  [${csv(ep.inferred)}]`)); }
   },
-  blindspots: (d) => {
-    if (!d.sources.length) { console.log(`candor blindspots — no Unknown sources${d.totalUnknown ? " (all Unknown here is inherited, not rooted in a call)" : ""}. ✓`); return; }
+  blindspots: (d, hedge) => {
+    if (!d.sources.length) {
+      console.log(hedge
+        ? `candor blindspots — no Unknown source candor COULD SEE ${NOT_A("there are no blind spots")}.`
+        : `candor blindspots — no Unknown sources${d.totalUnknown ? " (all Unknown here is inherited, not rooted in a call)" : ""}. ✓`);
+      return;
+    }
     console.log(`candor blindspots — ${d.sources.length} Unknown source${d.sources.length === 1 ? "" : "s"} (of ${d.totalUnknown} function(s) carrying Unknown), most-smearing first:`);
     for (const s of d.sources) console.log(`  \`${s.fn}\` — ${csv(s.why)}; reaches ${s.reaches} caller(s)`);
   },
-  blindspotsStats: (d) => {
-    if (!d.sources) { console.log("candor blindspots --stats — no Unknown sources (nothing to classify). ✓"); return; }
+  blindspotsStats: (d, hedge) => {
+    if (!d.sources) {
+      console.log(hedge
+        ? `candor blindspots --stats — no Unknown source candor COULD SEE (nothing to classify) ${NOT_A("there are no blind spots")}.`
+        : "candor blindspots --stats — no Unknown sources (nothing to classify). ✓");
+      return;
+    }
     console.log(`candor blindspots --stats — ${d.sources} Unknown source(s) by reason class (of ${d.totalUnknown} function(s) carrying Unknown) — size the blind-spot cost before \`deny E Unknown[…]\`:`);
     Object.entries(d.byClass).filter(([, v]) => v > 0).sort((a, b) => b[1] - a[1])
       .forEach(([k, v]) => console.log(`  ${k.padEnd(12)} ${String(v).padStart(4)}${k === "setup" ? "   ← fixable: the scan isn't configured, not a real blind spot" : ""}`));
   },
-  gains: (d) => {
-    if (!d.gained.length) { console.log("candor gains — no newly-reached effects vs the baseline. ✓"); return; }
+  // ⟨0.28⟩ `hedge` is true when EITHER side's report is incomplete (see the gains case). "No newly-reached
+  // effects ✓" IS the prose spelling of `gained: []`, and it is the determined negative this alarm verb
+  // exists to license — so it is withdrawn, not decorated. A non-empty list is left standing: it may be
+  // short, which the stderr note above says, but every entry in it was measured.
+  gains: (d, hedge) => {
+    if (!d.gained.length) {
+      console.log(hedge
+        ? `candor gains — no newly-reached effects candor COULD SEE vs the baseline ${NOT_A("this bump gained nothing")}.`
+        : "candor gains — no newly-reached effects vs the baseline. ✓");
+      return;
+    }
     console.log(`candor gains — the surface newly reaches: ${d.gained.join(", ")}`);
     for (const g of d.byFunction) console.log(`  \`${g.fn}\` gained ${g.effect}${g.origin ? `  (${g.origin})` : ""}`);
   },
@@ -180,6 +439,18 @@ const P = {
   },
 };
 
+// The fn-name UNIVERSE a `<fn>` target resolves against: the callgraph keys UNIONed with the report's fn
+// names. Not a new set — this is byte-for-byte the one mcp.mjs's fn-existence guard already builds, so
+// the CLI and the MCP surface refuse exactly the same names (a name the agent tool calls nonexistent must
+// not be one the CLI silently answers `0` for). Used by the `impact`/`path` bad-target gates below.
+//
+// THE UNION IS THE SAFE DIRECTION. §2.2 makes every fn a callgraph key and the report is the effectful
+// SUBSET, so today the union IS the keys; the union is what keeps that an observation rather than an
+// assumption. Refusing only a name that resolves in NEITHER set means no answer these verbs can actually
+// compute is ever withdrawn — gating on one set alone would be the ⟨0.24⟩ count-0 mirror defect the day
+// the two disagreed.
+const knownFnNames = (cg, fns) => [...new Set([...Object.keys(cg), ...fns.map((e) => e.fn)])];
+
 // Render `path` in HUMAN (non-`--json`) form — the indented provenance chain, BYTE-IDENTICAL to the
 // Rust reference (candor-query/src/callers.rs) and the Java port (Query.java). The `--json` shape is
 // UNTOUCHED (conformance PART 5 pins `{effect, fn, path:[{fn,loc,source}]}` four-way): this path is
@@ -232,7 +503,7 @@ function renderPathHuman(fns, cg, fnQ, eff) {
 // package.json; SPEC_VERSION is the spec contract this build speaks. Reused, never re-littered.
 const QUERY_DIR = path.dirname(fileURLToPath(import.meta.url));
 const PKG_VERSION = JSON.parse(fs.readFileSync(path.join(QUERY_DIR, "package.json"), "utf8")).version;
-const SPEC_VERSION = "0.26";
+const SPEC_VERSION = "0.28";
 
 // ---- the §3.3.1 canonical query grammar (⟨0.10⟩, additive over 0.9) --------------------------------
 // One shape for every verb: `<verb> <verb-args…> [--report <locator>] [--policy <file>] [--json]
@@ -313,15 +584,26 @@ function parseCanonical(rawArgs, { policy = false, strict = false, includeUnknow
   const positionals = [];
   let reportLocator = null, policyFile = null, wantStrict = false, wantIncludeUnknown = false;
   let sawClass = false;   // ⟨0.24⟩ `--class` takes ONE list and is NOT repeatable (SPEC §6.2)
+  // SPEC §3.2 ⟨0.28⟩ (every value-taking flag below): "given no value" MEANS the next token is
+  // flag-shaped, or the clause is unimplementable — consuming the token as the value made this very
+  // diagnostic unreachable and silently reinterpreted a flag. Measured on this file: `where Fs
+  // --report --json` diagnosed the wrong cause ("no report files at prefix '--json'"), and on a
+  // NON-policy verb `--policy --json` consumed-and-DISCARDED the next flag at exit 0 — a silently
+  // different command than the one on screen, the §6.2 unknown-flag reinterpretation one position
+  // over. A bare `-` stays a value and fails loud downstream (an unreadable file / unknown class);
+  // `./--weird` spells a file genuinely named like a flag.
+  const flagShaped = (v) => v !== undefined && v !== "-" && v.startsWith("-") && v.length > 1;
   for (let i = 0; i < rawArgs.length; i++) {
     const a = rawArgs[i];
     if (a === "--report") {
       // A `--report` with no following value is a LOUD usage error (exit 2), never a silent fall-back to
       // discovery and never an uncaught `locatorToPrefix(undefined)` TypeError (`where Fs --report`).
+      if (flagShaped(rawArgs[i + 1])) { console.error(`candor-ts: --report was given no value — the next token '${rawArgs[i + 1]}' is a flag, not a locator (a path really named that is spelled ./${rawArgs[i + 1]})`); process.exit(2); }
       if (i + 1 >= rawArgs.length) { console.error("candor-ts: --report requires a <locator> value (a directory, a .json report path, or a prefix)"); process.exit(2); }
       reportLocator = rawArgs[++i]; continue;
     }
     if (a === "--policy") { // consumed for EVERY verb (a valid candor flag); used only by policy verbs
+      if (flagShaped(rawArgs[i + 1])) { console.error(`candor-ts: --policy was given no value — the next token '${rawArgs[i + 1]}' is a flag, not a path (a file really named that is spelled ./${rawArgs[i + 1]})`); process.exit(2); }
       if (i + 1 >= rawArgs.length) { console.error("candor-ts: --policy requires a <file> value"); process.exit(2); }
       const v = rawArgs[++i]; if (policy) policyFile = v; continue;
     }
@@ -331,6 +613,7 @@ function parseCanonical(rawArgs, { policy = false, strict = false, includeUnknow
     if (a === "--include-unknown") { if (includeUnknown) wantIncludeUnknown = true; continue; } // used only by the verb that reads it
     if (a === "--stats") { continue; }   // ⟨0.20⟩ tolerated everywhere; read by the `blindspots` case via args.includes
     if (a === "--class") { // ⟨0.20⟩ value flag; the value is read by the `blindspots` and `unverified` cases
+      if (flagShaped(rawArgs[i + 1])) { console.error(`candor-ts: --class was given no value — the next token '${rawArgs[i + 1]}' is a flag, not a <class,…> list`); process.exit(2); }
       if (i + 1 >= rawArgs.length) { console.error("candor-ts: --class requires a <class,…> value (reflect,dispatch,indirect,native,unresolved,setup; aliases: dynamic,*)"); process.exit(2); }
       // ⟨0.24⟩ SPEC §6.2's VALUE GRAMMAR, validated HERE — the one place every verb's args pass through, so
       // no verb can accept a value the filter will not honour. Two rules, one reason (see parseClassFilter):
@@ -437,16 +720,222 @@ function resolveGateVerb(rawArgs, { strict = false } = {}) {
 // deprecated-alias machinery, because it has NO POSITIONALS: a stray argument is a usage error, never
 // probed as a report or a policy. Kept out of parseCanonical for that reason — the peel helpers exist to
 // accept the old grammar, and there is no old grammar for a verb introduced at ⟨0.24⟩.
+// ── SPEC §3.3.1 ⟨0.27⟩ sink-arming helpers, shared by the gate verb. The scan entry point has its own
+// copies (scan.mjs) because it must not import from this file; the RULES are the spec's, not shared code.
+
+/** Learn `--gate-json` and `--policy` from a verb's argv with NO side effects. */
+function preScanGateArgs(av) {
+  let gate = null, policy = null, report = null;
+  for (let i = 0; i < av.length; i++) {
+    const a = av[i], v = av[i + 1];
+    if (a !== "--gate-json" && a !== "--policy" && a !== "--report") continue;
+    if (v === undefined || (v.startsWith("-") && v !== "-")) continue;
+    if (a === "--gate-json") gate = v; else if (a === "--policy") policy = v; else report = v;
+    i++;
+  }
+  return { gate, policy, report };
+}
+
+/** Artifact identity, not string identity — `--policy /w/P --gate-json ./P` from /w is one file. */
+function sameArtifactPath(a, b) {
+  if (!a || !b || a === "-" || b === "-") return false;
+  const resolve = (p) => {
+    try { return fs.realpathSync(p); } catch { /* not there yet — resolve the parent */ }
+    try { return path.join(fs.realpathSync(path.dirname(path.resolve(p))), path.basename(p)); }
+    catch { return null; }
+  };
+  const x = resolve(a);
+  return x !== null && x === resolve(b);
+}
+
+/** The files the CWD-discovered \`.candor/config\` names, resolved as the loader resolves them. */
+function configDeclaredInputs() {
+  const out = [];
+  try {
+    const disc = discoverConfigPolicy(process.cwd());
+    if (disc?.policyPath) out.push([disc.policyPath, "the config policy key"]);
+    const cfgPath = discoverConfigPath(process.cwd());
+    if (cfgPath) out.push([cfgPath, 'the discovered .candor/config']);
+  } catch { /* lenient: the real load refuses on its own terms */ }
+  return out;
+}
+
+/** Refuse a sink that names an input of this run, having written nothing. */
+function refuseGateJsonOverInput(gate, other, flag) {
+  if (!sameArtifactPath(gate, other)) return;
+  console.error(`candor-ts-query: --gate-json ${gate} names the SAME FILE as ${flag} ${other} — refusing `
+    + `(exit 2). The verdict is armed before the policy is read, so this would overwrite your policy and `
+    + `then gate on the wreckage. Nothing was written; give the verdict its own path.`);
+  process.exit(2);
+}
+
+/** `.candor/config` is never a verdict sink, wherever it is. */
+function refuseGateJsonAtConfig(gate) {
+  if (!gate || gate === "-") return;
+  const abs = path.resolve(gate);
+  if (path.basename(abs) !== "config" || path.basename(path.dirname(abs)) !== ".candor") return;
+  console.error(`candor-ts-query: --gate-json ${gate} is a .candor/config — refusing (exit 2). This would `
+    + `destroy the config that configures this run. Nothing was written; give the verdict its own path.`);
+  process.exit(2);
+}
+
+/** Write the fail-closed refusal every later exit inherits unless a real verdict replaces it. */
+// ⟨0.28⟩ RESOLVE THE SINK TO ITS FINAL ARTIFACT BEFORE WRITING, and preserve the operator's layout.
+// `renameSync` REPLACES a symlink rather than following it, so an `artifacts/verdict.json` linked into a
+// shared directory kept a previous run's `{"ok": true}` while this run's document landed on the link — a
+// stale green with a single `--gate-json` and no operator mistake. And rename gives the destination a NEW
+// inode, so a multiply-linked target strands its other name with the previous document; there the write
+// goes in place, trading the atomicity window for not publishing a stale verdict at a name the operator
+// wired up. SPEC §3.3.1 states identity about ARTIFACTS; this family had it in the comparison only.
+function resolveSinkArtifact(p) {
+  let cur = p;
+  for (let i = 0; i < 32; i++) {
+    let st;
+    try { st = fs.lstatSync(cur); } catch { return cur; }
+    if (!st.isSymbolicLink()) return cur;
+    let t;
+    try { t = fs.readlinkSync(cur); } catch { return cur; }
+    cur = path.isAbsolute(t) ? t : path.join(path.dirname(cur), t);
+  }
+  return cur;
+}
+
+function writeSinkAtomic(p, text) {
+  const target = resolveSinkArtifact(p);
+  try {
+    if (fs.statSync(target).nlink > 1) { fs.writeFileSync(target, text); return; }
+  } catch { /* not there yet — the ordinary temp+rename path is right */ }
+  const tmp = `${target}.${process.pid}.tmp`;
+  fs.writeFileSync(tmp, text);
+  fs.renameSync(tmp, target);
+}
+
+function armQueryGateJson(p) {
+  try {
+    writeSinkAtomic(p, JSON.stringify(
+      refusalVerdict(SPEC_VERSION, "the gate did not complete — this document was written when the run "
+        + "STARTED and was never replaced by a verdict, so the run failed, crashed or was killed before "
+        + "it could decide. It is NOT a verdict about the code; see the run's stderr for the cause."),
+      null, 1) + "\n");
+  } catch (e) {
+    console.error(`candor-ts-query: could not arm --gate-json ${p} fail-closed (${e.message})`);
+  }
+}
+
 function resolveGateReportVerb(rawArgs) {
   const usageLine = "usage: candor-ts-query gate --report <locator> --policy <file> [--json] [--gate-json <file>]";
   let reportLocator = null, policyFile = null, gateJsonPath = null, json = false;
+  // SPEC §3.3.1 ⟨0.27⟩ — ARM FIRST, AND NEVER OVER AN INPUT. A pre-pass with no side effects, so both
+  // the collision refusal and the arming precede every exit in the loop below. See the note where the
+  // arming used to live for why the previous ordering was wrong.
+  {
+    const { gate, policy, report } = preScanGateArgs(rawArgs);
+    if (gate) {
+      // THE STREAM HOOK IS INSTALLED FIRST, before anything that can exit. It WRITES NOTHING until the
+      // process exits, so unlike the file arming below it cannot land on an input and has no reason to
+      // wait behind the collision checks.
+      //
+      // It used to be installed after them, and `configDeclaredInputs()` — one of those checks — reads
+      // the config, which exits 2 through a shared helper when the config is unreadable. So the earliest
+      // exit-2 cause there is left stdout EMPTY on this route while java and swift wrote the refusal.
+      // Found by the gate-verb cells in candor/bin/probe-causes.sh; candor-scan had the same gap through
+      // the same shared loader, one language across.
+      if (gate === "-") {
+        process.on("exit", (code) => {
+          if (code === 2 && !globalThis.__candorGateVerdictWritten) {
+            console.log(JSON.stringify(refusalVerdict(SPEC_VERSION,
+              "the gate did not complete — this run exited before a verdict could be produced", null), null, 1));
+          }
+        });
+      }
+      refuseGateJsonOverInput(gate, policy, "--policy");
+      // §3.3.1 names "a report being read (`gate --report`)" as an input. Writing the verdict there
+      // destroys the very report the gate was asked to judge, and the diagnostic then blames the report
+      // rather than the collision.
+      refuseGateJsonOverInput(gate, report, "--report");
+      // ⟨0.28⟩ …AND THE FILES THE LOCATOR EXPANDS TO, because the raw flag value above is not what the
+      // gate READS: a locator is a prefix/dir (or a discovery, when absent), and `loadGateReport` reads
+      // its expansion — so a sink naming one of the expanded reports, or one of their §2.2 sidecars,
+      // named an input the token comparison could not see. Enumerated by the loader-adjacent
+      // `gateReportInputFiles` (query-core.mjs); the measurement lives there.
+      const expandedInputs = gateReportInputFiles(report ? locatorToPrefix(report) : discoverReportPrefix());
+      for (const f of expandedInputs) refuseGateJsonOverInput(gate, f, "a file this gate reads —");
+      refuseGateJsonOverInput(gate, process.env.CANDOR_POLICY, "CANDOR_POLICY");
+      // THE CONFIG-DECLARED POLICY. This verb's policy ladder falls back to the \`policy\` key of the
+      // config discovered from the CWD, and the guard checked only the flags — so the checked-in form,
+      // which is the one a CI job has, was destroyed at exit 0 while the flag form refused. The same
+      // hole the scan route closed, one route across.
+      for (const [p2, label] of configDeclaredInputs()) refuseGateJsonOverInput(gate, p2, label);
+      refuseGateJsonAtConfig(gate);
+      // ⟨0.28⟩ THE RUNG BINDS EVERY ROUTE. It shipped on scan.mjs only, so this verb kept last-wins and a
+      // gate that FIRED left the first named sink holding a previous run's `{"ok": true}`. Every named
+      // sink also gets the input checks, and the input exemption covers that PATH, not the run — so the
+      // other sinks still receive the refusal.
+      const namedSinks = [];
+      for (let k = 0; k < rawArgs.length; k++) {
+        if (rawArgs[k] !== "--gate-json") continue;
+        const v = rawArgs[k + 1];
+        if (v === undefined || (v !== "-" && v.startsWith("-"))) continue;
+        if (!namedSinks.some((x) => x === v || (x !== "-" && v !== "-" && sameArtifactPath(x, v)))) namedSinks.push(v);
+        k++;
+      }
+      for (const g of namedSinks) {
+        refuseGateJsonOverInput(g, policy, "--policy");
+        refuseGateJsonOverInput(g, report, "--report");
+        // ⟨0.28⟩ the expanded report set (and its sidecars), exactly as the single-sink path asks it
+        // above — a duplicate must not smuggle an expanded input past the guard.
+        for (const f of expandedInputs) refuseGateJsonOverInput(g, f, "a file this gate reads —");
+        refuseGateJsonOverInput(g, process.env.CANDOR_POLICY, "CANDOR_POLICY");
+        refuseGateJsonOverInput(g, process.env.CANDOR_CONFIG, "CANDOR_CONFIG");
+        for (const [p2, label] of configDeclaredInputs()) refuseGateJsonOverInput(g, p2, label);
+        refuseGateJsonAtConfig(g);
+      }
+      if (namedSinks.length > 1) {
+        const list = namedSinks.join(", ");
+        console.error(`candor-ts-query: --gate-json given more than once (${list}) — refusing (exit 2). A `
+          + `gate publishes ONE verdict. Naming two sinks says where it goes twice, and the reader of the `
+          + `path that loses cannot tell it lost. Name one, or run the gate twice.`);
+        const doc = JSON.stringify(refusalVerdict(SPEC_VERSION,
+          `--gate-json was given more than once (${list}) — a run publishes one verdict to one sink`, null), null, 1);
+        for (const g of namedSinks) {
+          if (g === "-") { globalThis.__candorGateVerdictWritten = true; console.log(doc); continue; }
+          try { writeSinkAtomic(g, doc + "\n"); }
+          catch (e) { console.error(`candor-ts-query: could not write the refusal to --gate-json ${g} (${e.message})`); }
+        }
+        process.exit(2);
+      }
+      if (gate !== "-") armQueryGateJson(gate);
+      // …AND THE STREAM'S ANALOG OF ARMING — now installed at the top of this block, see the note there. `armQueryGateJson` writes a fail-closed placeholder to a
+      // FILE; a stream cannot hold one, so the equivalent is a hook that emits the refusal on any
+      // exit-2 path that has not already written a verdict.
+      //
+      // Without it, this verb exited 2 during ARGUMENT PARSING with stdout EMPTY, while the same verb
+      // refusing later from inside the gate streamed the document — the same operator mistake, two
+      // answers, decided by how early it was caught. A machine consumer reading an empty stream after
+      // exit 2 cannot tell it from a clean gate.
+      //
+      // Measured at the 0.27 go/no-go: java, swift and ts all had this hole on the `gate` verb, and
+      // PART 36's stream rows never reached it because every one of them runs the SCAN route. The row
+      // that catches it is now there.
+    }
+  }
+  // SPEC §3.2 ⟨0.28⟩: "given no value" MEANS the next token is flag-shaped — consuming it as a filename
+  // made this diagnostic unreachable and reinterpreted the command line: `--policy --gate-json -` read
+  // *policy = the file named `--gate-json`* and diagnosed the displaced `-` as an "unexpected argument".
+  // The sink the operator named is STILL a sink: the pre-pass above leaves a flag-shaped token live, so
+  // `--gate-json -` after the broken flag installed the stream hook (and a file sink was armed
+  // fail-closed) BEFORE this refusal fires — the exits below inherit that, like every other exit-2 in
+  // this loop. A bare `-` stays a value; `./--weird` spells a file genuinely named like a flag.
+  const flagShapedValue = (v) => v !== undefined && v !== "-" && v.startsWith("-") && v.length > 1;
   for (let i = 0; i < rawArgs.length; i++) {
     const a = rawArgs[i];
     if (a === "--report") {
+      if (flagShapedValue(rawArgs[i + 1])) { console.error(`candor-ts: --report was given no value — the next token '${rawArgs[i + 1]}' is a flag, not a locator (a path really named that is spelled ./${rawArgs[i + 1]})\n  ${usageLine}`); process.exit(2); }
       if (i + 1 >= rawArgs.length) { console.error(`candor-ts: --report requires a <locator> value (a directory, a .json report path, or a prefix)\n  ${usageLine}`); process.exit(2); }
       reportLocator = rawArgs[++i]; continue;
     }
     if (a === "--policy") {
+      if (flagShapedValue(rawArgs[i + 1])) { console.error(`candor-ts: --policy was given no value — the next token '${rawArgs[i + 1]}' is a flag, not a path (a file really named that is spelled ./${rawArgs[i + 1]})\n  ${usageLine}`); process.exit(2); }
       if (i + 1 >= rawArgs.length) { console.error(`candor-ts: --policy requires a <file> value\n  ${usageLine}`); process.exit(2); }
       policyFile = rawArgs[++i]; continue;
     }
@@ -469,8 +958,18 @@ function resolveGateReportVerb(rawArgs) {
     console.error(`candor-ts-query gate: unexpected argument '${a}' — \`gate\` takes no positionals; the report is a --report locator and the policy a --policy file\n  ${usageLine}`);
     process.exit(2);
   }
+  // ARMING MOVED ABOVE THE FLAG LOOP (SPEC §3.3.1 ⟨0.27⟩).
+  //
+  // It used to sit here, and the comment justified it with a ⟨0.24⟩ ruling of my own: "a USAGE error was
+  // never a gate invocation, so it must write NOTHING". SPEC §3.3 says the opposite in terms — it names
+  // an unknown flag as a broken-gate-config exit-2 cause, and §3.1 adds that "if `--gate-json` was
+  // requested and the run exits 2 for ANY reason, a fail-closed document is written", calling a
+  // carve-out "a fail-open path with a reason attached". The ruling I built here was that carve-out, and
+  // the test pinning it pinned a reading the spec had already superseded. The stale green does not care
+  // that the operator's shell also failed.
+  const _policy = resolvePolicy(policyFile, null).policyFile;
   const prefix = requireReport(reportLocator !== null ? locatorToPrefix(reportLocator) : discoverReportPrefix());
-  return { prefix, policyFile: resolvePolicy(policyFile, null).policyFile, gateJsonPath, json };
+  return { prefix, policyFile: _policy, gateJsonPath, json };
 }
 
 /**
@@ -678,7 +1177,13 @@ switch (cmd) {
     // A missing/empty <query> is a LOUD usage error (exit 2, like candor-java) — never a silently-empty
     // `[]` at exit 0, which reads as an authoritative "no such function" over a question never asked.
     if (!q) { console.error("usage: candor-ts-query show <query> [--report <locator>] [--json]"); process.exit(2); }
-    put(args, coreShow(loadReportOrDie(prefix), q), P.show);
+    // ⟨0.28⟩ RUNG A — `show`'s pinned shape is a TOP-LEVEL ARRAY, so over a hedging report it emits the
+    // CAVEAT DOCUMENT INSTEAD (see `putCaveatInstead`). Before this it took plain `put` and had no
+    // completeness reader at all: measured, `[]` at exit 0 over a report whose own manifest names a file
+    // candor could not read — the only verb of the six with no caveat on EITHER channel.
+    putCaveatInstead(args, coreShow(loadReportOrDie(prefix), q), P.show, reportCompleteness(prefix),
+      `the function(s) shown below are only those candor could SEE match \`${q}\``,
+      "A function in an unread unit is ABSENT from the report, so it cannot be shown here at all. Re-scan for a complete answer.");
     break;
   }
   case "where": {
@@ -697,7 +1202,11 @@ switch (cmd) {
     if (!KNOWN_EFFECTS.includes(eff) && !new Set(fnsW.flatMap((e) => e.inferred || [])).has(eff)) {
       console.error(`candor-ts-query where: unknown effect '${eff}' (known: ${KNOWN_EFFECTS.join(", ")})`); process.exit(2);
     }
-    put(args, coreWhere(fnsW, eff), P.where);
+    // ⟨0.28⟩ SPEC §2 — `{"directly":[],"inherited":[]}` is one of the four empty answers the clause names
+    // by measurement. The caveat rides the SAME document (see `putAnswer`); the exit code does not move.
+    putAnswer(args, coreWhere(fnsW, eff), P.where, reportCompleteness(prefix),
+      `the function(s) named below are only those candor could SEE perform ${eff}`,
+      `A function in an unread unit is ABSENT from the report, so it cannot appear in either list. Re-scan for a complete answer.`);
     break;
   }
   case "callers": {
@@ -708,12 +1217,64 @@ switch (cmd) {
     // A missing/empty <query> is a LOUD usage error (exit 2, like candor-java) — never an empty
     // {of:[],direct:[],transitive:[]} at exit 0 (reads as "nothing reaches it" for a fn never named).
     if (!q) { console.error("usage: candor-ts-query callers <query> [--include-unknown] [--report <locator>] [--json]"); process.exit(2); }
+    // ⟨0.28⟩ PREFER THE §2.2 SIDECAR, FALL BACK TO THE REPORT'S OWN `calls` EDGES — rust's exact split
+    // (callers.rs). The sidecar records EVERY function including pure ones, so it is the COMPLETE graph;
+    // the report's embedded edges are effect-relevant only, but a report is a §3.3.1 locator in its own
+    // right (a single hand-copied report.json) and rust/java answer real callers over it at exit 0 while
+    // this engine refused `unanswerable` exit 2 — a one-engine divergence that broke a cross-engine
+    // script. The fail-closed arm below now fires only when the graph is GENUINELY absent (no sidecar
+    // AND no embedded edges — the armed pair), which narrows when it fires without removing it.
     const cg = loadCallgraph(prefix);
-    const cres = includeUnknown ? callersFrontier(cg, loadReportOrDie(prefix), loadHierarchy(prefix), q) : coreCallers(cg, q);
+    const completeGraph = Object.keys(cg).length > 0;
+    const graph = completeGraph ? cg : reportCallsGraph(loadReportOrDie(prefix));
+    const cres = includeUnknown ? callersFrontier(graph, loadReportOrDie(prefix), loadHierarchy(prefix), q) : coreCallers(graph, q);
     // A nonexistent function is a LOUD error (exit 2), like path/impact — never an empty {of:[],direct:[],
     // transitive:[]} at exit 0, which reads as an authoritative "nothing calls it" for a fn that doesn't exist
     // (corpus-audit #3). Gated on a NON-empty callgraph so a missing sidecar isn't misreported as "no such fn".
-    if (Object.keys(cg).length > 0 && cres.of.length === 0) {
+    if (cres.of.length === 0) {
+      // ⟨0.28⟩ UNANSWERABLE MUST REACH THE MACHINE CHANNEL (SPEC §3.3.1). This branch printed
+      // `{"of":[],"direct":[],"transitive":[]}` at exit 0 while the human arm said "no function in the
+      // call graph matches that name" — and BOTH readings are a determined negative, which is worse than
+      // the reference engines' split: rust/java's human arm at least said "no call graph in the report".
+      // A consumer reading `direct`, or defaulting it (the fail-open idiom ⟨0.24⟩ names on every key in
+      // this format), is told NOBODY CALLS this function: a blast radius of "safe to edit" over a pair
+      // whose honest answer is "this run judged nothing". The ⟨0.28⟩ sidecar rule (scan.mjs, which
+      // deletes the §2.2 sidecars with an armed report) did not dig this hole — an absent sidecar has
+      // always answered this way — it aimed traffic at it by making no-sidecar the STANDARD state after
+      // a failed run.
+      //
+      // BOTH CHANNELS FAIL CLOSED: the document names itself unanswerable AND the exit is non-zero.
+      // §3.3.1 permits either, but each ALONE leaves a naive reader exposed — the key alone still lets
+      // `d.direct ?? []` read as a determined negative, and the exit alone leaves a JSON consumer
+      // holding an empty document. Same shape as rust `358e117` / java `927252c`.
+      //
+      // ONLY THIS ARM, and the control separation is the load-bearing half. An EMPTY graph means there
+      // is no call graph AT ALL (no §2.2 sidecar, and ⟨0.24⟩ rules an empty/unparseable one identical to
+      // an absent one), which is the unanswerable case. A function with genuinely no callers over a REAL
+      // graph still answers `direct: []` at exit 0 below — a determined negative, and withdrawing it
+      // would be the mirror defect (the ⟨0.24⟩ count-0 lesson) — and a name absent from a real graph
+      // still exits 2 as "no function matching", because a graph WAS read there.
+      //
+      // ONE SITE, MEASURED NOT ASSUMED: the rust reference had this branch twice (callers_via_callgraph
+      // + the frontier variant) and warned to grep for both; candor-ts folds `--include-unknown` through
+      // this same block via `callersFrontier`, so `grep -n 'coreCallers\|callersFrontier' query.mjs`
+      // finds exactly one CALL site (plus the import). Verified through the flag as well: `--json
+      // --include-unknown` discloses too. The MCP surface was measured, not assumed, and already fails
+      // closed — `candor_callers` over an armed pair returns `isError: true` from mcp.mjs's fn-existence
+      // guard, which unions the callgraph keys with the report's fns, both empty here.
+      if (Object.keys(graph).length === 0) {
+        const why = "no call graph in the report — the §2.2 sidecar is absent, so who calls this function is UNANSWERABLE, not empty (SPEC §3.3.1 ⟨0.28⟩)";
+        put(args, { of: [q], unanswerable: why }, () => console.log(`candor: ${why}`));
+        process.exit(2);
+      }
+      // ⟨0.28⟩ Only the COMPLETE graph (the sidecar) can prove a name absent. Over the effect-only
+      // fallback a miss is INCONCLUSIVE — a pure leaf called only by pure fns is simply invisible there —
+      // so the answer is empty at exit 0, never a fabricated "no such function" (rust corpus-audit #5,
+      // byte-matching its two arms: `{}` on the machine channel, the re-scan pointer on the human one).
+      if (!completeGraph) {
+        put(args, {}, () => console.log(`candor: no caller of \`${q}\` in the effect-relevant graph (the full call-graph sidecar is absent; re-scan with --out to see pure-only callers).`));
+        break;
+      }
       console.error(`candor-ts-query callers: no function matching '${q}' in the call graph`); process.exit(2);
     }
     put(args, cres, P.callers);
@@ -722,7 +1283,13 @@ switch (cmd) {
   case "map": {
     // Shared query-core — the CLI and MCP `candor_map` are one implementation (see `where` above).
     const { prefix } = resolveReportVerb(args, 0);
-    put(args, coreMap(loadReportOrDie(prefix)), P.map);
+    // ⟨0.28⟩ `map` answers `{}`, which SPEC §2 calls the STRONGEST determined negative there is: every key
+    // a consumer reads defaults to empty, so `d["db"] ?? {}` cannot tell an empty map from an unexamined
+    // one. RUNG A: its top level is a USER NAMESPACE, so the caveat REPLACES the module map rather than
+    // merging into it — the merged shape displaced a real module row to make space for the hedge.
+    putCaveatInstead(args, coreMap(loadReportOrDie(prefix)), P.map, reportCompleteness(prefix),
+      "the module rows below cover only the source candor read",
+      "A module living wholly in an unread unit is MISSING from this overview, and one that IS listed may be missing functions. Re-scan for a complete map.");
     break;
   }
   case "containment": {
@@ -752,10 +1319,20 @@ switch (cmd) {
         process.exit(2);
       }
       const r = coreContainment(loadReportOrDie(prefix), baseFns);
-      put(args, r, P.containment);
+      // ⟨0.28⟩ BOTH SIDES' MANIFESTS. This answer is a DIFFERENCE, so it is unsound if either side is
+      // partial, and in OPPOSITE directions: a leak living in an unread file of the CURRENT tree is missed
+      // (a false all-clear at exit 0), while one living in an unread file of the BASELINE reads as newly
+      // appeared (a fabricated leak, at exit 1). A wholly-empty baseline already fails closed above; a
+      // baseline that loaded but declares `unanalyzed` is the case that reached here silently.
+      putAnswer(args, r, P.containment,
+        absorbCompleteness(reportCompleteness(prefix), reportCompleteness(basePrefix)),
+        "the leak set below is a difference over only the code candor read on BOTH sides",
+        "An unread unit of the current tree hides a leak; an unread unit of the baseline manufactures one. Re-scan both before moving the ratchet.");
       process.exit(r.leaks.length ? 1 : 0);
     }
-    put(args, coreContainment(loadReportOrDie(prefix)), P.containment);
+    putAnswer(args, coreContainment(loadReportOrDie(prefix)), P.containment, reportCompleteness(prefix),
+      "the containment scores below cover only the boundary effects candor could see",
+      "A boundary effect in an unread unit is in no layer's count, so a dispersed effect can score as contained. Re-scan for a complete picture.");
     break;
   }
   case "diff": {
@@ -800,9 +1377,13 @@ switch (cmd) {
     const roots = fns.filter((e) => e.entryPoint);
     const byEff = {};
     for (const e of roots) for (const x of e.inferred) (byEff[x] ??= []).push(e.fn);
-    put(args, { entryPoints: roots.length,
+    // ⟨0.28⟩ `{"entryPoints":0,"effects":{}}` asserts *the program performs no effect at runtime* — the
+    // strongest claim in this binary — and over a report that judged nothing it rests on no evidence.
+    putAnswer(args, { entryPoints: roots.length,
            effects: Object.fromEntries(Object.entries(byEff).sort()
-             .map(([k, v]) => [k, { count: v.length, via: v.sort() }])) }, P.reachable);
+             .map(([k, v]) => [k, { count: v.length, via: v.sort() }])) }, P.reachable, reportCompleteness(prefix),
+      "the runtime effect set below is a union over only the entry points candor could see",
+      "An entry point in an unread unit contributes NOTHING to this union, and neither does any effect it reaches. Re-scan before treating this as the program's runtime surface.");
     break;
   }
   case "impact": {
@@ -812,7 +1393,60 @@ switch (cmd) {
     // A missing/empty <query> is a LOUD usage error (exit 2, like candor-java) — never an
     // affectedCount:0 blast radius at exit 0 for a function that was never named.
     if (!q) { console.error("usage: candor-ts-query impact <query> [--report <locator>] [--json]"); process.exit(2); }
-    put(args, coreImpact(loadReportOrDie(prefix), loadCallgraph(prefix), q), P.impact);
+    const impFns = loadReportOrDie(prefix);
+    // ⟨0.28⟩ Sidecar first, then the report's embedded `calls` edges — rust's `impact` runs on the
+    // report's edges ALONE (callers.rs cmd_impact), so a sidecar-less report must answer here too; see
+    // the callers verb. The unanswerable arm below keeps the genuinely-absent case (the armed pair).
+    let impCg = loadCallgraph(prefix);
+    if (Object.keys(impCg).length === 0) impCg = reportCallsGraph(impFns);
+    // ⟨0.28⟩ UNANSWERABLE MUST REACH THE MACHINE CHANNEL (SPEC §3.3.1), the `callers` fix (5091905) on
+    // the verb its own commit message named as still open. Over an armed pair — report armed to the
+    // ⟨0.21⟩ Row-1 empty, §2.2 sidecars deleted, the STANDARD post-failure state since the ⟨0.28⟩
+    // sidecar rung — this printed `{"fn":…,"affectedCount":0,"affected":[],"entryPoints":[]}` at exit 0.
+    // `affectedCount: 0` is the blast-radius verb's strongest claim: NOTHING CALLS THIS, SAFE TO CHANGE.
+    // With no call graph the engine has not judged that; it has judged nothing. rust/java exit 2 here.
+    //
+    // BOTH CHANNELS FAIL CLOSED (the exit alone leaves a JSON consumer holding a document; the key alone
+    // lets `d.affectedCount ?? 0` read as a determined negative), and the empty ANSWER keys are OMITTED
+    // rather than zeroed, so there is nothing left for a defaulting reader to mistake for a finding.
+    //
+    // THE GATE IS THE EMPTY GRAPH, NOT THE EMPTY ANSWER, and that separation is the load-bearing half.
+    // `impact` resolves its target over the CALLGRAPH keys, so an absent graph makes every answer a
+    // vacuous 0 — that is the unanswerable case. A function that genuinely affects nothing over a REAL
+    // graph still answers `affectedCount: 0` at exit 0 below: a determined negative, and withdrawing it
+    // would be the mirror defect (the ⟨0.24⟩ count-0 lesson, where the plausible fix withdrew 104 real
+    // claims to catch 6). The MCP `candor_impact` was measured, not assumed, and already fails closed —
+    // its fn-existence guard unions the callgraph keys with the report's, both empty here.
+    if (Object.keys(impCg).length === 0) {
+      const why = "no call graph in the report — the §2.2 sidecar is absent, so what this function affects is UNANSWERABLE, not empty (SPEC §3.3.1 ⟨0.28⟩)";
+      put(args, { fn: q, unanswerable: why }, () => console.log(`candor: ${why}`));
+      process.exit(2);
+    }
+    // BAD TARGET → LOUD exit 2 (corpus-audit #3), the rule `callers` applies one verb up and the rule
+    // rust/java ALREADY apply here — measured four-way, array-quoted, on a valid report: rust and java
+    // both exit 2 with `impact: no function matching '…'`, and candor-ts was the ONE arm that printed
+    // `{"fn":"zzz_no_such_fn","affectedCount":0,"affected":[],"entryPoints":[]}` at exit 0. On the
+    // BLAST-RADIUS verb, `affectedCount: 0` is the strongest claim in the vocabulary — "nothing calls
+    // this, safe to change" — and here it was asserted about a function that does not exist. A typo in a
+    // CI script or an agent's query reads back as reassurance (§4); the truth is the question was never
+    // posed. This is the same shape conformance §17 (1b) already pins for `where`/`callers`, on the two
+    // verbs whose comment there wrongly assumed "path/impact already gate".
+    //
+    // A DIFFERENT CONDITION FROM THE UNANSWERABLE GATE ABOVE, and keeping them distinguishable is the
+    // load-bearing half. That one is "there is no call graph" — nothing was judged, so the machine
+    // channel carries an `unanswerable` key. This one is "the graph is fine and the NAME does not
+    // resolve" — a USAGE error, reported the way `where`/`callers`/`show` report one: stderr, and NO
+    // `unanswerable` key, because the run judged plenty. Hence the ORDER: unanswerable first, so an
+    // absent sidecar is never misreported as a bad name (a wrong cause reads as an answer, 5091905).
+    //
+    // NOT THE OTHER DIRECTION: a REAL fn that genuinely affects nothing still answers `affectedCount: 0`
+    // at exit 0 below. "No such function" and "that function affects nothing" must not collapse into one
+    // another — withdrawing the determined negative to catch the fabricated one is the ⟨0.24⟩ count-0
+    // mirror defect, where the plausible fix withdrew 104 real claims to catch 6.
+    if (coreMatches(knownFnNames(impCg, impFns), q).length === 0) {
+      console.error(`candor-ts-query impact: no function matching '${q}'`); process.exit(2);
+    }
+    put(args, coreImpact(impFns, impCg, q), P.impact);
     break;
   }
   case "blindspots": {
@@ -821,10 +1455,18 @@ switch (cmd) {
     const { prefix } = resolveReportVerb(args, 0);
     const ci = args.indexOf("--class");
     const classFilter = ci >= 0 ? args[ci + 1] : null;   // ⟨0.20⟩ drill-down by reason class
+    // ⟨0.28⟩ THE SHARPEST OF THE SIX: `{"sources":[],"totalUnknown":0}` reports *no blind spots* out of a
+    // report whose own manifest names a file candor could not read — the unread file is the blind spot, and
+    // it contributes no entry, so nothing in the computation below can see it. BOTH forms, because
+    // `--stats` is the same claim counted differently (the sibling-route habit: a rule applied where the
+    // work is and never to the arm one line down).
+    const bsComp = reportCompleteness(prefix);
+    const bsSoWhat = "the Unknown sources below are only those rooted in a call candor could see";
+    const bsTail = "An unread unit contributes no entry at all, so its own Unknowns are not counted here and cannot be. Re-scan before treating this as the blind-spot inventory.";
     if (args.includes("--stats")) {   // ⟨0.20⟩ the reason-class distribution, not the source list
-      put(args, coreBlindspotsStats(loadReportOrDie(prefix), classFilter), P.blindspotsStats);
+      putAnswer(args, coreBlindspotsStats(loadReportOrDie(prefix), classFilter), P.blindspotsStats, bsComp, bsSoWhat, bsTail);
     } else {
-      put(args, coreBlindspots(loadReportOrDie(prefix), loadCallgraph(prefix), classFilter), P.blindspots);
+      putAnswer(args, coreBlindspots(loadReportOrDie(prefix), loadCallgraph(prefix), classFilter), P.blindspots, bsComp, bsSoWhat, bsTail);
     }
     break;
   }
@@ -880,6 +1522,9 @@ switch (cmd) {
     // The header names the report's §2 envelope `package` — meaningful and locator-independent, so every
     // engine and every --report form print the SAME crate. Falls back to the prefix basename.
     const crateName = reportPackage(prefix) ?? path.basename(prefix);
+    // ⟨0.28⟩ read ONCE, before either channel branches, so the JSON half and the prose half cannot end up
+    // triggered by two different readings of the same bytes (see `putAnswer`; tour renders its own output).
+    const tourComp = reportCompleteness(prefix);
     if (wantJson) {
       // Pure JSON to STDOUT: {"reaches":[{effect,fn,hops,loc,score,source}, …]} — ALPHABETICAL keys, the
       // same order Rust+Swift emit (loc is the SOURCE's file:line, "" when absent).
@@ -893,9 +1538,17 @@ switch (cmd) {
       const teff = fns.filter((e) => (e.inferred ?? []).length > 0).length;
       const tunk = fns.filter((e) => (e.inferred ?? []).includes("Unknown")).length;
       if (teff > 0 && tunk * 3 >= teff) out.unknown = { count: tunk, total: teff };
-      console.log(JSON.stringify(out));
+      // ⟨0.28⟩ THE SAME ARGUMENT AS `unknown` ABOVE, ONE CAUSE OVER — and the ⅓ threshold cannot reach this
+      // one. That field exists because a bare `{"reaches":[]}` read as clean to the agent loop over a
+      // mostly-Unknown graph; a report that judged nothing, or that names a file it could not read, yields
+      // the IDENTICAL empty array from strictly less evidence, and an unread unit contributes no entry, so
+      // it moves neither `unknown` nor `total`. Spread last, `{}` on a complete report.
+      console.log(JSON.stringify({ ...out, ...completenessFields(tourComp) }));
       break;
     }
+    incompleteAnswerNote(tourComp,
+      "the reaches below are ranked over only the call graph candor could see",
+      "A surprising reach whose path runs through an unread unit is not ranked here at all, and cannot be. Re-scan for the full tour.");
     if (finds.length === 0) {
       // Effectful-but-nothing-surprising vs genuinely-pure both land here; the honest line is the useful
       // answer (never a manufactured surprise) — mirrors the scan-note fallback + the Rust engine. BUT never
@@ -907,9 +1560,14 @@ switch (cmd) {
       if (teff > 0 && tunk * 3 >= teff) {
         console.log(
           `candor: no surprising reaches — but ${tunk} of ${teff} function(s) are Unknown `
-          + `(unresolved calls; their transitive effects are NOT analyzed). Run \`candor blindspots\`; `
-          + `a missing tsconfig.json or unresolvable imports are the usual cause.`,
+          + `(unresolved calls; their transitive effects are NOT analyzed). Run \`candor blindspots\` — `
+          + `the report records a reason for each.`,
         );
+      } else if (mustHedge(tourComp)) {
+        // "nothing hidden" is the single most reassuring sentence this binary prints, and over these bytes
+        // it is the false all-clear in plain English. The ⅓-Unknown branch above cannot catch it, for the
+        // reason given on the JSON arm.
+        console.log(`candor: nothing hidden in what candor COULD SEE ${NOT_A("nothing is hidden")}.`);
       } else {
         console.log("candor: nothing hidden — every effect sits where its name says it should.");
       }
@@ -954,9 +1612,26 @@ switch (cmd) {
     // read as total), plus `coverageDelta` when the baseline names different blind packages. Both
     // OMITTED when nothing applies, so a coverage-free comparison is byte-identical to ⟨0.14⟩.
     // Shared with the MCP `candor_gains` tool (gainsCoverage — the parity rule).
+    // ⟨0.28⟩ SPEC §2 — …AND THE ⟨0.21⟩ MANIFEST TRAVELS ON THE SAME TERMS, WHICH IS THE STRONGER CAVEAT.
+    // The line above carries `coverage` because "no gains over an uncovered dep reads clean with false
+    // confidence"; measured, this same call dropped `unanalyzed` — *I could not read a file of your own
+    // code* — and `analyzed.count: 0` — *I judged nothing at all*. BOTH SIDES, disclosed separately
+    // (`gainsCompletenessFields`): an incomplete CURRENT means the gained set may be SHORT, an incomplete
+    // BASELINE means the comparison floor is soft and the existing/new split unreliable. Not `put`,
+    // because ONE trigger must reach BOTH channels — the JSON-only half is the mutant that survived a
+    // whole suite in candor-rust. Verdict-preserving: the exit below is untouched.
     const gainsResult = coreGains(loadReportOrDie(curPrefix), loadReportOrDie(basePrefix), loadCallgraph(basePrefix));
-    put(args, { baseline_version: gbv ?? "", engine_version: gv ?? "",
-           ...gainsResult, ...gainsCoverage(curPrefix, basePrefix) }, P.gains);
+    const gCur = reportCompleteness(curPrefix), gBase = reportCompleteness(basePrefix);
+    const gDoc = { baseline_version: gbv ?? "", engine_version: gv ?? "",
+           ...gainsResult, ...gainsCoverage(curPrefix, basePrefix), ...gainsCompletenessFields(gCur, gBase) };
+    if (wantJsonOut(args)) emit(gDoc);
+    else {
+      incompleteAnswerNote(gCur, "the gained set below names only effects candor read in the CURRENT tree and may be SHORT",
+        "An effect introduced in an unread unit of the current tree is not in the list below.");
+      incompleteAnswerNote(gBase, "the BASELINE half of this comparison is itself partial and the floor it sets is soft",
+        "An effect living in an unread unit of the baseline reads as NEWLY gained here — the existing/new origin split is unreliable until the baseline is re-scanned.");
+      P.gains(gDoc, mustHedge(gCur) || mustHedge(gBase));
+    }
     // Advisory by default (exit 0 — gains is a diff view); `--strict` fails on ANY gained effect so a
     // supply-chain CI job can require a bump introduce no new capability (mirrors `unverified --strict`).
     process.exit(strict && (gainsResult.gained?.length ?? 0) > 0 ? 1 : 0);
@@ -973,7 +1648,54 @@ switch (cmd) {
     // "does not perform undefined" at exit 0 — a false all-clear over a question that was never posed.
     if (!fn || !eff) { console.error("usage: candor-ts-query path <fn> <Effect> [--report <locator>] [--json]"); process.exit(2); }
     const fns = loadReportOrDie(prefix);
-    const cg = loadCallgraph(prefix);
+    // ⟨0.28⟩ Sidecar first, then the report's embedded `calls` edges (rust's `path` runs on the report's
+    // edges alone — see the callers verb). The unanswerable arm below keeps the genuinely-absent case.
+    let cg = loadCallgraph(prefix);
+    if (Object.keys(cg).length === 0) cg = reportCallsGraph(fns);
+    // ⟨0.28⟩ UNANSWERABLE MUST REACH THE MACHINE CHANNEL (SPEC §3.3.1) — the `impact` argument above,
+    // on the verb that answers the OTHER direction. Over an armed pair this emitted
+    // `{"effect":…,"fn":…,"path":[]}` at exit 0: "there is no route by which this function reaches that
+    // effect", which is precisely the reassurance a reader asks `path` for, over a run that traced
+    // nothing. rust/java exit 2 here.
+    //
+    // BEFORE THE SPLIT, so BOTH arms fail closed, and the human arm is REPAIRED not merely forwarded —
+    // it exited 2 already, but said "no function matching 'f'", a determined negative about the NAME
+    // when the truth is about the GRAPH. (Its other two exits are worse: with a valid report and no
+    // sidecar, `path` reached "does not perform Fs" / "not statically traceable" at exit 0.) Same
+    // correction `callers` needed in 5091905, for the same reason: a wrong cause reads as an answer.
+    //
+    // THE GATE IS THE EMPTY GRAPH, NOT THE EMPTY PATH. `path` resolves its start over the CALLGRAPH
+    // keys, so with no graph every answer is a vacuous `[]`. A function that genuinely does not reach
+    // the effect over a REAL graph still answers `path: []` at exit 0 below — the graph SAID no, and
+    // withdrawing that is the ⟨0.24⟩ count-0 mirror defect. "The graph says no" and "there is no graph"
+    // must stay distinguishable. MCP `candor_path` was measured and already fails closed (`isError`).
+    if (Object.keys(cg).length === 0) {
+      const why = "no call graph in the report — the §2.2 sidecar is absent, so whether this function reaches that effect is UNANSWERABLE, not a determined `no` (SPEC §3.3.1 ⟨0.28⟩)";
+      if (wantJson) emit({ effect: eff, fn, unanswerable: why });
+      else console.log(`candor: ${why}`);
+      process.exit(2);
+    }
+    // BAD TARGET → LOUD exit 2 (corpus-audit #3), the `impact` argument above on the verb that answers
+    // the OTHER direction, and the ONE-ENGINE divergence was HALF a divergence here: the HUMAN arm
+    // (renderPathHuman) has always exited 2 with "no function matching", while `--json` printed
+    // `{"effect":"Net","fn":"zzz_no_such_fn","path":[]}` at exit 0 — "there is no route by which this
+    // function reaches that effect", the precise reassurance a reader asks `path` for, about a function
+    // that does not exist. The MACHINE arm being the lenient one is the worse half: the human at least
+    // saw an error. rust/java/swift all exit 2 on both arms (measured).
+    //
+    // HOISTED ABOVE THE SPLIT so ONE gate covers both arms — the divergence existed because the check
+    // lived inside the human renderer only, and a rule that lives on one route is a rule the sibling
+    // route does not have. renderPathHuman keeps its own resolution (over the REPORT entries, where
+    // `inferred` lives) as the stricter downstream case; this gate refuses only what neither set knows.
+    //
+    // DISTINCT FROM THE UNANSWERABLE GATE ABOVE and ordered after it: "there is no graph" carries the
+    // `unanswerable` key in the machine channel, "the graph is fine and the name is not in it" is a
+    // usage error on stderr. NOT the mirror: a real fn that genuinely does not reach the effect still
+    // answers `path: []` at exit 0 below — the graph SAID no, and "the graph says no", "there is no
+    // graph" and "there is no such function" are three answers, not one.
+    if (coreMatches(knownFnNames(cg, fns), fn).length === 0) {
+      console.error(`candor-ts-query path: no function matching '${fn}'`); process.exit(2);
+    }
     if (wantJson) emit(corePath(fns, cg, fn, eff));           // conformance PART 5 shape — UNCHANGED
     else {
       // The accepted 0.11 default change (the human chain replaced JSON as the no-flag output) gets a
@@ -1017,10 +1739,21 @@ switch (cmd) {
     // consulted BEFORE an edit, where the alternative is the operator guessing. The exit is UNCHANGED:
     // this verb has no `--strict`, §3.2 rules no exit for it, and inventing one is the failure mode the
     // clause it lives beside exists to prevent.
-    const wunan = reportUnanalyzed(prefix);
+    const wcomp = reportCompleteness(prefix);
+    const wunan = wcomp.unanalyzed;
     if (wunan.length)
       console.error(`candor-ts: whatif is NOT a complete answer — the report declares ${wunan.length} unit(s) candor could not analyze (disclosed under \`unanalyzed\`); \`ok\` is omitted because neither value is a statement the input licenses`);
-    emit(advisoryAnswer(r, wunan));
+    // ⟨0.28⟩ …and the count-0 cause, which reaches here through a LIVE §2.2 sidecar: the target resolves
+    // over the call graph, so this verb answers `ok: true` where the report-only verbs exit 2 on the name.
+    // MEASURED exactly so — the pre-edit gate check, green, over a report that judged nothing.
+    if (wcomp.judgedNothing.length) advisoryJudgedNothingNote("whatif");
+    if (wcomp.noManifest.length) advisoryNoManifestNote("whatif", wcomp.noManifest);
+    if (wcomp.unreadable.length) advisoryUnreadableNote("whatif", wcomp.unreadable);
+    // ⟨0.28⟩ SPEC §2 — a CONFIGURED policy that parsed to zero rules asked nothing, so the pre-edit
+    // verdict AND the blast radius it qualifies are withheld in favour of the caveat document. The exit
+    // is UNCHANGED (0: with no rules, `violations` was empty by construction on this path anyway).
+    if (policyFile && policyAskedNothing(pol)) { emitZeroRuleCaveat("whatif", policyFile, wcomp); process.exit(0); }
+    emit(advisoryAnswer(r, wunan, wcomp.judgedNothing, wcomp.unreadable, wcomp.noManifest));
     process.exit(r.violations.length ? 1 : 0);
     break; // unreachable (process.exit), but eslint can't prove it — defends against fallthrough
   }
@@ -1040,8 +1773,17 @@ switch (cmd) {
     // The sidecar is the ONLY graph a candor-ts report carries (it embeds no inline `calls`). Fail LOUD when
     // it's absent — never compute a degenerate empty-graph remedy that reads as a false "no clean hoist".
     if (!cg || Object.keys(cg).length === 0) { console.error(`candor: no call-graph sidecar for '${prefix}' — fix needs it (re-run: candor-ts <src> --out ${prefix})`); process.exit(2); }
-    const r = coreFix(cg, loadReportOrDie(prefix), target, eff, loadPolicyOrDie(policyFile, ptext), scopeMatches);
+    const fpol = loadPolicyOrDie(policyFile, ptext);
+    const r = coreFix(cg, loadReportOrDie(prefix), target, eff, fpol, scopeMatches);
     if (r === null) { console.error(`candor: no function matching \`${target}\` in the call graph`); process.exit(2); }
+    // ⟨0.28⟩ SPEC §2 — this verb shares the policy loader with the three the clause names, and its every
+    // answer is equally policy-relative: over a zero-rule policy it emitted `{"crossing": false,
+    // "reason": "not-forbidden"}` at exit 0, and *not-forbidden* by a policy that forbids nothing is
+    // vacuously true. Composed with the ⟨0.28⟩ `crossing` ruling, this emits NO `crossing` KEY — that key
+    // is present exactly when the verb answered, and here it did not. Exit UNCHANGED (0; the
+    // missing-function usage error above keeps its 2). Placed AFTER that error so a bad `fn` still
+    // reports the bad `fn`.
+    if (policyAskedNothing(fpol)) { emitZeroRuleCaveat("fix", policyFile, reportCompleteness(prefix)); process.exit(0); }
     // ⟨0.24⟩ SPEC §3.2 `4fd140c` — the printed channel for a REFUSED remedy (`refused: true`, no `crossing`
     // key). Without it the terminal shows a document with no plan in it and no reason for the absence.
     if (r.unevaluated?.length) advisoryUnevaluatedNote("fix", r.unevaluated,
@@ -1062,18 +1804,39 @@ switch (cmd) {
     catch { console.error(`candor: policy ${policyFile} could not be read — no fix computed`); process.exit(2); }
     const cg = loadCallgraph(prefix);
     if (!cg || Object.keys(cg).length === 0) { console.error(`candor: no call-graph sidecar for '${prefix}' — fix-gate needs it (re-run: candor-ts <src> --out ${prefix})`); process.exit(2); }
-    const fgr = coreFixGate(cg, loadReportOrDie(prefix), loadPolicyOrDie(policyFile, ptext), scopeMatches);
+    const fgpol = loadPolicyOrDie(policyFile, ptext);
+    const fgr = coreFixGate(cg, loadReportOrDie(prefix), fgpol, scopeMatches);
     // ⟨0.24⟩ SPEC §3.2 — see `advisoryAnswer`. Over a report declaring `unanalyzed` this OMITS `ok`, adds
     // the manifest, and `--strict` (the CI form) exits 2 — could-not-fully-evaluate, the same code the gate
     // uses for the same situation — rather than the 1 that would claim a finding or the 0 that certified.
-    const fgUnan = reportUnanalyzed(prefix);
+    const fgComp = reportCompleteness(prefix);
+    const fgUnan = fgComp.unanalyzed;
     if (fgUnan.length) advisoryIncompleteNote("fix-gate", fgUnan);
+    // ⟨0.28⟩ …and the count-0 cause, which reaches the DOCUMENT and the PROSE but deliberately NOT the exit
+    // below (see `advisoryAnswer`). Leaving it out would have let this verb print a remedy list beside
+    // `ok: true` over a report that judged nothing — the same false all-clear, arriving by omission.
+    if (fgComp.judgedNothing.length) advisoryJudgedNothingNote("fix-gate");
+    if (fgComp.noManifest.length) advisoryNoManifestNote("fix-gate", fgComp.noManifest);
+    if (fgComp.unreadable.length) advisoryUnreadableNote("fix-gate", fgComp.unreadable);
     // ⟨0.24⟩ SPEC §3.2 `4fd140c` — and the same posture for a rule the GATE refused: no remedy is computed
     // from evidence the gate declined to read, the refusal is disclosed on both channels, and `--strict`
     // exits 2 (could-not-evaluate) rather than the 0 that would read as "no crossings left to fix".
     if (fgr.unevaluated?.length) advisoryUnevaluatedNote("fix-gate", fgr.unevaluated, UNEVAL_TAIL_STRICT);
-    emit(advisoryAnswer(fgr, fgUnan));
-    process.exit(fgUnan.length || fgr.unevaluated?.length ? (strict ? 2 : 0) : (strict && !fgr.ok ? 1 : 0));
+    // ⟨0.28⟩ SPEC §2 — an empty `remedies` beside `ok: true` here is a claim relative to a gate that never
+    // asked a question. The caveat document replaces the result; the EXIT is the SAME expression the
+    // result path computes, over the finding sets a zero-rule policy produces by construction (no
+    // remedies, no unanswerable rule) — so it moves only with the REPORT's own incompleteness, exactly as
+    // it does today.
+    if (policyAskedNothing(fgpol)) {
+      emitZeroRuleCaveat("fix-gate", policyFile, fgComp);
+      process.exit(fgUnan.length || fgComp.unreadable.length ? (strict ? 2 : 0) : 0);
+    }
+    emit(advisoryAnswer(fgr, fgUnan, fgComp.judgedNothing, fgComp.unreadable, fgComp.noManifest));
+    // ⟨0.28⟩ `unreadable` joins the `--strict` exit-2 trigger (SPEC §3.2's pessimism relation): `gate
+    // --report` REFUSES over a corrupt member — measured, exit 2 — so exiting 0/1 here claimed this verb
+    // got FURTHER than the gate on identical bytes. The unreadable note above already SAID the exit was
+    // bounded by the gate's while this line did not read the field — a documented limitation, unmeasured.
+    process.exit(fgUnan.length || fgComp.unreadable.length || fgr.unevaluated?.length ? (strict ? 2 : 0) : (strict && !fgr.ok ? 1 : 0));
     break; // unreachable
   }
   case "unverified": {
@@ -1099,19 +1862,37 @@ switch (cmd) {
     const ucg = uci >= 0 ? loadCallgraph(prefix) : {};
     if (uci >= 0 && Object.keys(ucg).length === 0 && !ucg.partial && !ufns.some((e) => (e.calls ?? []).length))
       console.error(`candor-ts: no call-graph sidecar for '${prefix}' and no \`calls\` edges in the report — \`--class\` resolved each hole's reason class from its OWN \`unknownWhy\` only; a hole whose Unknown is INHERITED reads \`unresolved\` here (re-run: candor-ts <src> --out ${prefix})`);
-    const r = coreUnverified(ufns, loadPolicyOrDie(policyFile, ptext), scopeMatches,
+    const upol = loadPolicyOrDie(policyFile, ptext);
+    const r = coreUnverified(ufns, upol, scopeMatches,
                              uci >= 0 ? args[uci + 1] : null, ucg);
     // ⟨0.24⟩ SPEC §3.2 — see `advisoryAnswer`, and this is the SHARPEST case in the family: the verb whose
     // entire job is "your green gate is not provably green" was certifying a set it knows it cannot see all
     // of. A function in an unparsed file is absent from `functions`, so it cannot be enumerated as an
     // unverified pass — and that absence is exactly what this verb would have to report.
-    const uUnan = reportUnanalyzed(prefix);
+    const uComp = reportCompleteness(prefix);
+    const uUnan = uComp.unanalyzed;
     if (uUnan.length) advisoryIncompleteNote("unverified", uUnan);
+    // ⟨0.28⟩ …and the count-0 cause. MEASURED before this line: `{ok: true, unverified: []}` over a report
+    // that judged nothing — this verb certifying a package it never examined. The exit is untouched.
+    if (uComp.judgedNothing.length) advisoryJudgedNothingNote("unverified");
+    if (uComp.noManifest.length) advisoryNoManifestNote("unverified", uComp.noManifest);
+    if (uComp.unreadable.length) advisoryUnreadableNote("unverified", uComp.unreadable);
     // ⟨0.24⟩ SPEC §3.2 `4fd140c` — the function the gate could not judge is NAMED in `unverified` above,
     // with the missing evidence as its reason; this is the human channel for the same fact.
     if (r.unevaluated?.length) advisoryUnevaluatedNote("unverified", r.unevaluated, UNEVAL_TAIL_STRICT);
-    emit(advisoryAnswer(r, uUnan));
-    process.exit(uUnan.length || r.unevaluated?.length ? (strict ? 2 : 0) : (strict && !r.ok ? 1 : 0));
+    // ⟨0.28⟩ SPEC §2 — the sharpest of the four: the verb whose whole job is "your green gate is not
+    // provably green" answered `{"ok": true, "unverified": []}` over a policy that asked nothing. The
+    // empty list is withheld for ⟨0.27⟩'s reason (a refusal document must not carry `violations`), and the
+    // exit follows the same expression the result path computes over empty finding sets.
+    if (policyAskedNothing(upol)) {
+      emitZeroRuleCaveat("unverified", policyFile, uComp);
+      process.exit(uUnan.length || uComp.unreadable.length ? (strict ? 2 : 0) : 0);
+    }
+    emit(advisoryAnswer(r, uUnan, uComp.judgedNothing, uComp.unreadable, uComp.noManifest));
+    // ⟨0.28⟩ `unreadable` joins the `--strict` exit-2 trigger — see fix-gate above. Measured on this verb
+    // before the fix: over one good report plus one unparsable sibling, `gate --report` exited 2 and
+    // `unverified --strict` exited 0 — and `--strict` is how CI consumes it.
+    process.exit(uUnan.length || uComp.unreadable.length || r.unevaluated?.length ? (strict ? 2 : 0) : (strict && !r.ok ? 1 : 0));
     break; // unreachable
   }
   case "gate": {
@@ -1139,13 +1920,17 @@ switch (cmd) {
     const gwrite = (obj) => {
       const text = JSON.stringify(obj, null, 1);
       for (const dest of gdests) {
-        if (dest === "-") { console.log(text); continue; }
+        // THE FLAG IS SET WHERE THE WRITE HAPPENS, not where the gate is entered. It was set on
+        // entering this verb, under the comment "reaching here means the gate ran and will write its
+        // own document" — which is a claim about the future, and false: the `--policy` fallback ladder
+        // can still exit 2 below without writing. That suppressed the pre-pass hook and returned the
+        // run to EMPTY stdout after exit 2, which is the exact channel the hook was added to close.
+        // Caught by the second go/no-go panel; the first flag placement lasted about an hour.
+        if (dest === "-") { globalThis.__candorGateVerdictWritten = true; console.log(text); continue; }
         // A SURFACING side-output: an unwritable path is one stderr line, never a raw ENOENT crash whose
         // exit 1 would read as a policy violation on a clean run (the scan path's rule).
         try {
-          const tmp = `${dest}.${process.pid}.tmp`;
-          fs.writeFileSync(tmp, text + "\n");
-          fs.renameSync(tmp, dest);
+          writeSinkAtomic(dest, text + "\n");
         } catch (e) { console.error(`candor-ts: could not write --gate-json ${dest}: ${e.message}`); }
       }
     };
@@ -1182,7 +1967,23 @@ switch (cmd) {
     // uses (SPEC §3.1 makes byte-equality between the two documents the acceptance test — the scan route
     // needed this list so a dominating baseline regression could carry the refusal beside it, and a list on
     // one route only would break the equality on the very change that repaired the precedence).
-    if (gfatal.length) { const why = policyErrorText(policyFile, gfatal); console.error(why); grefuse(why, policyErrorUnevaluated(gfatal)); }
+    // ⟨0.27⟩ …listing EVERY rule of the refused policy, not only the unhonourable lines — the shared
+    // builder with the scan route (SPEC §3.1's composed-document clause; byte-equality binds the two).
+    if (gfatal.length) { const why = policyErrorText(policyFile, gfatal); console.error(why); grefuse(why, policyRefusalUnevaluated(gtext, gfatal)); }
+    // ⟨0.28⟩ …AND A CONFIGURED POLICY THAT YIELDED ZERO RULES REFUSES THE SAME WAY (SPEC §6.2). The scan
+    // route carries the same block with the same builder; this one is not optional beside it, on §6.2's own
+    // words ("Measured on the `gate --report` verb too — a route is not covered by its sibling") and on
+    // §3.1's byte-equality MUST, which a one-route rung would break on the `# nothing` policy. Every rule
+    // vector, never a subset: `deny` (deny + pure), `allow`, `forbid` — keying on one would refuse an
+    // ordinary allow-only or forbid-only gate as if it had no rules.
+    if (!gpol.deny.length && !gpol.allow.length && !gpol.forbid.length) {
+      const { why, unevaluated } = policyZeroRules(policyFile);
+      console.error(`candor-ts: gate: ${why} — refusing (exit 2, gate NOT enforced). Every line was ignored `
+        + `(see the \`ignoring policy rule\` warnings above), the file is empty, or it holds only comments. A `
+        + `gate with no rules cannot have caught anything, and \`ok: true\` here would be indistinguishable `
+        + `from a gate that ran and found nothing.`);
+      grefuse(why, unevaluated);
+    }
     // ⟨0.24⟩ THE CONFIG FILE THAT SUPPLIED VOCABULARY THE VERDICT USED (SPEC §3.1 `99eb4e9`) — named on a
     // REFERENCE, not only on a firing, because the measured harm was a GREEN verdict a vocabulary file made
     // green. Omitted when no alias was used, so every other verdict stays byte-identical to before.
@@ -1305,6 +2106,17 @@ switch (cmd) {
     // Route the human output exactly as a scan does: to stderr whenever stdout carries the verdict
     // document, so `candor-ts-query gate … --json | jq` sees pure JSON.
     const gsay = (json || gateJsonPath === "-") ? (l) => console.error(l) : (l) => console.log(l);
+    // ⟨0.27⟩ SPEC §4 — THE ZERO-MATCH DISCLOSURE BELONGS ON THIS ROUTE TOO. Its absence was found by a
+    // cross-engine differential: java and swift disclosed on `gate --report`, rust and ts did not, so
+    // the same typo'd policy was reported by two engines and silently scored as satisfied by two. §4's
+    // MUST carries no route qualifier, and this is the SUPPLY-CHAIN gate — a consumer pointing a policy
+    // at a report someone else produced. ALWAYS on stderr, never through `gsay`: this is a disclosure
+    // about the policy, not a verdict line, and stdout may be carrying the verdict document.
+    for (const raw of gviol.zeroMatch ?? []) {
+      console.error(`candor: policy rule matched NO function — \`${raw}\`. It was evaluated and bound `
+        + `nothing, so it cannot have caught anything. Legitimate when one policy is shared across `
+        + `repos; a typo'd layer name otherwise.`);
+    }
     for (const x of gviol) gsay(`[${x.rule}] ${x.detail}`);
     // ⟨0.21⟩ COMPLETENESS MANIFEST: a gate cannot be green over code candor never analyzed. The scan path
     // exits 2 on its OWN `unanalyzed`; here the same manifest travels ON the report, so the same verdict
@@ -1325,6 +2137,16 @@ switch (cmd) {
     if (gvocab) gverdictObj.policyVocabulary = gvocab;
     gverdictObj.violations = gviol;
     if (gunevaluated.length) gverdictObj.unevaluated = gunevaluated;
+    // ⟨0.27⟩ SPEC §4 `zeroMatch` — the same list the stderr lines above carry, in the machine channel,
+    // in the same position the scan route puts it (§3.1's byte-equality MUST binds the two documents).
+    if (gviol.zeroMatch?.length) gverdictObj.zeroMatch = gviol.zeroMatch;
+    // ⟨0.28⟩ SPEC §6.2 `ignored: [{line, text, reason}]` — the policy lines the parse DROPPED, in the SAME
+    // position the scan route puts them, because §3.1 makes byte-equality between the two documents the
+    // acceptance test and §6.2 records this defect measured "on the `gate --report` verb too — a route is
+    // not covered by its sibling". Distinct from `unevaluated`: that carries rules that PARSED and could
+    // not be answered, this carries text that never became a rule at all. Omitted when empty; `ok` and
+    // the exit do not consult it (the line-level leniency is unchanged, only disclosed).
+    if (gpol.ignored?.length) gverdictObj.ignored = gpol.ignored;
     if (gincomplete) { gverdictObj.incomplete = true; gverdictObj.unanalyzed = g.unanalyzed; }
     if (g.coverage.length)
       gverdictObj.coverage = { uncovered: g.coverage.length, packages: g.coverage.map((c) => c.name) };