forgev0.19
Docs pages

What forge never does

forge runs other models against your code, so it's strict about where their changes can go. These hold for every run.

Your branch and working tree

  • It never pushes. There's no push step anywhere in forge, and forge pr --create stops if the branch has no upstream.
  • It never commits on your branch during a run. A single task's change is left uncommitted in your tree. A parallel run commits and merges only on branches forge creates for itself. Your branch moves when you run integrate --approved.
  • It never merges unreviewed code. Only the exact commit a reviewer passed can merge. If code changes after its review, the review no longer counts. Overriding a reviewer takes a written reason and --approved.
  • It checks before your branch moves. With a verify command set, integration tests a candidate that includes your current branch. A failing check blocks it.

Models and sandboxes

  • It never picks a builder for you. Leave out --dwarf and forge asks. A task with no model makes the run refuse.
  • It never drops a sandbox on its own. --yolo-dwarf and --yolo-qa are the only way out, one role each.
  • One dwarf per working tree. Parallelism comes from separate worktrees, never two models in one tree.
  • The reviewer judges a throwaway copy. Editing the code it's reviewing voids its verdict.
  • Timeouts stop everything a dispatch started, including test runners and servers in their own process groups, before a retry can collide with them.

Records

  • It never deletes a failed attempt. Its branch and worktree are the record and the place to retry from.
  • The only thing it writes into your repo is .forge/, its project memory, and it never commits it.
  • Cleanup never touches an active run, a worktree, or a file forge didn't create.
  • Private text stays local. Exports, PR bodies and retro issues leave out prompts and local paths unless you include them, and retro issues post only what you approve by hash.

When forge refuses

SituationWhat forge does
Not a git repositoryParallel runs refuse; worktrees need git.
Uncommitted changesWarns loudly: dwarves start from your last commit and can't see them.
integrate without --approved, or on a dirty treeRefuses.
accept on code that changed since its reviewRefuses and asks for a fresh review.
Another command holds the plan's lockRefuses, says which command holds it, and on a live run which forge control to use instead.

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