@felixdotgo/aidlc-kit 0.1.1 → 0.3.0

package/docs/development.md

@@ -1,26 +1,32 @@
 # Development guide
 
-This guide is for contributors to `@felixdotgo/aidlc-kit`. It covers local setup, source ownership, and the rules that keep the package runtime and installed workflow behaviour aligned.
+Local setup, dogfooding, source ownership, and the rules that keep package runtime and installed workflow aligned. To use the workflow in your own project, start at the [documentation index](./README.md).
 
 ## Requirements and dependencies
 
-- Node.js 20.17 or newer is required by the package runtime.
-- npm installs the repository development dependencies.
-- `@inquirer/prompts` is the runtime dependency for interactive CLI prompts; installed lifecycle scripts remain dependency-free.
-- Development uses TypeScript and `@types/node` as declared in `package.json`.
+- Node.js 20.17 or newer; npm installs the dev dependencies (TypeScript, `@types/node`).
+- `@inquirer/prompts` is the only runtime dependency; installed lifecycle scripts are dependency-free.
+- Codex, Claude Code, or OpenCode: only for real evaluator drivers; OpenCode also needs `AIDLC_OPENCODE_MODEL` (`provider/model[#variant]`).
 
 ```sh
 npm install
 ```
 
-Codex, Claude Code, or OpenCode are optional for manually exercising real evaluator drivers. Ordinary build, lint, and unit-test work does not need external model credentials. OpenCode driver runs also need `AIDLC_OPENCODE_MODEL` set to a `provider/model[#variant]` value.
+## Platform support
+
+| Platform | Status | Notes |
+| --- | --- | --- |
+| Linux | Supported | Full CI coverage; Docker worker isolation available. |
+| macOS | Supported | Full test coverage; POSIX shell recipes apply. |
+| Windows | Best-effort | Use WSL or Git Bash for shell recipes. win32 separators handled in `src/state/guards.ts`, `src/profiles.ts`, installed `lib/store.mjs` and `context-runtime.mjs`; state lock liveness via `process.kill(pid, 0)`. Not in CI. |
+| Loop / fleet | Linux only | Needs Docker and a POSIX shell; `loop-local-workers.mjs` rejects other hosts. E2e tests need `AIDLC_TEST_WORKER_IMAGE` and `AIDLC_WORKER_DOCKER_IMAGE`. |
 
 ## Repository layout
 
 ```text
 assets/aidlc/                Source workflow contracts, schemas, and installed scripts
 skills/                      Source thin phase adapters
-src/                         TypeScript package CLI, installer, lifecycle, profiles, and migrations
+src/                         Package CLI (src/cli/), installer, shared planning core, lifecycle domain (src/model/, src/state/), profiles, migrations
 dev/evaluator/               Development-only evaluator harness and runners
 scripts/build-assets.mjs     Bundles workflow assets for package distribution
 test/unit/                   Unit and installed-runtime parity tests
@@ -28,25 +34,22 @@ docs/                        User, operator, and contributor documentation
 dist/                        Generated TypeScript and bundled assets; do not hand-edit
 ```
 
-The asset build copies `assets/aidlc/` and `skills/` into `dist/assets/.agents/`. At install time, the package writes the workflow to a consumer project's `.agents/aidlc/` and `.agents/skills/` locations. Always state which of these three layouts—source, bundle, or installed project—you mean in code or documentation.
+Three layouts: source (`assets/aidlc/`, `skills/`), bundle (`dist/assets/.agents/`), installed (consumer `.agents/aidlc/` and `.agents/skills/`). Say which you mean.
 
 ## Local commands
 
 | Command | Purpose |
 | --- | --- |
-| `npm run build` | Rebuild bundled workflow assets and compile TypeScript into `dist/`. |
+| `npm run build` | Bundle workflow assets and compile TypeScript into `dist/`. |
+| `npm run sync-core` | Copy `assets/aidlc/scripts/lib/store.mjs` to `services/aidlc-coordination/src/lifecycle-core.mjs` byte-identically. |
 | `npm run lint` | Type-check without emitting files. |
-| `npm test` | Build, then run every compiled unit test with Node's test runner. |
-| `node --test dist/test/unit/<file>.test.js` | Run a focused compiled test after building. |
-| `npm run release:check` | Run the repository release-evidence policy check. |
-
-Run the narrowest relevant test while iterating, then run `npm test` and `npm run lint` before handing off a non-trivial change. See [Testing and release](./testing-and-release.md) for the package smoke test and evaluator.
+| `npm test` | Build, then run all compiled unit tests (Node test runner). |
+| `node --test dist/test/unit/<file>.test.js` | Run one compiled test after building. |
+| `npm run release:check` | Release-evidence policy check. |
 
 ## Local build and registry-free installation
 
-Use this fast smoke test to install workflow assets from the current checkout into a disposable consumer project. It invokes the freshly compiled CLI directly, so the consumer installation does not use `npm install`, `npx`, a published package, or an npm registry. Repository bootstrap and build still use npm and the dependencies already installed in this checkout.
-
-Run the following POSIX shell commands from the repository root:
+Install the checkout's assets into a disposable consumer project via the compiled CLI (no `npm install`, `npx`, or registry). From the repository root:
 
 ```sh
 AIDLC_REPO="$(pwd)"
@@ -62,59 +65,131 @@ node "$AIDLC_LOCAL_PROJECT/.agents/aidlc/scripts/state.mjs" task list --root "$A
 printf 'Local test project: %s\n' "$AIDLC_LOCAL_PROJECT"
 ```
 
-The dry run previews the managed writes before `--yes` applies them. `status` describes the installed version and adapters, `doctor --strict` is the integrity check, and the final command confirms that the copied dependency-free lifecycle runtime can read its canonical state without the package CLI.
+- Use a new empty directory each time (reuse across versions triggers the human-only upgrade protection); remove it manually. On Windows, create it in PowerShell and pass the absolute path.
+- Do not target a real project unless its managed files and state are intentional test targets.
+- This checks the compiled checkout only, not the published allowlist, bin metadata, or tarball exclusions; run the [package smoke test](./testing-and-release.md#package-smoke-test) before release.
+
+## Run `npx` from a local package archive
+
+```sh
+npm pack
+npx --package felixdotgo-aidlc-kit-0.3.0.tgz -- aidlc-kit init .
+```
 
-Always use a new empty directory and inspect the printed path before removing it manually. Do not point this recipe at a real project unless its managed files and workflow state are intentional test targets. Reusing a fixture across package versions triggers the human-only upgrade protection by design. On Windows, use WSL or Git Bash for the snippet, or create a temporary directory in PowerShell and pass its absolute path to the same Node commands.
+Run from the archive's directory; pass a disposable project instead of `.` to avoid writing into the current directory.
 
-This direct-`dist` smoke verifies the compiled checkout, but it does not verify the published file allowlist, package bin metadata, or tarball exclusions. Before release, also run the separate [package smoke test](./testing-and-release.md#package-smoke-test), which packs and extracts a local tarball without installing or fetching the package from a registry.
+## Dogfooding this repository
 
-## Run `npx` from a local package archive
+`.agents/` is gitignored; each contributor installs the repository's own workflow from the checkout.
 
-To test the package before release, create its `.tgz` archive and run the local archive with `npx`:
+### Install the workflow from source
 
 ```sh
-npm pack
-npx --package felixdotgo-aidlc-kit-0.1.1.tgz -- aidlc-kit init .
+npm install
+npm run build
+node dist/src/cli.js init . --agent <codex|claude|opencode> --loop-mode off --yes
 ```
 
-`npx` runs the archive without publishing it. Run the command from the directory containing the archive. Use a disposable project instead of `.` if you do not want the command to write workflow files into the current directory.
+Edit `.agents/config.json` as below (`commands` as executable-and-argument arrays; your adapter id → `"scripted"` in `agentState`), then `node dist/src/cli.js profile validate .`.
+
+```json
+{
+  "commands": {
+    "build": { "command": "npm", "args": ["run", "build"] },
+    "test": { "command": "npm", "args": ["test"] },
+    "lint": { "command": "npm", "args": ["run", "lint"] }
+  },
+  "agentState": { "opencode": "scripted" }
+}
+```
 
-## Ownership boundaries
+### Check for drift and re-sync
 
-The package has three ownership layers:
+After changing `assets/aidlc/`, check for a stale install (any output means stale; symptom: `loop: Isolated local worker dispatcher is not integrated; loop execution is unavailable`):
 
-1. Package-managed kernel assets installed under `.agents/aidlc/`.
-2. Project-owned configuration, profiles, rules, and evaluation material under `.agents/project/`.
-3. Project-owned task state and derived data under `.agents/data/`.
+```sh
+diff -rq assets/aidlc/scripts .agents/aidlc/scripts
+```
 
-Do not introduce a second lifecycle board or hand-edit canonical state. The installed lifecycle scripts are dependency-free so consumer projects do not need this package to operate after installation.
+Re-sync is a human-only upgrade (TTY required); stop the loop daemon first (`node dist/src/cli.js loop down --root .` or `loop stop`), then re-run `diff -rq`:
 
-## Mirrored runtime behaviour
+```sh
+npm run build
+node dist/src/cli.js upgrade . --dry-run   # preview the plan
+node dist/src/cli.js upgrade .             # type the package version when prompted
+```
+
+### Run the loop from a source checkout
+
+> [!WARNING]
+> Experimental, pre-1.0. See [Status and stability](./loop-runbook.md#status-and-stability).
+
+In place of `npx --package @felixdotgo/aidlc-kit@<version> aidlc-kit …`, run the compiled CLI after `npm run build`:
 
-The TypeScript implementation powers the package CLI. Installed projects use a dependency-free mirror under `assets/aidlc/scripts/`. Changes to shared lifecycle, state, gate, profile, or context behaviour must preserve parity between these paths and add coverage for both package and installed-runtime execution.
+| Task | Command |
+| --- | --- |
+| Start the daemon and dashboard | `node dist/src/cli.js loop up --root .` |
+| Check daemon and task status | `node dist/src/cli.js loop status --root . [--task-id <task-id>]` |
+| Serve only the dashboard | `node dist/src/cli.js ui .` |
+
+See [Local loop walkthrough](./loop-local-run.md) and [Command reference](./command-reference.md#loop).
 
-Likewise, a public configuration or schema change must update its validator, JSON schema, installed assets, package inventory, documentation, and tests together.
+## Ownership boundaries
+
+- `.agents/aidlc/`: package-managed kernel assets.
+- `.agents/project/`: project-owned config, profiles, rules, and evaluation material.
+- `.agents/data/`: project-owned task state and derived data; never add a second lifecycle board or hand-edit it.
+
+## Mirrored runtime behaviour
+
+- TypeScript powers the package CLI; installed projects use the dependency-free mirror in `assets/aidlc/scripts/`. Lifecycle, state, gate, profile, or context changes keep parity and add coverage for both.
+- A public configuration or schema change updates validator, JSON schema, installed assets, package inventory, docs, and tests together.
+- Dual-core sync rule: after editing `assets/aidlc/scripts/lib/store.mjs`, run `npm run sync-core` so `services/aidlc-coordination/src/lifecycle-core.mjs` stays byte-identical.
 
 ## Code style and conventions
 
-Adopted as the project baseline (approved decision `D1-convention-standard` on task `refactor-source-readability`):
+Baseline (decision `D1-convention-standard`, task `refactor-source-readability`):
 
-- **Strict TypeScript, no new dependencies for tooling.** Keep `strict` mode; enforce via `npm run lint` (`tsc --noEmit`). No ESLint/Prettier for now.
-- **File size targets.** Aim for ≤250 lines per source file and ≤60 lines per function; split by domain responsibility when exceeded.
-- **Module boundaries.** One responsibility per module; a facade module may re-export a public API for compatibility (for example `src/state.ts`).
-- **Naming.** Descriptive camelCase for functions/variables, `PascalCase` for types/interfaces, `SCREAMING_SNAKE_CASE` for true constants; file names match their primary export.
-- **Error handling.** Fail with typed, one-line errors; never swallow exceptions silently; validate inputs before I/O.
-- **Dependencies.** Pass dependencies (fetch, clock, environment) explicitly as parameters; avoid module-level mutable state.
-- **Public API.** Document exported symbols with JSDoc when the contract is non-obvious.
-- **Behavior preservation.** Refactors must not change CLI output, state schema, file layout, or installed assets; run parity tests.
-- **Verification.** Run the narrowest relevant test while iterating; `npm test` + `npm run lint` before handing off.
+- **Strict TypeScript.** Keep `strict`; enforce via `npm run lint` (`tsc --noEmit`). No ESLint/Prettier or other tooling deps.
+- **Size.** ≤250 lines per file, ≤60 per function; split by responsibility.
+- **Modules.** One responsibility each; a facade may re-export a public API (e.g. `src/state.ts`).
+- **Naming.** camelCase functions/variables, `PascalCase` types, `SCREAMING_SNAKE_CASE` constants; file name matches primary export.
+- **Errors.** Typed one-line errors; never swallow; validate inputs before I/O.
+- **Dependencies.** Pass fetch, clock, environment explicitly; no module-level mutable state.
+- **Public API.** JSDoc exported symbols with non-obvious contracts.
+- **Behavior preservation.** Refactors never change CLI output, state schema, file layout, or installed assets; run parity tests.
+- **Verification.** Narrowest test while iterating; `npm test` + `npm run lint` before handoff.
 
 ## Safe implementation rules
 
-- Resolve all project-relative paths through the shared path helpers; reject traversal and symlink escape.
-- Keep installation, migration, and upgrade plans deterministic and conflict-first.
+- Resolve project-relative paths through the shared path helpers; reject traversal and symlink escape.
+- Keep install, migration, and upgrade plans deterministic and conflict-first.
 - Preserve project-owned configuration and state when changing managed assets.
-- Do not add remote profile discovery, runtime asset downloads, executable plugin hooks, registry checks, or shell-string command execution.
-- Treat human-gated lifecycle transitions as atomic, auditable state operations.
+- Never add remote profile discovery, runtime asset downloads, executable plugin hooks, registry checks, or shell-string execution.
+- Human-gated lifecycle transitions are atomic, auditable state operations.
+- Read [Architecture](./architecture.md) before changing a module boundary, migration, installed script, or bundle layout.
+
+## Contributing to prompt assets
+
+Prompt assets are the contracts under `assets/aidlc/` (`orchestrator.md`, `phase-*.md`) that `context.mjs` turns into phase packets.
+
+- Keep them compact: default packet budget is 16,000 characters (`config.context.maxChars`); optional rules and diagnostics drop first.
+- Never truncated (generation fails instead): next-action contract, phase contract, approved decisions, safety/spec anchors, task state, latest applicable evidence.
+- Heading invariants enforced by `gate-check.mjs`:
+  - Intent (`G0_confirm`): `## 📋 Problem`, `## 🗺️ Affected areas`, `## 💭 Assumptions`, `## ❓ Open questions`, `## 🎯 Scope`.
+  - Design (`G1_review`): `## 🧩 Solution per affected area`, `## 📌 Spec traceability`, `## 🔗 Cross-service contracts`, `## ⚠️ Risks / edge cases`.
+- After changing contracts, run `npm run release:check` (`--adapters opencode`) and the evaluator suite; update docs and tests in the same change. Rationale: [Design decisions](./design-decisions.md) D6.
+
+## Documentation conventions
+
+Follow [Adding or changing a page](./README.md#adding-or-changing-a-page). In addition:
+
+- A public contract change (command, config field, schema, installed asset) updates its guide and the asserting test in the same change.
+- Never duplicate canonical agent instructions from `assets/aidlc/`; link to the installed asset.
+
+## Related
 
-Read [Architecture](./architecture.md) before changing a module boundary, migration, installed script, or bundle layout.
+- [Testing and release](./testing-and-release.md)
+- [Architecture](./architecture.md)
+- [Design decisions](./design-decisions.md)
+- [Configuration](./configuration.md)

package/docs/loop-local-run.md

@@ -0,0 +1,228 @@
+# Local loop walkthrough
+
+Day-to-day operation of the loop in `local` mode on one machine: start the daemon, add tasks, watch, answer gates, resume. To enable the loop first, follow the [Loop setup runbook](./loop-runbook.md#local-mode).
+
+> [!WARNING]
+> Experimental, pre-1.0. See [Status and stability](./loop-runbook.md#status-and-stability).
+
+Commands use the published package (`npx --package @felixdotgo/aidlc-kit@0.3.0 aidlc-kit …`) or the installed launcher `./.agents/aidlc/scripts/loop.sh`; both drive the installed `loop-entry.mjs`. Source checkout: [Dogfooding this repository](./development.md#dogfooding-this-repository).
+
+## How the loop works
+
+- The **lead** runs `clarify` (gate `G0_confirm`), `plan` (`G1_review`), and `wrap` on the host, no Docker; **workers** run only `build` items (`G2_codereview`), isolated in Docker. Gates: [Operating the workflow](./operating-workflow.md).
+- Each iteration reads `state.mjs task next`, runs one agent turn on the returned `nextAction`, re-reads canonical state, and updates the checkpoint/fingerprint.
+- The loop **stops at every gate** and **never self-approves**; only a human on the trusted terminal or the signed-in dashboard approves.
+- It also stops after the per-run `maxTurns` budget (a resumed run gets a fresh one), after `maxStallTurns` unchanged turns, or at `blocked`/`terminal`/`complete` (`loop.limits`: [Configuration](./configuration.md#optional-loop-configuration)).
+- Config alone runs nothing; only `loop start` or `loop.sh up` runs the loop.
+
+## Prerequisites
+
+- Linux host with Docker (`docker info` must pass for the build phase) and a POSIX shell; Node.js ≥ 20.17.
+- Lead provider CLI (`opencode`, `codex`, or `claude`) on the host `PATH`, matching `loop.agents.lead`.
+- If any provider is `opencode`: `AIDLC_OPENCODE_MODEL` naming a model listed by `opencode models`.
+- Worker credentials per provider/model: `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, or `OPENCODE_API_KEY`. The worker image is built automatically ([Worker Docker image](#worker-docker-image)).
+
+## Set the environment
+
+Put loop variables in `.agents/loop.env` (installed as a commented template, git-ignored through `.agents/.gitignore`) or `export` them in the shell that starts the daemon; exported values win. `loop start`, `loop up`, and a dashboard-started daemon load the file.
+
+```sh
+# .agents/loop.env
+# Required for opencode unless "model" is set in opencode.json; use a model from `opencode models`:
+AIDLC_OPENCODE_MODEL=<provider/model>
+# Worker key for the build phase; read from ~/.local/share/opencode/auth.json when unset:
+# OPENCODE_API_KEY=...
+```
+
+```sh
+./.agents/aidlc/scripts/loop.sh check   # what the daemon will see; secrets are never printed
+```
+
+`AIDLC_LOOP_EVENT_LOG` is set to `.agents/data/loop/ui-events.jsonl` automatically. All variables: [runbook](./loop-runbook.md#step-2--fill-in-agentsloopenv); lookup order: [Command reference](./command-reference.md#loop).
+
+> [!IMPORTANT]
+> A running daemon keeps the environment it started with. After editing `.agents/loop.env`, run `loop.sh down`, then `loop.sh up`; `loop up` warns when the file changed after the daemon started.
+
+## Start the daemon and add tasks
+
+```sh
+./.agents/aidlc/scripts/loop.sh up      # --open launches the browser; --no-ui starts only the daemon
+./.agents/aidlc/scripts/loop.sh status  # daemon, dashboard, environment
+./.agents/aidlc/scripts/loop.sh logs    # follow the daemon log
+./.agents/aidlc/scripts/loop.sh down    # stop both; --now cancels the running turn
+```
+
+`Ctrl-C` in the `up` terminal closes only the dashboard. Windows: `.agents\aidlc\scripts\loop.cmd`, same commands.
+
+Underneath, `loop start` runs the persistent daemon in the foreground and reads no requirement; one per project (a second fails with `Loop daemon already running (pid N)`):
+
+```sh
+npx --package @felixdotgo/aidlc-kit@0.3.0 aidlc-kit loop start
+```
+
+- The daemon runs only **loop-owned** tasks: created through loop intake (`.agents/data/tasks/<id>/runtime/intake.json`) or holding a loop run record (`runtime/run.json`). An interactively created task (`state.mjs task create`) is never picked up, so the daemon cannot race an interactive lead.
+- It runs one bounded run per actionable task in turn and keeps polling after a gate or completion.
+
+Add a loop-owned task:
+
+- **Dashboard → New task** creates the task and starts the daemon if none is running.
+- **Terminal intake** reads the requirement from stdin (never an argument), at most 8192 bytes; id and title derive from the first line (`--task-id`/`--title` override).
+
+  ```sh
+  echo "Add PDF report export" | npx --package @felixdotgo/aidlc-kit@0.3.0 aidlc-kit loop intake
+  echo "Add PDF report export" | node .agents/aidlc/scripts/loop-entry.mjs intake "" .   # installed entry point
+  ```
+
+- Intake refuses (creates nothing) while an **interactive** task is actionable; finish or pause it first.
+
+Stopping (`Ctrl-C` or `SIGTERM`) is staged: first signal stops after the current turn, second cancels the in-flight agent turn, third exits immediately.
+
+- A stopped run is recorded as `stopped` (the task is **not** paused) and resumes on the next `loop start`. A terminal `Ctrl-C` also reaches the agent child, so the turn usually ends on the first press; still `stopped`, not a transport failure.
+- `aidlc-kit loop start` stays in the foreground for the whole shutdown (forwards `SIGTERM`, lets the terminal deliver `Ctrl-C`), so later presses reach the daemon.
+
+## Watch status
+
+```sh
+npx --package @felixdotgo/aidlc-kit@0.3.0 aidlc-kit loop status --task-id <task-id>
+```
+
+Prints `authority`, `record` (the loop run record), and `nextAction` (`classification`: `run_phase`, `await_user`, `blocked`, `complete`, …).
+
+## Approve a gate or send feedback
+
+Answer a gate on the trusted host terminal or the signed-in dashboard, never from the lead or a worker, never with piped input:
+
+```sh
+node .agents/aidlc/scripts/loop-gate.mjs <task-id>
+# type: approve            -> approves this exact review and advances the phase
+# type: <any other text>   -> feedback: the task stays at this gate
+```
+
+- Prints the exact review (task, phase, gate, artifact digests, and at `G2_codereview` the integration commit), then prompts `Type approve to approve this exact review, or type feedback to send guidance back to the loop:`.
+- **`approve`** is the only answer that moves the task forward; if the review changes while you type, it fails closed.
+- **Any other text is feedback**: recorded as evidence `Cancelled gate wait at <gate>: <feedback>`; the task returns to `active` at the same gate, and the next lead turn revises the review and re-presents the **same** gate.
+- The dashboard detail page offers the same actions, **Send feedback (stay at gate)** and **✓ Approve** ([dashboard](#use-the-web-dashboard)).
+
+## Resume after a gate or a pause
+
+There is **no `loop resume`** in either mode; the daemon auto-resumes every task whose `nextAction` is `run_phase` (*actionable*).
+
+- **After approving a gate**: nothing; the next poll runs the next lead turn.
+- **After a pause** (agent transport failure, per-run turn limit): the task is `paused` (`nextAction` `blocked`) and skipped. Fix the cause, then press **resume** on the dashboard or run the command below; the next poll (default about 5 s) picks it up.
+
+  ```sh
+  node .agents/aidlc/scripts/state.mjs task status <task-id> --status active   # or: loop-entry.mjs resume-task <task-id> .
+  ```
+
+- `aidlc-kit loop resume` and `loop-entry.mjs resume` fail closed with `loop resume is removed; the daemon auto-resumes actionable tasks — run 'loop start', and re-activate a paused task from the dashboard (resume) or with the task status command`.
+
+## Follow the streaming log
+
+Progress goes to **stderr** (stdout stays the final JSON):
+
+```
+━━ turn 1 · phase clarify · agent opencode ━━
+  › tool: grep
+  › tool: read
+  › command completed (exit 0)
+<stream text from the lead>
+━━ turn done ━━
+```
+
+A clarify or plan turn can take minutes without output. At a gate the daemon prints the **gate view** and moves on. Every event carries its `taskId`:
+
+| Event | Meaning |
+| --- | --- |
+| `turn_start` / `turn_end` | Turn boundary, with phase and agent. |
+| `agent_text` | Lead text, capped at 4096 characters per chunk. |
+| `agent_tool` | Tool in use (`grep`, `read`, `glob`, `shell`, …). |
+| `lifecycle_command` | Shell result and exit code. |
+| `gate` | Gate view. |
+| `daemon_start`, `daemon_poll`, `daemon_turn`, `loop_stopped` | Daemon lifecycle. |
+| `daemon_poll_error` | The task list could not be read; the daemon keeps polling. |
+| `daemon_turn_error` | A task run threw (or ended `blocked`/`reconcile`); retried with exponential backoff (poll interval doubled per failure, capped at 10 minutes). |
+| `build_deferred` | A ready build item held for a later batch. `reason`: overlaps another item, busy path held by an active assignment, unresolved assignment, or `capacity` (one item per configured worker per batch). |
+
+## Use the web dashboard
+
+```sh
+npx --package @felixdotgo/aidlc-kit@0.3.0 aidlc-kit ui .   # loop.sh up starts the same dashboard
+```
+
+Branded **Loop**, binds `127.0.0.1:4173` by default and prints `Open: http://127.0.0.1:4173` (or pass `--open`).
+
+**Access**
+
+- There is no login or session token: the dashboard is for a trusted local machine or internal network. Mutating actions (new task, resume, gate feedback, gate approve) work right away from the page.
+- Another origin, a foreign `Host` header, or a request that does not look like the dashboard's own `fetch` gets `403` ([Dashboard access](./command-reference.md#dashboard-access)). Binding to a non-loopback address prints a warning that the dashboard has no authentication.
+
+**Header and updates**
+
+- Header: authority (`authority · local`), daemon state, and a bell listing tasks needing review. The daemon pill turns amber (**daemon · N errors**) while a turn or poll keeps failing; hover for messages.
+- Pages poll about every 1.5 s and patch only what changed. An unreachable server shows a **reconnecting…** pill and polling backs off.
+- A new gate updates the bell, the tab title (`(2) Loop`), and a **Review needed** toast; with **Settings → notifications** on, a browser notification too (permission is asked only then).
+- Light/dark follows the system unless pinned in **Settings**. Shortcuts: <kbd>N</kbd> new task, <kbd>/</kbd> search, <kbd>Esc</kbd> close.
+
+**Where things live**
+
+| Where | What |
+| --- | --- |
+| Header bell | Tasks waiting at a gate (5 newest; **Load more**). A `blocked_on_user` card shows **review**, which opens the detail page. |
+| Card | Title only (id on hover and in search). Click opens the side panel and adds `?task=<task-id>` to the URL (or the full page, per **Settings**); ctrl/cmd/middle-click opens the full page in a new tab, shift-click in this tab. |
+| Side panel | Stepper (clarify → plan → build → wrap → done), artifacts, last 20 important log lines, a copy button for the id, **Open full page ↗**; at a gate, **Open review →**. |
+| Detail page `/tasks/<task-id>` | The only place with gate approval and feedback; containers, full live log — the one place to follow everything a task does. |
+| Settings (header ⚙) | Browser-only preferences: theme, live-update interval or pause, browser notifications for reviews, live log defaults, diff wrap / ignore whitespace, container log tail size, card click target. **Reset to defaults** restores them. |
+| Containers (detail page) | Every worker container the loop ran for the task (local or fleet; same layout), newest first: worker, item, turn, `running` / `exited <code>` / `signal`, start time and duration, host when recorded elsewhere. **Log** opens the raw output of that assignment (all turns, stdout and stderr unredacted) with **Follow** while it runs; the tail size comes from Settings. `docker · unavailable` means the state comes from the index only. |
+| Review panel (while `blocked_on_user`) | **Feedback** textarea + **Send feedback (stay at gate)**; **Approve** note + **✓ Approve** (popup; only **Confirm approve** sends). |
+| Approve semantics | The note is audit provenance, never feedback. A moved gate is refused with `409`. After feedback a **feedback pending** pill shows until approval; failing structural checks replace the gate view. |
+| New task (side panel) | Markdown editor. **Create task** runs loop intake and starts the daemon if none runs (stderr → `.agents/data/loop/daemon.log`); a toast shows the id or the intake error. |
+| Search and filters | Browser-only; never call the API. The **done** column shows 8 recent tasks; **Show N more** expands it. |
+| resume | On `paused` tasks; sets them back to `active`. |
+| Live log (detail page) | Lines `time · actor · what happened`, grouped by turn. **Important** (default) hides bookkeeping, **All** shows everything, **Raw JSON** shows the events. |
+| Changes `/tasks/<id>/changes` | Files and diff per work item from the commits workers recorded; otherwise the task range from the task's `baseCommit` to its `finalCommit` (or `HEAD` plus the working tree while open) — so a task driven from the terminal, or a finished task whose worker worktrees are gone, still shows its changes; last resort, the uncommitted working tree. **Wrap lines** and **Ignore whitespace** toggles. |
+
+Live log files: the log replays the last 200 events of `.agents/data/tasks/<task-id>/runtime/events.jsonl` (1 MiB, one `.1` generation; a file an older version left in `.agents/data/loop/events/` is read until `loop migrate-data` moves it), then follows live; older tasks fall back to the global `.agents/data/loop/ui-events.jsonl` (rotated to `.jsonl.1` at 5 MB), written only when `AIDLC_LOOP_EVENT_LOG` points at it. Container output is separate: `.agents/data/tasks/<task-id>/runtime/workers/<assignment>.log` (5 MiB, one `.log.1` generation) next to `index.json`, never committed. **Docs** in the header opens these guides.
+
+## Worker Docker image
+
+The build phase runs workers in Docker containers whose image contains the provider CLI (`opencode`, `codex`, or `claude`):
+
+- Dockerfiles ship with the package (`assets/aidlc/docker/Dockerfile.<provider>`); the supervisor **auto-builds** a missing image before preflight and records the name in `.agents/config.json` (`loop.workerImage`), so `AIDLC_WORKER_DOCKER_IMAGE` is not needed.
+- Build ahead of time (default provider `opencode`; default tag `aidlc-worker-<provider>:local`):
+
+  ```sh
+  npx @felixdotgo/aidlc-kit loop worker-image --provider opencode   # or codex | claude
+  ```
+
+- Images named `aidlc-worker-*-test:local` contain only a fake CLI for tests. The real image is `node:24-bookworm-slim` (Debian/glibc, because `opencode` is a dynamically linked ELF) with the CLI from `npm install -g`.
+- Each worker container is started with labels `aidlc.task`, `aidlc.item`, `aidlc.worker`, and `aidlc.assignment` (`docker ps --filter label=aidlc.task=<task-id>` lists a task's workers), and its stdout/stderr are teed unredacted into the task's `runtime/workers/` log while the live log keeps only summaries.
+- The container runs non-root and `--read-only`, so the CLI must be on the system `PATH` (npm global → `/usr/local/bin`). `opencode` uses `@opencode/cli` (OpenCode 2), **not** `opencode-ai` (OpenCode 1).
+- Worker credentials come from the environment, per model: `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, or `OPENCODE_API_KEY`. Preflight runs `docker run … --entrypoint <cli> --version`; a missing or invalid binary fails before any worker starts.
+
+## Quick lead-only run
+
+A single lead with no Docker or workers, using the installed loop runner directly:
+
+```sh
+export AIDLC_OPENCODE_MODEL=<provider/model>
+
+node .agents/aidlc/scripts/loop.mjs run <task-id> --agent opencode --max-turns 12 --root .
+node .agents/aidlc/scripts/loop.mjs status <task-id> --root .
+node .agents/aidlc/scripts/loop.mjs resume <task-id> --root .
+```
+
+The JSON output reports `status` (`gate`, `paused`, `blocked`, or `complete`) with `stopReason` and `nextAction`.
+
+## Troubleshooting
+
+- [Loop stops, pauses, or never starts](./troubleshooting.md#loop-stops-pauses-or-never-starts)
+- [Dashboard live log or actions do nothing](./troubleshooting.md#dashboard-live-log-or-actions-do-nothing)
+- [Loop leases, locks and claims](./troubleshooting.md#loop-leases-locks-and-claims) — "already running", unapprovable gate, stuck claims
+- [Build items deferred](./troubleshooting.md#build-items-deferred-or-build-dispatch-failure-unresolved-assignment) — `build_deferred`, `build dispatch failure`
+
+## Related
+
+- [Loop setup runbook](./loop-runbook.md) — enabling and configuring the loop.
+- [Configuration](./configuration.md#optional-loop-configuration) — `loop.*` fields.
+- [Command reference](./command-reference.md#loop) — all loop flags and environment variables.
+- [AI-DLC Coordination service](./coordination-service.md) — fleet (multi-machine) deployment.