@felixdotgo/aidlc-kit 0.1.1 → 0.2.0

package/DEVELOPMENT.md

@@ -12,6 +12,20 @@ npm test
 npm run lint
 ```
 
+## Workflow bootstrap
+
+`.agents/` is gitignored; every contributor installs the repo's own workflow locally.
+
+```sh
+npm install
+npm run build
+node dist/src/cli.js init . --agent <codex|claude|opencode> --yes
+```
+
+Then configure `.agents/config.json`: set `commands` to build/test/lint as executable+args arrays (`build`: `npm`/`["run","build"]`, `test`: `npm`/`["test"]`, `lint`: `npm`/`["run","lint"]`) and `agentState` mapping your adapter id to `"scripted"`. Validate with `node dist/src/cli.js profile validate .`.
+
+See [Configuration reference](./docs/configuration.md) and [Development guide](./docs/development.md).
+
 ## Contributor documentation
 
 - [Development guide](./docs/development.md) — dependencies, repository layout, implementation boundaries, and local commands.

package/README.md

@@ -1,28 +1,33 @@
 # aidlc-kit
 
+[![npm version](https://img.shields.io/npm/v/@felixdotgo/aidlc-kit)](https://www.npmjs.com/package/@felixdotgo/aidlc-kit)
+[![license](https://img.shields.io/npm/l/@felixdotgo/aidlc-kit)](https://github.com/felixdotgo/aidlc-kit/blob/main/LICENSE)
+[![node](https://img.shields.io/node/v/@felixdotgo/aidlc-kit)](https://nodejs.org/)
+
 `@felixdotgo/aidlc-kit` installs an AI-DLC workflow into an existing project. The workflow gives coding agents a shared task lifecycle, dependency-aware work, explicit human review gates, and project-owned state and rules. The normal lead runs in your Codex, Claude Code, or OpenCode conversation; an optional coordination service supports workers on multiple machines.
 
 Workflow assets are bundled with the package, `remoteUpdates` is `false`, and normal status checks never contact a registry. Fleet execution is opt-in and uses a separately deployed service. The optional end-to-end loop is also opt-in: select a mode during `init` or a human-run `upgrade`, then start it explicitly with `aidlc-kit loop start` — selecting a mode never starts or approves anything by itself.
 
 > [!WARNING]
-> The optional end-to-end loop and the AI-DLC Coordination service are **experimental and unfinished**: they contain known bugs and rough edges. The package is pre-1.0 (`0.x`), so their CLI flags, `loop.*`/`mcp.*` configuration fields, environment variables, and installed layouts can change incompatibly in any release before `1.0.0`.
+> **Local loop mode is usable** today; **fleet mode and the AI-DLC Coordination service are still under active development**. The loop is **experimental** — the package is pre-1.0 (`0.x`), so CLI flags, `loop.*`/`mcp.*` configuration fields, environment variables, and installed layouts can change incompatibly in any release before `1.0.0`.
 
 ## Requirements
 
 - Node.js 20.17 or newer.
 - An existing project directory.
 - Codex, Claude Code, or OpenCode.
+- Supported platforms: Linux and macOS are fully supported; Windows is best-effort (see `docs/development.md` Platform support). Loop/fleet features require Docker and a POSIX shell.
 
 ## Quick start
 
 Run these commands from your existing project's directory to preview the installation, then apply it:
 
 ```sh
-npx --package @felixdotgo/aidlc-kit@0.1.1 aidlc-kit init . --agent codex --dry-run
-npx --package @felixdotgo/aidlc-kit@0.1.1 aidlc-kit init . --agent codex --yes
+npx --package @felixdotgo/aidlc-kit@0.2.0 aidlc-kit init . --agent codex --dry-run
+npx --package @felixdotgo/aidlc-kit@0.2.0 aidlc-kit init . --agent codex --yes
 ```
 
-`npx` may ask permission to download the package on first use. These examples pin version `0.1.1`. After installation, the project's lifecycle scripts run locally without `npx` or a registry connection.
+`npx` may ask permission to download the package on first use. These examples pin version `0.2.0`. After installation, the project's lifecycle scripts run locally without `npx` or a registry connection.
 
 Use the adapter that matches the coding tool:
 
@@ -37,8 +42,8 @@ Use `--all` to install every supported adapter. Codex installs workspace-write s
 Confirm the installed project locally:
 
 ```sh
-npx --package @felixdotgo/aidlc-kit@0.1.1 aidlc-kit status .
-npx --package @felixdotgo/aidlc-kit@0.1.1 aidlc-kit doctor . --strict
+npx --package @felixdotgo/aidlc-kit@0.2.0 aidlc-kit status .
+npx --package @felixdotgo/aidlc-kit@0.2.0 aidlc-kit doctor . --strict
 ```
 
 ## Documentation
@@ -58,13 +63,6 @@ The detailed documentation is organised by task and audience:
 
 Only a human may initiate or apply a workflow upgrade. `upgrade` rejects `--yes` and `--force`, requires an interactive terminal, and asks the human to type the target package version. See the [command reference](./docs/command-reference.md#upgrade) before changing an existing installation.
 
-## Recent changes
-
-- Synced the two committed ESM lifecycle cores so `lifecycle-core-conformance` passes.
-- Normalized Git path scopes (trailing slashes stripped) consistently across fleet, local-worker, and snapshot flows; directory scopes now work in all three.
-- Hardened the state lock to reclaim partially written (corrupt) lock files instead of wedging mutations.
-- Made the fleet end-to-end test skip cleanly when its Docker worker image is unavailable.
-
 ## License
 
 MIT

package/dist/assets/.agents/aidlc/docker/Dockerfile.claude

@@ -0,0 +1,7 @@
+# AI-DLC worker image (Claude Code). Shipped and managed by aidlc-kit — build it
+# with `aidlc-kit loop worker-image --provider claude` instead of by hand.
+#
+# The agent CLI must be on the system PATH: workers run non-root with a read-only
+# root filesystem, so a global npm install lands the binary in /usr/local/bin.
+FROM node:24-bookworm-slim
+RUN npm install -g @anthropic-ai/claude-code

package/dist/assets/.agents/aidlc/docker/Dockerfile.codex

@@ -0,0 +1,9 @@
+# AI-DLC worker image (OpenAI Codex CLI). Shipped and managed by aidlc-kit —
+# build it with `aidlc-kit loop worker-image --provider codex` instead of by hand.
+#
+# The agent CLI must be on the system PATH: workers run non-root with a read-only
+# root filesystem, so a global npm install lands the binary in /usr/local/bin.
+# Use the scoped `@openai/codex` package (the unscoped `codex` npm package is
+# unrelated).
+FROM node:24-bookworm-slim
+RUN npm install -g @openai/codex

package/dist/assets/.agents/aidlc/docker/Dockerfile.opencode

@@ -0,0 +1,8 @@
+# AI-DLC worker image (OpenCode 2). Shipped and managed by aidlc-kit — build it
+# with `aidlc-kit loop worker-image --provider opencode` instead of by hand.
+#
+# The agent CLI must be on the system PATH: workers run non-root with a read-only
+# root filesystem, so a global npm install lands the binary in /usr/local/bin.
+# Use `@opencode/cli` (OpenCode 2) — NOT `opencode-ai` (OpenCode 1).
+FROM node:24-bookworm-slim
+RUN npm install -g @opencode/cli

package/dist/assets/.agents/aidlc/orchestrator.md

@@ -52,7 +52,7 @@ Economy models use the same bounded packet contract, gates, executable checks, a
 - The lead is the single writer for lifecycle state, gate actions, and task review artifacts. Workers never approve or present gates, mutate lifecycle records, or make canonical artifact decisions; every human-gate and state-machine invariant remains in force.
 - Each worker assignment must name a bounded objective, owned paths or read-only scope, dependencies, expected verification, and required return output (summary, changed paths, evidence, and concerns). The lead integrates and verifies worker results before recording evidence or advancing the task.
 - In local interactive mode, before dispatching a canonical build item, run `assignment.mjs claim <task-id> <item-id> --worker <worker-id> --paths <comma-separated-owned-paths>`. Pass the returned assignment ID to the native worker. Use `assignment.mjs heartbeat` for long work and `assignment.mjs report` when it returns. After integration and canonical item completion, run `assignment.mjs reconcile`. An expired claim becomes `uncertain`; inspect its files and report before `assignment.mjs release` and any retry. Do not use assignments to store approvals or mark canonical items done.
-- Assign one writer per path. Partition work so concurrent changes cannot overlap; workers may inspect shared files, but must report a needed cross-owner change to the lead rather than edit it. The lead resolves conflicts and performs final integration.
+- Assign one writer per path. Partition work so concurrent changes cannot overlap; workers may inspect shared files, but must report a needed cross-owner change to the lead rather than edit it. The lead resolves conflicts and performs final integration. Canonical build items carry this partition as `ownedPaths`/`dependsOn`; the Approve plan gate check reports `PARTITION_OVERLAP`/`PARTITION_SCOPE` when concurrently-runnable items overlap or lack owned paths.
 
 ## Customization layers
 

package/dist/assets/.agents/aidlc/phase-clarify.md

@@ -7,7 +7,7 @@ When independent, read-only index or ambiguity checks exist, use the shared orch
 1. Read the compact repository/spec indexes if available; do not scan implementation code.
 2. Read `templates/model-contract.md` and apply its COSTARS clarify emphasis to the intent brief. Use CRITICS only for elevated risk, ambiguity, or model disagreement.
 3. Canonical task state already exists from turn routing (`task create` runs there, before this packet). Never create it a second time; a repeated create fails with `Task already exists`.
-4. Fill the intent template: problem, affected areas, assumptions, open questions with safe defaults, and decidable in/out scope.
+4. Fill the intent template: problem, affected areas, work boundaries (independent streams and the paths each touches, or `single stream` with the reason), assumptions, open questions with safe defaults, and decidable in/out scope.
 5. Run `node .agents/aidlc/scripts/gate-check.mjs <task-id> --gate G0_confirm` and fix every structural error. Only after it passes, set the gate wait with `node .agents/aidlc/scripts/state.mjs task status <task-id> --status blocked_on_user`, then render only this task with `node .agents/aidlc/scripts/render.mjs <task-id>`.
 6. Run `node .agents/aidlc/scripts/gate-view.mjs <task-id>`, relay the output verbatim, and stop. Presenting the gate ends this turn.
 

package/dist/assets/.agents/aidlc/phase-plan.md

@@ -6,9 +6,9 @@ Use the shared orchestration contract in `orchestrator.md` to fan out only indep
 
 1. Retrieve only matched specs and impacted symbols. Parallelize bounded discovery when available; return summaries and exact spec anchors, not file dumps.
 2. Read `templates/model-contract.md` and apply its COSTARS plan emphasis. Use CRITICS only for elevated risk, ambiguity, or model disagreement.
-3. Fill the design template with the solution per affected area, exact sources for quantified rules, contracts, risks, and reuse candidates.
+3. Fill the design template with the solution per affected area, exact sources for quantified rules, contracts, risks, reuse candidates, and the Parallel work partition table matching the canonical items.
 4. Add every real judgement call with `node .agents/aidlc/scripts/state.mjs decision set <task-id> <decision-id> --status unresolved --label <label> --resolution <proposed-default>`. Code/spec conflicts and ambiguous enumerations are always decisions.
-5. Add implementation items with `node .agents/aidlc/scripts/state.mjs task item <task-id> <item-id> --status todo --label <label>` and configure narrow verification commands; render the workplan review artifact with `node .agents/aidlc/scripts/render.mjs <task-id>`.
+5. Add implementation items with `node .agents/aidlc/scripts/state.mjs task item <task-id> <item-id> --status todo --label <label> --owns <comma-separated-paths> [--depends-on <item-ids>]` and configure narrow verification commands. Every item passes `--owns`; add `--depends-on` whenever it must touch a path that another concurrently-runnable item owns. With the loop enabled, the Approve plan gate check fails with `PARTITION_OVERLAP`/`PARTITION_SCOPE` until fixed (warning when the loop is off). Then render the workplan review artifact with `node .agents/aidlc/scripts/render.mjs <task-id>`.
 6. Unresolved decisions block the Approve plan gate structurally. Present them to the user and apply each answer with `decision set <task-id> <decision-id> --status approved|changed|dropped --resolution <user-resolution>`. Do not treat a decision answer as gate approval.
 7. When every decision is resolved, run `node .agents/aidlc/scripts/gate-check.mjs <task-id> --gate G1_review` and fix every structural error. Only after it passes, set the gate wait with `node .agents/aidlc/scripts/state.mjs task status <task-id> --status blocked_on_user`, run `node .agents/aidlc/scripts/gate-view.mjs <task-id>`, relay it verbatim, and stop. Approve plan always requires explicit human approval.
 

package/dist/assets/.agents/aidlc/schemas/config.schema.json

@@ -13,7 +13,8 @@
     "context": { "type": "object", "required": ["maxChars"], "properties": { "maxChars": { "type": "integer", "minimum": 4000, "maximum": 128000 } } },
     "agentState": { "type": "object", "additionalProperties": { "enum": ["native", "scripted"] } },
     "tracker": { "type": "object", "additionalProperties": false, "required": ["enabled"], "properties": { "enabled": { "type": "boolean" }, "provider": { "enum": ["backlog"] }, "spaceUrl": { "type": "string", "format": "uri" }, "project": { "type": "string", "minLength": 1 }, "tokenEnv": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" }, "workflow": { "enum": ["waterfall", "scrum"] }, "mapping": { "type": "object", "properties": { "statuses": { "type": "object", "additionalProperties": { "type": "integer", "minimum": 1 } }, "gateFieldId": { "type": "integer", "minimum": 1 } } } } },
-    "mcp": { "type": "object", "additionalProperties": false, "required": ["enabled"], "properties": { "enabled": { "type": "boolean" }, "endpoint": { "type": "string", "format": "uri" }, "workspace": { "type": "string", "minLength": 1 }, "tokenEnv": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" }, "pollMs": { "type": "integer", "minimum": 1000, "maximum": 3600000 }, "providers": { "type": "array", "items": { "enum": ["jira", "trello", "github-issues"] }, "uniqueItems": true } } }
+    "mcp": { "type": "object", "additionalProperties": false, "required": ["enabled"], "properties": { "enabled": { "type": "boolean" }, "endpoint": { "type": "string", "format": "uri" }, "workspace": { "type": "string", "minLength": 1 }, "tokenEnv": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" }, "pollMs": { "type": "integer", "minimum": 1000, "maximum": 3600000 }, "providers": { "type": "array", "items": { "enum": ["jira", "trello", "github-issues"] }, "uniqueItems": true } } },
+    "$schema": { "type": "string", "maxLength": 512 }
   },
   "$defs": {
     "command": {

package/dist/assets/.agents/aidlc/scripts/lib/loop-authority.mjs

@@ -0,0 +1,245 @@
+/**
+ * Loop authority adapters: one interface the shared loop daemon, intake, and
+ * dashboard actions use for both `local` and `fleet` modes.
+ *
+ *   mode                                  "local" | "fleet"
+ *   listActionable()                      loop-owned tasks whose nextAction is run_phase (oldest first)
+ *   runTask({ taskId, signal, cancelSignal, onEvent })
+ *                                         one supervised run until a gate, block, pause, completion or stop
+ *   intake({ requirement, taskId?, title? })  create a loop-owned task without running it
+ *   resumeTask(taskId)                    re-activate a paused task
+ *   listTasks() / getTask(id) / gate(id)  read models for the dashboard (fleet)
+ *   approve({ taskId, source, reviewerToken })  fleet reviewer approval of the current snapshot
+ *
+ * The adapters never approve a gate on their own and never fall back from one
+ * authority to the other. Fleet credentials are scoped: the reviewer token is
+ * stripped from every lead/worker environment and is passed only to the single
+ * `remote-state.mjs gate approve` child of `approve`.
+ */
+import { execFileSync } from "node:child_process";
+import { existsSync, lstatSync, readdirSync, readFileSync, rmdirSync, unlinkSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { requireLocalAuthority } from "./authority.mjs";
+import { isLoopProvider } from "./loop-drivers.mjs";
+import { deriveTaskIdentity, prepareLoopIntake } from "./loop-intake.mjs";
+import { readLoopRecord, validateLimits } from "./loop-runtime.mjs";
+import { createIsolatedLocalSupervisor } from "./loop-supervisor-run-local.mjs";
+import { loadState, loadTask, nextAction } from "./store.mjs";
+
+const ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+const byUpdatedAt = (a, b) => String(a.updatedAt ?? "").localeCompare(String(b.updatedAt ?? "")) || a.id.localeCompare(b.id);
+const tasksDir = (root) => join(root, ".agents", "data", "tasks");
+
+/** The intake record written by `prepareLoopIntake`, or null. */
+export function readIntakeRecord(root, taskId) {
+  if (!ID.test(taskId ?? "")) return null;
+  const path = join(tasksDir(root), taskId, "loop-intake.json");
+  try { if (!lstatSync(path).isFile()) return null; return JSON.parse(readFileSync(path, "utf8")); }
+  catch (error) { if (error?.code === "ENOENT") return null; throw error; }
+}
+
+const stateError = (error) => {
+  const stderr = String(error?.stderr ?? "").trim();
+  try { const parsed = JSON.parse(stderr); if (parsed?.error?.message) return new Error(parsed.error.message); } catch { /* not JSON */ }
+  return stderr ? new Error(stderr.split("\n").filter(Boolean).at(-1)) : error;
+};
+
+/** Pick a unique, case-insensitive task id for an intake that did not name one. */
+const uniqueTaskId = (root, slug, takenIds) => {
+  const dirs = existsSync(tasksDir(root)) ? readdirSync(tasksDir(root)) : [];
+  const existing = new Set([...takenIds, ...dirs].map((id) => id.toLowerCase()));
+  const base = slug.slice(0, 120).replace(/-+$/, "") || "loop-task";
+  let taskId = slug;
+  for (let suffix = 2; existing.has(taskId.toLowerCase()); suffix += 1) taskId = `${base}-${suffix}`;
+  return taskId;
+};
+
+/** Run intake and roll back the intake files this call created when no task came into being. */
+const guardedIntake = async (root, taskId, readTask, body) => {
+  const files = [join(tasksDir(root), taskId, "loop-intake.json"), join(tasksDir(root), taskId, "requirement.md")];
+  const preexisting = files.map((path) => existsSync(path));
+  try { return await body(); }
+  catch (error) {
+    if (!(await readTask(taskId))) {
+      files.forEach((path, index) => { if (!preexisting[index]) { try { unlinkSync(path); } catch (cleanupError) { if (cleanupError?.code !== "ENOENT") throw cleanupError; } } });
+      try { rmdirSync(join(tasksDir(root), taskId)); } catch { /* not empty or already gone */ }
+    }
+    throw error;
+  }
+};
+
+const validRequirement = (requirement) => {
+  if (typeof requirement !== "string" || !requirement.trim() || Buffer.byteLength(requirement) > 8192) throw new Error("Requirement must contain 1–8192 bytes");
+};
+
+/* ---------------------------------------------------------------- local */
+
+/** A task is loop-owned locally when it has an intake record or a loop run record. */
+export function isLocalLoopOwned(root, taskId) {
+  if (!ID.test(taskId ?? "")) return false;
+  const record = readIntakeRecord(root, taskId);
+  if (record) return record.authority !== "fleet";
+  return readLoopRecord(root, taskId) !== null;
+}
+
+export function createLocalAuthority({ root, agent, workers = {}, workerImages = {}, limits, pollMs, supervisor = createIsolatedLocalSupervisor } = {}) {
+  requireLocalAuthority();
+  const stateScript = join(root, ".agents/aidlc/scripts/state.mjs");
+  const owned = (id) => { try { return isLocalLoopOwned(root, id); } catch { return true; } };
+  return {
+    mode: "local",
+    isOwned: owned,
+    async listActionable() {
+      return Object.values(loadState(root).tasks).filter((task) => nextAction(task, root).classification === "run_phase" && owned(task.id)).sort(byUpdatedAt);
+    },
+    async runTask({ taskId, signal, cancelSignal, onEvent }) {
+      const run = supervisor({ root, taskId, agent, workers, workerImages, limits, pollMs, signal, cancelSignal, untilStop: true, onEvent });
+      return readLoopRecord(root, taskId) ? run.resume() : run.start();
+    },
+    /** Interactive work keeps priority: intake refuses while a non-loop task is actionable. */
+    async intake({ requirement, taskId: requested, title: requestedTitle }) {
+      validRequirement(requirement);
+      const identity = deriveTaskIdentity(requirement);
+      const state = loadState(root);
+      const taskId = requested || uniqueTaskId(root, identity.slug, [...Object.keys(state.tasks), ...Object.keys(state.archive ?? {})]);
+      if (!ID.test(taskId)) throw new Error("Valid task ID required");
+      const title = requestedTitle || identity.title;
+      const actionableIds = (current) => Object.values(current.tasks).filter((task) => task.id !== taskId && nextAction(task, root).classification === "run_phase").map((task) => task.id).sort();
+      const interactive = actionableIds(state).filter((id) => !owned(id));
+      if (interactive.length) throw new Error(`Task create is blocked while interactive work is actionable: ${interactive.join(", ")}. Finish or pause it before starting loop work`);
+      const readTask = async (id) => loadTask(root, id);
+      await guardedIntake(root, taskId, readTask, () => prepareLoopIntake({ root, taskId, requirement, title, authority: "local", readTask, createTask: async ({ taskId: id, title: taskTitle }) => {
+        const loopOwned = actionableIds(loadState(root)).filter((other) => owned(other));
+        try { execFileSync(process.execPath, [stateScript, "task", "create", id, "--title", taskTitle, ...(loopOwned.length ? ["--switch-from", loopOwned.join(",")] : []), "--root", root], { stdio: ["ignore", "pipe", "pipe"], encoding: "utf8" }); }
+        catch (error) { throw stateError(error); }
+      } }));
+      return { ok: true, taskId, title, authority: "local" };
+    },
+    async resumeTask(taskId) {
+      const task = loadTask(root, taskId);
+      if (!task) throw new Error(`Unknown task: ${taskId}`);
+      if (task.status !== "paused" || task.handoff) throw new Error(`Only a paused task without a handoff can be resumed (status: ${task.status})`);
+      try { return JSON.parse(execFileSync(process.execPath, [stateScript, "task", "status", taskId, "--status", "active", "--root", root], { stdio: ["ignore", "pipe", "pipe"], encoding: "utf8" })); }
+      catch (error) { throw stateError(error); }
+    }
+  };
+}
+
+/* ---------------------------------------------------------------- fleet */
+
+const FLEET_REQUIRED = ["AIDLC_FLEET_URL", "AIDLC_FLEET_WORKSPACE", "AIDLC_FLEET_TOKEN", "AIDLC_FLEET_INTEGRATION_BRANCH"];
+/** Credentials that must never reach a lead or worker process. */
+const REVIEWER_SECRETS = ["AIDLC_FLEET_REVIEWER_TOKEN", "AIDLC_UI_TOKEN", "AIDLC_UI_TOKEN_FILE", "AIDLC_UI_REVIEWER_TOKEN_FILE"];
+const LIMIT_ENV = { maxTurns: "AIDLC_FLEET_MAX_TURNS", turnTimeoutMs: "AIDLC_FLEET_TURN_TIMEOUT_MS", maxStallTurns: "AIDLC_FLEET_MAX_STALL_TURNS" };
+
+/** Build the lead environment for fleet runs: validated service settings, the
+ * configured roster, `loop.limits`/`loop.pollMs` as defaults (explicit
+ * `AIDLC_FLEET_*` env wins), and no reviewer credentials. */
+export function fleetLeadEnv({ root, agent, workers, limits, pollMs, env = process.env }) {
+  for (const name of FLEET_REQUIRED) if (typeof env[name] !== "string" || !env[name].trim()) throw new Error(`Fleet loop requires ${name} for the configured remote authority`);
+  if (env.AIDLC_FLEET_PROJECT_ROOT && resolve(env.AIDLC_FLEET_PROJECT_ROOT) !== root) throw new Error("AIDLC_FLEET_PROJECT_ROOT does not match the loop root; refusing to run");
+  const workerIds = Object.keys(workers).join(",");
+  if (env.AIDLC_FLEET_WORKER_IDS && env.AIDLC_FLEET_WORKER_IDS.split(",").map((value) => value.trim()).filter(Boolean).join(",") !== workerIds) throw new Error("AIDLC_FLEET_WORKER_IDS does not match the configured loop workers");
+  if (env.AIDLC_FLEET_WORKER_PROVIDERS) {
+    // Compare content, not the JSON string: key order and spacing do not matter.
+    let mapping; try { mapping = JSON.parse(env.AIDLC_FLEET_WORKER_PROVIDERS); } catch { mapping = null; }
+    const same = mapping && typeof mapping === "object" && !Array.isArray(mapping) && Object.keys(mapping).length === Object.keys(workers).length && Object.entries(workers).every(([id, provider]) => mapping[id] === provider);
+    if (!same) throw new Error("AIDLC_FLEET_WORKER_PROVIDERS does not match the configured loop workers");
+  }
+  const lead = { ...env, AIDLC_FLEET_PROJECT_ROOT: root, AIDLC_FLEET_WORKER_IDS: workerIds, AIDLC_FLEET_WORKER_PROVIDERS: JSON.stringify(workers), AIDLC_FLEET_AGENT: agent };
+  for (const name of REVIEWER_SECRETS) delete lead[name];
+  for (const [key, name] of Object.entries(LIMIT_ENV)) if (limits?.[key] !== undefined && lead[name] === undefined) lead[name] = String(limits[key]);
+  if (pollMs !== undefined && lead.AIDLC_FLEET_POLL_MS === undefined) lead.AIDLC_FLEET_POLL_MS = String(pollMs);
+  return lead;
+}
+
+export async function createFleetAuthority({ root, agent, workers = {}, limits, pollMs, env = process.env, callTool: callToolOverride, runCli } = {}) {
+  if (!isLoopProvider(agent)) throw new Error("Loop requires a configured lead and worker providers");
+  const leadEnv = fleetLeadEnv({ root, agent, workers, limits, pollMs, env });
+  const url = leadEnv.AIDLC_FLEET_URL, token = leadEnv.AIDLC_FLEET_TOKEN, workspace = leadEnv.AIDLC_FLEET_WORKSPACE;
+  const remoteState = join(root, ".agents/aidlc/scripts/remote-state.mjs");
+  if (!existsSync(remoteState)) throw new Error(`Remote lifecycle CLI is missing: ${remoteState}`);
+  const { callRemoteTool } = await import("./remote-state-client.mjs");
+  const { createFleetRemoteRepository } = await import("./loop-fleet-remote.mjs");
+  const callTool = callToolOverride ?? (({ url: serviceUrl, token: serviceToken, name, args }) => callRemoteTool({ url: serviceUrl, token: serviceToken }, name, args));
+  const repository = createFleetRemoteRepository({ callTool, url, token, workspace, root });
+  const fleetCli = runCli ?? (await import("./loop-fleet-cli.mjs")).runFleetCli;
+  const owned = (id) => readIntakeRecord(root, id)?.authority === "fleet";
+  /** Run one remote lifecycle command under a short lead claim (task create/status). */
+  const withLead = async (taskId, args) => {
+    const claim = await repository.claimLead({ taskId, leaseMs: 60000 });
+    try { return JSON.parse(execFileSync(process.execPath, [remoteState, ...args], { cwd: root, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], env: { ...leadEnv, AIDLC_FLEET_LEAD_EPOCH: String(claim.epoch), AIDLC_FLEET_LEAD_OWNER_TOKEN: repository.leadOwnerToken() } })); }
+    catch (error) { throw stateError(error); }
+    finally { await repository.releaseLead({ taskId, epoch: claim.epoch }); }
+  };
+  const readTask = async (id) => { try { return (await repository.readTask({ taskId: id }))?.task ?? null; } catch (error) { if (String(error?.message ?? error).includes("task not found")) return null; throw error; } };
+  return {
+    mode: "fleet",
+    repository,
+    isOwned: owned,
+    /** Fail closed before starting: the service must answer and the integration branch must exist on the remote. */
+    async preflight() {
+      await callTool({ url, token, name: "fleet_get", args: { workspace } });
+      const { readIntegrationCommit } = await import("../remote-state.mjs");
+      await readIntegrationCommit({ projectRoot: root, integrationBranch: leadEnv.AIDLC_FLEET_INTEGRATION_BRANCH, gitRemote: leadEnv.AIDLC_FLEET_GIT_REMOTE ?? "origin" });
+    },
+    async listActionable() {
+      return (await repository.listTasks()).filter((task) => task.status === "active" && !task.handoff && owned(task.id) && nextAction(task, root).classification === "run_phase").sort(byUpdatedAt);
+    },
+    /** Bounded supervised run: returns at a gate (`gate`/`waiting`) instead of waiting for the reviewer. */
+    async runTask({ taskId, signal, cancelSignal, onEvent }) {
+      const result = await fleetCli(["supervisor", taskId], { callTool, env: leadEnv, signal, cancelSignal, untilStop: true, onEvent });
+      // The fleet supervisor already emitted its `gate` event through onEvent.
+      return result && typeof result === "object" ? { ...result, gateEmitted: true } : result;
+    },
+    async intake({ requirement, taskId: requested, title: requestedTitle }) {
+      validRequirement(requirement);
+      const identity = deriveTaskIdentity(requirement);
+      const taskId = requested || uniqueTaskId(root, identity.slug, (await repository.listTasks()).map((task) => task.id));
+      if (!ID.test(taskId)) throw new Error("Valid task ID required");
+      const title = requestedTitle || identity.title;
+      await guardedIntake(root, taskId, readTask, () => prepareLoopIntake({ root, taskId, requirement, title, authority: "fleet", readTask, createTask: async ({ taskId: id, title: taskTitle }) => { await withLead(id, ["task", "create", id, "--title", taskTitle]); } }));
+      return { ok: true, taskId, title, authority: "fleet" };
+    },
+    async resumeTask(taskId) {
+      const task = await readTask(taskId);
+      if (!task) throw new Error(`Unknown task: ${taskId}`);
+      if (task.status !== "paused" || task.handoff) throw new Error(`Only a paused task without a handoff can be resumed (status: ${task.status})`);
+      return withLead(taskId, ["task", "status", taskId, "--status", "active"]);
+    },
+    async listTasks() { return (await repository.listTasks()).map((task) => ({ ...task, loopOwned: owned(task.id) })); },
+    async getTask(taskId) { const snapshot = await repository.readTask({ taskId }); return { task: snapshot?.task ?? null, nextAction: snapshot?.nextAction ?? null, revision: snapshot?.revision ?? null }; },
+    /** The current review snapshot for a waiting task (lead-readable inbox + checkpoint). */
+    async gate(taskId) {
+      const task = await readTask(taskId);
+      if (!task) throw new Error(`Unknown task: ${taskId}`);
+      const checkpoint = await repository.readGateCheckpoint({ taskId });
+      const inbox = await callTool({ url, token, name: "gate_inbox_get", args: { workspace } });
+      const snapshot = Array.isArray(inbox) ? inbox.find((entry) => entry.taskId === taskId && entry.gate === task.gate && (!checkpoint?.snapshotId || entry.id === checkpoint.snapshotId)) ?? null : null;
+      return { taskId, status: task.status, gate: task.gate, checkpoint, snapshot };
+    },
+    /** Reviewer approval of the current snapshot. The reviewer token reaches only this child process. */
+    async approve({ taskId, source, reviewerToken }) {
+      if (typeof reviewerToken !== "string" || reviewerToken.length < 16) throw new Error("Fleet gate approval requires the reviewer credential (AIDLC_FLEET_REVIEWER_TOKEN)");
+      if (typeof source !== "string" || !source.trim()) throw new Error("Approval source is required");
+      const { snapshot, status } = await this.gate(taskId);
+      if (status !== "blocked_on_user" || !snapshot) throw new Error("Task has no current gate snapshot to approve");
+      try { return JSON.parse(execFileSync(process.execPath, [remoteState, "gate", "approve", taskId, "--snapshot", snapshot.id, "--source", source], { cwd: root, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], env: { ...leadEnv, AIDLC_FLEET_REVIEWER_TOKEN: reviewerToken } })); }
+      catch (error) { throw stateError(error); }
+    }
+  };
+}
+
+/** Create the authority for the configured loop mode; never falls back to the other mode. */
+export async function createLoopAuthority({ root, config, env = process.env, ...overrides }) {
+  const mode = config?.loop?.mode;
+  const agent = config?.loop?.agents?.lead;
+  const workers = config?.loop?.agents?.workers ?? {};
+  // Fail fast on a bad roster or `loop.limits` instead of failing every task run.
+  if (!isLoopProvider(agent) || !workers || typeof workers !== "object" || Array.isArray(workers) || !Object.keys(workers).length || Object.entries(workers).some(([id, provider]) => !ID.test(id) || !isLoopProvider(provider))) throw new Error("Loop requires a configured lead and worker providers");
+  if (config?.loop?.limits !== undefined) validateLimits(config.loop.limits);
+  const options = { root, agent, workers, workerImages: config?.loop?.workerImage ?? {}, limits: config?.loop?.limits, pollMs: config?.loop?.pollMs, ...overrides };
+  if (mode === "local") return createLocalAuthority(options);
+  if (mode === "fleet") return createFleetAuthority({ ...options, env });
+  throw new Error("Loop mode is off; configure an enabled loop mode first");
+}

package/dist/assets/.agents/aidlc/scripts/lib/loop-commit-message.mjs

@@ -0,0 +1,45 @@
+/**
+ * Conventional Commit message extraction for worker Git commits.
+ *
+ * The worker may author the commit message by ending its final answer with a
+ * dedicated line (`AI-DLC-COMMIT: type(scope): subject`) next to the existing
+ * `AI-DLC-ITEM-COMPLETE` completion marker. The supervisor parses and validates
+ * that message; when it is absent or malformed it derives a deterministic,
+ * conventional fallback from the item id and owned paths instead of reusing the
+ * legacy `AI-DLC <task>/<item>` form. This module is dependency-free like the
+ * rest of the installed loop runtime.
+ */
+
+const COMMIT_LINE = /^AI-DLC-COMMIT:\s*(.+?)\s*$/m;
+const TYPE = "(?:build|chore|ci|docs|feat|fix|perf|refactor|revert|style|test)";
+const SCOPE = "\\([^()\\r\\n]{1,64}\\)";
+const MESSAGE = new RegExp(`^${TYPE}(${SCOPE})?!?: [^\\r\\n]{1,200}$`);
+const CONTROL = /[\u0000-\u001f\u007f]/;
+
+function fallbackScope(ownedPaths) {
+  if (!Array.isArray(ownedPaths) || !ownedPaths.length) return "";
+  const topLevels = ownedPaths.map((path) => String(path).split("/")[0]);
+  const unique = [...new Set(topLevels)];
+  // Use a scope only when every owned path sits under one real top-level
+  // directory; a bare file (no "/") or a split across directories is ambiguous.
+  if (unique.length !== 1 || !ownedPaths.every((path) => String(path).includes("/"))) return "";
+  return unique[0];
+}
+
+/**
+ * Return a Conventional Commits message for a worker commit. When the worker's
+ * final answer carries a valid `AI-DLC-COMMIT:` line that message is used
+ * verbatim; otherwise a fallback `chore(<scope>): <item-id>` is derived.
+ */
+export function extractCommitMessage(resultText, { itemId, ownedPaths = [] } = {}) {
+  if (typeof resultText === "string") {
+    const match = resultText.match(COMMIT_LINE);
+    if (match) {
+      const message = match[1].trim();
+      if (MESSAGE.test(message) && !CONTROL.test(message)) return message;
+    }
+  }
+  const scope = fallbackScope(ownedPaths);
+  const subject = typeof itemId === "string" && itemId.trim() ? itemId.trim() : "update";
+  return scope ? `chore(${scope}): ${subject}` : `chore: ${subject}`;
+}