forgev0.19
Docs pages

Merge and verification

Passing tasks merge into a branch forge made for itself. Your project's checks run once on the combined result. Your own branch moves only when you say so.

Where the work goes

Each task works on forge/<run-id>/<task>. When it passes review, forge merges that exact reviewed commit into forge/<run-id>-integration, one merge at a time. Later tasks start from that branch, so they build on what already merged. If a merge conflicts, the task is marked CONFLICT; it usually means a task touched a file it didn't declare, and the run's summary names it.

Verifying the combined result

Give forge your project's check, once, and it runs on everything merged at the end of the run, rather than on every attempt.

bash scripts/forge-parallel.sh run "$PLAN" --verify 'pytest -q'
# or keep it in the repo
forge config set repo.verify 'pytest -q' --repo ~/dev/api
  • Coverage warnings. forge reads your test configuration and warns, before any model is paid, about suites your verify command never runs.
  • Flaky reruns. A failing check is rerun once on the same code. If the rerun passes, the result is PASS with a loud FLAKY line, never a quiet clean pass.
  • Lanes. Split verification into named lanes that run in parallel. Only a lane that failed reruns, and failures name the failing tests, new or already known.
  • A missing command is reported as unverified. A failing configured check blocks integration.
bash scripts/forge-parallel.sh run "$PLAN" \
  --verify-lane 'unit=pytest -q tests/unit' --verify-lane 'db=pytest -q tests/db'

Integrating

bash scripts/forge-parallel.sh integrate "$PLAN" --approved

integrate refuses without --approved and refuses on a working tree with uncommitted changes. It checks a candidate containing your current branch before updating it, and names any task that didn't merge and so isn't part of what it delivers.

Want one more look first? A whole-run review reads the combined diff for problems no single-task review could see:

bash scripts/forge-parallel.sh review "$PLAN" --qa opus                         # read-only look
bash scripts/forge-parallel.sh integrate "$PLAN" --approved --final-review opus  # gate on it

A pull request instead

forge pr writes the description a finished run deserves from what it recorded: the goal, a table of tasks with their builders and reviewers, what didn't merge, the verification result and the final review's open findings. Private text and local paths stay out.

forge pr "$PLAN" --out pr.md
git push -u origin forge/a1c4-integration
forge pr "$PLAN" --create --base main      # gh pr create --draft; never pushes for you

Bringing in outside work

Fixed something by hand in the middle of a run? adopt brings a commit made outside forge into the run, and the run's reviewer reviews just that range against your reason. A failed review puts the branch back unless you keep it with --approved.

bash scripts/forge-parallel.sh adopt "$PLAN" 3f2a9c1 --reason "hand fix for the flaky lane"

Full reference Every flag and edge case: docs/safety.md