docs(contributing): document enforced merge grading gate

[solomonneas]

Summary

• Document the 22 required GitHub Actions checks and strict up-to-date requirement.
• Document the required current non-author approval, resolved conversations, and approval after the last push.
• Separate CodeRabbit commit status from the formal GitHub review artifact.
• Add the exact CLI checks contributors can use before attempting a merge.

Verification

• ./scripts/verify through Brigade: pass
• git diff --check: pass
• detect CONTRIBUTING.md: 1% likely AI-generated

Closes #658

Summary by CodeRabbit

• Documentation
  • Added pull request contribution guidelines covering branch protection, required checks and reviews, approval rules, automated review responsibilities, merge-gate verification, and dispatched-session workflows.

[solomonneas]

@coderabbitai review

[coderabbitai]

Warning

Review limit reached

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

Next review available in: 53 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: Repository: escoffier-labs/coderabbit/.coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 8bd6cfcc-04c0-415a-970c-f373fa73e95e

📥 Commits

Reviewing files that changed from the base of the PR and between a9038fe and a0148d5.

📒 Files selected for processing (1)

• CONTRIBUTING.md

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

📝 Walkthrough

Walkthrough

The contribution guide adds a “Pull requests” section. It documents branch protection requirements, review rules, merge-gate commands, approval invalidation, and the dispatched-session workflow.

Changes

Pull request contribution guidance

Layer / File(s)	Summary
Document pull-request merge requirements CONTRIBUTING.md	Adds guidance for required checks, non-author approvals, resolved conversations, stale approvals, review-state commands, CodeRabbit reviews, and dispatched-session workflows.

Estimated code review effort: 1 (Trivial) | ~2 minutes

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Linked Issues check	⚠️ Warning	The PR documents the gate but does not implement branch protection or a grading-only status artifact, so core issue requirements remain unmet [#658].	Implement branch protection or a grader-only status check, configure the grading identity, and verify same-session merges are blocked and visible in gh pr checks.

✅ 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 identifies the documentation change for the enforced merge grading gate.
Out of Scope Changes check	✅ Passed	The changes only update CONTRIBUTING.md with documentation directly related to the linked issue objectives [#658].
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch work/658-mechanical-merge-gate

---

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

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[solomonneas]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[solomonneas]

@coderabbitai full review

[coderabbitai]

✅ Action performed

Full review finished.

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (1)

CONTRIBUTING.md (1)

63-74: 🗄️ Data Integrity & Integration | 🔵 Trivial | ⚡ Quick win

Name the identity that creates the formal approval.

Line 63 distinguishes CodeRabbit's status from the grading artifact, but Line 74 only says “the external reviewer” records approval. If CodeRabbit does not submit the formal GitHub APPROVED review, name the bot or second identity and document the trigger that creates it. Otherwise, dispatched sessions know when to stop but not how the required artifact is produced.

🤖 Prompt for 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.

In `@CONTRIBUTING.md` around lines 63 - 74, The CONTRIBUTING.md merge-gate
guidance must identify the bot or second identity that submits the formal GitHub
APPROVED review and document the trigger that causes it. Update the paragraph
referring to “the external reviewer” so dispatched sessions know which identity
produces the required artifact and when that approval is expected after the
final push.

🤖 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 `@CONTRIBUTING.md`:
- Around line 65-72: Update the merge-gate guidance near the “Inspect the gate
before attempting a merge” section to include verification that all review
conversations are resolved. Add either a UI or GraphQL-based check, or
explicitly instruct contributors to verify unresolved conversations separately,
while preserving the existing required-check and review-state commands.

---

Nitpick comments:
In `@CONTRIBUTING.md`:
- Around line 63-74: The CONTRIBUTING.md merge-gate guidance must identify the
bot or second identity that submits the formal GitHub APPROVED review and
document the trigger that causes it. Update the paragraph referring to “the
external reviewer” so dispatched sessions know which identity produces the
required artifact and when that approval is expected after the final push.

🪄 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: Repository: escoffier-labs/coderabbit/.coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 08ffd0ec-7390-4940-95b0-2ae6121c7203

📥 Commits

Reviewing files that changed from the base of the PR and between a9038fe and 6cce2e1.

📒 Files selected for processing (1)

• CONTRIBUTING.md

[solomonneas]

@coderabbitai full review

[coderabbitai]

✅ Action performed

Full review finished.

---

Your included review limit is currently reached under our Fair Usage Limits Policy. This review may still proceed through usage-based billing if eligible. Your next included review will be available in 54 minutes.