@felixdotgo/aidlc-kit 0.1.1 → 0.3.0

package/docs/configuration.md

@@ -1,6 +1,6 @@
 # Configuration
 
-Each installed project owns its workflow configuration at `.agents/config.json`. It selects topology profiles, specification roots, safe verification commands, and local rules without changing the package-managed kernel. The package supports Codex, Claude Code, and OpenCode.
+Each installed project owns `.agents/config.json`: topology profiles, specification roots, verification commands, local rules, and the optional `mcp` and `loop.*` settings. CLI flags and environment variables: [Command reference](./command-reference.md); loop setup: [Loop setup runbook](./loop-runbook.md).
 
 ## Minimal configuration
 
@@ -20,32 +20,26 @@ Each installed project owns its workflow configuration at `.agents/config.json`.
 }
 ```
 
-Commands are stored as executable and argument arrays. Do not replace them with shell strings: this keeps execution inspectable and avoids accidental shell interpretation.
+- Commands are executable and argument arrays, never shell strings.
+- G0, G1, and G2 always require explicit human approval; configuration cannot auto-pass a gate.
 
-G0, G1, and G2 always require explicit human approval. Configuration cannot auto-pass a gate.
+## Optional `$schema` key
+
+- `init` writes a top-level `$schema` of `./aidlc/schemas/config.schema.json` (installed under `.agents/aidlc/schemas/`); existing installs can add it by hand.
+- Editors use it for autocompletion and validation; it has no runtime effect.
+- Must be a string of at most 512 characters; the relative path keeps validation offline.
 
 ## Configuration layers
 
-Values resolve in this order, with the later applicable layer taking precedence:
+Later applicable layers take precedence:
 
 ```text
 kernel → built-in topology → local profile parents/child → project config/rules → approved task decisions
 ```
 
-Built-in topology profiles are:
-
-- `topology/generic`
-- `topology/single`
-- `topology/workspace`
-- `topology/git-submodules`
-
-Arrays are stable-deduplicated. Command keys are last-wins, so a project can replace a profile command intentionally. Validate the resolved profile chain with:
-
-```sh
-npx --package @felixdotgo/aidlc-kit@0.1.1 aidlc-kit profile validate .
-```
-
-This command uses the npm package at version `0.1.1`. To run from a source checkout instead, see the [development guide](./development.md).
+- Built-in topology profiles: `topology/generic`, `topology/single`, `topology/workspace`, `topology/git-submodules`.
+- Arrays are stable-deduplicated; command keys are last-wins, so a project can replace a profile command.
+- Validate the resolved chain with `npx --package @felixdotgo/aidlc-kit@0.3.0 aidlc-kit profile validate .` (source checkout: [development guide](./development.md)).
 
 ## Rules, project data, and managed assets
 
@@ -55,40 +49,86 @@ This command uses the npm package at version `0.1.1`. To run from a source check
 | `.agents/data/` | Project owned | Lifecycle state, task artifacts, indexes, memory, and evidence. |
 | `.agents/project/` | Project owned | Profiles, rules, and project-specific evaluation material. |
 
-Keep business/domain rules in `.agents/project/rules/`. Do not edit managed kernel files to customise a project; a later installation or human-run upgrade may report conflicts for modified managed content.
+Keep business/domain rules in `.agents/project/rules/`. Never edit managed kernel files; a later install or upgrade may report conflicts for modified managed content.
 
 ## Agent permissions
 
-The Codex adapter installs `.codex/config.toml` with `approval_policy = "on-request"` and `sandbox_mode = "workspace-write"`, plus `.codex/rules/aidlc.rules`. The execpolicy allowlists only the six lifecycle entry points under `node .agents/aidlc/scripts/`, allowing AI-DLC state transitions without granting general command approval. Each allowed lifecycle command must be run as its own exec invocation: joining commands with `&`, `&&`, `;`, or `|` creates shell command segments that are not covered by a single prefix rule. Codex loads this project config only after the user trusts the project; network access stays disabled unless the project separately enables it. Claude Code installs `.claude/settings.local.json` and phase skills that allow only `node .agents/aidlc/scripts/*`, so lifecycle state updates do not require repeated confirmation while general Bash commands remain unapproved.
+Each adapter grants only what the lifecycle needs; general commands stay unapproved.
 
-The OpenCode adapter installs only an owner-scoped managed block in `AGENTS.md` and reads `.opencode/` solely to detect the adapter. It writes no OpenCode configuration, MCP, or permission file, so user and project OpenCode settings are not overridden. Codex and OpenCode blocks are independently owned and merge in the same `AGENTS.md` when both adapters are installed.
+| Adapter | Installed files | What is allowed | Notes |
+| --- | --- | --- | --- |
+| Codex | A managed block in `AGENTS.md`, `.codex/config.toml` (`approval_policy = "on-request"`, `sandbox_mode = "workspace-write"`), and `.codex/rules/aidlc.rules` | The execpolicy allowlists only the seven lifecycle entry points under `node .agents/aidlc/scripts/` (`state`, `task-next`, `context`, `gate-check`, `gate-view`, `render`, `assignment`). | Loaded only after the user trusts the project; network access stays disabled unless the project enables it. |
+| Claude Code | A managed block in `CLAUDE.md`, `.claude/settings.local.json`, and phase skills | Only `node .agents/aidlc/scripts/*`. | Other Bash commands stay unapproved. |
+| OpenCode | An owner-scoped managed block in `AGENTS.md` only | Nothing: no OpenCode configuration, MCP, or permission file is written. | Reads `.opencode/` only to detect the adapter; OpenCode settings are never overridden. |
 
-## Context and risk
+- Codex allowlist rule: run each lifecycle command as its own exec invocation. Commands joined with `&`, `&&`, `;`, or `|` create shell segments that a single prefix rule does not cover.
+- Codex and OpenCode blocks are independently owned and merge in the same `AGENTS.md` when both are installed.
+- `init --force --yes` is only for an intentional initial install that replaces an unmanaged conflicting file, never an upgrade ([Command reference](./command-reference.md#init)).
 
-`context.maxChars` bounds a phase packet. The runtime preserves lifecycle instructions, approved decisions, and mandatory invariants; it fails clearly rather than silently truncating required contract content.
+## Context and risk
 
-Set the default risk level deliberately. Planning, migrations, cross-service contracts, and security-sensitive changes deserve a stronger reviewer or an explicit human decision even when the configuration default is normal.
+- `context.maxChars` bounds a phase packet. The runtime preserves lifecycle instructions, approved decisions, and mandatory invariants, and fails clearly rather than silently truncating them.
+- Set `risk.default` deliberately: planning, migrations, cross-service contracts, and security-sensitive changes deserve a stronger reviewer or an explicit human decision even at `normal`.
 
 ## Optional AI-DLC Coordination
 
-`mcp` is absent (or `{ "enabled": false }`) by default. An enabled configuration requires an HTTP(S) `endpoint` and non-empty `workspace`; it may also name a token environment variable, polling interval from 1,000 to 3,600,000 ms, and the enabled Jira/Trello/GitHub Issues preflight providers. See [AI-DLC Coordination service](./coordination-service.md) for the remote-authority and deployment contract. The coordination service is **experimental and unfinished** (known bugs included), and it can change incompatibly in any release before `1.0.0`.
+`mcp` is absent (or `{ "enabled": false }`) by default. Enabled, it requires an HTTP(S) `endpoint` and non-empty `workspace`, and may name a token environment variable, a polling interval from 1,000 to 3,600,000 ms, and the enabled Jira/Trello/GitHub Issues preflight providers. Experimental ([Status and stability](./loop-runbook.md#status-and-stability)); contract in [AI-DLC Coordination service](./coordination-service.md).
 
 ## Optional loop configuration
 
 > [!WARNING]
-> The loop and the coordination service are **experimental and unfinished**: they contain known bugs and rough edges, and — because the package is still pre-1.0 (`0.x`) — the `loop.*` fields, provider mappings, and environment variables can change incompatibly in any release before `1.0.0`.
+> Experimental, pre-1.0. See [Status and stability](./loop-runbook.md#status-and-stability).
 
-`loop.mode` can be `off`, `local`, or `fleet`; an absent `loop` field means `off`. The optional `loop.agents` maps one lead and named workers to `codex`, `claude`, or `opencode`, independently of `mcp.providers`:
+The `loop` object selects the loop mode, agents, and limits, set through `init`, the human-run upgrade preview, or a deliberate edit. It installs and starts nothing, authorizes no upgrade, grants no gate approval, and holds no provider credentials.
 
 ```json
 {
   "loop": {
     "mode": "local",
-    "agents": { "lead": "codex", "workers": { "worker-a": "codex", "worker-b": "opencode" } }
+    "agents": { "lead": "codex", "workers": { "worker-a": "codex", "worker-b": "opencode" } },
+    "pollMs": 5000,
+    "limits": { "maxTurns": 12, "turnTimeoutMs": 600000, "maxStallTurns": 2 }
   }
 }
 ```
 
-When any selected provider is `opencode`, set `AIDLC_OPENCODE_MODEL` to a `provider/model[#variant]` value such as `opencode-go/gpt-6-luna`. The provider turn fails closed without a valid value. Docker-isolated lead turns, local Docker worker batches, and fleet worker containers reject OpenCode with `OpenCode workers require file-based credentials and are not available in isolated containers yet`; they do not fall back to the host.
+### Mode and agents
+
+- `loop.mode` is `off`, `local`, or `fleet`; an absent `loop` means `off`. Selecting a mode starts nothing: run `./.agents/aidlc/scripts/loop.sh up` (or `aidlc-kit loop start`).
+- Both enabled modes run one lock-enforced multi-task daemon per project. It polls its authority — canonical local state, or the coordination service in `fleet` mode — and auto-picks every actionable **loop-owned** task without prompting for a requirement.
+- A task is loop-owned when created through loop intake (dashboard **New task**, `aidlc-kit loop intake`, `loop-entry.mjs intake`) or, locally, when it has a loop run record; fleet ownership is `.agents/data/tasks/<id>/runtime/intake.json` with `authority: "fleet"`. Interactive-lead tasks are never picked up.
+- `loop.agents` maps one lead and named workers to `codex`, `claude`, or `opencode`, independently of `mcp.providers`.
+
+### Polling and limits
+
+| Field | Range | Default | Meaning |
+| --- | --- | --- | --- |
+| `loop.pollMs` | integer `1000`–`300000` | `5000` | Daemon poll interval. |
+| `loop.limits.maxTurns` | `1`–`1000` | `12` | Turn budget of **one supervised lead run**; a resumed run starts a fresh budget. |
+| `loop.limits.turnTimeoutMs` | `1`–`3600000` | `600000` | Caps a single agent turn. |
+| `loop.limits.maxStallTurns` | `1`–`20` | `2` | Pauses after that many consecutive turns without observable progress. |
+
+In `fleet` mode these become `AIDLC_FLEET_MAX_TURNS`, `AIDLC_FLEET_TURN_TIMEOUT_MS`, `AIDLC_FLEET_MAX_STALL_TURNS`, and `AIDLC_FLEET_POLL_MS`; an exported value overrides the config.
+
+### Worker image
+
+`loop.workerImage` maps a provider to a worker Docker image tag (for example `{ "opencode": "aidlc-worker-opencode:local" }`), recorded by `aidlc-kit loop worker-image`. Local dispatch and fleet workers fall back to `aidlc-worker-<provider>:local`, auto-built from the packaged Dockerfile when missing; `AIDLC_WORKER_DOCKER_IMAGE` overrides it.
+
+### Provider credentials and OpenCode
+
+Provider credentials go in the git-ignored `.agents/loop.env` (or the shell), never in this file; env-file and auto-detection rules are in [Command reference](./command-reference.md#loop).
+
+- Any `opencode` provider needs `AIDLC_OPENCODE_MODEL` as `provider/model[#variant]` (for example `opencode-go/gpt-6-luna`) in `.agents/loop.env`, the shell, or `"model"` in `opencode.json` (detected locally). Without a valid value the provider turn fails closed and `loop start`/`loop up` stop before the daemon starts.
+- **Isolated lead.** Rejects OpenCode with `OpenCode workers require file-based credentials and are not available in isolated containers yet`; no host fallback.
+- **Docker workers.** Local worker batches and fleet worker containers accept OpenCode, authenticating from the key matching the model prefix (`openai/` → `OPENAI_API_KEY`, `anthropic/` → `ANTHROPIC_API_KEY`, otherwise `OPENCODE_API_KEY`) and redirecting OpenCode's XDG data/config roots into the worker's ephemeral HOME.
+
+### Parallel work partition
+
+With `loop.mode` `local` or `fleet`, the Approve plan gate check requires owned paths on every open build item (`PARTITION_SCOPE`) and no overlapping paths between items that can run concurrently (`PARTITION_OVERLAP`). With the loop `off` both are warnings and the gate passes; see [Troubleshooting](./troubleshooting.md#parallel-work-partition-partition_overlap--partition_scope).
+
+## Related
 
-Configure this field through the init or human-run upgrade preview, or edit the project-owned config deliberately. Provider credentials do not belong in this object. The configuration is an opt-in selection; it does not install or start a service, authorize an upgrade, or grant gate approval. Selecting a mode alone does not start the loop — run `aidlc-kit loop start` explicitly. Existing fleet operations and storage requirements are documented in [Coordination service](./coordination-service.md).
+- [Loop setup runbook](./loop-runbook.md) — loop setup.
+- [Command reference](./command-reference.md#loop) — loop actions and environment.
+- [AI-DLC Coordination service](./coordination-service.md) — fleet operations.
+- [Operating the workflow](./operating-workflow.md) — lifecycle and gates.

package/docs/coordination-service.md

@@ -1,52 +1,72 @@
 # AI-DLC Coordination service
 
-> [!WARNING]
-> The coordination service (and the end-to-end loop that builds on it) is **experimental and unfinished**: it contains known bugs and rough edges. The package is pre-1.0 (`0.x`), so setup flags, `mcp.*`/`loop.*` configuration, endpoints, environment variables, and storage behaviour can change incompatibly in any release before `1.0.0`. Do not treat it as a stable dependency yet.
+The optional, Docker-deployable authority for a workflow workspace: remote canonical state for a team, or the fleet loop across machines ([runbook](./loop-runbook.md#fleet-multi-machine)). Disabled by default: without an enabled `mcp` block, installed lifecycle scripts stay local and make no network calls.
 
-The optional AI-DLC Coordination service is a separate Docker-deployable authority for a workflow workspace. It is disabled by default: without an enabled `mcp` block, installed lifecycle scripts remain local and make no network calls.
+> [!WARNING]
+> Experimental, pre-1.0. See [Status and stability](./loop-runbook.md#status-and-stability).
 
 ## Safe setup
 
-Preview a configuration first. Outside an interactive terminal, provide all four selection flags.
+Preview first; outside an interactive terminal, provide all four selection flags:
 
 ```sh
-npx --package @felixdotgo/aidlc-kit@0.1.1 aidlc-kit mcp setup . --dry-run \
+npx --package @felixdotgo/aidlc-kit@0.3.0 aidlc-kit mcp setup . --dry-run \
   --deployment docker --storage sqlite --bind localhost --workspace engineering
 ```
 
-This command uses the npm package at version `0.1.1`. To run from a source checkout instead, see the [development guide](./development.md).
-
-Remove `--dry-run` and confirm to create `.agents/aidlc-coordination/` and update `.agents/config.json`. Setup does not start Docker. Copy `.env.example` to a secret-managed `.env`, review it, then start explicitly:
+Remove `--dry-run` and confirm to create `.agents/aidlc-coordination/` and update `.agents/config.json`. Setup does not start Docker. Copy `.env.example` to a secret-managed `.env`, review it, then start:
 
 ```sh
 docker compose --env-file .agents/aidlc-coordination/.env -f .agents/aidlc-coordination/compose.yaml up -d
 ```
 
-Use SQLite only on the local Docker volume. Use PostgreSQL for multiple hosts. A network bind requires `MCP_STATE_AUTH_TOKEN` and TLS/reverse-proxy termination; never commit either the `.env` file or provider credentials.
+- SQLite only on the local Docker volume; PostgreSQL for multiple hosts.
+- A network bind requires `MCP_STATE_AUTH_TOKEN` and TLS/reverse-proxy termination. Never commit `.env` or provider credentials.
+- Source checkout: [development guide](./development.md).
 
 ## State and synchronization contract
 
-When enabled, the remote workspace is canonical. Import/export is an explicit recovery or migration action; there is no background dual-write or local fallback during an outage. Clients pull a revision or poll `state_events_since`; the service provides neither realtime subscriptions nor push notifications.
+- When enabled, the remote workspace is canonical. Import/export is an explicit recovery or migration action; there is no background dual-write or local fallback during an outage.
+- Clients pull a revision or poll `state_events_since`; there are no realtime subscriptions or push notifications.
 
 ## Multi-machine loop deployment
 
-The fleet service supports both approved storage backends: SQLite through one coordination service on one host with the database on a local volume (set `MCP_STATE_DATABASE=sqlite`, the default, and `MCP_STATE_SQLITE_PATH`), and PostgreSQL for deployments spanning multiple hosts or service instances. Each deployment keeps its chosen backend; there is no implicit fallback or migration between them. SQLite limits availability and write concurrency to that single host. Do not switch an existing authority automatically; follow the supported deployment below.
+Storage backends, with no implicit fallback or migration between them (never switch an existing authority automatically):
+
+- **SQLite**: one service on one host, database on a local volume (`MCP_STATE_DATABASE=sqlite`, the default, plus `MCP_STATE_SQLITE_PATH`). Availability and write concurrency are limited to that host.
+- **PostgreSQL**: multiple hosts or service instances.
 
-Fleet mode is separate from the default local service profile. The source checkout keeps its deployment template in `services/aidlc-coordination/`; human-run `mcp setup` copies it into the target project's `.agents/aidlc-coordination/`. Copy that directory's `.env.fleet.example` to a private `.env`, set the database choice and three distinct credential classes (`MCP_FLEET_LEAD_TOKEN`, `MCP_FLEET_REVIEWER_TOKEN`, and the worker-ID-to-token JSON map `MCP_FLEET_WORKER_TOKENS`), then start the fleet profile. From a source checkout:
+Fleet mode is a separate compose profile. The source checkout keeps the template in `services/aidlc-coordination/`; human-run `mcp setup` copies it to `.agents/aidlc-coordination/`. Copy `.env.fleet.example` to a private `.env`, set the database and three distinct credential classes (`MCP_FLEET_LEAD_TOKEN`, `MCP_FLEET_REVIEWER_TOKEN`, and the worker-ID-to-token JSON map `MCP_FLEET_WORKER_TOKENS`), then start:
 
 ```sh
 docker compose --env-file .env --profile fleet -f services/aidlc-coordination/compose.yaml up -d fleet-coordination
+# installed project: -f .agents/aidlc-coordination/compose.yaml
 ```
 
-For an installed project, use `-f .agents/aidlc-coordination/compose.yaml` instead.
+- Default binding `127.0.0.1:8788`; for workers on other machines, expose `POST /mcp` through a TLS reverse proxy and set the binding deliberately.
+- Requires the chosen database backend and a shared Git remote. Each worker gets an isolated worktree, a scoped branch, and its own credential.
+- A process supervisor must restart the supervisor, lead, and workers; after restart they reacquire fenced leases and reconcile reported or uncertain Git results before retrying.
+
+**Vocabulary.** Three kinds of fenced ownership, each with its own epoch counter:
+
+- **supervisor lease** (`supervisor_*`): one `loop start` supervising a task;
+- **lead lease** (`run_claim`): the lead epoch every lifecycle mutation must present;
+- **job claims** (`job_*`): a worker's ownership of one item, with a job epoch.
+
+`aidlc-kit loop leases` shows the supervisor epoch only when it differs from the lead epoch. A `FleetConflict` (for example `stale or expired lead claim`) is reported as `Fleet conflict: <explanation>. Inspect: node .agents/aidlc/scripts/loop-entry.mjs leases (<original message>)`. Local leases: [Troubleshooting](./troubleshooting.md#loop-leases-locks-and-claims).
+
+**Roles.**
 
-The default host binding is `127.0.0.1:8788`. For workers on other machines, expose `POST /mcp` through a TLS reverse proxy and set the binding deliberately. Fleet mode requires the chosen database backend and a shared Git remote. Give each worker an isolated worktree, a scoped branch, and its own worker credential. A process supervisor must restart the supervisor, lead, and workers; after restart they reacquire fenced leases and reconcile reported or uncertain Git results before retrying.
+- Lead credential: advances lifecycle state only while holding the current task epoch.
+- Worker credentials: claim, checkpoint, and report assigned jobs; never mutate lifecycle state or approve gates.
+- Reviewer credential: reads pending gate snapshots and records a later explicit human approval against the snapshot and current revision.
+- When the database, Git remote, or reviewer is unavailable, the run waits or fails closed; never a local fallback.
 
-The lead credential can advance lifecycle state only while holding the current task epoch. Worker credentials can claim, checkpoint, and report assigned jobs but cannot mutate lifecycle state or approve gates. The reviewer credential can read pending gate snapshots and record a later explicit human approval against the snapshot and current revision. When the database, Git remote, or reviewer is unavailable, the run waits or fails closed; it does not fall back to local state.
+The remote lifecycle client needs `AIDLC_FLEET_URL` (full HTTPS `/mcp` URL), `AIDLC_FLEET_WORKSPACE`, and `AIDLC_FLEET_PROJECT_ROOT` (absolute); lead mutations also `AIDLC_FLEET_TOKEN` and the current `AIDLC_FLEET_LEAD_EPOCH` from its claim.
 
-The installed remote lifecycle client needs `AIDLC_FLEET_URL` (the full HTTPS `/mcp` URL), `AIDLC_FLEET_WORKSPACE`, and `AIDLC_FLEET_PROJECT_ROOT` (absolute). Lead mutations also need `AIDLC_FLEET_TOKEN` and the current `AIDLC_FLEET_LEAD_EPOCH` from its claim.
+### Create tasks and a feature manifest
 
-Create the task records before the remote feature manifest. For each task, claim a lead epoch, export the returned `epoch`, then create it with the feature ID; repeat for sibling tasks. Once both records exist, create and link the manifest:
+Create task records before the manifest: claim a lead epoch, export it, create the task with the feature ID, release; repeat per task; then create and link the manifest:
 
 ```sh
 node .agents/aidlc/scripts/remote-state.mjs run claim checkout-api
@@ -59,40 +79,81 @@ node .agents/aidlc/scripts/remote-state.mjs feature link checkout checkout-integ
 node .agents/aidlc/scripts/remote-state.mjs feature ready checkout
 ```
 
-The service checks that every manifest member has a canonical task record with the matching feature ID. A partially created task stays fail-closed until the manifest is completed. The lead epoch is task-specific and must be refreshed after release or expiry.
+Every manifest member must have a canonical task record with the matching feature ID; a partially created task stays fail-closed until the manifest is complete. The lead epoch is task-specific; refresh it after release or expiry.
 
-In a connected reviewer conversation, configure `AIDLC_FLEET_REVIEWER_TOKEN`, inspect the pending packet, and only after the human replies approving that packet run:
+### Approve gates as the reviewer
+
+In a connected reviewer conversation with `AIDLC_FLEET_REVIEWER_TOKEN`, inspect the pending packet; only after the human approves it, run:
 
 ```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 second command checks that the snapshot remains current and uses the reviewer-only service operation. At G2 it also verifies that the snapshot's integration commit still matches the live remote branch. Protect the integration branch against writes outside the lead so it cannot change between verification and approval. The review message is the source provenance; the token authenticates the reviewer client, while the client operator remains responsible for using the user's actual later reply.
+- `gate approve` checks the snapshot is still current and uses the reviewer-only operation; at G2 it also verifies the snapshot's integration commit matches the live remote branch (protect that branch against writes outside the lead).
+- `--source` is the review message as provenance; the token authenticates the client, and the operator is responsible for using the user's actual reply.
+
+### Run the fleet processes
 
-Run the packaged fleet process on a lead machine and worker machines under a process supervisor. Point every process to the same `AIDLC_FLEET_URL` and workspace, but give each its own role token. On the lead, set `AIDLC_FLEET_WORKER_IDS` (comma-separated), `AIDLC_FLEET_INTEGRATION_BRANCH`, and optionally `AIDLC_FLEET_AGENT` (`codex`, `claude`, or `opencode`); `AIDLC_FLEET_WORKER_PROVIDERS` can override the provider per worker. The `job_schedule` tool accepts the same three agent values, but worker containers reject `opencode` with `OpenCode workers require file-based credentials and are not available in isolated containers yet`. The explicit blocker is reported when the job executes; there is no silent host fallback. On each worker, set its matching `AIDLC_FLEET_WORKER_ID` and `AIDLC_FLEET_WORKTREES_ROOT`:
+Run the packaged fleet process on the lead and each worker machine under a process supervisor, same `AIDLC_FLEET_URL` and workspace, own role token each. Environment variables: runbook [lead](./loop-runbook.md#step-2--set-lead-machine-environment) and [worker](./loop-runbook.md#step-4--run-a-worker-on-each-worker-machine) tables; `AIDLC_FLEET_AGENT` selects the lead provider for the direct runner (default `codex`; `aidlc-kit loop` sets it from `loop.agents.lead`) and is the per-worker fallback; `AIDLC_FLEET_WORKER_PROVIDERS` overrides it per worker. `job_schedule` accepts `codex`, `claude`, or `opencode`; worker containers run all three, only the isolated lead container does not support OpenCode ([credentials](./configuration.md#provider-credentials-and-opencode)). The worker image is resolved to its immutable `sha256:` id before any job runs.
 
 ```sh
 node dist/services/aidlc-coordination/src/fleet-run.mjs feature <feature-id>
 node dist/services/aidlc-coordination/src/fleet-run.mjs worker
+# installed project: node .agents/aidlc-coordination/src/fleet-run.mjs …
 ```
 
-`coordinator <task-id>` runs one task. `--once` processes a bounded polling pass for supervision or diagnostics. Defaults are four worker jobs per feature, five-minute leases with one-minute heartbeat, 12 turns per phase or assignment, 10 minutes per turn, and two consecutive stalls. Set `AIDLC_FLEET_MAX_WORKERS`, `AIDLC_FLEET_LEASE_MS`, `AIDLC_FLEET_HEARTBEAT_MS`, `AIDLC_FLEET_MAX_TURNS`, `AIDLC_FLEET_TURN_TIMEOUT_MS`, and `AIDLC_FLEET_MAX_STALL_TURNS` to change them. Feature mode dispatches dependency-ready tasks in order from one integration checkout; independent items within the active task can use several machines concurrently. After a lost worker report, the lead checks remote Git state and stops for reconciliation if the outcome is ambiguous. Set `AIDLC_FLEET_CODE_ONLY_RETRY=1` to permit an automatic retry only after the prior turn's timeout window has elapsed and Git confirms that no branch was published.
+- `coordinator <task-id>` runs one task; `--once` runs a bounded polling pass.
+- Defaults: four worker jobs per feature, five-minute leases with one-minute heartbeat, 12 turns per phase or assignment, 10 minutes per turn, two consecutive stalls. Override: `AIDLC_FLEET_MAX_WORKERS`, `AIDLC_FLEET_LEASE_MS`, `AIDLC_FLEET_HEARTBEAT_MS`, `AIDLC_FLEET_MAX_TURNS`, `AIDLC_FLEET_TURN_TIMEOUT_MS`, `AIDLC_FLEET_MAX_STALL_TURNS`.
+- Feature mode dispatches dependency-ready tasks in order from one integration checkout; independent items of the active task can run on several machines.
+- The coordinator never dispatches two items whose owned paths overlap by path segment (`src` overlaps `src/a.ts`, not `srcx`); the later item waits. With `MCP_FLEET_ENABLED=1` the service also refuses to approve the Approve plan gate for such overlaps or unscoped open items (`PARTITION_OVERLAP`, `PARTITION_SCOPE`).
+- After a lost worker report the lead checks remote Git state and stops for reconciliation if ambiguous. `AIDLC_FLEET_CODE_ONLY_RETRY=1` permits an automatic retry only after the prior turn's timeout window elapsed and Git confirms no branch was published.
+- The coordinator and feature commands return at a human gate (feature mode dispatches no further tasks); restart after the reviewer acts.
+- Command events and failure diagnostics report status and exit code, never command text or output. Worker progress observes file content changes as well as paths.
 
-The coordinator and feature commands return when a task reaches a human gate; feature mode stops before dispatching further tasks. After the reviewer acts, restart the command to continue. Command events and command-failure diagnostics report status and exit code without the command text or its output. Worker progress observes changes to file content as well as paths.
+### Unattended operation with the loop daemon
+
+`aidlc-kit loop start --mode fleet` on the lead machine replaces a hand-run supervisor: it runs each fleet loop-owned task until its next gate, releases the supervisor lease, and re-claims after reviewer approval. It takes `loop.limits` and `loop.pollMs` as defaults for the `AIDLC_FLEET_*` limits and never passes `AIDLC_FLEET_REVIEWER_TOKEN` to a lead or worker process. Steps: [loop runbook](./loop-runbook.md#fleet-multi-machine). On the lead machine the task's event history, run record, and intake files live under `.agents/data/tasks/<task-id>/runtime/` exactly as in local mode; worker machines write only `runtime/workers/` there. Claims are service-side, so no `assignments.json` exists in fleet mode.
 
 ## Shared coordination board
 
-The opt-in service also provides a small workspace-scoped Kanban board that is separate from lifecycle state. Board tasks may link to an AI-DLC task ID or artifact, but board writes, comments, and claims cannot mutate lifecycle state, approve a gate, or rewrite project files.
+A small workspace-scoped Kanban board, separate from lifecycle state. Board tasks may link to an AI-DLC task ID or artifact, but board writes, comments, and claims cannot mutate lifecycle state, approve a gate, or rewrite project files.
+
+- Bounded MCP tools: `board_get`, `board_apply`, `task_thread_get`, `task_comment_add`, `task_claim`, `coordination_events_since`.
+- Status `backlog`, `ready`, `in_progress`, `blocked`, `done`, or `cancelled`, plus priority, labels, assignees, and renewable one-minute-to-one-hour claims.
+- Mutations require an expected board revision, idempotency key, actor ID, and role; a conflicting live claim is rejected.
+- Threads: short append-only comments with author type, optional mentions, and `question`, `status`, `handoff`, or `decision` intent; never credentials, hidden reasoning, chat, or gate approvals.
+- Clients poll compact cursor events, coalesce them, and read details only for assignment, mention, watched-task, explicit-user, or claim-expiry activity, always after a fresh revision check.
+
+### `state_apply` contract
+
+- Every write needs an `expectedRevision`, an `idempotencyKey`, and an absolute `clientProjectRoot`. The root only formats portable `nextActions` (absolute script paths, explicit `--root`); it grants no filesystem access or authority.
+- A stale revision returns the current projection for pull/rebase; a retry with the same idempotency key returns the original committed result.
+- Responses include `nextActions` for touched tasks, so remote callers follow the same item loop and stop classifications as the local CLI.
+- SQLite uses an immediate transaction and busy timeout; PostgreSQL locks the workspace row in a transaction.
+
+Lifecycle invariants are checked across the whole before/after snapshot, not only touched task IDs:
+
+- Evidence is append-only: the prior evidence array must remain an exact structural prefix (field-wise; key order is free, record order is not).
+- A validated `blocked_on_user` wait cannot be deleted; while a task waits, every non-evidence field (items, decisions, artifacts, …) is frozen.
+- Leaving a wait requires, in the same mutation, one of: a passing approval for that exact gate; gate-bound cancellation evidence with a non-empty source; or a sourced closure/handoff record (`closed`/`superseded` with closure metadata, `paused` with handoff metadata). One compatibility recovery mirrors the local CLI: an invalid wait at the gateless wrap phase may return to `active` with no appended evidence; it is not a human approval.
+- A snapshot that requests or holds `blocked_on_user` while shared predicates still require planning, items, verification, review, or an unexhausted repair bound is rejected.
+- The `legacyG2Wait` repair-bound exemption marker is migration-owned: stamped only when upgrading a stored pre-v4 row; client mutations creating or changing it are rejected.
 
-`board_get`, `board_apply`, `task_thread_get`, `task_comment_add`, `task_claim`, and `coordination_events_since` are bounded MCP tools. Tasks use `backlog`, `ready`, `in_progress`, `blocked`, `done`, or `cancelled`, plus priority, labels, assignees, and renewable one-minute-to-one-hour claims. Mutations require an expected board revision, idempotency key, actor ID, and role. A conflicting live claim is rejected.
+In default shared-token mode these guards keep history tamper-evident but do not authenticate approvals: `source` is client-supplied provenance. Fleet mode binds lead, worker, and reviewer credentials to server-side roles; only a reviewer credential can call the atomic gate approval tool. The service cannot inspect client artifacts: the lead runs local artifact checks before publishing a review snapshot; the service enforces structural gate readiness and snapshot revision at approval.
 
-Threads are short append-only comments with author type, optional mentions, and `question`, `status`, `handoff`, or `decision` intent. They never carry credentials, hidden reasoning, general chat, or gate approvals. Clients poll compact cursor events, coalesce and debounce them, then read details only for assignment, mention, watched-task, explicit-user, or claim-expiry activity. A notice always requires a fresh revision check before action.
+`work_item_request` is only a credential-free preflight for Jira, Trello, or GitHub Issues: it reports the required environment variable names and never returns a reusable token, Authorization header, or token-bearing URL. External updates are opt-in, outside the lifecycle transaction.
 
-Every `state_apply` write needs an `expectedRevision`, an `idempotencyKey`, and an absolute `clientProjectRoot`. The root is used only to format portable `nextActions` with absolute script paths and an explicit `--root`; it does not grant the server filesystem access or authority over that path. A stale revision returns the current projection for pull/rebase, and a retry with the same idempotency key returns the original committed result. Successful responses include `nextActions` for touched tasks so remote callers follow the same item loop and stop classifications as the local CLI.
+## Service health, logging, and image
 
-The service checks lifecycle invariants across the whole before/after snapshot, not only touched task IDs. Existing evidence is append-only: the prior evidence array must remain an exact structural prefix (compared field-wise, so re-serialization key order does not matter, while record order still does). A validated `blocked_on_user` wait cannot be deleted, and while a task waits its readiness-bearing state (items, decisions, artifacts, and every other non-evidence field) is frozen; only evidence may be appended. Leaving a wait requires, in the same mutation, one of: a passing approval for that exact gate, gate-bound cancellation diagnostic evidence with a non-empty source, or a sourced closure/handoff record (`closed`/`superseded` with closure metadata, or `paused` with handoff metadata). The one compatibility recovery mirrors the local CLI: an invalid wait at the gateless wrap phase may return to `active` with no appended evidence; it is not a human approval. A snapshot that requests or holds `blocked_on_user` while shared lifecycle predicates still require planning, items, verification, review, or an unexhausted repair bound is rejected. The `legacyG2Wait` repair-bound exemption marker is migration-owned: the service stamps it only when upgrading a stored pre-v4 row, and rejects any client mutation that creates or changes it. SQLite uses an immediate transaction and busy timeout; PostgreSQL locks the workspace row in a transaction.
+- `GET /healthz`: unauthenticated, static `200 {"ok":true}`, reads no state, version, or workspace data; registered before the auth middleware; used by the container `HEALTHCHECK` and compose healthchecks.
+- Each request logs one JSON line to stderr: `{"ts":...,"method":...,"path":...,"status":...,"principal":...,"ms":...}` (`principal` omitted when absent). Never headers, bodies, or tokens.
+- McpServer version: the `version` field of the `package.json` next to the service root (`new URL("../package.json", import.meta.url)`), fallback `"0.0.0-dev"` (source checkouts); the bundled image gets it by build-time injection.
+- Image: two stages, both `node:24-bookworm-slim` (matching `better-sqlite3` ABI), non-root `node` user, `HEALTHCHECK` against `/healthz`; the compose `aidlc-coordination` and `fleet-coordination` services define matching healthchecks.
 
-In default shared-token mode, these guards keep remote history tamper-evident but do not authenticate approvals: `source` remains provenance supplied by a client. Fleet mode binds separate lead, worker, and reviewer credentials to server-side roles, and only a reviewer credential can call the atomic gate approval tool. The service cannot inspect client project artifacts, so the lead must run local artifact checks before publishing a review snapshot; the service enforces structural gate readiness and snapshot revision at approval.
+## Related
 
-`work_item_request` is intentionally only a credential-free preflight for Jira, Trello, or GitHub Issues. It reports the required environment variable names and never returns a reusable token, Authorization header, or token-bearing URL. External updates remain opt-in and must be made outside the lifecycle transaction.
+- [Loop setup runbook](./loop-runbook.md#fleet-multi-machine) — step-by-step fleet loop setup.
+- [Configuration](./configuration.md) — the `mcp` and `loop` config blocks.
+- [Command reference](./command-reference.md) — `mcp setup`, `loop`, and environment variables.
+- [Troubleshooting](./troubleshooting.md#loop-leases-locks-and-claims) — leases, claims, and fleet conflicts.

package/docs/design-decisions.md

@@ -0,0 +1,87 @@
+# Design decisions (ADR-lite)
+
+Numbered decisions that constrain future changes across modules or releases (runtime boundaries, state formats, safety policies). Local implementation choices belong in code comments or the originating task.
+
+## D1. Dual lifecycle cores with conformance instead of codegen
+
+- **Context:** Installed projects need dependency-free lifecycle scripts; the package CLI is TypeScript.
+- **Decision:** Two cores: `src/state.ts` (TypeScript) and `assets/aidlc/scripts/lib/store.mjs` (dependency-free ESM), plus a committed byte-identical copy in `services/aidlc-coordination/src/lifecycle-core.mjs`.
+- **Consequences:** Parity is checked by `lifecycle-core-conformance` (byte identity + property/fuzz), not generated; a core change requires `npm run sync-core` and those tests.
+
+## D2. Single JSON state with file lock and archive catalog
+
+- **Context:** Local-first; no registry or database in consumer projects.
+- **Decision:** One JSON file (`.agents/data/state/aidlc-state.json`) serialized by a file lock (`.aidlc-state.lock` + guard); terminal records archived under `.agents/data/state/backups/`, digest-verified.
+- **Consequences:** Simple backup, restore, and git diffing; contention is bounded by the 5s/30s lock defaults; unsuited to high-concurrency multi-writer workloads.
+
+## D3. Append-only evidence with append-order boundaries
+
+- **Context:** Verification and review outcomes must stay auditable and never be rewritten.
+- **Decision:** Evidence is append-only; current-build boundaries follow append order, not wall-clock timestamps.
+- **Consequences:** Re-running a check appends; "latest" means latest appended. Tampering requires rewriting the whole state file, detectable via lock and digest checks.
+
+## D4. Human-only upgrades
+
+- **Context:** Upgrades touch managed assets and state; automated upgrades risk data loss.
+- **Decision:** `upgrade` rejects `--yes`/`--force`, requires an interactive TTY, and asks the human to type the target version; no background checks or postinstall.
+- **Consequences:** Upgrades are auditable and intentional; CI cannot auto-upgrade; rollback uses the upgrade journal.
+
+## D5. Local-first / no-registry policy
+
+- **Context:** Consumer projects must work offline; status/doctor must not phone home.
+- **Decision:** `remoteUpdates: false` by default; status and doctor never consult a registry; fleet is opt-in and separately deployed.
+- **Consequences:** No surprise network calls; version drift is detected locally; fleet authority is explicit via `AIDLC_FLEET_URL`.
+
+## D6. Compact code style in the installed kernel
+
+- **Context:** Installed scripts must fit the 16,000-character phase-packet budget.
+- **Decision:** The installed kernel uses compact style; package and service code do not.
+- **Consequences:** Two style regimes; never "pretty-print" installed scripts in ways that bloat packets; mandatory sections are never truncated.
+
+## D7. Machine-enforced repair bounds
+
+- **Context:** Repair loops need a hard stop.
+- **Decision:** Three failed verify records per affected area, or two failed review records, in the current build flip `nextAction` to `blocked` and add a `REPAIR_BOUND` error to the Review implementation gate check.
+- **Consequences:** No self-approval past the bound; a durable handoff is required. Legacy G2 waits migrated by schema v4 are exempt once.
+
+## D8. Assignment records are operational metadata
+
+- **Context:** Worker assignment state must not become a second lifecycle authority.
+- **Decision:** Assignment records (`.agents/data/tasks/<id>/runtime/assignments.json`) are operational metadata; canonical task state is the authority.
+- **Consequences:** Assignment corruption or loss does not invalidate the task; `assignment.mjs reconcile` is required before dispatch.
+
+## D9. Configured commands as executable + args arrays
+
+- **Context:** Shell strings are unsafe and non-portable.
+- **Decision:** Project-configured commands are stored and executed as executable + args arrays; shell strings are rejected.
+- **Consequences:** No shell injection; explicit invocation; predictable cross-platform behaviour.
+
+## D10. Task language `vi` / `en`
+
+- **Context:** Artifacts and prompts need a declared language; broader i18n is not justified yet.
+- **Decision:** Task language is `vi` or `en`; further extensibility is deferred.
+- **Consequences:** New languages need a schema and conformance change; existing tasks keep their declared language.
+
+## D11. Optional `$schema` reference in generated config
+
+- **Context:** Offline-first tooling needs schema validation without network.
+- **Decision:** Generated config may include an optional relative `$schema` reference to the local schema.
+- **Consequences:** Editors validate offline; a missing reference degrades gracefully.
+
+## D12. Timing-safe comparison for all coordination auth
+
+- **Context:** Non-fleet coordination endpoints must not leak tokens via timing.
+- **Decision:** Non-fleet coordination auth uses the same timing-safe comparison as the fleet path.
+- **Consequences:** One auth implementation; no fast-path bypass; consistent with the service's credential model.
+
+## How to add a decision
+
+1. Record it in canonical state via `decision set`, tracked with its task.
+2. Cite the source (file, PR, or task id) and present it at Approve plan (G1).
+3. Append a numbered Context / Decision / Consequences entry here; link from [Architecture](./architecture.md) when it changes a boundary.
+
+## Related
+
+- [Architecture](./architecture.md)
+- [Development guide](./development.md)
+- [Testing and release](./testing-and-release.md)