cairn-ai 0.1.10 → 0.2.0

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

@@ -2,17 +2,7 @@
 
 Goal: diagnose Cairn installation status.
 
-Run:
-
-```sh
-bunx cairn-ai@latest doctor
-```
-
-When running from local source:
-
-```sh
-node scripts/cairn.mjs doctor
-```
+Read the installed Cairn runtime locator at `{{CAIRN_RUNTIME_LOCATOR_JSON}}`. Invoke Node directly with the absolute `entrypoints.cli` value and `["doctor"]`; do not build a shell-interpolated command from the path.
 
 Checks:
 
@@ -20,3 +10,4 @@ Checks:
 - Claude Code commands and agents mirror files.
 - Antigravity skills and workflows mirror files.
 - Antigravity CLI skills and workflows mirror files.
+- Installed runtime locators and the referenced scripts, templates, and model guidance.

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

@@ -8,10 +8,6 @@ Run:
 bunx cairn-ai@latest install
 ```
 
-When running from local source:
-
-```sh
-node scripts/cairn.mjs install
-```
+Installation must run from the package/global source because the cached plugin is the destination. Do not copy Cairn runtime files into the target project and do not invoke install from a cached plugin locator.
 
 After installation, check status with the `cairn-doctor` workflow.

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

@@ -2,6 +2,8 @@
 
 Use the `cairn-memory` skill.
 
+Read the installed Cairn runtime locator at `{{CAIRN_RUNTIME_LOCATOR_JSON}}`. Cairn scripts and policy resources must be resolved through that locator, not from the target project.
+
 Goal: create or update repository memory without asking the user for discoverable facts.
 
 Procedure:
@@ -12,4 +14,4 @@ Procedure:
 4. Use `explorer` for read-only domain discovery and contradiction checks when available; use `worker` for exact references, command checks, and bounded evidence capture. 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.
 5. Write details to `docs/memory/<domain>.md`.
 6. Keep `MEMORY.md` as a short index.
-7. Use the OS locale for user-visible output unless the user asks for another language.
+7. Use the OS locale for user-visible responses and generated or updated documentation, plans, and memory artifacts unless the user asks for another language.

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

@@ -2,15 +2,17 @@
 
 Use the `cairn-plan` skill.
 
+Read the installed Cairn runtime locator at `{{CAIRN_RUNTIME_LOCATOR_JSON}}`. Resolve Cairn scripts, model guidance, templates, commands, and agents through that locator; only repository state such as `MEMORY.md`, `PLAN.md`, and `docs/plan/` belongs to the target project.
+
 Goal: leave a decision-complete plan for the current task in files 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 `docs/model-guidance/claude.md`; if Codex-family, read `docs/model-guidance/codex.md`.
-4. Run `node scripts/cairn.mjs toolcheck` when available.
-5. If required LSP/check tools are missing, run `node scripts/cairn.mjs toolcheck --install` or a repository-native install command before accepting a fallback.
+3. If the active or assigned model is Claude-family, read `claude.md` under the locator's `resources.modelGuidance`; if Codex-family, read `codex.md` there.
+4. Invoke Node directly with the locator's absolute `entrypoints.cli`, `toolcheck`, and `--root` for the target repository.
+5. If required LSP/check tools are missing, follow the installed toolcheck policy before any explicitly approved installation attempt.
 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.
@@ -20,4 +22,4 @@ Procedure:
 12. Write `docs/plan/<topic>.md`.
 13. Add the topic link and status to `PLAN.md`.
 14. Put the selected Light/Heavy Path, checked Heavy Path signals, tool readiness, module acceptance verification, and surface integration verification on every module task.
-15. Use the OS locale for user-visible output unless the user asks for another language.
+15. Use the OS locale for user-visible responses and generated or updated documentation, plans, and memory artifacts unless the user asks for another language.

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

@@ -2,6 +2,8 @@
 
 Use the `cairn-review` skill.
 
+Read the installed Cairn runtime locator at `{{CAIRN_RUNTIME_LOCATOR_JSON}}`. Cairn scripts and policy resources must be resolved through that locator, not from the target project.
+
 Goal: review completed work against plan, memory, policy, and evidence.
 
 Procedure:
@@ -11,4 +13,4 @@ Procedure:
 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`.
-6. Use the OS locale for user-visible output unless the user asks for another language.
+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/.agents/workflows/cairn-toolcheck.md

@@ -2,16 +2,8 @@
 
 Goal: detect repository stacks and check required LSP, typecheck, lint, dry-run, and verification tools.
 
-Run the local command first:
+Read the installed Cairn runtime locator at `{{CAIRN_RUNTIME_LOCATOR_JSON}}`. Invoke Node directly with the absolute `entrypoints.cli` value, `toolcheck`, and an explicit `--root` argument for the target repository; do not build a shell-interpolated command from the path.
 
-```sh
-node scripts/cairn.mjs toolcheck
-```
-
-If required tools are missing, attempt repository-native installation:
-
-```sh
-node scripts/cairn.mjs toolcheck --install
-```
+If required tools are missing, follow the installed command policy before any explicitly approved installation attempt.
 
 Record detected stacks, missing tools, install attempts, and blockers in the related `docs/plan/<topic>.md`.

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

@@ -2,16 +2,6 @@
 
 Goal: remove the Codex, Claude Code, and Antigravity entries installed by Cairn.
 
-Run:
-
-```sh
-bunx cairn-ai@latest uninstall
-```
-
-When running from local source:
-
-```sh
-node scripts/cairn.mjs uninstall
-```
+Read the installed Cairn runtime locator at `{{CAIRN_RUNTIME_LOCATOR_JSON}}`. Invoke Node directly with the absolute `entrypoints.cli` value and `["uninstall"]`; do not build a shell-interpolated command from the path.
 
 The source work folder and user-created `MEMORY.md`, `PLAN.md`, `docs/memory`, and `docs/plan` files are not deleted.

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

@@ -8,10 +8,6 @@ Run:
 bunx cairn-ai@latest upgrade
 ```
 
-When running from local source:
-
-```sh
-node scripts/cairn.mjs upgrade
-```
+Upgrade must run from the package/global source because the cached plugin is replaced. Do not invoke upgrade from a cached plugin locator.
 
 After upgrade, check status with the `cairn-doctor` workflow.

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

@@ -2,6 +2,8 @@
 
 Use the `cairn-work` skill.
 
+Read the installed Cairn runtime locator at `{{CAIRN_RUNTIME_LOCATOR_JSON}}`. Resolve Cairn scripts and policy resources through that locator; only work artifacts and state belong to the target project.
+
 Goal: execute the next incomplete module task in `PLAN.md` without bypassing the recorded complexity triage.
 
 Procedure:
@@ -10,7 +12,7 @@ Procedure:
 2. Read `PLAN.md`, the detailed plan, and relevant memory notes.
 3. Read the Codex or Claude model guidance recorded in the plan.
 4. Select one small module task.
-5. Confirm required tool readiness. If a required LSP/check tool is missing, run `node scripts/cairn.mjs toolcheck --install` or a repository-native install command before accepting a fallback.
+5. Confirm required tool readiness by invoking Node directly with the locator's absolute `entrypoints.cli`, `toolcheck`, and `--root` for the target repository. Follow the installed toolcheck policy before any explicitly approved installation attempt.
 6. Confirm the complexity triage and selected Light/Heavy Path recorded in the plan. If missing, update the plan before mutating files.
 7. 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.
@@ -19,4 +21,4 @@ Procedure:
 11. Re-run surface integration verification.
 12. Record tool readiness and verification evidence in `docs/plan/<topic>.md` and update `PLAN.md`.
 13. 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.
-14. Use the OS locale for user-visible output unless the user asks for another language.
+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/.claude/agents/explorer.md

@@ -4,4 +4,4 @@ Read-only discovery agent for codebase questions, impact analysis, pattern searc
 
 Before any task, read the project-root `MEMORY.md` for domain knowledge and repository policy.
 
-Refer to `agents/explorer.md`.
+Read the installed Cairn runtime locator at `{{CAIRN_RUNTIME_LOCATOR_JSON}}`. Resolve `resources.agents` from that JSON object and follow `explorer.md` in that directory. Do not resolve Cairn agent files from the target project.

package/.claude/agents/worker.md

@@ -4,4 +4,4 @@ Focused execution agent for search, small edits, command checks, and QA artifact
 
 Before any task, read the project-root `MEMORY.md` for domain knowledge and repository policy.
 
-Refer to `agents/worker.md`.
+Read the installed Cairn runtime locator at `{{CAIRN_RUNTIME_LOCATOR_JSON}}`. Resolve `resources.agents` from that JSON object and follow `worker.md` in that directory. Do not resolve Cairn agent files from the target project.

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

@@ -2,12 +2,4 @@
 
 Diagnose Cairn installation status.
 
-```sh
-node scripts/cairn.mjs doctor
-```
-
-Published package:
-
-```sh
-bunx cairn-ai@latest doctor
-```
+Read the installed Cairn runtime locator at `{{CAIRN_RUNTIME_LOCATOR_JSON}}`. Invoke Node directly with the absolute `entrypoints.cli` value and the argument array `["doctor"]`; do not build a shell-interpolated command from the path.

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

@@ -2,11 +2,7 @@
 
 Install Cairn into Codex, Claude Code, and Antigravity.
 
-```sh
-node scripts/cairn.mjs install
-```
-
-Published package:
+Installation must run from the package/global source because the cached installation is the destination. Do not copy runtime files into the target project and do not invoke install from the cached plugin locator.
 
 ```sh
 bunx cairn-ai@latest install

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

@@ -2,4 +2,4 @@
 
 Create or update `MEMORY.md` and `docs/memory/<domain>.md`.
 
-Follow plugin command `commands/cairn-memory.md`.
+Read the installed Cairn runtime locator at `{{CAIRN_RUNTIME_LOCATOR_JSON}}`. Resolve `resources.commands` from that JSON object and follow `cairn-memory.md` in that directory. Do not resolve Cairn command files from the target project.

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

@@ -2,4 +2,4 @@
 
 Start by reading the project-root `MEMORY.md`, then create or update `PLAN.md` and `docs/plan/<topic>.md` before non-trivial implementation, including Light/Heavy Path complexity triage and tool readiness.
 
-Follow plugin command `commands/cairn-plan.md`.
+Read the installed Cairn runtime locator at `{{CAIRN_RUNTIME_LOCATOR_JSON}}`. Resolve `resources.commands` from that JSON object and follow `cairn-plan.md` in that directory. Resolve model guidance and templates through the same locator. Do not resolve Cairn runtime resources from the target project.

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

@@ -2,4 +2,4 @@
 
 Review completed tasks against memory, plan, policy, tool readiness, and evidence.
 
-Follow plugin command `commands/cairn-review.md`.
+Read the installed Cairn runtime locator at `{{CAIRN_RUNTIME_LOCATOR_JSON}}`. Resolve `resources.commands` from that JSON object and follow `cairn-review.md` in that directory. Do not resolve Cairn command files from the target project.

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

@@ -2,9 +2,6 @@
 
 Detect repository stacks and check required LSP, typecheck, lint, dry-run, and verification tools.
 
-```sh
-node scripts/cairn.mjs toolcheck
-node scripts/cairn.mjs toolcheck --install
-```
+Read the installed Cairn runtime locator at `{{CAIRN_RUNTIME_LOCATOR_JSON}}`. Invoke Node directly with the absolute `entrypoints.cli` value, `toolcheck`, and an explicit `--root` pointing at the target repository; do not build a shell-interpolated command from the path.
 
-Use `--install` before accepting a missing required tool as unavailable.
+If required tools are missing, report the proposed install and obtain explicit user approval. Only then add `--install --yes` for a pinned/supported installer or use the approved repository-native command.

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

@@ -2,12 +2,4 @@
 
 Remove the Codex, Claude Code, and Antigravity entries installed by Cairn.
 
-```sh
-node scripts/cairn.mjs uninstall
-```
-
-Published package:
-
-```sh
-bunx cairn-ai@latest uninstall
-```
+Read the installed Cairn runtime locator at `{{CAIRN_RUNTIME_LOCATOR_JSON}}`. Invoke Node directly with the absolute `entrypoints.cli` value and the argument array `["uninstall"]`; do not build a shell-interpolated command from the path.

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

@@ -2,11 +2,7 @@
 
 Update the Cairn installation from the current source.
 
-```sh
-node scripts/cairn.mjs upgrade
-```
-
-Published package:
+Upgrade must run from the package/global source because the cached installation is replaced. Do not invoke upgrade from the cached plugin locator.
 
 ```sh
 bunx cairn-ai@latest upgrade

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

@@ -4,4 +4,4 @@ Start by reading the project-root `MEMORY.md`, then execute the next incomplete
 
 If the user asks a side question, status question, or narrow clarification while a task is still active, answer it briefly and then resume the previous active work unless the user explicitly asks to pause, stop, or switch tasks.
 
-Follow plugin command `commands/cairn-work.md`.
+Read the installed Cairn runtime locator at `{{CAIRN_RUNTIME_LOCATOR_JSON}}`. Resolve `resources.commands` from that JSON object and follow `cairn-work.md` in that directory. Do not resolve Cairn command files from the target project.

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "cairn",
-  "version": "0.1.10",
+  "version": "0.2.0",
   "description": "Token-efficient agent harness with tool readiness for Codex, Claude Code, and Antigravity.",
   "author": {
     "name": "WkNam"
@@ -24,6 +24,7 @@
       "Use Cairn to create MEMORY.md and PLAN.md for this repository.",
       "At the start of each task, every agent must read the project-root MEMORY.md for domain knowledge and repository policy before planning, implementation, review, or delegation.",
       "Run cairn-toolcheck before planning implementation work.",
+      "Resolve Cairn scripts, templates, commands, agents, and model guidance from the installed plugin runtime locator; never search for those runtime files in the target repository. Keep the target repository root separate and pass it explicitly to Cairn commands.",
       "Before non-trivial implementation, run cairn-plan for this task without asking me for discoverable facts.",
       "When planning, first understand the whole work, then classify it into small executable tasks; if a task needs further breakdown, split it into sub-tasks.",
       "The user-called/main agent is the orchestrator: plan, assign, verify, and record evidence; actual implementation edits must be delegated to worker subagents whenever subagent tools are available, on both Light Path and Heavy Path.",
@@ -33,6 +34,10 @@
       "If subagent tools are unavailable, the main agent takes over implementation directly and records that takeover in evidence; do not stop before local implementation solely because subagent tools are unavailable.",
       "Record Light Path or Heavy Path complexity triage in docs/plan/<topic>.md before mutating files.",
       "Run cairn-work from the current PLAN.md and pass dry-run/check, module acceptance, and surface integration gates.",
+      "For implementation requests, persist one active Cairn goal with stable task IDs. After a task passes its required bound receipts, advance immediately to the next task and continue until goal-level final review completes; active is never a completion state.",
+      "Missing, failed, skipped, stale, or placeholder evidence never completes a task. A worker may report only its assigned task; the main agent reviews the handoff and advances the goal.",
+      "If progress cannot continue, explicitly pause, block with a concrete reason, or cancel the Cairn goal instead of silently stopping. Do not repeatedly block a re-entered stop hook in the same turn.",
+      "Tool installation is an external-state change: report the proposal and obtain explicit user approval before using a pinned/supported installer.",
       "If I ask a side question, status question, or narrow clarification while a plan or task is still active, answer it briefly and then resume the previous active work unless I explicitly ask you to pause, stop, or switch tasks."
     ]
   }

package/README.de.md

@@ -33,8 +33,8 @@ Der gewählte path und die Begründung werden in `docs/plan/<topic>.md` festgeha
 `cairn toolcheck` untersucht das aktuelle repository auf JavaScript-, TypeScript-, Python-, PHP-, Java-, Kotlin-, Swift-, Go- und Rust-stacks und prüft die passenden LSP- und verification tools.
 
 ```sh
-cairn toolcheck
-cairn toolcheck --install
+cairn toolcheck --root .
+cairn toolcheck --install --yes --root .
 ```
 
 - `toolcheck` meldet detected stacks und missing tools.
@@ -57,7 +57,7 @@ Cairn wendet model-specific adjustment nur auf Claude-family und Codex-family mo
 - Claude-family: geeignet für long context, policy interpretation und plan/evidence review.
 - Codex-family: geeignet für small implementation tasks, explicit file edits, command-based verification und bounded `worker` tasks.
 
-Details stehen in `docs/model-guidance/README.md`, `docs/model-guidance/claude.md` und `docs/model-guidance/codex.md`.
+Details stehen im installierten Plugin unter `cairn://docs/model-guidance/README.md`, `cairn://docs/model-guidance/claude.md` und `cairn://docs/model-guidance/codex.md`.
 
 ## Repository Artifacts
 
@@ -65,7 +65,7 @@ Das harness erstellt und pflegt diese files im Ziel-repository root.
 
 - `MEMORY.md`: kurzer Index persistent domain knowledge.
 - `docs/memory/*.md`: detailliertes Wissen je domain.
-- `docs/model-guidance/*.md`: Claude- und Codex-model adjustment guidance.
+- `.cairn/state.json`: git-ignorierter Goal-, Task- und Receipt-Status für Wiederaufnahme und scoped stop gates.
 - `PLAN.md`: kurzer Index aktiver und abgeschlossener work topics.
 - `docs/plan/*.md`: detailed execution plans.
 
@@ -119,7 +119,7 @@ Codex-only hooks werden nicht nach Antigravity portiert. Stattdessen laufen dies
 
 ## Locale Policy
 
-Cairns reusable instructions sind für global use auf Englisch geschrieben. User-visible output folgt der konfigurierten OS locale, sofern der user nicht ausdrücklich eine andere Sprache verlangt. Die CLI lokalisiert common messages für `en`, `ko`, `ja`, `zh`, `es`, `fr`, `de` und `pt` und fällt bei unsupported locales auf English zurück. Codex hook `statusMessage` text bleibt static English, während hook command output English oder Korean ist.
+Cairns reusable instructions sind für global use auf Englisch geschrieben. User-visible output sowie erstellte oder aktualisierte documentation, plans und memory artifacts folgen der konfigurierten OS locale, sofern der user nicht ausdrücklich eine andere Sprache verlangt. Das umfasst Inhalte in `MEMORY.md`, `PLAN.md`, `docs/memory` und `docs/plan`. Die CLI lokalisiert common messages für `en`, `ko`, `ja`, `zh`, `es`, `fr`, `de` und `pt` und fällt bei unsupported locales auf English zurück. Codex hook `statusMessage` text bleibt static English, während hook command output English oder Korean ist.
 
 ## Delegation
 

package/README.es.md

@@ -33,8 +33,8 @@ El path seleccionado y su justificación se registran en `docs/plan/<topic>.md`
 `cairn toolcheck` inspecciona el repositorio actual para stacks JavaScript, TypeScript, Python, PHP, Java, Kotlin, Swift, Go y Rust, y luego revisa los LSP y verification tools correspondientes.
 
 ```sh
-cairn toolcheck
-cairn toolcheck --install
+cairn toolcheck --root .
+cairn toolcheck --install --yes --root .
 ```
 
 - `toolcheck` reporta detected stacks y missing tools.
@@ -57,7 +57,7 @@ Cairn solo aplica ajustes específicos de modelo a modelos Claude-family y Codex
 - Claude-family: útil para long context, policy interpretation y plan/evidence review.
 - Codex-family: útil para small implementation tasks, explicit file edits, command-based verification y bounded `worker` tasks.
 
-La guía detallada vive en `docs/model-guidance/README.md`, `docs/model-guidance/claude.md` y `docs/model-guidance/codex.md`.
+La guía detallada vive en el plugin instalado y se referencia como `cairn://docs/model-guidance/README.md`, `cairn://docs/model-guidance/claude.md` y `cairn://docs/model-guidance/codex.md`.
 
 ## Repository Artifacts
 
@@ -65,7 +65,7 @@ El harness crea y mantiene estos archivos en la raíz del repositorio objetivo.
 
 - `MEMORY.md`: índice corto de conocimiento persistente del dominio.
 - `docs/memory/*.md`: conocimiento detallado por dominio.
-- `docs/model-guidance/*.md`: guía de ajuste de modelos Claude y Codex.
+- `.cairn/state.json`: estado git-ignored de goal, task y receipt para reanudación y stop gates acotados.
 - `PLAN.md`: índice corto de temas activos y completados.
 - `docs/plan/*.md`: planes de ejecución detallados.
 
@@ -119,7 +119,7 @@ Los hooks exclusivos de Codex no se portan a Antigravity. En su lugar, los mismo
 
 ## Locale Policy
 
-Las instrucciones reutilizables de Cairn están escritas en inglés para uso global. El output visible para el usuario debe seguir el OS locale configurado, salvo que el usuario pida otro idioma explícitamente. La CLI localiza mensajes comunes para `en`, `ko`, `ja`, `zh`, `es`, `fr`, `de` y `pt`, y vuelve a English para locales no soportados. El texto `statusMessage` de Codex hooks permanece en inglés estático, mientras que hook command output es English o Korean.
+Las instrucciones reutilizables de Cairn están escritas en inglés para uso global. El output visible para el usuario y la documentation, los plans y los memory artifacts generados o actualizados deben seguir el OS locale configurado, salvo que el usuario pida otro idioma explícitamente. Esto incluye el contenido de `MEMORY.md`, `PLAN.md`, `docs/memory` y `docs/plan`. La CLI localiza mensajes comunes para `en`, `ko`, `ja`, `zh`, `es`, `fr`, `de` y `pt`, y vuelve a English para locales no soportados. El texto `statusMessage` de Codex hooks permanece en inglés estático, mientras que hook command output es English o Korean.
 
 ## Delegation
 

package/README.fr.md

@@ -33,8 +33,8 @@ Le path choisi et sa justification sont enregistrés dans `docs/plan/<topic>.md`
 `cairn toolcheck` inspecte le repository courant pour les stacks JavaScript, TypeScript, Python, PHP, Java, Kotlin, Swift, Go et Rust, puis vérifie les LSP et verification tools correspondants.
 
 ```sh
-cairn toolcheck
-cairn toolcheck --install
+cairn toolcheck --root .
+cairn toolcheck --install --yes --root .
 ```
 
 - `toolcheck` signale les detected stacks et missing tools.
@@ -57,7 +57,7 @@ Cairn applique des ajustements spécifiques uniquement aux modèles Claude-famil
 - Claude-family : utile pour long context, policy interpretation et plan/evidence review.
 - Codex-family : utile pour small implementation tasks, explicit file edits, command-based verification et bounded `worker` tasks.
 
-Les détails se trouvent dans `docs/model-guidance/README.md`, `docs/model-guidance/claude.md` et `docs/model-guidance/codex.md`.
+Les détails se trouvent dans le plugin installé sous `cairn://docs/model-guidance/README.md`, `cairn://docs/model-guidance/claude.md` et `cairn://docs/model-guidance/codex.md`.
 
 ## Repository Artifacts
 
@@ -65,7 +65,7 @@ Le harness crée et maintient ces fichiers à la racine du repository cible.
 
 - `MEMORY.md` : index court de persistent domain knowledge.
 - `docs/memory/*.md` : connaissances détaillées par domaine.
-- `docs/model-guidance/*.md` : guidance d'ajustement pour les modèles Claude et Codex.
+- `.cairn/state.json` : état git-ignored des goals, tasks et receipts pour la reprise et les stop gates ciblés.
 - `PLAN.md` : index court des sujets actifs et terminés.
 - `docs/plan/*.md` : detailed execution plans.
 
@@ -119,7 +119,7 @@ Les hooks propres à Codex ne sont pas portés vers Antigravity. À la place, le
 
 ## Locale Policy
 
-Les instructions réutilisables de Cairn sont écrites en anglais pour un usage global. La sortie visible par l'utilisateur doit suivre l'OS locale configurée, sauf si l'utilisateur demande explicitement une autre langue. La CLI localise les messages communs pour `en`, `ko`, `ja`, `zh`, `es`, `fr`, `de` et `pt`, puis revient à English pour les locales non prises en charge. Le texte `statusMessage` des Codex hooks reste en anglais statique, tandis que hook command output est English ou Korean.
+Les instructions réutilisables de Cairn sont écrites en anglais pour un usage global. La sortie visible par l'utilisateur ainsi que la documentation, les plans et les artifacts mémoire générés ou mis à jour doivent suivre l'OS locale configurée, sauf si l'utilisateur demande explicitement une autre langue. Cela inclut le contenu de `MEMORY.md`, `PLAN.md`, `docs/memory` et `docs/plan`. La CLI localise les messages communs pour `en`, `ko`, `ja`, `zh`, `es`, `fr`, `de` et `pt`, puis revient à English pour les locales non prises en charge. Le texte `statusMessage` des Codex hooks reste en anglais statique, tandis que hook command output est English ou Korean.
 
 ## Delegation
 

package/README.ja.md

@@ -33,8 +33,8 @@ Cairn は execution policy では LazyCodex と異なります。LazyCodex の r
 `cairn toolcheck` は現在の repository から JavaScript、TypeScript、Python、PHP、Java、Kotlin、Swift、Go、Rust stacks を検出し、対応する LSP と verification tools を確認します。
 
 ```sh
-cairn toolcheck
-cairn toolcheck --install
+cairn toolcheck --root .
+cairn toolcheck --install --yes --root .
 ```
 
 - `toolcheck` は detected stacks と missing tools を報告します。
@@ -57,7 +57,7 @@ Cairn は Claude-family と Codex-family models にのみ model-specific adjustm
 - Claude-family: long context、policy interpretation、plan/evidence review に有用です。
 - Codex-family: small implementation tasks、explicit file edits、command-based verification、bounded `worker` tasks に有用です。
 
-詳細は `docs/model-guidance/README.md`、`docs/model-guidance/claude.md`、`docs/model-guidance/codex.md` にあります。
+詳細はインストール済みプラグインの `cairn://docs/model-guidance/README.md`、`cairn://docs/model-guidance/claude.md`、`cairn://docs/model-guidance/codex.md` にあります。
 
 ## Repository Artifacts
 
@@ -65,7 +65,7 @@ harness は対象 repository root に次の files を作成して維持します
 
 - `MEMORY.md`: persistent domain knowledge の短い index。
 - `docs/memory/*.md`: domain ごとの詳細 knowledge。
-- `docs/model-guidance/*.md`: Claude と Codex model adjustment guidance。
+- `.cairn/state.json`: 再開と scoped stop gate のための git-ignored goal/task/receipt 状態。
 - `PLAN.md`: active/completed work topics の短い index。
 - `docs/plan/*.md`: detailed execution plans。
 
@@ -119,7 +119,7 @@ Codex-only hooks は Antigravity へ port されません。代わりに同じ p
 
 ## Locale Policy
 
-Cairn の reusable instructions は global use のため英語で書かれています。user-visible output は user が別の language を指定しない限り configured OS locale に従います。CLI は `en`、`ko`、`ja`、`zh`、`es`、`fr`、`de`、`pt` の common messages を localize し、unsupported locales は English に fallback します。Codex hook `statusMessage` text は static English のまま、hook command output は English または Korean です。
+Cairn の reusable instructions は global use のため英語で書かれています。user-visible output と生成または更新される documentation、plans、memory artifacts は、user が別の language を指定しない限り configured OS locale に従います。これには `MEMORY.md`、`PLAN.md`、`docs/memory`、`docs/plan` の内容が含まれます。CLI は `en`、`ko`、`ja`、`zh`、`es`、`fr`、`de`、`pt` の common messages を localize し、unsupported locales は English に fallback します。Codex hook `statusMessage` text は static English のまま、hook command output は English または Korean です。
 
 ## Delegation
 

package/README.ko.md

@@ -37,12 +37,14 @@ subagent 도구가 progress-reporting channel을 제공하면 subagent는 작업
 `cairn toolcheck`는 현재 저장소에서 JavaScript, TypeScript, Python, PHP, Java, Kotlin, Swift, Go, Rust 스택을 감지하고, 해당 LSP와 검증 도구를 확인합니다.
 
 ```sh
-cairn toolcheck
-cairn toolcheck --install
+cairn toolcheck --root .
+# 명시적 승인을 받은 경우에만:
+cairn toolcheck --install --yes --root .
 ```
 
 - `toolcheck`는 감지된 스택과 누락 도구를 보고합니다.
-- `toolcheck --install`은 package manager dev dependency, Composer dev dependency, `uv`, Java LSP bootstrap, `go install`, `rustup component add` 같은 가장 가까운 프로젝트 로컬 또는 저장소 네이티브 설치 경로를 시도합니다.
+- 기본 검사는 읽기 전용이고 timeout으로 제한되며, 저장소 로컬 wrapper를 단순 탐지를 위해 실행하지 않습니다.
+- `toolcheck --install`은 사용자의 명시적 승인과 `--yes`를 모두 요구합니다. 버전이 고정되지 않았거나 checksum이 없는 installer는 `latest`를 내려받는 대신 사용할 수 없는 것으로 보고합니다.
 - Cairn 계획은 감지된 스택, 필요한 도구, 설치 명령, blocker를 기록합니다.
 - LSP server가 없다는 사실만으로 정밀한 코드베이스 탐색을 건너뛸 수 없습니다. 설치 또는 동등한 symbol-aware fallback을 먼저 시도해야 합니다.
 
@@ -61,7 +63,7 @@ Cairn은 Claude-family와 Codex-family 모델에만 모델별 조정을 적용
 - Claude-family: 긴 컨텍스트, 정책 해석, 계획/증거 검토에 유용합니다.
 - Codex-family: 작은 구현 작업, 명시적 파일 편집, command 기반 검증, 제한된 `worker` 작업에 유용합니다.
 
-자세한 가이드는 `docs/model-guidance/README.md`, `docs/model-guidance/claude.md`, `docs/model-guidance/codex.md`에 있습니다.
+자세한 가이드는 설치된 플러그인에 있으며 `cairn://docs/model-guidance/README.md`, `cairn://docs/model-guidance/claude.md`, `cairn://docs/model-guidance/codex.md`로 참조합니다.
 
 ## Repository Artifacts
 
@@ -69,11 +71,11 @@ Cairn은 Claude-family와 Codex-family 모델에만 모델별 조정을 적용
 
 - `MEMORY.md`: 지속 도메인 지식의 짧은 색인.
 - `docs/memory/*.md`: 도메인별 상세 지식.
-- `docs/model-guidance/*.md`: Claude와 Codex 모델 조정 가이드.
 - `PLAN.md`: 활성/완료 작업 주제의 짧은 색인.
 - `docs/plan/*.md`: 상세 실행 계획.
+- `.cairn/state.json`: 중단 재개와 범위가 제한된 종료 게이트에 쓰는 git-ignored 버전드 goal/task/receipt 상태.
 
-루트 파일은 짧게 유지하고 상세 내용은 `docs/` 아래로 이동해, 에이전트가 필요한 컨텍스트만 읽도록 합니다.
+런타임 script, template, command, agent, model guidance는 설치된 플러그인 루트에 유지합니다. 각 표면의 locator가 같은 설치본을 가리키므로 대상 저장소에 Cairn 내부 파일을 복사하지 않습니다.
 
 ## Commands
 
@@ -103,12 +105,13 @@ cairn toolcheck
 - `cairn doctor`: Codex 설정, 설치, hook trust state, Claude Code mirror 파일, Antigravity mirror 파일을 진단합니다.
 - `cairn uninstall`: Cairn이 추가한 Codex 설정, cache, Claude Code mirror 파일, Antigravity mirror 파일을 제거합니다.
 - `cairn toolcheck`: 저장소 스택을 감지하고 필요한 LSP와 검증 도구를 확인하거나 설치합니다.
+- `cairn goal ...`: 저장소의 영속 goal을 시작·조회·일시정지·재개·차단·취소·완료합니다. task 완료에는 현재 goal/task/plan에 바인딩된 성공 receipt가 필요합니다.
 - `cairn-memory`: 도메인 지식을 탐색하고 `MEMORY.md`를 갱신합니다.
 - `cairn-plan`: `docs/plan/` 아래에 decision-complete plan을 만듭니다.
 - `cairn-work`: 현재 `PLAN.md`의 다음 모듈 작업을 실행하고 두 검증 게이트를 확보합니다.
 - `cairn-review`: 계획, memory, 증거를 기준으로 완료된 작업을 검토합니다.
 
-`install`과 `upgrade`는 `~/.codex/config.toml`을 수정하기 전에 `*.cairn-backup-*` 백업을 만듭니다. 소스 플러그인 manifest는 validator-friendly 상태를 유지하고, 설치된 cache copy에만 Codex hook 활성화를 위한 `hooks` field가 추가됩니다.
+`install`과 `upgrade`는 `~/.codex/config.toml`을 수정하기 전에 `*.cairn-backup-*` 백업을 만들고 각 표면의 runtime locator를 갱신합니다. 소스 플러그인 manifest는 validator-friendly 상태를 유지하고, 설치된 cache copy에만 Codex hook 활성화를 위한 `hooks` field가 추가됩니다. 현재 custom lifecycle은 유지하며, upgrade는 교체 대상인 cache copy가 아니라 게시/전역 package에서 실행해야 합니다.
 
 Codex는 `skills/`와 `commands/`를 사용합니다. Claude Code는 `.claude/` 아래의 mirror command와 agent definition을 사용합니다. Antigravity는 `.agents/workflows`와 global skills mirror를 사용합니다.
 
@@ -123,7 +126,7 @@ Codex 전용 hooks는 Antigravity로 포팅하지 않습니다. 대신 같은 pl
 
 ## Locale Policy
 
-Cairn의 재사용 지침은 전역 사용을 위해 영어로 작성됩니다. 사용자에게 보이는 출력은 사용자가 다른 언어를 명시하지 않는 한 설정된 OS locale을 따릅니다. CLI는 `en`, `ko`, `ja`, `zh`, `es`, `fr`, `de`, `pt`의 일반 메시지를 현지화하고, 지원하지 않는 locale은 영어로 fallback합니다. Codex hook `statusMessage` 텍스트는 정적 영어로 유지하고, hook command output은 영어 또는 한국어입니다.
+Cairn의 재사용 지침은 전역 사용을 위해 영어로 작성됩니다. 사용자에게 보이는 출력과 생성 또는 갱신되는 문서, 계획, 메모리 산출물은 사용자가 다른 언어를 명시하지 않는 한 설정된 OS locale을 따릅니다. 여기에는 `MEMORY.md`, `PLAN.md`, `docs/memory`, `docs/plan` 내용이 포함됩니다. CLI는 `en`, `ko`, `ja`, `zh`, `es`, `fr`, `de`, `pt`의 일반 메시지를 현지화하고, 지원하지 않는 locale은 영어로 fallback합니다. Codex hook `statusMessage` 텍스트는 정적 영어로 유지하고, hook command output은 영어 또는 한국어입니다.
 
 ## Delegation
 

package/README.md

@@ -45,12 +45,14 @@ When a delegated subagent finishes, it provides a final report before leaving. A
 `cairn toolcheck` inspects the current repository for JavaScript, TypeScript, Python, PHP, Java, Kotlin, Swift, Go, and Rust stacks, then checks the matching LSP and verification tools.
 
 ```sh
-cairn toolcheck
-cairn toolcheck --install
+cairn toolcheck --root .
+# After explicit approval only:
+cairn toolcheck --install --yes --root .
 ```
 
 - `toolcheck` reports detected stacks and missing tools.
-- `toolcheck --install` attempts the closest project-local or repository-native install path, such as package-manager dev dependencies, Composer dev dependencies, `uv`, Java LSP bootstrap, `go install`, or `rustup component add`.
+- 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`.
 - 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.
 
@@ -69,7 +71,7 @@ Cairn only applies model-specific adjustment to Claude-family and Codex-family m
 - Claude-family: useful for long context, policy interpretation, and plan/evidence review.
 - Codex-family: useful for small implementation tasks, explicit file edits, command-based verification, and bounded `worker` tasks.
 
-Detailed guidance lives in `docs/model-guidance/README.md`, `docs/model-guidance/claude.md`, and `docs/model-guidance/codex.md`.
+Detailed guidance lives in the installed plugin and is referenced as `cairn://docs/model-guidance/README.md`, `cairn://docs/model-guidance/claude.md`, and `cairn://docs/model-guidance/codex.md`.
 
 ## Repository Artifacts
 
@@ -77,11 +79,11 @@ The harness creates and maintains these files at the target repository root.
 
 - `MEMORY.md`: short index of persistent domain knowledge.
 - `docs/memory/*.md`: detailed knowledge by domain.
-- `docs/model-guidance/*.md`: Claude and Codex model adjustment guidance.
 - `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.
 
-Root files stay short and details move under `docs/`, so agents only read the context they need.
+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.
 
 ## Commands
 
@@ -111,12 +113,13 @@ cairn toolcheck
 - `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-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.
 
-Install and upgrade create `*.cairn-backup-*` backups before modifying `~/.codex/config.toml`. The source plugin manifest stays validator-friendly; only the installed cache copy gets a `hooks` field to activate Codex hooks.
+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.
 
 Codex uses `skills/` and `commands/`. Claude Code uses mirrored commands and agent definitions under `.claude/`. Antigravity uses `.agents/workflows` and global skills mirrors.
 
@@ -131,7 +134,7 @@ Codex-only hooks are not ported to Antigravity. Instead, the same planning, memo
 
 ## Locale Policy
 
-Cairn's reusable instructions are written in English for global use. User-visible output should follow the configured OS locale unless the user explicitly asks for another language. The CLI localizes common messages for `en`, `ko`, `ja`, `zh`, `es`, `fr`, `de`, and `pt`, and falls back to English for unsupported locales. Codex hook `statusMessage` text remains static English, while hook command output is English or Korean.
+Cairn's reusable instructions are written in English for global use. User-visible output and generated or updated documentation, plans, and memory artifacts should follow the configured OS locale unless the user explicitly asks for another language. This includes `MEMORY.md`, `PLAN.md`, `docs/memory`, and `docs/plan` content. The CLI localizes common messages for `en`, `ko`, `ja`, `zh`, `es`, `fr`, `de`, and `pt`, and falls back to English for unsupported locales. Codex hook `statusMessage` text remains static English, while hook command output is English or Korean.
 
 ## Delegation