@felixdotgo/aidlc-kit 0.1.1 → 0.3.0

package/DEVELOPMENT.md

@@ -1,31 +1,32 @@
 # Contributing to aidlc-kit
 
-This file is the short entry point for maintainers and contributors. Detailed guidance lives in [`docs/`](./docs/README.md) so that user setup, system operation, and repository development can evolve independently.
+Entry point for contributors. Details live in [`docs/`](./docs/README.md).
 
 ## Local bootstrap
 
-Requirements: Node.js 20 or newer and npm.
+Node.js 20.17+ and npm.
 
 ```sh
 npm install
-npm test
-npm run lint
+npm test        # build + unit tests
+npm run lint    # tsc --noEmit
 ```
 
+To develop with the repository's own workflow (`.agents/` is gitignored), follow [Dogfooding this repository](./docs/development.md#dogfooding-this-repository).
+
 ## Contributor documentation
 
-- [Development guide](./docs/development.md) — dependencies, repository layout, implementation boundaries, and local commands.
-- [Testing and release](./docs/testing-and-release.md) — focused tests, package smoke test, evaluator, and release readiness.
-- [Architecture](./docs/architecture.md) — module ownership, data flow, and installed-runtime parity.
-- [Configuration reference](./docs/configuration.md) — profiles, rules, provider permissions, and project-owned configuration.
+- [Development guide](./docs/development.md) — layout, local commands, boundaries, code style, dogfooding.
+- [Testing and release](./docs/testing-and-release.md) — focused tests, Docker/PostgreSQL verification, package smoke test, release checklist.
+- [Architecture](./docs/architecture.md) — module ownership and source → bundle → installed flow.
+- [Design decisions](./docs/design-decisions.md) — numbered decisions and how to add one.
 
 ## Documentation policy
 
-- Keep `README.md` focused on package requirements and setup.
-- Add operational and system guidance to the relevant page in `docs/`.
-- Update command/configuration examples and their tests in the same change as a public contract.
-- Do not duplicate canonical agent instructions from `assets/aidlc/` in overview documentation.
+- `README.md` is the fastest path to install and use; everything else goes in `docs/` per [Adding or changing a page](./docs/README.md#adding-or-changing-a-page).
+- A public contract change (command, config field, schema, installed asset) updates its guide and test in the same change.
+- Never duplicate canonical agent instructions from `assets/aidlc/`; link to them.
 
 ## Delivery boundary
 
-Running verification does not authorise publishing, tagging, committing, or pushing. Those actions require separate human approval.
+Passing verification does not authorise publishing, tagging, committing, or pushing; each needs separate human approval.

package/README.md

@@ -1,69 +1,63 @@
 # aidlc-kit
 
-`@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.
+[![version](https://img.shields.io/badge/version-0.3.0-blue)](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/)
 
-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.
+Installs an AI-DLC workflow into an existing project: a shared task lifecycle, explicit human review gates, and project-owned state for Codex, Claude Code, and OpenCode. Optionally, a loop daemon runs tasks end-to-end on one machine or across a fleet.
 
 > [!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`.
-
-## Requirements
-
-- Node.js 20.17 or newer.
-- An existing project directory.
-- Codex, Claude Code, or OpenCode.
+> Pre-1.0 (`0.x`). The local loop is usable; fleet mode and the coordination service are still in development. See [Status and stability](./docs/loop-runbook.md#status-and-stability).
 
 ## Quick start
 
-Run these commands from your existing project's directory to preview the installation, then apply it:
+Requires Node.js 20.17+ and Codex, Claude Code, or OpenCode (Linux/macOS; Windows is best-effort).
 
 ```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.3.0 aidlc-kit init .          # previews, then installs after you confirm
+npx --package @felixdotgo/aidlc-kit@0.3.0 aidlc-kit doctor . --strict
 ```
 
-`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.
-
-Use the adapter that matches the coding tool:
+In a terminal, `init` asks for the adapter (unless exactly one is detected or you pass `--agent codex|claude|opencode` / `--all`) and the loop mode (unless `--loop-mode …`), previews the files, then asks you to confirm; `--yes` skips the confirmation, `--dry-run` writes nothing. The installed lifecycle scripts run locally and never contact a registry.
 
-| Tool | `--agent` value | Installed entry point |
-| --- | --- | --- |
-| Codex | `codex` | `AGENTS.md` |
-| Claude Code | `claude` | `CLAUDE.md` and phase skills |
-| OpenCode | `opencode` | `AGENTS.md` |
+Then ask your agent for a change:
 
-Use `--all` to install every supported adapter. Codex installs workspace-write sandboxing with on-request approvals and a project execpolicy that permits only AI-DLC lifecycle scripts; trust the project before starting Codex so that it loads the project configuration. Claude Code installs a local permission allowlist for the same lifecycle-script command prefix without granting general Bash access. OpenCode installs an owner-scoped block in `AGENTS.md` and uses `.opencode/` only for detection; it writes no OpenCode configuration, MCP, or permission file, so your own settings are not overridden. When Codex and OpenCode are installed together, their blocks merge in the same `AGENTS.md`. Use `--force --yes` only for an initial installation when replacing an unmanaged conflicting file is intentional.
+```text
+Add rate limiting to the login endpoint using the AI-DLC workflow.
+```
 
-Confirm the installed project locally:
+The agent creates a task and stops at three review steps — Confirm requirements, Approve plan, Review implementation — each needing your explicit reply. The Codex and Claude Code adapters pre-approve only the lifecycle scripts, and OpenCode gets instructions only ([Agent permissions](./docs/configuration.md#agent-permissions)); for Codex, trust the project first.
 
-```sh
-npx --package @felixdotgo/aidlc-kit@0.1.1 aidlc-kit status .
-npx --package @felixdotgo/aidlc-kit@0.1.1 aidlc-kit doctor . --strict
-```
+## Run the loop (optional)
 
-## Documentation
+A daemon drives tasks end-to-end on a Linux host with Docker, stopping at every review step for you:
 
-The detailed documentation is organised by task and audience:
+1. In `.agents/config.json` update the `loop` section to match your environment, e.g.,
+    ```json
+    ...
+    "loop": {
+        "mode": "local",
+        "agents": {
+            "lead": "opencode",
+            "workers": {
+                "worker-a": "opencode"
+            }
+        }
+    }
+    ...
+    ```
+2. Put credentials in the git-ignored `.agents/loop.env`; keys your tools already store are detected.
+3. `./.agents/aidlc/scripts/loop.sh up` checks the environment, starts the daemon, and serves the dashboard (`--open` launches the browser); `loop.sh down` stops both.
 
-- [Documentation index](./docs/README.md) — choose the right guide.
-- [Operating the workflow](./docs/operating-workflow.md) — lifecycle, state, gates, and blocked work.
-- [Configuration](./docs/configuration.md) — project configuration, profiles, rules, and adapters.
-- [Command reference](./docs/command-reference.md) — every package CLI command and safety constraint.
-- [Development](./docs/development.md) — local contributor setup, source layout, and implementation rules.
-- [Testing and release](./docs/testing-and-release.md) — verification, evaluator, package smoke test, and release readiness.
-- [Architecture](./docs/architecture.md) — package boundaries and the source-to-installed flow.
-- [AI-DLC Coordination service](./docs/coordination-service.md) — opt-in Docker/remote coordination, security, and polling contract.
+Setup: [Loop setup runbook](./docs/loop-runbook.md). Daily use: [Local loop walkthrough](./docs/loop-local-run.md).
 
-## Safety note
+## Documentation
 
-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.
+[Index](./docs/README.md) · [Operating the workflow](./docs/operating-workflow.md) · [Configuration](./docs/configuration.md) · [Command reference](./docs/command-reference.md) · [Troubleshooting](./docs/troubleshooting.md) · [Coordination service (fleet)](./docs/coordination-service.md) · [Contributing](./DEVELOPMENT.md)
 
-## Recent changes
+## Safety note
 
-- 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.
+Only a human may upgrade: `upgrade` rejects `--yes` and `--force`, needs an interactive terminal, and asks you to type the target version ([details](./docs/command-reference.md#upgrade)).
 
 ## License
 

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

@@ -20,7 +20,7 @@ This file is the compact kernel contract. Project customization lives under `.ag
 
 Read-only questions remain off-workflow and do not create state. The current Codex, Claude Code, or OpenCode conversation is the interactive lead for local mode. It keeps following fresh `nextAction` in the same conversation, uses native host delegation for independent items, and presents gates here. A later explicit user reply approves a gate. No nested Codex/Claude/OpenCode CLI process is needed for interactive mode.
 
-On `resume <task-id>` in a reopened conversation, first read `task next` and `task show`, then run `assignment.mjs reconcile <task-id>` and inspect each `reported` or `uncertain` assignment against canonical item status, owned files, and worker output. Resume only work still required by canonical state. A stale assignment never authorizes replaying a lifecycle mutation or gate approval. Local assignment records under `.agents/data/loop/assignments/` are scheduling metadata, not lifecycle authority. Fleet mode uses an explicitly selected remote authority and fenced service claims; never silently switch between local and remote state.
+On `resume <task-id>` in a reopened conversation, first read `task next` and `task show`, then run `assignment.mjs reconcile <task-id>` and inspect each `reported` or `uncertain` assignment against canonical item status, owned files, and worker output. Resume only work still required by canonical state. A stale assignment never authorizes replaying a lifecycle mutation or gate approval. Local assignment records under `.agents/data/tasks/<task-id>/runtime/assignments.json` are scheduling metadata, not lifecycle authority. Fleet mode uses an explicitly selected remote authority and fenced service claims; never silently switch between local and remote state.
 
 ## Review steps
 
@@ -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/schemas/state.schema.json

@@ -35,6 +35,8 @@
         "legacyG2Wait": { "$ref": "#/$defs/legacyG2Wait" },
         "predecessorTaskId": { "type": "string", "minLength": 1 },
         "successorTaskId": { "type": "string", "minLength": 1 },
+        "baseCommit": { "type": "string", "pattern": "^[0-9a-f]{7,64}$" },
+        "finalCommit": { "type": "string", "pattern": "^[0-9a-f]{7,64}$" },
         "createdAt": { "type": "string" },
         "updatedAt": { "type": "string" }
       },

package/dist/assets/.agents/aidlc/scripts/lib/assignment-store.mjs

@@ -1,27 +1,31 @@
 import { randomUUID } from "node:crypto";
 import { execFileSync } from "node:child_process";
-import { closeSync, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
-import { dirname, join, resolve } from "node:path";
+import { closeSync, fsyncSync, mkdirSync, openSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { acquireHolder, describeHolder } from "./loop-holder.mjs";
+import { resolveTaskRuntimeRead, taskRuntimePath } from "./task-runtime.mjs";
+import { migrateTaskRuntime } from "./task-runtime-migrate.mjs";
 
 const idPattern = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
 const states = new Set(["leased", "reported", "uncertain", "integrated", "released"]);
 const safeId = (value, label) => { if (typeof value !== "string" || !idPattern.test(value)) throw new Error(`Invalid ${label}`); return value; };
 const iso = () => new Date().toISOString();
-const wait = (ms) => Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
 
+/** Write location of the task's assignment records
+ * (`.agents/data/tasks/<task>/runtime/assignments.json`; `.lock` for the mutex),
+ * refusing symlinked path components. */
 export function assignmentPath(root, taskId, suffix = ".json") {
   safeId(taskId, "task id");
-  let path = resolve(root);
-  for (const part of [".agents", "data", "loop", "assignments", `${taskId}${suffix}`]) {
-    path = join(path, part);
-    try { if (lstatSync(path).isSymbolicLink()) throw new Error(`Assignment path crosses symlink: ${path}`); }
-    catch (error) { if (error?.code !== "ENOENT") throw error; }
-  }
-  return path;
+  if (![".json", ".lock"].includes(suffix)) throw new Error(`Unknown assignment file suffix: ${suffix}`);
+  return taskRuntimePath(root, taskId, suffix === ".lock" ? "assignments.lock" : "assignments.json");
 }
 
+/** Read location: the runtime file, else the pre-runtime
+ * `.agents/data/loop/assignments/<task>.json` until it has been migrated. */
+export const assignmentReadPath = (root, taskId) => resolveTaskRuntimeRead(root, safeId(taskId, "task id"), "assignments.json");
+
 function read(root, taskId) {
-  const path = assignmentPath(root, taskId);
+  const path = assignmentReadPath(root, taskId);
   let value;
   try { value = JSON.parse(readFileSync(path, "utf8")); }
   catch (error) {
@@ -56,44 +60,66 @@ function write(root, taskId, value) {
   }
 }
 
-function alive(pid) {
-  try { process.kill(pid, 0); return true; }
-  catch (error) { return error?.code !== "ESRCH"; }
-}
-
+/** Short mutex around one read-modify-write of `assignments/<task>.json`
+ * (kind lock, 30s TTL, no heartbeat). Waits up to 5s for another holder. */
 function locked(root, taskId, action) {
+  // A legacy record moves under runtime/ before the first write, so the
+  // writer never has to choose between two locations.
+  migrateTaskRuntime(root, taskId, { names: ["assignments.json"] });
   const path = assignmentPath(root, taskId, ".lock");
-  mkdirSync(dirname(path), { recursive: true });
-  const token = randomUUID();
-  const deadline = Date.now() + 5000;
-  for (;;) {
-    try {
-      const fd = openSync(path, "wx", 0o600);
-      try { writeFileSync(fd, JSON.stringify({ pid: process.pid, token })); fsyncSync(fd); }
-      finally { closeSync(fd); }
-      break;
-    } catch (error) {
-      if (error?.code !== "EEXIST") throw error;
-      let owner;
-      try { owner = JSON.parse(readFileSync(path, "utf8")); }
-      catch { throw new Error(`Corrupt assignment lock for ${taskId}; inspect before retry`); }
-      if (!Number.isSafeInteger(owner.pid) || typeof owner.token !== "string") throw new Error(`Corrupt assignment lock for ${taskId}`);
-      if (!alive(owner.pid)) {
-        const current = JSON.parse(readFileSync(path, "utf8"));
-        if (current.token === owner.token) unlinkSync(path);
-        continue;
-      }
-      if (Date.now() >= deadline) throw new Error(`Timed out waiting for assignment lock: ${taskId}`);
-      wait(10);
-    }
-  }
+  const handle = acquireHolder({
+    path, kind: "lock", scope: `assignments:${taskId}`, purpose: "assignment read-modify-write", waitMs: 5000,
+    busyMessage: (entry) => `Timed out waiting for assignment lock: ${taskId}: ${describeHolder(entry)}`,
+  });
   try { return action(); }
   finally {
-    const current = JSON.parse(readFileSync(path, "utf8"));
-    if (current.token === token) unlinkSync(path);
+    // A release failure must not mask the committed write; the lock then
+    // expires on its own after its 30s TTL.
+    try { handle.release(); } catch { /* expires via TTL */ }
   }
 }
 
+/** User-facing labels for the persisted assignment (claim) states. */
+export const ASSIGNMENT_STATE_LABELS = Object.freeze({
+  leased: "claim held",
+  expired: "claim expired; needs reconcile",
+  uncertain: "expired or outcome unknown; needs reconcile",
+  reported: "worker reported; awaiting integration",
+  integrated: "integrated",
+  released: "released",
+});
+
+/** Display state computed at read time: a `leased` claim past its
+ * leaseExpiresAt shows as `expired` (mutations persist it as `uncertain`). */
+export function effectiveAssignmentState(assignment, now = Date.now()) {
+  return assignment.state === "leased" && Date.parse(assignment.leaseExpiresAt) <= now ? "expired" : assignment.state;
+}
+
+const reconcileCommand = (taskId) => `node .agents/aidlc/scripts/assignment.mjs reconcile ${taskId}`;
+const releaseCommand = (taskId, id) => `node .agents/aidlc/scripts/assignment.mjs release ${taskId} ${id}`;
+
+/** One-line description of a claim: id, item, worker, paths, state, expiry. */
+export function describeAssignment(assignment, now = Date.now()) {
+  const state = effectiveAssignmentState(assignment, now);
+  return `assignment ${assignment.id} (item ${assignment.itemId}, worker ${assignment.workerId}, paths ${(assignment.ownedPaths ?? []).join(", ")}, state ${state}: ${ASSIGNMENT_STATE_LABELS[state] ?? state}, claim expires ${assignment.leaseExpiresAt})`;
+}
+
+/** Remedy commands for a blocking claim. */
+export function assignmentRemedy(taskId, assignment, now = Date.now()) {
+  const release = `${releaseCommand(taskId, assignment.id)} to drop the claim (discards the worker's unintegrated result)`;
+  const state = effectiveAssignmentState(assignment, now);
+  if (state === "leased") return `wait for the worker to report or for the claim to expire; if the worker is gone, run ${release}`;
+  if (state === "expired" || state === "uncertain") return `the claim expired or its outcome is unknown: run ${reconcileCommand(taskId)} (marks it integrated if the item is done); if the item is not done and the worker is gone, run ${release}`;
+  return `run ${reconcileCommand(taskId)} once the item is done in canonical state; or run ${release}`;
+}
+
+const blockedBy = (taskId, assignment) => `${describeAssignment(assignment)}; ${assignmentRemedy(taskId, assignment)}`;
+
+function notLeased(taskId, assignmentId, item, suffix = "") {
+  if (!item) return new Error(`Assignment is not leased${suffix}: assignment ${assignmentId} does not exist for ${taskId}; inspect: node .agents/aidlc/scripts/assignment.mjs show ${taskId}`);
+  return new Error(`Assignment is not leased${suffix}: ${describeAssignment(item)}; run ${reconcileCommand(taskId)}`);
+}
+
 function canonical(root, taskId) {
   const raw = execFileSync(process.execPath, [join(root, ".agents/aidlc/scripts/state.mjs"), "task", "show", taskId, "--root", root], { cwd: root, encoding: "utf8", timeout: 30000, maxBuffer: 2 * 1024 * 1024 });
   const result = JSON.parse(raw);
@@ -108,8 +134,12 @@ function expire(value, now) {
   }
 }
 
+/** Read-only view: each assignment gains `effectiveState` and `stateLabel`
+ * (an overdue `leased` claim shows as `expired`); nothing is written. */
 export function showLocalAssignments(root, taskId) {
-  return read(root, safeId(taskId, "task id"));
+  const value = read(root, safeId(taskId, "task id"));
+  const now = Date.now();
+  return { ...value, assignments: value.assignments.map((assignment) => { const effectiveState = effectiveAssignmentState(assignment, now); return { ...assignment, effectiveState, stateLabel: ASSIGNMENT_STATE_LABELS[effectiveState] ?? effectiveState }; }) };
 }
 
 export function claimLocalAssignment(root, { taskId, itemId, workerId, ownedPaths, leaseMs = 300000, baseCommit = null, branch = null, sessionId = null }) {
@@ -124,9 +154,11 @@ export function claimLocalAssignment(root, { taskId, itemId, workerId, ownedPath
   return locked(root, taskId, () => {
     const value = read(root, taskId); expire(value, Date.now());
     const active = value.assignments.filter((entry) => ["leased", "reported", "uncertain"].includes(entry.state));
-    if (active.some((entry) => entry.itemId === itemId && entry.state === "leased")) throw new Error(`Item already leased: ${itemId}`);
-    if (value.assignments.some((entry) => entry.itemId === itemId && ["reported", "uncertain"].includes(entry.state))) throw new Error(`Item has unresolved assignment; reconcile before retry: ${itemId}`);
-    for (const other of active) for (const path of ownedPaths) for (const prior of other.ownedPaths) if (path === prior || path.startsWith(`${prior}/`) || prior.startsWith(`${path}/`)) throw new Error(`Owned path overlaps active assignment: ${path}`);
+    const leased = active.find((entry) => entry.itemId === itemId && entry.state === "leased");
+    if (leased) throw new Error(`Item already leased: ${itemId}: claimed by ${blockedBy(taskId, leased)}`);
+    const unresolved = value.assignments.find((entry) => entry.itemId === itemId && ["reported", "uncertain"].includes(entry.state));
+    if (unresolved) throw new Error(`Item has unresolved assignment; reconcile before retry: ${itemId}: ${blockedBy(taskId, unresolved)}`);
+    for (const other of active) for (const path of ownedPaths) for (const prior of other.ownedPaths) if (path === prior || path.startsWith(`${prior}/`) || prior.startsWith(`${path}/`)) throw new Error(`Owned path overlaps active assignment: ${path}: held by ${blockedBy(taskId, other)}`);
     const attempt = 1 + Math.max(0, ...value.assignments.filter((entry) => entry.itemId === itemId).map((entry) => entry.attempt));
     const assignment = { id: randomUUID(), taskId, itemId, workerId, ownedPaths, attempt, baseCommit, branch, sessionId, checkpoint: null, state: "leased", leaseExpiresAt: new Date(Date.now() + leaseMs).toISOString(), idempotencyKey: randomUUID(), createdAt: iso(), updatedAt: iso() };
     value.assignments.push(assignment); write(root, taskId, value);
@@ -139,7 +171,7 @@ export function heartbeatLocalAssignment(root, taskId, assignmentId, leaseMs = 3
   return locked(root, taskId, () => {
     const value = read(root, taskId); expire(value, Date.now());
     const item = value.assignments.find((entry) => entry.id === assignmentId);
-    if (!item || item.state !== "leased") throw new Error("Assignment is not leased");
+    if (!item || item.state !== "leased") throw notLeased(taskId, assignmentId, item);
     if (sessionId !== undefined) { if (typeof sessionId !== "string" || !sessionId || sessionId.length > 300) throw new Error("Invalid sessionId"); item.sessionId = sessionId; }
     item.leaseExpiresAt = new Date(Date.now() + leaseMs).toISOString(); item.updatedAt = iso(); write(root, taskId, value); return item;
   });
@@ -152,12 +184,26 @@ export function reportLocalAssignment(root, taskId, assignmentId, { checkpoint =
   return locked(root, taskId, () => {
     const value = read(root, taskId); expire(value, Date.now());
     const item = value.assignments.find((entry) => entry.id === assignmentId);
-    if (!item || item.state !== "leased") throw new Error("Assignment is not leased; reconcile before reporting");
+    if (!item || item.state !== "leased") throw notLeased(taskId, assignmentId, item, "; reconcile before reporting");
     for (const path of changedPaths) if (!item.ownedPaths.some((owned) => path === owned || path.startsWith(`${owned}/`))) throw new Error(`Changed path is outside assignment scope: ${path}`);
     item.state = "reported"; item.checkpoint = checkpoint; item.commit = commit; item.changedPaths = changedPaths; item.updatedAt = iso(); write(root, taskId, value); return item;
   });
 }
 
+/** Record the integration-branch commit created for a reported assignment, so
+ * the dashboard can show exactly what the item changed. It never changes the
+ * assignment state; `reconcile` still marks the item integrated. */
+export function recordLocalIntegration(root, taskId, assignmentId, integrationCommit) {
+  safeId(taskId, "task id");
+  if (typeof integrationCommit !== "string" || !/^[a-f0-9]{40,64}$/.test(integrationCommit)) throw new Error("Invalid integration commit");
+  return locked(root, taskId, () => {
+    const value = read(root, taskId);
+    const item = value.assignments.find((entry) => entry.id === assignmentId);
+    if (!item || !["reported", "integrated"].includes(item.state)) throw new Error("Only a reported or integrated assignment can record its integration commit");
+    item.integrationCommit = integrationCommit; item.updatedAt = iso(); write(root, taskId, value); return item;
+  });
+}
+
 export function reconcileLocalAssignments(root, taskId) {
   const task = canonical(root, taskId);
   return locked(root, taskId, () => {

package/dist/assets/.agents/aidlc/scripts/lib/context-runtime.mjs

@@ -5,6 +5,7 @@
 import { existsSync, lstatSync, readFileSync, readdirSync, realpathSync } from "node:fs";
 import { dirname, isAbsolute, join, normalize, resolve } from "node:path";
 import { loadMemoryRegistry, nextAction, selectAgenticMemory } from "./store.mjs";
+import { resolveTaskRuntimeRead } from "./task-runtime.mjs";
 
 const separator = process.platform === "win32" ? "\\" : "/";
 
@@ -228,10 +229,10 @@ export const compileContext = (root, task, phase = task.phase, options = {}) =>
   const phaseContract = readFileSync(phasePath, "utf8");
   let intake = "";
   if (phase === "clarify") {
-    const parts = [".agents", "data", "tasks", task.id, "requirement.md"];
-    let cursor = resolve(root), safe = true;
-    for (const part of parts) { cursor = join(cursor, part); if (!existsSync(cursor)) { safe = false; break; } if (lstatSync(cursor).isSymbolicLink()) throw new Error("Unsafe requirement path"); }
-    if (safe) { const requirement = readFileSync(cursor, "utf8"); if (Buffer.byteLength(requirement) > 8192) throw new Error("Requirement exceeds intake limit"); intake = `## User requirement\n${requirement}`; }
+    // The intake requirement (runtime/requirement.md, or the pre-runtime task-root copy); symlinked components are refused by the resolver.
+    let cursor;
+    try { cursor = resolveTaskRuntimeRead(root, task.id, "requirement.md"); } catch { throw new Error("Unsafe requirement path"); }
+    if (existsSync(cursor)) { const requirement = readFileSync(cursor, "utf8"); if (Buffer.byteLength(requirement) > 8192) throw new Error("Requirement exceeds intake limit"); intake = `## User requirement\n${requirement}`; }
   }
   let content = [`# AI-DLC phase packet — ${phase}`, `mode: ${options.mode ?? "standard"}${options.itemId ? ` · item: ${options.itemId}` : ""}`, "## Next action / stop contract", JSON.stringify(nextAction(task, root), null, 2), "## Phase contract", phaseContract, ...(intake ? [intake] : []), "## Canonical task state", compact, "## Resolved profiles", profiles.map((item) => JSON.stringify({ id: item.id, topology: item.topology, discovery: item.discovery, specs: item.specs, commands: item.commands })).join("\n"), "## Effective project configuration", JSON.stringify({ discovery: effective.discovery, specs: effective.specs, commands: effective.commands, risk: effective.risk, context: effective.context }, null, 2), "## Invariants", invariants].join("\n\n");
   if (content.length > config.context.maxChars) throw new Error("Context budget is too small for the full phase contract, next action, canonical task state, and mandatory invariants");