fix(engine): reorder cross-provider fallback to claude → copilot → gemini

[don-petry]

Why

The cross-provider rate-limit fallback chain was claude → gemini → copilot, so when Claude is exhausted it falls to Gemini before Copilot. With Gemini's prepayment credits depleted, that surfaced as hard 429 RESOURCE_EXHAUSTED failures (found by the post-implementation health check — markets dev-lead fix-bot-comment).

Per the intended engine preference — Claude default → Copilot → Gemini — Gemini should be the last resort. (Note: DEV_LEAD_ENGINE default is already claude and no override is set; the bug was purely the fallback order.)

Change

• engine.sh run_writer_with_fallback (dev-lead path): loop order claude copilot gemini.
• review-batch.sh (pr-review batch path): reorder the cascade so a Claude rate-limit falls to Copilot first, then Gemini; each engine's availability check travels with it.
• Comments + bats updated to the new order (test_engine_fallback, test_provider_headroom); where a test specifically targets the Gemini fallback, Copilot is forced to skip via a classic-PAT token.

Validation

• 22/22 engine bats pass (fallback + headroom); shellcheck clean (only pre-existing INFO notes).

Rollout

engine.sh is shared, so this ships via both agent releases: cut pr-review/vX + dev-lead/vX and promote both channels.

🤖 Generated with Claude Code

Summary by CodeRabbit

• Chores

  • Changed provider fallback order on rate-limit from Claude → Gemini → Copilot to Claude → Copilot → Gemini; batch review flow now may prefer Copilot first and will skip a PR if final fallback isn’t available.

• Tests

  • Updated unit tests to reflect the new provider fallback ordering and deterministic skip behavior.

• Documentation / Config

  • Expanded security-scan allowlists and added docs/comments to suppress known false positives for example tokens and manifest checksums.

[coderabbitai]

Warning

Review limit reached

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

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

Your organization has run out of usage credits. Purchase more credits in the billing tab to continue.

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

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available.

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: a0e82f1c-dc4c-491e-8ed8-c4951c78e01b

📥 Commits

Reviewing files that changed from the base of the PR and between 17168f3 and 11392e6.

📒 Files selected for processing (2)

• .gitleaks.toml
• scripts/review-batch.sh

📝 Walkthrough

Walkthrough

The PR reorders the AI engine fallback sequence from claude → gemini → copilot to claude → copilot → gemini, updating engine-layer iteration, batch orchestration, unit tests, and gitleaks allowlists/comments.

Changes

AI Engine Fallback Reordering

Layer / File(s)	Summary
Engine-layer fallback reordering scripts/engine.sh	Documentation comments (lines 21, 64, 1041) and the run_writer_with_fallback loop initialization (line 1051) are updated to sequence engines as claude → copilot → gemini on rate-limit.
Batch-level rate-limit orchestration scripts/review-batch.sh	Engine fallback chain comment (line 10) and rate-limit handling logic (lines 160–199) are reworked to try Copilot first from Claude, handle Copilot “unavailable” exits (55/127) by attempting Gemini, and skip the PR when Gemini is unavailable.
Test updates validating new fallback sequence tests/dev-lead/unit/test_engine_fallback.bats, tests/dev-lead/unit/test_provider_headroom.bats	Unit tests updated to reflect new fallback order; tests set COPILOT_GITHUB_TOKEN or ghp_stub where needed to force Copilot skipping so Gemini is reached and assertions match claude → copilot → gemini.
Gitleaks allowlists and docs comments .gitleaks.toml	Adds documentation comments about example expired JWTs, a new allowlist rule for expiredToken in .claude/skills/**/resources/knowledge/api-testing-patterns.md, and expands _bmad/_config/files-manifest.csv allowlist regexes to include 64-hex SHA-256 digests.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• petry-projects/.github-private#102: Modifies the same cross-engine rate-limit fallback mechanics and related tests.
• petry-projects/.github-private#226: Changes fallback trigger conditions and quota detection in scripts/engine.sh, related to this PR's fallback-order change.
• petry-projects/.github-private#227: Also modifies run_writer_with_fallback fallback behavior in scripts/engine.sh.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 66.67% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and specifically describes the main change: reordering the cross-provider fallback sequence from claude → gemini → copilot to claude → copilot → gemini, which is the primary objective across all modified files.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/engine-fallback-order

---

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

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

[gemini-code-assist]

Code Review

This pull request updates the cross-provider fallback order from claude → gemini → copilot to claude → copilot → gemini across the engine and batch scripts, with corresponding updates to the test suites. The review feedback points out that using raw gh command checks to verify Copilot availability bypasses pre-flight checks and can cause runtime failures if unsupported classic PATs are used. It is recommended to use the pre-flight COPILOT_AVAILABLE flag and explicitly guard against ghp_* tokens to ensure a robust fallback to Gemini.

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@scripts/review-batch.sh`:
- Around line 163-181: Replace the gh-based Copilot gate with the preflight
COPILOT_AVAILABLE flag and ensure Gemini is selected when Copilot is not
available or runtime returns fallback codes: check the COPILOT_AVAILABLE
env/flag before attempting the Copilot fallback (instead of `gh`), only run
`bash scripts/review-one-pr.sh` with REVIEW_ENGINE=copilot when
COPILOT_AVAILABLE is truthy, and on failure codes (55 or 127) or when
COPILOT_AVAILABLE is false set rc=2 and export REVIEW_ENGINE=gemini (update
engine_fallbacks/fallback_engines only when Copilot actually runs) so the
cascade proceeds to Gemini as intended.
- Around line 184-186: Change the fallback conditional that checks
rc/REVIEW_ENGINE/GEMINI_AVAILABLE to use the Bash conditional form [[ ... ]]
instead of [ ... ] (locate the if block that tests rc, REVIEW_ENGINE and
GEMINI_AVAILABLE), and ensure GEMINI_AVAILABLE is referenced with the
parameter-expansion default like ${GEMINI_AVAILABLE:-false} inside the [[ ...
]]; also run ShellCheck with -x to follow sourced scripts (validate_engines.sh,
engine.sh) so SC1091 warnings are suppressed during CI validation.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: 599a74b7-a08d-4413-8b60-aff20fe437fd

📥 Commits

Reviewing files that changed from the base of the PR and between 803e63f and 70fc2fa.

📒 Files selected for processing (4)

• scripts/engine.sh
• scripts/review-batch.sh
• tests/dev-lead/unit/test_engine_fallback.bats
• tests/dev-lead/unit/test_provider_headroom.bats

[don-petry]

@coderabbitai resolve

[don-petry]

Dev-Lead — review-changes (applied)

Changes committed and pushed.

[coderabbitai]

✅ Action performed

Comments resolved and changes approved.

[don-petry]

Dev-Lead — fix-bot-comment (applied)

Changes committed and pushed.

[don-petry]

Dev-Lead — review-changes (applied)

Changes committed and pushed.

[don-petry]

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

No changes were needed for this PR.

[don-petry]

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

No changes were needed for this PR.

[don-petry]

Auto-rebase failed — merge conflict — this branch has conflicts with main that must be resolved.

Claude will attempt to resolve this automatically. If it cannot, a follow-up comment will explain what needs manual attention.

To resolve manually instead:

git fetch origin
git merge origin/main
# resolve conflicts, then:
git add .
git commit
git push

[don-petry]

Dev-Lead — rebase (no-changes)

Agent reasoning

PR: #571
Rebased onto: main
Conflicts resolved: 1 file
- .gitleaks.toml: HEAD had a broad commit-SHA-based suppression for bda766be;
  PR (d0c3c37) replaced it with two targeted path+regex allowlists (JWT in
  api-testing-patterns.md, SHA256 hashes in files-manifest.csv). Kept the
  PR version per the "prefer PR changes" constraint.
Push: success
```