---
title: "PR & Code Review Process"
slug: onboarding-pr-review
section: Developer Onboarding
status: stable
description: "Every Alliance PR — BackOfficePrototype, PPPToo, HostPortalPrototype, and the rest — goes through the same gated review sequence before it merges."
last-updated: 2026-10-07
---

# PR & Code Review Process

Every Alliance PR — BackOfficePrototype, PPPToo, HostPortalPrototype, and the rest — goes through the same gated review sequence before it merges. Knowing the shape of it in advance means fewer surprise round-trips.

## Overview

The process has two halves: an automated pre-check that runs before any human or AI reviewer looks at the diff, and a sequence of gates that actually judge the change. A PR can fail at Gate 0 and never reach substantive review at all — that's by design, since it's cheap to catch there and expensive to catch later.

## Gate 0 — Quality/SLOP Pre-Check

Before anything else: a merge-conflict check, a slopgate run, an AI-slop pattern scan, and a Nexus semantic-correctness check (does the change contradict what the architecture docs say is true). Any failure here blocks further review until fixed — there's no point running the expensive specialist gates against a diff that doesn't even apply cleanly.

## Gates 1–6 — Specialist Review

The substantive review runs in parallel across multiple gates, each looking at the change from a different angle — correctness, security, design/reuse, and so on. Critically, one of these gates requires **pulling the branch and functionally verifying the change returns correct data** — not just reading the diff. A change that looks correct on paper but hasn't been run against real data has not cleared this gate.

## Posting the Verdict

The reviewer's findings are posted as a **native GitHub PR review** (approve / request changes / comment), not as a plain issue comment — this keeps the verdict attached to the PR's own review history and gates GitHub's merge button correctly when changes are requested.

## Gate 7 — Author-Fix Verification

If changes were requested, the *author* fixes them — the reviewer never edits the branch directly, even to save a round-trip. Once fixed, Gate 7 is a re-review: the reviewer checks the specific findings were actually addressed, not a full re-run of every earlier gate from scratch.

## Merge Procedure

Once approved, the standard procedure is a **squash merge with branch deletion** — one clean commit onto the target branch, and the feature branch removed rather than left to accumulate. (Note: this generic procedure applies to routine feature-branch PRs; a few repos or branch types have their own distinct promotion mechanics — see the CI/CD & Deployment Process page for the exceptions.)

## Automation Status

The gate sequence above is enforced by two live automation components, not left to human/AI reviewer discretion alone:

- **`pr-review-agent`** (Vertex AI Agent Engine, `skilled-script-469819-f2`/`us-central1`) evaluates Gates 0–7 above against a PR's diff and renders a structured verdict (`approved` / `changes_requested` / `commented_pending`). It fetches this policy live from the Gateway's `pr-review` skill on every call, so it never drifts from what's documented on this page. It has no merge capability in any mode — findings are always left for the author to fix.
- **`pr-review-eligibility-agent`** (Cloud Run) is the dispatcher: it listens for GitHub `workflow_run` webhook events, confirms every required status check is green on the PR's current head SHA, and only then calls `pr-review-agent`. This is what implements the "required checks green" condition deterministically rather than trusting the diff alone.

As of 2026-08-19, this pipeline is live in `review_only` mode (posts exactly one native GitHub review + one Teams notification per terminal verdict) on `BackOfficePrototype`, `HostPortalPrototype`, and `PPPToo`.

A PR authored by this automation's own GitHub App identity (`alliance-agent-workflow[bot]`, e.g. an automated dependency-bump PR) still gets reviewed, but its GitHub review is posted as a COMMENT rather than APPROVE/REQUEST_CHANGES — GitHub's API rejects a reviewer approving or requesting changes on its own PR — with the real verdict called out explicitly in the comment body instead.