@giamme/forge 0.8.0 → 0.10.0

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] [--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>] [--explore <0..0.5>] [--fail-first]'
 allowed-tools: [Bash, Read]
 ---
 
@@ -29,8 +29,9 @@ For explanation requests, explain the workflow without spending model quota.
   or `forge-solo.sh` and relay the `forge-ui:` URL they print. Never ask on resume or retry;
   unattended runs leave it off. A UI failure never changes the run. Read [forge-ui](references/ui.md).
 - A finished solo run, `plan` or `run` may end with one stderr line, `forge X is available
-  (you have Y): forge update` (checked at most once a day). Relay it once; run the update only
-  when the user asks (`forge update`, then restart the harness session). `FORGE_UPDATE_CHECK=off` silences it.
+  (you have Y): <command>` (checked at most once a day; the command is `forge update`, or npm's
+  for an npm installation). Relay it once; run the update only when the user asks (that
+  command, then restart the harness session). `FORGE_UPDATE_CHECK=off` silences it.
 - `--fractal-auto-decompose` enables automatic split-or-atomic decisions before each
   eligible node implements. Include the effective planner and bounds in the approval
   preview; child decisions need no additional user approval inside those bounds.
@@ -54,10 +55,28 @@ For explanation requests, explain the workflow without spending model quota.
   (`--escalate-after N`, `0` = off); an explicit `retry --dwarf` overrides it. `accept`
   overrides a reviewer, so run it (with the user's `--reason` and
   `--approved`) only on the user's explicit instruction; never self-accept.
+- When you report a run, read `<plan>/control.log` and mention any human change made mid-run
+  (a threshold, a budget, a model pin; `forge control show <plan>` lists them). Never set a
+  control, pin or delete a run with `forge control` / `forge runs rm` unless the user asks.
 - Exit `8` / status `INFRA` is a quota, auth or network stop, not a task failure and no
   attempt was spent: report it, say what to fix, and re-run only when told. For a multi-task
   plan, offer the opt-in whole-run review (`review`, or `integrate --final-review <qa-spec>`);
   it spends QA quota, so never run it unprompted.
+- **Leftover findings become issues.** A run can finish with review findings nobody will act on:
+  - CONFIRMED findings that `--qa-threshold` tolerated (`tasks/<id>/known_issues.md`);
+  - PLAUSIBLE findings in a passed task's `qa.last`;
+  - whatever a whole-run review left open.
+
+  When there are any, act on the user's `--file-issues` choice with one filer:
+  - **gh-proman**, only when it is installed and set up for the repository: `gh-proman -C <repo> config show` exits 0. It also puts the issues on the team's board with a priority. Run `gh-proman findings --from <plan or run dir> --include-plausible --json`, then follow the gh-proman skill's review-findings steps.
+  - **forge's own filer** otherwise (gh-proman missing, or not configured for this repo; never configure it yourself): `python3 <skill_dir>/scripts/forge-issues.py <plan or run dir> --include-plausible --json`, plain `gh issue create`. Pass `--lang` matching the repo's existing issues, and `--label bug` when the repo has that label. If `gh` is missing, unauthenticated or the repo has no GitHub remote, list the findings in the report and say why none were filed.
+
+  The choice:
+  - `ask` (the default): show the dry-run summary (count by severity, titles, anything already filed) and ask once: **"File these N findings as GitHub issues? [all / CONFIRMED only / none]"**. Then re-run with `--apply`, adding `--include-plausible` only for "all".
+  - `auto`: file them without asking (`--apply`, PLAUSIBLE included as "to verify" issues) and report what was created and skipped.
+  - `off`: never offer.
+
+  `--file-issues` is an instruction to you: never forward it to a runner. Skip INFRA, interrupted and still-failing runs. Both filers mark each issue with the same finding fingerprint and skip a finding either one already filed, so offering again after a retry only brings up new ones. A draft flagged as a possible duplicate is skipped on `--apply`: show it, and file it (`--confirm-new`) only if the user says it is different.
 - Jev is optional, off unless configured and enabled, and always advisory: it never
   changes a task's tier, never selects a model, and never substitutes for QA acceptance
   or repository verification (`--jev-act` is still accepted and changes nothing). Read

package/VERSION

@@ -1 +1 @@
-0.8
+0.10

package/docs/README.md

@@ -0,0 +1,26 @@
+# forge documentation
+
+[← README](../README.md)
+
+The README is the short overview. These pages hold the rest, one topic each.
+
+| Page | What's in it |
+|---|---|
+| [Install and update](install.md) | npm or a git checkout, the doctor, what the installer does per CLI, updating |
+| [Command reference](commands.md) | every `/forge` flag with examples, the `forge` command, the runner scripts and their exit codes |
+| [Models, efforts and harnesses](models.md) | the `alias:effort:harness` spec, effort ladders and clamping, yolo mode, the model registry |
+| [Decomposed runs](decomposed-runs.md) | decompose levels and difficulty, routing, waves, capsules, planning, resuming, split and combine, `tasks.tsv` |
+| [Reviews, retries and recovery](reviews.md) | verdicts, retries, infrastructure stops, severity thresholds, accepting, whole-run and shadow reviews, guards, verification, fail-first |
+| [Fractal execution](fractal.md) | the optional nested-execution backend: install, run, inspect, bounds and recovery |
+| [Project memory](memory.md) | `.forge/memory.md` and the ledger, what each role is told, whether to commit it, spend |
+| [forge-ui](forge-ui.md) | the run viewer: commands, the shared server, environment variables, privacy |
+| [Run dataset](dataset.md) | every run's inputs and outcomes, kept for training decision models |
+| [Run artifacts](artifacts.md) | the run directory, a plan's files, worktrees and branches |
+| [Safety](safety.md) | what forge never does to your branch, preconditions, execution integrity |
+| [Ripwire and Jev](add-ons.md) | optional repository context and advisory judgments |
+| [Troubleshooting](troubleshooting.md) | symptoms, causes and fixes |
+| [Development](development.md) | repository layout, offline checks, runtime measurement |
+
+Deeper material that the skill itself reads lives in [`references/`](../references/): the
+per-harness details, the decomposition and Fractal contracts, memory internals, Jev and the
+dataset schema.

package/docs/add-ons.md

@@ -0,0 +1,33 @@
+# Ripwire and Jev
+
+[← README](../README.md) · [All docs](README.md)
+
+Two optional add-ons: Ripwire adds repository evidence to every prompt, and Jev gives advisory judgments. forge works without either.
+
+## Ripwire context
+
+Forge automatically adds optional Ripwire 0.4.0 repository evidence to planner, dwarf,
+and QA prompts across all six harnesses. Setup and interactive runners offer a pinned,
+verified installation; headless runs continue when it is missing. Use `--no-ripwire`
+or `FORGE_RIPWIRE=off` to disable it. Decomposed plans preserve opt-out across resumes
+and retries. See [installation, controls and attempt artifacts](../references/ripwire.md).
+
+## Jev
+
+Jev is TypeSafe's "System One" model. It answers narrow, typed questions over the state it is
+given, quickly and with calibrated probabilities. forge can ask it for advice on routing, test
+selection, gates and memory curation. That advice sits beside forge's own decisions and never
+replaces a model choice, a test run, a review or verification.
+
+It is **off by default**. Each enabled capability sends a narrow slice of the run to an external
+API: task prompts, diff hunks, test names or memory text, and never `.forge/` or `.git`. The
+installer offers setup and declines by default.
+
+```sh
+forge jev setup                        # store an API key
+forge jev status                       # resolved config and enabled capabilities
+forge jev enable [--capability NAME]   # turn it on, optionally for one capability
+```
+
+Chosen sites can go to Cloudflare's hosted Clef instead (`forge jev setup --provider cloudflare`).
+The [full Jev reference](../references/jev.md) covers capabilities, privacy and backtests.

package/docs/artifacts.md

@@ -0,0 +1,84 @@
+# Run artifacts
+
+[← README](../README.md) · [All docs](README.md)
+
+What a run leaves on disk: the run directory, a decomposed plan's files, and where worktrees and branches live.
+
+Each stage writes into the run directory, which lives **outside** the repo — anything forge
+writes inside the working tree would show up in the dwarf's own diff and land in front of qa
+as if the dwarf had written it.
+
+```
+<run-dir>/
+  <role>.resolved     what the spec resolved to (model, effort, harness, any clamp)
+  <role>.prompt       the exact prompt sent
+  <role>.cmd          the exact command line executed
+  <role>.log          full transcript
+  <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
+  changes.diff        the dwarf's real diff, which is qa's input
+```
+
+A solo run also records, for forge-ui and for you:
+
+```
+<run-dir>/
+  status              RUNNING, then PASS|FAIL|UNKNOWN|NOCHANGES|INVALIDATED|TIMEOUT|INFRA|INTERRUPTED|ERROR
+  dwarf.spec, qa.spec the specs the run was given
+  attempts.tsv        epoch, attempt number, status, infrastructure class, dwarf spec; one row per invocation
+```
+
+Plus, in the repo itself and surviving the run:
+
+```
+.forge/memory.md    what forge learned here, injected into future prompts
+.forge/ledger.tsv   one row per dispatch, ever; never injected
+```
+
+A decomposed run adds:
+
+```
+<plan-dir>/
+  goal.txt
+  tasks.tsv
+  waves.tsv, deferrals.txt
+  tasks/<id>/{capsule.md,prompt.md,dwarf.*,qa.*,changes.diff,status}
+  tasks/<id>/attempt, attempts.tsv     attempts spent; one audit row per entry (incl. refunded stops)
+  tasks/<id>/known_issues.md, qa.gate  findings tolerated by --qa-threshold, and the gate's decision
+  tasks/<id>/guard.txt                 what forge observed about the implementer (self-commit, orphans, promises)
+  tasks/<id>/infra.txt, resume, noretry  infrastructure stop record; QA-only resume marker; no-progress marker
+  tasks/<id>/qa_threshold              optional per-task blocking threshold: P0-P3, or none (exempt from the plan's)
+  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_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)
+  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)
+  integration.base                     commit the integration branch started from
+  verification.{status,exit,log,command,fingerprint}   the combined verification
+  verification.{flaky,retry.log}       only when a failing command passed on rerun
+  verification.coverage.txt            suites the verify command does not run (advisory)
+```
+
+with worktrees and branches at:
+
+```
+<repo>/../.forge-worktrees/<run-id>/<task-id>    worktree
+forge/<run-id>/<task-id>                         task branch
+forge/<run-id>-integration                       integration branch
+```
+
+`control.log` lines look like
+`{"at": 1761200000.5, "actor": "ui", "action": "set", "task": null, "key": "qa-threshold", "value": "P2", "previous": "P1"}`
+(`actor` is `cli` or `ui`; `action` is `set`, `pin` or `unpin`; `key` is the control's name, or `pin`; `task` is null for a plan-wide
+control). `scheduler.live`, `retry_budget`, `infra_budget` and the per-task `retry_budget` exist
+only while the scheduler is live: it publishes the flags it was given when it starts, re-reads them
+at every decision and removes them when it stops, which is why `forge control` refuses a budget
+change outside a live run. See [live controls](decomposed-runs.md#changing-a-run-while-it-works).
+
+The worktree root is a **sibling of the repo, never `TMPDIR`**. Isolated worktrees are never
+pushed, so a temp root that gets cleaned takes the only copy of that work with it.

package/docs/commands.md

@@ -0,0 +1,365 @@
+# Command reference
+
+[← README](../README.md) · [All docs](README.md)
+
+Every flag of the `/forge` slash command, the `forge` command, and the scripts the skill runs underneath.
+
+## The `forge` command
+
+npm puts `forge` on your `PATH`; in a git checkout it is `./forge`. Runs start from your agent
+harness (`/forge`); this command installs forge and drives its optional tools.
+
+| Command | Does |
+|---|---|
+| `forge install [--dry-run]` | link forge into each agent harness on this machine; see [install](install.md) |
+| `forge update` | fast-forward a git checkout and refresh every harness installation; on an npm install it names the npm command instead. See [updating](install.md#updating-all-harness-installations) |
+| `forge version [--check]` | the installed version, and whether a newer release is out |
+| `forge fractal …` | opt-in Fractal execution; see [the command group](fractal.md#forge-fractal-command-group) |
+| `forge runs [--repo DIR \| --all] [--limit N] [--json]` | this repo's recent runs, newest first: run id, kind, age, task states, verification and final review, goal, and the run dir. Read-only; the same summaries forge-ui shows |
+| `forge control show\|set\|pin\|unpin PLAN_DIR …` | change a live plan: `set` takes `qa-threshold`, `timeout`, `escalate-after`, `verify-retries`, `retry-budget` or `infra-retries` (the last two only while a scheduler runs; `--task ID` for `qa-threshold` and `retry-budget`, value `inherit` drops the override); `pin PLAN_DIR TASK SPEC` sets the model the task's next full retry uses once, `unpin` drops it; `--json`. Every change is logged in `control.log`. See [live controls](decomposed-runs.md#changing-a-run-while-it-works) |
+| `forge config show\|set\|unset [--repo DIR] [--json]` | one view of every config source (registry, Jev, the repo's `.forge/verify`, `setup` and `verify-subset`, dataset, `FORGE_*` variables with secrets hidden); `set KEY VALUE` / `unset KEY` edit `repo.verify`, `repo.setup`, `repo.verify-subset` (must contain `{files}`) and, for `set`, `jev.enabled true\|false`. `-` as a value reads stdin. Exit 2 on invalid input |
+| `forge runs rm RUN_DIR [--dry-run] [--yes] [--no-archive] [--worktrees] [--branches] [--json]` | delete a run directory but keep what it taught the dataset; see [below](#forge-runs-rm) |
+| `forge issues RUN [--apply] …` | file the review findings a run left open as GitHub issues; see [below](#forge-issues) |
+| `forge ui open\|status\|stop` | forge-ui, the run viewer; see [the command group](forge-ui.md#forge-ui-command-group) |
+| `forge dataset …` | every run's inputs and outcomes; see [run dataset](dataset.md) |
+| `forge jev …` | optional Jev advice: setup, status, doctor, enable, disable, backtest; see [Jev](add-ons.md#jev) |
+| `forge --help` | list the commands; `forge <command> --help` shows each one's options |
+
+### `forge runs rm`
+
+Deletes a run directory (a plan dir or a solo run dir) without losing its traces. It holds the
+run's own lock from the first step to the last (`schedule.lock` of a plan, `pipeline.lock` of a
+solo run), so a run started meanwhile fails to start instead of racing the delete. In order:
+
+1. **preserve**: a strict dataset import of the run; every event must be stored, or nothing is deleted;
+2. **archive**: a self-describing `.tar.gz` under `<data home>/archive/` (`--no-archive` skips it);
+3. **intent**: the dataset event `run_delete_started`;
+4. `--worktrees` removes the run's clean worktrees; `--branches` runs `git branch -D` on its
+   branches that no worktree has checked out;
+5. the run directory is removed, `run_deleted` is recorded and the run leaves the registry.
+
+What counts as the run's is decided from the run id, not read from the run directory: a worktree
+under `<repo>/../.forge-worktrees/<run id>/` on `forge/<run id>/<task>` or
+`forge/<run id>-integration`. Any other worktree there is `foreign`, one with uncommitted changes
+is `dirty`; neither is touched, and a dirty one keeps the run directory too. Branches are reported
+`merged` or `UNMERGED`, so you see what deleting them would lose. `--dry-run` changes nothing and
+reports; `--yes` skips the prompt for the run id (needed without a terminal); `--json` prints one
+object, on failure too. Exit 0 ok, 2 refused input, 3 busy or the run is active, 4 failed during
+deletion or the run directory was kept (the same command finishes the job).
+
+### `forge issues`
+
+`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
+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 |
+| `--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 |
+| `--dismiss FP`, `--undismiss FP`, `--reason TEXT` | mark findings as needing no work (or take it back), then exit; no network. The marks live outside the repo, in `${XDG_STATE_HOME:-~/.local/state}/forge/findings/<repo key>.json` |
+| `--include-dismissed` | draft dismissed findings too |
+
+Two filers for one repository at once would both see a finding as unfiled, so `--apply` takes a
+repository lock from the issue lookup to the last `gh issue create`, and each dismissal takes it
+around its write. A busy lock is retried for 10 s, then exit 3. Exit 0 ok, 2 usage or a `gh` or
+dismissal-store error, 3 busy.
+
+## The `/forge` slash command
+
+```
+/forge "<goal>" --dwarf <alias>[:<effort>[:<harness>]]
+                [--qa <alias>[:<effort>[:<harness>]]]
+                [--planner <alias>[:<effort>[:<harness>]]]
+                [--yolo-dwarf] [--yolo-qa] [--repo <dir>] [--native-review]
+                [--no-memory] [--timeout <seconds>] [--ui | --no-ui] [--fractal | --no-fractal]
+                [--fractal-auto-decompose] [--fractal-planner <spec>]
+                [--fractal-depth <n>] [--fractal-children <n>] [--fractal-nodes <n>]
+                [--fractal-iterations <n>] [--fractal-concurrency <n>] [--fractal-deadline <s>]
+                [--decompose-level low|medium|high] [--max-parallel <n>]
+                [--dwarf-high <spec>] [--dwarf-medium <spec>] [--dwarf-low <spec>]
+                [--qa-high <spec>] [--qa-medium <spec>] [--qa-low <spec>]
+```
+
+| Flag | Default | Meaning |
+|---|---|---|
+| `--dwarf <spec>` | *asks* | the model that implements the change |
+| `--qa <spec>` | `opus` at `xhigh` | the model that reviews the dwarf's diff |
+| `--planner <spec>` | orchestrator plans | dispatch planning to a model; one dispatch per run, effort defaults to `xhigh` |
+| `--no-memory` | memory on | write and inject nothing in `.forge/` |
+| `--timeout <s>` | `2700` (45m) | kill any single dispatch that runs longer. `0` disables |
+| `--yolo-dwarf` | off | drop the dwarf's sandbox and approval gates |
+| `--yolo-qa` | off | drop the reviewer's sandbox |
+| `--repo <dir>` | cwd | repository to work in |
+| `--native-review` | off | use native Codex review against the recorded baseline instead of an inlined diff |
+| `--decompose-level <l>` | off | split the goal into parallel tasks |
+| `--max-parallel <n>` | `3` | concurrent task pipelines |
+| `--dwarf-high/-medium/-low` | — | per-difficulty routing; comma-list pools models |
+| `--qa-high/-medium/-low` | — | same, for reviewers |
+| `--fractal` / `--no-fractal` | ask interactively; off unattended | mutually exclusive, per-run backend choice |
+| `--fractal-auto-decompose` | off | enables Fractal with automatic recursive split-or-atomic decisions |
+| `--fractal-planner <spec>` | top-level planner, then task root spec | frozen decision model; requires automatic mode |
+| `--fractal-depth <n>` | `2` | nested levels below each Forge implementation node |
+| `--fractal-children <n>` | `3` | unsettled direct children per node |
+| `--fractal-nodes <n>` | `12` | lifetime nodes per Forge task, including implementation |
+| `--fractal-iterations <n>` | `6` | per node per execution attempt |
+| `--fractal-concurrency <n>` | `3` | shared model slots across nested trees and QA |
+| `--fractal-deadline <s>` | `2700` | task attempt deadline, excluding explicit pauses |
+| `--fractal-max-cost <amount>` | unsupported | returns an error; the bridge cannot enforce dollar caps |
+
+Fractal's task deadline still applies when `--timeout 0` disables the ordinary
+per-dispatch timeout. Child routing uses the dwarf tier flags; QA stays at the Forge
+task boundary. Pools and Fractal limits are frozen for an existing run.
+
+Before an interactive run, forge asks **“Use Fractal for this run? [y/N]”** once.
+Pass `--fractal` or `--no-fractal` to answer explicitly; unattended runs default off.
+It also asks **“Open forge-ui to watch this run? [y/N]”** (`--ui` / `--no-ui`); on a yes,
+the [forge-ui](forge-ui.md) page opens as soon as the run exists. Resume and retry never ask.
+
+For what `--native-review` trades away, see [native review](reviews.md#native-review).
+
+### Examples
+
+```bash
+# minimum
+/forge "make the cache key include the tenant id" --dwarf sol:high
+
+# both roles named, reviewer thinking harder than the implementer
+/forge "rewrite the rate limiter as a token bucket" --dwarf luna:max --qa sol:ultra
+
+# same model, different CLI
+/forge "extract the retry helper into its own module" --dwarf sol:high:openclaude
+
+# Gemini as the dwarf, unsandboxed so it can actually run the tests it writes
+/forge "add table-driven tests for the parser" --dwarf gemini:high:antigravity --yolo-dwarf
+
+# a cheap dwarf with an expensive reviewer
+/forge "update all the docstrings to match the new signatures" --dwarf haiku --qa opus:max
+
+# work in another repo
+/forge "bump the pinned deps and fix the fallout" --dwarf sol:xhigh --repo ~/dev/other-project
+
+# large refactor, reviewed by codex's native reviewer
+/forge "split the god object into three services" --dwarf sol:ultra --qa sol:ultra --native-review
+
+# parallel, one dwarf for every task
+/forge "add CRUD endpoints for projects, users and teams" \
+  --decompose-level medium --dwarf sol:high
+
+# parallel, routed by difficulty, wider fan-out
+/forge "migrate the whole API layer from REST to gRPC" \
+  --decompose-level high --max-parallel 5 \
+  --dwarf-high sol:ultra --dwarf-medium luna:high --dwarf-low haiku:medium \
+  --qa-high opus:max --qa sonnet:high
+
+# pool two providers on the hard tier so neither quota carries it alone
+/forge "implement the new billing rules across the codebase" \
+  --decompose-level medium \
+  --dwarf-high sol:xhigh,terra:xhigh --dwarf luna:high
+
+# a model that thinks for a long time; raise the per-dispatch backstop
+/forge "prove the scheduler cannot deadlock, and fix it if it can" \
+  --dwarf sol:ultra --timeout 7200
+```
+
+After a decomposed run, a task that failed review can be re-run on its own — with the
+findings that failed it, on a stronger model:
+
+```bash
+bash scripts/forge-parallel.sh retry /tmp/forge-billing pricing --dwarf sol:ultra
+```
+
+## `scripts/forge-dispatch.sh`
+
+Resolves a spec into a real CLI invocation and runs it. Needs only bash and coreutils, which
+is the point: it behaves identically no matter which harness is orchestrating.
+
+```
+forge-dispatch.sh doctor
+forge-dispatch.sh dwarf   <spec> --prompt-file <f> [--repo <dir>] [--run-dir <d>] [--yolo] [--dry-run]
+forge-dispatch.sh qa      <spec> --prompt-file <f> [--repo <dir>] [--run-dir <d>] [--yolo] [--dry-run]
+                                 [--native-review [--review-base <ref>]]
+forge-dispatch.sh planner <spec> --prompt-file <f> [--repo <dir>] [--run-dir <d>] [--dry-run]
+```
+
+| Option | Meaning |
+|---|---|
+| `--prompt-file <f>` | file holding the prompt (required for `dwarf`/`qa`) |
+| `--repo <dir>` | repository the role operates in |
+| `--run-dir <d>` | where prompts, logs and results are written |
+| `--yolo` | bypass sandbox and approvals for this role |
+| `--dry-run` | resolve and print the command; run nothing |
+| `--native-review` | qa only; use codex's built-in reviewer |
+| `--review-base <ref>` | qa only; base ref for the native review |
+| `--agy-timeout <s>` | antigravity `--print-timeout` (long runs need this raised) |
+| `--timeout <s>` | kill this dispatch after `<s>` seconds; `0` disables. See the precedence below |
+
+**Exit codes:** `0` ok · `2` spec or usage error · `3` harness missing or unusable ·
+`4` the backend ran and failed · `7` the backend hit its timeout and was killed ·
+`8` an **infrastructure failure** (quota or usage limit, auth, rate limit, network, or an
+empty answer) — nothing about the work was judged, so callers pause instead of counting a
+failure. On `8`, `<run-dir>/<role>.infra` holds `class=`, `retry_after=`, `detail=`, `rc=`,
+`role=`.
+
+**Timeout precedence.** An explicit `--timeout`, then `FORGE_TIMEOUT` (an explicit `0` wins
+and disables the watchdog), then the optional fifth `timeout` column of the model's
+[registry](models.md#model-registry) row, then the built-in `2700` (45 min). A value that was *not*
+explicit is scaled by the resolved (post-clamp) effort: up to `high` ×1, `xhigh` ×4/3,
+`max`/`ultra`/`ultracode` ×2. QA and planner default to `xhigh`, so their built-in limit is
+3600 s; dwarves default to `medium` and keep 2700 s. `<role>.resolved` records `timeout=` and
+`timeout_source=` (`explicit`, `env`, `registry` or `default`, plus `+effort-scaled`).
+`forge-parallel.sh run`/`retry --timeout S` sets it for a decomposed run (kept in the plan).
+`FORGE_REGISTRY` points the dispatcher at an alternative registry file.
+
+Only antigravity bounds its own runtime, and stock macOS has no `timeout` binary to wrap the
+others in — so a hung backend used to block forever, and under a decomposed run one hung task
+silently stalled the others. The default is deliberately generous: this is a backstop against
+a wedged process, not a budget. A role killed by it has usually left a partial edit behind, so
+`7` is worth reporting as such rather than as a clean failure.
+
+On `3` or `4`, forge shows you the actual error rather than substituting a different model —
+quietly swapping backends hides the fact that the one you picked is broken.
+
+**Process hygiene.** Unless `FORGE_ORPHAN_GUARD=off` (or the run is a Fractal one), the harness
+is started in its own session, and after it exits any process still alive in that session is
+listed in `<role>.orphans` and stopped, so a backgrounded measurement cannot outlive the
+dispatch. The timeout watchdog and the exit trap signal the whole session too.
+
+```bash
+# what would this actually run?
+bash scripts/forge-dispatch.sh dwarf sol:ultra --prompt-file /tmp/p --dry-run
+
+# check a clamp before committing to a long run
+bash scripts/forge-dispatch.sh qa gemini-pro:medium --prompt-file /tmp/p --dry-run
+# effort=low
+# clamped=medium -> low        (gemini-pro offers low and high, but no medium)
+```
+
+## `scripts/forge-solo.sh`
+
+The whole single-task run: memory injection, prompt assembly, the dwarf dispatch, the diff
+capture, the QA dispatch, and the ledger writes.
+
+```
+forge-solo.sh <run-dir> --repo <dir> --dwarf <spec> [--qa <spec>]
+              [--approach <file>] [--yolo-dwarf] [--yolo-qa]
+              [--native-review] [--no-memory] [--timeout <s>] [--dry-run] [--ui | --no-ui]
+              [--fail-first]
+              [--fractal | --no-fractal] [--fractal-<limit> <n>]
+              [--dwarf-low <pool>] [--dwarf-medium <pool>] [--dwarf-high <pool>] [--retry]
+```
+
+You write two files into the run directory; forge does the rest:
+
+| You write | Is |
+|---|---|
+| `prompt.md` | the implementation instruction (required) |
+| `goal.txt` | one line, what was asked — given to the reviewer as intent (optional) |
+
+| It writes | Is |
+|---|---|
+| `dwarf.last` / `qa.last` | each role's final message |
+| `changes.diff` | exactly what the reviewer read |
+| `verdict` | `PASS`, `FAIL`, `UNKNOWN` or `NOCHANGES` |
+| `<role>.{input,log,resolved,cmd}` | the prompt, the transcript, the resolution, the command |
+| `fractal-selection.json` | persisted backend choice; enabled runs include their managed run ID |
+
+With Fractal, per-step dispatch artifacts live in the managed run while the solo directory
+retains the aggregate diff and Forge QA result. `--retry` starts a new Fractal attempt;
+`forge fractal resume RUN_ID` continues preserved execution and pipeline checkpoints.
+
+```bash
+RUN="$(mktemp -d /tmp/forge-XXXXXX)"
+echo "add retry with backoff to the HTTP client" > "$RUN/goal.txt"
+echo "Add exponential backoff to src/http.py, capped at 5 attempts." > "$RUN/prompt.md"
+
+bash scripts/forge-solo.sh "$RUN" --repo ~/dev/api --dwarf sol:high --qa opus
+```
+
+**Exit codes:** `0` reviewed · `2` usage · `3` not a git repository · `4` a dispatch failed ·
+`5` **no changes or review invalidated** · `7` a dispatch timed out · `8` a dispatch hit an
+**infrastructure failure** (quota, auth, rate limit, network, empty output): nothing was
+judged, fix the cause and run again. A dwarf that exits 0 with an empty answer *and* changes
+nothing is reported as `8`, not `5` — it never really ran.
+
+The dwarf is given the same implementer rules as in a decomposed run (no commits, no
+background processes, finish measurements before the last message). If it commits anyway, the
+run still reviews its changes, says so, and prints the `git reset --soft <old HEAD>` that would
+turn them back into uncommitted changes; forge never resets anything itself. Orphan processes
+and promised-later-work notes appear under "implementer guard notes".
+
+`5` is the one worth recognising on sight. Headless dwarves genuinely stop to ask a
+clarifying question that nothing can answer; the run ends having spent the quota and changed
+nothing, with the question sitting in `dwarf.last`.
+
+Two things it gets right that are easy to get wrong by hand, and that fail *silently* rather
+than loudly:
+
+- **`.forge/` is excluded from the capture.** Forge rewrites its own memory in the working
+  tree at the end of every run, so left in, it reaches the reviewer as a file the dwarf
+  appears to have touched — which a good reviewer correctly flags as scope creep.
+- **New files are diffed against `/dev/null`.** A `git status` line says only `?? calc.py`.
+  A dwarf whose entire task was to add a file would have had its actual code reviewed by
+  nobody, while the run still reported a clean QA pass.
+
+The run directory must live outside the repository — anything forge writes inside the working
+tree shows up in the dwarf's own diff. `forge-solo.sh` refuses rather than letting that happen
+quietly.
+
+## `scripts/forge-parallel.sh`
+
+Decomposed runs: many dwarves in isolated worktrees, per-task QA, only passing work merged.
+Bash 3.2 entrypoints use a Python standard-library coordinator to schedule eligible tasks.
+
+```
+forge-parallel.sh plan      <plan-dir> --repo <dir> [routing flags] [--planner <spec>] [--no-memory]
+                                     [--decompose-level L] [--shadow-qa <spec>[,..]|none] [--shadow-rate R]
+                                     [--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]
+                                     [--retry-failed N] [--infra-retries M]
+                                     [--qa-threshold P0|P1|P2|P3|none] [--verify-retries N]
+                                     [--fractal | --no-fractal] [--fractal-<limit> <n>]
+forge-parallel.sh retry     <plan-dir> <task-id> [--dwarf <spec>] [--timeout S]
+                                     [--qa-threshold Pn|none] [--verify-retries N]
+forge-parallel.sh accept    <plan-dir> <task-id> --reason "<why>" --approved
+forge-parallel.sh review    <plan-dir> [--qa <spec>] [--yolo-qa] [--qa-threshold Pn]
+forge-parallel.sh integrate <plan-dir> --approved [--final-review <qa-spec>] [--verify-retries N]
+forge-parallel.sh split     <plan-dir> <new-plan-dir> --tasks <id,id> [--dry-run]
+forge-parallel.sh combine   <new-plan-dir> <plan-dir> <plan-dir>... [--verify <cmd>] [--dry-run]
+```
+
+| Subcommand | Does |
+|---|---|
+| `plan` | validate `tasks.tsv`, resolve difficulty → concrete dwarf/qa specs, compute waves, render the approval table |
+| `run` | schedule ready tasks; per task: worktree → dwarf → diff → QA → status; merge passing tasks onto the integration branch |
+| `retry` | re-run **one** failed task in the worktree it already has, with its reviewer's findings in the prompt |
+| `integrate` | **never automatic** — merge the integration branch into your branch |
+| `accept` | **only on your explicit instruction** — merge a `FAIL`/`UNKNOWN` task's reviewed work anyway, recording why |
+| `review` | **opt-in, spends QA quota** — one reviewer reads the whole combined result; read-only |
+| `split` / `combine` | move tasks into a plan of their own / join fully merged plans into one |
+
+| Flag | Subcommands | Remembered in the plan | Means |
+|---|---|---|---|
+| `--timeout S` | run, retry | `timeout` | per-dispatch timeout in seconds (`0` disables); wins over `FORGE_TIMEOUT` |
+| `--retry-failed N` | run | no — this run only | re-queue a task the reviewer rejected up to `N` more times inside the run |
+| `--infra-retries M` | run | no — this run only | wait out up to `M` infrastructure stops instead of pausing |
+| `--qa-threshold Pn` | run, retry | `qa_threshold` | least severe finding that still blocks; milder ones become known issues; `none` clears |
+| `--verify-retries N` | run, retry, integrate | `verify_retries` | reruns of a failed verify command (default `1`, `0` = strict single run) |
+
+**Exit codes:** `0` ok · `2` usage or validation · `3` precondition (not a git repo, …) ·
+`5` some task failed QA, or the combined verification failed · `6` integration conflict ·
+`8` **paused on an infrastructure failure** (quota, auth, rate limit, network): no attempt was
+spent and nothing was judged — fix the cause and run the same command again.
+
+The full plan → run → integrate walkthrough is in [decomposed runs](decomposed-runs.md#plan-run-integrate). `retry`, `accept` and `review` are covered in [reviews, retries and recovery](reviews.md); resuming, `split`/`combine`, scope drift and `tasks.tsv` in [decomposed runs](decomposed-runs.md).
+
+## `scripts/forge-memory.sh` and `scripts/forge-install.sh`
+
+See [project memory](memory.md#scriptsforge-memorysh) and [install](install.md#scriptsforge-installsh).

package/docs/dataset.md

@@ -0,0 +1,29 @@
+# Run dataset
+
+[← README](../README.md) · [All docs](README.md)
+
+Run dirs get deleted, and the ledger keeps spec strings and verdicts but no inputs. So
+every run also records its raw inputs and outcomes outside every repo, in
+`~/.local/share/forge/dataset/` (`FORGE_DATA_HOME` moves it, `FORGE_DATASET=off` turns
+it off). That covers resolved models, prompts, per-attempt diffs, verdicts and findings,
+tokens, merge and verification outcomes, and the full request behind every Jev judgment.
+It exists to train and calibrate decision models on what forge actually did.
+
+```sh
+forge dataset status            # size, counts, and anything that looks incomplete
+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
+```
+
+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
+dir's original path, run id and dataset uid, so `forge dataset import` maps it back to the same
+run later. It records `run_delete_started` and `run_deleted` events around the removal. The same
+import also reads a plan's `escalations.tsv` (with who decided: `policy`, `retry` or `pin`) and
+`control.log`, so human interventions made with `forge control` are in the dataset as
+`control` events. See [forge runs rm](commands.md#forge-runs-rm).
+
+Capture is fail-open and never read by anything that builds a prompt. See
+[references/dataset.md](../references/dataset.md) for the event schema and its invariants.