Augment Code Review: Add a Current-Head Gate

How should Augment Code Review fit into a merge gate?

Use Augment Code Review to produce findings and guide fixes, but do not treat an old review comment as approval for a changed branch. Record the reviewed commit, rerun review and tests after every push, reconcile open findings, and merge only when the review result names the current head and GitHub's required checks pass for their latest applicable head or test-merge commit.

This distinction matters because Augment covers more than one review job. Its current Code Review documentationdescribes automatic and manual review triggers, Thorough and Precise review styles, GitHub comments, follow-up reviews, repository-specific guidelines, and a path from a finding to a proposed fix. Those capabilities can reduce the work of understanding and repairing a pull request.

They do not change Git's state model. A review happens against some revision of a branch. A later fix produces another revision. GitHub can dismiss stale approvals and require checks for the latest head, but only if the repository configures those protections. The merge-safe AI code review workflowexplains that general boundary. This guide applies it to Augment's specific triggers, guidelines, findings, and fix loop.

What does Augment Code Review do on a pull request?

Augment Code Review is installed as a GitHub App on selected repositories. An administrator chooses a trigger per repository. Automatic review starts when a pull request comes out of draft; Manual Command waits for a comment such asauggie review; Disabled turns review off. The same manual command can request another review after a later commit, according to Augment'ssetup guide.

Augment documents the GitHub App with repository contents read-only, pull requests read/write, issues read-only, and organization members read-only permissions. Confirm those scopes against the currentinstallation guide before granting repository access.

Teams also choose a review style. Augment describes Thorough as the broader default and Precise as a lower-comment mode focused on critical issues. Treat that setting as policy, not taste. A change from Thorough to Precise alters the evidence-generating process, so record it when a result is used in a merge decision.

Repository knowledge can be encoded inreview guidelines. The structured file at .augment/code_review_guidelines.yaml supports identifiers, severity, path scopes, and repository-specific rules. The useful targets are objective invariants: authorization checks, transactional behavior, audit requirements, compatibility boundaries, or tests required for a risky path. Subjective style advice consumes attention without making the merge decision clearer.

Augment positions its Context Engine as the repository-context layer behind these reviews. Treat that context as an input to a finding, not proof by itself: a must-fix comment still needs an inspectable code path and consequence.

Augment also says it applies repository AGENTS.md andCLAUDE.md instructions automatically. Keep shared engineering rules there when other agents need them too; use the Augment-specific YAML when review needs stable rule IDs, severities, and glob-scoped areas.

When Augment reports an issue, itsFix in Augment workflowcan open an agent session in supported environments or copy the issue into another tool. Augment's own guidance tells users to review the proposed change, test it, push the update, and request follow-up review for significant changes. That is the right sequence, but a repository still needs a durable record connecting each review and check to the resulting commit.

Product naming needs one boundary too. Augment now presents a broaderCosmos code-review fleetwith specialized risk, correctness, and human-judgment agents. That orchestration is not identical to every capability in the standalone GitHub App documentation. This guide uses the documented GitHub App flow and does not assume Cosmos routing, auto-approval, or shared-memory behavior is enabled in a repository.

Where is the trust boundary in Augment code review?

The trust boundary sits between useful review evidence and merge authority. Augment can explain risk, post a finding, and help construct a fix. GitHub branch protection or rulesets decide which approvals and status checks must exist before a protected branch accepts the pull request.

GitHub documents that required checks must pass before merge. It can also dismiss stale approvals when the diff changes, require approval of the latest reviewable push, require conversation resolution, and restrict a required check to an expected GitHub App. These controls are independent. A resolved conversation does not prove tests passed; a green test does not prove a finding was dispositioned; an approval on the previous diff does not cover the new head.

Augment's public documentation tells teams how to trigger and repeat reviews, but it does not document a portable machine-result contract that every repository can consume as an exact-head verdict. That is not a criticism of its findings. It is a reason to keep the merge policy in the repository and to ask for one receipt that joins the review evidence to GitHub's current state.

Record an Augment review receipt for every decision

The information missing from most Augment Code Review pages is a reproducible review receipt. This is a small record maintained by your workflow or review process. It does not need Augment to expose a new API. It needs the repository to stop accepting an ambiguous “reviewed” label.

The receipt is a novel operating layer, not a claim about an Augment feature. Its purpose is to make a multi-step hosted review auditable with primitives GitHub and Git already provide. If Augment later exposes an exact reviewed SHA and structured dispositions, copy those values into the receipt. Until then, fail closed when the workflow cannot prove which revision a required verdict covers.

{
  "requested_sha": "d4e5f6",
  "observed_head_at_completion": "d4e5f6",
  "review_policy": "thorough@guidelines-7c91",
  "findings": { "payment-idempotency": "fixed" },
  "current_head_sha": "d4e5f6",
  "reviewed_sha": "d4e5f6",
  "tested_sha": "github-test-merge-8a20",
  "required_checks": { "reviewgate": "passed", "tests": "passed" }
}

Here, reviewed_sha must equal current_head_sha. The test suite can legitimately name GitHub's test-merge commit instead, provided it is the commit GitHub currently requires for that integration check.

1. Choose the Augment review trigger and style

Use Automatic when every ready pull request should receive an initial pass. Use Manual Command when cost, repository risk, contributor access, or workflow timing makes an explicit request preferable. For Enterprise plans, Augment also documentsallowlist and deny-list controlsfor who may trigger review. Deny bot accounts that should not create review work, and do not assume a repository trigger alone expresses your trust boundary.

Pick Thorough when the pilot needs broad defect discovery. Pick Precise when the team has measured comment noise and wants a narrower signal. Do not switch styles halfway through an evaluation and then compare the outputs as if the reviewer were unchanged. The AI code review benchmark guideprovides a scorecard for recall, false blockers, repeatability, failures, latency, and cost.

2. Version objective review guidelines

Add .augment/code_review_guidelines.yaml to the repository and keep every blocking rule falsifiable. “Prefer clean code” is not testable. “Every write under services/payments/** must call the audit logger before commit” names a scope, behavior, and failure condition.

Give each rule a stable identifier. When a finding cites the rule, the receipt can record the rule version from the requested commit. That prevents a later policy edit from silently changing the meaning of an older review. Keep formatters, linters, and type checks in deterministic CI instead of asking the review model to reproduce them as prose.

3. Capture the exact pull-request head before review

Read the current head SHA immediately before the automatic event is handled or the manual command is posted. Store it as requested_sha. If the branch changes before the review completes, mark the result superseded and request a new pass instead of guessing that the comments still apply.

Read the head again when the review completes and store it asobserved_head_at_completion. Matching values do not make Augment attest the SHA, but they prove the repository did not observe a branch change across the review window. A mismatch requires another review.

This is stricter than matching a pull-request number. One pull request can carry many heads. A comment URL and timestamp identify a conversation, not the complete tree that was analyzed. Exact-head binding turns “Augment reviewed PR 42” into the narrower statement “review evidence was requested for commit abc123.”

4. Accept Augment findings by evidence

A review comment becomes a merge obligation only when it contains four elements: a concrete claim, repository evidence, a causal path, and a consequence. “This may be unsafe” is a question. “This added unauthenticated route calls the account deletion service, so any network client can delete an account” is a finding that can be checked and fixed.

Use the disposition contract from thesignal-first PR comment guide. Keep valid blockers open. Mark a finding fixed only after the relevant code and tests changed. Reject it only with contradictory repository evidence. Route design ambiguity to a human instead of forcing the model to invent policy.

5. Invalidate the old review after Fix in Augment

Fix in Augment helps carry a finding into an agent session, but the accepted edit still changes the branch. Capture the new SHA as current_head_sha, run the focused regression for the original consequence, and run the repository's normal required checks. The original review remains useful history; it is no longer a result on the new tree.

Apply the review-staleness rule to human edits, rebases, and agent changes that create a new pull-request head. Treat base-branch updates separately: the head-bound review can remain current, but integration CI must rerun when GitHub's applicable test-merge commit changes.

6. Request follow-up review and reconcile state

Augment documents follow-up review through the same manual commands used for a first manual pass. Request the new review after the fixes and focused tests are on the branch. Do not ask while another writer is still pushing commits; that creates overlapping attempts whose comments are difficult to assign to one head.

Reconcile every accepted finding. A stable identifier can be based on rule ID, affected path, and causal consequence rather than exact wording or line number. That lets a moved finding remain open, a verified fix close it, and a recurrence reopen it without counting three comments as three independent defects.

7. Require an independent current-head repository verdict

Configure branch protection or a ruleset to require the checks that express your policy. GitHub lets a repository require status checks, require the latest reviewable push to be approved, dismiss stale approvals, and require conversation resolution. Use the controls that match the risk of the repository rather than declaring every Augment comment a blocker.

A review outage is not a clean result. ReviewGate represents that asreview_error, open validated blockers as needs_changes, and a clean current-head result as passed. Require ReviewGate'sreviewed_sha to equal the current pull-request head. Separately, require every GitHub check on the latest commit GitHub identifies for that check; depending on repository settings, that can be the head or a test-merge commit.

Worked example: one finding, two heads, one verdict

1. Pull request 42 is ready at head a1b2c3. Automatic Thorough review starts under guideline commit a1b2c3.
2. Augment reports that a new payment retry path can charge twice because the idempotency key is regenerated. The comment cites the path and consequence, so the team accepts it as a blocker.
3. The author opens Fix in Augment, reviews the proposed patch, adds a regression test, and pushes head d4e5f6. The receipt marks the earlier review superseded.
4. Focused tests pass for head d4e5f6, and required integration CI passes on GitHub's applicable head or test-merge commit. The author requests a follow-up review. The finding is closed only after the new code and test refute the original failure path.
5. The ReviewGate check publishes passed for reviewed SHAd4e5f6. GitHub reports the same current head and all required checks pass, so a maintainer can make the merge decision.

If any later push creates g7h8i9, the last step becomes false. The repository does not need to discard the conversation. It needs to withhold the verdict until evidence exists for the new head.

Should you use Augment Code Review, ReviewGate, or both?

Do not add two reviewers merely to produce more comments. Use both only when their authorities differ. ReviewGate is review-only: it runs through GitHub Actions, posts one canonical summary, emits structured reviewed_sha output, and uses passed, needs_changes, and review_errorstates. Augment adds a hosted review and fix workflow. The useful combination is different review inputs plus one clear repository verdict.

If your workflow begins with requirements rather than an existing pull request, the Kiro code review workflow shows how to connect specs, agent-authored code, review obligations, tests, and the exact-head verdict with a spec-to-verdict receipt.

Which Augment code review failure modes should you prevent?

• Relying on the first automatic review after later pushes. Request a follow-up pass and invalidate the old review.
• Counting every comment as a blocker. Require evidence, causal impact, and an explicit disposition policy.
• Resolving the thread without verifying the code. A UI state is not regression evidence.
• Letting guidelines become a style dump. Put deterministic style checks in CI and reserve review rules for repository-specific risk.
• Accepting review unavailability as no findings. Missing evidence is a review error, not a passing result.
• Giving one integration review, mutation, and merge authority.Keep branch policy and final human judgment independent.

Questions about Augment Code Review