cairn-ai 0.2.9 → 0.3.0

package/.agents/workflows/cairn-plan.md

@@ -2,28 +2,21 @@
 
 Use the `cairn-plan` skill.
 
-Read the installed Cairn runtime locator at `{{CAIRN_RUNTIME_LOCATOR_JSON}}`. Resolve Cairn scripts, model guidance, templates, commands, and agents through that locator; only repository state such as `MEMORY.md`, `PLAN.md`, and `docs/plan/` belongs to the target project. If the shared runtime or locator is missing, unreadable, or inconsistent, stop every dependent mirror and recover through published/global `cairn doctor` followed by `cairn upgrade`, never through another mirror.
+Read the installed Cairn runtime locator at `{{CAIRN_RUNTIME_LOCATOR_JSON}}`. Resolve Cairn scripts, model guidance, templates, skills, commands, and agents through that locator (`pluginRoot`, `entrypoints.cli`, `resources.modelGuidance`); only repository state such as `MEMORY.md`, `PLAN.md`, and `docs/plan/` belongs to the target project. If the shared runtime or locator is missing, unreadable, or inconsistent, stop every dependent mirror and recover through published/global `cairn doctor` followed by `cairn upgrade`, never through another mirror.
 
-Goal: write an initial plan with triage as its active task before exploration, persist the goal/roadmap, then update the same plan to a decision-complete implementation revision after triage.
+Goal: show an initial plan and goal before triage can be interrupted, then leave a decision-complete implementation plan before non-trivial implementation.
 
-Complexity triage has a 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.
+Paths: 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. Quick Path needs no `docs/plan` artifact and no goal when all hold: unambiguous requirements; about 3 files or fewer inside existing layers; no Heavy Path signal; no external-state mutation; one or two verification commands. Implement, run one focused check plus the project's normal check, and report; if any criterion fails, escalate to Light Path (plan + goal) before further edits. Otherwise use Light Path by default and Heavy Path only when a Heavy Path condition clearly applies.
 
-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 host incapability. Claim capability only from an 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.
+Complexity is staged: request checkpoint, planning checkpoint after exploration, and code checkpoint immediately before the first edit. Before editing, either route may change; after editing begins, only Light → Heavy promotion is allowed. Every change synchronizes the plan artifact, repository goal task roadmap through `goal replan`, native UI plan, and reasoning effort profile. Models always inherit; request Light `medium`, Heavy `high`, final verification/review `xhigh`.
 
 Procedure:
 
 1. Every agent reads project-root `MEMORY.md` when present and continues without repository memory when absent before repository exploration, tool selection, work, or delegation.
-2. Keep routine known-target Git/GitHub operations plan/goal-free unless they require code edits, conflict resolution, destructive recovery, release/deploy, or design. For non-trivial implementation or continuation of planned work, write the initial repository plan and `PLAN.md` entry from the request and `MEMORY.md`. Include a planned `triage-plan` task and anticipated execution/verification stages, then start or attach the repository Cairn goal before exploration.
-3. When the surface exposes native plan/goal UI tools, synchronize the same roadmap there before exploration; otherwise record that those tools are unavailable. If an unfinished repository goal already exists when a new implementation request, steer, or drift arrives, do not cancel it to start another. Fold the new work into it with `goal replan` (completed tasks and their evidence are preserved; resume a paused or blocked goal first), synchronize the plan artifact and native UI roadmap, and keep advancing until goal final review. Start a separate goal only when the user explicitly switches work. When a hook reports that another session owns the goal and this session continues that same work, take ownership with `goal claim --session <id>` using the ID shown by the hook.
-4. Read relevant `docs/memory/*.md` and perform toolcheck, exploration, and Light/Heavy Path triage according to the initial task.
-5. Update the same plan to a decision-complete implementation revision before implementation.
-6. If the active or assigned model is Claude-family, read `claude.md` under the locator's `resources.modelGuidance`; if Codex-family, read `codex.md` there.
-7. Invoke Node directly with the locator's absolute `entrypoints.cli`, `toolcheck`, and `--root` for the target repository.
-8. If required LSP/check tools are missing, follow the installed toolcheck policy before any explicitly approved installation attempt.
-9. Use Light Path by default unless a Heavy Path condition clearly applies.
-10. Use `explorer` for independent read-only discovery, impact analysis, pattern search, and read-only verification when available.
-11. Treat the user-called/main agent as the orchestrator: it plans, assigns, verifies, relays received subagent status events or observable lifecycle events to the user, and records evidence. Use `worker` for actual implementation edits with clear file ownership whenever subagent tools are available, on both Light Path and Heavy Path. When the subagent tool provides a progress-reporting channel, require subagents to report status when starting work, when deciding or confirming direction, during periodic progress, and when finishing; immediately relay received status events to the user. If no mid-run reporting channel exists, relay observable events such as assignment, waiting, and final completion. Require delegated subagents to provide a final report before leaving; after capturing the final report and evidence, close or release the completed subagent, then review the final report and evidence before marking the work complete. 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. If subagent tools are unavailable, the main agent takes over implementation directly and records that takeover in evidence.
-12. Record selected path, checked Heavy Path signals, tool readiness, module acceptance verification, and surface integration verification on every implementation task in the existing plan.
-13. Advance native UI steps only after the matching repository task transition succeeds with its required bound evidence records.
-14. Keep the existing `PLAN.md` entry and repository goal synchronized with the finalized plan status.
-15. Use the OS locale for user-visible responses and generated or updated documentation, plans, and memory artifacts unless the user asks for another language.
+2. For non-trivial implementation or continuation of planned work, write an initial `docs/plan/<topic>.md` and `PLAN.md` entry with `triage-plan` as the first active task. This initial plan is decision-complete for triage and explicitly not implementation-ready.
+3. Before exploration, toolcheck, triage, or delegation, call Codex `update_plan` and then `create_goal` when available, and start the repository Cairn goal with the same roadmap. Copy the session-start hook's `Cairn CLI:` prefix literally into each command; never store it in a shell variable. `--root` may be omitted when the cwd is inside the repository. Fold new work into an unfinished goal with `goal replan` instead of cancelling it; when a hook reports another session owns the goal you continue, run `goal claim --session <id>`.
+4. Read relevant `docs/memory/*.md` and, under the locator's `resources.modelGuidance`, `claude.md` for Claude-family or `codex.md` for Codex-family models; invoke Node with the locator's absolute `entrypoints.cli`, `toolcheck`, and `--root` for the target repository (installation only with explicit approval), and explore before asking the user.
+5. Classify the whole work into executable tasks with `dependsOn`, `writeScope`, and handoff files, finalize triage, and update the same plan and `update_plan` roadmap to a decision-complete implementation plan: selected path, checked Heavy Path signals, tool readiness, file scope, dry-run/check, module acceptance, surface integration, stable IDs, and fail-closed evidence. Heavy Path adds an explicit automated test command and `Tests:` evidence line.
+6. Resolve the skill's reference files through the locator's `pluginRoot` and read them only when needed: `cairn://skills/cairn-plan/planning-rules.md` when finalizing, `cairn://skills/cairn-plan/delegation.md` before dispatching, `cairn://skills/cairn-plan/heavy-path.md` only on a Heavy signal or route change.
+7. The user-called/main agent orchestrates; implementation edits go to `worker` when subagent tools are available, otherwise the main agent takes over and records it. Advance a UI step only after the matching repository task transition succeeds with its required bound evidence.
+8. Use the OS locale for user-visible responses and generated or updated documentation, plans, and memory artifacts unless the user asks for another language.

package/.agents/workflows/cairn-work.md

@@ -2,29 +2,23 @@
 
 Use the `cairn-work` skill.
 
-Read the installed Cairn runtime locator at `{{CAIRN_RUNTIME_LOCATOR_JSON}}`. Resolve Cairn scripts and policy resources through that locator; only work artifacts and state belong to the target project. If the shared runtime or locator is missing, unreadable, or inconsistent, stop every dependent mirror and recover through published/global `cairn doctor` followed by `cairn upgrade`, never through another mirror.
+Read the installed Cairn runtime locator at `{{CAIRN_RUNTIME_LOCATOR_JSON}}`. Resolve Cairn scripts, skills, and policy resources through that locator (`pluginRoot`, `entrypoints.cli`, `resources.modelGuidance`); only work artifacts and state belong to the target project. If the shared runtime or locator is missing, unreadable, or inconsistent, stop every dependent mirror and recover through published/global `cairn doctor` followed by `cairn upgrade`, never through another mirror.
 
-Goal: execute the next incomplete module task in `PLAN.md` without bypassing the recorded complexity triage.
+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. Quick Path work has no plan or goal: implement, run one focused check plus the project's normal check, and report; escalate to Light Path (plan + goal) before further edits if any Quick Path criterion fails.
 
-Confirm the provisional request checkpoint and post-exploration planning checkpoint, then record the 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 host incapability. Claim capability only from an 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.
+Record the code checkpoint after exact file/caller/test inspection immediately before the first edit. After editing begins, a new Heavy Path signal promotes Light Path to Heavy Path: stop further edits, mark affected evidence stale, synchronize the plan artifact, `goal replan` roadmap, and native UI plan, and repeat the code checkpoint. Models always inherit; request Light `medium`, Heavy `high`, final verification/review `xhigh`.
 
 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. Read the Codex or Claude model guidance recorded in the plan.
-4. Select one small module task. Read it with `goal task status` (full `goal status` only when receipts are needed). 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.
-5. Confirm required tool readiness by invoking Node directly with the locator's absolute `entrypoints.cli`, `toolcheck`, and `--root` for the target repository. Follow the installed toolcheck policy before any explicitly approved installation attempt.
-6. Confirm the complexity triage and selected Light/Heavy Path recorded in the plan. If missing, update the plan before mutating files.
-7. Spend reasoning on a focused executable test contract before implementation: requirements, invariants, boundaries, and failure modes. Confirm the intended failure, then require only the minimum implementation that passes.
-8. For Light Path, keep the user-called/main agent in the orchestrator role and delegate implementation edits to one bounded `worker` whenever subagent tools are available, then run focused verification.
-9. For Heavy Path, follow the plan's staged implementation and review gates without role-mapping shortcuts.
-10. Give implementation only the test contract, failing evidence, exact file ownership, and constraints. Delegate actual implementation edits to `worker` on both paths whenever subagent tools are available. 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; immediately relay received status events to the user. If no mid-run reporting channel exists, relay observable events such as assignment, waiting, and final completion. Require delegated subagents to provide a final report before leaving; after capturing the final report and evidence, close or release the completed subagent, then review the final report and evidence before marking the work complete. 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. If subagent tools are unavailable, the main agent takes over implementation directly and records that takeover in evidence.
-11. Treat tool exit codes and bounded machine summaries as authoritative. Keep success concise; expand context only around failing tests.
-12. Run focused tests, then one final full repository check through `goal verify -- ...`. Verification defaults to 600,000 ms (10 minutes), is capped at 3,600,000 ms (1 hour), and records evidence only when the starting goal/task identity and pre/post watched fingerprint still match. Select a semantic boundary that proves the claim. The default Git fingerprint excludes ignored files; explicitly `--watch` every ignored artifact needed by the claim. Any relevant later mutation makes affected evidence stale. 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. Inspect package lifecycle scripts before package verification 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 while the full-check evidence remains fresh.
-14. Record tool readiness and verification evidence in `docs/plan/<topic>.md` and update `PLAN.md`.
-15. If the user asks a side question, status question, or narrow clarification while this task is still active, answer it briefly and then resume the previous active work unless the user explicitly asks to pause, stop, or switch tasks.
-16. Use the OS locale for user-visible responses and generated or updated documentation, plans, and memory artifacts unless the user asks for another language.
+2. Read `PLAN.md`, the detailed plan, relevant memory notes, and the `cairn://` model guidance recorded in the plan through the installed runtime.
+3. Read the current task with `goal task status`; run `goal ready` and delegate independent ready tasks to parallel workers (same worktree, disjoint `writeScope`). Fold a new request into an unfinished goal with `goal replan` instead of cancelling it. Copy the session-start hook's `Cairn CLI:` prefix literally; never store it in a shell variable. `--root` may be omitted when the cwd is inside the repository.
+4. Confirm tool readiness by invoking Node with the locator's absolute `entrypoints.cli`, `toolcheck`, and `--root` (installation only with explicit approval) and the recorded route.
+5. Before implementation, spend reasoning on a focused executable test contract covering requirements, invariants, boundaries, and failure modes. Confirm the intended failure, then give the `worker` the contract, failing evidence, exact file ownership, and constraints and require the minimum change.
+6. Run module acceptance and surface integration through `goal verify -- ...`; `--kind "moduleAcceptance|surfaceIntegration"` records both from one run. Treat tool exit codes as authoritative and expand context only around failing tests. Heavy Path records explicit `Tests:` evidence.
+7. 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, and after a fix search for other implementations of the same rule or pattern.
+8. Inspect package lifecycle scripts 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 while the full check remains fresh.
+9. Relevant mutation makes the current task's evidence stale; rerun it before completing the task. Do not rerun earlier tasks' checks; finish with one goal-level check through `goal finish -- ...`. Missing, failed, skipped, stale, or placeholder evidence never completes work. `goal stats` measures receipt reruns.
+10. Resolve the skill's reference files through the locator's `pluginRoot` and read them only when needed: `cairn://skills/cairn-work/verification.md`, `cairn://skills/cairn-work/delegation.md`, `cairn://skills/cairn-work/recovery.md`, and `cairn://skills/cairn-work/heavy-path.md` (Heavy route only).
+11. Update the plan, goal state, and `PLAN.md` only after evidence exists. If the user asks a side question, status question, or narrow clarification while this task is still active, answer it briefly and then resume the previous active work unless the user explicitly asks to pause, stop, or switch tasks.
+12. Use the OS locale for user-visible responses and generated or updated documentation, plans, and memory artifacts unless the user asks for another language.

package/.claude/commands/cairn-plan.md

@@ -1,5 +1,5 @@
 # cairn-plan
 
-Start by reading the project-root `MEMORY.md`, write an initial `PLAN.md` and `docs/plan/<topic>.md` with a planned triage task, persist the goal before exploration, then update the same plan after Light/Heavy Path triage and tool readiness checks before implementation.
+Start by reading the project-root `MEMORY.md`, write an initial `PLAN.md` and `docs/plan/<topic>.md` with a planned triage task, persist the goal before exploration, then update the same plan after Light/Heavy Path triage and tool readiness checks before implementation. Quick Path work (criteria in `cairn-plan.md`) needs no plan or goal and escalates to Light Path before further edits when any criterion fails.
 
 Read the installed Cairn runtime locator at `{{CAIRN_RUNTIME_LOCATOR_JSON}}`. Resolve `resources.commands` from that JSON object and follow `cairn-plan.md` in that directory. Resolve model guidance and templates through the same locator. Do not resolve Cairn runtime resources from the target project. If the shared runtime or locator is missing, unreadable, or inconsistent, stop all dependent mirrors and recover with published/global `cairn doctor` followed by `cairn upgrade`; do not repair through another mirror.

package/.claude/commands/cairn-work.md

@@ -1,6 +1,6 @@
 # cairn-work
 
-Start by reading the project-root `MEMORY.md`, then execute the next incomplete module task only after the plan records Light/Heavy Path complexity triage, tool readiness, module acceptance verification, and surface integration verification. Before implementation, spend reasoning on a focused executable test contract covering requirements, invariants, boundaries, and failure modes; confirm the intended failure and make only the minimum implementation that passes. Run verification through `goal verify -- ...`; the default timeout is 600,000 ms (10 minutes), the maximum is 3,600,000 ms (1 hour), and evidence is committed only when the starting goal/task identity and pre/post watched fingerprint still match. Choose a semantic boundary that proves the claim, treat tool exit codes and bounded machine summaries as authoritative, keep successes concise, and expand context only for failing tests. Inspect package lifecycle scripts 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 while the prior full check remains fresh.
+Start by reading the project-root `MEMORY.md`, then execute the next incomplete module task only after the plan records Light/Heavy Path complexity triage, tool readiness, module acceptance verification, and surface integration verification. Before implementation, spend reasoning on a focused executable test contract covering requirements, invariants, boundaries, and failure modes; confirm the intended failure and make only the minimum implementation that passes. Run verification through `goal verify -- ...` and finish the goal with one goal-level check through `goal finish -- ...`; the default timeout is 600,000 ms (10 minutes), the maximum is 3,600,000 ms (1 hour), and evidence is committed only when the starting goal/task identity and pre/post watched fingerprint still match. Choose a semantic boundary that proves the claim, treat tool exit codes and bounded machine summaries as authoritative, keep successes concise, and expand context only for failing tests. Inspect package lifecycle scripts 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 while the prior full check remains fresh.
 
 If the user asks a side question, status question, or narrow clarification while a task is still active, answer it briefly and then resume the previous active work unless the user explicitly asks to pause, stop, or switch tasks.
 

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "cairn",
-  "version": "0.2.9",
+  "version": "0.3.0",
   "description": "Token-efficient agent harness with tool readiness for Codex, Claude Code, and Antigravity.",
   "author": {
     "name": "WkNam"

package/README.ko.md

@@ -115,7 +115,7 @@ cairn toolcheck
 - `cairn uninstall`: 먼저 config 외 모든 ownership manifest 항목을 설치 digest와 대조하고, 수정되거나 삭제된 managed artifact가 하나라도 있으면 아무것도 바꾸지 않고 uninstall 전체를 거부합니다. 그렇지 않으면 managed 항목을 제거·복원하고 빈 managed cache scaffold를 정리하며, unmanaged target과 그 상위 디렉터리는 보존하고 commit 전 실패는 rollback합니다.
 - `cairn toolcheck`: 저장소 스택과 필요한 LSP·검증 도구를 확인하며, 승인된 지원 installer만 실행합니다.
 - `cairn cleanup --root <repo>`: 기본값은 legacy 프로젝트 로컬 `.cairn` 잔여물을 읽기 전용으로 보고합니다. `--yes`는 유효한 활성 상태를 사용자 홈 저장소로 조정·이관하고 알려진 상태/lock/tool 잔여물만 제거하며, 알 수 없는 파일은 보존하고 비었을 때만 디렉터리를 정리합니다.
-- `cairn goal ...`: 저장소의 영속 goal을 시작·조회·일시정지·재개·차단·취소·완료합니다. `goal claim --session <id>`는 같은 작업을 이어받는 session(재개·압축·handoff·fork)에 미완료 goal의 소유권을 넘기며, 미완료 goal 중에 들어온 새 작업은 goal을 취소하지 않고 `goal replan`으로 합칩니다. 기본 tool-bound 정책은 `goal verify -- <argv>`가 명령을 직접 실행해 성공 증거를 기록합니다. `goal receipt`는 기존 선언 증거를 가져오는 호환 명령입니다.
+- `cairn goal ...`: 저장소의 영속 goal을 시작·조회·일시정지·재개·차단·취소·완료합니다. `goal claim --session <id>`는 같은 작업을 이어받는 session(재개·압축·handoff·fork)에 미완료 goal의 소유권을 넘기며, 미완료 goal 중에 들어온 새 작업은 goal을 취소하지 않고 `goal replan`으로 합칩니다. 기본 tool-bound 정책은 `goal verify -- <argv>`가 명령을 직접 실행해 성공 증거를 기록합니다. `goal receipt`는 기존 선언 증거를 가져오는 호환 명령입니다. 모든 `goal` 하위 명령에서 `--root`는 선택이며, 생략하면 `HARNESS_REPO_ROOT`, 없으면 cwd에서 가장 가까운 `.git` 상위 디렉터리로 결정됩니다. `goal verify --kind "moduleAcceptance|surfaceIntegration" -- <argv>`는 한 번 실행으로 kind마다 receipt를 기록하며, evidence scope는 `task`와 `goal`뿐입니다. `goal finish [--watch "<path|path>"] [--timeout-ms N] -- <argv>`는 active task를 완료하고(필수 증거가 fresh여야 함) argv를 한 번 실행해 goal requiredEvidence의 모든 kind(기본 `finalReview`)를 goal scope로 기록한 뒤 goal을 완료합니다. 이 goal scope 증거가 모든 task receipt 이후에 기록되면 이전 task 검사를 다시 실행하지 않습니다. `goal stats`는 receipt 수, 재실행, stale receipt를 JSON으로 출력합니다. task는 `dependsOn`(생략 시 이전 task)과 `writeScope`를 선언하고, `goal ready`는 active/ready/blocked task id를 출력하며, write scope가 겹치지 않는 ready task는 같은 worktree에서 최대 4개까지 병렬로 active가 될 수 있습니다.
 - `cairn-memory`: 도메인 지식을 탐색하고 `MEMORY.md`를 갱신합니다.
 - `cairn-plan`: `docs/plan/` 아래에 decision-complete plan을 만듭니다.
 - `cairn-work`: 현재 `PLAN.md`의 다음 모듈 작업을 실행하고 두 검증 게이트를 확보합니다.

package/README.md

@@ -123,7 +123,7 @@ cairn toolcheck
 - `cairn uninstall`: verifies every non-config ownership-manifest entry against its installed digest first and refuses the whole uninstall, changing nothing, if any managed artifact was modified or removed. Otherwise it removes or restores the managed entries, prunes empty managed cache scaffolds, preserves unmanaged targets and their parent directories, and rolls back pre-commit failures.
 - `cairn toolcheck`: detects repository stacks and checks required LSP and verification tools; installation runs only for an approved supported installer.
 - `cairn cleanup --root <repo>`: reports legacy project-local `.cairn` residue without changing it; `--yes` migrates/reconciles valid active state into the user-home store, removes only known Cairn state/lock/tool residue, preserves unknown files, and prunes the directory only when empty.
-- `cairn goal ...`: starts, inspects, pauses, resumes, blocks, cancels, and completes a persisted repository goal. `goal claim --session <id>` hands an unfinished goal to the session that continues the same work (resume, compaction, handoff, fork); new work that arrives during an unfinished goal is folded in with `goal replan` instead of cancelling it. State lives under user-home `.cairn`, separated by repository and Git worktree; state without `worktreeId` and state copied from another worktree are stale and removed on the next hook/goal start. Successful completion or cancellation removes active state because completed evidence already lives in the plan document, while paused/blocked state remains resumable. The default tool-bound policy records successful evidence by executing `goal verify -- <argv>`. The legacy `goal receipt` command imports declared evidence only.
+- `cairn goal ...`: starts, inspects, pauses, resumes, blocks, cancels, and completes a persisted repository goal. `goal claim --session <id>` hands an unfinished goal to the session that continues the same work (resume, compaction, handoff, fork); new work that arrives during an unfinished goal is folded in with `goal replan` instead of cancelling it. State lives under user-home `.cairn`, separated by repository and Git worktree; state without `worktreeId` and state copied from another worktree are stale and removed on the next hook/goal start. Successful completion or cancellation removes active state because completed evidence already lives in the plan document, while paused/blocked state remains resumable. The default tool-bound policy records successful evidence by executing `goal verify -- <argv>`. The legacy `goal receipt` command imports declared evidence only. `--root` is optional for every `goal` subcommand (it resolves via `HARNESS_REPO_ROOT`, else the nearest ancestor containing `.git`). `goal verify --kind "moduleAcceptance|surfaceIntegration" -- <argv>` records one receipt per kind from one run; evidence scopes are `task` and `goal`. `goal finish [--watch "<path|path>"] [--timeout-ms N] -- <argv>` completes the active task (its evidence must be fresh), runs the argv once, records every goal requiredEvidence kind (default `finalReview`) at goal scope, and completes the goal; once that goal-scope evidence is recorded after every task receipt, earlier task checks are not rerun. `goal stats` prints JSON receipt counts, reruns, and stale receipts. Tasks declare `dependsOn` (omitted = previous task) and `writeScope`; `goal ready` prints active/ready/blocked task ids, and up to 4 ready tasks with disjoint write scopes can be active in parallel in the same worktree.
 - `cairn-memory`: explores domain knowledge and updates `MEMORY.md`.
 - `cairn-plan`: creates a decision-complete plan under `docs/plan/`.
 - `cairn-work`: executes the next module task in the current `PLAN.md` with two verification gates.

package/commands/cairn-plan.md

@@ -6,23 +6,17 @@ Prerequisite: resolve the installed Cairn runtime from the plugin or skill locat
 
 Goal: show an initial plan and goal before triage can be interrupted, then leave a decision-complete implementation plan before non-trivial implementation.
 
-Complexity is staged, not decided once. Record a provisional request checkpoint, re-evaluate it at the planning checkpoint after exploration, and require a code checkpoint after exact file/caller/test inspection immediately before the first edit. Before editing, either route may change when evidence supports it. 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 only promotes Light Path to Heavy Path: stop further edits, mark affected evidence stale, synchronize all three roadmaps, and repeat the code checkpoint.
+Paths: 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. Quick Path needs no `docs/plan` artifact and no goal when all hold: unambiguous requirements; about 3 files or fewer inside existing layers; no Heavy Path signal; no external-state mutation; one or two verification commands. Implement, run one focused check plus the project's normal check, and report; if any criterion fails, escalate to Light Path (plan + goal) before further edits. Otherwise use Light Path by default and Heavy Path only when a Heavy Path condition clearly applies.
 
-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.
+Complexity is staged: request checkpoint, planning checkpoint after exploration, and code checkpoint immediately before the first edit. Before editing, either route may change; after editing begins, only Light → Heavy promotion is allowed. Every change synchronizes the plan artifact, repository goal task roadmap through `goal replan`, native UI plan, and reasoning effort profile. Models always inherit; request Light `medium`, Heavy `high`, final verification/review `xhigh`.
 
 Procedure:
 
 1. Every agent reads project-root `MEMORY.md` when present and continues without repository memory when absent before repository exploration, tool selection, work, or delegation.
-2. Classify routine known-target Git/GitHub operations separately: status, fetch, checkout, branch, merge, push, and PR management stay plan/goal-free unless they require code edits, conflict resolution, destructive recovery, release/deploy, or design. For non-trivial implementation or continuation of planned work, write an initial `docs/plan/<topic>.md` and `PLAN.md` entry from the request and `MEMORY.md`. Make `triage-plan` the first active task and specify its investigation scope, path-decision criteria, plan-update condition, and anticipated implementation/verification stages. This initial plan must be decision-complete for triage and explicitly not implementation-ready.
-3. Before repository exploration, toolcheck, complexity triage, delegation, or a non-blocking user question for planned work, call Codex `update_plan` and then `create_goal` when those UI tools are available. Mirror the same roadmap into the repository Cairn goal. Record unavailable UI tools instead of silently implying UI synchronization. Skip goal activation for routine known-target Git/GitHub operations, consultation, explanation, and plan-only requests. If an unfinished repository goal already exists when a new implementation request, steer, or drift arrives, do not cancel it to start another. Fold the new work into it with `goal replan` (completed tasks and their evidence are preserved; resume a paused or blocked goal first), synchronize the plan artifact and native UI roadmap, and keep advancing until goal final review. Start a separate goal only when the user explicitly switches work. When a hook reports that another session owns the goal and this session continues that same work, take ownership with `goal claim --session <id>` using the ID shown by the hook.
-4. Read relevant `docs/memory/*.md` as directed by the initial triage task.
-5. Read the applicable installed model guidance.
-6. Run the installed runtime's `toolcheck --root <repoRoot>` and handle missing tools through the explicit approval policy.
-7. Explore the repository according to the initial triage task before asking the user.
-8. Understand the whole work and affected surfaces, classify it into executable tasks/sub-tasks, run Light/Heavy Path triage, and update the same repository plan and Codex `update_plan` roadmap to a decision-complete implementation plan.
-9. Use Light Path by default unless a Heavy Path condition clearly applies.
-10. Apply delegation and orchestration policy only after the route is recorded. If subagent tools are unavailable or disallowed by a higher-priority policy, the main agent takes over and records it.
-11. Do not begin implementation until the updated plan records selected path, checked Heavy Path signals, tool readiness, file scope, dry-run/check, module acceptance, surface integration, stable IDs, and fail-closed evidence.
-12. For Heavy Path, include an explicit automated test command and `Tests:` evidence line.
-13. Keep the repository goal and Codex UI plan statuses synchronized as triage and later tasks advance. Advance a UI step only after the matching repository Cairn task transition succeeds with its required bound evidence records.
-14. Use the OS locale for user-visible responses and generated or updated documentation, plans, and memory artifacts unless the user asks for another language.
+2. For non-trivial implementation or continuation of planned work, write an initial `docs/plan/<topic>.md` and `PLAN.md` entry with `triage-plan` as the first active task. This initial plan is decision-complete for triage and explicitly not implementation-ready.
+3. Before exploration, toolcheck, triage, or delegation, call Codex `update_plan` and then `create_goal` when available, and start the repository Cairn goal with the same roadmap. Copy the session-start hook's `Cairn CLI:` prefix literally into each command; never store it in a shell variable. `--root` may be omitted when the cwd is inside the repository. Fold new work into an unfinished goal with `goal replan` instead of cancelling it; when a hook reports another session owns the goal you continue, run `goal claim --session <id>`.
+4. Read relevant `docs/memory/*.md` and the installed model guidance, run `toolcheck --root <repoRoot>` (installation only with explicit approval), and explore before asking the user.
+5. Classify the whole work into executable tasks with `dependsOn`, `writeScope`, and handoff files, finalize triage, and update the same plan and `update_plan` roadmap to a decision-complete implementation plan: selected path, checked Heavy Path signals, tool readiness, file scope, dry-run/check, module acceptance, surface integration, stable IDs, and fail-closed evidence. Heavy Path adds an explicit automated test command and `Tests:` evidence line.
+6. Read the skill's reference files only when needed: `cairn://skills/cairn-plan/planning-rules.md` when finalizing, `cairn://skills/cairn-plan/delegation.md` before dispatching, `cairn://skills/cairn-plan/heavy-path.md` only on a Heavy signal or route change.
+7. The user-called/main agent orchestrates; implementation edits go to `worker` when subagent tools are available, otherwise the main agent takes over and records it. Advance a UI step only after the matching repository task transition succeeds with its required bound evidence.
+8. Use the OS locale for user-visible responses and generated or updated documentation, plans, and memory artifacts unless the user asks for another language.

package/commands/cairn-work.md

@@ -4,29 +4,21 @@ Use the `cairn-work` skill.
 
 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.
+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. Quick Path work has no plan or goal: implement, run one focused check plus the project's normal check, and report; escalate to Light Path (plan + goal) before further edits if any Quick Path criterion fails.
 
-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.
+Record the code checkpoint after exact file/caller/test inspection immediately before the first edit. After editing begins, a new Heavy Path signal promotes Light Path to Heavy Path: stop further edits, mark affected evidence stale, synchronize the plan artifact, `goal replan` roadmap, and native UI plan, and repeat the code checkpoint. Models always inherit; request Light `medium`, Heavy `high`, final verification/review `xhigh`.
 
 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 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.
-8. For Light Path, keep the main agent in the orchestrator role and use one bounded `worker` when allowed; for Heavy Path, follow the recorded staged review gates.
-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. 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.
-16. Update the plan, goal state, and `PLAN.md` only after evidence exists.
-17. Answer side questions briefly and resume unless explicitly asked to pause, stop, or switch.
-18. Use the OS locale for user-visible responses and generated or updated documentation, plans, and memory artifacts unless the user asks for another language.
+2. Read `PLAN.md`, the detailed plan, relevant memory notes, and the `cairn://` model guidance recorded in the plan through the installed runtime.
+3. Read the current task with `goal task status`; run `goal ready` and delegate independent ready tasks to parallel workers (same worktree, disjoint `writeScope`). Fold a new request into an unfinished goal with `goal replan` instead of cancelling it. Copy the session-start hook's `Cairn CLI:` prefix literally; never store it in a shell variable. `--root` may be omitted when the cwd is inside the repository.
+4. Confirm tool readiness (installation only with explicit approval) and the recorded route.
+5. Before implementation, spend reasoning on a focused executable test contract covering requirements, invariants, boundaries, and failure modes. Confirm the intended failure, then give the `worker` the contract, failing evidence, exact file ownership, and constraints and require the minimum change.
+6. Run module acceptance and surface integration through `goal verify -- ...`; `--kind "moduleAcceptance|surfaceIntegration"` records both from one run. Treat tool exit codes as authoritative and expand context only around failing tests. Heavy Path records explicit `Tests:` evidence.
+7. 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, and after a fix search for other implementations of the same rule or pattern.
+8. Inspect package lifecycle scripts 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 while the full check remains fresh.
+9. Relevant mutation makes the current task's evidence stale; rerun it before completing the task. Do not rerun earlier tasks' checks; finish with one goal-level check through `goal finish -- ...`. Missing, failed, skipped, stale, or placeholder evidence never completes work. `goal stats` measures receipt reruns.
+10. Read the skill's reference files only when needed: `cairn://skills/cairn-work/verification.md`, `cairn://skills/cairn-work/delegation.md`, `cairn://skills/cairn-work/recovery.md`, and `cairn://skills/cairn-work/heavy-path.md` (Heavy route only).
+11. Update the plan, goal state, and `PLAN.md` only after evidence exists. Answer side questions briefly and resume unless explicitly asked to pause, stop, or switch.
+12. Use the OS locale for user-visible responses and generated or updated documentation, plans, and memory artifacts unless the user asks for another language.

package/docs/model-guidance/README.md

@@ -28,12 +28,12 @@ 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 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 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. Quick Path changes (criteria in `cairn-plan`) need no plan or goal and escalate to Light Path before further edits when a criterion fails.
 - 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. 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.
+- 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. Do not rerun earlier tasks' checks after later edits; finish with one goal-level check through `goal finish -- <argv>`.
 - 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.
 - Limit each task to two verification passes by default. After two failed passes, record the blocker or split it into sub-tasks instead of continuing a repeated loop.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cairn-ai",
-  "version": "0.2.9",
+  "version": "0.3.0",
   "description": "Token-efficient agent harness with tool readiness for Codex, Claude Code, and Antigravity",
   "license": "MIT",
   "author": {

package/scripts/cairn-goal-cli.mjs

@@ -1,3 +1,5 @@
+import { resolveRepoRoot } from "./cairn-paths.mjs";
+
 export async function runGoalCli(args, {
   stdout = console.log,
   defaultGoalEvidence,
@@ -6,7 +8,8 @@ export async function runGoalCli(args, {
   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();
+  // Without --root, resolve the repository (HARNESS_REPO_ROOT or the nearest .git ancestor), not a subdirectory cwd.
+  const root = resolveRepoRoot({ explicitRoot: options.root ?? null });
   const emit = options.quiet ? () => {} : stdout;
   if (command === "start") {
     const tasks = parseTasks(options.tasks ?? positional.slice(0));
@@ -91,7 +94,7 @@ export async function runGoalCli(args, {
     const result = await operations.verifyAndRecord({
       root,
       taskId: options.task ?? positional[0],
-      kind: options.kind,
+      kind: splitValues(options.kind),
       scope: options.scope,
       watchPaths: splitValues(options.watch),
       argv: passthrough,
@@ -99,16 +102,41 @@ export async function runGoalCli(args, {
         ? 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,
+    const summaries = result.receipts.map((receipt) => ({
+      id: receipt.id,
+      scope: receipt.scope,
+      kind: receipt.kind,
+      exitCode: receipt.exitCode,
+      outputDigest: receipt.outputDigest,
+      workspaceFingerprint: receipt.workspaceFingerprint,
     }));
+    emit(JSON.stringify(summaries.length === 1 ? summaries[0] : summaries));
     return result.state;
   }
+  if (command === "finish") {
+    const state = await operations.finishGoal({
+      root,
+      watchPaths: splitValues(options.watch),
+      argv: passthrough,
+      timeoutMs: options["timeout-ms"] === undefined
+        ? 600_000
+        : positiveIntegerOption(options["timeout-ms"], "timeout-ms"),
+    });
+    emit(JSON.stringify({ id: state.goal.id, status: state.goal.status }));
+    return state;
+  }
+  if (command === "ready") {
+    const state = await operations.readGoalState({ root });
+    const ids = (status) => (state ? state.tasks.filter((task) => task.status === status).map((task) => task.id) : []);
+    const summary = { active: ids("active"), ready: operations.readyTasks(state).map((task) => task.id), blocked: ids("blocked") };
+    stdout(JSON.stringify(summary));
+    return summary;
+  }
+  if (command === "stats") {
+    const stats = operations.goalStats(await operations.readGoalState({ root }), root);
+    stdout(JSON.stringify(stats));
+    return stats;
+  }
   if (["pause", "resume", "block", "cancel", "complete"].includes(command)) {
     const state = await operations.transitionGoal({
       root,
@@ -118,7 +146,7 @@ export async function runGoalCli(args, {
     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]");
+  throw new Error("Usage: cairn-goal start|status|ready|stats|task|replan|claim|assign|receipt|verify|finish|pause|resume|block|cancel|complete [--root PATH]");
 }
 
 function parseArgs(args, command) {
@@ -182,6 +210,9 @@ function allowedOptions(command) {
     assign: ["task", "agent"],
     receipt: ["task", "kind", "scope", "command", "exitCode", "exit-code", "exit", "timestamp", "goalId", "goal-id", "plan"],
     verify: ["task", "kind", "scope", "watch", "timeout-ms"],
+    finish: ["watch", "timeout-ms"],
+    stats: [],
+    ready: [],
     pause: [],
     resume: [],
     block: ["reason"],

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

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