@codyswann/lisa 4.33.5 → 4.33.8

package/plugins/src/base/skills/lisa-repair-intake/SKILL.md

@@ -1005,28 +1005,40 @@ is no normalized `is blocked by` field. Read the bundle, then extract blockers p
 - **Linear**: inspect the native issue **relations** from Linear MCP `get_issue` and select
   blocker relations.
 
-Then classify each blocker:
-
-- **Closed, or shipped to any environment** → **cleared**. A blocker is cleared at **any**
-  env-staged `done` role — not only the production terminal. The `done` role is configured
-  per-env as a `{dev, staging, production}` map (`config-resolution`), so `On Dev`, `On Stg`,
-  **and** production `Done` all mean the blocker's code is merged and deployed to ≥1 environment.
-  A post-build `review` role (e.g. `Code Review`) is likewise cleared — the change exists and is
-  in flight. An `is blocked by` link is a **development** dependency: it is satisfied once the
-  blocker's code is in trunk; it must NOT wait for the blocker to reach production. (This matches
-  the intake-path dependency-hold gate in `lisa-intake-explain`, which already treats
-  `code-review` / `on-dev` / `on-stg` / `done` as cleared — repair-intake must not be stricter.
-  In an env-staged workflow where `Done` means "in production", a strict production-terminal
-  check strands every dependent forever behind a blocker that is already merged and sitting at
-  `On Stg` / `On Dev`.)
-- **Open** in a pre-merge role (`ready` / `claimed` / unknown — code not yet in trunk) → **still
-  blocking**.
-- **Inaccessible** (deleted, cross-org, permission denied) → **still blocking**, unless the item
-  body or a newer human comment explicitly states the dependency is resolved.
+Then classify each blocker **by containment, per the `blocker-containment` rule** — cite that
+slug for the full contract; do not restate its resolution steps or its fail-closed table here.
+
+The one question is whether the blocker's code is on the branch **this item** will be built from:
+resolve this item's base branch from its `## Target Backend Environment` through
+`.lisa.config.json` `deploy.branches` (`derived-branch-plan`, `config-resolution` — never by
+reading a rendered `Branch Plan`), resolve the blocker's merge commit through the vendor access
+layer, and test ancestry against the remote.
+
+- **Contained** — every merged PR on the blocker is an ancestor of this item's base branch →
+  **cleared**.
+- **Not contained**, or containment **not computable** for any reason the rule enumerates (no
+  linked PR, PR not merged, blocker inaccessible, base branch underivable or absent from the
+  remote, ancestry query errored) → **still blocking**, with the rule's reason key in the run
+  record.
+- **Ships no code** — the blocker is closed as completed, positively declares
+  `Target Backend Environment: None — no runtime behavior change`, and has no merged PR →
+  **cleared** under the rule's carve-out. This is a positive determination, never an absence:
+  "no PR found" is `no-pr` and stays blocking.
+- **Human override** — an explicit human statement on this item that the dependency is satisfied
+  clears it and outranks a failed containment check. Name it in the run record.
+
+**A lifecycle status name is never the test.** `done`, `on-stg`, `on-dev` and `code-review` are
+labels that correlate with containment in a single-trunk workflow and come apart from it in a
+promotion workflow, where `main` is the trailing branch — a blocker at `On Stg` is on `staging`
+and absent from `main`, and a blocker in `Code Review` is merged to nothing. Containment gets
+both the loose and the strict failure right at once: a blocker merged into the branch this item
+builds from clears **immediately**, with no wait for production, so a dependent is never stranded
+behind work already merged where it needs it.
 
 Only re-dispatch when **every** parsed blocker is cleared. When in doubt, stay blocked — a
-false-negative (left blocked) is cheap; a false-positive (re-dispatched into a real blocker)
-wastes a build cycle.
+false-negative (left blocked) costs one cycle and is visible; a false-positive is **invisible**,
+because the item moves to `ready`, which looks exactly like a repair that worked, and the failure
+surfaces days later as work begun before its dependency existed.
 
 ### Class B — validation / quality-gate self-block
 

package/plugins/src/base/skills/lisa-ticket-triage/SKILL.md

@@ -46,7 +46,7 @@ If relevant code IS found, proceed to Phase 2.
 
 From the context bundle, evaluate relationships before analyzing this ticket in isolation:
 
-- **Open blockers (`is blocked by`)**: if any blocker is not `Done` or its linked PR is not merged, raise an ambiguity: "Blocker {KEY} is not shipped — work cannot meaningfully start." This is an automatic `BLOCKED` verdict unless the human confirms the blocker state is acceptable.
+- **Open blockers (`is blocked by`)**: clear-check each blocker **by containment, per the `blocker-containment` rule** — cite that slug for the full contract rather than restating it. A blocker is satisfied when its merged PRs are ancestors of the branch this ticket will be built from (resolved from this ticket's `## Target Backend Environment` through `.lisa.config.json` `deploy.branches`, never from a rendered `Branch Plan`), or when the rule's narrow no-code carve-out or human override applies. **`Done` is not the test** — a state name holds in a single-trunk workflow and comes apart in a promotion workflow, and requiring the production terminal strands every dependent behind work already merged where this ticket needs it. This is the same predicate the `DUPLICATE_ALREADY_FIXED` bullet below already requires ("present on the relevant base branch… never from a name/label match alone"), applied here too. For a blocker that is not contained, or where containment is not computable, raise an ambiguity naming the rule's reason key: "Blocker {KEY} is not on {BRANCH} ({REASON}) — work cannot meaningfully start." That is an automatic `BLOCKED` verdict unless the human confirms the blocker state is acceptable.
 - **Epic siblings in progress**: if a sibling under the same epic is `In Progress` / `In Review` with a different assignee and overlapping scope, raise it as an edge case in Phase 4 ("Duplicate-work risk with {KEY}").
 - **`duplicates` / `is duplicated by` links**:
   - If this ticket is a duplicate of an open canonical ticket whose fix is not yet merged into the base branch, verdict is `BLOCKED` with the recommendation to close as duplicate manually rather than implement.

package/typescript/copy-overwrite/.github/GITHUB_ACTIONS.md

@@ -45,6 +45,8 @@ For full functionality, configure the following secrets:
 |--------|---------|--------------|
 | `EXPO_TOKEN` | EAS builds and updates | Mobile deployment |
 | `SENTRY_AUTH_TOKEN` | Error tracking | Release monitoring |
+| `SENTRY_ORG` | Sentry organization slug | Release monitoring |
+| `SENTRY_PROJECT` | Sentry project slug | Release monitoring |
 | `SONAR_TOKEN` | Code quality analysis | Security scanning |
 | `SNYK_TOKEN` | Vulnerability scanning | Security scanning |
 
@@ -535,8 +537,6 @@ Variables are non-sensitive configuration values. Set them in **Settings** > **S
 | `JIRA_BASE_URL` | Jira instance base URL (enables Jira triage workflow) | `https://company.atlassian.net` |
 | `JIRA_USER_EMAIL` | Email associated with the Jira API token | `user@company.com` |
 | `JIRA_PROJECT_KEY` | Jira project key for ticket queries | `PROJ` |
-| `SENTRY_ORG` | Sentry organization slug | `my-company` |
-| `SENTRY_PROJECT` | Sentry project slug | `frontend-app` |
 
 ## External Service Setup
 

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,