Reviews and retries
The reviewer is why forge exists. It reads the code a dwarf actually changed and decides, finding by finding, whether that code can merge.
What the reviewer reads
The reviewer, qa, gets the task's requirements, the planned approach and the real diff, every line, new files included. It works in a throwaway copy of your repo with the attempt's own dependencies linked in, so it can run your tests. If it edits a tracked file there, its review is void and runs again on the unchanged work.
It ends with two lines: whether its tests ran, and the verdict.
FORGE_TESTS: RAN FORGE_VERDICT: FAIL
A review that never reaches a verdict counts as a fail. Merging code nobody finished judging would defeat the point.
How findings are rated
| Severity | Means |
|---|---|
| P0 | data loss, a security hole, or a crash on the main path |
| P1 | wrong behaviour on realistic input |
| P2 | a bug in an edge case |
| P3 | minor |
Each finding is confirmed or plausible, names a file and line, and ends with three facts: how likely its trigger is (reach), whether this change introduced it (origin), and how the reviewer knows (evidence: ran, traced or suspected). Those facts are recorded to test better blocking rules; today they decide nothing.
When a task passes
forge decides from the findings, not the reviewer's word, against a threshold: P2 unless you set --qa-threshold.
- A confirmed finding at P2 or worse fails the task, even under a PASS.
- A FAIL made only of milder confirmed findings passes with known issues: it merges, and the findings are kept in
known_issues.md. - Plausible findings never block.
--qa-threshold P3 blocks on every confirmed finding; P1 tolerates edge cases, which suits tooling work. You can change it on a live run, per task too.
When a task fails
A failed task stays out of the merge, keeps its branch and worktree, and the rest of the run goes on. A retry hands the dwarf the reviewer's report and continues in the same worktree, so it fixes its own code. The next review reads the whole task again, with the previous round's findings and what changed since.
# retry one task with its findings, on a stronger model bash scripts/forge-parallel.sh retry "$PLAN" token-model --dwarf sol:xhigh # or retry rejected tasks automatically inside the run, up to twice bash scripts/forge-parallel.sh run "$PLAN" --retry-failed 2
A retry that produces the same diff isn't reviewed again. A task that keeps failing moves to a stronger model from your pools: with plan --retry-per-model N each model gets N attempts before the next tier takes over, and the approval table prints the most dispatches that can cost if every model fails. The table records who decided. A review with no verdict is asked again on the same work, without paying a dwarf.
When the fix belongs to another task
Sometimes a blocking finding can only be fixed in a file the task doesn't own. The reviewer marks it {outside=path}, and a dwarf can say so itself with a FORGE_BLOCKED: <path>: <why> line for the reviewer to confirm. When every blocking finding is outside the task, forge stops it as NEEDS_DECISION instead of spending attempts on edits it may not make. It names the task that owns each file and the plan change that fixes it: add the file, depend on its owner, or merge the two rows.
When you edit a prompt mid-attempt
Edit a task's prompt.md or approach.md while its dwarf works, and that attempt isn't reviewed against text it never saw. It's marked STALE, costs no attempt, and the dwarf runs again with the new requirements and a diff of what changed.
A stuck provider isn't a failed task
A rate limit, used-up quota, sign-in problem or network error says nothing about the code. The task is marked INFRA, no attempt is spent, and forge pauses only the model or CLI that's stuck. It can move the task sideways to a healthy model in the same tier (--infra-fallback) or wait it out (--infra-retries).
Overriding a reviewer
When a reviewer keeps finding new corners of something that should ship, that's a person's call. It takes a written reason and an explicit approval, and only works on the exact code that was reviewed.
bash scripts/forge-parallel.sh accept "$PLAN" tooling \ --reason "only an unreachable option left; tracked in the backlog" --approved
On a live run, forge control accept does the same and lets the tasks waiting on it start. An agent driving forge never accepts on its own.
Optional extra checks
| Ask for | What it does |
|---|---|
integrate --final-review opus | One reviewer reads the whole combined result before your branch moves, looking for problems between tasks. |
plan --groups waves --group-review | Related tasks share one reviewer over their combined diff. Each finding goes back only to the task whose files it names, and the group merges in one step once it passes. A finding that names no task stops the group for your decision. |
run --sweep P3 | After every task merges, fixes the findings the threshold let through, while the context is fresh. |
plan --shadow-qa sonnet | Sends a sample of reviews to a second reviewer, to measure how much a verdict depends on who gave it. It never changes a result. |
--native-review | Uses Codex's own reviewer against the recorded baseline. |
Findings left over
Tolerated findings aren't forgotten. After a run, forge offers once to file them as GitHub issues, each with its severity, task, reviewer and a link to the code. A finding is never filed twice.
./forge issues "$PLAN" # drafts only ./forge issues "$PLAN" --apply --label bug # file them
Full reference Every flag and edge case: docs/reviews.md