@felixdotgo/aidlc-kit 0.1.1 → 0.3.0

package/dist/src/state/memory.js

@@ -1,10 +1,22 @@
-import { existsSync } from "node:fs";
+import { idPattern, iso, text } from "./guards.js";
+import { loadJsonOr, saveJson } from "./io.js";
+import { memoryRegistryPathRelative } from "./paths.js";
 import { loadState, loadTask } from "./store.js";
-import { assertNoSymlinkPath, idPattern, iso, memoryRegistryPath, parseJsonFile, text, writeAtomic } from "./shared.js";
 const memoryPhases = ["clarify", "plan", "build", "wrap", "*"];
 const validateMemoryEntry = (entry) => {
-    if (!entry || !idPattern.test(entry.id) || !text(entry.summary) || !text(entry.guidance) || !Array.isArray(entry.areas) || !entry.areas.length || entry.areas.some((area) => !text(area)) || !Array.isArray(entry.phases) || !entry.phases.length || entry.phases.some((phase) => !memoryPhases.includes(phase)) || !Number.isInteger(entry.priority) || entry.priority < 0 || entry.priority > 100 || !idPattern.test(entry.sourceTaskId) || !idPattern.test(entry.sourceLessonId) || !text(entry.approvedBy) || !iso(entry.approvedAt))
-        throw new Error(`Invalid agentic memory entry: ${entry?.id ?? "unknown"}`);
+    const id = entry?.id ?? "unknown";
+    if (!entry)
+        throw new Error(`Invalid agentic memory entry: ${id}`);
+    if (!idPattern.test(entry.id) || !text(entry.summary) || !text(entry.guidance))
+        throw new Error(`Invalid agentic memory entry: ${id}`);
+    if (!Array.isArray(entry.areas) || !entry.areas.length || entry.areas.some((area) => !text(area)))
+        throw new Error(`Invalid agentic memory entry: ${id}`);
+    if (!Array.isArray(entry.phases) || !entry.phases.length || entry.phases.some((phase) => !memoryPhases.includes(phase)))
+        throw new Error(`Invalid agentic memory entry: ${id}`);
+    if (!Number.isInteger(entry.priority) || entry.priority < 0 || entry.priority > 100)
+        throw new Error(`Invalid agentic memory entry: ${id}`);
+    if (!idPattern.test(entry.sourceTaskId) || !idPattern.test(entry.sourceLessonId) || !text(entry.approvedBy) || !iso(entry.approvedAt))
+        throw new Error(`Invalid agentic memory entry: ${id}`);
 };
 export const emptyMemoryRegistry = () => ({ schemaVersion: 1, entries: [], retired: [] });
 export const validateMemoryRegistry = (value) => {
@@ -30,19 +42,17 @@ export const validateMemoryRegistry = (value) => {
     }
     return registry;
 };
-const registryPathRelative = ".agents/data/memory/agentic-memory.json";
-export const loadMemoryRegistry = (root) => {
-    assertNoSymlinkPath(root, registryPathRelative);
-    return existsSync(memoryRegistryPath(root)) ? validateMemoryRegistry(parseJsonFile(memoryRegistryPath(root), "Agentic memory registry")) : emptyMemoryRegistry();
-};
+export const loadMemoryRegistry = (root) => loadJsonOr(root, memoryRegistryPathRelative, validateMemoryRegistry, emptyMemoryRegistry, "Agentic memory registry");
 export const saveMemoryRegistry = (root, registry) => {
     const normalized = validateMemoryRegistry(registry);
-    assertNoSymlinkPath(root, registryPathRelative);
-    writeAtomic(memoryRegistryPath(root), `${JSON.stringify(normalized, null, 2)}\n`);
+    saveJson(root, memoryRegistryPathRelative, normalized);
 };
 export const selectAgenticMemory = (registry, areas, phase, maxChars) => {
     const areaSet = new Set(areas.map((area) => area.toLocaleLowerCase()));
-    const matches = registry.entries.filter((entry) => entry.phases.includes("*") || entry.phases.includes(phase)).filter((entry) => entry.areas.includes("*") || entry.areas.some((area) => areaSet.has(area.toLocaleLowerCase()))).sort((left, right) => right.priority - left.priority || left.id.localeCompare(right.id));
+    const matches = registry.entries
+        .filter((entry) => entry.phases.includes("*") || entry.phases.includes(phase))
+        .filter((entry) => entry.areas.includes("*") || entry.areas.some((area) => areaSet.has(area.toLocaleLowerCase())))
+        .sort((left, right) => right.priority - left.priority || left.id.localeCompare(right.id));
     const selected = [];
     let used = 0;
     for (const entry of matches) {
@@ -81,6 +91,8 @@ export const retireAgenticMemory = (root, id, reason, retiredBy, retiredAt = new
     if (index < 0)
         throw new Error(`Unknown active agentic memory entry: ${id}`);
     const [entry] = registry.entries.splice(index, 1);
+    if (!entry)
+        throw new Error(`Unknown active agentic memory entry: ${id}`);
     registry.retired.push({ ...entry, retiredBy, retiredAt, reason });
     registry.retired.sort((left, right) => right.retiredAt.localeCompare(left.retiredAt) || left.id.localeCompare(right.id));
     saveMemoryRegistry(root, registry);

package/dist/src/state/{archive.js → migrate.js}

@@ -1,10 +1,11 @@
 import { existsSync, readFileSync } from "node:fs";
-import { join, resolve } from "node:path";
+import { buildArchiveRecord } from "./archive-record.js";
+import { legacyG2WaitSource, terminal } from "./domain.js";
+import { safeResolvedPath, writeAtomic } from "./io.js";
 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 = [];
@@ -28,9 +29,9 @@ export const prepareV4Migration = (value) => {
         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 });
+            const { content, summary } = buildArchiveRecord(task);
+            next.archive[task.id] = summary;
+            records.push({ path: summary.record, content });
         }
     }
     for (const item of Object.values(source.archive ?? {}))
@@ -45,8 +46,7 @@ export const migrateState = (root, state = loadState(root)) => {
         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);
+        const path = safeResolvedPath(root, record.path);
         if (existsSync(path)) {
             if (readFileSync(path, "utf8") !== record.content)
                 throw new Error(`Archived task record conflicts: ${record.path}`);

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

@@ -0,0 +1,15 @@
+import type { Diagnostic, TaskState } from "../model.js";
+type Item = TaskState["tasks"][number];
+export declare const pathOverlaps: (left: string, right: string) => boolean;
+export declare const pathsOverlap: (left?: readonly string[], right?: readonly string[]) => boolean;
+/** Pairs of open (not done/deferred) items that are not ordered by `dependsOn`. */
+export declare const concurrentItemPairs: (task: TaskState) => Array<[Item, Item]>;
+/** Approve-plan partition check. `strict` (enabled loop) makes findings ERRORs; otherwise WARNs. */
+export declare const partitionDiagnostics: (task: TaskState, { strict }?: {
+    strict?: boolean;
+}) => Diagnostic[];
+/** Strict when `loop.mode` is local/fleet or inside a fleet-enabled coordination service; a missing config is `off`; an unreadable one fails closed. */
+export declare const loopPartitionStrict: (root: string | undefined) => boolean;
+/** ` — owns: a, b · after: x` suffix for a rendered workplan line. */
+export declare const workplanScope: (item: Item) => string;
+export {};

package/dist/src/state/partition.js

@@ -0,0 +1,90 @@
+/**
+ * Parallel work partition checks, mirroring `assets/aidlc/scripts/lib/store.mjs`
+ * (`pathOverlaps`, `pathsOverlap`, `concurrentItemPairs`, `partitionDiagnostics`,
+ * `loopPartitionStrict`). Owned paths overlap by path segment (`a` overlaps
+ * `a/b`, not `ab`); two open items can run concurrently unless one is a direct
+ * or transitive dependency of the other.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+const ownedPathKey = (path) => String(path).replace(/\/+$/, "");
+export const pathOverlaps = (left, right) => {
+    const a = ownedPathKey(left);
+    const b = ownedPathKey(right);
+    return a === b || a.startsWith(`${b}/`) || b.startsWith(`${a}/`);
+};
+export const pathsOverlap = (left = [], right = []) => left.some((a) => right.some((b) => pathOverlaps(a, b)));
+const itemAncestors = (task) => {
+    const byId = new Map(task.tasks.map((item) => [item.id, item]));
+    const memo = new Map();
+    const walk = (id, trail = new Set()) => {
+        const cached = memo.get(id);
+        if (cached)
+            return cached;
+        const found = new Set();
+        if (trail.has(id))
+            return found;
+        trail.add(id);
+        for (const dep of byId.get(id)?.dependsOn ?? []) {
+            if (!byId.has(dep))
+                continue;
+            found.add(dep);
+            for (const deeper of walk(dep, trail))
+                found.add(deeper);
+        }
+        trail.delete(id);
+        memo.set(id, found);
+        return found;
+    };
+    return (id) => walk(id);
+};
+/** Pairs of open (not done/deferred) items that are not ordered by `dependsOn`. */
+export const concurrentItemPairs = (task) => {
+    const open = task.tasks.filter((item) => item.status !== "done" && item.status !== "deferred");
+    const ancestors = itemAncestors(task);
+    const pairs = [];
+    for (let i = 0; i < open.length; i += 1)
+        for (let j = i + 1; j < open.length; j += 1) {
+            const a = open[i];
+            const b = open[j];
+            if (!ancestors(a.id).has(b.id) && !ancestors(b.id).has(a.id))
+                pairs.push([a, b]);
+        }
+    return pairs;
+};
+/** Approve-plan partition check. `strict` (enabled loop) makes findings ERRORs; otherwise WARNs. */
+export const partitionDiagnostics = (task, { strict = true } = {}) => {
+    const level = strict ? "ERROR" : "WARN";
+    const diagnostics = [];
+    const unscoped = task.tasks.filter((item) => item.status !== "done" && item.status !== "deferred" && !(Array.isArray(item.ownedPaths) && item.ownedPaths.length));
+    if (unscoped.length)
+        diagnostics.push({ level, code: "PARTITION_SCOPE", message: `Build items need owned paths (--owns) for parallel workers: ${unscoped.map((item) => item.id).join(", ")}` });
+    for (const [a, b] of concurrentItemPairs(task)) {
+        const shared = (a.ownedPaths ?? []).filter((path) => (b.ownedPaths ?? []).some((other) => pathOverlaps(path, other)));
+        if (shared.length)
+            diagnostics.push({ level, code: "PARTITION_OVERLAP", message: `Items ${a.id} and ${b.id} can run concurrently but both own ${shared.join(", ")}; split the paths or add --depends-on` });
+    }
+    return diagnostics;
+};
+/** Strict when `loop.mode` is local/fleet or inside a fleet-enabled coordination service; a missing config is `off`; an unreadable one fails closed. */
+export const loopPartitionStrict = (root) => {
+    if (process.env["MCP_FLEET_ENABLED"] === "1")
+        return true;
+    if (root === undefined)
+        return false;
+    const path = join(resolve(root), ".agents", "config.json");
+    if (!existsSync(path))
+        return false;
+    try {
+        const mode = JSON.parse(readFileSync(path, "utf8"))?.loop?.mode;
+        return mode === "local" || mode === "fleet";
+    }
+    catch {
+        return true;
+    }
+};
+/** ` — owns: a, b · after: x` suffix for a rendered workplan line. */
+export const workplanScope = (item) => {
+    const parts = [item.ownedPaths?.length ? `owns: ${item.ownedPaths.join(", ")}` : "", item.dependsOn?.length ? `after: ${item.dependsOn.join(", ")}` : ""].filter(Boolean);
+    return parts.length ? ` — ${parts.join(" · ")}` : "";
+};

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

@@ -0,0 +1,11 @@
+export declare const statePathRelative = ".agents/data/state/aidlc-state.json";
+export declare const lessonIndexPathRelative = ".agents/data/lessons/index.json";
+export declare const memoryRegistryPathRelative = ".agents/data/memory/agentic-memory.json";
+export declare const stateLockPathRelative = ".agents/data/state/.aidlc-state.lock";
+export declare const stateLockGuardPathRelative = ".agents/data/state/.aidlc-state.lock.guard";
+export declare const statePath: (root: string) => string;
+export declare const lessonIndexPath: (root: string) => string;
+export declare const memoryRegistryPath: (root: string) => string;
+export declare const stateLockPath: (root: string) => string;
+export declare const stateLockGuardPath: (root: string) => string;
+export declare const archiveRecordPath: (id: string) => string;

package/dist/src/state/paths.js

@@ -0,0 +1,12 @@
+import { join, resolve } from "node:path";
+export const statePathRelative = ".agents/data/state/aidlc-state.json";
+export const lessonIndexPathRelative = ".agents/data/lessons/index.json";
+export const memoryRegistryPathRelative = ".agents/data/memory/agentic-memory.json";
+export const stateLockPathRelative = ".agents/data/state/.aidlc-state.lock";
+export const stateLockGuardPathRelative = ".agents/data/state/.aidlc-state.lock.guard";
+export const statePath = (root) => join(resolve(root), statePathRelative);
+export const lessonIndexPath = (root) => join(resolve(root), lessonIndexPathRelative);
+export const memoryRegistryPath = (root) => join(resolve(root), memoryRegistryPathRelative);
+export const stateLockPath = (root) => join(resolve(root), stateLockPathRelative);
+export const stateLockGuardPath = (root) => join(resolve(root), stateLockGuardPathRelative);
+export const archiveRecordPath = (id) => `.agents/data/state/archive/${id}.json`;

package/dist/src/state/render.js

@@ -1,12 +1,16 @@
-import { join, resolve } from "node:path";
+import { tokens } from "./guards.js";
+import { safeResolvedPath, writeAtomic } from "./io.js";
 import { loadState } from "./store.js";
-import { assertNoSymlinkPath, tokens, writeAtomic } from "./shared.js";
+import { workplanScope } from "./partition.js";
 export const listTaskSummaries = (state, options = {}) => {
     const active = Object.values(state.tasks).map((task) => ({ id: task.id, title: task.title, phase: task.phase, gate: task.gate, status: task.status, risk: task.risk, areas: task.areas, updatedAt: task.updatedAt, source: "active" }));
     const archived = options.includeArchive ? Object.values(state.archive ?? {}).map((task) => ({ id: task.id, title: task.title, phase: task.phase, gate: task.gate, status: task.status, risk: task.risk, areas: task.areas, updatedAt: task.updatedAt, source: "archive" })) : [];
     const queryTokens = tokens(options.query ?? "");
     const statuses = new Set(options.statuses ?? []);
-    const filtered = [...active, ...archived].filter((item) => (!statuses.size || statuses.has(item.status)) && (!queryTokens.length || queryTokens.every((token) => tokens(`${item.id} ${item.title} ${item.areas.join(" ")}`).includes(token)))).sort((a, b) => b.updatedAt.localeCompare(a.updatedAt) || a.id.localeCompare(b.id));
+    const filtered = [...active, ...archived]
+        .filter((item) => (!statuses.size || statuses.has(item.status)) &&
+        (!queryTokens.length || queryTokens.every((token) => tokens(`${item.id} ${item.title} ${item.areas.join(" ")}`).includes(token))))
+        .sort((a, b) => b.updatedAt.localeCompare(a.updatedAt) || a.id.localeCompare(b.id));
     const cursor = Math.max(0, options.cursor ?? 0);
     const limit = Math.max(1, Math.min(options.limit ?? 20, 100));
     const items = filtered.slice(cursor, cursor + limit);
@@ -15,7 +19,7 @@ export const listTaskSummaries = (state, options = {}) => {
 /** Renders the markdown workplan for a task. */
 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 tasks = task.tasks.length ? task.tasks.map((item) => `- [${item.status === "done" ? "x" : item.status === "in_progress" ? "~" : " "}] ${item.id} — ${item.label}${workplanScope(item)}`).join("\n") : "- None";
     const lifecycle = [`- Status: \`${task.status}\``, task.handoff ? `- Handoff: \`${task.handoff.kind}\` — ${task.handoff.reason}` : "", task.closure ? `- Closure: ${task.closure.reason}` : "", task.predecessorTaskId ? `- Predecessor: \`${task.predecessorTaskId}\`` : "", task.successorTaskId ? `- Successor: \`${task.successorTaskId}\`` : "", task.lessonDisposition ? `- Lessons: \`${task.lessonDisposition.status}\`` : ""].filter(Boolean).join("\n");
     return `# Workplan — ${task.title} (\`${task.id}\`)\n\n> Generated from canonical JSON state.\n\n## Lifecycle\n${lifecycle}\n\n## 🧩 Decisions (Approve plan — before implementation)\n${decisions}\n\n## 🧩 Tasks (Review implementation — work items)\n${tasks}\n`;
 };
@@ -23,7 +27,6 @@ export const renderViews = (root, state = loadState(root), selected = Object.val
     for (const task of selected) {
         if (!task.artifacts.workplan)
             continue;
-        assertNoSymlinkPath(root, task.artifacts.workplan);
-        writeAtomic(join(resolve(root), task.artifacts.workplan), renderWorkplan(task));
+        writeAtomic(safeResolvedPath(root, task.artifacts.workplan), renderWorkplan(task));
     }
 };

package/dist/src/state/store.js

@@ -1,20 +1,17 @@
 import { existsSync, readFileSync } from "node:fs";
-import { join, resolve } from "node:path";
+import { buildArchiveRecord } from "./archive-record.js";
+import { digest, emptyState, terminal } from "./domain.js";
+import { loadJsonOr, parseJsonText, safeResolvedPath, saveJson, writeAtomic } from "./io.js";
+import { statePath, statePathRelative } from "./paths.js";
 import { validateState, validateTask } from "./validate.js";
-import { assertNoSymlinkPath, digest, emptyState, parseJsonFile, parseJsonText, statePath, taskRecordContent, terminal, writeAtomic, archivedSummary } from "./shared.js";
-export const loadState = (root) => {
-    const path = statePath(root);
-    assertNoSymlinkPath(root, ".agents/data/state/aidlc-state.json");
-    return existsSync(path) ? validateState(parseJsonFile(path, "AI-DLC state file", "restore it from git history or the archive records")) : emptyState();
-};
+export const loadState = (root) => loadJsonOr(root, statePathRelative, validateState, emptyState, "AI-DLC state file", "restore it from git history or the archive records");
 export const loadTask = (root, id, state = loadState(root)) => {
     if (state.tasks[id])
         return state.tasks[id];
     const summary = state.archive?.[id];
     if (!summary)
         return undefined;
-    const path = join(resolve(root), summary.record);
-    assertNoSymlinkPath(root, summary.record);
+    const path = safeResolvedPath(root, summary.record);
     if (!existsSync(path))
         throw new Error(`Archived task record is missing: ${summary.record}`);
     const content = readFileSync(path, "utf8");
@@ -32,10 +29,8 @@ const archiveTerminalTasks = (normalized, persisted, root) => {
     for (const task of Object.values(normalized.tasks)) {
         if (!terminal(task))
             continue;
-        const content = taskRecordContent(task);
-        const summary = archivedSummary(task, content);
-        const path = join(resolve(root), summary.record);
-        assertNoSymlinkPath(root, summary.record);
+        const { content, summary } = buildArchiveRecord(task);
+        const path = safeResolvedPath(root, summary.record);
         if (existsSync(path)) {
             const current = readFileSync(path, "utf8");
             if (digest(current) !== summary.digest)
@@ -72,8 +67,7 @@ export const saveState = (root, state) => {
     const archived = normalized.schemaVersion >= 3 ? archiveTerminalTasks(normalized, persisted, root) : [];
     if (normalized.schemaVersion >= 3)
         validateState(normalized);
-    assertNoSymlinkPath(root, ".agents/data/state/aidlc-state.json");
-    writeAtomic(statePath(root), `${JSON.stringify(normalized, null, 2)}\n`);
+    saveJson(root, statePathRelative, normalized);
     state.tasks = normalized.tasks;
     state.archive = normalized.archive;
     state.schemaVersion = normalized.schemaVersion;

package/dist/src/state/transitions.js

@@ -1,8 +1,8 @@
-import { phases, phaseGate, terminal } from "./shared.js";
+import { phaseGate, phases, terminal } from "./domain.js";
 export const latestApproval = (task, gate) => {
     for (let index = task.evidence.length - 1; index >= 0; index -= 1) {
         const item = task.evidence[index];
-        if (item.kind === "approval" && item.gate === gate)
+        if (item && item.kind === "approval" && item.gate === gate)
             return item;
     }
     return undefined;
@@ -12,7 +12,7 @@ export const buildBoundary = (task) => {
     let boundary;
     for (let index = 0; index < task.evidence.length; index += 1) {
         const item = task.evidence[index];
-        if (item.kind === "approval" && item.gate === "G1_review" && item.result === "pass")
+        if (item && item.kind === "approval" && item.gate === "G1_review" && item.result === "pass")
             boundary = index;
     }
     return boundary;
@@ -23,9 +23,11 @@ const currentBuildEvidence = (task) => {
     return boundary === undefined ? [] : task.evidence.slice(boundary + 1);
 };
 const latestInOrder = (items, predicate) => {
-    for (let index = items.length - 1; index >= 0; index -= 1)
-        if (predicate(items[index]))
-            return items[index];
+    for (let index = items.length - 1; index >= 0; index -= 1) {
+        const item = items[index];
+        if (item && predicate(item))
+            return item;
+    }
     return undefined;
 };
 export const hasCurrentBuildApproval = (task, gate) => latestInOrder(currentBuildEvidence(task), (item) => item.kind === "approval" && item.gate === gate)?.result === "pass";
@@ -45,7 +47,7 @@ export const repairBounds = (task) => {
             verifyFailures[area] = (verifyFailures[area] ?? 0) + 1;
         }
     const reviewFailures = evidence.filter((item) => item.kind === "review" && item.result === "fail").length;
-    const exhaustedAreas = Object.keys(verifyFailures).filter((area) => verifyFailures[area] >= 3).sort();
+    const exhaustedAreas = Object.keys(verifyFailures).filter((area) => (verifyFailures[area] ?? 0) >= 3).sort();
     return { verifyFailures, reviewFailures, exhaustedAreas, verifyExhausted: exhaustedAreas.length > 0, reviewExhausted: reviewFailures >= 2 };
 };
 /** True only for a migration-stamped legacy G2 wait that is still fully ready; the stamp is written exclusively by schema migration. */

package/dist/src/state/validate.js

@@ -1,8 +1,20 @@
+import { gates, handoffKinds, phaseGate, phases } from "./domain.js";
+import { assertTaskArtifactPath, idPattern, iso, text } from "./guards.js";
 import { readyTaskItems } from "./items.js";
-import { assertTaskArtifactPath, gates, handoffKinds, idPattern, iso, phases, phaseGate, text } from "./shared.js";
+import { archiveRecordPath } from "./paths.js";
 const taskStatuses = ["active", "blocked_on_user", "paused", "done", "closed", "superseded"];
+const commitPattern = /^[0-9a-f]{7,64}$/;
+const commitFields = ["baseCommit", "finalCommit"];
 export const validateLesson = (taskId, lesson) => {
-    if (!lesson || !idPattern.test(lesson.id) || lesson.taskId !== taskId || !Array.isArray(lesson.areas) || !lesson.areas.length || lesson.areas.some((area) => !text(area)) || !text(lesson.summary) || !text(lesson.prevention) || !text(lesson.example) || !text(lesson.promotion) || !text(lesson.source) || !iso(lesson.recordedAt))
+    if (!lesson)
+        throw new Error(`Invalid lesson: ${taskId}`);
+    if (!idPattern.test(lesson.id) || lesson.taskId !== taskId)
+        throw new Error(`Invalid lesson: ${taskId}`);
+    if (!Array.isArray(lesson.areas) || !lesson.areas.length || lesson.areas.some((area) => !text(area)))
+        throw new Error(`Invalid lesson: ${taskId}`);
+    if (!text(lesson.summary) || !text(lesson.prevention) || !text(lesson.example))
+        throw new Error(`Invalid lesson: ${taskId}`);
+    if (!text(lesson.promotion) || !text(lesson.source) || !iso(lesson.recordedAt))
         throw new Error(`Invalid lesson: ${taskId}`);
 };
 export const validateTask = (id, task) => {
@@ -23,7 +35,13 @@ export const validateTask = (id, task) => {
     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"))))
+    if (task.evidence.some((item) => !["approval", "spec", "test", "lint", "review", "diagnostic"].includes(item.kind) ||
+        !["pass", "fail", "skip"].includes(item.result) ||
+        !item.source ||
+        !iso(item.recordedAt) ||
+        (item.area !== undefined && !text(item.area)) ||
+        (item.gate !== undefined && !gates.includes(item.gate)) ||
+        (item.kind === "approval" && (!item.gate || item.gate === "none"))))
         throw new Error(`Invalid evidence: ${id}`);
     const lessonIds = new Set();
     for (const lesson of task.lessons ?? []) {
@@ -32,11 +50,21 @@ export const validateTask = (id, task) => {
             throw new Error(`Duplicate lesson id: ${id}/${lesson.id}`);
         lessonIds.add(lesson.id);
     }
-    if (task.lessonDisposition && (!["captured", "none"].includes(task.lessonDisposition.status) || !text(task.lessonDisposition.source) || !iso(task.lessonDisposition.recordedAt) || (task.lessonDisposition.status === "captured" && !(task.lessons?.length)) || (task.lessonDisposition.status === "none" && (Boolean(task.lessons?.length) || !text(task.lessonDisposition.reason)))))
+    if (task.lessonDisposition && (!["captured", "none"].includes(task.lessonDisposition.status) ||
+        !text(task.lessonDisposition.source) ||
+        !iso(task.lessonDisposition.recordedAt) ||
+        (task.lessonDisposition.status === "captured" && !(task.lessons?.length)) ||
+        (task.lessonDisposition.status === "none" && (Boolean(task.lessons?.length) || !text(task.lessonDisposition.reason)))))
         throw new Error(`Invalid lesson disposition: ${id}`);
     if (task.handoff && (!handoffKinds.includes(task.handoff.kind) || !text(task.handoff.reason) || !text(task.handoff.source) || !iso(task.handoff.recordedAt) || task.status !== "paused"))
         throw new Error(`Invalid task handoff: ${id}`);
-    if (task.legacyG2Wait !== undefined && (typeof task.legacyG2Wait !== "object" || Array.isArray(task.legacyG2Wait) || !iso(task.legacyG2Wait.migratedAt) || !text(task.legacyG2Wait.source) || task.phase !== "build" || task.gate !== "G2_codereview" || task.status !== "blocked_on_user"))
+    if (task.legacyG2Wait !== undefined && (typeof task.legacyG2Wait !== "object" ||
+        Array.isArray(task.legacyG2Wait) ||
+        !iso(task.legacyG2Wait.migratedAt) ||
+        !text(task.legacyG2Wait.source) ||
+        task.phase !== "build" ||
+        task.gate !== "G2_codereview" ||
+        task.status !== "blocked_on_user"))
         throw new Error(`Invalid legacy G2 wait marker: ${id}`);
     if ((task.status === "closed" || task.status === "superseded") !== Boolean(task.closure))
         throw new Error(`Invalid task closure: ${id}`);
@@ -46,12 +74,29 @@ export const validateTask = (id, task) => {
         throw new Error(`Invalid task successor: ${id}`);
     if (task.predecessorTaskId !== undefined && !text(task.predecessorTaskId))
         throw new Error(`Invalid task predecessor: ${id}`);
+    for (const field of commitFields)
+        if (task[field] !== undefined && !(typeof task[field] === "string" && commitPattern.test(task[field])))
+            throw new Error(`Invalid task ${field}: ${id}`);
     for (const path of Object.values(task.artifacts))
         if (path)
             assertTaskArtifactPath(id, path);
 };
 const validateArchiveSummary = (id, item) => {
-    if (!idPattern.test(id) || !item || item.id !== id || !text(item.title) || !["feature", "bug", "refactor", "infra"].includes(item.type) || !phases.includes(item.phase) || !gates.includes(item.gate) || item.gate !== phaseGate(item.phase) || !["done", "closed", "superseded"].includes(item.status) || !["low", "normal", "high", "regulated"].includes(item.risk) || !Array.isArray(item.areas) || !item.areas.length || item.areas.some((area) => !text(area)) || item.record !== `.agents/data/state/archive/${id}.json` || !/^[a-f0-9]{64}$/.test(item.digest) || !Number.isInteger(item.lessonCount) || item.lessonCount < 0 || !iso(item.createdAt) || !iso(item.updatedAt))
+    if (!idPattern.test(id))
+        throw new Error(`Invalid archived task summary: ${id}`);
+    if (!item || item.id !== id || !text(item.title))
+        throw new Error(`Invalid archived task summary: ${id}`);
+    if (!["feature", "bug", "refactor", "infra"].includes(item.type))
+        throw new Error(`Invalid archived task summary: ${id}`);
+    if (!phases.includes(item.phase) || !gates.includes(item.gate) || item.gate !== phaseGate(item.phase))
+        throw new Error(`Invalid archived task summary: ${id}`);
+    if (!["done", "closed", "superseded"].includes(item.status) || !["low", "normal", "high", "regulated"].includes(item.risk))
+        throw new Error(`Invalid archived task summary: ${id}`);
+    if (!Array.isArray(item.areas) || !item.areas.length || item.areas.some((area) => !text(area)))
+        throw new Error(`Invalid archived task summary: ${id}`);
+    if (item.record !== archiveRecordPath(id) || !/^[a-f0-9]{64}$/.test(item.digest))
+        throw new Error(`Invalid archived task summary: ${id}`);
+    if (!Number.isInteger(item.lessonCount) || item.lessonCount < 0 || !iso(item.createdAt) || !iso(item.updatedAt))
         throw new Error(`Invalid archived task summary: ${id}`);
     if ((item.status === "superseded") !== Boolean(item.successorTaskId) || (item.status === "closed" && item.successorTaskId) || (item.predecessorTaskId !== undefined && !text(item.predecessorTaskId)))
         throw new Error(`Invalid archived task links: ${id}`);
@@ -93,7 +138,10 @@ export const validateState = (value) => {
             if (seen.has(cursor.successorTaskId))
                 throw new Error(`Cyclic successor link: ${id}`);
             seen.add(cursor.successorTaskId);
-            cursor = references[cursor.successorTaskId];
+            const next = references[cursor.successorTaskId];
+            if (!next)
+                throw new Error(`Invalid successor link: ${id}`);
+            cursor = next;
         }
     }
     return state;

package/dist/src/state.d.ts

@@ -2,14 +2,19 @@
  * Facade for the lifecycle-state domain. Behavior-preserving re-export of the
  * split modules under `src/state/`; import paths from outside remain unchanged.
  */
-export * from "./state/shared.js";
-export * from "./state/lock.js";
-export * from "./state/items.js";
-export * from "./state/transitions.js";
-export * from "./state/validate.js";
-export * from "./state/store.js";
-export * from "./state/memory.js";
-export * from "./state/lessons.js";
-export * from "./state/archive.js";
-export * from "./state/lifecycle.js";
-export * from "./state/render.js";
+export { stampLegacyG2Waits, prepareV4Migration, migrateState } from "./state/migrate.js";
+export { taskRecordContent, archivedSummary } from "./state/archive-record.js";
+export { emptyState, legacyG2WaitSource, phases, gates, handoffKinds, terminal, phaseGate, digest } from "./state/domain.js";
+export { iso, text, idPattern, audited, tokens, assertTaskArtifactPath } from "./state/guards.js";
+export { assertNoSymlinkPath, writeAtomic, parseJsonText, parseJsonFile } from "./state/io.js";
+export { type NextAction, readyTaskItems, nextAction } from "./state/items.js";
+export { recordLesson, recordNoLessons, lessonStateDigest, createLessonIndex, rebuildLessonIndex, searchLessons } from "./state/lessons.js";
+export { handoffTask, closeTask, supersedeTask, reopenTask } from "./state/lifecycle.js";
+export { type StateLockOptions, acquireStateLock } from "./state/lock.js";
+export { emptyMemoryRegistry, validateMemoryRegistry, loadMemoryRegistry, saveMemoryRegistry, selectAgenticMemory, promoteAgenticMemory, retireAgenticMemory } from "./state/memory.js";
+export { statePath, lessonIndexPath, memoryRegistryPath, stateLockPath, stateLockGuardPath, archiveRecordPath } from "./state/paths.js";
+export { type TaskSummary, listTaskSummaries, renderWorkplan, renderViews } from "./state/render.js";
+export { pathOverlaps, pathsOverlap, concurrentItemPairs, partitionDiagnostics, loopPartitionStrict, workplanScope } from "./state/partition.js";
+export { loadState, loadTask, saveState } from "./state/store.js";
+export { latestApproval, buildBoundary, hasApproval, hasCurrentBuildApproval, hasAreaVerification, hasVerification, hasReview, type RepairBounds, repairBounds, isLegacyG2Wait, transitionDiagnostics, transitionTask } from "./state/transitions.js";
+export { validateLesson, validateTask, validateState } from "./state/validate.js";

package/dist/src/state.js

@@ -2,14 +2,19 @@
  * Facade for the lifecycle-state domain. Behavior-preserving re-export of the
  * split modules under `src/state/`; import paths from outside remain unchanged.
  */
-export * from "./state/shared.js";
-export * from "./state/lock.js";
-export * from "./state/items.js";
-export * from "./state/transitions.js";
-export * from "./state/validate.js";
-export * from "./state/store.js";
-export * from "./state/memory.js";
-export * from "./state/lessons.js";
-export * from "./state/archive.js";
-export * from "./state/lifecycle.js";
-export * from "./state/render.js";
+export { stampLegacyG2Waits, prepareV4Migration, migrateState } from "./state/migrate.js";
+export { taskRecordContent, archivedSummary } from "./state/archive-record.js";
+export { emptyState, legacyG2WaitSource, phases, gates, handoffKinds, terminal, phaseGate, digest } from "./state/domain.js";
+export { iso, text, idPattern, audited, tokens, assertTaskArtifactPath } from "./state/guards.js";
+export { assertNoSymlinkPath, writeAtomic, parseJsonText, parseJsonFile } from "./state/io.js";
+export { readyTaskItems, nextAction } from "./state/items.js";
+export { recordLesson, recordNoLessons, lessonStateDigest, createLessonIndex, rebuildLessonIndex, searchLessons } from "./state/lessons.js";
+export { handoffTask, closeTask, supersedeTask, reopenTask } from "./state/lifecycle.js";
+export { acquireStateLock } from "./state/lock.js";
+export { emptyMemoryRegistry, validateMemoryRegistry, loadMemoryRegistry, saveMemoryRegistry, selectAgenticMemory, promoteAgenticMemory, retireAgenticMemory } from "./state/memory.js";
+export { statePath, lessonIndexPath, memoryRegistryPath, stateLockPath, stateLockGuardPath, archiveRecordPath } from "./state/paths.js";
+export { listTaskSummaries, renderWorkplan, renderViews } from "./state/render.js";
+export { pathOverlaps, pathsOverlap, concurrentItemPairs, partitionDiagnostics, loopPartitionStrict, workplanScope } from "./state/partition.js";
+export { loadState, loadTask, saveState } from "./state/store.js";
+export { latestApproval, buildBoundary, hasApproval, hasCurrentBuildApproval, hasAreaVerification, hasVerification, hasReview, repairBounds, isLegacyG2Wait, transitionDiagnostics, transitionTask } from "./state/transitions.js";
+export { validateLesson, validateTask, validateState } from "./state/validate.js";

package/dist/src/task-ui.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Local web UI for the AI-DLC loop and task status.
+ *
+ * Read-only over canonical local state (`.agents/data/state/aidlc-state.json`).
+ * Loop start/resume are thin facades that spawn the installed `loop-entry.mjs`
+ * exactly as `aidlc-kit loop` does; gate approval is a thin facade that spawns
+ * the same atomic `state.mjs gate approve` command, and gate feedback spawns the
+ * audited `state.mjs task status … --status active --mode audited` cancel (the
+ * task stays at its gate; the loop lead revises and re-presents it). This module
+ * never mutates lifecycle state itself and never bypasses the fail-closed gate
+ * channel.
+ *
+ * Built on `node:http` only; Bulma CSS, the dashboard theme layer, and the
+ * client scripts are vendored static assets (no CDN, no runtime npm dependency).
+ * The dashboard has no session credential (it runs on trusted local/LAN
+ * networks); mutating actions (loop start/resume, gate feedback, gate approve)
+ * are protected by request-shape guards instead: a pinned Host header, a
+ * matching Origin, Sec-Fetch-Site, and a custom request header that forces a
+ * CORS preflight (see `./ui/security.ts`). Fleet gate approval additionally
+ * needs the reviewer credential (`AIDLC_FLEET_REVIEWER_TOKEN` or
+ * `--reviewer-token-file`), which reaches only the approve child process.
+ *
+ * The implementation lives in `./ui/` (see `./ui/server.ts` for the route
+ * table); this module is the stable public entry point.
+ */
+export { openBrowser, readCredentialFile, resolveUiMode, scrubbedEnv, type UiAuthorityMode, type UiOptions } from "./ui/options.js";
+export { requestAllowed } from "./ui/security.js";
+export { daemonHealth, daemonStatus, stopDaemon, type DaemonError, type DaemonStatus, type StopResult } from "./ui/daemon.js";
+export { markdownToHtml } from "./ui/markdown.js";
+export { NOTIFY_PAGE } from "./ui/views/layout.js";
+export { DONE_COLUMN_LIMIT } from "./ui/views/board.js";
+export { SSE_REPLAY_LINES } from "./ui/sse.js";
+export { createUiHandler, startUiServer } from "./ui/server.js";

package/dist/src/task-ui.js

@@ -0,0 +1,33 @@
+/**
+ * Local web UI for the AI-DLC loop and task status.
+ *
+ * Read-only over canonical local state (`.agents/data/state/aidlc-state.json`).
+ * Loop start/resume are thin facades that spawn the installed `loop-entry.mjs`
+ * exactly as `aidlc-kit loop` does; gate approval is a thin facade that spawns
+ * the same atomic `state.mjs gate approve` command, and gate feedback spawns the
+ * audited `state.mjs task status … --status active --mode audited` cancel (the
+ * task stays at its gate; the loop lead revises and re-presents it). This module
+ * never mutates lifecycle state itself and never bypasses the fail-closed gate
+ * channel.
+ *
+ * Built on `node:http` only; Bulma CSS, the dashboard theme layer, and the
+ * client scripts are vendored static assets (no CDN, no runtime npm dependency).
+ * The dashboard has no session credential (it runs on trusted local/LAN
+ * networks); mutating actions (loop start/resume, gate feedback, gate approve)
+ * are protected by request-shape guards instead: a pinned Host header, a
+ * matching Origin, Sec-Fetch-Site, and a custom request header that forces a
+ * CORS preflight (see `./ui/security.ts`). Fleet gate approval additionally
+ * needs the reviewer credential (`AIDLC_FLEET_REVIEWER_TOKEN` or
+ * `--reviewer-token-file`), which reaches only the approve child process.
+ *
+ * The implementation lives in `./ui/` (see `./ui/server.ts` for the route
+ * table); this module is the stable public entry point.
+ */
+export { openBrowser, readCredentialFile, resolveUiMode, scrubbedEnv } from "./ui/options.js";
+export { requestAllowed } from "./ui/security.js";
+export { daemonHealth, daemonStatus, stopDaemon } from "./ui/daemon.js";
+export { markdownToHtml } from "./ui/markdown.js";
+export { NOTIFY_PAGE } from "./ui/views/layout.js";
+export { DONE_COLUMN_LIMIT } from "./ui/views/board.js";
+export { SSE_REPLAY_LINES } from "./ui/sse.js";
+export { createUiHandler, startUiServer } from "./ui/server.js";

package/dist/src/ui/assets.d.ts

@@ -0,0 +1,14 @@
+/** Client scripts, loaded as classic scripts in this order: `common` first, page scripts after. */
+export type ClientScript = "common" | "dashboard" | "detail" | "live-log" | "changes";
+/** The whitelisted asset for a request path, or undefined (the caller answers 404). */
+export declare const staticAsset: (route: string) => {
+    contentType: string;
+    body: string;
+} | undefined;
+/** Stylesheets served from `/assets`, loaded in this order. */
+export type Stylesheet = "bulma" | "dashboard";
+/** `<script src>` for a client script; `?v=<content hash>` makes an upgrade bust the browser cache. */
+export declare const scriptTag: (name: ClientScript) => string;
+/** `<link rel="stylesheet">` for a stylesheet, versioned like `scriptTag` so an upgrade is not
+ * stuck behind the cached theme while the hashed scripts already changed. */
+export declare const stylesheetTag: (name: Stylesheet) => string;