Proposed work: add review-bounty candidate selection report

[xyjk0511]

This is not a live MRWK bounty. Opening this issue does not reserve MRWK,
create a payout, or make implementation work claimable.

Related proposed-work bounty: #649

Problem

Review-bounty rounds such as #643 ask contributors to review open MergeWork PRs
with current-head evidence. The hard part is not only writing the review; it is
choosing a PR where a new review is actually useful and likely non-duplicate.

During the current round, that candidate selection is still mostly manual:

• some PRs are authored by the would-be reviewer and should be excluded;
• some PRs already have a current-head human review from the same reviewer;
• some PRs already have enough duplicate human reviews and are waiting for the
  author to update the branch;
• some PRs are dirty, mrwk:needs-info, or missing the standard quality
  workflow, so the useful next action is not another review comment;
• some PRs need a fresh current-head review only after headRefOid changes.

Without a compact candidate report, agents can waste review-bounty capacity on
repeating existing comments, and maintainers have to explain why the review was
not useful enough for payment.

Evidence

Current live examples from ramimbo/mergework on 2026-05-31:

• Fix async task queue timeout handling #668 has current-head change-request reviews already covering the key
  blockers: no runtime wiring, no tests, failing quality checks, and wrong
  Closes #601 linkage. Another review now would mostly duplicate them.
• Clarify MRWK claim-window checks in PR template #662 has a concrete review gap already posted by Gwani-28: the PR template
  adds five checklist items, while docs smoke protects only four. It is also
  UNSTABLE with only CodeRabbit status. A new review before an author update
  would repeat the same finding.
• Clarify live bounty claim checks in contributing guide #669 already has a current-head review and approval. The maintainer-facing
  blocker is the missing standard quality/docs workflow status, not lack of
  more human review.
• Add treasury proposal filters and links #639 is DIRTY and already has reviews saying the next step is to rebase or
  resolve the docs/api-examples.md conflict.
• docs: show effective bounty availability in API examples #685, Clarify security bounty proof status #689, docs: clarify non-PR bounty submissions #690, and Flag non-live bounty references in queue health #675 have already received current-head review work in
  this round, so they should not keep appearing as high-value candidates for the
  same reviewer unless their head SHA changes.

The existing queue-health tooling reports merge instability, needs-info state,
non-live bounty references, duplicate bounty scopes, and related queue risks.
It does not answer the review-bounty-specific question: "For this reviewer,
which open PRs are still worth a fresh evidence-backed review right now?"

Proposed work

Add a read-only review-bounty candidate report, either as a small new script
such as scripts/review_bounty_candidates.py or as a focused mode in
scripts/pr_queue_health.py.

The report should accept a reviewer login and summarize open PRs into advisory
states such as:

• candidate_for_fresh_review
• self_authored
• already_reviewed_current_head_by_reviewer
• already_has_sufficient_current_head_human_reviews
• waiting_for_author_update
• dirty_or_conflicted
• missing_standard_quality_check
• needs_info

For each PR, include the PR number, title, author, current headRefOid, merge
state, relevant labels, standard quality-check status, latest useful human
review state/commit, and a short reason.

The report should stay advisory. It should not auto-comment, auto-label,
auto-close, accept claims, reject claims, create bounties, or pay anything.

Expected value

This gives maintainers and reviewers a clear preflight before review-bounty
work starts. It reduces duplicate reviews, makes "wait for author update" cases
obvious, and helps contributors spend review time on PRs where current-head
evidence is still useful.

It also gives maintainers a reusable way to explain review-bounty acceptance:
the review was for an eligible current-head candidate, or it was not.

Reference tier

100-500 MRWK: useful issue, test, docs page, small bugfix

Possible acceptance criteria

• A read-only report can be generated for open PRs with a --reviewer LOGIN
  option.
• The report excludes or downgrades PRs authored by that reviewer.
• The report detects when that reviewer already reviewed the current head.
• The report distinguishes "needs fresh review" from "waiting for author update"
  when existing current-head reviews already identify blockers.
• The report surfaces dirty/conflicted PRs, mrwk:needs-info, and missing
  standard quality-check status as reasons a new review may not be the best
  next action.
• Markdown and JSON output are supported, or one output plus tests if
  maintainers want a smaller first slice.
• Existing queue-health behavior remains unchanged unless maintainers choose to
  integrate this as a mode.

Evidence or tests required

• Fixture test for a PR authored by the configured reviewer.
• Fixture test for a PR already reviewed by the configured reviewer at the
  current head.
• Fixture test for a PR whose latest human review is stale because the head SHA
  changed.
• Fixture test for a PR with enough current-head human reviews and no author
  update yet.
• Fixture test for dirty/missing-standard-CI/needs-info advisory reasons.
• ruff check, ruff format --check, focused pytest, and docs smoke if docs
  are touched.
• Optional live smoke against ramimbo/mergework that produces only read-only
  output.

Duplicate search

Related but distinct:

• Proposed work: Add proposed-work intake triage report #672 proposes a proposed-work intake triage report, not a PR review-bounty
  candidate selector.
• Proposed work: flag stale current-head reviews in queue health #679 proposes stale current-head review detection inside queue health; this
  proposal uses that kind of signal as one input but answers the broader
  reviewer-specific candidate-selection question.
• Proposed work: Flag bounty PRs missing the standard quality check #692 proposes flagging PRs missing the standard quality workflow; this
  proposal treats that as one advisory reason among several review-bounty
  eligibility reasons.
• Proposed work: expose active-attempt summary on bounty API rows #677 covers active-attempt summaries on bounty rows, not PR review candidate
  selection.
• Proposed work: expose structured submission mode for non-PR bounties #676 covers structured submission modes for non-PR bounties, not open PR
  review selection.
• MRWK bounty: 250 MRWK - flag PRs that reference non-live bounty issues #645/Flag non-live bounty references in queue health #660/Flag non-live bounty references in queue health #675 cover non-live bounty references in PR queue health, not
  whether a fresh human review by a specific reviewer is still useful.

I did not find an existing proposed-work issue whose main output is a
reviewer-specific list of open PRs that are currently worth fresh #643-style
review-bounty work.

Out of scope

• No automatic GitHub comments, labels, claim submissions, bounty creation,
  acceptance decisions, or payments.
• No subjective review-quality scoring beyond objective freshness and queue
  signals.
• No treasury proposal, wallet, balance, proof, ledger, exchange, bridge, or
  cash-out behavior changes.
• No private data, credentials, private security details, or fabricated payout
  claims.

[ramimbo]

Maintainer cleanup: implemented by #743 and present on current main in scripts/review_bounty_candidates.py. The proposed-work intake item is queued under #649 as pending treasury proposal #98; it is not paid until execution creates a proof. Closing as implemented.