cairn-ai 0.2.5 → 0.2.7

package/commands/cairn-review.md

@@ -2,13 +2,13 @@
 
 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 must read the project-root `MEMORY.md` for domain knowledge and repository policy before review work, then read the plan task and memory inputs.
+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.
 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.

package/commands/cairn-uninstall.md

@@ -19,4 +19,4 @@ Managed items:
 
 After the transaction commits, Cairn removes empty managed scaffold directories bottom-up and removes the custom marketplace root only after releasing its own lifecycle lock. A directory containing any unmanaged child is preserved; pruning never uses recursive deletion.
 
-The source work folder and repository `MEMORY.md`, `PLAN.md`, `docs/`, and `.cairn/state.json` are not deleted. The globally installed `cairn-ai` package, package-manager download caches, legacy backup files, and legacy shared settings not recorded by the current ownership manifest are also outside this command's scope and require a separate, explicit cleanup decision.
+The source work folder, repository `MEMORY.md`, `PLAN.md`, `docs/`, and user-home Cairn goal state are not deleted. The globally installed `cairn-ai` package, package-manager download caches, legacy backup files, and legacy shared settings not recorded by the current ownership manifest are also outside this command's scope and require a separate, explicit cleanup decision.

package/commands/cairn-work.md

@@ -2,13 +2,17 @@
 
 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`. 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 must read the project-root `MEMORY.md` for domain knowledge and repository policy before selecting or executing a task.
+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.
@@ -19,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.
 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,18 +7,20 @@ 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: root `MEMORY.md` → current phase skill → active plan → current-task references → model guidance recorded by the plan. If persisted state or an assignment requires a 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.
 - 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.
 - Preserve proper nouns, file names, variable names, service names, alert names, MCP tool names, and agent names exactly as written.
 - Select Light Path or Heavy Path before implementation.
+- Treat complexity as three checkpoints: a provisional request checkpoint, a post-exploration planning checkpoint, and a 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.
 - Treat the user-called/main agent as the orchestrator: it plans, assigns, verifies, and records evidence.
 - Delegate actual implementation edits to `worker` subagents whenever subagent tools are available, regardless of Light Path or Heavy Path.
 - When the subagent tool provides a progress-reporting channel, require subagents to report status to the orchestrator when starting work, when deciding or confirming direction, during periodic progress, and when finishing; the orchestrator must immediately relay received status events to the user. If no mid-run reporting channel exists, the orchestrator relays observable events such as assignment, waiting, and final completion.
@@ -26,11 +28,11 @@ The goal is not to make prompts long by model. The goal is to stabilize the same
 - If subagent tools are unavailable, the main agent takes over implementation directly and records that takeover in evidence.
 - Detect required LSP, typecheck, lint, dry-run, and verification tools before implementation.
 - Missing required tools must be reported with a proposed install. Installation requires explicit user approval and a pinned/supported installer.
-- Treat every implementation or continued-execution request as authorization to bind active work to a persisted Cairn goal and stable task IDs, even when the user does not mention a goal. After MEMORY.md, first write an initial plan that makes triage the active task. Before exploration or triage, synchronize its roadmap to Codex `update_plan` and `create_goal` when available and to the repository Cairn goal. Update both plans after triage, and implement only from the decision-complete revision. Exclude consultation, explanation, and plan-only requests.
+- Treat non-trivial implementation or continuation of planned work as authorization to bind active work to a persisted Cairn goal and stable task IDs, even when the user does not mention a goal. Routine known-target Git/GitHub operations (status, fetch, checkout, branch, merge, push, PR management) stay plan/goal-free unless they require code edits, conflict resolution, destructive recovery, release/deploy, or design. For planned work, after MEMORY.md, first write an initial plan that makes triage the active task, synchronize it before exploration, and implement only from the decision-complete revision. Exclude consultation, explanation, and plan-only requests.
 - 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.
@@ -46,6 +48,16 @@ The goal is not to make prompts long by model. The goal is to stabilize the same
 - Character budgets are regression proxies for cache-friendly prompt shape, not measurements of provider cache hits or cost. Cairn does not require provider cache keys, breakpoints, or live API telemetry.
 - Do not add read receipts that claim model attention. Restore references on every re-entry and use readable state plus fresh bound evidence as the enforceable contract.
 
+## Reasoning Effort Routing
+
+- 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`. 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, 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
 
 - `explorer`: use for read-only codebase discovery, impact analysis, pattern searches, and read-only verification when available.

package/docs/model-guidance/claude.md

@@ -18,7 +18,9 @@ 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. `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.
 - Write user-visible responses and generated or updated documentation, plans, and memory artifacts in the OS locale unless the user asks for another language.
 

package/docs/model-guidance/codex.md

@@ -17,8 +17,10 @@ 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 root `MEMORY.md` → current phase skill → active plan → current-task references → recorded model guidance. If persisted state or the assignment requires a 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.
 - Do not start implementation without a plan.
+- 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.
 - If `apply_patch` is unstable in the environment, use an editing tool or a clear file update path.
@@ -44,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.5",
+  "version": "0.2.7",
   "description": "Token-efficient agent harness with tool readiness for Codex, Claude Code, and Antigravity",
   "license": "MIT",
   "author": {
@@ -32,14 +32,16 @@
     "commands/",
     "docs/model-guidance/",
     "hooks/",
-    "scripts/",
+    "scripts/cairn",
+    "scripts/*.mjs",
+    "scripts/release-integrity-*.json",
     "skills/",
     "templates/",
     "README.md",
     "README.*.md"
   ],
   "scripts": {
-    "check": "node --check scripts/cairn.mjs && node --check scripts/cairn-paths.mjs && node --check scripts/cairn-safe-fs.mjs && node --check scripts/cairn-goal.mjs && node --check scripts/cairn-state.mjs && node --check scripts/cairn-lifecycle.mjs && node --check scripts/cairn-toolcheck.mjs && node -e \"JSON.parse(require('node:fs').readFileSync('package.json','utf8')); JSON.parse(require('node:fs').readFileSync('.codex-plugin/plugin.json','utf8')); JSON.parse(require('node:fs').readFileSync('hooks/hooks.json','utf8')); JSON.parse(require('node:fs').readFileSync('scripts/release-integrity-0.2.2.json','utf8'))\" && npm test",
+    "check": "node --check scripts/cairn.mjs && node --check scripts/cairn-paths.mjs && node --check scripts/cairn-safe-fs.mjs && node --check scripts/cairn-goal.mjs && node --check scripts/cairn-state.mjs && node --check scripts/cairn-cleanup.mjs && node --check scripts/cairn-lifecycle.mjs && node --check scripts/cairn-toolcheck.mjs && node -e \"JSON.parse(require('node:fs').readFileSync('package.json','utf8')); JSON.parse(require('node:fs').readFileSync('.codex-plugin/plugin.json','utf8')); JSON.parse(require('node:fs').readFileSync('hooks/hooks.json','utf8')); JSON.parse(require('node:fs').readFileSync('scripts/release-integrity-0.2.2.json','utf8'))\" && npm test",
     "test": "node --test",
     "prepack": "npm run check"
   },

package/scripts/cairn-cleanup.mjs

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+import { lstat, readdir, rm, rmdir } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { reconcileWorktreeState } from "./cairn-goal.mjs";
+import { parseRootArgs } from "./cairn-paths.mjs";
+
+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 rootStat;
+  try {
+    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 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 };
+
+  if (known.includes("state.json")) await reconcileWorktreeState({ root: repoRoot });
+  const removed = [];
+  for (const name of known) {
+    const path = join(legacyRoot, name);
+    try {
+      const stat = await lstat(path);
+      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;
+    }
+  }
+  let projectDirectoryRemoved = false;
+  try {
+    await rmdir(legacyRoot);
+    projectDirectoryRemoved = true;
+  } catch (error) {
+    if (!["ENOENT", "ENOTEMPTY", "EEXIST"].includes(error?.code)) throw error;
+  }
+  return { root: repoRoot, apply, known: known.sort(), unknown: unknown.sort(), removed: removed.sort(), projectDirectoryRemoved };
+}
+
+async function main() {
+  const { args, repoRoot } = parseRootArgs(process.argv.slice(2));
+  const apply = args.includes("--yes");
+  const unsupported = args.filter((value) => value !== "--yes" && value !== "--check");
+  if (unsupported.length > 0) throw new Error(`Unknown cleanup option: ${unsupported[0]}`);
+  console.log(JSON.stringify(await cleanupProjectCairn({ root: repoRoot, apply }), null, 2));
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  await main();
+}

package/scripts/cairn-goal-cli.mjs

@@ -0,0 +1,233 @@
+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 === "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|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"],
+    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;
+}