cairn-ai 0.2.9 → 0.3.0

package/skills/cairn-work/SKILL.md

@@ -5,172 +5,67 @@ description: Use after cairn-plan to execute the next incomplete docs/plan modul
 
 # Cairn Work
 
-Use this to implement a plan created by `cairn-plan`. Do not use this as a shortcut around planning; if no plan exists for non-trivial implementation, run `cairn-plan` first.
+Implement a `cairn-plan` plan, never as a shortcut around planning: one module task at a time, advancing the goal until every task and the goal-level final review complete. Quick Path work (criteria in `cairn-plan`) has no plan or goal: implement, run one focused check plus the project's normal check, and report; if any Quick Path criterion fails, escalate to Light Path (create plan + goal) before further edits.
 
-## Purpose
-
-Execute only one module task at a time, but keep advancing the active goal after each task passes until every task and the goal-level final review are complete. Instead of a repeated red-green loop, prove each small task with two strong verification gates.
-
-Every work run reads project-root `MEMORY.md` when present before choosing or executing a task. If it is absent, continue without repository memory; never invoke another memory service or block solely because the file is missing. Delegated agents follow the same rule.
-
-The user-called/main agent is the orchestrator for work execution: it selects the task, assigns implementation, verifies results, and records evidence. Actual implementation edits belong to `worker` subagents whenever subagent tools are available, regardless of Light Path or Heavy Path.
-
-When the subagent tool provides a progress-reporting channel, subagents 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.
-
-Delegated subagents must provide a final report before leaving. After the orchestrator captures the final report and evidence, it must close or release the completed subagent, then review the final report and evidence before marking the work complete.
-
-If the user asks a side question, status question, or narrow clarification while the selected task is still active, use the active goal's ordered task roadmap to preserve position, answer briefly, and then resume the current task unless the user explicitly asks to pause, stop, or switch tasks.
+The user-called/main agent orchestrates (selects, assigns, verifies, records). Implementation edits go to `worker` whenever subagent tools are available; otherwise the main agent takes over and records it. Answer side questions briefly and resume the current task unless the user asks to pause, stop, or switch.
 
 ## Re-entry and Required References
 
-At the start and after compaction, restart, delegation, or handoff, restore context in this order: optional root `MEMORY.md` → `cairn-work` → the active plan → current-task references → model guidance recorded by the plan. Confirm that the plan task, persisted current task, and worker assignment agree before acting. Missing `MEMORY.md` is not an inconsistency. If state, skill, plan, assignment, or another required reference is missing, unreadable, or inconsistent, do not edit, delegate, record completion evidence, or complete work; report a blocker to the orchestrator. Do not introduce read receipts as proof of model attention: current state, readable references, and fresh tool-bound evidence are the authority. Delegation means the delegated agent restores on its own entry; the orchestrator does not re-read this chain after dispatching or collecting a subagent, and within one unbroken context it rereads only references that changed, which keeps the cached prompt prefix stable.
-
-When subagent tools are available, each agent may recursively delegate bounded sub-tasks to subagents. Every child subagent reads project-root `MEMORY.md` when present and continues when absent, keeps the assigned scope, and preserves others' edits.
+At the start and after compaction, restart, delegation, or handoff, restore context in this order: optional root `MEMORY.md` → `cairn-work` → the active plan → current-task references → model guidance recorded by the plan. Confirm that plan task, persisted current task, and assignment agree. Missing `MEMORY.md` is not an inconsistency. If state, plan, assignment, or another required reference is missing, unreadable, or inconsistent, do not edit, delegate, record completion evidence, or complete work; report a blocker. No read receipts: state and fresh tool-bound evidence are the authority. A delegated agent restores on its own entry; the orchestrator rereads only changed references, keeping the cached prefix stable.
 
 ## Runtime Location
 
-Resolve Cairn's read-only runtime from `references/cairn-runtime.json` next to this `SKILL.md`. Its `pluginRoot` contains Cairn's scripts and model guidance. In a source checkout where the locator does not exist, resolve the plugin root from this `SKILL.md` location (`../..`). Never search the target repository for Cairn runtime files or derive the plugin root from the current working directory. Resolve `cairn://...` plan resources through this runtime and pass the target repository separately with `--root <repoRoot>`. If the shared runtime or locator is missing, unreadable, or inconsistent, stop every dependent mirror and recover from the published/global package with `cairn doctor` followed by `cairn upgrade`; do not use another mirror as a repair source.
+Resolve the read-only runtime from `references/cairn-runtime.json` next to this `SKILL.md` (its `pluginRoot`; in a source checkout without it, this file's `../..`). Never search the target repository for Cairn files; resolve `cairn://...` IDs through `pluginRoot`. If the runtime or locator is missing, unreadable, or inconsistent, stop every dependent mirror and recover with published/global `cairn doctor` then `cairn upgrade`.
 
-Use the installed CLI for durable state. Important forms are:
+The session-start hook prints `Cairn CLI: node "<abs>/scripts/cairn.mjs" goal <command>`. Copy that prefix literally into each command; never store it in a shell variable (shell variables do not persist between tool calls). `--root` is optional for every `goal` subcommand: when omitted it resolves via `HARNESS_REPO_ROOT`, else the nearest `.git` ancestor of the cwd.
 
 ```sh
 node "<pluginRoot>/scripts/cairn.mjs" goal task status --root "<repoRoot>"
-node "<pluginRoot>/scripts/cairn.mjs" goal status --root "<repoRoot>"
-node "<pluginRoot>/scripts/cairn.mjs" goal claim --quiet --root "<repoRoot>" --session "<session-id-shown-by-hook>"
+node "<pluginRoot>/scripts/cairn.mjs" goal ready --root "<repoRoot>"
 node "<pluginRoot>/scripts/cairn.mjs" goal replan --quiet --root "<repoRoot>" --tasks '[{"id":"<task-id>","title":"<task-title>","requiredEvidence":["moduleAcceptance","surfaceIntegration"]}]'
 node "<pluginRoot>/scripts/cairn.mjs" goal assign --quiet --root "<repoRoot>" --task "<task-id>" --agent "<agent-id>"
-node "<pluginRoot>/scripts/cairn.mjs" goal verify --quiet --root "<repoRoot>" --task "<task-id>" --kind moduleAcceptance --watch "<path|path>" -- <tool> <arg> ...
-node "<pluginRoot>/scripts/cairn.mjs" goal verify --quiet --root "<repoRoot>" --task "<task-id>" --kind surfaceIntegration --watch "<path|path>" -- <tool> <arg> ...
+node "<pluginRoot>/scripts/cairn.mjs" goal verify --quiet --root "<repoRoot>" --task "<task-id>" --kind "moduleAcceptance|surfaceIntegration" --watch "<path|path>" -- <tool> <arg> ...
 node "<pluginRoot>/scripts/cairn.mjs" goal task --quiet --root "<repoRoot>" --task "<task-id>" --status completed
-node "<pluginRoot>/scripts/cairn.mjs" goal verify --quiet --root "<repoRoot>" --scope goal --kind finalReview --watch "<path|path>" -- <tool> <arg> ...
-node "<pluginRoot>/scripts/cairn.mjs" goal complete --quiet --root "<repoRoot>"
+node "<pluginRoot>/scripts/cairn.mjs" goal finish --quiet --root "<repoRoot>" --watch "<path|path>" -- <tool> <arg> ...
+node "<pluginRoot>/scripts/cairn.mjs" goal stats --root "<repoRoot>"
 ```
 
-`goal verify` executes the argv after `--` without a shell and records its exit code, bounded tool output, output digest, and watched-workspace fingerprint. The legacy `goal receipt` command imports declared evidence for compatibility; declared evidence does not satisfy a default tool-bound goal.
-
-Verification defaults to 600,000 ms (10 minutes), accepts a shorter `--timeout-ms`, and is capped at 3,600,000 ms (1 hour). The external command never holds the state lock. A receipt is committed only when the starting goal/task identity and the pre/post watched fingerprint still match. Choose the watch set and verification command at the semantic boundary that proves the claimed behavior. With no explicit watch, Git-ignored files are excluded; pass each ignored artifact required by the claim with `--watch <path>` or explicitly watch its containing directory.
-
-Use `goal pause`, `goal block --reason "<concrete blocker>"`, or `goal cancel` when that is the truthful state. A task can be blocked with `goal task --task "<task-id>" --status blocked --reason "<concrete blocker>"`.
-
-## Token-Efficient Test Contract
-
-Use the test contract first. Spend reasoning on requirements, invariants, boundaries, and failure modes before implementation. Turn them into focused executable tests, confirm that new tests fail for the intended reason, then make the minimum implementation that passes.
-
-Treat the tool exit code and bounded machine summary as authoritative. On success, retain only the command, exit code, and pass count needed for evidence. Expand diagnostics and repository context only around the failing test; do not reread unrelated files or replay successful output.
-
-Use this verification ladder:
+- `goal verify` runs the argv after `--` without a shell and binds exit code, output digest, and watched fingerprint. One run with `--kind "a|b"` records one receipt per kind. Evidence scopes are only `task` and `goal`.
+- `goal finish` completes the active task (its required evidence must already be fresh), fails if any other task is not completed, runs the argv once, records every goal requiredEvidence kind (default `finalReview`) at goal scope, and completes the goal. It replaces the long form `task --status completed` → `verify --scope goal` → `complete`.
+- Read full `goal status` only when receipts are needed. `goal stats` prints JSON receipt counts, reruns, and stale receipts.
+- Use `--quiet` on state mutations. Pause, block, cancel, and claim: `recovery.md`.
 
-1. Run the focused contract tests.
-2. Implement the minimum change and rerun only those tests while diagnosing.
-3. Run the full repository check once after the final change.
-4. Before package verification, inspect package lifecycle scripts such as `prepack`, `prepare`, and `prepublishOnly` and classify whether they produce package contents.
-5. Run normal `npm pack --dry-run` by default. Content-producing or unknown lifecycle scripts must never be skipped with `--ignore-scripts`; their generated contents are part of the package contract.
-6. Only when lifecycle scripts are absent or proven content-neutral, the full check is still fresh, and the dry-run is only checking the file list may package verification use `npm pack --dry-run --ignore-scripts`.
+## Reference Files
 
-## Verification Integrity
+Read a reference only when the selected path or situation requires it (Quick and Light Path never need `heavy-path.md`):
 
-- The implementer must not be able to change the judge. Never edit, weaken, skip, or delete existing tests, fixtures, snapshots, or recorded verification commands to make a gate pass. When a contract genuinely changes, record the reason in `docs/plan/<topic>.md` before that edit; review rejects any judge change without a recorded reason.
-- Prefer executable checks (test, lint, script, hook) for machine-checkable rules; keep prose only for rules that need judgment.
-
-## Defect Investigation
-
-- Reproduce a reported defect with repository tools before fixing it; do not wait for more detail when a local reproduction is possible.
-- For unclear or non-reproducible failures, test one hypothesis at a time and close it with a measurement before changing code. Never fix on speculation.
-- Answer feasibility questions with a bounded experiment or measurement instead of an unverified "not possible". Stop and ask only when the experiment would bypass a security policy or mutate external state without approval.
-- After fixing a defect, search the repository for other implementations of the same rule or pattern. Fix them within the assigned scope or record them as follow-up in the plan.
-
-Any relevant mutation after a gate makes that result stale evidence. Rerun the affected focused gate and, when integration could change, the full gate. Use `--quiet` for successful Cairn state mutations so full state JSON does not consume conversation tokens. `goal status` is read-only and always returns state, including when `--quiet` is supplied.
-
-## Reasoning Effort Routing
-
-- Models always inherit the host/user default; never configure or override them.
-- Light Path planning, implementation, and verification request `medium`.
-- Heavy Path planning, review, and implementation request `high`; final verification and review request `xhigh`.
-- Every module task records `Requested reasoning effort` and `Effective reasoning effort` in `docs/plan/<topic>.md`. Requested is Cairn's desired profile; Effective is what the dispatch result confirms.
-- Pass requested effort only when dispatching a new task/worker and the host exposes a reasoning-effort option or host-native equivalent. Omit model overrides. Effective `inherited` means no task-level override was confirmed, not proof of missing host capability. Describe capability only from the exposed interface or dispatch response, distinguish Cairn non-integration from host non-support, and leave model/global config unchanged.
-- On every route change, synchronize the plan artifact, repository goal task roadmap through `goal replan`, native UI plan, and reasoning effort profile before edits resume. Completed task profiles are preserved as audit history; incomplete task profiles are recalculated for the new path.
+- `cairn://skills/cairn-work/verification.md`: timeouts, watch sets, freshness, defect investigation, tool readiness, dry-run policy.
+- `cairn://skills/cairn-work/delegation.md`: subagent lifecycle, parallel tasks, builder prompt, reasoning effort.
+- `cairn://skills/cairn-work/heavy-path.md`: Heavy gates and route changes; read only on a Heavy route or signal.
+- `cairn://skills/cairn-work/recovery.md`: failed gates, blocked/paused goals, ownership conflicts.
 
 ## Procedure
 
-1. Read project-root `MEMORY.md` when present; continue without repository memory when absent.
-2. Read `PLAN.md`, the selected `docs/plan/<topic>.md`, and relevant memory notes.
-3. Read the `cairn://docs/model-guidance/*.md` inputs recorded in the plan through the installed runtime.
-4. Read the current task through `cairn goal task status --root "<repoRoot>"`; the hook capsule already carries the roadmap. Read full `cairn goal status` only when receipts or the complete roadmap are needed, because its output grows with every receipt. Select only the active goal's current task. If a new implementation request or steer arrives while a goal is unfinished, add the work through `goal replan` instead of cancelling the goal, then keep advancing to goal final review. If implementation was requested but no goal exists, create one from the decision-complete plan before editing.
-5. Confirm that required LSP, typecheck, lint, dry-run, and verification tools are available from the plan's tool readiness section.
-6. If a required tool is missing, do not install it implicitly. Obtain explicit user approval, then run the installed runtime's `toolcheck --install --yes --root "<repoRoot>"` only for pinned/supported installers or run the approved repository-native command. Otherwise record a blocker.
-7. Confirm the selected Light Path or Heavy Path in the plan. If the plan lacks complexity triage, stop and update the plan before mutating files.
-8. Confirm the request checkpoint and planning checkpoint, inspect the exact files, callers, and tests, then record the code checkpoint immediately before the first edit. Missing or pending checkpoints block mutation.
-9. Before the first edit, evidence may change Light Path to Heavy Path or Heavy Path to Light Path. On every route change, update the plan artifact first, replace the incomplete repository goal task roadmap with `goal replan`, update the native UI plan to the same stable task order, and synchronize assignments, reviews, and required evidence. Do not mutate until all three agree.
-10. After editing starts, only promote Light Path to Heavy Path. Stop further edits on a new Heavy Path signal, mark affected evidence stale, revise and synchronize the plan artifact, repository goal task roadmap, and native UI plan, run newly required Heavy Path review, and repeat the code checkpoint before resuming.
-11. For Light Path, keep the main agent in the orchestrator role and delegate implementation edits to one bounded `worker` whenever subagent tools are available; keep the verification gate.
-12. For Heavy Path, follow the full planning and review pipeline recorded in the plan. Run pre-implementation review before mutation and read-only review after evidence exists.
-13. Delegate implementation to `worker` with exact files, ownership, constraints, and model-specific adjustment rules on both Light Path and Heavy Path whenever subagent tools are available. Tell every delegated agent and child subagent to read the project-root `MEMORY.md` before work, keep scope, preserve others' edits, and report status when the subagent tool provides a progress-reporting channel. 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 final report and evidence, close or release the completed subagent, then review the final report and evidence before marking the work complete. Use `explorer` for parallel read-only discovery or verification when available and useful. Allow recursive delegation only for bounded sub-tasks when the current surface supports it. If subagent tools are unavailable, the main agent takes over implementation directly and records that takeover in evidence.
-14. Before mutating external state, run the task dry-run or check command when one is recorded. If none exists, record the absence and continue with the smallest reversible command available.
-15. Design the focused executable test contract before implementation. For behavior changes, run it and confirm the intended failure; for policy-only work, use the closest deterministic assertion or record why a failing test is unavailable.
-16. Give the implementation worker only the contract, failing evidence, exact file scope, and constraints; require the minimum implementation rather than renewed broad discovery.
-17. For Heavy Path, run the recorded automated test command and record explicit `Tests:` evidence before claiming completion.
-18. `worker` must return a structured handoff for only its assigned goal/task with changed files, tool readiness result, dry-run or check result when applicable, automated test result for Heavy Path, module acceptance command and result, surface integration command or QA artifact, blocker, and cleanup notes. A worker must not select the next task.
-19. Re-run both verification gates through `goal verify -- ...`. Treat tool exit codes as authoritative, keep successful output summarized, and expand context only for a failing test. Record each success as evidence bound to the current goal ID, task ID, plan, exact argv, and watched-workspace fingerprint.
-20. Apply the bounded loop policy when a gate fails. After two failed passes, transition the task or goal to `blocked` with a concrete blocker instead of continuing automatically.
-21. Mark a task complete only after every required evidence record passes. Let Cairn advance to the next pending task, then continue the goal without yielding a false completion.
-22. After all tasks complete, run and record goal-level final review evidence and explicitly complete the goal. Successful completion or cancellation removes the user-home active state because completed evidence already lives in the plan document; paused and blocked state remains resumable. `active` is not a completion state.
-23. Record evidence in the plan file and state before updating `PLAN.md`.
-24. 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.
-25. Write user-visible responses and generated or updated documentation, plans, and memory artifacts in the OS locale unless the user asks for another language.
-
-## Builder Prompt Format
-
-```text
-TASK: Implement task <task-id> for <topic>.
-EXPECTED OUTCOME: Minimal code or documentation change satisfying the task contract.
-REQUIRED TOOLS: Scoped file editing, tool readiness checks, existing test/build commands, surface QA commands.
-MUST DO: Read the project-root `MEMORY.md` before doing assigned work and follow its policy. Stay within the listed file scope and ownership. Assume you are not alone in the codebase; do not revert others' edits. Treat the user-called/main agent as the orchestrator; delegate actual implementation edits to `worker` 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, relay observable events such as assignment, waiting, and final completion. Require delegated subagents to provide a final report before leaving; after capturing final report and evidence, close or release the completed subagent, then review the final report and evidence before marking the work complete. If subagent tools are unavailable, the main agent takes over implementation directly and records that takeover in evidence. When subagent tools are available, recursively delegate only bounded sub-tasks and pass these same constraints to every child subagent. Obtain explicit user approval before installing missing tools. Run dry-run or check mode before external-state mutation when available. Provide module evidence, surface evidence, and a structured handoff scoped to the assigned goal/task. Never edit, weaken, skip, or delete existing tests, fixtures, or verification commands to pass a gate without a reason recorded in the plan. After a defect fix, search for other implementations of the same rule or pattern and report them. Use the OS locale for user-visible responses and generated or updated documentation, plans, and memory artifacts.
-MUST NOT DO: Ask the user. Skip LSP/typecheck/lint because a tool is missing without attempting installation. Refactor unrelated code. Continue an open-ended verification loop. Treat a side question as permission to abandon the active task. Delegate vague or unbounded work. Claim completion without evidence. Modify files outside the assigned ownership.
-CONTEXT: docs/plan/<topic>.md task, relevant docs/memory notes, applied model guidance, exact files, verification commands.
-```
-
-## Tool Readiness Policy
-
-- Run the repository tool readiness command recorded in the plan before implementation.
-- If no command is recorded, run the resolved installed runtime's `toolcheck --root "<repoRoot>"`.
-- Missing LSP, typecheck, lint, dry-run, or verification tools must be reported with an install proposal. Installation requires explicit user approval and a pinned/supported installer.
-- After installation, rerun the exact tool command and record evidence.
-- If installation fails, stop the task and record the blocker rather than silently falling back to less precise exploration.
-
-## Two Verification Gates
-
-- Module acceptance: targeted unit, typecheck, lint, parser, schema, or command that proves the module contract.
-- Surface integration: HTTP, browser, CLI, tmux, desktop, or parsed artifact evidence proving behavior through the real surface.
-- Heavy Path test gate: run an explicit automated test command and record it as `Tests:` evidence in the plan. This is required even when module acceptance uses a broader check command.
-
-## Dry-Run Policy
-
-Run the closest available dry-run or check mode before commands that mutate external state.
-
-- Migrations and database changes: `--pretend`, dry-run, schema diff, rollback feasibility check, or equivalent.
-- Package and release work: inspect lifecycle scripts, then run normal `npm pack --dry-run`, publish dry-run, build check, or equivalent. Use `--ignore-scripts` only for absent or proven content-neutral lifecycle scripts while prior full-check evidence remains fresh.
-- Infrastructure and deployment: plan, diff, validate, check, or equivalent.
-- Code generation and formatting: check mode before write mode when available.
-- If no dry-run mode exists, record that fact in `docs/plan/<topic>.md` before continuing.
+1. Read `MEMORY.md` when present, `PLAN.md`, the plan, relevant memory notes, and the `cairn://docs/model-guidance/*.md` inputs it records.
+2. Read the current task with `goal task status`, then run `goal ready`: activate (`goal task --task <id> --status active`) and delegate independent ready tasks to parallel workers in the same worktree with disjoint `writeScope` and `--watch` inside it (`delegation.md`); rerun `goal ready` after each completion. Fold new requests in with `goal replan`, never cancel; with no goal, create one from the plan.
+3. Confirm tool readiness, route, and the request and planning checkpoints; inspect exact files, callers, and tests and record the code checkpoint just before the first edit (pending blocks mutation).
+4. Use the test contract first: spend reasoning on requirements, invariants, boundaries, and failure modes, write focused tests, confirm the intended failure, then give the `worker` only the contract, failing evidence, file scope, and constraints; require the minimum implementation.
+5. Before mutating external state, run the recorded dry-run or check (or record its absence).
+6. Run both gates through `goal verify -- ...` (module acceptance, surface integration). Treat the tool exit code as authoritative; keep successes short and expand context only for the failing test.
+7. Complete the task only with fresh required evidence, then continue. For the last task, run one goal-level final check through `goal finish -- ...`.
+8. Record evidence in the plan and state before updating `PLAN.md`. Workers report only their assigned task.
 
-## Bounded Loop Policy
+## Evidence Rules
 
-- Run at most two verification passes per task by default.
-- If a gate fails, diagnose the cause once, shrink the task or split it into sub-tasks, then rerun both gates.
-- After two failed passes, stop implementation for the task and record the blocker in `docs/plan/<topic>.md`.
-- Do not imitate repeated red-green loops unless the plan explicitly records a risk-based reason.
+- Verification ladder: focused contract tests, then one full repository check after the final change, then package verification. 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 `--ignore-scripts` while the full check is fresh.
+- Any relevant mutation after a gate makes that result stale evidence; rerun the affected gate before completing the current task. Do not rerun earlier completed tasks' checks after later edits: one fresh goal-scope receipt for every goal requiredEvidence kind recorded after all task receipts supersedes their fingerprints (if goal requiredEvidence is empty, task freshness is still rechecked).
+- Never edit, weaken, skip, or delete existing tests, fixtures, snapshots, or recorded verification commands to make a gate pass; record a genuine contract change in the plan first. After a defect fix, search for other implementations of the same rule or pattern.
+- At most two verification passes per task; after two failures, record the blocker (`recovery.md`).
+- Reasoning effort: models always inherit. Request Light `medium`, Heavy `high`, final verification/review `xhigh`; record Requested and Effective reasoning effort per task. Route changes resync the reasoning effort profile: completed profiles are preserved, incomplete profiles are recalculated.
+- Missing, failed, skipped, stale, or placeholder evidence never completes work. Use the OS locale for output and artifacts.
 
 ## Completion Criteria
 
-- Both verification gates passed in the current turn.
-- Heavy Path work has explicit automated test evidence in the current plan.
-- The active goal advanced through every task and has goal-level final review evidence, or it is explicitly `paused`, `blocked`, or `cancelled` with a recorded reason.
-- Implementation edits were delegated to `worker` when subagent tools were available, or the main agent took over implementation directly and recorded that takeover in evidence when subagent tools were unavailable.
-- Required LSP/check/verification tools were available, installed, or recorded as blockers with attempted commands.
-- Dry-run or check evidence exists when the task could mutate external state, or the plan records why no dry-run exists.
-- The required Light Path or Heavy Path flow was followed.
-- The model guidance recorded in the plan was applied.
-- No existing test, fixture, or verification command was weakened without a recorded plan reason.
-- Defect fixes record the same-rule sweep result.
-- Evidence was recorded in `docs/plan/<topic>.md`.
-- `PLAN.md` status was updated only after evidence existed.
+- Both gates passed with fresh evidence (Heavy: `Tests:`); the goal finished through `goal finish` or is explicitly `paused`, `blocked`, or `cancelled` with a reason.
+- Delegation, tool readiness, dry-run, route, and model guidance followed the plan; no judge weakened; defect fixes record the same-rule sweep.
+- Evidence is in the plan before `PLAN.md` is updated.

package/skills/cairn-work/delegation.md

@@ -0,0 +1,43 @@
+# Cairn Work: Delegation and Reasoning Effort
+
+Reference for `cairn-work`. Read before dispatching a `worker` or `explorer`, or when recording reasoning effort. Quick Path work done directly by the main agent does not need this file.
+
+## Subagent Lifecycle
+
+- The user-called/main agent is the orchestrator: it selects the task, assigns implementation, verifies results, and records evidence. Actual implementation edits belong to `worker` subagents whenever subagent tools are available, regardless of Light Path or Heavy Path.
+- Delegate implementation with exact files, ownership, constraints, and model-specific adjustment rules. For Light Path use one bounded `worker`. Use `explorer` for parallel read-only discovery or verification when useful.
+- When the subagent tool provides a progress-reporting channel, subagents 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.
+- Delegated subagents must provide a final report before leaving. After the orchestrator captures the final report and evidence, it must 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. Every child subagent reads project-root `MEMORY.md` when present and continues when absent, keeps the assigned scope, and preserves others' edits.
+- If subagent tools are unavailable, the main agent takes over implementation directly and records that takeover in evidence.
+- `worker` returns a structured handoff for only its assigned goal/task: changed files, tool readiness result, dry-run or check result when applicable, automated test result for Heavy Path, module acceptance command and result, surface integration command or QA artifact, blocker, and cleanup notes. A worker must not select the next task.
+
+## Parallel Tasks
+
+- `goal ready` (read-only) prints `{"active":[...],"ready":[...],"blocked":[...]}` task ids. A ready task is pending with every dependency completed.
+- Only ready tasks can be activated: `goal task --task <id> --status active`. At most 4 tasks are active at once; active `writeScope`s must not overlap (segment-wise prefix, case-insensitive), and a task without `writeScope` is active only alone. start/replan/completion auto-activate only the first ready task when nothing is active; open further parallel tasks explicitly.
+- Assign one `worker` per active task (`goal assign`); assignment, evidence, and completion stay per task. Workers stay inside their `writeScope` and exchange data only through the plan's handoff files.
+- Parallel workers must run in the same Git worktree: goal state is stored per worktree, so another worktree sees no goal.
+- While other tasks are active, task-scope `goal verify` needs `--watch` paths inside that task's `writeScope`, so sibling edits cannot stale or fail its evidence; goal-scope verify needs `--watch` when 2 or more tasks are active.
+- Rerun `goal ready` after each completion. A blocked task keeps its dependents pending while unrelated branches continue; the goal becomes blocked only when no task is active or ready.
+- Main Stop gates on all active tasks; SubagentStop gates the stopping agent's own assigned active task. The hook adds one `Parallel active:` line only when 2 or more tasks are active.
+
+## Builder Prompt Format
+
+```text
+TASK: Implement task <task-id> for <topic>.
+EXPECTED OUTCOME: Minimal code or documentation change satisfying the task contract.
+REQUIRED TOOLS: Scoped file editing, tool readiness checks, existing test/build commands, surface QA commands.
+MUST DO: Read the project-root `MEMORY.md` before doing assigned work and follow its policy. Stay within the listed file scope and the task's `writeScope`. Assume you are not alone in the codebase; do not revert others' edits. Follow the subagent lifecycle rules (status reporting when a channel exists, final report before leaving, recursive delegation only for bounded sub-tasks with these same constraints). Obtain explicit user approval before installing missing tools. Run dry-run or check mode before external-state mutation when available. Provide module evidence, surface evidence, and a structured handoff scoped to the assigned goal/task. Never edit, weaken, skip, or delete existing tests, fixtures, or verification commands to pass a gate without a reason recorded in the plan. After a defect fix, search for other implementations of the same rule or pattern and report them. Copy the Cairn CLI prefix line literally; never store it in a shell variable. Use the OS locale for user-visible responses and generated or updated documentation, plans, and memory artifacts.
+MUST NOT DO: Ask the user. Skip LSP/typecheck/lint because a tool is missing without attempting installation. Refactor unrelated code. Continue an open-ended verification loop. Treat a side question as permission to abandon the active task. Delegate vague or unbounded work. Claim completion without evidence. Modify files outside the assigned ownership.
+CONTEXT: docs/plan/<topic>.md task, relevant docs/memory notes, applied model guidance, exact files, verification commands, Cairn CLI prefix line.
+```
+
+## Reasoning Effort Routing
+
+- Models always inherit the host/user default; never configure or override them.
+- Light Path planning, implementation, and verification request `medium`.
+- Heavy Path planning, review, and implementation request `high`; final verification and review request `xhigh`.
+- Every module task records `Requested reasoning effort` and `Effective reasoning effort` in `docs/plan/<topic>.md`. Requested is Cairn's desired profile; Effective is what the dispatch result confirms.
+- Pass requested effort only when dispatching a new task/worker and the host exposes a reasoning-effort option or host-native equivalent. Omit model overrides. Effective `inherited` means no task-level override was confirmed, not proof of missing host capability. Describe capability only from the exposed interface or dispatch response, distinguish Cairn non-integration from host non-support, and leave model/global config unchanged.
+- On every route change, synchronize the plan artifact, repository goal task roadmap through `goal replan`, native UI plan, and reasoning effort profile before edits resume. Completed task profiles are preserved as audit history; incomplete task profiles are recalculated for the new path.

package/skills/cairn-work/heavy-path.md

@@ -0,0 +1,16 @@
+# Cairn Work: Heavy Path and Route Changes
+
+Reference for `cairn-work`. Read only when the recorded route is Heavy Path, a new Heavy Path signal appears, or a route change is being considered. Quick Path and Light Path never need this file.
+
+## Heavy Path Execution
+
+- Follow the full planning and review pipeline recorded in the plan without role-mapping shortcuts: pre-implementation review before mutation, bounded `worker` implementation, then verification worker or read-only review after evidence exists.
+- Run the recorded automated test command and record explicit `Tests:` evidence in the plan before claiming completion. This is required even when module acceptance uses a broader check command.
+- Planning, review, and implementation request `high` reasoning effort; final verification and review request `xhigh`.
+
+## Route Changes During Work
+
+1. Confirm the request checkpoint and planning checkpoint, inspect the exact files, callers, and tests, then record the code checkpoint immediately before the first edit. Missing or pending checkpoints block mutation.
+2. Before the first edit, evidence may change Light Path to Heavy Path or Heavy Path to Light Path. On every route change, update the plan artifact first, replace the incomplete repository goal task roadmap with `goal replan`, update the native UI plan to the same stable task order, and synchronize assignments, reviews, required evidence, and the reasoning effort profile. Do not mutate until all agree.
+3. After editing starts, only promote Light Path to Heavy Path. On a new Heavy Path signal, stop further edits, mark affected evidence stale, revise and synchronize the plan artifact, repository goal task roadmap, and native UI plan, run newly required Heavy Path review, and repeat the code checkpoint before resuming.
+4. Quick Path work that hits any failed Quick Path criterion first escalates to Light Path (create plan + goal) before further edits; a Heavy signal then follows step 3.

package/skills/cairn-work/recovery.md

@@ -0,0 +1,29 @@
+# Cairn Work: Recovery
+
+Reference for `cairn-work`. Read only when a gate fails twice, a goal must be paused, blocked, or cancelled, another session owns the goal, or state and plan disagree.
+
+## Bounded Loop Policy
+
+- Run at most two verification passes per task by default.
+- If a gate fails, diagnose the cause once, shrink the task or split it into sub-tasks, then rerun both gates.
+- After two failed passes, stop implementation for the task, record the blocker in `docs/plan/<topic>.md`, and transition the task or goal to `blocked` with a concrete reason instead of continuing automatically.
+- Do not imitate repeated red-green loops unless the plan explicitly records a risk-based reason.
+
+## Truthful Goal States
+
+```sh
+node "<pluginRoot>/scripts/cairn.mjs" goal task --quiet --root "<repoRoot>" --task "<task-id>" --status blocked --reason "<concrete blocker>"
+node "<pluginRoot>/scripts/cairn.mjs" goal block --quiet --root "<repoRoot>" --reason "<concrete blocker>"
+node "<pluginRoot>/scripts/cairn.mjs" goal pause --quiet --root "<repoRoot>"
+node "<pluginRoot>/scripts/cairn.mjs" goal resume --quiet --root "<repoRoot>"
+node "<pluginRoot>/scripts/cairn.mjs" goal cancel --quiet --root "<repoRoot>"
+```
+
+- `active` is not a completion state. Successful completion or cancellation removes the user-home active state because completed evidence already lives in the plan document; paused and blocked state remains resumable.
+- Resume a paused or blocked goal before folding new work into it with `goal replan`. Start a separate goal only when the user explicitly switches work.
+
+## Ownership and State Conflicts
+
+- When a hook reports that another session owns the goal and this session continues that same work, take ownership with `goal claim --quiet --root "<repoRoot>" --session "<session-id-shown-by-hook>"`. Never guess or invent a session ID.
+- If the plan task, persisted current task, and worker assignment disagree, or a required reference is missing, unreadable, or inconsistent, do not edit, delegate, record completion evidence, or complete work; report a blocker to the orchestrator.
+- If the shared runtime or locator is missing, unreadable, or inconsistent, stop every dependent mirror and recover with published/global `cairn doctor` followed by `cairn upgrade`; do not use another mirror as a repair source.

package/skills/cairn-work/verification.md

@@ -0,0 +1,65 @@
+# Cairn Work: Verification Detail
+
+Reference for `cairn-work`. Read when a gate needs more than the evidence rules in `SKILL.md`: watch sets, timeouts, freshness, defect investigation, missing tools, or external-state dry-runs.
+
+## Goal Verify Semantics
+
+- `goal verify --task "<task-id>" --kind "<kind>[|<kind>]" [--watch "<path|path>"] [--timeout-ms N] -- <argv>` executes the argv without a shell and records exit code, bounded tool output, output digest, and watched-workspace fingerprint. With several kinds, one run records one receipt per kind.
+- Evidence scopes are only `task` and `goal`. Goal scope is normally recorded by `goal finish`; the long form is `goal task --status completed` → `goal verify --scope goal --kind finalReview -- <argv>` → `goal complete`.
+- Verification defaults to 600,000 ms (10 minutes), accepts a shorter `--timeout-ms`, and is capped at 3,600,000 ms (1 hour).
+- The external command never holds the state lock. A receipt is committed only when the starting goal/task identity and the pre/post watched fingerprint still match.
+- Choose the watch set and verification command at the semantic boundary that proves the claimed behavior. With no explicit watch, Git-ignored files are excluded; pass each ignored artifact required by the claim with `--watch <path>` or watch its containing directory.
+- The legacy `goal receipt` command imports declared evidence for compatibility; declared evidence does not satisfy a default tool-bound goal.
+
+## Freshness
+
+- A task's required evidence must be fresh when that task is completed. Any relevant mutation after a gate makes that result stale evidence: rerun the affected focused gate and, when integration could change, the full gate.
+- At goal completion, task evidence fingerprints are not rechecked when a fresh goal-scope receipt for every goal requiredEvidence kind was recorded after every task receipt. Do not rerun earlier tasks' checks after later edits; run one final goal-level check instead (`goal finish`).
+- If goal requiredEvidence is empty, task freshness is still rechecked at goal completion.
+- `goal stats` prints JSON with verify receipt counts (total, by kind), reruns (repeated scope+task+kind), and currently stale receipts. Use it to measure verification overhead.
+- The PostToolUse evidence reminder is emitted once per goal/task/session, not after every edit; its absence is not evidence.
+
+## Token-Efficient Test Contract
+
+1. Run the focused contract tests.
+2. Implement the minimum change and rerun only those tests while diagnosing.
+3. Run the full repository check once after the final change.
+4. Before package verification, inspect lifecycle scripts such as `prepack`, `prepare`, and `prepublishOnly` and classify whether they produce package contents.
+5. Run normal `npm pack --dry-run` by default. Content-producing or unknown lifecycle scripts must never be skipped with `--ignore-scripts`; their generated contents are part of the package contract.
+6. Only when lifecycle scripts are absent or proven content-neutral, the full check is still fresh, and the dry-run only checks the file list may package verification use `npm pack --dry-run --ignore-scripts`.
+
+On success retain only the command, exit code, and pass count needed for evidence. Do not reread unrelated files or replay successful output.
+
+## Verification Integrity
+
+- The implementer must not be able to change the judge. Never edit, weaken, skip, or delete existing tests, fixtures, snapshots, or recorded verification commands to make a gate pass. When a contract genuinely changes, record the reason in `docs/plan/<topic>.md` before that edit; review rejects any judge change without a recorded reason.
+- Prefer executable checks (test, lint, script, hook) for machine-checkable rules; keep prose only for rules that need judgment.
+
+## Defect Investigation
+
+- Reproduce a reported defect with repository tools before fixing it; do not wait for more detail when a local reproduction is possible.
+- For unclear or non-reproducible failures, test one hypothesis at a time and close it with a measurement before changing code. Never fix on speculation.
+- Answer feasibility questions with a bounded experiment or measurement instead of an unverified "not possible". Stop and ask only when the experiment would bypass a security policy or mutate external state without approval.
+- After fixing a defect, search the repository for other implementations of the same rule or pattern. Fix them within the assigned scope or record them as follow-up in the plan.
+
+## Two Verification Gates
+
+- Module acceptance: targeted unit, typecheck, lint, parser, schema, or command that proves the module contract.
+- Surface integration: HTTP, browser, CLI, tmux, desktop, or parsed artifact evidence proving behavior through the real surface.
+- Heavy Path test gate: an explicit automated test command recorded as `Tests:` evidence, even when module acceptance uses a broader check.
+
+## Tool Readiness Policy
+
+- Run the tool readiness command recorded in the plan before implementation; if none is recorded, run the runtime's `toolcheck --root "<repoRoot>"`.
+- Missing LSP, typecheck, lint, dry-run, or verification tools must be reported with an install proposal. Installation requires explicit user approval and a pinned/supported installer (`toolcheck --install --yes`) or an approved repository-native command.
+- After installation, rerun the exact tool command and record evidence. If installation fails, stop the task and record the blocker rather than silently falling back to less precise exploration.
+
+## Dry-Run Policy
+
+Run the closest available dry-run or check mode before commands that mutate external state.
+
+- Migrations and database changes: `--pretend`, dry-run, schema diff, rollback feasibility check, or equivalent.
+- Package and release work: inspect lifecycle scripts, then run normal `npm pack --dry-run`, publish dry-run, build check, or equivalent. Use `--ignore-scripts` only for absent or proven content-neutral lifecycle scripts while prior full-check evidence remains fresh.
+- Infrastructure and deployment: plan, diff, validate, check, or equivalent.
+- Code generation and formatting: check mode before write mode when available.
+- If no dry-run mode exists, record that fact in `docs/plan/<topic>.md` before continuing.

package/templates/work-plan.md

@@ -130,7 +130,9 @@ Describe the observable result.
 - Contract:
 - Sub-tasks, if needed:
 - Files:
-- Dependencies:
+- Depends on (task ids):
+- Write scope:
+- Handoff files:
 - Tool readiness requirement:
 - Dry-run or check command:
 - Module acceptance verification: