chore(forge): add CodeRabbit review gate

Author: bluecloud-gilfoyle[bot]

.github/PULL_REQUEST_TEMPLATE/agent.md

@@ -22,6 +22,15 @@ $ uv run python-docs-mcp-server doctor
 <!-- Plus any change-type-specific gates from pipeline §5 (stdio smoke,
      validate-corpus, uv lock --check) that applied to this change. -->
 
+## CodeRabbit review
+<!-- After CodeRabbit comments, summarize findings as:
+     - Blocking: <items or None>
+     - Follow-up: <items or None>
+     - False positive: <items or None>
+     If CodeRabbit has not run yet, write "Pending." Do not mark findings green
+     by silence. -->
+Pending.
+
 ## What this does NOT touch
 <!-- Restate the forbidden-territory items (pipeline §2) relevant to this issue
      and affirm they were not modified. -->

AGENT-EXECUTION-PIPELINE.md

@@ -16,6 +16,7 @@
 - Every PR requires human review before merge. **No auto-merge, ever.**
 - Agents declare their scope explicitly and stay inside it.
 - The canonical validation gate (§5) must pass before any PR is opened. Failing gate → no PR, just a `WORKING-NOTES.md` on the branch + comment on the issue.
+- Automated review tools such as CodeRabbit provide review signal only. They do not approve, merge, or override the human-review gate.
 - Forbidden territory (§2) is non-negotiable. Any drift triggers a hard stop.
 - Recovery is always **stop and post a comment**, never **silently expand scope**.
 
@@ -134,6 +135,7 @@ uv run python-docs-mcp-server doctor
   - `Closes #<issue-number>` (or `Refs #` if intentionally not closing)
   - Each acceptance criterion as a checked or unchecked box, with a one-line explanation if unchecked
   - Output (or link to artifact) for the §5 validation gate
+  - CodeRabbit triage summary when CodeRabbit comments on the PR: blocking, follow-up, false positive, or pending/unavailable
   - "What this does NOT touch" section reaffirming the forbidden-territory items relevant to this issue
   - A short "Why this approach" paragraph if the design wasn't fully prescribed in the issue
 - **PR is opened against** the milestone integration branch (e.g., `release/v0.3.0`) when one exists, otherwise `main`. Never auto-merge.
@@ -371,5 +373,6 @@ The default loop is Vision → Gilfoyle → Heimdall → Vision/Aymen:
 - Vision owns issue pre-flight, `agent-ready`, review synthesis, branch protection, and pause/resume decisions.
 - Gilfoyle owns scoped implementation on exactly one issue at a time.
 - Heimdall owns independent verification, packaging/install smoke, security-sensitive checks, and release-readiness checks.
+- CodeRabbit findings are mandatory review signal when present. Vision/Heimdall must triage them as blocking, follow-up, or false positive before `verified`.
 - Saga is not in the default loop because this MCP has no UI.
 - Pipeline Monitor remains disabled unless Aymen explicitly asks for assisted merge checks; no auto-merge is allowed.

OPENCLAW-FORGE-PROTOCOL.md

@@ -13,6 +13,7 @@ The core loop is:
 - **Vision** plans, gates, reviews, and protects the repo.
 - **Gilfoyle** implements one scoped issue at a time.
 - **Heimdall** verifies behavior, packaging, security posture, and release readiness.
+- **CodeRabbit** provides automated review signal that Heimdall and Vision must triage.
 - **Aymen** remains the final human review authority for protected merges.
 
 `AGENT-EXECUTION-PIPELINE.md` remains the binding repo policy. This protocol is
@@ -27,6 +28,7 @@ the OpenClaw operating layer for applying that policy.
 | Supervisor | Vision (`main`) | Issue pre-flight, labels, branch protection, final review synthesis, stuck-work decisions | Yes, for protocol/config/documentation fixes | No auto-merge |
 | Implementer | Gilfoyle (`arch`) | Implement exactly one `agent-ready` issue, open/update one PR, run the canonical gate | Yes | No |
 | Verifier | Heimdall (`test`) | Independently validate PR behavior, test evidence, packaging/install smoke, security/release risks | Only test artifacts or diagnostic notes when explicitly assigned | No |
+| Automated reviewer | CodeRabbit | Static review comments, maintainability findings, and security-adjacent review signal | No | No |
 | Designer | Saga (`design`) | Not in the default loop; no UI exists | No | No |
 | Merger | Pipeline Monitor (`merge`) | Disabled for this repo unless Aymen explicitly asks for assisted merge checks | No | No auto-merge |
 
@@ -47,9 +49,12 @@ flowchart TD
     F --> G{Canonical gate green?}
     G -- no --> H[Commit WORKING-NOTES.md + stop]
     G -- yes --> I[Gilfoyle opens PR]
+    I --> R[CodeRabbit automated review]
     I --> J[Heimdall independent verification]
-    J --> K{Verifier pass?}
-    K -- no --> L[Heimdall labels verification-failed and comments exact failures]
+    R --> S[Vision/Heimdall triage findings]
+    J --> K{Verifier + review triage pass?}
+    S --> K
+    K -- no --> L[Heimdall or Vision labels verification-failed and comments exact failures]
     L --> E
     K -- yes --> M[Heimdall labels verified]
     M --> N[Vision review synthesis]
@@ -102,6 +107,8 @@ Vision also owns PR review synthesis:
 
 - Check the PR diff against forbidden territory.
 - Compare Heimdall's verification comment with Gilfoyle's claimed evidence.
+- Read CodeRabbit findings and classify each as blocking, non-blocking follow-up,
+  or false positive.
 - Decide whether to request changes, add `🛑 needs-human-review`, or approve
   for Aymen's final merge.
 
@@ -173,11 +180,16 @@ Then add targeted checks based on touched files:
 | Security-sensitive parsing | Grep for unsafe APIs and confirm trust boundary documentation |
 | ADR/docs-only PR | Verify links, file paths, command references, and forbidden-territory claims |
 
+Heimdall must also read CodeRabbit's review before applying `verified`.
+CodeRabbit is not authoritative, but unresolved blocking findings must prevent
+`verified`.
+
 Heimdall comments with:
 
 - Commit SHA verified.
 - Exact commands run.
 - Pass/fail result.
+- CodeRabbit triage summary: blocking / follow-up / false positive.
 - Any risk not covered by tests.
 - Final label action.
 
@@ -187,7 +199,42 @@ and posts exact reproduction steps. Heimdall must not request merge.
 
 ---
 
-## 7. Automation Mode
+## 7. CodeRabbit Protocol
+
+CodeRabbit is part of review signal, not governance.
+
+Required handling:
+
+1. Wait for the CodeRabbit check or review comment when it appears on a PR.
+2. Read every CodeRabbit finding that applies to the current PR head.
+3. Classify each finding:
+   - **Blocking:** correctness, security, public API drift, broken tests,
+     packaging/release risk, forbidden-territory drift, or real maintainability
+     issue inside the PR scope.
+   - **Follow-up:** valid but outside the issue scope or not worth expanding
+     the current PR.
+   - **False positive:** inaccurate, contradicted by tests, or based on a
+     misunderstanding of repo architecture.
+4. Blocking findings must be fixed by Gilfoyle before `verified`.
+5. Follow-up findings may become new issues if Vision agrees.
+6. False positives should be acknowledged in Heimdall or Vision's review
+   summary so Aymen does not have to re-triage them.
+
+CodeRabbit cannot:
+
+- Override the canonical validation gate.
+- Approve a PR.
+- Request merge.
+- Bypass Code Owner review.
+- Expand an issue's scope.
+
+If CodeRabbit is unavailable or delayed, Vision may proceed after Heimdall
+verification, but the PR summary must explicitly say CodeRabbit was unavailable
+or still pending. Do not pretend a missing review is green.
+
+---
+
+## 8. Automation Mode
 
 Initial v0.3.0 execution should be manual-triggered, not recurring cron.
 
@@ -215,7 +262,7 @@ stateDiagram-v2
 
 ---
 
-## 8. First Wave
+## 9. First Wave
 
 Start with the lowest-risk issues after the planning PR lands:
 
@@ -230,18 +277,18 @@ the SECURITY.md prose boundary is clear.
 
 ---
 
-## 9. Stop Conditions
+## 10. Stop Conditions
 
 Pause the forge and remove `agent-ready` from the queue if any of these happen:
 
 - A PR modifies forbidden territory without an explicit issue comment approving it.
 - Gilfoyle works on more than one issue in a cycle.
 - Heimdall verifies a different commit than the PR head.
+- A PR is marked `verified` while a CodeRabbit blocking finding is unresolved.
 - Any agent adds merge/approval language.
 - Any job uses Alto/Shopify/Vercel-specific assumptions.
 - The baseline canonical gate fails on `main`.
 
 When paused, Vision writes a short incident note and fixes the protocol before
 new work resumes. Small pauses are cheaper than turning a public repo into a
 committee-authored incident report.
-