@codyswann/lisa 3.6.2 → 3.8.0

package/typescript/copy-overwrite/ast-grep/rules/no-missing-fs-extra-namespace-member-js.yml

@@ -0,0 +1,71 @@
+# This file is managed by Lisa.
+# Do not edit directly — changes will be overwritten on the next `lisa` run.
+#
+# JavaScript-language twin of `no-missing-fs-extra-namespace-member.yml`.
+#
+# ast-grep binds one parser per rule: `language: typescript` scans only
+# .ts/.mts/.cts, so .js/.mjs/.cjs would otherwise be an unguarded gap — and a
+# guard with a silent hole is the failure mode this rule exists to prevent.
+# Build scripts and tooling in TypeScript projects are routinely .mjs, and
+# fs-extra is exactly the kind of dependency they reach for.
+#
+# The `constraints` block MUST stay byte-identical to the TypeScript rule.
+# `tests/unit/config/ast-grep-template.test.ts` asserts both files carry the
+# same allow list AND that it still equals the set real Node reports, so these
+# two cannot drift apart or drift away from reality unnoticed.
+#
+# See the TypeScript rule for the full rationale on why this is an allow list
+# rather than a deny list, and why the set is stable across fs-extra 11.x.
+id: no-missing-fs-extra-namespace-member-js
+language: javascript
+severity: error
+message: |
+  `fs-extra` does not expose this member on its ESM namespace object.
+
+  `import * as fse from "fs-extra"` resolves to fs-extra's CommonJS entry, so
+  Node derives the namespace keys with cjs-module-lexer. Only fs-extra's own
+  directly-assigned functions survive that. Absent members include every JSON
+  helper (readJson, readJSON, writeJson, outputJson, and their Sync forms),
+  every node:fs passthrough (readFile, writeFile, readdir, stat, existsSync,
+  appendFile, ...), and copySync, moveSync, removeSync, pathExistsSync and
+  outputFileSync.
+
+  The call is `undefined` at run time and throws a TypeError, and unit tests
+  cannot see it — Vitest and Jest resolve the import through CJS interop and
+  hand back the default export's properties.
+
+  Fix by importing the concrete API instead:
+    - file I/O     -> `readFile` / `writeFile` from `node:fs/promises`
+    - JSON         -> read the file, then `JSON.parse` / `JSON.stringify`
+    - whole module -> `import fse from "fs-extra"`. The DEFAULT export does
+                      carry every member and is deliberately not flagged here.
+# Test trees are excluded on purpose — see the TypeScript rule for the full
+# rationale. In short: the defect class is "works under a bundler, `undefined`
+# under real Node", so it can only bite code Node executes directly, and the
+# runtime control in the Lisa monorepo already scopes itself to source trees
+# for exactly that reason. Keep this list in step with the TypeScript rule.
+ignores:
+  - '**/tests/**'
+  - '**/test/**'
+  - '**/__tests__/**'
+  - '**/__mocks__/**'
+  - '**/*.test.js'
+  - '**/*.test.mjs'
+  - '**/*.test.cjs'
+  - '**/*.test.jsx'
+  - '**/*.spec.js'
+  - '**/*.spec.mjs'
+  - '**/*.spec.cjs'
+  - '**/*.spec.jsx'
+rule:
+  all:
+    - pattern: $NS.$MEMBER
+    - inside:
+        kind: program
+        stopBy: end
+        has:
+          pattern: import * as $NS from "fs-extra"
+constraints:
+  MEMBER:
+    not:
+      regex: ^(copy|createFile|createFileSync|createLink|createLinkSync|createSymlink|createSymlinkSync|default|emptyDir|emptyDirSync|emptydir|emptydirSync|ensureDir|ensureDirSync|ensureFile|ensureFileSync|ensureLink|ensureLinkSync|ensureSymlink|ensureSymlinkSync|exists|mkdirp|mkdirpSync|mkdirs|mkdirsSync|move|outputFile|pathExists|read|readv|remove|write|writev)$

package/typescript/copy-overwrite/ast-grep/rules/no-missing-fs-extra-namespace-member.yml

@@ -0,0 +1,90 @@
+# This file is managed by Lisa.
+# Do not edit directly — changes will be overwritten on the next `lisa` run.
+#
+# Bans `fs-extra` namespace members that do not exist under real Node ESM.
+#
+# The allow list below is an ALLOW list, not a deny list, and that is
+# deliberate. A deny list fails open: any absent member nobody thought to
+# enumerate passes silently, which is the exact rot this rule exists to
+# prevent. An allow list fails closed — an unrecognised member is flagged
+# loudly and a human decides.
+#
+# The list is the set of keys real Node reports for
+# `import * as fse from "fs-extra"`. It is byte-identical across fs-extra
+# 11.1.1, 11.3.3, 11.3.4 and 11.3.5, because the bare specifier always routes
+# through the package `exports` map to the CommonJS entry (`./lib/index.js`)
+# and Node derives the namespace keys with cjs-module-lexer from a re-export
+# shape that has not changed. `lib/esm.mjs` — which does export the JSON
+# helpers — is reachable only via the `fs-extra/esm` subpath, which is a
+# different import.
+#
+# Anti-rot: `tests/unit/core/fs-extra-namespace-callsites.test.ts` in the Lisa
+# monorepo derives this same set from real Node at run time, and
+# `tests/unit/config/ast-grep-template.test.ts` asserts the list below still
+# equals it. If fs-extra ever changes its namespace surface, that pairing goes
+# red centrally instead of this list silently drifting in every host project.
+id: no-missing-fs-extra-namespace-member
+language: typescript
+severity: error
+message: |
+  `fs-extra` does not expose this member on its ESM namespace object.
+
+  `import * as fse from "fs-extra"` resolves to fs-extra's CommonJS entry, so
+  Node derives the namespace keys with cjs-module-lexer. Only fs-extra's own
+  directly-assigned functions survive that. Absent members include every JSON
+  helper (readJson, readJSON, writeJson, outputJson, and their Sync forms),
+  every node:fs passthrough (readFile, writeFile, readdir, stat, existsSync,
+  appendFile, ...), and copySync, moveSync, removeSync, pathExistsSync and
+  outputFileSync.
+
+  The call is `undefined` at run time and throws a TypeError. Unit tests are
+  structurally blind to it: Vitest and Jest resolve the import through CJS
+  interop and hand back the default export's properties, so the call is a
+  function in every test and `undefined` in production. Lisa shipped this
+  defect three times in one release window (#2482, #2487) — once as a crash
+  that stranded seven merged PRs, twice inside error-swallowing `catch` blocks
+  where the TypeError replaced the error being handled.
+
+  Fix by importing the concrete API instead:
+    - file I/O     -> `readFile` / `writeFile` from `node:fs/promises`
+    - JSON         -> read the file, then `JSON.parse` / `JSON.stringify`
+    - whole module -> `import fse from "fs-extra"`. The DEFAULT export does
+                      carry every member and is deliberately not flagged here.
+# Test trees are excluded on purpose, matching the scope the runtime control
+# already chose. The defect class is "works under a bundler, `undefined` under
+# real Node" — so it can only bite code that Node executes directly. Vitest and
+# Jest resolve `import * as fse from "fs-extra"` through CJS interop and hand
+# back the default export's properties, which is precisely why test files can
+# call `fse.writeJson` forever without ever being wrong.
+#
+# `tests/unit/core/fs-extra-namespace-callsites.test.ts` scopes itself to
+# ["src", "scripts"] for this reason — "trees whose code is executed by Node
+# directly, not through a bundler". This rule matches that scope rather than
+# inventing a second, wider one. Path globs are used instead of a src/scripts
+# allowlist because host project layouts vary (apps/, packages/, lib/) while
+# test directory conventions do not.
+ignores:
+  - '**/tests/**'
+  - '**/test/**'
+  - '**/__tests__/**'
+  - '**/__mocks__/**'
+  - '**/*.test.ts'
+  - '**/*.test.mts'
+  - '**/*.test.cts'
+  - '**/*.test.tsx'
+  - '**/*.spec.ts'
+  - '**/*.spec.mts'
+  - '**/*.spec.cts'
+  - '**/*.spec.tsx'
+rule:
+  all:
+    - pattern: $NS.$MEMBER
+    - inside:
+        kind: program
+        stopBy: end
+        has:
+          pattern: import * as $NS from "fs-extra"
+constraints:
+  MEMBER:
+    not:
+      regex: ^(copy|createFile|createFileSync|createLink|createLinkSync|createSymlink|createSymlinkSync|default|emptyDir|emptyDirSync|emptydir|emptydirSync|ensureDir|ensureDirSync|ensureFile|ensureFileSync|ensureLink|ensureLinkSync|ensureSymlink|ensureSymlinkSync|exists|mkdirp|mkdirpSync|mkdirs|mkdirsSync|move|outputFile|pathExists|read|readv|remove|write|writev)$

package/typescript/copy-overwrite/scripts/check-skipped-required-checks.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 /**
- * check-skipped-required-checks — refuse a `skip_jobs` token that silences a
- * ruleset-required status check.
+ * check-skipped-required-checks — refuse a required status check that satisfies
+ * without proving anything.
  *
  * Shipped by Lisa (copy-overwrite). Generalized from tunnl's TUN-402 guard: the
  * logic is Lisa's and gets updated fleet-wide, the two REVIEWED SNAPSHOTS it
@@ -10,6 +10,23 @@
  *
  * Usage:
  *   node scripts/check-skipped-required-checks.mjs [rootDir] [--remote] [--json]
+ *   node scripts/check-skipped-required-checks.mjs --pr=1234 [--repo=OWNER/NAME]
+ *
+ * ## The family this guard covers
+ *
+ * **Required-and-red is loud; required-and-vacuous is not; advisory-and-stale is
+ * invisible.** All three are the same defect wearing different clothes — a gate
+ * that reports satisfied without having proven anything — and the useful
+ * question is never "did the check pass" but "did the check do anything".
+ *
+ * Two of the three live here:
+ *
+ *  - **Skipped** (`--remote` / offline arm, below): GitHub counts a `skipped`
+ *    required check as SATISFIED, so a `skip_jobs` token makes the gate
+ *    decorative. Static, offline, BLOCKING.
+ *  - **Vacuous** (`--pr` arm): the check really ran and really reported
+ *    `success`, having done no work — measured on CodeRabbit posting
+ *    `success — "Review rate limited"`. Live, per-PR, REPORTING ONLY.
  *
  * ## Where this runs
  *
@@ -96,6 +113,57 @@
  * network and `gh` auth on every run would flake, and a flaky guard gets
  * skipped — which reintroduces exactly the false-green class this file refuses.
  *
+ * ## `--pr` — the VACUOUS arm, and why it only ever reports
+ *
+ * Measured (CodySwannGT/lisa#2497): `CodeRabbit` was in this repository's
+ * required set, and on PRs #2483 and #2484 it posted `success` with the
+ * description `Review rate limited` having performed ZERO reviews. Both merged
+ * on that green, both carried security-relevant changes, both shipped in tag
+ * `v3.5.1`. Branch protection recorded "reviewed" for work nothing reviewed.
+ *
+ * The failure is silent by construction, and this is the whole point:
+ *
+ * ```
+ * gh pr checks <PR> | grep -i coderabbit
+ * CodeRabbit    pass    0    Review rate limited     <- hollow
+ * CodeRabbit    pass    1    Review completed        <- real
+ * ```
+ *
+ * **The status column says `pass` either way. Only the description
+ * distinguishes them.** So anything gating on such a check must read the
+ * description, and `--pr` is the machine-readable form of that one-line triage.
+ *
+ * This arm NEVER blocks — `NEVER_BLOCKING`, enforced regardless of the
+ * declaration's `enforcement` mode. Two independent reasons, both load-bearing:
+ *
+ *  1. A review bot's availability can depend on an org-wide SPENDING CAP. A
+ *     blocking check that fires on a billing state makes merges hostage to
+ *     accounting, which is a worse gate than the one it replaces.
+ *  2. Whether a review bot belongs in the required set at all is a governance
+ *     decision an owner has to make. Shipping the gate before the decision
+ *     would pre-empt it. Detection is what is uncontroversial; act on it.
+ *
+ * ## Proof is matched STRICTLY, no-work LOOSELY
+ *
+ * The two description lists are deliberately asymmetric, because their errors
+ * are not symmetric:
+ *
+ *  - A `proof` phrase must match the whole description (case-insensitive,
+ *    trimmed). Matching here GRANTS CREDIT, and a loose match that grants
+ *    credit is exactly the false green this file exists to refuse.
+ *  - A `no_work` phrase matches as a substring. Matching here DENIES credit,
+ *    so breadth is safe — and it survives a vendor appending detail
+ *    (`Review rate limited (retry in 12m)`).
+ *
+ * Anything matching neither is `unproven` — reported, never silently passed. A
+ * vocabulary nobody enumerated must not read as a pass.
+ *
+ * Unlike `required_contexts`, this vocabulary is NOT repo-specific: `Review
+ * rate limited` is the vendor's own product string, identical in every
+ * repository. That is why shipping it as a default is safe where shipping a
+ * guessed ruleset was not (#2476) — and why a wrong guess here costs one line
+ * of report rather than a red build.
+ *
  * ## Exact string equality, everywhere
  *
  * Every comparison here is `===`. Repos routinely carry confusable pairs — an
@@ -170,6 +238,55 @@ export const VIOLATIONS = Object.freeze({
   badExemption: "exemption_without_valid_ticket",
   remoteDrift: "ruleset_snapshot_drift",
   whitespace: "whitespace_in_skip_token",
+  vacuous: "vacuous_required_check",
+  unproven: "unproven_required_check",
+});
+
+/**
+ * The shipped description vocabulary for review-bot style checks.
+ *
+ * `proof` is matched STRICTLY (whole description, case-insensitive, trimmed)
+ * because a match grants credit. `no_work` is matched LOOSELY (substring)
+ * because a match denies it. See the header for why that asymmetry is the safe
+ * direction.
+ *
+ * Every string here was read off a real check on a real PR in this fleet, not
+ * invented: `Review rate limited` (#2483, #2484, #2495), `Review approved`
+ * (#2350). A repository may extend either list per check without losing these.
+ */
+export const REVIEW_DESCRIPTION_DEFAULTS = Object.freeze({
+  proof: Object.freeze([
+    "review approved",
+    "review completed",
+    "changes requested",
+    "comments posted",
+  ]),
+  no_work: Object.freeze([
+    "rate limited",
+    "review queued",
+    "review skipped",
+    "skipped",
+    "queued",
+    "waiting",
+    "in progress",
+    "no review",
+    "disabled",
+    "quota",
+    "billing",
+  ]),
+});
+
+/**
+ * Verdicts `classifyCheckDescription` returns.
+ *
+ * `unproven` is the FALLBACK on purpose: the absence of a recognised phrase is
+ * the absence of evidence, and this file's whole thesis is that those are not
+ * the same as a pass.
+ */
+export const DESCRIPTION_VERDICTS = Object.freeze({
+  proved: "proved",
+  noWork: "no-work",
+  unproven: "unproven",
 });
 
 /** Enforcement modes a declaration may select. */
@@ -195,6 +312,50 @@ const ALWAYS_BLOCKING = Object.freeze([
   VIOLATIONS.remoteDrift,
 ]);
 
+/**
+ * Violation kinds that NEVER fail the build, in any enforcement mode.
+ *
+ * The vacuity arm reports and stops there. A required check can go hollow
+ * because a vendor hit an org-wide SPENDING CAP, and a gate that reddens every
+ * PR the moment a bill goes unpaid is a worse gate than the one it is
+ * criticising. Whether such a check belongs in the required set at all is a
+ * governance decision an owner makes in an admin console, not one this script
+ * may pre-empt by turning its own finding into a blocker.
+ *
+ * Detection is the uncontroversial half, and it is the half that was missing:
+ * nothing anywhere could previously tell "the check reported success" apart
+ * from "the check did anything".
+ *
+ * This list is checked BEFORE `ALWAYS_BLOCKING` and before the enforcement
+ * mode, so deleting the `enforcement` key cannot silently arm it.
+ */
+export const NEVER_BLOCKING = Object.freeze([
+  VIOLATIONS.vacuous,
+  VIOLATIONS.unproven,
+]);
+
+/**
+ * Reads `--name=value` or `--name value` out of argv.
+ *
+ * Returns `undefined` for an absent flag and for `--name` with no value, so a
+ * typo cannot be read as an empty PR number and silently examine nothing.
+ *
+ * @param {ReadonlyArray<string>} argv - CLI arguments
+ * @param {string} name - The flag, including its leading dashes
+ * @returns {string|undefined} The value, or undefined
+ */
+export function readFlagValue(argv, name) {
+  const inline = argv.find(arg => arg.startsWith(`${name}=`));
+  if (inline !== undefined) {
+    const value = inline.slice(name.length + 1).trim();
+    return value === "" ? undefined : value;
+  }
+  const at = argv.indexOf(name);
+  if (at === -1) return undefined;
+  const next = argv[at + 1];
+  return next === undefined || next.startsWith("--") ? undefined : next;
+}
+
 /**
  * True when a line is a whole-line YAML comment.
  *
@@ -403,6 +564,30 @@ export function loadDeclaration(rootDir) {
       );
     }
   }
+
+  // Same reasoning for the vacuity declarations: a non-object entry would read
+  // as "declared" and then yield an empty vocabulary, quietly examining the
+  // check against defaults the author thought they had overridden.
+  for (const [name, entry] of Object.entries(
+    declaration.evidence_bearing_checks ?? {}
+  )) {
+    if (typeof entry !== "object" || entry === null || Array.isArray(entry)) {
+      throw new Error(
+        `check-skipped-required-checks: the declaration for \`${name}\` in \`evidence_bearing_checks\` must be an object — use \`{}\` to accept the shipped description vocabulary.`
+      );
+    }
+    for (const list of ["proof", "no_work"]) {
+      if (entry[list] === undefined) continue;
+      if (
+        !Array.isArray(entry[list]) ||
+        entry[list].some(phrase => typeof phrase !== "string")
+      ) {
+        throw new Error(
+          `check-skipped-required-checks: \`evidence_bearing_checks.${name}.${list}\` must be an array of description strings.`
+        );
+      }
+    }
+  }
   return declaration;
 }
 
@@ -616,6 +801,184 @@ export function evaluateSkippedRequiredChecks(
   return { violations, checked: skipped.length };
 }
 
+/**
+ * Decides whether a check's description proves the check did any work.
+ *
+ * @param {string|undefined} description - The check's description, verbatim
+ * @param {{proof?: ReadonlyArray<string>, no_work?: ReadonlyArray<string>}} [vocabulary] -
+ *   Per-check additions. Merged WITH the shipped defaults rather than replacing
+ *   them, so a repository naming one extra proof phrase does not silently lose
+ *   the no-work list that catches the measured defect.
+ * @returns {string} One of `DESCRIPTION_VERDICTS`
+ */
+export function classifyCheckDescription(description, vocabulary = {}) {
+  const text = (description ?? "").trim().toLowerCase();
+  if (text === "") return DESCRIPTION_VERDICTS.unproven;
+
+  // No-work is tested FIRST. The lists are asserted non-overlapping in the
+  // suite, so order cannot change a verdict today — testing the denying rule
+  // first means a future overlap fails safe (denied) rather than granting
+  // credit, which is the direction that matters.
+  const noWork = [
+    ...REVIEW_DESCRIPTION_DEFAULTS.no_work,
+    ...(vocabulary.no_work ?? []),
+  ];
+  if (noWork.some(phrase => text.includes(phrase.trim().toLowerCase()))) {
+    return DESCRIPTION_VERDICTS.noWork;
+  }
+
+  const proof = [
+    ...REVIEW_DESCRIPTION_DEFAULTS.proof,
+    ...(vocabulary.proof ?? []),
+  ];
+  if (proof.some(phrase => text === phrase.trim().toLowerCase())) {
+    return DESCRIPTION_VERDICTS.proved;
+  }
+  return DESCRIPTION_VERDICTS.unproven;
+}
+
+/**
+ * Reports every declared evidence-bearing check that satisfied without proving
+ * it did work.
+ *
+ * A check is examined only when the repository named it in
+ * `evidence_bearing_checks` — matched by EXACT name, like every other
+ * comparison in this file. Most CI jobs ship an empty description, so
+ * flagging them all would bury the one finding that matters, and the obvious
+ * fix for a noisy guard is to delete it.
+ *
+ * Four outcomes per declared check:
+ *
+ *  - Green + a `proof` description → nothing. This is the case the whole
+ *    machine exists to reach.
+ *  - Green + a `no_work` description → `vacuous_required_check`. The measured
+ *    #2483/#2484 defect.
+ *  - Green + anything else → `unproven_required_check`. Not an accusation: a
+ *    statement that this run produced no evidence either way.
+ *  - Absent entirely → `unproven_required_check`. Measured on #2493/#2491/
+ *    #2488, where the bot posted no context at all; "no unresolved review
+ *    threads" there means nobody looked, not that nothing was wrong.
+ *
+ * A RED check is deliberately ignored. Required-and-red is the loud case and
+ * needs no help from here; reporting it too would make this arm indistinguish-
+ * able from ordinary CI noise.
+ *
+ * `required_contexts` changes only the WORDING — whether branch protection
+ * actually recorded this hollow green as a satisfied gate. When that snapshot
+ * is untrusted the finding still stands; the guard just declines to claim
+ * required-ness it has not transcribed.
+ *
+ * @param {object} declaration - The per-repo declaration
+ * @param {ReadonlyArray<{name: string, state: string, bucket?: string, description?: string}>} checks -
+ *   Checks as `gh pr checks --json name,state,bucket,description` returns them
+ * @param {{trustRequiredContexts?: boolean}} [options] - Set
+ *   `trustRequiredContexts: false` to stop asserting whether a check is required
+ * @returns {{violations: object[], checked: number}} Violations and how many declared checks were examined
+ */
+export function evaluateVacuousChecks(declaration, checks, options = {}) {
+  const declared = declaration.evidence_bearing_checks ?? {};
+  const trustRequired = options.trustRequiredContexts !== false;
+  const required = new Set(declaration.required_contexts ?? []);
+  const violations = [];
+  let checked = 0;
+
+  for (const [name, entry] of Object.entries(declared)) {
+    checked += 1;
+    const vocabulary = typeof entry === "object" && entry !== null ? entry : {};
+    const found = checks.find(check => check.name === name);
+
+    if (found === undefined) {
+      violations.push({
+        kind: VIOLATIONS.unproven,
+        token: name,
+        message: `\`${name}\` is declared evidence-bearing but did not report on this pull request at all. A report of "no unresolved review threads" from this PR means NOBODY LOOKED, not that nothing was wrong — say which one you observed. (If the context was renamed, fix \`evidence_bearing_checks\`; names are compared byte for byte.)`,
+      });
+      continue;
+    }
+
+    const state = String(found.state ?? "").toUpperCase();
+    if (state === "FAILURE" || state === "ERROR") continue;
+
+    const verdict = classifyCheckDescription(found.description, vocabulary);
+    if (verdict === DESCRIPTION_VERDICTS.proved && state === "SUCCESS") {
+      continue;
+    }
+
+    const requiredNote = !trustRequired
+      ? " Whether it is ruleset-required is NOT KNOWN here — `required_contexts` has not been transcribed, so this cannot say what the merge gate recorded."
+      : required.has(name)
+        ? " This context IS ruleset-required, so branch protection recorded a satisfied review gate for a review that did not happen."
+        : " This context is not in `required_contexts`, so no merge gate was falsified — but nothing reviewed this either.";
+
+    violations.push(
+      verdict === DESCRIPTION_VERDICTS.noWork && state === "SUCCESS"
+        ? {
+            kind: VIOLATIONS.vacuous,
+            token: name,
+            contexts: [name],
+            message: `\`${name}\` reported ${state} with the description ${JSON.stringify(found.description ?? "")}, which says it DID NO WORK.${requiredNote} \`gh pr checks\` prints \`pass\` for this exactly as it does for a real review — the description is the only thing that tells them apart. Treat this PR as UNREVIEWED.`,
+          }
+        : {
+            kind: VIOLATIONS.unproven,
+            token: name,
+            message: `\`${name}\` reported ${state} with the description ${JSON.stringify(found.description ?? "")}, which proves neither that it reviewed anything nor that it did not.${requiredNote} Read the check itself before treating this PR as reviewed, or add the phrase to \`evidence_bearing_checks.${name}.proof\` once you have confirmed what it means.`,
+          }
+    );
+  }
+
+  return { violations, checked };
+}
+
+/**
+ * Reads one pull request's checks, descriptions included.
+ *
+ * `--json` is what makes this usable: the plain `gh pr checks` table is the
+ * human triage, and the description column is the load-bearing one, but only
+ * the JSON form survives being parsed. Both CheckRuns and legacy commit
+ * StatusContexts come back through this single call — CodeRabbit posts the
+ * latter, which `gh pr view --json statusCheckRollup` returns WITHOUT a
+ * description, so that route cannot see the defect at all.
+ *
+ * A non-zero exit is expected and ignored: `gh pr checks` exits 8 while checks
+ * are pending and 1 when any check failed, and both are perfectly readable
+ * states for this arm. Only unparseable output is an error.
+ *
+ * @param {string|number} pr - Pull request number or URL
+ * @param {string} [repo] - `OWNER/NAME`; defaults to the current repository
+ * @returns {Array<{name: string, state: string, bucket?: string, description?: string}>} The checks
+ * @throws {Error} When `gh` is unavailable or its output cannot be parsed
+ */
+export function fetchPullRequestChecks(pr, repo) {
+  const args = [
+    "pr",
+    "checks",
+    String(pr),
+    "--json",
+    "name,state,bucket,description",
+  ];
+  if (repo) args.push("--repo", repo);
+  let raw;
+  try {
+    raw = execFileSync("gh", args, { encoding: "utf8" });
+  } catch (error) {
+    raw = typeof error?.stdout === "string" ? error.stdout : "";
+    if (raw.trim() === "") {
+      throw new Error(
+        `check-skipped-required-checks: could not read checks for PR ${pr}${repo ? ` in ${repo}` : ""} — ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+  }
+  try {
+    const parsed = JSON.parse(raw);
+    if (!Array.isArray(parsed)) throw new TypeError("not an array");
+    return parsed;
+  } catch (error) {
+    throw new Error(
+      `check-skipped-required-checks: \`gh pr checks --json\` returned output this cannot parse (${error instanceof Error ? error.message : String(error)}). Refusing to report "nothing vacuous" from output nobody read.`
+    );
+  }
+}
+
 /**
  * Fetches the live required contexts for every declared ruleset.
  *
@@ -693,6 +1056,7 @@ export function runGuard(argv) {
   const positional = argv.filter(arg => !arg.startsWith("--"));
   const rootDir = positional[0] ?? process.cwd();
   const declaration = loadDeclaration(rootDir);
+  const pr = readFlagValue(argv, "--pr");
   const collected = collectSkipJobTokens(rootDir, declaration.workflows);
   const remote = argv.includes("--remote");
   const live = remote
@@ -714,6 +1078,21 @@ export function runGuard(argv) {
       ...compareRulesetBaseline(declaration.required_contexts, live)
     );
   }
+
+  // The vacuity arm is layered ON TOP of the offline run rather than replacing
+  // it: it is a third variant of one family, so it belongs in one report. Its
+  // findings are `NEVER_BLOCKING`, so adding them cannot change the exit code
+  // the offline arm would have produced on its own.
+  const vacuity =
+    pr === undefined
+      ? undefined
+      : evaluateVacuousChecks(
+          declaration,
+          fetchPullRequestChecks(pr, readFlagValue(argv, "--repo")),
+          { trustRequiredContexts: trust.trusted }
+        );
+  if (vacuity !== undefined) violations.push(...vacuity.violations);
+
   return {
     violations,
     checked: result.checked,
@@ -721,6 +1100,8 @@ export function runGuard(argv) {
     enforcement: declaration.enforcement ?? "error",
     trust,
     recipe: transcriptionRecipe(declaration),
+    pr,
+    evidenceChecked: vacuity?.checked ?? 0,
   };
 }
 
@@ -774,9 +1155,10 @@ function main(argv) {
    * @returns {boolean} True when it blocks
    */
   const blocks = violation =>
-    !warnOnly || ALWAYS_BLOCKING.includes(violation.kind);
+    !NEVER_BLOCKING.includes(violation.kind) &&
+    (!warnOnly || ALWAYS_BLOCKING.includes(violation.kind));
   const blocking = result.violations.filter(blocks);
-  const lines = ["## 🔒 Skipped required checks", ""];
+  const lines = ["## 🔒 Required checks that prove nothing", ""];
 
   // The refusal comes FIRST and replaces the verdict. Printing "✅ none
   // silences a required check" from a snapshot nobody transcribed is the one
@@ -803,7 +1185,12 @@ function main(argv) {
   if (result.violations.length === 0) {
     if (result.trust.trusted) {
       lines.push(
-        `✅ ${result.checked} \`skip_jobs\` token(s) examined; none silences a ruleset-required status check.`
+        `✅ ${result.checked} \`skip_jobs\` token(s) examined; none silences a ruleset-required status check.`,
+        ...(result.pr === undefined
+          ? []
+          : [
+              `✅ ${result.evidenceChecked} evidence-bearing check(s) examined on PR #${result.pr}; each proved it did work.`,
+            ])
       );
     } else {
       lines.push(
@@ -827,6 +1214,16 @@ function main(argv) {
         `This declaration sets \`"enforcement": "warn"\`, so everything above except a proven false green (\`${VIOLATIONS.suppressesRequired}\`) is reported without failing the build. Review each finding, fix or declare it, then delete the \`enforcement\` key so this guard can block.`
       );
     }
+    if (
+      result.violations.some(violation =>
+        NEVER_BLOCKING.includes(violation.kind)
+      )
+    ) {
+      lines.push(
+        "",
+        `\`${VIOLATIONS.vacuous}\` and \`${VIOLATIONS.unproven}\` are REPORT-ONLY in every enforcement mode — they never fail a build. A required check can go hollow because a vendor hit an org-wide spending cap, and reddening every PR on a billing state would be a worse gate than the one being criticised. What they change is what you may CLAIM: a PR carrying either finding has not been shown to be reviewed, so do not record it as reviewed.`
+      );
+    }
   }
   const report = `${lines.join("\n")}\n`;
   process.stdout.write(report);