@felixdotgo/aidlc-kit 0.0.1 → 0.1.1

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);
@@ -20,11 +30,11 @@ export const readManifest = (root) => {
     try {
         const value = JSON.parse(readFileSync(path, "utf8"));
         const validFiles = value.files && typeof value.files === "object" && !Array.isArray(value.files) && Object.values(value.files).every((item) => item && typeof item.hash === "string" && typeof item.owner === "string" && ["replace", "managed-block"].includes(item.strategy));
-        return value.schemaVersion === 2 && typeof value.packageVersion === "string" && value.workflow === "AI-DLC" && value.source === "local-package-assets" && value.remoteUpdates === false && value.managedBy === "aidlc-workflow" && Array.isArray(value.adapters) && validFiles ? value : undefined;
+        return value.schemaVersion === 2 && typeof value.packageVersion === "string" && value.workflow === "AI-DLC" && value.source === "local-package-assets" && value.remoteUpdates === false && (value.managedBy === "aidlc-kit" || value.managedBy === "aidlc-workflow") && Array.isArray(value.adapters) && validFiles ? value : undefined;
     }
     catch {
         return undefined;
-    }
+    } /* intentional: a malformed manifest is treated as "not installed" */
 };
 export const detectedAgents = (root) => installableAdapters().filter((adapter) => adapter.detect(root)).map((adapter) => adapter.id);
 export const selectAgents = (options) => {
@@ -51,13 +61,54 @@ 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";
+};
+/** Merges a later owner of an already-planned shared managed-block path into the emitted entry. */
+const mergeIntoPlannedBlock = (root, previous, spec) => {
+    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";
+};
+/** Plans managed workflow files, the manifest, and project-owned files; later block owners merge in line. */
+const planManagedWrites = (root, files, 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, force, installed));
+        else
+            mergeIntoPlannedBlock(root, previous, spec);
+    }
+    return plan;
+};
+/** Plans an init transaction: managed workflow files, manifest, and project-owned files. */
 export const planInit = (options) => {
     const root = resolve(options.root);
     const installed = readManifest(root);
@@ -70,10 +121,12 @@ 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 = planManagedWrites(root, files, options.force, installed);
     planProjectLayoutMigration(root, plan);
+    planLoopSelection(plan, options.loop);
     return plan;
 };
+/** Applies a planned init/uninstall transaction to disk. */
 export const applyPlan = (root, plan) => {
     for (const write of plan.filter((item) => item.action === "delete"))
         rmSync(safeTarget(root, write.path), { force: true });
@@ -89,42 +142,98 @@ const hasOwnedManifest = (root) => {
     if (!existsSync(path))
         return false;
     try {
-        return JSON.parse(readFileSync(path, "utf8")).managedBy === "aidlc-workflow";
+        const parsed = JSON.parse(readFileSync(path, "utf8"));
+        return parsed.managedBy === "aidlc-kit" || parsed.managedBy === "aidlc-workflow";
     }
     catch {
         return false;
+    } /* intentional: a malformed/missing manifest is not owned */
+};
+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();
+};
+/** Maps one manifest inventory record onto its current spec and installed hash. */
+const uninstallEntry = (key, item, currentSpecs) => {
+    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 };
+};
+/** Groups installed specs (or all current specs without a manifest) by path; shared blocks carry multiple owners. */
+const uninstallGroups = (installed, currentSpecs) => {
+    const entries = installed ? Object.entries(installed.files).map(([key, item]) => uninstallEntry(key, item, currentSpecs)) : currentSpecs.map((spec) => ({ spec }));
+    const groups = new Map();
+    for (const entry of entries)
+        groups.set(entry.spec.path, [...(groups.get(entry.spec.path) ?? []), entry]);
+    return groups;
+};
+/** Removes each verified owner block from a shared file; stops at the first user-modified block. */
+const stripManagedBlocks = (group, current) => {
+    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);
+    }
+    return { next, modified };
+};
+/** Decides the plan entry for a whole-file (non shared-block) path. */
+const uninstallWholeFile = (group, exists, current) => {
+    if (!exists)
+        return { ...group[0].spec, action: "skip", reason: "not installed" };
+    if (!group.some((entry) => entry.spec.strategy === "managed-block")) {
+        const { spec, hash } = group[0];
+        const installedHash = hash ?? contentHash(spec.content);
+        return contentHash(current) === installedHash ? { ...spec, action: "delete", reason: "remove unchanged managed file" } : { ...spec, action: "preserve", reason: "managed file was modified" };
     }
+    const { next, modified } = stripManagedBlocks(group, current);
+    const legacyResidue = group.find(({ spec }) => next.includes(`<!-- aidlc-installer:${spec.owner} -->`));
+    const ownerSpec = group[0].spec;
+    if (modified)
+        return { ...modified, action: "preserve", reason: "managed block was modified" };
+    if (legacyResidue)
+        return { ...legacyResidue.spec, action: "preserve", reason: "legacy prompt marker requires manual removal" };
+    if (next === current)
+        return { ...ownerSpec, action: "skip", reason: "owned block not found" };
+    if (next)
+        return { ...ownerSpec, content: `${next}\n`, action: "update", reason: "remove owned prompt block" };
+    return { ...ownerSpec, content: "", action: "delete", reason: "remove owned prompt file" };
 };
+/** Keeps the ownership manifest only while modified managed files remain on disk. */
+const manifestDisposition = (plan) => {
+    const preserved = plan.some((item) => item.action === "preserve");
+    return { path: ".agents/aidlc/manifest.json", owner: "aidlc-core", content: "", ownershipClass: "managed", action: preserved ? "preserve" : "delete", reason: preserved ? "retained while modified managed files remain" : "remove ownership manifest" };
+};
+/** Plans an uninstall transaction that removes only unchanged managed assets. */
 export const planUninstall = (root) => {
     const project = resolve(root);
     if (!hasOwnedManifest(project))
-        throw new Error("No aidlc-workflow ownership manifest found; refusing to remove files.");
+        throw new Error("No managed ownership manifest (.agents/aidlc/manifest.json) 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 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" };
-    });
-    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" });
+    const plan = [];
+    for (const [path, group] of uninstallGroups(installed, currentSpecs)) {
+        const target = safeTarget(project, path);
+        const exists = existsSync(target);
+        plan.push(uninstallWholeFile(group, exists, exists ? readFileSync(target, "utf8") : ""));
+    }
+    plan.push(manifestDisposition(plan));
     return plan;
 };
+/** Reports installed workflow version, schema, and detected agents. */
 export const status = (root) => {
     const manifest = readManifest(root);
     const legacyPath = join(resolve(root), ".agents/aidlc/manifest.json");
@@ -135,6 +244,23 @@ export const status = (root) => {
         `detected agents: ${detectedAgents(root).join(", ") || "none"}`
     ].join("\n");
 };
+/** Path portion of a manifest inventory key (`path#owner` for shared managed blocks). */
+const inventoryKeyPath = (key) => {
+    const separator = key.lastIndexOf("#");
+    return separator > 0 ? key.slice(0, separator) : key;
+};
+/** Manifest inventory paths whose on-disk content no longer matches the recorded owner hash. */
+const modifiedManagedPaths = (root, manifest) => {
+    const modified = Object.entries(manifest.files).filter(([key, item]) => {
+        const target = safeTarget(root, inventoryKeyPath(key));
+        if (!existsSync(target))
+            return true;
+        const spec = { owner: item.owner, strategy: item.strategy };
+        return managedContentHash(spec, readFileSync(target, "utf8")) !== item.hash;
+    });
+    return [...new Set(modified.map(([key]) => inventoryKeyPath(key)))];
+};
+/** Validates the installed workflow manifest and local config/state. */
 export const doctor = (root, strict = false) => {
     const manifestPath = join(resolve(root), ".agents/aidlc/manifest.json");
     if (!existsSync(manifestPath))
@@ -146,7 +272,7 @@ export const doctor = (root, strict = false) => {
     catch {
         return "ERROR: workflow manifest is invalid JSON.";
     }
-    if (parsed.remoteUpdates || parsed.source !== "local-package-assets" || parsed.managedBy !== "aidlc-workflow")
+    if (parsed.remoteUpdates || parsed.source !== "local-package-assets" || (parsed.managedBy !== "aidlc-kit" && parsed.managedBy !== "aidlc-workflow"))
         return "ERROR: workflow manifest violates local-only asset policy.";
     if (typeof parsed.schemaVersion === "number" && parsed.schemaVersion > 2)
         return `ERROR: installed manifest schema ${parsed.schemaVersion} is newer than this CLI supports.`;
@@ -160,13 +286,7 @@ 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 = modifiedManagedPaths(root, manifest);
     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[];
@@ -238,7 +253,7 @@ export interface WorkflowManifest {
     workflow: "AI-DLC";
     source: "local-package-assets";
     remoteUpdates: false;
-    managedBy: "aidlc-workflow";
+    managedBy: "aidlc-kit" | "aidlc-workflow";
     adapters: AgentId[];
     files: Record<string, ManifestInventoryItem>;
 }

package/dist/src/model.js

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

package/dist/src/profiles.d.ts

@@ -1,9 +1,15 @@
-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>>;
+/** Validates and normalizes a loop-execution configuration block. */
+export declare const validateLoopConfig: (value: unknown) => LoopConfig;
+/** Validates a single profile file (built-in or local). */
 export declare const validateProfile: (value: unknown, label?: string) => Profile;
 export declare const defaultConfig: () => ProjectConfig;
+/** Loads and validates `.agents/config.json`, falling back to the default config when absent. */
 export declare const loadProjectConfig: (root: string) => ProjectConfig;
+/** Resolves a list of profile ids into an ordered, cycle-free list of profiles. */
 export declare const resolveProfiles: (root: string, ids: string[]) => Profile[];
+/** Merges built-in and local profiles with the project config into the effective configuration. */
 export declare const resolveEffectiveConfig: (root: string, config: ProjectConfig) => {
     profiles: Profile[];
     discovery: {
@@ -24,5 +30,7 @@ export declare const resolveEffectiveConfig: (root: string, config: ProjectConfi
         maxChars: number;
     };
     mcp: McpConfig;
+    loop: LoopConfig;
 };
+/** Expands rule include patterns into concrete markdown file paths inside the project. */
 export declare const includedRuleFiles: (root: string, patterns: string[]) => string[];

package/dist/src/profiles.js

@@ -1,5 +1,13 @@
+/**
+ * Project profiles and configuration. Loads `.agents/config.json`, validates
+ * every nested section (loop, tracker, MCP, risk, context), and resolves the
+ * effective configuration by merging built-in and local profiles.
+ */
 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 +28,24 @@ const object = (value, label) => {
         throw new Error(`${label} must be an object`);
     return value;
 };
+/** Validates and normalizes a loop-execution configuration block. */
+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`);
@@ -78,6 +104,7 @@ const mcp = (value) => {
         throw new Error("config.mcp.providers is invalid");
     return { enabled: true, endpoint: item.endpoint, workspace: item.workspace, ...(item.tokenEnv === undefined ? {} : { tokenEnv: item.tokenEnv }), ...(item.pollMs === undefined ? {} : { pollMs: Number(item.pollMs) }), ...(providers === undefined ? {} : { providers: providers }) };
 };
+/** Validates a single profile file (built-in or local). */
 export const validateProfile = (value, label = "profile") => {
     const item = object(value, label);
     if (item.schemaVersion !== 1 || typeof item.id !== "string" || !/^[A-Za-z0-9][A-Za-z0-9._/-]{0,127}$/.test(item.id) || typeof item.topology !== "string" || !/^[A-Za-z0-9][A-Za-z0-9._/-]{0,127}$/.test(item.topology))
@@ -108,8 +135,10 @@ export const defaultConfig = () => ({
     risk: { default: "normal" },
     context: { maxChars: 16_000 },
     agentState: {},
-    mcp: { enabled: false }
+    mcp: { enabled: false },
+    loop: { mode: "off" }
 });
+/** Loads and validates `.agents/config.json`, falling back to the default config when absent. */
 export const loadProjectConfig = (root) => {
     const path = join(resolve(root), ".agents/config.json");
     if (!existsSync(path))
@@ -140,7 +169,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) => {
@@ -151,6 +181,7 @@ const readLocalProfile = (root, id) => {
         throw new Error(`Profile escapes the project: ${id}`);
     return validateProfile(JSON.parse(readFileSync(path, "utf8")), id);
 };
+/** Resolves a list of profile ids into an ordered, cycle-free list of profiles. */
 export const resolveProfiles = (root, ids) => {
     const resolved = [];
     const visiting = new Set();
@@ -173,6 +204,7 @@ export const resolveProfiles = (root, ids) => {
     return resolved;
 };
 const stable = (values) => [...new Set(values)];
+/** Merges built-in and local profiles with the project config into the effective configuration. */
 export const resolveEffectiveConfig = (root, config) => {
     const profiles = resolveProfiles(root, config.extends);
     return {
@@ -183,9 +215,11 @@ 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" }
     };
 };
+/** Expands rule include patterns into concrete markdown file paths inside the project. */
 export const includedRuleFiles = (root, patterns) => {
     const project = resolve(root);
     const realProject = realpathSync(project);

package/dist/src/project-migration.d.ts

@@ -1,2 +1,3 @@
 import type { PlannedWrite } from "./model.js";
+/** Plans the full legacy-layout migration: config rewrite, `.aidlc/` tree, and legacy index files. */
 export declare const planProjectLayoutMigration: (project: string, plan: PlannedWrite[]) => void;

package/dist/src/project-migration.js

@@ -1,6 +1,7 @@
 import { existsSync, lstatSync, readFileSync, readdirSync } from "node:fs";
 import { resolveProjectPath } from "./project-path.js";
 const safePath = (root, relative) => resolveProjectPath(root, relative, "Unsafe migration path");
+/* Legacy `.aidlc/...` path translation into the canonical `.agents/` layout. */
 const legacyReference = (value) => {
     if (value === ".aidlc/config.json")
         return ".agents/config.json";
@@ -15,6 +16,7 @@ const legacyReference = (value) => {
     return value;
 };
 const rewriteStrings = (value) => Array.isArray(value) ? value.map((entry) => typeof entry === "string" ? legacyReference(entry) : entry) : value;
+/** Rewrites legacy `.aidlc/` path references inside the JSON file formats that are known to hold them. */
 const rewriteKnownJson = (relative, content) => {
     const isConfig = relative === "config.json";
     const isProfile = /^profiles\/.+\/profile\.json$/.test(relative);
@@ -63,6 +65,7 @@ const legacyDestination = (relative) => {
         return `.agents/data/index/${relative.slice("index/".length)}`;
     return `.agents/project/${relative}`;
 };
+/** Plans the copy of one legacy file into its destination, including a tracked delete of the source. */
 const planMigrationFile = (project, plan, sourcePath, destinationPath, legacyRelative) => {
     const source = safePath(project, sourcePath);
     const payload = migrationPayload(legacyRelative, readFileSync(source));
@@ -95,6 +98,7 @@ const planMigrationFile = (project, plan, sourcePath, destinationPath, legacyRel
         plan.push({ path: sourcePath, owner: "aidlc-project", ownershipClass: "project", content: "", action: "delete", reason: `remove migrated legacy project file after creating ${destinationPath}` });
     }
 };
+/** Walks the legacy `.aidlc/` tree, refusing symlinks and special entries with a conflicted plan entry. */
 const planLegacyTreeMigration = (project, plan) => {
     const legacyRoot = safePath(project, ".aidlc");
     if (!existsSync(legacyRoot))
@@ -118,6 +122,7 @@ const planLegacyTreeMigration = (project, plan) => {
     };
     visit(legacyRoot);
 };
+/** Rewrites legacy `.aidlc/` references inside an already-installed canonical project config. */
 const planExistingConfigRewrite = (project, plan) => {
     const path = ".agents/config.json";
     const target = safePath(project, path);
@@ -130,6 +135,7 @@ const planExistingConfigRewrite = (project, plan) => {
     if (item)
         Object.assign(item, { content: rewritten.content, action: "migrate", reason: "rewrite legacy .aidlc references in canonical project config" });
 };
+/** Moves the legacy `.agents/data/state/{repo-map,specs-index}` files into the data/index directory. */
 const planLegacyIndexMigration = (project, plan) => {
     for (const name of ["repo-map.md", "specs-index.md"]) {
         const source = `.agents/data/state/${name}`;
@@ -137,6 +143,7 @@ const planLegacyIndexMigration = (project, plan) => {
             planMigrationFile(project, plan, source, `.agents/data/index/${name}`, `index/${name}`);
     }
 };
+/** Plans the full legacy-layout migration: config rewrite, `.aidlc/` tree, and legacy index files. */
 export const planProjectLayoutMigration = (project, plan) => {
     planExistingConfigRewrite(project, plan);
     planLegacyTreeMigration(project, plan);

package/dist/src/state/archive.d.ts

@@ -0,0 +1,17 @@
+import type { LessonIndex, WorkflowState } from "../model.js";
+/** Marks pre-existing ready G2 waits during migration; the marker is the only exemption from repair-bound enforcement. */
+export declare const stampLegacyG2Waits: (state: WorkflowState) => string[];
+export declare const prepareV4Migration: (value: WorkflowState) => {
+    state: WorkflowState;
+    records: Array<{
+        path: string;
+        content: string;
+    }>;
+    lessonIndex: LessonIndex;
+    stamped: string[];
+};
+export declare const migrateState: (root: string, state?: WorkflowState) => {
+    migrated: boolean;
+    archived: string[];
+    stamped: string[];
+};

package/dist/src/state/archive.js

@@ -0,0 +1,60 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { createLessonIndex, lessonStateDigest, rebuildLessonIndex } from "./lessons.js";
+import { hasReview, hasVerification } from "./transitions.js";
+import { loadState, saveState } from "./store.js";
+import { validateState } from "./validate.js";
+import { archiveRecordPath, assertNoSymlinkPath, legacyG2WaitSource, taskRecordContent, terminal, writeAtomic, archivedSummary } from "./shared.js";
+/** Marks pre-existing ready G2 waits during migration; the marker is the only exemption from repair-bound enforcement. */
+export const stampLegacyG2Waits = (state) => {
+    const stamped = [];
+    for (const task of Object.values(state.tasks)) {
+        if (task.legacyG2Wait !== undefined)
+            continue;
+        if (task.phase !== "build" || task.gate !== "G2_codereview" || task.status !== "blocked_on_user")
+            continue;
+        if (!task.tasks.every((item) => item.status === "done" || item.status === "deferred") || !hasVerification(task) || !hasReview(task))
+            continue;
+        task.legacyG2Wait = { migratedAt: task.updatedAt, source: legacyG2WaitSource };
+        stamped.push(task.id);
+    }
+    return stamped;
+};
+export const prepareV4Migration = (value) => {
+    const source = validateState(value);
+    const next = { schemaVersion: 4, tasks: {}, archive: {} };
+    const records = [];
+    for (const task of Object.values(source.tasks)) {
+        if (!terminal(task))
+            next.tasks[task.id] = task;
+        else {
+            const content = taskRecordContent(task);
+            next.archive[task.id] = archivedSummary(task, content);
+            records.push({ path: archiveRecordPath(task.id), content });
+        }
+    }
+    for (const item of Object.values(source.archive ?? {}))
+        next.archive[item.id] = item;
+    const stamped = Number(source.schemaVersion) < 4 ? stampLegacyG2Waits(next) : [];
+    validateState(next);
+    const lessons = Object.values(source.tasks).flatMap((task) => task.lessons ?? []);
+    return { state: next, records, lessonIndex: createLessonIndex(lessons, lessonStateDigest(next)), stamped };
+};
+export const migrateState = (root, state = loadState(root)) => {
+    if (state.schemaVersion === 4)
+        return { migrated: false, archived: [], stamped: [] };
+    const migration = prepareV4Migration(state);
+    for (const record of migration.records) {
+        assertNoSymlinkPath(root, record.path);
+        const path = join(resolve(root), record.path);
+        if (existsSync(path)) {
+            if (readFileSync(path, "utf8") !== record.content)
+                throw new Error(`Archived task record conflicts: ${record.path}`);
+        }
+        else
+            writeAtomic(path, record.content);
+    }
+    saveState(root, migration.state);
+    rebuildLessonIndex(root, migration.state);
+    return { migrated: true, archived: Object.keys(migration.state.archive ?? {}), stamped: migration.stamped };
+};

package/dist/src/state/items.d.ts

@@ -0,0 +1,25 @@
+import type { Gate, Phase, TaskState } from "../model.js";
+export interface NextAction {
+    classification: "await_user" | "run_phase" | "blocked" | "terminal" | "complete";
+    phase: Phase;
+    gate: Gate;
+    command?: string;
+    outcome?: "closed" | "superseded";
+    successorTaskId?: string;
+    itemId?: string;
+    remainingItems?: number;
+    actions?: Array<{
+        id: "reopen_g1" | "create_successor" | "supersede" | "close" | "record_handoff" | "resume";
+        command: string;
+    }>;
+    reason: string;
+}
+/** Validates execution dependencies and reports which pending items are ready to dispatch. */
+export declare const readyTaskItems: (task: TaskState) => {
+    ready: string[];
+    blocked: Array<{
+        id: string;
+        waitingOn: string[];
+    }>;
+};
+export declare const nextAction: (task: TaskState, root?: string) => NextAction;