@felixdotgo/aidlc-kit 0.0.1 → 0.1.0

package/dist/src/cli.js

@@ -1,20 +1,24 @@
 #!/usr/bin/env node
 import { stdin, stdout } from "node:process";
+import { spawnSync } from "node:child_process";
+import { resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { join } from "node:path";
 import { installableAdapters } from "./adapters.js";
 import { applyPlan, detectedAgents, doctor, formatPlan, planInit, planUninstall, selectAgents, status } from "./installer.js";
-import { loadProjectConfig, resolveProfiles } from "./profiles.js";
+import { LOOP_PROVIDERS } from "./model.js";
+import { loadProjectConfig, resolveProfiles, validateLoopConfig } from "./profiles.js";
 import { applyUpgrade, planUpgrade } from "./upgrade.js";
 import { packageVersion } from "./workflow.js";
 import { applyMcpSetup, planMcpSetup } from "./mcp-setup.js";
 const usage = `Usage:
-  npx @felixdotgo/aidlc-kit init [path] [--agent <name[,name]> | --all] [--yes] [--dry-run] [--force]
-  npx @felixdotgo/aidlc-kit upgrade [path] [--dry-run]
+  npx @felixdotgo/aidlc-kit init [path] [--agent <name[,name]> | --all] [--loop-mode off|local|fleet] [--loop-lead ${LOOP_PROVIDERS.join("|")}] [--loop-workers <id=provider,...>] [--yes] [--dry-run] [--force]
+  npx @felixdotgo/aidlc-kit upgrade [path] [--loop-mode off|local|fleet] [--loop-lead ${LOOP_PROVIDERS.join("|")}] [--loop-workers <id=provider,...>] [--dry-run]
   npx @felixdotgo/aidlc-kit uninstall [path] [--yes] [--dry-run]
   npx @felixdotgo/aidlc-kit status [path]
   npx @felixdotgo/aidlc-kit doctor [path] [--strict]
   npx @felixdotgo/aidlc-kit profile validate [path]
+  npx @felixdotgo/aidlc-kit loop start|status|resume [--task-id ID] [--root PATH] [--mode local|fleet]
   npx @felixdotgo/aidlc-kit mcp setup [path] [--dry-run] [--yes] [--storage sqlite|postgres] [--deployment docker|remote] [--bind localhost|network] [--workspace <id>] [--poll-ms <n>] [--enable]`;
 const interactive = () => Boolean(stdin.isTTY && stdout.isTTY);
 const prompts = async () => import("@inquirer/prompts");
@@ -23,7 +27,7 @@ const value = (args, name) => {
     return index < 0 ? undefined : args[index + 1];
 };
 const flags = (args) => new Set(args.filter((item) => item.startsWith("--")));
-const valueFlags = new Set(["--agent", "--storage", "--deployment", "--bind", "--workspace", "--poll-ms", "--token-env", "--providers"]);
+const valueFlags = new Set(["--agent", "--storage", "--deployment", "--bind", "--workspace", "--poll-ms", "--token-env", "--providers", "--loop-mode", "--loop-lead", "--loop-workers"]);
 const positional = (args) => {
     const result = [];
     for (let index = 0; index < args.length; index += 1) {
@@ -37,6 +41,42 @@ const positional = (args) => {
     return result;
 };
 const rootArg = (args, fallback = ".") => positional(args).find((item) => !["init", "upgrade", "uninstall", "status", "doctor", "validate", "run", "list"].includes(item)) ?? fallback;
+const chooseLoop = async (args, upgrade) => {
+    let mode = value(args, "--loop-mode");
+    const leadArg = value(args, "--loop-lead"), workersArg = value(args, "--loop-workers");
+    if (!mode && (leadArg || workersArg))
+        throw new Error("--loop-lead and --loop-workers require --loop-mode");
+    if (!mode && interactive()) {
+        const { select } = await prompts();
+        mode = await select({ message: "Loop execution mode", choices: [
+                ...(upgrade ? [{ name: "Keep existing loop configuration", value: "keep" }] : []),
+                { name: "Off", value: "off" }, { name: "Local", value: "local" }, { name: "Fleet", value: "fleet" }
+            ] });
+    }
+    if (!mode || mode === "keep")
+        return undefined;
+    if (mode === "off") {
+        if (leadArg || workersArg)
+            throw new Error("Disabled loop cannot specify agents");
+        return validateLoopConfig({ mode });
+    }
+    let lead = leadArg, rawWorkers = workersArg;
+    if (interactive() && (!lead || !rawWorkers)) {
+        const { select, input } = await prompts();
+        lead ??= await select({ message: "Lead agent", choices: LOOP_PROVIDERS.map((name) => ({ name, value: name })) });
+        rawWorkers ??= await input({ message: "Workers (id=provider, comma separated)", default: "codex-worker=codex,claude-worker=claude" });
+    }
+    if (!lead || !rawWorkers)
+        throw new Error("An enabled loop requires --loop-lead and --loop-workers");
+    const workers = Object.create(null);
+    for (const entry of rawWorkers.split(",")) {
+        const parts = entry.split("=");
+        if (parts.length !== 2 || !parts[0] || !parts[1] || Object.hasOwn(workers, parts[0]))
+            throw new Error("Invalid or duplicate loop worker mapping");
+        workers[parts[0]] = parts[1];
+    }
+    return validateLoopConfig({ mode, agents: { lead, workers } });
+};
 const initOptions = (args) => ({
     root: rootArg(args),
     agents: (value(args, "--agent") ?? "").split(",").filter(Boolean),
@@ -109,6 +149,26 @@ const main = async () => {
     const [command = "help", ...args] = process.argv.slice(2);
     if (command === "help" || command === "--help")
         return void console.log(usage);
+    if (command === "loop") {
+        const action = args[0];
+        if (!["start", "status", "resume"].includes(action))
+            throw new Error("Expected loop start, status, or resume");
+        const parsed = new Map();
+        for (let index = 1; index < args.length; index += 2) {
+            const key = args[index], entry = args[index + 1];
+            if (!["--task-id", "--root", "--mode"].includes(key) || !entry || entry.startsWith("--") || parsed.has(key))
+                throw new Error("Invalid or duplicate loop option");
+            parsed.set(key, entry);
+        }
+        const root = resolve(parsed.get("--root") ?? ".");
+        const script = join(root, ".agents", "aidlc", "scripts", "loop-entry.mjs");
+        const child = spawnSync(process.execPath, [script, action, parsed.get("--task-id") ?? "", root, parsed.get("--mode") ?? ""], { stdio: "inherit" });
+        if (child.error)
+            throw child.error;
+        if (child.status !== 0)
+            process.exitCode = child.status ?? 1;
+        return;
+    }
     if (command === "status")
         return void console.log(status(rootArg(args)));
     if (command === "doctor") {
@@ -119,7 +179,7 @@ const main = async () => {
         return;
     }
     if (command === "init") {
-        const options = await chooseAgents(initOptions(args));
+        const options = { ...await chooseAgents(initOptions(args)), loop: await chooseLoop(args, false) };
         const plan = planInit(options);
         preview("INIT", plan);
         if (plan.some((item) => item.action === "conflict"))
@@ -151,7 +211,7 @@ const main = async () => {
         if (flags(args).has("--yes") || flags(args).has("--force"))
             throw new Error("upgrade does not support --yes or --force; apply requires a human interactive TTY confirmation");
         const root = rootArg(args);
-        const plan = planUpgrade(root);
+        const plan = planUpgrade(root, await chooseLoop(args, true));
         preview("UPGRADE", plan);
         if (plan.some((item) => item.action === "conflict"))
             throw new Error("Upgrade contains conflicts; no files were written.");

package/dist/src/gate.js

@@ -98,9 +98,9 @@ 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." }
+    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." }
 };
 const artifactRows = (task) => Object.entries(task.artifacts).flatMap(([name, path]) => path ? [{ name: oneLine(name), path: oneLine(path) }] : []);
 const markdownLinkTarget = (value) => encodeURI(value).replace(/[()#?]/g, (character) => `%${character.charCodeAt(0).toString(16).toUpperCase()}`);

package/dist/src/installer.d.ts

@@ -1,8 +1,12 @@
-import type { AgentId, FileSpec, InitOptions, PlannedWrite, WorkflowManifest } from "./model.js";
+import type { AgentId, FileSpec, InitOptions, LoopConfig, ManifestInventoryItem, PlannedWrite, WorkflowManifest } from "./model.js";
+/** Managed prompt blocks share a path across owners, so inventory keys carry the owner. */
+export declare const installedHashFor: (files: Record<string, ManifestInventoryItem> | undefined, spec: Pick<FileSpec, "path" | "owner" | "strategy">) => string | undefined;
 export declare const managedContentHash: (spec: Pick<FileSpec, "owner" | "strategy">, content: string) => string | undefined;
 export declare const readManifest: (root: string) => WorkflowManifest | undefined;
 export declare const detectedAgents: (root: string) => AgentId[];
 export declare const selectAgents: (options: Pick<InitOptions, "root" | "agents" | "all">) => AgentId[];
+/** Include an explicitly selected loop config in the same preview/transaction as setup. */
+export declare const planLoopSelection: (plan: PlannedWrite[], selection?: LoopConfig) => void;
 export declare const planInit: (options: InitOptions) => PlannedWrite[];
 export declare const applyPlan: (root: string, plan: PlannedWrite[]) => void;
 export declare const formatPlan: (plan: PlannedWrite[]) => string;

package/dist/src/installer.js

@@ -1,7 +1,7 @@
 import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { adapters, findAdapter, installableAdapters, resolvedAdapters } from "./adapters.js";
-import { loadProjectConfig } from "./profiles.js";
+import { loadProjectConfig, validateLoopConfig } from "./profiles.js";
 import { loadState } from "./state.js";
 import { planProjectLayoutMigration } from "./project-migration.js";
 import { managedBlock, mergeManagedBlock } from "./managed-content.js";
@@ -9,6 +9,16 @@ import { resolveProjectPathWithoutSymlinks } from "./project-path.js";
 import { contentHash, coreWorkflowFiles, initialProjectFiles, manifestSpec, packageVersion } from "./workflow.js";
 const shortHash = (content) => contentHash(content).slice(0, 12);
 const safeTarget = (root, path) => resolveProjectPathWithoutSymlinks(root, path, "Managed path escapes the project", "Managed path crosses a symlink");
+/** Managed prompt blocks share a path across owners, so inventory keys carry the owner. */
+export const installedHashFor = (files, spec) => {
+    if (!files)
+        return undefined;
+    const keyed = files[`${spec.path}#${spec.owner}`];
+    if (keyed)
+        return keyed.hash;
+    const legacy = files[spec.path];
+    return legacy && (spec.strategy !== "managed-block" || legacy.owner === spec.owner) ? legacy.hash : undefined;
+};
 export const managedContentHash = (spec, content) => {
     const managed = managedBlock(spec, content);
     return managed === undefined ? undefined : contentHash(managed);
@@ -51,13 +61,33 @@ const planFile = (root, spec, force, installed) => {
         return { ...spec, action: "skip", reason: "already current" };
     if (spec.path === ".agents/aidlc/manifest.json" && installed)
         return { ...spec, action: "update", reason: "refresh manifest inventory" };
-    const installedHash = installed?.files[spec.path]?.hash;
+    const installedHash = installedHashFor(installed?.files, spec);
     if (installedHash && contentHash(current) === installedHash)
         return { ...spec, action: "update", reason: "unchanged managed file" };
     if (force)
         return { ...spec, action: "update", reason: "--force permits replacement of an unmanaged file" };
     return { ...spec, action: "conflict", reason: "managed ownership cannot be proven; use upgrade or review --force" };
 };
+/** Include an explicitly selected loop config in the same preview/transaction as setup. */
+export const planLoopSelection = (plan, selection) => {
+    if (selection === undefined)
+        return;
+    const loop = validateLoopConfig(selection);
+    const config = plan.find((item) => item.path === ".agents/config.json");
+    if (!config || !["create", "preserve", "skip", "migrate"].includes(config.action))
+        throw new Error("Cannot change loop configuration while the project config has another planned change");
+    const parsed = JSON.parse(config.content);
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+        throw new Error("Invalid project config");
+    const current = parsed;
+    if (JSON.stringify(current.loop) === JSON.stringify(loop))
+        return;
+    const previousAction = config.action;
+    current.loop = loop;
+    config.content = `${JSON.stringify(current, null, 2)}\n`;
+    config.action = previousAction === "create" || previousAction === "migrate" ? previousAction : "update";
+    config.reason = "explicit loop mode selection";
+};
 export const planInit = (options) => {
     const root = resolve(options.root);
     const installed = readManifest(root);
@@ -70,8 +100,21 @@ export const planInit = (options) => {
     const agentFiles = selected.flatMap((id) => findAdapter(id)?.files() ?? []).map((file) => ({ ...file, ownershipClass: "managed" }));
     const managedFiles = [...coreWorkflowFiles(), ...agentFiles];
     const files = [...managedFiles, manifestSpec(managedFiles, selected), ...initialProjectFiles()];
-    const plan = files.map((spec) => planFile(root, spec, options.force, installed));
+    const plan = [];
+    for (const spec of files) {
+        const previous = spec.strategy === "managed-block" ? plan.find((item) => item.path === spec.path && ["create", "update", "skip"].includes(item.action)) : undefined;
+        if (!previous) {
+            plan.push(planFile(root, spec, options.force, installed));
+            continue;
+        }
+        const target = safeTarget(root, spec.path);
+        const current = existsSync(target) ? readFileSync(target, "utf8") : "";
+        previous.content = mergeManagedBlock(spec, previous.content);
+        previous.action = existsSync(target) ? (previous.content === current ? "skip" : "update") : "create";
+        previous.reason = existsSync(target) ? "managed prompt block" : "new managed prompt";
+    }
     planProjectLayoutMigration(root, plan);
+    planLoopSelection(plan, options.loop);
     return plan;
 };
 export const applyPlan = (root, plan) => {
@@ -95,33 +138,73 @@ const hasOwnedManifest = (root) => {
         return false;
     }
 };
+const removeManagedBlock = (current, owner) => {
+    const start = `<!-- aidlc-installer:${owner}:start -->`;
+    const end = `<!-- aidlc-installer:${owner}:end -->`;
+    return current.replace(new RegExp(`${start}[\\s\\S]*?${end}\\n?`, "g"), "").replace(/\n{3,}/g, "\n\n").trimEnd();
+};
 export const planUninstall = (root) => {
     const project = resolve(root);
     if (!hasOwnedManifest(project))
         throw new Error("No aidlc-workflow ownership manifest found; refusing to remove files.");
     const installed = readManifest(project);
     const currentSpecs = [...coreWorkflowFiles(), ...resolvedAdapters().flatMap((adapter) => adapter.files()).map((file) => ({ ...file, ownershipClass: "managed" }))];
-    const specs = installed ? Object.entries(installed.files).map(([path, item]) => currentSpecs.find((spec) => spec.path === path) ?? ({ path, owner: item.owner, strategy: item.strategy, content: "", ownershipClass: "managed" })) : currentSpecs;
-    const plan = specs.map((spec) => {
-        const target = safeTarget(project, spec.path);
-        if (!existsSync(target))
-            return { ...spec, action: "skip", reason: "not installed" };
-        const current = readFileSync(target, "utf8");
-        if (spec.strategy === "managed-block") {
-            const block = managedBlock(spec, current);
-            if (!block)
-                return { ...spec, action: "skip", reason: "owned block not found" };
-            const installedHash = installed?.files[spec.path]?.hash ?? contentHash(spec.content.trimEnd());
-            if (contentHash(block) !== installedHash)
-                return { ...spec, action: "preserve", reason: "managed block was modified" };
-            const start = `<!-- aidlc-installer:${spec.owner}:start -->`;
-            const end = `<!-- aidlc-installer:${spec.owner}:end -->`;
-            const next = current.replace(new RegExp(`${start}[\\s\\S]*?${end}\\n?`, "g"), "").replace(/\n{3,}/g, "\n\n").trimEnd();
-            return next ? { ...spec, content: `${next}\n`, action: "update", reason: "remove owned prompt block" } : { ...spec, content: "", action: "delete", reason: "remove owned prompt file" };
+    const entries = installed
+        ? Object.entries(installed.files).map(([key, item]) => {
+            const separator = key.lastIndexOf("#");
+            const path = separator > 0 ? key.slice(0, separator) : key;
+            const owner = separator > 0 ? key.slice(separator + 1) : item.owner;
+            const spec = currentSpecs.find((candidate) => candidate.path === path && (candidate.strategy !== "managed-block" || candidate.owner === owner)) ?? { path, owner, strategy: item.strategy, content: "", ownershipClass: "managed" };
+            return { spec, hash: item.hash };
+        })
+        : currentSpecs.map((spec) => ({ spec }));
+    const grouped = new Map();
+    for (const entry of entries)
+        grouped.set(entry.spec.path, [...(grouped.get(entry.spec.path) ?? []), entry]);
+    const plan = [];
+    for (const [path, group] of grouped) {
+        const target = safeTarget(project, path);
+        const exists = existsSync(target);
+        const current = exists ? readFileSync(target, "utf8") : "";
+        if (!exists) {
+            plan.push({ ...group[0].spec, action: "skip", reason: "not installed" });
+            continue;
+        }
+        if (!group.some((entry) => entry.spec.strategy === "managed-block")) {
+            const { spec, hash } = group[0];
+            const installedHash = hash ?? contentHash(spec.content);
+            plan.push(contentHash(current) === installedHash ? { ...spec, action: "delete", reason: "remove unchanged managed file" } : { ...spec, action: "preserve", reason: "managed file was modified" });
+            continue;
         }
-        const installedHash = installed?.files[spec.path]?.hash ?? contentHash(spec.content);
-        return contentHash(current) === installedHash ? { ...spec, action: "delete", reason: "remove unchanged managed file" } : { ...spec, action: "preserve", reason: "managed file was modified" };
-    });
+        let next = current;
+        let modified;
+        for (const { spec, hash } of group) {
+            const block = managedBlock(spec, next);
+            // A v0.2.1 single-marker block cannot be removed safely; retain ownership instead of orphaning it.
+            if (!block) {
+                if (next.includes(`<!-- aidlc-installer:${spec.owner} -->`))
+                    modified = spec;
+                continue;
+            }
+            if (contentHash(block) !== (hash ?? contentHash(spec.content.trimEnd()))) {
+                modified = spec;
+                break;
+            }
+            next = removeManagedBlock(next, spec.owner);
+        }
+        const ownerSpec = group[0].spec;
+        const legacyResidue = group.find(({ spec }) => next.includes(`<!-- aidlc-installer:${spec.owner} -->`));
+        if (modified)
+            plan.push({ ...modified, action: "preserve", reason: "managed block was modified" });
+        else if (legacyResidue)
+            plan.push({ ...legacyResidue.spec, action: "preserve", reason: "legacy prompt marker requires manual removal" });
+        else if (next === current)
+            plan.push({ ...ownerSpec, action: "skip", reason: "owned block not found" });
+        else if (next)
+            plan.push({ ...ownerSpec, content: `${next}\n`, action: "update", reason: "remove owned prompt block" });
+        else
+            plan.push({ ...ownerSpec, content: "", action: "delete", reason: "remove owned prompt file" });
+    }
     plan.push({ path: ".agents/aidlc/manifest.json", owner: "aidlc-core", content: "", ownershipClass: "managed", action: plan.some((item) => item.action === "preserve") ? "preserve" : "delete", reason: plan.some((item) => item.action === "preserve") ? "retained while modified managed files remain" : "remove ownership manifest" });
     return plan;
 };
@@ -160,13 +243,14 @@ export const doctor = (root, strict = false) => {
     catch (error) {
         return `ERROR: local config/state is invalid: ${error instanceof Error ? error.message : String(error)}`;
     }
-    const modified = Object.entries(manifest.files).filter(([path, item]) => {
-        const target = safeTarget(root, path);
-        if (!existsSync(target))
-            return true;
-        const spec = { owner: item.owner, strategy: item.strategy };
-        return managedContentHash(spec, readFileSync(target, "utf8")) !== item.hash;
-    }).map(([path]) => path);
+    const modified = [...new Set(Object.entries(manifest.files).filter(([key, item]) => {
+            const separator = key.lastIndexOf("#");
+            const target = safeTarget(root, separator > 0 ? key.slice(0, separator) : key);
+            if (!existsSync(target))
+                return true;
+            const spec = { owner: item.owner, strategy: item.strategy };
+            return managedContentHash(spec, readFileSync(target, "utf8")) !== item.hash;
+        }).map(([key]) => key.includes("#") ? key.slice(0, key.lastIndexOf("#")) : key))];
     if (modified.length)
         return `${strict ? "ERROR" : "WARN"}: managed integrity differs: ${modified.join(", ")}`;
     return `OK: local workflow ${manifest.packageVersion} is valid; remote updates are disabled.`;

package/dist/src/managed-content.js

@@ -10,7 +10,7 @@ export const mergeManagedBlock = (spec, current) => {
     const end = `<!-- aidlc-installer:${spec.owner}:end -->`;
     const block = spec.content.trimEnd();
     const matches = new RegExp(`${start}[\\s\\S]*?${end}\\n?`, "g");
-    const withoutOwnedBlocks = current.replace(matches, "").replace(/\n{3,}/g, "\n\n").trimEnd();
+    const withoutOwnedBlocks = current.replace(matches, "").replace(/\n{3,}/g, "\n\n").trim();
     const next = `${withoutOwnedBlocks}${withoutOwnedBlocks ? "\n\n" : ""}${block}`;
     return `${next.trimEnd()}\n`;
 };

package/dist/src/model.d.ts

@@ -31,6 +31,17 @@ export interface InitOptions {
     dryRun: boolean;
     yes: boolean;
     force: boolean;
+    loop?: LoopConfig;
+}
+export type LoopMode = "off" | "local" | "fleet";
+export declare const LOOP_PROVIDERS: readonly ["codex", "claude", "opencode"];
+export type LoopAgent = (typeof LOOP_PROVIDERS)[number];
+export interface LoopConfig {
+    mode: LoopMode;
+    agents?: {
+        lead: LoopAgent;
+        workers: Record<string, LoopAgent>;
+    };
 }
 export interface CommandSpec {
     command: string;
@@ -72,6 +83,7 @@ export interface ProjectConfig {
     agentState: Partial<Record<AgentId, StateMutationMode>>;
     tracker?: TrackerConfig;
     mcp: McpConfig;
+    loop?: LoopConfig;
 }
 export interface McpConfig {
     enabled: boolean;
@@ -127,6 +139,7 @@ export interface LessonDisposition {
 }
 export interface TaskState {
     id: string;
+    featureId?: string;
     title: string;
     type: "feature" | "bug" | "refactor" | "infra";
     phase: Phase;
@@ -146,6 +159,8 @@ export interface TaskState {
         id: string;
         label: string;
         status: "todo" | "in_progress" | "done" | "deferred";
+        dependsOn?: string[];
+        ownedPaths?: string[];
     }>;
     evidence: Evidence[];
     lessons?: LessonRecord[];

package/dist/src/model.js

@@ -1 +1 @@
-export {};
+export const LOOP_PROVIDERS = Object.freeze(["codex", "claude", "opencode"]);

package/dist/src/profiles.d.ts

@@ -1,5 +1,6 @@
-import type { McpConfig, Profile, ProjectConfig, RiskLevel } from "./model.js";
+import type { LoopConfig, McpConfig, Profile, ProjectConfig, RiskLevel } from "./model.js";
 export declare const builtInProfiles: Readonly<Record<string, Profile>>;
+export declare const validateLoopConfig: (value: unknown) => LoopConfig;
 export declare const validateProfile: (value: unknown, label?: string) => Profile;
 export declare const defaultConfig: () => ProjectConfig;
 export declare const loadProjectConfig: (root: string) => ProjectConfig;
@@ -24,5 +25,6 @@ export declare const resolveEffectiveConfig: (root: string, config: ProjectConfi
         maxChars: number;
     };
     mcp: McpConfig;
+    loop: LoopConfig;
 };
 export declare const includedRuleFiles: (root: string, patterns: string[]) => string[];

package/dist/src/profiles.js

@@ -1,5 +1,8 @@
 import { existsSync, lstatSync, readFileSync, readdirSync, realpathSync } from "node:fs";
 import { dirname, isAbsolute, join, normalize, resolve } from "node:path";
+import { LOOP_PROVIDERS } from "./model.js";
+const loopProviderNames = `${LOOP_PROVIDERS.slice(0, -1).join(", ")}, or ${LOOP_PROVIDERS[LOOP_PROVIDERS.length - 1]}`;
+const isLoopProvider = (value) => typeof value === "string" && LOOP_PROVIDERS.includes(value);
 const profile = (id, markers = []) => ({
     schemaVersion: 1,
     id: `topology/${id}`,
@@ -20,6 +23,23 @@ const object = (value, label) => {
         throw new Error(`${label} must be an object`);
     return value;
 };
+export const validateLoopConfig = (value) => {
+    if (value === undefined)
+        return { mode: "off" };
+    const item = object(value, "config.loop");
+    if (Object.keys(item).some((key) => !["mode", "agents"].includes(key)) || typeof item.mode !== "string" || !["off", "local", "fleet"].includes(item.mode))
+        throw new Error("config.loop requires a valid mode and only supported fields");
+    if (item.agents === undefined)
+        return { mode: item.mode };
+    const agents = object(item.agents, "config.loop.agents");
+    if (Object.keys(agents).some((key) => !["lead", "workers"].includes(key)) || !isLoopProvider(agents.lead))
+        throw new Error(`config.loop.agents.lead must be ${loopProviderNames}`);
+    const workers = object(agents.workers, "config.loop.agents.workers");
+    for (const [id, provider] of Object.entries(workers))
+        if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(id) || !isLoopProvider(provider))
+            throw new Error(`config.loop.agents.workers must map worker IDs to ${loopProviderNames}`);
+    return { mode: item.mode, agents: { lead: agents.lead, workers: workers } };
+};
 const strings = (value, label) => {
     if (!Array.isArray(value) || value.some((item) => typeof item !== "string"))
         throw new Error(`${label} must be a string array`);
@@ -108,7 +128,8 @@ export const defaultConfig = () => ({
     risk: { default: "normal" },
     context: { maxChars: 16_000 },
     agentState: {},
-    mcp: { enabled: false }
+    mcp: { enabled: false },
+    loop: { mode: "off" }
 });
 export const loadProjectConfig = (root) => {
     const path = join(resolve(root), ".agents/config.json");
@@ -140,7 +161,8 @@ export const loadProjectConfig = (root) => {
         context: { maxChars },
         agentState,
         tracker: tracker(item.tracker),
-        mcp: mcp(item.mcp)
+        mcp: mcp(item.mcp),
+        loop: validateLoopConfig(item.loop)
     };
 };
 const readLocalProfile = (root, id) => {
@@ -183,7 +205,8 @@ export const resolveEffectiveConfig = (root, config) => {
         rules: { include: stable([...profiles.flatMap((item) => item.rules?.include ?? []), ...config.rules.include]) },
         risk: config.risk,
         context: config.context,
-        mcp: config.mcp
+        mcp: config.mcp,
+        loop: config.loop ?? { mode: "off" }
     };
 };
 export const includedRuleFiles = (root, patterns) => {

package/dist/src/state.d.ts

@@ -73,6 +73,13 @@ export interface NextAction {
     }>;
     reason: string;
 }
+export declare const readyTaskItems: (task: TaskState) => {
+    ready: string[];
+    blocked: Array<{
+        id: string;
+        waitingOn: string[];
+    }>;
+};
 export declare const nextAction: (task: TaskState, root?: string) => NextAction;
 export declare const handoffTask: (state: WorkflowState, id: string, kind: HandoffKind, reason: string, source: string, recordedAt?: string) => TaskState;
 export declare const closeTask: (state: WorkflowState, id: string, reason: string, source: string, recordedAt?: string) => TaskState;

package/dist/src/state.js

@@ -241,8 +241,11 @@ const validateTask = (id, task) => {
         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();
@@ -551,6 +554,48 @@ export const transitionTask = (state, id, target) => {
     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))}`;
@@ -579,9 +624,12 @@ export const nextAction = (task, root) => {
         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")
@@ -590,9 +638,12 @@ export const nextAction = (task, root) => {
         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` };
@@ -752,7 +803,7 @@ 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`;
+    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) {

package/dist/src/upgrade.d.ts

@@ -1,9 +1,9 @@
-import type { FileSpec, PlannedWrite, WorkflowState } from "./model.js";
+import type { FileSpec, LoopConfig, PlannedWrite, WorkflowState } from "./model.js";
 export declare const migrateLegacyBoard: (root: string) => {
     state: WorkflowState;
     files: FileSpec[];
 };
-export declare const planUpgrade: (root: string) => PlannedWrite[];
+export declare const planUpgrade: (root: string, loop?: LoopConfig) => PlannedWrite[];
 export interface UpgradeResult {
     backup: string;
     changed: number;