@felixdotgo/aidlc-kit 0.1.1 → 0.3.0

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;

package/dist/src/state/items.js

@@ -1,7 +1,6 @@
-import { isAbsolute, join, resolve } from "node:path";
+import { isAbsolute } from "node:path";
+import { commandKit } from "./commands.js";
 import { hasReview, hasVerification, isLegacyG2Wait, repairBounds } from "./transitions.js";
-const rootSuffix = (root) => root === undefined ? "" : ` --root ${JSON.stringify(resolve(root))}`;
-const script = (root, name) => root === undefined ? `node .agents/aidlc/scripts/${name}` : `node ${JSON.stringify(join(resolve(root), ".agents/aidlc/scripts", name))}`;
 const isPending = (item) => item.status === "in_progress" || item.status === "todo";
 const pendingItems = (task) => task.tasks.filter(isPending);
 /** Validates execution dependencies and reports which pending items are ready to dispatch. */
@@ -28,7 +27,15 @@ export const readyTaskItems = (task) => {
     for (const item of task.tasks) {
         if (item.dependsOn !== undefined && (!Array.isArray(item.dependsOn) || new Set(item.dependsOn).size !== item.dependsOn.length || item.dependsOn.some((dep) => typeof dep !== "string" || !dep)))
             throw new Error(`Invalid execution dependencies: ${task.id}/${item.id}`);
-        if (item.ownedPaths !== undefined && (!Array.isArray(item.ownedPaths) || new Set(item.ownedPaths).size !== item.ownedPaths.length || item.ownedPaths.some((path) => typeof path !== "string" || !path || isAbsolute(path) || path === ".." || path.startsWith("../") || path.includes("\\") || path.split("/").includes(".."))))
+        if (item.ownedPaths !== undefined && (!Array.isArray(item.ownedPaths) ||
+            new Set(item.ownedPaths).size !== item.ownedPaths.length ||
+            item.ownedPaths.some((path) => typeof path !== "string" ||
+                !path ||
+                isAbsolute(path) ||
+                path === ".." ||
+                path.startsWith("../") ||
+                path.includes("\\") ||
+                path.split("/").includes(".."))))
             throw new Error(`Invalid owned paths: ${task.id}/${item.id}`);
         visit(item.id);
     }
@@ -52,50 +59,27 @@ const dispatchableItem = (open, task) => {
     return open.find((entry) => entry.status === "in_progress" && ready.has(entry.id)) ?? open.find((entry) => ready.has(entry.id));
 };
 const noReadyItemReason = (task) => `No dependency-ready build item: ${readyTaskItems(task).blocked.map((entry) => `${entry.id} waits for ${entry.waitingOn.join(",")}`).join("; ")}`;
-const handoffActions = (task, suffix, stateCommand) => [
-    ...(task.phase === "build" ? [{ id: "reopen_g1", command: `${stateCommand} task reopen ${task.id} --to plan --reason <reason> --source <explicit-user-request>${suffix}` }] : []),
-    { id: "create_successor", command: `${stateCommand} task create <new-task-id> --title <title>${suffix}` },
-    { id: "supersede", command: `${stateCommand} task supersede ${task.id} --successor <new-task-id> --reason <reason> --source <explicit-user-request>${suffix}` },
-    { id: "close", command: `${stateCommand} task close ${task.id} --reason <reason> --source <explicit-user-request>${suffix}` }
-];
-const pausedActions = (task, suffix, stateCommand) => [
-    { id: "resume", command: `${stateCommand} task status ${task.id} --status active${suffix}` },
-    { id: "record_handoff", command: `${stateCommand} task handoff ${task.id} --kind <kind> --reason <reason> --source <source>${suffix}` }
-];
-const repairExhausted = (task, suffix, stateCommand) => {
+const repairExhausted = (task) => {
     if (task.phase !== "build" || isLegacyG2Wait(task))
         return undefined;
     const bounds = repairBounds(task);
     if (!bounds.verifyExhausted && !bounds.reviewExhausted)
         return undefined;
-    const kind = bounds.reviewExhausted ? "review_exhausted" : "repair_exhausted";
+    const handoffKind = bounds.reviewExhausted ? "review_exhausted" : "repair_exhausted";
     const detail = bounds.verifyExhausted ? `3+ failed verify cycles in: ${bounds.exhaustedAreas.join(", ")}` : `${bounds.reviewFailures} failed review passes`;
-    return {
-        classification: "blocked",
-        phase: task.phase,
-        gate: task.gate,
-        reason: `Repair bound exhausted (${detail}); record a durable handoff`,
-        actions: [{ id: "record_handoff", command: `${stateCommand} task handoff ${task.id} --kind ${kind} --reason <summary-of-exhausted-repairs> --source <agent>${suffix}` }]
-    };
+    return { kind: "repair_exhausted", handoffKind, reason: `Repair bound exhausted (${detail}); record a durable handoff` };
 };
-const continueItem = (item, openCount, task, suffix, contextCommand, premature) => ({
-    classification: "run_phase",
-    phase: task.phase,
-    gate: task.gate,
+const continueItem = (item, openCount, premature) => ({
+    kind: "continue_item",
     itemId: item.id,
     remainingItems: openCount,
-    command: `${contextCommand} ${task.id} --phase build --item ${item.id}${suffix}`,
     reason: premature ? `Invalid premature G2 wait; continue build item ${item.id}` : `Continue build item ${item.id}; ${openCount} actionable item(s) remain before verification, review, and G2`
 });
-const continueVerification = (task, suffix, contextCommand, premature) => ({
-    classification: "run_phase",
-    phase: task.phase,
-    gate: task.gate,
-    remainingItems: 0,
-    command: `${contextCommand} ${task.id} --phase build${suffix}`,
+const continueVerification = (premature) => ({
+    kind: "continue_verification",
     reason: premature ? "Invalid premature G2 wait; continue verification and adversarial review before presenting G2" : "All build items are terminal; continue verification, adversarial review, and G2 preparation"
 });
-const prematureG2Wait = (task, suffix, contextCommand) => {
+const prematureG2Wait = (task) => {
     if (task.status !== "blocked_on_user" || task.gate !== "G2_codereview")
         return undefined;
     if (!(task.tasks.some((item) => !["done", "deferred"].includes(item.status)) || !hasVerification(task) || !hasReview(task)))
@@ -103,44 +87,61 @@ const prematureG2Wait = (task, suffix, contextCommand) => {
     const open = pendingItems(task);
     const item = dispatchableItem(open, task);
     if (item)
-        return continueItem(item, open.length, task, suffix, contextCommand, true);
+        return continueItem(item, open.length, true);
     if (open.length)
-        return { classification: "blocked", phase: task.phase, gate: task.gate, reason: noReadyItemReason(task) };
-    return continueVerification(task, suffix, contextCommand, true);
+        return { kind: "no_ready_item", reason: noReadyItemReason(task) };
+    return continueVerification(true);
 };
-export const nextAction = (task, root) => {
-    const suffix = rootSuffix(root);
-    const stateCommand = script(root, "state.mjs");
-    const contextCommand = script(root, "context.mjs");
+/** Pure classification: maps a task onto its next-action decision without touching any command string. */
+const classify = (task) => {
     if (task.phase === "done")
-        return { classification: "complete", phase: task.phase, gate: task.gate, reason: "Task is complete" };
+        return { kind: "complete", reason: "Task is complete" };
     if (task.status === "closed" || task.status === "superseded")
-        return { classification: "terminal", phase: task.phase, gate: task.gate, outcome: task.status, successorTaskId: task.successorTaskId, reason: task.closure?.reason ?? "Task ended without successful completion" };
+        return { kind: "terminal", outcome: task.status, successorTaskId: task.successorTaskId, reason: task.closure?.reason ?? "Task ended without successful completion" };
     if (task.handoff)
-        return { classification: "blocked", phase: task.phase, gate: task.gate, reason: task.handoff.reason, actions: handoffActions(task, suffix, stateCommand) };
+        return { kind: "handoff", reason: task.handoff.reason };
     if (task.status === "paused")
-        return { classification: "blocked", phase: task.phase, gate: task.gate, reason: "Task is paused", actions: pausedActions(task, suffix, stateCommand) };
-    const repair = repairExhausted(task, suffix, stateCommand);
+        return { kind: "paused", reason: "Task is paused" };
+    const repair = repairExhausted(task);
     if (repair)
         return repair;
-    const prematureG2 = prematureG2Wait(task, suffix, contextCommand);
+    const prematureG2 = prematureG2Wait(task);
     if (prematureG2)
         return prematureG2;
-    if (task.status === "blocked_on_user" && task.gate === "G1_review" && task.decisions.some((decision) => decision.status === "unresolved")) {
-        return { classification: "run_phase", phase: task.phase, gate: task.gate, command: `${contextCommand} ${task.id} --phase plan${suffix}`, reason: "Invalid premature G1 wait; resolve every decision before presenting G1" };
-    }
+    if (task.status === "blocked_on_user" && task.gate === "G1_review" && task.decisions.some((decision) => decision.status === "unresolved"))
+        return { kind: "recover_g1_wait", reason: "Invalid premature G1 wait; resolve every decision before presenting G1" };
     if (task.status === "blocked_on_user" && task.gate === "none")
-        return { classification: "run_phase", phase: task.phase, gate: task.gate, command: `${stateCommand} task status ${task.id} --status active${suffix}`, reason: "Recover invalid wait at a gateless wrap phase before continuing wrap" };
+        return { kind: "recover_gateless_wrap", reason: "Recover invalid wait at a gateless wrap phase before continuing wrap" };
     if (task.status === "blocked_on_user")
-        return { classification: "await_user", phase: task.phase, gate: task.gate, command: `${stateCommand} gate approve ${task.id} --gate ${task.gate} --source <explicit-user-approval>${suffix}`, reason: `Explicit human approval is required at ${task.gate}` };
+        return { kind: "await_user", reason: `Explicit human approval is required at ${task.gate}` };
     if (task.phase === "build") {
         const open = pendingItems(task);
         const item = dispatchableItem(open, task);
         if (item)
-            return continueItem(item, open.length, task, suffix, contextCommand, false);
+            return continueItem(item, open.length, false);
         if (open.length)
-            return { classification: "blocked", phase: task.phase, gate: task.gate, reason: noReadyItemReason(task) };
-        return continueVerification(task, suffix, contextCommand, false);
+            return { kind: "no_ready_item", reason: noReadyItemReason(task) };
+        return continueVerification(false);
+    }
+    return { kind: "continue_phase", reason: `Continue ${task.phase} until the next human gate, real blocker, or completion` };
+};
+/** Attaches the command strings a decision implies; the single call site of the command kit. */
+const realize = (task, decision, commands) => {
+    const base = { phase: task.phase, gate: task.gate };
+    switch (decision.kind) {
+        case "complete": return { classification: "complete", ...base, reason: decision.reason };
+        case "terminal": return { classification: "terminal", ...base, outcome: decision.outcome, successorTaskId: decision.successorTaskId, reason: decision.reason };
+        case "handoff": return { classification: "blocked", ...base, reason: decision.reason, actions: commands.handoffActions(task) };
+        case "paused": return { classification: "blocked", ...base, reason: decision.reason, actions: commands.pausedActions(task.id) };
+        case "repair_exhausted": return { classification: "blocked", ...base, reason: decision.reason, actions: commands.repairHandoffAction(task.id, decision.handoffKind) };
+        case "continue_item": return { classification: "run_phase", ...base, itemId: decision.itemId, remainingItems: decision.remainingItems, command: commands.continueItem(task.id, decision.itemId), reason: decision.reason };
+        case "continue_verification": return { classification: "run_phase", ...base, remainingItems: 0, command: commands.continueVerification(task.id), reason: decision.reason };
+        case "no_ready_item": return { classification: "blocked", ...base, reason: decision.reason };
+        case "recover_g1_wait": return { classification: "run_phase", ...base, command: commands.recoverG1Wait(task.id), reason: decision.reason };
+        case "recover_gateless_wrap": return { classification: "run_phase", ...base, command: commands.recoverGatelessWrap(task.id), reason: decision.reason };
+        case "await_user": return { classification: "await_user", ...base, command: commands.approveGate(task.id, task.gate), reason: decision.reason };
+        case "continue_phase": return { classification: "run_phase", ...base, command: commands.continuePhase(task.id, task.phase), reason: decision.reason };
     }
-    return { classification: "run_phase", phase: task.phase, gate: task.gate, command: `${contextCommand} ${task.id} --phase ${task.phase}${suffix}`, reason: `Continue ${task.phase} until the next human gate, real blocker, or completion` };
 };
+/** Classifies the next lifecycle action for a task and attaches root-qualified command strings. */
+export const nextAction = (task, root) => realize(task, classify(task), commandKit(root));

package/dist/src/state/lessons.js

@@ -1,7 +1,10 @@
 import { existsSync } from "node:fs";
-import { validateLesson } from "./validate.js";
+import { digest } from "./domain.js";
+import { audited, tokens } from "./guards.js";
+import { assertNoSymlinkPath, parseJsonFile, saveJson } from "./io.js";
+import { lessonIndexPath, lessonIndexPathRelative } from "./paths.js";
 import { loadState, loadTask } from "./store.js";
-import { assertNoSymlinkPath, audited, digest, lessonIndexPath, parseJsonFile, tokens, writeAtomic } from "./shared.js";
+import { validateLesson } from "./validate.js";
 const lessonEntry = (lesson) => ({ id: lesson.id, taskId: lesson.taskId, areas: lesson.areas, summary: lesson.summary, prevention: lesson.prevention, source: lesson.source, recordedAt: lesson.recordedAt });
 export const recordLesson = (task, lesson, recordedAt = new Date().toISOString()) => {
     if (task.phase !== "wrap" || task.status !== "active")
@@ -40,13 +43,12 @@ const allLessons = (root, state) => [
 ];
 export const rebuildLessonIndex = (root, state = loadState(root)) => {
     const index = createLessonIndex(allLessons(root, state), lessonStateDigest(state));
-    assertNoSymlinkPath(root, ".agents/data/lessons/index.json");
-    writeAtomic(lessonIndexPath(root), `${JSON.stringify(index, null, 2)}\n`);
+    saveJson(root, lessonIndexPathRelative, index);
     return index;
 };
 export const searchLessons = (root, state, query, areas = [], limit = 5) => {
     const path = lessonIndexPath(root);
-    assertNoSymlinkPath(root, ".agents/data/lessons/index.json");
+    assertNoSymlinkPath(root, lessonIndexPathRelative);
     if (!existsSync(path)) {
         const hasLessons = Object.values(state.tasks).some((task) => Boolean(task.lessons?.length)) || Object.values(state.archive ?? {}).some((task) => task.lessonCount > 0);
         if (!hasLessons)
@@ -58,10 +60,15 @@ export const searchLessons = (root, state, query, areas = [], limit = 5) => {
         throw new Error("Lesson index is stale; run state.mjs lesson rebuild");
     const queryTokens = tokens(query);
     const areaSet = new Set(areas.map((area) => area.toLocaleLowerCase()));
-    return index.lessons.map((item) => {
+    return index.lessons
+        .map((item) => {
         const haystack = new Set(tokens(`${item.summary} ${item.prevention} ${item.taskId} ${item.areas.join(" ")}`));
         const areaScore = item.areas.some((area) => areaSet.has(area.toLocaleLowerCase())) ? 100 : 0;
         const tokenScore = queryTokens.filter((token) => haystack.has(token)).length;
         return { item, score: areaScore + tokenScore };
-    }).filter(({ score }) => score > 0 || (!queryTokens.length && !areaSet.size)).sort((a, b) => b.score - a.score || b.item.recordedAt.localeCompare(a.item.recordedAt)).slice(0, Math.max(1, Math.min(limit, 20))).map(({ item }) => item);
+    })
+        .filter(({ score }) => score > 0 || (!queryTokens.length && !areaSet.size))
+        .sort((a, b) => b.score - a.score || b.item.recordedAt.localeCompare(a.item.recordedAt))
+        .slice(0, Math.max(1, Math.min(limit, 20)))
+        .map(({ item }) => item);
 };

package/dist/src/state/lifecycle.js

@@ -1,7 +1,7 @@
-import { handoffKinds } from "./shared.js";
+import { handoffKinds, terminal } from "./domain.js";
+import { audited } from "./guards.js";
 import { hasApproval } from "./transitions.js";
 import { validateState } from "./validate.js";
-import { audited, terminal } from "./shared.js";
 export const handoffTask = (state, id, kind, reason, source, recordedAt = new Date().toISOString()) => {
     const task = state.tasks[id];
     if (!task || terminal(task) || !handoffKinds.includes(kind))

package/dist/src/state/lock.js

@@ -1,7 +1,8 @@
 import { randomUUID } from "node:crypto";
 import { closeSync, existsSync, mkdirSync, openSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
-import { dirname, join, resolve } from "node:path";
-import { assertNoSymlinkPath } from "./shared.js";
+import { dirname } from "node:path";
+import { assertNoSymlinkPath } from "./io.js";
+import { stateLockGuardPath, stateLockGuardPathRelative, stateLockPath, stateLockPathRelative } from "./paths.js";
 const sleep = (milliseconds) => {
     if (milliseconds > 0)
         Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, milliseconds);
@@ -72,10 +73,10 @@ export const acquireStateLock = (root, options = {}) => {
     const timeoutMs = options.timeoutMs ?? 5_000;
     const retryMs = options.retryMs ?? 25;
     const staleMs = options.staleMs ?? 30_000;
-    const lockPath = join(resolve(root), ".agents/data/state/.aidlc-state.lock");
-    const guardPath = join(resolve(root), ".agents/data/state/.aidlc-state.lock.guard");
-    assertNoSymlinkPath(root, ".agents/data/state/.aidlc-state.lock");
-    assertNoSymlinkPath(root, ".agents/data/state/.aidlc-state.lock.guard");
+    const lockPath = stateLockPath(root);
+    const guardPath = stateLockGuardPath(root);
+    assertNoSymlinkPath(root, stateLockPathRelative);
+    assertNoSymlinkPath(root, stateLockGuardPathRelative);
     const token = randomUUID();
     const deadline = Date.now() + timeoutMs;
     const acquireGuard = () => {