feat: implement issue #680 — pr-auto-review ready-check counts non-required/cancelled checks → false 'not passing', blocks auto-dispatch

[don-petry]

Closes #680

Implemented by dev-lead agent. Please review.

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, you can upgrade your account or add credits to your account and enable them for code reviews in your settings.

[coderabbitai]

Warning

Review limit reached

@don-petry, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 36 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: fc5d67dc-3b0b-402f-b90c-8ccdb394aab4

📥 Commits

Reviewing files that changed from the base of the PR and between 5209dd7 and 5dbc9b0.

📒 Files selected for processing (6)

• .github/scripts/pr-auto-review/README.md
• .github/scripts/pr-auto-review/lib/ready-check.sh
• .github/workflows/pr-auto-review-reusable.yml
• .github/workflows/pr-auto-review-tests.yml
• test/workflows/pr-auto-review/helpers/setup.bash
• test/workflows/pr-auto-review/ready-check.bats

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch dev-lead/issue-680-20260712-1641

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[don-petry]

Dev-Lead — review-changes (no-changes)

No changes were needed for this PR.

[don-petry]

Dev-Lead — fix-bot-comment (no-changes)

Agent reasoning

Issues addressed: 0
Files changed: none
Skipped (informational): 0
Summary: Quality Gate passed with 0 new issues, 0 accepted issues, and 0 security hotspots — no actionable changes required.
```
The PR is ready to merge from a quality/compliance perspective. The only in-progress check is "Analyze (actions)" — once that completes, all checks should be green.

[gemini-code-assist]

Code Review

This pull request introduces the pr-auto-review helper scripts and associated bats tests to determine whether a PR's CI checks satisfy the passing-gate before dispatching the review agent. The review feedback focuses on enhancing the robustness of the jq parsing logic within ready-check.sh to prevent fatal errors when dealing with null, missing, or malformed JSON payloads, along with adding corresponding test coverage in the bats suite.

[don-petry]

Dev-Lead — fix-reviews (applied)

Changes committed and pushed.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[don-petry]

Dev-Lead — review-changes (no-changes)

No changes were needed for this PR.

[donpetry-bot]

Automated review — APPROVED ✓

Risk: MEDIUM
Reviewed commit: 5dbc9b0eebe5bf08dc83f3e5107998c96f97df5a
Review mode: triage-approved (single reviewer)

Summary

Implements issue #680 (option A with option B fallback): the pr-auto-review ready-check now gates auto-dispatch on the base branch's REQUIRED status-check contexts only, so non-required/cancelled advisory contexts (e.g. superseded dev-lead / ci-relay runs) no longer block dispatch. Decision logic is extracted into a pure, side-effect-free bash/jq helper with a 16-case bats suite and a new CI workflow gate, following the house Layer-0 pattern. All CI green, all review threads resolved, triage assessment confirmed.

Linked issue analysis

Closes #680 — pr-auto-review ready-check counts non-required/cancelled checks as "not passing", blocking auto-dispatch.

All acceptance criteria are met:

• Non-required/cancelled advisory contexts no longer block: pr_auto_review_checks_ready gates on the branch ruleset's required contexts only (fetched via GET /repos/{owner}/{repo}/rules/branches/{branch}); the exact #678 repro (cancelled dev-lead / ci-relay + dev-lead / dispatch alongside green required checks) is pinned by a dedicated bats test.
• Required-check failure/pending still blocks: failing, pending, cancelled, and not-yet-reported required contexts each return not-ready (all tested).
• Decision logic unit-tested: logic lives in .github/scripts/pr-auto-review/lib/ready-check.sh (pure functions) with test/workflows/pr-auto-review/ready-check.bats (16 tests) run by the new pr-auto-review-tests.yml workflow, which triggered and passed on this PR.
• The issue's recommended option A was implemented, with option B (fail/pending-only gate, cancel non-blocking) as the documented fallback when no required contexts are configured — matching the issue's guidance.

Findings

No blocking findings.

Security review of the workflow changes (all clean):

• New checkout step: actions/checkout pinned to 9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0, verified via the GitHub API as the exact commit for tag v7.0.0 (repo standard: SHAs looked up, not guessed).
• GH_PAT_WORKFLOWS is already a declared secret of this reusable workflow on main (used for GH_TOKEN in existing steps) — no new credential surface. persist-credentials: false is set, and the checkout ref is github.job_workflow_sha (the reusable's own pinned commit), so the sourced script always matches the pinned workflow version and cannot be swapped by a caller.
• No script-injection vectors: BASE_BRANCH comes from trusted gh pr view output and is used as a quoted API path argument; REQUIRED_JSON is jq-produced compact JSON passed via --argjson with [] fallbacks on API/parse failure.
• Secret scan: run_secret_scanning MCP tool not available in this environment; gitleaks CI check passed. No secrets in the diff.

Correctness notes (non-blocking):

• The name-matching heuristic (bare context vs "workflow / job", suffix match in both directions) could in theory match a same-named job from a different workflow, but this is documented in the README and is the pragmatic trade-off given how rulesets store contexts.
• Robustness feedback from the prior gemini review (null .parameters, non-string .name/contexts, empty-arg defaults) was applied in commit 5dbc9b0 and is covered by tests; all 4 review threads are resolved.

CI status

All checks green at 5dbc9b0eebe5bf08dc83f3e5107998c96f97df5a: CI (Lint, ShellCheck, Secret scan/gitleaks, Agent Security Scan), CodeQL (Analyze actions), SonarCloud (Quality Gate passed: 0 new issues, 0 hotspots), AgentShield, Dependency audit, PR Auto-Review Tests (Lint and bats — new gate introduced by this PR), CodeRabbit. Skipped: dependabot-automerge, ecosystem-specific audits, dev-lead ci-relay (expected). Mergeable: MERGEABLE; merge state BLOCKED only on the pending review decision.

---

Reviewed automatically by the PR-review agent (single-reviewer mode: fable 5). Reply if you need a human review.