feat(ci): label fresh PRs waiting-for-review once they clear the bar

[dhruv0811]

Related issue

Part of OMNI-2214 / OMNI-2315. Closes the last gap in the review-state machine;
this PR declares Test / CI below, which is one of the exempt types.

Summary

waiting-for-review had exactly one entrance: hand_off_to_reviewer, which fires
when an author replies to feedback on a PR already carrying waiting-on-author.

A PR nobody had touched yet therefore sat in neither state. That is why 478 of
479 currently-open PRs carry no review-state label, and why the label cannot yet be
used as the review queue it was built to be. A fresh PR that references an issue
should be labelled ready, and today nothing does that.

This adds a sweep step that applies the label to PRs clearing the bar.

The bar today is just "references an issue." It reuses pr-issue-link.js's
resolution (closing links, sidebar links, and Part of / Related to / Towards
/ Refs pointing at a real issue), so the gate and the nudge can never disagree
about what counts. It is designed to rise: CI green, demo present, Polly clean each
become one more predicate in belowBar, and nothing else changes.

Never applied when:

• the PR is a draft (the author is telling us it is not ready)
• waiting-on-author is set (the ball is in the author's court, and applying both
  would break the mutual exclusion the pair relies on)
• the label is already there (idempotent)
• a human removed it before. A maintainer who takes the label off is saying
  "not ready"; an hourly sweep that reapplies it would be arguing with them. An
  unrelated label removal is ignored.

Forward-only, sharing EFFECTIVE_FROM with the issue-link check: labelling 478
backlog PRs in one sweep would bury the signal the label exists to create.

Ships dry-run (ENFORCE: "false"), consistent with how the nudge shipped.

Test Plan

• node .github/workflows/ready-for-review.test.js passes. 12 cases: a closing
  link clears the bar; Part of #N to a real issue clears it; a reference to a
  PR does not; no reference does not; drafts skip; waiting-on-author wins;
  idempotent; a prior manual removal is respected while an unrelated removal is
  ignored; a dry run reports READY without labelling; an unverifiable link
  lookup fails closed; and the effective date is shared with the issue-link module.

• Verified against production with the label write rigged to throw, so
  "nothing was touched" is proven rather than assumed:

  Found 26 open PRs in the window
  Done (enforce=false). READY=4 below bar=20 skip=2
  

  The 4 ready are fix(pi-native): carry catalog token limits into the pi-native model list #4178, Persist custom agent reasoning effort for bundled sessions #4128, feat(web): keep conversation streams open in the background #4113, fix(datetime): make timezone handling explicit #4095. Note fix(datetime): make timezone handling explicit #4095 is the Refs #3644 PR
  from the earlier Part of fix, so that change flows through to the gate as
  intended. fix(python-client): fail loud when a stream opens on a redirect #4173 comes back below bar (no issue referenced), matching the nudge's
  verdict on the same PR. No write was attempted.

• A new ready-for-review-test.yml runs the unit test on any PR touching the
  script, its test, or the issue-link module it reuses.

Demo

N/A. CI label mechanics, no user-visible UI.

Type of change

• Bug fix
• Feature
• UI / frontend change
• Refactor / chore
• Docs
• Test / CI
• Breaking change

Test coverage

• Unit tests added or updated
• Integration / E2E tests added or updated
• Manual verification completed
• Not applicable

Coverage notes

Unit tests cover every predicate and exclusion. Manual verification was running the
shipped script against live GitHub with the label write rigged to throw, confirming
both the verdict set and that nothing was written.

Follow-up

Once this is enforcing, CONTRIBUTING can state that reviewers work the
waiting-for-review queue. It deliberately does not say that today, because the
label was not yet applied to fresh PRs and the doc would have read as "we will
never review your PR."

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[dhruv0811]

/review

[omnigent-ci]

Polly AI Review

Blocking issues

removedBefore ignores the actor, so the bot's own mutual-exclusion removal permanently disqualifies a PR. In ready-for-review.js:

function removedBefore(pr) {
  const events = pr.timelineItems?.nodes ?? [];
  return events.some((e) => e?.label?.name === REVIEW_LABEL);
}

The GraphQL query selects actor { login } on each UnlabeledEvent, and the doc comment states the intent explicitly — "a maintainer who takes it off is saying 'not ready'", "an unrelated label removal is ignored". But the function only matches on label name; it never inspects the actor. That matters because this repo's own automation removes exactly this label: .github/scripts/waiting_on_author.py::clear_review_label_on_waiting deletes waiting-for-review whenever waiting-on-author is applied (the mutual-exclusion pair). That deletion is performed by github-actions[bot] and is recorded as an UnlabeledEvent for waiting-for-review.

Reachable sequence:

1. Sweep labels a fresh PR waiting-for-review.
2. A maintainer engages → waiting-on-author applied → bot removes waiting-for-review (UnlabeledEvent, actor = bot).
3. The waiting-on-author state is later cleared without an author-activity handoff (e.g. a maintainer removes it manually).
4. PR is now in neither state — exactly the gap this PR exists to close — but removedBefore returns true forever, so the sweep will never re-label it.

So the bot's routine state transition is misread as a human "not ready" signal, silently and permanently excluding the PR from the very queue this change builds. The fix is to filter to human actors (exclude [bot] logins / the workflow bot) before treating a removal as intentional — which is what the query already fetches the actor for. Note the test suite (cases #17/#18) only exercises human-attributed removals, so this path is untested.

Security vulnerabilities

None. Actions are pinned by SHA; the sweep runs from the trusted default-branch checkout (never PR head), the test workflow uses persist-credentials: false with contents: read only, and no secrets are read or emitted. Label writes require the issues: write already granted to the demo-check job.

Non-blocking notes

• Dead field / self-documenting gap. actor { login } is queried but never referenced anywhere. Once the blocking issue above is addressed it becomes live; if you deliberately keep name-only matching, drop the actor selection so the code and comment stop implying an actor check that doesn't happen.
• Partial sweep on write failure. A thrown addLabels (non-429) aborts the loop mid-run, labelling a prefix of the ready set and skipping the rest. Harmless given idempotency and hourly re-runs, but worth a per-PR try/catch so one failure doesn't stop the sweep (mirrors the resilience close_stale_waiting_prs has in the Python script).
• referencesIssue resolves cross-repo owner/repo#N refs against the local repo (same as pr-issue-link.js), so a Refs other/repo#5 could match a coincidental local issue Sync 🌊: 48 upstream changes #5. Consistent with the existing nudge, so not a regression — flagging only for awareness.

Summary

Well-scoped, well-tested addition that correctly reuses pr-issue-link.js resolution, honors the draft / waiting-on-author / idempotency exclusions, and ships safely in dry-run behind pinned actions with least-privilege permissions. The one real problem is removedBefore: it claims to respect only human removals but matches any removal, and this repo's mutual-exclusion bot removes precisely this label — so a common lifecycle transition can permanently disqualify a PR from the queue the feature is meant to populate. Filter the removal check to human actors (the actor is already fetched) and add a bot-removal test case; the rest is ready.

---

_{Automated review by Polly · workflow run}

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[dhruv0811]

/review

[dhruv0811]

/review

[dhruv0811]

/review

[omnigent-ci]

Polly AI Review

Blocking issues

None. The logic is correct and the test suite passes. I applied the patch locally and ran node .github/workflows/ready-for-review.test.js — all assertions pass. I verified the specifics that matter most:

• The new Ready-for-review gate step is appended to the demo-check job, which already declares issues: write / pull-requests: write, so addLabels has the permission it needs. if: always() keeps it independent of the earlier steps.
• The demo-check job checks out sparse-checkout: .github on the default branch, so both ready-for-review.js and its require("./pr-issue-link.js") dependency are present, and no PR-authored code runs.
• removedByHuman correctly excludes the github-actions[bot] self-removal that waiting_on_author.py performs on every waiting-on-author transition (REVIEW_LABEL not in labels → remove), which would otherwise permanently disqualify most PRs. The endsWith("[bot]") actor check is the right guard and is directly exercised by the #181 / #182 tests.
• Fail-closed behavior is consistent: a LINK_QUERY error returns false (below bar, no label) and an unresolvable tracking-reference lookup is swallowed and skipped — matching the nudge's contract so the gate and nudge can't disagree.
• Rate-limit 429s re-throw out of the per-PR addLabels catch and are handled by the top-level graceful exit.

Security vulnerabilities

None. The new ready-for-review-test.yml runs the PR's own code but uses the safe pattern: pull_request (not pull_request_target), permissions: contents: read only, persist-credentials: false, no secrets, and the test is fully mocked/offline. The label-writing script only ever runs from the trusted default-branch checkout in the scheduled sweep. No injection, secret exposure, or boundary weakening.

Non-blocking notes

• 24h rolling window can miss late-linked PRs. The sweep searches is:open created:>cutoff with a 24h window (shared with the nudge). A PR that opens without an issue reference and then adds one on day 2+ has already aged out of the window, so it will never enter the waiting-for-review queue via this sweep — its only entrance remains hand_off_to_reviewer. Since the stated goal is "a queue of reviewable PRs," this is a small gap worth being aware of; it's consistent with the existing nudge design, so it's fine to defer.
• removedByHuman is a permanent disqualification. As the code comments acknowledge, a single historical human removal permanently opts a PR out of the sweep even after substantial revision. Intended, but worth noting for when the bar rises (CI-green/demo/Polly predicates) — a stale "not ready" signal will suppress re-labelling.
• timelineItems(last: 50, itemTypes: [UNLABELED_EVENT]) is uncapped-safe only up to 50 events. A very churny PR with >50 unlabel events could push an older human removal out of view. Extremely unlikely on fresh PRs; no action needed.

Summary

A tight, well-scoped CI addition that closes the fresh-PR entrance to waiting-for-review. It correctly reuses the nudge's issue-resolution logic, handles the bot-vs-human removal distinction that would otherwise poison the gate, fails closed on unverifiable lookups, ships dry-run by default, and is backed by a thorough 12-case offline test plus a safe PR-triggered test workflow. No blocking or security issues. Ready to merge once maintainers are comfortable flipping ENFORCE to "true" after reviewing the dry-run summary.

---

_{Automated review by Polly · workflow run}

[github-actions]

🏷️ Doc impact: no-doc-update

Adds a CI-only GitHub Actions "ready-for-review" labeling gate plus its workflow and unit tests, an internal maintainer tooling change with no user-facing surface or integration affected.

_{Auto-classified on merge. Set the label manually before merging to override. · run}