docs: make CodeRabbit review best-effort instead of merge-blocking

[simple-agent-manager]

Summary

• Problem. Rule 25 and /do Phase 7 told agents to add needs-human-review and not merge whenever CodeRabbit did not respond. That label fails check-specialist-review-evidence. CodeRabbit has not reviewed an agent-authored PR since fix(snapshot): restore exact saved Git state #2115 (2026-09-21): it reports Review skipped: bot user not eligible for review (GraphQL survey: zero CodeRabbit reviews on agent PRs Add Cloudflare cost audit quality script #2116–docs(blog): publish SAM daily engineering journal #2188). The result was that finished PRs waited on per-PR human waivers. fix(vm-agent): bind prompt-cancel grace watchdog to the cancelled attempt #2180 and Whole-session resource timeline for the Resources drawer #2185 are parked that way right now.
• Change (Raphaël, 2026-09-29). A CodeRabbit review is no longer required. Agents must still request one (the coderabbit-review label, or the trusted workflow_dispatch when the label run does not fire) and wait about 15 minutes.
  • A review that arrives blocks merge until its feedback is resolved.
  • If nothing arrives (silence, Review skipped, rate limit, failed workflow), the agent records what it observed and merges on the remaining gates.
  • A silent CodeRabbit never justifies needs-human-review, request_human_input, or waiting for a waiver.
• Files.
  • Rule 25 is restructured so the local-reviewer rule and the CodeRabbit rule each own their sections. It now says explicitly that CodeRabbit silence is not a needs-human-review reason and that CodeRabbit does not go in the Specialist table.
  • Rule 14's state-file tracker.
  • /do Phase 7 and the Phase 0 todo item.
  • The Codex do skill and its openai.yaml prompt.
  • The PR template's CodeRabbit evidence section, whose checkboxes now work for both outcomes.
  • The AGENTS.md guardrail row.
• Formatting. Prettier-formatted rule 14, rule 25 and AGENTS.md, which lowers format debt from 2118 to 2115. No runtime code, workflow, or CI-parser changes.
• SAM-side (already live, not in this diff).
  • Policy 73ed7a68 rewritten to the new rule.
  • Deactivated 7da78e9f (now folded into 73ed7a68), plus 118e4832 and 05aa1079, the waivers for Draft: Implement ProjectData terminal archive-sharding bridge #1984 and Fix cleanup for providerless destroying nodes #2157, both already merged.
  • Nine CodeRabbit knowledge observations updated to point at the new rule.

Validation

• pnpm lint: N/A, no TypeScript or JavaScript changed
• pnpm typecheck: N/A, no TypeScript changed
• pnpm test: N/A, no runtime code or tests changed
• Additional validation run:
  • pnpm format:check ratchet passed (2115/2225).
  • prettier --check is clean on every changed Markdown file. The pre-existing quote-style warning on openai.yaml is unchanged and outside the ratchet.
  • pnpm quality:agent-context-budget: rule 25 is +2.9 KB, about +700 tokens in the Claude root surface.
  • A repo-wide grep for old-rule phrases found none outside task records and blog history.
• If this PR changes candidate selection for a sweep/cron/alarm loop: N/A

Staging Verification (REQUIRED for all code changes — merge-blocking)

N/A: docs-only. The diff touches agent-instruction Markdown, the PR template, and one Codex skill prompt string; there are zero runtime code changes.

• Staging deployment green: N/A: docs-only
• Live app verified via Playwright: N/A: docs-only
• Existing workflows confirmed working: N/A: docs-only
• New feature/fix verified on staging: N/A: docs-only
• Infrastructure verification completed: N/A: no infra changes
• Mobile and desktop verification notes added for UI changes: N/A: no UI changes

Staging Verification Evidence

N/A: docs-only. No application code changed, so there is nothing to deploy or exercise on staging.

UI Compliance Checklist (Required for UI changes)

N/A: no UI changes.

UI Screenshot Evidence

N/A: no UI changes.

End-to-End Verification (Required for multi-component changes)

N/A: docs-only process change.

Data Flow Trace

N/A: no runtime data flow changes. The only machinery involved was checked against the text:

• scripts/quality/check-specialist-review-evidence.ts fails on the needs-human-review label and on PENDING/FAILED rows.
• .github/workflows/coderabbit-bot-review.yml fires on the label only for non-draft bot PRs; workflow_dispatch works for any open PR.
• Both are unchanged.

Untested Gaps

N/A: no code paths changed.

Post-Mortem (Required for bug fix PRs)

What broke

Finished agent PRs stalled for hours or days with every other gate green. They waited on a CodeRabbit review that never came, then on per-PR human waivers. Examples: #2133, #2157, #2170–#2174, #2180, #2185.

Root cause

Rule 25 and /do Phase 7 treated "CodeRabbit did not respond" as "cannot verify" and escalated via needs-human-review. From 2026-09-21, CodeRabbit skips every bot-authored PR, so the escalation fired on every agent PR.

Class of bug

An over-firing guard keyed on a proxy: "a CodeRabbit review exists" stood in for the actual condition, "there is unresolved CodeRabbit feedback". See .claude/rules/74-proxy-signals-must-match-the-condition.md. When no review exists, there is also no unresolved feedback.

Why it wasn't caught

The external service changed its behavior silently, and each stall was resolved by a one-off waiver, which masked the systemic cause.

Process fix included in this PR

.claude/rules/25-review-merge-gate.md, .claude/rules/14-do-workflow-persistence.md, .claude/commands/do.md, .agents/skills/do/SKILL.md, .agents/skills/do/agents/openai.yaml, .github/pull_request_template.md, AGENTS.md. SAM policy 73ed7a68 carries the same rule.

Post-mortem file

This PR description, plus the "Why CodeRabbit Is Best-Effort" section of .claude/rules/25-review-merge-gate.md.

Specialist Review Evidence (Required for agent-authored PRs)

• All local reviewers completed and findings addressed before merge
• If any reviewer did NOT complete: needs-human-review label added and merge deferred to human (N/A: all completed)

Reviewer	Status	Outcome
doc-sync-validator	ADDRESSED	PASS with no CRITICAL/HIGH. It verified the factual claims (workflow draft gating, .coderabbit.yaml, evidence-check failure modes) and found no old-rule text left in the repo. Two MEDIUM and three LOW findings; fixed in fdb96cb: added the in-progress-review clause to /do, capped it at about 45 min, reworded rule 25's checklist, and added "do not re-trigger" to AGENTS.md and the Codex skill. The draft-PR edge case is left as is because step 1 already routes drafts to the workflow dispatch.

CodeRabbit Review Evidence (Required for agent-authored PRs)

• CodeRabbit requested after local review, staging if applicable, and CI gates passed
• Waited about 15 minutes, or up to about 45 minutes in total while a review CodeRabbit had started was still in progress
• Either CodeRabbit reviewed and no CodeRabbit feedback is unresolved, or it did not review and the observed outcome is recorded below

CodeRabbit Notes

Outcome: CodeRabbit did not review, so this step is complete under the new rule 25, step 4. No needs-human-review label and no waiver.

• Requested at 2026-09-29T19:30:18Z via the coderabbit-review label, after CI was green and doc-sync-validator had finished. Label run 36619711658 succeeded at 19:30:21Z and posted @coderabbitai review under the human-scoped PAT.
• Waited until 19:46:13Z (about 16 minutes), polling every 30 s. CodeRabbit never started a review.
• Observed: zero reviews and zero inline comments. The CodeRabbit status is success: "Review skipped: bot user not eligible for review" (19:30:26Z). Its summary comment re-rendered at 19:30:25Z as "Review skipped: Bot user detected" and shows Plan: Advanced, so this is the bot-author exclusion, not a quota limit. It is the same outcome every agent PR has had since fix(snapshot): restore exact saved Git state #2115.

Exceptions (If any)

• Scope: none
• Rationale: none
• Expiration: none

Agent Preflight (Required)

• Preflight completed before code changes

Classification

• external-api-change
• cross-component-change
• business-logic-change
• public-surface-change
• docs-sync-change
• security-sensitive-change
• ui-change
• infra-change

External References

N/A: no external API was integrated or changed. CodeRabbit's behavior was established from repository evidence:

• .coderabbit.yaml: auto_review.enabled: false, label coderabbit-review.
• .github/workflows/coderabbit-bot-review.yml.
• The GitHub GraphQL review history for PRs Fix atomic VM-agent releases and Instant deployment recovery #2059–docs(blog): publish SAM daily engineering journal #2188.
• The main branch ruleset: the only required check is "Durable Object Workers", with no required reviews.

Codebase Impact Analysis

Agent-instruction surfaces only:

• .claude/rules/25-review-merge-gate.md
• .claude/rules/14-do-workflow-persistence.md
• .claude/commands/do.md
• .agents/skills/do/SKILL.md and .agents/skills/do/agents/openai.yaml
• .github/pull_request_template.md
• AGENTS.md

The CI evidence parsers do not read the CodeRabbit section, so they are unaffected: scripts/quality/check-specialist-review-evidence.ts parses only the Specialist table and labels, and scripts/quality/check-preflight-evidence.ts reads only this preflight block. The CodeRabbit workflow and config are unchanged.

Documentation & Specs

Updated in this PR:

• .claude/rules/25-review-merge-gate.md: new "Request CodeRabbit and Wait — a Review Is Not Required" rule and rationale.
• .claude/rules/14-do-workflow-persistence.md: Phase 7 tracker.
• .claude/commands/do.md: Phase 7 steps 4–6 and the Phase 0 todo.
• .agents/skills/do/SKILL.md and agents/openai.yaml.
• .github/pull_request_template.md: CodeRabbit evidence section, plus a Specialist-table note.
• AGENTS.md: CodeRabbit guardrail row.

No public docs under apps/www/ describe the gate; the only mention is a historical blog post, left as is. No spec docs apply.

Constitution & Risk Check

Principle XI does not apply: no code, URLs, timeouts or limits changed. The 15-minute wait is agent guidance, not a runtime value.

Risks and mitigations:

• Real findings could be dropped. They are not: an arriving CodeRabbit review stays binding, and a review that lands after merge goes through a follow-up PR (rule 25, hard requirement 6).
• Agents re-trigger CodeRabbit in a loop. Explicitly forbidden.
• Larger always-loaded context. The Claude root rule surface grows by about 700 tokens.

🤖 Generated with Claude Code

[coderabbitai]

Important

Review skipped

Bot user detected.

To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository: raphaeltm/simple-agent-manager/.coderabbit.yaml

Review profile: CHILL

Plan: Advanced

Run ID: e48aa2a4-51c2-49a6-9f1b-a16d5758b59f

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

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

[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

[raphaeltm]

@coderabbitai review