@felixdotgo/aidlc-kit 0.1.1 → 0.2.0

package/dist/src/state/items.js

@@ -1,7 +1,6 @@
-import { isAbsolute, join, resolve } from "node:path";
+import { isAbsolute } from "node:path";
+import { commandKit } from "./commands.js";
 import { hasReview, hasVerification, isLegacyG2Wait, repairBounds } from "./transitions.js";
-const rootSuffix = (root) => root === undefined ? "" : ` --root ${JSON.stringify(resolve(root))}`;
-const script = (root, name) => root === undefined ? `node .agents/aidlc/scripts/${name}` : `node ${JSON.stringify(join(resolve(root), ".agents/aidlc/scripts", name))}`;
 const isPending = (item) => item.status === "in_progress" || item.status === "todo";
 const pendingItems = (task) => task.tasks.filter(isPending);
 /** Validates execution dependencies and reports which pending items are ready to dispatch. */
@@ -28,7 +27,15 @@ export const readyTaskItems = (task) => {
     for (const item of task.tasks) {
         if (item.dependsOn !== undefined && (!Array.isArray(item.dependsOn) || new Set(item.dependsOn).size !== item.dependsOn.length || item.dependsOn.some((dep) => typeof dep !== "string" || !dep)))
             throw new Error(`Invalid execution dependencies: ${task.id}/${item.id}`);
-        if (item.ownedPaths !== undefined && (!Array.isArray(item.ownedPaths) || new Set(item.ownedPaths).size !== item.ownedPaths.length || item.ownedPaths.some((path) => typeof path !== "string" || !path || isAbsolute(path) || path === ".." || path.startsWith("../") || path.includes("\\") || path.split("/").includes(".."))))
+        if (item.ownedPaths !== undefined && (!Array.isArray(item.ownedPaths) ||
+            new Set(item.ownedPaths).size !== item.ownedPaths.length ||
+            item.ownedPaths.some((path) => typeof path !== "string" ||
+                !path ||
+                isAbsolute(path) ||
+                path === ".." ||
+                path.startsWith("../") ||
+                path.includes("\\") ||
+                path.split("/").includes(".."))))
             throw new Error(`Invalid owned paths: ${task.id}/${item.id}`);
         visit(item.id);
     }
@@ -52,50 +59,27 @@ const dispatchableItem = (open, task) => {
     return open.find((entry) => entry.status === "in_progress" && ready.has(entry.id)) ?? open.find((entry) => ready.has(entry.id));
 };
 const noReadyItemReason = (task) => `No dependency-ready build item: ${readyTaskItems(task).blocked.map((entry) => `${entry.id} waits for ${entry.waitingOn.join(",")}`).join("; ")}`;
-const handoffActions = (task, suffix, stateCommand) => [
-    ...(task.phase === "build" ? [{ id: "reopen_g1", command: `${stateCommand} task reopen ${task.id} --to plan --reason <reason> --source <explicit-user-request>${suffix}` }] : []),
-    { id: "create_successor", command: `${stateCommand} task create <new-task-id> --title <title>${suffix}` },
-    { id: "supersede", command: `${stateCommand} task supersede ${task.id} --successor <new-task-id> --reason <reason> --source <explicit-user-request>${suffix}` },
-    { id: "close", command: `${stateCommand} task close ${task.id} --reason <reason> --source <explicit-user-request>${suffix}` }
-];
-const pausedActions = (task, suffix, stateCommand) => [
-    { id: "resume", command: `${stateCommand} task status ${task.id} --status active${suffix}` },
-    { id: "record_handoff", command: `${stateCommand} task handoff ${task.id} --kind <kind> --reason <reason> --source <source>${suffix}` }
-];
-const repairExhausted = (task, suffix, stateCommand) => {
+const repairExhausted = (task) => {
     if (task.phase !== "build" || isLegacyG2Wait(task))
         return undefined;
     const bounds = repairBounds(task);
     if (!bounds.verifyExhausted && !bounds.reviewExhausted)
         return undefined;
-    const kind = bounds.reviewExhausted ? "review_exhausted" : "repair_exhausted";
+    const handoffKind = bounds.reviewExhausted ? "review_exhausted" : "repair_exhausted";
     const detail = bounds.verifyExhausted ? `3+ failed verify cycles in: ${bounds.exhaustedAreas.join(", ")}` : `${bounds.reviewFailures} failed review passes`;
-    return {
-        classification: "blocked",
-        phase: task.phase,
-        gate: task.gate,
-        reason: `Repair bound exhausted (${detail}); record a durable handoff`,
-        actions: [{ id: "record_handoff", command: `${stateCommand} task handoff ${task.id} --kind ${kind} --reason <summary-of-exhausted-repairs> --source <agent>${suffix}` }]
-    };
+    return { kind: "repair_exhausted", handoffKind, reason: `Repair bound exhausted (${detail}); record a durable handoff` };
 };
-const continueItem = (item, openCount, task, suffix, contextCommand, premature) => ({
-    classification: "run_phase",
-    phase: task.phase,
-    gate: task.gate,
+const continueItem = (item, openCount, premature) => ({
+    kind: "continue_item",
     itemId: item.id,
     remainingItems: openCount,
-    command: `${contextCommand} ${task.id} --phase build --item ${item.id}${suffix}`,
     reason: premature ? `Invalid premature G2 wait; continue build item ${item.id}` : `Continue build item ${item.id}; ${openCount} actionable item(s) remain before verification, review, and G2`
 });
-const continueVerification = (task, suffix, contextCommand, premature) => ({
-    classification: "run_phase",
-    phase: task.phase,
-    gate: task.gate,
-    remainingItems: 0,
-    command: `${contextCommand} ${task.id} --phase build${suffix}`,
+const continueVerification = (premature) => ({
+    kind: "continue_verification",
     reason: premature ? "Invalid premature G2 wait; continue verification and adversarial review before presenting G2" : "All build items are terminal; continue verification, adversarial review, and G2 preparation"
 });
-const prematureG2Wait = (task, suffix, contextCommand) => {
+const prematureG2Wait = (task) => {
     if (task.status !== "blocked_on_user" || task.gate !== "G2_codereview")
         return undefined;
     if (!(task.tasks.some((item) => !["done", "deferred"].includes(item.status)) || !hasVerification(task) || !hasReview(task)))
@@ -103,44 +87,61 @@ const prematureG2Wait = (task, suffix, contextCommand) => {
     const open = pendingItems(task);
     const item = dispatchableItem(open, task);
     if (item)
-        return continueItem(item, open.length, task, suffix, contextCommand, true);
+        return continueItem(item, open.length, true);
     if (open.length)
-        return { classification: "blocked", phase: task.phase, gate: task.gate, reason: noReadyItemReason(task) };
-    return continueVerification(task, suffix, contextCommand, true);
+        return { kind: "no_ready_item", reason: noReadyItemReason(task) };
+    return continueVerification(true);
 };
-export const nextAction = (task, root) => {
-    const suffix = rootSuffix(root);
-    const stateCommand = script(root, "state.mjs");
-    const contextCommand = script(root, "context.mjs");
+/** Pure classification: maps a task onto its next-action decision without touching any command string. */
+const classify = (task) => {
     if (task.phase === "done")
-        return { classification: "complete", phase: task.phase, gate: task.gate, reason: "Task is complete" };
+        return { kind: "complete", reason: "Task is complete" };
     if (task.status === "closed" || task.status === "superseded")
-        return { classification: "terminal", phase: task.phase, gate: task.gate, outcome: task.status, successorTaskId: task.successorTaskId, reason: task.closure?.reason ?? "Task ended without successful completion" };
+        return { kind: "terminal", outcome: task.status, successorTaskId: task.successorTaskId, reason: task.closure?.reason ?? "Task ended without successful completion" };
     if (task.handoff)
-        return { classification: "blocked", phase: task.phase, gate: task.gate, reason: task.handoff.reason, actions: handoffActions(task, suffix, stateCommand) };
+        return { kind: "handoff", reason: task.handoff.reason };
     if (task.status === "paused")
-        return { classification: "blocked", phase: task.phase, gate: task.gate, reason: "Task is paused", actions: pausedActions(task, suffix, stateCommand) };
-    const repair = repairExhausted(task, suffix, stateCommand);
+        return { kind: "paused", reason: "Task is paused" };
+    const repair = repairExhausted(task);
     if (repair)
         return repair;
-    const prematureG2 = prematureG2Wait(task, suffix, contextCommand);
+    const prematureG2 = prematureG2Wait(task);
     if (prematureG2)
         return prematureG2;
-    if (task.status === "blocked_on_user" && task.gate === "G1_review" && task.decisions.some((decision) => decision.status === "unresolved")) {
-        return { classification: "run_phase", phase: task.phase, gate: task.gate, command: `${contextCommand} ${task.id} --phase plan${suffix}`, reason: "Invalid premature G1 wait; resolve every decision before presenting G1" };
-    }
+    if (task.status === "blocked_on_user" && task.gate === "G1_review" && task.decisions.some((decision) => decision.status === "unresolved"))
+        return { kind: "recover_g1_wait", reason: "Invalid premature G1 wait; resolve every decision before presenting G1" };
     if (task.status === "blocked_on_user" && task.gate === "none")
-        return { classification: "run_phase", phase: task.phase, gate: task.gate, command: `${stateCommand} task status ${task.id} --status active${suffix}`, reason: "Recover invalid wait at a gateless wrap phase before continuing wrap" };
+        return { kind: "recover_gateless_wrap", reason: "Recover invalid wait at a gateless wrap phase before continuing wrap" };
     if (task.status === "blocked_on_user")
-        return { classification: "await_user", phase: task.phase, gate: task.gate, command: `${stateCommand} gate approve ${task.id} --gate ${task.gate} --source <explicit-user-approval>${suffix}`, reason: `Explicit human approval is required at ${task.gate}` };
+        return { kind: "await_user", reason: `Explicit human approval is required at ${task.gate}` };
     if (task.phase === "build") {
         const open = pendingItems(task);
         const item = dispatchableItem(open, task);
         if (item)
-            return continueItem(item, open.length, task, suffix, contextCommand, false);
+            return continueItem(item, open.length, false);
         if (open.length)
-            return { classification: "blocked", phase: task.phase, gate: task.gate, reason: noReadyItemReason(task) };
-        return continueVerification(task, suffix, contextCommand, false);
+            return { kind: "no_ready_item", reason: noReadyItemReason(task) };
+        return continueVerification(false);
+    }
+    return { kind: "continue_phase", reason: `Continue ${task.phase} until the next human gate, real blocker, or completion` };
+};
+/** Attaches the command strings a decision implies; the single call site of the command kit. */
+const realize = (task, decision, commands) => {
+    const base = { phase: task.phase, gate: task.gate };
+    switch (decision.kind) {
+        case "complete": return { classification: "complete", ...base, reason: decision.reason };
+        case "terminal": return { classification: "terminal", ...base, outcome: decision.outcome, successorTaskId: decision.successorTaskId, reason: decision.reason };
+        case "handoff": return { classification: "blocked", ...base, reason: decision.reason, actions: commands.handoffActions(task) };
+        case "paused": return { classification: "blocked", ...base, reason: decision.reason, actions: commands.pausedActions(task.id) };
+        case "repair_exhausted": return { classification: "blocked", ...base, reason: decision.reason, actions: commands.repairHandoffAction(task.id, decision.handoffKind) };
+        case "continue_item": return { classification: "run_phase", ...base, itemId: decision.itemId, remainingItems: decision.remainingItems, command: commands.continueItem(task.id, decision.itemId), reason: decision.reason };
+        case "continue_verification": return { classification: "run_phase", ...base, remainingItems: 0, command: commands.continueVerification(task.id), reason: decision.reason };
+        case "no_ready_item": return { classification: "blocked", ...base, reason: decision.reason };
+        case "recover_g1_wait": return { classification: "run_phase", ...base, command: commands.recoverG1Wait(task.id), reason: decision.reason };
+        case "recover_gateless_wrap": return { classification: "run_phase", ...base, command: commands.recoverGatelessWrap(task.id), reason: decision.reason };
+        case "await_user": return { classification: "await_user", ...base, command: commands.approveGate(task.id, task.gate), reason: decision.reason };
+        case "continue_phase": return { classification: "run_phase", ...base, command: commands.continuePhase(task.id, task.phase), reason: decision.reason };
     }
-    return { classification: "run_phase", phase: task.phase, gate: task.gate, command: `${contextCommand} ${task.id} --phase ${task.phase}${suffix}`, reason: `Continue ${task.phase} until the next human gate, real blocker, or completion` };
 };
+/** Classifies the next lifecycle action for a task and attaches root-qualified command strings. */
+export const nextAction = (task, root) => realize(task, classify(task), commandKit(root));

package/dist/src/state/lessons.js

@@ -1,7 +1,10 @@
 import { existsSync } from "node:fs";
-import { validateLesson } from "./validate.js";
+import { digest } from "./domain.js";
+import { audited, tokens } from "./guards.js";
+import { assertNoSymlinkPath, parseJsonFile, saveJson } from "./io.js";
+import { lessonIndexPath, lessonIndexPathRelative } from "./paths.js";
 import { loadState, loadTask } from "./store.js";
-import { assertNoSymlinkPath, audited, digest, lessonIndexPath, parseJsonFile, tokens, writeAtomic } from "./shared.js";
+import { validateLesson } from "./validate.js";
 const lessonEntry = (lesson) => ({ id: lesson.id, taskId: lesson.taskId, areas: lesson.areas, summary: lesson.summary, prevention: lesson.prevention, source: lesson.source, recordedAt: lesson.recordedAt });
 export const recordLesson = (task, lesson, recordedAt = new Date().toISOString()) => {
     if (task.phase !== "wrap" || task.status !== "active")
@@ -40,13 +43,12 @@ const allLessons = (root, state) => [
 ];
 export const rebuildLessonIndex = (root, state = loadState(root)) => {
     const index = createLessonIndex(allLessons(root, state), lessonStateDigest(state));
-    assertNoSymlinkPath(root, ".agents/data/lessons/index.json");
-    writeAtomic(lessonIndexPath(root), `${JSON.stringify(index, null, 2)}\n`);
+    saveJson(root, lessonIndexPathRelative, index);
     return index;
 };
 export const searchLessons = (root, state, query, areas = [], limit = 5) => {
     const path = lessonIndexPath(root);
-    assertNoSymlinkPath(root, ".agents/data/lessons/index.json");
+    assertNoSymlinkPath(root, lessonIndexPathRelative);
     if (!existsSync(path)) {
         const hasLessons = Object.values(state.tasks).some((task) => Boolean(task.lessons?.length)) || Object.values(state.archive ?? {}).some((task) => task.lessonCount > 0);
         if (!hasLessons)
@@ -58,10 +60,15 @@ export const searchLessons = (root, state, query, areas = [], limit = 5) => {
         throw new Error("Lesson index is stale; run state.mjs lesson rebuild");
     const queryTokens = tokens(query);
     const areaSet = new Set(areas.map((area) => area.toLocaleLowerCase()));
-    return index.lessons.map((item) => {
+    return index.lessons
+        .map((item) => {
         const haystack = new Set(tokens(`${item.summary} ${item.prevention} ${item.taskId} ${item.areas.join(" ")}`));
         const areaScore = item.areas.some((area) => areaSet.has(area.toLocaleLowerCase())) ? 100 : 0;
         const tokenScore = queryTokens.filter((token) => haystack.has(token)).length;
         return { item, score: areaScore + tokenScore };
-    }).filter(({ score }) => score > 0 || (!queryTokens.length && !areaSet.size)).sort((a, b) => b.score - a.score || b.item.recordedAt.localeCompare(a.item.recordedAt)).slice(0, Math.max(1, Math.min(limit, 20))).map(({ item }) => item);
+    })
+        .filter(({ score }) => score > 0 || (!queryTokens.length && !areaSet.size))
+        .sort((a, b) => b.score - a.score || b.item.recordedAt.localeCompare(a.item.recordedAt))
+        .slice(0, Math.max(1, Math.min(limit, 20)))
+        .map(({ item }) => item);
 };

package/dist/src/state/lifecycle.js

@@ -1,7 +1,7 @@
-import { handoffKinds } from "./shared.js";
+import { handoffKinds, terminal } from "./domain.js";
+import { audited } from "./guards.js";
 import { hasApproval } from "./transitions.js";
 import { validateState } from "./validate.js";
-import { audited, terminal } from "./shared.js";
 export const handoffTask = (state, id, kind, reason, source, recordedAt = new Date().toISOString()) => {
     const task = state.tasks[id];
     if (!task || terminal(task) || !handoffKinds.includes(kind))

package/dist/src/state/lock.js

@@ -1,7 +1,8 @@
 import { randomUUID } from "node:crypto";
 import { closeSync, existsSync, mkdirSync, openSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
-import { dirname, join, resolve } from "node:path";
-import { assertNoSymlinkPath } from "./shared.js";
+import { dirname } from "node:path";
+import { assertNoSymlinkPath } from "./io.js";
+import { stateLockGuardPath, stateLockGuardPathRelative, stateLockPath, stateLockPathRelative } from "./paths.js";
 const sleep = (milliseconds) => {
     if (milliseconds > 0)
         Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, milliseconds);
@@ -72,10 +73,10 @@ export const acquireStateLock = (root, options = {}) => {
     const timeoutMs = options.timeoutMs ?? 5_000;
     const retryMs = options.retryMs ?? 25;
     const staleMs = options.staleMs ?? 30_000;
-    const lockPath = join(resolve(root), ".agents/data/state/.aidlc-state.lock");
-    const guardPath = join(resolve(root), ".agents/data/state/.aidlc-state.lock.guard");
-    assertNoSymlinkPath(root, ".agents/data/state/.aidlc-state.lock");
-    assertNoSymlinkPath(root, ".agents/data/state/.aidlc-state.lock.guard");
+    const lockPath = stateLockPath(root);
+    const guardPath = stateLockGuardPath(root);
+    assertNoSymlinkPath(root, stateLockPathRelative);
+    assertNoSymlinkPath(root, stateLockGuardPathRelative);
     const token = randomUUID();
     const deadline = Date.now() + timeoutMs;
     const acquireGuard = () => {

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. */