@giamme/forge 0.8.0 → 0.10.0

package/docs/reviews.md

@@ -0,0 +1,245 @@
+# 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.
+
+Tolerated findings are recorded, not fixed. After a run, the skill offers once to file them as
+GitHub issues, together with PLAUSIBLE findings of passed tasks and whatever a whole-run review
+left open (`--file-issues ask|auto|off`, `ask` by default). Where the
+[gh-proman](https://github.com/Giamme/gh-proman) skill is set up for the repository, it files
+them on the team's project board; anywhere else forge files them itself with plain `gh`:
+
+```sh
+./forge issues <plan-dir>                       # drafts only: titles, severity, already filed
+./forge issues <plan-dir> --include-plausible --apply --label bug
+```
+
+Each issue gets the finding, its severity, the task, reviewer and a code link at the merged
+commit. A hidden fingerprint, shared with gh-proman, keeps a finding from being filed twice.
+
+## 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).

package/docs/safety.md

@@ -0,0 +1,55 @@
+# Safety
+
+[← README](../README.md) · [All docs](README.md)
+
+What forge never does to your branch and working tree, what it refuses to run on, and how it keeps reviewed work and merged work the same.
+
+## Safety guarantees
+
+- Solo runs leave source changes uncommitted. Forge creates private review commits, but
+  does not commit on the solo source branch, push, or reset the user tree.
+- In a decomposed run, commits and merges happen **only** on the `forge/<run-id>/*` task
+  branches and the `forge/<run-id>-integration` branch — branches forge created for itself.
+  Never your branch, never a push. Your branch and working tree are untouched for the whole
+  run.
+- Bypass flags are never added on forge's own initiative. `--yolo-dwarf` / `--yolo-qa` are the
+  only route to an unsandboxed run, so that choice is always explicit and visible.
+- **One dwarf per working tree, always.** Two agents editing one tree interleave their edits
+  into a diff neither of them wrote and qa cannot untangle. Parallelism comes from separate
+  worktrees, which is why worktrees are mandatory there rather than an optimization.
+- A failed task's branch and worktree are **never** deleted — they're the only record of what
+  went wrong and the only thing to retry from. A successful task's worktree is removed only
+  after `results.tsv` is written and read back.
+- QA runs in a disposable repository. Mutations to the source or review snapshot invalidate
+  acceptance. Disabled editing tools alone do not prevent writes through Bash.
+
+## Preconditions
+
+- Not a git repo → decomposed runs refuse. Worktrees are impossible and there's no honest
+  fallback.
+- Uncommitted changes → **warned prominently.** Worktrees branch from a commit, so your local
+  edits are invisible to every dwarf. This is the likeliest route to a confusingly wrong
+  result.
+
+## Execution integrity
+
+Forge now captures solo changes against a recorded starting snapshot, including staged edits,
+without altering the user's index. Existing work is recorded separately in `existing.diff`.
+QA receives the full implementation requirements and reviews a disposable repository; source
+or snapshot changes invalidate the result. Only the recorded reviewed task commit can merge.
+
+Parallel execution rechecks dependencies before each task and retry. Failed prerequisites leave
+consumers BLOCKED. Directory and child file declarations are serialized.
+
+`forge-dispatch.sh doctor --spec sol --role dwarf` validates a selected model recipe using local
+CLI help. Solo and parallel runners preflight the whole selected pipeline before implementation.
+These checks do not establish authentication, billing or live model availability.
+
+Use `forge-parallel.sh run <plan> --verify 'your check command'` or put the command in
+`.forge/verify` to verify the combined result. Output and exit status are saved with the plan.
+Integration checks a candidate containing the current user branch before updating it. A missing
+command is reported as UNVERIFIED; a failing configured check blocks integration. The project's
+own test suites that the command does not run are named as warnings (advisory), and a failing
+command is rerun once so a flaky lane is reported rather than failing the run — see
+[verification coverage and flaky reruns](reviews.md#verification-coverage-and-flaky-reruns).
+`integrate` also names any task that is not merged and therefore not part of what it delivers.

package/docs/troubleshooting.md

@@ -0,0 +1,54 @@
+# Troubleshooting
+
+[← README](../README.md) · [All docs](README.md)
+
+Symptoms, causes and fixes, from a skill a harness cannot see to a task that will not merge.
+
+| Symptom | Cause / fix |
+|---|---|
+| skill missing in **codex** only | frontmatter isn't strict YAML. Codex refuses to load and logs `invalid YAML`; the other four are lenient and load it fine. Note codex's line numbers exclude the opening `---`, so its "line 3" is the file's line 4 |
+| skill missing in **antigravity** | `agy` ignores `~/.gemini/skills` entirely — skills load only inside a plugin. Re-run `forge-install.sh` |
+| antigravity runs an **old version** | `agy plugin install` copies. Re-run `forge-install.sh` after every edit |
+| duplicate entry in **opencode** | opencode auto-scans `~/.claude/`; a `~/.config/opencode/command/forge.md` on top is redundant |
+| agy: `Find command timed out` | missing `--add-dir <repo>` — forge passes it; a hand-built command must too |
+| agy dwarf ends with an error and an empty diff | it tried to run a shell command without yolo. A single denial aborts the run — use `--yolo-dwarf` |
+| dwarf produced no changes | usually an ambiguous prompt it couldn't resolve headlessly. Nobody can answer a question mid-run |
+| task status `ERROR` | worktree creation or a dispatch failed — read `tasks/<id>/dwarf.out` / `qa.out` |
+| task status `UNKNOWN` | QA never emitted a verdict line; read `tasks/<id>/qa.last`. `retry` (or `run --retry-failed N`) asks QA again on the unchanged work — no dwarf runs, no attempt is spent |
+| task status `INFRA`, `run` exits `8` | a quota/usage limit, auth problem, rate limit, network error or empty answer stopped a dispatch — not a task failure, and no attempt was spent. Read `tasks/<id>/infra.txt` (`class=`, `retry_after=`), fix the cause, run the same command again. `run --infra-retries M` waits it out instead. Dependents stay `PENDING`, never `BLOCKED` |
+| a task merged although its reviewer said FAIL | `--qa-threshold` accepted it: every CONFIRMED finding was labelled and milder than the threshold. See `tasks/<id>/known_issues.md` and `qa.gate`; nothing is accepted without an explicit threshold |
+| `accept` exits `3` "changed since it was reviewed" | the branch or worktree moved after QA, so accepting would sign off on unreviewed code. `retry` for a fresh review |
+| `combine` / `split` refuses | the message names why: unmerged task left behind, duplicate ids, locked or dirty plan, a Fractal-backed plan, or a selection that strands a dependent. Nothing was changed |
+| `integrate --final-review` stops with exit `5` | the whole-run reviewer found a blocking defect (or never reached a verdict); findings are in `<plan>/…/final-review/qa.last`. Your branch is untouched. Exit `8` means the reviewer hit a quota/auth stop: run it again |
+| `FLAKY` in the summary, verification `PASS` | the verify command failed once and passed on rerun. Read `verification.log` (the first run) — an intermittent failure can be a real bug. `--verify-retries 0` restores the strict single run |
+| `verify coverage: suite '…' is not run by the verify command` | the project defines a suite your `--verify` skips. Advisory only; add it to the command (or `.forge/verify`) if it should gate the merge |
+| implementer guard notes in the summary | the dwarf committed, switched branch, left processes running, or promised later work. Recorded in `tasks/<id>/guard.txt`; the diff and the reviewer still decide. Leftover processes were stopped |
+| task status `CONFLICT` | QA passed but the merge conflicted — `files` was understated somewhere. Check the run's scope-drift list: it usually names the file |
+| task status `TIMEOUT` | that role exceeded the dispatch timeout and was killed. Raise `--timeout`, or `retry` — the partial edit is still in the worktree |
+| a dispatch never returns | it can't any more: every backend is killed at its timeout (`--timeout`, else `FORGE_TIMEOUT`, else the registry's `timeout` column, else 45 min — 60 min for the default `xhigh` QA/planner effort) |
+| a task won't re-run: "already exists" | a worktree directory was deleted by hand. `run` and `retry` prune stale registrations first, so re-run rather than deleting the branch |
+| a failed task is expensive to redo | it isn't — `forge-parallel.sh retry <dir> <id> [--dwarf <spec>]` re-runs that one task with its reviewer's findings, in the worktree it already has |
+| an interrupted run seems lost | run `run` again; merged tasks are skipped, not re-dispatched |
+| every wave has exactly one task | `files` sets overlap across most tasks; the decomposition isn't actually parallel |
+| dwarves reimplement already-merged work | `goal.txt` or `files` missing, so the capsule carries no useful status |
+| several tasks report "produced no changes" | the decomposition made tasks that weren't independently actionable — use a coarser `--decompose-level`, not more retries |
+| `retry` says "produced no new changes" | the dwarf returned a byte-identical diff, so no reviewer was paid to read the same code twice. Escalate with `--dwarf`, or fix the prompt |
+| a new file's code never reached QA | fixed: untracked files are diffed against `/dev/null`. A hand-built capture using only `git status --porcelain` shows the reviewer a filename and no content |
+| claude dwarf ends "I need your permission to edit" | a permission mode that prompts for Edit. forge uses `acceptEdits` plus an explicit Bash allowance, because `auto` allows shell but prompts for Edit, and `acceptEdits` alone allows Edit but prompts for real shell commands |
+| `.forge/` turns up in a review | a diff capture is missing `':(exclude).forge'` |
+| memory stays empty | nothing durable was learned — the common, correct case. The ledger still has a row per dispatch |
+| a wrong fact keeps reappearing | `memory.md` is rebuilt from the ledger; delete the ledger rows, not the memory line |
+| dwarves build incompatible interfaces | the seam was never agreed — plan the approach, or use `--planner` |
+| Fractal was installed but a new unattended run uses ordinary execution | installation never activates it; pass `--fractal` explicitly |
+| `Fractal selected but unavailable` | run `forge fractal doctor`, then the suggested managed install; resume retains the selected backend |
+| existing run rejects a new backend, pool or limit | selection and bounds are recorded; create a new run directory for changed settings |
+| Fractal reports completion but Forge has not accepted the work | inspect QA, verdict and verification; execution completion does not establish acceptance |
+| Fractal import stops with `source_drift` | the source changed after its snapshot; preserve both versions and inspect the candidate instead of forcing import |
+| Fractal work was paused or its coordinator exited | inspect `status` and `logs`, then use explicit `resume RUN_ID`; retry starts a new attempt |
+| browser dashboard closed while work is running | execution is independent; reopen with `forge fractal open RUN_ID` |
+| costs are unknown or a dollar cap is rejected | the bridge only reports available usage; v1 cannot enforce a spending cap |
+
+For per-harness invocation details, effort ladders and known CLI failure modes, see
+[`references/harnesses.md`](../references/harnesses.md). For decomposition mechanics, see
+[`references/decompose.md`](../references/decompose.md). For memory internals, see
+[`references/memory.md`](../references/memory.md).

package/forge

@@ -21,7 +21,11 @@ usage() {
     '  fractal   opt-in Fractal execution: install, doctor, runs, status, tree, logs, open, report, ...' \
     '  jev       optional Jev advice: setup, status, doctor, enable, disable, backtest' \
     '  dataset   every run'"'"'s inputs and outcomes: status, dump, import, export, outcomes, ...' \
+    '  issues    file the review findings a run left open as GitHub issues (plain gh)' \
     '  ui        forge-ui, the run viewer: open [DIR], status, stop' \
+    '  runs      this repo'"'"'s recent runs in the terminal: state, verdicts and run dirs' \
+    '  control   a plan'"'"'s live controls: show, set (QA threshold, retries, timeouts), pin, unpin' \
+    '  config    every config source: show, and set/unset the per-repo .forge files and Jev on/off' \
     '  update    fast-forward this checkout and refresh every harness installation' \
     '  version   the installed version, and whether a newer release is out' \
     '' \
@@ -46,10 +50,26 @@ case "${1:-}" in
     shift
     exec python3 "$ROOT/scripts/forge-dataset.py" "$@"
     ;;
+  issues)
+    shift
+    exec python3 "$ROOT/scripts/forge-issues.py" "$@"
+    ;;
   ui)
     shift
     exec python3 "$ROOT/scripts/forge-ui.py" "$@"
     ;;
+  runs)
+    shift
+    exec python3 "$ROOT/scripts/forge-runs.py" "$@"
+    ;;
+  control)
+    shift
+    exec python3 "$ROOT/scripts/forge-control.py" "$@"
+    ;;
+  config)
+    shift
+    exec python3 "$ROOT/scripts/forge-config.py" "$@"
+    ;;
   update)
     shift
     exec /bin/bash "$ROOT/scripts/forge-update.sh" "$@"

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@giamme/forge",
-  "version": "0.8.0",
-  "description": "One model builds it. A different model reviews what it actually built.",
+  "version": "0.10.0",
+  "description": "Multi-model coding with a reviewer that reads the code: plan, build in parallel worktrees, review every real diff, merge only what passes.",
   "keywords": ["claude-code", "codex", "opencode", "agent-skill", "code-review", "multi-model"],
   "license": "MIT",
   "author": "Giamme",
@@ -14,6 +14,7 @@
     "VERSION",
     "CHANGELOG.md",
     "README.md",
+    "docs/",
     "LICENSE",
     "registry.tsv",
     "references/",

package/references/dataset.md

@@ -35,7 +35,9 @@ time order: an attempt that PASSed, then a merge that CONFLICTed, then a human `
 | `run_end` | `run` | results per task, the accepted integration commit, `memory.md` |
 | `invocation` | user-facing `forge-parallel.sh` subcommand | argv, exit, duration, plus final review, accept, integrate and split/combine payloads |
 | `event` | point event | `merge` (MERGED, CONFLICT with the files, INVALIDATED and why), `integrate_advanced`, `integrate_conflict`, `combine_conflict`, `sched_terminal`, `subset_run` (every outcome), `memory_record`, `memory_prune` |
-| `event` `escalation` | `retry --dwarf` | the model a retry escalated from and to, recorded at the rewrite, before the retried attempt begins |
+| `event` `escalation` | retry that changes the model | the model a retry escalated from and to, `after_attempt`, and `source` (`policy`, `retry` for an explicit `--dwarf`, or `pin`), recorded at the rewrite, before the retried attempt begins |
+| `event` `control` | `forge control` change | a human's live change: `at`, `actor` (`cli`/`ui`), `action` (`set`, `pin`, `unpin`), `key`, `value`, `previous`; task events carry the task id. Also read back from `control.log` by `import` |
+| `event` `run_delete_started` / `run_deleted` | `forge runs rm` | written strictly around a run's deletion: `path`, `run_id`, `archive`, and for `run_deleted` the bytes freed |
 | `event` `shadow_review` | shadow review | how an opt-in second review ended (`done`, `invalid`, `overtime`, `orphaned`, ...), with the reviewed commit and both specs. Its dispatch is recorded with role `qa_shadow` |
 | `jev` | Jev request | site, answers, usage, latency, mode. Blob: the **full request** (state and questions). Its original sha is `jev.jsonl`'s `key` |
 | `fractal_step` / `fractal_node` | Fractal step, node state | decomposition decision, iteration, resolved model, cost, tokens, candidate diff |
@@ -297,6 +299,21 @@ so the importer will not guess which execution wrote a mutable file:
 - Archives are extracted to a temp dir and mapped back to their original path. The legacy
   run id hashes that original path, so the archive and the original dir agree on it.
 
+- **Import is strict when a caller must know.** `importer.import_run` is strict by default and
+  `forge runs rm` relies on it: it stores through `record_strict`, which raises (and the deletion
+  stops) if any event, blob included, was not stored, or any part of the run could not be read,
+  instead of treating an unreadable file as absent. Live capture stays fail-open. Interventions import by content, not by time of capture:
+  `tasks/<id>/escalations.tsv` (four or five columns; a missing `source` reads as `policy`) and
+  `control.log` produce the same event ids as live capture, so a re-import fills gaps without
+  duplicating. A line that does not parse is reported as failed.
+- **Archives describe themselves.** `archive_run` writes `FORGE_ARCHIVE.json` first
+  (`format`, `original_path`, `run_id`, `dataset_uid`, `created`), then `FORGE_ARCHIVE_EXCLUDED.txt`, then
+  the run dir under its basename. Symlinks, files over 50 MB, `review-*` snapshots and what the
+  importer never reads are left out and listed in the excluded file. Importing such an archive maps
+  it back to `original_path`, so its run id and uid match the original dir's; an unreadable path
+  during archiving is an error, not a silent omission. The archive is written to a temp name, fsynced
+  and renamed.
+
 `~/.local/share/forge/legacy/` holds archives of run dirs taken before live capture, with a
 `MANIFEST.tsv`. Passing that dir to `import` reads every archive, plus the ledger copies
 listed in `ledgers/REPOS.tsv`.

package/references/decompose.md

@@ -390,7 +390,7 @@ realistic input or a broken existing contract; P2 edge-case bug, unusual-timing
 hardening; P3 minor. Severity is impact; CONFIRMED/PLAUSIBLE is confidence.
 
 `run`/`retry --qa-threshold Pn` (remembered in `<plan>/qa_threshold`; `none` clears it) sets
-the **least severe level that still blocks**. `tasks/<id>/qa_threshold` overrides it per task —
+the **least severe level that still blocks**. `tasks/<id>/qa_threshold` overrides it per task (the value `none` exempts the task from a plan threshold; `forge control set ... qa-threshold` writes both and takes effect at the next attempt) —
 the way to give a dev-tooling or investigation task a looser bar than production code,
 which otherwise gets a new finding in a new corner of a non-default option every round and
 only a human decision ends it. The orchestrator decides *deterministically* (`forge-contract.py gate`),
@@ -470,6 +470,24 @@ turns it off):
 History cannot yet say whether escalating rescues a task (31% of the 29 later attempts on a
 changed spec passed, mostly effort bumps); the attempts this policy makes are what will.
 
+**Live controls.** `forge control show|set|pin|unpin <plan>` changes a run while it works:
+`qa-threshold` (read once per attempt, so an attempt keeps the bar it started with; per task, `none`
+exempts it and `inherit` drops the override), `timeout`, `escalate-after`, `verify-retries`, and,
+only while a scheduler is live, `retry-budget` (plan or `--task`) and `infra-retries`. The budgets
+keep the **per invocation** rule: the flags of `run` are not remembered, and a live scheduler only
+mirrors them into `retry_budget`, `infra_budget` and `tasks/<id>/retry_budget` (re-read at every
+decision, removed when it stops; `tasks/<id>/retries.used` stays), so a change dies with the
+run. `pin <task> <spec>` sets the model the task's next full retry uses, once (checked with
+`forge-dispatch.sh doctor`, no quota): `prepare_retry` claims `escalation.pin` as
+`escalation.pin.applying`, rewrites `tasks.tsv`, appends the `escalations.tsv` row with
+`source=pin`, clears `escalation.stop`/`split.suggested`, then consumes the pin. A QA-only resume
+leaves it for the next full retry; Fractal plans never apply pins; a MERGED task refuses one.
+The last column of `escalations.tsv` says who decided: `policy`, `retry` (an explicit
+`--dwarf`) or `pin`; four-column rows read as `policy`. Every change goes to `control.log` (JSON lines:
+`at`, `actor` `cli|ui`, `action`, `task`, `key`, `value`, `previous`) and to the dataset as a
+`control` event. Exit 2 invalid input, 3 refused (not live, MERGED, Fractal, failing doctor,
+lock busy over 5 s). Report them; never set one yourself unless asked.
+
 **Ordinary execution resume:** run `run` again. Tasks already `MERGED` are skipped. A saved PASS is fingerprint-checked and merged without
 redispatch. PENDING, `INFRA` (paused by an infrastructure failure) and newly unblocked tasks run
 when eligible. Failed or interrupted tasks
@@ -521,7 +539,7 @@ its last message, and to say plainly what it could not run.
 ## Accepting, splitting, combining and the whole-run review
 
 Four subcommands act on plans after tasks have run. Full usage and refusal conditions are in the
-[README](../README.md#accepting-a-task-despite-its-reviewer); the mechanics:
+[README](../docs/reviews.md#accepting-a-task-despite-its-reviewer); the mechanics:
 
 - **`accept <plan> <task> --reason … --approved`** overrides a `FAIL`/`UNKNOWN` reviewer only
   when the reviewed commit is still the branch tip and the worktree still matches

package/references/fractal.md

@@ -5,7 +5,7 @@ model routing, independent QA of the cumulative diff, verification and integrati
 Fractal execution completion and Forge acceptance are separate outcomes. Costs are
 observational, and this integration makes no speed or cost-saving claim.
 
-For a first run, follow the [README walkthrough](../README.md#fractal-execution).
+For a first run, follow the [Fractal guide](../docs/fractal.md).
 This reference covers the exact selection, routing, lifecycle and inspection contracts.
 
 ## Contents

package/references/harnesses.md

@@ -46,8 +46,8 @@ disables), else the optional `timeout` column of the model's registry row, else
 
 **Infrastructure failures exit `8`.** After the backend exits, `forge-runtime.py classify` reads
 the dispatch log (never `<role>.last`, which is only created afterwards): claude/openclaude/grok
-`result` events with `is_error`, codex `turn.failed`/`error` events that nothing followed,
-and for the raw-log harnesses (opencode, antigravity) the last 2 KB when the exit was nonzero —
+`result` events with `is_error`, codex `turn.failed`/`error` and opencode `error` events that no
+answer followed, and for the raw-log harness (antigravity) the last 2 KB when the exit was nonzero —
 looking for strong phrases (usage/session limit, quota, insufficient balance/credit, rate limit,
 429/529, unauthorized/401/403, invalid API key, not logged in, ECONNRESET/ENOTFOUND/…). An
 `empty` answer (exit 0, nothing said) is the fifth class. codex's non-fatal reconnect notices
@@ -90,8 +90,9 @@ reason forge validates efforts itself before dispatch.
 
 **Prompt delivery uses stdin.** Forge copies the input once (including FIFOs), checks it
 with a streaming whitespace character class, and runs `codex exec ... - < role.prompt`.
-Native review has no custom prompt and uses `/dev/null`. Codex JSONL events and Claude
-`--output-format json` provide native usage; final responses remain in `<role>.last`.
+Native review has no custom prompt and uses `/dev/null`. Codex JSONL events, Claude and openclaude
+`--output-format stream-json` and opencode `--format json` provide native usage; final responses
+remain in `<role>.last`.
 See the official [Codex non-interactive guide](https://learn.chatgpt.com/docs/non-interactive-mode)
 and [Claude headless guide](https://code.claude.com/docs/en/headless).
 
@@ -109,12 +110,18 @@ and `--approve-for-me` additionally conflicts with an explicit `-s/--sandbox`.
 ## claude / openclaude
 
 ```
-<harness> -p --model <model> --add-dir <run-dir> --effort <effort> \
+<harness> -p --model <model> --add-dir <run-dir> --output-format stream-json --verbose --effort <effort> \
   (--permission-mode acceptEdits --allowedTools Bash | --dangerously-skip-permissions)
   [--disallowed-tools "Edit,Write,NotebookEdit"]
 ```
 with the prompt delivered on **stdin**.
 
+**The log is a stream.** `--output-format stream-json` (which `-p` accepts only with `--verbose`)
+writes one JSON message per line: the session, every assistant message and tool call, every tool
+result, and a closing `result` line with the final answer and the token counts, which is what
+forge reads into `<role>.last` and the metrics. The rest is the run's conversation, which forge-ui
+shows. Hook and rate-limit events in the stream are ignored.
+
 **The prompt must not go on argv when a variadic flag precedes it.** `--disallowed-tools`,
 `--allowed-tools` and friends are variadic, so a following positional is consumed as
 another value. In practice the prompt is parsed word by word into tool names — you get a
@@ -162,7 +169,7 @@ Claude-Code-shaped harness. That is the point of `sol:xhigh:openclaude`.
 ## opencode
 
 ```
-opencode run -m <provider>/<model> --dir <repo> --variant <effort> --auto [--agent plan] "<prompt>"
+opencode run -m <provider>/<model> --dir <repo> --variant <effort> --auto [--agent plan] --format json "<prompt>"
 ```
 
 Models are always `provider/model`; `opencode models` lists what is configured.
@@ -195,6 +202,11 @@ agy --model <model> --print-timeout <t> [--effort <e>] --add-dir <repo> --add-di
 The harness is named `antigravity` in forge; the binary is `agy`. This is how Gemini is
 reached.
 
+**Its log stays plain text.** agy has `--output-format stream-json`, but only its closing event
+has been seen (`{"event": "result", "result": {"status", "response", "error", "usage", ...}}`, on a
+lapsed login), not the stream of a working run, and the final answer would come from it. Until
+then forge keeps agy's printed output, which is both its log and its answer.
+
 **`--print` must use the attached `=` form.** It is a Go flag with an optional value, so
 written detached it consumes whatever token follows as its prompt. `agy --print
 --print-timeout 120s --model X "real prompt"` fails with *"--print took --print-timeout as

package/references/solo.md

@@ -48,7 +48,7 @@ nothing was judged — fix the cause and run again; a dwarf that returns nothing
 nothing is reported as 8, not 5). The default dispatch timeout is 2700 seconds, scaled up for
 `xhigh`/`max` effort (so the default QA/planner effort gets 3600), overridable per model in the
 registry; 0 disables that dispatch timeout, but an enabled Fractal task still has its own attempt
-deadline. See [dispatch timeouts](../README.md#scriptsforge-dispatchsh).
+deadline. See [dispatch timeouts](../docs/commands.md#scriptsforge-dispatchsh).
 
 The dwarf prompt carries implementer rules (no commits, no background processes, finish every
 measurement before the last message). forge records what it observes: if the dwarf committed

package/references/ui.md

@@ -1,6 +1,6 @@
 # forge-ui
 
-forge-ui is a read-only local web page that shows a forge run live: a decomposed plan or a
+forge-ui is a local web page that shows a forge run live and can change it: a decomposed plan or a
 solo run. It is opt-in per run. The orchestrator asks "Open forge-ui to watch this run?
 [y/N]" once at the start of every new interactive run and passes the answer as `--ui` or
 `--no-ui`. Nothing about the run depends on it: a UI that cannot start prints a note and the
@@ -23,6 +23,15 @@ run goes on, with the same exit code.
   review's combined diff, with every P0–P3 finding shown under the line it names.
 - **Fractal child tasks:** the tree a Fractal task was split into, in the inspector and above
   the opened task in 3D, each node with its decision, cost, output and candidate diff.
+- **Controls:** change a live plan from its inspector: QA threshold, timeout, escalate-after,
+  verify retries, and (while a scheduler is live) the retry and infra-retry budgets; per task, a
+  threshold override (`None` exempts it), a retry budget and a one-shot model pin. Each is one
+  `forge control` call; the change is confirmed first and logged in `control.log`.
+- **Open findings and issues:** the findings a run (or all of its repository's runs) left open,
+  filed as GitHub issues or dismissed through `forge issues`.
+- **Delete a run:** a dry run, then `forge runs rm`: the dataset keeps the traces, an archive is
+  written unless declined, and clean worktrees and unchecked-out branches can go with it.
+- **Settings:** `forge config show` in one view, with edits for the per-repo files and Jev.
 - **Export a run:** one HTML file to share that opens without forge-ui; prompts, diffs, reports
   and local paths stay out unless chosen.
 - **Quick jump and notifications:** Ctrl K (⌘K) or `/` searches every run, task, project and
@@ -96,10 +105,23 @@ how the map shows all of a repo's runs. `forge-parallel.sh run` also records the
 
 ## Privacy
 
-The server binds only `127.0.0.1` and serves read-only. It has **no token**: any process on
-the machine, under any user who can reach loopback, can read every run it knows, including
-prompts, diffs and review text from private repos. A running server keeps serving them,
-including runs that were later rerun with `--no-ui`.
+The server binds only `127.0.0.1`. **Reading needs no token**: any process on the machine,
+under any user who can reach loopback, can read every run it knows, including prompts, diffs and
+review text from private repos. A running server keeps serving them, including runs that were
+later rerun with `--no-ui`.
+
+**Changing needs one.** The server never writes a run file, a repo or a config itself: every
+change is a call of forge's own CLI (`forge control`, `forge issues`, `forge runs rm`,
+`forge config`), so validation, locks and the audit log are the CLI's. Each server start makes a
+random token and puts it in the page it serves; every change must send it back, from a `Host` of
+`127.0.0.1` or `localhost` and with an `Origin` equal to that host when the browser sends one, or
+it is refused before any CLI runs. There are no CORS headers, so another site in your browser
+can neither send nor read a change. Any process that can fetch the page can read the token, as
+it can read the runs, so on a shared machine start the server **read-only**: `--read-only`
+(`python3 -m forge_ui`) or `FORGE_UI_READONLY=1` (also for `forge ui open`). A read-only server
+issues no token and answers every change with 405; its `/api/health` says `"controls": false`.
+`forge ui open` never reuses a server in the other mode: it replaces it, as it does one running
+old code, and `forge ui status` shows the mode.
 
 Every run is registered, so a running server shows every run on the machine, not only those
 opened with `--ui`. The 3D view fetches three.js from cdn.jsdelivr.net (no run data is sent;