@felixdotgo/aidlc-kit 0.2.0 → 0.3.0

package/DEVELOPMENT.md

@@ -1,45 +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
 ```
 
-## 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).
+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,67 +1,63 @@
 # aidlc-kit
 
-[![npm version](https://img.shields.io/npm/v/@felixdotgo/aidlc-kit)](https://www.npmjs.com/package/@felixdotgo/aidlc-kit)
+[![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/)
 
-`@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.
+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]
-> **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.
+> 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.2.0 aidlc-kit init . --agent codex --dry-run
-npx --package @felixdotgo/aidlc-kit@0.2.0 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.2.0`. After installation, the project's lifecycle scripts run locally without `npx` or a registry connection.
+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.
 
-Use the adapter that matches the coding tool:
+Then ask your agent for a change:
 
-| Tool | `--agent` value | Installed entry point |
-| --- | --- | --- |
-| Codex | `codex` | `AGENTS.md` |
-| Claude Code | `claude` | `CLAUDE.md` and phase skills |
-| OpenCode | `opencode` | `AGENTS.md` |
+```text
+Add rate limiting to the login endpoint using the AI-DLC workflow.
+```
 
-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.
+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.
 
-Confirm the installed project locally:
+## Run the loop (optional)
 
-```sh
-npx --package @felixdotgo/aidlc-kit@0.2.0 aidlc-kit status .
-npx --package @felixdotgo/aidlc-kit@0.2.0 aidlc-kit doctor . --strict
-```
+A daemon drives tasks end-to-end on a Linux host with Docker, stopping at every review step for you:
 
-## Documentation
+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.
 
-The detailed documentation is organised by task and audience:
+Setup: [Loop setup runbook](./docs/loop-runbook.md). Daily use: [Local loop walkthrough](./docs/loop-local-run.md).
+
+## Documentation
 
-- [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.
+[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)
 
 ## Safety note
 
-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.
+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/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
 

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");

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

@@ -10,6 +10,8 @@
  *   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
+ *   feedback({ taskId, reason, source })  fleet human feedback that keeps the task at its gate
+ *                                         (local dashboards call `state.mjs task status` directly)
  *
  * 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
@@ -24,7 +26,9 @@ 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 { explainFleetConflict } from "./loop-holder.mjs";
 import { loadState, loadTask, nextAction } from "./store.mjs";
+import { resolveTaskRuntimeRead, taskRuntimeDir } from "./task-runtime.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);
@@ -33,15 +37,15 @@ 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");
+  const path = resolveTaskRuntimeRead(root, taskId, "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;
+  try { const parsed = JSON.parse(stderr); if (parsed?.error?.message) return new Error(explainFleetConflict(parsed.error.message)); } catch { /* not JSON */ }
+  return stderr ? new Error(explainFleetConflict(stderr.split("\n").filter(Boolean).at(-1))) : error;
 };
 
 /** Pick a unique, case-insensitive task id for an intake that did not name one. */
@@ -56,12 +60,14 @@ const uniqueTaskId = (root, slug, takenIds) => {
 
 /** 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 files = [resolveTaskRuntimeRead(root, taskId, "intake.json"), resolveTaskRuntimeRead(root, taskId, "requirement.md")];
   const preexisting = files.map((path) => existsSync(path));
+  const runtimeExisted = existsSync(taskRuntimeDir(root, taskId));
   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; } } });
+      if (!runtimeExisted) { try { rmdirSync(taskRuntimeDir(root, taskId)); } catch { /* not empty or already gone */ } }
       try { rmdirSync(join(tasksDir(root), taskId)); } catch { /* not empty or already gone */ }
     }
     throw error;
@@ -129,7 +135,7 @@ export function createLocalAuthority({ root, agent, workers = {}, workerImages =
 
 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 REVIEWER_SECRETS = ["AIDLC_FLEET_REVIEWER_TOKEN", "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
@@ -226,6 +232,16 @@ export async function createFleetAuthority({ root, agent, workers = {}, limits,
       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); }
+    },
+    /** Human feedback at a gate: records the `Cancelled gate wait` evidence and re-activates the task
+     * so the loop revises and re-presents the same gate. Runs as the lead; never needs the reviewer credential. */
+    async feedback({ taskId, reason, source }) {
+      if (typeof reason !== "string" || !reason.trim()) throw new Error("Feedback reason is required");
+      if (typeof source !== "string" || !source.trim()) throw new Error("Feedback source is required");
+      const task = await readTask(taskId);
+      if (!task) throw new Error(`Unknown task: ${taskId}`);
+      if (task.status !== "blocked_on_user" || task.gate === "none") throw new Error("Task is not waiting at a human gate");
+      return withLead(taskId, ["task", "status", taskId, "--status", "active", "--mode", "audited", "--reason", reason, "--source", source]);
     }
   };
 }