@giamme/forge 0.8.0 → 0.9.0

package/docs/install.md

@@ -0,0 +1,160 @@
+# Install and update
+
+[← README](../README.md) · [All docs](README.md)
+
+Install forge from npm or a git checkout, check which agent CLIs it can reach, and keep every harness installation current.
+
+## Requirements
+
+forge runs on macOS and Linux. It needs bash, git and Python 3.9 or later, plus the agent
+CLIs you route models through; the doctor below shows which ones it finds. Installing from
+npm brings none of these with it.
+
+## From npm
+
+```bash
+npm install -g @giamme/forge
+forge install
+```
+
+`forge install` links the installed package into each harness, as the installer does for a
+checkout below. It is a step of its own rather than an npm install script, so it works where
+scripts are turned off (`--ignore-scripts`). To update:
+
+```bash
+npm install -g @giamme/forge@latest && forge install
+```
+
+The links point into npm's global package directory, so they keep working across updates;
+`forge install` refreshes antigravity's copied plugin. Under nvm, that directory belongs to
+one Node version: after switching Node, install forge on the new one and run `forge install`
+again.
+
+> **Foundry users:** Foundry's `forge` has the same name, and whichever directory comes first
+> on your `PATH` wins; npm's global bin usually comes first. Runs start from your harness
+> (`/forge`), so this command is only for `forge install` and the optional tools. If you keep
+> Foundry's `forge` first, run ours as `"$(npm root -g)/@giamme/forge/forge"`.
+
+## From a git checkout
+
+```bash
+git clone https://github.com/Giamme/forge.git ~/.claude/skills/forge
+bash ~/.claude/skills/forge/scripts/forge-install.sh
+```
+
+Clone anywhere you like — the installer works out its own location and links from there.
+`~/.claude/skills/forge` is just the tidiest home: claude reads that path directly, and
+opencode and grok scan it on their own.
+
+The installer also offers optional Fractal support in an interactive terminal. Declining
+or a Fractal installation failure does not prevent ordinary Forge setup. See
+[Fractal installation](fractal.md#install-the-optional-runtime) for prerequisites and a separate install.
+
+## Check what forge can reach
+
+`<forge>` is your checkout, or `"$(npm root -g)/@giamme/forge"` for an npm install:
+
+```bash
+bash <forge>/scripts/forge-dispatch.sh doctor
+```
+
+```
+HARNESS      STATUS     DETAIL
+codex        found      /Users/you/.nvm/versions/node/v24.18.0/bin/codex
+claude       found      /Users/you/.local/bin/claude
+openclaude   found      /Users/you/.nvm/versions/node/v24.18.0/bin/openclaude
+opencode     found      /Users/you/.opencode/bin/opencode
+antigravity  MISSING    agy not on PATH
+grok         found      /Users/you/.grok/bin/grok
+```
+
+A `MISSING` harness is fine — forge only needs the ones you actually route models through.
+
+**Binary presence is not reachability.** A harness can be installed and still fail on auth or
+billing (opencode in particular fails this way), and that failure only surfaces mid-dispatch.
+To prove a pairing end to end before spending a real run:
+
+```bash
+bash <forge>/scripts/forge-dispatch.sh dwarf <spec> --prompt-file /dev/stdin --repo <scratch dir> \
+    <<< 'Reply with exactly: FORGE_OK'
+```
+
+## What the installer does per harness
+
+Each CLI discovers skills differently, and the differences are not guessable — so verify
+with the listed check rather than trusting file placement.
+
+| Harness | Mechanism | Verify with |
+|---|---|---|
+| claude | `~/.claude/skills/forge/` | `/forge` appears in the skill list |
+| openclaude | symlink into `~/.openclaude/skills/` | `openclaude skills list --json` |
+| codex | symlink into **`~/.codex/skills/`** | `codex exec "do you have a skill named forge?"` |
+| opencode | **nothing** — it scans `~/.claude/` itself | `opencode debug skill` |
+| antigravity | `agy plugin install` of a generated wrapper | `agy --print='/forge'` |
+
+> **The one ongoing caveat:** `agy plugin install` *copies* the files instead of referencing
+> them. The other four track the source directory live, so an edit reaches them instantly —
+> antigravity keeps running whatever it copied. **Re-run `forge-install.sh` after any edit**,
+> or agy silently runs a stale version.
+
+`forge-install.sh --dry-run` prints what it would do and touches nothing. It never clobbers
+a real directory that isn't a symlink.
+
+## Updating all harness installations
+
+Run the updater from your Forge checkout (or through one of its skill symlinks):
+
+```bash
+./forge update            # same as: bash ~/.claude/skills/forge/scripts/forge-update.sh
+./forge version           # VERSION, checkout commit, tracked upstream, last known release
+./forge version --check   # ask the upstream for its newest release now
+```
+
+It fetches the current branch's configured upstream, fast-forwards the checkout, and
+runs Forge's installer to refresh Claude, OpenClaude and Codex links, OpenCode discovery,
+and Antigravity's copied plugin. Harnesses that are not present are skipped. Restart
+active harness sessions afterward to load the updated skill.
+
+```bash
+# Preview without fetching or changing files:
+bash <forge-checkout>/scripts/forge-update.sh --dry-run
+
+# Refresh harness installations after local edits, without fetching:
+bash <forge-checkout>/scripts/forge-update.sh --local
+
+# Point a copied installation's updater at the original checkout:
+bash <path>/scripts/forge-update.sh --source <forge-checkout>
+```
+
+When a solo run, `plan` or `run` finishes, forge checks the checkout's upstream for a newer
+release tag at most once a day (`git ls-remote`, 5-second timeout, cached in
+`${XDG_STATE_HOME:-~/.local/state}/forge/update-check.json`) and, if there is one, prints a
+single line on stderr: `forge 0.8 is available (you have 0.7.1): forge update`. The check is
+silent offline, in a copied installation without Git, in CI (`CI` set) and with
+`FORGE_UPDATE_CHECK=off`, and it never changes a run's outcome or exit code.
+
+An npm installation has no Git upstream, so there the same daily check asks the npm registry
+for the package's `latest` (`npm_config_registry` when you set one, as npm does), and the line
+names npm's command instead: `forge 0.9.0 is available (you have 0.8): npm install -g
+@giamme/forge@latest && forge install`. `forge version` shows the same command.
+
+The default update requires a clean Git checkout and a branch with an upstream. Local
+changes, detached HEAD, fetch failures and diverged branches stop the update without
+resetting or stashing your work. `--local` deliberately allows current local edits.
+Real skill directories are preserved; a conflicting directory or plugin installation
+failure produces a nonzero exit and an explanation. After fixing an installation
+failure, use `--local` to retry from the updated source. Updating Forge does not prompt
+for optional Ripwire installation.
+
+An npm installation is not a Git checkout, so the updater stops there and prints the npm
+command [above](#from-npm) instead. `--local` still refreshes its harness installations.
+
+## `scripts/forge-install.sh`
+
+```
+forge-install.sh [--dry-run]
+```
+
+Links this directory into every installed harness. Skips harnesses that aren't present,
+skips a destination that exists and isn't a symlink (it will never clobber a directory you
+may have edited in place), and reports opencode as auto-detected.

package/docs/memory.md

@@ -0,0 +1,156 @@
+# Project memory
+
+[← README](../README.md) · [All docs](README.md)
+
+What forge learns about a repository, where it keeps it, what each role is told, and what forge has spent there.
+
+Every forge dispatch is a clean slate, so without help the tenth run in a repo rediscovers
+what the first one learned. forge keeps that in the repo, in two files:
+
+```
+.forge/memory.md     small, capped, injected into every prompt
+.forge/ledger.tsv    append-only, one row per dispatch, never injected
+```
+
+The split is the design. Injected context is paid for on every dispatch of every future run,
+so "remember everything" and "stay small" pull against each other — the ledger remembers at
+zero context cost and is read only when asked, while `memory.md` is capped at 40 lines / 4 KB.
+
+```markdown
+## Verify
+- pytest -q runs the suite; make test also lints and is 4x slower
+
+## Known traps
+- tests/test_api.py::test_timeout is flaky under -n auto  [tests/test_api.py]
+
+## Recurring QA findings
+- 3x: route added without updating openapi.yaml  [src/routes]
+```
+
+## How a fact gets in
+
+The role that just did the work writes it down, in its final message, next to the verdict:
+
+```
+FORGE_LEARNING: trap | src/proto/*_pb2.py is generated, never hand-edit [src/proto]
+```
+
+No extra dispatch and no separate model guessing what mattered — the one that hit the
+landmine is the one that records it. Everything after that is deterministic bash.
+
+**What stops it becoming a junk drawer:**
+
+| Guard | Effect |
+|---|---|
+| recurrence threshold | a `finding` needs **two distinct runs** before it is injected. One occurrence is an incident, not a pattern |
+| stale anchors | an entry ending in `[path]` is dropped once that path stops existing, so memory stays true as code moves |
+| hard cap | over 40 lines / 4 KB, lowest-count and least-recent facts are trimmed; one entry is clamped to 180 chars |
+| bias to silence | the prompt says most runs teach nothing durable and emitting nothing is correct. A false fact costs every future run; a missing one costs a single rediscovery |
+
+Only `verify` and `trap` are kept on first sighting — those are facts, true the first time.
+
+## Slices, and what forge writes
+
+| Role | Gets |
+|---|---|
+| planner, dwarf | Verify + Known traps + Recurring findings |
+| qa | Known traps + Recurring findings |
+
+QA is not told the build command; it is not building anything. It *is* told the recurring
+findings, so it can notice this is the fourth time the same bug shipped.
+
+`.forge/` is the **only** thing forge writes into your working tree rather than onto a branch
+of its own. It is excluded from every captured diff, so a reviewer never sees it as the
+dwarf's work — but it *will* show up as untracked in `git status` after your first run.
+
+## What to do with `.forge/` when it appears
+
+forge never commits it. That decision is yours, and there are three sane answers:
+
+| You want | Do this |
+|---|---|
+| memory shared with your team, and with future you | **commit `.forge/`** — the intended case; every teammate's runs then build on the same facts |
+| memory kept to your machine | `echo '.forge/' >> .gitignore` |
+| no memory at all | `--no-memory`, or `FORGE_MEMORY=off` in your environment |
+
+Two things that are easy to get wrong:
+
+**Gitignoring is not the same as turning it off.** An ignored `.forge/` is still written and
+still injected into every prompt — it just stops travelling. Only `--no-memory` /
+`FORGE_MEMORY=off` actually disables the feature.
+
+**Never commit one file and ignore the other.** `memory.md` is *rebuilt from* `ledger.tsv` on
+every write, so a clone that has the memory but not the ledger loses everything the moment
+anyone runs forge there — the rebuild regenerates `memory.md` from that machine's own short
+ledger and the shared facts are gone, silently. Verified behaviour, not a theoretical risk:
+
+```
+teammate A commits memory.md only, ledger.tsv gitignored
+  memory.md: - pytest -q runs the suite
+             - src/a.py is generated [src/a.py]
+
+teammate B clones, runs forge once, learns one unrelated thing
+  memory.md: - b learned something new        ← A's two facts destroyed
+```
+
+Commit both, or neither. If you commit them, expect `ledger.tsv` to gain a line per dispatch
+— small, but it will appear in your diffs; that growth is the price of the recurrence
+counting that keeps `memory.md` honest.
+
+If you contribute to someone else's repo, gitignore it. A pull request containing forge's
+notes to itself is noise to a reviewer who does not use forge.
+
+## `scripts/forge-memory.sh`
+
+```
+forge-memory.sh inject <repo> <planner|dwarf|qa>   # the block to prepend to a prompt
+forge-memory.sh note <planner|dwarf|qa>            # the instruction to append
+forge-memory.sh record <repo> --last <file> --role <r> [--run-id X] [--task T]
+                              [--model M] [--verdict V] [--duration S]
+forge-memory.sh show <repo>
+forge-memory.sh prune <repo>                       # re-apply staleness and the cap now
+forge-memory.sh spend <repo> [--run <run-id>]      # what forge has cost this repo
+```
+
+`record` appends to the ledger and then rebuilds `memory.md` from the whole ledger — the
+rebuild is idempotent, so a crashed run can leave the ledger a row short but can never leave
+memory half-written. Editing `memory.md` by hand therefore does not stick; remove the ledger
+rows instead.
+
+```bash
+# what would a dwarf actually be told about this repo?
+bash scripts/forge-memory.sh inject ~/dev/api dwarf
+
+# start over
+rm -rf ~/dev/api/.forge
+```
+
+## Spend
+
+The ledger already holds a row per dispatch and is never injected into a prompt, so
+accounting from it costs nothing:
+
+```bash
+bash scripts/forge-memory.sh spend ~/dev/api
+```
+```
+14 dispatch(es) across 3 run(s), 1h12m of model time
+Durations sum concurrent work, so they exceed the wall-clock of a parallel run.
+
+  by model                     disp     total      mean
+  sol:xhigh                       4     38m20s     9m35s
+  opus                            7     22m10s     3m10s
+  gemini:low:antigravity          3     11m30s     3m50s
+
+  by role                      disp     total
+  dwarf                           7     49m50s
+  qa                              7     22m10s
+```
+
+**Time and dispatch counts, never tokens or money.** The six CLIs expose usage differently
+or not at all, and a number forge cannot actually measure would be worse than no number.
+
+`duration_s` is the ledger's tenth column, appended at the end on purpose: a ledger written
+by an older forge — possibly already committed and shared — has nine fields, and awk yields
+an empty string for the missing one instead of shifting every column. Those rows are counted
+but not timed, and the output says so.

package/docs/models.md

@@ -0,0 +1,118 @@
+# Models, efforts and harnesses
+
+[← README](../README.md) · [All docs](README.md)
+
+How forge names a model (`alias:effort:harness`), what each harness offers, how effort is validated and clamped, when to drop the sandbox, and how to teach forge a new model.
+
+## The spec: `alias:effort:harness`
+
+Everywhere forge takes a model, it takes the same three-field spec. Each field after the
+first is optional:
+
+| Spec | Resolves to |
+|---|---|
+| `sol` | alias `sol`, default effort for the role, its default harness (codex) |
+| `sol:xhigh` | `sol` at `xhigh` effort on its default harness |
+| `sol:xhigh:openclaude` | same model and effort, run through the `openclaude` CLI |
+| `opus::claude` | explicit harness, effort left to the role default — the middle field may be empty |
+| `gpt-5.6-sol::codex` | not in the registry? passed through as a literal model id — but only with an explicit harness |
+
+An alias with no registry row still works, provided you name the harness. forge won't guess
+a default harness for a model it has never seen; that guess would silently spend quota on
+the wrong provider.
+
+**Role defaults when you leave things out:**
+
+- `--dwarf` missing → forge **asks**. Every dispatch spends real quota on your account, so
+  picking for you isn't its call.
+- `--qa` missing → `opus`, which runs locally through `claude` and adds no cost surprise.
+- effort missing → dwarf builds at `medium`, qa reviews at `xhigh`. A reviewer thinking
+  *less* than the implementer tends to wave things through, which wastes the stage entirely.
+
+## Effort, ceilings and clamping
+
+Every harness has its own effort ladder:
+
+| Harness | Ladder |
+|---|---|
+| codex | `low medium high xhigh max ultra` |
+| claude | `low medium high xhigh max` |
+| openclaude | `low medium high xhigh max ultracode` |
+| antigravity | `low medium high` |
+| grok | `low medium high xhigh max` (grok-4.7 offers up to `xhigh`) |
+| opencode | provider-specific; forwarded verbatim |
+
+And support is more irregular than one ceiling per backend:
+
+- **Ceilings** — `luna` tops out at `max` on codex, so `luna:ultra` clamps down.
+- **Gaps** — `gemini-pro` offers `low` and `high` but *not* `medium`, so `gemini-pro:medium`
+  clamps to `low`.
+- **None at all** — Claude models on antigravity take no effort flag; passing one errors, so
+  forge reports it and drops it.
+
+When forge clamps, it says so (`clamped=ultra -> max`) and the orchestrator passes that on
+to you. Getting less thinking than you paid for, silently, is exactly the failure worth ten
+lines of validation to prevent — and it's a real one: **codex accepts an invalid effort
+without complaint and quietly runs at some other level.** forge validates first.
+
+A word that isn't a recognized effort at all is an error, not a clamp.
+
+## Yolo mode
+
+`--yolo-dwarf` and `--yolo-qa` drop that role's sandbox and approval gates:
+
+| Harness | Flag used |
+|---|---|
+| codex | `--dangerously-bypass-approvals-and-sandbox` |
+| claude / openclaude / antigravity | `--dangerously-skip-permissions` |
+| opencode | `--auto` |
+| grok | `--always-approve` |
+
+Each flag applies to **one role only**, so `--yolo-dwarf` alone is the normal combination:
+the implementer gets a free hand, the reviewer stays fenced in and still can't edit the code
+it's judging.
+
+You mostly don't need it. On codex, claude and openclaude the sandboxed roles are already
+useful — the dwarf edits files and runs tests, qa reads and runs commands but cannot write.
+Reach for yolo when a role genuinely must escape the sandbox: installing dependencies,
+writing outside the repo, touching the network.
+
+> **Antigravity is the exception worth knowing.** Without yolo it cannot run *any* shell
+> command, and a single denied command **aborts the whole run** rather than degrading — a
+> dwarf that tries to run the test suite ends with an error and an empty diff. forge detects
+> this and appends a note telling that role not to attempt commands, which is why an
+> antigravity dwarf reports its work as unverified by execution. If you want a Gemini dwarf
+> that can actually run the tests it writes, it needs `--yolo-dwarf`.
+
+## Model registry
+
+`registry.tsv` is the single source of truth for alias resolution. Four tab-separated
+columns, plus an optional fifth:
+
+```
+# alias	harness	model	effort	[timeout]
+sol	codex	gpt-6.1-sol	<=ultra
+sol	openclaude	gpt-6.1-sol	<=max
+gemini-pro	antigravity	gemini-3.1-pro	low,high
+opus	antigravity	claude-opus-4-6-thinking	none
+grok	grok	grok-4.7	<=xhigh
+grok	opencode	github-copilot/grok-4.6	-
+```
+
+| `effort` form | Means |
+|---|---|
+| `<=X` | any effort on that harness's ladder up to and including `X` |
+| `a,b,c` | exactly these efforts — gaps are real, and this is how they're expressed |
+| `none` | takes no effort flag at all; passing one errors |
+| `-` | no validated ladder; forwarded verbatim |
+
+The optional fifth column, `timeout`, is a per-model default dispatch limit in seconds (`-`
+or absent = the built-in default). It applies only when neither `--timeout` nor
+`FORGE_TIMEOUT` was given and is scaled by the resolved effort (see
+[timeout precedence](commands.md#scriptsforge-dispatchsh)). Rows without it behave exactly as before.
+
+**Row order is meaningful:** the *first* row for an alias is that alias's default harness.
+`--dwarf sol` means sol on codex; `--dwarf sol:high:openclaude` moves the same model
+elsewhere.
+
+Adding a model is one line in this file. Nothing else needs to change.

package/docs/reviews.md

@@ -0,0 +1,231 @@
+# Reviews, retries and recovery
+
+[← README](../README.md) · [All docs](README.md)
+
+What a reviewer must answer, what forge does when it fails a task, how to retry, tolerate or accept findings, and the checks forge runs around the reviewer.
+
+## Verdicts and failure
+
+Decompose-mode QA must end with a sentinel line:
+
+```
+FORGE_VERDICT: PASS     no confirmed correctness bug (style nits are not failures)
+FORGE_VERDICT: FAIL     at least one CONFIRMED correctness bug
+```
+
+Only a standalone final line counts, and the parser is shared by every runner (solo,
+decomposed, Fractal's QA checkpoint). The prompt shows each verdict with a dash and its
+meaning, and some reviewers copy that whole line, so `FORGE_VERDICT: PASS — meaning` is
+accepted, as are trailing whitespace and CRLF line endings. Prose or a quoted marker earlier
+in the reply is never a verdict. A missing verdict is `UNKNOWN` and is treated exactly like a
+failure — excluded from integration and flagged. Merging a diff whose reviewer never reached
+a conclusion would defeat the point of reviewing it, so the ambiguous case fails safe.
+
+A failing task is excluded and **its branch and worktree are preserved**; the rest of the run
+proceeds. forge never loops a dwarf against its reviewer on its own: a retry happens when you
+type `retry`, or when you opt in for a run with `--retry-failed N` ([below](#retrying-inside-a-run---retry-failed-n)).
+
+An `UNKNOWN` task is different from a rejected one: the reviewer never judged the code, so
+`retry` (or `--retry-failed`) asks **QA again on the unchanged work** instead of paying an
+implementer to rewrite something nobody rejected. No attempt is spent and no dwarf runs. If
+the worktree no longer matches what was reviewed, the full task runs instead.
+
+## Retrying a failed task
+
+```bash
+# re-run one task with the findings that failed it, on a stronger model
+bash scripts/forge-parallel.sh retry "$PLAN" middleware --dwarf sol:xhigh
+```
+
+The findings are the point. `retry` prepends the previous reviewer's report to the dwarf's
+prompt — "your last attempt was reviewed and these were the findings; fix them" — and reuses
+the worktree, so the dwarf continues from its own code rather than starting over. If the
+verdict comes back `PASS` the task merges like any other.
+
+`--dwarf` is written back into `tasks.tsv`, so the table shows the model that will actually
+be spent and the escalation survives a re-plan.
+
+Two things it deliberately does:
+
+- **Reviews the task's cumulative diff**, against the commit the task was originally branched
+  from — not just the fix. Reviewing the fix alone would let the first attempt's code through
+  unread.
+- **Refuses to re-review identical code.** If the retry produces a byte-identical diff, the
+  task fails again without spending a QA dispatch.
+
+`retry` is something you run. Forge never loops a dwarf against its own reviewer on its own
+initiative — unless you ask a *run* to with `--retry-failed N`, see
+[retrying inside a run](#retrying-inside-a-run---retry-failed-n). A task whose reviewer
+never gave a verdict (`UNKNOWN`) or whose run stopped on an infrastructure failure (`INFRA`)
+resumes at the review stage instead: QA runs again on the unchanged work, no dwarf runs, and
+no attempt is spent.
+
+## Retrying inside a run: `--retry-failed N`
+
+```bash
+forge-parallel.sh run <plan-dir> --retry-failed 2
+```
+
+A task whose reviewer says `FAIL` (or `UNKNOWN`) is re-queued at once, **inside the same
+run**, up to `N` more times — with the reviewer's findings carried into the next prompt exactly
+as `retry` does. Other tasks keep running meanwhile; dependents still wait for the task to
+*merge*, so nothing downstream starts early. Without this, a failed task waited for the whole
+run (verification included) to finish before a human could retry it.
+
+It is opt-in and per invocation: it is not remembered by the plan, and the orchestrator never
+adds it unprompted. Only reviewer rejections are retried automatically — `TIMEOUT`, `ERROR`,
+`INVALIDATED` and `CONFLICT` still need a human. A retry that changes nothing (empty diff, or
+a diff byte-identical to the previous attempt) writes a `noretry` marker and is **not**
+retried again, so a stuck task cannot burn its whole budget repeating itself.
+`tasks/<id>/attempts.tsv` records every entry (epoch, attempt number, resulting status, infra
+class).
+
+## Infrastructure failures are not task failures
+
+A quota or usage limit, an auth problem, a rate limit, a network error, or a harness that
+returns nothing at all says nothing about the work. forge classifies those from the dispatch
+log (`forge-runtime.py classify`) and `forge-dispatch.sh` exits **8** instead of 4. A
+decomposed task then ends as **`INFRA`**, not `ERROR`/`FAIL`, and:
+
+- **no attempt is spent** — a dwarf-stage stop refunds the counter; a QA-stage stop keeps the
+  dwarf's committed work and re-runs **QA only** next time (`tasks/<id>/resume`, revalidated
+  against the branch tip and fingerprint before it is trusted);
+- the scheduler stops dispatching, lets running tasks drain, leaves unstarted ones `PENDING`
+  (never `BLOCKED`) and `run` exits **8**: fix the cause, then run the same command again;
+- `run --infra-retries M` waits instead — up to `M` times, using the provider's retry-after
+  hint when it gave one (capped at 6 hours) and otherwise 60 s doubling to 30 min
+  (`FORGE_INFRA_BACKOFF` sets the base) — and resumes in the same run;
+- verification is skipped for a paused run (it is unfinished); the next `run` verifies at its end.
+
+`.infra` (`dwarf.infra`/`qa.infra`) holds `class=`, `retry_after=`, `detail=`, `rc=`,
+`role=`. Detection is deliberately strict: strong phrases only, and ordinary text that merely
+mentions "rate limit" in a reply that otherwise succeeded is never classified. A false
+positive costs a pause, not a spent attempt. Under Fractal a dwarf-side infrastructure stop
+still collapses to Fractal's own "failed" handling; QA-side stops propagate as above.
+
+## Severity, thresholds and known issues
+
+QA is asked to label every finding `- [P0..P3][CONFIRMED|PLAUSIBLE] file:line — what breaks`
+(P0 data loss/security/crash on the main path, P1 wrong behaviour on realistic input, P2
+edge-case bug, P3 minor). By default the verdict rule is unchanged — any CONFIRMED bug fails.
+
+`--qa-threshold Pn` (on `run` or `retry`; remembered in the plan; `none` clears it) names the
+**least severe level that still blocks**: `P2` means P0–P2 block and only P3 is tolerated.
+A task-specific `tasks/<id>/qa_threshold` file beats the plan-level value, which is how a
+dev-tooling or investigation task gets a looser bar than production code. With a threshold, a
+reviewer `FAIL` made only of CONFIRMED findings that are all labelled and strictly milder than
+the threshold is accepted as **PASS with known issues**: the task merges, `tasks/<id>/known_issues.md`
+keeps the findings, `qa.gate` records the decision, and every run/retry/integrate summary
+lists them. The literal status stays `PASS`, so nothing downstream needed a new vocabulary.
+It fails safe: an unlabelled CONFIRMED finding, or a FAIL with no CONFIRMED finding at all,
+is never tolerated, and without a threshold nothing changes.
+
+## Accepting a task despite its reviewer
+
+```bash
+bash scripts/forge-parallel.sh accept "$PLAN" tooling \
+  --reason "only an unreachable option left; tracked in the backlog" --approved
+```
+
+When a reviewer keeps finding new corners of something that should ship (one real
+investigation harness got 12 findings over five rounds, and only a human decision ended it),
+`accept` is that decision made explicit instead of done with git plumbing. It needs **both**
+`--reason` and `--approved`, because it overrides a reviewer; an orchestrating model never runs
+it on its own. It accepts only a `FAIL` or `UNKNOWN` task whose reviewed work is **intact** —
+the branch is still at the reviewed commit and the worktree still has the saved fingerprint —
+otherwise it exits `3` and says to `retry` for a fresh review (accepting would sign off on code
+nobody reviewed). It writes `tasks/<id>/known_issues.md` (your reason, who and when, and the
+reviewer's reply copied verbatim) and `accepted.by`, merges through the same checks as any other
+task, and puts everything back if the merge conflicts (exit `6`). Dependents are not touched;
+`run` continues them.
+
+## Whole-run review (opt-in)
+
+Per-task QA only sees one slice. In one real run, a holistic review of the combined result still
+found two confirmed P2 defects in code every per-task review had passed. It is opt-in because it
+spends QA quota and `integrate` made no model calls before:
+
+```bash
+bash scripts/forge-parallel.sh review "$PLAN" --qa opus              # read-only look at the combined result
+bash scripts/forge-parallel.sh integrate "$PLAN" --approved --final-review opus   # and gate the merge on it
+```
+
+The reviewer gets the overall goal, every task's complete requirements (bounded to about 80 KB,
+truncated visibly), what forge observed that no per-task reviewer saw (accepted known issues,
+scope drift, guard notes, the verification result including a `FLAKY` pass and coverage
+warnings), the combined diff (inline up to 400 KB), and the same labelled-findings contract —
+with an emphasis on cross-task interactions, interface mismatches and ordering races. `review`
+reads `integration.base..integration tip` from a disposable checkout, writes
+`<plan>/final-review-<epoch>-<pid>/` (`qa.input`, `qa.last`, `verdict`, `qa.gate`, …), keeps
+`<plan>/final-review` and `final-review.verdict` pointing at the newest, and never touches your
+branch or the integration branch. With `integrate --final-review`, it runs after verification
+and before your branch can move: `PASS` (or a `FAIL` accepted by `--qa-threshold`) continues,
+anything else stops with exit `5`; an infrastructure stop exits `8`. The QA spec is `--qa`, else
+the one remembered in `final_qa`, else the single spec every task shares (otherwise it asks).
+Tasks that are not merged are not in the result, and it says so. `integrate` also names unmerged
+tasks even without a review.
+
+## Shadow reviews: how much of a verdict is the reviewer?
+
+`plan --shadow-qa <spec>[,<spec>...] [--shadow-rate R]` (default R = 0.1) sends a sampled
+share of reviewed attempts to a second reviewer, the first listed one of another model
+family than the task's. Its verdict goes to the run dataset and nothing in the run reads it,
+so it never changes a status, merge, memory or retry. `forge dataset status` then reports how
+often the two reviewers agree, overall and per model pair. The table shows the extra reviews
+before you approve. The shadow runs beside the main review and is stopped soon after that
+finishes, so the most it costs is reviews and a little latency. See
+[decomposition](../references/decompose.md#shadow-reviews-opt-in).
+
+## Implementer guards
+
+The dwarf is told not to commit, switch branches, start background processes, or claim checks
+it did not run. forge then **observes** whether it did, rather than trusting its report:
+
+- **self-commit / branch switch** — HEAD or the checked-out ref moved during the dispatch;
+- **orphan processes** — the harness runs in its own session; anything still alive in it after
+  the harness exits is listed in `<role>.orphans` and stopped (`FORGE_ORPHAN_GUARD=off`
+  disables this; it is also skipped under Fractal);
+- **promised later work** — "running in the background", "will report back once it
+  finishes" and similar in the final message.
+
+These are warnings recorded in `tasks/<id>/guard.txt`, shown in the QA prompt ("Implementer
+guard notes") and in the run summary. They never change a status: the diff and the reviewer
+still decide. In solo mode a self-commit prints the `git reset --soft <old HEAD>` that would
+undo it; forge never resets anything itself.
+
+## Verification coverage and flaky reruns
+
+`--verify` is whatever you hand it, and a gate that skips a suite the project defines lets a
+regression there reach your branch silently. `forge-verify-coverage.py` reads the project's own
+test configuration (`package.json` scripts, Makefile targets, pytest/tox, Cargo, Go, Ruby,
+Elixir, `scripts/test*.sh`), follows aggregate scripts, and **warns** — before any model is
+paid for, again in the run summary and at integrate — about suites the verify command never
+runs, e.g. `suite 'test:contract' (npm run test:contract) is not run by the verify command`.
+It is advisory: it never fails a run, and `verification.coverage.txt` keeps the lines. It is a
+text heuristic (root of the repo only; a mentioned command counts as run).
+
+A failing verify command is rerun **once** (`--verify-retries N`; `0` restores the single strict
+run) when the source fingerprint is unchanged. If the rerun passes the status is `PASS` but
+`verification.flaky` is written, `verification.log` keeps the first (failing) run,
+`verification.retry.log` the second, and `run`/`integrate` print a loud `FLAKY` line — an
+intermittent failure can be a real bug, so it is never passed off as a clean pass. A command
+that changes the tree is never retried. This deterministic rerun comes before Jev's optional
+model-assisted triage, which then does not run.
+
+## Native review
+
+`--native-review` switches a codex reviewer to its purpose-built reviewer, for a diff too large
+to inline. Know the trade: codex refuses a custom prompt alongside its scope flags, so the
+reviewer never learns what the dwarf was *asked* to do. It can still judge whether the code is
+correct, but not whether it's the right change, so its result is informational and the verdict
+is `UNKNOWN`. See [solo runs](../references/solo.md) for how the baseline is passed.
+
+## Fail-first evidence (opt-in)
+
+`--fail-first` (on a solo run or `plan`) checks that the tests a change adds or edits can
+actually fail. Before each review, forge runs each new or edited test file against the change
+and against the base without it, using the per-file command in `.forge/verify-subset`, and hands
+the reviewer the result: `proven`, `passes_without_change`, `inconclusive` or `error`. The
+reviewer is asked for a P2 finding for every test that passes without the change. It is advice
+only: forge never changes a status or verdict from it. forge-ui shows the evidence under the
+review findings. See [fail-first evidence](../references/decompose.md#fail-first-evidence-opt-in).