@felixdotgo/aidlc-kit 0.0.1 → 0.1.0

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

@@ -0,0 +1,309 @@
+#!/usr/bin/env node
+// Fleet lead lifecycle entry point. It never reads or writes local lifecycle JSON.
+import { execFile } from "node:child_process";
+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";
+
+const parse = (argv) => {
+  const positionals = []; const options = new Map();
+  for (let i = 0; i < argv.length; i += 1) {
+    const value = argv[i];
+    if (!value.startsWith("--")) { positionals.push(value); continue; }
+    if (i + 1 >= argv.length || argv[i + 1].startsWith("--")) throw new Error(`Missing value for ${value}`);
+    if (options.has(value)) throw new Error(`Duplicate option: ${value}`);
+    options.set(value, argv[++i]);
+  }
+  return { positionals, options, option: (name) => options.get(name) };
+};
+
+const required = (value, name) => { if (typeof value !== "string" || !value.trim()) throw new Error(`${name} is required`); return value; };
+const statuses = new Set(["active", "blocked_on_user", "paused"]);
+const itemStatuses = new Set(["todo", "in_progress", "done", "deferred"]);
+const evidenceKinds = new Set(["spec", "test", "lint", "review", "diagnostic"]);
+const results = new Set(["pass", "fail", "skip"]);
+const gateNames = new Set(["G0_confirm", "G1_review", "G2_codereview"]);
+const now = () => new Date().toISOString();
+const execFileAsync = promisify(execFile);
+export const readIntegrationCommit = async ({ projectRoot, integrationBranch, gitRemote = "origin" }, run = execFileAsync) => {
+  if (!projectRoot?.startsWith("/") || !integrationBranch || !/^[A-Za-z0-9][A-Za-z0-9._/-]{0,127}$/.test(integrationBranch) || integrationBranch.includes("..") || integrationBranch.endsWith("/") || !gitRemote || gitRemote.startsWith("-")) throw new Error("Valid project root, integration branch, and Git remote are required for G2 approval");
+  const ref = `refs/heads/${integrationBranch}`;
+  let stdout;
+  try { ({ stdout } = await run("git", ["ls-remote", "--exit-code", "--heads", gitRemote, ref], { cwd: projectRoot, timeout: 20000, maxBuffer: 65536 })); }
+  catch (error) { throw new Error(`Cannot verify integration branch remote ref: ${error.message}`); }
+  const rows = String(stdout).trim().split(/\r?\n/).filter(Boolean).map((line) => line.split("\t"));
+  if (rows.length !== 1 || rows[0][1] !== ref || !/^[a-f0-9]{40}$/i.test(rows[0][0])) throw new Error("Integration branch remote ref is missing or ambiguous");
+  return rows[0][0].toLowerCase();
+};
+const remoteCommand = (value) => typeof value === "string" ? value
+  .replace(/node (?:"([^"]*\/)context\.mjs"|([^\s"]*\/)context\.mjs)/g, (_match, quoted, bare) => quoted ? `node "${quoted}remote-state.mjs" phase context` : `node ${bare}remote-state.mjs phase context`)
+  .replace(/node (?:"([^"]*\/)state\.mjs"|([^\s"]*\/)state\.mjs)/g, (_match, quoted, bare) => quoted ? `node "${quoted}remote-state.mjs"` : `node ${bare}remote-state.mjs`)
+  .replace(/node (?:"([^"]*\/)gate-check\.mjs"|([^\s"]*\/)gate-check\.mjs)/g, (_match, quoted, bare) => quoted ? `node "${quoted}remote-state.mjs" gate check` : `node ${bare}remote-state.mjs gate check`)
+  .replace(/ --root (?:"[^"]*"|[^\s]+)/g, "") : value;
+const remoteAction = (action) => action && typeof action === "object" ? { ...action, ...(action.command ? { command: remoteCommand(action.command) } : {}) } : action;
+
+export const runRemoteState = async (argv, client, root, git = {}) => {
+  const { positionals: args, options, option } = parse(argv);
+  const [group, action, id, extra] = args;
+  const route = `${group ?? ""} ${action ?? ""}`;
+  const readOnly = new Set(["task show", "task next", "task ready", "gate check", "phase context"]);
+  const mutations = new Set(["task create", "task status", "task item", "task transition", "task handoff", "task close", "task reopen", "decision set", "evidence add", "lesson record", "lesson none", "gate snapshot"]);
+  if (!readOnly.has(route) && !mutations.has(route)) throw new Error(`Unsupported remote lifecycle command: ${route}. Gate approval is reviewer-only.`);
+  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 status": ["--status", "--mode", "--reason", "--source"], "task item": ["--status", "--label", "--depends-on", "--owns"],
+    "task transition": ["--to", "--mode", "--reason", "--source"],
+    "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"],
+    "lesson record": ["--area", "--summary", "--prevention", "--example", "--promotion", "--source"],
+    "lesson none": ["--reason", "--source"],
+    "gate snapshot": ["--gate", "--review-file"]
+  }[route];
+  for (const key of options.keys()) if (!allowed.includes(key)) throw new Error(`Unsupported option for ${route}: ${key}`);
+  if (extra && !["task item", "decision set", "lesson record"].includes(route)) throw new Error(`Unexpected argument: ${extra}`);
+  if (!extra && ["task item", "decision set", "lesson record"].includes(route)) throw new Error(`${route} requires an item/decision/lesson id`);
+
+  const current = await client.get();
+  if (!Number.isSafeInteger(current?.revision) || !current?.state?.tasks) throw new Error("Remote coordination returned invalid canonical state");
+  const state = current.state;
+  const previous = state.tasks[id];
+  if (route === "task show") return { ok: true, result: previous ?? null };
+  if (route === "task next") { if (!previous) throw new Error(`Unknown task: ${id}`); return { ok: true, result: { id, phase: previous.phase, gate: previous.gate, status: previous.status }, nextAction: remoteAction(nextAction(previous, root)) }; }
+  if (route === "task ready") { if (!previous) throw new Error(`Unknown task: ${id}`); return { ok: true, result: { id, ...readyTaskItems(previous) }, nextAction: remoteAction(nextAction(previous, root)) }; }
+  if (route === "phase context") {
+    if (!previous) throw new Error(`Unknown task: ${id}`);
+    const packet = compileContext(root, previous, option("--phase") ?? previous.phase, { mode: option("--mode") ?? "standard", itemId: option("--item") });
+    const warning = "Fleet lifecycle authority: use remote-state.mjs for task, evidence, decision, lesson, and gate commands. Lead credentials cannot approve gates; only a reviewer using AIDLC_FLEET_REVIEWER_TOKEN may run gate approve after explicit user assent.\n\n";
+    const content = warning + remoteCommand(packet.content);
+    return { ok: true, result: { ...packet, content, chars: content.length, estimatedTokens: Math.ceil(content.length / 4), canonicalRevision: current.revision } };
+  }
+  if (route === "gate check") {
+    if (!previous) throw new Error(`Unknown task: ${id}`);
+    const gate = option("--gate") ?? previous.gate;
+    if (!gateNames.has(gate)) throw new Error("Gate must be G0_confirm, G1_review, or G2_codereview");
+    const diagnostics = checkGate(root, state, id, gate);
+    return { ok: !diagnostics.some((item) => item.level === "ERROR"), result: { taskId: id, gate, diagnostics } };
+  }
+  if (route === "gate snapshot") {
+    if (!previous) throw new Error(`Unknown task: ${id}`);
+    const gate = required(option("--gate"), "--gate");
+    if (!gateNames.has(gate) || previous.gate !== gate || previous.status !== "blocked_on_user") throw new Error("Task is not waiting at the requested gate");
+    const reviewFile = required(option("--review-file"), "--review-file");
+    const reviewText = await readFile(reviewFile, "utf8");
+    if (!reviewText.trim() || reviewText.length > 20000) throw new Error("Review text must contain 1–20000 characters");
+    const integrationCommit = gate === "G2_codereview" ? await (git.readRemoteRef ?? readIntegrationCommit)({ projectRoot: root, integrationBranch: git.integrationBranch, gitRemote: git.gitRemote }) : undefined;
+    return { ok: true, result: await client.snapshot(current.revision, id, gate, reviewText, integrationCommit) };
+  }
+
+  let task;
+  if (route === "task create") {
+    if (previous || state.archive?.[id]) throw new Error(`Task already exists: ${id}`);
+    if (Object.keys({ ...state.tasks, ...state.archive }).some((key) => key.toLowerCase() === id.toLowerCase())) throw new Error("Task id collides case-insensitively");
+    const title = required(option("--title"), "--title");
+    const featureId = option("--feature");
+    if (featureId) {
+      const manifest = await client.featureGet(featureId);
+      if (manifest?.feature && !manifest.feature.tasks.some((member) => member.id === id)) throw new Error(`Task ${id} is not declared in feature ${featureId}; run feature link first`);
+    }
+    const recordedAt = now();
+    task = { id, title, ...(featureId ? { featureId } : {}), type: option("--type") ?? "infra", phase: "clarify", gate: "G0_confirm", status: "active",
+      language: option("--language") === "en" ? "en" : "vi", risk: option("--risk") ?? "normal",
+      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 };
+  } else {
+    if (!previous) throw new Error(`Unknown task: ${id}`);
+    task = structuredClone(previous);
+    if (task.status === "blocked_on_user" && !["evidence add", "task status", "task handoff", "task close"].includes(route)) throw new Error("Task is frozen at a human gate");
+    if (route === "task status") {
+      const status = required(option("--status"), "--status");
+      if (!statuses.has(status)) throw new Error("Invalid task status");
+      if (task.status === "blocked_on_user" && status !== "blocked_on_user") {
+        if (option("--mode") !== "audited") throw new Error("Cancelling a human-gate wait requires --mode audited");
+        const reason = required(option("--reason"), "--reason"); const source = required(option("--source"), "--source");
+        task.evidence.push({ kind: "diagnostic", result: "pass", source, detail: `Cancelled gate wait at ${task.gate}: ${reason}`, recordedAt: now() });
+      }
+      if (task.status === "active" && status === "paused") {
+        if (option("--mode") !== "audited") throw new Error("Pausing active work requires --mode audited");
+        const reason = required(option("--reason"), "--reason"); const source = required(option("--source"), "--source");
+        task.evidence.push({ kind: "diagnostic", result: "pass", source, detail: `Paused while active: ${reason}`, recordedAt: now() });
+      }
+      if (status === "blocked_on_user") {
+        const diagnostics = checkGate(root, state, id, task.gate).filter((item) => item.level === "ERROR");
+        if (diagnostics.length) throw new Error(`Gate is not ready: ${diagnostics.map((item) => item.code).join(", ")}`);
+      }
+      task.status = status;
+    } else if (route === "task handoff") {
+      const clone = structuredClone(state); clone.tasks[id] = task;
+      task = handoffTask(clone, id, required(option("--kind"), "--kind"), required(option("--reason"), "--reason"), required(option("--source"), "--source"));
+    } else if (route === "task close") {
+      const clone = structuredClone(state); clone.tasks[id] = task;
+      task = closeTask(clone, id, required(option("--reason"), "--reason"), required(option("--source"), "--source"));
+    } else if (route === "task reopen") {
+      const clone = structuredClone(state); clone.tasks[id] = task;
+      task = reopenTask(clone, id, required(option("--to"), "--to"), required(option("--reason"), "--reason"), required(option("--source"), "--source"));
+    } else if (route === "task item") {
+      const status = required(option("--status"), "--status");
+      if (!itemStatuses.has(status)) throw new Error("Invalid item status");
+      const item = task.tasks.find((entry) => entry.id === extra);
+      const split = (name) => option(name)?.split(",").map((entry) => entry.trim()).filter(Boolean);
+      if (item) { item.status = status; if (options.has("--label")) item.label = option("--label"); if (options.has("--depends-on")) item.dependsOn = split("--depends-on"); if (options.has("--owns")) item.ownedPaths = split("--owns"); }
+      else task.tasks.push({ id: extra, label: option("--label") ?? extra, status, ...(split("--depends-on") ? { dependsOn: split("--depends-on") } : {}), ...(split("--owns") ? { ownedPaths: split("--owns") } : {}) });
+      readyTaskItems(task);
+    } else if (route === "task transition") {
+      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" && task.featureId) {
+        const manifest = await client.featureGet(task.featureId);
+        const member = manifest?.feature?.tasks?.find((entry) => entry.id === id);
+        if (!member) throw new Error(`Task ${id} is missing from feature ${task.featureId}`);
+        const waitingOn = member.dependsOn.filter((dependency) => (state.tasks[dependency] ?? state.archive?.[dependency])?.status !== "done");
+        if (waitingOn.length) throw new Error(`Feature prerequisites incomplete for ${id}: ${waitingOn.join(", ")}`);
+      }
+      const clone = structuredClone(state); clone.tasks[id] = task;
+      transitionTask(clone, id, target);
+      task = clone.tasks[id];
+      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");
+      if (!["unresolved", "approved", "changed", "dropped"].includes(status)) throw new Error("Invalid decision status");
+      const decision = task.decisions.find((entry) => entry.id === extra);
+      if (decision) { decision.status = status; if (options.has("--label")) decision.label = option("--label"); if (options.has("--resolution")) decision.resolution = option("--resolution"); }
+      else task.decisions.push({ id: extra, label: option("--label") ?? extra, status, resolution: option("--resolution") });
+    } else if (route === "evidence add") {
+      const kind = required(option("--kind"), "--kind"); const result = required(option("--result"), "--result");
+      if (!evidenceKinds.has(kind) || !results.has(result)) throw new Error("Invalid evidence kind or result");
+      const area = option("--area");
+      if (area && !task.areas.includes(area)) throw new Error("Evidence area must belong to task");
+      if (["test", "lint"].includes(kind) && task.areas.length > 1 && !area) throw new Error("Multi-area verification requires --area");
+      task.evidence.push({ kind, gate: option("--gate"), area, result, source: option("--source") ?? "fleet lead", detail: option("--detail"), recordedAt: now() });
+    } else if (route === "lesson record") {
+      recordLesson(task, { id: extra, areas: (option("--area") ?? task.areas.join(",")).split(",").map((entry) => entry.trim()).filter(Boolean), summary: option("--summary"), prevention: option("--prevention"), example: option("--example"), promotion: option("--promotion") ?? "not promoted", source: required(option("--source"), "--source") });
+    } else if (route === "lesson none") {
+      recordNoLessons(task, required(option("--reason"), "--reason"), required(option("--source"), "--source"));
+    }
+    task.updatedAt = now();
+  }
+  const candidate = structuredClone(state); candidate.tasks[id] = task; validateState(candidate);
+  const saved = await client.apply(current.revision, id, task);
+  const canonical = saved?.state?.tasks?.[id];
+  if (!Number.isSafeInteger(saved?.revision) || !canonical) throw new Error("Remote coordination did not confirm the mutation");
+  return { ok: true, result: { task: canonical, revision: saved.revision }, nextAction: remoteAction(saved.nextActions?.[id] ?? nextAction(canonical, root)) };
+};
+
+export const runRemoteReview = async (argv, client, git = {}) => {
+  const { positionals: args, options, option } = parse(argv);
+  const [group, action, taskId] = args;
+  if (group !== "gate" || !["inbox", "approve"].includes(action)) throw new Error("Reviewer commands are gate inbox and gate approve");
+  if (action === "inbox") {
+    if (taskId || options.size) throw new Error("gate inbox takes no arguments");
+    return { ok: true, result: await client.inbox() };
+  }
+  required(taskId, "task id");
+  if (args.length !== 3 || [...options.keys()].some((key) => !["--snapshot", "--source"].includes(key))) throw new Error("Usage: gate approve <task-id> --snapshot <id> --source <explicit user message>");
+  const snapshotId = required(option("--snapshot"), "--snapshot");
+  const source = required(option("--source"), "--source");
+  const current = await client.get();
+  if (!Number.isSafeInteger(current?.revision) || !current.state?.tasks?.[taskId]) throw new Error("Task is absent from canonical remote state");
+  const inbox = await client.inbox();
+  if (!Array.isArray(inbox)) throw new Error("Remote gate inbox returned invalid data");
+  const snapshot = inbox.find((entry) => entry.id === snapshotId && entry.taskId === taskId);
+  if (!snapshot || current.state.tasks[taskId].gate !== snapshot.gate || current.state.tasks[taskId].status !== "blocked_on_user") throw new Error("Gate snapshot is stale or does not match the waiting task");
+  let integrationCommit;
+  if (snapshot.gate === "G2_codereview") {
+    if (!/^[a-f0-9]{40}$/i.test(snapshot.integrationCommit ?? "")) throw new Error("G2 snapshot has no valid integration commit");
+    integrationCommit = await (git.readRemoteRef ?? readIntegrationCommit)({ projectRoot: git.projectRoot, integrationBranch: git.integrationBranch, gitRemote: git.gitRemote });
+    if (integrationCommit !== snapshot.integrationCommit.toLowerCase()) throw new Error("Integration branch remote ref changed since G2 snapshot; review a fresh snapshot");
+  }
+  const saved = await client.approve(current.revision, taskId, snapshotId, source, integrationCommit);
+  const task = saved?.state?.tasks?.[taskId];
+  if (!Number.isSafeInteger(saved?.revision) || !task) throw new Error("Remote coordination did not confirm gate approval");
+  return { ok: true, result: { task, revision: saved.revision }, nextAction: remoteAction(saved.nextActions?.[taskId]) };
+};
+
+export const runRemoteFeature = async (argv, client) => {
+  const { positionals: args, options, option } = parse(argv);
+  const [group, action, featureId, taskId] = args;
+  if (group !== "feature" || !["create", "show", "ready", "link"].includes(action)) throw new Error("Unsupported remote feature command");
+  required(featureId, "feature id");
+  if (taskId && action !== "link") throw new Error(`Unexpected task id for feature ${action}`);
+  if (action === "link") required(taskId, "task id");
+  const allowed = { create: ["--branch", "--tasks"], show: [], ready: [], link: ["--depends-on"] }[action];
+  for (const key of options.keys()) if (!allowed.includes(key)) throw new Error(`Unsupported option: ${key}`);
+  const current = await client.featureGet(featureId);
+  if (!Number.isSafeInteger(current?.revision)) throw new Error("Remote feature service returned invalid revision");
+  const feature = current.feature;
+  if (action === "show") return { ok: true, result: feature };
+  if (action === "ready") {
+    if (!feature) throw new Error(`Unknown feature: ${featureId}`);
+    const ready = await client.featureReady(featureId);
+    if (!Number.isSafeInteger(ready?.stateRevision) || !Array.isArray(ready.items)) throw new Error("Remote feature readiness unavailable");
+    return { ok: true, result: { feature, ...ready } };
+  }
+  let next;
+  if (action === "create") {
+    if (feature) throw new Error(`Feature already exists: ${featureId}`);
+    const tasks = required(option("--tasks"), "--tasks").split(",").map((entry) => entry.trim()).filter(Boolean);
+    if (!tasks.length || new Set(tasks).size !== tasks.length) throw new Error("Feature requires unique initial tasks");
+    const canonical = await client.get();
+    if (!canonical?.state?.tasks) throw new Error("Remote lifecycle state unavailable");
+    for (const id of tasks) if (canonical.state.tasks[id]?.featureId !== featureId) throw new Error(`Create canonical task ${id} with --feature ${featureId} before feature create`);
+    next = { schemaVersion: 1, id: featureId, integrationBranch: required(option("--branch"), "--branch"), tasks: tasks.map((id) => ({ id, dependsOn: [] })) };
+  } else {
+    if (!feature) throw new Error(`Unknown feature: ${featureId}`);
+    const canonical = await client.get();
+    if (!canonical?.state?.tasks) throw new Error("Remote lifecycle state unavailable");
+    if (canonical.state.tasks[taskId] && canonical.state.tasks[taskId].featureId !== featureId) throw new Error(`Declare feature membership before task creation: ${taskId}`);
+    next = structuredClone(feature);
+    const dependsOn = (option("--depends-on") ?? "").split(",").map((entry) => entry.trim()).filter(Boolean);
+    const member = next.tasks.find((entry) => entry.id === taskId);
+    if (member) member.dependsOn = dependsOn;
+    else next.tasks.push({ id: taskId, dependsOn });
+  }
+  const saved = await client.featureApply(current.revision, next);
+  const canonical = saved?.fleet?.features?.[featureId];
+  if (!canonical) throw new Error("Remote feature service did not confirm manifest mutation");
+  return { ok: true, result: { feature: canonical, revision: saved.revision } };
+};
+
+export const runRemoteLease = async (argv, client) => {
+  const { positionals: args, options, option } = parse(argv);
+  const [group, action, taskId] = args;
+  if (group !== "run" || !["claim", "release"].includes(action) || args.length !== 3) throw new Error("Usage: run claim <task-id> [--lease-ms <ms>] | run release <task-id> --epoch <n>");
+  required(taskId, "task id");
+  const allowed = action === "claim" ? ["--lease-ms"] : ["--epoch"];
+  for (const key of options.keys()) if (!allowed.includes(key)) throw new Error(`Unsupported option: ${key}`);
+  const current = await client.fleetGet();
+  if (!Number.isSafeInteger(current?.revision) || !current.fleet?.leads) throw new Error("Remote fleet state unavailable");
+  if (action === "claim") {
+    const leaseMs = option("--lease-ms") === undefined ? 300000 : Number(option("--lease-ms"));
+    if (!Number.isSafeInteger(leaseMs) || leaseMs < 60000 || leaseMs > 3600000) throw new Error("--lease-ms must be 60000..3600000");
+    const saved = await client.runClaim(current.revision, taskId, leaseMs);
+    const lease = saved?.fleet?.leads?.[taskId];
+    if (!Number.isSafeInteger(lease?.epoch) || !lease.expiresAt) throw new Error("Remote fleet service did not confirm lead claim");
+    return { ok: true, result: { taskId, epoch: lease.epoch, expiresAt: lease.expiresAt, fleetRevision: saved.revision } };
+  }
+  const epoch = Number(required(option("--epoch"), "--epoch"));
+  if (!Number.isSafeInteger(epoch) || epoch < 1) throw new Error("--epoch must be a positive integer");
+  const saved = await client.runRelease(current.revision, taskId, epoch);
+  if (!Number.isSafeInteger(saved?.revision)) throw new Error("Remote fleet service did not confirm lead release");
+  return { ok: true, result: { taskId, epoch, fleetRevision: saved.revision, released: true } };
+};
+
+const isEntry = process.argv[1] && new URL(`file://${process.argv[1]}`).href === import.meta.url;
+if (isEntry) {
+  try {
+    const argv = process.argv.slice(2);
+    const isReview = argv[0] === "gate" && ["inbox", "approve"].includes(argv[1]);
+    const config = isReview ? reviewerConfig() : ["feature", "run"].includes(argv[0]) ? featureConfig() : remoteConfig();
+    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; }
+}

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

@@ -1,6 +1,8 @@
 import { acquireStateLock, failEntry, loadState, loadTask, parseArguments, renderViews, rootOption, validateArguments } from "./lib/runtime.mjs";
+import { requireLocalAuthority } from "./lib/authority.mjs";
 
 try {
+  requireLocalAuthority();
   const raw = process.argv.slice(2);
   const parsed = parseArguments(raw, { valueOptions: ["--root"], booleanOptions: ["--all"] });
   validateArguments(parsed, { minPositionals: 0, maxPositionals: 1, booleanOptions: ["--all"], usage: "Usage: render.mjs <task-id> [--root <path>] | --all [--root <path>]" });

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

@@ -1,9 +1,14 @@
 #!/usr/bin/env node
 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 { 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"];
+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 parsed = parseArguments(raw, { valueOptions, booleanOptions: ["--include-archive"] });
 const args = parsed.positionals;
 const [group, action, rawId] = args;
@@ -14,7 +19,8 @@ const schemas = {
   "task list": { minPositionals: 2, valueOptions: ["--status", "--limit", "--cursor"], booleanOptions: ["--include-archive"] },
   "task find": { minPositionals: 2, valueOptions: ["--query", "--status", "--limit", "--cursor"], booleanOptions: ["--include-archive"], requiredOptions: ["--query"] },
   "task next": { minPositionals: 3 },
-  "task create": { minPositionals: 3, valueOptions: ["--title", "--type", "--language", "--risk", "--area", "--switch-from"], requiredOptions: ["--title"] },
+  "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 handoff": { minPositionals: 3, valueOptions: ["--kind", "--reason", "--source"], requiredOptions: ["--kind", "--reason", "--source"] },
@@ -22,7 +28,11 @@ const schemas = {
   "task supersede": { minPositionals: 3, valueOptions: ["--successor", "--reason", "--source"], requiredOptions: ["--successor", "--reason", "--source"] },
   "task reopen": { minPositionals: 3, valueOptions: ["--to", "--reason", "--source"], requiredOptions: ["--to", "--reason", "--source"] },
   "task status": { minPositionals: 3, valueOptions: ["--status", "--mode", "--reason", "--source"], requiredOptions: ["--status"] },
-  "task item": { minPositionals: 4, valueOptions: ["--status", "--label"], requiredOptions: ["--status"] },
+  "task item": { minPositionals: 4, valueOptions: ["--status", "--label", "--depends-on", "--owns"], requiredOptions: ["--status"] },
+  "feature create": { minPositionals: 3, valueOptions: ["--branch"], requiredOptions: ["--branch"] },
+  "feature show": { minPositionals: 3 },
+  "feature ready": { minPositionals: 3 },
+  "feature link": { minPositionals: 4, valueOptions: ["--depends-on"] },
   "decision set": { minPositionals: 4, valueOptions: ["--status", "--label", "--resolution"], requiredOptions: ["--status"] },
   "evidence add": { minPositionals: 3, valueOptions: ["--kind", "--result", "--gate", "--area", "--source", "--detail"], requiredOptions: ["--kind", "--result"] },
   "lesson record": { minPositionals: 4, valueOptions: ["--area", "--summary", "--prevention", "--example", "--promotion", "--source"] },
@@ -34,7 +44,7 @@ const schemas = {
   "memory retire": { minPositionals: 3, valueOptions: ["--reason", "--approved-by"], requiredOptions: ["--reason", "--approved-by"] },
   "gate approve": { minPositionals: 3, valueOptions: ["--gate", "--source"], requiredOptions: ["--gate", "--source"] }
 };
-const usage = "Usage: state.mjs state migrate | task create|show|list|find|next|status|item|transition|archive|handoff|close|supersede|reopen | decision set | evidence add | lesson record|none|search|rebuild | memory list|promote|retire | gate approve";
+const usage = "Usage: state.mjs state migrate | task create|show|list|find|next|ready|status|item|transition|archive|handoff|close|supersede|reopen | feature create|show|ready|link | decision set | evidence add | lesson record|none|search|rebuild | memory list|promote|retire | gate approve";
 const schema = schemas[`${group ?? ""} ${action ?? ""}`];
 if (!schema) throw new Error(usage);
 validateArguments(parsed, { ...schema, maxPositionals: schema.maxPositionals ?? schema.minPositionals, usage: schema.usage ?? usage });
@@ -69,6 +79,15 @@ const persist = (tasks, rebuildLessons = false) => {
 };
 const emit = (result, task) => console.log(JSON.stringify({ ok: true, ...(result === undefined ? {} : { result }), ...(warnings.length ? { warnings } : {}), ...(task ? { nextAction: nextAction(task, root) } : {}) }, null, 2));
 const respond = (task, result = {}) => emit({ task, ...result }, task);
+const requireFeaturePrerequisites = (task) => {
+  if (!task) throw new Error("Unknown active task");
+  if (!task.featureId) return;
+  const feature = loadFeature(root, task.featureId, state);
+  const member = feature?.tasks.find((entry) => entry.id === task.id);
+  if (!member) throw new Error(`Task is missing from feature manifest: ${task.id}`);
+  const waitingOn = member.dependsOn.filter((dependency) => (state.tasks[dependency] ?? state.archive?.[dependency])?.status !== "done");
+  if (waitingOn.length) throw new Error(`Feature prerequisites incomplete for ${task.id}: ${waitingOn.join(", ")}`);
+};
 
 if (group === "state" && action === "migrate") {
   emit(migrateState(root, state));
@@ -85,6 +104,31 @@ if (group === "state" && action === "migrate") {
   const task = loadTask(root, id, state);
   if (!task) throw new Error(`Unknown task: ${id}`);
   emit({ id: task.id, phase: task.phase, gate: task.gate, status: task.status }, task);
+} else if (group === "task" && action === "ready") {
+  const task = loadTask(root, id, state);
+  if (!task) throw new Error(`Unknown task: ${id}`);
+  emit({ id, ...readyTaskItems(task) }, task);
+} else if (group === "feature" && action === "create") {
+  if (loadFeature(root, id, state)) throw new Error(`Feature already exists: ${id}`);
+  emit(saveFeature(root, { schemaVersion: 1, id, integrationBranch: option(parsed, "--branch"), tasks: [] }, state));
+} else if (group === "feature" && action === "show") {
+  const feature = loadFeature(root, id, state);
+  if (!feature) throw new Error(`Unknown feature: ${id}`);
+  emit(feature);
+} else if (group === "feature" && action === "ready") {
+  const feature = loadFeature(root, id, state);
+  if (!feature) throw new Error(`Unknown feature: ${id}`);
+  emit(readyFeatureTasks(feature, state));
+} else if (group === "feature" && action === "link") {
+  const taskId = args[3]; const feature = loadFeature(root, id, state); const task = state.tasks[taskId];
+  if (!feature || !task) throw new Error(`Unknown feature or active task: ${id}/${taskId}`);
+  if (task.featureId && task.featureId !== id) throw new Error(`Task belongs to another feature: ${taskId}`);
+  if (listFeatures(root, state).some((other) => other.id !== id && other.tasks.some((entry) => entry.id === taskId))) throw new Error(`Task belongs to another feature: ${taskId}`);
+  const dependsOn = (option(parsed, "--depends-on") ?? "").split(",").map((entry) => entry.trim()).filter(Boolean);
+  const entry = feature.tasks.find((item) => item.id === taskId);
+  if (entry) entry.dependsOn = dependsOn; else feature.tasks.push({ id: taskId, dependsOn });
+  saveFeature(root, feature, state);
+  task.featureId = id; task.updatedAt = now(); persist([task]); respond(task, { feature });
 } else if (group === "task" && action === "create") {
   const title = option(parsed, "--title");
   if (!id || !title) throw new Error("task create requires <task-id> and --title");
@@ -97,11 +141,14 @@ if (group === "state" && action === "migrate") {
   const unknownAcknowledgement = acknowledgedTokens.filter((ack) => !actionableByLowercase.has(ack.toLowerCase()));
   if (unknownAcknowledgement.length) throw new Error(`--switch-from must name only actionable task(s); not actionable: ${unknownAcknowledgement.join(", ")}`);
   const acknowledged = [...new Set(acknowledgedTokens.map((ack) => actionableByLowercase.get(ack.toLowerCase())))];
-  const stranded = actionable.filter((existing) => !acknowledged.includes(existing));
+  const featureId = option(parsed, "--feature");
+  const feature = featureId ? loadFeature(root, featureId, state) : undefined;
+  if (featureId && !feature) throw new Error(`Unknown feature: ${featureId}`);
+  const stranded = actionable.filter((existing) => !acknowledged.includes(existing) && (!feature || state.tasks[existing].featureId !== featureId));
   if (stranded.length) throw new Error(`Task create is blocked while other work is actionable: ${stranded.join(", ")}. With explicit user direction to switch, rerun with --switch-from ${actionable.join(",")}; acknowledged tasks keep their state and remain the resume target`);
   const recordedAt = now();
   const task = state.tasks[id] = {
-    id, title, type: option(parsed, "--type") ?? "infra", phase: "clarify", gate: "G0_confirm", status: "active",
+    id, title, featureId, type: option(parsed, "--type") ?? "infra", phase: "clarify", gate: "G0_confirm", status: "active",
     language: option(parsed, "--language") === "en" ? "en" : "vi", risk: option(parsed, "--risk") ?? "normal",
     areas: (option(parsed, "--area") ?? "root").split(",").map((area) => area.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` },
@@ -112,17 +159,22 @@ if (group === "state" && action === "migrate") {
     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 });
     prior.updatedAt = recordedAt;
   }
+  if (feature) {
+    const dependsOn = (option(parsed, "--depends-on") ?? "").split(",").map((entry) => entry.trim()).filter(Boolean);
+    feature.tasks.push({ id, dependsOn });
+    saveFeature(root, feature, state);
+  }
   persist([task, ...acknowledgedTasks]); respond(task);
 } 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"); const task = transitionTask(state, id, target);
+  const from = state.tasks[id]?.phase; const target = option(parsed, "--to"); if (target === "done") requireFeaturePrerequisites(state.tasks[id]); const task = transitionTask(state, id, target);
   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");
-  const task = transitionTask(state, id, "done");
+  requireFeaturePrerequisites(state.tasks[id]); const task = transitionTask(state, id, "done");
   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") {
@@ -164,8 +216,11 @@ if (group === "state" && action === "migrate") {
   const itemId = args[3]; const task = state.tasks[id]; const status = option(parsed, "--status");
   if (!task || !itemId || !["todo", "in_progress", "done", "deferred"].includes(status)) throw new Error("task item requires active task id, item id, and valid --status");
   const item = task.tasks.find((entry) => entry.id === itemId);
-  if (item) { item.status = status; if (parsed.present.has("--label")) item.label = option(parsed, "--label"); }
-  else task.tasks.push({ id: itemId, label: option(parsed, "--label") ?? itemId, status });
+  const dependsOn = parsed.present.has("--depends-on") ? (option(parsed, "--depends-on") ?? "").split(",").map((entry) => entry.trim()).filter(Boolean) : undefined;
+  const ownedPaths = parsed.present.has("--owns") ? (option(parsed, "--owns") ?? "").split(",").map((entry) => entry.trim()).filter(Boolean) : undefined;
+  if (item) { item.status = status; if (parsed.present.has("--label")) item.label = option(parsed, "--label"); if (dependsOn) item.dependsOn = dependsOn; if (ownedPaths) item.ownedPaths = ownedPaths; }
+  else task.tasks.push({ id: itemId, label: option(parsed, "--label") ?? itemId, status, ...(dependsOn ? { dependsOn } : {}), ...(ownedPaths ? { ownedPaths } : {}) });
+  readyTaskItems(task);
   task.updatedAt = now(); persist([task]); respond(task);
 } else if (group === "decision" && action === "set") {
   const decisionId = args[3]; const task = state.tasks[id]; const status = option(parsed, "--status");
@@ -211,9 +266,10 @@ 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 outcome = approveAndAdvance(root, state, id, gate, source); persist([outcome.task]); emit({ task: outcome.task, idempotent: outcome.idempotent }, outcome.task);
 } else {
-  throw new Error("Usage: state.mjs state migrate | task create|show|list|find|next|status|item|transition|archive|handoff|close|supersede|reopen | decision set | evidence add | lesson record|none|search|rebuild | memory list|promote|retire | gate approve");
+  throw new Error(usage);
 }
 } finally {
   process.off("exit", releaseOnce);

package/dist/assets/.agents/aidlc/scripts/task-next.mjs

@@ -1,6 +1,8 @@
 import { failEntry, loadState, loadTask, nextAction, parseArguments, rootOption, validateArguments } from "./lib/runtime.mjs";
+import { requireLocalAuthority } from "./lib/authority.mjs";
 
 try {
+  requireLocalAuthority();
   const raw = process.argv.slice(2);
   const parsed = parseArguments(raw, { valueOptions: ["--root"], booleanOptions: ["--require-stop"] });
   validateArguments(parsed, { minPositionals: 1, booleanOptions: ["--require-stop"], usage: "Usage: task-next.mjs <task-id> [--root <path>] [--require-stop]" });

package/dist/assets/.agents/aidlc/templates/model-contract.md

@@ -28,7 +28,7 @@ Use CRITICS during clarify or plan only when risk is elevated, requirements are
 
 ## CRITICS — adversarial review
 
-Before recording passing review evidence for G2, report these sections against the approved decisions, cited anchors, and task diff:
+Before recording passing review evidence for Review implementation, report these sections against the approved decisions, cited anchors, and task diff:
 
 1. **Criteria** — acceptance criteria, invariants, and exact spec anchors checked.
 2. **Risks** — regression, safety, compatibility, and unverified assumptions.
@@ -36,6 +36,6 @@ Before recording passing review evidence for G2, report these sections against t
 4. **Tests / evidence** — commands or inspections run, results, and residual gaps.
 5. **Improvements** — required fixes or explicitly deferred follow-ups, each tied to an issue.
 6. **Conclusion** — `pass`, `needs changes`, or `escalate`; a pass requires no unresolved critical/high issue.
-7. **Stop / escalate** — reopen G1 for a structural/spec conflict; otherwise defer to the human gate when authority is needed.
+7. **Stop / escalate** — reopen the Approve plan step for a structural/spec conflict; otherwise defer to the human gate when authority is needed.
 
-CRITICS is a review record, not approval. Only the state machine, recorded evidence, and human G2 approval advance the task.
+CRITICS is a review record, not approval. Only the state machine, recorded evidence, and human Review implementation approval advance the task.

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

@@ -2,8 +2,8 @@
 
 > Review artifact derived from `.agents/data/state/aidlc-state.json`. Resolve decisions and update progress with `node .agents/aidlc/scripts/state.mjs`, then run `node .agents/aidlc/scripts/render.mjs`.
 
-## 🧩 Decisions (Gate G1 — approve before build)
+## 🧩 Decisions (Approve plan — before implementation)
 - <generated decision state>
 
-## 🧩 Tasks (Gate G2 — build execution)
+## 🧩 Tasks (Review implementation — work items)
 - <generated task state>

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

@@ -1,9 +1,9 @@
 ---
 name: aidlc-build
-description: "AI-DLC phase 3 (Gate G2): after explicit G1 plan approval, implement the canonical work items, run the narrowest tests/lint, then run code-review. Triggers when the AI-DLC Orchestrator routes an approved post-G1 task to build. Ends at G2 for explicit user code review."
+description: "AI-DLC phase 3 (Review implementation): after explicit plan approval, implement the canonical work items, run the narrowest tests/lint, then run code-review. Triggers when the AI-DLC Orchestrator routes a task after plan approval to build. Ends at Review implementation for explicit user code review."
 ---
 
-# AI-DLC · Build (Gate G2) — adapter
+# AI-DLC · Build (Review implementation) — adapter
 
 This skill is a thin Claude Code adapter. The canonical playbook is tool-agnostic and lives in the repo:
 

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

@@ -1,9 +1,9 @@
 ---
 name: aidlc-clarify
-description: "AI-DLC phase 1 (Gate G0): turn a raw request into a confirmed intent brief — restate the problem, map affected submodules + specs, list assumptions and open questions, fix scope. Cheap: reads only the AI-DLC index, no deep code dive. Triggers: a NEW feature/bug/change request when the AI-DLC Orchestrator routes to clarify. Ends by STOPPING for user confirmation (G0)."
+description: "AI-DLC phase 1 (Confirm requirements): turn a raw request into a confirmed intent brief — restate the problem, map affected submodules + specs, list assumptions and open questions, fix scope. Cheap: reads only the AI-DLC index, no deep code dive. Triggers: a NEW feature/bug/change request when the AI-DLC Orchestrator routes to clarify. Ends by STOPPING for user confirmation (Confirm requirements)."
 ---
 
-# AI-DLC · Clarify (Gate G0) — adapter
+# AI-DLC · Clarify (Confirm requirements) — adapter
 
 This skill is a thin Claude Code adapter. The canonical playbook is tool-agnostic and lives in the repo:
 

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

@@ -1,9 +1,9 @@
 ---
 name: aidlc-plan
-description: "AI-DLC phase 2 (Gate G1): 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 confirmed post-G0 task to planning. Ends at the executable G1 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. 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 (Gate G1) — adapter
+# AI-DLC · Plan (Approve plan) — adapter
 
 This skill is a thin Claude Code adapter. The canonical playbook is tool-agnostic and lives in the repo:
 

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

@@ -1,6 +1,6 @@
 ---
 name: aidlc-wrap
-description: "AI-DLC phase 4 (post-G2): after the user approves the code, follow project delivery policy, capture lessons and residual risk, then close canonical task state."
+description: "AI-DLC phase 4 (after implementation approval): after the user approves the code, follow project delivery policy, capture lessons and residual risk, then close canonical task state."
 ---
 
 # AI-DLC · Wrap — adapter

package/dist/services/aidlc-coordination/.env.fleet.example

@@ -0,0 +1,11 @@
+# Copy to .env, set distinct random credentials, then run:
+# docker compose --profile fleet up -d fleet-coordination
+# Bind through a TLS reverse proxy before exposing this service to other machines.
+MCP_POSTGRES_PASSWORD=replace-with-a-strong-postgres-password
+# Existing local SQLite service in compose.yaml uses this only when started.
+MCP_STATE_AUTH_TOKEN=replace-with-a-distinct-local-service-token
+MCP_FLEET_LEAD_TOKEN=replace-with-a-distinct-lead-token-at-least-24-characters
+MCP_FLEET_REVIEWER_TOKEN=replace-with-a-distinct-reviewer-token-at-least-24-characters
+MCP_FLEET_WORKER_TOKENS={"worker1":"replace-with-a-distinct-worker-token-at-least-24-characters"}
+MCP_FLEET_BIND_ADDRESS=127.0.0.1
+MCP_FLEET_PORT=8788