forgedock 1.0.21 → 1.1.1

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/examples/forgedock-demo/README.md

@@ -0,0 +1,113 @@
+# ForgeDock Demo — A Risk-Free First Pipeline Run
+
+A tiny **Notes API** (~300 lines, zero dependencies) with five pre-written
+issues. It exists so you can watch ForgeDock investigate, build, review, and
+merge a change **without touching your real codebase**.
+
+> Clone → `npx forgedock` → open Claude Code → `/work-on 1` → watch it go.
+
+---
+
+## Why this exists
+
+Trying ForgeDock on your own project means trusting an AI pipeline with real
+code on your very first run. This demo removes that risk: it's a self-contained
+sandbox where every issue is small, fast, and safe to break.
+
+The API has a couple of **intentional, clearly-labelled flaws** (a missing auth
+check, an unsafe query path) so that ForgeDock's `/review-pr` agents have real
+findings to surface — that's the part that makes the review feel impressive.
+
+---
+
+## What's inside
+
+```
+forgedock-demo/
+├── src/
+│   ├── server.js        # built-in http server + router (no Express)
+│   ├── router.js        # (added by Issue #3)
+│   ├── routes/notes.js  # CRUD handlers — has the intentional flaws
+│   ├── db.js            # in-memory store
+│   └── auth.js          # bearer-token check
+├── scripts/smoke.js     # dependency-free smoke test (npm run smoke)
+├── issues/              # the 5 pre-written issue specs
+├── forge.yaml           # minimal working ForgeDock config
+├── labels.json          # workflow + priority labels
+└── bootstrap.sh         # one command to stand up the live repo
+```
+
+No database. No Docker. No API keys. Runs on Node 18+.
+
+---
+
+## Run it locally (optional)
+
+```bash
+node src/server.js          # starts on http://localhost:3000
+# in another terminal:
+curl http://localhost:3000/notes
+npm run smoke               # runs the smoke test
+```
+
+---
+
+## The five demo issues
+
+Each issue targets a different pipeline strength and is scoped to finish fast.
+
+| # | Type | Title | What it shows |
+|---|------|-------|---------------|
+| 1 | Bug / security | DELETE is missing an auth check | Simplest fix — fastest run |
+| 2 | Feature / security | Safe filtering for `GET /notes` | Investigation + architecture |
+| 3 | Refactor | Extract the router module | "No behavior change" review |
+| 4 | Performance | O(1) `findById` | Investigation phase tracing the hot path |
+| 5 | Docs | Add an API reference | Pipeline handles non-code work |
+
+Full specs live in [`issues/`](./issues). When you run `bootstrap.sh`, these
+become real GitHub issues #1–#5 in your demo repo, in this order.
+
+---
+
+## Stand up your own live demo repo
+
+The scaffold is complete and ready — the only step that needs your GitHub
+credentials is creating the actual repo. One command does it:
+
+```bash
+# requires an authenticated gh CLI (gh auth login)
+./bootstrap.sh                        # creates <your-user>/forgedock-demo (public)
+# or:
+./bootstrap.sh my-org/forgedock-demo  # custom owner/repo
+```
+
+`bootstrap.sh` will:
+
+1. Create the GitHub repo (skips if it already exists).
+2. Push this codebase to `main`.
+3. Create the workflow + priority labels (via `npx forgedock labels setup`,
+   falling back to `labels.json`).
+4. File the five issues from [`issues/`](./issues).
+
+Then:
+
+```bash
+git clone https://github.com/<you>/forgedock-demo.git
+cd forgedock-demo
+npx forgedock              # install the ForgeDock commands
+# open Claude Code in this directory, then run:
+/work-on 1
+```
+
+Watch ForgeDock investigate the missing-auth bug, write the fix, run the quality
+gate, open a PR, review it, and merge — all on a repo you can safely throw away.
+
+---
+
+## After your first run
+
+Try `/work-on 2` through `/work-on 5` to see the other pipeline phases, or run
+`/orchestrate` to let ForgeDock work several issues in parallel.
+
+When you're comfortable, point ForgeDock at your real project — you've already
+seen exactly what it does.

package/examples/forgedock-demo/bootstrap.sh

@@ -0,0 +1,125 @@
+#!/usr/bin/env bash
+#
+# bootstrap.sh — stand up a live ForgeDock demo repo from this scaffold.
+#
+# This is the ONE step that needs a human: it creates a real GitHub repo (which
+# requires your credentials), pushes this code, sets up the workflow labels, and
+# files the five demo issues. Everything else in the scaffold is ready to go.
+#
+# Usage:
+#   ./bootstrap.sh                       # creates <your-user>/forgedock-demo (public)
+#   ./bootstrap.sh my-org/forgedock-demo # custom owner/repo
+#   ./bootstrap.sh my-org/forgedock-demo --private
+#
+# Requirements: an authenticated `gh` CLI (`gh auth status`) and `git`.
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+cd "$SCRIPT_DIR"
+
+# ---- args -------------------------------------------------------------------
+REPO_SLUG="${1:-}"
+VISIBILITY="--public"
+for arg in "$@"; do
+  case "$arg" in
+    --private) VISIBILITY="--private" ;;
+    --public)  VISIBILITY="--public" ;;
+  esac
+done
+
+if [ -z "$REPO_SLUG" ] || [[ "$REPO_SLUG" == --* ]]; then
+  GH_USER="$(gh api user --jq '.login')"
+  REPO_SLUG="${GH_USER}/forgedock-demo"
+fi
+
+echo "==> Target repo: $REPO_SLUG ($VISIBILITY)"
+
+command -v gh >/dev/null || { echo "ERROR: gh CLI not found"; exit 1; }
+gh auth status >/dev/null || { echo "ERROR: run 'gh auth login' first"; exit 1; }
+
+# ---- 1. create the repo -----------------------------------------------------
+REPO_CREATED=false
+if gh repo view "$REPO_SLUG" >/dev/null 2>&1; then
+  echo "==> Repo already exists, skipping creation."
+else
+  echo "==> Creating repo..."
+  gh repo create "$REPO_SLUG" $VISIBILITY \
+    --description "Try ForgeDock risk-free — a tiny Notes API with pre-written issues." \
+    --disable-wiki
+  REPO_CREATED=true
+fi
+
+# ---- 2. push the scaffold ---------------------------------------------------
+TMP_DIR="$(mktemp -d)"
+echo "==> Staging scaffold in $TMP_DIR"
+# Copy everything except bootstrap.sh and the issues/ specs (issues become GH issues).
+cp -r src scripts package.json forge.yaml labels.json README.md .gitignore "$TMP_DIR/" 2>/dev/null || true
+# Ship the issue specs too, for reference inside the repo.
+cp -r issues "$TMP_DIR/issues"
+
+(
+  cd "$TMP_DIR"
+  git init -q
+  git checkout -q -b main
+  git add .
+  git -c user.name="forgedock-demo" -c user.email="demo@forgedock.dev" \
+      commit -q -m "chore: initial demo scaffold"
+  git remote add origin "https://github.com/${REPO_SLUG}.git"
+  if [ "$REPO_CREATED" = "true" ]; then
+    # Fresh repo we just created — safe to push.
+    git push -q -u origin main
+  else
+    # Repo pre-existed. Never force-push over someone's existing main; do a
+    # non-destructive push and let it fail loudly if the repo already has commits.
+    if ! git push -q -u origin main 2>/dev/null; then
+      echo "ERROR: '$REPO_SLUG' already has content on main. Refusing to overwrite it." >&2
+      echo "       Use a fresh/empty repo, or push manually if you intend to replace it." >&2
+      exit 1
+    fi
+  fi
+)
+echo "==> Pushed scaffold to $REPO_SLUG"
+
+# ---- 3. labels --------------------------------------------------------------
+echo "==> Creating labels..."
+# Prefer the ForgeDock CLI if available; otherwise create from labels.json.
+if command -v npx >/dev/null && npx --no-install forgedock --help >/dev/null 2>&1; then
+  npx forgedock labels setup --repo "$REPO_SLUG" || true
+else
+  node -e '
+    const fs = require("fs");
+    const labels = JSON.parse(fs.readFileSync("labels.json", "utf8"));
+    for (const l of labels) console.log([l.name, l.color, l.description].join("\t"));
+  ' labels.json | while IFS=$'\t' read -r name color desc; do
+    gh label create "$name" --color "$color" --description "$desc" --force -R "$REPO_SLUG" >/dev/null 2>&1 || true
+  done
+fi
+
+# ---- 4. issues --------------------------------------------------------------
+echo "==> Creating issues..."
+for f in issues/*.md; do
+  title="$(grep -m1 '^title:' "$f" | sed -E 's/^title:[[:space:]]*"?([^"]*)"?[[:space:]]*$/\1/')"
+  labels="$(grep -m1 '^labels:' "$f" | sed -E 's/^labels:[[:space:]]*\[(.*)\][[:space:]]*$/\1/' | tr -d '"' | tr -d ' ')"
+  # Body = everything after the closing front-matter '---'.
+  body="$(awk 'f{print} /^---[[:space:]]*$/{c++; if(c==2) f=1}' "$f")"
+  label_args=()
+  if [ -n "$labels" ]; then
+    IFS=',' read -ra parts <<< "$labels"
+    for l in "${parts[@]}"; do label_args+=(--label "$l"); done
+  fi
+  echo "    - $title"
+  gh issue create -R "$REPO_SLUG" --title "$title" --body "$body" "${label_args[@]}" >/dev/null \
+    || gh issue create -R "$REPO_SLUG" --title "$title" --body "$body" >/dev/null
+done
+
+rm -rf "$TMP_DIR"
+
+echo ""
+echo "Done. Your demo repo is ready:"
+echo "  https://github.com/${REPO_SLUG}"
+echo ""
+echo "Next:"
+echo "  git clone https://github.com/${REPO_SLUG}.git && cd forgedock-demo"
+echo "  npx forgedock           # install the commands"
+echo "  # open Claude Code here, then run:  /work-on 1"

package/examples/forgedock-demo/issues/01-bug-delete-missing-auth.md

@@ -0,0 +1,37 @@
+---
+title: "fix(notes): DELETE /notes/:id is missing an auth check"
+labels: ["bug", "security", "priority:P1"]
+---
+
+## Problem
+
+`DELETE /notes/:id` lets **anyone** delete any note. The other mutating route
+(`POST /notes`) requires a bearer token via `requireToken(req)`, but the delete
+handler skips that check entirely. This is an authorization gap.
+
+## Steps to Reproduce
+
+```bash
+# No token, yet it succeeds:
+curl -X DELETE http://localhost:3000/notes/1
+# => {"deleted":1}
+```
+
+## Affected Files
+
+1. `src/routes/notes.js` — `deleteNote()` is missing a `requireToken(req)` call.
+
+## Expected Behavior
+
+`DELETE /notes/:id` returns `401 Unauthorized` when no valid bearer token is
+supplied, matching the protection on `POST /notes`.
+
+## Acceptance Criteria
+
+- [ ] `deleteNote()` calls `requireToken(req)` before deleting.
+- [ ] Unauthenticated delete returns 401.
+- [ ] Authenticated delete (`Authorization: Bearer demo-token`) still works.
+- [ ] No regression in `npm run smoke`.
+
+> Good first run: this is the simplest issue — expect the pipeline to finish in
+> a couple of minutes.