canary-test-cli 7.1.0 → 7.2.0

package/agents/skills/claude-code/canary-blackhawk/scripts/rules.mjs

@@ -0,0 +1,120 @@
+// Temporal-dependency rule catalog (pure data + compiled patterns).
+//
+// Each rule is a line-level pattern plus the reason it matters. The catalog is
+// deliberately small and language-agnostic: the same scan runs over Python and
+// JS/TS because the idioms do not collide (`new Date()` never appears in Python,
+// `time.time()` never in TypeScript).
+//
+// Rules whose `clockDependent` flag is set are suppressed when the file already
+// installs a frozen clock (see scanner.frozenClockMarkers). Timezone rules are
+// not, because freezing the clock pins *when* a test runs, never *where*.
+//
+// JS has no verbose-regex flag, so patterns are compact literals documented by
+// the comment above them.
+
+export const SEVERITIES = ['high', 'medium', 'low'];
+
+// Frozen-clock idioms. Their presence anywhere in a file suppresses every
+// clock-dependent rule in that file -- the single most important behaviour in
+// this skill, because a naive universal wall-clock rule false-positives on
+// exactly the tests that already handle time correctly.
+export const FROZEN_CLOCK_MARKERS = [
+  'vi.useFakeTimers',
+  'vi.setSystemTime',
+  'jest.useFakeTimers',
+  'jest.setSystemTime',
+  'sinon.useFakeTimers',
+  'MockDate',
+  'freeze_time',
+  'freezegun',
+  'time_machine',
+];
+
+// Tokens that make a datetime expression explicitly timezone-aware.
+const TZ_TOKENS = [
+  'tzinfo',
+  'timezone.utc',
+  'pytz',
+  'tz=',
+  'ZoneInfo',
+  'astimezone',
+];
+
+// JS Date.now() | bare new Date() | moment() | PY datetime.now/today/utcnow() |
+// date.today() | time.time() | pd.Timestamp.now()
+const WALL_CLOCK =
+  /\bDate\.now\s*\(|\bnew\s+Date\s*\(\s*\)|\bmoment\s*\(\s*\)|\bdatetime\.(?:now|today|utcnow)\s*\(|\bdate\.today\s*\(|\btime\.time\s*\(|\bTimestamp\.now\s*\(/;
+
+// PY time.sleep(n) | JS setTimeout(fn, n) with a literal numeric delay.
+const REAL_DELAY =
+  /\btime\.sleep\s*\(\s*(?<delay>[0-9][0-9_]*(?:\.[0-9]+)?)\s*\)|\bsetTimeout\s*\([^,]*,\s*(?<delay2>[0-9][0-9_]*(?:\.[0-9]+)?)\s*[,)]/;
+
+// JS locale formatting | PY strftime with %z / %Z.
+const LOCAL_TZ =
+  /\.toLocale(?:String|DateString|TimeString)\s*\(|strftime\s*\(\s*[frbu]*['"][^'"]*%[zZ]/;
+
+// A comparison against datetime(YYYY, ...) or strptime(...) on either side.
+const NAIVE_COMPARE =
+  /(?:==|!=|<=|>=|<|>)\s*(?:\w+\.)*datetime\s*\(\s*\d{4}|(?:\w+\.)*datetime\s*\(\s*\d{4}[^)]*\)\s*(?:==|!=|<=|>=|<|>)|(?:==|!=|<=|>=|<|>)\s*(?:\w+\.)*strptime\s*\(|(?:\w+\.)*strptime\s*\([^)]*\)\s*(?:==|!=|<=|>=|<|>)/;
+
+/** BH002 guard: keep only when the literal delay is > 0. */
+function delayIsPositive(match) {
+  const raw = match.groups?.delay ?? match.groups?.delay2;
+  const n = Number.parseFloat(String(raw).replace(/_/g, ''));
+  return Number.isFinite(n) && n > 0;
+}
+
+/** BH004 guard: keep only when the compared datetime carries no timezone token. */
+function naiveDatetime(match) {
+  const line = match.input ?? '';
+  return !TZ_TOKENS.some((token) => line.includes(token));
+}
+
+/**
+ * @typedef {{ruleId: string, severity: string, why: string, pattern: RegExp,
+ *            clockDependent: boolean, keep: ((m: RegExpExecArray) => boolean)|null}} Rule
+ */
+
+/** @type {Rule[]} */
+export const RULES = [
+  {
+    ruleId: 'BH001-wall-clock',
+    severity: 'high',
+    why:
+      'reads the wall clock, so the assertion depends on when the suite runs ' +
+      '(midnight, a DST shift, or Feb 29 changes the answer)',
+    pattern: WALL_CLOCK,
+    clockDependent: true,
+    keep: null,
+  },
+  {
+    ruleId: 'BH002-real-delay',
+    severity: 'medium',
+    why:
+      'burns a real delay, so the test is slow by construction and races the ' +
+      'scheduler on a loaded CI runner',
+    pattern: REAL_DELAY,
+    clockDependent: true,
+    keep: delayIsPositive,
+  },
+  {
+    ruleId: 'BH003-local-timezone',
+    severity: 'medium',
+    why:
+      "formats against the machine's local timezone, so the expected string " +
+      'differs between a developer laptop and a UTC CI runner',
+    pattern: LOCAL_TZ,
+    clockDependent: false,
+    keep: null,
+  },
+  {
+    ruleId: 'BH004-naive-datetime-compare',
+    severity: 'low',
+    why:
+      'compares a timezone-naive datetime, so the result shifts with the host ' +
+      'offset and breaks across a DST boundary',
+    pattern: NAIVE_COMPARE,
+    clockDependent: true,
+    keep: naiveDatetime,
+  },
+];

package/agents/skills/claude-code/canary-blackhawk/scripts/scanner.mjs

@@ -0,0 +1,244 @@
+// Line scanner: turns test sources into temporal-dependency findings (pure).
+//
+// Regex/AST-lite by design -- no parser dependency, standard library only -- so
+// it ships wherever node does. See SKILL.md for the fidelity limits that buys.
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { FROZEN_CLOCK_MARKERS, RULES } from './rules.mjs';
+import { stringLiteralRanges, execOutsideStrings } from './string-literals.mjs';
+
+export const SNIPPET_LIMIT = 120;
+
+const SUPPORTED_SUFFIXES = [
+  '.py',
+  '.js',
+  '.jsx',
+  '.ts',
+  '.tsx',
+  '.mjs',
+  '.cjs',
+];
+
+const SKIP_DIRS = new Set([
+  '.git',
+  'node_modules',
+  '__pycache__',
+  '.venv',
+  'venv',
+  'dist',
+  'build',
+  '.mypy_cache',
+  '.pytest_cache',
+  '.tox',
+  // Fixture directories are test DATA: files here never RUN as tests, so a
+  // temporal/order smell in one is a property of the data, not a defect (#493
+  // one level up). Also keeps pragmas out of golden-pinned fixture files.
+  'fixtures',
+  '__fixtures__',
+  '__mocks__',
+  'testdata',
+]);
+
+const TEST_DIRS = new Set(['tests', 'test', '__tests__', 'e2e', 'spec']);
+
+const COMMENT_PREFIXES = ['#', '//', '*', '/*', '"""', "'''"];
+
+const splitLines = (text) => text.split(/\r\n|\r|\n/);
+const isComment = (stripped) =>
+  COMMENT_PREFIXES.some((p) => stripped.startsWith(p));
+const partsOf = (p) => p.split(/[\\/]/).filter(Boolean);
+
+/**
+ * Return the frozen-clock idioms present in `text`, in catalog order. A
+ * non-empty result suppresses every clock-dependent rule for the whole file --
+ * file-wide (not block-scoped) on purpose: a scope-accurate answer needs a real
+ * parser, and blackhawk errs toward silence.
+ */
+export function frozenClockMarkers(text) {
+  return FROZEN_CLOCK_MARKERS.filter((marker) => text.includes(marker));
+}
+
+/** True when a path looks like a test file by name or containing directory. */
+function isTestFile(filePath) {
+  const suffix = path.extname(filePath);
+  if (!SUPPORTED_SUFFIXES.includes(suffix)) return false;
+  const name = path.basename(filePath);
+  const stem = name.slice(0, name.length - suffix.length);
+  if (name.includes('.test.') || name.includes('.spec.')) return true;
+  if (stem.startsWith('test_') || stem.endsWith('_test')) return true;
+  return partsOf(filePath)
+    .slice(0, -1)
+    .some((part) => TEST_DIRS.has(part));
+}
+
+/** Convert an internal finding to its JSON-contract shape (snake_case id). */
+export function toJson(f) {
+  return {
+    file: f.file,
+    line: f.line,
+    rule_id: f.ruleId,
+    severity: f.severity,
+    snippet: f.snippet,
+    why: f.why,
+  };
+}
+
+// Inline suppression pragma (#393): `blackhawk-ignore <RULE>[,<RULE>] -- reason`
+// in a comment. Rule-scoped (so it never blanket-silences a line) and the reason
+// is required (keeps suppressions honest and greppable). A pragma covers the
+// finding on its own line (trailing comment) and the next line (comment above
+// the code) - the two idioms teams reach for.
+const PRAGMA = /\bblackhawk-ignore\s+([A-Za-z0-9,\s-]*?)\s*--\s*(\S.*)$/;
+
+function parsePragmas(lines) {
+  const map = new Map();
+  const add = (ln, tokens) => {
+    if (!map.has(ln)) map.set(ln, new Set());
+    for (const t of tokens) map.get(ln).add(t);
+  };
+  lines.forEach((raw, i) => {
+    // #499: a pragma is a DIRECTIVE, so it only counts as code. Matching the
+    // raw line let a `blackhawk-ignore` inside a string literal register as
+    // live -- data acting as directive, with a fabricated "reason" entering the
+    // suppressed count. This suite necessarily carries pragma text inside
+    // fixture strings, so the self-scan was the thing at risk. Savant shipped
+    // this guard in #498; blackhawk never got it ported back.
+    const m = execOutsideStrings(PRAGMA, raw, stringLiteralRanges(raw));
+    if (!m || !m[2].trim()) return; // reason required
+    const tokens = m[1].split(/[,\s]+/).filter(Boolean);
+    if (!tokens.length) return; // rule-scoped: must name a rule
+    add(i + 1, tokens); // same-line (trailing pragma)
+    add(i + 2, tokens); // next line (pragma above the code)
+  });
+  return map;
+}
+
+// A `BH002` token matches `BH002-real-delay`; the full id also matches.
+const tokenMatches = (ruleId, token) =>
+  ruleId === token || ruleId.split('-')[0] === token;
+
+/**
+ * @typedef {{file: string, line: number, ruleId: string, severity: string,
+ *            snippet: string, why: string}} Finding
+ */
+
+/**
+ * Scan source text. Returns kept `findings` plus `suppressed` findings silenced
+ * by an inline pragma, both ordered by line then rule id.
+ * @returns {{findings: Finding[], suppressed: Finding[]}}
+ */
+export function scanTextFull(text, file = '<text>') {
+  const lines = splitLines(text);
+  const frozen = frozenClockMarkers(text).length > 0;
+  const pragmas = parsePragmas(lines);
+  const findings = [];
+  const suppressed = [];
+  lines.forEach((raw, i) => {
+    const stripped = raw.trim();
+    if (!stripped || isComment(stripped)) return;
+    // #493: a match starting inside a string literal is fixture data, not
+    // code. Computed once per line; every rule's anchor token is code, even
+    // when the pattern's tail reaches into quotes (BH003's strftime('..%Z')).
+    const ranges = stringLiteralRanges(stripped);
+    for (const rule of RULES) {
+      if (frozen && rule.clockDependent) continue;
+      const match = execOutsideStrings(rule.pattern, stripped, ranges);
+      if (!match) continue;
+      if (rule.keep && !rule.keep(match)) continue;
+      const finding = {
+        file,
+        line: i + 1,
+        ruleId: rule.ruleId,
+        severity: rule.severity,
+        snippet: stripped.slice(0, SNIPPET_LIMIT),
+        why: rule.why,
+      };
+      const tokens = pragmas.get(i + 1);
+      if (tokens && [...tokens].some((t) => tokenMatches(rule.ruleId, t))) {
+        suppressed.push(finding);
+      } else {
+        findings.push(finding);
+      }
+    }
+  });
+  return { findings, suppressed };
+}
+
+/** Scan source text, returning kept findings (back-compat wrapper). */
+export function scanText(text, file = '<text>') {
+  return scanTextFull(text, file).findings;
+}
+
+/** Scan one file. Unreadable files yield nothing. */
+function scanFileFull(filePath) {
+  let text;
+  try {
+    text = fs.readFileSync(filePath, 'utf8');
+  } catch {
+    return { findings: [], suppressed: [] };
+  }
+  return scanTextFull(text, filePath);
+}
+
+/** Yield the files a path contributes: explicit files win, dirs are filtered. */
+function* iterFiles(root) {
+  let stat;
+  try {
+    stat = fs.statSync(root);
+  } catch {
+    return;
+  }
+  if (stat.isFile()) {
+    if (SUPPORTED_SUFFIXES.includes(path.extname(root))) yield root;
+    return;
+  }
+  const collected = [];
+  const walk = (dir) => {
+    let entries;
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (SKIP_DIRS.has(entry.name)) continue;
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) walk(full);
+      else if (entry.isFile()) collected.push(full);
+    }
+  };
+  walk(root);
+  collected.sort();
+  for (const f of collected) {
+    if (partsOf(f).some((part) => SKIP_DIRS.has(part))) continue;
+    if (isTestFile(f)) yield f;
+  }
+}
+
+/** Scan every given file/directory, de-duplicating overlapping paths. */
+export function scanPaths(paths) {
+  const seen = new Set();
+  const findings = [];
+  let scanned = 0;
+  let suppressed = 0;
+  for (const entry of paths) {
+    for (const filePath of iterFiles(entry)) {
+      const resolved = path.resolve(filePath);
+      if (seen.has(resolved)) continue;
+      seen.add(resolved);
+      scanned += 1;
+      const r = scanFileFull(filePath);
+      findings.push(...r.findings);
+      suppressed += r.suppressed.length;
+    }
+  }
+  findings.sort(
+    (a, b) =>
+      a.file.localeCompare(b.file) ||
+      a.line - b.line ||
+      a.ruleId.localeCompare(b.ruleId),
+  );
+  return { findings, filesScanned: scanned, suppressed };
+}

package/agents/skills/claude-code/canary-blackhawk/scripts/string-literals.mjs

@@ -0,0 +1,116 @@
+// String-literal ranges for a single source line (pure, stdlib-only). #493.
+//
+// Both canary-blackhawk and canary-savant regex over raw lines, so without
+// this they flag their own test fixtures: `pyFile('time.sleep(1)')` is data,
+// not a call. The correction is deliberately narrow -- a match is rejected
+// only when its START index falls inside a string literal. Stripping string
+// contents before matching would be wrong: blackhawk's BH003 pattern matches
+// `strftime('..%Z')` with the `%Z` inside the quotes ON PURPOSE; the anchor
+// token (`strftime`, `time.sleep`, `Date.now`, ...) is what separates code
+// from data.
+//
+// This file is intentionally duplicated verbatim in canary-blackhawk and
+// canary-savant: skills are self-contained by contract (their packaging
+// suites forbid cross-imports), and #479 tracks extracting shared skill
+// infrastructure. A parity test pins the two copies byte-identical.
+//
+// Fidelity limits (line-based scanner, no parser):
+// - Handles '...', "...", and `...` template literals. `${...}` interpolation
+//   regions are CODE (a nested-frame scan, so `${`x`}` and `${fn({a:1})}`
+//   work); backslash escapes are respected; a quote of the other kind inside
+//   a string is content.
+// - An unterminated quote marks the REST OF THE LINE as string. That is the
+//   safe default for multi-line Python strings whose opener ends mid-line,
+//   and for apostrophes in trailing comments: this helper only ever REJECTS
+//   matches, so the worst case is a suppressed match inside what was really
+//   string-ish text -- never a new false positive.
+// - Strings spanning lines (template literals, triple quotes) are only seen
+//   on their opening line; continuation lines look like code. Accepted: the
+//   scanners are line-based by design.
+// - Regex literals containing quotes (/['"]/) can open a phantom string for
+//   the rest of the line. Same rejection-only safety argument applies.
+
+/**
+ * Compute the [start, end) index ranges of string-literal CONTENT in `line`
+ * (quote characters excluded; empty literals contribute no range).
+ * @param {string} line
+ * @returns {Array<[number, number]>}
+ */
+export function stringLiteralRanges(line) {
+  /** @type {Array<[number, number]>} */
+  const ranges = [];
+  // Frames: {quote, start} while inside a string; {interp: true, depth}
+  // while inside a template's ${...} (which is code and may nest strings).
+  const stack = [];
+  const top = () => stack[stack.length - 1];
+  for (let i = 0; i < line.length; i += 1) {
+    const ch = line[i];
+    const frame = top();
+    if (frame && frame.quote) {
+      if (ch === '\\') {
+        i += 1; // escaped char is content, never a closer
+      } else if (ch === frame.quote) {
+        ranges.push([frame.start, i]);
+        stack.pop();
+      } else if (frame.quote === '`' && ch === '$' && line[i + 1] === '{') {
+        // Interpolation is code: close the string segment before `${`.
+        ranges.push([frame.start, i]);
+        stack.push({ interp: true, depth: 0 });
+        i += 1;
+      }
+      continue;
+    }
+    // Code context: top-level, or inside `${ ... }`.
+    if (ch === "'" || ch === '"' || ch === '`') {
+      stack.push({ quote: ch, start: i + 1 });
+    } else if (frame && frame.interp) {
+      if (ch === '{') {
+        frame.depth += 1;
+      } else if (ch === '}') {
+        if (frame.depth === 0) {
+          stack.pop();
+          top().start = i + 1; // the enclosing template resumes here
+        } else {
+          frame.depth -= 1;
+        }
+      }
+    }
+  }
+  // Unterminated string: treat the rest of the line as string (see header).
+  // An open interpolation frame is code and stays unmarked.
+  const frame = top();
+  if (frame && frame.quote) ranges.push([frame.start, line.length]);
+  return ranges.filter(([start, end]) => end > start);
+}
+
+/**
+ * True when `index` falls inside any of the given content ranges.
+ * @param {Array<[number, number]>} ranges
+ * @param {number} index
+ * @returns {boolean}
+ */
+export function inStringLiteral(ranges, index) {
+  return ranges.some(([start, end]) => index >= start && index < end);
+}
+
+/**
+ * Like `pattern.exec(line)`, but skips matches whose start index falls
+ * inside a string literal, returning the first CODE match (or null).
+ * @param {RegExp} pattern
+ * @param {string} line
+ * @param {Array<[number, number]>} ranges precomputed for `line`
+ * @returns {RegExpExecArray | null}
+ */
+export function execOutsideStrings(pattern, line, ranges) {
+  if (ranges.length === 0) return pattern.exec(line);
+  const flags = pattern.flags.includes('g')
+    ? pattern.flags
+    : `${pattern.flags}g`;
+  const re = new RegExp(pattern.source, flags);
+  let match;
+  while ((match = re.exec(line)) !== null) {
+    if (!inStringLiteral(ranges, match.index)) return match;
+    if (re.lastIndex === match.index) re.lastIndex += 1; // zero-width guard
+  }
+  return null;
+}

package/agents/skills/claude-code/canary-cassandra/SKILL.md

@@ -0,0 +1,180 @@
+---
+name: canary-cassandra
+description: >
+  Vacuous-test detection — finds tests that PASS WITHOUT PROVING ANYTHING: an
+  assertion that compares a value with itself, a test that never invokes the
+  target it claims to cover, and a test whose every assertion is an absence
+  observed on a bystander rather than on the code under test. Use when the user
+  says "why did this pass against the bug", "are these tests actually testing
+  anything", "audit my suite for vacuous tests", "green but worthless", or after
+  a bug shipped through a green suite. Advisory and deterministic — no LLM, no
+  execution. NOT for tests with zero assertions (that is `canary review-test`'s
+  LINT-006), NOT for flaky tests (canary-flake-hunter), and NOT a coverage tool
+  — a vacuous test has coverage, which is exactly why coverage never caught it.
+cli: scripts/cli.mjs
+requires: [node>=20]
+---
+
+# Canary Cassandra
+
+> Cassandra Cain reads the fake. So does this skill.
+
+A test with no assertions is easy to find and everybody already looks for it.
+The dangerous test is the one with assertions that **cannot fail** — it has
+coverage, it goes green, and it goes green identically against the bug it was
+written to catch. Three of those shipped in this project in a single cycle
+(recorded in [#486]) and every gate the repo owned read all three as healthy.
+
+Cassandra is Tier-0: deterministic, no LLM, no network, no execution.
+
+## What it finds
+
+| Rule      | Severity | Fires on                                                                                                          |
+| --------- | -------- | ----------------------------------------------------------------------------------------------------------------- |
+| `VAC-001` | critical | An assertion whose expectation is identical to the value it checks — `expect(true).toBe(true)`, `assert x == x`   |
+| `VAC-002` | warning  | The test never references the target it claims to cover                                                           |
+| `VAC-003` | warning  | Every assertion in the test asserts an _absence_, and none of them observes the target — so nothing proves it ran |
+
+`VAC-001` is deterministic, hence `critical`: no implementation can fail it.
+`VAC-002` and `VAC-003` depend on resolving a target, which is inference, so
+they are `warning` and carry a fidelity tier.
+
+## Run it
+
+Two doors, one detector. Both run the same engine rules, so they cannot disagree
+about a finding or about the denominator.
+
+```bash
+canary vacuity-check tests/            # human-readable
+canary vacuity-check tests/ --json     # verdict + denominator + skips
+canary vacuity-check tests/a.test.ts   # one file
+```
+
+As a skill, for an orchestrator or a CI step composing all four Tier-0
+detectors:
+
+```bash
+canary skills run canary-cassandra -- tests/
+canary skills run canary-cassandra -- tests/ --json --strict
+```
+
+Usage, flags, and the full rule list — this one is runnable verbatim, needs no
+fixtures, and is what CI executes to prove the doc still matches the CLI:
+
+```bash
+canary skills run canary-cassandra -- --help
+```
+
+The `--json` envelope matches `canary-savant` / `canary-blackhawk` /
+`canary-katana` — `schema_version`, a `findings` array of
+`{file, line, rule_id, severity, snippet, why}`, and a `summary` — so findings
+from all four merge without special-casing one. Cassandra adds `suggestion` and
+`fidelity` per finding, and `tests_checked` to the summary, because its
+denominator is tests rather than files.
+
+**Advisory by design.** Findings exit **0**. This is the repo's established
+shape for a new detector — advisory first, ratchet to strict only after triage
+(see the dogfooding jobs, [#485]). Do not wire it as a required check on the day
+you adopt it; run it, triage the count, then decide.
+
+A collapsed denominator is **not** advisory and exits **3**. See below.
+
+## The fidelity ladder (the part that decides whether to trust a finding)
+
+A test's "declared target" is declared nowhere, so `VAC-002`/`VAC-003` have to
+resolve one. Three rungs, and the finding says which one it used:
+
+| Tier              | How the target was resolved                                                                   | Trust                                 |
+| ----------------- | --------------------------------------------------------------------------------------------- | ------------------------------------- |
+| `annotated`       | The author wrote `// @covers <symbol>`. That exact symbol is checked.                         | High — the author stated the contract |
+| `import-inferred` | The symbols imported from first-party (relative) modules, closed over local helpers           | Medium — read the test before acting  |
+| _(skipped)_       | Neither available. Reported as a skip with its reason; the test is **not** reported as clean. | None — the check did not run          |
+
+`import-inferred` reads four binding forms, not one: a named or default import,
+a **namespace** import (`import * as store from './store.js'`), a **dynamic**
+import (`const { save } = await import('./store.js')`), and a handle bound to a
+first-party **script path** that a `spawnSync`/`execFileSync`-family call then
+runs. The last is what a subprocess test has instead of a symbol; the
+discriminator is the path, so spawning a bare command (`spawnSync('git', …)`)
+still counts as reaching nothing. A test that launches a script path written
+inline, or that carries a bare `await import('./x.js')`, is likewise read as
+reaching its target — but `VAC-003` stays dark for it and says so in the skip
+list, because "did an assertion observe the target" needs a symbol that a
+subprocess boundary does not provide (#705).
+
+To upgrade a finding from inferred to annotated, add the annotation above the
+test:
+
+```ts
+// @covers resolveOverlay
+it('falls back to the tracked overlay', () => {
+  /* ... */
+});
+```
+
+That is also the fix for a false positive: if the target is reached several
+frames deep and the inference cannot see it, `@covers` tells the check what to
+look for instead of arguing with the heuristic.
+
+## Why a zero denominator exits 3
+
+The whole point of this skill is that **green can mean nothing**. A vacuity
+detector that reported its own silence as success would be the joke telling
+itself, so:
+
+- **No test file matched** → exit 3, `Abstained — verified zero items`.
+- **Files matched but held zero tests** → also exit 3. This is the subtler zero:
+  the file-level count looks healthy, and a scanner that only guarded that one
+  prints a clean tick.
+- **A test whose target could not be resolved** → a `skipped` entry naming the
+  test and the reason, rendered in every summary line.
+
+`checked` in the JSON payload is the number of **tests** read, not files. Always
+read it before believing a zero.
+
+## Reading the output
+
+```text
+[CRITICAL] tests/cli.test.ts:41 (VAC-001)
+  --help does not write the ledger: Assertion compares a value with itself; no implementation can fail it.
+  → Assert the value the code under test should have produced, not the input.
+
+3 finding(s) across 214 checked (11 skipped: VAC-002/VAC-003 (adds two numbers) [target unresolvable: ...])
+```
+
+The summary line always carries the denominator and the skips. A finding count
+with no denominator is not a result.
+
+## Rationalizations to reject
+
+| Rationalization                                          | Why it is wrong                                                                                                                                   |
+| -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| "It's covered, so it's tested"                           | A vacuous test executes the line and asserts nothing about it. Coverage is the reason this class survives — it satisfies the metric perfectly.    |
+| "VAC-002 flagged a test I know is correct, so it's junk" | Add `// @covers <symbol>`. That converts a guess into a checked claim, permanently, for every future run.                                         |
+| "0 findings, we're clean"                                | Only if `checked` is greater than zero. Read the denominator; exit 3 means the check never ran.                                                   |
+| "We'll make it a required check right away"              | A new detector lands advisory. Triage the existing count first, then ratchet — otherwise the first red build teaches the team to bypass the gate. |
+| "The absence assertion is fine, the test passes"         | That is the `VAC-003` defect exactly: it also passed when the code exited before doing anything. One positive assertion makes it load-bearing.    |
+
+## Escalation
+
+- **A VAC-001 finding is never a false positive.** It is a comparison of a value
+  with itself. Fix the test.
+- **A large VAC-002 count on first run usually means dynamic imports.** Tests
+  that `await import(...)` their target have no static import for the inference
+  to read. Annotate them, or accept the tier and move on — do not rewrite the
+  suite to satisfy a heuristic.
+- **A finding you disagree with is a doc gap, not an argument.** Write the
+  `@covers` annotation; the next reader gets the answer for free.
+
+## Related
+
+- `canary review-test` — `LINT-006` (zero assertions) and `SOUND-001/002/003` (a
+  test that pins a value no correct implementation must produce). Cassandra
+  deliberately does not duplicate either.
+- `canary-promote-test` — consumes these findings as a structured verdict and
+  blocks promotion on the deterministic ones.
+- `canary-katana`, `canary-savant`, `canary-blackhawk` — the other Tier-0
+  deterministic scanners.
+
+[#485]: https://github.com/bop-clocktower/canary/issues/485
+[#486]: https://github.com/bop-clocktower/canary/issues/486