source: .claude/rules/review-record.md · generated — edit the markdown, not this file

The Review Record

The detail behind the rule in .claude/CLAUDE.md § Quality Gates › Mandatory: every app-repo PR into main or release/* carries a review record for its head commit, and every later push needs it written again. Read this file before writing, skipping or re-writing a record.

Every PR into main or release/* in the three app repos, except a Dependabot PR whose head is Dependabot’s own commit, carries a review record for its head commit (.claude/CLAUDE.md § Quality Gates; design forge-review-gate.md). That includes ci: and chore: PRs and any docs: PR that touches a file other than Markdown: a label is no safe basis for exemption, because chore: and docs: PRs have changed src/. Branch protection on main requires a PR and green checks but no approval (git-conventions.md § Branch Protection), so this review is the one every app-repo PR gets. The record has two halves, both written by one script, .claude/lib/forge-review-record.sh:

  • a PR comment — the verdict, the commit reviewed, and each finding marked fixed (with its commit), deferred (with where it is recorded) or left as is. There is one comment per writer, edited in place;
  • a commit status named Forge review on the PR’s head, set with the writer’s own gh login: success for an approve or a skip, failure for a block. A status belongs to one commit, so every push leaves the new head without one until the record is written again. Writing it costs no Actions minutes.

How it is written:

  • /forge-review-pr <repo>#<N> writes it at the end of its review, after the fixes; /forge-deliver runs that on every wave PR and single-plan code PR before the merge checkpoint. The script refuses a commit that is not the PR’s head and a base other than main or release/*. It accepts a draft, and the record still counts after gh pr ready, which does not change the head.
  • After any later push — a review fix, a merge of main, “Update branch” — run /forge-review-pr <repo>#<N> again, after the last push and the local record (forge-et-be: git push, then the build record; the frontends: git push, or pnpm e2e:gate --full --push on a PR into release/*, then pnpm test:record, then on a PR into main pnpm e2e:gate --selected with its line in the test evidence, fewer-nightly-reds.md R-1). It runs a delta: when the latest record is approve and its commit is an ancestor of the head, it reviews only the commits since, one by one, and a merge of the base branch with no conflict resolution needs no review. From a block record it also re-checks the listed Blockers; from a skip, or after a force-push, it runs a full review.
  • A skip is the developer’s decision for that PR, with a reason: bash .claude/lib/forge-review-record.sh <owner/repo> <N> <head-sha> --skip "<reason>". It is refused over a block unless --over-block "<reason>" is also given. A skip needs no tracker note; the skip record is the record. The merge-back PR from release/* into main gets a skip naming the hotfix PRs it re-brings, unless it needed a conflict resolution, which is then reviewed as a delta.
  • Dependabot PRs need no review record while the head is Dependabot’s own commit; a head a person pushed onto a Dependabot PR needs a record. Their Forge review status comes from a small workflow in each app repo, forge-review-dependabot.yml (design R-3). Their Test record does not: CI does not run their suite (test-run-cost.md N-5), so before merging, a delivery-team member runs the repo’s local record on the final head, after any rebase, as on any other PR (test-record.md). Check the PR out with gh pr checkout <N> in a worktree of its own, so the record script finds the PR from the branch (a detached checkout has none), install the bumped lockfile (corepack pnpm install --frozen-lockfile in the frontends), then run the record. To bring a Dependabot PR up to date, comment @dependabot rebase: “Update branch” makes a merge commit a person sent, which the workflow leaves without a status. After the rebase, check the PR validation runs (gh run list --branch <branch>): a run on the old head can start after the rebase and cancel the new head’s runs. Cancel the run on the old head, then gh run rerun every cancelled run on the new head, including a second one whose checks already pass from another run; until then GitHub refuses the merge with all required checks green. Why: on forge-et-fe#400 and #401 (2026-11-04) the new heads were left with a cancelled run each, and both merged only after it was re-run. No review record is not no review: green CI and the local record are not enough to merge one. Before merging, read the release notes for breaking changes, find where the code uses the package, and run the checks that exercise it — the browser gate for a runtime, Playwright or axe bump, the full backend build for a test-framework bump, the tool itself for a tooling bump; after merging, check only the areas the bump touches (for a workflow or build-tool bump, the dev deploy and dev’s health). Why: three green Dependabot PRs were merged on CI alone, and the review that followed found Playwright 1.64 hanging on 204 navigations, which CI could not show because no CI job runs a browser (2026-10-15).
  • To hold one package back from a Dependabot group whose other updates are safe, comment @dependabot ignore <package> (or ignore <package> major version) on the group PR, then @dependabot recreate: Dependabot closes the group PR (“updatable in another way”) and opens a new one without that package. Record the held-back package in owed.md with the @dependabot unignore <package> that ends the hold; Dependabot reads commands only on its own PRs, so post it on an open Dependabot PR of the same repo, never on the fix PR. A rebase that Dependabot leaves unanswered (no reaction) is redone with recreate. Why: on 2026-11-11 TanStack Query and jsdom 31 were held back from forge-et-fe#489 and #488 this way while their fixes were made (forge-et-fe#502, #503), and an unignore posted on #502 did nothing.
  • A PR that changes only .md files (README, CLAUDE.md, docs) needs no review. Each app repo’s forge-review-docs-only.yml (design D-14) sets Forge review on its head when every changed file is Markdown; a later commit that touches any other file leaves the new head without a status, so it needs a record. This holds too when the Markdown file is one the test suite reads (BUILD_INPUTS in forge-et-be’s scripts/fast-lane-scope.py, TEST_INPUTS in the frontends’ scripts/fast-lane-scope.mjs); the local record still runs the suite on it (design Q-7).
  • After changing a PR’s base branch, record again — a review, or a skip naming the reason. A status belongs to the commit, not to the base, so the head keeps the status it was given against the old base (design Q-6).
  • The record names the reviewer agent — backend-reviewer in forge-et-be, frontend-reviewer in forge-et-fe and forge-et-pwa. The script refuses a summary without it (design D-15).
  • An approve record carries a Security pass: line — the result of /forge-review-pr step 6a, Security pass: not security-sensitive — <reason>, or on a delta that touches nothing security-sensitive Security pass: unchanged from <sha7>. The script refuses an approve summary without one; a skip needs none.
  • The local record is a required check of its own, Test record: the record script sets it on the commit it tested, so a PR into main or release/* whose head has none cannot merge; CI sets it, in a job of its own after the Fast lane, on a PR that changes only documentation no test or build step reads, and forge-review-dependabot.yml on Dependabot’s own commits. The merge-back PR from release/* into main needs it too: run the local record on its head. Record once, after the last push, as git-conventions.md § The test suites run locally, and the PR records them says, then write or update the review record. A run asked for with gh workflow run does not set it.

Forge review is a required check in the protect-main and protect-releases rulesets of all three app repos, with its source left as “any source”, because a person’s gh login sets it. A PR whose head has no Forge review status, or a failure, cannot be merged from the GitHub UI or with gh pr merge. Creating a release/* branch is exempt (do_not_enforce_on_create on protect-releases), because a release tag’s commit is a merge on main with no status of its own; every PR into the branch still needs a record.

The harness repo has no review record: its PRs ship on green CI and teammate review.

Generated from .claude/rules/review-record.md by .claude/lib/render-docs-html.js. Markdown is canonical.