@felixdotgo/aidlc-kit 0.1.0 → 0.2.0

package/dist/src/state/io.js

@@ -0,0 +1,35 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { resolveProjectPathWithoutSymlinks } from "../project-path.js";
+export const assertNoSymlinkPath = (root, relative) => {
+    resolveProjectPathWithoutSymlinks(root, relative, "Unsafe state path", "State path crosses a symlink");
+};
+export const writeAtomic = (path, content) => {
+    mkdirSync(dirname(path), { recursive: true });
+    const temporary = `${path}.tmp-${process.pid}-${Date.now()}`;
+    writeFileSync(temporary, content, "utf8");
+    renameSync(temporary, path);
+};
+export const parseJsonText = (content, label, recovery = "") => {
+    try {
+        return JSON.parse(content);
+    }
+    catch (error) {
+        throw new Error(`${label} is corrupted or unreadable: ${error instanceof Error ? error.message : String(error)}${recovery ? `; ${recovery}` : ""}`);
+    }
+};
+export const parseJsonFile = (path, label, recovery = "") => parseJsonText(readFileSync(path, "utf8"), label, recovery);
+/** Resolves a project-relative state path to its absolute form, rejecting symlink-crossing variants first. */
+export const safeResolvedPath = (root, relative) => {
+    assertNoSymlinkPath(root, relative);
+    return join(resolve(root), relative);
+};
+/** Loads and validates a canonical JSON state file, or produces the fallback when the file does not exist. */
+export const loadJsonOr = (root, relative, validate, fallback, label, recovery = "") => {
+    const path = safeResolvedPath(root, relative);
+    return existsSync(path) ? validate(parseJsonFile(path, label, recovery)) : fallback();
+};
+/** Persists a JSON state file atomically in the canonical 2-space, trailing-newline formatting. */
+export const saveJson = (root, relative, value) => {
+    writeAtomic(safeResolvedPath(root, relative), `${JSON.stringify(value, null, 2)}\n`);
+};

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

@@ -0,0 +1,24 @@
+import type { Gate, Phase, TaskState } from "../model.js";
+import { type NextActionActions } from "./commands.js";
+export interface NextAction {
+    classification: "await_user" | "run_phase" | "blocked" | "terminal" | "complete";
+    phase: Phase;
+    gate: Gate;
+    command?: string;
+    outcome?: "closed" | "superseded";
+    successorTaskId?: string;
+    itemId?: string;
+    remainingItems?: number;
+    actions?: NextActionActions;
+    reason: string;
+}
+/** Validates execution dependencies and reports which pending items are ready to dispatch. */
+export declare const readyTaskItems: (task: TaskState) => {
+    ready: string[];
+    blocked: Array<{
+        id: string;
+        waitingOn: string[];
+    }>;
+};
+/** Classifies the next lifecycle action for a task and attaches root-qualified command strings. */
+export declare const nextAction: (task: TaskState, root?: string) => NextAction;

package/dist/src/state/items.js

@@ -0,0 +1,147 @@
+import { isAbsolute } from "node:path";
+import { commandKit } from "./commands.js";
+import { hasReview, hasVerification, isLegacyG2Wait, repairBounds } from "./transitions.js";
+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 repairExhausted = (task) => {
+    if (task.phase !== "build" || isLegacyG2Wait(task))
+        return undefined;
+    const bounds = repairBounds(task);
+    if (!bounds.verifyExhausted && !bounds.reviewExhausted)
+        return undefined;
+    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 { kind: "repair_exhausted", handoffKind, reason: `Repair bound exhausted (${detail}); record a durable handoff` };
+};
+const continueItem = (item, openCount, premature) => ({
+    kind: "continue_item",
+    itemId: item.id,
+    remainingItems: openCount,
+    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 = (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) => {
+    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, true);
+    if (open.length)
+        return { kind: "no_ready_item", reason: noReadyItemReason(task) };
+    return continueVerification(true);
+};
+/** Pure classification: maps a task onto its next-action decision without touching any command string. */
+const classify = (task) => {
+    if (task.phase === "done")
+        return { kind: "complete", reason: "Task is complete" };
+    if (task.status === "closed" || task.status === "superseded")
+        return { kind: "terminal", outcome: task.status, successorTaskId: task.successorTaskId, reason: task.closure?.reason ?? "Task ended without successful completion" };
+    if (task.handoff)
+        return { kind: "handoff", reason: task.handoff.reason };
+    if (task.status === "paused")
+        return { kind: "paused", reason: "Task is paused" };
+    const repair = repairExhausted(task);
+    if (repair)
+        return repair;
+    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 { 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 { kind: "recover_gateless_wrap", reason: "Recover invalid wait at a gateless wrap phase before continuing wrap" };
+    if (task.status === "blocked_on_user")
+        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, false);
+        if (open.length)
+            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 };
+    }
+};
+/** 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.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,74 @@
+import { existsSync } from "node:fs";
+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 { 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")
+        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));
+    saveJson(root, lessonIndexPathRelative, index);
+    return index;
+};
+export const searchLessons = (root, state, query, areas = [], limit = 5) => {
+    const path = lessonIndexPath(root);
+    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)
+            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, terminal } from "./domain.js";
+import { audited } from "./guards.js";
+import { hasApproval } from "./transitions.js";
+import { validateState } from "./validate.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,125 @@
+import { randomUUID } from "node:crypto";
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+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);
+};
+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 = stateLockPath(root);
+    const guardPath = stateLockGuardPath(root);
+    assertNoSymlinkPath(root, stateLockPathRelative);
+    assertNoSymlinkPath(root, stateLockGuardPathRelative);
+    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,100 @@
+import { idPattern, iso, text } from "./guards.js";
+import { loadJsonOr, saveJson } from "./io.js";
+import { memoryRegistryPathRelative } from "./paths.js";
+import { loadState, loadTask } from "./store.js";
+const memoryPhases = ["clarify", "plan", "build", "wrap", "*"];
+const validateMemoryEntry = (entry) => {
+    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) => {
+    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;
+};
+export const loadMemoryRegistry = (root) => loadJsonOr(root, memoryRegistryPathRelative, validateMemoryRegistry, emptyMemoryRegistry, "Agentic memory registry");
+export const saveMemoryRegistry = (root, registry) => {
+    const normalized = validateMemoryRegistry(registry);
+    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 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);
+    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);
+    return entry;
+};

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

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