@felixdotgo/aidlc-kit 0.1.0 → 0.2.0

package/dist/src/state/migrate.js

@@ -0,0 +1,60 @@
+import { existsSync, readFileSync } from "node:fs";
+import { buildArchiveRecord } from "./archive-record.js";
+import { legacyG2WaitSource, terminal } from "./domain.js";
+import { safeResolvedPath, writeAtomic } from "./io.js";
+import { createLessonIndex, lessonStateDigest, rebuildLessonIndex } from "./lessons.js";
+import { hasReview, hasVerification } from "./transitions.js";
+import { loadState, saveState } from "./store.js";
+import { validateState } from "./validate.js";
+/** Marks pre-existing ready G2 waits during migration; the marker is the only exemption from repair-bound enforcement. */
+export const stampLegacyG2Waits = (state) => {
+    const stamped = [];
+    for (const task of Object.values(state.tasks)) {
+        if (task.legacyG2Wait !== undefined)
+            continue;
+        if (task.phase !== "build" || task.gate !== "G2_codereview" || task.status !== "blocked_on_user")
+            continue;
+        if (!task.tasks.every((item) => item.status === "done" || item.status === "deferred") || !hasVerification(task) || !hasReview(task))
+            continue;
+        task.legacyG2Wait = { migratedAt: task.updatedAt, source: legacyG2WaitSource };
+        stamped.push(task.id);
+    }
+    return stamped;
+};
+export const prepareV4Migration = (value) => {
+    const source = validateState(value);
+    const next = { schemaVersion: 4, tasks: {}, archive: {} };
+    const records = [];
+    for (const task of Object.values(source.tasks)) {
+        if (!terminal(task))
+            next.tasks[task.id] = task;
+        else {
+            const { content, summary } = buildArchiveRecord(task);
+            next.archive[task.id] = summary;
+            records.push({ path: summary.record, content });
+        }
+    }
+    for (const item of Object.values(source.archive ?? {}))
+        next.archive[item.id] = item;
+    const stamped = Number(source.schemaVersion) < 4 ? stampLegacyG2Waits(next) : [];
+    validateState(next);
+    const lessons = Object.values(source.tasks).flatMap((task) => task.lessons ?? []);
+    return { state: next, records, lessonIndex: createLessonIndex(lessons, lessonStateDigest(next)), stamped };
+};
+export const migrateState = (root, state = loadState(root)) => {
+    if (state.schemaVersion === 4)
+        return { migrated: false, archived: [], stamped: [] };
+    const migration = prepareV4Migration(state);
+    for (const record of migration.records) {
+        const path = safeResolvedPath(root, record.path);
+        if (existsSync(path)) {
+            if (readFileSync(path, "utf8") !== record.content)
+                throw new Error(`Archived task record conflicts: ${record.path}`);
+        }
+        else
+            writeAtomic(path, record.content);
+    }
+    saveState(root, migration.state);
+    rebuildLessonIndex(root, migration.state);
+    return { migrated: true, archived: Object.keys(migration.state.archive ?? {}), stamped: migration.stamped };
+};

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

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

package/dist/src/state/partition.js

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

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

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

package/dist/src/state/paths.js

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

package/dist/src/state/render.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,32 @@
+import { tokens } from "./guards.js";
+import { safeResolvedPath, writeAtomic } from "./io.js";
+import { loadState } from "./store.js";
+import { workplanScope } from "./partition.js";
+export const listTaskSummaries = (state, options = {}) => {
+    const active = Object.values(state.tasks).map((task) => ({ id: task.id, title: task.title, phase: task.phase, gate: task.gate, status: task.status, risk: task.risk, areas: task.areas, updatedAt: task.updatedAt, source: "active" }));
+    const archived = options.includeArchive ? Object.values(state.archive ?? {}).map((task) => ({ id: task.id, title: task.title, phase: task.phase, gate: task.gate, status: task.status, risk: task.risk, areas: task.areas, updatedAt: task.updatedAt, source: "archive" })) : [];
+    const queryTokens = tokens(options.query ?? "");
+    const statuses = new Set(options.statuses ?? []);
+    const filtered = [...active, ...archived]
+        .filter((item) => (!statuses.size || statuses.has(item.status)) &&
+        (!queryTokens.length || queryTokens.every((token) => tokens(`${item.id} ${item.title} ${item.areas.join(" ")}`).includes(token))))
+        .sort((a, b) => b.updatedAt.localeCompare(a.updatedAt) || a.id.localeCompare(b.id));
+    const 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}${workplanScope(item)}`).join("\n") : "- None";
+    const lifecycle = [`- Status: \`${task.status}\``, task.handoff ? `- Handoff: \`${task.handoff.kind}\` — ${task.handoff.reason}` : "", task.closure ? `- Closure: ${task.closure.reason}` : "", task.predecessorTaskId ? `- Predecessor: \`${task.predecessorTaskId}\`` : "", task.successorTaskId ? `- Successor: \`${task.successorTaskId}\`` : "", task.lessonDisposition ? `- Lessons: \`${task.lessonDisposition.status}\`` : ""].filter(Boolean).join("\n");
+    return `# Workplan — ${task.title} (\`${task.id}\`)\n\n> Generated from canonical JSON state.\n\n## Lifecycle\n${lifecycle}\n\n## 🧩 Decisions (Approve plan — before implementation)\n${decisions}\n\n## 🧩 Tasks (Review implementation — work items)\n${tasks}\n`;
+};
+export const renderViews = (root, state = loadState(root), selected = Object.values(state.tasks)) => {
+    for (const task of selected) {
+        if (!task.artifacts.workplan)
+            continue;
+        writeAtomic(safeResolvedPath(root, task.artifacts.workplan), renderWorkplan(task));
+    }
+};

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,75 @@
+import { existsSync, readFileSync } from "node:fs";
+import { buildArchiveRecord } from "./archive-record.js";
+import { digest, emptyState, terminal } from "./domain.js";
+import { loadJsonOr, parseJsonText, safeResolvedPath, saveJson, writeAtomic } from "./io.js";
+import { statePath, statePathRelative } from "./paths.js";
+import { validateState, validateTask } from "./validate.js";
+export const loadState = (root) => loadJsonOr(root, statePathRelative, validateState, emptyState, "AI-DLC state file", "restore it from git history or the archive records");
+export const loadTask = (root, id, state = loadState(root)) => {
+    if (state.tasks[id])
+        return state.tasks[id];
+    const summary = state.archive?.[id];
+    if (!summary)
+        return undefined;
+    const path = safeResolvedPath(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, summary } = buildArchiveRecord(task);
+        const path = safeResolvedPath(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);
+    saveJson(root, statePathRelative, normalized);
+    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,95 @@
+import { phaseGate, phases, terminal } from "./domain.js";
+export const latestApproval = (task, gate) => {
+    for (let index = task.evidence.length - 1; index >= 0; index -= 1) {
+        const item = task.evidence[index];
+        if (item && 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 && 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) {
+        const item = items[index];
+        if (item && predicate(item))
+            return item;
+    }
+    return undefined;
+};
+export const hasCurrentBuildApproval = (task, gate) => latestInOrder(currentBuildEvidence(task), (item) => item.kind === "approval" && item.gate === gate)?.result === "pass";
+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] ?? 0) >= 3).sort();
+    return { verifyFailures, reviewFailures, exhaustedAreas, verifyExhausted: exhaustedAreas.length > 0, reviewExhausted: reviewFailures >= 2 };
+};
+/** True only for a migration-stamped legacy G2 wait that is still fully ready; the stamp is written exclusively by schema migration. */
+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,143 @@
+import { gates, handoffKinds, phaseGate, phases } from "./domain.js";
+import { assertTaskArtifactPath, idPattern, iso, text } from "./guards.js";
+import { readyTaskItems } from "./items.js";
+import { archiveRecordPath } from "./paths.js";
+const taskStatuses = ["active", "blocked_on_user", "paused", "done", "closed", "superseded"];
+export const validateLesson = (taskId, lesson) => {
+    if (!lesson)
+        throw new Error(`Invalid lesson: ${taskId}`);
+    if (!idPattern.test(lesson.id) || lesson.taskId !== taskId)
+        throw new Error(`Invalid lesson: ${taskId}`);
+    if (!Array.isArray(lesson.areas) || !lesson.areas.length || lesson.areas.some((area) => !text(area)))
+        throw new Error(`Invalid lesson: ${taskId}`);
+    if (!text(lesson.summary) || !text(lesson.prevention) || !text(lesson.example))
+        throw new Error(`Invalid lesson: ${taskId}`);
+    if (!text(lesson.promotion) || !text(lesson.source) || !iso(lesson.recordedAt))
+        throw new Error(`Invalid lesson: ${taskId}`);
+};
+export const validateTask = (id, task) => {
+    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))
+        throw new Error(`Invalid archived task summary: ${id}`);
+    if (!item || item.id !== id || !text(item.title))
+        throw new Error(`Invalid archived task summary: ${id}`);
+    if (!["feature", "bug", "refactor", "infra"].includes(item.type))
+        throw new Error(`Invalid archived task summary: ${id}`);
+    if (!phases.includes(item.phase) || !gates.includes(item.gate) || item.gate !== phaseGate(item.phase))
+        throw new Error(`Invalid archived task summary: ${id}`);
+    if (!["done", "closed", "superseded"].includes(item.status) || !["low", "normal", "high", "regulated"].includes(item.risk))
+        throw new Error(`Invalid archived task summary: ${id}`);
+    if (!Array.isArray(item.areas) || !item.areas.length || item.areas.some((area) => !text(area)))
+        throw new Error(`Invalid archived task summary: ${id}`);
+    if (item.record !== archiveRecordPath(id) || !/^[a-f0-9]{64}$/.test(item.digest))
+        throw new Error(`Invalid archived task summary: ${id}`);
+    if (!Number.isInteger(item.lessonCount) || item.lessonCount < 0 || !iso(item.createdAt) || !iso(item.updatedAt))
+        throw new Error(`Invalid archived task summary: ${id}`);
+    if ((item.status === "superseded") !== Boolean(item.successorTaskId) || (item.status === "closed" && item.successorTaskId) || (item.predecessorTaskId !== undefined && !text(item.predecessorTaskId)))
+        throw new Error(`Invalid archived task links: ${id}`);
+};
+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);
+            const next = references[cursor.successorTaskId];
+            if (!next)
+                throw new Error(`Invalid successor link: ${id}`);
+            cursor = next;
+        }
+    }
+    return state;
+};