@felixdotgo/aidlc-kit 0.0.1 → 0.1.0

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

@@ -0,0 +1,65 @@
+import { createHash } from 'node:crypto';
+import { copyFileSync, lstatSync, mkdirSync, readdirSync, realpathSync } from 'node:fs';
+import { dirname, isAbsolute, join, sep } from 'node:path';
+
+const excluded = (path) => path.split('/').includes('.git') || path === '.agents/data' || path.startsWith('.agents/data/');
+const scopePath = (path) => typeof path === 'string' && path && !isAbsolute(path) && !path.includes('\\') && !path.split('/').some((part) => !part || part === '.' || part === '..' || part === '.git' || part === '.agents');
+const within = (path, scopes) => scopes.some((scope) => path === scope || path.startsWith(`${scope}/`));
+const digest = (path) => createHash('sha256').update(readFile(path)).digest('hex');
+import { readFileSync as readFile } from 'node:fs';
+
+// Reject links and special files rather than allowing a worker to make a host
+// copy operation follow an external path or alias a file outside its scope.
+function inventory(root, skipExcluded) {
+  const files = new Map();
+  function visit(dir, prefix = '') {
+    for (const name of readdirSync(dir)) {
+      const path = prefix ? `${prefix}/${name}` : name;
+      if (excluded(path)) {
+        if (skipExcluded) continue;
+        throw new Error(`Worker created a protected path: ${path}`);
+      }
+      const full = join(dir, name), info = lstatSync(full);
+      if (info.isSymbolicLink() || (!info.isDirectory() && !info.isFile()) || (info.isFile() && info.nlink !== 1)) throw new Error(`Unsafe worker file: ${path}`);
+      if (info.isDirectory()) visit(full, path);
+      else files.set(path, { digest: digest(full), executable: Boolean(info.mode & 0o111) });
+    }
+  }
+  visit(root);
+  return files;
+}
+
+/** Create a source-only snapshot. The caller supplies a new empty directory. */
+export function createWorkerSnapshot(source, destination, trackedPaths) {
+  const src = realpathSync(source), dst = realpathSync(destination);
+  if (src === dst || dst.startsWith(`${src}${sep}`) || src.startsWith(`${dst}${sep}`)) throw new Error('Worker snapshot must be separate from source');
+  if (readdirSync(dst).length) throw new Error('Worker snapshot destination must be empty');
+  if (!Array.isArray(trackedPaths) || !trackedPaths.length || trackedPaths.some((path) => typeof path !== 'string' || !path || isAbsolute(path) || path.includes('\\') || path.split('/').some((part) => !part || part === '.' || part === '..') || excluded(path))) throw new Error('An explicit safe tracked-file manifest is required');
+  const sourceFiles = inventory(src, true), baseline = new Map();
+  for (const path of new Set(trackedPaths)) {
+    const entry = sourceFiles.get(path);
+    if (!entry) throw new Error(`Tracked worker source is missing or unsafe: ${path}`);
+    baseline.set(path, entry);
+  }
+  for (const [path] of baseline) {
+    const target = join(dst, path);
+    mkdirSync(dirname(target), { recursive: true });
+    copyFileSync(join(src, path), target);
+  }
+  return baseline;
+}
+
+/** Validate the complete stopped-worker snapshot before host integration. */
+export function inspectWorkerSnapshot(destination, baseline, scopes) {
+  if (!(baseline instanceof Map) || !Array.isArray(scopes) || !scopes.length || !scopes.every(scopePath)) throw new Error('Invalid snapshot baseline or scopes');
+  const root = realpathSync(destination), current = inventory(root, false);
+  const changed = [];
+  for (const path of new Set([...baseline.keys(), ...current.keys()])) {
+    const before = baseline.get(path), after = current.get(path);
+    if (!before || !after || before.digest !== after.digest || before.executable !== after.executable) {
+      if (!scopePath(path) || !within(path, scopes)) throw new Error(`Worker changed a path outside its scope: ${path}`);
+      changed.push(path);
+    }
+  }
+  return changed.sort();
+}

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

@@ -0,0 +1,112 @@
+import { randomUUID } from "node:crypto";
+
+const parseMessage = (body, contentType, id) => {
+  if (contentType.includes("text/event-stream")) {
+    for (const block of body.split(/\r?\n\r?\n/)) {
+      const data = block.split(/\r?\n/).filter((line) => line.startsWith("data:")).map((line) => line.slice(5).trim()).join("\n");
+      if (!data || data === "[DONE]") continue;
+      try { const message = JSON.parse(data); if (message.id === id) return message; } catch { /* keep reading */ }
+    }
+    return undefined;
+  }
+  const message = JSON.parse(body);
+  return Array.isArray(message) ? message.find((entry) => entry.id === id) : message;
+};
+
+export const remoteConfig = (env = process.env) => {
+  const url = env.AIDLC_FLEET_URL;
+  const workspace = env.AIDLC_FLEET_WORKSPACE;
+  const token = env.AIDLC_FLEET_TOKEN;
+  const projectRoot = env.AIDLC_FLEET_PROJECT_ROOT;
+  const leadEpoch = Number(env.AIDLC_FLEET_LEAD_EPOCH);
+  if (!url || !/^https?:\/\//.test(url) || !workspace || !token || !projectRoot?.startsWith("/") || !Number.isSafeInteger(leadEpoch) || leadEpoch < 1) {
+    throw new Error("Remote state requires AIDLC_FLEET_URL, WORKSPACE, TOKEN, absolute PROJECT_ROOT, and positive LEAD_EPOCH");
+  }
+  return { url, workspace, token, projectRoot, leadEpoch, leadOwnerToken: env.AIDLC_FLEET_LEAD_OWNER_TOKEN, integrationBranch: env.AIDLC_FLEET_INTEGRATION_BRANCH, gitRemote: env.AIDLC_FLEET_GIT_REMOTE ?? "origin" };
+};
+
+export const featureConfig = (env = process.env) => {
+  const url = env.AIDLC_FLEET_URL;
+  const workspace = env.AIDLC_FLEET_WORKSPACE;
+  const token = env.AIDLC_FLEET_TOKEN;
+  const projectRoot = env.AIDLC_FLEET_PROJECT_ROOT;
+  if (!url || !/^https?:\/\//.test(url) || !workspace || !token || !projectRoot?.startsWith("/")) {
+    throw new Error("Remote feature commands require AIDLC_FLEET_URL, WORKSPACE, TOKEN, and absolute PROJECT_ROOT");
+  }
+  return { url, workspace, token, projectRoot };
+};
+
+export const reviewerConfig = (env = process.env) => {
+  const url = env.AIDLC_FLEET_URL;
+  const workspace = env.AIDLC_FLEET_WORKSPACE;
+  const token = env.AIDLC_FLEET_REVIEWER_TOKEN;
+  const projectRoot = env.AIDLC_FLEET_PROJECT_ROOT;
+  if (!url || !/^https?:\/\//.test(url) || !workspace || !token || !projectRoot?.startsWith("/")) {
+    throw new Error("Remote review requires AIDLC_FLEET_URL, WORKSPACE, REVIEWER_TOKEN, and absolute PROJECT_ROOT");
+  }
+  return { url, workspace, token, projectRoot, integrationBranch: env.AIDLC_FLEET_INTEGRATION_BRANCH, gitRemote: env.AIDLC_FLEET_GIT_REMOTE ?? "origin" };
+};
+
+export const callRemoteTool = async (config, name, args = {}, fetchImpl = fetch) => {
+  const id = randomUUID();
+  let response;
+  try {
+    response = await fetchImpl(config.url, {
+      method: "POST",
+      headers: { Authorization: `Bearer ${config.token}`, Accept: "application/json, text/event-stream", "Content-Type": "application/json", "MCP-Protocol-Version": "2025-06-18" },
+      body: JSON.stringify({ jsonrpc: "2.0", id, method: "tools/call", params: { name, arguments: args } }),
+      signal: AbortSignal.timeout(20000)
+    });
+  } catch (error) { throw new Error(`Remote coordination unavailable: ${error.message}`); }
+  const body = await response.text();
+  if (!response.ok) throw new Error(`Remote coordination HTTP ${response.status}: ${body.slice(0, 300)}`);
+  let message;
+  try { message = parseMessage(body, response.headers.get("content-type") ?? "", id); }
+  catch { throw new Error("Remote coordination returned invalid JSON"); }
+  if (!message || message.id !== id) throw new Error("Remote coordination returned no matching result");
+  if (message.error) throw new Error(`Remote coordination RPC ${message.error.code}: ${message.error.message}`);
+  const tool = message.result;
+  if (!Array.isArray(tool?.content) || tool.content[0]?.type !== "text") throw new Error("Remote coordination returned no JSON text");
+  let value;
+  try { value = JSON.parse(tool.content[0].text); } catch { throw new Error("Remote coordination returned invalid tool JSON"); }
+  if (tool.isError) {
+    const error = new Error(value.message ?? value.code ?? "Remote coordination rejected operation");
+    error.code = value.code; error.current = value.current;
+    throw error;
+  }
+  return value;
+};
+
+export const createRemoteStateClient = (config, call = callRemoteTool) => ({
+  get: () => call(config, "state_get", { workspace: config.workspace }),
+  task: (taskId) => call(config, "task_get", { workspace: config.workspace, taskId, clientProjectRoot: config.projectRoot }),
+  apply: (expectedRevision, taskId, task) => call(config, "state_apply", {
+    workspace: config.workspace, expectedRevision, idempotencyKey: randomUUID(), clientProjectRoot: config.projectRoot,
+    leadEpoch: config.leadEpoch, ...(config.leadOwnerToken ? { leadOwnerToken: config.leadOwnerToken } : {}), command: { type: "upsertTask", taskId, task }
+  }),
+  snapshot: (expectedRevision, taskId, gate, reviewText, integrationCommit) => call(config, "gate_snapshot_put", {
+    workspace: config.workspace, expectedRevision, idempotencyKey: randomUUID(), taskId,
+    leadEpoch: config.leadEpoch, ...(config.leadOwnerToken ? { leadOwnerToken: config.leadOwnerToken } : {}), gate, reviewText, ...(integrationCommit ? { integrationCommit } : {})
+  }),
+  featureGet: (featureId) => call(config, "feature_get", { workspace: config.workspace, featureId }),
+  featureReady: (featureId) => call(config, "feature_ready", { workspace: config.workspace, featureId }),
+  featureApply: (expectedRevision, feature) => call(config, "feature_apply", {
+    workspace: config.workspace, expectedRevision, idempotencyKey: randomUUID(), feature
+  }),
+  fleetGet: () => call(config, "fleet_get", { workspace: config.workspace }),
+  runClaim: (expectedRevision, taskId, leaseMs) => call(config, "run_claim", {
+    workspace: config.workspace, expectedRevision, idempotencyKey: randomUUID(), taskId, leaseMs
+  }),
+  runRelease: (expectedRevision, taskId, epoch) => call(config, "run_release", {
+    workspace: config.workspace, expectedRevision, idempotencyKey: randomUUID(), taskId, epoch
+  })
+});
+
+export const createRemoteReviewerClient = (config, call = callRemoteTool) => ({
+  get: () => call(config, "state_get", { workspace: config.workspace }),
+  inbox: () => call(config, "gate_inbox_get", { workspace: config.workspace }),
+  approve: (expectedRevision, taskId, snapshotId, source, integrationCommit) => call(config, "gate_approve", {
+    workspace: config.workspace, expectedRevision, idempotencyKey: randomUUID(), taskId, snapshotId,
+    source, clientProjectRoot: config.projectRoot, ...(integrationCommit ? { integrationCommit } : {})
+  })
+});

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

@@ -61,7 +61,9 @@ const validateTask = (id, task) => {
   if (!task.title || !["feature", "bug", "refactor", "infra"].includes(task.type) || !statuses.includes(task.status) || (task.phase === "done") !== (task.status === "done")) throw new Error(`Invalid task fields: ${id}`);
   if (!["vi", "en"].includes(task.language) || !["low", "normal", "high", "regulated"].includes(task.risk) || !Array.isArray(task.areas) || !task.areas.length || task.areas.some((area) => !text(area))) throw new Error(`Invalid task language, risk, or areas: ${id}`);
   if (task.decisions.some((item) => !item.id || !item.label || !["unresolved", "approved", "changed", "dropped"].includes(item.status) || (item.status === "changed" && !item.resolution))) throw new Error(`Invalid decisions: ${id}`);
+  if (task.featureId !== undefined && !idPattern.test(task.featureId)) throw new Error(`Invalid feature id: ${id}`);
   if (task.tasks.some((item) => !item.id || !item.label || !["todo", "in_progress", "done", "deferred"].includes(item.status))) throw new Error(`Invalid execution tasks: ${id}`);
+  readyTaskItems(task);
   if (task.evidence.some((item) => !["approval", "spec", "test", "lint", "review", "diagnostic"].includes(item.kind) || !["pass", "fail", "skip"].includes(item.result) || !item.source || !iso(item.recordedAt) || (item.area !== undefined && !text(item.area)) || (item.gate !== undefined && !gates.includes(item.gate)) || (item.kind === "approval" && (!item.gate || item.gate === "none")))) throw new Error(`Invalid evidence: ${id}`);
   const lessonIds = new Set();
   for (const lesson of task.lessons ?? []) { validateLesson(id, lesson); if (lessonIds.has(lesson.id)) throw new Error(`Duplicate lesson id: ${id}/${lesson.id}`); lessonIds.add(lesson.id); }
@@ -276,6 +278,35 @@ export const transitionTask = (state, id, target) => {
   task.phase = target; task.gate = phaseGate(target); task.status = target === "done" ? "done" : "active"; delete task.legacyG2Wait; task.updatedAt = new Date().toISOString(); return task;
 };
 
+export const readyTaskItems = (task) => {
+  const byId = new Map(task.tasks.map((item) => [item.id, item]));
+  if (byId.size !== task.tasks.length) throw new Error(`Duplicate execution item: ${task.id}`);
+  const visiting = new Set(); const visited = new Set();
+  const visit = (id) => {
+    if (visiting.has(id)) throw new Error(`Cyclic execution dependency: ${task.id}/${id}`);
+    if (visited.has(id)) return;
+    visiting.add(id);
+    for (const dep of byId.get(id)?.dependsOn ?? []) {
+      if (dep === id || !byId.has(dep)) throw new Error(`Unknown execution dependency: ${task.id}/${id}/${dep}`);
+      visit(dep);
+    }
+    visiting.delete(id); visited.add(id);
+  };
+  for (const item of task.tasks) {
+    if (item.dependsOn !== undefined && (!Array.isArray(item.dependsOn) || new Set(item.dependsOn).size !== item.dependsOn.length || item.dependsOn.some((dep) => typeof dep !== "string" || !dep))) throw new Error(`Invalid execution dependencies: ${task.id}/${item.id}`);
+    if (item.ownedPaths !== undefined && (!Array.isArray(item.ownedPaths) || new Set(item.ownedPaths).size !== item.ownedPaths.length || item.ownedPaths.some((path) => typeof path !== "string" || !path || isAbsolute(path) || path === ".." || path.startsWith("../") || path.includes("\\") || path.split("/").includes("..")))) throw new Error(`Invalid owned paths: ${task.id}/${item.id}`);
+    visit(item.id);
+  }
+  const ready = []; const blocked = [];
+  for (const item of task.tasks) {
+    const waitingOn = (item.dependsOn ?? []).filter((dep) => byId.get(dep)?.status !== "done");
+    if (item.status === "done" && waitingOn.length) throw new Error(`Completed item has incomplete prerequisites: ${task.id}/${item.id}`);
+    if (item.status !== "todo" && item.status !== "in_progress") continue;
+    if (waitingOn.length) blocked.push({ id: item.id, waitingOn }); else ready.push(item.id);
+  }
+  return { ready, blocked };
+};
+
 export const nextAction = (task, root) => {
   const rootSuffix = root === undefined ? "" : ` --root ${JSON.stringify(resolve(root))}`;
   const script = (name) => root === undefined ? `node .agents/aidlc/scripts/${name}` : `node ${JSON.stringify(join(resolve(root), ".agents/aidlc/scripts", name))}`;
@@ -288,16 +319,20 @@ export const nextAction = (task, root) => {
   if (task.status === "blocked_on_user" && task.gate === "G1_review" && task.decisions.some((decision) => decision.status === "unresolved")) return { classification: "run_phase", phase: task.phase, gate: task.gate, command: `${contextCommand} ${task.id} --phase plan${rootSuffix}`, reason: "Invalid premature G1 wait; resolve every decision before presenting G1" };
   if (task.status === "blocked_on_user" && task.gate === "G2_codereview" && (task.tasks.some((item) => !["done", "deferred"].includes(item.status)) || !hasVerification(task) || !hasReview(task))) {
     const open = task.tasks.filter((item) => item.status === "in_progress" || item.status === "todo");
-    const item = open.find((entry) => entry.status === "in_progress") ?? open[0];
+    const ready = new Set(readyTaskItems(task).ready);
+    const item = open.find((entry) => entry.status === "in_progress" && ready.has(entry.id)) ?? open.find((entry) => ready.has(entry.id));
     if (item) return { classification: "run_phase", phase: task.phase, gate: task.gate, itemId: item.id, remainingItems: open.length, command: `${contextCommand} ${task.id} --phase build --item ${item.id}${rootSuffix}`, reason: `Invalid premature G2 wait; continue build item ${item.id}` };
+    if (open.length) return { classification: "blocked", phase: task.phase, gate: task.gate, reason: `No dependency-ready build item: ${readyTaskItems(task).blocked.map((entry) => `${entry.id} waits for ${entry.waitingOn.join(",")}`).join("; ")}` };
     return { classification: "run_phase", phase: task.phase, gate: task.gate, remainingItems: 0, command: `${contextCommand} ${task.id} --phase build${rootSuffix}`, reason: "Invalid premature G2 wait; continue verification and adversarial review before presenting G2" };
   }
   if (task.status === "blocked_on_user" && task.gate === "none") return { classification: "run_phase", phase: task.phase, gate: task.gate, command: `${stateCommand} task status ${task.id} --status active${rootSuffix}`, reason: "Recover invalid wait at a gateless wrap phase before continuing wrap" };
   if (task.status === "blocked_on_user") return { classification: "await_user", phase: task.phase, gate: task.gate, command: `${stateCommand} gate approve ${task.id} --gate ${task.gate} --source <explicit-user-approval>${rootSuffix}`, reason: `Explicit human approval is required at ${task.gate}` };
   if (task.phase === "build") {
     const open = task.tasks.filter((item) => item.status === "in_progress" || item.status === "todo");
-    const item = open.find((entry) => entry.status === "in_progress") ?? open[0];
+    const ready = new Set(readyTaskItems(task).ready);
+    const item = open.find((entry) => entry.status === "in_progress" && ready.has(entry.id)) ?? open.find((entry) => ready.has(entry.id));
     if (item) return { classification: "run_phase", phase: task.phase, gate: task.gate, itemId: item.id, remainingItems: open.length, command: `${contextCommand} ${task.id} --phase build --item ${item.id}${rootSuffix}`, reason: `Continue build item ${item.id}; ${open.length} actionable item(s) remain before verification, review, and G2` };
+    if (open.length) return { classification: "blocked", phase: task.phase, gate: task.gate, reason: `No dependency-ready build item: ${readyTaskItems(task).blocked.map((entry) => `${entry.id} waits for ${entry.waitingOn.join(",")}`).join("; ")}` };
     return { classification: "run_phase", phase: task.phase, gate: task.gate, remainingItems: 0, command: `${contextCommand} ${task.id} --phase build${rootSuffix}`, reason: "All build items are terminal; continue verification, adversarial review, and G2 preparation" };
   }
   return { classification: "run_phase", phase: task.phase, gate: task.gate, command: `${contextCommand} ${task.id} --phase ${task.phase}${rootSuffix}`, reason: `Continue ${task.phase} until the next human gate, real blocker, or completion` };
@@ -322,7 +357,7 @@ export const searchLessons = (root, state, query, areas = [], limit = 5) => { co
 
 export const listTaskSummaries = (state, options = {}) => { const active = Object.values(state.tasks).map((task) => ({ id: task.id, title: task.title, phase: task.phase, gate: task.gate, status: task.status, risk: task.risk, areas: task.areas, updatedAt: task.updatedAt, source: "active" })); const archived = options.includeArchive ? Object.values(state.archive ?? {}).map((task) => ({ id: task.id, title: task.title, phase: task.phase, gate: task.gate, status: task.status, risk: task.risk, areas: task.areas, updatedAt: task.updatedAt, source: "archive" })) : []; const queryTokens = tokens(options.query ?? ""); const statusSet = new Set(options.statuses ?? []); const filtered = [...active, ...archived].filter((item) => (!statusSet.size || statusSet.has(item.status)) && (!queryTokens.length || queryTokens.every((token) => tokens(`${item.id} ${item.title} ${item.areas.join(" ")}`).includes(token)))).sort((a, b) => b.updatedAt.localeCompare(a.updatedAt) || a.id.localeCompare(b.id)); const cursor = Math.max(0, options.cursor ?? 0); const limit = Math.max(1, Math.min(options.limit ?? 20, 100)); const items = filtered.slice(cursor, cursor + limit); return { items, nextCursor: cursor + items.length < filtered.length ? String(cursor + items.length) : null, total: filtered.length }; };
 
-export const renderWorkplan = (task) => { const decisions = task.decisions.length ? task.decisions.map((item) => `- [${item.status === "approved" ? "x" : " "}] ${item.id} — ${item.label}${item.resolution ? ` — ${item.resolution}` : ""}`).join("\n") : "- None"; const tasks = task.tasks.length ? task.tasks.map((item) => `- [${item.status === "done" ? "x" : item.status === "in_progress" ? "~" : " "}] ${item.id} — ${item.label}`).join("\n") : "- None"; const lifecycle = [`- Status: \`${task.status}\``, task.handoff ? `- Handoff: \`${task.handoff.kind}\` — ${task.handoff.reason}` : "", task.closure ? `- Closure: ${task.closure.reason}` : "", task.predecessorTaskId ? `- Predecessor: \`${task.predecessorTaskId}\`` : "", task.successorTaskId ? `- Successor: \`${task.successorTaskId}\`` : "", task.lessonDisposition ? `- Lessons: \`${task.lessonDisposition.status}\`` : ""].filter(Boolean).join("\n"); return `# Workplan — ${task.title} (\`${task.id}\`)\n\n> Generated from canonical JSON state.\n\n## Lifecycle\n${lifecycle}\n\n## 🧩 Decisions (Gate G1 — approve before build)\n${decisions}\n\n## 🧩 Tasks (Gate G2 — build execution)\n${tasks}\n`; };
+export const renderWorkplan = (task) => { const decisions = task.decisions.length ? task.decisions.map((item) => `- [${item.status === "approved" ? "x" : " "}] ${item.id} — ${item.label}${item.resolution ? ` — ${item.resolution}` : ""}`).join("\n") : "- None"; const tasks = task.tasks.length ? task.tasks.map((item) => `- [${item.status === "done" ? "x" : item.status === "in_progress" ? "~" : " "}] ${item.id} — ${item.label}`).join("\n") : "- None"; const lifecycle = [`- Status: \`${task.status}\``, task.handoff ? `- Handoff: \`${task.handoff.kind}\` — ${task.handoff.reason}` : "", task.closure ? `- Closure: ${task.closure.reason}` : "", task.predecessorTaskId ? `- Predecessor: \`${task.predecessorTaskId}\`` : "", task.successorTaskId ? `- Successor: \`${task.successorTaskId}\`` : "", task.lessonDisposition ? `- Lessons: \`${task.lessonDisposition.status}\`` : ""].filter(Boolean).join("\n"); return `# Workplan — ${task.title} (\`${task.id}\`)\n\n> Generated from canonical JSON state.\n\n## Lifecycle\n${lifecycle}\n\n## 🧩 Decisions (Approve plan — before implementation)\n${decisions}\n\n## 🧩 Tasks (Review implementation — work items)\n${tasks}\n`; };
 export const renderViews = (root, state = loadState(root), selected = Object.values(state.tasks)) => { for (const task of selected) { if (!task.artifacts.workplan) continue; assertNoSymlinkPath(root, task.artifacts.workplan); writeAtomic(join(resolve(root), task.artifacts.workplan), renderWorkplan(task)); } };
 
 const safeArtifactTarget = (root, path) => { assertNoSymlinkPath(root, path); return join(resolve(root), path); };
@@ -335,7 +370,7 @@ export const formatDiagnostics = (diagnostics) => diagnostics.map((item) => `${i
 
 const oneLine = (value) => value.replace(/[\r\n\t]+/g, " ").replace(/\s+/g, " ").replace(/ACTION\s+REQUIRED/gi, "ACTION-REQUIRED").trim();
 const markdownText = (value) => oneLine(value).replace(/([\\`*_{}\[\]()<>#+.!|>~])/g, "\\$1");
-const gateMeta = { G0_confirm: { icon: "🟢", title: "GATE G0 · CONFIRM INTENT", action: "Reply `ok` to approve intent, or state changes." }, G1_review: { icon: "🔵", title: "GATE G1 · REVIEW PLAN", action: "Reply `approve` to start build, or state decision changes." }, G2_codereview: { icon: "🟣", title: "GATE G2 · REVIEW CODE", action: "Approve to wrap, or point out what to fix." } };
+const gateMeta = { G0_confirm: { icon: "🟢", title: "Review step · Confirm requirements", action: "Reply `ok` to confirm requirements, or state changes." }, G1_review: { icon: "🔵", title: "Review step · Approve plan", action: "Reply `approve` to approve the plan and start implementation, or state decision changes." }, G2_codereview: { icon: "🟣", title: "Review step · Review implementation", action: "Approve the implementation to complete the task, or point out what to fix." } };
 export const gateView = (task, diagnostics) => { if (task.gate === "none") throw new Error(`Task has no human gate: ${task.id}`); const errors = diagnostics.filter((item) => item.level === "ERROR"); if (errors.length) throw new Error(errors.map((item) => item.message).join("; ")); const meta = gateMeta[task.gate]; const counts = (items) => items.reduce((result, item) => ({ ...result, [item.status]: (result[item.status] ?? 0) + 1 }), {}); return { schemaVersion: 1, gate: task.gate, icon: meta.icon, title: meta.title, action: meta.action, task: { id: task.id, title: oneLine(task.title), status: task.status, risk: task.risk, areas: task.areas }, artifacts: Object.entries(task.artifacts).flatMap(([name, path]) => path ? [{ name: oneLine(name), path: oneLine(path) }] : []), decisions: counts(task.decisions), execution: counts(task.tasks), evidence: task.evidence.filter((item) => ["test", "lint", "review"].includes(item.kind)).slice(-5).map((item) => ({ kind: item.kind, result: item.result, source: oneLine(item.source) })), diagnostics: diagnostics.filter((item) => item.level !== "INFO").map((item) => ({ level: item.level, code: item.code, message: oneLine(item.message) })) }; };
 const markdownLinkTarget = (value) => encodeURI(value).replace(/[()#?]/g, (character) => `%${character.charCodeAt(0).toString(16).toUpperCase()}`);
 export const formatGateView = (task, diagnostics, format = "markdown") => { const view = gateView(task, diagnostics); if (format === "json") return `${JSON.stringify(view, null, 2)}\n`; const artifacts = view.artifacts.length ? view.artifacts.map((item) => format === "markdown" ? `- **${markdownText(item.name)}:** [${markdownText(item.path)}](${markdownLinkTarget(item.path)})` : `- ${item.name}: ${item.path}`).join("\n") : "- none"; const decisions = Object.entries(view.decisions).map(([status, count]) => `${count} ${status}`).join(" · ") || "none"; const execution = Object.entries(view.execution).map(([status, count]) => `${count} ${status}`).join(" · ") || "none"; const evidence = view.evidence.length ? view.evidence.map((item) => `- ${item.kind}: ${item.result} — ${format === "markdown" ? markdownText(item.source) : item.source}`).join("\n") : "- none yet"; const warnings = view.diagnostics.length ? `\n\n${view.diagnostics.map((item) => `- ${item.level} ${item.code}: ${format === "markdown" ? markdownText(item.message) : item.message}`).join("\n")}` : ""; if (format === "plain") return [`[IMPORTANT] ${view.icon} ${view.title}`, `Task: ${view.task.id} — ${view.task.title}`, `Status: ${view.task.status} · Risk: ${view.task.risk} · Areas: ${view.task.areas.join(", ")}`, "", "Review artifacts", artifacts, "", `Decisions: ${decisions}`, `Execution: ${execution}`, "Evidence", evidence, warnings, "", `ACTION REQUIRED -> ${oneLine(view.action)}`].join("\n").replace(/\n{3,}/g, "\n\n") + "\n"; return ["> [!IMPORTANT]", `> ${view.icon} **${view.title}**`, `> **Task:** \`${view.task.id}\` — ${markdownText(view.task.title)}`, `> **Status:** \`${view.task.status}\` · **Risk:** \`${view.task.risk}\` · **Areas:** ${view.task.areas.map((area) => `\`${markdownText(area)}\``).join(", ")}`, "", "### Review artifacts", artifacts, "", `**Decisions:** ${decisions}  `, `**Execution:** ${execution}`, "", "### Verification evidence", evidence, warnings, "", `> **ACTION REQUIRED →** ${view.action}`].join("\n").replace(/\n{3,}/g, "\n\n") + "\n"; };

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

@@ -0,0 +1,90 @@
+#!/usr/bin/env node
+import { execFileSync } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { existsSync, readFileSync } from "node:fs";
+import { resolve, join } from "node:path";
+import { createInterface } from "node:readline/promises";
+import { stdin, stdout } from "node:process";
+import { requireLocalAuthority } from "./lib/authority.mjs";
+import { isLoopProvider } from "./lib/loop-drivers.mjs";
+import { prepareLoopIntake } from "./lib/loop-intake.mjs";
+import * as localSupervisor from "./lib/loop-supervisor-run-local.mjs";
+import { loadTask } from "./lib/store.mjs";
+
+const [action, taskArg, rootArg, modeArg] = process.argv.slice(2);
+const root = resolve(rootArg || ".");
+const readRequirement = async () => {
+  if (stdin.isTTY) { const rl = createInterface({ input: stdin, output: stdout }); try { return await rl.question("Requirement: "); } finally { rl.close(); } }
+  const chunks = []; for await (const chunk of stdin) { chunks.push(chunk); if (chunks.reduce((n, c) => n + c.length, 0) > 8192) throw new Error("Requirement exceeds 8192 bytes"); } return Buffer.concat(chunks).toString("utf8");
+};
+try {
+  if (!["start", "resume", "status"].includes(action)) throw new Error("Expected loop start, resume, or status");
+  const config = JSON.parse(readFileSync(join(root, ".agents", "config.json"), "utf8"));
+  const mode = modeArg || config.loop?.mode || "off";
+  if (!["local", "fleet"].includes(mode)) throw new Error("Loop mode is off; configure an enabled loop mode first");
+  if (mode !== config.loop?.mode) throw new Error("Requested mode does not match configured authority");
+  const agent = config.loop?.agents?.lead;
+  const workers = config.loop?.agents?.workers ?? {};
+  if (!isLoopProvider(agent) || !Object.keys(workers).length || Object.entries(workers).some(([, value]) => !isLoopProvider(value))) throw new Error("Loop requires a configured lead and worker providers");
+  const taskId = taskArg || (action === "start" ? `loop-${randomUUID()}` : "");
+  if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(taskId)) throw new Error("Valid task ID required");
+  if (mode === "fleet") {
+    const { callRemoteTool } = await import("./lib/remote-state-client.mjs");
+    const { createFleetRemoteRepository } = await import("./lib/loop-fleet-remote.mjs");
+    const { runFleetCli } = await import("./lib/loop-fleet-cli.mjs");
+    const { readIntegrationCommit } = await import("./remote-state.mjs");
+    const requiredEnv = (name) => { const value = process.env[name]; if (typeof value !== "string" || !value.trim()) throw new Error(`Fleet loop requires ${name} for the configured remote authority`); return value; };
+    const url = requiredEnv("AIDLC_FLEET_URL"), workspace = requiredEnv("AIDLC_FLEET_WORKSPACE"), token = requiredEnv("AIDLC_FLEET_TOKEN");
+    const integrationBranch = requiredEnv("AIDLC_FLEET_INTEGRATION_BRANCH");
+    if (process.env.AIDLC_FLEET_PROJECT_ROOT && resolve(process.env.AIDLC_FLEET_PROJECT_ROOT) !== root) throw new Error("AIDLC_FLEET_PROJECT_ROOT does not match the loop root; refusing to run");
+    if (process.env.AIDLC_FLEET_WORKER_IDS && process.env.AIDLC_FLEET_WORKER_IDS.split(",").map((value) => value.trim()).filter(Boolean).join(",") !== Object.keys(workers).join(",")) throw new Error("AIDLC_FLEET_WORKER_IDS does not match the configured loop workers");
+    if (process.env.AIDLC_FLEET_WORKER_PROVIDERS && process.env.AIDLC_FLEET_WORKER_PROVIDERS !== JSON.stringify(workers)) throw new Error("AIDLC_FLEET_WORKER_PROVIDERS does not match the configured loop workers");
+    const env = { ...process.env, AIDLC_FLEET_PROJECT_ROOT: root, AIDLC_FLEET_WORKER_IDS: Object.keys(workers).join(","), AIDLC_FLEET_WORKER_PROVIDERS: JSON.stringify(workers), AIDLC_FLEET_AGENT: agent };
+    const remoteState = join(root, ".agents/aidlc/scripts/remote-state.mjs");
+    if (!existsSync(remoteState)) throw new Error(`Remote lifecycle CLI is missing: ${remoteState}`);
+    const callTool = ({ url: serviceUrl, token: serviceToken, name, args }) => callRemoteTool({ url: serviceUrl, token: serviceToken }, name, args);
+    const repository = createFleetRemoteRepository({ callTool, url, token, workspace, root });
+    if (action === "status") {
+      let snapshot = null;
+      try { snapshot = await repository.readTask({ taskId }); } catch (error) { if (!String(error?.message ?? error).includes("task not found")) throw error; }
+      const checkpoint = await repository.readGateCheckpoint({ taskId });
+      console.log(JSON.stringify({ taskId, authority: "fleet", task: snapshot?.task ?? null, nextAction: snapshot?.nextAction ?? null, checkpoint }, null, 2));
+    } else {
+      if (action === "resume") {
+        const recordPath = join(root, ".agents/data/tasks", taskId, "loop-intake.json");
+        if (!existsSync(recordPath)) throw new Error("Loop record missing; use start");
+        const record = JSON.parse(readFileSync(recordPath, "utf8"));
+        if (record.taskId !== taskId || record.authority !== "fleet") throw new Error("Loop record authority mismatch; use the recorded authority and task");
+      }
+      await callRemoteTool({ url, token }, "fleet_get", { workspace });
+      await readIntegrationCommit({ projectRoot: root, integrationBranch, gitRemote: env.AIDLC_FLEET_GIT_REMOTE ?? "origin" });
+      if (action === "start") {
+        const requirement = await readRequirement();
+        const readTask = async (id) => { try { return (await callRemoteTool({ url, token }, "task_get", { workspace, taskId: id, clientProjectRoot: root })).task; } catch { return null; } };
+        const current = await callRemoteTool({ url, token }, "state_get", { workspace });
+        const actionable = Object.values(current?.state?.tasks ?? {}).filter((task) => task.id !== taskId && task.status === "active" && !task.handoff);
+        if (actionable.length) throw new Error(`Task create is blocked while other work is actionable: ${actionable.map((task) => task.id).join(", ")}`);
+        await prepareLoopIntake({ root, taskId, requirement, authority: "fleet", readTask, createTask: async ({ taskId: id, title }) => {
+          const claim = await repository.claimLead({ taskId: id, leaseMs: 60000 });
+          try {
+            execFileSync(process.execPath, [remoteState, "task", "create", id, "--title", title], { cwd: root, encoding: "utf8", env: { ...env, AIDLC_FLEET_LEAD_EPOCH: String(claim.epoch), AIDLC_FLEET_LEAD_OWNER_TOKEN: repository.leadOwnerToken() } });
+          } finally { await repository.releaseLead({ taskId: id, epoch: claim.epoch }); }
+        } });
+      }
+      await runFleetCli(["supervisor", taskId], { callTool, env, out: (line) => console.log(line) });
+    }
+  } else {
+    requireLocalAuthority();
+    // The factory contract guarantees that the dispatcher is actually wired into
+    // the supervisor, not merely present in the package. No host fallback.
+    if (typeof localSupervisor.createIsolatedLocalSupervisor !== "function") throw new Error("Isolated local worker dispatcher is not integrated; loop execution is unavailable");
+    const supervisor = await localSupervisor.createIsolatedLocalSupervisor({ root, taskId, agent, workers: config.loop.agents.workers });
+    if (action === "status") {
+      console.log(JSON.stringify(await supervisor.status(), null, 2));
+    } else if (action === "start") {
+      const requirement = await readRequirement();
+      await prepareLoopIntake({ root, taskId, requirement, authority: "local", readTask: async (id) => loadTask(root, id), createTask: async ({ taskId: id, title }) => { execFileSync(process.execPath, [join(root, ".agents/aidlc/scripts/state.mjs"), "task", "create", id, "--title", title, "--root", root], { stdio: ["ignore", "pipe", "pipe"] }); } });
+      console.log(JSON.stringify(await supervisor.start(), null, 2));
+    } else console.log(JSON.stringify(await supervisor.resume(), null, 2));
+  }
+} catch (error) { console.error(`loop: ${error.message}`); process.exitCode = 1; }

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

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+// This host-only terminal is deliberately not available to lead/worker containers.
+import { createHash } from "node:crypto";
+import { execFileSync } from "node:child_process";
+import { lstatSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { createInterface } from "node:readline/promises";
+import { stdin, stdout } from "node:process";
+import { acquireStateLock, approveAndAdvance, checkGate, loadState, saveState } from "./lib/store.mjs";
+import { formatGateView } from "./lib/runtime.mjs";
+import { requireLocalAuthority } from "./lib/authority.mjs";
+import { leadArtifactDigest } from "./lib/loop-lead-artifacts.mjs";
+import { readLocalGateCheckpoint, writeLocalGateReceipt } from "./lib/loop-local-gate-receipt.mjs";
+
+const digest = (value) => createHash("sha256").update(JSON.stringify(value)).digest("hex");
+function snapshot(root, taskId, state) {
+  const task = state.tasks[taskId];
+  if (!task || task.status !== "blocked_on_user") throw new Error("Task is not waiting at a human gate");
+  const pending = join(root, ".agents", "data", "tasks", taskId, ".lead-artifact-journal.json");
+  try { lstatSync(pending); throw new Error("Pending artifact journal requires supervised recovery before review"); }
+  catch (error) { if (error.code !== "ENOENT") throw error; }
+  const checks = checkGate(root, state, taskId, task.gate);
+  if (checks.some((entry) => entry.level === "ERROR")) throw new Error("Gate checks failed; repair before approval");
+  const artifacts = Object.fromEntries(["intent", "design", "workplan"].map((name) => [name, leadArtifactDigest({ root, taskId, task, name })]));
+  let commit = null;
+  if (task.gate === "G2_codereview") {
+    commit = execFileSync("git", ["rev-parse", "HEAD"], { cwd: root, encoding: "utf8", timeout: 30000 }).trim();
+    const status = execFileSync("git", ["status", "--porcelain=v1", "-z", "--untracked-files=all"], { cwd: root, encoding: "utf8", timeout: 30000 });
+    if (status.split("\0").filter(Boolean).some((entry) => !entry.slice(3).startsWith(".agents/data/"))) throw new Error("G2 review requires a clean integration checkout outside workflow data");
+  }
+  const checkpoint = readLocalGateCheckpoint(root, task);
+  return { taskId, phase: task.phase, gate: task.gate, taskHash: digest(task), checkpointHash: digest(checkpoint), artifacts, commit, view: formatGateView(task, checks, "plain") };
+}
+async function main() {
+  if (!stdin.isTTY || !stdout.isTTY) throw new Error("Gate approval requires the trusted host terminal");
+  const [taskId, ...args] = process.argv.slice(2);
+  if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(taskId ?? "") || (args.length && (args.length !== 2 || args[0] !== "--root" || !args[1]))) throw new Error("Usage: loop-gate.mjs <task-id> [--root <path>]");
+  const root = resolve(args[1] ?? "."); requireLocalAuthority();
+  let release = acquireStateLock(root), review;
+  try { review = snapshot(root, taskId, loadState(root)); } finally { release(); }
+  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");
+  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 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)}`);
+  } finally { release(); }
+}
+main().catch((error) => { console.error(`loop-gate: ${error.message}`); process.exitCode = 1; });

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

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+import { resolve } from "node:path";
+import { loopStatus, runLoop } from "./lib/loop-runtime.mjs";
+import { LOOP_PROVIDERS, runAgentTurn } from "./lib/loop-drivers.mjs";
+import { requireLocalAuthority } from "./lib/authority.mjs";
+
+function parse(argv) {
+  const [command, taskId, ...tail] = argv;
+  const providers = LOOP_PROVIDERS.join("|");
+  if (!["run", "resume", "status"].includes(command) || !taskId) throw new Error(`Usage: loop.mjs run <task-id> --agent ${providers} [--max-turns N] [--turn-timeout-ms N] [--max-stall-turns N] [--root PATH] | resume <task-id> [--max-turns N] [--turn-timeout-ms N] [--max-stall-turns N] [--root PATH] | status <task-id> [--root PATH]`);
+  const options = {};
+  const supported = new Set(["--root", "--agent", "--max-turns", "--turn-timeout-ms", "--max-stall-turns"]);
+  for (let i = 0; i < tail.length; i += 2) {
+    const name = tail[i], value = tail[i + 1];
+    if (!supported.has(name) || !value || value.startsWith("--") || options[name] !== undefined) throw new Error(`Invalid option: ${name}`);
+    options[name] = value;
+  }
+  if (command === "status" && Object.keys(options).some((key) => key !== "--root")) throw new Error("status only accepts --root");
+  if (command === "run" && !LOOP_PROVIDERS.includes(options["--agent"])) throw new Error(`run requires --agent ${LOOP_PROVIDERS.join("|")}`);
+  const limits = {};
+  if (options["--max-turns"] !== undefined) limits.maxTurns = Number(options["--max-turns"]);
+  if (options["--turn-timeout-ms"] !== undefined) limits.turnTimeoutMs = Number(options["--turn-timeout-ms"]);
+  if (options["--max-stall-turns"] !== undefined) limits.maxStallTurns = Number(options["--max-stall-turns"]);
+  return { command, taskId, root: resolve(options["--root"] ?? process.cwd()), agent: options["--agent"], limits };
+}
+
+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)); } });
+  console.log(JSON.stringify({ ok: true, result }, null, 2));
+  if (result.status && !["complete", "gate"].includes(result.status)) process.exitCode = 2;
+} catch (error) {
+  console.error(JSON.stringify({ ok: false, error: error instanceof Error ? error.message : String(error) }));
+  process.exitCode = 1;
+}