Add --max-reviews: cap reviews per loop, cut after the seeded shuffle

[ywy50]

--max-reviews N caps how many reviews one loop runs, however large the expanded --reviews/set schedule is. 0 (the default) is unlimited, a negative value is a usage error, and a cap at or above the schedule length changes nothing.

Where the cut happens. After the per-loop Fisher-Yates draw in schedule(), which still shuffles the full list. Cutting before it would change the draw keys, so this order keeps --seed replaying exactly which N ran, keeps every loop's draws identical to an uncapped run's, and lets different loops of one run sample different reviews. A review scheduled twice (weighting) fills two of the N slots when both land inside the cut — the flag help and docs say so.

Stacked PRs. Stack mode never calls schedule(); its one pass walks cfg.Reviews in configured order and the resume suffix check indexes into that slice. The cap therefore truncates cfg.Reviews itself in New, so the pass runs its first N entries (at most N PRs) and stackResumeIndex stays consistent.

Hot-reload resume. A ResumeQueue is never re-capped: it is the already-truncated remainder of an interrupted loop, and may legitimately exceed a cap raised between processes. Pinned by TestMaxReviewsDoesNotRecapAResumeQueue.

Reporting. --dry-run prints Reviews per loop: 2 of 5, capped by --max-reviews (and, in stack mode, truncates the printed pass, whose order is known there). The run-start and loop-start events carry the capped per-loop total.

Wiring. Registered in flags.go mirroring --retries, validated in finishFlags, documented in the Reviews help group and docs/CLI.md, added to goldenFlagNames and the CHANGELOG. Not in any subcommandFlags allowlist, so gauntlet runs --max-reviews 3 is refused (test added).

Tests. Truncation-after-shuffle determinism under a fixed seed, oversized cap as a no-op, resume queue not re-capped, stack-pass truncation, flag parsing/rejection rows, and dry-run output. make ci (fmt/fix/vet + full race suite) is green, and the behaviors above were also exercised against the built binary.

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Team

Run ID: 3041fd7a-ec0d-4629-87b2-79de56cfc67c

---

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