@felixdotgo/aidlc-kit 0.1.0 → 0.1.1

package/dist/src/gate.js

@@ -11,7 +11,7 @@ const artifactContent = (root, path) => {
     }
     catch {
         return undefined;
-    }
+    } /* intentional: unreadable/unsafe artifact is treated as absent */
 };
 const artifactDiagnostics = (root, task, names) => names.flatMap((name) => {
     const path = task.artifacts[name];
@@ -24,10 +24,39 @@ const artifactDiagnostics = (root, task, names) => names.flatMap((name) => {
         return [{ level: "ERROR", code: "ARTIFACT_UNSAFE", message: error instanceof Error ? error.message : String(error) }];
     }
 });
-export const checkGate = (root, state, taskId, gate) => {
-    const task = state.tasks[taskId];
-    if (!task)
-        return [{ level: "ERROR", code: "TASK_UNKNOWN", message: `Unknown task: ${taskId}` }];
+const missingHeadings = (content, headings) => headings.filter((heading) => !content.includes(heading));
+const confirmGateDiagnostics = (root, task) => {
+    const diagnostics = artifactDiagnostics(root, task, ["intent"]);
+    const content = artifactContent(root, task.artifacts.intent);
+    if (content !== undefined)
+        for (const heading of missingHeadings(content, ["## 📋 Problem", "## 🗺️ Affected areas", "## 💭 Assumptions", "## ❓ Open questions", "## 🎯 Scope"]))
+            diagnostics.push({ level: "ERROR", code: "INTENT_HEADING", message: `Intent is missing ${heading}` });
+    return diagnostics;
+};
+const reviewGateDiagnostics = (root, task) => {
+    const diagnostics = artifactDiagnostics(root, task, ["intent", "design", "workplan"]);
+    diagnostics.push(...transitionDiagnostics(task, "build").filter((item) => item.code === "UNRESOLVED_DECISION"));
+    const content = artifactContent(root, task.artifacts.design);
+    if (content !== undefined)
+        for (const heading of missingHeadings(content, ["## 🧩 Solution per affected area", "## 📌 Spec traceability", "## 🔗 Cross-service contracts", "## ⚠️ Risks / edge cases"]))
+            diagnostics.push({ level: "ERROR", code: "DESIGN_HEADING", message: `Design is missing ${heading}` });
+    return diagnostics;
+};
+const codeReviewGateDiagnostics = (root, task) => {
+    const diagnostics = artifactDiagnostics(root, task, ["intent", "design", "workplan"]);
+    if (task.tasks.some((item) => item.status !== "done" && item.status !== "deferred"))
+        diagnostics.push({ level: "ERROR", code: "TASKS_OPEN", message: "Build tasks remain open" });
+    for (const area of task.areas)
+        if (!hasAreaVerification(task, area))
+            diagnostics.push({ level: "ERROR", code: "VERIFY_EVIDENCE", message: `Latest post-G1 verification evidence must pass for affected area: ${area}` });
+    if (!hasReview(task))
+        diagnostics.push({ level: "ERROR", code: "REVIEW_EVIDENCE", message: "Latest post-G1 review evidence must pass" });
+    const bounds = repairBounds(task);
+    if (!isLegacyG2Wait(task) && (bounds.verifyExhausted || bounds.reviewExhausted))
+        diagnostics.push({ level: "ERROR", code: "REPAIR_BOUND", message: "Repair bound exhausted; record a durable handoff instead of presenting G2" });
+    return diagnostics;
+};
+const generalGateDiagnostics = (taskId, task, gate) => {
     const diagnostics = [];
     if (task.gate !== gate)
         diagnostics.push({ level: "ERROR", code: "GATE_STATE", message: `Task is at ${task.gate}, not ${gate}` });
@@ -39,36 +68,20 @@ export const checkGate = (root, state, taskId, gate) => {
         diagnostics.push({ level: "ERROR", code: "TASK_ID", message: "Task key and id differ" });
     if (!task.title.trim() || !task.areas.length)
         diagnostics.push({ level: "ERROR", code: "TASK_FIELDS", message: "Task title and affected areas are required" });
-    if (gate === "G0_confirm") {
-        diagnostics.push(...artifactDiagnostics(root, task, ["intent"]));
-        const content = artifactContent(root, task.artifacts.intent);
-        if (content !== undefined)
-            for (const heading of ["## 📋 Problem", "## 🗺️ Affected areas", "## 💭 Assumptions", "## ❓ Open questions", "## 🎯 Scope"])
-                if (!content.includes(heading))
-                    diagnostics.push({ level: "ERROR", code: "INTENT_HEADING", message: `Intent is missing ${heading}` });
-    }
-    if (gate === "G1_review") {
-        diagnostics.push(...artifactDiagnostics(root, task, ["intent", "design", "workplan"]));
-        diagnostics.push(...transitionDiagnostics(task, "build").filter((item) => item.code === "UNRESOLVED_DECISION"));
-        const content = artifactContent(root, task.artifacts.design);
-        if (content !== undefined)
-            for (const heading of ["## 🧩 Solution per affected area", "## 📌 Spec traceability", "## 🔗 Cross-service contracts", "## ⚠️ Risks / edge cases"])
-                if (!content.includes(heading))
-                    diagnostics.push({ level: "ERROR", code: "DESIGN_HEADING", message: `Design is missing ${heading}` });
-    }
-    if (gate === "G2_codereview") {
-        diagnostics.push(...artifactDiagnostics(root, task, ["intent", "design", "workplan"]));
-        if (task.tasks.some((item) => item.status !== "done" && item.status !== "deferred"))
-            diagnostics.push({ level: "ERROR", code: "TASKS_OPEN", message: "Build tasks remain open" });
-        for (const area of task.areas)
-            if (!hasAreaVerification(task, area))
-                diagnostics.push({ level: "ERROR", code: "VERIFY_EVIDENCE", message: `Latest post-G1 verification evidence must pass for affected area: ${area}` });
-        if (!hasReview(task))
-            diagnostics.push({ level: "ERROR", code: "REVIEW_EVIDENCE", message: "Latest post-G1 review evidence must pass" });
-        const bounds = repairBounds(task);
-        if (!isLegacyG2Wait(task) && (bounds.verifyExhausted || bounds.reviewExhausted))
-            diagnostics.push({ level: "ERROR", code: "REPAIR_BOUND", message: "Repair bound exhausted; record a durable handoff instead of presenting G2" });
-    }
+    return diagnostics;
+};
+/** Runs all diagnostics for a gate and returns them (empty-ish with GATE_OK when clean). */
+export const checkGate = (root, state, taskId, gate) => {
+    const task = state.tasks[taskId];
+    if (!task)
+        return [{ level: "ERROR", code: "TASK_UNKNOWN", message: `Unknown task: ${taskId}` }];
+    const diagnostics = generalGateDiagnostics(taskId, task, gate);
+    if (gate === "G0_confirm")
+        diagnostics.push(...confirmGateDiagnostics(root, task));
+    if (gate === "G1_review")
+        diagnostics.push(...reviewGateDiagnostics(root, task));
+    if (gate === "G2_codereview")
+        diagnostics.push(...codeReviewGateDiagnostics(root, task));
     if (!diagnostics.length)
         diagnostics.push({ level: "INFO", code: "GATE_OK", message: `${gate} checks passed for ${taskId}` });
     return diagnostics;

package/dist/src/installer.d.ts

@@ -7,9 +7,14 @@ 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;
+/** Plans an init transaction: managed workflow files, manifest, and project-owned files. */
 export declare const planInit: (options: InitOptions) => PlannedWrite[];
+/** Applies a planned init/uninstall transaction to disk. */
 export declare const applyPlan: (root: string, plan: PlannedWrite[]) => void;
 export declare const formatPlan: (plan: PlannedWrite[]) => string;
+/** Plans an uninstall transaction that removes only unchanged managed assets. */
 export declare const planUninstall: (root: string) => PlannedWrite[];
+/** Reports installed workflow version, schema, and detected agents. */
 export declare const status: (root: string) => string;
+/** Validates the installed workflow manifest and local config/state. */
 export declare const doctor: (root: string, strict?: boolean) => string;

package/dist/src/installer.js

@@ -30,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) => {
@@ -88,6 +88,27 @@ export const planLoopSelection = (plan, selection) => {
     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);
@@ -100,23 +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 = [];
-    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";
-    }
+    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 });
@@ -132,82 +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 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) {
+    for (const [path, group] of uninstallGroups(installed, currentSpecs)) {
         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;
-        }
-        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(uninstallWholeFile(group, exists, exists ? readFileSync(target, "utf8") : ""));
     }
-    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" });
+    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");
@@ -218,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))
@@ -229,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.`;
@@ -243,14 +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 = [...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))];
+    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/model.d.ts

@@ -253,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/profiles.d.ts

@@ -1,10 +1,15 @@
 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: {
@@ -27,4 +32,5 @@ export declare const resolveEffectiveConfig: (root: string, config: ProjectConfi
     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,3 +1,8 @@
+/**
+ * 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";
@@ -23,6 +28,7 @@ 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" };
@@ -98,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))
@@ -131,6 +138,7 @@ export const defaultConfig = () => ({
     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))
@@ -173,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();
@@ -195,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 {
@@ -209,6 +219,7 @@ export const resolveEffectiveConfig = (root, config) => {
         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 };
+};