@giamme/forge 0.10.0 → 0.11.0

package/CHANGELOG.md

@@ -5,6 +5,36 @@ All notable changes to this project are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and versions follow the format `{major}.{minor}[.{patch}]` ([...] parts appear only when non-zero).
 
+## [0.11] - 2026-10-26
+
+Reviews now remember the last round: a retry's review starts from the previous findings, and a repeated whole-run review from the last report. forge dataset can forecast a plan before it runs and grade how often each reviewer's PASS held, and forge-ui shows a superseded final review as OUTDATED instead of FAIL.
+
+### Highlights
+
+- `forge dataset reviewers`: a report card for reviewer models. For each reviewer, how often work it PASSed was later reverted or mostly rewritten within the outcome horizon (14 days by default), with a 95% interval, or "not enough data" below 10 outcomes. forge-ui's Models view shows it as the Reviewers table's Did not hold column. Advisory only: it never changes routing.
+- `forge dataset forecast <plan>` estimates a plan from past tasks at the same tier and model: median and p90 tokens and time, and the first-try PASS rate with a 95% interval, per task and in total, flagging tasks unlikely to pass first time. `forge-parallel.sh run` prints it before dispatching and records it for later checks (`--no-forecast` turns it off). It is advisory only.
+- On a retry, the per-task reviewer now first checks the previous round's findings, sees the diff between the two attempts and reads the implementer's reply, instead of starting cold. This applies on every harness, so a finding that was fixed is confirmed as fixed and one that was not is raised again.
+- A final review that later merges superseded now shows as OUTDATED in the forge-ui run view and on the cloud map, not as the run's verdict, and tasks merged with `accept` show as accepted instead of failed. `forge issues` and the Open-findings view mark the findings of an outdated review, and accepted findings get their own origin and issue text.
+
+### Added
+
+- `plan --reviewer-session` is an opt-in experiment that continues the reviewer's own session across rounds on claude, openclaude and codex, and falls back to a fresh session whenever it cannot. Those reviews are tagged in the dataset and kept out of the reviewer statistics, so the experiment does not skew the independence numbers.
+
+### Changed
+
+- A mistyped command now says which one you most likely meant, for example `forge rnus` answers "Did you mean `forge runs`?" above the usage.
+- A repeated whole-run review now carries the previous final review's report and the diff since it, so it checks what the earlier review found rather than reviewing the run from scratch.
+
+### Fixed
+
+- forge-ui started directly (`python3 -m forge_ui`) now finds forge's run registry the way forge writes it: an `XDG_CONFIG_HOME` that starts with `~` lists your runs instead of none.
+- A grok dwarf or reviewer that runs its tests in the background no longer ends as an error after 10 minutes: grok now waits for that work as long as forge's own time limit allows, and `forge-dispatch.sh doctor` checks that the installed grok supports this.
+- A relative `XDG_CONFIG_HOME` now counts as unset, as the XDG spec says, so forge registers runs and keeps `jev.json` in `~/.config` instead of recording nothing. Before, `forge ui open` printed a link to a run that forge-ui then did not list.
+- The dataset now imports the traces from the archive of a run whose directory name starts with `review-`; before, nothing from it was imported.
+- An escalation pin, or any escalation, no longer writes through a symlinked `escalations.tsv`.
+- The run summary, and `escalation.next` in the router's `--check`, no longer say a pin waits for a QA-only re-run when the next retry will really be a full attempt.
+- A relative `XDG_DATA_HOME` now counts as unset, as the XDG spec says, so the run dataset, run archives and exports stay in `~/.local/share/forge` instead of a folder inside whichever repo forge ran from. `forge config show` reports the same place.
+
 ## [0.10] - 2026-10-23
 
 forge-ui can now change a run: live QA threshold, retries and timeout, a one-shot model pin, open findings filed as GitHub issues, deleting runs while the dataset keeps them, and every config source in one view. Each control is also a forge CLI: forge control, forge runs rm, forge config and new forge issues modes.

package/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: forge
 description: Dispatch implementation and independent diff review to user-selected models through local agent CLIs. Use for /forge or explicit requests to delegate coding or review; explanation-only questions do not authorize dispatch.
-argument-hint: '"<goal>" --dwarf <alias>[:effort[:harness]] [--qa <alias>] [--planner <alias>] [--yolo-dwarf] [--yolo-qa] [--decompose-level low|medium|high] [--fractal|--no-fractal|--fractal-auto-decompose] [--fractal-planner <spec>] [--jev|--no-jev] [--jev-shadow] [--no-memory] [--no-ripwire] [--ui|--no-ui] [--timeout <seconds>] [--retry-failed <n>] [--escalate-after <n>] [--qa-threshold P0|P1|P2|P3] [--file-issues ask|auto|off] [--shadow-qa <spec>[,<spec>]] [--shadow-rate <0..1>] [--explore <0..0.5>] [--fail-first]'
+argument-hint: '"<goal>" --dwarf <alias>[:effort[:harness]] [--qa <alias>] [--planner <alias>] [--yolo-dwarf] [--yolo-qa] [--decompose-level low|medium|high] [--fractal|--no-fractal|--fractal-auto-decompose] [--fractal-planner <spec>] [--jev|--no-jev] [--jev-shadow] [--no-memory] [--no-ripwire] [--ui|--no-ui] [--timeout <seconds>] [--retry-failed <n>] [--escalate-after <n>] [--qa-threshold P0|P1|P2|P3] [--file-issues ask|auto|off] [--shadow-qa <spec>[,<spec>]] [--shadow-rate <0..1>] [--reviewer-session] [--explore <0..0.5>] [--fail-first]'
 allowed-tools: [Bash, Read]
 ---
 
@@ -43,8 +43,9 @@ For explanation requests, explain the workflow without spending model quota.
   separate authorization and `integrate --approved`. Never push automatically.
 - Show the decomposed task/model table and wait for approval before dispatch. Retry only
   when requested; preserve failed task branches and worktrees. `run --retry-failed N`,
-  `--infra-retries M`, `--qa-threshold Pn` and `plan --shadow-qa` (a second review of a
-  sampled share of attempts, never read, to measure reviewer agreement) are opt-in: offer
+  `--infra-retries M`, `--qa-threshold Pn`, `plan --shadow-qa` (a second review of a
+  sampled share of attempts, never read, to measure reviewer agreement) and
+  `plan --reviewer-session` (continue the reviewer's session across rounds) are opt-in: offer
   them, never add them unprompted. So is `--fail-first` (solo or `plan`): the change's new
   tests also run without its non-test changes, and the reviewer is asked to report any that
   still pass as P2; it needs `.forge/verify-subset` and never changes a result by itself. `plan` explores by default (`--explore 0.2`: now and then

package/VERSION

@@ -1 +1 @@
-0.10
+0.11

package/docs/artifacts.md

@@ -17,6 +17,8 @@ as if the dwarf had written it.
   <role>.last         the final message — read this first
   <role>.infra        only after an infrastructure failure: class, retry_after, detail
   <role>.orphans      only when processes were left running after the harness exited
+  <role>.session      session id reported by claude, openclaude or codex; absent when the dispatch published none
+  <role>.continue     only when the dispatch was asked to continue a reviewer session: requested=, mode=continued|failed, reason=
   changes.diff        the dwarf's real diff, which is qa's input
 ```
 
@@ -52,9 +54,18 @@ A decomposed run adds:
   tasks/<id>/escalations.tsv           epoch, attempt, from-spec, to-spec, source (policy|retry|pin); older rows have 4 columns
   tasks/<id>/escalation.pin            a human's one-shot model for the next full retry: one dwarf spec on one line
   tasks/<id>/escalation.pin.applying   the pin while a retry has claimed it; removed once the retry is recorded
+  tasks/<id>/retry_findings.commit     commit the carried review judged
+  tasks/<id>/retry_findings.session    session id of that review, when it recorded one
+  tasks/<id>/retry_findings.resolved   that review's resolution (harness=, model=, effort=)
+  tasks/<id>/changes.since.diff        diff from that commit to the one under review; omitted when there is no such range
+  tasks/<id>/changes.since.range       the two commits, full hashes
+  tasks/<id>/changes.since.stat        diff --stat of that range
+  tasks/<id>/review_sessions.tsv       one row per review round while plan --reviewer-session is on: round, attempt, mode, reason, session id
   tasks/<id>/retry_budget, retries.used   live per-task retry budget (a number); retries spent (kept after the run)
   results.tsv                          id  status  branch
   timeout, qa_threshold, verify_retries  options remembered from run/retry flags (also escalate_after)
+  reviewer_session                     holds on; present while plan --reviewer-session is on
+  <final-review-dir>/review.meta       final-review-<epoch>-<pid>/ or integrate-*/final-review/; base=, tip=, source=, spec=, threshold=, integration=, previous=, since=; session= and session_reason= while reviewer_session is set
   control.log                          one JSON line per human change made with forge control
   scheduler.live, control.lock         only while a scheduler runs: {"pid", "started"}; the lock serialises forge control
   retry_budget, infra_budget           only while a scheduler runs: its live budgets (a number each)

package/docs/commands.md

@@ -51,15 +51,19 @@ deletion or the run directory was kept (the same command finishes the job).
 
 `forge issues <plan dir, task dir, review dir, known_issues.md or qa.last>` drafts one GitHub
 issue per finding the run left open (`--group task|run` for fewer) and files them only with
-`--apply`. The findings are the CONFIRMED ones `--qa-threshold` tolerated, PLAUSIBLE ones with
-`--include-plausible`, and what the whole-run review left open. Each issue carries a hidden
+`--apply`. The findings are the CONFIRMED ones `--qa-threshold` tolerated (origin
+`tolerated`), the CONFIRMED ones a person accepted with `accept` (origin `accepted`, with
+their own issue text: a person accepted the work over the reviewer's verdict), PLAUSIBLE
+ones with `--include-plausible`, and what the whole-run review left open. A whole-run
+review the integration branch has moved past is outdated: the issue says so and names the
+tasks that merged after it. Each issue carries a hidden
 fingerprint, so a finding is never filed twice, by this command or by gh-proman. Also:
 `--min-severity`, `--repo`, `--lang`, `--label`, `--confirm-new`, `--max-issues` (default 10; pass
 the size of a `--only` selection).
 
 | Flag | Does |
 |---|---|
-| `--json` | machine-readable output; `findings` lists each one with its fingerprint, severity, origin, task, `filed` state and `dismissed` mark |
+| `--json` | machine-readable output; `findings` lists each one with its fingerprint, severity, origin (`tolerated`, `accepted`, `review` or `plausible`), task, `review`, `filed` state and `dismissed` mark. A whole-run finding's `review` is `{name, outdated, merged_since}` (`outdated` is null when the review has no verdict or the plan has no accepted integration commit; `merged_since` is empty unless the review is outdated). Every other finding has `review` null |
 | `--offline` | never run `gh`: no filed state, commit publication judged from local refs |
 | `--only FP` | keep only these 12-hex fingerprints (repeatable or comma-separated) |
 | `--all-runs` | read `RUN` as a repository (or a plan dir naming one) and collect every run in its registry; the newest plan wins for a finding in several |
@@ -320,6 +324,7 @@ Bash 3.2 entrypoints use a Python standard-library coordinator to schedule eligi
 ```
 forge-parallel.sh plan      <plan-dir> --repo <dir> [routing flags] [--planner <spec>] [--no-memory]
                                      [--decompose-level L] [--shadow-qa <spec>[,..]|none] [--shadow-rate R]
+                                     [--reviewer-session | --no-reviewer-session]
                                      [--explore E] [--ui | --no-ui] [--fail-first | --no-fail-first]
 forge-parallel.sh run       <plan-dir> [--max-parallel N] [--yolo-dwarf] [--yolo-qa] [--dry-run]
                                      [--verify <cmd>] [--setup <cmd>] [--timeout S]

package/docs/dataset.md

@@ -14,8 +14,21 @@ forge dataset status            # size, counts, and anything that looks incomple
 forge dataset import ~/.local/share/forge/legacy   # runs that predate live capture
 forge dataset export            # labeled decision cases for benchmarks and fine-tuning
 forge dataset outcomes          # which integrated lines survived, read from git history
+forge dataset reviewers         # how often work each reviewer PASSed was later reverted or rewritten
+forge dataset forecast <plan>   # likely tokens, time and first-try PASS rate for a plan's tasks
 ```
 
+`forge dataset reviewers` is a report card for reviewer models, built on those outcomes. It is
+advisory only and never changes routing, and it shows "not enough data" below 10 outcomes per
+reviewer rather than a rate a handful of tasks would make up. See
+[the reviewer report card](../references/dataset.md#reviewer-report-card).
+
+`forge dataset forecast <plan>` estimates a plan from past tasks at the same tier and model:
+median and p90 tokens and time, and the first-try PASS rate with a 95% interval, per task and in
+total. It flags tasks below 50% and says "not enough history" under 5 past tasks. `run` prints
+the same block before it dispatches (`--no-forecast` turns it off) and records it, so its accuracy
+can be checked later. It is advisory only. See [plan forecast](../references/dataset.md#plan-forecast).
+
 Deleting a run keeps what it taught the dataset. `forge runs rm <run-dir>` first imports the run
 **strictly** (every event must be stored, or nothing is deleted), then writes a self-describing
 archive under `<data home>/archive/`: a `.tar.gz` whose `FORGE_ARCHIVE.json` records the run

package/docs/decomposed-runs.md

@@ -99,8 +99,9 @@ that baseline, and QA sees only baseline membership recorded for that task.
 ## Fresh session per task, plus a capsule
 
 Every dispatch is a **clean slate** — forge never passes `--continue`, `--resume`, or
-`codex exec resume`. One task's confused turn can't poison another, and each task's context
-stays small.
+`codex exec resume`, except the opt-in `plan --reviewer-session` experiment (it continues
+a reviewer's session across rounds on claude, openclaude and codex). One task's confused
+turn can't poison another, and each task's context stays small.
 
 Clean slates alone would leave every dwarf blind to the wider run, so a short `capsule.md` is
 generated from the task's pinned baseline and preserved for both implementation and QA:
@@ -181,6 +182,10 @@ bash scripts/forge-parallel.sh run "$PLAN" --max-parallel 4 --yolo-dwarf
 bash scripts/forge-parallel.sh integrate "$PLAN" --approved
 ```
 
+`run` starts by printing a forecast for the plan from the dataset: likely tokens, time and
+first-try PASS rate per task, with tasks unlikely to pass first time flagged. It is advisory only,
+and `--no-forecast` turns it off. See [plan forecast](../references/dataset.md#plan-forecast).
+
 `integrate` refuses without `--approved`, and refuses on a dirty working tree.
 For Fractal execution, pass tier pools to `plan` and backend/limit flags to `run`.
 `--max-parallel` limits task pipelines; the shared `--fractal-concurrency` limit includes
@@ -232,7 +237,12 @@ Each change is validated, written under `control.lock`, and says when it applies
   `forge-dispatch.sh doctor`, which spends no quota). A QA-only resume spends no implementer
   attempt and leaves the pin for later. The retry applies it, writes it into `tasks.tsv`, records
   an `escalations.tsv` row with `source` `pin`, clears any `split.suggested` stop and consumes
-  it. Fractal plans never apply pins, and a MERGED task refuses one.
+  it. That row is never written through a symlink: if `escalations.tsv`, or any directory
+  from the plan down to it, is one, the pin stays and nothing is retried. The run summary
+  says a pin waits (`pinned; after the QA-only re-run`) only when the next entry really
+  re-runs QA: a `resume` marker, or an unreviewed verdict, that still matches the
+  worktree. A marker the next retry will discard is reported as `pinned`.
+  Fractal plans never apply pins, and a MERGED task refuses one.
 - **Who decided an escalation.** The last column of `tasks/<id>/escalations.tsv` is `policy`
   (`--escalate-after`), `retry` (a typed `retry --dwarf`) or `pin`; rows from before it was added
   have four columns and read as `policy`.

package/docs/forge-ui.md

@@ -32,7 +32,10 @@ and the cloud remembers it.
 
 The page reads like a signal box's desk: engraved plates for headings, push buttons with lamps
 for switches, and lamps that keep one meaning everywhere (amber running, green merged, red failed,
-unlit pending). Two layouts share it. *Immersive*, the default, floats the runs, the inspector and the tasks
+unlit pending). Tasks merged with `accept` show as accepted (hollow green) rather than failed.
+A final review superseded by tasks merged into the integration branch shows as OUTDATED
+(hollow unlit) instead of as the run's verdict; changes on the user's own branch after an
+integrate are not tracked. Two layouts share it. *Immersive*, the default, floats the runs, the inspector and the tasks
 over a full-window stage (on a first visit the inspector and the tasks start folded, so a run
 opens on its plate); *Workbench* docks them beside it with splitters. `1`, `2` and
 `3` fold each module away, the header switches layout and theme (system, light or dark), and the
@@ -69,8 +72,10 @@ indistinguishable from the same command typed in a terminal, except that `contro
   apply (a budget with no live scheduler, a merged task) is disabled and says why.
 - **Open findings:** the review findings a run left open (tolerated by `--qa-threshold`,
   PLAUSIBLE, or left by the whole-run review), for this run or every run of its repository.
-  Select some and file them as GitHub issues, or dismiss the ones that need no work (and take
-  that back). It runs `forge issues`, so a finding is never filed twice.
+  Findings of an outdated review carry an "outdated review" marker, and findings a person
+  accepted have origin `accepted`. Select some and file them as GitHub issues, or dismiss the
+  ones that need no work (and take that back). It runs `forge issues`, so a finding is never
+  filed twice.
 - **Delete a run:** a dialog that first shows a dry run, then deletes the run directory
   through `forge runs rm`. The dataset keeps the run's traces, and by default a `.tar.gz` of
   them too; you can also remove its clean worktrees and its branches that nothing has checked

package/docs/memory.md

@@ -4,8 +4,10 @@
 
 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:
+Every forge dispatch is a clean slate — the opt-in `plan --reviewer-session` experiment,
+which continues a reviewer's session across rounds, is the exception — 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

package/docs/reviews.md

@@ -51,7 +51,20 @@ Two things it deliberately does:
   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.
+  task fails again without spending a QA dispatch. A retry that only rejects the findings,
+  and leaves that diff unchanged, is still this identical retry: it writes
+  `tasks/<id>/noretry` and QA is not dispatched.
+
+When the diff did change, QA on that retry is handed the previous round as well as the
+cumulative diff. The report goes under **Findings from the previous review round**. The
+diff between the two attempts goes under **Changes since that review**, and is kept as
+`tasks/<id>/changes.since.diff`, `changes.since.range` and `changes.since.stat` (the
+range is omitted when the earlier commit is missing, unknown or not an ancestor, or when
+nothing changed; a diff over 100 KB is replaced in the prompt by its stat). The
+implementer's reply goes under **The implementer's reply (its own account; verify
+every claim against the code)**. The prompt tells the reviewer to restate only findings that are still
+open, as `- [Px][CONFIRMED|PLAUSIBLE]` lines, and to mention a fixed or rejected finding
+only in a plain sentence. The gate and `forge issues` count every labelled line.
 
 `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
@@ -133,6 +146,16 @@ them on the team's project board; anywhere else forge files them itself with pla
 
 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.
+Findings a person merged with `accept` are origin `accepted`: the CONFIRMED lines under
+`## Accepted by a human despite the reviewer's <status> verdict` in `known_issues.md`.
+Their issue says a person accepted the work over that verdict, and gives the recorded
+reason. Findings above that heading, which a threshold tolerated, stay origin
+`tolerated`. A whole-run review whose integration branch has moved since it is outdated.
+Its findings stay listed, and the issue says the review is outdated and names the tasks
+that merged after it. In `--json` each whole-run finding carries `review`: `name`,
+`outdated` and `merged_since`. `outdated` is null when the review has no verdict or the
+plan has no accepted integration commit, and `merged_since` is empty unless the review
+is outdated. Every other finding has `review` null.
 
 ## Accepting a task despite its reviewer
 
@@ -149,7 +172,9 @@ it on its own. It accepts only a `FAIL` or `UNKNOWN` task whose reviewed work is
 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
+reviewer's reply copied verbatim, under
+`## Accepted by a human despite the reviewer's <status> verdict`) 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.
 
@@ -179,6 +204,52 @@ the one remembered in `final_qa`, else the single spec every task shares (otherw
 Tasks that are not merged are not in the result, and it says so. `integrate` also names unmerged
 tasks even without a review.
 
+A later whole-run review carries the previous one's report, under **Findings from the
+previous final review**, and the diff since it, under **Changes since that review**
+(inlined up to 200 KB, otherwise its stat). `review.meta` records `integration=` (the
+accepted integration commit, or `none`), `previous=` (that review's directory, or
+`none`) and `since=` (its tip, when that commit is an ancestor of this review;
+otherwise `none`, and the prompt says the range cannot be shown). When the two reviews
+share a commit, `since=` is that commit and the prompt says nothing changed. The same
+labelled-line rule applies: restate only what is still open, because every labelled line
+is filed.
+
+## Reviewer session (opt-in experiment)
+
+`plan --reviewer-session` continues the same reviewer's session across rounds. It is off
+unless you pass it; `--no-reviewer-session` turns it off again and removes the plan's
+`reviewer_session` marker. While the marker is present, per-task QA and a repeated
+whole-run review continue the previous round's session on claude, openclaude and codex,
+when the resolved harness, model and effort are unchanged. The approval table names it.
+Dispatch details are in
+[continuing a reviewer session](../references/harnesses.md#continuing-a-reviewer-session).
+
+Any round that cannot continue starts a fresh session. That is the first round, a missing
+or malformed session id, a resolution that is missing or different, any harness other
+than those three, a Fractal plan, and a continue that the harness refuses or that fails
+(dispatch exit **9**). Exit 9 means the session was not continued. Forge sends the same
+prompt again as a fresh session, and that dispatch decides the round. One row per round
+is appended to `tasks/<id>/review_sessions.tsv`: round, attempt, `continued` or `fresh`,
+the reason, and the session id the round considered (empty when there was none). The
+row describes the dispatch whose result counts, so a failed continue is a single
+`fresh` row. Reasons are `same-spec`, `first-round`, `no-session`, `invalid-session`,
+`spec-changed`, `harness-unsupported`, `fractal`, `continue-unsupported` and
+`continue-failed`. A final review records the same outcome as `session=` and
+`session_reason=` in `review.meta`.
+
+A shadow review never continues a session. It stays a separate fresh review of a copy of
+the prompt.
+
+A review that was asked to continue is tagged `session_continue` in the dataset
+(`continued`, or `failed` when the continue did not succeed) and left out of the
+reviewer slices and the agreement rate. The fresh dispatch after exit 9 is not tagged,
+so it still counts. See [the dataset](../references/dataset.md).
+
+This is separate from a QA-only resume, the re-run after an infrastructure stop. That
+re-run is the `tasks/<id>/resume` marker: forge revalidates it against the worktree,
+then asks QA again about unchanged work, and no attempt is spent. The reviewer session
+continues the reviewer's conversation into a later round, and only when you opt in.
+
 ## 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

package/forge

@@ -33,6 +33,18 @@ usage() {
     'Runs start from your agent harness (/forge "<goal>" --dwarf <model>); see README.md.'
 }
 
+# suggest WORD — the listed command WORD most likely meant (a unique prefix or a close
+# spelling), read from usage so the two never drift apart; prints nothing when none is close
+# or python3 is missing. -I keeps a stray module in the current directory out of it.
+suggest() {
+  usage | python3 -I -c 'import difflib, re, sys
+word = sys.argv[1].lower()
+names = re.findall(r"^  ([a-z]+) ", sys.stdin.read(), re.M)
+prefixed = [name for name in names if len(word) >= 2 and name.startswith(word)]
+hit = prefixed if len(prefixed) == 1 else difflib.get_close_matches(word, names, 1, 0.6)
+print(hit[0] if hit else "")' "$1" 2>/dev/null
+}
+
 case "${1:-}" in
   install)
     shift
@@ -87,7 +99,10 @@ case "${1:-}" in
     exit 2
     ;;
   *)
-    printf 'forge: unknown command: %s\n\n' "$1" >&2
+    printf 'forge: unknown command: %s\n' "$1" >&2
+    GUESS="$(suggest "$1")"
+    [ -n "$GUESS" ] && printf 'Did you mean `forge %s`?\n' "$GUESS" >&2
+    printf '\n' >&2
     usage >&2
     exit 2
     ;;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@giamme/forge",
-  "version": "0.10.0",
+  "version": "0.11.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",

package/references/dataset.md

@@ -14,6 +14,8 @@ ${FORGE_DATA_HOME:-${XDG_DATA_HOME:-~/.local/share}/forge}/dataset/
   errors.log            capture failures
 ```
 
+An empty or relative `XDG_DATA_HOME` counts as unset, as the XDG spec says.
+
 Capture is on by default and costs a few milliseconds per execution. `FORGE_DATASET=off`
 turns it off for one invocation.
 
@@ -28,10 +30,10 @@ time order: an attempt that PASSed, then a merge that CONFLICTed, then a human `
 | kind | one per | what it holds |
 |---|---|---|
 | `start` | execution | a receipt written by `begin()`. A start with no matching end is an execution that was killed or is still running |
-| `dispatch` | model call | role, alias, harness, **resolved** model, effort after clamping, timeout and its source, delivery (custom or native review), phase timings, exit, timeout, infra class, tokens, parsed verdict and findings, `FORGE_LEARNING` lines. Blobs: the delivered prompt and the final message |
+| `dispatch` | model call | role, alias, harness, **resolved** model, effort after clamping, timeout and its source, delivery (custom or native review), phase timings, exit, timeout, infra class, tokens, parsed verdict and findings, `FORGE_LEARNING` lines, `session_id`, `session_continue`. Blobs: the delivered prompt and the final message |
 | `attempt` | task attempt or solo run | status, attempt number (with refund and resume flags), trigger (`initial`, `auto`, `human`), dwarf and qa spec, declared vs changed files, numstat, drift, guard notes, gate line, patch key, the files this execution wrote and the ones it only carried. Blobs: the diff, retry findings, memory slices, capsule, Jev task files |
 | `verification` / `verify_run` | verify, and each command execution | command and its source (flag, `.forge/verify`, Jev), status, flaky, Jev triage. One `verify_run` per execution, each with its own log |
-| `plan` | `plan` | goal, original request, decompose level, exploratory routing decisions (`tasks[id].route`, with their odds), author (orchestrator or planner), per-task declared vs executed difficulty and who set it, pools, waves, Jev routing and coupling. Blobs: both task tables, prompts, approaches, excerpts of the declared files at plan time, the file inventory, `memory.md` |
+| `plan` | `plan` | goal, original request, decompose level, exploratory routing decisions (`tasks[id].route`, with their odds), author (orchestrator or planner), per-task declared vs executed difficulty and who set it, pools, waves, Jev routing and coupling, options (including `reviewer_session` when that file is present). Blobs: both task tables, prompts, approaches, excerpts of the declared files at plan time, the file inventory, `memory.md` |
 | `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` |
@@ -42,8 +44,22 @@ time order: an attempt that PASSed, then a merge that CONFLICTed, then a human `
 | `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 |
 | `ledger` | ledger row | imported `.forge/ledger.tsv` rows |
+| `forecast` | forecast shown by `run` | the plan forecast printed before dispatch (see [plan forecast](#plan-forecast)), once per run and content. Also in the plan as `forecast.json` |
 | `outcome` | integrated task, per horizon | written by `forge dataset outcomes`, never by a run: how many of the lines a task added survive N days after `integrate`, and what reverted it |
 
+A dispatch carries `session_id` and `session_continue`. `session_id` comes from the attempt
+dir's `<role>.session`, and from `metrics.json` when that file is absent. `session_continue`
+is null when the attempt dir has no `<role>.continue`. That file is written only when the
+dispatch was asked to continue a reviewer session: `mode=continued` is `continued`, and
+`mode=failed`, a missing mode or any other mode is `failed`. The file's presence means
+continuing was requested, so a failed continue that still printed a verdict is tagged too.
+The `attempt` event's `resumed` flag is a different fact: a QA-only re-run after an
+infrastructure stop (the `tasks/<id>/resume` marker).
+
+`plan --reviewer-session` writes `$PLAN/reviewer_session` (`on`). The plan event records
+it in `options`. The file joins the plan id only when it is present, so every plan already
+in a store keeps its id, and turning the experiment on stores a new plan event.
+
 Each blob reference carries `sha` (the stored bytes), `original_sha`, `n` (the original
 size), `kept`, and `cut`. A cut keeps the head and the tail, because a QA prompt ends with
 the diff and a log ends with the failure. Caps: prompt 1 MiB, diff 2 MiB, message 256 KiB,
@@ -117,6 +133,8 @@ forge still running keeps writing.
 ./forge dataset export [--slice S]... [--limit N] [--seed N] [--out DIR]   # labeled decision cases
 ./forge dataset outcomes [--horizon-days 14] [--repo PATH] [--dry-run]     # what integrated work became
 ./forge dataset routing [--repo PATH] [--since DAYS] [--json]   # pass rate and runtime per tier and model
+./forge dataset reviewers [--horizon-days 14] [--repo PATH] [--json]   # how each reviewer's PASSed work held up
+./forge dataset forecast <plan> [--repo PATH] [--json]   # likely cost and first-try PASS rate per task
 ```
 
 `status` runs a different completeness check for each mode, because each mode
@@ -185,6 +203,18 @@ finished on an untouched snapshot and reviewed the same commit counts. The prima
 labels never change, because `qa_shadow` dispatches are not reviews of record.
 `./forge dataset status` prints the agreement rate, overall and per model pair.
 
+A dispatch with `session_continue` set is left out of every slice built from QA rows
+(review cases, citation cases) and out of the shadow agreement pairs. That covers a
+continue that succeeded and one that failed after printing a verdict. A fresh fallback
+dispatch in the same round has `session_continue` null and stays in. The slices have no
+switch that puts the continued reviews back, so a group never mixes the two. Agreement
+still selects the attempt's last verdict-bearing primary, and then drops the pair when
+that primary continued a session: an earlier fresh verdict does not stand in for it.
+`./forge dataset status` prints the number of continued reviews and the number of failed
+continues on their own lines whenever either is non-zero, including in a store with no
+shadow review. The experiment's comparison reads the `dispatch` events (`session_continue`,
+tokens, verdicts, attempts), not these slices.
+
 `meta.jsonl` records each case's slice, run, repo and label source. It also holds hosted
 Jev's own answers where forge recorded them, as baselines that are never part of a case.
 Routing and retry cases add:
@@ -280,6 +310,56 @@ exporter attaches it to that diff's review.
 Each verification event also records the commit it verified (`verification.commit`, named
 before any early return), so a FAIL or UNVERIFIED result can be joined to its code too.
 
+## Reviewer report card
+
+`forge dataset reviewers` joins the survival outcomes above to the reviews that let the work
+through. For each reviewed commit with an outcome at the horizon (`--horizon-days`, default 14,
+only outcomes recorded at exactly that horizon), every primary reviewer (role `qa`) that gave
+that attempt a PASS is credited with one landed outcome. A row is keyed by the reviewer's alias,
+or its model when no alias was recorded, as the forge-ui Models view keys it. A landed outcome
+**did not hold** when a later commit reverted it, or when under 80% of its added lines were kept
+(rewritten): the export's `survives` rule.
+
+- The rate of work that did not hold has a Wilson 95% interval, shown only from 10 landed
+  outcomes on. Below that the row reads `not enough data (n/10)`, and the JSON has
+  `enough: false` with `rate` and `ci` null.
+- A shadow review's PASS decided nothing, so it is not credited. Work that landed after a FAIL
+  (the severity gate or a human accepted it) and work with no recorded review are counted as
+  unattributed. `lost` and `no_additions` outcomes are skipped.
+- Survival is only followed for parallel integrations, so solo runs and hand merges are not here.
+- It only advises: nothing that routes a task or builds a prompt reads it.
+
+forge-ui shows the rate as the Reviewers table's **Did not hold** column, through
+`GET /api/models/reviewers`, which runs this command with `--json`.
+
+## Plan forecast
+
+`forge dataset forecast <plan>` reads the plan's `tasks.tsv` (the declared tier from
+`tasks.declared.tsv` when there is one) and, for each task not yet MERGED, looks up past tasks
+that ran at the same tier on the same resolved model. The effort must match too when the task's
+spec names one. It uses the same task history as `forge dataset routing`, without the plan's own
+run.
+
+- Tokens are input plus output (cached input is not added again), summed over every implement
+  and review dispatch of the task, retries included. Time is the sum of those dispatches'
+  durations. Both show median and p90 (nearest rank).
+- The first-try PASS rate has a Wilson 95% interval. Tasks below 50% are flagged as likely to
+  need a retry. Under 5 past tasks the row reads `not enough history (n/5)` and the JSON has
+  `enough: false` with no rate.
+- Totals add up the per-task medians and p90s, the wall time by wave (the slowest task of each
+  wave), and the expected number of first-try passes.
+- It never creates the store, and prints nothing when the store is missing or has no history.
+
+`forge-parallel.sh run` prints the same block before it dispatches. It runs with a time budget
+(`FORGE_FORECAST_BUDGET_S`, default 3 seconds), prints one line and moves on if reading the
+history takes longer, never prints errors and never changes the exit code. `--no-forecast` or
+`FORGE_FORECAST=off` turn it off. The block is written to the plan as `forecast.json` and
+recorded once as a `forecast` event, so it can later be compared to what the run did.
+
+The history is observational: harder tasks tend to go to stronger models, so a rate describes
+what happened to similar tasks, not what a model would do on this one. It only advises: nothing
+that routes a task or builds a prompt reads it.
+
 ## Importing old runs
 
 `import` reads run dirs that predate live capture through the same readers. An execution
@@ -312,7 +392,8 @@ so the importer will not guess which execution wrote a mutable file:
   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.
+  and renamed. `<role>.session` and `<role>.continue` are plain files in the attempt dir, so a
+  run archive carries them and import tags the dispatch from those files.
 
 `~/.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
@@ -325,7 +406,8 @@ listed in `ledgers/REPOS.tsv`.
 - **Never read by a prompt builder.** Memory inject, the capsule and Ripwire must not read
   the store. A reviewer that could see earlier runs' verdicts would not be independent.
   `tests/test_dataset.py` enforces that outside its own package, the dataset is only
-  imported for capture.
+  imported for capture. The one read is `run`'s [plan forecast](#plan-forecast), which goes to
+  the operator's terminal and `forecast.json`, never into a prompt.
 - **Read-only in your repos.** Capture and the harvester run only object-store git queries
   in a repo: `rev-parse`, `rev-list`, `log`, `show`, `ls-tree`, `cat-file`, `diff` between
   commits and `blame` at a commit. All run with `GIT_OPTIONAL_LOCKS=0`. None takes the

package/references/decompose.md

@@ -266,8 +266,10 @@ So:
 ## The capsule
 
 Every dispatch is a clean slate — forge never passes `--continue`, `--resume`, or
-`codex exec resume`. That keeps one task's confused turn from poisoning another and keeps
-each task's context small, but it also leaves each dwarf blind to the wider run.
+`codex exec resume`, except the opt-in `plan --reviewer-session` experiment (it continues
+a reviewer's session across rounds on claude, openclaude and codex). That keeps one task's
+confused turn from poisoning another and keeps each task's context small, but it also
+leaves each dwarf blind to the wider run.
 
 `tasks/<id>/capsule.md` records ownership and baseline context. `baseline.capsule` preserves
 the implementation-time capsule for QA. MERGED means the reviewed commit is an ancestor of
@@ -275,7 +277,8 @@ this task's pinned baseline, not merely that another task finished while QA was
 Complete requirements, approach, retry findings and distinct memory facts are assembled once
 per role; implementation and review instructions are separate.
 
-It exists to prevent two specific failures that clean slates create:
+It exists to prevent two specific failures that clean slates create, which the opt-in
+`--reviewer-session` experiment does not change:
 
 - a dwarf reimplementing a helper an earlier task already merged, because nothing told it
   that task was done;
@@ -425,7 +428,8 @@ Two details that are load-bearing rather than incidental:
   diff.
 - **An identical retry is not re-reviewed.** If the diff comes back byte-identical to the
   previous attempt, the task fails again without a QA dispatch. Paying a reviewer to read
-  the same code twice buys nothing.
+  the same code twice buys nothing. A retry that only rejects the findings, and leaves
+  that diff unchanged, is still this identical retry.
 
 `retry` is a command a human types. Forge does not loop a dwarf against its own reviewer on
 its own initiative; the one exception is the opt-in `run --retry-failed N` below.
@@ -437,6 +441,14 @@ work: no dwarf, no new commit, no attempt spent. A `tasks/<id>/resume` marker re
 revalidated against the branch tip and the saved source fingerprint before it is trusted; if the
 worktree changed, the full task runs. Findings are carried only from a real review.
 
+On a retry whose diff changed, QA receives the previous round under **Findings from the
+previous review round**, the diff since that round (`tasks/<id>/changes.since.diff`,
+`changes.since.range` and `changes.since.stat`; omitted when the earlier commit is
+missing or not an ancestor, or when nothing changed) and the implementer's reply. It is
+told to restate only findings that are still open, as `- [Px][CONFIRMED|PLAUSIBLE]`
+lines, because every labelled line is counted. That is the retry's review, not the
+QA-only re-run above.
+
 **In-run retries.** `run <plan> --retry-failed N` re-queues a task whose reviewer said
 `FAIL`/`UNKNOWN` as soon as it ends, up to `N` more times in that run, preparing the retry exactly
 as `retry` does (same findings carry-forward, same pinned base, same cumulative review). Other
@@ -466,6 +478,10 @@ turns it off):
   QA-only resume, which spends no implementer attempt.
 - **Reporting:** the policy's state is decided after every attempt, so a run whose retry budget ran out
   still reports `its next retry goes to <spec>` or the split suggestion under the results.
+  A pending pin is reported ahead of both, as `its next retry goes to <spec> (pinned)`, or
+  `(pinned; after the QA-only re-run)` only when the next entry really re-runs QA (the
+  `resume` marker, or an unreviewed verdict, still matches the worktree). A marker the
+  next retry will discard is not that wait.
 
 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.
@@ -480,8 +496,10 @@ decision, removed when it stops; `tasks/<id>/retries.used` stays), so a change d
 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.
+`source=pin`, clears `escalation.stop`/`split.suggested`, then consumes the pin. A symlinked
+`escalations.tsv`, or a symlink in any directory from the plan down to it, is not written:
+the pin stays and nothing is retried. 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