cairn-ai 0.2.8 → 0.3.0

package/scripts/cairn-goal-operations-evidence.mjs

@@ -2,10 +2,11 @@ import { randomUUID } from "node:crypto";
 import { normalizeVerificationArgv, normalizeWatchPaths, runVerificationEvidence, workspaceFingerprint } from "./cairn-goal-evidence.mjs";
 import { readGoalState } from "./cairn-goal-state.mjs";
 import {
-  normalizeToolEvidence, requiredText, timestamp, validReceiptCommand, validReceiptScope,
+  normalizeToolEvidence, pathContains, requiredText, timestamp, validReceiptCommand, validReceiptScope,
   validReceiptSource, validTimestamp,
 } from "./cairn-goal-state-validation.mjs";
-import { assertGoalMutable, mutateGoal, taskById } from "./cairn-goal-operations-mutations.mjs";
+import { assertGoalMutable, isReceiptFresh, mutateGoal, taskById } from "./cairn-goal-operations-mutations.mjs";
+import { setTaskStatus, transitionGoal } from "./cairn-goal-operations.mjs";
 
 export async function recordReceipt(options = {}) {
   if (options.source !== undefined && options.source !== "declared") throw new Error("Only goal verify can create tool evidence");
@@ -69,7 +70,7 @@ export async function verifyAndRecord({
   const normalizedArgv = normalizeVerificationArgv(argv);
   const normalizedWatchPaths = normalizeWatchPaths(root, watchPaths);
   const normalizedScope = validReceiptScope(scope);
-  const normalizedKind = requiredText(kind, "evidence kind");
+  const normalizedKinds = normalizeKinds(kind);
   const initialState = await readGoalState({ root });
   if (!initialState) throw new Error("No Cairn goal state exists; start a goal first");
   assertGoalMutable(initialState);
@@ -78,6 +79,7 @@ export async function verifyAndRecord({
   if (initialTask && !["active", "completed"].includes(initialTask.status)) {
     throw new Error(`Verification task must be active or completed: ${initialTask.id}`);
   }
+  assertParallelWatch(initialState, initialTask, normalizedWatchPaths);
   const identity = {
     goalId: initialState.goal.id,
     planId: initialState.goal.planId,
@@ -102,23 +104,96 @@ export async function verifyAndRecord({
       throw new Error("Verification task changed during verification; evidence was not recorded");
     }
   }
-  const state = await recordEvidence({
-    root,
-    taskId: normalizedTaskId,
-    kind: normalizedKind,
-    scope: normalizedScope,
-    command: evidence.command,
-    exitCode: 0,
-    source: "tool",
-    argv: evidence.argv,
-    outputDigest: evidence.outputDigest,
-    summary: evidence.summary,
-    workspaceFingerprint: evidence.workspaceFingerprint,
-    watchPaths: evidence.watchPaths,
-    goalId: identity.goalId,
-    planId: identity.planId,
-    expectedIdentity: identity,
-    expectedFingerprint: evidence.workspaceFingerprint,
-  });
-  return { state, evidence: state.receipts.at(-1) };
+  // One verification run may prove several evidence kinds; record one receipt per kind without rerunning it.
+  const receipts = [];
+  let state;
+  for (const normalizedKind of normalizedKinds) {
+    state = await recordEvidence({
+      root,
+      taskId: normalizedTaskId,
+      kind: normalizedKind,
+      scope: normalizedScope,
+      command: evidence.command,
+      exitCode: 0,
+      source: "tool",
+      argv: evidence.argv,
+      outputDigest: evidence.outputDigest,
+      summary: evidence.summary,
+      workspaceFingerprint: evidence.workspaceFingerprint,
+      watchPaths: evidence.watchPaths,
+      goalId: identity.goalId,
+      planId: identity.planId,
+      expectedIdentity: identity,
+      expectedFingerprint: evidence.workspaceFingerprint,
+    });
+    receipts.push(state.receipts.at(-1));
+  }
+  return { state, evidence: receipts.at(-1), receipts };
+}
+
+// Completes the active task, proves every goal-level evidence kind with one run, and completes the goal.
+export async function finishGoal({
+  root = process.cwd(), argv = [], watchPaths = [], runner, timeoutMs = 600_000,
+} = {}) {
+  const initialState = await readGoalState({ root });
+  if (!initialState) throw new Error("No Cairn goal state exists; start a goal first");
+  assertGoalMutable(initialState);
+  const active = initialState.tasks.find((task) => task.status === "active");
+  const unfinished = initialState.tasks.filter((task) => task.status !== "completed" && task !== active);
+  if (unfinished.length > 0) {
+    throw new Error(`Goal cannot be finished while other tasks remain: ${unfinished.map((task) => task.id).join(", ")}`);
+  }
+  const goalKinds = initialState.goal.requiredEvidence;
+  if (goalKinds.length > 0) normalizeVerificationArgv(argv);
+  if (active) await setTaskStatus({ root, taskId: active.id, status: "completed" });
+  if (goalKinds.length > 0) {
+    await verifyAndRecord({ root, scope: "goal", kind: goalKinds, argv, watchPaths, runner, timeoutMs });
+  }
+  return transitionGoal({ root, status: "completed" });
+}
+
+// Overhead measurement: how many verifications ran, how many were reruns, and which latest receipts are stale.
+export function goalStats(state, root = process.cwd()) {
+  if (!state) return null;
+  const byKind = {};
+  const latest = new Map();
+  let reruns = 0;
+  for (const receipt of state.receipts) {
+    byKind[receipt.kind] = (byKind[receipt.kind] ?? 0) + 1;
+    const key = `${receipt.scope}\0${receipt.taskId ?? ""}\0${receipt.kind}`;
+    if (latest.has(key)) reruns += 1;
+    latest.set(key, receipt);
+  }
+  const stale = [...latest.values()]
+    .filter((receipt) => receipt.source === "tool" && !isReceiptFresh(root, receipt))
+    .map((receipt) => ({ scope: receipt.scope, ...(receipt.taskId ? { taskId: receipt.taskId } : {}), kind: receipt.kind }));
+  return {
+    goalId: state.goal.id,
+    status: state.goal.status,
+    receipts: state.receipts.length,
+    toolReceipts: state.receipts.filter((receipt) => receipt.source === "tool").length,
+    byKind,
+    reruns,
+    stale,
+  };
+}
+
+// While other tasks run in parallel, an unscoped fingerprint would include their edits. Require a watch set,
+// and keep it inside the task's declared writeScope so sibling edits cannot stale or fail this evidence.
+function assertParallelWatch(state, task, watchPaths) {
+  const othersActive = state.tasks.filter((item) => item.status === "active" && item.id !== task?.id);
+  if (task ? othersActive.length === 0 : othersActive.length < 2) return;
+  if (watchPaths.length === 0) {
+    throw new Error(`Other tasks are active (${othersActive.map((item) => item.id).join(", ")}); pass --watch with this task's write scope`);
+  }
+  if (task?.writeScope) {
+    const outside = watchPaths.filter((path) => !task.writeScope.some((scope) => pathContains(scope, path)));
+    if (outside.length > 0) throw new Error(`--watch must stay inside task ${task.id} writeScope while other tasks are active: ${outside.join(", ")}`);
+  }
+}
+
+function normalizeKinds(kind) {
+  const kinds = (Array.isArray(kind) ? kind : [kind]).map((item) => requiredText(item, "evidence kind"));
+  if (kinds.length === 0) throw new Error("evidence kind is required");
+  return [...new Set(kinds)];
 }

package/scripts/cairn-goal-operations-mutations.mjs

@@ -20,8 +20,27 @@ export function ensureTaskCanComplete(state, task, root) {
 export function ensureGoalCanComplete(state, root) {
   const incomplete = state.tasks.filter((task) => task.status !== "completed");
   if (incomplete.length > 0) throw new Error(`Goal cannot be completed while tasks remain: ${incomplete.map((task) => task.id).join(", ")}`);
+  const goalReceipts = state.goal.requiredEvidence.map((kind) => ensureCurrentEvidence({ state, root, scope: "goal", kind }));
+  // Task freshness was enforced when each task completed. Fresh goal-level evidence recorded after every task
+  // receipt supersedes it, so later edits do not force reruns of every earlier task's checks.
+  const lastTaskReceipt = state.receipts.findLastIndex((receipt) => receipt.scope === "task");
+  const superseded = goalReceipts.length > 0
+    && goalReceipts.every((receipt) => state.receipts.indexOf(receipt) > lastTaskReceipt);
+  if (superseded) {
+    for (const task of state.tasks) ensureTaskEvidenceExists(state, task);
+    return;
+  }
   for (const task of state.tasks) ensureTaskCanComplete(state, task, root);
-  for (const kind of state.goal.requiredEvidence) ensureCurrentEvidence({ state, root, scope: "goal", kind });
+}
+
+function ensureTaskEvidenceExists(state, task) {
+  for (const kind of task.requiredEvidence) {
+    const recorded = state.receipts.some((receipt) => (
+      receipt.scope === "task" && receipt.taskId === task.id && receipt.kind === kind
+      && (state.goal.evidencePolicy === "declared" || receipt.source === "tool")
+    ));
+    if (!recorded) throw new Error(`Task ${task.id} cannot be completed without tool-bound evidence record: ${kind}`);
+  }
 }
 
 function ensureCurrentEvidence({ state, root, scope, task, kind }) {
@@ -31,25 +50,40 @@ function ensureCurrentEvidence({ state, root, scope, task, kind }) {
   const subject = scope === "goal" ? "Goal" : `Task ${task.id}`;
   if (state.goal.evidencePolicy === "declared") {
     if (candidates.length === 0) throw new Error(`${subject} cannot be completed without successful, bound evidence record: ${kind}`);
-    return;
+    return candidates.at(-1);
   }
   const toolEvidence = candidates.filter((receipt) => receipt.source === "tool");
   if (toolEvidence.length === 0) throw new Error(`${subject} cannot be completed without tool-bound evidence record: ${kind}`);
   for (const receipt of [...toolEvidence].reverse()) {
-    if (workspaceFingerprint(root, receipt.watchPaths) === receipt.workspaceFingerprint) return;
+    if (isReceiptFresh(root, receipt)) return receipt;
   }
   throw new Error(`${subject} has stale evidence record: ${kind}`);
 }
 
-export function activateNextPendingTask(state) {
-  if (state.tasks.some((task) => task.status === "active")) return true;
-  const next = state.tasks.find((task) => task.status === "pending");
+export function isReceiptFresh(root, receipt) {
+  return receipt.source === "tool" && workspaceFingerprint(root, receipt.watchPaths) === receipt.workspaceFingerprint;
+}
+
+export function readyTasks(state) {
+  if (!state) return [];
+  const completed = new Set(state.tasks.filter((task) => task.status === "completed").map((task) => task.id));
+  return state.tasks.filter((task) => task.status === "pending" && task.dependsOn.every((id) => completed.has(id)));
+}
+
+// Keeps the goal moving after a task leaves "active": when nothing is active, activate the first ready task in
+// list order (the sequential behavior); when nothing is active or ready while work remains, block the goal.
+export function advanceGoal(state, preferredBlocker = null, { block = true } = {}) {
+  if (state.tasks.some((task) => task.status === "active")) return;
+  const next = readyTasks(state)[0];
   if (next) {
     next.status = "active";
     next.updatedAt = new Date().toISOString();
-    return true;
+    return;
   }
-  return false;
+  if (!block || state.tasks.every((task) => task.status === "completed")) return;
+  state.goal.status = "blocked";
+  state.goal.blocker = preferredBlocker ?? state.tasks.find((task) => task.status === "blocked")?.blocker
+    ?? "No task is ready: remaining tasks wait on unfinished dependencies";
 }
 
 export function assertGoalMutable(state) {

package/scripts/cairn-goal-operations.mjs

@@ -5,11 +5,12 @@ import { assertNoSymlinkComponents } from "./cairn-safe-fs.mjs";
 import { goalStatePath, readGoalState, readGoalStateUnlocked, withGoalStateLock, writeGoalStateUnlocked } from "./cairn-goal-state.mjs";
 import {
   GOAL_STATE_VERSION, PLAN_ID_MAX_LENGTH, assertRecoveryReferenceBudget, boundedRequiredText,
+  assertCanBeActive, assertTaskGraph,
   defaultGoalEvidence, normalizeCriteria, normalizeTask, optionalText, requiredText,
   terminalGoalStatuses, timestamp, validEvidencePolicy, validGoalStatus, validTaskStatus, validateState,
 } from "./cairn-goal-state-validation.mjs";
 import {
-  activateNextPendingTask, assertGoalMutable, ensureGoalCanComplete, ensureTaskCanComplete,
+  advanceGoal, assertGoalMutable, ensureGoalCanComplete, ensureTaskCanComplete,
   mutateGoal, taskById,
 } from "./cairn-goal-operations-mutations.mjs";
 
@@ -44,7 +45,8 @@ export async function startGoal({ root = process.cwd(), goal, planId, tasks, com
       throw new Error(`An unfinished Cairn goal already exists (${existing.goal.id}, ${existing.goal.status}); add the new work to it with goal replan (resume it first if paused or blocked), or cancel or complete it before starting another goal`);
     }
     const now = timestamp();
-    const normalizedTasks = tasks.map((task, index) => normalizeTask(task, index, index === 0 ? "active" : "pending"));
+    const normalizedTasks = normalizeTaskList(tasks, []);
+    assertTaskGraph(normalizedTasks);
     for (const task of normalizedTasks) assertRecoveryReferenceBudget(normalizedPlanId, task.id);
     const state = {
       schemaVersion: GOAL_STATE_VERSION,
@@ -66,6 +68,7 @@ export async function startGoal({ root = process.cwd(), goal, planId, tasks, com
       tasks: normalizedTasks,
       receipts: [],
     };
+    advanceGoal(state);
     await writeGoalStateUnlocked({ root, state });
     return state;
   });
@@ -112,6 +115,7 @@ function applyGoalTransition(state, nextStatus, blocker, root) {
   if (nextStatus === "active") state.goal.blocker = null;
   state.goal.status = nextStatus;
   state.goal.updatedAt = timestamp();
+  if (nextStatus === "active" && currentStatus === "blocked") advanceGoal(state, null, { block: false });
   return state;
 }
 
@@ -124,19 +128,14 @@ export async function setTaskStatus({ root = process.cwd(), taskId, status, bloc
     if (task.status === nextStatus) return state;
     if (!taskTransitions[task.status].has(nextStatus)) throw new Error(`Cannot transition task ${task.id} from ${task.status} to ${nextStatus}`);
     if (nextStatus === "active") {
-      const anotherActive = state.tasks.find((item) => item.id !== task.id && item.status === "active");
-      if (anotherActive) throw new Error(`Task ${anotherActive.id} is already active`);
+      assertCanBeActive(state.tasks, task, state.tasks.filter((item) => item.id !== task.id && item.status === "active"));
     }
     if (nextStatus === "completed") ensureTaskCanComplete(state, task, root);
     if (nextStatus === "blocked") task.blocker = requiredText(blocker, "blocker");
     if (nextStatus === "active" || nextStatus === "pending") task.blocker = null;
     task.status = nextStatus;
     task.updatedAt = timestamp();
-    if (nextStatus === "completed") activateNextPendingTask(state);
-    if (nextStatus === "blocked" && !activateNextPendingTask(state)) {
-      state.goal.status = "blocked";
-      state.goal.blocker = task.blocker;
-    }
+    if (nextStatus === "completed" || nextStatus === "blocked") advanceGoal(state, nextStatus === "blocked" ? task.blocker : null);
     state.goal.updatedAt = timestamp();
     return state;
   });
@@ -149,20 +148,34 @@ export async function replanGoal({ root = process.cwd(), tasks } = {}) {
     if (state.goal.status !== "active") throw new Error("Only an active goal can be replanned");
     const completedTasks = state.tasks.filter((task) => task.status === "completed");
     const completedIds = new Set(completedTasks.map((task) => task.id));
-    const replacementTasks = tasks.map((task, index) => {
-      const source = typeof task === "string" ? task : { ...task, status: undefined, blocker: undefined };
-      const normalized = normalizeTask(source, index, index === 0 ? "active" : "pending");
-      if (completedIds.has(normalized.id)) throw new Error(`Replanned task conflicts with completed task id: ${normalized.id}`);
-      return normalized;
-    });
+    const replacementTasks = normalizeTaskList(
+      tasks.map((task) => (typeof task === "string" ? task : { ...task, status: undefined, blocker: undefined })),
+      completedTasks,
+    );
+    for (const task of replacementTasks) {
+      if (completedIds.has(task.id)) throw new Error(`Replanned task conflicts with completed task id: ${task.id}`);
+    }
     state.tasks = [...completedTasks, ...replacementTasks];
+    assertTaskGraph(state.tasks);
     state.receipts = state.receipts.filter((receipt) => receipt.scope === "task" && completedIds.has(receipt.taskId));
     state.goal.blocker = null;
     state.goal.updatedAt = timestamp();
+    advanceGoal(state);
     return state;
   });
 }
 
+// Normalizes tasks as pending; an omitted dependsOn follows the previous task across completed + new tasks.
+function normalizeTaskList(tasks, precedingTasks) {
+  let previousId = precedingTasks.at(-1)?.id ?? null;
+  const normalized = tasks.map((task, index) => {
+    const result = normalizeTask(task, index, "pending", previousId);
+    previousId = result.id;
+    return result;
+  });
+  return normalized;
+}
+
 export async function claimGoal({ root = process.cwd(), sessionId } = {}) {
   const normalizedSessionId = requiredText(sessionId, "sessionId");
   return mutateGoal(root, (state) => {

package/scripts/cairn-goal-policy.mjs

@@ -1,6 +1,9 @@
+import { readyTasks } from "./cairn-goal-operations-mutations.mjs";
+
 export function currentTask(state) {
   if (!state) return null;
   return state.tasks.find((task) => task.status === "active")
+    ?? readyTasks(state)[0]
     ?? state.tasks.find((task) => task.status === "pending")
     ?? state.tasks.find((task) => task.status === "blocked")
     ?? null;
@@ -23,10 +26,22 @@ export function evaluateStop(state, { subagent = false, agentId } = {}) {
     };
   }
   if (subagent) {
-    if (!agentId || task.assignedAgentId !== agentId) return { block: false };
+    // Parallel workers each own a task; gate on the stopping agent's own unfinished task, not the first active one.
+    const assigned = !agentId ? null
+      : state.tasks.find((item) => item.status === "active" && item.assignedAgentId === agentId)
+        ?? (task.assignedAgentId === agentId ? task : null);
+    if (!assigned) return { block: false };
     return {
       block: true,
-      reason: `Cairn task ${task.id} (${task.title}) is assigned to this subagent and is ${task.status}. Continue only this assigned task, record a successful evidence record, then hand off.`,
+      reason: `Cairn task ${assigned.id} (${assigned.title}) is assigned to this subagent and is ${assigned.status}. Continue only this assigned task, record a successful evidence record, then hand off.`,
+    };
+  }
+  const active = state.tasks.filter((item) => item.status === "active");
+  if (active.length > 1) {
+    const list = active.map((item) => `${item.id} (${clip(item.title, 40)})`).join(", ");
+    return {
+      block: true,
+      reason: `Cairn goal "${state.goal.title}" is active with parallel tasks ${list}. Collect or continue each one; record successful evidence before marking a task complete.`,
     };
   }
   return {
@@ -34,3 +49,8 @@ export function evaluateStop(state, { subagent = false, agentId } = {}) {
     reason: `Cairn goal "${state.goal.title}" is active. Continue current task ${task.id} (${task.title}); its status is ${task.status}. Record a successful evidence record before marking it complete.`,
   };
 }
+
+function clip(value, maxLength) {
+  const text = String(value ?? "");
+  return text.length <= maxLength ? text : `${text.slice(0, maxLength - 1)}…`;
+}

package/scripts/cairn-goal-state-validation.mjs

@@ -1,6 +1,7 @@
 import { normalizeVerificationArgv } from "./cairn-goal-evidence.mjs";
 
-export const GOAL_STATE_VERSION = 2;
+export const GOAL_STATE_VERSION = 3;
+export const MAX_ACTIVE_TASKS = 4;
 export const GOAL_STATUSES = new Set(["active", "paused", "blocked", "cancelled", "completed"]);
 export const TASK_STATUSES = new Set(["pending", "active", "blocked", "completed"]);
 export const PLAN_ID_MAX_LENGTH = 128;
@@ -43,7 +44,6 @@ export function validateState(value) {
   if (!Array.isArray(value.tasks) || value.tasks.length === 0) throw new Error("Cairn goal state must contain tasks");
   if (!Array.isArray(value.receipts)) throw new Error("Cairn goal state evidence records (receipts) must be an array");
   const ids = new Set();
-  let activeTasks = 0;
   for (const task of value.tasks) {
     if (!task || typeof task !== "object") throw new Error("Each task must be an object");
     const taskId = boundedRequiredText(task.id, "task.id", TASK_ID_MAX_LENGTH);
@@ -52,7 +52,8 @@ export function validateState(value) {
     ids.add(task.id);
     requiredText(task.title, "task.title");
     validTaskStatus(task.status);
-    if (task.status === "active") activeTasks += 1;
+    if (!Array.isArray(task.dependsOn)) throw new Error(`task ${task.id} dependsOn must be an array`);
+    if (task.writeScope !== null && !Array.isArray(task.writeScope)) throw new Error(`task ${task.id} writeScope must be an array or null`);
     if (task.assignedAgentId !== null && task.assignedAgentId !== undefined) requiredText(task.assignedAgentId, "task.assignedAgentId");
     if (!Array.isArray(task.requiredEvidence) || task.requiredEvidence.length === 0) throw new Error(`task ${task.id} requiredEvidence must be a non-empty array`);
     task.requiredEvidence.forEach((kind, index) => requiredText(kind, `task ${task.id} requiredEvidence[${index}]`));
@@ -60,7 +61,9 @@ export function validateState(value) {
     validTimestamp(task.createdAt);
     validTimestamp(task.updatedAt);
   }
-  if (activeTasks > 1) throw new Error("Only one task may be active");
+  assertTaskGraph(value.tasks);
+  const active = value.tasks.filter((task) => task.status === "active");
+  for (const task of active) assertCanRunAlongside(task, active.filter((other) => other !== task));
   for (const receipt of value.receipts) validateReceipt(receipt, value);
   return value;
 }
@@ -86,7 +89,9 @@ function validateReceipt(receipt, state) {
   }
 }
 
-export function normalizeTask(task, index, defaultStatus) {
+// dependsOn omitted means "after the previous task in list order" so existing sequential plans keep their order;
+// an explicit [] means no dependency.
+export function normalizeTask(task, index, defaultStatus, previousTaskId = null) {
   const source = typeof task === "string" ? { title: task } : task;
   if (!source || typeof source !== "object") throw new Error(`tasks[${index}] must be a string or object`);
   const id = source.id === undefined ? `task-${index + 1}` : boundedRequiredText(source.id, `tasks[${index}].id`, TASK_ID_MAX_LENGTH);
@@ -97,6 +102,12 @@ export function normalizeTask(task, index, defaultStatus) {
     status: source.status === undefined ? defaultStatus : validTaskStatus(source.status),
     assignedAgentId: source.assignedAgentId === undefined || source.assignedAgentId === null ? null : requiredText(source.assignedAgentId, `tasks[${index}].assignedAgentId`),
     requiredEvidence: normalizeCriteria(source.requiredEvidence ?? defaultTaskEvidence),
+    dependsOn: source.dependsOn === undefined
+      ? (previousTaskId === null ? [] : [previousTaskId])
+      : normalizeDependsOn(source.dependsOn, `tasks[${index}].dependsOn`),
+    writeScope: source.writeScope === undefined || source.writeScope === null
+      ? null
+      : normalizeWriteScope(source.writeScope, `tasks[${index}].writeScope`),
     blocker: null,
     createdAt: timestamp(),
     updatedAt: timestamp(),
@@ -104,13 +115,103 @@ export function normalizeTask(task, index, defaultStatus) {
 }
 
 export function migrateState(value) {
-  if (!value || typeof value !== "object" || Array.isArray(value) || value.schemaVersion !== 1) return value;
-  return {
-    ...value,
-    schemaVersion: GOAL_STATE_VERSION,
-    goal: { ...value.goal, evidencePolicy: value.goal?.evidencePolicy ?? "tool-bound" },
-    receipts: Array.isArray(value.receipts) ? value.receipts.map((receipt) => ({ ...receipt, source: "declared" })) : value.receipts,
+  if (!value || typeof value !== "object" || Array.isArray(value)) return value;
+  let state = value;
+  if (state.schemaVersion === 1) {
+    state = {
+      ...state,
+      schemaVersion: 2,
+      goal: { ...state.goal, evidencePolicy: state.goal?.evidencePolicy ?? "tool-bound" },
+      receipts: Array.isArray(state.receipts) ? state.receipts.map((receipt) => ({ ...receipt, source: "declared" })) : state.receipts,
+    };
+  }
+  if (state.schemaVersion === 2) {
+    // v2 tasks ran strictly in list order; make that order explicit as previous-task dependencies.
+    state = {
+      ...state,
+      schemaVersion: 3,
+      tasks: Array.isArray(state.tasks)
+        ? state.tasks.map((task, index) => ({
+          ...task,
+          dependsOn: index === 0 ? [] : [state.tasks[index - 1]?.id],
+          writeScope: null,
+        }))
+        : state.tasks,
+    };
+  }
+  return state;
+}
+
+export function normalizeDependsOn(value, label) {
+  if (!Array.isArray(value)) throw new Error(`${label} must be an array of task ids`);
+  return [...new Set(value.map((item, index) => boundedRequiredText(item, `${label}[${index}]`, TASK_ID_MAX_LENGTH)))];
+}
+
+export function normalizeWriteScope(value, label) {
+  if (!Array.isArray(value) || value.length === 0) throw new Error(`${label} writeScope must be a non-empty array of repository paths`);
+  return [...new Set(value.map((item, index) => {
+    const path = requiredText(item, `${label}[${index}]`).replace(/\\/g, "/").replace(/\/{2,}/g, "/")
+      .replace(/^(\.\/)+/, "").replace(/\/+$/, "");
+    if (/[*?[\]{}]/.test(path)) throw new Error(`${label} writeScope must list literal paths, not globs: ${item}`);
+    if (path === "" || path === "." || path.startsWith("/") || /^[a-zA-Z]:/.test(path) || path.split("/").includes("..")) {
+      throw new Error(`${label} writeScope must stay inside the repository: ${item}`);
+    }
+    return path;
+  }))];
+}
+
+// Segment-wise prefix match, case-insensitive so case-insensitive filesystems cannot hide an overlap.
+export function writeScopesOverlap(left, right) {
+  return left.some((a) => right.some((b) => pathContains(a, b) || pathContains(b, a)));
+}
+
+export function pathContains(scope, path) {
+  const outer = scope.toLowerCase();
+  const inner = path.toLowerCase();
+  return inner === outer || inner.startsWith(`${outer}/`);
+}
+
+export function assertTaskGraph(tasks) {
+  const byId = new Map();
+  for (const task of tasks) {
+    if (byId.has(task.id)) throw new Error(`Duplicate task id: ${task.id}`);
+    byId.set(task.id, task);
+  }
+  for (const task of tasks) {
+    for (const dependency of task.dependsOn) {
+      if (dependency === task.id) throw new Error(`Task ${task.id} cannot depend on itself`);
+      if (!byId.has(dependency)) throw new Error(`Task ${task.id} depends on unknown task: ${dependency}`);
+    }
+  }
+  const visiting = new Set();
+  const done = new Set();
+  const visit = (task, path) => {
+    if (done.has(task.id)) return;
+    if (visiting.has(task.id)) throw new Error(`Task dependency cycle: ${[...path, task.id].join(" -> ")}`);
+    visiting.add(task.id);
+    for (const dependency of task.dependsOn) visit(byId.get(dependency), [...path, task.id]);
+    visiting.delete(task.id);
+    done.add(task.id);
   };
+  for (const task of tasks) visit(task, []);
+}
+
+// Throws unless task may be active next to otherActive: dependencies completed, under the cap, and disjoint
+// writeScopes. A task without writeScope may only run alone.
+export function assertCanBeActive(tasks, task, otherActive) {
+  const waiting = task.dependsOn.filter((id) => tasks.find((item) => item.id === id)?.status !== "completed");
+  if (waiting.length > 0) throw new Error(`Task ${task.id} is waiting for: ${waiting.join(", ")}`);
+  assertCanRunAlongside(task, otherActive);
+}
+
+function assertCanRunAlongside(task, otherActive) {
+  if (otherActive.length === 0) return;
+  if (otherActive.length + 1 > MAX_ACTIVE_TASKS) throw new Error(`Only at most ${MAX_ACTIVE_TASKS} active tasks are allowed`);
+  if (task.writeScope === null) throw new Error(`Task ${task.id} without writeScope cannot run alongside active task ${otherActive[0].id}`);
+  for (const other of otherActive) {
+    if (other.writeScope === null) throw new Error(`Task ${task.id} cannot run alongside active task ${other.id} without writeScope`);
+    if (writeScopesOverlap(task.writeScope, other.writeScope)) throw new Error(`Task ${task.id} writeScope overlaps active task ${other.id}`);
+  }
 }
 
 export function requiredText(value, label) {
@@ -145,7 +246,7 @@ export function validTaskStatus(value) {
 }
 
 export function validReceiptScope(value) {
-  if (value !== "task" && value !== "goal") throw new Error(`Invalid evidence scope: ${value}`);
+  if (value !== "task" && value !== "goal") throw new Error(`Invalid evidence scope: ${value} (allowed: task, goal)`);
   return value;
 }
 

package/scripts/cairn-goal-state.mjs

@@ -18,12 +18,24 @@ export async function readGoalState({ root = process.cwd() } = {}) {
 }
 
 export function stopGuardPath(root = process.cwd()) {
-  return join(goalStateDirectory(root), "stop-guard.json");
+  return hookGuardPath(root, "stop");
+}
+
+export function hookGuardPath(root = process.cwd(), name) {
+  return join(goalStateDirectory(root), `${name}-guard.json`);
 }
 
 export async function readStopGuard(root = process.cwd()) {
+  return readHookGuard(root, "stop");
+}
+
+export async function writeStopGuard(root = process.cwd(), value) {
+  return writeHookGuard(root, "stop", value);
+}
+
+export async function readHookGuard(root = process.cwd(), name) {
   try {
-    const path = stopGuardPath(root);
+    const path = hookGuardPath(root, name);
     await assertNoSymlinkComponents(cairnHome(), path);
     const value = JSON.parse(await readFile(path, "utf8"));
     return value && typeof value === "object" ? value : null;
@@ -32,11 +44,11 @@ export async function readStopGuard(root = process.cwd()) {
   }
 }
 
-export async function writeStopGuard(root = process.cwd(), value) {
+export async function writeHookGuard(root = process.cwd(), name, value) {
   try {
-    await safeWriteFile(cairnHome(), stopGuardPath(root), `${JSON.stringify(value)}\n`, "utf8");
+    await safeWriteFile(cairnHome(), hookGuardPath(root, name), `${JSON.stringify(value)}\n`, "utf8");
   } catch {
-    // The guard only prevents no-progress continuation loops; failing to persist it must not break the stop hook.
+    // Guards only deduplicate hook output; failing to persist one must not break the hook.
   }
 }
 

package/scripts/cairn-goal.mjs

@@ -3,8 +3,9 @@ import { realpathSync } from "node:fs";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { runGoalCli } from "./cairn-goal-cli.mjs";
 import { assignTask, claimGoal, replanGoal, setTaskStatus, startGoal, transitionGoal } from "./cairn-goal-operations.mjs";
-import { recordReceipt, verifyAndRecord } from "./cairn-goal-operations-evidence.mjs";
+import { finishGoal, goalStats, recordReceipt, verifyAndRecord } from "./cairn-goal-operations-evidence.mjs";
 import { readGoalState } from "./cairn-goal-state.mjs";
+import { readyTasks } from "./cairn-goal-operations-mutations.mjs";
 import { defaultGoalEvidence } from "./cairn-goal-state-validation.mjs";
 
 export { workspaceFingerprint } from "./cairn-goal-evidence.mjs";
@@ -20,8 +21,9 @@ export {
 } from "./cairn-goal-state-validation.mjs";
 export { goalStatePath, readGoalState, writeGoalState } from "./cairn-goal-state.mjs";
 export { assignTask, claimGoal, reconcileWorktreeState, replanGoal, setTaskStatus, startGoal, transitionGoal } from "./cairn-goal-operations.mjs";
-export { recordReceipt, verifyAndRecord } from "./cairn-goal-operations-evidence.mjs";
+export { finishGoal, goalStats, recordReceipt, verifyAndRecord } from "./cairn-goal-operations-evidence.mjs";
 export { currentTask, evaluateStop, isGoalOwnedBySession } from "./cairn-goal-policy.mjs";
+export { readyTasks } from "./cairn-goal-operations-mutations.mjs";
 
 export async function handleGoalCli(args = process.argv.slice(2), { stdout = console.log } = {}) {
   return runGoalCli(args, {
@@ -30,7 +32,10 @@ export async function handleGoalCli(args = process.argv.slice(2), { stdout = con
     operations: {
       assignTask,
       claimGoal,
+      finishGoal,
+      goalStats,
       readGoalState,
+      readyTasks,
       recordReceipt,
       replanGoal,
       setTaskStatus,