@felixdotgo/aidlc-kit 0.1.1 → 0.2.0

package/dist/src/upgrade-board.js

@@ -12,7 +12,7 @@ const parseFrontmatter = (content) => {
     const match = content.match(/^---\n([\s\S]*?)\n---/);
     if (!match)
         return {};
-    return Object.fromEntries(match[1].split("\n").flatMap((line) => {
+    return Object.fromEntries((match[1] ?? "").split("\n").flatMap((line) => {
         const separator = line.indexOf(":");
         return separator < 0 ? [] : [[line.slice(0, separator).trim(), line.slice(separator + 1).trim().replace(/^['"]|['"]$/g, "")]];
     }));
@@ -30,7 +30,7 @@ const legacyEvidence = (phase, recordedAt) => {
 /** Maps one legacy BOARD row to a canonical task, copying its prose files into the stable artifact layout. */
 const taskFromLegacyRow = (root, files, row, recordedAt) => {
     const [id, title, phaseRaw, gateRaw, statusRaw, branch, areasRaw, doc] = row;
-    const oldDoc = safePath(root, doc);
+    const oldDoc = safePath(root, doc ?? "");
     const source = existsSync(oldDoc) ? readFileSync(oldDoc, "utf8") : "";
     const frontmatter = parseFrontmatter(source);
     const stableDir = `.agents/data/tasks/${id}`;
@@ -38,21 +38,21 @@ const taskFromLegacyRow = (root, files, row, recordedAt) => {
     const workplanPath = `${stableDir}/workplan.md`;
     if (source)
         files.push({ path: prosePath, owner: "aidlc-state", ownershipClass: "state", content: source });
-    const oldWorkplan = doc.replace(/\.md$/, ".workplan.md");
+    const oldWorkplan = (doc ?? "").replace(/\.md$/, ".workplan.md");
     if (existsSync(safePath(root, oldWorkplan)))
         files.push({ path: `${stableDir}/legacy-workplan.md`, owner: "aidlc-state", ownershipClass: "state", content: readFileSync(safePath(root, oldWorkplan), "utf8") });
-    const phase = ["clarify", "plan", "build", "wrap", "done"].includes(phaseRaw) ? phaseRaw : "clarify";
-    const gate = ["none", "G0_confirm", "G1_review", "G2_codereview"].includes(gateRaw) ? gateRaw : "G0_confirm";
+    const phase = (phaseRaw !== undefined && ["clarify", "plan", "build", "wrap", "done"].includes(phaseRaw) ? phaseRaw : "clarify");
+    const gate = (gateRaw !== undefined && ["none", "G0_confirm", "G1_review", "G2_codereview"].includes(gateRaw) ? gateRaw : "G0_confirm");
     return {
-        id,
-        title,
-        type: (["feature", "bug", "refactor", "infra"].includes(frontmatter.type) ? frontmatter.type : "infra"),
+        id: id ?? "",
+        title: title ?? "",
+        type: (["feature", "bug", "refactor", "infra"].includes(frontmatter.type ?? "") ? frontmatter.type : "infra"),
         phase,
         gate,
-        status: (["active", "blocked_on_user", "paused", "done"].includes(statusRaw) ? statusRaw : "paused"),
+        status: (statusRaw !== undefined && ["active", "blocked_on_user", "paused", "done"].includes(statusRaw) ? statusRaw : "paused"),
         language: frontmatter.language === "en" ? "en" : "vi",
         risk: "normal",
-        areas: areasRaw.split(",").map((area) => area.trim()).filter(Boolean),
+        areas: (areasRaw ?? "").split(",").map((area) => area.trim()).filter(Boolean),
         branch: branch || "—",
         artifacts: { intent: source ? prosePath : undefined, design: source ? prosePath : undefined, workplan: workplanPath },
         decisions: [],

package/dist/src/upgrade.d.ts

@@ -1,5 +1,4 @@
 import type { LoopConfig, PlannedWrite } from "./model.js";
-export { migrateLegacyBoard } from "./upgrade-board.js";
 /** Plans an upgrade transaction from the installed manifest to the current package. */
 export declare const planUpgrade: (root: string, loop?: LoopConfig) => PlannedWrite[];
 export interface UpgradeResult {

package/dist/src/upgrade.js

@@ -1,95 +1,32 @@
 import { copyFileSync, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, renameSync, rmdirSync, rmSync, writeFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
-import { findAdapterForUpgrade, resolvedAdaptersForUpgrade } from "./adapters.js";
-import { installedHashFor, managedContentHash, planLoopSelection, readManifest } from "./installer.js";
+import { findAdapter, resolvedAdapters } from "./adapters.js";
 import { legacyV021AdapterContents, legacyV021Hashes } from "./legacy.js";
 import { planProjectLayoutMigration } from "./project-migration.js";
-import { mergeManagedBlock } from "./managed-content.js";
+import { legacyManifest, managedContentHash, planLoopSelection, planManagedWrites, preserveOwnedFile, readManifest, splitInventoryKey } from "./managed-planning.js";
 import { resolveProjectPath, resolveProjectPathWithoutSymlinks } from "./project-path.js";
 import { prepareV4Migration, validateState } from "./state.js";
 import { contentHash, coreWorkflowFiles, initialProjectFiles, manifestSpec } from "./workflow.js";
 import { migrateLegacyBoard } from "./upgrade-board.js";
-export { migrateLegacyBoard } from "./upgrade-board.js";
 const safePath = (root, relative) => resolveProjectPath(root, relative, "Unsafe upgrade path");
 const assertNoSymlinkPath = (root, relative) => { resolveProjectPathWithoutSymlinks(root, relative, "Unsafe upgrade path", "Refusing to upgrade symlink path"); };
-const legacyManifest = (root) => {
-    const path = join(resolve(root), ".agents/aidlc/manifest.json");
-    if (!existsSync(path))
-        return false;
-    try {
-        const parsed = JSON.parse(readFileSync(path, "utf8"));
-        return parsed.managedBy === "aidlc-workflow" && (parsed.schemaVersion === 0 || parsed.schemaVersion === 1);
-    }
-    catch {
-        return false;
-    } /* intentional: a malformed/missing manifest is not a legacy v0.x install */
-};
 /* --- Managed file planning -------------------------------------------------- */
-const planManaged = (root, spec, installedHash, legacy) => {
-    const target = safePath(root, spec.path);
-    if (!existsSync(target))
-        return { ...spec, action: "create", reason: "new managed file" };
-    const current = readFileSync(target, "utf8");
-    const next = spec.strategy === "managed-block" ? mergeManagedBlock(spec, current) : spec.content;
-    const currentHash = managedContentHash(spec, current);
-    const nextHash = contentHash(spec.strategy === "managed-block" ? spec.content.trimEnd() : spec.content);
-    if (currentHash === nextHash)
-        return { ...spec, content: next, action: next === current ? "skip" : "update", reason: "managed content already current" };
-    if (installedHash && currentHash === installedHash)
-        return { ...spec, content: next, action: "update", reason: "unchanged managed file" };
-    const legacyAdapter = legacyV021AdapterContents[spec.path];
-    const legacyAdapterHash = legacyAdapter ? contentHash(spec.strategy === "managed-block" ? legacyAdapter.trimEnd() : legacyAdapter) : undefined;
-    if (legacy && (legacyV021Hashes[spec.path] === currentHash || legacyAdapterHash === currentHash))
-        return { ...spec, content: next, action: "update", reason: "recognized v0.2.1 baseline" };
-    if (spec.strategy === "managed-block" && current.includes(`<!-- aidlc-installer:${spec.owner} -->`))
-        return { ...spec, content: next, action: "conflict", reason: "managed prompt block was modified" };
-    return { ...spec, content: next, action: "conflict", reason: legacy ? "legacy core differs from known baseline" : "managed file differs from installed hash" };
-};
-/** Merges a later owner of a shared managed-block path into the already-emitted plan entry. */
-const mergeSharedBlockOwner = (project, previous, spec, installed) => {
-    if (!["create", "update", "skip"].includes(previous.action))
-        return;
-    const target = safePath(project, spec.path);
-    const current = existsSync(target) ? readFileSync(target, "utf8") : "";
-    // Every owner block is checked before merging so a user edit to a later
-    // adapter's block is reported instead of being silently overwritten.
-    const installedBlockHash = installedHashFor(installed?.files, spec);
-    const currentBlockHash = managedContentHash(spec, current);
-    if (installedBlockHash !== undefined && currentBlockHash !== undefined && installedBlockHash !== currentBlockHash) {
-        previous.action = "conflict";
-        previous.reason = "managed prompt block was modified";
-        return;
-    }
-    previous.content = mergeManagedBlock(spec, previous.content);
-    previous.action = existsSync(target) ? (previous.content === current ? "skip" : "update") : "create";
-    previous.reason = "managed prompt block";
-};
-/** Plans managed replacements and shared managed-block writes across every owner. */
-const planManagedFiles = (project, managed, installed, legacy) => {
-    const plan = [];
-    const mergedBlocks = new Map();
-    for (const spec of managed) {
-        const installedHash = installedHashFor(installed?.files, spec);
-        if (spec.strategy !== "managed-block") {
-            plan.push(planManaged(project, spec, installedHash, legacy));
-            continue;
-        }
-        const previous = mergedBlocks.get(spec.path);
-        if (!previous) {
-            const write = planManaged(project, spec, installedHash, legacy);
-            plan.push(write);
-            mergedBlocks.set(spec.path, write);
-            continue;
-        }
-        mergeSharedBlockOwner(project, previous, spec, installed);
+/** Upgrade's planning policy: ownership is proven against installed hashes and the frozen v0.2.1 baselines. */
+const upgradePlanPolicy = (installed, legacy) => ({
+    flow: "upgrade",
+    installed,
+    legacy,
+    resolvePath: safePath,
+    legacyBaseline: (spec, currentHash) => {
+        const legacyAdapter = legacyV021AdapterContents[spec.path];
+        const legacyAdapterHash = legacyAdapter ? contentHash(spec.strategy === "managed-block" ? legacyAdapter.trimEnd() : legacyAdapter) : undefined;
+        return legacyV021Hashes[spec.path] === currentHash || legacyAdapterHash === currentHash;
     }
-    return plan;
-};
-/* --- Obsolete files and project-owned files ---------------------------------- */
+});
 /** Deletes obsolete managed files tracked by the installed manifest that no longer ship in this release. */
 const planObsoleteRemovals = (project, plan, installed, managed) => {
     for (const [key, item] of Object.entries(installed.files)) {
-        const path = key.includes("#") ? key.slice(0, key.lastIndexOf("#")) : key;
+        const path = splitInventoryKey(key).path;
         // Shared prompt blocks are upgraded through the merged plan above; never delete their whole path here.
         if (item.strategy === "managed-block")
             continue;
@@ -107,8 +44,7 @@ const preserveProjectFiles = (project, plan, legacy) => {
     for (const spec of initialProjectFiles()) {
         if (legacy && spec.path === ".agents/data/state/aidlc-state.json" && !existsSync(safePath(project, spec.path)))
             continue;
-        const target = safePath(project, spec.path);
-        plan.push(existsSync(target) ? { ...spec, content: readFileSync(target, "utf8"), action: "preserve", reason: `${spec.ownershipClass}-owned file` } : { ...spec, action: "create", reason: `new ${spec.ownershipClass}-owned file` });
+        plan.push(preserveOwnedFile(safePath(project, spec.path), spec));
     }
 };
 /* --- Canonical state and legacy BOARD migration -------------------------------- */
@@ -171,11 +107,11 @@ const removeLegacyBoard = (project, plan) => {
 /* --- planUpgrade orchestration ------------------------------------------------ */
 /** Selects which adapters to upgrade: manifest-registered ones, else auto-detected installable ones. */
 const selectedUpgradeAgents = (project, installed) => {
-    const upgradeAdapters = resolvedAdaptersForUpgrade();
+    const upgradeAdapters = resolvedAdapters();
     const requested = installed?.adapters?.length ? installed.adapters : upgradeAdapters.filter((adapter) => adapter.detect(project)).map((adapter) => adapter.id);
-    return requested.filter((id) => findAdapterForUpgrade(id));
+    return requested.filter((id) => findAdapter(id));
 };
-const agentUpgradeFiles = (selected) => selected.flatMap((id) => findAdapterForUpgrade(id)?.files() ?? []).map((file) => ({ ...file, ownershipClass: "managed" }));
+const agentUpgradeFiles = (selected) => selected.flatMap((id) => findAdapter(id)?.files() ?? []).map((file) => ({ ...file, ownershipClass: "managed" }));
 /** Plans an upgrade transaction from the installed manifest to the current package. */
 export const planUpgrade = (root, loop) => {
     const project = resolve(root);
@@ -185,7 +121,7 @@ export const planUpgrade = (root, loop) => {
         throw new Error("No owned AI-DLC installation found. Use init instead of upgrade.");
     const selected = selectedUpgradeAgents(project, installed);
     const managed = [...coreWorkflowFiles(), ...agentUpgradeFiles(selected)];
-    const plan = planManagedFiles(project, managed, installed, legacy);
+    const plan = planManagedWrites(project, managed, upgradePlanPolicy(installed, legacy));
     if (installed)
         planObsoleteRemovals(project, plan, installed, managed);
     preserveProjectFiles(project, plan, legacy);

package/dist/src/workflow.js

@@ -1,13 +1,13 @@
-import { createHash } from "node:crypto";
 import { readdirSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { defaultConfig } from "./profiles.js";
-import { createLessonIndex, emptyMemoryRegistry, emptyState, lessonStateDigest } from "./state.js";
+import { createLessonIndex, digest, emptyMemoryRegistry, emptyState, lessonStateDigest } from "./state.js";
 const owner = "aidlc-core";
 const assetRoot = fileURLToPath(new URL("../assets/.agents", import.meta.url));
 const packageJson = JSON.parse(readFileSync(fileURLToPath(new URL("../../package.json", import.meta.url)), "utf8"));
-export const contentHash = (content) => createHash("sha256").update(content).digest("hex");
+// node:crypto update() hashes Uint8Array bytes unchanged; the cast only satisfies digest's narrower parameter type.
+export const contentHash = (content) => digest(content);
 const collect = (directory, target) => readdirSync(directory, { withFileTypes: true }).flatMap((entry) => {
     const source = join(directory, entry.name);
     const destination = `${target}/${entry.name}`;

package/docs/README.md

@@ -8,7 +8,8 @@ Use this page to choose the guide that matches your role and next task.
 2. Read [Operating the workflow](./operating-workflow.md) before asking an agent to change a project.
 3. Use [Configuration](./configuration.md) to configure project rules, profiles, and Codex, Claude Code, and OpenCode permissions.
 4. Keep [Command reference](./command-reference.md) nearby for safe CLI usage.
-5. Read [AI-DLC Coordination service](./coordination-service.md) before enabling remote canonical state — the service and the loop are **experimental and unfinished**, with known bugs and possible breaking changes in every release before `1.0.0`.
+5. Read [AI-DLC Coordination service](./coordination-service.md) before enabling remote canonical state — the coordination service and **fleet** mode are **experimental and still under active development**, with known bugs and possible breaking changes in every release before `1.0.0`.
+6. Use the [Loop setup runbook](./loop-runbook.md) to run the loop end-to-end — enable from `off`, run in `local` mode, or spread across machines with `fleet`.
 
 ## For contributors and maintainers
 
@@ -26,6 +27,9 @@ Use this page to choose the guide that matches your role and next task.
 | [Development](./development.md) | Contributors | Dependencies, source layout, local commands, and implementation rules. |
 | [Testing and release](./testing-and-release.md) | Maintainers | Test strategy, evaluator, package smoke test, and release checks. |
 | [Architecture](./architecture.md) | Contributors | Boundaries, dependency direction, and source-to-consumer flow. |
-| [AI-DLC Coordination service](./coordination-service.md) | Operators | Opt-in service deployment, state authority, and credential safety. Experimental and unfinished: known bugs, breaking changes possible before `1.0.0`. |
+| [AI-DLC Coordination service](./coordination-service.md) | Operators | Opt-in service deployment, state authority, and credential safety. Experimental and under active development: known bugs, breaking changes possible before `1.0.0`. |
+| [Loop setup runbook](./loop-runbook.md) | Operators | Step-by-step loop setup: enable from `off`, run in `local` mode (usable today), or spread across machines with `fleet` (in development). Experimental: breaking changes possible before `1.0.0`. |
+| [Troubleshooting](./troubleshooting.md) | Operators and contributors | Symptom/error-code recovery guide for locks, corrupt state, continuation guard, gate-check errors, and fleet authority. |
+| [Design decisions](./design-decisions.md) | Contributors | ADR-lite: dual core, single JSON state, compact style, human-only upgrade, append-only evidence, and how to add a decision. |
 
 When a public command, configuration field, or installed layout changes, update the relevant guide and its validation in the same change.

package/docs/architecture.md

@@ -26,14 +26,15 @@ The distinction matters:
 
 | Boundary | Modules | Responsibility |
 | --- | --- | --- |
-| CLI and installation | `src/cli.ts`, `src/installer.ts`, `src/workflow.ts`, `src/adapters.ts` | Parse commands, select adapters, plan deterministic writes, install managed assets, and expose local status/doctor checks. |
-| Lifecycle domain | `src/model.ts`, `src/state.ts`, `src/gate.ts`, `src/context.ts` | Validate canonical state, calculate transitions and gate readiness, and build bounded phase packets. |
-| Profiles and project integration | `src/profiles.ts`, `src/tracker.ts` | Resolve project configuration/profiles and optional tracker integration. |
-| Migration | `src/upgrade.ts`, `src/project-migration.ts`, `src/legacy.ts` | Plan and apply safe legacy-data and version-layout migration with audit backups. |
-| Shared file semantics | `src/project-path.ts`, `src/managed-content.ts` | Keep all paths inside the project, reject unsafe symlinks, and preserve managed-content ownership. |
+| CLI and installation | `src/cli.ts` + `src/cli/` (`argv`, `options`, `prompt`, `commands` registry), `src/installer.ts`, `src/workflow.ts`, `src/adapters.ts`, `src/mcp-setup.ts` | Parse commands, select adapters, plan deterministic writes, install managed assets (including the coordination-service template), and expose local status/doctor checks. |
+| Shared planning core | `src/managed-planning.ts` | Single manifest reading, inventory-key handling, and the managed-file planning ladder (create/skip/update/conflict) with explicit init vs upgrade policies; consumed by installation and migration. |
+| Lifecycle domain | `src/model/` (barrel `src/model.ts`), `src/state/` (barrel `src/state.ts`: `io`, `paths`, `domain`, `guards`, `archive-record`, `items`, `commands`, `transitions`, `validate`, `store`, `memory`, `lessons`, `lifecycle`, `render`, `migrate`, `lock`), `src/gate.ts`, `src/context.ts` | Validate canonical state, calculate transitions and gate readiness, classify next actions, and build bounded phase packets. |
+| Profiles and project integration | `src/profiles.ts` | Resolve project configuration/profiles, validate config (incl. the config-only `tracker` section — no runtime tracker consumer ships today), and expand effective rules. |
+| Migration | `src/upgrade.ts`, `src/project-migration.ts`, `src/legacy.ts`, `src/upgrade-board.ts` | Plan and apply safe legacy-data and version-layout migration (incl. legacy `BOARD.md` parsing) with audit backups. |
+| Shared file semantics | `src/project-path.ts`, `src/managed-content.ts` | Keep all paths inside the project, reject unsafe symlinks, and own the managed-block marker format as its single definition. |
 | Development evaluator | `dev/evaluator/` | Run repository-only evaluation; never expose evaluator assets through the published package CLI. |
 
-Dependencies flow inward: CLI, installation, and migration depend on lifecycle and shared helpers; lifecycle does not depend on installation; evaluator may provision an installation but is not part of published runtime behaviour.
+Dependencies flow inward: CLI, installation, and migration depend on the shared planning core, lifecycle, and shared helpers; the planning core depends only on lifecycle/config/shared modules (`model`, `workflow`, `managed-content`, `profiles`) — never on the CLI, installer, or upgrade. Migration does not import installation (`upgrade.ts` consumes `managed-planning.ts` directly); the remaining one-directional `installer.ts` → `project-migration.ts` edge supports init-time legacy-layout planning. Lifecycle does not depend on installation; evaluator may provision an installation but is not part of published runtime behaviour. `src/ledger.ts` and `src/tracker.ts` were removed as runtime-dead code; the `tracker` config section remains schema-only (`TrackerConfig`).
 
 ## Installed workflow runtime
 
@@ -48,7 +49,7 @@ The installed kernel consists of contracts, templates, schemas, profiles, and de
 The state machine enforces the lifecycle; gates require explicit human approval; evidence is append-only. Installed scripts remain usable without an `aidlc-kit` executable or a duplicate board file.
 
 > [!WARNING]
-> The interactive-loop support and the end-to-end loop/fleet coordinator described below are **experimental and unfinished**: they contain known bugs and rough edges, and — because the package is still pre-1.0 (`0.x`) — their command surface, configuration fields, and state layout can change incompatibly in any release before `1.0.0`.
+> The **local/interactive loop is usable** today; the end-to-end **fleet** coordinator described below is **still under active development**. Both are **experimental** — because the package is still pre-1.0 (`0.x`), their command surface, configuration fields, and state layout can change incompatibly in any release before `1.0.0`.
 
 The interactive loop runs inside the current Codex, Claude Code, or OpenCode conversation. Native workers use local assignment records under `.agents/data/loop/`; those records hold claims and checkpoints while `.agents/data/state/` remains lifecycle authority. The optional headless fleet runner uses the coordination service's PostgreSQL state, fenced lead and worker claims, and Git commit handoff. Its assignment records are operational metadata; task phase, evidence, and gates stay in the canonical lifecycle state. All hosts derive dispatch from task `nextAction` and dependency-ready work.
 
@@ -77,4 +78,4 @@ Installed entry points share a strict dependency-free argv parser. Parsing and c
 Use this guide with [Development](./development.md) and [Testing and release](./testing-and-release.md) before changing a cross-cutting boundary.
 
 
-The optional end-to-end loop coordinator is implemented for both authorities. Local mode runs a foreground supervisor over the canonical local state: Docker-isolated workers, a read-only lead sandbox whose structured proposals are applied by a host broker, and gate approval only through the trusted host terminal. Fleet mode runs the same loop against a coordination service: the service owns supervisor leases, gate checkpoints, and reviewer approval, workers execute in Docker with their own credentials, and Git integration is fenced per backend (SQLite on one host with a local volume, or PostgreSQL across hosts). Selecting a mode configures the loop; only an explicit `loop start` runs it. Host-executed lead turns accept Codex, Claude Code, or OpenCode; container-isolated lead turns and worker containers accept Codex and Claude Code only and reject OpenCode with an explicit diagnostic because its credentials are file-based. See [Coordination service](./coordination-service.md) for deployment and recovery constraints.
+The optional end-to-end loop coordinator is implemented for both authorities. Local mode runs a foreground supervisor over the canonical local state: a host-executed lead, Docker-isolated workers, and gate approval only through the trusted host terminal. Fleet mode runs the same loop against a coordination service: the service owns supervisor leases, gate checkpoints, and reviewer approval, workers execute in Docker with their own credentials, and Git integration is fenced per backend (SQLite on one host with a local volume, or PostgreSQL across hosts). Selecting a mode configures the loop; only an explicit `loop start` runs it. Host-executed lead turns accept Codex, Claude Code, or OpenCode; container-isolated lead turns accept Codex and Claude Code only and reject OpenCode with an explicit diagnostic because its credentials are file-based. Local Docker worker batches accept Codex, Claude Code, or OpenCode (OpenCode workers authenticate from environment credentials with their XDG roots redirected into the ephemeral worker HOME); fleet worker containers reject OpenCode. See [Coordination service](./coordination-service.md) for deployment and recovery constraints.

package/docs/command-reference.md

@@ -1,39 +1,41 @@
 # Command reference
 
-All package commands operate on local files. The examples run version `0.1.1` through npm; `npx` may ask permission to fetch that package on first use. Replace `.` with the target project path when needed. For a source checkout, see the [development guide](./development.md).
+All package commands operate on local files. The examples run version `0.2.0` through npm; `npx` may ask permission to fetch that package on first use. Replace `.` with the target project path when needed. For a source checkout, see the [development guide](./development.md).
+
+Global flags available on every invocation: `--version` (or `-v`) prints the package version and exits; `--help` prints usage.
 
 ## `init`
 
 ```sh
-npx --package @felixdotgo/aidlc-kit@0.1.1 aidlc-kit init [path] [--agent <name[,name]> | --all] [--loop-mode off|local|fleet] [--loop-lead codex|claude|opencode] [--loop-workers <id=provider,...>] [--yes] [--dry-run] [--force]
+npx --package @felixdotgo/aidlc-kit@0.2.0 aidlc-kit init [path] [--agent <name[,name]> | --all] [--loop-mode off|local|fleet] [--loop-lead codex|claude|opencode] [--loop-workers <id=provider,...>] [--yes] [--dry-run] [--force]
 ```
 
 Plans the installation, prints a preview, and then writes the workflow only after confirmation (or `--yes`). `--dry-run` prints the same plan without writing. If exactly one installed agent is detected, it can be selected automatically. In an interactive terminal, choose multiple agents with the checkbox prompt: use arrow keys to move, Space to toggle, A to toggle all, and Enter to confirm. For scripts and non-interactive terminals, use `--agent <name[,name]>` or `--all`.
 
-In interactive setup, choose a loop mode and, when enabled, the lead and worker providers. For non-interactive setup, omit loop options to keep the default off, or specify `--loop-mode local|fleet` together with `--loop-lead` and `--loop-workers` (for example, `--loop-workers a=codex,b=opencode`). The preview includes the project config change. These settings only configure the loop; run `aidlc-kit loop start` to actually start it. The loop and the coordination service are experimental: their flags and defaults may change incompatibly in any release before `1.0.0`.
+In interactive setup, choose a loop mode and, when enabled, the lead and worker providers. For non-interactive setup, omit loop options to keep the default off, or specify `--loop-mode local|fleet` together with `--loop-lead` and `--loop-workers` (for example, `--loop-workers a=codex,b=opencode`). The preview includes the project config change. These settings only configure the loop; run `aidlc-kit loop start` to actually start it. Local loop mode is usable today; fleet mode is still under active development; the loop and the coordination service remain experimental: their flags and defaults may change incompatibly in any release before `1.0.0`.
 
 `--force` is for an intentional initial replacement of an unmanaged conflicting file. It is not an upgrade mechanism. If the project already has another workflow package version, use the human-run upgrade flow instead.
 
 ## `status`
 
 ```sh
-npx --package @felixdotgo/aidlc-kit@0.1.1 aidlc-kit status [path]
+npx --package @felixdotgo/aidlc-kit@0.2.0 aidlc-kit status [path] [--json]
 ```
 
-Reports the installed version and local installation status. It does not query a registry.
+Reports the installed version and local installation status. It does not query a registry. Pass `--json` to print the same data as a JSON object (`workflow`, `installedVersion`, `schema`, `detectedAgents`).
 
 ## `doctor`
 
 ```sh
-npx --package @felixdotgo/aidlc-kit@0.1.1 aidlc-kit doctor [path] [--strict]
+npx --package @felixdotgo/aidlc-kit@0.2.0 aidlc-kit doctor [path] [--strict] [--json]
 ```
 
-Checks the local manifest, configuration, and canonical state. `--strict` turns compatibility warnings such as a legacy manifest into errors. It does not query a registry.
+Checks the local manifest, configuration, and canonical state. `--strict` turns compatibility warnings such as a legacy manifest into errors. It does not query a registry. Pass `--json` to print `{level, message, strict}`; an `error` level sets a non-zero exit code.
 
 ## `profile validate`
 
 ```sh
-npx --package @felixdotgo/aidlc-kit@0.1.1 aidlc-kit profile validate [path]
+npx --package @felixdotgo/aidlc-kit@0.2.0 aidlc-kit profile validate [path]
 ```
 
 Loads `.agents/config.json`, resolves its profile chain, and prints the effective profile order. Use it after changing `extends` or local profiles.
@@ -41,7 +43,7 @@ Loads `.agents/config.json`, resolves its profile chain, and prints the effectiv
 ## `uninstall`
 
 ```sh
-npx --package @felixdotgo/aidlc-kit@0.1.1 aidlc-kit uninstall [path] [--yes] [--dry-run]
+npx --package @felixdotgo/aidlc-kit@0.2.0 aidlc-kit uninstall [path] [--yes] [--dry-run]
 ```
 
 Prints the removal plan before applying it. It removes eligible unchanged managed assets but preserves project configuration and state. Prefer `--dry-run` first when working in an existing project.
@@ -49,15 +51,17 @@ Prints the removal plan before applying it. It removes eligible unchanged manage
 ## `mcp setup`
 
 ```sh
-npx --package @felixdotgo/aidlc-kit@0.1.1 aidlc-kit mcp setup [path] [--dry-run] [--yes] [--storage sqlite|postgres] [--deployment docker|remote] [--bind localhost|network] [--workspace <id>] [--poll-ms <n>] [--enable]
+npx --package @felixdotgo/aidlc-kit@0.2.0 aidlc-kit mcp setup [path] [--dry-run] [--yes] [--storage sqlite|postgres] [--deployment docker|remote] [--bind localhost|network] [--workspace <id>] [--poll-ms <n>] [--token-env <name>] [--providers <p,...>] [--enable]
 ```
 
 Previews the optional AI-DLC Coordination service configuration, then writes only after confirmation. Non-interactive use requires `--deployment`, `--storage`, `--bind`, and `--workspace`. It never starts Docker; `--enable` is explicit and remote mode has no local fallback. See [AI-DLC Coordination service](./coordination-service.md) for deployment and credential requirements.
 
+`--token-env <name>` overrides the default `AIDLC_MCP_TOKEN` environment variable name used in the generated compose file. `--providers <p,...>` selects project-management connectors non-interactively (`jira`, `trello`, `github-issues`).
+
 ## `upgrade`
 
 ```sh
-npx --package @felixdotgo/aidlc-kit@0.1.1 aidlc-kit upgrade [path] [--loop-mode off|local|fleet] [--loop-lead codex|claude|opencode] [--loop-workers <id=provider,...>] [--dry-run]
+npx --package @felixdotgo/aidlc-kit@0.2.0 aidlc-kit upgrade [path] [--loop-mode off|local|fleet] [--loop-lead codex|claude|opencode] [--loop-workers <id=provider,...>] [--dry-run]
 ```
 
 Upgrade is deliberately human-only. The command rejects `--yes` and `--force`; applying it requires an interactive terminal and an exact typed confirmation of the package version. Interactive confirmations use the same styled terminal prompt as `init`. Agents must not run, preview, detect, or suggest package upgrades on their own.
@@ -69,19 +73,76 @@ The upgrade plan handles supported legacy `.aidlc/` project data transactionally
 ## `loop`
 
 ```sh
-npx --package @felixdotgo/aidlc-kit@0.1.1 aidlc-kit loop start|status|resume [options]
+npx --package @felixdotgo/aidlc-kit@0.2.0 aidlc-kit loop start [--root PATH] [--mode local|fleet]
+npx --package @felixdotgo/aidlc-kit@0.2.0 aidlc-kit loop intake [--task-id ID] [--title TITLE] [--root PATH] [--mode local|fleet]
+npx --package @felixdotgo/aidlc-kit@0.2.0 aidlc-kit loop status --task-id ID [--root PATH] [--mode local|fleet]
+npx --package @felixdotgo/aidlc-kit@0.2.0 aidlc-kit loop worker-image [--provider opencode|codex|claude] [--tag TAG] [--root PATH]
 ```
 
 > [!WARNING]
-> The loop commands and fleet mode are **experimental and unfinished**: they contain known bugs and rough edges, and — because the package is still pre-1.0 (`0.x`) — their options, environment variables, and diagnostics can change incompatibly in any release before `1.0.0`.
+> **Local loop mode is usable** today; **fleet mode is still under active development**. The loop commands remain **experimental** — because the package is still pre-1.0 (`0.x`), their options, environment variables, and diagnostics can change incompatibly in any release before `1.0.0`.
+
+`--mode` defaults to the configured `loop.mode`; the command fails closed when it does not match (`Requested mode does not match configured authority`). Every action except `worker-image` requires an enabled `loop.mode` with a lead and worker mapping. Local and fleet mode share one daemon and the same actions:
+
+| Action | Behaviour |
+| --- | --- |
+| `start` | Starts the singleton loop daemon for the project in the foreground (lock `.agents/data/loop/daemon.lock`; a second `start` fails with `Loop daemon already running (pid N)`). It reads **no** requirement. Fleet `start` first preflights the coordination service (`fleet_get`) and the remote integration branch and fails closed instead of falling back to local. |
+| `intake` | Creates one loop-owned task without running it. The requirement is read from stdin (an interactive prompt on a TTY), at most 8192 bytes; the id and title are derived from its first line unless `--task-id`/`--title` are given. Local intake refuses while an interactive (non-loop) task is actionable. Fleet intake creates the remote task under a short lead claim. Both write `.agents/data/tasks/<id>/loop-intake.json` (`authority: "local"` or `"fleet"`). |
+| `status` | Prints the canonical task and its derived next action; local mode adds the loop run record, fleet mode the durable gate checkpoint. |
+| `worker-image` | Builds (or rebuilds) the shipped worker image without requiring loop configuration: `--provider` defaults to `opencode`, `--tag` to `aidlc-worker-<provider>:local`. It runs `docker build` against the packaged `assets/aidlc/docker/Dockerfile.<provider>` and records the tag in `config.loop.workerImage`. |
+
+`loop resume` is removed in both modes; it fails with `loop resume is removed; the daemon auto-resumes actionable tasks — run 'loop start' …`. Re-activate a paused task with the dashboard **resume** button, `state.mjs task status <id> --status active` (local), or `node .agents/aidlc/scripts/loop-entry.mjs resume-task <id> .` (either mode).
+
+The daemon only runs **loop-owned** tasks: locally, tasks with an intake record or a loop run record; in fleet mode, only tasks whose local intake record says `authority: "fleet"`. Tasks created by an interactive lead are never picked up. Every `loop.pollMs` (default `5000` ms) it lists actionable loop-owned tasks and runs one bounded supervised run per task in round-robin order (bounded by the per-run `loop.limits.maxTurns`). A run that throws, or ends `blocked` or `reconcile`, is retried with exponential backoff (poll interval doubled per failure, capped at 10 minutes). A gate wait or completion does not stop the daemon, and an unreachable authority (for example the fleet service) is reported as `daemon_poll_error` and retried on the next poll. In fleet mode a run returns at a gate (`gate`/`waiting`) and releases the supervisor lease; after the reviewer approves, the next poll re-claims the task and continues.
+
+Shutdown is two-stage in both modes: the first `SIGINT`/`SIGTERM` stops after the current turn, the second cancels the in-flight agent turn (and any build worker batch), and the third exits immediately. A terminal `Ctrl-C` also reaches the agent child process, so the in-flight turn usually ends on the first press. Stopped runs are recorded as `stopped` (the task is not paused) and continue on the next `start`. Events go to stderr, carry their `taskId`, and are also appended to the JSONL file named by `AIDLC_LOOP_EVENT_LOG` when set. Daemon events include `daemon_start`, `daemon_poll`, `daemon_poll_error`, `daemon_turn`, `daemon_turn_error`, `build_deferred` (a ready build item waiting for a later batch), `gate`, and `loop_stopped`.
+
+Local mode requires Docker plus the provider credential environment; the worker image is auto-built from the packaged Dockerfile on first dispatch and its tag is recorded automatically, so `AIDLC_WORKER_DOCKER_IMAGE` is only needed to override the default. Local approval happens through the trusted host terminal command `node .agents/aidlc/scripts/loop-gate.mjs <task-id>`, which refuses piped input, or the dashboard.
+
+Fleet mode requires `AIDLC_FLEET_URL`, `AIDLC_FLEET_WORKSPACE`, the lead `AIDLC_FLEET_TOKEN`, and `AIDLC_FLEET_INTEGRATION_BRANCH` (optionally `AIDLC_FLEET_GIT_REMOTE`). The facade derives `AIDLC_FLEET_PROJECT_ROOT`, `AIDLC_FLEET_WORKER_IDS`, `AIDLC_FLEET_WORKER_PROVIDERS`, and the lead agent from the root and `loop.agents`; explicitly set values must match. `loop.limits` (`maxTurns`, `turnTimeoutMs`, `maxStallTurns`) and `loop.pollMs` become the fleet defaults, and an explicit `AIDLC_FLEET_MAX_TURNS`, `AIDLC_FLEET_TURN_TIMEOUT_MS`, `AIDLC_FLEET_MAX_STALL_TURNS`, or `AIDLC_FLEET_POLL_MS` still overrides them. Lead and worker processes never receive `AIDLC_FLEET_REVIEWER_TOKEN`. Fleet workers run separately through the fleet runner on each worker machine, and a reviewer approves gates with the reviewer credential as documented in [Coordination service](./coordination-service.md).
+
+The installed `loop-entry.mjs` is the single entry point behind the CLI and the dashboard. Its positional form is `loop-entry.mjs <action> [task-id] [root] [mode] [provider] [tag] [title]`, for example `echo "<requirement>" | node .agents/aidlc/scripts/loop-entry.mjs intake "" .`. Besides the actions above it accepts `resume-task <id>` (re-activate a paused task, both modes) and the fleet-only dashboard JSON actions `tasks`, `task <id>`, `gate <id>` (current review snapshot with its checkpoint), and `approve <id>` (approval source on stdin; reviewer credential only from that process's `AIDLC_FLEET_REVIEWER_TOKEN`). A local dashboard reads local state in-process, so those read actions fail in local mode.
+
+## `ui`
+
+```sh
+npx --package @felixdotgo/aidlc-kit@0.2.0 aidlc-kit ui [path] [--port 4173] [--host 127.0.0.1] [--open] [--token-file PATH] [--reviewer-token-file PATH]
+```
+
+Starts a web dashboard (built on `node:http`, no extra dependencies) for viewing task status and operating the loop without typing CLI commands repeatedly. The project is the positional `path` (default `.`); `ui` has no `--root` flag. The authority comes from `loop.mode`: the header shows `authority · local` or `authority · fleet`. Local dashboards read canonical local state in-process; fleet dashboards read tasks, task details, and gate snapshots (review text from the coordination service) through the `loop-entry.mjs` JSON actions.
+
+| Flag | Effect |
+| --- | --- |
+| `--port`, `--host` | Bind address; defaults to `127.0.0.1:4173`. Pass `--host 0.0.0.0` only as an explicit opt-in. |
+| `--open` | Launches the system browser with the login URL (best effort; the URL is printed anyway). |
+| `--token-file PATH` | Uses a fixed session token from `PATH` so the browser stays signed in across restarts. The file must live outside the project, be a regular non-symlink file with mode `600`/`400`, and hold one 16–256 character token; a missing file is created with a random token. |
+| `--reviewer-token-file PATH` | Fleet only: reads the reviewer credential from `PATH` (same file rules, never created). `AIDLC_FLEET_REVIEWER_TOKEN` in the `ui` environment works the same way. |
+
+Routes:
+
+- `GET /` renders a **kanban board by default** (columns grouped by `phase`: clarify / plan / build / wrap / done) with a list/table toggle, plus **New task** and **Settings** modals. The page uses the full window width and is branded **Loop**. Clicking a task opens a **side panel** that slides in from the right (`/?task=<id>` opens it directly; Back or <kbd>Esc</kbd> closes it); ctrl/cmd-click or middle-click opens the full detail page.
+- `GET /tasks/:id` renders the full task detail page: a horizontal progress stepper, a structured gate view (in fleet mode the review snapshot text), rendered `intent`/`design`/`workplan` artifacts (Markdown), decisions, work items, evidence, details, and a live log stream. `GET /partial/tasks/:id` returns the same detail body as an HTML fragment for the side panel.
+- `GET /api/tasks` returns task summaries as JSON (`?archive=1`, `?statuses=`, `?query=`, `?limit=`, `?cursor=`); `GET /api/tasks/:id` returns one task; `GET /api/tasks/:id/gate` returns the gate view or fleet snapshot (`409` when the task is not waiting); `GET /api/tasks/:id/artifact/:name` returns raw artifact content for programmatic clients.
+- `GET /api/loop/status?task-id=` returns `loop status` as JSON. `POST /api/loop/start` (field `requirement`) runs loop intake and starts the daemon if none is running (`201` with `taskId`, `title`, `daemon`; `409` with the intake error). `POST /api/loop/resume` (field `taskId`) re-activates a `paused` task (`409` for any other status). `POST /api/gate/approve` (fields `taskId`, `source`) runs the atomic `state.mjs gate approve` locally, or the fleet reviewer approval of the current snapshot. All spawn the installed scripts asynchronously as thin facades; a malformed or non-object JSON body is a `400`.
+- `GET /api/events[?task-id=]` streams the event-log sidecar as SSE: on connect the last 200 matching lines within the most recent 256 KB, then new complete lines; it follows rotation/truncation and resumes from `Last-Event-ID`.
+
+### Dashboard authentication
+
+At start the CLI prints a login URL such as `http://127.0.0.1:4173/#token=<token>`. Opening it stores the token in the browser's `localStorage` and strips the fragment from the address bar (a fragment is never sent to the server); **⚙ Settings** still accepts a pasted token. There is no unauthenticated mode. The rules:
 
-Options: `--task-id <id>` (optional for `start`, which derives one; required for `status`/`resume`), `--root <path>`, and `--mode local|fleet` (defaults to the configured `loop.mode`). `start` reads the requirement from an interactive prompt or stdin — the requirement is never passed as an argument. The command fails closed when the requested mode does not match the configured authority, when another task is actionable, or when a resume record is missing.
+- The mutating actions (new task, resume, gate approve) require the token in a header — `x-aidlc-token` or `Authorization: Bearer <token>` — never in a form or JSON body field. A missing or wrong token is `401`.
+- Every request whose `Host` header does not name the bound address is rejected `403` (any loopback name — `127.0.0.1`, `localhost`, `[::1]` — is accepted when bound to loopback). A wildcard bind (`0.0.0.0`, `::`) cannot pin the Host and relies on the token and the Origin check.
+- A non-`GET` request whose `Origin` is not the dashboard's own origin is rejected `403`.
+- In fleet mode, `POST /api/gate/approve` returns `403` unless the UI holds a reviewer credential (`AIDLC_FLEET_REVIEWER_TOKEN` or `--reviewer-token-file`); the detail page then shows the `remote-state.mjs gate inbox` / `gate approve` reviewer commands instead of the approve form. The credential is passed only to that one approve child process.
+- The daemon and every other child process the UI spawns never inherit the UI token or the reviewer credential.
 
-`status` prints the canonical task, its derived next action, and — in fleet mode — the durable gate checkpoint. `start` and `resume` run the supervisor in the foreground until the next gate, a pause, a blocked state, or completion; the emitted events include each gate view and the waiting state.
+These rules exist because a browser will send requests to `127.0.0.1` on behalf of any web page: a header-only token defeats cross-site form posts (CSRF), the Host check defeats DNS rebinding, and keeping tokens out of the daemon environment stops a host-executed lead from approving its own gate. Residual risk: a `--token-file` is readable by any process running as the same user, so prefer the per-session token unless you need restarts to keep the browser signed in.
 
-Local mode requires the Docker worker image configuration described in [Testing and release](./testing-and-release.md) plus the provider credential environment; approval happens through the trusted host terminal command `node .agents/aidlc/scripts/loop-gate.mjs <task-id>`, which refuses piped input.
+Operational notes:
 
-Fleet mode requires the running coordination service (`AIDLC_FLEET_URL`, `AIDLC_FLEET_WORKSPACE`, lead `AIDLC_FLEET_TOKEN`, `AIDLC_FLEET_INTEGRATION_BRANCH`, and optionally `AIDLC_FLEET_GIT_REMOTE`); worker IDs must match the configured `loop.agents.workers`, and `AIDLC_FLEET_WORKER_PROVIDERS` may map each worker to `codex`, `claude`, or `opencode`. The facade preflights the service and the integration branch and fails closed with a diagnosis instead of falling back to local. Fleet worker containers reject `opencode` with the container diagnostic above; assignment validation accepts it so that blocker surfaces when the job executes rather than being reported as an invalid provider. Fleet workers run separately through the fleet runner (`worker --once`) on each worker machine with `AIDLC_WORKER_DOCKER_IMAGE` and their own worker credential; a reviewer approves gates through the reviewer credential as documented in [Coordination service](./coordination-service.md).
+- The gate **approve** form renders only on the full task detail page (`/tasks/:id`) while the task is `blocked_on_user`; on the dashboard such a task shows an **approve** button that opens that page. The dashboard header shows whether the daemon is running.
+- The **live log** on the detail page is an SSE stream of that task's events over the fixed file `.agents/data/loop/ui-events.jsonl` (rotated to `.jsonl.1` at 5 MB). A daemon started by **New task** gets `AIDLC_LOOP_EVENT_LOG` pointed at that file automatically and writes its stderr to `.agents/data/loop/daemon.log`; a **manually started** daemon must export the same variable, or the live log stays empty (see [Loop local run](./loop-local-run.md#51-set-environment-variables)).
+- The dashboard **resume** button appears only on `paused` tasks and sets them back to `active` (locally equivalent to `node .agents/aidlc/scripts/state.mjs task status <id> --status active`; in fleet mode `loop-entry.mjs resume-task`); the daemon then picks the task up on its next poll if it is loop-owned.
 
 ## Installed lifecycle scripts
 
@@ -108,7 +169,7 @@ node .agents/aidlc/scripts/loop.mjs resume <task-id> [--max-turns N] [--turn-tim
 node .agents/aidlc/scripts/loop.mjs status <task-id> [--root PATH]
 ```
 
-`--agent opencode` requires `AIDLC_OPENCODE_MODEL` in `provider/model[#variant]` form; the turn fails closed without it. 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` and do not fall back to the host. Use `loop.mjs run --agent opencode` for host-executed lead turns, or use Codex or Claude Code where container isolation is required.
+`--agent opencode` requires `AIDLC_OPENCODE_MODEL` in `provider/model[#variant]` form; the turn fails closed without it. The container-isolated lead rejects OpenCode with `OpenCode workers require file-based credentials and are not available in isolated containers yet` and does not fall back to the host. Local Docker worker batches and fleet worker containers accept OpenCode via environment credentials — the key follows the `AIDLC_OPENCODE_MODEL` prefix: `openai/` → `OPENAI_API_KEY`, `anthropic/` → `ANTHROPIC_API_KEY`, otherwise `OPENCODE_API_KEY` — with OpenCode's XDG data/config roots redirected into the worker's ephemeral HOME. Use `loop.mjs run --agent opencode` for host-executed lead turns, or use Codex or Claude Code where an isolated lead is required.
 
 The defaults are 12 turns and 10 minutes per turn; two completed turns without observable progress stop the run. Each run records its provider, and `resume` rejects a different agent. The runner never grants human approval. An interactive client can resume by reading `task next` and reconciling local assignment metadata; fleet execution uses fenced service leases and the remote canonical state.
 
@@ -122,7 +183,7 @@ node .agents/aidlc-coordination/src/fleet-run.mjs coordinator <task-id> --once
 node .agents/aidlc-coordination/src/fleet-run.mjs worker --once
 ```
 
-`supervisor` claims the task's supervisor lease, runs fenced lead turns through the coordinator, publishes each gate snapshot with its checkpoint in one service transaction, waits for the reviewer approval, and resumes automatically; it returns at a pause, blocked state, or completion, and never approves a gate. `coordinator --once` runs a single unattended pass without the supervisor lease. `worker --once` claims one ready assignment on a worker machine; it requires `AIDLC_WORKER_DOCKER_IMAGE` and that machine's worker credential and fails closed without them. `aidlc-kit loop start --mode fleet` wraps the same supervisor with requirement intake and preflight.
+`supervisor` claims the task's supervisor lease, runs fenced lead turns through the coordinator, publishes each gate snapshot with its checkpoint in one service transaction, waits for the reviewer approval, and resumes automatically; it returns at a pause, blocked state, or completion, and never approves a gate. `coordinator --once` runs a single unattended pass without the supervisor lease. `worker --once` claims one ready assignment on a worker machine and fails closed without a usable worker image or that machine's worker credential; see [Coordination service](./coordination-service.md#multi-machine-loop-deployment) for how the image is resolved. `aidlc-kit loop start --mode fleet` runs the same supervisor inside the shared loop daemon in a bounded mode that returns at each gate instead of waiting for the reviewer.
 
 Fleet mode uses `remote-state.mjs` instead of local `state.mjs`. Set `AIDLC_FLEET_URL`, `AIDLC_FLEET_WORKSPACE`, and `AIDLC_FLEET_PROJECT_ROOT`; lead mutations additionally require `AIDLC_FLEET_TOKEN` and the current `AIDLC_FLEET_LEAD_EPOCH`. Claim an epoch before creating or changing a task:
 
@@ -158,7 +219,7 @@ node .agents/aidlc/scripts/state.mjs gate approve <task-id> --gate <gate> --sour
 node .agents/aidlc/scripts/state.mjs task transition <task-id> --to <phase> --mode audited --reason "<reason>" --source "<source>"
 ```
 
-Self-transitions are rejected, and `task create` rejects an id that collides case-insensitively with an existing task or archive record. `task create` also fails while another unrelated task is actionable; its `--switch-from <ids>` acknowledgement still requires explicit user direction. `--feature <feature-id>` permits sibling tasks in an existing feature without abandoning them. `feature link` checks membership and task dependencies; `task item ... --depends-on <item-id,...> --owns <path,...>` adds item edges and an optional Git path scope. Fleet dispatch requires a nonempty path scope. Path scopes are normalized (trailing slashes stripped) and may name either a file or a directory; directory scopes cover every file beneath them. Missing and cyclic dependencies fail, and an item or feature task cannot finish before its prerequisites. After reopening the Approve plan step, all non-deferred execution items return to `todo`; prior Review implementation, verification, and review evidence cannot satisfy the new build boundary, and repair-bound counters reset with it.
+Self-transitions are rejected, and `task create` rejects an id that collides case-insensitively with an existing task or archive record. `task create` also fails while another unrelated task is actionable; its `--switch-from <ids>` acknowledgement still requires explicit user direction. `--feature <feature-id>` permits sibling tasks in an existing feature without abandoning them. `feature link` checks membership and task dependencies; `task item ... --depends-on <item-id,...> --owns <path,...>` adds item edges and an optional Git path scope. Loop dispatch (local and fleet) requires a nonempty path scope. When `loop.mode` is `local` or `fleet`, the Approve plan check also fails with `PARTITION_SCOPE` for an open item without `--owns`, and with `PARTITION_OVERLAP` when two items that can run concurrently (no direct or transitive `--depends-on` between them) own overlapping paths; with the loop off both are warnings. Overlap is per path segment: `src` overlaps `src/a.ts` but not `srcx`. The rendered workplan shows each item's scope as `owns: … · after: …`. Path scopes are normalized (trailing slashes stripped) and may name either a file or a directory; directory scopes cover every file beneath them. Missing and cyclic dependencies fail, and an item or feature task cannot finish before its prerequisites. After reopening the Approve plan step, all non-deferred execution items return to `todo`; prior Review implementation, verification, and review evidence cannot satisfy the new build boundary, and repair-bound counters reset with it.
 
 State writes and generated workplans use symlink-checked atomic replacement. State-lock release is owner-token checked and never removes a replacement owner's lock. If a process stops after writing a terminal archive record but before committing the catalog, a retry replaces that orphan only when the persisted catalog still contains the same active task identity and does not reference an archive record; malformed, referenced, or identity-conflicting records fail closed.
 

package/docs/configuration.md

@@ -22,6 +22,18 @@ 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.
 
+## Optional `$schema` key
+
+The generated `.agents/config.json` includes an optional top-level `$schema` key pointing at the relative path `./aidlc/schemas/config.schema.json` (the schema installed under `.agents/aidlc/schemas/`). Editors use it for autocompletion and validation of the configuration file, and it has no runtime effect. New installs receive it automatically through `init`; existing installs can add it manually:
+
+```json
+{
+  "$schema": "./aidlc/schemas/config.schema.json"
+}
+```
+
+The value must be a string of at most 512 characters. The path is relative so validation works offline without a network dependency.
+
 G0, G1, and G2 always require explicit human approval. Configuration cannot auto-pass a gate.
 
 ## Configuration layers
@@ -42,10 +54,10 @@ Built-in topology profiles are:
 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 .
+npx --package @felixdotgo/aidlc-kit@0.2.0 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).
+This command uses the npm package at version `0.2.0`. To run from a source checkout instead, see the [development guide](./development.md).
 
 ## Rules, project data, and managed assets
 
@@ -71,24 +83,32 @@ Set the default risk level deliberately. Planning, migrations, cross-service con
 
 ## 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. 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 (and fleet mode) is **experimental and still under active development** (known bugs included), and it can change incompatibly in any release before `1.0.0`.
 
 ## 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`.
+> The loop is **experimental** and pre-1.0 (`0.x`): the `loop.*` fields, provider mappings, and environment variables can change incompatibly in any release before `1.0.0`. **Local mode is usable** today; **fleet mode is still under active development**.
 
-`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`:
+`loop.mode` can be `off`, `local`, or `fleet`; an absent `loop` field means `off`. Both enabled modes run the loop as the same persistent multi-task daemon (one per project, enforced by a lock): `loop start` launches it, and it polls the configured authority — canonical local state, or the coordination service in `fleet` mode — auto-picking every actionable **loop-owned** task without prompting for a requirement. A task is loop-owned when it was created through loop intake (the web dashboard **New task**, `aidlc-kit loop intake`, or `loop-entry.mjs intake`) or, locally, already has a loop run record; fleet ownership is recorded by the intake file `.agents/data/tasks/<id>/loop-intake.json` with `authority: "fleet"`. Tasks created by an interactive lead are never picked up. The optional `loop.agents` maps one lead and named workers to `codex`, `claude`, or `opencode`, independently of `mcp.providers`:
 
 ```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.
+The optional `loop.pollMs` (integer, `1000`–`300000`, default `5000`) sets the daemon's poll interval. The optional `loop.limits` bounds each supervised lead run: `maxTurns` (`1`–`1000`, default `12`) is the turn budget of **one run** — a resumed run starts a fresh budget, so a long multi-gate task is not permanently re-paused — `turnTimeoutMs` (`1`–`3600000`, default `600000`) caps a single agent turn, and `maxStallTurns` (`1`–`20`, default `2`) pauses after that many consecutive turns without observable progress. `loop.pollMs` and `loop.limits` apply to `fleet` mode as well: `loop start` passes them to the fleet supervisor as `AIDLC_FLEET_MAX_TURNS`, `AIDLC_FLEET_TURN_TIMEOUT_MS`, `AIDLC_FLEET_MAX_STALL_TURNS`, and `AIDLC_FLEET_POLL_MS`, and an explicitly exported value of any of those variables overrides the config.
+
+The optional `loop.workerImage` maps a provider to a worker Docker image tag (for example `{ "opencode": "aidlc-worker-opencode:local" }`). `aidlc-kit loop worker-image` records it; local build dispatch and fleet worker machines use it, falling back to `aidlc-worker-<provider>:local`, which is auto-built from the packaged Dockerfile when missing. `AIDLC_WORKER_DOCKER_IMAGE` overrides it.
+
+With `loop.mode` set to `local` or `fleet`, the Approve plan gate check enforces a parallel work partition: every open build item needs owned paths (`PARTITION_SCOPE`), and items that can run concurrently must not own overlapping paths (`PARTITION_OVERLAP`). With the loop `off` the same findings are warnings and the gate still passes. See [Troubleshooting](./troubleshooting.md#parallel-work-partition-partition_overlap--partition_scope).
+
+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. The container-isolated lead rejects OpenCode with `OpenCode workers require file-based credentials and are not available in isolated containers yet`; it does not fall back to the host. Local Docker worker batches and fleet worker containers accept OpenCode: they authenticate from the environment key matching the model prefix (`openai/` → `OPENAI_API_KEY`, `anthropic/` → `ANTHROPIC_API_KEY`, otherwise `OPENCODE_API_KEY`) and redirect OpenCode's XDG data/config roots into the worker's ephemeral HOME.
 
-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).
+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` to launch the daemon. Existing fleet operations and storage requirements are documented in [Coordination service](./coordination-service.md).