@felixdotgo/aidlc-kit 0.1.0 → 0.2.0

package/docs/loop-runbook.md

@@ -0,0 +1,235 @@
+# Loop setup runbook
+
+> [!WARNING]
+> The loop is **experimental** and pre-1.0 (`0.x`): the `loop.*` fields, provider mappings, environment variables, and diagnostics can change incompatibly in any release before `1.0.0`. **Local mode is usable** on a single Linux host today; **fleet mode is still under active development** and is not yet stable.
+
+This runbook walks through the three most common operational journeys for the end-to-end loop, in order:
+
+1. [Enable the loop from `off`](#enable-the-loop-from-off)
+2. [Run the loop in `local` mode](#local-mode)
+3. [Run the loop across multiple machines (`fleet`)](#fleet-multi-machine)
+
+It is a step-by-step guide, not a reference. For the full field, flag, and environment reference, see [Configuration](./configuration.md), [Command reference](./command-reference.md), and [AI-DLC Coordination service](./coordination-service.md); this runbook links to those pages for depth instead of repeating them.
+
+## The loop in one paragraph
+
+The loop drives a task end-to-end. A **lead** agent runs the clarify, plan, and wrap phases, while **workers** execute build items. `local` mode uses the project's canonical local state (`state.mjs`) with a host-executed lead and Docker-isolated workers on one Linux host. `fleet` mode delegates authority to a coordination service and can spread workers across machines. Both modes use the same loop daemon, intake, and dashboard; only the authority differs. Selecting a mode only configures the loop; nothing runs until you call `aidlc-kit loop start` explicitly.
+
+## Enable the loop from `off`
+
+`loop.mode` defaults to `off` (an absent `loop` field also means `off`). Enabling it means setting `loop.mode` to `local` or `fleet` and providing `loop.agents` with one `lead` and one or more named `workers`, each mapped to `codex`, `claude`, or `opencode`:
+
+```json
+{
+  "loop": {
+    "mode": "local",
+    "agents": { "lead": "codex", "workers": { "worker-a": "codex", "worker-b": "opencode" } }
+  }
+}
+```
+
+### Step 1 — Choose how to write the config
+
+Pick one of three ways to set `loop.mode` and `loop.agents`:
+
+- **Edit `.agents/config.json` directly.** This is the project-owned config; the fields are described in [Configuration](./configuration.md#optional-loop-configuration).
+- **Use `init`** for a new install:
+  ```sh
+  npx --package @felixdotgo/aidlc-kit@0.2.0 aidlc-kit init . \
+    --loop-mode local --loop-lead codex --loop-workers a=codex,b=opencode
+  ```
+- **Use the human-only `upgrade`** for an existing install, which preserves the existing config when you omit the loop flags and lets an authorised human review the change before applying:
+  ```sh
+  npx --package @felixdotgo/aidlc-kit@0.2.0 aidlc-kit upgrade . \
+    --loop-mode local --loop-lead codex --loop-workers a=codex,b=opencode --dry-run
+  ```
+
+### Step 2 — Verify the loop is enabled
+
+`aidlc-kit loop start` fails closed unless the config is complete:
+
+- `loop.mode` must be `local` or `fleet`.
+- `loop.agents` must have a valid `lead` provider and at least one valid `worker` mapping (`Loop requires a configured lead and worker providers`).
+- The requested `--mode` must match the configured `loop.mode` (`Requested mode does not match configured authority`).
+
+These checks run on any `aidlc-kit loop` invocation before anything starts, so a wrong configuration fails closed with a clear message rather than silently running. A valid configuration is only a selection: it does not install or start a service, authorise an upgrade, or grant gate approval. Run `aidlc-kit loop start` to actually start the loop, and keep provider credentials out of the config object.
+
+## Local mode
+
+Local mode is the single-machine journey. The lead runs on the host (Codex, Claude Code, or OpenCode) for clarify/plan/wrap, and build items fan out to Docker-isolated workers. It uses the canonical local state and requires local authority; see [Command reference](./command-reference.md#loop) for the authority boundary.
+
+### Prerequisites
+
+| Requirement | Notes |
+| --- | --- |
+| Linux host | Loop/fleet features require Docker and a POSIX shell; `loop-local-workers.mjs` rejects non-Linux hosts. |
+| Docker engine | The worker batch preflights `docker info` and the worker image. |
+| Non-root host user | Docker workers require a non-root uid/gid. |
+| Worker Docker image | Auto-built from the packaged Dockerfile on first build dispatch (`aidlc-kit loop worker-image`); set `AIDLC_WORKER_DOCKER_IMAGE` only to override the per-provider default. |
+| Provider credentials | Exported in the environment; never written into `.agents/config.json`. |
+
+### Step 1 — Configure `local`
+
+Set `loop.mode` to `local` with a lead and workers (see [Enable the loop from `off`](#enable-the-loop-from-off)):
+
+```json
+{
+  "loop": {
+    "mode": "local",
+    "agents": { "lead": "codex", "workers": { "worker-a": "codex", "worker-b": "opencode" } }
+  }
+}
+```
+
+### Step 2 — Set the environment
+
+| Variable | Required | Purpose |
+| --- | --- | --- |
+| `AIDLC_WORKER_DOCKER_IMAGE` | no | Optional single-image override. The per-provider default `aidlc-worker-<provider>:local` is auto-built and recorded in `loop.workerImage`. |
+| `AIDLC_OPENCODE_MODEL` | if any provider is `opencode` | `provider/model[#variant]` (for example `opencode-go/gpt-6-luna`). The turn fails closed without a valid value. |
+| `OPENAI_API_KEY` | if a provider is `codex` | Codex worker credential. |
+| `ANTHROPIC_API_KEY` | if a provider is `claude` | Claude Code worker credential. |
+| `OPENCODE_API_KEY` | if a provider is `opencode` | OpenCode worker credential. The key follows the model provider: `openai/` → `OPENAI_API_KEY`, `anthropic/` → `ANTHROPIC_API_KEY`, otherwise `OPENCODE_API_KEY`. |
+| `AIDLC_LOCAL_WORKTREES_ROOT` | no | Root for worker worktrees; defaults to a system temp directory. It must be outside the integration checkout. |
+| `AIDLC_LOOP_EVENT_LOG` | no (see note) | Path to a JSONL event-log sidecar that feeds the web dashboard live log. The `aidlc-kit ui` **New task** action (when it starts the daemon) sets it to `.agents/data/loop/ui-events.jsonl` automatically; a **manually started** daemon must set it to the same path or the dashboard live log stays empty. |
+
+Docker workers (local and fleet) authenticate OpenCode from the environment and redirect OpenCode's XDG data/config roots into the worker's ephemeral HOME. Only the **isolated lead** container does not support OpenCode yet (`OpenCode workers require file-based credentials and are not available in isolated containers yet`); the daemon runs the lead on the host, so an OpenCode lead works there.
+
+### Step 3 — Build the worker image (usually automatic)
+
+Build the worker image for each provider you use, or let the supervisor auto-build it on the first build dispatch:
+
+```sh
+npx @felixdotgo/aidlc-kit loop worker-image --provider codex    # → aidlc-worker-codex:local
+npx @felixdotgo/aidlc-kit loop worker-image --provider opencode # → aidlc-worker-opencode:local
+```
+
+The command records the tag into `loop.workerImage`; the local supervisor reuses it and auto-builds any missing per-provider image before dispatch. The batch preflight still inspects the image and runs each provider CLI with `--version` inside the container, so a missing or mismatched image fails before any worker starts. See [Testing and release](./testing-and-release.md#loop-docker-and-postgresql-verification) for the fixture build pattern used by the test suite.
+
+### Step 4 — Start the daemon, add tasks, and watch
+
+`start` launches the singleton daemon (one per project) and reads no requirement. Add tasks with the web dashboard **New task** or loop intake, which reads the requirement from stdin (capped at 8192 bytes) and never from an argument:
+
+```sh
+npx --package @felixdotgo/aidlc-kit@0.2.0 aidlc-kit loop start
+echo "Add PDF report export" | npx --package @felixdotgo/aidlc-kit@0.2.0 aidlc-kit loop intake
+```
+
+The daemon runs only loop-owned tasks (created through intake), one bounded run per task in turn, and keeps polling after a task reaches a gate or completes. Stop it with `Ctrl-C`: the first signal stops after the current turn, the second cancels the turn, the third exits. A stopped run is not a pause; the task continues on the next `start`.
+
+`status` prints the canonical task and its derived next action:
+
+```sh
+npx --package @felixdotgo/aidlc-kit@0.2.0 aidlc-kit loop status --task-id <task-id>
+```
+
+There is no `loop resume`. After a gate approval the daemon continues the task on its next poll. A **paused** task is not actionable: fix the cause, then press **resume** on the dashboard or run `node .agents/aidlc/scripts/state.mjs task status <task-id> --status active`.
+
+As an alternative to typing these commands repeatedly, `aidlc-kit ui` starts a web dashboard to view task status, add tasks, resume paused tasks, and approve gates; it prints a login URL that signs the browser in. See [Command reference](./command-reference.md#ui) and [Loop local run](./loop-local-run.md#57-web-dashboard-aidlc-kit-ui).
+
+### Step 5 — Approve gates from the trusted host terminal
+
+Gate approval happens only through a human — the trusted host terminal or the signed-in dashboard — never from a lead or worker container, and never via piped input:
+
+```sh
+node .agents/aidlc/scripts/loop-gate.mjs <task-id>
+```
+
+The command 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:`. Type `approve` to approve that exact review. If the review changes while you type, it fails closed and asks you to inspect the new review.
+
+## Fleet (multi-machine)
+
+Fleet mode spreads the loop across machines through the coordination service. It uses `remote-state.mjs` instead of the local `state.mjs`, and the remote workspace is canonical. Deployment, storage (SQLite for one host, PostgreSQL for multiple hosts), and credentials are covered in [Coordination service](./coordination-service.md); this section keeps the loop-specific steps and links there for the rest.
+
+### Prerequisites
+
+- A deployed coordination service with PostgreSQL for a multi-host topology, and a shared Git remote — see [Coordination service](./coordination-service.md#multi-machine-loop-deployment).
+- `loop.mode` set to `fleet` with a lead and workers matching your worker machines.
+- Three distinct credential classes (`MCP_FLEET_LEAD_TOKEN`, `MCP_FLEET_REVIEWER_TOKEN`, and `MCP_FLEET_WORKER_TOKENS`) configured on the service.
+
+### Step 1 — Configure `fleet`
+
+```json
+{
+  "loop": {
+    "mode": "fleet",
+    "agents": { "lead": "codex", "workers": { "worker-a": "codex", "worker-b": "opencode" } }
+  }
+}
+```
+
+### Step 2 — Set lead-machine environment
+
+| Variable | Required | Purpose |
+| --- | --- | --- |
+| `AIDLC_FLEET_URL` | yes | The full HTTPS `/mcp` URL of the service. |
+| `AIDLC_FLEET_WORKSPACE` | yes | The remote workspace id. |
+| `AIDLC_FLEET_TOKEN` | yes | The lead credential. |
+| `AIDLC_FLEET_INTEGRATION_BRANCH` | yes | The shared integration branch; it must exist on the remote. |
+| `AIDLC_FLEET_PROJECT_ROOT` | no | Set automatically by `aidlc-kit loop`; required only for the direct `remote-state.mjs` / fleet-runner client. When set explicitly it must match the loop root. |
+| `AIDLC_FLEET_WORKER_IDS` / `AIDLC_FLEET_WORKER_PROVIDERS` | no | Derived from `loop.agents.workers`; when set explicitly they must match it. |
+| `AIDLC_FLEET_GIT_REMOTE` | no | Git remote name; defaults to `origin`. |
+| `AIDLC_FLEET_MAX_TURNS`, `AIDLC_FLEET_TURN_TIMEOUT_MS`, `AIDLC_FLEET_MAX_STALL_TURNS`, `AIDLC_FLEET_POLL_MS` | no | Override `loop.limits` and `loop.pollMs`, which are the defaults. |
+
+The lead agent comes from `loop.agents.lead`. Do not export `AIDLC_FLEET_REVIEWER_TOKEN` in the lead shell; the daemon strips it from every lead and worker process anyway.
+
+### Step 3 — Start the daemon and add tasks
+
+`aidlc-kit loop start --mode fleet` preflights the service (`fleet_get`) and the remote integration branch, then starts the same daemon as local mode, failing closed instead of falling back to local:
+
+```sh
+npx --package @felixdotgo/aidlc-kit@0.2.0 aidlc-kit loop start --mode fleet
+echo "Add PDF report export" | npx --package @felixdotgo/aidlc-kit@0.2.0 aidlc-kit loop intake --mode fleet
+```
+
+Intake creates the remote task under a short lead claim and writes `.agents/data/tasks/<task-id>/loop-intake.json` with `authority: "fleet"` on this lead machine. Only those tasks are fleet loop-owned; a remote task created any other way is never picked up. For each actionable task the daemon runs the fleet supervisor in a bounded mode: it claims the supervisor lease, runs fenced lead turns and worker dispatch through the coordinator, publishes the gate snapshot with its checkpoint, then returns and releases the lease. After the reviewer approves, the next poll re-claims the task and continues. An unreachable service shows up as `daemon_poll_error` and does not stop the daemon. Shutdown, backoff, and `status` behave as in local mode; there is no `loop resume` (re-activate a paused task with the dashboard **resume**).
+
+The underlying fleet runner is also available directly from the service deployment (the installed `.agents/aidlc-coordination/`, or `dist/services/aidlc-coordination/` from a source checkout):
+
+```sh
+node .agents/aidlc-coordination/src/fleet-run.mjs supervisor <task-id>
+node .agents/aidlc-coordination/src/fleet-run.mjs coordinator <task-id> --once
+```
+
+Run directly, `supervisor` waits at each gate for the reviewer approval and resumes automatically; it never approves a gate.
+
+### Step 4 — Run a worker on each worker machine
+
+On each worker machine, point at the same `AIDLC_FLEET_URL`, workspace, and `AIDLC_FLEET_PROJECT_ROOT` (a checkout of the project), use that worker's own `AIDLC_FLEET_TOKEN`, then set:
+
+| Variable | Required | Purpose |
+| --- | --- | --- |
+| `AIDLC_FLEET_WORKER_ID` | yes | This machine's worker id (must be a configured worker). |
+| `AIDLC_FLEET_WORKTREES_ROOT` | yes | Root for this worker's isolated worktrees. |
+| `AIDLC_FLEET_WORKER_AGENT` | recommended | This worker's provider (`codex`, `claude`, or `opencode`); falls back to this worker's entry in `AIDLC_FLEET_WORKER_PROVIDERS`, then to `AIDLC_FLEET_AGENT`. A worker with a provider rejects jobs for another provider. |
+| `AIDLC_WORKER_DOCKER_IMAGE` | no | Image override. Otherwise the image is `loop.workerImage[provider]` from the project config or `aidlc-worker-<provider>:local`, auto-built from the packaged Dockerfile when missing. Without a known provider this variable is required. |
+| `AIDLC_OPENCODE_MODEL` | if the provider is `opencode` | `provider/model[#variant]`. |
+| worker credential | yes | `OPENAI_API_KEY` (codex), `ANTHROPIC_API_KEY` (claude), or for opencode the key matching the model prefix (`openai/`, `anthropic/`, otherwise `OPENCODE_API_KEY`). |
+
+Run one bounded assignment per invocation, or omit `--once` to keep polling:
+
+```sh
+node .agents/aidlc-coordination/src/fleet-run.mjs worker --once
+```
+
+The worker resolves the image to its immutable `sha256:` id and preflights Docker and the provider CLI before claiming work.
+
+### Step 5 — Approve gates as the reviewer
+
+Use the reviewer credential in a connected reviewer conversation:
+
+```sh
+node .agents/aidlc/scripts/remote-state.mjs gate inbox
+node .agents/aidlc/scripts/remote-state.mjs gate approve <task-id> --snapshot <snapshot-id> --source "<explicit user approval>"
+```
+
+The approve command checks that the snapshot is still current and uses the reviewer-only service operation. Run it only after the human explicitly approves the packet. Alternatively, start `aidlc-kit ui` with the fleet environment from Step 2 plus the reviewer credential (`AIDLC_FLEET_REVIEWER_TOKEN` or `--reviewer-token-file`): the dashboard then approves the current snapshot itself, passing the credential only to that one approve process. Without a reviewer credential the dashboard shows these commands instead and its approve API returns `403`.
+
+## Authority boundary
+
+`local` mode uses the canonical local state and requires local authority; `fleet` mode uses `remote-state.mjs`. When `AIDLC_FLEET_URL` is set, local lifecycle, context, gate, assignment, and standalone loop commands reject use so an unattended lead cannot accidentally mutate a second local authority. Unset `AIDLC_FLEET_URL` only when deliberately returning to a local run. See [Coordination service](./coordination-service.md#state-and-synchronization-contract) for the remote canonical-state contract.
+
+## Where to go next
+
+- [Operating the workflow](./operating-workflow.md) — gates, approvals, handoffs, and task ownership.
+- [Troubleshooting](./troubleshooting.md) — symptom/error-code recovery, including fleet authority and Docker worker image diagnostics.

package/docs/operating-workflow.md

@@ -116,8 +116,11 @@ See [Configuration](./configuration.md) for project customisation and [Command r
 
 ## Optional end-to-end loop
 
-When the project enables `loop.mode`, `aidlc-workflow loop start` accepts a requirement once (interactive prompt or stdin), creates exactly one task under the configured authority, and runs the loop to the first gate or to completion. `loop status` reports the canonical task and gate checkpoint; `loop resume` continues after an interruption. The intake is idempotent: re-running `start` with the same task ID and requirement reuses the existing task, and it refuses to create a second task while another one is actionable.
+> [!WARNING]
+> **Local loop mode is usable** today; **fleet mode and the coordination service are still under active development**. The loop is **experimental** — because the package is still pre-1.0 (`0.x`), its commands, configuration, and recovery behaviour can change incompatibly in any release before `1.0.0`.
+
+When the project enables `loop.mode`, `aidlc-kit loop start` accepts a requirement once (interactive prompt or stdin), creates exactly one task under the configured authority, and runs the loop to the first gate or to completion. `loop status` reports the canonical task and gate checkpoint; `loop resume` continues after an interruption. The intake is idempotent: re-running `start` with the same task ID and requirement reuses the existing task, and it refuses to create a second task while another one is actionable.
 
 The loop never approves a gate itself. At each gate it publishes the review packet and waits; in local mode approval happens only through the trusted host terminal command, and in fleet mode only through the reviewer credential against the published snapshot and revision. After a real approval the running supervisor re-reads the canonical state and checkpoint, re-acquires its fenced lease, and resumes automatically. If the supervisor is not running at approval time, restart it and it reconciles from the checkpoint; a consumed, stale, or mismatched checkpoint stops for manual reconciliation instead of guessing. Restarting never resumes a paused or handed-off task, an outdated snapshot, or an uncertain Git result — those require the documented recovery actions.
 
-The supervisor runs in the foreground or under a process supervisor you choose; there is no background daemon. Workers execute in Docker with their own scoped credentials and never inherit host access. Host-executed lead turns support `codex`, `claude`, or `opencode`; container-isolated lead turns, local Docker worker batches, and fleet worker containers reject `opencode` because it requires file-based credentials, returning `OpenCode workers require file-based credentials and are not available in isolated containers yet` instead of falling back to the host. When the loop uses `opencode`, set `AIDLC_OPENCODE_MODEL` to a `provider/model[#variant]` value. See [Command reference](./command-reference.md) for the loop commands and environment, and [Coordination service](./coordination-service.md) for fleet deployment, backends, and recovery.
+The supervisor runs in the foreground or under a process supervisor you choose; there is no background daemon. Workers execute in Docker with their own scoped credentials and never inherit host access. Host-executed lead turns support `codex`, `claude`, or `opencode`; container-isolated lead turns and fleet worker containers reject `opencode` because it requires file-based credentials, returning `OpenCode workers require file-based credentials and are not available in isolated containers yet` instead of falling back to the host. Local Docker worker batches accept `opencode` via environment credentials with OpenCode's XDG roots redirected into the worker's ephemeral HOME. When the loop uses `opencode`, set `AIDLC_OPENCODE_MODEL` to a `provider/model[#variant]` value. See [Command reference](./command-reference.md) for the loop commands and environment, and [Coordination service](./coordination-service.md) for fleet deployment, backends, and recovery.

package/docs/testing-and-release.md

@@ -16,6 +16,10 @@ npm test
 
 If a test depends on child processes and a sandbox returns `EPERM`, rerun it in an appropriate local environment before deciding that the product failed.
 
+## Lifecycle core sync
+
+The TypeScript core (`src/state.ts`) and the dependency-free installed/runtime core (`assets/aidlc/scripts/lib/store.mjs`, mirrored to `services/aidlc-coordination/src/lifecycle-core.mjs`) must stay byte-identical. After editing `assets/aidlc/scripts/lib/store.mjs`, run `npm run sync-core` to copy it into the coordination service, then commit both files together. The byte-identity conformance test (`test/unit/lifecycle-core-conformance.test.ts`) enforces this link.
+
 ## Focused tests
 
 Build first, then invoke a compiled test file directly:
@@ -77,7 +81,7 @@ AIDLC_TEST_PROJECT="$(mktemp -d /tmp/aidlc-project.XXXXXX)"
 
 npm run build
 npm pack --pack-destination "$AIDLC_PACK_DIR"
-tar -xzf "$AIDLC_PACK_DIR/felixdotgo-aidlc-kit-0.0.1.tgz" -C "$AIDLC_EXTRACT_DIR"
+tar -xzf "$AIDLC_PACK_DIR/felixdotgo-aidlc-kit-0.2.0.tgz" -C "$AIDLC_EXTRACT_DIR"
 node "$AIDLC_EXTRACT_DIR/package/dist/src/cli.js" init "$AIDLC_TEST_PROJECT" --agent codex --dry-run
 node "$AIDLC_EXTRACT_DIR/package/dist/src/cli.js" init "$AIDLC_TEST_PROJECT" --agent codex --yes
 node "$AIDLC_EXTRACT_DIR/package/dist/src/cli.js" status "$AIDLC_TEST_PROJECT"
@@ -100,7 +104,7 @@ node dist/dev/evaluator/cli.js run --runner local-simulated
 
 Runners exchange JSON, and reports capture transport, transcript, normalised events, usage, and diagnostics. Real Codex, Claude Code, or OpenCode runs can consume credentials and model budget; they are not required for ordinary development verification.
 
-The pinned `opencode-gpt6` runner uses adapter `opencode` with model `opencode-go/gpt-6-luna`, version `opencode-2.2.0`, protocol version `2`, real evidence, and a 300000 ms timeout. It runs `opencode run --format json --standalone --auto` once per turn, resumes with `--session`, and writes `opencode.json` containing `{"mcp": {}}` into each scenario workspace so project MCP servers do not leak into the evaluation. OpenCode resolves its project directory from the inherited `PWD`, not the spawned process working directory, so the runner and the loop driver pin `PWD` to the workspace; without that pin, commands would silently run in the invoking repository. OpenCode has no environment-credential mode, so the runner reuses the local Console authentication; the residual risk is that user plugins or agents can still load. That isolation is workspace configuration, not a security boundary.
+The pinned `opencode-beam` runner uses adapter `opencode` with model `opencode-go/beam-free`, version `opencode-2.2.0`, protocol version `2`, real evidence, and a 300000 ms timeout; the `economy` category is pinned to the lighter `opencode-go/beam-free#medium` variant so heavier turns stay inside that timeout. It runs `opencode run --format json --standalone --auto` once per turn, resumes with `--session`, and writes `opencode.json` containing `{"mcp": {}}` into each scenario workspace so project MCP servers do not leak into the evaluation. OpenCode resolves its project directory from the inherited `PWD`, not the spawned process working directory, so the runner and the loop driver pin `PWD` to the workspace; without that pin, commands would silently run in the invoking repository. OpenCode has no environment-credential mode, so the runner reuses the local Console authentication; the residual risk is that user plugins or agents can still load. That isolation is workspace configuration, not a security boundary.
 
 The release-eligible `aidlc-official-agentic` suite is version `2.5.0`. Its `supported-adapters` scenario asks the agent to explain that the workflow supports Codex, Claude Code, and OpenCode without executing remote code or shell strings. The suite also includes `build-multi-item-continuation`, which starts with three canonical build items and requires one agent run to complete all of them, record verification/review evidence, and stop only at a ready G2. This complements unit guards by exercising the model-facing continuation contract.
 
@@ -126,17 +130,17 @@ Publishing, tagging, committing, and pushing are separate human-authorised actio
 
 ## First npm publication
 
-The first release is `@felixdotgo/aidlc-kit@0.0.1`, with public access and the `latest` dist-tag. Complete the release checks and the project's human review gates before publishing.
+The first release is `@felixdotgo/aidlc-kit@0.1.1`, with public access and the `latest` dist-tag. Complete the release checks and the project's human review gates before publishing.
 
 From the repository root, sign in to an npm account with permission to publish to the `@felixdotgo` scope and confirm the active account:
 
 ```sh
 npm login --registry https://registry.npmjs.org
 npm whoami --registry https://registry.npmjs.org
-npm view @felixdotgo/aidlc-kit@0.0.1 version --registry https://registry.npmjs.org
+npm view @felixdotgo/aidlc-kit@0.1.1 version --registry https://registry.npmjs.org
 ```
 
-An unpublished package normally returns `404` from `npm view`; that response does not establish scope ownership or publish permission. If `0.0.1` already exists, stop: npm versions cannot be overwritten. If `npm whoami` returns `401`, sign in again before publishing.
+An unpublished package normally returns `404` from `npm view`; that response does not establish scope ownership or publish permission. If `0.1.1` already exists, stop: npm versions cannot be overwritten. If `npm whoami` returns `401`, sign in again before publishing.
 
 After inspecting the local tarball and documentation, publish from the repository root:
 
@@ -149,8 +153,8 @@ npm publish --access public --tag latest --registry https://registry.npmjs.org
 Confirm the published version, dist-tag and artifact metadata:
 
 ```sh
-npm view @felixdotgo/aidlc-kit@0.0.1 version dist.tarball dist.integrity --json --registry https://registry.npmjs.org
+npm view @felixdotgo/aidlc-kit@0.1.1 version dist.tarball dist.integrity --json --registry https://registry.npmjs.org
 npm view @felixdotgo/aidlc-kit dist-tags --json --registry https://registry.npmjs.org
 ```
 
-Expect version `0.0.1`, a tarball URL and integrity value, and `latest` pointing to `0.0.1`. Git tags, GitHub releases, commits, and pushes require their own delivery authorisation.
+Expect version `0.1.1`, a tarball URL and integrity value, and `latest` pointing to `0.1.1`. Git tags, GitHub releases, commits, and pushes require their own delivery authorisation.

package/docs/troubleshooting.md

@@ -0,0 +1,125 @@
+# Troubleshooting
+
+Symptom- and error-code-oriented recovery guide for the AI-DLC workflow. Read [Operating the workflow](./operating-workflow.md) for the lifecycle model and [Command reference](./command-reference.md) for flag details.
+
+## State lock held or times out
+
+- Lock files live at `.agents/data/state/.aidlc-state.lock` and its companion `.agents/data/state/.aidlc-state.lock.guard`.
+- Defaults: acquisition times out after **5 seconds** (`timeoutMs` 5000) and treats a lock as stale only when it is **30 seconds** old (`staleMs` 30000) **and** its owning PID is no longer alive.
+- Contention under concurrent agents is normal; every mutation acquires the lock, including read-only `task list` and `task show`. Wait or serialize callers rather than deleting a live lock.
+- A dead PID lets the lock be reclaimed automatically. Do not delete a lock whose PID is still alive — that corrupts in-flight state.
+- Partially written or corrupt lock records are now reclaimed automatically instead of wedging mutations (recent release note). The reclamation is best-effort: if it fails, inspect the file before retrying.
+- When a lock is corrupt, the owning process may be unable to release it; remove only an unreadable/partial file after confirming no live process holds it.
+
+## Corrupt state or assignment files
+
+- Corrupt local assignment files surface as `Corrupt local assignments for <task-id>`; corrupt loop/lease records surface as `Corrupt loop lease` / `Corrupt loop run record`. State JSON problems surface as `<label> is corrupted or unreadable: ...`.
+- Restore from `.agents/data/state/backups/upgrade-<timestamp>` created by `upgrade`/migration, or from git. These backups are the audit trail for managed writes.
+- `assignment-store` also guards against a corrupt assignment lock file (`Corrupt assignment lock for <task-id>`); inspect it before retrying rather than blindly deleting.
+- Never hand-edit canonical state to "fix" corruption; restore from backup or git and re-run `state.mjs state migrate` if schema-versioned.
+
+## `LESSON_INDEX_STALE` warning
+
+- A mutation committed but the derived lesson-index rebuild failed. The mutation stays committed and the exit code stays `0`.
+- Run `node .agents/aidlc/scripts/state.mjs lesson rebuild` (local authority required; throws `Fleet authority is configured` if `AIDLC_FLEET_URL` is set — use `remote-state.mjs`).
+
+## `RENDER_FAILED` warning
+
+- A mutation committed but the workplan render failed.
+- Run `node .agents/aidlc/scripts/render.mjs <task-id>` (or `--all`).
+
+## Continuation guard exit code 2 (`CONTINUATION_REQUIRED`)
+
+- `task-next.mjs <task-id> --require-stop` exits `2` when `continuation.code = CONTINUATION_REQUIRED`. This is an expected pause, not a failure.
+- Execute `continuation.command` instead of replying. Do not treat exit code 2 as an error.
+- If a premature final response already slipped out, recover in the very next turn by running `task next <task-id>` and executing its returned command. Never re-approve a gate to catch up.
+
+## Gate-check structural errors
+
+`gate-check.mjs` returns diagnostics; fix the underlying artifact or record, never skip the check. Codes:
+
+- `INTENT_HEADING` — intent artifact missing one of the five required headings: `## 📋 Problem`, `## 🗺️ Affected areas`, `## 💭 Assumptions`, `## ❓ Open questions`, `## 🎯 Scope`.
+- `DESIGN_HEADING` — design artifact missing one of the four required headings: `## 🧩 Solution per affected area`, `## 📌 Spec traceability`, `## 🔗 Cross-service contracts`, `## ⚠️ Risks / edge cases`.
+- `UNRESOLVED_DECISION` — a decision is still `unresolved`; resolve every decision before presenting G1.
+- `TASKS_OPEN` — build tasks remain open (`todo`/`in_progress`).
+- `VERIFY_EVIDENCE` — latest post-G1 verification evidence must pass for every affected area.
+- `REVIEW_EVIDENCE` — latest post-G1 code-review evidence must pass.
+- `REPAIR_BOUND` — repair bound exhausted (3 failed verify cycles per area, or 2 failed review passes); record a durable handoff instead of presenting G2.
+- `TASK_UNKNOWN` — unknown task id.
+- `GATE_STATE` — task is at a different gate than requested.
+- `TASK_TERMINAL` — terminal task cannot approve a gate.
+- `TASK_HANDOFF` — task has an unresolved handoff.
+- `TASK_ID` — task key and id differ.
+- `TASK_FIELDS` — task title or affected areas missing.
+- `PARTITION_SCOPE` / `PARTITION_OVERLAP` — Approve plan parallel work partition; see [below](#parallel-work-partition-partition_overlap--partition_scope).
+- `GATE_OK` — informational; no `ERROR` diagnostics (warnings may still be listed).
+
+## Parallel work partition (`PARTITION_OVERLAP` / `PARTITION_SCOPE`)
+
+The Approve plan check (`gate-check.mjs <task-id>`) inspects build items so parallel workers never edit the same files:
+
+- `PARTITION_SCOPE` — an open item has no owned paths. Give it a scope: `node .agents/aidlc/scripts/state.mjs task item <task-id> <item-id> --status todo --label "<label>" --owns src/a,docs/b`.
+- `PARTITION_OVERLAP` — two items that can run concurrently (no direct or transitive `dependsOn` between them) own overlapping paths. Overlap is per path segment: `src` overlaps `src/a.ts`, but not `srcx`. Split the paths, merge the items, or order them with `--depends-on <item-id>`.
+- Severity follows the loop: `ERROR` when `loop.mode` is `local` or `fleet` (or inside a fleet-enabled coordination service), so the gate cannot be presented; `WARN` when the loop is `off`, and the gate still passes with `GATE_OK`.
+- The rendered workplan shows each item's scope as `owns: … · after: …`; the intent and design templates carry **Work boundaries** / **Parallel work partition** sections to plan it.
+
+## Build items deferred or `build dispatch failure: Unresolved assignment`
+
+- A `build_deferred` event (with `itemId` and `reason`) is not an error. The local scheduler dispatches a batch of non-overlapping ready items, at most one per configured worker, and defers the rest (`overlaps <item>`, `busy path held by an active assignment`, `unresolved assignment`, `capacity`) to a later batch. The fleet coordinator applies the same overlap rule.
+- The task pauses with `build dispatch failure: Unresolved assignment <id> (<state>) for <item> holds <paths>; inspect it, then run node .agents/aidlc/scripts/assignment.mjs reconcile <task-id> or … release <task-id> <assignment-id>` when a `reported` or `uncertain` assignment of an unfinished item (or a still-`leased` one, reported as `Active assignment`) blocks every ready item. The loop never releases it automatically.
+- Inspect it with `node .agents/aidlc/scripts/assignment.mjs show <task-id>` and the worker's branch or worktree. Run `assignment.mjs reconcile <task-id>` when the outcome is recorded, or `assignment.mjs release <task-id> <assignment-id>` only after confirming the work is abandoned. Then re-activate the task (dashboard **resume** or `state.mjs task status <task-id> --status active`).
+- `Build item <item> requires an owned path scope for Docker dispatch` means an item reached build without `--owns`; fix the plan (see `PARTITION_SCOPE`).
+
+## `Git worktree must be clean before handoff or integration`
+
+- The lead checkout must have no uncommitted or untracked changes before a worker handoff or integration. Commit, stash, or remove them, then re-activate the task.
+- Host-local loop files under `.agents/data/loop/` (daemon lock, `daemon.log`, `ui-events.jsonl`) are ignored by this check, so a running daemon or dashboard does not trigger it.
+
+## `Task already exists` / actionable-task guard
+
+- `task create` fails with `Task already exists: <id>` when the id is already present; resume with `task next <id>`.
+- While another task has `nextAction: run_phase`, `task create` fails with `Task create is blocked while other work is actionable: ...`. Pass `--switch-from <task-id>` **only** with explicit user direction; acknowledged tasks keep their state and remain the resume target (a resume-marker diagnostic is stamped). Never pause or mutate the acknowledged task.
+- This guard is local-CLI enforcement; the coordination service does not enforce it.
+
+## Fleet authority mismatch
+
+- When `AIDLC_FLEET_URL` is set, local lifecycle scripts throw `Fleet authority is configured; use remote-state.mjs instead of local lifecycle scripts`. This is by design — never silently switch authorities.
+- Use `node .agents/aidlc/scripts/remote-state.mjs ...` for all mutations. See [Coordination service](./coordination-service.md).
+
+## Docker worker image missing (fleet e2e tests)
+
+- `test/unit/loop-fleet-e2e.test.ts` skips cleanly with `Docker worker image unavailable` when the image (default `aidlc-worker-fleet-e2e-test:local`, overridable via `AIDLC_WORKER_DOCKER_IMAGE`) is missing. No failure is recorded.
+- Build the worker image, or set `AIDLC_TEST_WORKER_IMAGE`/`AIDLC_WORKER_DOCKER_IMAGE`, to enable coverage. Postgres coverage additionally needs `TEST_POSTGRES_URL`.
+
+## Worker image missing at build dispatch
+
+- Local build dispatch auto-builds the per-provider image (`aidlc-worker-<provider>:local`) from the packaged Dockerfile when it is missing, so this error usually does not surface.
+- If the build cannot complete (no Docker daemon, no network to fetch the CLI, or a removed Dockerfile), the worker batch fails with `Docker engine, image, or provider CLI preflight failed`. Run `aidlc-kit loop worker-image --provider <provider>` directly to see the build output, or set `AIDLC_WORKER_DOCKER_IMAGE` to an image you built yourself.
+- Fleet workers resolve the image on their own machine: `AIDLC_WORKER_DOCKER_IMAGE`, else `loop.workerImage[provider]` from the project config, else `aidlc-worker-<provider>:local` (auto-built when missing). The provider comes from `AIDLC_FLEET_WORKER_AGENT`, else the worker's entry in `AIDLC_FLEET_WORKER_PROVIDERS`, else `AIDLC_FLEET_AGENT` (a copied lead env never overrides the worker's own mapping); without one, `AIDLC_WORKER_DOCKER_IMAGE is required when the worker provider is unknown`. To build ahead of time, run `aidlc-kit loop worker-image --provider codex|claude|opencode` on that machine.
+
+## Loop daemon diagnostics
+
+- `Loop daemon already running (pid N)` — one daemon per project (`.agents/data/loop/daemon.lock`); stop the running one first. A lock owned by a dead pid is reclaimed automatically.
+- `daemon_poll_error` — the daemon could not list tasks (for example the fleet service is unreachable). It keeps polling and does not stop; fix connectivity or credentials and it recovers on the next poll.
+- `daemon_turn_error`, or a `daemon_turn` with status `blocked`/`reconcile` — that task is retried with exponential backoff (capped at 10 minutes) while other tasks keep running. Inspect it with `task show` (local) or `remote-state.mjs task next` (fleet).
+- `loop resume is removed …` — use `loop start`; re-activate a paused task with the dashboard **resume** or the task status command.
+
+## Dashboard `401` / `403`
+
+- `401 Invalid or missing approve token` — the browser has no current token. Open the login URL printed by `aidlc-kit ui` (the token changes on every restart unless you pass `--token-file`), or paste the token into **Settings**. The token is accepted only in the `x-aidlc-token` or `Authorization: Bearer` header, never as a form or body field.
+- `403 Host header does not match this dashboard; open it at its bound address` — the page was opened under a host name other than the bound address (for example a LAN name while bound to `127.0.0.1`). Use the printed URL; any loopback name works when bound to loopback.
+- `403 Cross-origin request rejected` — a state-changing request came from another origin. Use the dashboard page itself.
+- `403 Fleet approval needs the reviewer credential …` — a fleet dashboard without a reviewer credential cannot approve. Restart `aidlc-kit ui` with `AIDLC_FLEET_REVIEWER_TOKEN` or `--reviewer-token-file <file>` (outside the project, mode `600`), or approve from a reviewer terminal with `remote-state.mjs gate approve <task-id> --snapshot <id> --source "<approval>"`.
+- `Token file must …` — `--token-file`/`--reviewer-token-file` must live outside the project, be a regular non-symlink file with mode `600`/`400`, and contain one 16–256 character token.
+
+## Loop / fleet experimental status
+
+- Local loop mode is usable today; fleet mode and the coordination service are still under active development. The whole loop is experimental; pre-1.0 breaking changes are possible.
+- Selecting a mode during `init` or `upgrade` never starts or approves anything. Only `aidlc-kit loop start` runs the loop daemon, in either mode.
+- See the warning in [README](../README.md) and [Coordination service](./coordination-service.md).
+
+## When to escalate
+
+- Repair bound hit (`REPAIR_BOUND`): follow the returned handoff command — record a durable handoff (`task handoff`), reopen to plan, create a successor, supersede, or close — with evidence. Do not present G2.
+- Security, migration, or contract changes reopen Approve plan (G1) even after a prior approval; re-run `gate-check` and present the gate again.
+- Fleet/loop issues affecting canonical state: stop and use `remote-state.mjs`; never mix authorities.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@felixdotgo/aidlc-kit",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Install a local, agent-adapted AI-DLC workflow into a project.",
   "keywords": [
     "ai-dlc",
@@ -22,7 +22,7 @@
   "license": "MIT",
   "type": "module",
   "bin": {
-    "aidlc-workflow": "dist/src/cli.js"
+    "aidlc-kit": "dist/src/cli.js"
   },
   "files": [
     "dist/src",
@@ -35,7 +35,10 @@
   ],
   "scripts": {
     "build": "node scripts/build-assets.mjs && tsc -p tsconfig.json",
+    "sync-core": "node scripts/sync-core.mjs",
     "test": "npm run build && node --test dist/test/unit/*.test.js",
+    "test:fast": "node --test dist/test/unit/*.test.js",
+    "test:coverage": "node --test --experimental-test-coverage dist/test/unit/*.test.js",
     "lint": "tsc --noEmit -p tsconfig.json",
     "release:check": "node dist/dev/evaluator/release-check.js .agents/project/release-eval.json --adapters opencode",
     "prepublishOnly": "npm test && npm run lint && npm run release:check"

package/dist/src/ledger.d.ts

@@ -1,22 +0,0 @@
-import type { TaskState, WorkflowState } from "./model.js";
-export declare const trackedTasksPath: (root: string) => string;
-export declare const taskEventsPath: (root: string, taskId: string) => string;
-export interface TaskLedgerEvent {
-    schemaVersion: 1;
-    id: string;
-    taskId: string;
-    parentDigest: string | null;
-    actor: string;
-    recordedAt: string;
-    snapshot: TaskState;
-    digest: string;
-}
-export declare const validateLedgerEvent: (value: unknown) => TaskLedgerEvent;
-export declare const createLedgerEvent: (task: TaskState, parentDigest: string | null, actor: string, recordedAt?: string, id?: string) => TaskLedgerEvent;
-export declare const loadTaskLedger: (root: string, taskId: string) => TaskLedgerEvent[];
-export declare const reduceTaskLedger: (events: readonly TaskLedgerEvent[]) => {
-    task: TaskState;
-    headDigest: string;
-} | undefined;
-export declare const loadTrackedState: (root: string) => WorkflowState | undefined;
-export declare const appendTaskLedgerEvent: (root: string, task: TaskState, actor: string) => TaskLedgerEvent;

package/dist/src/ledger.js

@@ -1,119 +0,0 @@
-import { createHash, randomUUID } from "node:crypto";
-import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, renameSync, writeFileSync } from "node:fs";
-import { dirname, join, resolve } from "node:path";
-import { validateState } from "./state.js";
-export const trackedTasksPath = (root) => join(resolve(root), ".agents/workflow/tasks");
-export const taskEventsPath = (root, taskId) => join(trackedTasksPath(root), taskId, "events");
-const digest = (value) => createHash("sha256").update(JSON.stringify(value)).digest("hex");
-const eventContent = (event) => `${JSON.stringify(event, null, 2)}\n`;
-const eventPath = (root, event) => join(taskEventsPath(root, event.taskId), `${event.id}.json`);
-const taskIdPattern = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
-const iso = (value) => typeof value === "string" && Number.isFinite(Date.parse(value)) && new Date(Date.parse(value)).toISOString() === value;
-const assertSafeTaskId = (taskId) => {
-    if (!taskIdPattern.test(taskId))
-        throw new Error(`Invalid ledger task id: ${taskId}`);
-};
-const atomicWrite = (path, content) => {
-    mkdirSync(dirname(path), { recursive: true });
-    const temporary = `${path}.tmp-${process.pid}-${Date.now()}`;
-    writeFileSync(temporary, content, "utf8");
-    renameSync(temporary, path);
-};
-export const validateLedgerEvent = (value) => {
-    if (!value || typeof value !== "object" || Array.isArray(value))
-        throw new Error("Ledger event must be an object");
-    const event = value;
-    if (event.schemaVersion !== 1 || typeof event.id !== "string" || !taskIdPattern.test(event.id) || typeof event.taskId !== "string" || !taskIdPattern.test(event.taskId) || (event.parentDigest !== null && !/^[a-f0-9]{64}$/.test(event.parentDigest ?? "")) || typeof event.actor !== "string" || !event.actor.trim() || !iso(event.recordedAt) || !event.snapshot || typeof event.digest !== "string" || !/^[a-f0-9]{64}$/.test(event.digest))
-        throw new Error("Invalid ledger event fields");
-    if (event.snapshot.id !== event.taskId)
-        throw new Error(`Ledger event task mismatch: ${event.id}`);
-    validateState({ schemaVersion: 4, tasks: { [event.taskId]: event.snapshot }, archive: {} });
-    const { digest: supplied, ...unsigned } = event;
-    if (digest(unsigned) !== supplied)
-        throw new Error(`Ledger event digest mismatch: ${event.id}`);
-    return event;
-};
-export const createLedgerEvent = (task, parentDigest, actor, recordedAt = new Date().toISOString(), id = randomUUID()) => {
-    assertSafeTaskId(task.id);
-    if (!actor.trim() || !iso(recordedAt) || !taskIdPattern.test(id))
-        throw new Error("Invalid ledger event metadata");
-    validateState({ schemaVersion: 4, tasks: { [task.id]: task }, archive: {} });
-    const unsigned = { schemaVersion: 1, id, taskId: task.id, parentDigest, actor, recordedAt, snapshot: task };
-    return { ...unsigned, digest: digest(unsigned) };
-};
-export const loadTaskLedger = (root, taskId) => {
-    assertSafeTaskId(taskId);
-    const directory = taskEventsPath(root, taskId);
-    if (!existsSync(directory))
-        return [];
-    if (lstatSync(directory).isSymbolicLink())
-        throw new Error(`Ledger path crosses a symlink: ${taskId}`);
-    const events = readdirSync(directory, { withFileTypes: true })
-        .filter((entry) => entry.isFile() && entry.name.endsWith(".json"))
-        .map((entry) => validateLedgerEvent(JSON.parse(readFileSync(join(directory, entry.name), "utf8"))))
-        .sort((left, right) => left.id.localeCompare(right.id));
-    if (events.some((event) => event.taskId !== taskId))
-        throw new Error(`Ledger event is in the wrong task directory: ${taskId}`);
-    return events;
-};
-export const reduceTaskLedger = (events) => {
-    if (!events.length)
-        return undefined;
-    const byDigest = new Map(events.map((event) => [event.digest, event]));
-    if (byDigest.size !== events.length)
-        throw new Error("Duplicate ledger event digest");
-    const roots = events.filter((event) => event.parentDigest === null);
-    if (roots.length !== 1)
-        throw new Error("Ledger must have exactly one root event");
-    const children = new Map();
-    for (const event of events)
-        if (event.parentDigest) {
-            if (!byDigest.has(event.parentDigest))
-                throw new Error(`Ledger event has unknown parent: ${event.id}`);
-            const siblings = children.get(event.parentDigest) ?? [];
-            siblings.push(event);
-            children.set(event.parentDigest, siblings);
-        }
-    const sibling = [...children.values()].find((items) => items.length > 1);
-    if (sibling)
-        throw new Error(`Concurrent ledger events require resolution: ${sibling.map((event) => event.id).join(", ")}`);
-    const visited = new Set();
-    let current = roots[0];
-    while (true) {
-        if (visited.has(current.digest))
-            throw new Error("Ledger event cycle");
-        visited.add(current.digest);
-        const next = children.get(current.digest) ?? [];
-        if (!next.length)
-            break;
-        current = next[0];
-    }
-    if (visited.size !== events.length)
-        throw new Error("Ledger contains disconnected events");
-    return { task: current.snapshot, headDigest: current.digest };
-};
-export const loadTrackedState = (root) => {
-    const directory = trackedTasksPath(root);
-    if (!existsSync(directory))
-        return undefined;
-    if (lstatSync(directory).isSymbolicLink())
-        throw new Error("Tracked ledger path crosses a symlink");
-    const tasks = {};
-    for (const entry of readdirSync(directory, { withFileTypes: true })) {
-        if (!entry.isDirectory() || !taskIdPattern.test(entry.name))
-            continue;
-        const reduced = reduceTaskLedger(loadTaskLedger(root, entry.name));
-        if (reduced)
-            tasks[entry.name] = reduced.task;
-    }
-    return validateState({ schemaVersion: 4, tasks, archive: {} });
-};
-export const appendTaskLedgerEvent = (root, task, actor) => {
-    const current = reduceTaskLedger(loadTaskLedger(root, task.id));
-    const event = createLedgerEvent(task, current?.headDigest ?? null, actor);
-    const path = eventPath(root, event);
-    if (existsSync(path))
-        throw new Error(`Ledger event already exists: ${event.id}`);
-    atomicWrite(path, eventContent(event));
-    return event;
-};