forgedock 1.0.22 → 1.1.2

package/docs/superpowers/specs/2026-07-03-cinematic-onboarding-tui-design.md

@@ -0,0 +1,157 @@
+# Cinematic Onboarding TUI — Design
+
+**Date:** 2026-07-03
+**Status:** Approved (design); pending implementation plan
+**Supersedes/extends:** `2026-06-09-intelligent-onboarding-design.md` (Pillars A & B were built as modules but never wired into the CLI; this design closes that seam and defines the visual/experiential layer on top)
+
+## Problem
+
+The onboarding audit (2026-07-03) found two classes of failure:
+
+1. **The intelligent onboarding is dead code.** `init-detect.mjs` (confidence-scored detection), `annotatedReviewScreen` (tui.mjs:835-1170), `init-enrich-api.mjs` (BYO-key AI enrichment), `registry.mjs`, and `bin/hooks/session-start.mjs` all exist with tests — and none are reachable. `forgedock.mjs`'s `init()` uses its own inline template; `install()` never registers the SessionStart hook; `enable`/`disable`/`status` don't exist.
+2. **The funnel lies.** README advertises `npx forgedock demo` (dead — `Unknown command`), `integrate` (dead), and a CLAUDE.md injection that never happens. `getting-started.md` sends users to `/forgedock-init`, which hard-errors without a forge.yaml. `CONFIG.md` documents `--manual`/`--verbose` flags that parse nowhere. `plugin.json` says 1.0.1 while `package.json` says 1.0.8.
+
+Beyond correctness, the shipped experience is plain warnings-and-homework. The goal is an install that feels revolutionary.
+
+## Decisions (locked with user)
+
+| Decision | Choice |
+| --- | --- |
+| TUI stack | Zero-dependency, hand-rolled — extend existing `tui.mjs`, no frameworks |
+| Scope | Full onboarding arc: preflight → install → detect → review → celebrate, plus SessionStart hook wiring and `enable`/`disable`/`status`. `forgedock demo` is **out of scope** (own milestone) |
+| Motion | Full cinematic, **always** — no first-run-only fast path; every command plays its full choreography. Automatic degradation (non-TTY/CI/`NO_COLOR`) and explicit escape hatches (`--fast`, `FORGE_NO_MOTION=1`). Note: an already-configured bare invocation shows the status screen (per approved storyboard) — that screen has its own full choreography; it doesn't replay the install acts |
+| Visual identity | **Molten Forge**: fire-orange → amber gradients, "forging" language |
+| Logo treatment | **Chrome & Ember**: block-art F mark keeps the official metallic chrome/champagne gradient; ember lives in the wordmark and UI. Hero mark on install; compact 4-row lockup on all other commands |
+| Flow shape | **One continuous journey**: bare `npx forgedock` plays the whole arc; `install`/`init` are aliases that jump into the relevant acts |
+| Architecture | **Cinema layer + journey orchestrator** (new `bin/cinema.mjs` + `bin/journey.mjs`; `forgedock.mjs` becomes a thin router) |
+
+## The Experience — five acts, one keypress
+
+The only interaction in the happy path is a single Enter at Act IV. Total added latency from theater: motion overlays real work wherever work exists; pure-theater beats (shimmer, quench flash) total ≈1.2s.
+
+### Act I — Ignition (~2.5s)
+
+Chrome block-art mark materializes with a one-pass heat-shimmer sweep (~800ms); ember gradient wordmark `F O R G E D O C K` + version; rule line "lighting the forge". Preflight rows appear one-by-one, each live (`○` → braille spinner → `✔`):
+
+- Node ≥18 (version shown)
+- git present + repo detected
+- Claude Code (`~/.claude` exists)
+- GitHub CLI installed + authenticated (account shown)
+
+A failed check renders an ember-bordered **fix card** with the exact copy-paste remedy (e.g. `winget install GitHub.cli`, `gh auth login`) and the journey **continues** with whatever still works. Preflight failures are advisory, not fatal — missing `gh` degrades detection confidence, it does not stop the forge.
+
+### Act II — Forging (real work)
+
+- Progress bar with molten leading edge (`█▓▒░`) and per-command name ticker while symlinking the 24 commands into `~/.claude/commands` (existing logic, restyled).
+- **Seam-closing (new):** merge a SessionStart hook entry into `~/.claude/settings.json` (idempotent read-modify-write; preserves existing hooks; removed on `uninstall`; malformed JSON → skip with fix card, never clobber). Write the registry entry marking the directory forge-managed.
+- Settle lines: `✔ 24 slash commands linked`, `✔ SessionStart hook registered`, `✔ directory forge-managed`.
+
+### Act III — Reading your repository
+
+Each detection field resolves as a live row: value + confidence badge + source, e.g.
+`✔ owner/repo  RapierCraftStudios/ForgeDock  [high] git remote`.
+Driven by the existing `detectConfig()` (init-detect.mjs). Fields: owner/repo, default branch, staging branch, project name, description, worktree base, project board (via `gh` when available). If `ANTHROPIC_API_KEY` is set, `init-enrich-api.mjs` fills review/verification sections (`✦ enriching with AI…`); if not, one quiet skip line. Spinners here cover *actual* latency (git/gh/API calls) — nothing is artificially slowed.
+
+### Act IV — The Review (the single interaction)
+
+The existing `annotatedReviewScreen` (tui.mjs), wired in at last and restyled to ember: numbered field table with `[high]/[med]/[low]` badges, confidence legend, low-confidence warning. `Press Enter to forge, or a number to edit a field`. Low-confidence fields are written with `# TODO(forgedock:<field>)` comments instead of blocking. Existing forge.yaml → overwrite banner + backup to `forge.yaml.bak` before write (existing behavior preserved).
+
+### Act V — Forged (celebration)
+
+Compact mark flashes white-hot once (quench, ~400ms), then settles:
+
+- `Forged.` + **real elapsed time** (`install → config in 34s`) — proof, not hype
+- Receipt lines: forge.yaml written (with TODO count), commands + hook active
+- Boxed "what's next" card: `1. open claude in this repo` / `2. run /work-on next`
+- Footer: docs link + star nudge
+
+Next Claude Code session, the now-installed SessionStart hook greets the user with the command table — the experience continues past the terminal.
+
+### Re-runs and aliases
+
+- Bare `npx forgedock` in an already-configured repo → short status screen (compact lockup, current config summary, hook state) + offer to review config. Not the full movie.
+- `npx forgedock install` → Acts I–II (+ III–V only if unconfigured, matching today's auto-init).
+- `npx forgedock init` → Acts III–V.
+- `enable` / `disable` / `status` → registry operations, compact lockup, instant.
+- `update` / `uninstall` → existing logic, compact restyle; `uninstall` also removes the hook entry and registry entries.
+
+## Architecture
+
+### `bin/cinema.mjs` (new — animation engine)
+
+Kept separate from tui.mjs (already 1,171 lines). Exports:
+
+- Truecolor per-cell gradient rendering with 256-color fallback (`COLORTERM`/`TERM` detection); gradient text lines and gradient block art
+- `renderMark(size)` — the chrome F mark, hero (8-row) and compact (4-row); block-art geometry approved v1 from mockups, may be pixel-tuned during implementation
+- `shimmer(lines, opts)` — one-pass highlight sweep
+- `reveal(rows, opts)` — staged live rows (`○` → spinner → `✔`/`✖`/fix card)
+- `progressBar` molten variant with ticker
+- `motionEnabled()` — the single motion gate: TTY ∧ ¬`NO_COLOR` ∧ ¬`FORGE_NO_MOTION` ∧ ¬`--fast` ∧ ¬CI
+
+**No alternate screen buffer.** Animations redraw in place (cursor-up) only while active, then settle to static lines — scrollback keeps a complete plain receipt of the run.
+
+### `bin/journey.mjs` (new — choreographer)
+
+Five act functions — `preflight()`, `forge()`, `read()`, `review()`, `celebrate()` — over a shared context object; each act independently callable (for aliases) and unit-testable. Orchestrates the existing modules: `init-detect.mjs`, `init-enrich-api.mjs`, `annotatedReviewScreen`, `registry.mjs`. The forge.yaml writer moves here, driven from the detection `ConfigDraft` (single source of truth; deletes the duplicate inline template in forgedock.mjs) and emits `# TODO(forgedock:<field>)` for low-confidence values.
+
+### `bin/forgedock.mjs` (shrinks to router)
+
+Command dispatch → journey acts as above. Fixes: `HOME` check gains `USERPROFILE`/`os.homedir()` fallback (currently hard-fails on bare Windows shells); flag parsing added (`--fast`, `--manual`, `--verbose`). `--manual` = plain-prompt path (no detection auto-accept), making CONFIG.md's documented flags real.
+
+### Hook wiring (the seam)
+
+`forge()` merges into `~/.claude/settings.json`:
+
+```json
+{ "hooks": { "SessionStart": [ { "hooks": [ { "type": "command",
+  "command": "node \"$FORGE_HOME/bin/hooks/session-start.mjs\"" } ] } ] } }
+```
+
+The command path is resolved to the absolute installed package location at install time (the same resolution `install()` already performs for symlink sources) — written as an absolute path, not a literal env reference, so the hook works regardless of shell profile.
+
+Idempotent (detects its own entry, never duplicates), preserves unrelated hooks, guards malformed JSON (skip + fix card, never overwrite), and is removed by `uninstall`. This makes the existing `session-start.mjs` (managed-active greeting / missing-config nudge / one-time unmanaged nudge) actually fire.
+
+## Degradation ladder
+
+1. Full cinematic — interactive TTY, truecolor
+2. 256-color — same choreography, quantized gradients
+3. `NO_COLOR` — monochrome, motion intact
+4. `--fast` / `FORGE_NO_MOTION=1` — instant renders, no animation frames
+5. Non-TTY/CI — deterministic plain sequential log, same information, zero ANSI animation; review screen auto-accepts nothing — in non-TTY, detection results are written with TODO flags and the run says so (preserves current "never block CI" behavior while still protecting existing configs via the existing non-interactive abort on overwrite)
+6. Narrow terminals (<60 cols) — compact lockup replaces hero mark; tables wrap to stacked rows
+
+## Error handling
+
+- **Never a dead stop, never a lie.** Preflight fix cards + continue; degraded steps stated inline at the moment they happen and echoed in the Act V receipt (e.g. `2 fields flagged # TODO`). No silently skipped sections.
+- **Ctrl-C per act:** restore cursor/style, print partial-state summary (`commands installed, config not written — run npx forgedock init to finish`), exit cleanly. No half-drawn screens, no orphaned temp files.
+- **Filesystem safety unchanged or better:** forge.yaml backup before overwrite; settings.json read-modify-write with parse guard; registry writes stay atomic (existing).
+
+## Testing
+
+Extends the existing `node --test` suite in `bin/tests/`:
+
+- **Acts:** unit tests with injected exec/IO stubs — preflight verdict matrix, hook-merge idempotency (twice → one entry), unrelated-hook preservation, TODO-flag emission, ConfigDraft→YAML writer output.
+- **Degradation:** snapshot tests of the non-TTY plain log (`FORGE_NO_MOTION=1`, piped stdout) — deterministic byte-for-byte.
+- **Cinema:** frame-function tests (gradient math, color-mode fallback selection), not timing tests — motion verified by eye; everything beneath it deterministic.
+- **Windows first-class:** path handling, `USERPROFILE` fallback, symlink-vs-copy behavior — primary dev platform is Windows.
+
+## Docs truth-pass (ships in this milestone)
+
+- **README:** remove `demo` (deferred) and `integrate`; replace CLAUDE.md-injection claim with the (now true) hook story; collapse the two-step install to one `npx forgedock`; requirements list gains Node ≥18.
+- **getting-started.md:** fix the `/forgedock-init`-without-forge.yaml dead end; document the journey.
+- **CONFIG.md:** `--manual`/`--verbose` now real; describe actual flags only.
+- **Versioning:** reconcile `plugin.json` (1.0.1) with `package.json` (1.0.8); ship as **1.1.0**.
+- **demo.tape:** re-record after implementation so the README gif shows the real flow.
+
+## Out of scope
+
+- `npx forgedock demo` (sandbox pipeline showcase) — its own future milestone
+- Self-healing `validate` (spec 2026-06-09 Pillar C, AI-fix loop) — future
+- Skill-backend enrichment inside Claude Code — future; API backend + deterministic baseline only for now
+
+## Success criteria
+
+- Fresh `npx forgedock` on a clean machine: zero commands to remember, one Enter, ends with a valid forge.yaml, installed commands, live SessionStart hook, and next-step card — in under ~60s on a normal repo.
+- Re-run is a status screen, not a movie sit-through beyond its own short choreography.
+- CI/non-TTY runs produce a stable plain log and never hang on a prompt.
+- No user-facing doc advertises a command or behavior that doesn't exist.

package/docs/superpowers/specs/2026-07-03-durable-execution-engine-design.md

@@ -0,0 +1,194 @@
+# Durable Execution Engine — Design Spec
+
+**Date:** 2026-07-03
+**Status:** Implemented (headless engine core) on branch feat/durable-execution-engine — see docs/superpowers/plans/2026-07-03-durable-execution-engine.md
+**Tracking:** #1256 (keystone), epic #1320 (five foundations of autonomy)
+**Scope of this spec:** the durable engine **core** only — phase state machine, run-log, resume, and orchestrator integration for **headless / orchestrated** runs. Verification, learning, economics, and provenance (#1315–#1319) are separate specs that build on this substrate.
+
+---
+
+## 1. Motivation
+
+The pipeline today is a **prose-driven state machine**. `work-on.md` describes a linear walk (Phase 0→7) whose only continuation mechanism is imperative text ("do NOT stop"), and its subcommands reference a numbered state router that `work-on.md` never implements (#1308). Phase transitions therefore depend on an LLM *choosing* not to emit `end_turn` at a Skill-return boundary. This produces the recurring failure classes:
+
+- **review→close stalls** (~half of runs merge the PR but leave the issue open).
+- **quality-gate→3H stalls.**
+- **"Prompt is too long" deaths** mid-run (#1305), patched with a self-counted "≥20 Skill calls" heuristic.
+- **Lossy state** — GitHub prose comments are the de-facto database; resume re-parses them.
+- **Blind observability** — progress is inferred from JSONL output files, which are 0-byte on Windows (#1307).
+
+The insight that makes a fix cheap: **`bin/runner.mjs` already owns the Anthropic tool-use loop** (issue #1151). ForgeDock is not locked inside Claude Code's opaque agent loop — it drives its own loop. So the work is not "adopt a runtime from scratch," it is "make the loop we already own durable."
+
+## 2. Goals / Non-goals
+
+**Goals**
+- Phase transitions are decided by **deterministic code**, never by an LLM's choice to continue.
+- A run survives crash / kill / compaction / rate-limit and **resumes from the last committed phase** in a fresh context.
+- State is **machine-readable and shared**, so any machine or the orchestrator can resume and observe a run.
+- Eliminate the stall and "prompt too long" classes structurally, not with prose.
+
+**Non-goals (explicitly out; each is its own spec / increment)**
+- The interactive Claude Code `/work-on` path (a later increment adopts the same core via hooks).
+- Per-turn / mid-phase durability (this spec is **per-phase** granularity).
+- The verification gate, learning memory, economic governance, provenance (#1315–#1319).
+- Full per-command parity for the standalone runtime (#1151 follow-up).
+
+## 3. Locked decisions
+
+These were settled during design and are not open:
+
+1. **Durability granularity: per-phase.** The engine checkpoints each pipeline *phase*. A mid-phase crash re-runs that one phase (idempotently). Per-turn durability is rejected as over-complex (partial file edits / half-made commits).
+2. **State authority: hybrid (local hot + GitHub mirror), GitHub wins on divergence.** A local append-only run-log is the crash-safe hot path; a structured `FORGE:STATE` block on the issue is the durable shared mirror. On conflict the GitHub mirror is authoritative and invalidates the local cache.
+3. **First surface: headless / orchestrated.** The engine drives runs through `runner.mjs` — where autonomy matters most and there is no human to un-stick a stall. Interactive Claude Code adopts the same core later.
+4. **`FORGE:STATE` is a compact index, not self-describing.** It carries the resume pointer (phase, `committed[]`, branch, pr, version, lease) — **not** the rich per-phase outputs. Rich outputs live in the existing `FORGE:INVESTIGATOR` / `ARCHITECT` / etc. structured comments (which the engine writes anyway). A fresh-clone resume reads the index for *where*, then reads those comments for *content*. This avoids duplicating data and preserves human-readable artifacts.
+
+## 4. Architecture
+
+Five components, each with one responsibility and a clean seam so the interactive path can later slot in as a second execution adapter.
+
+| Component | File | Responsibility |
+|---|---|---|
+| **Phase state machine** | `bin/engine/phases.mjs` | Declarative table encoding the canonical phase sequence (today's prose in `work-on.md`). Each entry: `id`, `entryCondition(state)`, `command` (spec to run), `terminal?`, `reconcile(state)`. |
+| **Engine loop** | `bin/engine.mjs` | The durable driver. Loads state, picks the next phase deterministically, invokes the phase, commits, handles failure. |
+| **LLM-execution adapter** | `bin/runner.mjs` *(existing)* | Runs one phase = one bounded `runCommand()` with a **fresh context window**. Loop unchanged; new caller. |
+| **Run-log store** | `bin/engine/runlog.mjs` | Append-only `.forge/runs/{issue}.jsonl`. Crash-safe local hot path. |
+| **GitHub adapter (projector)** | `bin/engine/projector.mjs` | Reads/writes the `FORGE:STATE` block; manages the lease. Durable shared mirror + data source for `forgedock watch` (#1312). |
+
+The engine core (`phases`, `engine`, `runlog`, `projector`) is runtime-agnostic; `runner.mjs` is the LLM adapter; the projector is the GitHub adapter.
+
+### Engine loop (shape)
+
+```
+state = load(issue)                       // local log → else FORGE:STATE → else fresh
+while (next = pickPhase(state)) {          // ENGINE decides; never the LLM
+  if (next.terminal) break
+  reconcile(state, next)                   // make re-entry safe (idempotency)
+  result = runner.runCommand(next.command, ctx(state))   // fresh context per phase
+  switch (result.status) {
+    case 'committed': commit(state, next, result.outputs); break   // append log + mirror
+    case 'failed':    if (attempts(next) < maxAttempts) retry; else block(state, next); break
+    case 'blocked':   terminate(state, 'needs-human', result.detail); return
+  }
+}                                          // no event on crash → next run drops + re-runs
+```
+
+## 5. State model
+
+### 5.1 Run-log (`.forge/runs/{issue}.jsonl`)
+
+Append-only, one JSON event per line. `seq` is a monotonic per-issue version counter.
+
+```jsonc
+{"seq":1,"event":"RUN_START","issue":42,"run":"r_a1","lane":"staging","baseSha":"9ea38…"}
+{"seq":2,"event":"PHASE_START","phase":"investigate"}
+{"seq":3,"event":"PHASE_COMMIT","phase":"investigate","outputs":{"verdict":"CONFIRMED","decompose":false}}
+{"seq":4,"event":"PHASE_START","phase":"build"}
+{"seq":5,"event":"PHASE_FAILED","phase":"build","attempt":1,"reason":"tsc error"}
+{"seq":6,"event":"PHASE_START","phase":"build"}
+{"seq":7,"event":"PHASE_COMMIT","phase":"build","outputs":{"branch":"fix/pay-42","headSha":"…","skipped":false}}
+{"seq":8,"event":"RUN_TERMINAL","reason":"merged"}
+```
+
+Events: `RUN_START`, `PHASE_START`, `PHASE_COMMIT`, `PHASE_FAILED`, `RUN_TERMINAL`.
+
+**The commit rule (the entire durability story):** a phase is *committed* iff a `PHASE_COMMIT` follows its latest `PHASE_START`. A `PHASE_START` with no following `PHASE_COMMIT` = a crashed / in-flight phase → **dropped and re-run**.
+
+**Corruption tolerance:** a crash mid-write leaves a truncated final line; the reader ignores any final line that does not parse as complete JSON.
+
+### 5.2 GitHub mirror (`FORGE:STATE`)
+
+One machine-readable HTML-comment block the projector **overwrites in place** (not appends) after each `PHASE_COMMIT`:
+
+```html
+<!-- FORGE:STATE
+{"v":7,"run":"r_a1","phase":"review","committed":["investigate","context","architect","build"],
+ "branch":"fix/pay-42","pr":null,"lane":"staging","terminal":false,
+ "lease":{"by":"agent_7","until":"2026-07-03T04:10Z"}}
+-->
+```
+
+`v` mirrors the run-log `seq` at last commit — the shared version used for divergence detection. It carries the **compact index only** (see locked decision 4).
+
+### 5.3 Resume + divergence (`GitHub wins`)
+
+```
+onStart(issue):
+  local  = readRunLog(issue)          // absent on fresh clone / other machine
+  remote = projector.read(issue)      // FORGE:STATE, may be absent
+  state  = reconcile(local, remote)
+
+reconcile(local, remote):
+  if !remote: return local ?? fresh
+  if !local:  return hydrateFromRemote(remote)          // fresh clone / other machine
+  if remote.v > local.lastSeq: return hydrateFromRemote(remote)   // advanced elsewhere → GitHub wins, discard local
+  if remote.v < local.lastSeq: projector.write(fromLocal(local)); return local  // we crashed pre-mirror → re-mirror, keep local
+  return local                                          // in sync
+```
+
+`hydrateFromRemote` reconstructs working state from the compact index plus, where a phase's rich outputs are needed downstream, the existing `FORGE:*` structured comments on the issue.
+
+## 6. Deterministic transitions & idempotency
+
+**`pickPhase(state)`** = the first phase in the `phases.mjs` table whose `entryCondition(state)` holds and whose `id` is not in `state.committed`. If none qualify or a terminal condition holds → terminal. No LLM involvement — this is the fix for the stall class.
+
+**`phase.reconcile(state)`** runs *before* the LLM on every entry, because a dropped phase re-runs and must be safe to re-enter:
+
+- `build.reconcile`: branch already exists and is ahead of base → resume rather than re-create.
+- `review.reconcile`: a PR already exists for the branch → adopt it, do not open a second.
+- `close.reconcile`: PR already merged → proceed straight to close steps.
+
+These leverage the existing `FORGE:*` markers and `gh` queries; the engine makes idempotency a required step rather than an ad-hoc convention.
+
+## 7. Failure policy
+
+Each phase returns a typed result; the engine acts on the **type** (replacing prose "try again / do not stop"):
+
+| Result | Meaning | Engine action |
+|---|---|---|
+| `committed` | phase produced outputs | write `PHASE_COMMIT`, advance |
+| `failed` | transient (rate-limit, network, `gh` timeout, context-budget hit mid-phase) | `PHASE_FAILED`; retry same phase with backoff up to `maxAttempts` (default 3); on exhaustion → treat as `blocked` |
+| `blocked` | deterministic human-needed (gate failed after loop, contract wrong, ancestry violation, push rejected) | `RUN_TERMINAL{needs-human}`, set label via projector, **stop visibly** |
+| *(no event)* | crash / kill / compaction | next run drops the uncommitted `PHASE_START` and re-runs the phase |
+
+**Visible skips (closes #1306):** a phase that no-ops (e.g. missing `verification.commands`) must emit `outputs:{skipped:true, which:"typecheck"}` into its `PHASE_COMMIT` and `FORGE:STATE`. A skip is surfaced (PR body / trajectory / review verdict), never a silent pass.
+
+**"Prompt too long" (dissolves #1305):** fresh context per phase removes the dominant cause. If a *single* phase still exhausts context mid-run, it is a `failed` attempt whose `reconcile` resumes from committed artifacts on retry. Note honestly: an oversized single-phase input (e.g. a 10k-line review diff) remains the review phase's own concern — the engine bounds it (`runner` tool-result caps + iteration budget) but does not shrink it; that is the verification/review spec's responsibility.
+
+## 8. Concurrency & orchestrator integration
+
+**Lease.** `FORGE:STATE.lease = {by: agentId, until: ts}` is written on `RUN_START`, renewed on each `PHASE_COMMIT`, released on `RUN_TERMINAL`. On start, if a live lease held by another agent exists, the caller defers. This is best-effort mutual exclusion (checked on start; not an atomic CAS) — GitHub issue-edit has no compare-and-swap, so a concurrent start can still race between the lease read and the next write. It replaces the orchestrator's fuzzy "already in progress" label heuristic with a much tighter, race-*reducing* primitive.
+
+**`/orchestrate` becomes a thin driver:**
+- Decomposes into the wave/DAG (unchanged), then calls `engine.run(issue)` per issue.
+- Watches `FORGE:STATE` per issue for progress — which also feeds `forgedock watch` (#1312) and removes any dependence on JSONL output files (killing the Windows-blind audit problem #1307 for orchestrated runs).
+- **Exact stall detection:** a lease whose `until` expired on a non-terminal state = a dead agent → re-spawn `engine.run(issue)`, which resumes from the last `PHASE_COMMIT`. This replaces "resume up to 3× with nagging."
+- File-overlap serialization remains the orchestrator's responsibility (unchanged), aided by the engine's `baseSha`/branch tracking.
+
+## 9. Testing strategy
+
+Correctness of a durable engine is won in tests. `runner.mjs` already lazy-imports the SDK and separates pure helpers, so the engine is tested with a **fake `runCommand`** that returns scripted phase outputs — no live LLM.
+
+- **State-machine units** (`bin/tests/phases.test.mjs`, `engine.test.mjs`): table-driven `pickPhase` over crafted states; `reconcile` across all divergence cases (local-only, remote-only, remote-ahead, local-ahead, in-sync); the commit-detection rule.
+- **Crash-injection harness** (the durability proof): run the engine against the fake runner, kill after each phase boundary *and* mid-phase, assert resume lands on the correct phase with no double-PR / double-commit.
+- **Run-log** (`runlog.test.mjs`): append/read/replay; truncated-final-line tolerance.
+- **Projector** (`projector.test.mjs`): `FORGE:STATE` serialize/parse round-trip; overwrite-in-place; lease acquire / renew / expire against a mocked `gh`.
+- **Per-phase `reconcile`** idempotency tests (build resumes, review adopts existing PR, close handles already-merged).
+
+## 10. Open implementation-time decision (defer to the plan)
+
+Whether the engine runs concurrent issues as **separate processes** (matches today's background-agent model; strong isolation) or an **in-process worker pool** (one place to observe; shared rate-limit backpressure). Recommendation: **in-process pool + a git worktree per issue** for filesystem isolation (worktrees are already the pattern). Decide during planning.
+
+## 11. Relationship to existing code & the epic
+
+- **Reuses:** `runner.mjs` (`runCommand`, tool handlers, result caps, lazy SDK) as the unmodified LLM adapter; the `work-on` phase sequence as the seed for `phases.mjs`; the existing `FORGE:*` structured comments as rich-output storage; git worktrees for isolation.
+- **Retires / fixes:** the phantom numbered-state router (#1308), the "≥20 Skill calls" heuristic and "prompt too long" deaths (#1305), silent verification skips (#1306), and — for orchestrated runs — the JSONL-based audit blindness (#1307).
+- **Enables (as substrate, not in scope):** the run-log's structured `outputs` and `FORGE:STATE` are deliberately the foundation for verification (#1315), learning memory (#1316), economics (#1317), and provenance (#1318).
+
+## 12. Definition of done
+
+- A headless `engine.run(issue)` drives an issue through the full phase sequence with the engine deciding every transition.
+- Killing the process at any phase boundary or mid-phase resumes correctly on the next run, with no duplicated PRs/commits (crash-injection suite green).
+- A fresh clone / second machine resumes a run from `FORGE:STATE` alone.
+- `/orchestrate` drives issues via `engine.run`, coordinates via the lease, and detects/recovers stalls via lease expiry.
+- Skipped verification is visible on the PR; a `blocked` result stops the run with `needs-human`, never silently.
+- Unit + crash-injection + projector/lease test suites pass with a mocked runner and mocked `gh`.

package/docs/superpowers/specs/2026-07-04-economic-self-governance-design.md

@@ -0,0 +1,181 @@
+# Economic Self-Governance — Design Spec
+
+**Date:** 2026-07-04
+**Status:** Design — ready to build
+**Tracking:** #1317 (economics layer), epic #1320 (five foundations of autonomy)
+**Scope:** Risk×cost go/no-go scoring function, budget-aware scheduler, and backpressure model. Unifies #1313 (preserve `needs-human`) and #1314 (autopilot `--yes` for low-risk) into a single decision model.
+
+---
+
+## 1. Motivation
+
+Safety Rule 3 in `/orchestrate` today reads: "no artificial concurrency limit — spawn as many agents as there are issues." That is the opposite of autonomy. Autonomy is **knowing when not to act**.
+
+The current decision surface has three static switches:
+
+| Surface | Policy | Problem |
+|---------|--------|---------|
+| `/work-on` solo | Ask human at every ambiguity | Over-asks on clear issues |
+| `/orchestrate` | "NEVER ask… merge anyway" | Under-asks on high-risk changes |
+| `/autopilot` | Gate every fix | Blocks low-risk wins behind human review |
+
+None of these is a decision — they are static switches baked into prose. The result: an agent either burns compute on issues it should not touch, or stalls on issues it could safely auto-run. Neither is economic.
+
+The fix is a **self-governing scheduler** that treats compute as a budget and makes an explicit go/no-go per issue before spawning any agent.
+
+---
+
+## 2. Goals / Non-goals
+
+**Goals**
+- A scoring function `(expected_cost, risk_tier, confidence) → {auto, escalate, defer}` runs before each issue is dispatched.
+- Per-run and per-wave budget caps with backpressure replace the "no artificial concurrency limit" rule.
+- `#1313` (preserve `needs-human` for high-risk) and `#1314` (autopilot `--yes` for low-risk) both fall out of the single model as threshold configurations — not separate flags.
+- The decision and its inputs are recorded in `FORGE:ECONOMICS` so runs are auditable.
+
+**Non-goals**
+- Real-time token streaming cost measurement (post-run accounting only, fed by #1255/#1295).
+- The durable engine state machine (#1256) — assumed as a substrate but not implemented here.
+- Per-turn interruption of in-flight agents (this spec is pre-dispatch).
+
+---
+
+## 3. Locked Decisions
+
+1. **Decision granularity: per-issue, pre-dispatch.** The go/no-go is computed once before an agent is spawned. Mid-run escalation is a separate concern.
+2. **Three-outcome model: `auto | escalate | defer`.** `auto` = spawn with no human gate. `escalate` = post a comment and wait for human approval. `defer` = place back in queue with lower priority, do not block the wave.
+3. **Budget authority: the orchestrator holds the budget, not individual agents.** Agents report estimated cost; the orchestrator decides whether to spend it.
+4. **Score inputs are observable.** Every input to the scoring function is logged in `FORGE:ECONOMICS` before any agent runs — so a human can audit why an issue was auto-run or escalated.
+5. **Thresholds are configurable in `forge.yaml`.** Default thresholds ship with the spec; operators can tighten or loosen them without editing command files.
+
+---
+
+## 4. Architecture
+
+### 4.1 Scoring Function
+
+```
+score(issue) → { decision, reasoning, estimated_cost, risk_tier, confidence }
+```
+
+**Inputs:**
+
+| Input | Source | Type |
+|-------|--------|------|
+| `expected_cost` | Historical cost-per-issue data (#1255/#1295) or heuristic (label + size estimate) | USD float |
+| `risk_tier` | Domain risk tag on issue label (`risk:low`, `risk:medium`, `risk:high`) or inferred from affected paths | `low \| medium \| high` |
+| `confidence` | FORGE:INVESTIGATOR confidence field, or `0.5` if no investigation comment exists | 0.0–1.0 |
+| `budget_remaining` | Current wave budget minus committed spend | USD float |
+| `needs_human` | Issue has `needs-human` label | bool |
+
+**Decision matrix (defaults):**
+
+| risk_tier | confidence | expected_cost | decision |
+|-----------|-----------|---------------|----------|
+| `low` | ≥ 0.7 | ≤ $0.50 | `auto` |
+| `low` | ≥ 0.7 | > $0.50 | `escalate` |
+| `low` | < 0.7 | any | `escalate` |
+| `medium` | ≥ 0.8 | ≤ $0.30 | `auto` |
+| `medium` | any other | any | `escalate` |
+| `high` | any | any | `escalate` |
+| any | any | > budget_remaining | `defer` |
+| `needs_human=true` | any | any | `escalate` (always) |
+
+Thresholds are overridable via `forge.yaml → economics`:
+
+```yaml
+economics:
+  auto_cost_ceiling_usd: 0.50       # max cost for auto-run (low risk)
+  medium_auto_cost_ceiling_usd: 0.30
+  auto_confidence_floor: 0.70
+  medium_confidence_floor: 0.80
+  wave_budget_usd: 5.00             # per-wave budget cap
+  run_budget_usd: 20.00             # per-run (session) budget cap
+```
+
+### 4.2 Budget Tracker
+
+A simple stateful accumulator maintained by the orchestrator across the wave:
+
+```
+budget_tracker = {
+  wave_limit: float,        # from forge.yaml or --budget flag
+  wave_committed: float,    # sum of expected_cost for auto-dispatched issues
+  wave_actual: float,       # sum of reported actual cost from completed agents
+  run_limit: float,
+  run_committed: float,
+}
+```
+
+`defer` fires when `wave_committed + expected_cost > wave_limit * 0.90` (10% buffer to absorb cost overruns).
+
+Backpressure: when the wave budget is exhausted, remaining issues are set to `workflow:deferred` label and the orchestrator reports a budget summary. They are the first candidates in the next wave.
+
+### 4.3 FORGE:ECONOMICS Annotation
+
+Written to the issue before the agent is spawned (or before posting the escalation comment):
+
+```html
+<!-- FORGE:ECONOMICS
+decision: auto
+risk_tier: low
+confidence: 0.82
+expected_cost_usd: 0.18
+budget_remaining_usd: 3.47
+wave: 1
+rationale: "low-risk label, high investigation confidence, well within budget"
+timestamp: 2026-07-04T12:00:00Z
+-->
+```
+
+Downstream stages (verification gate, provenance) can read this annotation to understand the economic context of the decision.
+
+### 4.4 Integration Points
+
+**`/orchestrate`**: Phase 2B (issue selection) gains a `score_issues()` step before dispatching agents. Issues that score `escalate` are held; `auto` issues proceed; `defer` issues are re-queued.
+
+**`/autopilot`**: The `--fix` phase queries the scoring function instead of the current "gate every fix" heuristic. `--yes` flag sets `auto_confidence_floor: 0.0` and raises cost ceilings — effectively the current `--yes` behavior, but explicit and auditable.
+
+**`/work-on`**: Solo interactive use is unaffected. The scoring function is opt-in via `forge.yaml → economics.solo_mode: enabled`.
+
+---
+
+## 5. Implementation Plan
+
+### Increment 1: Scoring function + FORGE:ECONOMICS (no budget tracking)
+- Add `score_issue()` logic to `/orchestrate` Phase 2B.
+- Read domain risk labels and FORGE:INVESTIGATOR confidence.
+- Emit `FORGE:ECONOMICS` annotation.
+- `escalate` path posts a comment and adds `needs-human` label; agent is not spawned.
+- `defer` path is treated as `escalate` in this increment.
+
+### Increment 2: Budget tracker + backpressure
+- Add `budget_tracker` state to orchestrator.
+- Read `forge.yaml → economics` thresholds.
+- `defer` path sets `workflow:deferred` label and skips the issue.
+- Post wave budget summary at end of orchestrator run.
+
+### Increment 3: Unify #1313 and #1314
+- Remove hard-coded "NEVER ask" language from `/orchestrate`.
+- Remove hard-coded "gate every fix" from `/autopilot`.
+- Both commands delegate to the scoring function with appropriate threshold profiles (`orchestrate` uses `medium_confidence_floor`, `autopilot --yes` raises ceilings).
+
+---
+
+## 6. Open Questions
+
+- **Cost estimation without history**: For issues with no historical data, the default heuristic is label-based (`bug` → $0.20, `feat` → $0.40, `epic` → $1.00). This needs calibration once #1255 data is available.
+- **Risk tag inference**: If no `risk:*` label exists, infer from affected paths (e.g., changes to `bin/`, `commands/quality-gate.md`, or CI workflows → `risk:high`). Path-based inference is a follow-on to Increment 1.
+- **Wave vs. run budget interaction**: A "run" spans multiple waves in `/autopilot`. The run budget should be the outer limit; wave budget is the inner pacing mechanism.
+
+---
+
+## 7. References
+
+- #1317 — this issue
+- #1255, #1295, #1296, #1297 — cost-per-issue accounting (feeds `expected_cost`)
+- #1249 — per-agent model/effort tiering (feeds `expected_cost`)
+- #1313 — preserve `needs-human` for high-risk (subsumed by this spec)
+- #1314 — autopilot `--yes` for low-risk (subsumed by this spec)
+- #1320 — five foundations epic (economics layer)
+- #1256 — durable engine (substrate for stateful budget tracking)