Skip to main content

RaR-IT Code Review & Pull Request Policy

:::danger Status: PROPOSED — Pending Review, Approval, and Publication Version 1.0 · 28 August 2026. This document is not yet binding — see Section 8. :::

1. Purpose & Scope​

This policy establishes mandatory pull-request and code-review requirements for every RaR-IT repository — the shared platform kernel (rarit-saas-kernel), all product verticals (AMAAR, Clinivio, EduSuite, Shipping & Transport, Tourism), and every independent application not built on the kernel (currently Dw2ni, Adl, Hajez, Lasscar, Rizq, Bindoo, CashBlash, Axil, and any future standalone app).

This is deliberately broader than the SaaS Architecture Policy's own scope (kernel + verticals only) — that policy governs what gets built; this one governs how a change gets reviewed and merged, independent of stack. Where a repo is also in scope for the Architecture Policy, both apply; nothing here overrides that policy's technical requirements.

2. Pull Request Requirements​

  • Every PR must use the repository's .github/PULL_REQUEST_TEMPLATE.md, with these sections populated: Story, Acceptance Scenarios (Given-When-Then), What changed, Notes for the reviewer.
  • Branch names must carry the story key in the form <PROJECT>-<number> (e.g. EDS-118, SASK-42), as a token anywhere in the branch name. This is a hard requirement, not a style preference — both Claude Code Review's scenario-matching (Section 3) and the PR automation tooling (Section 5) depend on it being parseable.
  • An empty Story/Acceptance Scenarios section is permitted (not every change traces to a backlog item — a hotfix, a dependency bump) but is flagged by Code Review rather than silently skipped; see Section 3.

3. Automated Review — Claude Code Review​

  • Implemented as a self-hosted GitHub Actions workflow (.github/workflows/claude-review.yml, using anthropics/claude-code-action@v1) on every repository in scope — not the Team-plan's built-in, Anthropic-managed Code Review product. This formally resolves Actions ACT-005; its outcome is this policy and the workflow file itself.
  • Why self-hosted, not the built-in product: the built-in Team-plan Code Review was measured at roughly $15–25/review; the self-hosted workflow, on claude-sonnet-5 with a scoped prompt, measured at roughly $0.10/PR for comparable coverage. Revisit this choice if the built-in product's pricing or depth changes materially.
  • Authentication: GitHub Actions OIDC workload identity federation, not a static ANTHROPIC_API_KEY secret. Scoped by a federation rule matching the GitHub org (by immutable numeric ID, not name) and this policy's repos-in-scope list — nothing to rotate, store, or leak.
  • Trigger: currently every PR push (opened, synchronize, ready_for_review, reopened), not "once after PR creation." The original once-plus-@claude review-comment design is not yet implemented: a comment-triggered re-run authenticates via a GitHub OIDC token whose event_name claim is issue_comment, not pull_request, which the current federation rule doesn't accept. Implementing the original design requires updating that rule's claim match to also accept issue_comment, tracked as ACT-008 (Section 7) — until then, every push re-reviewing the PR is the accepted behavior, not a bug.
  • Two files per repo, different strength — never conflate them:
    • CLAUDE.md — general project context. Code Review reads it, but violations surface only as nits.
    • REVIEW.md — the enforcement-facing file. Read directly by every finding and verification agent. Policy-derived rules belong here, not in CLAUDE.md. Governed by Section 4.
  • Severity vocabulary, used consistently across every REVIEW.md:
    • Important — escalate; a real policy or correctness violation.
    • Report as-is — worth surfacing, not severe enough to escalate.
    • Nit — cosmetic; capped at 5 per review, remainder summarized as a count rather than listed individually.
    • Skip — explicitly out of scope for review (docs, generated files).
  • Findings are advisory only. Code Review does not approve or block a PR. This is a deliberate choice matching the team's current trust-based merge process — not a limitation to be worked around. See Section 6 for what would need to change for this to become a real gate.

4. REVIEW.md Governance​

  • One REVIEW.md per repository — Code Review only reads the file inside the repo it's reviewing; cross-repo references do not work.
  • Kernel and vertical repos: each REVIEW.md carries a shared base (the architecture rules common to every kernel-consuming repo — rejected DB-access pattern, cross-vertical import ban, RLS FORCE requirement, route-layering, audit-write pairing) plus a repo-specific section (e.g. EduSuite's MVP scope guard and Entitlements manifest checks).
  • Independent apps (separate stack — currently the mobile apps): their REVIEW.md is built from general best practice for that stack, not the kernel base, since the kernel's architecture rules don't apply. Each such file should have its stack-specific unknowns (state management, networking layer, persistence choice) explicitly confirmed before being relied on — an unconfirmed assumption here produces false-positive findings on correct code.
  • Known gap, not yet solved: the shared base is currently copied by hand into each kernel/vertical repo's REVIEW.md. There is no templating or sync mechanism, so a change to the shared rules requires manually re-propagating it to every repo, and drift between repos is possible without anyone noticing. Tracked as ACT-006 (Section 7).

5. PR Creation Tooling​

  • Story/scenario text should be carried into the PR description via tooling, not retyped by hand — this policy does not mandate a specific tool, but does mandate the branch-naming convention (Section 2) that any such tool depends on.
  • A reference implementation exists (scripts/create-pr.mjs (Node) + VS Code task + optional pre-push hook): extracts the story key from the branch name, pulls Story/Acceptance Scenario from the repo's backlog file, fills the PR template, and creates the PR via gh pr create. Any automatic hook-based trigger must prompt for confirmation before creating a PR — a silent side effect of git push is not acceptable.

6. Merge Enforcement & Its Current Limits​

  • On GitHub Free, branch protection and required status checks are not available on private repositories — this affects both this policy's Code Review findings and the Architecture Policy's A.9 CI lint checks equally. Both remain advisory (visible, not blocking) under the current GitHub plan.
  • This is a known, accepted limitation of the current plan, not a defect silently worked around. Revisiting the GitHub plan is tracked separately — see Actions ACT-004 (branch-protection-adjacent) and the note against A.9 Step 5.
  • If the plan changes, no REVIEW.md content needs to change — only branch-protection configuration does. The severity vocabulary in Section 3 already anticipates this: "Important" findings are the natural candidates for a future required check, should merge-blocking enforcement ever be adopted for Code Review specifically.

7. Open Items​

Tracked centrally in actions.md alongside the Architecture Policy's items, not in a separate tracker:

  • ACT-005 — Configure Claude Code Review. Status: Closed. Outcome: this policy.
  • ACT-006 (new) — REVIEW.md drift-prevention across repos (template or generation mechanism for the shared base). Type: Implementation.
  • ACT-007 (new) — Roll out PULL_REQUEST_TEMPLATE.md and the branch-naming convention across all repos in scope, including the independent mobile apps, which are not currently covered by any existing rollout. Type: Implementation.
  • ACT-008 (new) — Update the workload identity federation rule's claim match to also accept issue_comment-triggered runs (currently event_name is pinned to pull_request only), so an @claude review comment can re-trigger a review without a full new push. Unblocks moving the trigger in Section 3 from "every push" to "once after PR creation, plus on-demand." Type: Implementation (Console configuration).

8. Governance & Sign-off​

Same mechanism as the Architecture Policy: CODEOWNERS-gated PR approval plus required branch-protection status check on this document's own source, once the GitHub plan permits it (see Section 6); Architecture Review Board sign-off required before this leaves Proposed status. Quarterly review cadence, same as Architecture Policy Section 9.