@felixdotgo/aidlc-kit 0.1.1 → 0.2.0

package/dist/src/model.d.ts

@@ -1,264 +1,11 @@
-export type AgentId = string;
-export type StateMutationMode = "native" | "scripted";
-export type Phase = "clarify" | "plan" | "build" | "wrap" | "done";
-export type Gate = "none" | "G0_confirm" | "G1_review" | "G2_codereview";
-export type TaskStatus = "active" | "blocked_on_user" | "paused" | "done" | "closed" | "superseded";
-export type RiskLevel = "low" | "normal" | "high" | "regulated";
-export type DecisionStatus = "unresolved" | "approved" | "changed" | "dropped";
-export type HandoffKind = "repair_exhausted" | "review_exhausted" | "g2_failed" | "release_failed" | "structural_change" | "other";
-export interface FileSpec {
-    path: string;
-    content: string;
-    owner: string;
-    strategy?: "replace" | "managed-block";
-    ownershipClass?: "managed" | "project" | "state";
-}
-export interface Adapter {
-    id: AgentId;
-    displayName: string;
-    detect(root: string): boolean;
-    files(): FileSpec[];
-}
-export interface PlannedWrite extends FileSpec {
-    action: "create" | "update" | "delete" | "skip" | "conflict" | "migrate" | "preserve";
-    reason: string;
-    contentEncoding?: "base64";
-}
-export interface InitOptions {
-    root: string;
-    agents: AgentId[];
-    all: boolean;
-    dryRun: boolean;
-    yes: boolean;
-    force: boolean;
-    loop?: LoopConfig;
-}
-export type LoopMode = "off" | "local" | "fleet";
-export declare const LOOP_PROVIDERS: readonly ["codex", "claude", "opencode"];
-export type LoopAgent = (typeof LOOP_PROVIDERS)[number];
-export interface LoopConfig {
-    mode: LoopMode;
-    agents?: {
-        lead: LoopAgent;
-        workers: Record<string, LoopAgent>;
-    };
-}
-export interface CommandSpec {
-    command: string;
-    args: string[];
-}
-export interface Profile {
-    schemaVersion: 1;
-    id: string;
-    extends?: string[];
-    topology: string;
-    discovery?: {
-        roots?: string[];
-        workspaceMarkers?: string[];
-    };
-    specs?: {
-        roots?: string[];
-    };
-    commands?: Record<string, CommandSpec>;
-    rules?: {
-        include?: string[];
-    };
-}
-export interface ProjectConfig {
-    schemaVersion: 1 | 2 | 3;
-    extends: string[];
-    specs: {
-        roots: string[];
-    };
-    commands: Record<string, CommandSpec>;
-    rules: {
-        include: string[];
-    };
-    risk: {
-        default: RiskLevel;
-    };
-    context: {
-        maxChars: number;
-    };
-    agentState: Partial<Record<AgentId, StateMutationMode>>;
-    tracker?: TrackerConfig;
-    mcp: McpConfig;
-    loop?: LoopConfig;
-}
-export interface McpConfig {
-    enabled: boolean;
-    endpoint?: string;
-    workspace?: string;
-    tokenEnv?: string;
-    pollMs?: number;
-    providers?: Array<"jira" | "trello" | "github-issues">;
-}
-export interface TrackerConfig {
-    enabled: boolean;
-    provider: "backlog";
-    spaceUrl: string;
-    project: string;
-    tokenEnv: string;
-    workflow: "waterfall" | "scrum";
-    mapping: {
-        statuses?: Partial<Record<"clarify" | "plan" | "build" | "wrap" | "done", number>>;
-        gateFieldId?: number;
-    };
-}
-export interface TaskDecision {
-    id: string;
-    label: string;
-    status: DecisionStatus;
-    resolution?: string;
-}
-export interface Evidence {
-    kind: "approval" | "spec" | "test" | "lint" | "review" | "diagnostic";
-    gate?: Gate;
-    area?: string;
-    source: string;
-    result: "pass" | "fail" | "skip";
-    detail?: string;
-    recordedAt: string;
-}
-export interface LessonRecord {
-    id: string;
-    taskId: string;
-    areas: string[];
-    summary: string;
-    prevention: string;
-    example: string;
-    promotion: string;
-    source: string;
-    recordedAt: string;
-}
-export interface LessonDisposition {
-    status: "captured" | "none";
-    reason?: string;
-    source: string;
-    recordedAt: string;
-}
-export interface TaskState {
-    id: string;
-    featureId?: string;
-    title: string;
-    type: "feature" | "bug" | "refactor" | "infra";
-    phase: Phase;
-    gate: Gate;
-    status: TaskStatus;
-    language: "vi" | "en";
-    risk: RiskLevel;
-    areas: string[];
-    branch: string;
-    artifacts: {
-        intent?: string;
-        design?: string;
-        workplan?: string;
-    };
-    decisions: TaskDecision[];
-    tasks: Array<{
-        id: string;
-        label: string;
-        status: "todo" | "in_progress" | "done" | "deferred";
-        dependsOn?: string[];
-        ownedPaths?: string[];
-    }>;
-    evidence: Evidence[];
-    lessons?: LessonRecord[];
-    lessonDisposition?: LessonDisposition;
-    handoff?: {
-        kind: HandoffKind;
-        reason: string;
-        source: string;
-        recordedAt: string;
-    };
-    closure?: {
-        reason: string;
-        source: string;
-        recordedAt: string;
-    };
-    legacyG2Wait?: {
-        migratedAt: string;
-        source: string;
-    };
-    predecessorTaskId?: string;
-    successorTaskId?: string;
-    createdAt: string;
-    updatedAt: string;
-}
-export interface WorkflowState {
-    schemaVersion: 1 | 2 | 3 | 4;
-    tasks: Record<string, TaskState>;
-    archive?: Record<string, ArchivedTaskSummary>;
-}
-export interface ArchivedTaskSummary {
-    id: string;
-    title: string;
-    type: TaskState["type"];
-    phase: Phase;
-    gate: Gate;
-    status: "done" | "closed" | "superseded";
-    risk: RiskLevel;
-    areas: string[];
-    record: string;
-    digest: string;
-    lessonCount: number;
-    predecessorTaskId?: string;
-    successorTaskId?: string;
-    createdAt: string;
-    updatedAt: string;
-}
-export interface LessonIndexEntry {
-    id: string;
-    taskId: string;
-    areas: string[];
-    summary: string;
-    prevention: string;
-    source: string;
-    recordedAt: string;
-}
-export interface LessonIndex {
-    schemaVersion: 1;
-    sourceDigest: string;
-    lessons: LessonIndexEntry[];
-}
-export interface AgenticMemoryEntry {
-    id: string;
-    summary: string;
-    guidance: string;
-    areas: string[];
-    phases: Array<Exclude<Phase, "done"> | "*">;
-    priority: number;
-    sourceTaskId: string;
-    sourceLessonId: string;
-    approvedBy: string;
-    approvedAt: string;
-}
-export interface AgenticMemoryRegistry {
-    schemaVersion: 1;
-    entries: AgenticMemoryEntry[];
-    retired: Array<AgenticMemoryEntry & {
-        retiredBy: string;
-        retiredAt: string;
-        reason: string;
-    }>;
-}
-export interface ManifestInventoryItem {
-    hash: string;
-    owner: string;
-    strategy: "replace" | "managed-block";
-}
-export interface WorkflowManifest {
-    schemaVersion: 2;
-    packageVersion: string;
-    workflow: "AI-DLC";
-    source: "local-package-assets";
-    remoteUpdates: false;
-    managedBy: "aidlc-kit" | "aidlc-workflow";
-    adapters: AgentId[];
-    files: Record<string, ManifestInventoryItem>;
-}
-export interface Diagnostic {
-    level: "ERROR" | "WARN" | "INFO";
-    code: string;
-    message: string;
-}
+/**
+ * Facade for the shared type hub. Behavior-preserving re-export of the split
+ * modules under `src/model/`; import paths from outside remain unchanged.
+ */
+export type { AgentId, StateMutationMode, Phase, Gate, TaskStatus, RiskLevel, DecisionStatus, HandoffKind, Diagnostic } from "./model/lifecycle-enums.js";
+export type { FileSpec, Adapter, PlannedWrite, InitOptions } from "./model/install-contracts.js";
+export type { LoopMode, LoopAgent, LoopConfig, LoopLimits } from "./model/loop.js";
+export { LOOP_PROVIDERS } from "./model/loop.js";
+export type { CommandSpec, Profile, ProjectConfig, McpConfig, TrackerConfig } from "./model/config-contracts.js";
+export type { TaskDecision, Evidence, LessonRecord, LessonDisposition, TaskState, WorkflowState, ArchivedTaskSummary, LessonIndexEntry, LessonIndex, AgenticMemoryEntry, AgenticMemoryRegistry } from "./model/records.js";
+export type { ManifestInventoryItem, WorkflowManifest } from "./model/manifest.js";

package/dist/src/model.js

@@ -1 +1 @@
-export const LOOP_PROVIDERS = Object.freeze(["codex", "claude", "opencode"]);
+export { LOOP_PROVIDERS } from "./model/loop.js";

package/dist/src/profiles.d.ts

@@ -5,6 +5,8 @@ export declare const validateLoopConfig: (value: unknown) => LoopConfig;
 /** Validates a single profile file (built-in or local). */
 export declare const validateProfile: (value: unknown, label?: string) => Profile;
 export declare const defaultConfig: () => ProjectConfig;
+/** Validates and normalizes a parsed `.agents/config.json` value. */
+export declare const validateProjectConfig: (value: unknown) => ProjectConfig;
 /** Loads and validates `.agents/config.json`, falling back to the default config when absent. */
 export declare const loadProjectConfig: (root: string) => ProjectConfig;
 /** Resolves a list of profile ids into an ordered, cycle-free list of profiles. */

package/dist/src/profiles.js

@@ -33,10 +33,15 @@ export const validateLoopConfig = (value) => {
     if (value === undefined)
         return { mode: "off" };
     const item = object(value, "config.loop");
-    if (Object.keys(item).some((key) => !["mode", "agents"].includes(key)) || typeof item.mode !== "string" || !["off", "local", "fleet"].includes(item.mode))
+    if (Object.keys(item).some((key) => !["mode", "agents", "workerImage", "pollMs", "limits"].includes(key)) || typeof item.mode !== "string" || !["off", "local", "fleet"].includes(item.mode))
         throw new Error("config.loop requires a valid mode and only supported fields");
+    const workerImage = validateWorkerImageMap(item.workerImage);
+    if (item.pollMs !== undefined && (!Number.isSafeInteger(item.pollMs) || Number(item.pollMs) < 1_000 || Number(item.pollMs) > 300_000))
+        throw new Error("config.loop.pollMs must be an integer from 1000 to 300000");
+    const limits = validateLoopLimits(item.limits);
+    const optional = { ...(workerImage ? { workerImage } : {}), ...(item.pollMs !== undefined ? { pollMs: Number(item.pollMs) } : {}), ...(limits ? { limits } : {}) };
     if (item.agents === undefined)
-        return { mode: item.mode };
+        return { mode: item.mode, ...optional };
     const agents = object(item.agents, "config.loop.agents");
     if (Object.keys(agents).some((key) => !["lead", "workers"].includes(key)) || !isLoopProvider(agents.lead))
         throw new Error(`config.loop.agents.lead must be ${loopProviderNames}`);
@@ -44,7 +49,34 @@ export const validateLoopConfig = (value) => {
     for (const [id, provider] of Object.entries(workers))
         if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(id) || !isLoopProvider(provider))
             throw new Error(`config.loop.agents.workers must map worker IDs to ${loopProviderNames}`);
-    return { mode: item.mode, agents: { lead: agents.lead, workers: workers } };
+    return { mode: item.mode, agents: { lead: agents.lead, workers: workers }, ...optional };
+};
+/** Bounds mirror `validateLimits` in assets/aidlc/scripts/lib/loop-runtime.mjs. */
+const LOOP_LIMIT_BOUNDS = { maxTurns: 1_000, turnTimeoutMs: 3_600_000, maxStallTurns: 20 };
+const validateLoopLimits = (value) => {
+    if (value === undefined)
+        return undefined;
+    const map = object(value, "config.loop.limits");
+    const result = {};
+    for (const [key, entry] of Object.entries(map)) {
+        if (!Object.hasOwn(LOOP_LIMIT_BOUNDS, key))
+            throw new Error(`config.loop.limits supports only ${Object.keys(LOOP_LIMIT_BOUNDS).join(", ")}`);
+        const max = LOOP_LIMIT_BOUNDS[key];
+        if (!Number.isSafeInteger(entry) || Number(entry) < 1 || Number(entry) > max)
+            throw new Error(`config.loop.limits.${key} must be an integer from 1 to ${max}`);
+        result[key] = Number(entry);
+    }
+    return result;
+};
+const validateWorkerImageMap = (value) => {
+    if (value === undefined)
+        return undefined;
+    const map = object(value, "config.loop.workerImage");
+    for (const [provider, tag] of Object.entries(map)) {
+        if (!isLoopProvider(provider) || typeof tag !== "string" || !/^[a-zA-Z0-9][a-zA-Z0-9._/:@-]{0,255}$/.test(tag))
+            throw new Error(`config.loop.workerImage must map ${loopProviderNames} to image tags`);
+    }
+    return map;
 };
 const strings = (value, label) => {
     if (!Array.isArray(value) || value.some((item) => typeof item !== "string"))
@@ -127,6 +159,7 @@ export const validateProfile = (value, label = "profile") => {
     };
 };
 export const defaultConfig = () => ({
+    $schema: "./aidlc/schemas/config.schema.json",
     schemaVersion: 2,
     extends: ["topology/single"],
     specs: { roots: [] },
@@ -138,12 +171,9 @@ export const defaultConfig = () => ({
     mcp: { enabled: false },
     loop: { mode: "off" }
 });
-/** Loads and validates `.agents/config.json`, falling back to the default config when absent. */
-export const loadProjectConfig = (root) => {
-    const path = join(resolve(root), ".agents/config.json");
-    if (!existsSync(path))
-        return defaultConfig();
-    const item = object(JSON.parse(readFileSync(path, "utf8")), ".agents/config.json");
+/** Validates and normalizes a parsed `.agents/config.json` value. */
+export const validateProjectConfig = (value) => {
+    const item = object(value, ".agents/config.json");
     const risk = object(item.risk ?? {}, "config.risk");
     const context = object(item.context ?? {}, "config.context");
     const levels = ["low", "normal", "high", "regulated"];
@@ -159,7 +189,14 @@ export const loadProjectConfig = (root) => {
     const maxChars = Number(context.maxChars ?? 16_000);
     if (!Number.isInteger(maxChars) || maxChars < 4_000 || maxChars > 128_000)
         throw new Error("context.maxChars must be an integer from 4000 to 128000");
+    let schema;
+    if (item.$schema !== undefined) {
+        if (typeof item.$schema !== "string" || item.$schema.length > 512)
+            throw new Error("config.$schema must be a string of at most 512 characters");
+        schema = item.$schema;
+    }
     return {
+        $schema: schema,
         schemaVersion: Number(item.schemaVersion),
         extends: strings(item.extends ?? ["topology/single"], "config.extends"),
         specs: { roots: strings(object(item.specs ?? {}, "config.specs").roots ?? [], "config.specs.roots").map((entry) => safeRelative(entry, "config.specs.roots")) },
@@ -173,6 +210,13 @@ export const loadProjectConfig = (root) => {
         loop: validateLoopConfig(item.loop)
     };
 };
+/** Loads and validates `.agents/config.json`, falling back to the default config when absent. */
+export const loadProjectConfig = (root) => {
+    const path = join(resolve(root), ".agents/config.json");
+    if (!existsSync(path))
+        return defaultConfig();
+    return validateProjectConfig(JSON.parse(readFileSync(path, "utf8")));
+};
 const readLocalProfile = (root, id) => {
     const path = join(resolve(root), ".agents/project/profiles", safeRelative(id, "profile id"), "profile.json");
     if (!existsSync(path))

package/dist/src/state/archive-record.d.ts

@@ -0,0 +1,9 @@
+import type { ArchivedTaskSummary, TaskState } from "../model.js";
+export declare const taskRecordContent: (task: TaskState) => string;
+/** Builds the immutable archive-catalog summary for a terminal task from its record content. */
+export declare const archivedSummary: (task: TaskState, content?: string) => ArchivedTaskSummary;
+/** Single terminal-to-archive policy shared by auto-archive on save and schema migration. */
+export declare const buildArchiveRecord: (task: TaskState) => {
+    content: string;
+    summary: ArchivedTaskSummary;
+};

package/dist/src/state/archive-record.js

@@ -0,0 +1,26 @@
+import { digest } from "./domain.js";
+import { archiveRecordPath } from "./paths.js";
+export const taskRecordContent = (task) => `${JSON.stringify(task, null, 2)}\n`;
+/** 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
+});
+/** Single terminal-to-archive policy shared by auto-archive on save and schema migration. */
+export const buildArchiveRecord = (task) => {
+    const content = taskRecordContent(task);
+    return { content, summary: archivedSummary(task, content) };
+};

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

@@ -0,0 +1,18 @@
+import type { TaskState } from "../model.js";
+export type NextActionActions = Array<{
+    id: "reopen_g1" | "create_successor" | "supersede" | "close" | "record_handoff" | "resume";
+    command: string;
+}>;
+export interface CommandKit {
+    continueItem: (taskId: string, itemId: string) => string;
+    continueVerification: (taskId: string) => string;
+    continuePhase: (taskId: string, phase: string) => string;
+    recoverG1Wait: (taskId: string) => string;
+    recoverGatelessWrap: (taskId: string) => string;
+    approveGate: (taskId: string, gate: string) => string;
+    handoffActions: (task: TaskState) => NextActionActions;
+    pausedActions: (taskId: string) => NextActionActions;
+    repairHandoffAction: (taskId: string, kind: "review_exhausted" | "repair_exhausted") => NextActionActions;
+}
+/** Command-string synthesis for `nextAction`: script paths, `--root` suffixes, and CLI placeholders exist only here. */
+export declare const commandKit: (root?: string) => CommandKit;

package/dist/src/state/commands.js

@@ -0,0 +1,27 @@
+import { join, resolve } from "node:path";
+/** Command-string synthesis for `nextAction`: script paths, `--root` suffixes, and CLI placeholders exist only here. */
+export const commandKit = (root) => {
+    const suffix = root === undefined ? "" : ` --root ${JSON.stringify(resolve(root))}`;
+    const script = (name) => root === undefined ? `node .agents/aidlc/scripts/${name}` : `node ${JSON.stringify(join(resolve(root), ".agents/aidlc/scripts", name))}`;
+    const stateScript = script("state.mjs");
+    const contextScript = script("context.mjs");
+    return {
+        continueItem: (taskId, itemId) => `${contextScript} ${taskId} --phase build --item ${itemId}${suffix}`,
+        continueVerification: (taskId) => `${contextScript} ${taskId} --phase build${suffix}`,
+        continuePhase: (taskId, phase) => `${contextScript} ${taskId} --phase ${phase}${suffix}`,
+        recoverG1Wait: (taskId) => `${contextScript} ${taskId} --phase plan${suffix}`,
+        recoverGatelessWrap: (taskId) => `${stateScript} task status ${taskId} --status active${suffix}`,
+        approveGate: (taskId, gate) => `${stateScript} gate approve ${taskId} --gate ${gate} --source <explicit-user-approval>${suffix}`,
+        handoffActions: (task) => [
+            ...(task.phase === "build" ? [{ id: "reopen_g1", command: `${stateScript} task reopen ${task.id} --to plan --reason <reason> --source <explicit-user-request>${suffix}` }] : []),
+            { id: "create_successor", command: `${stateScript} task create <new-task-id> --title <title>${suffix}` },
+            { id: "supersede", command: `${stateScript} task supersede ${task.id} --successor <new-task-id> --reason <reason> --source <explicit-user-request>${suffix}` },
+            { id: "close", command: `${stateScript} task close ${task.id} --reason <reason> --source <explicit-user-request>${suffix}` }
+        ],
+        pausedActions: (taskId) => [
+            { id: "resume", command: `${stateScript} task status ${taskId} --status active${suffix}` },
+            { id: "record_handoff", command: `${stateScript} task handoff ${taskId} --kind <kind> --reason <reason> --source <source>${suffix}` }
+        ],
+        repairHandoffAction: (taskId, kind) => [{ id: "record_handoff", command: `${stateScript} task handoff ${taskId} --kind ${kind} --reason <summary-of-exhausted-repairs> --source <agent>${suffix}` }]
+    };
+};

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

@@ -0,0 +1,9 @@
+import type { Gate, HandoffKind, Phase, TaskState, WorkflowState } from "../model.js";
+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 digest: (content: string) => string;

package/dist/src/state/domain.js

@@ -0,0 +1,9 @@
+import { createHash } from "node:crypto";
+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 digest = (content) => createHash("sha256").update(content).digest("hex");

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

@@ -0,0 +1,7 @@
+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 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;

package/dist/src/state/guards.js

@@ -0,0 +1,17 @@
+import { isAbsolute, normalize } from "node:path";
+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 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}`);
+    }
+};

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

@@ -0,0 +1,10 @@
+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;
+/** Resolves a project-relative state path to its absolute form, rejecting symlink-crossing variants first. */
+export declare const safeResolvedPath: (root: string, relative: string) => string;
+/** Loads and validates a canonical JSON state file, or produces the fallback when the file does not exist. */
+export declare const loadJsonOr: <T>(root: string, relative: string, validate: (value: unknown) => T, fallback: () => T, label: string, recovery?: string) => T;
+/** Persists a JSON state file atomically in the canonical 2-space, trailing-newline formatting. */
+export declare const saveJson: (root: string, relative: string, value: unknown) => void;

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

@@ -1,4 +1,5 @@
 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;
@@ -8,10 +9,7 @@ export interface NextAction {
     successorTaskId?: string;
     itemId?: string;
     remainingItems?: number;
-    actions?: Array<{
-        id: "reopen_g1" | "create_successor" | "supersede" | "close" | "record_handoff" | "resume";
-        command: string;
-    }>;
+    actions?: NextActionActions;
     reason: string;
 }
 /** Validates execution dependencies and reports which pending items are ready to dispatch. */
@@ -22,4 +20,5 @@ export declare const readyTaskItems: (task: TaskState) => {
         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;