@felixdotgo/aidlc-kit 0.1.0 → 0.1.1

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;

package/dist/src/state/shared.js

@@ -0,0 +1,71 @@
+import { createHash } from "node:crypto";
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname, isAbsolute, join, normalize, resolve } from "node:path";
+import { resolveProjectPathWithoutSymlinks } from "../project-path.js";
+export const statePath = (root) => join(resolve(root), ".agents/data/state/aidlc-state.json");
+export const lessonIndexPath = (root) => join(resolve(root), ".agents/data/lessons/index.json");
+export const memoryRegistryPath = (root) => join(resolve(root), ".agents/data/memory/agentic-memory.json");
+export const stateLockPath = (root) => join(resolve(root), ".agents/data/state/.aidlc-state.lock");
+export const stateLockGuardPath = (root) => join(resolve(root), ".agents/data/state/.aidlc-state.lock.guard");
+export const emptyState = () => ({ schemaVersion: 4, tasks: {}, archive: {} });
+export const legacyG2WaitSource = "schema-v4-migration";
+export const phases = ["clarify", "plan", "build", "wrap", "done"];
+export const gates = ["none", "G0_confirm", "G1_review", "G2_codereview"];
+export const handoffKinds = ["repair_exhausted", "review_exhausted", "g2_failed", "release_failed", "structural_change", "other"];
+export const terminal = (task) => task.status === "done" || task.status === "closed" || task.status === "superseded";
+export const phaseGate = (phase) => phase === "clarify" ? "G0_confirm" : phase === "plan" ? "G1_review" : phase === "build" ? "G2_codereview" : "none";
+export const iso = (value) => typeof value === "string" && Number.isFinite(Date.parse(value)) && new Date(Date.parse(value)).toISOString() === value;
+export const text = (value) => typeof value === "string" && Boolean(value.trim());
+export const idPattern = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+export const digest = (content) => createHash("sha256").update(content).digest("hex");
+export const archiveRecordPath = (id) => `.agents/data/state/archive/${id}.json`;
+export const taskRecordContent = (task) => `${JSON.stringify(task, null, 2)}\n`;
+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);
+export const audited = (reason, source) => {
+    if (!text(reason) || !text(source))
+        throw new Error("Lifecycle mutation requires non-empty --reason and --source");
+};
+export const tokens = (value) => [...new Set(value.toLocaleLowerCase().split(/[^\p{L}\p{N}]+/u).filter((item) => item.length > 1))];
+/** Rejects artifact paths that escape the project-owned tasks directory. */
+export const assertTaskArtifactPath = (id, path) => {
+    const separator = process.platform === "win32" ? "\\" : "/";
+    const cleaned = normalize(path);
+    if (isAbsolute(cleaned) || cleaned === ".." || cleaned.startsWith(`..${separator}`) || !cleaned.startsWith(`.agents${separator}data${separator}tasks${separator}`)) {
+        throw new Error(`Invalid artifact path for ${id}: ${path}`);
+    }
+};
+/** Builds the immutable archive-catalog summary for a terminal task from its record content. */
+export const archivedSummary = (task, content = taskRecordContent(task)) => ({
+    id: task.id,
+    title: task.title,
+    type: task.type,
+    phase: task.phase,
+    gate: task.gate,
+    status: task.status,
+    risk: task.risk,
+    areas: task.areas,
+    record: archiveRecordPath(task.id),
+    digest: digest(content),
+    lessonCount: task.lessons?.length ?? 0,
+    predecessorTaskId: task.predecessorTaskId,
+    successorTaskId: task.successorTaskId,
+    createdAt: task.createdAt,
+    updatedAt: task.updatedAt
+});

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

@@ -0,0 +1,4 @@
+import type { TaskState, WorkflowState } from "../model.js";
+export declare const loadState: (root: string) => WorkflowState;
+export declare const loadTask: (root: string, id: string, state?: WorkflowState) => TaskState | undefined;
+export declare const saveState: (root: string, state: WorkflowState) => string[];

package/dist/src/state/store.js

@@ -0,0 +1,81 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+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 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);
+    if (!existsSync(path))
+        throw new Error(`Archived task record is missing: ${summary.record}`);
+    const content = readFileSync(path, "utf8");
+    if (digest(content) !== summary.digest)
+        throw new Error(`Archived task digest mismatch: ${id}`);
+    const task = parseJsonText(content, `Archived task record ${id}`);
+    validateTask(id, task);
+    if (!terminal(task) || task.status !== summary.status || task.updatedAt !== summary.updatedAt || (task.lessons?.length ?? 0) !== summary.lessonCount)
+        throw new Error(`Archived task summary mismatch: ${id}`);
+    return task;
+};
+const archiveTerminalTasks = (normalized, persisted, root) => {
+    const archived = [];
+    normalized.archive ??= {};
+    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);
+        if (existsSync(path)) {
+            const current = readFileSync(path, "utf8");
+            if (digest(current) !== summary.digest)
+                commitRecoveryRecordOrThrow(task, content, path, current, persisted);
+        }
+        else
+            writeAtomic(path, content);
+        normalized.archive[task.id] = summary;
+        delete normalized.tasks[task.id];
+        archived.push(task.id);
+    }
+    return archived;
+};
+/** Replaces an interrupted-write orphan only when the persisted catalog still proves the same active task identity. */
+const commitRecoveryRecordOrThrow = (task, content, path, current, persisted) => {
+    let orphan;
+    try {
+        orphan = JSON.parse(current);
+        validateTask(task.id, orphan);
+    }
+    catch {
+        throw new Error(`Archived task record conflicts: ${task.id}`);
+    }
+    const authority = persisted?.tasks[task.id];
+    const identityHolds = authority && authority.createdAt === task.createdAt;
+    const orphanMatches = terminal(orphan) && orphan.id === task.id && orphan.createdAt === task.createdAt;
+    if (persisted?.archive?.[task.id] || !identityHolds || !orphanMatches)
+        throw new Error(`Archived task record conflicts: ${task.id}`);
+    writeAtomic(path, content);
+};
+export const saveState = (root, state) => {
+    const normalized = validateState(structuredClone(state));
+    const persisted = existsSync(statePath(root)) ? loadState(root) : undefined;
+    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`);
+    state.tasks = normalized.tasks;
+    state.archive = normalized.archive;
+    state.schemaVersion = normalized.schemaVersion;
+    return archived;
+};

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

@@ -0,0 +1,21 @@
+import type { Diagnostic, Gate, Phase, TaskState, WorkflowState } from "../model.js";
+export declare const latestApproval: (task: TaskState, gate: Gate) => import("../model.js").Evidence | undefined;
+/** Evidence index where the currently effective Approve plan approval starts; undefined when none exists. */
+export declare const buildBoundary: (task: TaskState) => number | undefined;
+export declare const hasApproval: (task: TaskState, gate: Gate) => boolean;
+export declare const hasCurrentBuildApproval: (task: TaskState, gate: Gate) => boolean;
+export declare const hasAreaVerification: (task: TaskState, area: string) => boolean;
+export declare const hasVerification: (task: TaskState) => boolean;
+export declare const hasReview: (task: TaskState) => boolean;
+export interface RepairBounds {
+    verifyFailures: Record<string, number>;
+    reviewFailures: number;
+    exhaustedAreas: string[];
+    verifyExhausted: boolean;
+    reviewExhausted: boolean;
+}
+export declare const repairBounds: (task: TaskState) => RepairBounds;
+/** True only for a migration-stamped legacy G2 wait that is still fully ready; the stamp is written exclusively by schema migration. */
+export declare const isLegacyG2Wait: (task: TaskState) => boolean;
+export declare const transitionDiagnostics: (task: TaskState, target: Phase) => Diagnostic[];
+export declare const transitionTask: (state: WorkflowState, id: string, target: Phase) => TaskState;

package/dist/src/state/transitions.js

@@ -0,0 +1,93 @@
+import { phases, phaseGate, terminal } from "./shared.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)
+            return item;
+    }
+    return undefined;
+};
+/** Evidence index where the currently effective Approve plan approval starts; undefined when none exists. */
+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")
+            boundary = index;
+    }
+    return boundary;
+};
+export const hasApproval = (task, gate) => latestApproval(task, gate)?.result === "pass";
+const currentBuildEvidence = (task) => {
+    const boundary = buildBoundary(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];
+    return undefined;
+};
+export const hasCurrentBuildApproval = (task, gate) => latestInOrder(currentBuildEvidence(task), (item) => item.kind === "approval" && item.gate === gate)?.result === "pass";
+export const hasAreaVerification = (task, area) => {
+    const evidence = currentBuildEvidence(task).filter((item) => (item.kind === "test" || item.kind === "lint") && (item.area === area || (!item.area && task.areas.length === 1)));
+    const kinds = [...new Set(evidence.map((item) => item.kind))];
+    return kinds.length > 0 && kinds.every((kind) => latestInOrder(evidence, (item) => item.kind === kind)?.result === "pass");
+};
+export const hasVerification = (task) => task.areas.every((area) => hasAreaVerification(task, area));
+export const hasReview = (task) => latestInOrder(currentBuildEvidence(task), (item) => item.kind === "review")?.result === "pass";
+export const repairBounds = (task) => {
+    const evidence = currentBuildEvidence(task);
+    const verifyFailures = {};
+    for (const item of evidence)
+        if (["test", "lint"].includes(item.kind) && item.result === "fail") {
+            const area = item.area ?? (task.areas.length === 1 ? task.areas[0] : "unscoped");
+            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();
+    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. */
+export const isLegacyG2Wait = (task) => task.legacyG2Wait !== undefined && task.phase === "build" && task.gate === "G2_codereview" && task.status === "blocked_on_user" && task.tasks.every((item) => item.status === "done" || item.status === "deferred") && hasVerification(task) && hasReview(task);
+export const transitionDiagnostics = (task, target) => {
+    const diagnostics = [];
+    if (target === task.phase || phases.indexOf(target) !== phases.indexOf(task.phase) + 1)
+        diagnostics.push({ level: "ERROR", code: "STATE_TRANSITION", message: `Cannot transition ${task.phase} → ${target}` });
+    if (target === "plan" && !hasApproval(task, "G0_confirm"))
+        diagnostics.push({ level: "ERROR", code: "G0_APPROVAL", message: "G0 approval evidence is required" });
+    if (target === "build") {
+        if (!hasApproval(task, "G1_review"))
+            diagnostics.push({ level: "ERROR", code: "G1_APPROVAL", message: "G1 approval evidence is required" });
+        for (const decision of task.decisions)
+            if (decision.status === "unresolved")
+                diagnostics.push({ level: "ERROR", code: "UNRESOLVED_DECISION", message: `Decision ${decision.id} is unresolved` });
+    }
+    if (target === "wrap") {
+        if (!hasVerification(task))
+            diagnostics.push({ level: "ERROR", code: "VERIFY_EVIDENCE", message: "Latest current-build verification evidence must pass for every affected area" });
+        if (!hasReview(task))
+            diagnostics.push({ level: "ERROR", code: "REVIEW_EVIDENCE", message: "Latest current-build code-review evidence must pass" });
+        if (!hasCurrentBuildApproval(task, "G2_codereview"))
+            diagnostics.push({ level: "ERROR", code: "G2_APPROVAL", message: "Current-build G2 approval evidence is required" });
+    }
+    if (target === "done" && !task.lessonDisposition)
+        diagnostics.push({ level: "ERROR", code: "LESSON_DISPOSITION", message: "Wrap must record lessons or an explicit no-lesson disposition" });
+    return diagnostics;
+};
+export const transitionTask = (state, id, target) => {
+    const task = state.tasks[id];
+    if (!task)
+        throw new Error(`Unknown active task: ${id}`);
+    if (terminal(task))
+        throw new Error(`Terminal task cannot transition: ${id}`);
+    const errors = transitionDiagnostics(task, target).filter((item) => item.level === "ERROR");
+    if (errors.length)
+        throw new Error(errors.map((item) => item.message).join("; "));
+    task.phase = target;
+    task.gate = phaseGate(target);
+    task.status = target === "done" ? "done" : "active";
+    delete task.legacyG2Wait;
+    task.updatedAt = new Date().toISOString();
+    return task;
+};

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

@@ -0,0 +1,4 @@
+import type { LessonRecord, TaskState, WorkflowState } from "../model.js";
+export declare const validateLesson: (taskId: string, lesson: LessonRecord) => void;
+export declare const validateTask: (id: string, task: TaskState) => void;
+export declare const validateState: (value: unknown) => WorkflowState;

package/dist/src/state/validate.js

@@ -0,0 +1,100 @@
+import { readyTaskItems } from "./items.js";
+import { assertTaskArtifactPath, gates, handoffKinds, idPattern, iso, phases, phaseGate, text } from "./shared.js";
+const taskStatuses = ["active", "blocked_on_user", "paused", "done", "closed", "superseded"];
+export const validateLesson = (taskId, lesson) => {
+    if (!lesson || !idPattern.test(lesson.id) || lesson.taskId !== taskId || !Array.isArray(lesson.areas) || !lesson.areas.length || lesson.areas.some((area) => !text(area)) || !text(lesson.summary) || !text(lesson.prevention) || !text(lesson.example) || !text(lesson.promotion) || !text(lesson.source) || !iso(lesson.recordedAt))
+        throw new Error(`Invalid lesson: ${taskId}`);
+};
+export const validateTask = (id, task) => {
+    if (!idPattern.test(id))
+        throw new Error(`Invalid task id: ${id}`);
+    if (!task || task.id !== id || !phases.includes(task.phase) || !gates.includes(task.gate) || task.gate !== phaseGate(task.phase))
+        throw new Error(`Invalid task state: ${id}`);
+    if (!Array.isArray(task.decisions) || !Array.isArray(task.tasks) || !Array.isArray(task.evidence) || (task.lessons !== undefined && !Array.isArray(task.lessons)))
+        throw new Error(`Invalid task collections: ${id}`);
+    if (!task.title || !["feature", "bug", "refactor", "infra"].includes(task.type) || !taskStatuses.includes(task.status) || (task.phase === "done") !== (task.status === "done"))
+        throw new Error(`Invalid task fields: ${id}`);
+    if (!["vi", "en"].includes(task.language) || !["low", "normal", "high", "regulated"].includes(task.risk) || !Array.isArray(task.areas) || !task.areas.length || task.areas.some((area) => !text(area)))
+        throw new Error(`Invalid task language, risk, or areas: ${id}`);
+    if (task.decisions.some((item) => !item.id || !item.label || !["unresolved", "approved", "changed", "dropped"].includes(item.status) || (item.status === "changed" && !item.resolution)))
+        throw new Error(`Invalid decisions: ${id}`);
+    if (task.featureId !== undefined && !idPattern.test(task.featureId))
+        throw new Error(`Invalid feature id: ${id}`);
+    if (task.tasks.some((item) => !item.id || !item.label || !["todo", "in_progress", "done", "deferred"].includes(item.status)))
+        throw new Error(`Invalid execution tasks: ${id}`);
+    readyTaskItems(task);
+    if (task.evidence.some((item) => !["approval", "spec", "test", "lint", "review", "diagnostic"].includes(item.kind) || !["pass", "fail", "skip"].includes(item.result) || !item.source || !iso(item.recordedAt) || (item.area !== undefined && !text(item.area)) || (item.gate !== undefined && !gates.includes(item.gate)) || (item.kind === "approval" && (!item.gate || item.gate === "none"))))
+        throw new Error(`Invalid evidence: ${id}`);
+    const lessonIds = new Set();
+    for (const lesson of task.lessons ?? []) {
+        validateLesson(id, lesson);
+        if (lessonIds.has(lesson.id))
+            throw new Error(`Duplicate lesson id: ${id}/${lesson.id}`);
+        lessonIds.add(lesson.id);
+    }
+    if (task.lessonDisposition && (!["captured", "none"].includes(task.lessonDisposition.status) || !text(task.lessonDisposition.source) || !iso(task.lessonDisposition.recordedAt) || (task.lessonDisposition.status === "captured" && !(task.lessons?.length)) || (task.lessonDisposition.status === "none" && (Boolean(task.lessons?.length) || !text(task.lessonDisposition.reason)))))
+        throw new Error(`Invalid lesson disposition: ${id}`);
+    if (task.handoff && (!handoffKinds.includes(task.handoff.kind) || !text(task.handoff.reason) || !text(task.handoff.source) || !iso(task.handoff.recordedAt) || task.status !== "paused"))
+        throw new Error(`Invalid task handoff: ${id}`);
+    if (task.legacyG2Wait !== undefined && (typeof task.legacyG2Wait !== "object" || Array.isArray(task.legacyG2Wait) || !iso(task.legacyG2Wait.migratedAt) || !text(task.legacyG2Wait.source) || task.phase !== "build" || task.gate !== "G2_codereview" || task.status !== "blocked_on_user"))
+        throw new Error(`Invalid legacy G2 wait marker: ${id}`);
+    if ((task.status === "closed" || task.status === "superseded") !== Boolean(task.closure))
+        throw new Error(`Invalid task closure: ${id}`);
+    if (task.closure && (!text(task.closure.reason) || !text(task.closure.source) || !iso(task.closure.recordedAt)))
+        throw new Error(`Invalid task closure: ${id}`);
+    if ((task.status === "superseded") !== Boolean(task.successorTaskId) || (task.status === "closed" && task.successorTaskId))
+        throw new Error(`Invalid task successor: ${id}`);
+    if (task.predecessorTaskId !== undefined && !text(task.predecessorTaskId))
+        throw new Error(`Invalid task predecessor: ${id}`);
+    for (const path of Object.values(task.artifacts))
+        if (path)
+            assertTaskArtifactPath(id, path);
+};
+const validateArchiveSummary = (id, item) => {
+    if (!idPattern.test(id) || !item || item.id !== id || !text(item.title) || !["feature", "bug", "refactor", "infra"].includes(item.type) || !phases.includes(item.phase) || !gates.includes(item.gate) || item.gate !== phaseGate(item.phase) || !["done", "closed", "superseded"].includes(item.status) || !["low", "normal", "high", "regulated"].includes(item.risk) || !Array.isArray(item.areas) || !item.areas.length || item.areas.some((area) => !text(area)) || item.record !== `.agents/data/state/archive/${id}.json` || !/^[a-f0-9]{64}$/.test(item.digest) || !Number.isInteger(item.lessonCount) || item.lessonCount < 0 || !iso(item.createdAt) || !iso(item.updatedAt))
+        throw new Error(`Invalid archived task summary: ${id}`);
+    if ((item.status === "superseded") !== Boolean(item.successorTaskId) || (item.status === "closed" && item.successorTaskId) || (item.predecessorTaskId !== undefined && !text(item.predecessorTaskId)))
+        throw new Error(`Invalid archived task links: ${id}`);
+};
+export const validateState = (value) => {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error("Workflow state must be an object");
+    const state = value;
+    if (![1, 2, 3, 4].includes(Number(state.schemaVersion)) || !state.tasks || typeof state.tasks !== "object" || Array.isArray(state.tasks))
+        throw new Error("Unsupported workflow state schema");
+    if (Number(state.schemaVersion) >= 3 && (!state.archive || typeof state.archive !== "object" || Array.isArray(state.archive)))
+        throw new Error("Schema v3+ requires an archive catalog");
+    if (Number(state.schemaVersion) < 3 && state.archive !== undefined)
+        throw new Error("Legacy workflow state cannot contain an archive catalog");
+    if (Number(state.schemaVersion) < 4 && Object.values(state.tasks).some((task) => task?.legacyG2Wait !== undefined))
+        throw new Error("Legacy G2 wait markers require schema v4");
+    for (const [id, task] of Object.entries(state.tasks))
+        validateTask(id, task);
+    for (const [id, item] of Object.entries(state.archive ?? {})) {
+        if (state.tasks[id])
+            throw new Error(`Task exists in active and archive state: ${id}`);
+        validateArchiveSummary(id, item);
+    }
+    const references = { ...(state.archive ?? {}), ...state.tasks };
+    for (const [id, item] of Object.entries(references)) {
+        if (item.successorTaskId) {
+            const successor = references[item.successorTaskId];
+            if (!successor || successor.id === id || successor.predecessorTaskId !== id)
+                throw new Error(`Invalid successor link: ${id}`);
+        }
+        if (item.predecessorTaskId) {
+            const predecessor = references[item.predecessorTaskId];
+            if (!predecessor || predecessor.id === id || predecessor.status !== "superseded" || predecessor.successorTaskId !== id)
+                throw new Error(`Invalid predecessor link: ${id}`);
+        }
+        const seen = new Set([id]);
+        let cursor = item;
+        while (cursor.successorTaskId) {
+            if (seen.has(cursor.successorTaskId))
+                throw new Error(`Cyclic successor link: ${id}`);
+            seen.add(cursor.successorTaskId);
+            cursor = references[cursor.successorTaskId];
+        }
+    }
+    return state;
+};

package/dist/src/state.d.ts

@@ -1,117 +1,15 @@
-import type { AgenticMemoryEntry, AgenticMemoryRegistry, Diagnostic, Gate, HandoffKind, LessonIndex, LessonIndexEntry, LessonRecord, 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 emptyState: () => WorkflowState;
-export declare const legacyG2WaitSource = "schema-v4-migration";
-export declare const emptyMemoryRegistry: () => AgenticMemoryRegistry;
-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);
-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;
-export declare const validateState: (value: unknown) => WorkflowState;
-/** 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[];
-};
-export declare const loadState: (root: string) => WorkflowState;
-export declare const loadTask: (root: string, id: string, state?: WorkflowState) => TaskState | undefined;
-export declare const saveState: (root: string, state: WorkflowState) => string[];
-export declare const latestApproval: (task: TaskState, gate: Gate) => import("./model.js").Evidence | undefined;
-export declare const buildBoundary: (task: TaskState) => number | undefined;
-export declare const hasApproval: (task: TaskState, gate: Gate) => boolean;
-export declare const hasCurrentBuildApproval: (task: TaskState, gate: Gate) => boolean;
-export declare const hasAreaVerification: (task: TaskState, area: string) => boolean;
-export declare const hasVerification: (task: TaskState) => boolean;
-export declare const hasReview: (task: TaskState) => boolean;
-export interface RepairBounds {
-    verifyFailures: Record<string, number>;
-    reviewFailures: number;
-    exhaustedAreas: string[];
-    verifyExhausted: boolean;
-    reviewExhausted: boolean;
-}
-export declare const repairBounds: (task: TaskState) => RepairBounds;
-/** True only for a migration-stamped legacy G2 wait that is still fully ready; the stamp is written exclusively by schema migration. */
-export declare const isLegacyG2Wait: (task: TaskState) => boolean;
-export declare const transitionDiagnostics: (task: TaskState, target: Phase) => Diagnostic[];
-export declare const transitionTask: (state: WorkflowState, id: string, target: Phase) => TaskState;
-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?: Array<{
-        id: "reopen_g1" | "create_successor" | "supersede" | "close" | "record_handoff" | "resume";
-        command: string;
-    }>;
-    reason: string;
-}
-export declare const readyTaskItems: (task: TaskState) => {
-    ready: string[];
-    blocked: Array<{
-        id: string;
-        waitingOn: string[];
-    }>;
-};
-export declare const nextAction: (task: TaskState, root?: string) => NextAction;
-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;
-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[];
-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;
-};
-export declare const renderWorkplan: (task: TaskState) => string;
-export declare const renderViews: (root: string, state?: WorkflowState, selected?: TaskState[]) => void;
+/**
+ * Facade for the lifecycle-state domain. Behavior-preserving re-export of the
+ * split modules under `src/state/`; import paths from outside remain unchanged.
+ */
+export * from "./state/shared.js";
+export * from "./state/lock.js";
+export * from "./state/items.js";
+export * from "./state/transitions.js";
+export * from "./state/validate.js";
+export * from "./state/store.js";
+export * from "./state/memory.js";
+export * from "./state/lessons.js";
+export * from "./state/archive.js";
+export * from "./state/lifecycle.js";
+export * from "./state/render.js";