cairn-ai 0.2.0 → 0.2.2

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

@@ -4,22 +4,22 @@ 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.
+Goal: write an initial plan with triage as its active task before exploration, persist the goal/roadmap, then update the same plan to a decision-complete implementation revision after triage.
 
 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 `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.
+2. For implementation or continued execution, write the initial repository plan and `PLAN.md` entry from the request and `MEMORY.md`. Include a planned `triage-plan` task and anticipated execution/verification stages, then start or attach the repository Cairn goal before exploration.
+3. When the surface exposes native plan/goal UI tools, synchronize the same roadmap there before exploration; otherwise record that those tools are unavailable.
+4. Read relevant `docs/memory/*.md` and perform toolcheck, exploration, and Light/Heavy Path triage according to the initial task.
+5. Update the same plan to a decision-complete implementation revision before implementation.
+6. If the active or assigned model is Claude-family, read `claude.md` under the locator's `resources.modelGuidance`; if Codex-family, read `codex.md` there.
+7. Invoke Node directly with the locator's absolute `entrypoints.cli`, `toolcheck`, and `--root` for the target repository.
+8. If required LSP/check tools are missing, follow the installed toolcheck policy before any explicitly approved installation attempt.
 9. Use Light Path by default unless a Heavy Path condition clearly applies.
 10. Use `explorer` for independent read-only discovery, impact analysis, pattern search, and read-only verification when available.
 11. Treat the user-called/main agent as the orchestrator: it plans, assigns, verifies, relays received subagent status events or observable lifecycle events to the user, and records evidence. Use `worker` for actual implementation edits with clear file ownership whenever subagent tools are available, on both Light Path and Heavy Path. When the subagent tool provides a progress-reporting channel, require subagents to report status when starting work, when deciding or confirming direction, during periodic progress, and when finishing; immediately relay received status events to the user. If no mid-run reporting channel exists, relay observable events such as assignment, waiting, and final completion. Require delegated subagents to provide a final report before leaving; after capturing the final report and evidence, close or release the completed subagent, then review the final report and evidence before marking the work complete. When subagent tools are available, each agent may recursively delegate bounded sub-tasks to subagents. Tell every delegated agent and child subagent to read the project-root `MEMORY.md` before work, keep scope, and preserve others' edits. If subagent tools are unavailable, the main agent takes over implementation directly and records that takeover in evidence.
-12. 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.
+12. Record selected path, checked Heavy Path signals, tool readiness, module acceptance verification, and surface integration verification on every implementation task in the existing plan.
+13. Advance native UI steps only after the matching repository task transition succeeds with its required bound evidence records.
+14. Keep the existing `PLAN.md` entry and repository goal synchronized with the finalized plan status.
 15. Use the OS locale for user-visible responses and generated or updated documentation, plans, and memory artifacts unless the user asks for another language.

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

@@ -14,11 +14,13 @@ Procedure:
 4. Select one small module task.
 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.
-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. Re-run module acceptance verification.
-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 responses and generated or updated documentation, plans, and memory artifacts unless the user asks for another language.
+7. Spend reasoning on a focused executable test contract before implementation: requirements, invariants, boundaries, and failure modes. Confirm the intended failure, then require only the minimum implementation that passes.
+8. For Light Path, keep the user-called/main agent in the orchestrator role and delegate implementation edits to one bounded `worker` whenever subagent tools are available, then run focused verification.
+9. For Heavy Path, follow the plan's staged implementation and review gates without role-mapping shortcuts.
+10. Give implementation only the test contract, failing evidence, exact file ownership, and constraints. Delegate actual implementation edits to `worker` on both paths whenever subagent tools are available. When the subagent tool provides a progress-reporting channel, require subagents to report status to the orchestrator when starting work, when deciding or confirming direction, during periodic progress, and when finishing; immediately relay received status events to the user. If no mid-run reporting channel exists, relay observable events such as assignment, waiting, and final completion. Require delegated subagents to provide a final report before leaving; after capturing the final report and evidence, close or release the completed subagent, then review the final report and evidence before marking the work complete. When subagent tools are available, each agent may recursively delegate bounded sub-tasks to subagents. Tell every delegated agent and child subagent to read the project-root `MEMORY.md` before work, keep scope, and preserve others' edits. If subagent tools are unavailable, the main agent takes over implementation directly and records that takeover in evidence.
+11. Treat tool exit codes and bounded machine summaries as authoritative. Keep success concise; expand context only around failing tests.
+12. Run focused tests, then one final full repository check through `goal verify -- ...` so exact argv, tool exit code, bounded output, and watched-workspace fingerprint are recorded together. Any relevant later mutation makes affected evidence stale.
+13. Inspect package lifecycle scripts before package verification and run normal `npm pack --dry-run` by default. Content-producing or unknown lifecycle scripts must never use `--ignore-scripts`; only absent or proven content-neutral scripts may use it while the full-check evidence remains fresh.
+14. Record tool readiness and verification evidence in `docs/plan/<topic>.md` and update `PLAN.md`.
+15. If the user asks a side question, status question, or narrow clarification while this task is still active, answer it briefly and then resume the previous active work unless the user explicitly asks to pause, stop, or switch tasks.
+16. Use the OS locale for user-visible responses and generated or updated documentation, plans, and memory artifacts unless the user asks for another language.

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

@@ -1,5 +1,5 @@
 # cairn-plan
 
-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.
+Start by reading the project-root `MEMORY.md`, write an initial `PLAN.md` and `docs/plan/<topic>.md` with a planned triage task, persist the goal before exploration, then update the same plan after Light/Heavy Path triage and tool readiness checks before implementation.
 
 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-work.md

@@ -1,6 +1,6 @@
 # cairn-work
 
-Start by reading the project-root `MEMORY.md`, then execute the next incomplete module task only after the plan records Light/Heavy Path complexity triage, tool readiness, module acceptance verification, and surface integration verification.
+Start by reading the project-root `MEMORY.md`, then execute the next incomplete module task only after the plan records Light/Heavy Path complexity triage, tool readiness, module acceptance verification, and surface integration verification. Before implementation, spend reasoning on a focused executable test contract covering requirements, invariants, boundaries, and failure modes; confirm the intended failure and make only the minimum implementation that passes. Run verification through `goal verify -- ...`; treat tool exit codes and bounded machine summaries as authoritative, keep successes concise, and expand context only for failing tests. Inspect package lifecycle scripts and run normal `npm pack --dry-run` by default. Content-producing or unknown lifecycle scripts must never use `--ignore-scripts`; only absent or proven content-neutral scripts may use it while the prior full check remains fresh.
 
 If the user asks a side question, status question, or narrow clarification while a task is still active, answer it briefly and then resume the previous active work unless the user explicitly asks to pause, stop, or switch tasks.
 

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "cairn",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Token-efficient agent harness with tool readiness for Codex, Claude Code, and Antigravity.",
   "author": {
     "name": "WkNam"
@@ -22,23 +22,17 @@
     ],
     "defaultPrompt": [
       "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.",
-      "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.",
-      "When a delegated subagent finishes, it must provide its final report before leaving; after the orchestrator captures the final report and evidence, the orchestrator 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 must read MEMORY.md, keep scope, and preserve others' edits.",
-      "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."
+      "Every agent must read the project-root MEMORY.md before planning, implementation, review, or delegation. Keep MEMORY.md and PLAN.md as short indexes; open only current-task details.",
+      "Resolve Cairn runtime resources only through the installed locator, keep repoRoot separate, and run toolcheck before implementation planning. Tool installation requires explicit approval.",
+      "Run cairn-plan before non-trivial changes. Understand the whole work, split it into executable tasks/sub-tasks, record Light/Heavy Path triage, and finalize a decision-complete implementation plan before editing.",
+      "The user-called/main agent is the orchestrator. Delegate bounded implementation edits to worker subagents when allowed; otherwise the main agent implements and records takeover evidence.",
+      "With a progress-reporting channel, subagents report start, direction, periodic progress, and finish; relay those events immediately. Otherwise relay assignment, waiting, and final completion.",
+      "Delegated agents read MEMORY.md, preserve others' edits, return a final report, and may recursively delegate only bounded work. Capture evidence, close/release the agent, then review its report before completion.",
+      "Implementation/continue requests authorize an active Cairn goal even without the word goal. After MEMORY.md, write an initial plan with triage-plan active; before exploration call update_plan, then create_goal, then start/attach the repository goal. Triage finalizes the repository and UI plans before implementation. Keep roadmap/current-task recovery context; consultation, explanation, and plan-only requests stay goal-free.",
+      "Use a test contract first: spend reasoning on requirements, invariants, boundaries, and failure modes; design executable tests before implementation; make the minimum implementation that passes. Treat tool exit codes and machine summaries as authoritative, and expand context only for failing tests.",
+      "Missing, failed, skipped, stale, or placeholder evidence never completes work. Advance a UI step only after the matching repository task passes bound evidence; workers report only assigned tasks; active is not complete.",
+      "Use goal verify -- <argv>, quiet state mutations, and concise success summaries. Run focused tests and one final full check. Inspect package lifecycle scripts before packaging: run normal npm pack --dry-run by default; never skip content-producing or unknown scripts with --ignore-scripts, and use it only for absent or proven content-neutral scripts while evidence is fresh.",
+      "If blocked, pause/block/cancel explicitly. Answer side questions briefly, then resume the current task unless asked to pause, stop, or switch."
     ]
   }
 }

package/README.de.md

@@ -65,12 +65,14 @@ 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.
-- `.cairn/state.json`: git-ignorierter Goal-, Task- und Receipt-Status für Wiederaufnahme und scoped stop gates.
+- `.cairn/state.json`: git-ignorierter Goal-, Task- und Evidence-Record-Status für Wiederaufnahme und scoped stop gates.
 - `PLAN.md`: kurzer Index aktiver und abgeschlossener work topics.
 - `docs/plan/*.md`: detailed execution plans.
 
 Root files bleiben kurz, Details wandern unter `docs/`, damit agents nur den benötigten context lesen.
 
+Für geringe Tokenkosten entsteht zuerst ein test contract aus Anforderungen, Invarianten, Grenzen und Fehlermodi. Der tool exit code von `goal verify -- <argv>` ist maßgeblich; Erfolge bleiben kurz, nur Fehler erweitern den Kontext. Package lifecycle scripts werden geprüft; standardmäßig läuft ein normales `npm pack --dry-run`. Content-producing oder unbekannte scripts dürfen `--ignore-scripts` nie verwenden; es ist nur bei fehlenden oder nachweislich content-neutral scripts und frischer full-check evidence erlaubt.
+
 ## Commands
 
 Das veröffentlichte package kann mit `bunx` oder global installierten `cairn` commands ausgeführt werden.

package/README.es.md

@@ -65,12 +65,14 @@ 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.
-- `.cairn/state.json`: estado git-ignored de goal, task y receipt para reanudación y stop gates acotados.
+- `.cairn/state.json`: estado git-ignored de goal, task y evidence record para reanudación y stop gates acotados.
 - `PLAN.md`: índice corto de temas activos y completados.
 - `docs/plan/*.md`: planes de ejecución detallados.
 
 Los archivos raíz se mantienen cortos y los detalles pasan a `docs/`, para que los agentes lean solo el contexto que necesitan.
 
+Para ahorrar tokens, define primero un test contract con requisitos, invariantes, límites y modos de fallo. Usa el tool exit code de `goal verify -- <argv>` como autoridad, resume el éxito y amplía el contexto solo al fallar. Inspecciona el package lifecycle y ejecuta normalmente `npm pack --dry-run`. Los scripts content-producing o desconocidos nunca deben usar `--ignore-scripts`; úsalo solo si no hay scripts o son content-neutral demostrados y la evidencia del full check sigue vigente.
+
 ## Commands
 
 El paquete publicado puede ejecutarse con `bunx` o con comandos `cairn` instalados globalmente.

package/README.fr.md

@@ -65,12 +65,14 @@ 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.
-- `.cairn/state.json` : état git-ignored des goals, tasks et receipts pour la reprise et les stop gates ciblés.
+- `.cairn/state.json` : état git-ignored des goals, tasks et evidence records 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.
 
 Les fichiers racine restent courts et les détails vont sous `docs/`, afin que les agents ne lisent que le contexte nécessaire.
 
+Pour économiser les tokens, définissez d'abord un test contract couvrant exigences, invariants, limites et modes d'échec. Prenez le tool exit code de `goal verify -- <argv>` comme autorité, résumez les succès et n'élargissez le contexte qu'en cas d'échec. Inspectez le package lifecycle et exécutez normalement `npm pack --dry-run`. Les scripts content-producing ou inconnus ne doivent jamais utiliser `--ignore-scripts`; utilisez-le seulement si les scripts sont absents ou prouvés content-neutral et si la preuve du full check reste valide.
+
 ## Commands
 
 Le package publié peut être exécuté avec `bunx` ou avec des commandes `cairn` installées globalement.

package/README.ja.md

@@ -65,12 +65,14 @@ harness は対象 repository root に次の files を作成して維持します
 
 - `MEMORY.md`: persistent domain knowledge の短い index。
 - `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 の短い index。
 - `docs/plan/*.md`: detailed execution plans。
 
 root files は短く保ち、詳細は `docs/` に移すことで、agents が必要な context だけを読めるようにします。
 
+トークン効率のため、実装前に要件・不変条件・境界・失敗モードを 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
 
 published package は `bunx` または global install された `cairn` command で実行できます。

package/README.ko.md

@@ -73,7 +73,7 @@ Cairn은 Claude-family와 Codex-family 모델에만 모델별 조정을 적용
 - `docs/memory/*.md`: 도메인별 상세 지식.
 - `PLAN.md`: 활성/완료 작업 주제의 짧은 색인.
 - `docs/plan/*.md`: 상세 실행 계획.
-- `.cairn/state.json`: 중단 재개와 범위가 제한된 종료 게이트에 쓰는 git-ignored 버전드 goal/task/receipt 상태.
+- `.cairn/state.json`: 중단 재개와 범위가 제한된 종료 게이트에 쓰는 git-ignored 버전드 goal/task/증거 기록 상태.
 
 런타임 script, template, command, agent, model guidance는 설치된 플러그인 루트에 유지합니다. 각 표면의 locator가 같은 설치본을 가리키므로 대상 저장소에 Cairn 내부 파일을 복사하지 않습니다.
 
@@ -105,12 +105,16 @@ 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 goal ...`: 저장소의 영속 goal을 시작·조회·일시정지·재개·차단·취소·완료합니다. 기본 tool-bound 정책은 `goal verify -- <argv>`가 명령을 직접 실행해 성공 증거를 기록합니다. `goal receipt`는 기존 선언 증거를 가져오는 호환 명령입니다.
 - `cairn-memory`: 도메인 지식을 탐색하고 `MEMORY.md`를 갱신합니다.
 - `cairn-plan`: `docs/plan/` 아래에 decision-complete plan을 만듭니다.
 - `cairn-work`: 현재 `PLAN.md`의 다음 모듈 작업을 실행하고 두 검증 게이트를 확보합니다.
 - `cairn-review`: 계획, memory, 증거를 기준으로 완료된 작업을 검토합니다.
 
+모든 `UserPromptSubmit`에서 Cairn은 구현 또는 계속 실행 요청 자체가 goal 생성 권한이며 사용자가 “goal”을 직접 말할 필요가 없다는 모델 가시 지침을 주입합니다. 에이전트는 먼저 트리아지를 active task로 둔 초기 저장소 계획을 작성하고, 탐색·트리아지 전에 가능한 경우 Codex `update_plan`과 `create_goal`로 같은 roadmap을 UI에 표시한 뒤 저장소 Cairn goal을 시작합니다. 트리아지 결과로 두 계획을 decision-complete 구현 계획으로 갱신한 뒤에만 구현합니다. 활성 goal은 전체 순서형 roadmap, 각 상태, 현재 task를 hook 컨텍스트에 유지하므로 곁가지 질문 뒤 원래 작업으로 돌아갈 수 있습니다. 상담·설명·계획 전용 요청은 goal 없이 처리합니다.
+
+토큰 효율 실행에서는 구현보다 먼저 요구사항·불변식·경계·실패 모드로 집중 실행 test contract를 설계하는 데 추론을 배분합니다. 구현에는 실패 계약과 제한된 파일 범위만 전달하고 통과에 필요한 최소 변경을 요구합니다. 성공 여부는 도구 exit code와 기계적 요약으로 판정하며 성공 출력은 축약하고 실패할 때만 컨텍스트를 확장합니다. package 검증 전 lifecycle script를 검사하고 기본적으로 정상 `npm pack --dry-run`을 실행합니다. content-producing 또는 미분류 script에는 `--ignore-scripts`를 사용하면 안 되며, script가 없거나 content-neutral임을 입증했고 전체 검사 증거가 여전히 유효할 때만 사용할 수 있습니다. 성공한 상태 변경은 `--quiet`를 지원하므로 커지는 goal JSON이 대화 토큰을 소모하지 않습니다.
+
 `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를 사용합니다.

package/README.md

@@ -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.
 
@@ -113,12 +113,16 @@ 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 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.” 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.
+
+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 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.

package/README.pt.md

@@ -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.

package/README.zh.md

@@ -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 执行。

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-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 -- ...` so the tool exit code, bounded output, and watched-workspace fingerprint are recorded together.
+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 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.
-- Bind active work to a persisted Cairn goal and stable task IDs. 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 -- ...`; treat tool exit codes and bounded machine summaries as authoritative. Compress success output and expand context only for failing tests and related code. The exact argv, output digest, and watched-workspace fingerprint make stale evidence fail closed.
+- 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 -- ...`. On success, retain exact argv, tool exit code, pass count, output digest, and watched-workspace fingerprint. 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.0",
+  "version": "0.2.2",
   "description": "Token-efficient agent harness with tool readiness for Codex, Claude Code, and Antigravity",
   "license": "MIT",
   "author": {