@felixdotgo/aidlc-kit 0.1.1 → 0.3.0

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}`;
@@ -17,11 +17,43 @@ export const coreWorkflowFiles = () => [
     ...collect(join(assetRoot, "aidlc"), ".agents/aidlc"),
     ...collect(join(assetRoot, "skills"), ".agents/skills")
 ];
+/** Commented template for the loop daemon's env file; seeded once and never overwritten. */
+export const LOOP_ENV_TEMPLATE = `# AI-DLC loop environment, read by \`loop.sh up\` / \`aidlc-kit loop start\` (local mode).
+# Precedence: shell exports > this file > values detected from your tools' own config.
+# Keep real keys here only; .agents/.gitignore excludes this file from git.
+# See what the loop will use with:  .agents/aidlc/scripts/loop.sh check
+#
+# --- OpenCode (lead or workers set to "opencode") ---
+# Model as provider/model[#variant] (list them with: opencode models).
+# When unset, "model" from opencode.json is used.
+# AIDLC_OPENCODE_MODEL=opencode-go/<model>
+# Worker key; when unset it is read from ~/.local/share/opencode/auth.json.
+# The key follows the model prefix: openai/ -> OPENAI_API_KEY, anthropic/ -> ANTHROPIC_API_KEY, otherwise OPENCODE_API_KEY.
+# OPENCODE_API_KEY=
+#
+# --- Codex workers ---
+# When unset, read from ~/.codex/auth.json (after: codex login --with-api-key).
+# OPENAI_API_KEY=
+#
+# --- Claude Code workers ---
+# When unset, read from "env" in .claude/settings.local.json, .claude/settings.json, or ~/.claude/settings.json.
+# ANTHROPIC_API_KEY=
+#
+# --- Optional ---
+# Override the auto-built worker image:
+# AIDLC_WORKER_DOCKER_IMAGE=
+# Where worker worktrees live (default: the system temp directory):
+# AIDLC_LOCAL_WORKTREES_ROOT=
+`;
+/** Installed files that must be executable (POSIX launchers). */
+export const isExecutableAsset = (path) => path.endsWith(".sh");
 export const initialProjectFiles = () => [
     { path: ".agents/config.json", owner: "aidlc-project", ownershipClass: "project", content: `${JSON.stringify(defaultConfig(), null, 2)}\n` },
     { path: ".agents/data/state/aidlc-state.json", owner: "aidlc-state", ownershipClass: "state", content: `${JSON.stringify(emptyState(), null, 2)}\n` },
     { path: ".agents/data/lessons/index.json", owner: "aidlc-state", ownershipClass: "state", content: `${JSON.stringify(createLessonIndex([], lessonStateDigest(emptyState())), null, 2)}\n` },
-    { path: ".agents/data/memory/agentic-memory.json", owner: "aidlc-memory", ownershipClass: "project", content: `${JSON.stringify(emptyMemoryRegistry(), null, 2)}\n` }
+    { path: ".agents/data/memory/agentic-memory.json", owner: "aidlc-memory", ownershipClass: "project", content: `${JSON.stringify(emptyMemoryRegistry(), null, 2)}\n` },
+    { path: ".agents/loop.env", owner: "aidlc-project", ownershipClass: "project", content: LOOP_ENV_TEMPLATE },
+    { path: ".agents/.gitignore", owner: "aidlc-project", ownershipClass: "project", content: "# Local loop credentials (aidlc-kit)\nloop.env\n# Loop daemon/process state and per-task runtime data (aidlc-kit)\ndata/loop/\ndata/tasks/*/runtime/\n" }
 ];
 export const manifestKey = (spec) => spec.strategy === "managed-block" ? `${spec.path}#${spec.owner}` : spec.path;
 export const manifestFor = (files, adapters) => ({

package/docs/README.md

@@ -1,31 +1,50 @@
 # Documentation
 
-Use this page to choose the guide that matches your role and next task.
+Pick a page by what you want to do. New here? Install with the [README](../README.md), then read [Operating the workflow](./operating-workflow.md).
 
-## For package users and operators
+> [!WARNING]
+> The loop, fleet mode, and the coordination service are pre-1.0 and experimental. See [Status and stability](./loop-runbook.md#status-and-stability).
 
-1. Start with the repository [README](../README.md) to install the workflow.
-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`.
+## Get started
 
-## For contributors and maintainers
+| Page | Read it when… |
+| --- | --- |
+| [README](../README.md) | You are installing the workflow into a project. |
+| [Loop setup runbook](./loop-runbook.md) | You want to enable the loop, locally or across machines. |
+| [Local loop walkthrough](./loop-local-run.md) | The loop is set up and you want to add tasks, watch them, approve gates, and use the dashboard. |
 
-1. Begin with [Development](./development.md) for local setup and implementation boundaries.
-2. Use [Testing and release](./testing-and-release.md) for the verification and package-smoke workflow.
-3. Read [Architecture](./architecture.md) before changing package, installed-runtime, migration, or asset behaviour.
+## Use and operate
 
-## Documentation map
+| Page | Read it when… |
+| --- | --- |
+| [Operating the workflow](./operating-workflow.md) | You want the lifecycle, task state, review gates, and handoffs. |
+| [AI-DLC Coordination service](./coordination-service.md) | You are deploying remote state or fleet workers on several machines. |
 
-| Page | Audience | Purpose |
-| --- | --- | --- |
-| [Operating the workflow](./operating-workflow.md) | Operators | Lifecycle, task state, human gates, and blocked work. |
-| [Configuration](./configuration.md) | Operators and maintainers | Project configuration, profile precedence, rules, and Codex, Claude Code, and OpenCode permissions. |
-| [Command reference](./command-reference.md) | Operators | Package CLI commands, flags, previews, and safety limits. |
-| [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`. |
+## Reference
 
-When a public command, configuration field, or installed layout changes, update the relevant guide and its validation in the same change.
+| Page | Read it when… |
+| --- | --- |
+| [Configuration](./configuration.md) | You are editing `.agents/config.json`: profiles, rules, agent permissions, loop settings. |
+| [Command reference](./command-reference.md) | You need a command, flag, environment variable, or installed script. |
+| [Troubleshooting](./troubleshooting.md) | You have an error code, a stuck or paused task, or a dashboard problem. |
+
+## Contribute
+
+| Page | Read it when… |
+| --- | --- |
+| [Development](./development.md) | You are setting up this repository, dogfooding its workflow, or changing source. |
+| [Testing and release](./testing-and-release.md) | You are verifying a change or preparing a release. |
+| [Architecture](./architecture.md) | You are changing a package boundary, installed runtime, migration, or asset layout. |
+| [Design decisions](./design-decisions.md) | You need the reasoning behind a project-wide decision, or must record one. |
+
+## Adding or changing a page
+
+Pages are flat `docs/<slug>.md` files; the dashboard, tests, and external links depend on the names.
+
+- **Shape:** `# Title`, a 1–2 sentence opening (purpose and audience), `##` headings by reader task, tables for lookups, `## Related` with 2–4 links.
+- **One source of truth:** each fact lives on one page; other pages give one sentence and a link. Experimental features get only a one-line callout to [Status and stability](./loop-runbook.md#status-and-stability).
+- **Links:** `./<slug>.md#anchor`. The dashboard keeps links to pages in `DOC_PAGES` (`src/ui/docs.ts`) in-app and opens the rest on GitHub. Don't rename a linked heading without updating the links.
+- **Register it:** add the page to a table above; to show it in the dashboard, add it to `DOC_PAGES` and run `node --test dist/test/unit/ui-docs.test.js` after `npm run build`; if the package must always ship it, add it to the docs test in `test/unit/installer.test.ts`.
+- **Versions:** pages with version-pinned commands go on the [version bump checklist](./testing-and-release.md#version-bump-checklist).
+
+A public command, configuration field, or installed-layout change updates the relevant page and its test in the same change.

package/docs/architecture.md

@@ -1,6 +1,6 @@
 # Architecture
 
-`aidlc-kit` is a single Node.js/TypeScript package that installs static AI-DLC workflow assets into another project. The package CLI is used for installation and human-authorised maintenance; an installed project runs the dependency-free workflow scripts locally.
+One Node.js/TypeScript package: the CLI installs and maintains static AI-DLC workflow assets; installed projects run dependency-free scripts locally.
 
 ## Source-to-consumer flow
 
@@ -14,55 +14,117 @@ dist/assets/.agents/ + dist/src/
 consumer project: .agents/aidlc/ + .agents/skills/ + project-owned .agents/data/
 ```
 
-The distinction matters:
-
-- **Source layout** is this repository's editable `assets/aidlc/` and `skills/` tree.
-- **Bundle layout** is generated under `dist/assets/.agents/` for package publication.
-- **Installed layout** is written under a consumer project's `.agents/` directory.
-
-`dist/` is generated. Source assets and installed assets must remain behaviourally aligned through the bundle and package-smoke tests.
+Layouts: **source** (editable `assets/aidlc/`, `skills/`), **bundle** (generated `dist/assets/.agents/`, never hand-edited), **installed** (consumer `.agents/`); bundle and package-smoke tests keep them aligned.
 
 ## Module boundaries
 
 | 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. |
-| 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.
+| CLI and installation | `src/cli.ts` + `src/cli/` (`argv`, `options`, `prompt`, `commands`), `src/installer.ts`, `src/workflow.ts`, `src/adapters.ts`, `src/mcp-setup.ts` | Parse commands, select adapters, plan deterministic writes, install managed assets (incl. coordination-service template), status/doctor. |
+| Shared planning core | `src/managed-planning.ts` | Manifest reading, inventory keys, managed-file planning ladder (create/skip/update/conflict), init vs upgrade policies. |
+| Lifecycle domain | `src/model/` (barrel `src/model.ts`), `src/state/` (barrel `src/state.ts`), `src/gate.ts`, `src/context.ts` | Validate state, compute transitions and gate readiness, classify next actions, build phase packets. |
+| Profiles | `src/profiles.ts` | Resolve and validate config/profiles (incl. schema-only `tracker`), expand effective rules. |
+| Migration | `src/upgrade.ts`, `src/project-migration.ts`, `src/legacy.ts`, `src/upgrade-board.ts` | Legacy-data and version-layout migration (incl. legacy `BOARD.md`) with audit backups. |
+| Web dashboard | `src/task-ui.ts` (barrel) over `src/ui/`; browser scripts `assets/ui/*.js` | Serve `aidlc-kit ui` dependency-free; mutations only spawn installed scripts, never write state. |
+| Shared file semantics | `src/project-path.ts`, `src/managed-content.ts` | Path containment, unsafe-symlink rejection, managed-block marker format. |
+| Development evaluator | `dev/evaluator/` | Repository-only; never in the published CLI. |
+
+`src/state/`: `io`, `paths`, `domain`, `guards`, `archive-record`, `items`, `commands`, `transitions`, `validate`, `store`, `memory`, `lessons`, `lifecycle`, `render`, `migrate`, `lock`.
+
+### Web dashboard modules
+
+- `src/ui/server`: route table (`ROUTES`) and `startUiServer`.
+- `src/ui/security`: Host and request-shape checks (Origin, `Sec-Fetch-Site`, custom header); there is no session token.
+- `src/ui/containers`: per-task worker container index and raw log tail (`.agents/data/tasks/<id>/runtime/workers/`), with `docker ps` enrichment.
+- `src/ui/changes`: code changes with one source order for every mode (fleet snapshot → assignments → task range from `baseCommit`/`finalCommit` → working tree).
+- `src/ui/options`, `src/ui/http`: option parsing, HTTP helpers.
+- `src/ui/assets`: whitelisted static CSS/JS from `assets/ui/`.
+- `src/ui/daemon`: daemon status, health, spawned script actions.
+- `src/ui/data`: local and fleet reads.
+- `src/ui/changes`: task diffs via Git.
+- `src/ui/live`, `src/ui/sse`: `/api/live` regions and `/api/events`.
+- `src/ui/markdown`: Markdown rendering.
+- `src/ui/docs`: read-only packaged `docs/*.md` via the fixed `DOC_PAGES` whitelist.
+- `src/ui/files`: byte-range file reads, optionally refusing symlinks.
+- `src/ui/views/`: `layout`, `components`, `board`, `task`, `changes`, `docs`.
+- `assets/ui/*.js`: plain browser scripts `common`, `dashboard`, `detail`, `live-log`, `changes`.
+
+New page: route in `ROUTES` (`src/ui/server.ts`) + view in `src/ui/views/`.
+
+### Dependency direction
+
+- Inward only: CLI, installation, migration depend on planning core, lifecycle, shared helpers.
+- Planning core depends only on `model`, `workflow`, `managed-content`, `profiles`; never on CLI, installer, or upgrade.
+- Migration never imports installation (`upgrade.ts` uses `managed-planning.ts` directly); the only `installer.ts` → `project-migration.ts` edge is init-time legacy-layout planning.
+- Lifecycle never depends on installation; the evaluator may provision one but is not published runtime.
+- `src/ledger.ts` and `src/tracker.ts` were removed as dead code; `tracker` config is schema-only (`TrackerConfig`).
 
 ## Installed workflow runtime
 
-The installed kernel consists of contracts, templates, schemas, profiles, and dependency-free scripts under `.agents/aidlc/`. Thin adapter instructions connect a selected coding tool to that kernel. Project customisation belongs outside the kernel:
+Kernel: contracts, templates, schemas, profiles, dependency-free scripts in `.agents/aidlc/`, reached via thin adapter instructions. Customisation stays outside:
 
 | Location | Ownership | Purpose |
 | --- | --- | --- |
-| `.agents/aidlc/` | Package managed | Lifecycle contracts, schemas, and scripts. |
-| `.agents/data/` | Project owned | Canonical state, task artifacts, derived indexes, memory, and evidence. |
-| `.agents/project/` | Project owned | Local profiles, rules, and evaluation material. |
+| `.agents/aidlc/` | Package managed | Lifecycle contracts, schemas, scripts. |
+| `.agents/data/` | Project owned | Canonical state, task artifacts, derived indexes, memory, evidence. |
+| `.agents/project/` | Project owned | Local profiles, rules, evaluation material. |
 
-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.
+State machine enforces the lifecycle; gates need human approval; evidence is append-only; no `aidlc-kit` executable or duplicate board file needed.
+
+### Loop runtime
 
 > [!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`.
+> Experimental, pre-1.0. See [Status and stability](./loop-runbook.md#status-and-stability).
+
+Dispatch derives from task `nextAction` and dependency-ready work; assignment records are operational metadata; phase, evidence, gates stay canonical. Selecting a mode only configures; `loop start` (or `loop up`) runs.
 
-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.
+| Variant | Authority | How it runs |
+| --- | --- | --- |
+| Interactive | Local `.agents/data/state/` | In the current agent conversation; native workers claim and checkpoint via assignment records in the task's `runtime/` directory. |
+| Local | Local `.agents/data/state/` | Singleton daemon (`loop start` or `loop.sh up`): host-executed lead, Docker-isolated workers; gate approval only via trusted host terminal or dashboard. |
+| Fleet | Coordination service | Service owns supervisor leases, gate checkpoints, reviewer approval; Docker workers hold own credentials; Git uses fenced lead/worker claims with commit handoff. SQLite single-host, PostgreSQL multi-host. |
+
+Every variant is a wrapper around the same data: the canonical task state (including `baseCommit`/`finalCommit`, written by `state.mjs` locally and `remote-state.mjs` in fleet mode through the shared core) and the task directory `.agents/data/tasks/<id>/`. Review artifacts (`intent.md`, `design.md`, `workplan.md`) sit at its root; everything operational sits under `runtime/`, identical for the no-loop workflow, the local loop, and fleet (one helper, `lib/task-runtime.mjs`, names every path and refuses symlinked components):
+
+| `.agents/data/tasks/<id>/runtime/` | Written by | Purpose |
+| --- | --- | --- |
+| `assignments.json`, `assignments.lock` | `assignment.mjs` (interactive), local supervisor | worker claims (local only; fleet claims live in the service) |
+| `events.jsonl` (+ `.1`) | `loop-stream.mjs` | the task's event history (dashboard live log) |
+| `run.json` | `loop-runtime.mjs` | the loop run record (run id, agent, status, session, checkpoint) |
+| `intake.json`, `requirement.md` | loop intake | loop ownership and the requirement text |
+| `workers/index.json`, `workers/<assignment>.log` | local and fleet workers | container index and raw output |
 
-Installed entry points share a strict dependency-free argv parser. Parsing and command-shape validation precede root discovery, lock acquisition, and state reads. Explicit roots are validated project directories; implicit roots use nearest-ancestor `.agents/aidlc/` discovery and never fall back to writing beneath an arbitrary working directory.
+`.agents/data/loop/` holds only daemon and process state: `daemon.lock`, `daemon.log`, `daemon.stop`, the global `ui-events.jsonl`, `ui.json`/`cli.json`, task leases (`<id>.lease`), the lead checkpoint (`<id>.supervisor.json`) and gate receipt. Both directories are operational: never committed, handed off, or clean-checked, and the installer's `.agents/.gitignore` excludes them. Files written by versions before this layout are read in place and moved by `aidlc-kit loop migrate-data` or the daemon at start ([Command reference](./command-reference.md#loop)).
+
+**Agent support.**
+
+- Host-executed lead turns: Codex, Claude Code, OpenCode.
+- Container-isolated lead turns: Codex, Claude Code; OpenCode rejected with a diagnostic (file-based credentials; `lib/loop-lead-sandbox.mjs`).
+- Docker workers (local and fleet): all three; OpenCode uses environment credentials, XDG roots redirected into the ephemeral worker HOME (`lib/loop-worker-docker.mjs`).
+
+**Leases, locks, and claims.** One holder-file primitive (`lib/loop-holder.mjs`), three meanings:
+
+- **Lock:** short mutex around a file write (assignment records).
+- **Lease:** process ownership of the singleton daemon or one task's loop run (replacing separate runner and supervisor leases); its `activity` (`waiting` or `turn`) gates approval.
+- **Claim:** a worker's ownership of an item and its paths.
+
+One file format and liveness rule; 15 s renewal, 60 s TTL; a `<file>.guard` serializes reclaim, renewal, release. `aidlc-kit loop leases` lists them; details: [Troubleshooting](./troubleshooting.md#loop-leases-locks-and-claims).
+
+### Installed entry points
+
+A shared strict argv parser validates command shape before root discovery, lock acquisition, and state reads. Explicit roots must be validated project directories; implicit roots use nearest-ancestor `.agents/aidlc/` discovery, never an arbitrary cwd.
 
 ## Trust and safety boundaries
 
-- Workflow assets are local package assets. The manifest records `remoteUpdates: false`; status and doctor do not consult a registry.
-- Install/upgrade plans are conflict-first, path-contained, and reject unsafe symlink traversal.
-- Human-only upgrade is an intentional boundary: interactive confirmation is required and agents must not run or discover upgrades.
-- Codex, Claude Code, and OpenCode adapters are installed. Codex uses trusted project-scoped `.codex/config.toml` and `.codex/rules/aidlc.rules`; Claude Code scopes lifecycle-script permission through its local settings and phase skills. OpenCode gets an owner-scoped `AGENTS.md` block only, and `.opencode/` is read solely for detection, so no OpenCode configuration, MCP, or permission file is overridden.
-- Project commands are configured as executable-and-argument arrays rather than opaque shell strings.
-- Canonical state, terminal records, and rendered workplans reject symlink traversal and use same-directory atomic replacement. Lock acquisition is guard-serialized, while release verifies the owner token directly so a contended guard cannot strand the owner's main lock.
-- The compact master catalog remains archive authority. Recovery can replace only a valid, unreferenced terminal orphan tied by `id` and `createdAt` to the still-active catalog task; referenced, malformed, and identity-conflicting records fail closed.
+- Assets are local (manifest `remoteUpdates: false`); status/doctor never consult a registry.
+- Install/upgrade plans: conflict-first, path-contained, no unsafe symlink traversal.
+- Upgrade is human-only (interactive confirmation); agents never run or discover upgrades.
+- Codex: project-scoped `.codex/config.toml`, `.codex/rules/aidlc.rules`. Claude Code: lifecycle-script permission via local settings and phase skills. OpenCode: owner-scoped `AGENTS.md` block only; `.opencode/` read for detection only.
+- Project commands: executable-and-argument arrays, never shell strings.
+- Canonical state, terminal records, and rendered workplans reject symlink traversal; writes are same-directory atomic replaces.
+- State lock: guard-serialized; release verifies the owner token directly, so a contended guard cannot strand it; stale when its pid is gone and it is 30 s old.
+- Loop holders (`lib/loop-holder.mjs`) re-read the token under the guard on reclaim, so a reclaimer never deletes a newer holder.
+- The compact master catalog is archive authority; recovery replaces only a valid, unreferenced terminal orphan matching the active catalog task by `id` and `createdAt`; referenced, malformed, or identity-conflicting records fail closed.
 
 ## Change impact guide
 
@@ -70,11 +132,13 @@ Installed entry points share a strict dependency-free argv parser. Parsing and c
 | --- | --- |
 | A lifecycle/state rule | Installed scripts, schemas, gate/context rendering, runtime parity tests. |
 | An asset or adapter | Asset builder, package inventory, installer, adapter tests, tarball smoke test. |
-| A configuration/profile field | Validator, schema, effective-profile behaviour, documentation, and tests. |
-| Migration semantics | Upgrade plan/apply logic, path safety, transaction rollback, and migration tests. |
-| A public command | CLI parsing, README/setup guidance, command reference, and package tests. |
-
-Use this guide with [Development](./development.md) and [Testing and release](./testing-and-release.md) before changing a cross-cutting boundary.
+| A configuration/profile field | Validator, schema, effective-profile behaviour, docs, tests. |
+| Migration semantics | Upgrade plan/apply logic, path safety, transaction rollback, migration tests. |
+| A public command | CLI parsing, README/setup guidance, command reference, package tests. |
 
+## Related
 
-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.
+- [Development guide](./development.md)
+- [Testing and release](./testing-and-release.md)
+- [Design decisions](./design-decisions.md)
+- [Coordination service](./coordination-service.md)