source: .forge/design/harness/forge-review-gate.md · generated — edit the markdown, not this file

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.md and .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 the protect-main and protect-releases rulesets.

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:

  1. Per-WI PRs merged straight to main. They bypass the wave PR, which is where the review normally runs.
  2. 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.
  3. The record is scattered across PR comments, PR bodies, plan notes, bugs.md and 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. State success (verdict approve or skipped) or failure (block). The description is under 140 characters: approve · <sha7> · <n> fixed · <m> deferred · <login>, skipped · <reason, truncated> · <login>, or block · <sha7> · <n> blocker(s) · <login>. target_url is 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. A block comment lists each open Blocker. A skip that overrides a block carries its --over-block reason.
  • 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_url therefore 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 sha is not the PR’s head, the base is not main or release/*, or gh is not signed in.
    • Refuses --skip when the head’s current Forge review status is failure, unless --over-block is 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.
  • H-2. /forge-review-pr (.claude/commands/forge-review-pr.md):
    • resolve the PR as forge-et-be#124, altrium-io/forge-et-be#124 or 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 main or release/*;
    • 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.
  • 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 main or release/* (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 review required check enforces the rule.
    • The tracker note for a skip is dropped only if Q-2 says so.
  • H-7. .claude/rules/tracker.md, bug-fix flow step 4: the pre-merge review is /forge-review-pr, which writes the record. A /council or 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: add Forge review to the required checks for all three app repos, and add a ### The review record subsection next to the local-build record’s.
  • H-6. The frontends’ browser-gate skip text says a skip is “reviewed like a /forge-review-pr skip”. Update it to name the skip record.

Each app repo

  • R-1. The PR template’s /forge-review-pr checkbox becomes: “Forge review is set by /forge-review-pr’s record (or a skip record with a reason).”
  • R-2. The repo’s CLAUDE.md PR 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.
  • R-4. .github/workflows/forge-review-docs-only.yml, as D-14 says (added 2026-10-02).
  • R-5. In forge-et-be only, a Build record step in the Fast 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 review as expected and waiting, and the merge is refused (once required);
    • after /forge-review-pr → success on the head;
    • after a push → the new head has no status;
    • after a delta review → success again.
  • AC-2. A block record sets failure; a skip record sets success with the reason in the description. A skip over a block is refused without --over-block, and accepted with it, with the reason in the comment.
  • AC-3. The script refuses a sha that 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 after gh pr ready.
  • AC-4. Cases on a test PR, with the verdicts expected:
    • a merge of main with 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 block record re-checks its listed Blockers;
    • a delta from a skipped record runs a full review.
  • AC-5. /forge-review-pr forge-et-be#124 reviews the backend PR. /forge-review-pr 124 is 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-deliver Stage 12 leaves every app-repo wave PR with a success status 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 success from 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_target writes the status on a Dependabot PR’s head, not on the base tip (a probe on the next Dependabot PR). If it cannot, switch to pull_request with permissions: 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 a release/* branch from a tag on main succeeds, 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

  1. 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.
  2. Each app repo gets a PR with forge-review-dependabot.yml, the template change and its CLAUDE.md line. Each of those PRs gets a record too.
  3. 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 rebase comment, which fires synchronize, or by a skip.
  4. 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 review to protect-main and protect-releases in each repo, source “any source”;
    • sets do_not_enforce_on_create: true on protect-releases;
    • runs the AC-9 and AC-10 probes. The second harness PR, with H-4’s enforcement sentence, merges the same day.
  5. 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, synchronize or reopened event. 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 skipped record, 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 a skipped record, as this design proposes. There is no automatic exemption. Revised 2026-10-02 (lead): a PR that changes only .md files 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 becomes approve (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 is approve.
  • 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: true on protect-releases means 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 for Fast lane and Slow lane too, because pushes to main run 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 a Forge review status onto the tag commit. Decided 2026-09-30 (lead): acceptable. protect-releases gets do_not_enforce_on_create: true.
  • Q-6 [lead] (raised 2026-10-02, to decide before rollout step 5). A Forge review status 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 into main retargeted to release/*, whose diff then includes the code main has and the release branch lacks. The same holds for a record written by the script. edited is not among the workflows’ triggers, so nothing re-checks on a retarget. It cannot happen while no release/* branch exists.
    • A related case, live today: a person writes block on a Markdown-only PR, and the author then pushes another Markdown-only commit. The new head has no status, so the docs-only workflow writes success on it. The existing-status check protects only the commit that carries the block. The record script refuses a plain skip after a block; the workflow does not apply that rule. A block on 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 a block on a Markdown-only PR, since such a PR needs no review. Nothing to build.
    • Option B: add edited to the docs-only workflow’s triggers, with a job if: limited to a base change, and have it write pending (“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.md says to write a new record after changing a PR’s base.
  • 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 .md file from review, so a PR that changes only that list gets Forge review with 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.md wording 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-releases enforces required checks on branch creation, so D-12 sets do_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 than git diff <sha>..<head>, and more AC-4 cases.
    • I-3: a delta only from an approve record; from block it re-checks the listed Blockers; from skipped it 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.
  • 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_url limit 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.sh and 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 review to the required checks moves to rollout step 4, in the second harness PR with the ruleset change; the first harness PR’s git-conventions.md says 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 is failure. A push after a block leaves the new head with no status, so the status check alone would accept a plain --skip there. It reads the record comments, newest by updated_at, first line only, and refuses when the PR’s latest record or the writer’s own latest record says verdict=block, unless --over-block is 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 block record. This replaces D-10’s “the delta over fix commits fixes Blockers only”.
  • D-7 changes. block now also covers an Important that must be fixed and is still open: the summary lists it as - **Open Important**. The record script refuses an approve summary with an Open Blocker or Open Important line, and a block summary with neither. The block status description reads block · <sha7> · <n> blocker(s) · <m> important · <login>.
  • Changed with it: .claude/lib/forge-review-record.sh (and its self-test), /forge-review-pr step 9 and the verdict table, /forge-deliver Stages 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 review check (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-pr with the repo’s reviewer agent;
    • PRs with only documentation changes (README, CLAUDE.md and the like) are exempt;
    • CI fails a backend PR with no build record;
    • rollout step 4 (the required check) goes ahead.
  • D-14 (new): a PR that changes only .md files passes automatically. This revises Q-1 and D-5. .github/workflows/forge-review-docs-only.yml in each app repo:
    • Trigger: pull_request_target (opened, synchronize, reopened, ready_for_review) with paths: ['**/*.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 .md does it write Forge review = success, described “docs only — every changed file is Markdown”, on github.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 .md file 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 .md file.
  • D-15 (new): the record names the reviewer agent. The record script refuses a summary (approve or block) that does not name the repo’s agent: backend-reviewer for forge-et-be, frontend-reviewer for forge-et-fe and forge-et-pwa. /forge-review-pr dispatches 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, the Fast lane gains a Build record step on a ready, non-Dependabot PR. It reads the PR’s comments with gh 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 lane counts 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-pr step 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 review exists. The last status on a commit wins, so without this a reopened or ready_for_review event, or a re-run, none of which changes the head, would turn a person’s block green with no trace (the rule D-3 sets for skips). Found by frontend-reviewer on forge-et-fe#108 (I-1).
  • D-14 corrected. The revision above says a later commit that touches no .md file does not start the docs-only workflow. That is not how GitHub’s paths filter works on pull_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 record step runs after the Decide how much of the build runs step, not first in the Fast lane, so it is skipped where that step gives full=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 .md file from review, but some Markdown files there are build inputs (the test suite reads docs/audit/README.md, the audit event-code list). A PR that changes only such a file gets Forge review from 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 into main or release/*, and before the JDK setup and the build. It reads the delivery team from the * line of .github/CODEOWNERS on 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 .md files gets success, 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 .md gets no status;
    • a head that already has a block keeps it after a re-run;
    • the job’s token is enough for the API reads (a 403 means a missing permission).
  • 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 (then git-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 approve record. 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 renaming scripts/browser-gate.mjs to .md got 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 #139 block. Drafts need none. No Dependabot PR was open.
  • Step 4, 2026-10-02, by Tharinda (repo admin): Forge review was added, with no app pin, to protect-main and protect-releases in all three repos, and do_not_enforce_on_create set to true on protect-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): with Fast lane green and no record, GitHub reported the PR BLOCKED; after a skip record it reported CLEAN. 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 first release/* 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 in git-conventions.md § Branch Protection (H-5), and /forge-review-pr step 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 — Dependabot so far was on a non-Dependabot PR: 26 in forge-et-be, 16 in forge-et-fe and 14 in forge-et-pwa, all skipped (gh run list -w "Forge review — Dependabot" -L 200). One run per repo was checked with gh api repos/altrium-io/<repo>/actions/runs/<id>/timing: forge-et-be 37031792842, forge-et-fe 37008292276 and forge-et-pwa 36998273654 each have one Dependabot review status job, skipped, with billable.UBUNTU.total_ms 0.

  • 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 has Forge review success, “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:

    1. Create release/v0.0.0-probe from main through the API. This should succeed. The repo has no tags yet, so the branch is cut from main’s tip, not from a tag as AC-10 says; the creation rule is the same either way.
    2. Open a ready PR into it that changes .editorconfig.
    3. Confirm that gh pr checks <N> --required lists Forge review as missing and that the merge state is BLOCKED. BLOCKED alone proves nothing, because release/* also needs a Code Owner’s approval.
    4. Close the PR without merging. A repo admin then deletes the branch, since the deletion rule stops anyone else from doing it.

    The steps have not been sent to anyone yet.

  • 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 an approve record 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, head e33a97c, authored by dependabot[bot]). Its head has Forge review success, “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_target works and no fallback is needed.
  • AC-10 is unchanged: still unrun, with the steps above.

Generated from .forge/design/harness/forge-review-gate.md by .claude/lib/render-docs-html.js. Markdown is canonical.