cairn-ai 0.2.1 → 0.2.3

package/README.md

@@ -19,7 +19,7 @@ The core idea is to keep useful agent-harness behavior: hooks, persistent state,
 
 Before a task mutates external state, Cairn records and runs the closest available dry-run or check mode. Verification is bounded: each task gets two verification passes by default, then the agent records a blocker or splits it into sub-tasks instead of continuing an open-ended loop.
 
-Cairn also treats tool readiness as part of the work. LSP, typecheck, lint, dry-run, and verification tools are checked against the repository stack. If a required tool is missing, Cairn attempts project-local or repository-native installation before accepting a fallback.
+Cairn also treats tool readiness as part of the work. LSP, typecheck, lint, dry-run, and verification tools are checked against the repository stack. A missing tool is installed only after explicit approval and only when a pinned, supported installer exists; otherwise Cairn reports a blocker.
 
 ## LazyCodex Attribution
 
@@ -52,7 +52,7 @@ cairn toolcheck --install --yes --root .
 
 - `toolcheck` reports detected stacks and missing tools.
 - Default checks are read-only, bounded by a timeout, and do not execute repository-local wrappers merely to discover them.
-- `toolcheck --install` requires both `--yes` and explicit user approval. Unpinned or checksum-free installers are unavailable rather than silently downloading `latest`.
+- `toolcheck --install` requires both `--yes` and explicit user approval. Unpinned or checksum-free installers return the canonical `installer-unavailable` refusal rather than silently downloading `latest`.
 - Cairn plans record detected stack, required tools, install commands, and blockers.
 - A missing LSP server is not a valid reason to skip precise codebase exploration until installation or an equivalent symbol-aware fallback has been attempted.
 
@@ -81,7 +81,7 @@ The harness creates and maintains these files at the target repository root.
 - `docs/memory/*.md`: detailed knowledge by domain.
 - `PLAN.md`: short index of active and completed work topics.
 - `docs/plan/*.md`: detailed execution plans.
-- `.cairn/state.json`: git-ignored, versioned active goal/task/receipt state used for interruption recovery and scoped stop gates.
+- `.cairn/state.json`: git-ignored, versioned active goal/task/evidence-record state used for interruption recovery and scoped stop gates.
 
 Runtime scripts, templates, commands, agents, and model guidance stay in the installed plugin root. Runtime locator files let Codex, Claude Code, and Antigravity share that installed copy without copying Cairn internals into the target repository.
 
@@ -108,20 +108,22 @@ cairn uninstall
 cairn toolcheck
 ```
 
-- `cairn install`: installs the plugin into the Codex marketplace cache and configures Codex multi-agent settings, hook trust state, Claude Code mirror files, and Antigravity skills/workflows.
-- `cairn upgrade`: updates the installation, Codex multi-agent settings, hook trust state, Claude Code mirror files, and Antigravity skills/workflows from the current source.
-- `cairn doctor`: diagnoses Codex settings, installation, hook trust state, Claude Code mirror files, and Antigravity mirror files.
-- `cairn uninstall`: removes Cairn-added Codex settings, cache, Claude Code mirror files, and Antigravity mirror files.
-- `cairn toolcheck`: detects repository stacks and checks or installs required LSP and verification tools.
-- `cairn goal ...`: starts, inspects, pauses, resumes, blocks, cancels, and completes a persisted repository goal; task completion requires bound successful receipts.
+- `cairn install`: transactionally installs the custom marketplace source, versioned Codex runtime cache, Cairn-owned config sections, Claude Code mirrors, and current Antigravity IDE/CLI skill surfaces.
+- `cairn upgrade`: replaces only ownership-manifest entries whose installed digests still match, with staged validation and reverse-order rollback on failure.
+- `cairn doctor`: validates the ownership manifest, managed digests, effective Codex features, actual installed/enabled/version plugin state, and mirror/runtime locators without repairing them.
+- `cairn uninstall`: removes or restores only ownership-manifest entries that remain unmodified; modified or unmanaged targets are preserved as conflicts and failures roll back.
+- `cairn toolcheck`: detects repository stacks and checks required LSP and verification tools; installation runs only for an approved supported installer.
+- `cairn goal ...`: starts, inspects, pauses, resumes, blocks, cancels, and completes a persisted repository goal; the default tool-bound policy records successful evidence by executing `goal verify -- <argv>`. The legacy `goal receipt` command imports declared evidence only.
 - `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.
 - `cairn-review`: reviews completed tasks against plan, memory, and evidence.
 
-On every `UserPromptSubmit`, Cairn injects model-visible guidance that an implementation or continued-execution request authorizes goal creation even if the user never says “goal.” An active goal also injects its full ordered task roadmap, task statuses, and current task so the agent can answer a side question and return to the original work. The agent creates or attaches the goal after a decision-complete plan and before implementation, while consultation, explanation, and plan-only requests remain goal-free.
+On every `UserPromptSubmit`, Cairn injects model-visible guidance that an implementation or continued-execution request authorizes goal creation even if the user never says “goal.” The agent first writes an initial repository plan with triage as the active task, then—before exploration or triage—shows the same roadmap through Codex `update_plan` and `create_goal` when available and starts the repository Cairn goal. Triage updates both plans to a decision-complete implementation revision before implementation begins. An active goal keeps the full ordered roadmap, statuses, and current task in hook context so a side question returns to the original work. Consultation, explanation, and plan-only requests remain goal-free.
 
-Install and upgrade create `*.cairn-backup-*` backups before modifying `~/.codex/config.toml`. They also write runtime locators for every surface. The source plugin manifest stays validator-friendly; only the installed cache copy gets a `hooks` field to activate Codex hooks. The current custom lifecycle remains in use; lifecycle upgrade should run from the published/global package, not from the cached copy that it replaces.
+For token-efficient execution, Cairn puts reasoning into a focused executable test contract—requirements, invariants, boundaries, and failure modes—before implementation. Implementation receives the failing contract and bounded file scope, then makes the minimum passing change. Tool exit codes and machine summaries decide success; successful output stays concise and only failures expand context. Verification climbs from focused tests to one final full check. Before package verification, inspect lifecycle scripts and run normal `npm pack --dry-run` by default: content-producing or unknown scripts must never use `--ignore-scripts`; only absent or proven content-neutral scripts may use it while the full-check evidence remains fresh. Successful state mutations support `--quiet` so growing goal JSON does not consume the conversation budget.
+
+Install and upgrade keep the custom marketplace lifecycle; they do not invoke `codex plugin add`. Candidates are staged and validated before commit, every managed destination and digest is recorded in an ownership manifest, and committed phases roll back in reverse order on failure. An exact unmodified supported legacy installation can be adopted after release-integrity validation; modified or unknown artifacts are preserved and rejected. Cairn edits only its own TOML sections and never forces public feature or agent settings. The source plugin manifest stays validator-friendly; only the installed cache copy gets a `hooks` field. Lifecycle commands must run from the published/global package, not from the cached copy that they replace.
 
 Codex uses `skills/` and `commands/`. Claude Code uses mirrored commands and agent definitions under `.claude/`. Antigravity uses `.agents/workflows` and global skills mirrors.
 
@@ -129,8 +131,8 @@ Codex uses `skills/` and `commands/`. Claude Code uses mirrored commands and age
 
 Antigravity supports `SKILL.md`-based Agent Skills and Workflows invoked as `/workflow-name`. Cairn installs these paths for that surface.
 
-- Antigravity IDE: `~/.agents/skills/cairn-*`, `~/.agents/workflows/cairn-*.md`.
-- Antigravity CLI: `~/.gemini/antigravity-cli/skills/cairn-*`, `~/.gemini/antigravity-cli/workflows/cairn-*.md`.
+- Antigravity IDE: `~/.gemini/config/skills/cairn-*/SKILL.md`.
+- Antigravity CLI: flat `~/.gemini/antigravity-cli/skills/cairn-*.md` skill files.
 
 Codex-only hooks are not ported to Antigravity. Instead, the same planning, memory, complexity triage, and two-gate verification procedures run through Skills and Workflows. Set `ANTIGRAVITY_HOME` or `ANTIGRAVITY_CLI_HOME` to override paths.
 

package/README.pt.md

@@ -11,7 +11,7 @@ A ideia central e manter comportamentos uteis de agent harness: hooks, estado pe
 
 Antes que um task altere estado externo, Cairn registra e executa o dry-run ou check mode mais proximo disponivel. A verificacao e limitada: cada task recebe duas verification passes por padrao; depois, o agente registra um blocker ou divide o task em vez de continuar um loop aberto.
 
-Cairn tambem trata tool readiness como parte do trabalho. LSP, typecheck, lint, dry-run e verification tools sao verificados contra o stack do repositorio. Se uma ferramenta obrigatoria estiver ausente, Cairn tenta uma instalacao project-local ou repository-native antes de aceitar um fallback.
+Cairn tambem trata tool readiness como parte do trabalho. LSP, typecheck, lint, dry-run e verification tools sao verificados contra o stack do repositorio. A instalacao ocorre apenas com aprovacao explicita e um installer suportado e fixado; caso contrario, um blocker e informado.
 
 ## LazyCodex Attribution
 
@@ -38,7 +38,7 @@ cairn toolcheck --install --yes --root .
 ```
 
 - `toolcheck` informa detected stacks e missing tools.
-- `toolcheck --install` tenta o caminho de instalacao project-local ou repository-native mais proximo, como dev dependencies do package manager, dev dependencies do Composer, `uv`, Java LSP bootstrap, `go install` ou `rustup component add`.
+- `toolcheck --install` exige aprovacao explicita e `--yes`; um installer sem suporte retorna o resultado canonico `installer-unavailable` sem ser executado.
 - Os planos Cairn registram detected stack, required tools, install commands e blockers.
 - Um LSP server ausente nao e motivo valido para pular precise codebase exploration antes de tentar installation ou um fallback symbol-aware equivalente.
 
@@ -65,12 +65,14 @@ O harness cria e mantem estes arquivos na raiz do repositorio alvo.
 
 - `MEMORY.md`: indice curto de persistent domain knowledge.
 - `docs/memory/*.md`: conhecimento detalhado por dominio.
-- `.cairn/state.json`: estado git-ignored de goal, task e receipt para retomada e stop gates com escopo.
+- `.cairn/state.json`: estado git-ignored de goal, task e evidence record para retomada e stop gates com escopo.
 - `PLAN.md`: indice curto de active and completed work topics.
 - `docs/plan/*.md`: detailed execution plans.
 
 Arquivos raiz ficam curtos e os detalhes vao para `docs/`, para que agentes leiam apenas o contexto necessario.
 
+Para economizar tokens, crie primeiro um test contract com requisitos, invariantes, limites e modos de falha. Use o tool exit code de `goal verify -- <argv>` como autoridade, resuma o sucesso e expanda o contexto apenas em falhas. Inspecione o package lifecycle e execute normalmente `npm pack --dry-run`. Scripts content-producing ou desconhecidos nunca devem usar `--ignore-scripts`; use-o apenas quando os scripts estiverem ausentes ou comprovadamente content-neutral e a evidencia do full check continuar atual.
+
 ## Commands
 
 O pacote publicado pode ser executado com `bunx` ou comandos `cairn` instalados globalmente.
@@ -94,17 +96,17 @@ cairn uninstall
 cairn toolcheck
 ```
 
-- `cairn install`: instala o plugin no Codex marketplace cache e configura hook trust state, Claude Code mirror files e Antigravity skills/workflows.
-- `cairn upgrade`: atualiza installation, hook trust state, Claude Code mirror files e Antigravity skills/workflows a partir da source atual.
-- `cairn doctor`: diagnostica Codex settings, installation, hook trust state, Claude Code mirror files e Antigravity mirror files.
-- `cairn uninstall`: remove Codex settings, cache, Claude Code mirror files e Antigravity mirror files adicionados pelo Cairn.
-- `cairn toolcheck`: detecta repository stacks e verifica ou instala required LSP e verification tools.
+- `cairn install`: instala de forma transacional custom marketplace source, versioned runtime, secoes config do Cairn e mirrors atuais.
+- `cairn upgrade`: substitui apenas entradas intactas do ownership manifest apos staged validation e usa rollback em falhas.
+- `cairn doctor`: valida ownership digests, features efetivos do Codex, status real do plugin e runtime locators sem reparar.
+- `cairn uninstall`: remove apenas entradas gerenciadas intactas; alvos modified ou unmanaged sao preservados como conflict.
+- `cairn toolcheck`: detecta repository stacks e verifica required tools; apenas um installer suportado e aprovado e executado, caso contrario `installer-unavailable`.
 - `cairn-memory`: explora domain knowledge e atualiza `MEMORY.md`.
 - `cairn-plan`: cria um decision-complete plan em `docs/plan/`.
 - `cairn-work`: executa o proximo module task no `PLAN.md` atual com dois verification gates.
 - `cairn-review`: revisa completed tasks contra plan, memory e evidence.
 
-`install` e `upgrade` criam backups `*.cairn-backup-*` antes de modificar `~/.codex/config.toml`. O source plugin manifest permanece validator-friendly; apenas a installed cache copy recebe um campo `hooks` para ativar Codex hooks.
+O custom marketplace lifecycle separa source e versioned runtime. Staged validation precede cada commit, o ownership manifest vincula todos os managed digests e uma falha aciona reverse-order rollback. Artifacts modified ou unmanaged sao preserved e relatados como conflict. O Cairn altera apenas suas TOML sections e nao forca feature/agent settings publicos.
 
 Codex usa `skills/` e `commands/`. Claude Code usa comandos espelhados e agent definitions em `.claude/`. Antigravity usa `.agents/workflows` e global skills mirrors.
 
@@ -112,8 +114,8 @@ Codex usa `skills/` e `commands/`. Claude Code usa comandos espelhados e agent d
 
 Antigravity suporta Agent Skills e Workflows baseados em `SKILL.md` chamados como `/workflow-name`. Cairn instala estes paths para essa superficie.
 
-- Antigravity IDE: `~/.agents/skills/cairn-*`, `~/.agents/workflows/cairn-*.md`.
-- Antigravity CLI: `~/.gemini/antigravity-cli/skills/cairn-*`, `~/.gemini/antigravity-cli/workflows/cairn-*.md`.
+- Antigravity IDE: `~/.gemini/config/skills/cairn-*/SKILL.md`.
+- Antigravity CLI: arquivos skill planos em `~/.gemini/antigravity-cli/skills/cairn-*.md`.
 
 Codex-only hooks nao sao portados para Antigravity. Em vez disso, os mesmos procedimentos de planning, memory, complexity triage e two-gate verification rodam por Skills e Workflows. Defina `ANTIGRAVITY_HOME` ou `ANTIGRAVITY_CLI_HOME` para sobrescrever paths.
 

package/README.zh.md

@@ -11,7 +11,7 @@ Cairn 的核心思路是保留有用的 agent harness 行为：hooks、persisten
 
 在 task 修改外部状态之前，Cairn 会记录并运行最接近的 dry-run 或 check mode。verification 是有边界的：默认每个 task 有两次 verification pass，然后 agent 会记录 blocker 或拆分 task，而不是继续开放式循环。
 
-Cairn 也把 tool readiness 视为工作的一部分。它会根据 repository stack 检查 LSP、typecheck、lint、dry-run 和 verification tools。如果缺少必要工具，Cairn 会先尝试 project-local 或 repository-native installation，再接受 fallback。
+Cairn 也把 tool readiness 视为工作的一部分。它会根据 repository stack 检查 LSP、typecheck、lint、dry-run 和 verification tools。只有在获得明确批准且存在固定版本的受支持 installer 时才安装，否则报告 blocker。
 
 ## LazyCodex Attribution
 
@@ -38,7 +38,7 @@ cairn toolcheck --install --yes --root .
 ```
 
 - `toolcheck` 报告 detected stacks 和 missing tools。
-- `toolcheck --install` 尝试最接近的 project-local 或 repository-native install path，例如 package-manager dev dependencies、Composer dev dependencies、`uv`、Java LSP bootstrap、`go install` 或 `rustup component add`。
+- `toolcheck --install` 要求明确批准和 `--yes`；不受支持的 installer 不会执行，并返回 canonical `installer-unavailable`。
 - Cairn plans 会记录 detected stack、required tools、install commands 和 blockers。
 - 缺少 LSP server 不能作为跳过 precise codebase exploration 的理由，除非已尝试 installation 或等价的 symbol-aware fallback。
 
@@ -65,12 +65,14 @@ harness 会在目标 repository root 创建并维护这些文件。
 
 - `MEMORY.md`: persistent domain knowledge 的短索引。
 - `docs/memory/*.md`: 按 domain 记录的详细 knowledge。
-- `.cairn/state.json`: 用于中断恢复和 scoped stop gate 的 git-ignored goal/task/receipt 状态。
+- `.cairn/state.json`: 用于中断恢复和 scoped stop gate 的 git-ignored goal/task/evidence-record 状态。
 - `PLAN.md`: active 和 completed work topics 的短索引。
 - `docs/plan/*.md`: detailed execution plans。
 
 root files 保持简短，细节移到 `docs/` 下，让 agents 只读取当前任务需要的 context。
 
+为节省 token，先把需求、不变量、边界和失败模式写成 test contract。以 `goal verify -- <argv>` 的 tool exit code 为判定依据，成功时保持简短，只在失败时扩展 context。检查 package lifecycle，并默认运行正常的 `npm pack --dry-run`。content-producing 或未知 script 不得使用 `--ignore-scripts`；只有 script 不存在或已证明为 content-neutral，且 full-check evidence 仍然新鲜时才可使用。
+
 ## Commands
 
 发布后的 package 可以通过 `bunx` 或全局安装的 `cairn` commands 执行。
@@ -94,17 +96,17 @@ cairn uninstall
 cairn toolcheck
 ```
 
-- `cairn install`: 将 plugin 安装到 Codex marketplace cache，并配置 hook trust state、Claude Code mirror files 和 Antigravity skills/workflows。
-- `cairn upgrade`: 从当前 source 更新 installation、hook trust state、Claude Code mirror files 和 Antigravity skills/workflows。
-- `cairn doctor`: 诊断 Codex settings、installation、hook trust state、Claude Code mirror files 和 Antigravity mirror files。
-- `cairn uninstall`: 移除 Cairn 添加的 Codex settings、cache、Claude Code mirror files 和 Antigravity mirror files。
-- `cairn toolcheck`: 检测 repository stacks，并检查或安装 required LSP 和 verification tools。
+- `cairn install`: 以事务方式安装 custom marketplace source、versioned runtime、Cairn-owned config sections 和当前 host mirrors。
+- `cairn upgrade`: staged validation 后只替换 ownership manifest 中未修改的 entry，失败时 rollback。
+- `cairn doctor`: 只读验证 ownership digests、effective Codex features、真实 plugin status 和 runtime locators。
+- `cairn uninstall`: 只删除未修改的 managed entry；modified 或 unmanaged target 会 preserve 并报告 conflict。
+- `cairn toolcheck`: 检测 repository stacks 和 required tools；只执行已批准的 supported installer，否则返回 `installer-unavailable`。
 - `cairn-memory`: 探索 domain knowledge 并更新 `MEMORY.md`。
 - `cairn-plan`: 在 `docs/plan/` 下创建 decision-complete plan。
 - `cairn-work`: 执行当前 `PLAN.md` 中的下一个 module task，并收集两个 verification gates。
 - `cairn-review`: 根据 plan、memory 和 evidence review completed tasks。
 
-`install` 和 `upgrade` 在修改 `~/.codex/config.toml` 前会创建 `*.cairn-backup-*` backups。source plugin manifest 保持 validator-friendly；只有 installed cache copy 会添加启用 Codex hooks 的 `hooks` field。
+custom marketplace lifecycle 将 source 与 versioned runtime 分离。每次 commit 前执行 staged validation，ownership manifest 绑定全部 managed digests，失败时执行 reverse-order rollback。modified 或 unmanaged artifacts 会 preserve 并报告 conflict。Cairn 只修改自身 TOML sections，不强制 public feature/agent settings。
 
 Codex 使用 `skills/` 和 `commands/`。Claude Code 使用 `.claude/` 下的 mirrored commands 和 agent definitions。Antigravity 使用 `.agents/workflows` 和 global skills mirrors。
 
@@ -112,8 +114,8 @@ Codex 使用 `skills/` 和 `commands/`。Claude Code 使用 `.claude/` 下的 mi
 
 Antigravity 支持通过 `/workflow-name` 调用的 `SKILL.md` based Agent Skills and Workflows。Cairn 会为该 surface 安装这些 paths。
 
-- Antigravity IDE: `~/.agents/skills/cairn-*`, `~/.agents/workflows/cairn-*.md`.
-- Antigravity CLI: `~/.gemini/antigravity-cli/skills/cairn-*`, `~/.gemini/antigravity-cli/workflows/cairn-*.md`.
+- Antigravity IDE: `~/.gemini/config/skills/cairn-*/SKILL.md`。
+- Antigravity CLI: `~/.gemini/antigravity-cli/skills/cairn-*.md` 下的扁平 skill 文件。
 
 Codex-only hooks 不会移植到 Antigravity。相同的 planning、memory、complexity triage 和 two-gate verification procedures 会通过 Skills 和 Workflows 运行。设置 `ANTIGRAVITY_HOME` 或 `ANTIGRAVITY_CLI_HOME` 可以覆盖 paths。
 

package/commands/cairn-doctor.md

@@ -8,15 +8,17 @@ Run from the published or global package:
 bunx cairn-ai@latest doctor
 ```
 
+The doctor validates the custom marketplace installation and ownership manifest without repairing it. Diagnostics are read-only; rollback is performed only by lifecycle transaction recovery.
+
 Checks:
 
 - Source plugin manifest.
 - Codex cached installation.
 - Marketplace file.
 - Hook manifest link in the installed copy.
-- `features.plugins`, `features.plugin_hooks`, `features.multi_agent`.
-- `agents.max_depth`.
-- `cairn@cairn` plugin enabled.
+- ownership manifest presence and managed destination digests.
+- `cairn@cairn` installed/enabled/version from the actual Codex CLI.
+- effective Codex plugin/hook/multi-agent feature state (reported, never forced).
 - hook trust state.
 - Claude Code commands and agents mirror files.
 - Antigravity IDE/CLI skills and workflows mirror files.

package/commands/cairn-install.md

@@ -8,14 +8,15 @@ Run from the published or global package, not from the installed cache copy:
 bunx cairn-ai@latest install
 ```
 
-The current custom lifecycle remains in use. Do not invoke lifecycle install/upgrade from the cached plugin root because that copy is the replacement target.
+The current custom marketplace lifecycle remains in use; this is not a migration to `codex plugin add`. Do not invoke lifecycle install/upgrade from the cached plugin root because that copy is the replacement target.
 
 Actions:
 
-- Copy the Cairn installation into the Codex marketplace cache.
+- Stage and validate the Cairn installation, then transactionally commit the custom marketplace source and versioned runtime cache.
 - Add the `hooks/hooks.json` link to the installed manifest.
-- Register marketplace, plugin, and hook trust state in `~/.codex/config.toml`.
+- Register only Cairn-owned marketplace, plugin, and hook trust sections in `~/.codex/config.toml`; do not rewrite public feature or agent settings.
 - Install `cairn-*` commands and agents mirror files for Claude Code.
 - Install `cairn-*` skills and workflows mirror files for Antigravity IDE/CLI.
 - Write runtime locators so all mirrors resolve scripts, templates, and model guidance from the installed plugin root.
-- Create `*.cairn-backup-*` backups before changing settings.
+- Record every managed destination and digest in the ownership manifest under the custom marketplace, and rollback committed phases in reverse order on failure.
+- Adopt an exact, unmodified supported legacy install only after release-integrity validation; preserve and reject modified or unknown artifacts.

package/commands/cairn-plan.md

@@ -4,24 +4,21 @@ Use the `cairn-plan` skill.
 
 Prerequisite: resolve the installed Cairn runtime from the plugin or skill locator. If `cairn doctor` fails, restore it with the published/global lifecycle command. Never look for Cairn scripts, templates, or model guidance in the target repository.
 
-Goal: leave a decision-complete plan for the current task in files before non-trivial implementation.
+Goal: show an initial plan and goal before triage can be interrupted, then leave a decision-complete implementation plan before non-trivial implementation.
 
 Procedure:
 
 1. Every agent must read the project-root `MEMORY.md` for domain knowledge and repository policy before repository exploration, tool selection, work, or delegation.
-2. Read relevant `docs/memory/*.md`.
-3. If the active or assigned model is Claude-family, read `cairn://docs/model-guidance/claude.md`; if Codex-family, read `cairn://docs/model-guidance/codex.md`, resolving it through the installed runtime.
-4. Run the installed runtime's `toolcheck --root <repoRoot>`.
-5. If required LSP/check tools are missing, report the proposed install and obtain explicit user approval. Only then use `toolcheck --install --yes --root <repoRoot>` for pinned/supported installers or the approved repository-native command.
-6. Explore before asking the user.
-7. Understand the whole work and affected surfaces first, then classify it into small executable tasks. If a task is still too broad to verify cleanly, split it into sub-tasks.
-8. Run complexity triage before applying agent, plugin, or delegated workflow guidance, and record it before mutating files.
+2. For implementation or continued execution, 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, 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 consultation, explanation, and plan-only requests.
+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. 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. Write `docs/plan/<topic>.md`.
-13. Add the topic link and status to `PLAN.md`.
-14. Give the plan and every task stable IDs plus fail-closed task and goal evidence requirements. If implementation was requested, start or attach the Cairn goal after planning; do not activate a goal for plan-only requests.
-15. Put the selected Light/Heavy Path, checked Heavy Path signals, tool readiness, module acceptance verification, and surface integration verification on every module task.
-16. For Heavy Path, include an explicit automated test command and `Tests:` evidence line; Heavy Path completion must not rely on generic verification wording alone.
-17. Use the OS locale for user-visible responses and generated or updated documentation, plans, and memory artifacts unless the user asks for another language.
+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.

package/commands/cairn-review.md

@@ -12,5 +12,5 @@ Procedure:
 2. Check changed files, tool readiness evidence, and verification evidence.
 3. Delegate independent read-only review to `explorer` when it materially improves speed or quality; use `worker` only for scoped verification reruns or QA artifacts. When subagent tools are available, each agent may recursively delegate bounded sub-tasks to subagents. Tell every delegated agent and child subagent to read the project-root `MEMORY.md` before work, keep scope, and preserve others' edits.
 4. Report findings first, ordered by severity, with file and line references. If no issues are found, say so clearly and mention remaining test gaps or residual risk.
-5. Record review evidence in `docs/plan/<topic>.md` and as the goal-level final review receipt before completing the goal.
+5. Record review evidence in `docs/plan/<topic>.md` and as the goal-level final review evidence record before completing the goal.
 6. 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-uninstall.md

@@ -8,11 +8,13 @@ Run from the published or global package:
 bunx cairn-ai@latest uninstall
 ```
 
-Removed items:
+The custom marketplace ownership manifest is authoritative. Uninstall removes or restores only destinations whose current digest still matches the recorded installed digest; modified or unmanaged targets are preserved as conflicts. A failure rolls back the transaction.
+
+Managed items:
 
 - Cairn marketplace, plugin, and hook trust state blocks in `~/.codex/config.toml`.
 - `~/.codex/plugins/cache/cairn`.
 - Claude Code `cairn-*` commands and agents mirror files.
 - Antigravity IDE/CLI `cairn-*` skills and workflows mirror files.
 
-The source work folder is not deleted.
+The source work folder is not deleted. The custom marketplace root is removed last, after external mirrors and config have committed successfully.

package/commands/cairn-upgrade.md

@@ -8,13 +8,13 @@ Run from the published or global package, not from the installed cache copy:
 bunx cairn-ai@latest upgrade
 ```
 
-The current custom lifecycle remains in use. The cached plugin root is a replacement target and must not upgrade itself.
+The current custom marketplace lifecycle remains in use. The cached plugin root is a replacement target and must not upgrade itself.
 
 Actions:
 
-- Replace the Cairn installation in the Codex cache.
-- Recompute hook trust state and update settings.
-- Overwrite Claude Code mirror files with the latest content.
-- Overwrite Antigravity IDE/CLI skills and workflows mirror files with the latest content.
+- Replace only files tracked by the ownership manifest whose current digest still matches the installed digest.
+- Recompute Cairn-owned hook trust state without rewriting public feature or agent settings.
+- Replace owned Claude Code and Antigravity mirror files with the latest content.
 - Refresh runtime locators for every installed surface.
-- Create `*.cairn-backup-*` backups before changing settings.
+- Stage and validate all candidates before commit; rollback committed phases in reverse order on failure.
+- Preserve and report a conflict for modified, unmanaged, or invalid legacy artifacts.

package/commands/cairn-work.md

@@ -14,14 +14,15 @@ Procedure:
 4. Read Cairn goal status and select only its current task. If implementation was requested but no goal exists, create it from the decision-complete plan.
 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. 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.
-8. For Heavy Path, follow the plan's staged implementation and review gates without role-mapping shortcuts.
-9. Delegate actual implementation edits to `worker` with clear file ownership on both Light Path and Heavy Path 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.
-10. For Heavy Path, run the recorded automated test command and record explicit `Tests:` evidence before any completion claim.
-11. Re-run module acceptance verification.
-12. Re-run surface integration verification.
-13. Record successful verification as structured receipts bound to the goal/task/plan. Missing, failed, skipped, or placeholder receipts never complete a task.
-14. Complete the current task, let Cairn advance to the next one, and continue until every task and goal-level final review receipt passes. Workers return only their assigned task handoff and never select the next task.
-15. Record tool readiness and verification evidence in `docs/plan/<topic>.md`, update goal state, and update `PLAN.md` only after evidence exists.
-16. 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.
-17. Use the OS locale for user-visible responses and generated or updated documentation, plans, and memory artifacts unless the user asks for another language.
+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.
+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.

package/docs/model-guidance/README.md

@@ -25,8 +25,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 every implementation or continued-execution request as authorization to bind active work to a persisted Cairn goal and stable task IDs, even when the user does not mention a goal. Exclude consultation, explanation, and plan-only requests. Continue through tasks until goal-level final review completes, or record an explicit pause, blocker, or cancellation.
-- Treat missing, failed, skipped, stale, or placeholder evidence as failure. Task receipts must be bound to the current goal, task, and plan.
+- Treat every implementation or continued-execution request as authorization to bind active work to a persisted Cairn goal and stable task IDs, even when the user does not mention a goal. After MEMORY.md, first write an initial plan that makes triage the active task. Before exploration or triage, synchronize its roadmap to Codex `update_plan` and `create_goal` when available and to the repository Cairn goal. Update both plans after triage, and implement only from the decision-complete revision. Exclude consultation, explanation, and plan-only requests.
+- Treat missing, failed, skipped, stale, or placeholder evidence as failure. Task evidence records must be bound to the current goal, task, and plan.
+- Treat the repository Cairn state as the fail-closed transition authority. Advance the matching Codex UI plan step only after the evidence-gated repository task transition succeeds.
+- Spend reasoning on a focused executable test contract before implementation: requirements, invariants, boundaries, and failure modes. Give implementation only that contract, failing evidence, file scope, and constraints; require the minimum passing change.
+- Run verification through `goal verify -- ...`; its default timeout is 600,000 ms and its maximum is 3,600,000 ms. Treat tool exit codes and bounded machine summaries as authoritative. Record evidence only when the starting goal/task identity and pre/post watched fingerprint still match, and choose the watch set and command at the semantic boundary that proves the claim. Compress success output and expand context only for failing tests and related code.
+- Use a verification ladder: focused contract tests, one full check after the final change, then package dry-run while the full check remains fresh. Inspect package lifecycle scripts first and run normal `npm pack --dry-run` by default. Content-producing or unknown lifecycle scripts must never use `--ignore-scripts`; only absent or proven content-neutral scripts may use it.
 - Every implementation task must pass module acceptance verification and surface integration verification.
 - Before mutating external state, run the closest available dry-run, check, plan, diff, validate, or equivalent command.
 - 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/docs/model-guidance/codex.md

@@ -31,6 +31,8 @@ Codex-family models are strong at small implementation tasks, explicit tool use,
 
 ### Planning
 
+- Use `update_plan` to display the initial triage roadmap before repository exploration, then use `create_goal` when exposed so the Codex UI has an active goal before the turn can be interrupted.
+- Treat the initial plan as decision-complete for its `triage-plan` task, not as authorization to implement. After triage, update the same repository plan and `update_plan` roadmap to the decision-complete implementation revision.
 - On Light Path, write explicit task contracts when a plan artifact exists.
 - Record detected stack, required tools, install commands, and tool blockers.
 - Specify file scope and verification commands so implementation does not need to rediscover them.
@@ -39,6 +41,8 @@ Codex-family models are strong at small implementation tasks, explicit tool use,
 
 ### Implementation
 
+- Invest Codex reasoning in executable test design first, then hand the bounded failing contract to implementation and require the minimum passing patch.
+- Run verification through `goal verify -- ...`. Its default timeout is 600,000 ms (10 minutes), capped at 3,600,000 ms (1 hour). On success, retain exact argv, tool exit code, pass count, output digest, and watched-workspace fingerprint; commit evidence only when the starting goal/task identity and pre/post watched fingerprint match. Choose the watch set and command at the semantic boundary that proves the claim. Expand diagnostics only for the failing test and its related file/symbol scope; reject stale evidence after related changes.
 - If acting as the user-called/main agent, orchestrate the work and delegate actual implementation edits to `worker` whenever subagent tools are available, regardless of Light Path or Heavy Path.
 - If acting as the user-called/main agent, immediately relay received subagent status events to the user. If no mid-run reporting channel exists, relay observable events such as assignment, waiting, and final completion.
 - If acting as the user-called/main agent, close or release completed subagents after capturing their final report and evidence, then review the final report and evidence before marking the work complete.
@@ -46,6 +50,7 @@ Codex-family models are strong at small implementation tasks, explicit tool use,
 - Confirm required tools are available. Install or bootstrap missing required tools before implementation.
 - Run the recorded dry-run or check command before external-state mutation when applicable.
 - After changes, run both module acceptance verification and surface integration verification.
+- Inspect package lifecycle scripts before package verification. Run normal `npm pack --dry-run` by default; content-producing or unknown lifecycle scripts must never use `--ignore-scripts`, while absent or proven content-neutral scripts may use it only when the prior full check remains fresh.
 - If a gate fails, diagnose once, shrink the task or split it into sub-tasks, and rerun both gates. Stop after the second failed pass and record the blocker.
 - Return evidence in a form that can be recorded in `docs/plan/<topic>.md`.
 

package/hooks/hooks.json

@@ -32,7 +32,7 @@
             "type": "command",
             "command": "node \"${PLUGIN_ROOT}/scripts/cairn-state.mjs\" post-tool-use",
             "timeout": 10,
-            "statusMessage": "Cairn: reminding current goal receipt requirements"
+            "statusMessage": "Cairn: reminding current goal evidence requirements"
           }
         ]
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cairn-ai",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "Token-efficient agent harness with tool readiness for Codex, Claude Code, and Antigravity",
   "license": "MIT",
   "author": {
@@ -39,7 +39,7 @@
     "README.*.md"
   ],
   "scripts": {
-    "check": "node --check scripts/cairn.mjs && node --check scripts/cairn-paths.mjs && node --check scripts/cairn-goal.mjs && node --check scripts/cairn-state.mjs && node --check scripts/cairn-lifecycle.mjs && node --check scripts/cairn-toolcheck.mjs && node -e \"JSON.parse(require('node:fs').readFileSync('package.json','utf8')); JSON.parse(require('node:fs').readFileSync('.codex-plugin/plugin.json','utf8')); JSON.parse(require('node:fs').readFileSync('hooks/hooks.json','utf8'))\" && npm test",
+    "check": "node --check scripts/cairn.mjs && node --check scripts/cairn-paths.mjs && node --check scripts/cairn-safe-fs.mjs && node --check scripts/cairn-goal.mjs && node --check scripts/cairn-state.mjs && node --check scripts/cairn-lifecycle.mjs && node --check scripts/cairn-toolcheck.mjs && node -e \"JSON.parse(require('node:fs').readFileSync('package.json','utf8')); JSON.parse(require('node:fs').readFileSync('.codex-plugin/plugin.json','utf8')); JSON.parse(require('node:fs').readFileSync('hooks/hooks.json','utf8')); JSON.parse(require('node:fs').readFileSync('scripts/release-integrity-0.2.2.json','utf8'))\" && npm test",
     "test": "node --test",
     "prepack": "npm run check"
   },