@comento/pota-harness 0.0.0-stage → 1.0.0

package/scripts/pota-goal-history.mjs

@@ -0,0 +1,316 @@
+import { randomUUID } from "node:crypto";
+import { lstatSync, readFileSync } from "node:fs";
+import { lstat, readFile, readdir, rename, rm } from "node:fs/promises";
+import { isAbsolute, join, relative, resolve, sep } from "node:path";
+import { potaHome, goalStateDirectory, repositoryId } from "./pota-paths.mjs";
+import { assertNoSymlinkComponents, safeWriteFile } from "./pota-safe-fs.mjs";
+
+export const GOAL_HISTORY_SCHEMA_VERSION = 1;
+export const GOAL_HISTORY_MAX_RECORDS = 200;
+export const GOAL_HISTORY_LIMIT_MAX = 200;
+const TITLE_MAX_LENGTH = 120;
+const PLAN_FILE_MAX_BYTES = 512 * 1024;
+const RECENT_MAX = 5;
+const TREND_MIN_COMPLETED = 4;
+const historyStatuses = new Set(["completed", "cancelled"]);
+const memoryPromotionValues = ["note", "none", "missing", "unknown"];
+const memoryPromotionLine = /^\s*(?:[-*]\s*)?Memory promotion\s*:\s*(.*)$/gim;
+
+export function goalHistoryPath(root = process.cwd()) {
+  return join(goalStateDirectory(root), "history.jsonl");
+}
+
+export function memoryPromotionReminder(planId) {
+  return `Pota memory: plan ${planId} has no "Memory promotion:" line. If this goal produced reusable repository knowledge, write it to docs/memory/<domain>.md and run pota memory index; otherwise record "Memory promotion: none: <reason>" in the plan.`;
+}
+
+// Classifies the plan's memory promotion decision. Anything that is not a regular repository file of at most
+// 512 KiB (an id such as plan-status, a symlink, a directory, a path outside root) is "unknown"; never throws.
+export function memoryPromotionStatus(root, planId) {
+  try {
+    const workspaceRoot = resolve(root);
+    const target = resolve(workspaceRoot, String(planId));
+    const relation = relative(workspaceRoot, target);
+    if (relation === "" || relation === ".." || relation.startsWith(`..${sep}`) || isAbsolute(relation)) return "unknown";
+    let current = workspaceRoot;
+    for (const component of relation.split(sep)) {
+      current = join(current, component);
+      if (lstatSync(current).isSymbolicLink()) return "unknown";
+    }
+    const stat = lstatSync(target);
+    if (!stat.isFile() || stat.size > PLAN_FILE_MAX_BYTES) return "unknown";
+    const text = readFileSync(target, "utf8");
+    for (const match of text.matchAll(memoryPromotionLine)) {
+      const value = match[1].trim();
+      if (value.length === 0 || /^<.*>$/.test(value)) continue;
+      return /^(?:none|없음)/i.test(value) ? "none" : "note";
+    }
+    return "missing";
+  } catch {
+    return "unknown";
+  }
+}
+
+// Builds the schemaVersion 1 summary of a terminal goal. It carries ids and counts only, never absolute paths.
+export function buildGoalHistoryRecord(state, { root = process.cwd(), recordedBy, endedAt = state.goal.updatedAt } = {}) {
+  const { goal, tasks, receipts } = state;
+  const createdMs = Date.parse(goal.createdAt);
+  const endedMs = Date.parse(endedAt);
+  const durationMs = Number.isFinite(createdMs) && Number.isFinite(endedMs) ? Math.max(0, endedMs - createdMs) : 0;
+  const byKind = {};
+  const latest = new Set();
+  let reruns = 0;
+  // Same rerun definition as goalStats: a later receipt for an already-seen scope, task, and kind.
+  for (const receipt of 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.add(key);
+  }
+  const models = {};
+  const efforts = {};
+  for (const task of tasks) {
+    if (task.model) models[task.model] = (models[task.model] ?? 0) + 1;
+    if (task.effort) efforts[task.effort] = (efforts[task.effort] ?? 0) + 1;
+  }
+  return {
+    schemaVersion: GOAL_HISTORY_SCHEMA_VERSION,
+    goalId: goal.id,
+    planId: goal.planId,
+    title: Array.from(goal.title).slice(0, TITLE_MAX_LENGTH).join(""),
+    status: goal.status,
+    worktreeId: goal.worktreeId ?? null,
+    createdAt: goal.createdAt,
+    endedAt,
+    durationMs,
+    revision: state.revision,
+    evidencePolicy: goal.evidencePolicy,
+    tasks: {
+      total: tasks.length,
+      completed: tasks.filter((task) => task.status === "completed").length,
+      heavy: tasks.filter((task) => task.route === "heavy").length,
+      light: tasks.filter((task) => task.route === "light").length,
+      delegated: tasks.filter((task) => task.assignedAgentId).length,
+      design: tasks.filter((task) => task.kind === "design").length,
+    },
+    receipts: {
+      total: receipts.length,
+      tool: receipts.filter((receipt) => receipt.source === "tool").length,
+      reruns,
+      byKind,
+    },
+    waivers: {
+      effort: tasks.filter((task) => task.effortWaiver).length,
+      design: tasks.filter((task) => task.designWaiver).length,
+    },
+    models,
+    efforts,
+    memoryPromotion: memoryPromotionStatus(root, goal.planId),
+    recordedBy,
+  };
+}
+
+// Records a terminal goal while the caller holds the goal state lock. History is best effort: it never throws, and
+// the caller reports a returned error instead of blocking the transition.
+export async function recordGoalHistoryUnlocked(root, state, options) {
+  let record = null;
+  try {
+    record = buildGoalHistoryRecord(state, { ...options, root });
+    await writeGoalHistoryRecordUnlocked(root, record);
+    return { record, error: null };
+  } catch (error) {
+    return { record, error };
+  }
+}
+
+// Keeps valid lines only, replaces a record with the same goalId, appends, and keeps the newest 200 records.
+// The state lock serializes writers per worktree; temporary file + rename keeps readers on a whole file.
+export async function writeGoalHistoryRecordUnlocked(root, record) {
+  const path = goalHistoryPath(root);
+  await assertNoSymlinkComponents(potaHome(), path);
+  const { records } = await readHistoryFile(path);
+  const kept = records.filter((item) => item.goalId !== record.goalId);
+  kept.push(record);
+  const text = kept.slice(-GOAL_HISTORY_MAX_RECORDS).map((item) => JSON.stringify(item)).join("\n");
+  const temporaryPath = `${path}.${process.pid}.${randomUUID()}.tmp`;
+  try {
+    await safeWriteFile(potaHome(), temporaryPath, `${text}\n`, "utf8");
+    await rename(temporaryPath, path);
+  } catch (error) {
+    await rm(temporaryPath, { force: true }).catch(() => {});
+    throw error;
+  }
+}
+
+async function readHistoryFile(path) {
+  let text;
+  try {
+    text = await readFile(path, "utf8");
+  } catch (error) {
+    if (error?.code === "ENOENT") return { records: [], skippedLines: 0 };
+    throw error;
+  }
+  const records = [];
+  let skippedLines = 0;
+  for (const line of text.split("\n")) {
+    if (line.trim().length === 0) continue;
+    let value;
+    try {
+      value = JSON.parse(line);
+    } catch {
+      value = null;
+    }
+    if (isHistoryRecord(value)) records.push(value);
+    else skippedLines += 1;
+  }
+  return { records, skippedLines };
+}
+
+function isHistoryRecord(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value)
+    && value.schemaVersion === GOAL_HISTORY_SCHEMA_VERSION
+    && typeof value.goalId === "string" && value.goalId.length > 0
+    && historyStatuses.has(value.status)
+    && typeof value.endedAt === "string" && Number.isFinite(Date.parse(value.endedAt));
+}
+
+// Reads every worktree history of this repository without taking locks or creating directories.
+async function readRepositoryHistory(root) {
+  const worktreesDirectory = join(potaHome(), "projects", repositoryId(root), "worktrees");
+  let entries;
+  try {
+    await assertNoSymlinkComponents(potaHome(), worktreesDirectory);
+    entries = await readdir(worktreesDirectory, { withFileTypes: true });
+  } catch (error) {
+    if (error?.code === "ENOENT" || error?.code === "ENOTDIR") return { records: [], skippedLines: 0 };
+    throw error;
+  }
+  const byGoal = new Map();
+  let skippedLines = 0;
+  for (const entry of entries.filter((item) => item.isDirectory()).sort((a, b) => a.name.localeCompare(b.name))) {
+    const path = join(worktreesDirectory, entry.name, "history.jsonl");
+    try {
+      if (!(await lstat(path)).isFile()) continue;
+    } catch (error) {
+      if (error?.code === "ENOENT") continue;
+      throw error;
+    }
+    const file = await readHistoryFile(path);
+    skippedLines += file.skippedLines;
+    for (const record of file.records) {
+      const existing = byGoal.get(record.goalId);
+      if (!existing || Date.parse(record.endedAt) > Date.parse(existing.endedAt)) byGoal.set(record.goalId, record);
+    }
+  }
+  return { records: [...byGoal.values()], skippedLines };
+}
+
+export function validHistoryLimit(value) {
+  if (value === undefined || value === null) return null;
+  const text = String(value);
+  const result = Number(text);
+  if (!/^\d+$/.test(text) || !Number.isSafeInteger(result) || result < 1 || result > GOAL_HISTORY_LIMIT_MAX) {
+    throw new Error(`--limit must be an integer between 1 and ${GOAL_HISTORY_LIMIT_MAX}`);
+  }
+  return result;
+}
+
+// Repository-wide summary across goals. Medians, p90, rates, and trend use completed goals only; limit keeps the
+// newest N records by endedAt.
+export async function goalHistoryStats({ root = process.cwd(), limit } = {}) {
+  const normalizedLimit = validHistoryLimit(limit);
+  const history = await readRepositoryHistory(root);
+  const ordered = history.records.sort((a, b) => Date.parse(a.endedAt) - Date.parse(b.endedAt) || a.goalId.localeCompare(b.goalId));
+  const records = normalizedLimit === null ? ordered : ordered.slice(-normalizedLimit);
+  if (records.length === 0) {
+    return {
+      schemaVersion: GOAL_HISTORY_SCHEMA_VERSION,
+      scope: "repository",
+      goals: 0,
+      ...(history.skippedLines > 0 ? { skippedLines: history.skippedLines } : {}),
+    };
+  }
+  const completed = records.filter((record) => record.status === "completed");
+  const memoryPromotion = Object.fromEntries(memoryPromotionValues.map((value) => [value, 0]));
+  for (const record of records) {
+    const value = memoryPromotionValues.includes(record.memoryPromotion) ? record.memoryPromotion : "unknown";
+    memoryPromotion[value] += 1;
+  }
+  const durations = completed.map((record) => count(record.durationMs)).sort((a, b) => a - b);
+  const receiptTotals = completed.map((record) => count(record.receipts?.total));
+  return {
+    schemaVersion: GOAL_HISTORY_SCHEMA_VERSION,
+    scope: "repository",
+    goals: records.length,
+    completed: completed.length,
+    cancelled: records.length - completed.length,
+    skippedLines: history.skippedLines,
+    window: { from: records[0].endedAt, to: records.at(-1).endedAt },
+    durationMs: { median: median(durations), p90: durations.length === 0 ? 0 : durations[Math.ceil(0.9 * durations.length) - 1] },
+    tasks: {
+      total: sum(completed, (record) => record.tasks?.total),
+      median: median(completed.map((record) => count(record.tasks?.total))),
+      heavy: sum(completed, (record) => record.tasks?.heavy),
+      light: sum(completed, (record) => record.tasks?.light),
+      delegated: sum(completed, (record) => record.tasks?.delegated),
+    },
+    receipts: {
+      total: sum(completed, (record) => record.receipts?.total),
+      tool: sum(completed, (record) => record.receipts?.tool),
+      reruns: sum(completed, (record) => record.receipts?.reruns),
+      rerunRate: rerunRate(completed),
+      median: median(receiptTotals),
+    },
+    waivers: {
+      effort: sum(records, (record) => record.waivers?.effort),
+      design: sum(records, (record) => record.waivers?.design),
+    },
+    memoryPromotion,
+    trend: trend(completed),
+    recent: records.slice(-RECENT_MAX).reverse().map((record) => ({
+      goalId: record.goalId,
+      planId: record.planId,
+      status: record.status,
+      endedAt: record.endedAt,
+      durationMs: count(record.durationMs),
+      tasks: count(record.tasks?.total),
+      receipts: count(record.receipts?.total),
+      reruns: count(record.receipts?.reruns),
+      memoryPromotion: record.memoryPromotion,
+    })),
+  };
+}
+
+// Completed goals in endedAt order split in half; an odd count gives newer the extra goal.
+function trend(completed) {
+  if (completed.length < TREND_MIN_COMPLETED) return null;
+  const middle = Math.floor(completed.length / 2);
+  const summarize = (records) => ({
+    goals: records.length,
+    durationMsMedian: median(records.map((record) => count(record.durationMs))),
+    receiptsMedian: median(records.map((record) => count(record.receipts?.total))),
+    rerunRate: rerunRate(records),
+  });
+  return { older: summarize(completed.slice(0, middle)), newer: summarize(completed.slice(middle)) };
+}
+
+function rerunRate(records) {
+  const total = sum(records, (record) => record.receipts?.total);
+  const reruns = sum(records, (record) => record.receipts?.reruns);
+  return Number((reruns / Math.max(1, total)).toFixed(3));
+}
+
+function median(values) {
+  if (values.length === 0) return 0;
+  const sorted = [...values].sort((a, b) => a - b);
+  const middle = Math.floor(sorted.length / 2);
+  return sorted.length % 2 === 1 ? sorted[middle] : Math.round((sorted[middle - 1] + sorted[middle]) / 2);
+}
+
+function sum(records, pick) {
+  return records.reduce((total, record) => total + count(pick(record)), 0);
+}
+
+function count(value) {
+  return Number.isFinite(value) && value > 0 ? value : 0;
+}

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

@@ -0,0 +1,213 @@
+import { randomUUID } from "node:crypto";
+import { normalizeVerificationArgv, normalizeWatchPaths, runVerificationEvidence, workspaceFingerprint } from "./pota-goal-evidence.mjs";
+import { readGoalState } from "./pota-goal-state.mjs";
+import {
+  normalizeToolEvidence, pathContains, requiredText, timestamp, validReceiptCommand, validReceiptScope,
+  validReceiptSource, validTimestamp,
+} from "./pota-goal-state-validation.mjs";
+import { assertGoalMutable, isReceiptFresh, mutateGoal, taskById } from "./pota-goal-operations-mutations.mjs";
+import { setTaskStatus, transitionGoal } from "./pota-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");
+  return recordEvidence({ ...options, source: "declared" });
+}
+
+async function recordEvidence({
+  root = process.cwd(), taskId, kind, scope = "task", command, exitCode,
+  timestamp: receiptTimestamp, goalId, planId, source, argv, outputDigest,
+  summary, workspaceFingerprint: fingerprint, watchPaths = [], expectedIdentity,
+  expectedFingerprint,
+} = {}) {
+  const normalizedScope = validReceiptScope(scope);
+  const normalizedTaskId = normalizedScope === "task" ? requiredText(taskId, "taskId") : undefined;
+  const normalizedKind = requiredText(kind, "evidence kind");
+  const normalizedCommand = validReceiptCommand(command);
+  const normalizedSource = validReceiptSource(source);
+  if (exitCode !== 0) throw new Error("evidence exitCode must be 0");
+  const normalizedTimestamp = validTimestamp(receiptTimestamp ?? timestamp());
+  const toolFields = normalizedSource === "tool" ? normalizeToolEvidence({ argv, outputDigest, summary, fingerprint, watchPaths }) : {};
+  return mutateGoal(root, (state) => {
+    assertGoalMutable(state);
+    const task = normalizedScope === "task" ? taskById(state, normalizedTaskId) : null;
+    if (expectedIdentity && (state.goal.id !== expectedIdentity.goalId || state.goal.planId !== expectedIdentity.planId)) {
+      throw new Error("Goal identity changed during verification; evidence was not recorded");
+    }
+    if (expectedIdentity && normalizedScope === "task" && (
+      task?.id !== expectedIdentity.taskId
+      || task?.status !== expectedIdentity.taskStatus
+      || task?.assignedAgentId !== expectedIdentity.taskAgentId
+    )) throw new Error("Verification task changed during verification; evidence was not recorded");
+    if (expectedFingerprint && workspaceFingerprint(root, watchPaths) !== expectedFingerprint) {
+      throw new Error("Watched workspace changed during verification; evidence was not recorded");
+    }
+    if (goalId !== undefined && goalId !== state.goal.id) throw new Error("evidence goalId does not match the active goal");
+    if (planId !== undefined && planId !== state.goal.planId) throw new Error("evidence planId does not match the active goal");
+    const receipt = {
+      id: `receipt-${randomUUID()}`,
+      scope: normalizedScope,
+      kind: normalizedKind,
+      ...(task ? { taskId: task.id } : {}),
+      goalId: state.goal.id,
+      planId: state.goal.planId,
+      command: normalizedCommand,
+      exitCode: 0,
+      timestamp: normalizedTimestamp,
+      source: normalizedSource,
+      ...toolFields,
+    };
+    state.receipts.push(receipt);
+    if (task) task.updatedAt = timestamp();
+    state.goal.updatedAt = timestamp();
+    return state;
+  });
+}
+
+export async function verifyAndRecord({
+  root = process.cwd(), taskId, kind, scope = "task", argv, watchPaths = [],
+  runner, timeoutMs = 600_000,
+} = {}) {
+  const normalizedArgv = normalizeVerificationArgv(argv);
+  const normalizedWatchPaths = normalizeWatchPaths(root, watchPaths);
+  const normalizedScope = validReceiptScope(scope);
+  const normalizedKinds = normalizeKinds(kind);
+  const initialState = await readGoalState({ root });
+  if (!initialState) throw new Error("No Pota goal state exists; start a goal first");
+  assertGoalMutable(initialState);
+  const normalizedTaskId = normalizedScope === "task" ? requiredText(taskId, "taskId") : undefined;
+  const initialTask = normalizedScope === "task" ? taskById(initialState, normalizedTaskId) : null;
+  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,
+    taskId: normalizedTaskId,
+    taskStatus: initialTask?.status,
+    taskAgentId: initialTask?.assignedAgentId,
+  };
+  const evidence = runVerificationEvidence({
+    root,
+    argv: normalizedArgv,
+    watchPaths: normalizedWatchPaths,
+    runner,
+    timeoutMs,
+  });
+  const postState = await readGoalState({ root });
+  if (!postState || postState.goal.id !== identity.goalId || postState.goal.planId !== identity.planId) {
+    throw new Error("Goal identity changed during verification; evidence was not recorded");
+  }
+  if (normalizedScope === "task") {
+    const postTask = taskById(postState, normalizedTaskId);
+    if (postTask.status !== identity.taskStatus || postTask.assignedAgentId !== identity.taskAgentId) {
+      throw new Error("Verification task changed during verification; evidence was not recorded");
+    }
+  }
+  // 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, onTerminal,
+} = {}) {
+  const initialState = await readGoalState({ root });
+  if (!initialState) throw new Error("No Pota 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", onTerminal });
+}
+
+// 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,
+    tasks: state.tasks.map((task) => ({
+      id: task.id,
+      status: task.status,
+      route: task.route ?? null,
+      effort: task.effort ?? null,
+      effortSource: task.effortSource ?? null,
+      ...(task.effortWaiver ? { effortWaiver: task.effortWaiver } : {}),
+      ...(task.kind ? { kind: task.kind } : {}),
+      ...(task.model ? { model: task.model } : {}),
+      ...(task.modelSource ? { modelSource: task.modelSource } : {}),
+      ...(task.designWaiver ? { designWaiver: task.designWaiver } : {}),
+      ...(task.modelHost ? { modelHost: task.modelHost } : {}),
+      ...(task.effectiveModel ? { effectiveModel: task.effectiveModel } : {}),
+    })),
+  };
+}
+
+// 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/pota-goal-operations-mutations.mjs

@@ -0,0 +1,97 @@
+import { workspaceFingerprint } from "./pota-goal-evidence.mjs";
+import { readGoalStateUnlocked, withGoalStateLock, writeGoalStateUnlocked } from "./pota-goal-state.mjs";
+import { terminalGoalStatuses } from "./pota-goal-state-validation.mjs";
+
+export async function mutateGoal(root, mutate) {
+  return withGoalStateLock(root, async () => {
+    const state = await readGoalStateUnlocked(root);
+    if (!state) throw new Error("No Pota goal state exists; start a goal first");
+    const next = await mutate(structuredClone(state));
+    next.revision += 1;
+    await writeGoalStateUnlocked({ root, state: next });
+    return next;
+  });
+}
+
+export function ensureTaskCanComplete(state, task, root) {
+  for (const kind of task.requiredEvidence) ensureCurrentEvidence({ state, root, scope: "task", task, kind });
+}
+
+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);
+}
+
+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 }) {
+  const candidates = state.receipts.filter((receipt) => (
+    receipt.scope === scope && receipt.kind === kind && (scope === "goal" || receipt.taskId === task.id)
+  ));
+  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 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 (isReceiptFresh(root, receipt)) return receipt;
+  }
+  throw new Error(`${subject} has stale evidence record: ${kind}`);
+}
+
+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;
+  }
+  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) {
+  if (terminalGoalStatuses.has(state.goal.status)) throw new Error(`Cannot change a ${state.goal.status} goal`);
+}
+
+export function taskById(state, taskId) {
+  const task = state.tasks.find((item) => item.id === taskId);
+  if (!task) throw new Error(`Unknown task: ${taskId}`);
+  return task;
+}