@felixdotgo/aidlc-kit 0.0.1 → 0.1.1

package/dist/src/state/items.js

@@ -0,0 +1,146 @@
+import { isAbsolute, join, resolve } from "node:path";
+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. */
+export const readyTaskItems = (task) => {
+    const byId = new Map(task.tasks.map((item) => [item.id, item]));
+    if (byId.size !== task.tasks.length)
+        throw new Error(`Duplicate execution item: ${task.id}`);
+    const visiting = new Set();
+    const visited = new Set();
+    const visit = (id) => {
+        if (visiting.has(id))
+            throw new Error(`Cyclic execution dependency: ${task.id}/${id}`);
+        if (visited.has(id))
+            return;
+        visiting.add(id);
+        for (const dep of byId.get(id)?.dependsOn ?? []) {
+            if (dep === id || !byId.has(dep))
+                throw new Error(`Unknown execution dependency: ${task.id}/${id}/${dep}`);
+            visit(dep);
+        }
+        visiting.delete(id);
+        visited.add(id);
+    };
+    for (const item of task.tasks) {
+        if (item.dependsOn !== undefined && (!Array.isArray(item.dependsOn) || new Set(item.dependsOn).size !== item.dependsOn.length || item.dependsOn.some((dep) => typeof dep !== "string" || !dep)))
+            throw new Error(`Invalid execution dependencies: ${task.id}/${item.id}`);
+        if (item.ownedPaths !== undefined && (!Array.isArray(item.ownedPaths) || new Set(item.ownedPaths).size !== item.ownedPaths.length || item.ownedPaths.some((path) => typeof path !== "string" || !path || isAbsolute(path) || path === ".." || path.startsWith("../") || path.includes("\\") || path.split("/").includes(".."))))
+            throw new Error(`Invalid owned paths: ${task.id}/${item.id}`);
+        visit(item.id);
+    }
+    const ready = [];
+    const blocked = [];
+    for (const item of task.tasks) {
+        const waitingOn = (item.dependsOn ?? []).filter((dep) => byId.get(dep)?.status !== "done");
+        if (item.status === "done" && waitingOn.length)
+            throw new Error(`Completed item has incomplete prerequisites: ${task.id}/${item.id}`);
+        if (!isPending(item))
+            continue;
+        if (waitingOn.length)
+            blocked.push({ id: item.id, waitingOn });
+        else
+            ready.push(item.id);
+    }
+    return { ready, blocked };
+};
+const dispatchableItem = (open, task) => {
+    const ready = new Set(readyTaskItems(task).ready);
+    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) => {
+    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 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}` }]
+    };
+};
+const continueItem = (item, openCount, task, suffix, contextCommand, premature) => ({
+    classification: "run_phase",
+    phase: task.phase,
+    gate: task.gate,
+    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}`,
+    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) => {
+    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)))
+        return undefined;
+    const open = pendingItems(task);
+    const item = dispatchableItem(open, task);
+    if (item)
+        return continueItem(item, open.length, task, suffix, contextCommand, true);
+    if (open.length)
+        return { classification: "blocked", phase: task.phase, gate: task.gate, reason: noReadyItemReason(task) };
+    return continueVerification(task, suffix, contextCommand, true);
+};
+export const nextAction = (task, root) => {
+    const suffix = rootSuffix(root);
+    const stateCommand = script(root, "state.mjs");
+    const contextCommand = script(root, "context.mjs");
+    if (task.phase === "done")
+        return { classification: "complete", phase: task.phase, gate: task.gate, 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" };
+    if (task.handoff)
+        return { classification: "blocked", phase: task.phase, gate: task.gate, reason: task.handoff.reason, actions: handoffActions(task, suffix, stateCommand) };
+    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);
+    if (repair)
+        return repair;
+    const prematureG2 = prematureG2Wait(task, suffix, contextCommand);
+    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 === "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" };
+    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}` };
+    if (task.phase === "build") {
+        const open = pendingItems(task);
+        const item = dispatchableItem(open, task);
+        if (item)
+            return continueItem(item, open.length, task, suffix, contextCommand, false);
+        if (open.length)
+            return { classification: "blocked", phase: task.phase, gate: task.gate, reason: noReadyItemReason(task) };
+        return continueVerification(task, suffix, contextCommand, false);
+    }
+    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` };
+};

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

@@ -0,0 +1,7 @@
+import type { LessonIndex, LessonIndexEntry, LessonRecord, TaskState, WorkflowState } from "../model.js";
+export declare const recordLesson: (task: TaskState, lesson: Omit<LessonRecord, "taskId" | "recordedAt">, recordedAt?: string) => LessonRecord;
+export declare const recordNoLessons: (task: TaskState, reason: string, source: string, recordedAt?: string) => void;
+export declare const lessonStateDigest: (state: WorkflowState) => string;
+export declare const createLessonIndex: (lessons: LessonRecord[], sourceDigest?: string) => LessonIndex;
+export declare const rebuildLessonIndex: (root: string, state?: WorkflowState) => LessonIndex;
+export declare const searchLessons: (root: string, state: WorkflowState, query: string, areas?: string[], limit?: number) => LessonIndexEntry[];

package/dist/src/state/lessons.js

@@ -0,0 +1,67 @@
+import { existsSync } from "node:fs";
+import { validateLesson } from "./validate.js";
+import { loadState, loadTask } from "./store.js";
+import { assertNoSymlinkPath, audited, digest, lessonIndexPath, parseJsonFile, tokens, writeAtomic } from "./shared.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")
+        throw new Error(`Lessons can only be recorded during active wrap: ${task.id}`);
+    const current = task.lessons?.find((item) => item.id === lesson.id);
+    const next = { ...lesson, taskId: task.id, recordedAt };
+    validateLesson(task.id, next);
+    if (current) {
+        if (JSON.stringify({ ...current, recordedAt: undefined }) === JSON.stringify({ ...next, recordedAt: undefined }))
+            return current;
+        throw new Error(`Lesson already exists with different content: ${task.id}/${lesson.id}`);
+    }
+    task.lessons ??= [];
+    task.lessons.push(next);
+    task.lessonDisposition = { status: "captured", source: lesson.source, recordedAt };
+    task.updatedAt = recordedAt;
+    return next;
+};
+export const recordNoLessons = (task, reason, source, recordedAt = new Date().toISOString()) => {
+    if (task.phase !== "wrap" || task.status !== "active")
+        throw new Error(`Lesson disposition can only be recorded during active wrap: ${task.id}`);
+    audited(reason, source);
+    if (task.lessons?.length)
+        throw new Error(`Task already has captured lessons: ${task.id}`);
+    task.lessonDisposition = { status: "none", reason, source, recordedAt };
+    task.updatedAt = recordedAt;
+};
+export const lessonStateDigest = (state) => digest(JSON.stringify({
+    active: Object.values(state.tasks).flatMap((task) => task.lessons ?? []).sort((a, b) => `${a.taskId}:${a.id}`.localeCompare(`${b.taskId}:${b.id}`)),
+    archive: Object.values(state.archive ?? {}).map((item) => ({ id: item.id, digest: item.digest, lessonCount: item.lessonCount })).sort((a, b) => a.id.localeCompare(b.id))
+}));
+export const createLessonIndex = (lessons, sourceDigest) => ({ schemaVersion: 1, sourceDigest: sourceDigest ?? digest(JSON.stringify(lessons)), lessons: lessons.map(lessonEntry).sort((a, b) => b.recordedAt.localeCompare(a.recordedAt) || a.taskId.localeCompare(b.taskId) || a.id.localeCompare(b.id)) });
+const allLessons = (root, state) => [
+    ...Object.values(state.tasks).flatMap((task) => task.lessons ?? []),
+    ...Object.keys(state.archive ?? {}).flatMap((id) => loadTask(root, id, state)?.lessons ?? [])
+];
+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`);
+    return index;
+};
+export const searchLessons = (root, state, query, areas = [], limit = 5) => {
+    const path = lessonIndexPath(root);
+    assertNoSymlinkPath(root, ".agents/data/lessons/index.json");
+    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)
+            return [];
+        throw new Error("Lesson index is missing; run state.mjs lesson rebuild");
+    }
+    const index = parseJsonFile(path, "Lesson index", "run state.mjs lesson rebuild");
+    if (index.schemaVersion !== 1 || !Array.isArray(index.lessons) || index.sourceDigest !== lessonStateDigest(state))
+        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) => {
+        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);
+};

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

@@ -0,0 +1,5 @@
+import type { HandoffKind, TaskState, WorkflowState } from "../model.js";
+export declare const handoffTask: (state: WorkflowState, id: string, kind: HandoffKind, reason: string, source: string, recordedAt?: string) => TaskState;
+export declare const closeTask: (state: WorkflowState, id: string, reason: string, source: string, recordedAt?: string) => TaskState;
+export declare const supersedeTask: (state: WorkflowState, id: string, successorId: string, reason: string, source: string, recordedAt?: string) => TaskState;
+export declare const reopenTask: (state: WorkflowState, id: string, target: "plan", reason: string, source: string, recordedAt?: string) => TaskState;

package/dist/src/state/lifecycle.js

@@ -0,0 +1,78 @@
+import { handoffKinds } from "./shared.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))
+        throw new Error(`Task cannot enter handoff: ${id}`);
+    audited(reason, source);
+    if (task.handoff) {
+        if (task.handoff.kind === kind && task.handoff.reason === reason && task.handoff.source === source)
+            return task;
+        throw new Error(`Task already has a different handoff: ${id}`);
+    }
+    task.status = "paused";
+    task.handoff = { kind, reason, source, recordedAt };
+    delete task.legacyG2Wait;
+    task.updatedAt = recordedAt;
+    return task;
+};
+export const closeTask = (state, id, reason, source, recordedAt = new Date().toISOString()) => {
+    const task = state.tasks[id];
+    if (!task || task.status === "done" || task.status === "superseded")
+        throw new Error(`Task cannot be closed: ${id}`);
+    audited(reason, source);
+    if (task.status === "closed") {
+        if (task.closure?.reason === reason && task.closure.source === source)
+            return task;
+        throw new Error(`Task is already closed with different metadata: ${id}`);
+    }
+    task.status = "closed";
+    task.closure = { reason, source, recordedAt };
+    delete task.handoff;
+    delete task.successorTaskId;
+    delete task.legacyG2Wait;
+    task.updatedAt = recordedAt;
+    return task;
+};
+export const supersedeTask = (state, id, successorId, reason, source, recordedAt = new Date().toISOString()) => {
+    const task = state.tasks[id];
+    const successor = state.tasks[successorId];
+    audited(reason, source);
+    if (!task || task.status === "done" || task.status === "closed" || !successor || id === successorId)
+        throw new Error(`Task cannot be superseded: ${id}`);
+    if (task.status === "superseded") {
+        if (task.successorTaskId === successorId && task.closure?.reason === reason && task.closure.source === source)
+            return task;
+        throw new Error(`Task is already superseded with different metadata: ${id}`);
+    }
+    if (successor.phase !== "clarify" || successor.gate !== "G0_confirm" || terminal(successor) || hasApproval(successor, "G0_confirm") || (successor.predecessorTaskId && successor.predecessorTaskId !== id))
+        throw new Error(`Successor must be a fresh pre-G0 task: ${successorId}`);
+    task.status = "superseded";
+    task.closure = { reason, source, recordedAt };
+    task.successorTaskId = successorId;
+    delete task.handoff;
+    delete task.legacyG2Wait;
+    task.updatedAt = recordedAt;
+    successor.predecessorTaskId = id;
+    successor.updatedAt = recordedAt;
+    validateState(state);
+    return task;
+};
+export const reopenTask = (state, id, target, reason, source, recordedAt = new Date().toISOString()) => {
+    const task = state.tasks[id];
+    audited(reason, source);
+    if (!task || target !== "plan" || task.phase !== "build" || task.status !== "paused" || !task.handoff)
+        throw new Error(`Task cannot reopen G1: ${id}`);
+    task.evidence.push({ kind: "approval", gate: "G1_review", result: "fail", source, detail: `Reopened G1: ${reason}`, recordedAt });
+    for (const item of task.tasks)
+        if (item.status !== "deferred")
+            item.status = "todo";
+    task.phase = "plan";
+    task.gate = "G1_review";
+    task.status = "active";
+    delete task.handoff;
+    task.updatedAt = recordedAt;
+    return task;
+};

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

@@ -0,0 +1,7 @@
+export interface StateLockOptions {
+    timeoutMs?: number;
+    retryMs?: number;
+    staleMs?: number;
+}
+/** Serializes lifecycle script mutations across local Node.js processes. */
+export declare const acquireStateLock: (root: string, options?: StateLockOptions) => (() => void);

package/dist/src/state/lock.js

@@ -0,0 +1,124 @@
+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";
+const sleep = (milliseconds) => {
+    if (milliseconds > 0)
+        Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, milliseconds);
+};
+const lockRecord = (path) => {
+    try {
+        const value = JSON.parse(readFileSync(path, "utf8"));
+        return typeof value.token === "string" && typeof value.pid === "number" && Number.isInteger(value.pid) && value.pid > 0 && typeof value.createdAt === "number" && Number.isFinite(value.createdAt) ? value : undefined;
+    }
+    catch {
+        return undefined;
+    } /* intentional: unreadable lock record is treated as absent */
+};
+const processAlive = (pid) => {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === "EPERM";
+    }
+};
+const tryCreateLock = (path, record) => {
+    try {
+        mkdirSync(dirname(path), { recursive: true });
+        const descriptor = openSync(path, "wx", 0o600);
+        try {
+            writeFileSync(descriptor, `${JSON.stringify(record)}\n`, "utf8");
+        }
+        finally {
+            closeSync(descriptor);
+        }
+        return true;
+    }
+    catch (error) {
+        if (error.code === "EEXIST")
+            return false;
+        throw error;
+    }
+};
+const removeOwnedLock = (path, token) => {
+    if (lockRecord(path)?.token === token)
+        unlinkSync(path);
+};
+const lockExpired = (record, now, staleMs) => Boolean(record && now - record.createdAt >= staleMs && !processAlive(record.pid));
+const releaseOwnedLock = (lockRecordOrNull, lockPath, token) => {
+    if (!lockRecordOrNull) {
+        // A corrupt/unreadable lock record must not wedge release; reclaim best-effort.
+        if (existsSync(lockPath)) {
+            try {
+                unlinkSync(lockPath);
+            }
+            catch { /* best-effort cleanup of a corrupt lock */ }
+        }
+        return;
+    }
+    if (lockRecordOrNull.token !== token)
+        return;
+    try {
+        unlinkSync(lockPath);
+    }
+    catch (error) {
+        throw new Error(`Failed to release owned AI-DLC state lock: ${error instanceof Error ? error.message : String(error)}`);
+    }
+};
+/** Serializes lifecycle script mutations across local Node.js processes. */
+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 token = randomUUID();
+    const deadline = Date.now() + timeoutMs;
+    const acquireGuard = () => {
+        const guardToken = randomUUID();
+        const now = Date.now();
+        const existing = lockRecord(guardPath);
+        if (existing === undefined && existsSync(guardPath)) {
+            try {
+                unlinkSync(guardPath);
+            }
+            catch { /* best-effort reclamation of a corrupt guard */ }
+        }
+        else if (lockExpired(existing, now, staleMs)) {
+            removeOwnedLock(guardPath, existing.token);
+        }
+        return tryCreateLock(guardPath, { token: guardToken, pid: process.pid, createdAt: now }) ? guardToken : undefined;
+    };
+    while (Date.now() <= deadline) {
+        const guardToken = acquireGuard();
+        if (!guardToken) {
+            sleep(retryMs);
+            continue;
+        }
+        try {
+            const now = Date.now();
+            const existing = lockRecord(lockPath);
+            if (existing === undefined && existsSync(lockPath)) {
+                try {
+                    unlinkSync(lockPath);
+                }
+                catch { /* best-effort reclamation of a corrupt lock */ }
+            }
+            else if (lockExpired(existing, now, staleMs)) {
+                removeOwnedLock(lockPath, existing.token);
+            }
+            if (tryCreateLock(lockPath, { token, pid: process.pid, createdAt: now })) {
+                return () => releaseOwnedLock(lockRecord(lockPath), lockPath, token);
+            }
+        }
+        finally {
+            removeOwnedLock(guardPath, guardToken);
+        }
+        sleep(retryMs);
+    }
+    throw new Error(`Timed out waiting for AI-DLC state lock after ${timeoutMs}ms`);
+};

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

@@ -0,0 +1,8 @@
+import type { AgenticMemoryEntry, AgenticMemoryRegistry, Phase } from "../model.js";
+export declare const emptyMemoryRegistry: () => AgenticMemoryRegistry;
+export declare const validateMemoryRegistry: (value: unknown) => AgenticMemoryRegistry;
+export declare const loadMemoryRegistry: (root: string) => AgenticMemoryRegistry;
+export declare const saveMemoryRegistry: (root: string, registry: AgenticMemoryRegistry) => void;
+export declare const selectAgenticMemory: (registry: AgenticMemoryRegistry, areas: string[], phase: Exclude<Phase, "done">, maxChars: number) => AgenticMemoryEntry[];
+export declare const promoteAgenticMemory: (root: string, entry: AgenticMemoryEntry) => AgenticMemoryEntry;
+export declare const retireAgenticMemory: (root: string, id: string, reason: string, retiredBy: string, retiredAt?: string) => AgenticMemoryEntry;

package/dist/src/state/memory.js

@@ -0,0 +1,88 @@
+import { existsSync } from "node:fs";
+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"}`);
+};
+export const emptyMemoryRegistry = () => ({ schemaVersion: 1, entries: [], retired: [] });
+export const validateMemoryRegistry = (value) => {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error("Agentic memory registry must be an object");
+    const registry = value;
+    if (registry.schemaVersion !== 1 || !Array.isArray(registry.entries) || !Array.isArray(registry.retired))
+        throw new Error("Unsupported agentic memory registry schema");
+    const ids = new Set();
+    for (const entry of registry.entries) {
+        validateMemoryEntry(entry);
+        if (ids.has(entry.id))
+            throw new Error(`Duplicate agentic memory entry: ${entry.id}`);
+        ids.add(entry.id);
+    }
+    for (const entry of registry.retired) {
+        validateMemoryEntry(entry);
+        if (!text(entry.retiredBy) || !text(entry.reason) || !iso(entry.retiredAt))
+            throw new Error(`Invalid retired agentic memory entry: ${entry.id}`);
+        if (ids.has(entry.id))
+            throw new Error(`Agentic memory entry is active and retired: ${entry.id}`);
+        ids.add(entry.id);
+    }
+    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 saveMemoryRegistry = (root, registry) => {
+    const normalized = validateMemoryRegistry(registry);
+    assertNoSymlinkPath(root, registryPathRelative);
+    writeAtomic(memoryRegistryPath(root), `${JSON.stringify(normalized, null, 2)}\n`);
+};
+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 selected = [];
+    let used = 0;
+    for (const entry of matches) {
+        const size = `- ${entry.id} — ${entry.summary} — guidance: ${entry.guidance} — source: ${entry.sourceTaskId}/${entry.sourceLessonId}\n`.length;
+        if (used + size > maxChars)
+            continue;
+        selected.push(entry);
+        used += size;
+    }
+    return selected;
+};
+export const promoteAgenticMemory = (root, entry) => {
+    const state = loadState(root);
+    const source = loadTask(root, entry.sourceTaskId, state);
+    if (!source?.lessons?.some((lesson) => lesson.id === entry.sourceLessonId))
+        throw new Error(`Agentic memory source lesson is missing: ${entry.sourceTaskId}/${entry.sourceLessonId}`);
+    const registry = loadMemoryRegistry(root);
+    const current = registry.entries.find((item) => item.id === entry.id);
+    if (current) {
+        if (JSON.stringify(current) === JSON.stringify(entry))
+            return current;
+        throw new Error(`Agentic memory entry already exists with different content: ${entry.id}`);
+    }
+    if (registry.retired.some((item) => item.id === entry.id))
+        throw new Error(`Retired agentic memory id cannot be reused: ${entry.id}`);
+    registry.entries.push(entry);
+    registry.entries.sort((left, right) => right.priority - left.priority || left.id.localeCompare(right.id));
+    saveMemoryRegistry(root, registry);
+    return entry;
+};
+export const retireAgenticMemory = (root, id, reason, retiredBy, retiredAt = new Date().toISOString()) => {
+    if (!text(reason) || !text(retiredBy) || !iso(retiredAt))
+        throw new Error("Retiring agentic memory requires a reason, approver, and valid timestamp");
+    const registry = loadMemoryRegistry(root);
+    const index = registry.entries.findIndex((entry) => entry.id === id);
+    if (index < 0)
+        throw new Error(`Unknown active agentic memory entry: ${id}`);
+    const [entry] = registry.entries.splice(index, 1);
+    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);
+    return entry;
+};

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

@@ -0,0 +1,26 @@
+import type { Phase, Gate, TaskState, WorkflowState } from "../model.js";
+export interface TaskSummary {
+    id: string;
+    title: string;
+    phase: Phase;
+    gate: Gate;
+    status: TaskState["status"];
+    risk: TaskState["risk"];
+    areas: string[];
+    updatedAt: string;
+    source: "active" | "archive";
+}
+export declare const listTaskSummaries: (state: WorkflowState, options?: {
+    includeArchive?: boolean;
+    statuses?: string[];
+    query?: string;
+    limit?: number;
+    cursor?: number;
+}) => {
+    items: TaskSummary[];
+    nextCursor: string | null;
+    total: number;
+};
+/** Renders the markdown workplan for a task. */
+export declare const renderWorkplan: (task: TaskState) => string;
+export declare const renderViews: (root: string, state?: WorkflowState, selected?: TaskState[]) => void;

package/dist/src/state/render.js

@@ -0,0 +1,29 @@
+import { join, resolve } from "node:path";
+import { loadState } from "./store.js";
+import { assertNoSymlinkPath, tokens, writeAtomic } from "./shared.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 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);
+    return { items, nextCursor: cursor + items.length < filtered.length ? String(cursor + items.length) : null, total: filtered.length };
+};
+/** 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 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`;
+};
+export const renderViews = (root, state = loadState(root), selected = Object.values(state.tasks)) => {
+    for (const task of selected) {
+        if (!task.artifacts.workplan)
+            continue;
+        assertNoSymlinkPath(root, task.artifacts.workplan);
+        writeAtomic(join(resolve(root), task.artifacts.workplan), renderWorkplan(task));
+    }
+};

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

@@ -0,0 +1,29 @@
+import type { ArchivedTaskSummary, Gate, HandoffKind, Phase, TaskState, WorkflowState } from "../model.js";
+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 emptyState: () => WorkflowState;
+export declare const legacyG2WaitSource = "schema-v4-migration";
+export declare const phases: Phase[];
+export declare const gates: Gate[];
+export declare const handoffKinds: HandoffKind[];
+export declare const terminal: (task: TaskState) => boolean;
+export declare const phaseGate: (phase: Phase) => Gate;
+export declare const iso: (value: unknown) => value is string;
+export declare const text: (value: unknown) => value is string;
+export declare const idPattern: RegExp;
+export declare const digest: (content: string) => string;
+export declare const archiveRecordPath: (id: string) => string;
+export declare const taskRecordContent: (task: TaskState) => string;
+export declare const assertNoSymlinkPath: (root: string, relative: string) => void;
+export declare const writeAtomic: (path: string, content: string) => void;
+export declare const parseJsonText: (content: string, label: string, recovery?: string) => unknown;
+export declare const parseJsonFile: (path: string, label: string, recovery?: string) => unknown;
+export declare const audited: (reason: string, source: string) => void;
+export declare const tokens: (value: string) => string[];
+/** Rejects artifact paths that escape the project-owned tasks directory. */
+export declare const assertTaskArtifactPath: (id: string, path: string) => void;
+/** Builds the immutable archive-catalog summary for a terminal task from its record content. */
+export declare const archivedSummary: (task: TaskState, content?: string) => ArchivedTaskSummary;