@codyswann/lisa 4.33.4 → 4.33.6

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

@@ -487,6 +487,40 @@ export const SETTLE_INTERVAL_SECONDS = 15;
 /** Enables the blocking review-evidence policy. */
 const REQUIRE_REVIEW_EVIDENCE_FLAG = "--require-review-evidence";
 
+/**
+ * Selects how many recently merged pull requests the waive-rate sample reads.
+ *
+ * Zero — the shipped default — disables the sample entirely, so no repository
+ * acquires a network read it did not ask for. The workflow that ships with Lisa
+ * passes a value, because the number is the point: `.github/workflows/
+ * review-evidence.yml` recorded "of the last 40 merged pull requests, 39 waive"
+ * in a COMMENT, where it changed nothing for eight months. A rate that an
+ * operator reads at merge time is a different artefact from a rate somebody
+ * once measured.
+ */
+const WAIVE_RATE_SAMPLE_FLAG = "--waive-rate-sample";
+
+/**
+ * The one call the waive-rate sample makes.
+ *
+ * Kept beside the flag rather than inline in the reader so the network shape is
+ * visible without reading a function: merged pull requests, newest first, each
+ * with its head commit's rollup contexts. `StatusContext` and `CheckRun` are
+ * both selected because a review bot may report as either and the description —
+ * `description` on one, `title` on the other — is the only field that separates
+ * a review from a waiver.
+ */
+const RECENT_MERGED_CHECKS_QUERY = [
+  "query($owner:String!,$name:String!,$limit:Int!){",
+  "repository(owner:$owner,name:$name){",
+  "pullRequests(states:MERGED,first:$limit,orderBy:{field:UPDATED_AT,direction:DESC}){",
+  "nodes{number commits(last:1){nodes{commit{statusCheckRollup{contexts(last:100){",
+  "nodes{__typename",
+  " ... on StatusContext{context state description}",
+  " ... on CheckRun{name conclusion title}",
+  "}}}}}}}}}}",
+].join("");
+
 /**
  * The flag that used to select the live-ruleset drift mode, retired with it.
  *
@@ -1284,13 +1318,18 @@ export function reviewGateState(reading, vocabulary = {}) {
  * @param {object} declaration - The per-repo declaration
  * @param {ReadonlyArray<{name: string, state: string, description?: string}>} checks - The checks
  * @param {{headSha?: string}} [options] - `headSha` is cited in every finding
- * @returns {{violations: object[], states: Record<string, string>, checked: number}} Findings, per-check state, and how many were examined
+ * @returns {{violations: object[], states: Record<string, string>, descriptions: Record<string, string>, checked: number}} Findings, per-check state, the description each verdict was read from, and how many were examined
  */
 export function evaluateReviewGate(declaration, checks, options = {}) {
   const declared = declaration.evidence_bearing_checks ?? {};
   const at = citeHeadSha(options.headSha);
   const violations = [];
   const states = {};
+  // Carried out with the states because the RENDERED verdict quotes it. A title
+  // that said only "WAIVED" would tell an operator that something was waived
+  // and not which vendor sentence did the waiving, which is the fact that says
+  // whether to wait for the entitlement or merge on the waiver.
+  const descriptions = {};
   let checked = 0;
 
   for (const [name, entry] of Object.entries(declared)) {
@@ -1308,6 +1347,13 @@ export function evaluateReviewGate(declaration, checks, options = {}) {
       vocabulary
     );
     states[name] = verdict.state;
+    // Assigned ONLY when the check reported. An absent check with a `""`
+    // description entry renders as `CodeRabbit reported ""` — a sentence that
+    // says it reported. MEASURED on this fix's own first commit, where the
+    // published verdict read exactly that. Absence is not a quiet report, and
+    // the whole file turns on the two being different facts.
+    if (found !== undefined)
+      descriptions[name] = String(found.description ?? "");
     if (verdict.state === REVIEW_GATE_STATES.satisfied) continue;
     violations.push({
       kind:
@@ -1320,7 +1366,295 @@ export function evaluateReviewGate(declaration, checks, options = {}) {
     });
   }
 
-  return { violations, states, checked };
+  return { violations, states, descriptions, checked };
+}
+
+/**
+ * The check-run conclusion each review-gate verdict is published under.
+ *
+ * THIS IS THE WHOLE POINT OF #3639. Before this map existed the gate's three
+ * verdicts all reached a merge decision through the same rendering: the job
+ * exited 0 for `satisfied` AND for `waived`, so `gh pr checks` printed
+ *
+ *     🕵️ Did the required review checks do any work?   pass
+ *
+ * for a pull request nothing had read, character for character what it prints
+ * for one a reviewer completed. The distinction lived in the run log, and the
+ * file's own header had already measured how little that is worth: of the last
+ * 40 merged pull requests, 39 waived. A waiver that applies to 39 of 40 merges
+ * is the default path, and the default path rendering as the success path
+ * reproduces — on the guard's own green — the exact indistinguishability the
+ * guard exists to remove.
+ *
+ * `neutral` is the mechanism because it is the one conclusion that is NOT a
+ * pass and NOT a failure. `gh pr checks` buckets NEUTRAL as `skipping`, so the
+ * row reads differently at a glance, while contributing neither a failure to
+ * gh's exit code nor a satisfied context to branch protection. The waiver keeps
+ * its rationale — a pull request author cannot fix a vendor's billing state,
+ * and reddening every PR on it would be a worse gate — and loses only its
+ * disguise.
+ */
+export const REVIEW_VERDICT_CONCLUSIONS = Object.freeze({
+  satisfied: "success",
+  waived: "neutral",
+  unsatisfied: "failure",
+  uninspected: "failure",
+});
+
+/** GitHub truncates a check-run output title past this many characters. */
+export const REVIEW_VERDICT_TITLE_LIMIT = 255;
+
+/**
+ * Flattens a title to one line and fits it in a check-run output title.
+ *
+ * Single-line is a correctness requirement, not tidiness: this string is
+ * written to `$GITHUB_OUTPUT` as `key=value`, where a newline in the value ends
+ * the assignment and the remainder is parsed as further output keys. A vendor
+ * description is arbitrary text from outside this repository.
+ *
+ * @param {string} text - The composed title
+ * @returns {string} One line, at most {@link REVIEW_VERDICT_TITLE_LIMIT} chars
+ */
+function fitTitle(text) {
+  const flat = String(text).replace(/\s+/gu, " ").trim();
+  return flat.length <= REVIEW_VERDICT_TITLE_LIMIT
+    ? flat
+    : `${flat.slice(0, REVIEW_VERDICT_TITLE_LIMIT - 1)}…`;
+}
+
+/**
+ * The waive-rate sentence appended to a verdict title, or nothing.
+ *
+ * @param {{waived: number, sampled: number}|undefined} rate - A sampled tally
+ * @returns {string} The sentence, or an empty string when nothing was sampled
+ */
+function waiveRateSuffix(rate) {
+  return rate === undefined || rate.sampled === 0
+    ? ""
+    : ` · waived on ${rate.waived} of the last ${rate.sampled} merged pull requests`;
+}
+
+/**
+ * Renders one merge-time verdict for every declared evidence-bearing check.
+ *
+ * Worst-wins across the declared checks, in the order `unsatisfied` > `waived`
+ * > `satisfied`. One waived check among four satisfied ones still means this
+ * pull request has an unreviewed arm, and a verdict that averaged them would be
+ * the summary that hides the finding.
+ *
+ * Pure, and deliberately separate from the publishing step, so the property
+ * that matters — a waiver and a satisfaction never render the same — is
+ * testable without a GitHub API.
+ *
+ * @param {{states?: Record<string, string>, descriptions?: Record<string, string>, refusal?: {kind: string}|null, waiveRate?: {waived: number, sampled: number}}} reading -
+ *   The gate's per-check states, the descriptions they were read from, any
+ *   refusal, and an optional sampled waive rate
+ * @returns {{verdict: string, conclusion: string, title: string}} What to publish
+ */
+export function reviewGateVerdict(reading = {}) {
+  const states = reading.states ?? {};
+  const descriptions = reading.descriptions ?? {};
+  const names = Object.keys(states);
+  const suffix = waiveRateSuffix(reading.waiveRate);
+
+  if (reading.refusal || names.length === 0) {
+    return {
+      verdict: "uninspected",
+      conclusion: REVIEW_VERDICT_CONCLUSIONS.uninspected,
+      title: fitTitle(
+        `NOT INSPECTED — no review evidence was read${reading.refusal ? ` (${reading.refusal.kind})` : ""}. NOBODY LOOKED is not the same fact as a clean review.`
+      ),
+    };
+  }
+
+  /**
+   * Names one check alongside the exact description its verdict was read from.
+   *
+   * A check with no entry never REPORTED, and says so. `reported ""` for a
+   * check that posted nothing is the one phrasing this whole file exists to
+   * refuse: it makes absence look like a quiet answer.
+   *
+   * @param {string} name - The declared check name
+   * @returns {string} `<name> reported "<description>"`, or that it posted none
+   */
+  const quote = name =>
+    Object.hasOwn(descriptions, name)
+      ? `${name} reported ${JSON.stringify(descriptions[name])}`
+      : `${name} posted NO review status at all`;
+
+  const unsatisfied = names.filter(
+    name => states[name] === REVIEW_GATE_STATES.unsatisfied
+  );
+  if (unsatisfied.length > 0) {
+    return {
+      verdict: REVIEW_GATE_STATES.unsatisfied,
+      conclusion: REVIEW_VERDICT_CONCLUSIONS.unsatisfied,
+      title: fitTitle(
+        `UNREVIEWED — review evidence unsatisfied: ${unsatisfied.map(quote).join("; ")}${suffix}`
+      ),
+    };
+  }
+
+  const waived = names.filter(
+    name => states[name] === REVIEW_GATE_STATES.waived
+  );
+  if (waived.length > 0) {
+    return {
+      verdict: REVIEW_GATE_STATES.waived,
+      conclusion: REVIEW_VERDICT_CONCLUSIONS.waived,
+      title: fitTitle(
+        `WAIVED — this pull request is UNREVIEWED and merging it is a decision taken on that basis: ${waived.map(quote).join("; ")}${suffix}`
+      ),
+    };
+  }
+
+  return {
+    verdict: REVIEW_GATE_STATES.satisfied,
+    conclusion: REVIEW_VERDICT_CONCLUSIONS.satisfied,
+    title: fitTitle(`REVIEWED — ${names.map(quote).join("; ")}${suffix}`),
+  };
+}
+
+/**
+ * Counts how a sample of pull requests ended up, worst-wins per pull request.
+ *
+ * A pull request whose declared checks produced no state at all is not counted
+ * as reviewed OR waived — it is not counted. A denominator that quietly absorbs
+ * unreadable pull requests reports a lower waive rate than the truth, which is
+ * the direction that makes the number reassuring rather than useful.
+ *
+ * @param {ReadonlyArray<Record<string, string>>} samples - One states map per pull request
+ * @returns {{sampled: number, waived: number, satisfied: number, unsatisfied: number}} The tally
+ */
+export function summarizeWaiveRate(samples) {
+  const tally = { sampled: 0, waived: 0, satisfied: 0, unsatisfied: 0 };
+  for (const states of samples) {
+    const values = Object.values(states ?? {});
+    if (values.length === 0) continue;
+    tally.sampled += 1;
+    if (values.includes(REVIEW_GATE_STATES.unsatisfied)) tally.unsatisfied += 1;
+    else if (values.includes(REVIEW_GATE_STATES.waived)) tally.waived += 1;
+    else tally.satisfied += 1;
+  }
+  return tally;
+}
+
+/**
+ * Reads the declared evidence-bearing rows for recently merged pull requests.
+ *
+ * ONE GraphQL call, not one REST call per pull request. A per-PR loop is ~2N
+ * network reads inside a job that is already spending five minutes waiting for
+ * a review bot to settle, and a sampler that can time the job out would be
+ * deleted rather than read.
+ *
+ * `orderBy: UPDATED_AT` rather than a merge timestamp, and the difference is
+ * worth naming: this is "recently touched merged pull requests", a proxy for
+ * "recently merged" that the single-call shape buys. The number it produces is
+ * an order-of-magnitude reading of how often the waiver is the path — which is
+ * what an operator needs — not an audit figure.
+ *
+ * @param {number} limit - How many merged pull requests to read
+ * @param {string} [repo] - `OWNER/NAME`; defaults to the current repository
+ * @returns {Array<Array<{name: string, state: string, description: string}>>} Rows per pull request
+ * @throws {Error} When the slug cannot be resolved or `gh` cannot answer
+ */
+export function fetchRecentMergedChecks(limit, repo) {
+  const slug = resolveRepoSlug(repo);
+  if (slug === undefined) {
+    throw new Error(
+      "check-skipped-required-checks: the waive-rate sample needs an OWNER/NAME. Pass `--repo=OWNER/NAME`, or set GITHUB_REPOSITORY."
+    );
+  }
+  const [owner, name] = slug.split("/");
+  const raw = boundedExecFileSync(
+    "gh",
+    [
+      "api",
+      "graphql",
+      "-f",
+      `query=${RECENT_MERGED_CHECKS_QUERY}`,
+      "-F",
+      `owner=${owner}`,
+      "-F",
+      `name=${name}`,
+      "-F",
+      `limit=${limit}`,
+    ],
+    { encoding: "utf8" }
+  );
+  const nodes = JSON.parse(raw)?.data?.repository?.pullRequests?.nodes ?? [];
+  return nodes.map(node =>
+    (
+      node?.commits?.nodes?.[0]?.commit?.statusCheckRollup?.contexts?.nodes ??
+      []
+    ).map(context =>
+      context?.__typename === "CheckRun"
+        ? normalizeCheckRow(context.name, context.conclusion, context.title)
+        : normalizeCheckRow(
+            context?.context,
+            context?.state,
+            context?.description
+          )
+    )
+  );
+}
+
+/**
+ * Samples how often the review gate waives, best-effort and never fatal.
+ *
+ * A failed sample must never change the verdict. The rate is CONTEXT for a
+ * decision the gate has already made from this pull request's own evidence, so
+ * an unreachable API costs an operator one sentence rather than a red build —
+ * and the absent sentence is the honest rendering of "not measured", which is
+ * what the caller prints in its place.
+ *
+ * @param {object} declaration - The per-repo declaration
+ * @param {number} limit - How many merged pull requests to read; 0 disables
+ * @param {string} [repo] - `OWNER/NAME`; defaults to the current repository
+ * @param {(limit: number, repo?: string) => Array<Array<object>>} [fetch] - Injection seam
+ * @returns {{sampled: number, waived: number, satisfied: number, unsatisfied: number}|undefined} The tally, or undefined when it could not be taken
+ */
+export function sampleWaiveRate(declaration, limit, repo, fetch) {
+  if (!Number.isInteger(limit) || limit <= 0) return undefined;
+  try {
+    const perPullRequest = (fetch ?? fetchRecentMergedChecks)(limit, repo);
+    return summarizeWaiveRate(
+      perPullRequest.map(
+        checks => evaluateReviewGate(declaration, checks).states
+      )
+    );
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Publishes the verdict where a workflow step can read it.
+ *
+ * `$GITHUB_OUTPUT` rather than stdout because the consumer is the next step in
+ * the job, which turns it into a check run — the surface a merge decision
+ * actually consults. Best-effort for the same reason the step summary is:
+ * losing the rendering must not invert the exit code the guard worked to earn.
+ *
+ * @param {{verdict: string, conclusion: string, title: string}} verdict - What to publish
+ * @param {NodeJS.ProcessEnv} [env] - Environment, injectable for tests
+ * @returns {boolean} True when the outputs were written
+ */
+export function writeVerdictOutputs(verdict, env = process.env) {
+  const target = env.GITHUB_OUTPUT;
+  if (target === undefined || target === "") return false;
+  try {
+    appendFileSync(
+      target,
+      `review_evidence_verdict=${verdict.verdict}\nreview_evidence_conclusion=${verdict.conclusion}\nreview_evidence_title=${verdict.title}\n`
+    );
+    return true;
+  } catch (error) {
+    console.error(
+      `[skipped-required-checks] review verdict outputs not written: ${error.message}`
+    );
+    return false;
+  }
 }
 
 /**
@@ -1917,6 +2251,26 @@ export function vacuityRefusal(input) {
   return null;
 }
 
+/**
+ * Reads a `--name=<integer>` flag, falling back when absent or unreadable.
+ *
+ * Separate from the seconds reader because the fallback for an unreadable value
+ * differs in kind: a bad timeout should still wait, while a bad sample size must
+ * NOT silently become the shipped default and start making network calls a
+ * caller did not ask for. Both clamp at zero.
+ *
+ * @param {ReadonlyArray<string>} argv - CLI arguments
+ * @param {string} name - The flag, including its leading dashes
+ * @param {number} fallback - Value to use when the flag is absent or unreadable
+ * @returns {number} A non-negative integer
+ */
+function readIntegerFlag(argv, name, fallback) {
+  const raw = readFlagValue(argv, name);
+  if (raw === undefined) return fallback;
+  const value = Number(raw);
+  return Number.isInteger(value) && value >= 0 ? value : fallback;
+}
+
 /**
  * Reads a `--name=<seconds>` flag, falling back when absent or unreadable.
  *
@@ -1968,8 +2322,19 @@ export function inspectVacuity(argv, declaration, options = {}) {
     violations: [],
     settled: false,
   };
+  /**
+   * Attaches the published verdict to a refusal, which must not render as green.
+   *
+   * @param {{kind: string, reason: string}|null} refusal - Why nothing was read
+   * @returns {object} The refusal result, verdict included
+   */
+  const refused = refusal => ({
+    ...empty,
+    refusal,
+    verdict: reviewGateVerdict({ refusal }),
+  });
   if (pr === undefined) {
-    return { ...empty, refusal: vacuityRefusal({ declaration, pr }) };
+    return refused(vacuityRefusal({ declaration, pr }));
   }
 
   const repo = readFlagValue(argv, "--repo");
@@ -1992,16 +2357,15 @@ export function inspectVacuity(argv, declaration, options = {}) {
       headSha: options.headSha,
     });
   } catch (error) {
-    return { ...empty, refusal: vacuityRefusal({ declaration, pr, error }) };
+    return refused(vacuityRefusal({ declaration, pr, error }));
   }
 
   const refusal = vacuityRefusal({ declaration, pr, checks: read.checks });
   if (refusal !== null) {
     return {
-      ...empty,
+      ...refused(refusal),
       headSha: read.headSha,
       settled: read.settled,
-      refusal,
     };
   }
   const evaluated = evaluateVacuousChecks(declaration, read.checks, {
@@ -2015,6 +2379,20 @@ export function inspectVacuity(argv, declaration, options = {}) {
   const gate = evaluateReviewGate(declaration, read.checks, {
     headSha: read.headSha,
   });
+  // Sampled ONLY when this pull request is itself waived. The rate answers
+  // "is this the exception or the rule?", a question that only arises once a
+  // waiver is on the table, and every other run keeps the sampler's network
+  // call — and its failure modes — out of the job entirely.
+  const waiveRate = Object.values(gate.states).includes(
+    REVIEW_GATE_STATES.waived
+  )
+    ? sampleWaiveRate(
+        declaration,
+        readIntegerFlag(argv, WAIVE_RATE_SAMPLE_FLAG, 0),
+        repo,
+        options.sampleChecks
+      )
+    : undefined;
   return {
     pr,
     prSource: source,
@@ -2022,6 +2400,13 @@ export function inspectVacuity(argv, declaration, options = {}) {
     checked: evaluated.checked,
     violations: [...evaluated.violations, ...gate.violations],
     gateStates: gate.states,
+    gateDescriptions: gate.descriptions,
+    waiveRate,
+    verdict: reviewGateVerdict({
+      states: gate.states,
+      descriptions: gate.descriptions,
+      waiveRate,
+    }),
     settled: read.settled,
     refusal: null,
   };
@@ -2081,6 +2466,8 @@ export function runGuard(argv, options = {}) {
     recipe: transcriptionRecipe(declaration),
     pr: vacuity?.pr,
     evidenceChecked: vacuity?.checked ?? 0,
+    verdict: vacuity?.verdict,
+    waiveRate: vacuity?.waiveRate,
     vacuity,
   };
 }
@@ -2141,6 +2528,11 @@ function main(argv) {
       : !warnOnly || ALWAYS_BLOCKING.includes(violation.kind);
   };
   const blocking = result.violations.filter(blocks);
+  // Published BEFORE the report and before the exit code, because it is the only
+  // artefact of this run that a merge decision reads. A verdict computed after a
+  // `return` on some branch is a verdict that exists on the happy path only.
+  const verdict = result.verdict;
+  if (verdict !== undefined) writeVerdictOutputs(verdict);
   const refusal = result.vacuity?.refusal ?? null;
   const refusalBlocks =
     refusal !== null && (!warnOnly || requireReviewEvidence);
@@ -2169,6 +2561,22 @@ function main(argv) {
 
   const lines = ["## 🔒 Required checks that prove nothing", ""];
 
+  // The verdict is the FIRST line of the report and not a footnote, and it is
+  // the same string published to the check run, so the two surfaces cannot
+  // drift into disagreeing about what this run concluded.
+  if (verdict !== undefined) {
+    lines.push(
+      `**${verdict.title}**`,
+      "",
+      `Published as check-run conclusion \`${verdict.conclusion}\`. A \`neutral\` conclusion is how a WAIVED pull request is kept out of the shape a satisfied one prints — the waiver still blocks nothing, and it no longer looks like a review.`,
+      "",
+      result.waiveRate === undefined
+        ? "The waive rate over recently merged pull requests was NOT sampled on this run, so no rate is claimed here."
+        : `Recently merged pull requests sampled: ${result.waiveRate.sampled} — ${result.waiveRate.satisfied} reviewed, ${result.waiveRate.waived} waived, ${result.waiveRate.unsatisfied} unsatisfied.`,
+      ""
+    );
+  }
+
   // The refusal comes FIRST and replaces the verdict. Printing "✅ none
   // silences a required check" from a snapshot nobody transcribed is the one
   // outcome that is worse than never running: it is a confident wrong answer,

package/typescript/create-only/.github/workflows/review-evidence.yml

@@ -30,6 +30,25 @@
 # `Review skipped: manual review required for this OSS repository`. They stay
 # loud and nonblocking because a pull request author cannot fix the entitlement.
 #
+# AND "LOUD" IS A RENDERING, NOT A LOG LINE (#3639). This job exits 0 for a
+# satisfied gate and 0 for a waived one, so on its own `gh pr checks` prints
+# `pass` for a pull request nothing read, character for character what it
+# prints for a reviewed one. Measured on the repository that ships this: 39 of
+# the last 40 merged pull requests waived, which makes the waiver the DEFAULT
+# path rather than an exception. The second step republishes the verdict as its
+# own check run whose conclusion the guard chose — `success` reviewed,
+# `neutral` WAIVED, `failure` unsatisfied. `neutral` blocks nothing and buckets
+# as `skipping`, so the waiver keeps its rationale and loses its disguise. Do
+# not "simplify" that step away, and do not turn the waiver into a failure:
+# a gate that reddens every pull request on a vendor's billing state gets
+# deleted, and then nothing is watching at all.
+#
+# `--waive-rate-sample=<N>` samples recently merged pull requests and reports
+# how many of them waived, in the job summary and in the verdict title. It runs
+# ONLY when this pull request is itself waived, is one GraphQL call, and is
+# best-effort: a failed sample costs one sentence, never the verdict. Omit the
+# flag to disable the sample entirely.
+#
 # A rate-limit queue may be roughly hour-long. Agentic delivery retries through
 # it, with an auditable admin-merge only at the exterior governance gate after
 # every other required check and independent review has passed.
@@ -70,7 +89,11 @@ on:
 permissions:
   contents: read
   actions: read
-  checks: read
+  # `checks: write` is what publishing the verdict needs. A check run is the
+  # only artefact that can carry a `neutral` conclusion, and `neutral` is the
+  # only rendering that is neither a pass nor a failure; a commit status has no
+  # such state, so a waiver posted that way would be a `pass` again.
+  checks: write
   statuses: read
   pull-requests: read
 
@@ -102,6 +125,7 @@ jobs:
           node-version: '22.21.1'
 
       - name: 🕵️ Refuse a required check that reviewed nothing
+        id: review_evidence
         env:
           GH_TOKEN: ${{ github.token }}
           # Absent on a `pull_request` run, where the guard reads the event
@@ -124,7 +148,58 @@ jobs:
             exit 1
           fi
           if [ -n "${VACUITY_PR:-}" ]; then
-            node scripts/check-skipped-required-checks.mjs --vacuity --require-review-evidence --pr="$VACUITY_PR"
+            node scripts/check-skipped-required-checks.mjs --vacuity --require-review-evidence --waive-rate-sample=40 --pr="$VACUITY_PR"
           else
-            node scripts/check-skipped-required-checks.mjs --vacuity --require-review-evidence
+            node scripts/check-skipped-required-checks.mjs --vacuity --require-review-evidence --waive-rate-sample=40
+          fi
+
+      # ---------------------------------------------------------------------
+      # The point of #3639: render the verdict where a merge decision reads it.
+      # ---------------------------------------------------------------------
+      # The job above exits 0 for a SATISFIED gate and 0 for a WAIVED one, so
+      # `gh pr checks` printed `pass` for a pull request nothing had read,
+      # character for character what it prints for a reviewed one. The waiver
+      # was honest in the run log and invisible at the only layer anybody
+      # consults before pressing merge; measured on this repository, 39 of the
+      # last 40 merged pull requests took that path, so the disguise was the
+      # DEFAULT rendering rather than an edge case.
+      #
+      # This step republishes the same verdict as its own check run, whose
+      # conclusion the guard chose: `success` reviewed, `neutral` WAIVED,
+      # `failure` unsatisfied. `gh pr checks` buckets NEUTRAL as `skipping`, so
+      # a waiver stops looking like a pass without acquiring the power to block
+      # — the waiver's rationale is untouched, because a pull request author
+      # still cannot fix a vendor's billing state.
+      #
+      # `continue-on-error` and `if: always()`: this is RENDERING, downstream of
+      # a verdict already reached and already exited on. A fork pull request
+      # gets a read-only token and cannot write a check run at all, and losing
+      # the rendering there must not invert the verdict above it.
+      - name: 🕵️ Publish the review verdict where a merge decision reads it
+        if: always() && steps.review_evidence.outputs.review_evidence_conclusion != ''
+        continue-on-error: true
+        env:
+          GH_TOKEN: ${{ github.token }}
+          HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+          # Empty on the `workflow_dispatch` path, where there is no
+          # `pull_request` payload to read a head SHA from. The step resolves it
+          # from the dispatched number instead, so it needs the number too.
+          VACUITY_PR: ${{ inputs.pr }}
+          VERDICT_CONCLUSION: ${{ steps.review_evidence.outputs.review_evidence_conclusion }}
+          VERDICT_TITLE: ${{ steps.review_evidence.outputs.review_evidence_title }}
+        run: |
+          set -eu
+          if [ -z "${HEAD_SHA:-}" ]; then
+            HEAD_SHA="$(gh api "repos/${GITHUB_REPOSITORY}/pulls/${VACUITY_PR}" --jq .head.sha)"
           fi
+          gh api "repos/${GITHUB_REPOSITORY}/check-runs" \
+            --method POST \
+            --field name='🕵️ Review evidence verdict' \
+            --field head_sha="$HEAD_SHA" \
+            --field status=completed \
+            --field conclusion="$VERDICT_CONCLUSION" \
+            --field output[title]="$VERDICT_TITLE" \
+            --field output[summary]="$VERDICT_TITLE
+
+          Published by the \`🕵️ Review Evidence\` workflow. A \`neutral\` conclusion here means WAIVED: a declared review check said in its own words that it could not review, this pull request is UNREVIEWED, and merging it is a decision taken on that basis. It is deliberately not a failure — a pull request author cannot fix a vendor entitlement — and deliberately not a pass." \
+            > /dev/null