forgedock 1.0.22 → 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forgedock",
-  "version": "1.0.22",
+  "version": "1.1.1",
   "description": "Autonomous dev pipeline for Claude Code. GitHub as institutional memory — every issue, PR, and annotation survives context resets and makes the next agent smarter.",
   "bin": {
     "forgedock": "bin/forgedock.mjs"
@@ -27,7 +27,7 @@
     "type": "git",
     "url": "git+https://github.com/RapierCraftStudios/ForgeDock.git"
   },
-  "homepage": "https://forgedock.dev",
+  "homepage": "https://github.com/RapierCraftStudios/ForgeDock#readme",
   "bugs": {
     "url": "https://github.com/RapierCraftStudios/ForgeDock/issues"
   },
@@ -43,13 +43,19 @@
     "README.md"
   ],
   "scripts": {
-    "test": "node --test \"bin/tests/**/*.test.mjs\""
+    "test": "node --test \"bin/tests/**/*.test.mjs\"",
+    "docs:dev": "vitepress dev docs/site",
+    "docs:build": "vitepress build docs/site",
+    "docs:preview": "vitepress preview docs/site"
   },
   "engines": {
     "node": ">=18"
   },
   "optionalDependencies": {
-    "@anthropic-ai/sdk": ">=0.30.0"
+    "@anthropic-ai/sdk": ">=0.30.0 <1"
+  },
+  "devDependencies": {
+    "vitepress": "^1.6.3"
   },
   "peerDependencies": {
     "@anthropic-ai/claude-code": ">=2.0.0"

package/scripts/verify-env-vars.sh

@@ -179,8 +179,24 @@ for var in $VAR_NAMES; do
     fi
 
     if [ -z "$FOUND_IN" ]; then
-        echo "BLOCKING: $var — not found in .env.example, docker-compose.yml, or env_validation.py"
-        BLOCKING=$((BLOCKING + 1))
+        # Determine whether any of the optional surfaces exist in this repo.
+        # If NONE of the known surfaces exist (not even .env.example), the repo
+        # uses a layout we can't validate — emit SKIP instead of a false BLOCKING.
+        # This is the verify-sops-chain.sh pattern: unknown layout → graceful skip,
+        # not a spurious failure. <!-- Added: forge#1349 -->
+        HAS_ANY_SURFACE=0
+        [ -f "$REPO_ROOT/.env.example" ] && HAS_ANY_SURFACE=1
+        [ -f "$REPO_ROOT/docker-compose.yml" ] && HAS_ANY_SURFACE=1
+        [ -f "$REPO_ROOT/docker-compose.prod.yml" ] && HAS_ANY_SURFACE=1
+        [ -f "$REPO_ROOT/services/api/app/core/env_validation.py" ] && HAS_ANY_SURFACE=1
+        [ -f "$REPO_ROOT/scripts/decrypt-secrets.sh" ] && HAS_ANY_SURFACE=1
+
+        if [ "$HAS_ANY_SURFACE" -eq 0 ]; then
+            echo "SKIP: $var — no known env-wiring surfaces found in repo (no .env.example, docker-compose, env_validation.py, or SOPS mapping). Configure verification.env_check_surfaces in forge.yaml or add .env.example to enable this check."
+        else
+            echo "BLOCKING: $var — not found in any detected env-wiring surface (.env.example, docker-compose.yml, env_validation.py, or decrypt-secrets.sh)"
+            BLOCKING=$((BLOCKING + 1))
+        fi
     else
         echo "OK: $var — found in:$FOUND_IN"
     fi

package/scripts/verify-host-headers.sh

@@ -67,9 +67,9 @@ while read -r f; do
         elif echo "$CONTENT" | grep -qE "\-\-header\s+[\"']Host:"; then
             echo "OK: $f:$LINENO — Host header explicitly set (--header)"
         else
-            echo "BLOCKING: $f:$LINENO — curl/wget to internal service without explicit Host header. TrustedHostMiddleware will reject raw IP as Host value."
+            echo "BLOCKING: $f:$LINENO — curl/wget to internal service without explicit Host header. Host-validation middleware will reject a raw IP as the Host value."
             echo "  Line: $CONTENT"
-            echo "  Fix: Add -H 'Host: localhost' (or appropriate allowed host from services/api/app/main.py allowed_hosts)"
+            echo "  Fix: Add -H 'Host: <allowed-hostname>' — check your service's allowed_hosts configuration for the correct value"
             BLOCKING=$((BLOCKING + 1))
         fi
     done < <(echo "$CURL_LINES")
@@ -96,11 +96,11 @@ if [ -n "$FRONTEND_FILES" ]; then
         fi
 
         if [ -n "$DIRECT_CALLS" ]; then
-            echo "BLOCKING: $f — direct /api/v1/ call bypasses Next.js proxy (auth will fail)"
+            echo "BLOCKING: $f — direct /api/v1/ call bypasses frontend proxy (auth middleware will be skipped)"
             while IFS= read -r match; do
                 echo "  $match"
             done < <(echo "$DIRECT_CALLS")
-            echo "  Fix: Use /api/* proxy routes instead of /api/v1/* direct FastAPI calls"
+            echo "  Fix: Use the frontend proxy route (e.g. /api/*) instead of calling the backend API directly"
             BLOCKING=$((BLOCKING + 1))
         else
             echo "OK: $f — no direct backend calls"

package/scripts/verify-route-registration.sh

@@ -5,7 +5,7 @@
 #   changed_files_file: path to a file listing changed files (one per line)
 #   repo_root: path to the repository root
 #
-# Layout path overrides (env vars — override defaults for non-AlterLab layouts):
+# Layout path overrides (env vars — override defaults for project-specific layouts):
 #   FORGE_PAGES_ROOT          Root of Next.js App Router pages dir (default: web/src/app)
 #   FORGE_API_ROUTERS_DIR     Dir containing FastAPI router .py files (default: services/api/app/routers)
 #   FORGE_API_MAIN            Path to API app entrypoint, relative to repo root (default: services/api/app/main.py)
@@ -35,7 +35,7 @@ else
     FILES=$(cat "$CHANGED_FILES")
 fi
 
-# Layout path configuration — read from env vars, fall back to AlterLab defaults
+# Layout path configuration — read from env vars, fall back to project defaults
 FORGE_PAGES_ROOT="${FORGE_PAGES_ROOT:-web/src/app}"
 FORGE_API_ROUTERS_DIR="${FORGE_API_ROUTERS_DIR:-services/api/app/routers}"
 FORGE_API_MAIN="${FORGE_API_MAIN:-services/api/app/main.py}"