Review gate: making /forge-review-pr a required check on app-repo PRs — Design
Status: approved (Draft 3) Author: Tharinda Rajapaksha Reviewed by: two fresh-context review passes, 2026-09-30 (Draft 1 “Needs a redraft”, Draft 2 “Ready after Importants”; Draft 3 applies pass 2’s Importants). Approval: Tharinda Rajapaksha (lead), 2026-09-30 Date: 2026-09-30 · approved 2026-09-30 Scope: the delivery harness and the three app repos (
forge-et-be,forge-et-fe,forge-et-pwa).
- Harness: a new record script under
.claude/lib/,/forge-review-pr,/forge-deliver(Stages 10–15, the Human Checkpoints list, the Resume Protocol and the Stage map),.claude/skills/forge-pr-open/SKILL.mdand.claude/skills/forge-plan-author/SKILL.md(their “(optional) /forge-review-pr” lines), .claude/CLAUDE.md(§ Quality Gates and § Role Delegation),.claude/rules/git-conventions.md,.claude/rules/tracker.md(the bug-fix review step), and the guides under.forge/guides/that describe the review.- Each app repo: the PR template, the repo’s
CLAUDE.md, one small Dependabot-only workflow, and one new required status check in theprotect-mainandprotect-releasesrulesets.It changes CI in three repos, which needs the lead’s approval (
.claude/CLAUDE.md § NEVER DO). Adding a required check needs a repo admin.
Context
.claude/CLAUDE.md § Quality Gates has made /forge-review-pr <N> mandatory on every shipped app-repo code PR since 2026-09-18 (commit 13c1fb31). Branch protection on main requires no approval (.claude/rules/git-conventions.md § Branch Protection), so that review is the only review most code PRs get. Nothing enforces it: the rule is text, the PR template has a checkbox, and a PR can be merged in the GitHub UI whatever the review state.
What an audit found (2026-09-30). The audit covered every merged app-repo PR since the rule started: 91 code PRs, Dependabot excluded. It found:
- 64 reviewed before merge;
- 1 ambiguous: fe#33 has a frontend-reviewer pass recorded, but not
/forge-review-pr; - 16 reviewed only after merge, most by the lead’s post-merge audit of 2026-09-28;
- 2 with a skip written in the PR body but no tracker note;
- 8 with no evidence of any review: forge-et-be#35, #40, #75, #76, #88 and forge-et-fe#21, #25, #87.
The gaps come from every author. Three patterns explain most of them:
- Per-WI PRs merged straight to
main. They bypass the wave PR, which is where the review normally runs. - Follow-up and fix PRs are not reviewed themselves. On 2026-09-30, forge-et-be#124’s three late fix commits were merged before any reviewer had read them.
- The record is scattered across PR comments, PR bodies, plan notes,
bugs.mdand unmerged branches. Nobody can tell from a PR whether it was reviewed.
The results are recorded in .forge/engagement-gate-runs.md § Post-merge /forge-review-pr backfill — 2026-09-30.
Why the PR description is not used. All three app repos’ pr-validation.yml list edited in their pull_request types (the comment above on: on each origin/main). A description edit re-runs the whole Fast lane, so a review line written there would cost a full Fast lane run each time. The browser gate avoids this by writing its line in the same step as the push (pnpm e2e:gate --push). A review is written after CI has already run, so it cannot share a push.
Threat model. The gate stops people forgetting the review. It does not stop a writer who means to bypass it. Such a writer can already self-merge, because no approvals are required, and can use the administrator bypass. So the design does not try to prove who wrote a record. It keeps the record honest by having one writer that refuses a stale commit (D-3), and keeps it visible (D-2).
Decisions
| # | Decision | Why |
|---|---|---|
| D-1 | The gate is a commit status named Forge review on the PR’s head commit, set by the record script itself (gh api repos/<owner>/<repo>/statuses/<sha>, with the developer’s own gh login). It is not set by a workflow. The status is success for an approve or skipped record and failure for block. |
GitHub attaches a commit status to one commit. A push makes a new head with no Forge review status, and a required check with no status blocks the merge until one is set. So “the head was reviewed” needs no workflow, costs no Actions minutes, and has no job-naming or concurrency problems. |
| D-2 | Each record is also a PR comment, the human-readable half. The comment starts with the marker in § Contract, then gives the verdict, the commit reviewed, and each finding marked fixed (with its commit), deferred (with where it is recorded) or left as is. A skip gives the reason. There is one comment per writer, updated in place. The most recently updated comment holds the current record. The status’s target_url points at this comment. |
Reviewers and later audits read the record in one place, the PR. It replaces the scattered records the audit found. This mirrors scripts/local-build-evidence.py, which updates the running user’s own comment. |
| D-3 | One script writes every record: .claude/lib/forge-review-record.sh. It writes the comment first, then the status. It refuses a sha that is not the PR’s current head (gh pr view --json headRefOid), and a PR whose base is not main or release/*. It accepts drafts: a draft is not required to have a record, but marking it ready does not change its head, so a record written on the draft still counts. The developer’s skip uses the same script with --skip "<reason>". A skip never silently overrides a block: when the head’s current Forge review status is failure, --skip is refused unless --over-block "<reason>" is also given, and that reason goes into the comment. |
One writer means one format. Refusing a stale commit stops a record from describing code the PR no longer contains. Accepting drafts lets the review and its fix pushes happen while draft CI is short. The last status on a commit wins, so without the over-block rule anyone’s skip would turn a reviewer’s Blocker green with no trace. |
| D-4 | Dependabot PRs get their status from a small workflow, forge-review-dependabot.yml in each app repo, with one job dependabot-review-status (display name “Dependabot review status”). It runs on pull_request_target (opened, synchronize, reopened) with no checkout. Its job-level if: requires the PR author to be dependabot[bot] and the event’s sender to be dependabot[bot]. It writes the status on github.event.pull_request.head.sha, not github.sha, which under pull_request_target is the base branch’s tip. The status is success, described “Dependabot — the full suite runs in CI”. (2026-11-13: CI no longer runs the suite on a Dependabot PR (test-run-cost.md N-5). The workflow sets only Forge review, described “Dependabot — a person reviews and records it before merge”; a delivery-team member’s local record sets Test record.) |
Dependabot PRs already run the full suite in CI (git-conventions.md § The backend test suite runs locally) and nobody reviews them with /forge-review-pr. (Since 2026-11-13 they do not: a person’s local record is their test evidence, test-run-cost.md N-5.) pull_request_target is chosen because it always runs the workflow file from the base branch, so a PR cannot edit its own gate; with no checkout it runs no PR code. The sender condition means a person’s commit pushed onto a Dependabot PR gets no automatic success: that head needs a record. A false job-level if: bills nothing. |
| D-5 | Everything else into main or release/* needs a record, including docs:, ci: and chore: PRs (revised 2026-10-02: a PR that changes only .md files passes automatically, D-14). This widens the rule from “wave and single-plan code PRs” to every non-Dependabot app-repo PR. A PR that the developer decides needs no review gets a skipped record with the reason. The skip record replaces the tracker note the current rule asks for. |
The audit found chore: and docs: PRs that changed src/ (be#35, be#85, pwa#20), so a label is not a safe basis for exemption. A skip is one command, and the record is visible on the PR. PRs into wave branches and drafts need nothing: rulesets do not govern a wave branch, and a draft cannot merge. |
| D-6 | /forge-review-pr takes the PR as forge-et-be#124, altrium-io/forge-et-be#124 or a PR URL. A bare number is refused whenever more than one configured repo has a PR with that number in any state (open, merged or closed). This applies to post-mortem mode too. |
Harness PR numbers (past #324) overlap every app repo’s. Step 1 of the skill tries the harness first, so /forge-review-pr 124 resolved harness#124 on 2026-09-30, which is merged, and ran post-mortem mode. The gate depends on reviewing the right PR. |
| D-7 | Verdict mapping. The skill’s verdicts are approve, approve-with-fixes and block. When the review ends with every Blocker fixed, it writes approve: approve-with-fixes has become approve because its fixes were applied, and every Important left is listed as deferred with where it is recorded. When the review ends with a Blocker still open (escalated to the lead), it writes block and lists each open Blocker in the comment. A Blocker the lead decides to accept is listed as deferred with “accepted by <lead> — <where recorded>”, and the verdict is approve (Q-3). |
The record says what state the head is in, not what the first pass found. block fails the check, and its list is what a later delta must re-check (D-9). |
| D-8 | An out-of-date base is a finding only when main’s new commits touch the PR’s files. Even then the fix is to merge main in, never a rebase. This replaces the skill’s step 2, where an out-of-date base was a Blocker and the skill asked for a rebase. Step 5’s numbering-collision checks for harness PRs (AD and Revision numbers) stay: such a collision touches the same files, so the file-overlap rule still flags it. |
git-conventions.md § Branching says a branch merges main in only for a reason, never because it is behind, and never rebases a pushed branch. With block failing a required check, the old step 2 would force a merge and an extra CI run on every PR that was behind. |
| D-9 | Delta mode, automatic, from an approve record only. When the PR’s latest record is approve and its sha is an ancestor of the head, the skill reviews only what came after it and writes a new record for the head, without asking. It reviews each commit after the record one by one: each ordinary commit’s own diff, and each merge’s own changes. It never uses git diff <sha>..<head>, which would pull in everything main gained. A merge needs no review when all of these hold: it has exactly two parents; its first parent is the recorded sha or a descendant of it; its second parent is an ancestor of origin/<base> (so it merged the base branch, not another feature or work-item branch); and git show --remerge-diff --format= <merge> prints nothing on stdout or stderr (git ≥ 2.36). Any other merge (an octopus, a merge of another branch, one with a conflict resolution or an extra change) is reviewed. From a block record, the delta also re-checks each Blocker the record lists. From a skipped record, or when the recorded sha is not an ancestor (a force-push), the skill runs a full review. |
After review fixes, a merge of main or “Update branch”, the head changes. A full re-review each time would waste time and push people to skip. A delta from a block or skipped record would otherwise let an approve cover code nobody reviewed. The exact merge test closes the gaps a bare “remerge-diff is empty” check leaves: that command prints a header by default, prints nothing for an octopus merge, and prints nothing for a clean merge of a branch that is not the base. |
| D-10 | The fix-and-review loop is bounded, and runs on the draft where it can. The order is: review; apply the safe fixes (.claude/CLAUDE.md § Quality Gates › Apply a review's recommended fixes); push them; run a delta review of the fix commits; write the record. While the PR is a draft, a fix push is a plain git push, because draft CI is short. On a ready PR it goes through the repo’s own path: commit, python3 scripts/local-build-evidence.py, then git push in forge-et-be; pnpm e2e:gate --push in the frontends. The fix → delta round repeats while a delta finds a Blocker or an Important that must be fixed, for at most three delta rounds; a finding still open after that goes to the lead as block (revised 2026-10-01 — see ## Revisions; this replaced “the delta over fix commits fixes Blockers only”). Who pushes fixes: the PR’s author, or someone they have agreed to. A reviewer who is not the author and has no such agreement does not push to the branch (.claude/CLAUDE.md § Boundaries › ASK FIRST). They write block listing the fixes, or leave the record to the author. |
This stops fixes that were never reviewed themselves from reaching main, as happened on be#124, without an endless review-fix-review cycle. Reviewing on the draft keeps each fix push off the full Fast lane. |
| D-11 | /forge-deliver reviews every app-repo wave PR itself, at Stage 12, and every single-plan code PR at Stage 10. It routes the safe fixes to the owning implementer (the orchestrator never edits src/), re-integrates them, runs the delta and writes the record, and only then halts at Stage 13. Where the wave PR can open as a draft first, the review runs on the draft (D-10). The Stage 13 and Stage 14 text keeps one instruction for the person: after any later push (a merge of main, “Update branch”), run /forge-review-pr <repo>#<N>, which is a delta, after the build record or pnpm e2e:gate --push. Resume: Stage 10’s entry check, Stage 12’s resume, the Resume Protocol rows and the Stage map treat a stage as done only when the head carries a success Forge review status (gh api repos/<owner>/<repo>/commits/<sha>/status). An open PR alone is not enough. Where the review runs, in the wave’s own session or a fresh one, is Q-4. |
The merge checkpoint then gets PRs that are already reviewed and recorded. The one push the conventions ask for just before a merge is covered by a cheap delta. Without the resume rule, a session that stopped after the PR opened but before the record was written would resume past the review. |
| D-12 | The status becomes a required check in protect-main and protect-releases in all three app repos, with its source left as “any source”. The existing required checks are pinned to GitHub Actions (integration_id 15368); the new one must not copy that pin. Branch creation: protect-releases has do_not_enforce_on_create: false, so creating a release/* branch needs every required check passing on its commit. The commit a release tag points at is a merge commit on main, which has no Forge review status. This design sets do_not_enforce_on_create: true on protect-releases. Every later push to the release branch still goes through a PR under the same rules (Q-5). The check is added only after the harness changes and the Dependabot workflow are on main and every open PR has a record (§ Rollout). Administrator bypass stays for genuine emergencies, under the existing rule that a PR merged that way says so in its body. |
A required check is the only thing that stops a merge from the GitHub UI. The status is set by a person’s token, so pinning the source to GitHub Actions would reject every record. Without the creation setting, cutting the first release branch at the Phase 1 hand-over would be refused. |
Contract (the record format, version 1)
The script is the only writer. The format changes only in a change that updates the script, this section and /forge-review-pr together.
- Status. Context
Forge review, on the head commit. Statesuccess(verdictapproveorskipped) orfailure(block). The description is under 140 characters:approve · <sha7> · <n> fixed · <m> deferred · <login>,skipped · <reason, truncated> · <login>, orblock · <sha7> · <n> blocker(s) · <login>.target_urlis the comment’s URL. - Comment marker. The first line is exactly
<!-- forge-review v=1 sha=<40 lowercase hex> verdict=<approve|block|skipped> -->. Everything after it is free text for people. Ablockcomment lists each open Blocker. A skip that overrides ablockcarries its--over-blockreason. - No other job or check in these repos may use the name
Forge review. - One comment per writer, updated in place. An older status’s
target_urltherefore opens text that now describes a newer commit. This is accepted: the status’s own description still names the commit it was set for.
Requirements
The harness
- H-1.
.claude/lib/forge-review-record.sh, as D-3 says. Usage:forge-review-record.sh <owner/repo> <pr> <head-sha> <verdict> <summary-file>, or… <owner/repo> <pr> <head-sha> --skip "<reason>" [--over-block "<reason>"]. Behaviour:- Exits non-zero, writing nothing, when the
shais not the PR’s head, the base is notmainorrelease/*, orghis not signed in. - Refuses
--skipwhen the head’s currentForge reviewstatus isfailure, unless--over-blockis given. - If the status write fails after the comment was written, it edits the comment to add “status not set” and exits non-zero.
- The header comment documents all of this.
- Exits non-zero, writing nothing, when the
- H-2.
/forge-review-pr(.claude/commands/forge-review-pr.md):- resolve the PR as
forge-et-be#124,altrium-io/forge-et-be#124or a URL, refusing an ambiguous bare number (D-6); - replace step 2 as D-8 says;
- add the verdict mapping (D-7) and delta mode (D-9);
- after the fixes (D-10), call the script for any PR in the three app repos whose base is
mainorrelease/*; - keep the full verdict comment opt-in (
--comment), and rewrite the “Must Not post without a flag” rule to cover only that comment; - post-mortem mode for merged PRs writes no record.
- resolve the PR as
- H-3.
/forge-deliver, as D-11 says: Stage 10, Stage 12, the Stage 13 and 14 text, the Resume Protocol rows, the Stage map row that marks the review “HUMAN”, and Human Checkpoints item 7. - H-4.
.claude/CLAUDE.md:- At rollout step 1, § Quality Gates › Mandatory gets:
- how to write a record and how to skip (the script, with a reason);
- that the scope is every non-Dependabot app-repo PR into
mainorrelease/*(D-5); - that the harness repo has no such check;
- the second-pass limit of D-10 on “Apply a review’s recommended fixes”.
§ Role Delegation’s
/forge-review-pr <number>line becomes<repo>#<N>.
- At rollout step 4, in a second harness PR, the sentence that the
Forge reviewrequired check enforces the rule. - The tracker note for a skip is dropped only if Q-2 says so.
- At rollout step 1, § Quality Gates › Mandatory gets:
- H-7.
.claude/rules/tracker.md, bug-fix flow step 4: the pre-merge review is/forge-review-pr, which writes the record. A/councilor direct adversarial review is recorded as a skip that names it. - H-8. The other places that describe the review:
.claude/skills/forge-pr-open/SKILL.md(its “(optional) /forge-review-pr” next steps), .claude/skills/forge-plan-author/SKILL.md, and the guides under.forge/guides/that describe it. Each becomes “run by/forge-deliver, or/forge-review-pr <repo>#<N>”. - H-5.
.claude/rules/git-conventions.md: addForge reviewto the required checks for all three app repos, and add a### The review recordsubsection next to the local-build record’s. - H-6. The frontends’ browser-gate skip text says a skip is “reviewed like a
/forge-review-prskip”. Update it to name the skip record.
Each app repo
- R-1. The PR template’s
/forge-review-prcheckbox becomes: “Forge reviewis set by/forge-review-pr’s record (or a skip record with a reason).” - R-2. The repo’s
CLAUDE.mdPR section names the check and the skip command. - R-3.
.github/workflows/forge-review-dependabot.yml, as D-4 says:- one job,
dependabot-review-status; permissions: { statuses: write };- the author and sender condition as a job-level
if:; - the status written on
github.event.pull_request.head.sha; - values passed through environment variables only;
- a non-zero exit if the status write fails.
- one job,
- R-4.
.github/workflows/forge-review-docs-only.yml, as D-14 says (added 2026-10-02). - R-5. In
forge-et-beonly, aBuild recordstep in theFast lane, as D-16 says (added 2026-10-02).
Acceptance criteria
- AC-1. On a test PR in each app repo:
- no record → the merge box shows
Forge reviewas expected and waiting, and the merge is refused (once required); - after
/forge-review-pr→successon the head; - after a push → the new head has no status;
- after a delta review →
successagain.
- no record → the merge box shows
- AC-2. A
blockrecord setsfailure; a skip record setssuccesswith the reason in the description. A skip over ablockis refused without--over-block, and accepted with it, with the reason in the comment. - AC-3. The script refuses a
shathat is not the head, and a PR into a wave branch, writing neither a comment nor a status. It accepts a draft, and the status still counts aftergh pr ready. - AC-4. Cases on a test PR, with the verdicts expected:
- a merge of
mainwith no conflict resolution is recorded by a delta that runs only the merge test of D-9; - a merge with a conflict resolution gets a real delta review;
- an octopus merge gets a real delta review;
- a merge of another feature branch gets a real delta review;
- a delta from a
blockrecord re-checks its listed Blockers; - a delta from a
skippedrecord runs a full review.
- a merge of
- AC-5.
/forge-review-pr forge-et-be#124reviews the backend PR./forge-review-pr 124is refused as ambiguous, because harness#124 exists (merged). A grep over the H-3 and H-8 files finds no bare/forge-review-pr <N>left. - AC-6.
/forge-deliverStage 12 leaves every app-repo wave PR with asuccessstatus before Stage 13 halts, and a resumed session that stopped after the PR opened runs the review instead of skipping it. This is checked on the first app-repo wave delivered after rollout step 4. - AC-7. A Dependabot PR gets
successfrom R-3 with no record. A commit a person pushes onto a Dependabot PR gets no automatic status. The run list shows that the workflow billed nothing on a non-Dependabot PR. - AC-8.
pull_request_targetwrites the status on a Dependabot PR’s head, not on the base tip (a probe on the next Dependabot PR). If it cannot, switch topull_requestwithpermissions: statuses: write. If that also fails, a person writes a skip record on Dependabot PRs, and the design is revised. - AC-9. Once required, the GitHub UI refuses to merge a PR with no status for its head. This is a probe on a test PR, the same way the ruleset rules were probe-verified.
- AC-10. With the check required and
do_not_enforce_on_create: true, creating arelease/*branch from a tag onmainsucceeds, and a PR into it still needs a record (a probe, deleted afterwards by a repo admin).
Scope
In scope. Every non-Dependabot PR into main or release/* in the three app repos.
Out of scope, each for a stated reason:
- The harness repo. Its PRs carry specs, plans and the tracker. They ship on green CI and teammate review (
.claude/CLAUDE.md § Quality Gates). - Per-WI PRs into wave branches. They cannot merge to
main; their code is reviewed on the wave PR. - Drafts. A draft cannot merge.
- Post-mortem reviews of merged PRs. They write no record.
- Fork PRs. The repos are private and there are none. A fork PR would still need a record, which a team member can write.
The merge-back PR from release/* into main. It re-brings commits already reviewed on their hotfix PRs. It gets a skipped record naming those hotfix PRs, unless it needed a conflict resolution, which is then reviewed as a delta.
Rollout
- The first harness PR merges: the script,
/forge-review-pr,/forge-deliver,git-conventions.md,tracker.md, H-8, and H-4’s step-1 wording. From then on, records are written, but nothing requires them. - Each app repo gets a PR with
forge-review-dependabot.yml, the template change and itsCLAUDE.mdline. Each of those PRs gets a record too. - Every open non-draft PR in the three repos gets a record, from a review or a skip. Open Dependabot PRs get their status by a
@dependabot rebasecomment, which firessynchronize, or by a skip. - Just before the ruleset change, the open PRs are swept again, because a push since step 3 leaves a head with no status. Then a repo admin:
- adds
Forge reviewtoprotect-mainandprotect-releasesin each repo, source “any source”; - sets
do_not_enforce_on_create: trueonprotect-releases; - runs the AC-9 and AC-10 probes. The second harness PR, with H-4’s enforcement sentence, merges the same day.
- adds
- No
release/*branch exists yet (no phase has gone live). The first one is cut after step 4 (AC-10).
Rejected alternatives
| Alternative | Why rejected |
|---|---|
A workflow on issue_comment that reads the record comment and sets the status (Draft 1) |
Every run needs a concurrency group per PR. It costs a billed minute per push and per record. It adds a job whose own check run would clash with the status name. It also writes exempt statuses onto commits that can later become a wave PR’s head. The script setting the status directly has none of these problems and costs nothing. |
A Forge review: line in the PR description, read by the Fast lane |
A description edit re-runs the whole Fast lane (edited trigger), which is a full run per review. |
The Fast lane reading a record comment |
Nothing re-runs the Fast lane on a comment, so a record written after CI ran would need a manual re-run of the whole lane. |
| A GitHub App posting a check run | It needs an App to build, host and secure. It adds nothing the threat model needs. |
Requiring one approval on main |
The author cannot approve their own PR, and the team relies on self-merge. The lead removed the approval on purpose (git-conventions.md § Branch Protection). |
A harness hook on gh pr merge |
Merges happen in the GitHub UI, where a hook cannot run. The required check covers both. |
Minutes cost
- Normal PRs: none. The script calls the GitHub API from the developer’s machine.
- Dependabot PRs: one billed minute per
opened,synchronizeorreopenedevent. Non-Dependabot PRs skip the job, so they bill nothing.
Where each rule lives
| Rule | Home |
|---|---|
| An app-repo PR needs a review record for its head | .claude/CLAUDE.md § Quality Gates › Mandatory, enforced by the Forge review required check |
| The record format and the one writer | § Contract; .claude/lib/forge-review-record.sh header |
When /forge-review-pr writes the record; delta mode; verdict mapping; PR resolution |
.claude/commands/forge-review-pr.md |
| The orchestrator reviews before the merge checkpoint | .claude/commands/forge-deliver.md Stages 10, 12, 13, 14 |
| Which checks are required, and the record subsection | .claude/rules/git-conventions.md § Branch Protection, § The review record (the detail moved to .claude/rules/review-record.md on 2026-10-02) |
| The Dependabot status | each app repo’s .github/workflows/forge-review-dependabot.yml |
| What a PR author sees | each app repo’s PR template (R-1) and CLAUDE.md (R-2) |
| The browser-gate skip text that referred to the old skip rule | the frontends’ CLAUDE.md (H-6) |
Open questions
- Q-1 [lead]. A PR that changes only Markdown files: should it need a
skippedrecord, or be exempt automatically? This design proposes a record. Automatic exemption would need a workflow run on every PR. Decided 2026-09-30 (lead): a Markdown-only PR needs askippedrecord, as this design proposes. There is no automatic exemption. Revised 2026-10-02 (lead): a PR that changes only.mdfiles passes automatically (D-14,## Revisions). - Q-2 [lead]. Should the skip record replace the tracker note for a skip? This design proposes yes. Decided 2026-09-30 (lead): yes. The skip record replaces the tracker note.
- Q-3 [lead]. If the lead decides to accept a reviewer’s Blocker, should it still be allowed to merge? This design says the review is re-run after the decision and records the Blocker as deferred (“accepted by
<lead>”), so the verdict becomesapprove(D-7). Decided 2026-09-30 (lead): as this design says. The review is re-run after the decision, the Blocker is recorded as deferred (“accepted by<lead>”), and the verdict isapprove. - Q-4 [lead]. Where should the orchestrator’s review run? The wave session is already the heaviest session unit (
forge-deliver § Context budget), and it built the code it would review.- Option A (this design’s default): the review runs at the end of Stage 12 in the same session. It is simplest, and the reviewer sub-agents still start with a fresh context.
- Option B: a new soft-boundary session unit, “Review wave N”, starts fresh after Stage 12 opens the PR. It keeps the wave session lighter, and the orchestrator reading the review has not built the code, at the cost of one more re-invocation per wave.
- Decided 2026-09-30 (lead): Option A. The review runs at the end of Stage 12, in the wave’s own session.
- Q-5 [lead]. Setting
do_not_enforce_on_create: trueonprotect-releasesmeans a new release branch no longer needs its commit to pass the required checks when it is created. Today this may already block creating one forFast laneandSlow lanetoo, because pushes tomainrun no CI. Every later change to the branch still needs a PR under all the checks. Is that acceptable? The alternative is a rule that the person cutting a release writes aForge reviewstatus onto the tag commit. Decided 2026-09-30 (lead): acceptable.protect-releasesgetsdo_not_enforce_on_create: true. - Q-6 [lead] (raised 2026-10-02, to decide before rollout step 5). A
Forge reviewstatus belongs to a commit, not to a PR and its base (D-1). If a PR is retargeted to another base, or the same head is opened against another base, the head keeps its status, although the diff the status was given for has changed. The case that matters: a Markdown-only PR intomainretargeted torelease/*, whose diff then includes the codemainhas and the release branch lacks. The same holds for a record written by the script.editedis not among the workflows’ triggers, so nothing re-checks on a retarget. It cannot happen while norelease/*branch exists.- A related case, live today: a person writes
blockon a Markdown-only PR, and the author then pushes another Markdown-only commit. The new head has no status, so the docs-only workflow writessuccesson it. The existing-status check protects only the commit that carries theblock. The record script refuses a plain skip after ablock; the workflow does not apply that rule. Ablockon a Markdown-only PR is rare, because such a PR needs no review. - Option A (recommended): accept both, and add one line to
git-conventions.md § The review record: after changing a PR’s base, write a new record (or a skip naming the reason). Accept that a later Markdown-only push clears ablockon a Markdown-only PR, since such a PR needs no review. Nothing to build. - Option B: add
editedto the docs-only workflow’s triggers, with a jobif:limited to a base change, and have it writepending(“base changed — needs a record”) when the PR is no longer Markdown-only. This covers only the docs-only status, not records the script wrote, and bills a minute per base change. - Decided 2026-10-02 (lead): Option A.
.claude/rules/review-record.mdsays to write a new record after changing a PR’s base.
- A related case, live today: a person writes
- Q-7 [lead] (raised 2026-10-02). In forge-et-be some Markdown files are build inputs: the test suite reads
docs/audit/README.md, the audit event-code list, and the backend’s slow-lane scope script lists such files. D-14 exempts every.mdfile from review, so a PR that changes only that list getsForge reviewwith no review. It still needs a build record (D-16), so the suite runs on it.- Option A (recommended): accept it. The suite checks the event codes against the code, and the file is documentation for people.
- Option B: in forge-et-be only, the docs-only workflow also refuses a PR that touches a file the scope script lists as a build input. The workflow is then no longer the same file in all three repos.
- Decided 2026-10-02 (lead): Option A. A Markdown-only PR in forge-et-be is exempt from review even when it changes a build input; the build record still runs the suite on it.
Revisions
Draft 2 — 2026-09-30 (before approval)
- Trigger: a fresh-context review of Draft 1 (“Needs a redraft”: 1 Blocker, 11 Importants, 12 Nits).
- Changed: the status is now set by the record script, not by a workflow (D-1). This removes the Blocker (a job named like the status), the concurrency Important, the exempt-status-on-shared-commits Important and the minutes question. Also changed in response to the Importants:
- a threat model (Context);
<repo>#<N>PR resolution (D-6);- the verdict mapping (D-7);
- the out-of-date-base rule (D-8);
- an automatic delta with the remerge-diff check (D-9);
- the bounded loop (D-10);
- fixes routed to implementers, with the Stage 13 and 14 instruction kept (D-11);
- “any source” for the required check (D-12);
- § Contract with a version field;
- § Scope, including release merge-back PRs;
- § Rejected alternatives;
CLAUDE.mdwording timed with the ruleset change (H-4, Rollout). The nits are applied as well: the count now includes fe#33, “all three” repos, the local-build-evidence wording,target_url, and extra ACs and table rows.
Draft 3 — 2026-09-30 (before approval)
- Trigger: a second fresh-context review, of Draft 2 (“Ready after Importants”: no Blocker, 12 Importants, 10 Nits). This is the last automatic pass. The lead approves or asks for more.
- Changed, in response to the Importants:
- I-1:
protect-releasesenforces required checks on branch creation, so D-12 setsdo_not_enforce_on_create: true, with AC-10 and Q-5. - I-2: D-9’s exact merge test (two parents, second parent an ancestor of the base,
--format=with nothing on stdout or stderr), a per-commit delta rather thangit diff <sha>..<head>, and more AC-4 cases. - I-3: a delta only from an
approverecord; fromblockit re-checks the listed Blockers; fromskippedit runs a full review. - I-4: a skip cannot silently override a
block(--over-block). - I-5: D-4’s reason corrected; the sender condition; the status written on the PR’s head sha; AC-8’s fallback replaced.
- I-6: an ambiguous number in any PR state; the accepted forms listed.
- I-7: records allowed on drafts, and the review runs on the draft where it can.
- I-8: resume checks the status, not just an open PR.
- I-9: where the review runs is Q-4.
- I-10: the files that still describe the review as optional are in scope (H-8).
- I-11:
tracker.md’s bug-fix review step (H-7). - I-12: a non-author does not push fixes without the author’s agreement.
- I-1:
- Nits applied:
- the comment is edited when the status write fails;
- D-7’s wording;
- H-4 split between rollout steps 1 and 4, with the tracker note tied to Q-2;
- D-10’s narrowing named in H-4;
- the Dependabot job named;
- the
target_urllimit accepted in § Contract; - the rollout re-sweep and Dependabot rebase;
- AC-6 no longer names specific waves;
- D-8 keeps the numbering-collision checks.
Approved — 2026-09-30
- Approved by Tharinda Rajapaksha (lead) as Draft 3. Q-1 to Q-5 are decided (see
## Open questions): each takes this design’s default, with Option A for Q-4. The harness half is implemented by.claude/lib/forge-review-record.shand the rule and skill changes H-2 to H-8. The enforcement sentence (H-4, rollout step 4) and the app-repo changes (R-1 to R-3, H-6) follow in later PRs. - H-5’s line adding
Forge reviewto the required checks moves to rollout step 4, in the second harness PR with the ruleset change; the first harness PR’sgit-conventions.mdsays only that the status becomes required at step 4. H-6 moves to the app-repo PRs, because the browser-gate skip text it changes lives in the frontends’CLAUDE.md; it is no longer in rollout step 1’s list.
Implementation note — 2026-10-01
- D-3: the script also refuses a plain skip when the PR’s latest record is
block, not only when the head’s status isfailure. A push after ablockleaves the new head with no status, so the status check alone would accept a plain--skipthere. It reads the record comments, newest byupdated_at, first line only, and refuses when the PR’s latest record or the writer’s own latest record saysverdict=block, unless--over-blockis given.
Revision — 2026-10-01: fix and re-review until clean (lead decision)
- Trigger: Tharinda Rajapaksha (lead), 2026-10-01: app-repo reviews are mandatory for every team member, and a review’s findings that should be fixed are fixed and re-reviewed until none is open; Nits may be left when they are not needed or are intended.
- D-10 changes. It no longer limits the delta over fix commits to Blockers. The loop is now: review; fix every Blocker and every Important; push; delta over the fix commits; repeat while a delta finds a Blocker or an Important. An Important stays unfixed in the PR only as the lead’s decision, a problem in code the PR did not change, or the reviewer’s own “leave as is”, each recorded with its reason and home. A Nit is fixed when cheap and otherwise left with a one-line reason. After three delta rounds, a finding still open goes to the lead as a
blockrecord. This replaces D-10’s “the delta over fix commits fixes Blockers only”. - D-7 changes.
blocknow also covers an Important that must be fixed and is still open: the summary lists it as- **Open Important**. The record script refuses anapprovesummary with anOpen BlockerorOpen Importantline, and ablocksummary with neither. Theblockstatus description readsblock · <sha7> · <n> blocker(s) · <m> important · <login>. - Changed with it:
.claude/lib/forge-review-record.sh(and its self-test),/forge-review-prstep 9 and the verdict table,/forge-deliverStages 10 and 12, and.claude/CLAUDE.md § Quality Gates › Apply a review's recommended fixes. - Enforcement for the whole team is still the required
Forge reviewcheck (D-12, rollout step 4). Until a repo admin adds it, the rule is in the instructions and the record only.
Revision — 2026-10-02: a hard gate, docs-only PRs, the reviewer agent, the build record (lead decisions)
- Trigger: Tharinda Rajapaksha (lead), 2026-10-02. All four answers took the recommended option:
- every app-repo PR is gated so it cannot merge without a review by
/forge-review-prwith the repo’s reviewer agent; - PRs with only documentation changes (README,
CLAUDE.mdand the like) are exempt; - CI fails a backend PR with no build record;
- rollout step 4 (the required check) goes ahead.
- every app-repo PR is gated so it cannot merge without a review by
- D-14 (new): a PR that changes only
.mdfiles passes automatically. This revises Q-1 and D-5..github/workflows/forge-review-docs-only.ymlin each app repo:- Trigger:
pull_request_target(opened,synchronize,reopened,ready_for_review) withpaths: ['**/*.md', '*.md'], so it starts only when the PR touches a Markdown file. A code-only PR never starts it and bills nothing. - Check: one job,
docs-only-review-status, with no checkout. It lists the PR’s files through the API (gh api repos/<repo>/pulls/<N>/files --paginate). Only when every filename ends in.mddoes it writeForge review=success, described “docs only — every changed file is Markdown”, ongithub.event.pull_request.head.sha. Otherwise it writes nothing, so the head stays without a status and needs a record. - A later code commit cannot ride on an earlier docs-only pass. If it touches no
.mdfile the workflow does not run, and if it does, the file check fails. Either way the new head has no status. - Same shape as D-4:
pull_request_target, so a PR cannot edit its own gate; values through environment variables; a non-zero exit if the status write fails. - Cost: about one billed minute per PR event that touches a
.mdfile.
- Trigger:
- D-15 (new): the record names the reviewer agent. The record script refuses a summary (
approveorblock) that does not name the repo’s agent:backend-reviewerforforge-et-be,frontend-reviewerforforge-et-feandforge-et-pwa./forge-review-prdispatches the agent and writes its name into the summary. A skip is not affected. - D-16 (new): CI checks the backend build record. In
forge-et-be, theFast lanegains aBuild recordstep on a ready, non-Dependabot PR. It reads the PR’s comments withgh api(no JDK) and fails unless one, written by a member of the delivery team, starts<!-- local-build-evidence sha=<the PR's head sha>.- Order: the order of work is commit, record, push, so the record already exists when the push starts CI.
- A push made before the record: the step fails. Re-run the job after recording, which is cheap: the step is first in its job and needs no build.
- Exempt: Dependabot PRs, which run the suite in CI.
- Why: it closes be#101’s I-2. A skipped
Slow lanecounts as passing, so until now a PR with no record merged green.
- Rollout: D-14 and D-16 land in rollout step 2 with R-3 (the app-repo PRs). D-15 lands now, with this harness PR. Step 4’s ruleset change is unchanged.
- Changed with it:
.claude/lib/forge-review-record.sh(D-15, self-test 53 cases),/forge-review-prstep 10,.claude/CLAUDE.md § Quality Gates,.claude/rules/git-conventions.md § The review record.
Implementation note — 2026-10-02: rollout step 2 (the app-repo PRs)
- Where it is: forge-et-be#141, forge-et-fe#108 and forge-et-pwa#48 carry R-1 to R-5 and H-6. The two status workflows are the same file in all three repos.
- Both status workflows leave an existing status alone. Before writing, each reads the head’s statuses and writes nothing when one named
Forge reviewexists. The last status on a commit wins, so without this areopenedorready_for_reviewevent, or a re-run, none of which changes the head, would turn a person’sblockgreen with no trace (the rule D-3 sets for skips). Found byfrontend-revieweron forge-et-fe#108 (I-1). - D-14 corrected. The revision above says a later commit that touches no
.mdfile does not start the docs-only workflow. That is not how GitHub’spathsfilter works onpull_request_target: it checks the PR’s whole diff against its base, not the pushed commit. A docs PR that gains a code commit still starts the run, which then finds the code file and writes nothing. The outcome is the one D-14 states. - D-16’s step position. The
Build recordstep runs after theDecide how much of the build runsstep, not first in the Fast lane, so it is skipped where that step givesfull=false: on a draft, and on a PR that changes only documentation no build step reads (as forge-et-be’s slow-lane scope script decides). Such a PR needs no build record. The two exemptions differ in forge-et-be: D-14 exempts every.mdfile from review, but some Markdown files there are build inputs (the test suite readsdocs/audit/README.md, the audit event-code list). A PR that changes only such a file getsForge reviewfrom the docs-only workflow with no review, and still needs a build record, so the suite runs on it. Whether such a file should need a review is raised to the lead (Q-7). The step also runs only on PRs intomainorrelease/*, and before the JDK setup and the build. It reads the delivery team from the*line of.github/CODEOWNERSon the base branch (HEAD^1), so a PR cannot add its own author. Re-running the job after a late record re-runs the whole Fast lane. - AC-11 (new): the docs-only probe, run on a test PR in each app repo after the workflow is on
main:- a PR that changes only
.mdfiles getssuccess, described “docs only — every changed file is Markdown”; - a PR that also changes another file gets no status;
- a PR that renames a code file to
.mdgets no status; - a head that already has a
blockkeeps it after a re-run; - the job’s token is enough for the API reads (a 403 means a missing permission).
- a PR that changes only
- Lead decisions, 2026-10-02: Q-6 and Q-7 both take Option A (see
## Open questions). The one rule change, recording again after a base change, is in.claude/rules/review-record.md(thengit-conventions.md § The review record).
Implementation note — 2026-10-02: rollout steps 2 to 4 done, the check is required
- Step 2: forge-et-be#141, forge-et-fe#108 and forge-et-pwa#48 merged on 2026-10-02, each with an
approverecord. The rules for the record now live in.claude/rules/review-record.md. - AC-11 (the docs-only probe), passed on forge-et-pwa#50, closed without merging. A Markdown-only head got
success, “docs only — every changed file is Markdown”. A re-run of the same job printed “already has a Forge review status; left as it is” and left the one status in place. A later commit renamingscripts/browser-gate.mjsto.mdgot no status, and the job named the old file. No API call was refused, so the job’s token is enough. - Step 3: every open, ready PR in the three repos had a record before the change: forge-et-be#138 and #144
approve; forge-et-be#134, #135, #137 and #139block. Drafts need none. No Dependabot PR was open. - Step 4, 2026-10-02, by Tharinda (repo admin):
Forge reviewwas added, with no app pin, toprotect-mainandprotect-releasesin all three repos, anddo_not_enforce_on_createset totrueonprotect-releases. Every other rule in the six rulesets is unchanged, checked by diffing each against a copy taken just before. - AC-9, passed on forge-et-pwa#51 (a change to
.editorconfig, closed without merging): withFast lanegreen and no record, GitHub reported the PRBLOCKED; after a skip record it reportedCLEAN. The probe read GitHub’s merge state rather than attempting a merge. - AC-10, not yet run. The repository-admin role bypasses
protect-releases(bypass_mode: always), so a probe by an admin would create the branch whatever the setting is and prove nothing. It needs someone with write access and no admin, or it is checked when the firstrelease/*branch is cut at the Phase 1 hand-over. - AC-7 and AC-8 (the Dependabot workflow), not yet run: no Dependabot PR was open. They are checked on the next one.
- Changed with it:
.claude/CLAUDE.md § Quality Gates(the enforcement sentence, H-4),.claude/rules/review-record.md, the required-checks list ingit-conventions.md § Branch Protection(H-5), and/forge-review-prstep 10.
Implementation note — 2026-10-02: the Dependabot and release-branch checks, re-checked
-
AC-7, the billing half, passed. Every run of
Forge review — Dependabotso far was on a non-Dependabot PR: 26 in forge-et-be, 16 in forge-et-fe and 14 in forge-et-pwa, allskipped(gh run list -w "Forge review — Dependabot" -L 200). One run per repo was checked withgh api repos/altrium-io/<repo>/actions/runs/<id>/timing: forge-et-be 37031792842, forge-et-fe 37008292276 and forge-et-pwa 36998273654 each have oneDependabot review statusjob,skipped, withbillable.UBUNTU.total_ms0. -
AC-7’s success half and AC-8, still not run. No Dependabot PR was open in the three repos (
gh pr list --author app/dependabot). The latest ones (forge-et-be#130, forge-et-fe#91, forge-et-pwa#43) merged on 2026-09-30, before the workflow existed. They are checked on the next Dependabot PR: its head hasForge reviewsuccess, “Dependabot — the full suite runs in CI”, set by the workflow’s run on that head. -
AC-10, still not run; the steps are drafted for a teammate. In forge-et-pwa, Dinil Gamage, Biseni Perera and Nanndish Satgunarajah have write access and no admin (collaborator list, 2026-10-02), so any of them can run it. The steps:
- Create
release/v0.0.0-probefrommainthrough the API. This should succeed. The repo has no tags yet, so the branch is cut frommain’s tip, not from a tag as AC-10 says; the creation rule is the same either way. - Open a ready PR into it that changes
.editorconfig. - Confirm that
gh pr checks <N> --requiredlistsForge reviewas missing and that the merge state isBLOCKED.BLOCKEDalone proves nothing, becauserelease/*also needs a Code Owner’s approval. - Close the PR without merging. A repo admin then deletes the branch, since the
deletionrule stops anyone else from doing it.
The steps have not been sent to anyone yet.
- Create
-
Found alongside it: three comments in forge-et-pwa called the error-screen
<main>fix BUG-058, the number #47 was first filed under; the bug is BUG-060. forge-et-pwa#57 corrects them. It has anapproverecord and a passing browser gate, and the lead merges it.
Implementation note — 2026-10-05: AC-7’s success half and AC-8, run on forge-et-be#190
- AC-7’s success half passed. forge-et-be#190 was a Dependabot PR (author
app/dependabot, heade33a97c, authored bydependabot[bot]). Its head hasForge reviewsuccess, “Dependabot — the full suite runs in CI”, with no review record (gh api repos/altrium-io/forge-et-be/commits/e33a97c0a11f0677c82a0f1596de7e8f54b88038/status). The half “a commit a person pushes onto a Dependabot PR gets no automatic status” is still unrun; it is checked the next time someone pushes to a Dependabot PR. - AC-8 passed. The status sits on the PR’s head commit, not on the base tip, so
pull_request_targetworks and no fallback is needed. - AC-10 is unchanged: still unrun, with the steps above.