cairn-ai 0.2.6 → 0.2.8

package/commands/cairn-review.md

@@ -2,14 +2,14 @@
 
 Use the `cairn-review` skill.
 
-Prerequisite: resolve Cairn from its installed runtime locator. If `cairn doctor` fails, restore it with the published/global lifecycle command. Never look for Cairn runtime files in the target repository.
+Prerequisite: resolve Cairn from its installed runtime locator. If the shared runtime or locator is missing, unreadable, or inconsistent, stop every dependent mirror; run published/global `cairn doctor`, then `cairn upgrade` to recover it. Never repair through another mirror or look for Cairn runtime files in the target repository.
 
 Goal: review completed work against plan, memory, policy, and evidence.
 
 Procedure:
 
 1. Every agent reads project-root `MEMORY.md` when present and continues without repository memory when absent before review work, then reads the plan task and available memory inputs.
-2. Check changed files, tool readiness evidence, and verification evidence.
+2. Check changed files, tool readiness evidence, and verification evidence. Inspect test, fixture, and verification-command diffs and reject any weakening without a recorded plan reason. For defect fixes, confirm the same-rule sweep was performed and its result recorded.
 3. Delegate independent read-only review to `explorer` when it materially improves speed or quality; use `worker` only for scoped verification reruns or QA artifacts. When subagent tools are available, each agent may recursively delegate bounded sub-tasks to subagents. Tell every delegated agent and child subagent to read the project-root `MEMORY.md` before work, keep scope, and preserve others' edits.
 4. Report findings first, ordered by severity, with file and line references. If no issues are found, say so clearly and mention remaining test gaps or residual risk.
 5. Record review evidence in `docs/plan/<topic>.md` and as the goal-level final review evidence record before completing the goal.

package/commands/cairn-work.md

@@ -2,20 +2,20 @@
 
 Use the `cairn-work` skill.
 
-Prerequisite: resolve the installed Cairn runtime from the plugin or skill locator. If `cairn doctor` fails, restore it with the published/global lifecycle command. Never look for Cairn scripts or model guidance in the target repository.
+Prerequisite: resolve the installed Cairn runtime from the plugin or skill locator. If the shared runtime or locator is missing, unreadable, or inconsistent, stop every dependent mirror; run published/global `cairn doctor`, then `cairn upgrade` to recover it. Never repair through another mirror or look for Cairn scripts or model guidance in the target repository.
 
 Goal: execute the active goal's current task without bypassing complexity triage, then keep advancing tasks until goal-level final review completes or the goal is explicitly paused, blocked, or cancelled.
 
 Require three complexity records: the provisional request checkpoint, post-exploration planning checkpoint, and code checkpoint after exact file/caller/test inspection immediately before the first edit. Before editing, evidence may change either route. Every change must synchronize the plan artifact, repository goal task roadmap through `goal replan`, and native UI plan, including reviews and required evidence. After editing begins, a new Heavy Path signal promotes Light Path to Heavy Path: stop further edits, mark affected evidence stale, synchronize all three roadmaps, and repeat the code checkpoint.
 
-Models always inherit. Route reasoning effort per task: Light planning/implementation/verification=`medium`; Heavy planning/review/implementation=`high`; final verification/review=`xhigh`. Record requested/effective effort for every task. Only a new task/worker may receive requested effort through a supported host-native option; unsupported host/value means effective=`inherited` with no model/global config change. Route changes synchronize the plan artifact, repository goal task roadmap, native UI plan, and reasoning effort profile; preserve completed profiles and recalculate incomplete profiles.
+Models always inherit. Route reasoning effort per task: Light planning/implementation/verification=`medium`; Heavy planning/review/implementation=`high`; final verification/review=`xhigh`. Requested is Cairn's desired profile; Effective records the dispatch result. Effective=`inherited` means no task override was confirmed, not that the host is incapable. Claim host capability only from its exposed interface or dispatch response, and distinguish Cairn non-integration from host non-support. Only a new task/worker may receive requested effort through a supported host-native option; never change model/global config. Route changes synchronize the plan artifact, repository goal task roadmap, native UI plan, and reasoning effort profile; preserve completed profiles and recalculate incomplete profiles.
 
 Procedure:
 
 1. Every agent reads project-root `MEMORY.md` when present and continues without repository memory when absent before selecting or executing a task.
 2. Read `PLAN.md`, the detailed plan, and relevant memory notes.
 3. Resolve and read the `cairn://` Codex or Claude model guidance recorded in the plan through the installed runtime.
-4. Read Cairn goal status and select only its current task. If implementation was requested but no goal exists, create it from the decision-complete plan.
+4. Read the current task with `goal task status` (full `goal status` only when receipts are needed) and select only that task. Fold a new request or steer that arrives during an unfinished goal into it with `goal replan` instead of cancelling it, and keep advancing to goal final review. If implementation was requested but no goal exists, create it from the decision-complete plan.
 5. Confirm required tool readiness. If a required LSP/check tool is missing, report it and obtain explicit user approval before `toolcheck --install --yes` or a repository-native install command.
 6. Confirm the complexity triage and selected Light/Heavy Path recorded in the plan. If missing, update the plan before mutating files.
 7. Before implementation, spend reasoning on a focused executable test contract covering requirements, invariants, boundaries, and failure modes. Confirm the intended failure, then constrain implementation to the minimum change that passes it.
@@ -23,7 +23,7 @@ Procedure:
 9. Give implementation the test contract, failing evidence, exact file ownership, and constraints. Require minimal implementation and no repeated broad discovery. Preserve status, final-report, close-and-review, recursive bounded delegation, and main-agent fallback rules.
 10. Treat tool exit codes and bounded summaries as authoritative. Keep success output concise; expand only the failing test and related code context.
 11. For Heavy Path, run the recorded automated test command and record explicit `Tests:` evidence.
-12. Run focused module acceptance, then one final surface integration check through `goal verify -- ...`. Verification defaults to 600,000 ms (10 minutes), may be shortened with `--timeout-ms`, and is capped at 3,600,000 ms (1 hour). The command runs without holding the state lock; evidence is recorded only if the starting goal/task identity and the pre/post watched fingerprint still match.
+12. Run focused module acceptance, then one final surface integration check through `goal verify -- ...`. Verification defaults to 600,000 ms (10 minutes), may be shortened with `--timeout-ms`, and is capped at 3,600,000 ms (1 hour). The command runs without holding the state lock; evidence is recorded only if the starting goal/task identity and the pre/post watched fingerprint still match. The default Git fingerprint excludes ignored files, so explicitly `--watch` every ignored artifact needed by the claim. Never edit, weaken, skip, or delete existing tests, fixtures, or verification commands to make a gate pass unless the plan records the contract change. Reproduce reported defects before fixing, test one hypothesis at a time with a measurement, and after a fix search for other implementations of the same rule or pattern.
 13. Before package verification, inspect package lifecycle scripts. Run normal `npm pack --dry-run` by default. Content-producing or unknown lifecycle scripts must never use `--ignore-scripts`; only absent or proven content-neutral scripts may use it when the prior full check remains fresh.
 14. Record evidence at the semantic boundary that proves the claimed behavior, bound to goal/task/plan. Missing, failed, skipped, stale, or placeholder evidence never completes work; relevant mutation invalidates affected evidence.
 15. Complete the task and continue the goal. Use `--quiet` on successful state mutations; workers report only their assigned task and never select the next one.

package/docs/model-guidance/README.md

@@ -7,14 +7,14 @@ The goal is not to make prompts long by model. The goal is to stabilize the same
 ## Application Order
 
 1. Identify the active model name. If the model name is not directly exposed, infer it from the user's default model setting and agent role frontmatter.
-2. Resolve this installed guidance root from the active skill's `references/cairn-runtime.json` or the source skill's location. Never look for Cairn model guidance in the target repository.
+2. Resolve this installed guidance root from the active skill's `references/cairn-runtime.json` or the source skill's location. Never look for Cairn model guidance in the target repository. If the shared runtime or locator is missing, unreadable, or inconsistent, stop using every dependent mirror; run published/global `cairn doctor`, then `cairn upgrade` for recovery, rather than repairing through another mirror.
 3. For Claude-family models, apply `cairn://docs/model-guidance/claude.md`.
 4. For Codex-family models, apply `cairn://docs/model-guidance/codex.md`.
 5. If the model is not clearly classified, apply only the common rules and skip model-specific adjustment.
 
 ## Common Rules
 
-- On every fresh entry, compaction recovery, restart, delegation, or handoff, restore context in this order: optional root `MEMORY.md` → current phase skill → active plan → current-task references → model guidance recorded by the plan. If `MEMORY.md` is absent, continue without repository memory and do not invoke another memory service. If persisted state or an assignment requires another reference that is missing, unreadable, or inconsistent, fail closed: do not edit, delegate, approve, or complete; report or record a blocker.
+- On every fresh entry, compaction recovery, restart, delegation, or handoff, restore context in this order: optional root `MEMORY.md` → current phase skill → active plan → current-task references → model guidance recorded by the plan. If `MEMORY.md` is absent, continue without repository memory and do not invoke another memory service. If persisted state or an assignment requires another reference that is missing, unreadable, or inconsistent, fail closed: do not edit, delegate, approve, or complete; report or record a blocker. Delegation means the delegated agent restores on its own entry; the orchestrator does not re-read this chain after dispatching or collecting a subagent, and within one unbroken context it rereads only references that changed, which keeps the cached prompt prefix stable.
 - Keep root `MEMORY.md` and `PLAN.md` as indexes only.
 - Keep repository-specific judgment in `docs/memory/` and `docs/plan/`. Keep Cairn's model guidance in the installed plugin and reference it with `cairn://docs/model-guidance/...`.
 - Treat the user-home `.cairn/projects/<project-id>/worktrees/<worktree-id>/state.json` as a worktree-bound active-work slot. State without `worktreeId` and state copied into another worktree are stale and are removed on the next hook/goal start. Successful completion or cancellation removes the owning copy after plan evidence is recorded; only paused or blocked work remains for resumption.
@@ -32,7 +32,7 @@ The goal is not to make prompts long by model. The goal is to stabilize the same
 - Treat missing, failed, skipped, stale, or placeholder evidence as failure. Task evidence records must be bound to the current goal, task, and plan.
 - Treat the repository Cairn state as the fail-closed transition authority. Advance the matching Codex UI plan step only after the evidence-gated repository task transition succeeds.
 - Spend reasoning on a focused executable test contract before implementation: requirements, invariants, boundaries, and failure modes. Give implementation only that contract, failing evidence, file scope, and constraints; require the minimum passing change.
-- Run verification through `goal verify -- ...`; its default timeout is 600,000 ms and its maximum is 3,600,000 ms. Treat tool exit codes and bounded machine summaries as authoritative. Record evidence only when the starting goal/task identity and pre/post watched fingerprint still match, and choose the watch set and command at the semantic boundary that proves the claim. Compress success output and expand context only for failing tests and related code.
+- Run verification through `goal verify -- ...`; its default timeout is 600,000 ms and its maximum is 3,600,000 ms. Treat tool exit codes and bounded machine summaries as authoritative. Record evidence only when the starting goal/task identity and pre/post watched fingerprint still match, and choose the watch set and command at the semantic boundary that proves the claim. The default Git fingerprint excludes ignored files; explicitly pass every ignored artifact needed by the claim with `--watch`. Compress success output and expand context only for failing tests and related code.
 - Use a verification ladder: focused contract tests, one full check after the final change, then package dry-run while the full check remains fresh. Inspect package lifecycle scripts first and run normal `npm pack --dry-run` by default. Content-producing or unknown lifecycle scripts must never use `--ignore-scripts`; only absent or proven content-neutral scripts may use it.
 - Every implementation task must pass module acceptance verification and surface integration verification.
 - Before mutating external state, run the closest available dry-run, check, plan, diff, validate, or equivalent command.
@@ -53,9 +53,9 @@ The goal is not to make prompts long by model. The goal is to stabilize the same
 - Models always inherit the host or user default; Cairn never selects or overrides a model.
 - Light Path planning, implementation, and verification request `medium`.
 - Heavy Path planning, review, and implementation request `high`; final verification and review request `xhigh`.
-- Every plan task records `Requested reasoning effort` and `Effective reasoning effort`.
+- Every plan task records `Requested reasoning effort` and `Effective reasoning effort`. Requested is Cairn's desired profile; Effective is the value confirmed by the dispatch result.
 - Only a newly dispatched task or worker may receive the requested value, and only through a host-exposed reasoning-effort option or host-native equivalent. Omit every model override.
-- For an unsupported host or value, record `Effective reasoning effort: inherited` with the reason. Do not change the model or global config and do not silently choose a nearby value.
+- For an unsupported host or value, use `Effective reasoning effort: inherited`; this means no task-level override was confirmed and does not prove the host lacks the capability. Describe host capability only from an exposed interface or dispatch result, and distinguish Cairn's choice not to integrate or use an option from host non-support. Do not change the model or global config and do not silently choose a nearby value.
 - A route change synchronizes the plan artifact, repository goal task roadmap through `goal replan`, native UI plan, and reasoning effort profile before edits resume. Preserve completed task profiles as audit history and recalculate incomplete task profiles for the new path.
 
 ## Delegation Defaults

package/docs/model-guidance/claude.md

@@ -18,7 +18,7 @@ Claude-family models are strong at long-context retention, policy interpretation
 - Do not skip the two verification gates even on Light Path.
 - Do not approve a plan that lacks dry-run or check evidence for external-state-changing work.
 - Do not allow open-ended verification loops. Require a blocker or sub-task split after two failed passes.
-- Keep the model inherited. Review each task's `Requested reasoning effort` and `Effective reasoning effort`; apply the requested value only to a newly dispatched task or worker through a host-native task/subagent option, never a model override. For an unsupported host or value, require effective reasoning effort `inherited` and no model/global configuration change.
+- Keep the model inherited. `Requested reasoning effort` is Cairn's desired profile; `Effective reasoning effort` is what the dispatch response confirms. Apply the requested value only to a newly dispatched task or worker through a host-native task/subagent option, never a model override. For an unsupported host or value, record Effective `inherited`; this means no task override was confirmed, not proof of missing host capability. Infer capability only from the exposed interface or dispatch response, distinguish Cairn non-integration from host non-support, and make no model/global configuration change.
 - On Heavy Path, check plan gaps before implementation.
 - Review all three complexity records: the provisional request checkpoint, post-exploration planning checkpoint, and code checkpoint after exact file/caller/test inspection immediately before the first edit. Before editing, evidence may change either route. Every change must synchronize the plan artifact, repository goal task roadmap through `goal replan`, and native UI plan, including reviews and required evidence. After editing begins, a new Heavy signal promotes Light Path to Heavy Path: stop further edits, mark affected evidence stale, synchronize all three roadmaps, and repeat the code checkpoint.
 - Before asking the user, use repository evidence and available `explorer`/`worker` delegation when it materially improves speed or quality.

package/docs/model-guidance/codex.md

@@ -17,9 +17,9 @@ Codex-family models are strong at small implementation tasks, explicit tool use,
 
 ## Adjustment Rules
 
-- On every fresh entry, compaction recovery, restart, delegation, or handoff, restore optional root `MEMORY.md` → current phase skill → active plan → current-task references → recorded model guidance. Missing `MEMORY.md` never blocks and must not trigger another memory service. If persisted state or the assignment requires another missing, unreadable, or inconsistent reference, fail closed and report a blocker before editing, delegating, approving, or completing.
+- On every fresh entry, compaction recovery, restart, delegation, or handoff, restore optional root `MEMORY.md` → current phase skill → active plan → current-task references → recorded model guidance. Missing `MEMORY.md` never blocks and must not trigger another memory service. If persisted state or the assignment requires another missing, unreadable, or inconsistent reference, fail closed and report a blocker before editing, delegating, approving, or completing. Delegation means the delegated agent restores on its own entry; the orchestrator does not re-read this chain after dispatching or collecting a subagent, and within one unbroken context it rereads only references that changed, which keeps the cached prompt prefix stable.
 - Do not start implementation without a plan.
-- Keep the model inherited. Read each plan task's `Requested reasoning effort` and `Effective reasoning effort`; only a newly dispatched task or worker may receive the requested effort through the host's task/subagent option, with no model override. For an unsupported host or value, record the effective reasoning effort as `inherited` and leave model/global configuration unchanged.
+- Keep the model inherited. `Requested reasoning effort` is Cairn's desired profile; `Effective reasoning effort` is what the dispatch response confirms. Only a newly dispatched task or worker may receive the requested effort through the host's task/subagent option, with no model override. For an unsupported host or value, record Effective `inherited`; this means no task override was confirmed, not proof of missing host capability. Infer capability only from the exposed interface or dispatch response, distinguish Cairn non-integration from host non-support, and leave model/global configuration unchanged.
 - Do not treat complexity as a one-time choice. Require the provisional request checkpoint, post-exploration planning checkpoint, and code checkpoint after exact file/caller/test inspection immediately before the first edit. Before editing, evidence may change either route. Every change must synchronize the plan artifact, repository goal task roadmap through `goal replan`, and native UI plan, including reviews and required evidence. After editing begins, a new Heavy signal promotes Light Path to Heavy Path: stop further edits, mark affected evidence stale, synchronize all three roadmaps, and repeat the code checkpoint.
 - Do not stop before local implementation solely because subagent tools are unavailable; the main agent takes over implementation directly and records that takeover in evidence.
 - Keep work units small. Split large changes into smaller plan tasks.
@@ -46,7 +46,7 @@ Codex-family models are strong at small implementation tasks, explicit tool use,
 ### Implementation
 
 - Invest Codex reasoning in executable test design first, then hand the bounded failing contract to implementation and require the minimum passing patch.
-- Run verification through `goal verify -- ...`. Its default timeout is 600,000 ms (10 minutes), capped at 3,600,000 ms (1 hour). On success, retain exact argv, tool exit code, pass count, output digest, and watched-workspace fingerprint; commit evidence only when the starting goal/task identity and pre/post watched fingerprint match. Choose the watch set and command at the semantic boundary that proves the claim. Expand diagnostics only for the failing test and its related file/symbol scope; reject stale evidence after related changes.
+- Run verification through `goal verify -- ...`. Its default timeout is 600,000 ms (10 minutes), capped at 3,600,000 ms (1 hour). On success, retain exact argv, tool exit code, pass count, output digest, and watched-workspace fingerprint; commit evidence only when the starting goal/task identity and pre/post watched fingerprint match. Choose the watch set and command at the semantic boundary that proves the claim. The default Git fingerprint excludes ignored files; explicitly `--watch` every ignored artifact needed by the claim. Expand diagnostics only for the failing test and its related file/symbol scope; reject stale evidence after related changes.
 - If acting as the user-called/main agent, orchestrate the work and delegate actual implementation edits to `worker` whenever subagent tools are available, regardless of Light Path or Heavy Path.
 - If acting as the user-called/main agent, immediately relay received subagent status events to the user. If no mid-run reporting channel exists, relay observable events such as assignment, waiting, and final completion.
 - If acting as the user-called/main agent, close or release completed subagents after capturing their final report and evidence, then review the final report and evidence before marking the work complete.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cairn-ai",
-  "version": "0.2.6",
+  "version": "0.2.8",
   "description": "Token-efficient agent harness with tool readiness for Codex, Claude Code, and Antigravity",
   "license": "MIT",
   "author": {
@@ -32,7 +32,9 @@
     "commands/",
     "docs/model-guidance/",
     "hooks/",
-    "scripts/",
+    "scripts/cairn",
+    "scripts/*.mjs",
+    "scripts/release-integrity-*.json",
     "skills/",
     "templates/",
     "README.md",

package/scripts/cairn-cleanup.mjs

@@ -5,24 +5,28 @@ import { pathToFileURL } from "node:url";
 import { reconcileWorktreeState } from "./cairn-goal.mjs";
 import { parseRootArgs } from "./cairn-paths.mjs";
 
-const knownNames = new Set(["state.json", "state.lock", "tools"]);
+const staleLockName = /^state\.lock\.stale\..+\.[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
 
 export async function cleanupProjectCairn({ root = process.cwd(), apply = false } = {}) {
   const repoRoot = resolve(root);
   const legacyRoot = join(repoRoot, ".cairn");
-  let entries;
+  let rootStat;
   try {
-    entries = await readdir(legacyRoot, { withFileTypes: true });
+    rootStat = await lstat(legacyRoot);
   } catch (error) {
     if (error?.code === "ENOENT") return { root: repoRoot, apply, known: [], unknown: [], removed: [], projectDirectoryRemoved: false };
     throw error;
   }
+  if (rootStat.isSymbolicLink()) throw new Error(`Legacy Cairn root must not be a symbolic link: ${legacyRoot}`);
+  if (!rootStat.isDirectory()) throw new Error(`Legacy Cairn root is not a directory: ${legacyRoot}`);
 
+  const entries = await readdir(legacyRoot, { withFileTypes: true });
   const known = [];
   const unknown = [];
   for (const entry of entries) {
-    const isKnownStaleLock = entry.name.startsWith("state.lock.stale.");
-    (knownNames.has(entry.name) || isKnownStaleLock ? known : unknown).push(entry.name);
+    const isKnownFile = entry.isFile() && (entry.name === "state.json" || entry.name === "state.lock" || staleLockName.test(entry.name));
+    const isKnownDirectory = entry.isDirectory() && entry.name === "tools";
+    (isKnownFile || isKnownDirectory ? known : unknown).push(entry.name);
   }
   if (!apply) return { root: repoRoot, apply, known: known.sort(), unknown: unknown.sort(), removed: [], projectDirectoryRemoved: false };
 
@@ -32,7 +36,9 @@ export async function cleanupProjectCairn({ root = process.cwd(), apply = false
     const path = join(legacyRoot, name);
     try {
       const stat = await lstat(path);
-      await rm(path, { recursive: stat.isDirectory(), force: true });
+      const expectedType = name === "tools" ? stat.isDirectory() : stat.isFile();
+      if (!expectedType) continue;
+      await rm(path, { recursive: name === "tools", force: true });
       removed.push(name);
     } catch (error) {
       if (error?.code !== "ENOENT") throw error;

package/scripts/cairn-goal-cli.mjs

@@ -0,0 +1,239 @@
+export async function runGoalCli(args, {
+  stdout = console.log,
+  defaultGoalEvidence,
+  operations,
+}) {
+  const [firstCommand = "help", ...remaining] = args;
+  const [command = "help", ...rest] = firstCommand === "goal" ? remaining : [firstCommand, ...remaining];
+  const { options, positional, passthrough } = parseArgs(rest, command);
+  const root = options.root ?? process.cwd();
+  const emit = options.quiet ? () => {} : stdout;
+  if (command === "start") {
+    const tasks = parseTasks(options.tasks ?? positional.slice(0));
+    const state = await operations.startGoal({
+      root,
+      goal: options.goal,
+      planId: options.plan,
+      tasks,
+      completionCriteria: splitValues(options.criteria),
+      requiredEvidence: options.requiredEvidence ? splitValues(options.requiredEvidence) : defaultGoalEvidence,
+      ownerSessionId: options.session,
+      evidencePolicy: options.evidencePolicy ?? options["evidence-policy"] ?? "tool-bound",
+    });
+    emit(JSON.stringify(state));
+    return state;
+  }
+  if (command === "status") {
+    const state = await operations.readGoalState({ root });
+    stdout(JSON.stringify(state));
+    return state;
+  }
+  if (command === "task") {
+    if (positional[0] === "status" && options.status === undefined) {
+      const state = await operations.readGoalState({ root });
+      if (!state) {
+        stdout(JSON.stringify(null));
+        return null;
+      }
+      const requestedTaskId = options.task ?? positional[1];
+      const task = requestedTaskId === undefined
+        ? state.tasks.find((candidate) => candidate.status === "active") ?? null
+        : state.tasks.find((candidate) => candidate.id === requestedTaskId);
+      if (requestedTaskId !== undefined && task === undefined) throw new Error(`Unknown task: ${requestedTaskId}`);
+      stdout(JSON.stringify(task));
+      return task;
+    }
+    const taskAction = taskStatusFromAction(positional[0]);
+    const state = await operations.setTaskStatus({
+      root,
+      taskId: options.task ?? (taskAction ? positional[1] : positional[0]),
+      status: options.status ?? taskAction ?? positional[1],
+      blocker: options.reason,
+    });
+    emit(JSON.stringify(state));
+    return state;
+  }
+  if (command === "replan") {
+    const state = await operations.replanGoal({ root, tasks: parseTasks(options.tasks ?? positional.slice(0)) });
+    emit(JSON.stringify(state));
+    return state;
+  }
+  if (command === "claim") {
+    const state = await operations.claimGoal({ root, sessionId: options.session });
+    emit(JSON.stringify(state));
+    return state;
+  }
+  if (command === "assign") {
+    const state = await operations.assignTask({
+      root,
+      taskId: options.task ?? positional[0],
+      agentId: options.agent ?? positional[1] ?? null,
+    });
+    emit(JSON.stringify(state));
+    return state;
+  }
+  if (command === "receipt") {
+    const state = await operations.recordReceipt({
+      root,
+      taskId: options.task ?? positional[0],
+      kind: options.kind,
+      scope: options.scope,
+      command: options.command,
+      exitCode: numberOption(options.exitCode ?? options["exit-code"] ?? options.exit),
+      timestamp: options.timestamp,
+      goalId: options.goalId ?? options["goal-id"],
+      planId: options.plan,
+    });
+    emit(JSON.stringify(state));
+    return state;
+  }
+  if (command === "verify") {
+    const result = await operations.verifyAndRecord({
+      root,
+      taskId: options.task ?? positional[0],
+      kind: options.kind,
+      scope: options.scope,
+      watchPaths: splitValues(options.watch),
+      argv: passthrough,
+      timeoutMs: options["timeout-ms"] === undefined
+        ? 600_000
+        : positiveIntegerOption(options["timeout-ms"], "timeout-ms"),
+    });
+    emit(JSON.stringify({
+      id: result.evidence.id,
+      scope: result.evidence.scope,
+      kind: result.evidence.kind,
+      exitCode: result.evidence.exitCode,
+      outputDigest: result.evidence.outputDigest,
+      workspaceFingerprint: result.evidence.workspaceFingerprint,
+    }));
+    return result.state;
+  }
+  if (["pause", "resume", "block", "cancel", "complete"].includes(command)) {
+    const state = await operations.transitionGoal({
+      root,
+      status: { pause: "paused", resume: "active", block: "blocked", cancel: "cancelled", complete: "completed" }[command],
+      blocker: options.reason,
+    });
+    emit(JSON.stringify(state));
+    return state;
+  }
+  throw new Error("Usage: cairn-goal start|status|task|replan|claim|assign|receipt|verify|pause|resume|block|cancel|complete [--root PATH]");
+}
+
+function parseArgs(args, command) {
+  const options = {};
+  const positional = [];
+  const passthrough = [];
+  const booleanOptions = new Set(["quiet"]);
+  const allowed = allowedOptions(command);
+  const seenCanonicalOptions = new Set();
+  for (let index = 0; index < args.length; index += 1) {
+    const value = args[index];
+    if (value === "--") {
+      passthrough.push(...args.slice(index + 1));
+      break;
+    }
+    if (!value.startsWith("--")) {
+      positional.push(value);
+      continue;
+    }
+    const option = value.slice(2);
+    const equalsIndex = option.indexOf("=");
+    const key = equalsIndex === -1 ? option : option.slice(0, equalsIndex);
+    const inline = equalsIndex === -1 ? undefined : option.slice(equalsIndex + 1);
+    if (!allowed.has(key)) throw new Error(`Unknown option for ${command}: --${key}`);
+    const canonicalKey = canonicalOptionKey(key);
+    if (seenCanonicalOptions.has(canonicalKey)) throw new Error(`--${canonicalKey} may only be provided once`);
+    seenCanonicalOptions.add(canonicalKey);
+    if (inline !== undefined) {
+      if (!booleanOptions.has(key) && inline.length === 0) throw new Error(`--${key} requires a value`);
+      if (booleanOptions.has(key) && !["true", "false"].includes(inline)) throw new Error(`--${key} must be true or false`);
+      options[key] = booleanOptions.has(key) ? inline !== "false" : inline;
+    } else if (booleanOptions.has(key)) {
+      options[key] = true;
+    } else {
+      const next = args[index + 1];
+      if (next === undefined || next === "--" || next.startsWith("--")) throw new Error(`--${key} requires a value`);
+      options[key] = next;
+      index += 1;
+    }
+  }
+  return { options, positional, passthrough };
+}
+
+function canonicalOptionKey(key) {
+  return {
+    exitCode: "exit-code",
+    exit: "exit-code",
+    goalId: "goal-id",
+    evidencePolicy: "evidence-policy",
+  }[key] ?? key;
+}
+
+function allowedOptions(command) {
+  const common = ["root", "quiet"];
+  const byCommand = {
+    start: ["goal", "plan", "tasks", "criteria", "requiredEvidence", "session", "evidencePolicy", "evidence-policy"],
+    status: [],
+    task: ["task", "status", "reason"],
+    replan: ["tasks"],
+    claim: ["session"],
+    assign: ["task", "agent"],
+    receipt: ["task", "kind", "scope", "command", "exitCode", "exit-code", "exit", "timestamp", "goalId", "goal-id", "plan"],
+    verify: ["task", "kind", "scope", "watch", "timeout-ms"],
+    pause: [],
+    resume: [],
+    block: ["reason"],
+    cancel: [],
+    complete: [],
+    help: [],
+  };
+  return new Set([...common, ...(byCommand[command] ?? [])]);
+}
+
+function parseTasks(value) {
+  if (Array.isArray(value)) return value;
+  if (typeof value !== "string" || value.trim().length === 0) throw new Error("Provide tasks with --tasks JSON or positional task titles");
+  try {
+    const parsed = JSON.parse(value);
+    if (!Array.isArray(parsed)) throw new Error("--tasks JSON must be an array");
+    return parsed;
+  } catch (error) {
+    if (error instanceof SyntaxError) return value.split("|").map((item) => item.trim()).filter(Boolean);
+    throw error;
+  }
+}
+
+function splitValues(value) {
+  if (!value) return [];
+  return String(value).split("|").map((item) => item.trim()).filter(Boolean);
+}
+
+function numberOption(value) {
+  if (value === undefined) return undefined;
+  const result = Number(value);
+  if (!Number.isInteger(result)) throw new Error("exitCode must be an integer");
+  return result;
+}
+
+function positiveIntegerOption(value, label) {
+  const result = Number(value);
+  if (!Number.isSafeInteger(result) || result <= 0 || result > 3_600_000) {
+    throw new Error(`${label} must be an integer between 1 and 3600000`);
+  }
+  return result;
+}
+
+function taskStatusFromAction(value) {
+  return {
+    start: "active",
+    activate: "active",
+    active: "active",
+    complete: "completed",
+    completed: "completed",
+    block: "blocked",
+    blocked: "blocked",
+    pending: "pending",
+  }[value] ?? null;
+}

package/scripts/cairn-goal-evidence.mjs

@@ -0,0 +1,186 @@
+import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { lstatSync, readFileSync, readlinkSync, readdirSync } from "node:fs";
+import { join, relative, resolve, sep } from "node:path";
+
+export function normalizeVerificationArgv(argv) {
+  if (!Array.isArray(argv) || argv.length === 0) throw new Error("verification command must follow -- as argv");
+  return argv.map((item, index) => {
+    if (typeof item !== "string") throw new Error(`verification argv[${index}] must be a string`);
+    if (index === 0 && item.trim().length === 0) throw new Error("verification executable must be a non-empty string");
+    return item;
+  });
+}
+
+export function normalizeWatchPaths(root, watchPaths) {
+  if (!Array.isArray(watchPaths)) throw new Error("watchPaths must be an array");
+  const workspaceRoot = resolve(root);
+  return [...new Set(watchPaths.map((item, index) => {
+    const source = requiredText(item, `watchPaths[${index}]`);
+    const absolutePath = resolve(workspaceRoot, source);
+    const relativePath = relative(workspaceRoot, absolutePath);
+    if (relativePath === ".." || relativePath.startsWith(`..${sep}`)) {
+      throw new Error(`watch path must remain inside the workspace: ${source}`);
+    }
+    const normalizedPath = relativePath === "" ? "." : relativePath.split(sep).join("/");
+    if (isInternalStatePath(normalizedPath)) throw new Error(`watch path cannot target internal Cairn or Git state: ${source}`);
+    return normalizedPath;
+  }))];
+}
+
+export function workspaceFingerprint(root = process.cwd(), watchPaths = []) {
+  const workspaceRoot = resolve(root);
+  const normalizedWatchPaths = normalizeWatchPaths(workspaceRoot, watchPaths);
+  const gitPaths = normalizedWatchPaths.length === 0 ? listGitWorkspacePaths(workspaceRoot) : null;
+  const paths = normalizedWatchPaths.length > 0
+    ? listFilesystemPaths(workspaceRoot, normalizedWatchPaths)
+    : (gitPaths ?? listFilesystemPaths(workspaceRoot, normalizedWatchPaths));
+  const hash = createHash("sha256");
+  for (const path of [...new Set(paths)].sort()) hashWorkspacePath(hash, workspaceRoot, path);
+  return `sha256:${hash.digest("hex")}`;
+}
+
+export function runVerificationEvidence({
+  root,
+  argv,
+  watchPaths,
+  runner = spawnSync,
+  timeoutMs,
+}) {
+  const initialFingerprint = workspaceFingerprint(root, watchPaths);
+  const result = runner(argv[0], argv.slice(1), {
+    cwd: resolve(root),
+    encoding: "utf8",
+    maxBuffer: 16 * 1024 * 1024,
+    shell: false,
+    timeout: validTimeout(timeoutMs),
+  });
+  if (result.error?.code === "ETIMEDOUT") throw new Error(`Verification timed out after ${timeoutMs}ms`);
+  if (result.error) throw new Error(`Verification could not start: ${result.error.message}`);
+  const exitCode = Number.isInteger(result.status) ? result.status : 1;
+  const output = combinedOutput(result.stdout, result.stderr);
+  if (exitCode !== 0) {
+    const detail = boundedText(output, 2000);
+    throw new Error(`Verification failed with exit ${exitCode}${detail ? `:\n${detail}` : ""}`);
+  }
+
+  const fingerprint = workspaceFingerprint(root, watchPaths);
+  if (fingerprint !== initialFingerprint) throw new Error("Watched workspace changed during verification; evidence was not recorded");
+  return {
+    argv,
+    command: argv.map((value) => JSON.stringify(value)).join(" "),
+    outputDigest: sha256(output),
+    summary: successSummary(output),
+    workspaceFingerprint: fingerprint,
+    watchPaths,
+  };
+}
+
+function listGitWorkspacePaths(root) {
+  const result = spawnSync("git", ["-C", root, "ls-files", "-z", "--cached", "--others", "--exclude-standard"], {
+    encoding: "utf8",
+    maxBuffer: 16 * 1024 * 1024,
+  });
+  if (result.status !== 0 || result.error) return null;
+  return result.stdout.split("\0").filter(Boolean)
+    .filter((path) => !isInternalStatePath(path) && !isCairnRecordPath(path));
+}
+
+// Cairn records evidence in these artifacts after verification; including them in the default fingerprint would
+// make every recorded receipt stale. Pass --watch explicitly when a claim is about these files.
+function isCairnRecordPath(path) {
+  return path === "PLAN.md" || path === "MEMORY.md" || path.startsWith("docs/plan/") || path.startsWith("docs/memory/");
+}
+
+function listFilesystemPaths(root, watchPaths) {
+  const paths = [];
+  const visit = (relativePath) => {
+    if (isInternalStatePath(relativePath)) return;
+    const absolutePath = relativePath === "." ? root : join(root, ...relativePath.split("/"));
+    let stat;
+    try {
+      stat = lstatSync(absolutePath);
+    } catch (error) {
+      if (error?.code === "ENOENT") {
+        paths.push(relativePath);
+        return;
+      }
+      throw error;
+    }
+    if (!stat.isDirectory()) {
+      paths.push(relativePath);
+      return;
+    }
+    const entries = readdirSync(absolutePath).sort();
+    if (entries.length === 0) paths.push(relativePath);
+    for (const entry of entries) {
+      const child = relativePath === "." ? entry : `${relativePath}/${entry}`;
+      visit(child);
+    }
+  };
+  for (const path of watchPaths.length > 0 ? watchPaths : ["."]) visit(path);
+  return paths;
+}
+
+function hashWorkspacePath(hash, root, relativePath) {
+  const absolutePath = relativePath === "." ? root : join(root, ...relativePath.split("/"));
+  hash.update(`${relativePath}\0`);
+  let stat;
+  try {
+    stat = lstatSync(absolutePath);
+  } catch (error) {
+    if (error?.code === "ENOENT") {
+      hash.update("missing\0");
+      return;
+    }
+    throw error;
+  }
+  hash.update(`${stat.mode}\0`);
+  if (stat.isSymbolicLink()) {
+    hash.update(`symlink\0${readlinkSync(absolutePath)}\0`);
+  } else if (stat.isFile()) {
+    hash.update("file\0");
+    hash.update(readFileSync(absolutePath));
+    hash.update("\0");
+  } else if (stat.isDirectory()) {
+    hash.update("directory\0");
+  } else {
+    hash.update("other\0");
+  }
+}
+
+function isInternalStatePath(path) {
+  const firstSegment = path.split("/")[0];
+  return firstSegment === ".git" || firstSegment === ".cairn";
+}
+
+function requiredText(value, label) {
+  if (typeof value !== "string" || value.trim().length === 0) throw new Error(`${label} must be a non-empty string`);
+  return value.trim();
+}
+
+function combinedOutput(stdout, stderr) {
+  return [stdout, stderr].filter((value) => typeof value === "string" && value.length > 0).join("\n").trim();
+}
+
+function boundedText(value, maxLength) {
+  const text = String(value ?? "").trim();
+  if (text.length <= maxLength) return text;
+  return `…${text.slice(-(maxLength - 1))}`;
+}
+
+function successSummary(output) {
+  const text = String(output ?? "");
+  const outputBytes = Buffer.byteLength(text);
+  const outputLines = text.length === 0 ? 0 : text.split(/\r?\n/).length;
+  return `verification passed; outputBytes=${outputBytes}; outputLines=${outputLines}`;
+}
+
+function sha256(value) {
+  return `sha256:${createHash("sha256").update(value).digest("hex")}`;
+}
+
+function validTimeout(value) {
+  if (!Number.isSafeInteger(value) || value <= 0) throw new Error("timeoutMs must be a positive integer");
+  return value;
+}