From fb485f6cf513a00f7463b84875a9be932e08292c Mon Sep 17 00:00:00 2001
From: Pieter Viljoen <ptr727@users.noreply.github.com>
Date: Sun, 25 Oct 2026 18:12:10 -0700
Subject: [PATCH 1/3] Render pr_review's Digest From a Pure Leaf Module (#3493)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

## Summary

Implements #3457 (the closing keyword goes on the promotion pull
request).

- `scripts/pr_review_digest.py` is a new pure reader module. Its
`render` takes the payload, the normalized checks, the run log's
rate-limit sentence, and the seen set as arguments, and makes no call.
It imports only the other readers and the reviewer adapter, never the
gate.
- `digest` stays in `pr_review.py` as the shell that does the reads
(`full_read`, `check_nodes`, and `confirmed_quota` when a refusal is
present), so the tests that patch it there keep working.
- The `status` header is an ordered list of `(key, value)` pairs joined
by one space, a `None` value leaving the field out, so a new field is
one entry.
- The window, threads-truncated, and reviews-truncated advisory lines
print from an ordered `(value, template)` table, in the order they
printed before.
- `confirmed_quota` is now read once per digest rather than up to twice,
so `refusal=QUOTA` and the `RATE LIMIT` line can no longer disagree
across two run-log reads.
- The new module joins the readers' import guard, the whole-source
guards, and the size ceilings, and `scripts/README.md` names it.

## Verification

- Every `digest` output the existing suite produces, 256 renderings
across `tests/test_pr_review.py`, was recorded before and after the move
and compared byte for byte, identical.
- `TestDigestRenderIsPinned` pins a crowded and a quiet digest whole,
with text captured from the pre-move code.
- The full suite passes, `python -m unittest discover -s tests`, 2963
tests, 7 skipped. Ruff, mypy, and the pre-commit hook are clean.
- A local strict review ran two rounds. Round 1 raised two `introduced`
findings, the new helper's name colliding with
`pr_review_rounds.refusal_of` and the pin test's docstring claiming more
than it pins, both fixed in 023589f8. Round 2 raised none.

## Pre-existing findings, not filed

- `scripts/README.md:9`, `scripts/README.md:190`,
`scripts/pr_review.py:16`: `pre-existing`, each an older sentence over
the opt-in sentence-length check's 25 words, flagged only because its
line is in this diff.

The `comments` label is applied because four comment lines moved
verbatim from `pr_review.py` into the new module.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
---
 scripts/README.md            |   4 +-
 scripts/pr_review.py         | 263 +----------------------------
 scripts/pr_review_digest.py  | 318 +++++++++++++++++++++++++++++++++++
 tests/test_pr_review.py      | 100 ++++++++++-
 tests/test_pr_review_size.py |   1 +
 5 files changed, 422 insertions(+), 264 deletions(-)
 create mode 100644 scripts/pr_review_digest.py

diff --git a/scripts/README.md b/scripts/README.md
index 6b54bfeb..b6e3dc44 100644
--- a/scripts/README.md
+++ b/scripts/README.md
@@ -6,7 +6,7 @@ The fleet's checks and review tooling, run by hand, with the deterministic ones
 
 Python only, and standard library only, with markdown-it-py the one exception. `build_dist.py`, `canonical_review.py`, `carry.py`, `pr_review.py`, `pr_review_copilot.py`, and `pr_cleanup.py` declare it in their inline script metadata. `build_dist.py` and `carry.py` import it only on the path that reads a region, since `skills_install.py` and `handoff.py` import them under a plain `python3`. Every check script is read-only and exits non-zero on a finding. `build_dist.py`, `local_review.py`, `canonical_review.py`, `handoff.py`, and `skills_install.py` below are the exceptions, since a generator, two recorders, an installer, and the handoff chain all exist to write. `build_dist.py --check` and `skills_install.py --report` are read-only modes for CI and for asking without changing anything. `local_review.py status` and `check` answer without recording anything, but they are not read-only in that same sense: reading the working tree stages it, which writes inside `.git` and runs any `filter.*.clean` the repository configures, and only the receipt is left untouched. `canonical_review.py` reads files rather than staging them, so its `list`, `status`, `sweep`, and `report` are read-only outright, and `record` alone writes.
 
-The directory separates its kinds by name and by tree. A gate checks and exits non-zero on a finding, and its name carries a `_lint` or `_gate` suffix saying what it gates. The `prose_lint.py` and `repo_gate.py` entry points delegate to the action-owned implementations that gate this tree in CI, and `host_gate.py` gates the machine it runs on. A utility does work rather than gating and carries no suffix: `backlog_metrics.py`, `build_dist.py`, `canonical_review.py`, `handoff.py`, `local_review.py`, `pr_cleanup.py`, `pr_review.py`, `pr_review_copilot.py`, `skills_install.py`. `gh_graphql.py` is a library with no command line, the GraphQL transport and cursor walker that `backlog_metrics.py`, `handoff.py`, `pr_cleanup.py`, and `pr_review.py` import from beside them. `pr_review_checks.py` and `pr_review_rounds.py` are libraries with no command line as well. They are the pure readers `pr_review.py` imports for the head's checks and its review rounds. The unit tests live apart at the repository root under [`tests/`][tests], one `test_<script>.py` per script, driving the canonical implementations against input they must reject. The gate's two reader modules are tested through `test_pr_review.py`. A gate nobody has watched fail is a gate nobody knows works. Where a case covers a table it reads the live table rather than restating it, and each one asserts a floor on what a healthy run reaches, since a check whose scan matches nothing reports zero findings and reads exactly like a pass.
+The directory separates its kinds by name and by tree. A gate checks and exits non-zero on a finding, and its name carries a `_lint` or `_gate` suffix saying what it gates. The `prose_lint.py` and `repo_gate.py` entry points delegate to the action-owned implementations that gate this tree in CI, and `host_gate.py` gates the machine it runs on. A utility does work rather than gating and carries no suffix: `backlog_metrics.py`, `build_dist.py`, `canonical_review.py`, `handoff.py`, `local_review.py`, `pr_cleanup.py`, `pr_review.py`, `pr_review_copilot.py`, `skills_install.py`. `gh_graphql.py` is a library with no command line, the GraphQL transport and cursor walker that `backlog_metrics.py`, `handoff.py`, `pr_cleanup.py`, and `pr_review.py` import from beside them. `pr_review_checks.py`, `pr_review_rounds.py`, and `pr_review_digest.py` are libraries with no command line as well. They are the pure readers `pr_review.py` imports for the head's checks, its review rounds, and the digest rendered from both. The unit tests live apart at the repository root under [`tests/`][tests], one `test_<script>.py` per script, driving the canonical implementations against input they must reject. The gate's three reader modules are tested through `test_pr_review.py`. A gate nobody has watched fail is a gate nobody knows works. Where a case covers a table it reads the live table rather than restating it, and each one asserts a floor on what a healthy run reaches, since a check whose scan matches nothing reports zero findings and reads exactly like a pass.
 
 ```sh
 python3 tests/test_prose_lint.py
@@ -187,7 +187,7 @@ uv run --no-project --script scripts/pr_review.py attest 452 --repo ptr727/Proje
 uv run --no-project --script scripts/pr_review.py cleanup 452 --repo ptr727/ProjectTemplate
 ```
 
-**The gate and its readers are separate files.** This script holds the GraphQL and REST plumbing, the verdict, the wait loop, and the writes. The head's checks are read by `pr_review_checks.py` and its review rounds by `pr_review_rounds.py`. Both read the payload the gate already fetched, and neither makes a call or imports the gate. What a reviewer's body says is read by `pr_review_copilot.py`, whose result is a small typed reading rather than a body. The reviewer's wording has changed many times and has no programmatic API, so a change in it is a data edit in `reviewers/` plus one fixture, and never reaches the gate. A part of a head round that the reader cannot place holds the gate, `shapes=HELD` and exit `50`. A finding can sit in it where no count reaches. Its text prints under `UNPLACED ON THE HEAD`, each part cut to `EXCERPT_LINES` lines of `EXCERPT_WIDTH` characters. Beside it prints a fingerprint, the first `FINGERPRINT_HEX` hex characters of a SHA-256 over the set's text. An owner, member, or collaborator clears the hold, `shapes=ACKNOWLEDGED`, with written outcomes posted by `comment --fingerprint`. That comment carries `<!-- fleet-shape-ack: fingerprint=<fp> -->` as an HTML line of its own. A new head carrying new unplaced text has a new fingerprint and owes a new acknowledgment. A part on an earlier round prints under `REVIEWER OUTPUT NOTED` with a one-line note. So does a label nested in a list, a quote, or a placed part. It decides no exit code. `shapes=NOTED` shows only where no head hold takes the field.
+**The gate and its readers are separate files.** This script holds the GraphQL and REST plumbing, the verdict, the wait loop, and the writes. The head's checks are read by `pr_review_checks.py` and its review rounds by `pr_review_rounds.py`, and `pr_review_digest.py` renders the `status` and `wait` digest from both. Each reads the payload the gate already fetched, and none makes a call or imports the gate. The digest's header is an ordered list of fields, and its fixed advisory lines are an ordered table. What a reviewer's body says is read by `pr_review_copilot.py`, whose result is a small typed reading rather than a body. The reviewer's wording has changed many times and has no programmatic API, so a change in it is a data edit in `reviewers/` plus one fixture, and never reaches the gate. A part of a head round that the reader cannot place holds the gate, `shapes=HELD` and exit `50`. A finding can sit in it where no count reaches. Its text prints under `UNPLACED ON THE HEAD`, each part cut to `EXCERPT_LINES` lines of `EXCERPT_WIDTH` characters. Beside it prints a fingerprint, the first `FINGERPRINT_HEX` hex characters of a SHA-256 over the set's text. An owner, member, or collaborator clears the hold, `shapes=ACKNOWLEDGED`, with written outcomes posted by `comment --fingerprint`. That comment carries `<!-- fleet-shape-ack: fingerprint=<fp> -->` as an HTML line of its own. A new head carrying new unplaced text has a new fingerprint and owes a new acknowledgment. A part on an earlier round prints under `REVIEWER OUTPUT NOTED` with a one-line note. So does a label nested in a list, a quote, or a placed part. It decides no exit code. `shapes=NOTED` shows only where no head hold takes the field.
 
 **A Copilot round is requested at defined moments rather than on every push.** The one moment is the head of a pull request into the default branch, a promotion among them. A promotion re-reviews content its feature pull requests already carried, so the hosted review runs once per change, at the promotion. On a pull request into any other branch, every head is covered by the recorded local pass the push already owes. That pass lives in the checkout's git directory, where nothing on GitHub can read it, so `attest` publishes it as a comment carrying `<!-- fleet-local-review: head=<sha> base=<branch> findings=<n> -->`. It does so only after confirming the checkout is the pushed head, holds no other change, measures the pull request's own merge base, and has a covering pass in `local_review.py status`. `status` then reads that head as `review_on_head=local` with `coverage=local`, where the attestation comes from an owner, member, or collaborator, stands as an HTML line of its own outside any code, and no round on record states partial coverage with the whole history in view. A hidden attestation comment does not count. `wait` requests nothing on such a head and polls its checks instead, while they can still move the merge. Where it is not attested, `wait` exits `49`, and `--request` asks for a round anyway. The comment's findings count prints beside the reading and gates nothing, since a local pass's findings are advisory. A default branch the payload does not name reads as a promotion, so an unreadable field costs a Copilot request rather than passing a head on a local pass alone.
 
diff --git a/scripts/pr_review.py b/scripts/pr_review.py
index d37e2249..45df3307 100755
--- a/scripts/pr_review.py
+++ b/scripts/pr_review.py
@@ -13,7 +13,8 @@
 
 This file is the gate: the plumbing, the verdict, the wait loop, and the writes. The head's checks
 are read by `pr_review_checks.py` and its review rounds by `pr_review_rounds.py`, both off a payload
-this file fetched. What a reviewer's body says is read by `pr_review_copilot.py`, whose vocabulary lives in
+this file fetched. `pr_review_digest.py` renders the digest from those readings. What a reviewer's
+body says is read by `pr_review_copilot.py`, whose vocabulary lives in
 `reviewers/<name>.json`, so a change in the reviewer's wording is a data edit there and never
 an edit here. A part of a head round the adapter cannot place holds the gate. A trusted author's
 written outcomes acknowledge it, and on an earlier round it is a note.
@@ -186,40 +187,32 @@
 from pathlib import Path
 
 import gh_graphql as shared
-import pr_review_copilot as adapter
 from pr_review_checks import (
     CHECK_GRACE,
     CHECK_STALL,
     CHECKS_WINDOW,
     WORKFLOW_KEYS_UNAVAILABLE,
     _unmet_note,
-    check_lines,
     check_nodes,
     checks_never_ran,
     checks_settling,
     checks_stuck,
-    checks_tally,
     held_checks_open,
     runs_open,
 )
+from pr_review_digest import digest_refusal, render
 from pr_review_rounds import (
     ACK_MARKER,
     CARRIED_PARTIAL,
-    CODERABBIT_LOGIN,
     FILES_UNREAD,
-    KNOWN_REVIEWERS,
-    OTHER_REVIEWERS,
-    QODO_LOGIN,
     REVIEWER,
     answered_outside_review,
     attested,
-    collected,
     copilot_bot_id,
     coverage,
     describe,
     files_unread,
     finding_text,
-    first_comment,
     head_review_done,
     head_reviews,
     history_entry,
@@ -227,31 +220,20 @@
     local_cover,
     matching_threads,
     newest_first,
-    newest_of,
     open_threads,
-    opened_by,
     possible_quota,
-    qodo_comment,
-    qodo_comments_blind,
     quota_refusal,
     quota_signal,
-    rate_limited_by,
-    reading,
     refusing_review,
     request_recorded,
-    review_effort,
     reviewed_head,
     reviewer_login_drift,
     reviewer_nodes,
     reviewer_requested,
-    reviews_truncated,
     shape_hold,
     standing_quota,
     stopping_refusal,
-    thread_author,
-    threads_truncated,
     uncounted_verdict,
-    window_blind,
 )
 
 # The directory this script sits in, the anchor every scope answer is read from.
@@ -758,248 +740,17 @@ def digest(
     stall: float = CHECK_STALL,
     checks: list[dict] | None = None,
 ) -> tuple[str, int]:
-    """Render the digest from a caller's payload and normalized checks when supplied.
+    """Read what the digest needs, unless the caller supplied it, and render it.
 
     The caller passes its own readings so the exit code agrees with what was printed. `now` is a
     parameter so a case can hold a check at a known age.
     """
     pr = full_read(owner, repo, num) if pr is None else pr
     now = datetime.now(UTC) if now is None else now
-    head = pr["headRefOid"]
-    revs = reviewer_nodes(pr, "reviews")
-    on_head = head_reviews(pr)
-    newest = newest_of(on_head)
-    found = reading(newest, pr=pr) if newest is not None else None
-    effort, effort_source = review_effort(pr)
-    cover, cover_why = coverage(pr)
-    hold = shape_hold(pr)
-    # Every round's notes, since a renamed section on an earlier round hides a finding too.
-    notes = [
-        *dict.fromkeys(
-            f"round {((node.get('commit') or {}).get('oid') or 'unknown')[:8]}: {n}"
-            for node in revs
-            for n in reading(node).notes
-            if node not in on_head or n not in {p.note for p in reading(node).unplaced}
-        ),
-        *reviewer_login_drift(pr),
-    ]
-    threads = pr["reviewThreads"]["nodes"]
-    truncated = threads_truncated(pr)
-    revs_truncated = reviews_truncated(pr)
-    unresolved = open_threads(threads)
-    by_login = {
-        login: sum(1 for t in unresolved if thread_author(t) == login) for login in KNOWN_REVIEWERS
-    }
-    by_login["other"] = sum(1 for t in unresolved if thread_author(t) not in KNOWN_REVIEWERS)
-    contributors = {login: n for login, n in by_login.items() if n}
-    breakdown = (
-        " (" + " ".join(f"{login}={n}" for login, n in contributors.items()) + ")"
-        if len(contributors) > 1 or "other" in contributors
-        else ""
-    )
-    suppressed, suppressed_field = collected(pr, REVIEWER, "suppressed")
-    missed, missed_field = collected(pr, REVIEWER, "previously_missed")
-    outside, outside_field = collected(pr, CODERABBIT_LOGIN, "previously_missed")
-    listed = len(opened_by(pr, newest)) if newest is not None else 0
-    flagged = uncounted_verdict(pr)
-    advisory = uncounted_verdict(pr, "clean")
-    answer = answered_outside_review(pr)
-    refusal = stopping_refusal(pr) or (None if on_head else refusing_review(pr))
-    refusal_field = (
-        "no"
-        if not refusal
-        else "QUOTA"
-        if quota_refusal(refusal) or confirmed_quota(owner, repo, refusal)
-        else "ERROR"
-        if possible_quota(refusal)
-        else "YES"
-    )
-    blind = [f for f in ("reviews", "comments") if window_blind(pr, f)]
-    answered = "yes" if answer else ("unknown" if blind else "no")
     checks = check_nodes(pr) if checks is None else checks
-    ok, total = checks_tally(checks)
-    stuck = checks_stuck(checks, now, grace, stall)
-    other_on_head = [
-        login
-        for login in OTHER_REVIEWERS
-        if any(
-            (n.get("commit") or {}).get("oid") == head for n in reviewer_nodes(pr, "reviews", login)
-        )
-    ]
-    other_limited = {
-        login: name for login in OTHER_REVIEWERS if (name := rate_limited_by(pr, login)) is not None
-    }
-    qodo = qodo_comment(pr)
-    qodo_open = [s for s in reading(qodo, QODO_LOGIN).sections if s.kind == "open"] if qodo else []
-    lines = [
-        # The repository leads the line, since a digest of the wrong pull request is well-formed.
-        f"repo={owner}/{repo} pr={num} head={head[:8]} rounds={len(revs)} "
-        f"review_on_head={'yes' if on_head else 'local' if cover == 'local' else 'NO'} "
-        + (f"other_reviewed={','.join(other_on_head)} " if other_on_head else "")
-        + (
-            "other_rate_limited="
-            + ",".join(
-                f"{login}:{name}" if name else login for login, name in other_limited.items()
-            )
-            + " "
-            if other_limited
-            else ""
-        )
-        + f"effort={effort} effort_source={effort_source} "
-        f"coverage={cover.upper() if cover in ('partial', 'unknown') else cover} "
-        f"shapes={('ACKNOWLEDGED' if hold[2] else 'HELD') if hold else 'NOTED' if notes else 'ok'} "
-        f"refusal={refusal_field} "
-        f"threads={len(threads)}{'+' if truncated else ''} "
-        f"unresolved={len(unresolved)}{'+' if truncated else ''}{breakdown} "
-        f"suppressed={suppressed_field} "
-        + (f"previously_missed={missed_field} " if missed or revs_truncated else "")
-        + (
-            f"overview={'?' if found.open is None else found.open}/{listed} "
-            if found is not None and found.marked
-            else ""
-        )
-        + (f"cr_outside_diff={outside_field} " if outside or revs_truncated else "")
-        + (
-            f"qodo_open={len(qodo_open)} "
-            if qodo
-            else ("qodo_open=unknown " if qodo_comments_blind(pr) else "")
-        )
-        + f"answered_outside_review={answered} "
-        f"requested={'yes' if reviewer_requested(pr) else 'no'} "
-        f"merge={pr.get('mergeStateStatus')} "
-        f"checks={ok}/{total}"
-        + (f" stuck={','.join(sorted({s for _, s in stuck}))}" if stuck else "")
-    ]
-    if refusal:
-        lines.append(
-            "  COPILOT REFUSED THIS ROUND: the newest Copilot review on this pull request says "
-            "it did not review, so it covers nothing and re-requesting repeats it, and the body "
-            "below is what says which remedy applies"
-        )
-        lines += [
-            f"    {ln.rstrip()}" for ln in (refusal.get("body") or "").splitlines() if ln.strip()
-        ]
-        if limit := confirmed_quota(owner, repo, refusal):
-            lines.append(f"  RATE LIMIT FROM THE REVIEWER'S RUN LOG: {limit}")
-    if notes:
-        lines.append(
-            f"  REVIEWER OUTPUT NOTED ({len(notes)}): the reader placed part of what the reviewer "
-            "sent nowhere, so read the body itself before closing the review loop. A spelling "
-            f"to add belongs in `scripts/reviewers/` on {HUB}, which hosts this script"
-        )
-        lines += [f"    {note}" for note in notes]
-    if hold:
-        lines.append(
-            f"  UNPLACED ON THE HEAD (fingerprint={hold[0]}): a round covering the head carries "
-            + (
-                "parts an owner, member, or collaborator acknowledged with written outcomes"
-                if hold[2]
-                else "text the reader cannot place, where a finding can sit. Read each part whole "
-                "in the review body, the excerpt only locating it, and give each item an outcome, "
-                "fixed with its SHA, declined with evidence, or listed as pre-existing in the PR "
-                f"body. Post them with `comment {num} --repo {owner}/{repo} --fingerprint "
-                f"{hold[0]} --body <outcomes>`"
-            )
-        )
-        for part in hold[1]:
-            lines += [f"    {part.note}", *([] if hold[2] else adapter.excerpt(part.text))]
-    if found is not None and found.unthreaded:
-        lines.append(
-            f"  FINDINGS WITH NO THREAD ({found.unthreaded}): the round covering the head names "
-            f"more findings than its open entries link to threads on this pull request, so "
-            f"{found.unthreaded} {'is' if found.unthreaded == 1 else 'are'} raised where polling "
-            "threads cannot see them. Read the review body and give each the triage a suppressed "
-            "finding gets. A thread past the hundred read here counts too, and `threads=` "
-            "carries a trailing `+` where that page was cut"
-        )
-    if flagged:
-        lines.append(
-            f"  VERDICT WITH NO COUNTED FINDING: the round covering the head opens on "
-            f"`{flagged[0]}` and counts no finding, so its headline is the one place what it "
-            "flags is named. Give the headline the triage a suppressed finding gets"
-        )
-        lines.append(f"    {flagged[1] or '(the headline carries no prose)'}")
-    if advisory and advisory[1]:
-        lines.append(
-            f"  CLEAN VERDICT HEADLINE: the round covering the head opens on `{advisory[0]}` and "
-            "counts no finding. Its headline may name a remaining nit, new or already answered, "
-            "which nothing here tells apart, so this is advisory and changes no exit code"
-        )
-        lines.append(f"    {advisory[1]}")
-    if cover in ("table", "carried:table", "local", "partial", "unknown"):
-        lines.append(f"  COVERAGE IS {cover.upper()}: {cover_why}")
-    elif cover == "none" and on_head:
-        lines.append(
-            "  NO COVERAGE IS SHOWN: no round covering the head states coverage, and "
-            f"{cover_why or 'nothing stands in'}. Merge Gate item 2 reads this field"
-        )
-    lines.extend(check_lines(pr, checks, stuck, now))
-    if blind:
-        lines.append(
-            f"  BEHIND THE WINDOW ({' and '.join(blind)}): the newest {WINDOW} carry "
-            "none from the reviewer and older ones exist, so this cannot decide"
-        )
-    if truncated:
-        lines.append(
-            "  THREADS TRUNCATED: this pull request carries more review threads than the "
-            "100 read here, and the connection reads oldest-first, so the ones cut off are "
-            "the newest rather than the oldest, exactly the ones most likely to still be "
-            "open. `threads=` and `unresolved=` above undercount. Read the rest with "
-            "`reply`'s own paginated walk before trusting either number"
-        )
-    if revs_truncated:
-        lines.append(
-            "  REVIEWS TRUNCATED: this pull request carries more reviews than the 100 read "
-            "here, and the connection reads newest-first, so the ones cut off are the "
-            "oldest, exactly where an unanswered suppressed or outside-diff-range finding is "
-            "most likely to still sit unresolved. `suppressed=` and `cr_outside_diff=` above "
-            "undercount"
-        )
-    if answer:
-        # Printed whole, since its wording is the only thing separating a refusal from a remark.
-        lines.append(
-            f"  COPILOT COMMENT ({answer.get('createdAt')}, newer than any review): "
-            "the reviewer answered without reviewing, so read the body below and "
-            "decide, since a refusal is terminal and a remark is not"
-        )
-        lines += [
-            f"    {ln.rstrip()}" for ln in (answer.get("body") or "").splitlines() if ln.strip()
-        ]
-    new = 0
-    for t in unresolved:
-        c = first_comment(t)
-        tid = t["id"]
-        mark = ""
-        if seen is not None:
-            if tid in seen:
-                continue
-            seen.add(tid)
-            mark = "NEW "
-            new += 1
-        body = " ".join((c.get("body") or "").split())
-        lines.append(f"  {mark}{tid} {c.get('path')}:{c.get('line')} {body[:160]}")
-    # Printed whole, since a finding with no thread appears nowhere but here.
-    for heading, entries in (
-        ("SUPPRESSED", suppressed),
-        ("PREVIOUSLY MISSED", missed),
-        ("CODERABBIT OUTSIDE-DIFF", outside),
-    ):
-        for where, section in entries:
-            lines.append(
-                f"  {heading} ({where}): no thread to resolve, "
-                "answer it in the PR conversation quoting the finding"
-            )
-            lines += [f"    {ln}" for ln in section.text.splitlines() if ln.strip()]
-    for section in qodo_open:
-        lines.append(
-            "  QODO OPEN FINDING: neither Resolved nor Dismissed, no thread to resolve, "
-            "answer it in the PR conversation quoting the finding, and spot-verify Qodo's "
-            "own badge against `gh pr diff` rather than trusting it outright"
-        )
-        lines.append(f"    {section.title}")
-    if seen is not None:
-        lines[0] += f" new={new}"
-    return "\n".join(lines), len(unresolved)
+    refusal = digest_refusal(pr)
+    quota = confirmed_quota(owner, repo, refusal) if refusal else ""
+    return render(owner, repo, num, pr, checks, now, grace, stall, quota, seen, HUB, WINDOW)
 
 
 def report_verdict(pr: dict) -> int:
diff --git a/scripts/pr_review_digest.py b/scripts/pr_review_digest.py
new file mode 100644
index 00000000..a0da787f
--- /dev/null
+++ b/scripts/pr_review_digest.py
@@ -0,0 +1,318 @@
+"""The review gate's digest, rendered off one payload, for the gate in `pr_review.py`.
+
+This is a library module and has no command line. `pr_review.py` imports it as a sibling, and
+`pr_review.digest` does the reads: the payload, the normalized checks, and the run log behind a
+refusal.
+`render` takes those results as arguments and makes no call. The header is an ordered list of
+fields, so a new one is one entry. The fixed advisory lines are an ordered table, one row each.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+
+import pr_review_copilot as adapter
+from pr_review_checks import check_lines, checks_stuck, checks_tally
+from pr_review_rounds import (
+    CODERABBIT_LOGIN,
+    KNOWN_REVIEWERS,
+    OTHER_REVIEWERS,
+    QODO_LOGIN,
+    REVIEWER,
+    answered_outside_review,
+    collected,
+    coverage,
+    first_comment,
+    head_reviews,
+    newest_of,
+    open_threads,
+    opened_by,
+    possible_quota,
+    qodo_comment,
+    qodo_comments_blind,
+    quota_refusal,
+    rate_limited_by,
+    reading,
+    refusing_review,
+    review_effort,
+    reviewer_login_drift,
+    reviewer_nodes,
+    reviewer_requested,
+    reviews_truncated,
+    shape_hold,
+    stopping_refusal,
+    thread_author,
+    threads_truncated,
+    uncounted_verdict,
+    window_blind,
+)
+
+BEHIND_THE_WINDOW = (
+    "  BEHIND THE WINDOW ({value}): the newest {window} carry "
+    "none from the reviewer and older ones exist, so this cannot decide"
+)
+THREADS_TRUNCATED = (
+    "  THREADS TRUNCATED: this pull request carries more review threads than the "
+    "100 read here, and the connection reads oldest-first, so the ones cut off are "
+    "the newest rather than the oldest, exactly the ones most likely to still be "
+    "open. `threads=` and `unresolved=` above undercount. Read the rest with "
+    "`reply`'s own paginated walk before trusting either number"
+)
+REVIEWS_TRUNCATED = (
+    "  REVIEWS TRUNCATED: this pull request carries more reviews than the 100 read "
+    "here, and the connection reads newest-first, so the ones cut off are the "
+    "oldest, exactly where an unanswered suppressed or outside-diff-range finding is "
+    "most likely to still sit unresolved. `suppressed=` and `cr_outside_diff=` above "
+    "undercount"
+)
+
+
+def digest_refusal(pr: dict) -> dict | None:
+    """The refusal the digest reports: a stopping one, else one standing in for a missing head round."""
+    return stopping_refusal(pr) or (None if head_reviews(pr) else refusing_review(pr))
+
+
+def header(fields: list[tuple[str, object]]) -> str:
+    """Join each `key=value` pair by one space, leaving out a field whose value is None."""
+    return " ".join(f"{key}={value}" for key, value in fields if value is not None)
+
+
+def render(
+    owner: str,
+    repo: str,
+    num: int,
+    pr: dict,
+    checks: list[dict],
+    now: datetime,
+    grace: float,
+    stall: float,
+    quota: str,
+    seen: set[str] | None,
+    hub: str,
+    window: int,
+) -> tuple[str, int]:
+    """Render the digest and return it with the unresolved count.
+
+    `quota` is the run log's rate-limit sentence for the refusal `digest_refusal` names, read by the
+    caller. Where `seen` is a set, only threads absent from it print, marked new, and are added.
+    """
+    head = pr["headRefOid"]
+    revs = reviewer_nodes(pr, "reviews")
+    on_head = head_reviews(pr)
+    newest = newest_of(on_head)
+    found = reading(newest, pr=pr) if newest is not None else None
+    effort, effort_source = review_effort(pr)
+    cover, cover_why = coverage(pr)
+    hold = shape_hold(pr)
+    # Every round's notes, since a renamed section on an earlier round hides a finding too.
+    notes = [
+        *dict.fromkeys(
+            f"round {((node.get('commit') or {}).get('oid') or 'unknown')[:8]}: {n}"
+            for node in revs
+            for n in reading(node).notes
+            if node not in on_head or n not in {p.note for p in reading(node).unplaced}
+        ),
+        *reviewer_login_drift(pr),
+    ]
+    threads = pr["reviewThreads"]["nodes"]
+    truncated = threads_truncated(pr)
+    revs_truncated = reviews_truncated(pr)
+    unresolved = open_threads(threads)
+    by_login = {
+        login: sum(1 for t in unresolved if thread_author(t) == login) for login in KNOWN_REVIEWERS
+    }
+    by_login["other"] = sum(1 for t in unresolved if thread_author(t) not in KNOWN_REVIEWERS)
+    contributors = {login: n for login, n in by_login.items() if n}
+    breakdown = (
+        " (" + " ".join(f"{login}={n}" for login, n in contributors.items()) + ")"
+        if len(contributors) > 1 or "other" in contributors
+        else ""
+    )
+    suppressed, suppressed_field = collected(pr, REVIEWER, "suppressed")
+    missed, missed_field = collected(pr, REVIEWER, "previously_missed")
+    outside, outside_field = collected(pr, CODERABBIT_LOGIN, "previously_missed")
+    listed = len(opened_by(pr, newest)) if newest is not None else 0
+    flagged = uncounted_verdict(pr)
+    advisory = uncounted_verdict(pr, "clean")
+    answer = answered_outside_review(pr)
+    refusal = digest_refusal(pr)
+    refusal_field = (
+        "no"
+        if not refusal
+        else "QUOTA"
+        if quota_refusal(refusal) or quota
+        else "ERROR"
+        if possible_quota(refusal)
+        else "YES"
+    )
+    blind = [f for f in ("reviews", "comments") if window_blind(pr, f)]
+    answered = "yes" if answer else ("unknown" if blind else "no")
+    ok, total = checks_tally(checks)
+    stuck = checks_stuck(checks, now, grace, stall)
+    other_on_head = [
+        login
+        for login in OTHER_REVIEWERS
+        if any(
+            (n.get("commit") or {}).get("oid") == head for n in reviewer_nodes(pr, "reviews", login)
+        )
+    ]
+    other_limited = {
+        login: name for login in OTHER_REVIEWERS if (name := rate_limited_by(pr, login)) is not None
+    }
+    qodo = qodo_comment(pr)
+    qodo_open = [s for s in reading(qodo, QODO_LOGIN).sections if s.kind == "open"] if qodo else []
+    shown = []
+    for t in unresolved:
+        if seen is not None:
+            if t["id"] in seen:
+                continue
+            seen.add(t["id"])
+        shown.append(t)
+    plus = "+" if truncated else ""
+    # The repository leads the line, since a digest of the wrong pull request is well-formed.
+    fields: list[tuple[str, object]] = [
+        ("repo", f"{owner}/{repo}"),
+        ("pr", num),
+        ("head", head[:8]),
+        ("rounds", len(revs)),
+        ("review_on_head", "yes" if on_head else "local" if cover == "local" else "NO"),
+        ("other_reviewed", ",".join(other_on_head) or None),
+        (
+            "other_rate_limited",
+            ",".join(f"{login}:{name}" if name else login for login, name in other_limited.items())
+            or None,
+        ),
+        ("effort", effort),
+        ("effort_source", effort_source),
+        ("coverage", cover.upper() if cover in ("partial", "unknown") else cover),
+        (
+            "shapes",
+            ("ACKNOWLEDGED" if hold[2] else "HELD") if hold else "NOTED" if notes else "ok",
+        ),
+        ("refusal", refusal_field),
+        ("threads", f"{len(threads)}{plus}"),
+        ("unresolved", f"{len(unresolved)}{plus}{breakdown}"),
+        ("suppressed", suppressed_field),
+        ("previously_missed", missed_field if missed or revs_truncated else None),
+        (
+            "overview",
+            f"{'?' if found.open is None else found.open}/{listed}"
+            if found is not None and found.marked
+            else None,
+        ),
+        ("cr_outside_diff", outside_field if outside or revs_truncated else None),
+        ("qodo_open", len(qodo_open) if qodo else "unknown" if qodo_comments_blind(pr) else None),
+        ("answered_outside_review", answered),
+        ("requested", "yes" if reviewer_requested(pr) else "no"),
+        ("merge", str(pr.get("mergeStateStatus"))),
+        ("checks", f"{ok}/{total}"),
+        ("stuck", ",".join(sorted({s for _, s in stuck})) or None),
+        ("new", len(shown) if seen is not None else None),
+    ]
+    lines = [header(fields)]
+    if refusal:
+        lines.append(
+            "  COPILOT REFUSED THIS ROUND: the newest Copilot review on this pull request says "
+            "it did not review, so it covers nothing and re-requesting repeats it, and the body "
+            "below is what says which remedy applies"
+        )
+        lines += [
+            f"    {ln.rstrip()}" for ln in (refusal.get("body") or "").splitlines() if ln.strip()
+        ]
+        if quota:
+            lines.append(f"  RATE LIMIT FROM THE REVIEWER'S RUN LOG: {quota}")
+    if notes:
+        lines.append(
+            f"  REVIEWER OUTPUT NOTED ({len(notes)}): the reader placed part of what the reviewer "
+            "sent nowhere, so read the body itself before closing the review loop. A spelling "
+            f"to add belongs in `scripts/reviewers/` on {hub}, which hosts this script"
+        )
+        lines += [f"    {note}" for note in notes]
+    if hold:
+        lines.append(
+            f"  UNPLACED ON THE HEAD (fingerprint={hold[0]}): a round covering the head carries "
+            + (
+                "parts an owner, member, or collaborator acknowledged with written outcomes"
+                if hold[2]
+                else "text the reader cannot place, where a finding can sit. Read each part whole "
+                "in the review body, the excerpt only locating it, and give each item an outcome, "
+                "fixed with its SHA, declined with evidence, or listed as pre-existing in the PR "
+                f"body. Post them with `comment {num} --repo {owner}/{repo} --fingerprint "
+                f"{hold[0]} --body <outcomes>`"
+            )
+        )
+        for part in hold[1]:
+            lines += [f"    {part.note}", *([] if hold[2] else adapter.excerpt(part.text))]
+    if found is not None and found.unthreaded:
+        lines.append(
+            f"  FINDINGS WITH NO THREAD ({found.unthreaded}): the round covering the head names "
+            f"more findings than its open entries link to threads on this pull request, so "
+            f"{found.unthreaded} {'is' if found.unthreaded == 1 else 'are'} raised where polling "
+            "threads cannot see them. Read the review body and give each the triage a suppressed "
+            "finding gets. A thread past the hundred read here counts too, and `threads=` "
+            "carries a trailing `+` where that page was cut"
+        )
+    if flagged:
+        lines.append(
+            f"  VERDICT WITH NO COUNTED FINDING: the round covering the head opens on "
+            f"`{flagged[0]}` and counts no finding, so its headline is the one place what it "
+            "flags is named. Give the headline the triage a suppressed finding gets"
+        )
+        lines.append(f"    {flagged[1] or '(the headline carries no prose)'}")
+    if advisory and advisory[1]:
+        lines.append(
+            f"  CLEAN VERDICT HEADLINE: the round covering the head opens on `{advisory[0]}` and "
+            "counts no finding. Its headline may name a remaining nit, new or already answered, "
+            "which nothing here tells apart, so this is advisory and changes no exit code"
+        )
+        lines.append(f"    {advisory[1]}")
+    if cover in ("table", "carried:table", "local", "partial", "unknown"):
+        lines.append(f"  COVERAGE IS {cover.upper()}: {cover_why}")
+    elif cover == "none" and on_head:
+        lines.append(
+            "  NO COVERAGE IS SHOWN: no round covering the head states coverage, and "
+            f"{cover_why or 'nothing stands in'}. Merge Gate item 2 reads this field"
+        )
+    lines.extend(check_lines(pr, checks, stuck, now))
+    for value, template in (
+        (" and ".join(blind), BEHIND_THE_WINDOW),
+        (truncated, THREADS_TRUNCATED),
+        (revs_truncated, REVIEWS_TRUNCATED),
+    ):
+        if value:
+            lines.append(template.format(value=value, window=window))
+    if answer:
+        # Printed whole, since its wording is the only thing separating a refusal from a remark.
+        lines.append(
+            f"  COPILOT COMMENT ({answer.get('createdAt')}, newer than any review): "
+            "the reviewer answered without reviewing, so read the body below and "
+            "decide, since a refusal is terminal and a remark is not"
+        )
+        lines += [
+            f"    {ln.rstrip()}" for ln in (answer.get("body") or "").splitlines() if ln.strip()
+        ]
+    mark = "NEW " if seen is not None else ""
+    for t in shown:
+        c = first_comment(t)
+        body = " ".join((c.get("body") or "").split())
+        lines.append(f"  {mark}{t['id']} {c.get('path')}:{c.get('line')} {body[:160]}")
+    # Printed whole, since a finding with no thread appears nowhere but here.
+    for heading, entries in (
+        ("SUPPRESSED", suppressed),
+        ("PREVIOUSLY MISSED", missed),
+        ("CODERABBIT OUTSIDE-DIFF", outside),
+    ):
+        for where, section in entries:
+            lines.append(
+                f"  {heading} ({where}): no thread to resolve, "
+                "answer it in the PR conversation quoting the finding"
+            )
+            lines += [f"    {ln}" for ln in section.text.splitlines() if ln.strip()]
+    for section in qodo_open:
+        lines.append(
+            "  QODO OPEN FINDING: neither Resolved nor Dismissed, no thread to resolve, "
+            "answer it in the PR conversation quoting the finding, and spot-verify Qodo's "
+            "own badge against `gh pr diff` rather than trusting it outright"
+        )
+        lines.append(f"    {section.title}")
+    return "\n".join(lines), len(unresolved)
diff --git a/tests/test_pr_review.py b/tests/test_pr_review.py
index e33f9b84..e1522b9b 100755
--- a/tests/test_pr_review.py
+++ b/tests/test_pr_review.py
@@ -42,11 +42,25 @@
 
 REPO = Path(__file__).resolve().parent.parent
 # The gate and the reader modules it imports, which every whole-source guard below reads together.
-GATE_SOURCES = ("pr_review.py", "pr_review_checks.py", "pr_review_rounds.py")
-# What a reader module may import: the standard library it parses with, and the reviewer adapter.
-READER_IMPORTS = frozenset({"__future__", "collections", "datetime", "re", "pr_review_copilot"})
+GATE_SOURCES = ("pr_review.py", "pr_review_checks.py", "pr_review_rounds.py", "pr_review_digest.py")
+# What a reader may import: the stdlib it parses with, the reviewer adapter, and the other readers.
+READER_IMPORTS = frozenset(
+    {
+        "__future__",
+        "collections",
+        "datetime",
+        "re",
+        "pr_review_copilot",
+        "pr_review_checks",
+        "pr_review_rounds",
+    }
+)
 # One import each reader module is known to make, the floor under the allowlist above.
-READER_FLOORS = {"pr_review_checks": "datetime", "pr_review_rounds": "pr_review_copilot"}
+READER_FLOORS = {
+    "pr_review_checks": "datetime",
+    "pr_review_rounds": "pr_review_copilot",
+    "pr_review_digest": "pr_review_rounds",
+}
 # What a reader must never load, directly or through the adapter.
 REACHING_OUT = ("pr_review", "gh_graphql", "subprocess")
 RUNBOOK = REPO / ".github" / "copilot-instructions.md"
@@ -733,6 +747,80 @@ def test_a_body_is_flattened_and_bounded(self) -> None:
         self.assertLessEqual(len(body.split("a.py:1 ")[1]), 160)
 
 
+CROWDED_DIGEST = "\n".join(
+    (
+        (
+            "repo=o/r pr=7 head=aaaaaaaa rounds=2 review_on_head=yes effort=unknown "
+            "effort_source=unknown coverage=full shapes=ok refusal=no threads=2+ unresolved=2+ "
+            f"({pr_review_rounds.REVIEWER}=1 other=1) suppressed=0+ (on_head=0 earlier=0) "
+            "previously_missed=0+ (on_head=0 earlier=0) overview=?/0 cr_outside_diff=0+ "
+            "(on_head=0 earlier=0) qodo_open=unknown answered_outside_review=unknown requested=no "
+            "merge=BLOCKED checks=0/1 stuck=FAILED new=2"
+        ),
+        (
+            "  CHECK FAILED ('Check pull request workflow status job', COMPLETED/FAILURE): a verdict "
+            "rather than a stuck check, so read the run and fix what failed, since no wait and no "
+            "re-run clears a real failure"
+        ),
+        (
+            "  BEHIND THE WINDOW (comments): the newest 100 carry none from the reviewer and older "
+            "ones exist, so this cannot decide"
+        ),
+        (
+            "  THREADS TRUNCATED: this pull request carries more review threads than the 100 read "
+            "here, and the connection reads oldest-first, so the ones cut off are the newest rather "
+            "than the oldest, exactly the ones most likely to still be open. `threads=` and "
+            "`unresolved=` above undercount. Read the rest with `reply`'s own paginated walk before "
+            "trusting either number"
+        ),
+        (
+            "  REVIEWS TRUNCATED: this pull request carries more reviews than the 100 read here, and "
+            "the connection reads newest-first, so the ones cut off are the oldest, exactly where an "
+            "unanswered suppressed or outside-diff-range finding is most likely to still sit "
+            "unresolved. `suppressed=` and `cr_outside_diff=` above undercount"
+        ),
+        "  NEW T1 a.py:1 First finding.",
+        "  NEW T2 a.py:1 A finding.",
+    )
+)
+QUIET_DIGEST = (
+    "repo=o/r pr=7 head=aaaaaaaa rounds=1 review_on_head=NO effort=unknown effort_source=unknown "
+    "coverage=none shapes=ok refusal=no threads=0 unresolved=0 suppressed=0 (on_head=0 earlier=0) "
+    "answered_outside_review=no requested=yes merge=CLEAN checks=1/1"
+)
+
+
+class TestDigestRenderIsPinned(GqlCase):
+    """The whole digest, byte for byte, as `pr_review_digest.render` lays it out.
+
+    Each expected text was captured before the rendering moved to the leaf module.
+    A reorder among the fields and lines these two cases print fails here rather than in a parse.
+    """
+
+    def test_a_crowded_digest_keeps_its_field_and_advisory_order(self) -> None:
+        self.answer(
+            payload(
+                [review(), review(oid=OLD, rid="PRR_two")],
+                [thread("T1", body="First finding."), thread("T2", login="ptr727")],
+                merge="BLOCKED",
+                comments=[comment(login="ptr727") for _ in range(pr_review.WINDOW)],
+                older=True,
+                older_reviews=True,
+                checks=[check(conclusion="FAILURE")],
+                more_threads=True,
+            )
+        )
+        out, unresolved = pr_review.digest("o", "r", 7, set(), now=NOW)
+        self.assertEqual(2, unresolved)
+        self.assertEqual(CROWDED_DIGEST, out)
+
+    def test_a_quiet_digest_leaves_out_every_optional_field(self) -> None:
+        self.answer(payload([review(oid=OLD)], checks=[check()], pending=True))
+        out, unresolved = pr_review.digest("o", "r", 7, now=NOW)
+        self.assertEqual(0, unresolved)
+        self.assertEqual(QUIET_DIGEST, out)
+
+
 class TestOtherReviewers(GqlCase):
     """Thread resolution, head-presence, and the rate-limit marker's own structural pattern,
     generalized past Copilot to the other review bots this repository has trialed. Free-text
@@ -2107,7 +2195,7 @@ def test_a_note_on_an_earlier_round_still_reaches_the_digest(self) -> None:
         self.assertIn(f"round {OLD[:8]}: the body carries no", self.out.getvalue())
 
     def test_a_body_the_reader_trips_on_holds_and_is_never_a_refusal(self) -> None:
-        with mock.patch.object(pr_review.adapter, "_read", side_effect=ValueError("boom")):
+        with mock.patch.object(pr_review_rounds.adapter, "_read", side_effect=ValueError("boom")):
             self.assertEqual(50, self.status(payload([review(body="odd body")], files=["a.py"])))
         out = self.out.getvalue()
         self.assertIn("review_on_head=yes ", out)
@@ -5506,7 +5594,7 @@ def test_the_runbook_publishes_the_machine_readable_coverage_marker(self) -> Non
         # Raw, since a marker split over two lines is not the one-line shape the skill asks for.
         self.assertIn(marker, CODE_REVIEW_SKILL.read_text(encoding="utf-8"))
         body = f"{OVERVIEW}\n{marker.replace('N', '1')}"
-        self.assertEqual("full", pr_review.adapter.read(body).coverage)
+        self.assertEqual("full", pr_review_rounds.adapter.read(body).coverage)
 
     def test_the_runbook_names_partial_coverage_as_a_state_that_blocks_a_merge(self) -> None:
         """A verify step reading `commit.oid` alone is what let five partial rounds merge.
diff --git a/tests/test_pr_review_size.py b/tests/test_pr_review_size.py
index 0b48af85..7fdeba79 100755
--- a/tests/test_pr_review_size.py
+++ b/tests/test_pr_review_size.py
@@ -11,6 +11,7 @@
     "pr_review.py": 2200,
     "pr_review_checks.py": 450,
     "pr_review_rounds.py": 700,
+    "pr_review_digest.py": 350,
     "pr_review_copilot.py": 1500,
     "pr_cleanup.py": 1200,
 }

From 41d513889677830918231e1120e15e39936c7053 Mon Sep 17 00:00:00 2001
From: Pieter Viljoen <ptr727@users.noreply.github.com>
Date: Sun, 25 Oct 2026 18:33:48 -0700
Subject: [PATCH 2/3] Drop the Incidental Count of the Gate's Reader Modules
 (#3495)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

## Summary

Answers the finding on promotion
[#3494](https://github.com/ptr727/ProjectTemplate/pull/3494) that
`scripts/README.md:9` counted the reader modules ("three"), a second
copy of the list just before it that goes stale when a reader is added.
The sentence now reads "The reader modules `pr_review.py` imports are
tested through `test_pr_review.py`.", which also stops it leaning on
"the gate", since the same paragraph defines a gate as a `_lint` or
`_gate` script and lists `pr_review.py` as a utility.

## Verification

A local strict review ran two rounds. Round 1 raised the "the gate's"
antecedent, fixed in `aab59769`, and round 2 raised none. The prose gate
is clean.

## Pre-existing findings, not filed

- `scripts/README.md:9`: `pre-existing`, the older "Where a case covers
a table" sentence runs 43 words against the opt-in sentence-length
check's 25.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
---
 scripts/README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/scripts/README.md b/scripts/README.md
index b6e3dc44..b3fa46b0 100644
--- a/scripts/README.md
+++ b/scripts/README.md
@@ -6,7 +6,7 @@ The fleet's checks and review tooling, run by hand, with the deterministic ones
 
 Python only, and standard library only, with markdown-it-py the one exception. `build_dist.py`, `canonical_review.py`, `carry.py`, `pr_review.py`, `pr_review_copilot.py`, and `pr_cleanup.py` declare it in their inline script metadata. `build_dist.py` and `carry.py` import it only on the path that reads a region, since `skills_install.py` and `handoff.py` import them under a plain `python3`. Every check script is read-only and exits non-zero on a finding. `build_dist.py`, `local_review.py`, `canonical_review.py`, `handoff.py`, and `skills_install.py` below are the exceptions, since a generator, two recorders, an installer, and the handoff chain all exist to write. `build_dist.py --check` and `skills_install.py --report` are read-only modes for CI and for asking without changing anything. `local_review.py status` and `check` answer without recording anything, but they are not read-only in that same sense: reading the working tree stages it, which writes inside `.git` and runs any `filter.*.clean` the repository configures, and only the receipt is left untouched. `canonical_review.py` reads files rather than staging them, so its `list`, `status`, `sweep`, and `report` are read-only outright, and `record` alone writes.
 
-The directory separates its kinds by name and by tree. A gate checks and exits non-zero on a finding, and its name carries a `_lint` or `_gate` suffix saying what it gates. The `prose_lint.py` and `repo_gate.py` entry points delegate to the action-owned implementations that gate this tree in CI, and `host_gate.py` gates the machine it runs on. A utility does work rather than gating and carries no suffix: `backlog_metrics.py`, `build_dist.py`, `canonical_review.py`, `handoff.py`, `local_review.py`, `pr_cleanup.py`, `pr_review.py`, `pr_review_copilot.py`, `skills_install.py`. `gh_graphql.py` is a library with no command line, the GraphQL transport and cursor walker that `backlog_metrics.py`, `handoff.py`, `pr_cleanup.py`, and `pr_review.py` import from beside them. `pr_review_checks.py`, `pr_review_rounds.py`, and `pr_review_digest.py` are libraries with no command line as well. They are the pure readers `pr_review.py` imports for the head's checks, its review rounds, and the digest rendered from both. The unit tests live apart at the repository root under [`tests/`][tests], one `test_<script>.py` per script, driving the canonical implementations against input they must reject. The gate's three reader modules are tested through `test_pr_review.py`. A gate nobody has watched fail is a gate nobody knows works. Where a case covers a table it reads the live table rather than restating it, and each one asserts a floor on what a healthy run reaches, since a check whose scan matches nothing reports zero findings and reads exactly like a pass.
+The directory separates its kinds by name and by tree. A gate checks and exits non-zero on a finding, and its name carries a `_lint` or `_gate` suffix saying what it gates. The `prose_lint.py` and `repo_gate.py` entry points delegate to the action-owned implementations that gate this tree in CI, and `host_gate.py` gates the machine it runs on. A utility does work rather than gating and carries no suffix: `backlog_metrics.py`, `build_dist.py`, `canonical_review.py`, `handoff.py`, `local_review.py`, `pr_cleanup.py`, `pr_review.py`, `pr_review_copilot.py`, `skills_install.py`. `gh_graphql.py` is a library with no command line, the GraphQL transport and cursor walker that `backlog_metrics.py`, `handoff.py`, `pr_cleanup.py`, and `pr_review.py` import from beside them. `pr_review_checks.py`, `pr_review_rounds.py`, and `pr_review_digest.py` are libraries with no command line as well. They are the pure readers `pr_review.py` imports for the head's checks, its review rounds, and the digest rendered from both. The unit tests live apart at the repository root under [`tests/`][tests], one `test_<script>.py` per script, driving the canonical implementations against input they must reject. The reader modules `pr_review.py` imports are tested through `test_pr_review.py`. A gate nobody has watched fail is a gate nobody knows works. Where a case covers a table it reads the live table rather than restating it, and each one asserts a floor on what a healthy run reaches, since a check whose scan matches nothing reports zero findings and reads exactly like a pass.
 
 ```sh
 python3 tests/test_prose_lint.py

From 162d1aaccbc8c6598d2eb65273248add203c0b9f Mon Sep 17 00:00:00 2001
From: Pieter Viljoen <ptr727@users.noreply.github.com>
Date: Sun, 25 Oct 2026 19:11:24 -0700
Subject: [PATCH 3/3] Move wait Out of pr_review.py's main and Check Subcommand
 Flags From a Table (#3497)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

## Summary

Implements #3458 (the closing keyword goes on the promotion pull
request).

- The whole `wait` body moves out of `main` into `run_wait(owner, repo,
a)`, unchanged, so `main` is parsing and dispatch.
- Flag ownership is read from `FLAG_OWNERS`, one row of `(flag, owners,
late)` per flag, checked in two passes around the `cleanup` and `number`
checks so a command line with several bad flags names the same one
first. Listing `cleanup` among `--checkout`'s owners lets the error text
be the owners joined, and the `cleanup` check right after it still
refuses that command.
- The four negative-value checks are one loop.
- `COMMANDS` is the parser's choices, and the owner test reads it.

## Verification

- The first error line and the exit of 1904 bad command lines, every
subcommand crossed with pairs of misplaced, negative, and malformed
flags, were recorded before and after with every subprocess stubbed out,
and are identical.
- `test_a_command_line_with_two_bad_flags_names_the_same_one_first` pins
six multi-flag orderings, and passes against the pre-change code as
well.
- The full suite passes, `python -m unittest discover -s tests`, 2965
tests, 7 skipped. Ruff, mypy, and the pre-commit hook are clean.
- A local strict review ran two rounds on the first push. Round 1 raised
three `introduced` findings, each fixed in `d145242d`. Round 2 raised
one, `COMMANDS` landing between the `FLAG_OWNERS` comment and the table,
which the second push fixed in `2ca2e75d`. Its own pass raised none.

## Pre-existing findings, filed

- `--timeout`, `--min-rounds`, and `--ignore-quota-signal` are still
accepted silently on subcommands other than `wait`: #3496.

The `comments` label is applied for the new table and loop comments.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
---
 scripts/pr_review.py    | 384 +++++++++++++++++++++-------------------
 tests/test_pr_review.py |  52 ++++++
 2 files changed, 250 insertions(+), 186 deletions(-)

diff --git a/scripts/pr_review.py b/scripts/pr_review.py
index 45df3307..1e77171a 100755
--- a/scripts/pr_review.py
+++ b/scripts/pr_review.py
@@ -1409,192 +1409,8 @@ def utf8_console() -> None:
             reconfigure(encoding="utf-8", errors="replace")
 
 
-def main(argv: list[str] | None = None) -> int:
-    args = sys.argv[1:] if argv is None else argv
-    pre = argparse.ArgumentParser(add_help=False)
-    pre.add_argument("first", nargs="?")
-    for flag in ("--repo", "--checkout", "--min-age-hours"):
-        pre.add_argument(flag)
-    if pre.parse_known_args(args)[0].first == "cleanup":
-        sys.modules.setdefault("pr_review", sys.modules[__name__])
-        import pr_cleanup
-
-        rest = list(args)
-        rest.remove("cleanup")
-        return pr_cleanup.main(rest)
-    utf8_console()
-    ap = argparse.ArgumentParser()
-    ap.add_argument(
-        "cmd", choices=["attest", "claims", "cleanup", "comment", "status", "reply", "wait"]
-    )
-    ap.add_argument("number", type=int, nargs="?")
-    # No default, because a default names one repository and every run from elsewhere would read that one.
-    ap.add_argument(
-        "--repo",
-        required=True,
-        metavar="OWNER/NAME",
-        help="the repository the pull request is in, since a pull "
-        "request number identifies no repository on its own",
-    )
-    ap.add_argument("--timeout", type=int, default=2700, help="seconds (default 45m)")
-    ap.add_argument(
-        "--pickup-grace",
-        type=int,
-        default=300,
-        help="deprecated compatibility option, accepted but ignored",
-    )
-    ap.add_argument(
-        "--check-grace",
-        type=int,
-        default=CHECK_GRACE,
-        help="seconds a check may sit queued, or a required status go unposted, "
-        f"before either reads as unstarted (default {CHECK_GRACE // 60}m)",
-    )
-    ap.add_argument(
-        "--check-stall",
-        type=int,
-        default=CHECK_STALL,
-        help="seconds a check may run before its duration is reported "
-        f"(default {CHECK_STALL // 60}m)",
-    )
-    ap.add_argument(
-        "--ignore-quota-signal",
-        action="store_true",
-        help="wait: request and poll the full --timeout even where the reviewer's own most "
-        "recent activity elsewhere in this repository is a quota-limit refusal with nothing "
-        "answering it since, or this pull request's newest Copilot review is a quota or "
-        "error refusal, pass this once the quota is believed to have reset",
-    )
-    ap.add_argument(
-        "--request",
-        action="store_true",
-        help="wait: request a Copilot round even on a pull request into a branch other than the "
-        "default, which an attested local pass otherwise covers",
-    )
-    ap.add_argument(
-        "--min-rounds",
-        type=int,
-        default=0,
-        metavar="N",
-        help="wait: treat the head as covered only once the reviewer's total rounds on this "
-        "pull request, the same count `status` prints as `rounds=`, exceed N. Pass the "
-        "`rounds=` a prior `status` already read, after re-requesting a review on a head that "
-        "already carries one: `reviewed_head` alone would report that earlier round as done "
-        "at once, never waiting for the fresh one the re-request was for. N is the count "
-        "already seen, not the count to reach: on a pull request reading `rounds=3`, N=3 "
-        "waits for the fourth round and N=4 for a fifth (default 0, so any round counts, "
-        "unchanged from before this flag existed)",
-    )
-    # `reply` takes the finding's words, and there is no argument an id fits in.
-    ap.add_argument(
-        "--match",
-        metavar="TEXT",
-        help="reply: words from the finding, matched against the thread's opening "
-        "comment, and required to select exactly one unresolved thread",
-    )
-    ap.add_argument(
-        "--path",
-        metavar="FILE",
-        help="reply: narrow --match to one file, for a file with several findings",
-    )
-    ap.add_argument(
-        "--all-identical",
-        action="store_true",
-        help="reply: where --match selects several threads whose opening comments read the "
-        "same, a finding posted twice, answer each of them with --body rather than refusing",
-    )
-    ap.add_argument(
-        "--body",
-        metavar="TEXT",
-        help="comment or reply: the answer to post, carrying the fixing commit SHA or "
-        "the evidence that disproves the finding",
-    )
-    ap.add_argument("--fingerprint", help="comment: acknowledge the unplaced set it names")
-    ap.add_argument(
-        "--resolve",
-        action="store_true",
-        help="reply: resolve the thread once the reply is confirmed",
-    )
-    ap.add_argument(
-        "--checkout",
-        metavar="DIR",
-        help="attest: the checkout holding the pull request's head and its recorded local pass "
-        "(default the current directory)",
-    )
-    a = ap.parse_args(args)
-    # Named for the command they belong to, since an ignored flag reads as one that took effect.
-    reply_only = {
-        "--match": a.match,
-        "--path": a.path,
-        "--resolve": a.resolve or None,
-        "--all-identical": a.all_identical or None,
-    }
-    if a.cmd != "reply":
-        for flag, value in reply_only.items():
-            if value is not None:
-                ap.error(f"{flag} belongs to `reply`, not `{a.cmd}`")
-    if a.cmd != "wait" and a.request:
-        ap.error(f"--request belongs to `wait`, not `{a.cmd}`")
-    if a.cmd == "cleanup":
-        ap.error("`cleanup` takes its arguments after it, as `cleanup NUMBER --repo OWNER/NAME`")
-    if a.cmd != "attest" and a.checkout is not None:
-        ap.error(f"--checkout belongs to `attest` or `cleanup`, not `{a.cmd}`")
-    if a.number is None:
-        ap.error("the following arguments are required: number")
-    if a.cmd != "comment" and a.fingerprint is not None:
-        ap.error(f"--fingerprint belongs to `comment`, not `{a.cmd}`")
-    if a.cmd not in ("comment", "reply") and a.body is not None:
-        ap.error(f"--body belongs to `comment` or `reply`, not `{a.cmd}`")
-    required = ["--body"] + (["--match"] if a.cmd == "reply" else [])
-    if a.cmd in ("comment", "reply"):
-        values = {"--body": a.body, "--match": a.match}
-        for flag in required:
-            if not (values[flag] or "").strip():
-                ap.error(
-                    f"{a.cmd} requires a non-empty {flag}, since an empty answer records nothing"
-                )
-    if a.pickup_grace < 0:
-        ap.error("--pickup-grace cannot be negative")
-    if a.min_rounds < 0:
-        ap.error("--min-rounds cannot be negative")
-    # A negative threshold would report every check in that state on every run.
-    for name in ("check_grace", "check_stall"):
-        if getattr(a, name) < 0:
-            ap.error(f"--{name.replace('_', '-')} cannot be negative")
-    # The two thresholds mean opposite things and the readings invert if the order does.
-    if a.check_grace >= a.check_stall:
-        ap.error(
-            "--check-grace must be less than --check-stall, since a queued check is "
-            f"judged sooner than a running one (got {a.check_grace} and {a.check_stall})"
-        )
-    # A bare name is the near-miss a required argument still admits, and unpacking it raises a
-    # ValueError traceback rather than saying which half is missing.
-    owner, _, repo = a.repo.partition("/")
-    if not owner or not repo or "/" in repo:
-        ap.error(f"--repo takes OWNER/NAME, not {a.repo!r}")
-
-    if a.cmd == "claims":
-        return check_claims(owner, repo, a.number)
-
-    if a.cmd == "attest":
-        return attest(owner, repo, a.number, a.checkout or ".")
-
-    if a.cmd == "comment":
-        marker = f"\n\n{ACK_MARKER.format(a.fingerprint)}" if a.fingerprint else ""
-        return comment_on_pr(owner, repo, a.number, a.body.strip() + marker)
-
-    if a.cmd == "status":
-        # One payload renders the digest and decides the code, as in `wait`.
-        pr = full_read(owner, repo, a.number)
-        out, _ = digest(owner, repo, a.number, pr=pr, grace=a.check_grace, stall=a.check_stall)
-        print(out)
-        return report_verdict(pr)
-
-    if a.cmd == "reply":
-        return reply_to_thread(
-            owner, repo, a.number, a.match, a.body, a.path, a.resolve, a.all_identical
-        )
-
+def run_wait(owner: str, repo: str, a: argparse.Namespace) -> int:
+    """Request a review where one is owed, poll until it lands or the timeout, and return the code."""
     # `wait` mutates through the auto-request, so a cross-owner target is refused before the read as well.
     ok, why = in_scope(owner)
     if not ok:
@@ -1908,5 +1724,201 @@ def held_read() -> dict:
     return 30
 
 
+COMMANDS = ("attest", "claims", "cleanup", "comment", "status", "reply", "wait")
+# Each flag listed is refused on a subcommand not owning it, since an ignored flag reads as one that took effect.
+# A late row is checked after the `cleanup` and `number` checks, which fixes the first error printed.
+# `cleanup` owns `--checkout` only once it has dispatched, so its row here only defers to that check.
+FLAG_OWNERS = (
+    ("--match", ("reply",), False),
+    ("--path", ("reply",), False),
+    ("--resolve", ("reply",), False),
+    ("--all-identical", ("reply",), False),
+    ("--request", ("wait",), False),
+    ("--checkout", ("attest", "cleanup"), False),
+    ("--fingerprint", ("comment",), True),
+    ("--body", ("comment", "reply"), True),
+)
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = sys.argv[1:] if argv is None else argv
+    pre = argparse.ArgumentParser(add_help=False)
+    pre.add_argument("first", nargs="?")
+    for flag in ("--repo", "--checkout", "--min-age-hours"):
+        pre.add_argument(flag)
+    if pre.parse_known_args(args)[0].first == "cleanup":
+        sys.modules.setdefault("pr_review", sys.modules[__name__])
+        import pr_cleanup
+
+        rest = list(args)
+        rest.remove("cleanup")
+        return pr_cleanup.main(rest)
+    utf8_console()
+    ap = argparse.ArgumentParser()
+    ap.add_argument("cmd", choices=COMMANDS)
+    ap.add_argument("number", type=int, nargs="?")
+    # No default, because a default names one repository and every run from elsewhere would read that one.
+    ap.add_argument(
+        "--repo",
+        required=True,
+        metavar="OWNER/NAME",
+        help="the repository the pull request is in, since a pull "
+        "request number identifies no repository on its own",
+    )
+    ap.add_argument("--timeout", type=int, default=2700, help="seconds (default 45m)")
+    ap.add_argument(
+        "--pickup-grace",
+        type=int,
+        default=300,
+        help="deprecated compatibility option, accepted but ignored",
+    )
+    ap.add_argument(
+        "--check-grace",
+        type=int,
+        default=CHECK_GRACE,
+        help="seconds a check may sit queued, or a required status go unposted, "
+        f"before either reads as unstarted (default {CHECK_GRACE // 60}m)",
+    )
+    ap.add_argument(
+        "--check-stall",
+        type=int,
+        default=CHECK_STALL,
+        help="seconds a check may run before its duration is reported "
+        f"(default {CHECK_STALL // 60}m)",
+    )
+    ap.add_argument(
+        "--ignore-quota-signal",
+        action="store_true",
+        help="wait: request and poll the full --timeout even where the reviewer's own most "
+        "recent activity elsewhere in this repository is a quota-limit refusal with nothing "
+        "answering it since, or this pull request's newest Copilot review is a quota or "
+        "error refusal, pass this once the quota is believed to have reset",
+    )
+    ap.add_argument(
+        "--request",
+        action="store_true",
+        help="wait: request a Copilot round even on a pull request into a branch other than the "
+        "default, which an attested local pass otherwise covers",
+    )
+    ap.add_argument(
+        "--min-rounds",
+        type=int,
+        default=0,
+        metavar="N",
+        help="wait: treat the head as covered only once the reviewer's total rounds on this "
+        "pull request, the same count `status` prints as `rounds=`, exceed N. Pass the "
+        "`rounds=` a prior `status` already read, after re-requesting a review on a head that "
+        "already carries one: `reviewed_head` alone would report that earlier round as done "
+        "at once, never waiting for the fresh one the re-request was for. N is the count "
+        "already seen, not the count to reach: on a pull request reading `rounds=3`, N=3 "
+        "waits for the fourth round and N=4 for a fifth (default 0, so any round counts, "
+        "unchanged from before this flag existed)",
+    )
+    # `reply` takes the finding's words, and there is no argument an id fits in.
+    ap.add_argument(
+        "--match",
+        metavar="TEXT",
+        help="reply: words from the finding, matched against the thread's opening "
+        "comment, and required to select exactly one unresolved thread",
+    )
+    ap.add_argument(
+        "--path",
+        metavar="FILE",
+        help="reply: narrow --match to one file, for a file with several findings",
+    )
+    ap.add_argument(
+        "--all-identical",
+        action="store_true",
+        help="reply: where --match selects several threads whose opening comments read the "
+        "same, a finding posted twice, answer each of them with --body rather than refusing",
+    )
+    ap.add_argument(
+        "--body",
+        metavar="TEXT",
+        help="comment or reply: the answer to post, carrying the fixing commit SHA or "
+        "the evidence that disproves the finding",
+    )
+    ap.add_argument("--fingerprint", help="comment: acknowledge the unplaced set it names")
+    ap.add_argument(
+        "--resolve",
+        action="store_true",
+        help="reply: resolve the thread once the reply is confirmed",
+    )
+    ap.add_argument(
+        "--checkout",
+        metavar="DIR",
+        help="attest: the checkout holding the pull request's head and its recorded local pass "
+        "(default the current directory)",
+    )
+    a = ap.parse_args(args)
+
+    def refuse_foreign(late: bool) -> None:
+        for flag, owners, row_late in FLAG_OWNERS:
+            value = getattr(a, flag.removeprefix("--").replace("-", "_"))
+            if (
+                row_late is late
+                and a.cmd not in owners
+                and value is not None
+                and value is not False
+            ):
+                ap.error(
+                    f"{flag} belongs to {' or '.join(f'`{o}`' for o in owners)}, not `{a.cmd}`"
+                )
+
+    refuse_foreign(late=False)
+    if a.cmd == "cleanup":
+        ap.error("`cleanup` takes its arguments after it, as `cleanup NUMBER --repo OWNER/NAME`")
+    if a.number is None:
+        ap.error("the following arguments are required: number")
+    refuse_foreign(late=True)
+    required = ["--body"] + (["--match"] if a.cmd == "reply" else [])
+    if a.cmd in ("comment", "reply"):
+        values = {"--body": a.body, "--match": a.match}
+        for flag in required:
+            if not (values[flag] or "").strip():
+                ap.error(
+                    f"{a.cmd} requires a non-empty {flag}, since an empty answer records nothing"
+                )
+    # None of these four takes a negative value, and a negative check threshold reports every check stuck.
+    for name in ("pickup_grace", "min_rounds", "check_grace", "check_stall"):
+        if getattr(a, name) < 0:
+            ap.error(f"--{name.replace('_', '-')} cannot be negative")
+    # The two thresholds mean opposite things and the readings invert if the order does.
+    if a.check_grace >= a.check_stall:
+        ap.error(
+            "--check-grace must be less than --check-stall, since a queued check is "
+            f"judged sooner than a running one (got {a.check_grace} and {a.check_stall})"
+        )
+    # A bare name is the near-miss a required argument still admits, and unpacking it raises a
+    # ValueError traceback rather than saying which half is missing.
+    owner, _, repo = a.repo.partition("/")
+    if not owner or not repo or "/" in repo:
+        ap.error(f"--repo takes OWNER/NAME, not {a.repo!r}")
+
+    if a.cmd == "claims":
+        return check_claims(owner, repo, a.number)
+
+    if a.cmd == "attest":
+        return attest(owner, repo, a.number, a.checkout or ".")
+
+    if a.cmd == "comment":
+        marker = f"\n\n{ACK_MARKER.format(a.fingerprint)}" if a.fingerprint else ""
+        return comment_on_pr(owner, repo, a.number, a.body.strip() + marker)
+
+    if a.cmd == "status":
+        # One payload renders the digest and decides the code, as in `wait`.
+        pr = full_read(owner, repo, a.number)
+        out, _ = digest(owner, repo, a.number, pr=pr, grace=a.check_grace, stall=a.check_stall)
+        print(out)
+        return report_verdict(pr)
+
+    if a.cmd == "reply":
+        return reply_to_thread(
+            owner, repo, a.number, a.match, a.body, a.path, a.resolve, a.all_identical
+        )
+
+    return run_wait(owner, repo, a)
+
+
 if __name__ == "__main__":
     sys.exit(main())
diff --git a/tests/test_pr_review.py b/tests/test_pr_review.py
index e1522b9b..d0cbff72 100755
--- a/tests/test_pr_review.py
+++ b/tests/test_pr_review.py
@@ -5301,6 +5301,58 @@ def test_a_writing_option_on_a_reading_command_is_an_error(self) -> None:
             with self.subTest(flag=flag[0]):
                 self.assertIn(flag[0], self.err(["status", "7", "--repo", "o/r", *flag]))
 
+    def test_a_command_line_with_two_bad_flags_names_the_same_one_first(self) -> None:
+        """Each expected line was printed before the ownership checks became `FLAG_OWNERS`."""
+        cases = (
+            (
+                ["status", "7", "--repo", "o/r", "--body", "b", "--match", "x"],
+                "--match belongs to `reply`, not `status`",
+            ),
+            (
+                ["status", "--repo", "o/r", "--fingerprint", "f", "--checkout", "."],
+                "--checkout belongs to `attest` or `cleanup`, not `status`",
+            ),
+            (
+                ["status", "--repo", "o/r", "--fingerprint", "f", "--body", "b"],
+                "the following arguments are required: number",
+            ),
+            (
+                [
+                    "--timeout",
+                    "5",
+                    "cleanup",
+                    "7",
+                    "--repo",
+                    "o/r",
+                    "--checkout",
+                    ".",
+                    "--body",
+                    "b",
+                ],
+                "`cleanup` takes its arguments after it, as `cleanup NUMBER --repo OWNER/NAME`",
+            ),
+            (
+                ["wait", "7", "--repo", "o/r", "--min-rounds", "-1", "--pickup-grace", "-1"],
+                "--pickup-grace cannot be negative",
+            ),
+            (
+                ["wait", "7", "--repo", "o/r", "--check-stall", "-1", "--request", "--body", "b"],
+                "--body belongs to `comment` or `reply`, not `wait`",
+            ),
+        )
+        for argv, first in cases:
+            with self.subTest(argv=argv):
+                self.assertTrue(self.err(argv).strip().endswith(f"error: {first}"), argv)
+
+    def test_every_owner_in_the_table_is_a_subcommand(self) -> None:
+        """A misspelled owner would refuse its flag on the one command it belongs to."""
+        commands = set(pr_review.COMMANDS)
+        # A floor, since an emptied table would pass the subset check below.
+        self.assertGreaterEqual(len(pr_review.FLAG_OWNERS), 8)
+        for flag, owners, _ in pr_review.FLAG_OWNERS:
+            with self.subTest(flag=flag):
+                self.assertLessEqual(set(owners), commands)
+
 
 PIN = "actions/checkout@" + "9" * 40