@giamme/forge 0.8.0 → 0.9.0

package/docs/decomposed-runs.md

@@ -0,0 +1,268 @@
+# Decomposed runs
+
+[← README](../README.md) · [All docs](README.md)
+
+Split one goal into tasks, route each to a model by difficulty, and run them in parallel in isolated worktrees, merging only the tasks that pass review.
+
+`--decompose-level low|medium|high` turns one dwarf into many. Without the flag, nothing
+changes — one dwarf, one QA pass.
+
+## Two independent axes
+
+Easy to conflate, so: **decompose-level** is how finely the *goal* is split. **difficulty**
+is how hard each resulting *task* is.
+
+| `--decompose-level` | Split |
+|---|---|
+| `low` | only where the goal has obviously independent pieces; 2–3 coarse tasks |
+| `medium` | one task per coherent unit (module, feature slice); typically 4–6 |
+| `high` | finest split where each task is still independently reviewable *and* independently correct; typically 7–12 |
+
+| `difficulty` | Means |
+|---|---|
+| `low` | mechanical and local: rename, move, docs, a test for behaviour that already exists |
+| `medium` | self-contained implementation against a clear spec; bounded blast radius |
+| `high` | needs design judgment, cross-cutting behaviour, subtle edge cases, state or concurrency |
+
+Difficulty is about **judgment required, not diff size**. A five-hundred-line mechanical
+rename is `low`. A ten-line concurrency fix is `high`. Getting this backwards sends the cheap
+model at the subtle problem and the expensive one at the boilerplate — worse than not routing
+at all.
+
+## Routing dwarves to tasks
+
+Per-task assignment can't be expressed when you type the command, because the tasks don't
+exist yet. Naming a dwarf per task would mean guessing how the goal will split. So you map
+**model tiers to difficulty tiers**, once, in advance — three layers, each optional:
+
+```bash
+# 1. one dwarf for everything
+--dwarf sol:xhigh
+
+# 2. per-tier routing, with plain --dwarf as the fallback for any tier not named
+--dwarf-high sol:xhigh --dwarf-medium luna:high --dwarf-low gemini:low:antigravity
+--dwarf sonnet:medium
+
+# 3. pool several models within one tier — round-robined across tasks
+--dwarf-high sol:xhigh,terra:xhigh
+```
+
+`--qa`, `--qa-high`, `--qa-medium`, `--qa-low` mirror it exactly. QA has no tier rules by
+default and falls back to `opus`.
+
+Resolution order per task: **explicit column value → the tier's rule → plain `--dwarf` →
+`UNASSIGNED`**. An `UNASSIGNED` task makes `plan` exit `2` and `run` refuse outright. forge
+does not invent a model when you haven't said which one should spend your quota.
+
+Layer three is **the approval gate**: after decomposition, before any dispatch, you get the
+task table with each task's difficulty and resolved dwarf/qa. Retier a task ("2 is actually
+medium") and it re-routes per your rules, or override a single row's dwarf outright. This is
+also the cost gate — `high` on a large goal is 20+ dispatches, which should be visible before
+it's spent.
+
+**Exploration is on by default** (`--explore 0.2`):
+- **Which rows:** only rows left to forge, never one whose dwarf column you filled.
+- **What changes:** now and then such a row gets its *neighbouring* tier's spec from your own
+  pools: the next cheaper tier for medium and high rows, the next stronger for low rows.
+  Pools that differ only in effort (`--dwarf-low sol --dwarf-high sol:xhigh`) compare the
+  two efforts.
+- **How often:** about one row in ten at the default.
+- **What you see:** each explored row is marked `*` in the table, before anything is spent.
+- **What it's for:** `forge dataset routing` reads the draws back as pass rates per model and
+  effort. Pass `--explore 0` to turn it off.
+
+See [decompose.md](../references/decompose.md#exploratory-routing-on-by-default).
+
+## Waves, and what actually bounds parallelism
+
+A **wave** is the largest set of tasks whose dependencies are all satisfied by earlier waves
+**and** whose declared `files` sets are pairwise disjoint.
+
+Disjointness — not the task count — is the real bound. Two dwarves editing one file produce a
+conflict no reviewer can untangle and no merge can resolve honestly, so they land in different
+waves however the goal was decomposed. When that happens forge says so:
+
+```
+deferrals (serialized to protect the merge):
+  wave 1: lint deferred (file overlap with a task already in this wave)
+```
+
+That line matters. A decomposition that looks parallel but serializes at run time should
+announce it, rather than leaving you wondering why eight tasks took eight rounds. When most
+tasks overlap, the fix is a better split — not more parallelism.
+
+Waves are a planning preview. A Python 3 standard-library coordinator starts eligible tasks
+as prerequisites merge and capacity becomes available, while excluding overlapping active
+paths. Merges are serialized. Each task pins the integration commit at dispatch; retries keep
+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.
+
+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:
+
+```
+# forge run <run-id>
+Goal: <overall goal>
+You are doing ONE task of <N>. Do not do the others' work.
+
+## Your task
+tokens — Add the token model   difficulty: medium
+Files you own: src/auth/token.py
+
+## Run status
+id        diff     status       files
+middleware high    MERGED       src/auth/middleware.py
+tokens     medium  THIS ONE     src/auth/token.py
+docs       low     NOT IN BASE  README.md
+
+## Ground rules
+- Your branch already contains every MERGED task's work — do not reimplement it.
+- Files owned by other tasks are off limits; another dwarf is editing them now.
+- If your task truly needs a change in someone else's file, say so in your final
+  message instead of making it.
+```
+
+It's written **per task**, not once per run — tasks in a wave execute concurrently, so a
+single shared capsule file is a race in which each task overwrites it and reads back whichever
+sibling wrote last, handing a dwarf someone else's task description.
+
+For QA the capsule additionally scopes the review: code from `MERGED` tasks is already in the
+base and is not this task's bug. Without that, a wave-2 reviewer reports wave-1 code as
+defects in the diff it was handed.
+
+## Planning
+
+A dwarf that is handed only an objective plans its own approach, silently, inside its own
+run. Usually fine — but in a decomposed run the capsule prevents two dwarves editing one
+*file* and does nothing about them inventing incompatible *interfaces* at a shared seam.
+Both stay in their lane, both pass their own QA, and the mismatch surfaces at integration.
+
+So forge plans before it dispatches. By default the orchestrator does it and writes the
+approach into each task's prompt — no extra dispatch. `--planner <spec>` hands that stage to
+a named model instead:
+
+```bash
+/forge "migrate the API layer to gRPC" --decompose-level medium \
+  --planner sol:xhigh --dwarf-high sol:high --dwarf luna:high
+```
+
+**One planner dispatch per run, never one per task.** That is the whole point: a single mind
+designs both sides of every seam, where N independent planners would recreate the problem.
+Effort defaults to `xhigh`, since a bad plan is executed at full price by every dwarf
+downstream of it. The planner runs with QA's permission profile — it reads the repo and
+writes nothing to it.
+
+The approach shows up in the approval table under each task, which is the last moment it can
+be changed for free, and it is handed to QA as the *intended* approach — so a review can
+finally say "this works, but it abandons the planned shape" rather than only judging against
+the objective.
+
+## Plan, run, integrate
+
+```bash
+PLAN=/tmp/forge-auth
+
+# 1. plan and inspect the routing
+bash scripts/forge-parallel.sh plan "$PLAN" --repo ~/dev/api \
+  --dwarf-high sol:xhigh --dwarf-low gemini:low:antigravity --dwarf luna:high
+
+# 2. see exactly what will be dispatched, without dispatching
+bash scripts/forge-parallel.sh run "$PLAN" --dry-run
+
+# 3. run it, four dwarves at a time, implementers unsandboxed
+bash scripts/forge-parallel.sh run "$PLAN" --max-parallel 4 --yolo-dwarf
+
+# 4. after reading the results, deliver the passing work
+bash scripts/forge-parallel.sh integrate "$PLAN" --approved
+```
+
+`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
+all their child invocations and QA. See [decomposed Fractal execution](../references/decompose.md#fractal-within-decomposed-tasks).
+
+## Resuming an interrupted run
+
+Run `run` again to skip MERGED tasks, merge saved PASS results after fingerprint checks,
+and dispatch eligible pending tasks. Tasks paused on an infrastructure failure (`INFRA`) are
+dispatched again without any flag, since nothing was wrong with the work. Failed and
+interrupted tasks need an explicit `retry` (or `run --retry-failed N` for rejected ones).
+Their worktrees and pinned baselines remain available. Concurrent run/retry/integrate
+operations for the same plan are excluded by an advisory lock.
+
+For a Fractal-backed run, use `forge fractal resume RUN_ID` to recover recorded execution
+and pipeline checkpoints. A task/subtree selector resumes only that execution scope.
+Explicit `retry` retains the backend and frozen pools; a replacement dwarf must already
+belong to that pool. See [recovery](../references/fractal.md#limits-and-lifecycle).
+
+## Splitting and combining plans
+
+`run --retry-failed N` removes most of the reason to split a plan (a failed task no longer holds
+the rest of a run). When you still want independent work in separate plans — separate locks,
+separate integration branches, one verified at a time — these two make it a supported operation
+instead of hand-built git plumbing:
+
+- `split <plan> <new-plan> --tasks a,b` moves tasks **with their saved state** (attempts,
+  findings, reviewed commit, status) into a new plan: their branches and worktrees are renamed to
+  the new run (`forge/<new>/<id>`), the new integration branch starts at the source's accepted
+  tip, dependencies on already-merged tasks are dropped, and the source forgets the moved rows
+  (`split-<new>.txt` records them). It refuses — changing nothing — for a Fractal-backed plan, a
+  MERGED or RUNNING task, a selection that leaves a dependent behind, or a dependency that is
+  neither moving nor merged. Copy first, delete last; an interrupted split rolls back.
+- `combine <new-plan> <plan-a> <plan-b>…` joins plans whose tasks are **all `MERGED`** into one
+  plan: a new integration branch merges each source's, the per-task records are copied, and
+  `run <new-plan>` then only verifies (no model call) so `integrate` works unchanged. It refuses
+  different repositories, locked or dirty sources, duplicate task ids, and any task left behind;
+  a merge conflict exits `6` after removing everything it created. `--verify` sets the combined
+  plan's check; `--dry-run` previews and predicts conflicts. Task branches keep their original
+  names.
+
+## Scope drift
+
+After each dwarf, the runner compares what the task **declared** in `files` against what it
+actually touched (a declared directory covers the paths beneath it). Undeclared paths appear
+in the summary and in the QA prompt:
+
+```
+scope drift (touched files the task did not declare):
+  auth           src/db.py
+```
+
+Never a failure — a dwarf that genuinely needed one more file did the right thing. What it
+buys is that a merge `CONFLICT` two waves later arrives with its cause already named.
+
+## `tasks.tsv`
+
+Tab-separated, one row per task, written during decomposition:
+
+```
+# id  deps  difficulty  files  dwarf  qa  title
+middleware	-	high	src/auth/middleware.py	-	-	Auth middleware
+tokens	-	medium	src/auth/token.py	-	-	Token model
+route	middleware,tokens	medium	src/routes/login.py	-	-	Login route
+docs	-	low	README.md	-	-	Document the auth flow
+```
+
+| Column | Meaning |
+|---|---|
+| `id` | short unique slug; also the worktree and branch name |
+| `deps` | comma-list of task ids that must land first, or `-` |
+| `difficulty` | `low` \| `medium` \| `high` |
+| `files` | expected touch set, comma-separated — **drives disjointness** |
+| `dwarf` / `qa` | `-` to resolve from the routing rules; an explicit spec always wins |
+| `title` | one line, shown in the approval table and the capsule |
+
+Each task also needs `tasks/<id>/prompt.md`, written the same way a single-task forge goal is.
+
+`files` is a **promise, not a prediction**: it's what the wave planner trusts when deciding
+what may run concurrently, and what the capsule tells other dwarves not to touch. An
+understated `files` is how two dwarves end up in the same file.
+
+`plan` writes resolved specs back into the `dwarf`/`qa` columns, so `run` never consults the
+routing rules — and an explicit value survives a re-plan, which is what makes a gate override
+durable. (`UNASSIGNED` is treated as a leftover marker and re-resolved.)

package/docs/development.md

@@ -0,0 +1,95 @@
+# Development
+
+[← README](../README.md) · [All docs](README.md)
+
+The repository layout, the offline checks, and how forge measures its own runtime cost.
+
+## Repository layout
+
+```
+forge/
+├── SKILL.md                     the skill itself — what the orchestrating model reads
+├── registry.tsv                 alias → (harness, model, effort). Add a row to teach forge a model
+├── README.md                    the short overview
+├── docs/                        the full documentation, one page per topic
+├── LICENSE                      MIT
+├── package.json                 the npm package: its name, version and the files it ships
+├── forge                        launcher, on PATH from npm: `forge install`, `fractal`, `jev`, `dataset` and `ui`
+├── scripts/
+│   ├── forge-dispatch.sh        resolve a spec → run one role on one harness
+│   ├── forge-solo.sh            the whole single-task run: dwarf → diff → qa
+│   ├── forge-parallel.sh        plan / run / retry / integrate for decomposed runs
+│   ├── forge-parallel-options.sh flags shared by several forge-parallel.sh subcommands
+│   ├── forge-lib-task.sh        attempt log, infra stops, QA-only resume, guards, severity gate, report blocks
+│   ├── forge-lib-verify.sh      verify command lookup and the coverage report
+│   ├── forge-lib-plans.sh       accept / split / combine
+│   ├── forge-lib-review.sh      the opt-in whole-run review (review, integrate --final-review)
+│   ├── forge-schedule.py        readiness scheduler: in-run retries, infrastructure pauses
+│   ├── forge-contract.py        the shared QA/dwarf prompt contract and the severity gate
+│   ├── forge-guard.py           implementer guards: session wrapper, orphan reaping, promise scan
+│   ├── forge-verify-coverage.py suites the project defines that the verify command skips
+│   ├── forge-memory.sh          inject / note / record / spend project memory
+│   ├── forge-fractal.py         Fractal CLI and internal adapter entrypoint
+│   ├── forge-fractal-options.sh runner selection, limit flags and help
+│   ├── forge-fractal-dispatch.sh bridge entrypoint for existing pipelines
+│   ├── forge-install-fractal.sh isolated optional runtime installer
+│   ├── forge_fractal/           nested execution, recovery, inspection and dashboard
+│   ├── forge-ui.py              `forge ui open|status|stop`: the one shared forge-ui server
+│   ├── forge-ui-options.sh      `--ui|--no-ui` and the fail-open launch, sourced by the runners
+│   ├── forge_registry.py        the run registry: where run dirs are noted, read by forge-ui
+│   ├── forge-dataset.py         `forge dataset` entry point
+│   ├── forge_dataset/           the run dataset: capture hooks, readers, importer, status checks
+│   └── forge-install.sh         install into every harness that needs it (opencode and grok find it themselves)
+├── ui/                          forge-ui: read-only local run viewer (`forge_ui` package, tests, API contract)
+└── references/
+    ├── ui.md                    forge-ui: commands, env vars, shared server, state, privacy
+    ├── harnesses.md             per-harness invocation, ladders, failure modes
+    ├── decompose.md             tasks.tsv schema, difficulty criteria, wave algorithm
+    ├── fractal.md               opt-in backend, limits, recovery and observability
+    ├── memory.md                FORGE_LEARNING grammar, promotion and pruning rules
+    └── dataset.md               the run dataset: what is captured, where, and its invariants
+```
+
+## Offline checks
+
+Run `bash tests/check.sh` for offline regression checks. See [tests](../tests/README.md) for skill
+invocation scenarios and verification limits. There is currently no CI workflow.
+
+## Runtime efficiency and measurement
+
+Shell entrypoints require Python 3 (standard library only) in addition to Bash and Git.
+The [runtime helper decision](../references/runtime.md) records the module boundaries and tradeoffs.
+Solo and parallel runners default to `--output summary`; use `--output full` to include raw
+backend output. Direct dispatch keeps its full-output default. Read each `dwarf.last` and
+`qa.last` once, and retrieve `.log` or `.out` only when investigating a problem.
+
+QA receives complete requirements, approach, ownership, retry findings and distinct memory
+facts once, with review instructions separate from implementation instructions. Prompts and
+full binary diffs remain on disk. Review repositories receive self-contained tree object packs,
+create baseline/final commits, and check out the final tree once. Exact tree comparisons and
+all source, review and integration fingerprint checks remain acceptance boundaries.
+
+`FORGE_CAPABILITY_CACHE` optionally selects an offline help cache. Runners share a run-local
+`capabilities/` cache across preflights and dispatches. Keys cover the executable's resolved
+path, device/inode, size and modification/change timestamps, help command mode, registry
+contents and dispatch recipe. Every selected spec, effort and permission recipe is still
+validated; cached help never proves authentication or live model availability.
+
+Run `bash scripts/forge-dispatch.sh report <run-dir>` for JSON attempt records, including
+failures and timeouts, with project memory enabled or disabled. `attempts/<role>-<id>/`
+retains prompts, final responses, raw logs, resolution, command and `metrics.json` per dispatch.
+Pipeline records capture preparation, preflight, snapshot, verification and total time;
+dispatch records capture preparation, preflight, model and total time. Nested pipeline
+`dispatch` time includes dispatch overhead: do not add nested totals together. Timing uses
+monotonic seconds. A still-running or forcibly killed record has a null exit code and may
+have incomplete timings. A dispatch that stopped on an infrastructure failure records its class
+(`quota`, `auth`, `rate_limit`, `network`, `empty`) as `infra_class`, and keeps the `.infra` and
+`.orphans` files beside the other attempt artifacts.
+
+Prompt bytes are separate from native input, cached-input and output token counts. Codex
+uses `turn.completed` usage; Claude uses result usage (input includes uncached, cache-read
+and cache-creation tokens). Unsupported or absent usage stays null, never estimated from
+bytes. See [measurement and live evaluation](../tests/README.md).
+
+Measured results, including the live comparison's higher total token use and latency, are
+recorded in [the September 7 evaluation](../tests/benchmark-2026-09-07.md).

package/docs/forge-ui.md

@@ -0,0 +1,92 @@
+# forge-ui
+
+[← README](../README.md) · [All docs](README.md)
+
+forge-ui is a small read-only local web page that shows runs live, as a 3D isometric map
+ported from [archivision](https://github.com/Giamme/archivision). Its **run cloud** puts every
+run in one full-screen view, grouped by project, in five layouts (helix, sphere, galaxy,
+timeline, constellation), filtered down to exactly the runs you want; drag any run anywhere
+and the cloud remembers it.
+
+<p align="center">
+  <img src="../ui/docs/media/cloud.webp" width="880" alt="The run cloud: about seventy runs as blocks in five project spirals, orbited, then laid out as galaxies and as a timeline with one lane per project.">
+</p>
+
+<table>
+<tr>
+<td width="50%" valign="top"><img src="../ui/docs/media/run.png" alt="forge-ui's window: the runs list, a run's eight tasks on a 3D plate in their planned waves with dependency cables, finding marks and the finish nodes, and the run's inspector."><br><b>A run, as planned.</b> Tasks in their waves with dependency cables, ending in integration, verification and the final review. Click a task to open its attempts, dwarves and reviews.</td>
+<td width="50%" valign="top"><img src="../ui/docs/media/execution.png" alt="The same run on wall-clock time: one block per attempt, failed attempts in red with their finding marks, a plane marking now, the concurrency strip, and the inspector's timeline and critical path."><br><b>And as it ran.</b> One block per attempt in the lane it ran in, failed ones in red, against <code>--max-parallel</code>; the inspector names the critical path.</td>
+</tr>
+<tr>
+<td valign="top"><img src="../ui/docs/media/diff.png" alt="The diff a reviewer read, with a P1 finding pinned under the line comparing token digests and a P2 finding under the revoke function."><br><b>Findings on their lines.</b> Any diff of a task, or exactly the diff one reviewer read, with each P0–P3 finding under the line it names.</td>
+<td valign="top"><img src="../ui/docs/media/conversation.png" alt="A dwarf's conversation: its thinking, a search, the files it wrote, a test run that failed with exit 1 and the run that passed after the fix."><br><b>What each agent said and ran.</b> A dwarf's or reviewer's conversation from its CLI's log: commands with their exit and output, edits linked to the diff, its thinking; searchable, errors one key apart, live while it runs.</td>
+</tr>
+<tr>
+<td valign="top"><img src="../ui/docs/media/models.png" alt="The model leaderboard: per implementer, tasks, first-attempt pass rate with a 95% interval bar, retries, escalations, timeouts, accepts, median model time and tokens."><br><b>Models, measured on your runs.</b> First-attempt pass rate with a confidence interval, retries, escalations, time and tokens; reviewers' verdicts and shadow agreement.</td>
+<td valign="top"><img src="../ui/docs/media/files.png" alt="The files heatmap: files grouped by directory against tasks grouped by wave, with planned, touched, drift and same-wave overlap marks."><br><b>Who touched which file.</b> Planned, changed, drifted into or conflicted on, wave by wave; a cell opens that file's diff.</td>
+</tr>
+<tr>
+<td colspan="2" valign="top" align="center"><img width="50%" src="../ui/docs/media/map.png" alt="The map of every run: one block per run in a district per repo, green when done, amber while running, red with failures."><br><b>Every run, by repo.</b> One block per run with a lamp per task, filtered by state, repo, model, age or review verdict.</td>
+</tr>
+</table>
+
+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
+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
+task and model tables sort, reorder and hide columns. forge-ui remembers all of it in your browser.
+
+On the 3D stage every review finding stands over its block as a mark shaped by its severity, and
+a click opens the diff at that finding. A chosen task keeps its route lit, a hover shows its card
+(attempts, time, tokens, worst finding), and merges, failed attempts and escalations play over the
+plate as they happen or as a replay passes them. The *View* menu switches each part of the drawing
+on or off; the keys at the stage's edge fit, zoom, switch between perspective, isometric and
+top-down, open a legend of what is drawn, and `?` lists every key.
+
+Each dwarf's and reviewer's conversation opens from its attempt: what it said, what it ran and
+with what exit, what it changed (with a link into the diff), its thinking folded, and the final
+answer with tokens and cost, searchable, with its errors one key apart and, while it runs,
+following its log as it grows. It is read from the agent CLI's own log, whichever harness
+wrote it (as plain text for those that log no events yet), or for an older claude run from
+Claude's session file on this machine.
+
+Also: replay, critical path, Fractal child-task trees, quick jump (Ctrl K, ⌘K on a Mac, or
+`/`), a bell for runs that finish or fail, failed tasks and final-review verdicts (with opt-in
+browser notifications), and a run exported as one HTML file that opens without forge-ui, with
+prompts, diffs and local paths left out unless you choose them.
+
+Offline (it loads three.js from a CDN for the 3D view) the same page works in 2D. It is opt-in.
+The `/forge` skill asks "Open forge-ui to watch this run? [y/N]" at the start of every new
+interactive run, or you pass it yourself:
+
+```sh
+bash scripts/forge-solo.sh "$RUN" --repo "$REPO" --dwarf sol --ui
+bash scripts/forge-parallel.sh plan "$PLAN" --repo "$REPO" --decompose-level medium --ui
+forge ui open [DIR]     # an existing run dir, or the run list
+```
+
+All runs share one detached server on `127.0.0.1:8765` (`FORGE_UI_PORT`) that exits after
+four idle hours (`FORGE_UI_IDLE_S`). A UI that cannot start never fails the run. It has no
+token: any local process can read the prompts and diffs of the runs it shows. See
+[references/ui.md](../references/ui.md) and [ui/README.md](../ui/README.md).
+
+To look around before your first run, point it at made-up runs (the ones in these pictures), from a git checkout:
+
+```sh
+python3 ui/tools/demo_runs.py /tmp/forge-demo
+(cd ui && python3 -m forge_ui --no-registry --root /tmp/forge-demo --open)
+```
+
+## `forge ui` command group
+
+| Command | Purpose |
+| --- | --- |
+| `open [DIR] [--no-browser] [--port N]` | start or reuse the shared forge-ui server; print `forge-ui: <url>` for the plan or solo run dir `DIR` (the run list without it) and open a browser the first time |
+| `status [--json]` | exit 0 and describe the server when it runs, 1 when not |
+| `stop` | stop the server |
+
+`FORGE_UI=off` makes `--ui` on a runner start nothing (it does not stop a running server or block `forge ui open`; use `forge ui stop`), `FORGE_UI_BROWSER=off` never opens a browser,
+`FORGE_UI_PORT` (8765) and `FORGE_UI_IDLE_S` (14400, `0` = never) tune the server. State and
+`server.log` are in `${XDG_STATE_HOME:-~/.local/state}/forge/ui/`.

package/docs/fractal.md

@@ -0,0 +1,181 @@
+# Fractal execution
+
+[← README](../README.md) · [All docs](README.md)
+
+Fractal is an optional implementation backend for both solo and decomposed runs. It uses
+the existing Forge dispatcher for Codex, Claude, OpenClaude, OpenCode and Antigravity.
+Each work step gets a fresh model invocation; preserved files and child results provide
+continuity when a parent resumes. Independent QA reviews the complete Forge task diff.
+
+`--decompose-level` plans top-level Forge tasks before execution. `--fractal` lets an
+implementer request nested children during execution. They can be used together, and
+solo runs can use Fractal without a top-level decomposition.
+
+## Install the optional runtime
+
+```bash
+forge fractal install --dry-run
+forge fractal install --yes --with-prerequisites
+forge fractal doctor --spec sol --spec opus --json
+```
+
+The managed runtime pins **Fractal 1.2.0** at revision
+`18793200c0d7e8cdb2db369ea3abe5647a1e15e4`, checks the source archive checksum,
+and includes the required `wiki` executable. It prefers an existing Python 3.12–3.14;
+with prerequisite installation selected, it can provision uv, Python 3.13 and tmux.
+tmux installation uses an existing Homebrew on macOS or apt on Debian/Ubuntu.
+The [installation reference](../references/fractal.md#installation-and-provenance) covers
+consent, supported bootstrap platforms, provenance and failure diagnostics.
+
+Installation never enables Fractal for a run, adds no command and leaves your shell startup
+files alone.
+Doctor checks the runtime and advertised harness capabilities without calling a provider.
+
+## Start and inspect a run
+
+Through the skill:
+
+```text
+/forge "add retry with exponential backoff to the HTTP client" --dwarf sol:high --fractal
+```
+
+Or prepare a solo run directory outside the product repository and invoke the runner:
+
+```bash
+FORGE_RUN="$HOME/.local/state/forge/examples/http-client"
+mkdir -p "$FORGE_RUN"
+printf '%s\n' 'Add bounded exponential backoff to the HTTP client and run its tests.' > "$FORGE_RUN/prompt.md"
+bash scripts/forge-solo.sh "$FORGE_RUN" --repo /absolute/path/to/product \
+  --dwarf sol:high --qa opus --fractal --fractal-concurrency 3
+```
+
+Choose a new run directory for unrelated work. Backend selection, routing pools and limits
+are stored with the run; resume and explicit retry retain them. For a prepared, approved
+decomposed plan, select the backend on `run`:
+
+```bash
+bash scripts/forge-parallel.sh run /absolute/path/to/plan --fractal --dry-run
+bash scripts/forge-parallel.sh run /absolute/path/to/plan --fractal
+```
+
+Dry runs show resolved model pools, limits and proposed workspaces without installation
+or provider calls. When a selected runtime is unavailable, interactive runs offer
+installation; unattended runs return an actionable error instead of changing backends.
+
+Discover the managed run ID, then inspect it from another terminal:
+
+```bash
+forge fractal runs --repo /absolute/path/to/product --json
+forge fractal open                         # live runs index
+forge fractal status RUN_ID --json
+forge fractal tree RUN_ID --json
+forge fractal logs RUN_ID --follow
+forge fractal report RUN_ID --html /absolute/path/to/report.html
+```
+
+`RUN_ID` is the `run-…` identifier returned by `runs`, not the solo directory or plan name.
+The [run inspector](../references/fractal-dashboard.md) opens on progress and problems, then lets
+readers inspect task QA/history or node decisions, logs and changes. It refreshes about every
+two seconds without replacing the workspace; search, selection, focus and scrolling remain in
+place. “Pause live updates” affects the browser only. Browser access is read-only, bound to
+`127.0.0.1` with an ephemeral access token. Closing its server does not stop execution.
+Portable HTML embeds complete captured history and logs, works offline and needs no Fractal
+runtime to read.
+
+## Automatic recursive decomposition
+
+`--fractal` permits workers to request children. To require a planning decision before
+every eligible node implements, use `--fractal-auto-decompose`:
+
+```text
+/forge "<goal>" --dwarf luna:high --qa sol:high --fractal-auto-decompose --fractal-planner sol:xhigh --fractal-depth 3 --fractal-nodes 24
+```
+
+After the top-level Forge approval, the planner automatically splits useful work or
+records why it is atomic. Children repeat this decision within the approved ownership
+and frozen limits. `--fractal-planner` selects a separate decision model; when omitted,
+Forge reuses the configured top-level planner, then the task's initial root model.
+Decisions use disposable snapshots, persist for resume, and appear in tree/status/HTML
+reports. Ordinary `--fractal` and existing runs retain their current behavior. Start a
+new run to change policy or planner. See the [full decision contract](../references/fractal.md#automatic-decomposition-decisions).
+
+## Bounds, recovery and acceptance
+
+Defaults per Forge task are two nesting levels below implementation, three unsettled
+direct children per node, twelve lifetime nodes, six iterations per node per attempt,
+and a 45-minute attempt deadline excluding explicit pauses. Three model slots are shared
+across the whole Forge run, including QA. `--max-parallel` bounds top-level task pipelines;
+`--fractal-concurrency` bounds model invocations across their nested trees.
+
+Child difficulty selects a frozen `--dwarf-low`, `--dwarf-medium` or `--dwarf-high` pool,
+falling back to the configured general dwarf, then the parent. Dependencies and owned
+paths constrain admission; overlapping ownership is serialized. Fractal never implies
+`--yolo-dwarf`. Costs are observational; unavailable usage stays unknown and dollar-cap
+requests are rejected.
+
+```bash
+forge fractal pause RUN_ID
+forge fractal resume RUN_ID
+forge fractal stop RUN_ID
+```
+
+Pause and stop preserve work and diagnostics. Run-level resume recovers recorded execution
+and the Forge pipeline without repeating accepted stages. Use explicit runner retry for
+a new attempt, retaining work and the original Forge QA baseline. Controls also accept
+`--task TASK_ID` and `--task TASK_ID --node NODE_ID`; those IDs come from `tree` output.
+
+Managed data lives in `${XDG_STATE_HOME:-$HOME/.local/state}/forge/fractal/`. Solo execution
+uses an isolated snapshot and imports changes only after checking source drift, preserving
+staging and leaving changes uncommitted. Decomposed candidates return to Forge's existing
+review/integration pipeline. **Fractal completion is not Forge acceptance**: QA, repository
+verification and authorization to update the user's branch remain distinct.
+
+See the [full Fractal reference](../references/fractal.md) for limits, child requests and
+recovery details, and [verification evidence](../tests/fractal-verification.md) for the tested
+platforms and browser checks. No paid-provider or speed/cost claim follows from fake-CLI tests.
+
+## `forge fractal` command group
+
+Run it as `forge fractal`, or `forge fractal` from a git checkout.
+This group manages Fractal runs; it does not replace the `/forge` skill or runner scripts.
+
+| Command | Purpose |
+| --- | --- |
+| `install [--dry-run] [--yes] [--with-prerequisites]` | preview or install the isolated pinned runtime |
+| `doctor [--spec SPEC] [--json]` | check runtime/hooks/tmux and optional repeated harness specs without provider calls |
+| `runs [--repo DIR] [--json] [--html PATH]` | discover managed runs, optionally filtered by repository |
+| `status\|tree\|activity RUN_ID` | inspect progress, hierarchy and history |
+| `logs\|costs\|messages\|config RUN_ID` | inspect diagnostics, observed accounting, radio traffic and effective settings |
+| `pause\|resume\|stop RUN_ID` | request a control and record its observed state |
+| `open [RUN_ID] [--port PORT]` | open the read-only live dashboard or runs index |
+| `report RUN_ID [--html PATH]` | capture a self-contained HTML report; default filename is `RUN_ID.html` |
+
+Inspection commands accept `--task TASK_ID`, `--node NODE_ID`, `--json`, `--html PATH`,
+`--offset N` and `--limit N` (1–1000). They currently return a common JSON run projection;
+the command names do not imply separate output schemas. `logs --follow` follows changes.
+HTML exports capture full history and logs. Controls require an explicit run ID, and a
+node control also requires its task ID; they never guess the latest run. Use each command's
+`--help` for its accepted options. Installation is also available through
+`bash scripts/forge-install-fractal.sh`.
+
+Fractal adds a managed workspace alongside the runner artifacts described here:
+
+```text
+${XDG_STATE_HOME:-$HOME/.local/state}/forge/fractal/
+  runtime/                       isolated pinned Fractal and wiki environment
+  provenance.json                installed versions and source checksum
+  installs/                      installation attempts and diagnostics
+  runs/<run-id>/run.json          effective routing, limits and runner binding
+  runs/<run-id>/controls/         requested controls and observed results
+  runs/<run-id>/tasks/<task-id>/
+    request.json / state.json     task request and execution checkpoint
+    initialization.json         control repository and Fractal ledger provenance
+    control/                     Fractal metadata, separate from product changes
+    nodes/<node-id>/product/      isolated product candidate
+    nodes/<node-id>/steps/        fresh dispatcher attempts and raw logs
+    outcome.json                 captured Forge acceptance and verification
+```
+
+The original solo/plan directory stores `fractal-selection.json`; decomposed plans also
+store `fractal-routing.json`. Prefer `forge fractal runs`, `tree`, `logs` and `report`
+to direct ledger access. Inspection and stop never delete managed work.