@felixdotgo/aidlc-kit 0.1.1 → 0.3.0

package/dist/assets/.agents/aidlc/scripts/loop-gate.mjs

@@ -41,18 +41,30 @@ async function main() {
   console.log(review.view.trimEnd());
   console.log(`Review identity: ${JSON.stringify({ taskId, phase: review.phase, gate: review.gate, taskHash: review.taskHash, artifacts: review.artifacts, integrationCommit: review.commit })}`);
   const rl = createInterface({ input: stdin, output: stdout });
-  let answer; try { answer = await rl.question("Type approve to approve this exact review: "); } finally { rl.close(); }
-  if (answer.trim() !== "approve") throw new Error("Review was not approved");
+  let answer; try { answer = await rl.question("Type approve to approve this exact review, or type feedback to send guidance back to the loop: "); } finally { rl.close(); }
+  const trimmed = answer.trim();
+  if (!trimmed) throw new Error("Review was not approved");
   release = acquireStateLock(root);
   try {
     const state = loadState(root), fresh = snapshot(root, taskId, state);
     if (digest({ ...fresh, view: undefined }) !== digest({ ...review, view: undefined })) throw new Error("Review changed while waiting for approval; inspect the new review");
-    const checkpoint = readLocalGateCheckpoint(root, state.tasks[taskId]);
+    const task = state.tasks[taskId];
     const reviewHash = digest({ ...review, view: undefined });
-    const outcome = approveAndAdvance(root, state, taskId, review.gate, `Trusted host terminal: approve (${reviewHash})`);
-    saveState(root, state);
-    writeLocalGateReceipt(root, checkpoint, outcome.task, reviewHash);
-    console.log(`Approved ${review.gate}; next action: ${JSON.stringify(outcome.nextAction)}`);
+    if (trimmed === "approve") {
+      const checkpoint = readLocalGateCheckpoint(root, task);
+      const outcome = approveAndAdvance(root, state, taskId, review.gate, `Trusted host terminal: approve (${reviewHash})`);
+      saveState(root, state);
+      writeLocalGateReceipt(root, checkpoint, outcome.task, reviewHash);
+      console.log(`Approved ${review.gate}; next action: ${JSON.stringify(outcome.nextAction)}`);
+    } else {
+      const recordedAt = new Date().toISOString();
+      task.evidence.push({ kind: "diagnostic", result: "pass", source: `Trusted host terminal: feedback (${reviewHash})`, detail: `Cancelled gate wait at ${task.gate}: ${trimmed}`, recordedAt });
+      delete task.legacyG2Wait;
+      task.status = "active";
+      task.updatedAt = recordedAt;
+      saveState(root, state);
+      console.log(`Feedback recorded at ${review.gate}; the loop will revise the review and re-present the gate`);
+    }
   } finally { release(); }
 }
 main().catch((error) => { console.error(`loop-gate: ${error.message}`); process.exitCode = 1; });

package/dist/assets/.agents/aidlc/scripts/loop.cmd

@@ -0,0 +1,101 @@
+@echo off
+rem AI-DLC loop launcher (managed by aidlc-kit; upgrades overwrite local edits).
+rem   .agents\aidlc\scripts\loop.cmd [command] [options]
+rem Edit .agents\config.json ("loop") and .agents\loop.env, then run "loop.cmd up".
+rem The script only locates the aidlc-kit CLI and forwards to "aidlc-kit loop <command>";
+rem it never installs or upgrades anything. Local workers need Docker Desktop; the loop is
+rem verified on Linux, so treat native Windows as best effort.
+setlocal
+for %%I in ("%~dp0..\..\..") do set "ROOT=%%~fI"
+
+where node >nul 2>nul
+if errorlevel 1 (
+  echo loop.cmd: Node.js 20.17 or newer is required ^(https://nodejs.org^) 1>&2
+  exit /b 1
+)
+
+set "CMD=%~1"
+rem Options without a command run the default command: "loop.cmd --open" = "loop.cmd up --open".
+if "%CMD%"=="" goto default_cmd
+if /i "%CMD%"=="-h" goto named_cmd
+if /i "%CMD%"=="--help" goto named_cmd
+if "%CMD:~0,1%"=="-" goto default_cmd
+:named_cmd
+shift
+goto args
+:default_cmd
+set "CMD=up"
+:args
+set "ARGS="
+:collect
+if "%~1"=="" goto dispatch
+set ARGS=%ARGS% %1
+shift
+goto collect
+
+:dispatch
+if /i "%CMD%"=="help" goto usage
+if /i "%CMD%"=="-h" goto usage
+if /i "%CMD%"=="--help" goto usage
+if /i "%CMD%"=="check" set "CMD=env"
+if /i "%CMD%"=="logs" goto logs
+for %%C in (up down stop status env) do if /i "%CMD%"=="%%C" goto run
+echo loop.cmd: unknown command: %CMD% 1>&2
+call :usage 1>&2
+exit /b 2
+
+:run
+call :cli loop %CMD% --root "%ROOT%" %ARGS%
+exit /b %ERRORLEVEL%
+
+:cli
+if exist "%ROOT%\node_modules\.bin\aidlc-kit.cmd" (
+  call "%ROOT%\node_modules\.bin\aidlc-kit.cmd" %*
+  goto :eof
+)
+set "RECORDED_CLI="
+for /f "usebackq delims=" %%P in (`node -e "try{const r=require(process.argv[1]);if(typeof r.cli==='string'&&require('fs').statSync(r.cli).isFile())process.stdout.write(r.cli)}catch{}" "%ROOT%\.agents\data\loop\cli.json" 2^>nul`) do set "RECORDED_CLI=%%P"
+if defined RECORDED_CLI (
+  node "%RECORDED_CLI%" %*
+  goto :eof
+)
+where aidlc-kit >nul 2>nul
+if not errorlevel 1 (
+  call aidlc-kit %*
+  goto :eof
+)
+set "VERSION=latest"
+for /f "usebackq delims=" %%V in (`node -p "require(process.argv[1]).packageVersion" "%ROOT%\.agents\aidlc\manifest.json" 2^>nul`) do set "VERSION=%%V"
+where npx >nul 2>nul
+if not errorlevel 1 (
+  echo loop.cmd: aidlc-kit was not found in this project or recorded by init/upgrade; trying npx --no-install ^(if it fails: npm install --save-dev @felixdotgo/aidlc-kit@%VERSION%, or rerun init/upgrade from the package or .tgz you want^) 1>&2
+  call npx --no-install @felixdotgo/aidlc-kit %*
+  goto :eof
+)
+echo loop.cmd: the aidlc-kit CLI was not found: install it in this project ^(npm install --save-dev @felixdotgo/aidlc-kit@%VERSION%^), or rerun init/upgrade from the package or .tgz you want 1>&2
+exit /b 1
+
+:logs
+set "LOG=%ROOT%\.agents\data\loop\daemon.log"
+if exist "%LOG%" goto follow_log
+echo No daemon log yet: "%LOG%"
+exit /b 0
+:follow_log
+powershell -NoProfile -Command "Get-Content -LiteralPath $env:LOG -Tail 200 -Wait"
+exit /b %ERRORLEVEL%
+
+:usage
+echo Usage: .agents\aidlc\scripts\loop.cmd [command] [options]
+echo.
+echo Commands:
+echo   up       check the environment, start the loop daemon, and serve the dashboard (default)
+echo            options: --loop-env PATH  --port 4173  --host 127.0.0.1  --open  --no-ui
+echo   down     stop the dashboard started by "up" and the loop daemon (--now cancels the running turn)
+echo   stop     stop only the loop daemon (--now cancels the running turn)
+echo   status   daemon, dashboard, and environment at a glance (--json)
+echo   check    show providers, the env file, and every variable the loop needs (--json)
+echo   logs     follow the daemon log
+echo   help     show this help
+echo.
+echo Configure .agents\config.json ("loop" section) and .agents\loop.env (model and API keys).
+exit /b 0

package/dist/assets/.agents/aidlc/scripts/loop.mjs

@@ -2,6 +2,7 @@
 import { resolve } from "node:path";
 import { loopStatus, runLoop } from "./lib/loop-runtime.mjs";
 import { LOOP_PROVIDERS, runAgentTurn } from "./lib/loop-drivers.mjs";
+import { streamLog } from "./lib/loop-stream.mjs";
 import { requireLocalAuthority } from "./lib/authority.mjs";
 
 function parse(argv) {
@@ -27,7 +28,7 @@ function parse(argv) {
 try {
   requireLocalAuthority();
   const options = parse(process.argv.slice(2));
-  const result = options.command === "status" ? loopStatus(options.root, options.taskId) : await runLoop({ root: options.root, taskId: options.taskId, agent: options.agent, mode: options.command, limits: options.limits, driver: runAgentTurn, preflight: true, onEvent: (event) => { if (event?.type === "diagnostic") console.error(event.message); if (event?.type === "resume" || event?.type === "context_changed") console.error(JSON.stringify(event)); } });
+  const result = options.command === "status" ? loopStatus(options.root, options.taskId) : await runLoop({ root: options.root, taskId: options.taskId, agent: options.agent, mode: options.command, limits: options.limits, driver: runAgentTurn, preflight: true, onEvent: (event) => { streamLog(event); if (event?.type === "diagnostic") console.error(event.message); if (event?.type === "resume" || event?.type === "context_changed") console.error(JSON.stringify(event)); } });
   console.log(JSON.stringify({ ok: true, result }, null, 2));
   if (result.status && !["complete", "gate"].includes(result.status)) process.exitCode = 2;
 } catch (error) {

package/dist/assets/.agents/aidlc/scripts/loop.sh

@@ -0,0 +1,71 @@
+#!/bin/sh
+# AI-DLC loop launcher (managed by aidlc-kit; upgrades overwrite local edits).
+#
+#   .agents/aidlc/scripts/loop.sh [command] [options]
+#
+# Edit .agents/config.json ("loop") and .agents/loop.env, then run `loop.sh up`.
+# The script only locates the aidlc-kit CLI and forwards to `aidlc-kit loop <command>`;
+# it never installs or upgrades anything.
+set -eu
+
+SCRIPT_DIR=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
+ROOT=$(CDPATH= cd -- "$SCRIPT_DIR/../../.." && pwd)
+
+usage() {
+  cat <<'EOF'
+Usage: .agents/aidlc/scripts/loop.sh [command] [options]
+
+Commands:
+  up       check the environment, start the loop daemon, and serve the dashboard (default)
+           options: --loop-env PATH  --port 4173  --host 127.0.0.1  --open  --no-ui
+  down     stop the dashboard started by `up` and the loop daemon (--now cancels the running turn)
+  stop     stop only the loop daemon (--now cancels the running turn)
+  status   daemon, dashboard, and environment at a glance (--json)
+  check    show providers, the env file, and every variable the loop needs (--json)
+  logs     follow the daemon log
+  help     show this help
+
+Configure:
+  .agents/config.json   "loop": { "mode": "local", "agents": { "lead": "<provider>", "workers": { "worker-a": "<provider>" } } }
+  .agents/loop.env      model and API keys (git-ignored); values your tools already store are detected
+EOF
+}
+
+command -v node >/dev/null 2>&1 || { echo "loop.sh: Node.js 20.17 or newer is required (https://nodejs.org)" >&2; exit 1; }
+
+# The installed workflow version, so hints name the matching package.
+VERSION=$(node -p 'require(process.argv[1]).packageVersion' "$ROOT/.agents/aidlc/manifest.json" 2>/dev/null || echo latest)
+INSTALL_HINT="install it in this project (npm install --save-dev @felixdotgo/aidlc-kit@$VERSION), or rerun init/upgrade from the package or .tgz you want"
+# The CLI that installed this workflow (recorded by init/upgrade), if it still exists.
+RECORDED_CLI=$(node -e 'try{const r=require(process.argv[1]);if(typeof r.cli==="string"&&require("fs").statSync(r.cli).isFile())process.stdout.write(r.cli)}catch{}' "$ROOT/.agents/data/loop/cli.json" 2>/dev/null || true)
+
+run_cli() {
+  if [ -x "$ROOT/node_modules/.bin/aidlc-kit" ]; then exec "$ROOT/node_modules/.bin/aidlc-kit" "$@"; fi
+  if [ -n "$RECORDED_CLI" ]; then exec node "$RECORDED_CLI" "$@"; fi
+  if command -v aidlc-kit >/dev/null 2>&1; then exec aidlc-kit "$@"; fi
+  if command -v npx >/dev/null 2>&1; then
+    echo "loop.sh: aidlc-kit was not found in this project or recorded by init/upgrade; trying npx --no-install (if it fails: $INSTALL_HINT)" >&2
+    exec npx --no-install @felixdotgo/aidlc-kit "$@"
+  fi
+  echo "loop.sh: the aidlc-kit CLI was not found: $INSTALL_HINT" >&2
+  exit 1
+}
+
+# Options without a command run the default command: `loop.sh --open` = `loop.sh up --open`.
+case "${1:-up}" in
+  -h|--help) cmd=help; shift ;;
+  -*) cmd=up ;;
+  *) cmd=${1:-up}; [ $# -gt 0 ] && shift ;;
+esac
+
+case "$cmd" in
+  up|down|stop|status) run_cli loop "$cmd" --root "$ROOT" "$@" ;;
+  check|env) run_cli loop env --root "$ROOT" "$@" ;;
+  logs)
+    log="$ROOT/.agents/data/loop/daemon.log"
+    if [ ! -f "$log" ]; then echo "No daemon log yet: $log"; exit 0; fi
+    exec tail -n 200 -f "$log"
+    ;;
+  help|-h|--help) usage ;;
+  *) echo "loop.sh: unknown command: $cmd" >&2; usage >&2; exit 2 ;;
+esac

package/dist/assets/.agents/aidlc/scripts/remote-state.mjs

@@ -5,7 +5,9 @@ import { readFile } from "node:fs/promises";
 import { promisify } from "node:util";
 import { createRemoteReviewerClient, createRemoteStateClient, featureConfig, remoteConfig, reviewerConfig } from "./lib/remote-state-client.mjs";
 import { compileContext } from "./lib/context-runtime.mjs";
-import { checkGate, closeTask, handoffTask, nextAction, readyTaskItems, recordLesson, recordNoLessons, reopenTask, transitionTask, validateState } from "./lib/store.mjs";
+import { explainFleetConflict } from "./lib/loop-holder.mjs";
+import { checkGate, closeTask, handoffTask, nextAction, readyTaskItems, recordLesson, recordNoLessons, recordTaskCommit, reopenTask, transitionTask, validateState } from "./lib/store.mjs";
+import { headCommit } from "./lib/repo-head.mjs";
 
 const parse = (argv) => {
   const positionals = []; const options = new Map();
@@ -54,9 +56,9 @@ export const runRemoteState = async (argv, client, root, git = {}) => {
   required(id, "task id");
   const allowed = {
     "task show": [], "task next": [], "task ready": [], "gate check": ["--gate"], "phase context": ["--phase", "--mode", "--item"],
-    "task create": ["--title", "--type", "--language", "--risk", "--area", "--feature"],
+    "task create": ["--title", "--type", "--language", "--risk", "--area", "--feature", "--base-commit"],
     "task status": ["--status", "--mode", "--reason", "--source"], "task item": ["--status", "--label", "--depends-on", "--owns"],
-    "task transition": ["--to", "--mode", "--reason", "--source"],
+    "task transition": ["--to", "--mode", "--reason", "--source", "--final-commit"],
     "task handoff": ["--kind", "--reason", "--source"], "task close": ["--reason", "--source"], "task reopen": ["--to", "--reason", "--source"],
     "decision set": ["--status", "--label", "--resolution"],
     "evidence add": ["--kind", "--result", "--gate", "--area", "--source", "--detail"],
@@ -118,6 +120,8 @@ export const runRemoteState = async (argv, client, root, git = {}) => {
       areas: (option("--area") ?? "root").split(",").map((item) => item.trim()).filter(Boolean), branch: "—",
       artifacts: { intent: `.agents/data/tasks/${id}/intent.md`, design: `.agents/data/tasks/${id}/design.md`, workplan: `.agents/data/tasks/${id}/workplan.md` },
       decisions: [], tasks: [], evidence: [], createdAt: recordedAt, updatedAt: recordedAt };
+    const baseCommit = option("--base-commit") ?? headCommit(root);
+    if (baseCommit !== undefined) recordTaskCommit(task, "baseCommit", baseCommit);
   } else {
     if (!previous) throw new Error(`Unknown task: ${id}`);
     task = structuredClone(previous);
@@ -161,6 +165,7 @@ export const runRemoteState = async (argv, client, root, git = {}) => {
       if (option("--mode") !== "audited") throw new Error("Transition requires --mode audited");
       const reason = required(option("--reason"), "--reason"); const source = required(option("--source"), "--source");
       const target = required(option("--to"), "--to");
+      if (target !== "done" && option("--final-commit") !== undefined) throw new Error("--final-commit is only accepted with --to done");
       if (target === "done" && task.featureId) {
         const manifest = await client.featureGet(task.featureId);
         const member = manifest?.feature?.tasks?.find((entry) => entry.id === id);
@@ -171,6 +176,7 @@ export const runRemoteState = async (argv, client, root, git = {}) => {
       const clone = structuredClone(state); clone.tasks[id] = task;
       transitionTask(clone, id, target);
       task = clone.tasks[id];
+      if (target === "done") { const finalCommit = option("--final-commit") ?? headCommit(root); if (finalCommit !== undefined) recordTaskCommit(task, "finalCommit", finalCommit); }
       task.evidence.push({ kind: "diagnostic", result: "pass", source, detail: `Audited transition ${previous.phase} → ${target}: ${reason}`, recordedAt: now() });
     } else if (route === "decision set") {
       const status = required(option("--status"), "--status");
@@ -307,5 +313,5 @@ if (isEntry) {
     const result = isReview ? await runRemoteReview(argv, createRemoteReviewerClient(config), config) : argv[0] === "feature" ? await runRemoteFeature(argv, createRemoteStateClient(config)) : argv[0] === "run" ? await runRemoteLease(argv, createRemoteStateClient(config)) : await runRemoteState(argv, createRemoteStateClient(config), config.projectRoot, config);
     console.log(JSON.stringify(result, null, 2));
     if (!result.ok) process.exitCode = 1;
-  } catch (error) { console.error(JSON.stringify({ ok: false, error: error.message, code: error.code, currentRevision: error.current?.revision }, null, 2)); process.exitCode = 1; }
+  } catch (error) { console.error(JSON.stringify({ ok: false, error: error.code === "FLEET_CONFLICT" ? explainFleetConflict(error.message) : error.message, code: error.code, currentRevision: error.current?.revision }, null, 2)); process.exitCode = 1; }
 }

package/dist/assets/.agents/aidlc/scripts/state.mjs

@@ -6,13 +6,14 @@
 import { acquireStateLock, approveAndAdvance, checkGate, closeTask, failEntry, handoffTask, listTaskSummaries, loadMemoryRegistry, loadState, loadTask, migrateState, nextAction, option, parseArguments, promoteAgenticMemory, rebuildLessonIndex, recordLesson, recordNoLessons, renderViews, reopenTask, retireAgenticMemory, rootOption, saveState, searchLessons, supersedeTask, transitionTask, validateArguments } from "./lib/runtime.mjs";
 import { readLiveLease } from "./lib/loop-lease.mjs";
 import { listFeatures, loadFeature, readyFeatureTasks, saveFeature } from "./lib/feature-store.mjs";
-import { readyTaskItems } from "./lib/store.mjs";
+import { readyTaskItems, recordTaskCommit } from "./lib/store.mjs";
+import { headCommit } from "./lib/repo-head.mjs";
 import { requireLocalAuthority } from "./lib/authority.mjs";
 
 try {
 requireLocalAuthority();
 const raw = process.argv.slice(2);
-const valueOptions = ["--root", "--status", "--limit", "--cursor", "--query", "--title", "--type", "--language", "--risk", "--area", "--mode", "--reason", "--source", "--to", "--kind", "--successor", "--label", "--resolution", "--result", "--gate", "--detail", "--summary", "--prevention", "--example", "--promotion", "--guidance", "--phase", "--priority", "--source-task", "--source-lesson", "--approved-by", "--switch-from", "--feature", "--depends-on", "--branch", "--owns"];
+const valueOptions = ["--root", "--status", "--limit", "--cursor", "--query", "--title", "--type", "--language", "--risk", "--area", "--mode", "--reason", "--source", "--to", "--kind", "--successor", "--label", "--resolution", "--result", "--gate", "--detail", "--summary", "--prevention", "--example", "--promotion", "--guidance", "--phase", "--priority", "--source-task", "--source-lesson", "--approved-by", "--switch-from", "--feature", "--depends-on", "--branch", "--owns", "--base-commit", "--final-commit"];
 const parsed = parseArguments(raw, { valueOptions, booleanOptions: ["--include-archive"] });
 const args = parsed.positionals;
 const [group, action, rawId] = args;
@@ -24,9 +25,9 @@ const schemas = {
   "task find": { minPositionals: 2, valueOptions: ["--query", "--status", "--limit", "--cursor"], booleanOptions: ["--include-archive"], requiredOptions: ["--query"] },
   "task next": { minPositionals: 3 },
   "task ready": { minPositionals: 3 },
-  "task create": { minPositionals: 3, valueOptions: ["--title", "--type", "--language", "--risk", "--area", "--switch-from", "--feature", "--depends-on"], requiredOptions: ["--title"] },
-  "task transition": { minPositionals: 3, valueOptions: ["--mode", "--reason", "--source", "--to"], requiredOptions: ["--mode", "--reason", "--source", "--to"], usage: "task transition requires --mode audited, --reason, --source, and --to" },
-  "task archive": { minPositionals: 3, valueOptions: ["--reason", "--source"], requiredOptions: ["--reason", "--source"] },
+  "task create": { minPositionals: 3, valueOptions: ["--title", "--type", "--language", "--risk", "--area", "--switch-from", "--feature", "--depends-on", "--base-commit"], requiredOptions: ["--title"] },
+  "task transition": { minPositionals: 3, valueOptions: ["--mode", "--reason", "--source", "--to", "--final-commit"], requiredOptions: ["--mode", "--reason", "--source", "--to"], usage: "task transition requires --mode audited, --reason, --source, and --to" },
+  "task archive": { minPositionals: 3, valueOptions: ["--reason", "--source", "--final-commit"], requiredOptions: ["--reason", "--source"] },
   "task handoff": { minPositionals: 3, valueOptions: ["--kind", "--reason", "--source"], requiredOptions: ["--kind", "--reason", "--source"] },
   "task close": { minPositionals: 3, valueOptions: ["--reason", "--source"], requiredOptions: ["--reason", "--source"] },
   "task supersede": { minPositionals: 3, valueOptions: ["--successor", "--reason", "--source"], requiredOptions: ["--successor", "--reason", "--source"] },
@@ -75,6 +76,7 @@ const summaryOptions = (query) => ({
   cursor: numberOption("--cursor", 0)
 });
 const warnings = [];
+const recordFinalCommit = (task) => { const sha = option(parsed, "--final-commit") ?? headCommit(root); if (sha !== undefined) recordTaskCommit(task, "finalCommit", sha); };
 const derivedStep = (code, hint, step) => { try { step(); } catch (error) { warnings.push({ code, message: error instanceof Error ? error.message : String(error), hint }); } };
 const persist = (tasks, rebuildLessons = false) => {
   const archived = saveState(root, state);
@@ -158,6 +160,8 @@ if (group === "state" && action === "migrate") {
     artifacts: { intent: `.agents/data/tasks/${id}/intent.md`, design: `.agents/data/tasks/${id}/design.md`, workplan: `.agents/data/tasks/${id}/workplan.md` },
     decisions: [], tasks: [], evidence: [], createdAt: recordedAt, updatedAt: recordedAt
   };
+  const baseCommit = option(parsed, "--base-commit") ?? headCommit(root);
+  if (baseCommit !== undefined) recordTaskCommit(task, "baseCommit", baseCommit);
   const acknowledgedTasks = acknowledged.map((ack) => state.tasks[ack]);
   for (const prior of acknowledgedTasks) {
     prior.evidence.push({ kind: "diagnostic", result: "pass", source: `task create ${id}`, detail: `Switch acknowledged: created ${id} while ${prior.id} was actionable; ${prior.id} keeps its state — resume with task next ${prior.id}`, recordedAt });
@@ -172,13 +176,16 @@ if (group === "state" && action === "migrate") {
 } else if (group === "task" && action === "transition") {
   const mode = option(parsed, "--mode"); const reason = option(parsed, "--reason"); const source = option(parsed, "--source");
   if (mode !== "audited" || !reason?.trim() || !source?.trim()) throw new Error("task transition requires --mode audited, --reason, and --source");
-  const from = state.tasks[id]?.phase; const target = option(parsed, "--to"); if (target === "done") requireFeaturePrerequisites(state.tasks[id]); const task = transitionTask(state, id, target);
+  const from = state.tasks[id]?.phase; const target = option(parsed, "--to"); if (target === "done") requireFeaturePrerequisites(state.tasks[id]);
+  if (target !== "done" && option(parsed, "--final-commit") !== undefined) throw new Error("--final-commit is only accepted with --to done");
+  const task = transitionTask(state, id, target);
+  if (target === "done") recordFinalCommit(task);
   task.evidence.push({ kind: "diagnostic", result: "pass", source, detail: `Audited transition ${from} → ${target}: ${reason}`, recordedAt: now() });
   persist([task]); respond(task);
 } else if (group === "task" && action === "archive") {
   const reason = option(parsed, "--reason"); const source = option(parsed, "--source");
   if (!reason?.trim() || !source?.trim()) throw new Error("task archive requires --reason and --source");
-  requireFeaturePrerequisites(state.tasks[id]); const task = transitionTask(state, id, "done");
+  requireFeaturePrerequisites(state.tasks[id]); const task = transitionTask(state, id, "done"); recordFinalCommit(task);
   task.evidence.push({ kind: "diagnostic", result: "pass", source, detail: `Archive to done: ${reason}`, recordedAt: now() });
   persist([task], true); respond(task);
 } else if (group === "task" && action === "handoff") {
@@ -270,7 +277,8 @@ if (group === "state" && action === "migrate") {
 } else if (group === "gate" && action === "approve") {
   const gate = option(parsed, "--gate"); const source = option(parsed, "--source");
   if (!id || !gate || !source) throw new Error("gate approve requires active task id, --gate, and explicit --source");
-  if (readLiveLease(root, id)) throw new Error(`Gate approval is unavailable while loop runner owns ${id}; wait for the runner to stop at the human gate`);
+  const runner = readLiveLease(root, id);
+  if (runner) throw new Error(`Gate approval is unavailable while loop runner owns ${id}; wait for the runner to stop at the human gate (task lease held by pid ${runner.pid}${runner.host ? ` on ${runner.host}` : ""}${runner.activity ? `, activity ${runner.activity}` : ""}${runner.expiresAt ? `, expires ${runner.expiresAt}` : ""}; inspect: node .agents/aidlc/scripts/loop-entry.mjs leases ${id})`);
   const outcome = approveAndAdvance(root, state, id, gate, source); persist([outcome.task]); emit({ task: outcome.task, idempotent: outcome.idempotent }, outcome.task);
 } else {
   throw new Error(usage);

package/dist/assets/.agents/aidlc/templates/design.md

@@ -11,5 +11,14 @@
 ## 🔗 Cross-service contracts
 - <contract or `none`>
 
+## 🔀 Parallel work partition
+| item | owned paths | depends on | verification |
+|------|-------------|------------|--------------|
+| <item-id> | <paths it alone writes> | <item-ids or `none`> | <narrow command> |
+
+- One owner per path among items that can run at the same time; overlapping items must be ordered with `dependsOn`.
+- Shared surfaces (barrel/index files, shared config, cross-cutting docs, a single entry script) get exactly one owning item; others depend on it.
+- Prefer file/module-level ownership over broad parent directories.
+
 ## ⚠️ Risks / edge cases
 - <risk and mitigation>

package/dist/assets/.agents/aidlc/templates/intent.md

@@ -6,6 +6,10 @@
 ## 🗺️ Affected areas
 - `<area>` — <why> — spec: <indexed source or `none indexed`>
 
+## 🔀 Work boundaries
+- `<work stream>` — <code areas/paths it touches> — <independent of / depends on>
+- or `single stream` — <why the work cannot be split>
+
 ## 💭 Assumptions
 - <assumption>
 

package/dist/assets/.agents/aidlc/templates/workplan.md

@@ -6,4 +6,4 @@
 - <generated decision state>
 
 ## 🧩 Tasks (Review implementation — work items)
-- <generated task state>
+- <generated task state — each line shows `owns: <paths> · after: <item-ids>`>

package/dist/assets/.agents/skills/aidlc-plan/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: aidlc-plan
-description: "AI-DLC phase 2 (Approve plan): after intent is confirmed, run bounded discovery, then produce a detailed design, canonical decisions, and a per-submodule workplan. Triggers when the AI-DLC Orchestrator routes a task after requirements confirmation to planning. Ends at the executable Approve plan review for explicit user approval."
+description: "AI-DLC phase 2 (Approve plan): after intent is confirmed, run bounded discovery, then produce a detailed design, canonical decisions, and a per-submodule workplan whose items own non-overlapping paths so parallel workers do not collide. Triggers when the AI-DLC Orchestrator routes a task after requirements confirmation to planning. Ends at the executable Approve plan review for explicit user approval."
 ---
 
 # AI-DLC · Plan (Approve plan) — adapter