@giamme/forge 0.0.0-stage → 0.8.0

package/references/memory.md

@@ -0,0 +1,228 @@
+# Project memory
+
+How forge remembers what it learned about a repository across runs: the `FORGE_LEARNING`
+grammar, what gets promoted into a prompt and what only reaches the ledger, and how memory
+stays small and true as the code moves under it.
+
+Read this when memory looks empty, looks wrong, or has grown past its budget.
+
+## Contents
+
+- [Why two files](#why-two-files)
+- [Committing, ignoring, disabling](#committing-ignoring-disabling)
+- [The sentinel](#the-sentinel)
+- [Promotion](#promotion)
+- [Dedup, and the limits of it](#dedup-and-the-limits-of-it)
+- [Staleness and the cap](#staleness-and-the-cap)
+- [Injection slices](#injection-slices)
+- [The diff exclusion](#the-diff-exclusion)
+- [Spend accounting](#spend-accounting)
+- [Commands](#commands)
+- [Failure modes](#failure-modes)
+
+## Why two files
+
+```
+.forge/memory.md     curated, hard-capped, injected into every prompt
+.forge/ledger.tsv    append-only, one row per dispatch, NEVER injected
+```
+
+Injected context is paid for on every dispatch of every future run — with a decomposed run
+that is 2N prompts, forever. So the two things a memory has to do pull in opposite
+directions: remembering everything makes it big, and staying small means forgetting.
+
+Splitting them resolves that. The ledger is unbounded and costs nothing, because nothing
+reads it unless asked; it is what recurrence is counted from and what answers "has this been
+tried here before". Only `memory.md` is in prompts, and it is capped hard.
+
+Never inline the ledger into a prompt. That would undo the whole arrangement.
+
+Both live in the repo so the memory travels with it, and both are written by forge but
+committed by the user — forge does not commit on anyone's behalf.
+
+## Committing, ignoring, disabling
+
+`.forge/` appears untracked after the first run. Three coherent choices:
+
+| Intent | Action |
+|---|---|
+| share memory with the team | commit `.forge/` |
+| keep it to this machine | `echo '.forge/' >> .gitignore` |
+| no memory at all | `--no-memory` or `FORGE_MEMORY=off` |
+
+Gitignoring does **not** disable anything: an ignored `.forge/` is still written and still
+injected into every prompt. Only the third row turns the feature off.
+
+**The two files must share a fate.** Because `memory.md` is rebuilt from `ledger.tsv` on
+every write, committing the memory while ignoring the ledger destroys the shared facts the
+first time anyone runs forge on a fresh clone — the rebuild regenerates `memory.md` from that
+machine's own short ledger, and nothing warns:
+
+```
+A commits memory.md only:   - pytest -q runs the suite
+                            - src/a.py is generated [src/a.py]
+B clones, runs forge once:  - b learned something new     <- A's facts gone
+```
+
+Committing both means `ledger.tsv` grows a line per dispatch and shows up in diffs. That is
+the price of the recurrence counting; the alternative is memory that cannot tell a one-off
+from a pattern.
+
+For a repo you contribute to but do not own, ignore it — a PR carrying forge's notes to
+itself is noise to a reviewer who does not use forge.
+
+## The sentinel
+
+Extraction happens in-band, in the final message of the role that just did the work:
+
+```
+FORGE_LEARNING: verify | pytest -q runs the suite; make test also lints and is 4x slower
+FORGE_LEARNING: trap | test_api.py::test_timeout is flaky under -n auto [tests/test_api.py]
+FORGE_LEARNING: finding | route added without updating openapi.yaml [src/routes]
+```
+
+`<category> | <text> [optional anchor]`. Categories:
+
+| Category | Is |
+|---|---|
+| `verify` | how this project is actually built, tested or checked |
+| `trap` | a landmine: a flaky test, a generated file, a sharp edge |
+| `finding` | a *mistake pattern* likely to recur — emitted by qa, not a description of one bug |
+
+This costs no extra dispatch, which is the reason it works at all: a separate "librarian"
+model would have to re-derive from a transcript what the working model already knew. The
+role that hit the landmine is the one that writes it down.
+
+`forge-memory.sh note <role>` produces the instruction. It is deliberately biased toward
+silence — "most runs teach nothing durable; emitting no line is the normal, correct
+outcome" — because a false fact is worse than a missing one. A missing fact costs one
+rediscovery; a false one is injected into every future prompt until someone notices.
+Measured behaviour matches: on a trivial task with nothing to learn, models emit nothing;
+on a task with a real trap, they emit it.
+
+## Promotion
+
+| Category | Enters `memory.md` |
+|---|---|
+| `verify`, `trap` | on first sighting — these are facts, true the first time |
+| `finding` | only after **two distinct runs** |
+
+Everything reaches the ledger immediately regardless; promotion governs only what gets
+injected. The threshold is the main guard against a junk drawer: one QA noticing one bug is
+an incident, and putting it in every future prompt would be noise. Two separate runs finding
+the same thing is a pattern worth telling the next dwarf about.
+
+Recurrence counts **distinct runs**, not lines — one run emitting the same learning twice is
+still one occurrence. Promoted findings display their count (`3x:`), which is also how a
+human spots a systemic problem worth fixing properly.
+
+## Dedup, and the limits of it
+
+The key is the text lowercased with every run of non-alphanumerics collapsed to one space.
+So `Route added without updating openapi.yaml` and `route added, without updating
+openapi.yaml!` are the same key; a genuinely different phrasing is not.
+
+This is exact matching, not fuzzy, and pretending otherwise would be worse than stating it.
+What makes it work in practice is a feedback loop rather than cleverness: memory is *in the
+prompt*, and `note` asks explicitly to reuse the wording of anything already listed. A
+reviewer that can see `2x: route added without updating openapi.yaml` tends to re-emit that
+line rather than invent a synonym, so repeats converge on one phrasing.
+
+`memory.md` is rebuilt from the whole ledger on every write rather than edited in place.
+Rebuilding is idempotent and order-independent, so a crashed or concurrent run cannot leave
+memory half-updated — at worst the ledger is one row short.
+
+## Staleness and the cap
+
+An entry ending in `[path]` is anchored. When that path stops existing the entry is dropped:
+the code it describes is gone, so the fact is at best useless and at worst actively
+misleading. This is what keeps memory true as the codebase moves, and it is why `note` asks
+for an anchor wherever one makes sense.
+
+Caps are 40 lines and 4 KB (`FORGE_MEMORY_MAX_LINES`, `FORGE_MEMORY_MAX_BYTES`). Over cap,
+entries are trimmed from the bottom — lowest recurrence count first, then least recent.
+A single entry is clamped to 180 characters (`FORGE_MEMORY_MAX_FACT_CHARS`), truncated at a
+word boundary with its anchor preserved, so one discursive model cannot spend the whole
+budget on one line.
+
+## Injection slices
+
+| Role | Gets |
+|---|---|
+| planner | Verify + Known traps + Recurring findings |
+| dwarf | Verify + Known traps + Recurring findings |
+| qa | Known traps + Recurring findings |
+
+QA is not told the build command because it is not building anything. It *is* told the
+recurring findings, so it can notice this is the fourth time the same bug shipped, and the
+traps, so it does not report a known-generated file as a defect.
+
+## The diff exclusion
+
+`.forge/` must be excluded from every diff capture:
+
+```bash
+git diff -- . ':(exclude).forge'
+git add -A -- . ':(exclude).forge' && git diff --cached -- . ':(exclude).forge'
+```
+
+Two distinct failures otherwise, both quiet:
+
+- memory is rewritten in the working tree at the end of every run, so the *next* run's
+  capture hands it to qa as if a dwarf had written it — an unrelated file in the diff, which
+  a good reviewer will correctly flag as scope creep;
+- if `.forge/` ever entered a task's `files`, every task would overlap every other task and
+  the wave planner would serialize the entire run while reporting it as deferrals.
+
+## Spend accounting
+
+`forge-dispatch.sh` times every dispatch and `record` stores it, so the ledger answers what
+forge has cost this repo without any new bookkeeping and without a byte of prompt context:
+
+```bash
+forge-memory.sh spend <repo> [--run <run-id>]
+```
+
+Wall-clock and dispatch counts grouped by model and by role — **not** tokens and not money.
+The five CLIs expose usage differently or not at all, so a token number would be a number
+forge cannot actually measure, which is worse than none.
+
+Two things the output states rather than leaves the reader to work out: durations *sum*
+concurrent work, so a `--max-parallel 3` run reports more model time than it took in
+wall-clock; and dispatches recorded before `duration_s` existed are counted but not timed.
+
+`duration_s` is the ledger's tenth column, appended at the end on purpose. A ledger written
+by an older forge — and possibly already committed and shared — has nine fields, and awk
+yields `""` for the missing one instead of shifting every column, so old rows stay readable.
+
+Counting is by dispatch, not by row: one dispatch that emits two learnings writes two rows,
+and every row from a single dispatch shares its timestamp, which is what the counter keys on.
+
+## Commands
+
+```bash
+forge-memory.sh inject <repo> <planner|dwarf|qa>   # block to prepend; empty if no memory
+forge-memory.sh note <planner|dwarf|qa>            # the instruction to append
+forge-memory.sh record <repo> --last <file> --role <r> [--run-id X] [--task T]
+                              [--model M] [--verdict V] [--duration S]
+forge-memory.sh show <repo>
+forge-memory.sh prune <repo>                       # re-apply staleness and cap now
+forge-memory.sh spend <repo> [--run <run-id>]      # time and dispatch counts
+```
+
+`--no-memory`, or `FORGE_MEMORY=off` in the environment, disables all of it: nothing is
+injected, nothing is recorded, and no `.forge/` is created.
+
+## Failure modes
+
+| Symptom | Cause |
+|---|---|
+| memory stays empty | nothing durable was learned — the common and correct case. Check the ledger: rows with `-` categories mean dispatches ran and emitted nothing |
+| a fact you wanted is missing | it was a `finding` seen once; it is in the ledger and will promote on its second run |
+| the same fact appears twice, worded differently | dedup is exact-after-normalization; delete the weaker line from `memory.md`, or let the cap evict it |
+| a fact is wrong and keeps coming back | it is in the ledger. Editing `memory.md` alone will not hold — the next rebuild regenerates from the ledger; remove the ledger rows |
+| memory vanished after a refactor | its entries were anchored to paths that no longer exist and were dropped as stale. Working as intended |
+| `.forge/` shows up in a review | a diff capture is missing the exclude pathspec |
+| memory in a worktree is stale | inject reads the **main repo**, not the worktree; on a repo's first run `.forge/` is not committed, so a worktree branched from the base commit does not have it |
+| a teammate's clone lost every shared fact | `memory.md` was committed but `ledger.tsv` was not; the first `record` there rebuilt memory from an empty ledger. Commit both, or neither |
+| `.forge/` keeps appearing in `git status` | expected — forge never commits it. Commit it to share, or gitignore it to keep it local |

package/references/planning.md

@@ -0,0 +1,42 @@
+## Planning
+
+Fractal selection applies to the later implementation stage. It does not turn a planner
+dispatch or `forge-parallel.sh plan` into nested execution, install a runtime during
+planning, or bypass the task/model approval table. Pass `--fractal` or `--no-fractal` to
+the eventual solo runner or decomposed `run`. See [Fractal](fractal.md).
+
+For automatic recursive decisions during execution, use `--fractal-auto-decompose`.
+Its `--fractal-planner` selects the per-node decision model, independently of the
+top-level `--planner` that designs the whole run. Without an override it reuses that
+planner when configured, then each task's initial root model. Child planning must
+preserve the approved interfaces and ownership established here.
+
+By default **you** plan: before dispatching, decide the approach and put it in the prompt,
+so the dwarf builds the agreed thing rather than inventing a shape nobody has seen. In a
+decomposed run that matters more, because the capsule prevents two dwarves from touching
+one *file* but nothing stops them inventing incompatible *interfaces* at a seam they share.
+
+`--planner <spec>` hands that stage to a named model instead — one dispatch for the whole
+run, never one per task. A single planner is the point: one 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.
+
+Offer optional installation once before a direct planner dispatch with
+`bash <skill_dir>/scripts/forge-install-ripwire.sh`. Propagate `FORGE_RIPWIRE=off`
+when the user opted out. Supply `--ripwire-query-file` when requirements are separate
+from the assembled planner prompt; see [Ripwire context](ripwire.md).
+
+```bash
+bash <skill_dir>/scripts/forge-dispatch.sh planner <spec> \
+  --repo "$REPO" --run-dir "$FORGE_RUN" --prompt-file "$FORGE_RUN/planner.prompt"
+```
+
+The planner is instructed to read only and uses QA permission flags. These flags alone do not enforce filesystem immutability.
+Ask it for the approach only: in a decomposed run, `tasks.tsv` rows plus a few lines of
+approach per task; in a single-task run, just the approach. Ask too for tasks small enough to
+pass on a first attempt, each ending its prompt with an `## Acceptance criteria` section of
+checks the reviewer can verify; see [task size](decompose.md#task-size-and-acceptance-criteria). Write each task's approach to
+`tasks/<id>/approach.md`, where the runner picks it up for both the dwarf and qa.
+
+Show the approach before dispatching and let the user change it. That gate is the last
+moment the plan is free; after it, changing the plan costs a whole run.

package/references/ripwire.md

@@ -0,0 +1,47 @@
+## Optional Ripwire context
+
+Forge automatically uses Ripwire **0.4.0** when found on `PATH`, then in
+`~/.local/bin`. Other versions are preserved but skipped until compatibility is verified.
+All six harnesses use the same preparation step. No provider calls are needed for it.
+
+Use `--no-ripwire` on dispatch, solo, or parallel `plan`, `run`, and `retry`, or set
+`export FORGE_RIPWIRE=off` in your shell configuration. Opt-out is resolved before
+probing or offering installation. Parallel plans remember opt-out in `no_ripwire`
+for later resumes and retries; remove that marker to enable it again.
+
+Forge setup and solo/parallel run entrypoints offer installation once before agents
+start. The helper shows v0.4.0 and `~/.local/bin/ripwire`, then asks
+“Ripwire is missing. Install it now? [Y/n]”. Enter accepts; no or EOF continues.
+It reads the controlling terminal separately from task stdin. Without a terminal it
+prints the helper command and continues. Dispatch itself never prompts, so background
+workers cannot wait for installation input.
+
+```bash
+bash <skill_dir>/scripts/forge-install-ripwire.sh           # offer installation
+bash <skill_dir>/scripts/forge-install-ripwire.sh --dry-run # preview, no downloads
+bash <skill_dir>/scripts/forge-install-ripwire.sh --yes     # explicit unattended consent
+```
+
+The helper pins the [upstream v0.4.0 installer](https://github.com/redhat-et/ripwire/blob/v0.4.0/scripts/install.sh)
+and its SHA-256, retains upstream archive checksum and binary version checks, and sets
+`RIPWIRE_NO_ACTIVATE=1`. Existing installations are preserved. Failed installation
+reports its cause; Forge runners continue without requiring Ripwire.
+
+Planner/dwarf use `--for` in their own repository or worktree. Runners pass the
+requirements via `--ripwire-query-file`; direct dispatch defaults to the original
+prompt. Only this search excerpt is limited to 2,048 characters. QA uses
+`--pr-context=<review-base>` against the disposable review snapshot; direct QA without
+a baseline uses task context. See the [pinned command reference](https://github.com/redhat-et/ripwire/blob/v0.4.0/docs/COMMANDS.md).
+
+The full prompt remains intact, followed by one marked advisory section. Requirements,
+ownership, retry findings and the actual diff remain authoritative; suggested tests
+supplement required verification. Each attempt prepares fresh context with `--no-cache`,
+excluding `.forge` and Git internal paths. Temporary preparation files live with the
+external attempt artifacts. Preparation has a shared 30-second deadline, a 4,096 estimated
+token budget and a 16 KiB subprocess output ceiling. Failed, empty, oversized, incompatible
+or timed-out results are skipped with a reason; timeout cleanup kills the process group.
+
+Each `attempts/<role>-*/ripwire.json` records the command, binary version, repository,
+baseline, duration, status and delivered section (or skip reason). Dry runs and preflight
+skip preparation. Doctor reports availability without installation. Native Codex review
+skips context because its dispatch cannot accept an additional prompt.

package/references/runtime.md

@@ -0,0 +1,64 @@
+# Runtime helper decision
+
+The approved optimization plan permits Python 3 standard-library helpers while retaining
+shell entrypoints and all existing model, retry and integration boundaries.
+
+A complete Python runner would simplify process ownership, but would also rewrite artifact
+capture, retry, merge, permission and setup behavior. The chosen design keeps those shell
+contracts and adds focused helpers: `forge-prompt.py` assembles context without summarizing
+requirements, `forge-schedule.py` coordinates eligible tasks (including opt-in in-run retries and
+infrastructure pauses), `forge-runtime.py` handles capability caching, attempt telemetry and
+infrastructure-failure classification, `forge-contract.py` owns the shared QA/dwarf prompt
+contract and the severity gate, `forge-guard.py` the implementer guards, and
+`forge-verify-coverage.py` the verify-coverage warnings. `forge-metrics.sh` connects pipeline timing to
+existing shell stages. Python unit tests retain the repository's standard-library unittest
+convention; no new dependency manager or test framework is required.
+
+Tasks execute through `_task` and merge through `_merge`. The coordinator pins baselines
+before launching tasks, excludes overlapping active ownership paths, and serializes merges.
+Each merge still checks dependency status, reviewed commit, source fingerprint and accepted
+integration revision. A plan lock spans run/retry/integrate operations. Saved passing work
+can resume without a new dispatch; ordinary failed and interrupted work requires explicit
+retry (or an opt-in `run --retry-failed N`), while tasks paused on an infrastructure failure
+resume on the next `run` and an unjudged review re-runs QA only. Fractal has the additional
+recovery checkpoints described below.
+
+Review repositories import self-contained tree object packs and create two commits before
+checking out the final tree. No alternates or source repository access is required afterward.
+Both exact tree comparisons and the existing fingerprint checks remain mandatory.
+
+Telemetry is independent of project memory. Dispatch and pipeline attempt records are nested;
+their total durations must not be added together. Unsupported usage remains unknown. See
+[the evaluation](../tests/benchmark-2026-09-07.md) for observed improvements and regressions.
+
+## Optional Fractal adapter decision
+
+Fractal adds a Python adapter around the existing shell pipeline instead of replacing
+Forge's dispatcher, model registry, QA or integration rules. This keeps provider effort,
+permission and attempt-record behavior in one place. The isolated runtime pins Fractal
+1.2.0 and registers `ForgeAgent` through upstream `agents.py`; no Fractal fork is required.
+Ordinary execution and inspection do not require that runtime to be installed.
+
+`forge-fractal-options.sh` records the per-run choice and selects the bridge only when
+enabled. `forge_fractal/selection.py` freezes routing and limits; `execution.py` manages
+bounded children, shared model slots, process ownership and candidate import checks;
+`pipeline.py` preserves Forge checkpoints for resume and explicit retry. Work steps use
+fresh dispatcher invocations rather than provider conversation continuation.
+
+Each task separates a Fractal control repository from product snapshot repositories.
+That separation prevents wiki/configuration/ledger initialization from entering the product
+diff. Solo imports check source fingerprints and preserve the user's index. Decomposed
+candidates return to the task's existing pinned review and integration boundary. Explicit
+retry retains prior work and the original Forge QA baseline while recording a new attempt.
+
+Runtime and durable run records live under
+`${XDG_STATE_HOME:-$HOME/.local/state}/forge/fractal/`, outside the product repository.
+A single task coordinator and a run-wide invocation limiter bound nested work and QA;
+setup and shutdown count toward the task deadline, explicit pauses do not. Fractal
+execution status, Forge acceptance and repository verification remain separate records.
+
+`inspection.py` reads curated managed artifacts and the pinned SQLite ledger without
+constructing lifecycle-reconciling Fractal nodes or marking messages read. The browser
+server is read-only and localhost-bound; portable HTML embeds captured data and assets.
+Unsupported tokens/cost/tool details stay unknown, and the bridge rejects dollar caps.
+See [operating instructions](fractal.md) and [verification evidence](../tests/fractal-verification.md).

package/references/solo.md

@@ -0,0 +1,113 @@
+# Solo runs
+
+Create a run directory outside the repository, write the full implementation requirements to
+`prompt.md`, and optionally add `goal.txt` and an approach file. State the selected models,
+efforts, harnesses and any explicit bypass flags before dispatch.
+
+```bash
+bash <skill_dir>/scripts/forge-solo.sh "$FORGE_RUN" --repo "$REPO" \
+  --dwarf <spec> [--qa <spec>] [--approach <file>] \
+  [--yolo-dwarf] [--yolo-qa] [--timeout <seconds>] [--no-memory] [--dry-run] \
+  [--fractal | --no-fractal] [--fractal-concurrency <n>] [--fractal-deadline <seconds>] \
+  [--ui | --no-ui]
+```
+
+`--ui` opens the run in [forge-ui](ui.md) before the first dispatch and prints a
+`forge-ui: <url>` line to relay. It is fail-open (a UI that cannot start never changes the
+exit code), is not remembered, and is ignored with `--dry-run`. Ask once for a new run; do
+not ask on a re-run or `--retry`.
+
+Besides the artifacts above, the runner writes these for forge-ui and for you:
+
+| File | Meaning |
+|---|---|
+| `status` | `RUNNING` while it works, then this invocation's outcome: a verdict word (`PASS`, `FAIL`, `UNKNOWN`, `NOCHANGES`, `INVALIDATED`) or `TIMEOUT`, `INFRA`, `INTERRUPTED`, `ERROR` |
+| `dwarf.spec`, `qa.spec` | the specs this run was given, one line each |
+| `attempts.tsv` | one row per invocation: epoch, attempt number, status, infrastructure class, dwarf spec |
+
+Both roles receive offline preflight before implementation starts. The runner records a
+starting tree with a private index, then captures the net filesystem changes since that
+snapshot, including staged, unstaged, binary and untracked files. It does not alter the
+user's staging choices. `existing.diff` distinguishes pre-existing work from `changes.diff`.
+Ignored files and Forge memory are outside the implementation diff. Concurrent writers
+cannot be attributed reliably: keep one implementer per source tree.
+
+QA receives the full implementation input, approach and actual diff in a disposable Git
+repository. Source and review fingerprints are checked afterwards; mutations invalidate QA.
+This detects mutations; it is not an operating-system security sandbox for unrestricted Bash.
+
+Read `dwarf.last`, `qa.last`, `changes.diff` and `verdict`. Preserve CONFIRMED/PLAUSIBLE labels
+when relaying findings. Report scope drift and unsupported implementation claims. Do not
+automatically retry. In ordinary execution the run is one implementation followed by
+one review; Fractal may use multiple bounded work steps before that independent review.
+
+Statuses: PASS, FAIL, UNKNOWN, NOCHANGES, INVALIDATED. Exit codes: 0 completed review
+(inspect verdict), 2 usage, 3 precondition, 4 dispatch failure, 5 no changes or invalidated
+review, 7 timeout, 8 infrastructure failure (quota, auth, rate limit, network, empty output:
+nothing was judged — fix the cause and run again; a dwarf that returns nothing *and* changes
+nothing is reported as 8, not 5). The default dispatch timeout is 2700 seconds, scaled up for
+`xhigh`/`max` effort (so the default QA/planner effort gets 3600), overridable per model in the
+registry; 0 disables that dispatch timeout, but an enabled Fractal task still has its own attempt
+deadline. See [dispatch timeouts](../README.md#scriptsforge-dispatchsh).
+
+The dwarf prompt carries implementer rules (no commits, no background processes, finish every
+measurement before the last message). forge records what it observes: if the dwarf committed
+anyway the run still reviews its changes, says so, and prints `git reset --soft <old HEAD>` —
+it never resets anything itself; leftover processes (stopped) and promises of later work appear
+under "implementer guard notes". The QA prompt asks for `P0..P3`-labelled findings; solo has no
+threshold gate, so any CONFIRMED finding still fails.
+
+`--native-review` is an explicit Codex-only alternative: native review cannot accept the
+custom requirements prompt or verdict instruction. Its result is informational and UNKNOWN;
+it cannot establish requirements coverage. The disposable repository supplies the recorded
+baseline via `--review-base`.
+
+`--fail-first` runs the change's new tests against the code without its non-test changes
+first and gives the reviewer the result (`failfirst.json`); see
+[fail-first evidence](decompose.md#fail-first-evidence-opt-in).
+
+Changes remain in the source working tree. Forge does not commit or integrate solo work.
+
+Solo defaults to `--output summary`; `--output full` includes raw CLI output. Read the two
+`.last` files once, then inspect logs only as needed. `forge-dispatch.sh report <run-dir>`
+reports immutable attempt metrics and native usage independently of project memory. Shared
+context is assembled from original requirements and approach; QA does not embed dwarf
+execution instructions. Review snapshots use self-contained object packs and one checkout.
+
+Optional [Ripwire context](ripwire.md) is enabled by default. Use `--no-ripwire`
+or `FORGE_RIPWIRE=off` to disable preparation and installation offers.
+
+## Fractal execution and recovery
+
+[Fractal](fractal.md) is separately opt-in. It starts from the complete snapshot
+above, runs in a managed isolated repository, and imports the candidate only after
+checking source drift. Resume preserves that snapshot. `--retry` starts an explicit
+new Fractal attempt using preserved work and the original QA baseline. A saved PASS
+checkpoint is reused only while its source fingerprint remains unchanged.
+
+Ask `Use Fractal for this run? [y/N]` once in the conversational workflow and pass
+`--fractal` or `--no-fractal` explicitly to the runner. A direct interactive runner
+asks if neither flag is given; unattended execution defaults off. Installation is a
+separate choice. Do not ask again when resuming or retrying a recorded run.
+
+```bash
+# First run, with optional child routing; the run directory already contains prompt.md.
+bash <skill_dir>/scripts/forge-solo.sh "$FORGE_RUN" --repo "$REPO" \
+  --dwarf sol:high --qa opus --dwarf-low luna:medium --fractal
+
+# Discover the managed run ID, then inspect or resume from another terminal.
+<skill_dir>/forge fractal runs --repo "$REPO" --json
+<skill_dir>/forge fractal tree RUN_ID --json
+<skill_dir>/forge fractal resume RUN_ID
+
+# Start a new attempt only when explicitly requested, using the same frozen settings.
+bash <skill_dir>/scripts/forge-solo.sh "$FORGE_RUN" --repo "$REPO" \
+  --dwarf sol:high --qa opus --dwarf-low luna:medium --fractal --retry
+```
+
+The solo directory's `fractal-selection.json` also records the managed run ID.
+Per-node workspaces, preserved responses and raw attempts are under the managed run;
+the solo directory still supplies `changes.diff`, `qa.last` and `verdict` for delivery.
+Parent invocations yield while their children run. QA sees their combined task diff.
+Use [Fractal controls and reports](fractal.md#inspection-and-controls) to inspect partial
+work; a completed execution node does not imply a PASS verdict or repository verification.

package/references/ui.md

@@ -0,0 +1,112 @@
+# forge-ui
+
+forge-ui is a read-only local web page that shows a forge run live: a decomposed plan or a
+solo run. It is opt-in per run. The orchestrator asks "Open forge-ui to watch this run?
+[y/N]" once at the start of every new interactive run and passes the answer as `--ui` or
+`--no-ui`. Nothing about the run depends on it: a UI that cannot start prints a note and the
+run goes on, with the same exit code.
+
+## What it shows
+
+- **Map of every run:** every run forge has registered, one district per repo and one block per
+  run with a lamp per task, filterable by state, repo, kind, model, age and review verdict.
+- **Run cloud:** every run at once, full screen in 3D, grouped by project, in one of five layouts
+  (helix, sphere, galaxy, timeline, constellation) as blocks or orbs. Filters narrow it to exactly
+  the runs wanted (project, state, difficulty, tasks per run, models and more), and runs can be
+  dragged anywhere; where they were dropped is remembered in that browser.
+- **Files heatmap:** which tasks planned, changed, drifted into or conflicted on which files,
+  with same-wave overlaps marked, and each file's diff a click away.
+- **Model leaderboard:** first-attempt pass rates with confidence intervals, retries, escalations,
+  timeouts, time and tokens per implementer, and verdicts, findings and shadow agreement per
+  reviewer, filterable by project, difficulty and period.
+- **Diffs with findings in place:** any task diff, the exact diff each reviewer read, or a final
+  review's combined diff, with every P0–P3 finding shown under the line it names.
+- **Fractal child tasks:** the tree a Fractal task was split into, in the inspector and above
+  the opened task in 3D, each node with its decision, cost, output and candidate diff.
+- **Export a run:** one HTML file to share that opens without forge-ui; prompts, diffs, reports
+  and local paths stay out unless chosen.
+- **Quick jump and notifications:** Ctrl K (⌘K) or `/` searches every run, task, project and
+  model; the bell tells you when a run finishes or fails, a task fails or a final review gives its
+  verdict, and can raise browser notifications while the tab is in the background.
+- **Plan run:** tasks in their planned waves with dependency cables, then the finish line:
+  integration, verification and the whole-run final review, each a node with its status. The
+  *Execution* view shows the same run on wall-clock time, one block per attempt in the lane it
+  ran in, with projected blocks for what has not started and a strip of busy slots against
+  `--max-parallel`.
+- **Opening a node** shows its attempts, dwarves and reviews, and an inspector with the prompt
+  that launched each one, the model, timings by phase, tokens, verdicts and the P0–P3 findings
+  of every review (the final review's included).
+- **Solo run:** one task: its attempts, specs, prompts and the final messages.
+- It refreshes every two seconds while something runs (five otherwise) while the tab is
+  visible, so a run can be watched as it goes. A run can also be replayed from its record.
+
+The 3D view loads three.js from cdn.jsdelivr.net when first used; offline, the page shows the
+same run in 2D. The full page description is in [ui/README.md](../ui/README.md).
+
+## Commands
+
+```bash
+bash <skill_dir>/scripts/forge-parallel.sh plan "$PLAN" --repo "$REPO" ... --ui
+bash <skill_dir>/scripts/forge-solo.sh "$FORGE_RUN" --repo "$REPO" --dwarf <spec> --ui
+<skill_dir>/forge ui open [DIR] [--no-browser] [--port N]
+<skill_dir>/forge ui status [--json]
+<skill_dir>/forge ui stop
+```
+
+- `--ui` starts (or reuses) the server for this run and prints a `forge-ui: <url>` line;
+  relay that URL to the user. `--no-ui` is the explicit "no". `plan --ui` prints the link
+  under the task table. `forge-solo.sh --ui` is ignored with `--dry-run`.
+- `forge ui open DIR` does the same for an existing plan or solo run dir; without `DIR` it
+  opens the run list. `--no-browser` prints the link only. The browser opens the first time a
+  run is opened, not on every `open`.
+- `forge ui status` exits 0 when the server runs and 1 when not; `--json` prints
+  `{"running": ...}` with pid, port, url, version, build, started and log.
+- `forge ui stop` stops it; it exits 0 when nothing was running.
+
+| Variable | Meaning |
+|---|---|
+| `FORGE_UI=off` | `--ui` on a runner starts nothing (a note is printed); `forge ui open` still starts the server |
+| `FORGE_UI_BROWSER=off` | print the link, never open a browser |
+| `FORGE_UI_PORT` | preferred port, default `8765`; `--port` wins; a taken port falls back to a free one |
+| `FORGE_UI_IDLE_S` | idle seconds before the server exits, default `14400`; `0` never |
+| `FORGE_RUN_REGISTRY=off` | runs stop registering themselves (`--ui` and `forge ui open DIR` still register the run they open) |
+
+## One shared server
+
+All runs share one detached server on `127.0.0.1`. A second `forge ui open` reuses it.
+It is replaced when it runs old code: `open` compares the server's build (a hash of the
+`forge_ui` Python files, reported by `/api/health`) with the checkout's, and when they differ,
+or the registry directory changed, stops the old server and starts a new one. It exits by
+itself after `FORGE_UI_IDLE_S` seconds without a request; the next `open` starts it again.
+Concurrent launchers are serialised by a lock, so they never start two servers.
+
+## State and logs
+
+```text
+${XDG_STATE_HOME:-~/.local/state}/forge/ui/
+  server.json     pid, port, build, registry and the runs a browser was opened for
+  server.log      the server's output; read it when the server did not start
+  lock            serialises launchers
+```
+
+Every plan, run and solo run registers its run dir in forge's run registry
+(`${XDG_CONFIG_HOME:-~/.config}/forge/runs/`), whether or not the UI was asked for: that is
+how the map shows all of a repo's runs. `forge-parallel.sh run` also records the
+`--max-parallel` it was given in `$PLAN/max_parallel`.
+
+## Privacy
+
+The server binds only `127.0.0.1` and serves read-only. It has **no token**: any process on
+the machine, under any user who can reach loopback, can read every run it knows, including
+prompts, diffs and review text from private repos. A running server keeps serving them,
+including runs that were later rerun with `--no-ui`.
+
+Every run is registered, so a running server shows every run on the machine, not only those
+opened with `--ui`. The 3D view fetches three.js from cdn.jsdelivr.net (no run data is sent;
+choose 2D in the page to never contact it).
+
+`--no-ui` and `FORGE_UI=off` only stop a *runner* from launching the server. They do not stop a
+server that is already running, do not unregister runs, and do not block `forge ui open`. To
+close the exposure, run `forge ui stop`. Do not forward the server's port.
+
+The API contract is [ui/docs/api.md](../ui/docs/api.md).