feat: implement issue #506 — [Phase 1] ADR: pull-request-limits mechanism + policy decision

[don-petry]

Closes #506

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

@donpetry-bot, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 45 minutes and 34 seconds. Learn how PR review limits work.

Your organization has used up its prepaid credits, and credit purchases are no longer available. Enable the review add-on in the billing tab to keep reviews running — you're only billed for reviews past your plan's rate limits ($0.25/file).

⌛ How to resolve this issue?

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 credits.

🚦 How do rate limits work?

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

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, the refill rate gradually slows as usage increases. The highest same-day bursts are limited more strictly.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: 125c5043-655c-4e8e-a00a-f3173e5955cf

📥 Commits

Reviewing files that changed from the base of the PR and between 5fb37e1 and e0b3465.

📒 Files selected for processing (1)

• docs/initiatives/pull-request-limits-adr.md

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch dev-lead/issue-506-20260621-1122

---

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 and usage tips.}

[don-petry]

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

No changes were needed for this PR.

[gemini-code-assist]

Code Review

This pull request adds an Architecture Decision Record (ADR) detailing a proposed policy and mechanism to limit open pull requests. Since GitHub lacks a native general-purpose limit, the ADR proposes implementing source-side admission gates in PR-creating automation while maintaining Dependabot's existing ecosystem-scoped limits. The review feedback suggests minor editorial improvements, including correcting a grammatical phrasing to 'ruleset rules' and updating 'labelled' to 'labeled' for spelling consistency.

[don-petry]

Dev-Lead — fix-reviews (applied)

Changes committed and pushed.

[don-petry]

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

No changes were needed for this PR.

[donpetry-bot]

Automated review — APPROVED ✓

Risk: LOW
Reviewed commit: 2c712079dfee8bbe253d23e690827c7ba3f597f1
Review mode: triage-approved (single reviewer)

Summary

Docs-only PR adding a single ADR (docs/initiatives/pull-request-limits-adr.md, +262/-0) that records the mechanism + policy decision for limiting open automation PRs. Triage cleared this as low-risk; this confirmation review agrees. The ADR is well-structured, explicitly marks its limit numbers and exempt-actor list as proposals pending human sign-off, and mutates no repository/org/ruleset config (AC #5 satisfied). It also usefully corrects two issue-premise errors (no native GitHub "max open PRs" surface exists; .github/rulesets/code-quality.json is generated by apply-rulesets.sh rather than checked in).

Linked issue analysis

Closes #506. All five acceptance criteria are substantively addressed: §3 identifies the exact surfaces (repo setting / org setting / ruleset rule) with doc citations and records the no-API finding with evidence (AC #1, #2); §4–§6 enumerate PR sources, give a measured baseline, and propose caps + exempt list marked as non-final (AC #3); §7 maps onto the apply-script pattern, names the Story 2 integration point, and reconciles with the Dependabot cap (AC #4); the change is documentation-only (AC #5). §8 honestly records the WebSearch/changelog gap.

Findings

No blocking findings. Bot reviewers (gemini-code-assist, coderabbit) only raised minor editorial nits (e.g. "labeled" spelling) which the dev-lead fix-reviews pass addressed (HEAD shows "labeled" already); coderabbit's review is DISMISSED and rate-limited. Secret scanning: the run_secret_scanning MCP tool was unavailable in this environment; not applicable to a markdown-only change, and the gitleaks CI check passed. Note: mergeStateStatus is BEHIND — the branch needs a rebase before merge (handled by auto-rebase), not a review blocker.

CI status

All checks green or appropriately skipped: Lint, ShellCheck, Agent Security Scan, Secret scan (gitleaks), CodeQL (Analyze actions), AgentShield, SonarCloud (Quality Gate passed), Dependency audit (ecosystem-specific jobs skipped). No failures.

---

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

[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 — fix-bot-comment (no-changes)

Agent reasoning

Issues addressed: 0
Files changed: None
Skipped (informational): 0
Status: ✅ No action needed — Quality Gate passed with 0 issues found.
```