cairn-ai 0.2.1 → 0.2.2

package/scripts/cairn-state.mjs

@@ -65,6 +65,7 @@ This file is a short index of active and completed work plans.
 ## Planning Rules
 
 - Every agent must start assigned work by reading the project-root \`MEMORY.md\` for domain knowledge and repository policy.
+- For implementation or continued execution, first write an initial plan with \`triage-plan\` active, synchronize it to native UI plan/goal tools and the repository goal before exploration, then update it after triage.
 - Plans must be decision-complete before implementation.
 - Run complexity triage before applying agent, plugin, or delegated workflow guidance.
 - Record the selected Light Path or Heavy Path and the checked Heavy Path signals in \`docs/plan/<topic>.md\`.
@@ -96,6 +97,7 @@ const planTemplateKo = `# PLAN
 ## Planning Rules
 
 - 모든 에이전트는 배정된 작업을 시작할 때 도메인 지식과 저장소 정책을 위해 프로젝트 루트 \`MEMORY.md\`를 먼저 읽어야 합니다.
+- 구현 또는 계속 실행 요청은 먼저 \`triage-plan\`이 active인 초기 계획을 쓰고, 탐색 전에 UI plan/goal과 저장소 goal을 동기화한 뒤 트리아지 결과로 계획을 갱신합니다.
 - 계획은 구현 전에 의사결정이 완료된 상태여야 합니다.
 - 에이전트, 플러그인, 위임 워크플로 지침을 적용하기 전에 복잡도 트리아지를 실행합니다.
 - 선택한 Light Path 또는 Heavy Path와 확인한 Heavy Path 신호를 \`docs/plan/<topic>.md\`에 기록합니다.
@@ -112,6 +114,13 @@ const planTemplateKo = `# PLAN
 - 두 번 실패한 뒤에는 blocker를 \`docs/plan/<topic>.md\`에 기록합니다.
 `;
 
+const contextLimits = {
+  goalTitle: 64,
+  taskId: 32,
+  taskTitle: 40,
+  roadmapWindow: 3,
+};
+
 if (isCliEntry()) {
   const event = process.argv[2] ?? "manual";
   const payload = await readHookInput();
@@ -156,8 +165,8 @@ export async function runStateResult(event = "manual", {
     return {
       status: 0,
       message: ko
-        ? "Cairn 점검: 외부 상태 변경에는 dry-run/check receipt가 필요합니다. 활성 목표가 있다면 현재 task에 성공 receipt를 기록하세요."
-        : "Cairn check: external-state changes need a dry-run/check receipt. When a goal is active, record a successful receipt for its current task.",
+        ? "Cairn 점검: 외부 상태 변경에는 dry-run/check 증거 기록이 필요합니다. 활성 목표가 있다면 현재 task에 성공 증거를 기록하세요."
+        : "Cairn check: external-state changes need dry-run/check evidence. When a goal is active, record successful evidence for its current task.",
       hookOutput: {},
     };
   }
@@ -200,37 +209,57 @@ async function writeIfMissing(path, content) {
 }
 
 function contextResult({ ko, state, event }) {
-  const base = ko
-    ? "Cairn 컨텍스트: 작업 전 프로젝트 루트 MEMORY.md를 읽으세요."
-    : "Cairn context: read the project-root MEMORY.md before working.";
-  const goalPolicy = event === "user-prompt-submit"
+  const base = ko ? "Cairn: 루트 MEMORY.md를 읽으세요." : "Cairn: read root MEMORY.md.";
+  const idlePolicy = event === "user-prompt-submit"
     ? (ko
-      ? "현재 사용자 prompt가 구현 또는 계속 실행을 요청한다면, 사용자가 goal을 언급하지 않아도 이 요청 자체를 권한으로 간주하세요. decision-complete plan에 순서가 있는 stable task 단계를 정의한 뒤 구현 전에 활성 Cairn goal을 생성하거나 연결하고, 완료·일시정지·차단·취소 상태가 될 때까지 계속 진행하세요. 상담·설명·계획 전용 요청에는 goal을 만들지 마세요."
-      : "If the current user prompt requests implementation or continued execution, treat the request itself as authorization even when the user does not mention a goal. Define stable, ordered task steps in a decision-complete plan, then create or attach an active Cairn goal before implementation and continue until it is completed, paused, blocked, or cancelled. Do not create a goal for consultation, explanation, or plan-only requests.")
+      ? " 구현/계속 실행: 초기 트리아지 계획 작성 → update_plan → create_goal → 탐색 전 저장소 goal 시작 → 트리아지 후 계획 확정 → 구현. 상담·설명·계획 전용은 goal 없이 처리하세요."
+      : " Implementation/continue: write an initial triage plan; call update_plan, then create_goal; start the repository goal before exploration; finalize the plan after triage, then implement. Skip goals for consultation, explanation, or plan-only requests.")
     : "";
-  const initialContext = [base, goalPolicy].filter(Boolean).join(" ");
-  if (!state || state.goal.status !== "active") return contextHookResult({ event, message: initialContext });
-  const task = state.tasks.find((item) => item.status === "active") ?? state.tasks.find((item) => item.status === "pending");
+  if (!state || state.goal.status !== "active") return contextHookResult({ event, message: `${base}${idlePolicy}` });
+  const task = state.tasks.find((item) => item.status === "active")
+    ?? state.tasks.find((item) => item.status === "pending")
+    ?? state.tasks.find((item) => item.status === "blocked");
+  const goalTitle = clipText(state.goal.title, contextLimits.goalTitle);
+  const activeHeader = ko
+    ? `Cairn active: "${goalTitle}". ${base}`
+    : `Cairn active: "${goalTitle}". ${base}`;
   if (!task) {
     return contextHookResult({
       event,
-      message: [initialContext, taskRoadmap(ko, state), activeGoalCompletionMessage(ko, state)].join("\n"),
+      message: [activeHeader, taskRoadmap(ko, state), activeGoalCompletionMessage(ko, state)].join("\n"),
     });
   }
+  const taskId = clipText(task.id, contextLimits.taskId);
+  const taskTitle = clipText(task.title, contextLimits.taskTitle);
   const continuation = ko
-    ? `활성 목표 "${state.goal.title}"의 현재 task는 ${task.id} (${task.title})입니다. 완료 전 성공 receipt를 기록하세요.`
-    : `Active goal "${state.goal.title}" current task: ${task.id} (${task.title}). Record a successful receipt before completing it.`;
+    ? `현재: ${taskId} (${taskTitle}). 바인딩된 증거 뒤에만 완료하세요.`
+    : `Current: ${taskId} (${taskTitle}). Complete only after bound evidence.`;
   const resume = event === "user-prompt-submit"
     ? (ko
-      ? `곁가지 질문에 답한 뒤 사용자가 명시적으로 일시정지·중단·전환을 요청하지 않았다면 현재 task ${task.id}로 돌아와 계속 진행하세요.`
-      : `After answering a side question, return to current task ${task.id} and continue unless the user explicitly asks to pause, stop, or switch tasks.`)
+      ? `곁가지 질문 뒤 일시정지·중단·전환 요청이 없으면 ${taskId}를 재개하세요.`
+      : `After a side question, resume ${taskId} unless asked to pause, stop, or switch.`)
     : "";
-  return contextHookResult({ event, message: [initialContext, taskRoadmap(ko, state), continuation, resume].filter(Boolean).join("\n") });
+  return contextHookResult({ event, message: [activeHeader, taskRoadmap(ko, state), continuation, resume].filter(Boolean).join("\n") });
 }
 
 function taskRoadmap(ko, state) {
-  const steps = state.tasks.map((task, index) => `${index + 1}. ${task.id} [${task.status}] ${task.title}`);
-  return `${ko ? "작업 단계" : "Work steps"}:\n${steps.join("\n")}`;
+  const formatTask = (task, index) => `${index + 1}. ${clipText(task.id, contextLimits.taskId)} [${task.status}] ${clipText(task.title, contextLimits.taskTitle)}`;
+  if (state.tasks.length <= contextLimits.roadmapWindow) {
+    return `${ko ? "작업 단계" : "Work steps"}:\n${state.tasks.map(formatTask).join("\n")}`;
+  }
+
+  const currentIndex = Math.max(0, state.tasks.findIndex((task) => task.status === "active" || task.status === "pending"));
+  const maxStart = state.tasks.length - contextLimits.roadmapWindow;
+  const start = Math.min(Math.max(0, currentIndex - 1), maxStart);
+  const visible = state.tasks.slice(start, start + contextLimits.roadmapWindow);
+  const counts = Object.fromEntries([...TASK_STATUS_NAMES].map((status) => [status, state.tasks.filter((task) => task.status === status).length]));
+  const countSummary = Object.entries(counts).filter(([, count]) => count > 0).map(([status, count]) => `${status} ${count}`).join(", ");
+  const omitted = state.tasks.length - visible.length;
+  const header = ko
+    ? `작업 단계 (${state.tasks.length}개; ${countSummary})`
+    : `Work steps (${state.tasks.length}; ${countSummary})`;
+  const omission = ko ? `… ${omitted}개 단계 생략` : `… ${omitted} steps omitted`;
+  return `${header}:\n${visible.map((task, index) => formatTask(task, start + index)).join("\n")}\n${omission}`;
 }
 
 function contextHookResult({ event, message }) {
@@ -272,9 +301,17 @@ function stopAllowedMessage({ ko, state, event }) {
 }
 
 function activeGoalCompletionMessage(ko, state) {
+  const goalTitle = clipText(state.goal.title, contextLimits.goalTitle);
   return ko
-    ? `활성 목표 "${state.goal.title}"의 모든 task가 완료되었습니다. 완료 기준을 확인하고 명시적으로 complete 상태로 전이하세요.`
-    : `All tasks for active goal "${state.goal.title}" are complete. Verify criteria and explicitly transition the goal to completed.`;
+    ? `활성 목표 "${goalTitle}"의 모든 task가 완료되었습니다. 완료 기준을 확인하고 명시적으로 complete 상태로 전이하세요.`
+    : `All tasks for active goal "${goalTitle}" are complete. Verify criteria and explicitly transition the goal to completed.`;
+}
+
+const TASK_STATUS_NAMES = ["active", "pending", "blocked", "completed"];
+
+function clipText(value, maxLength) {
+  const text = String(value ?? "");
+  return text.length <= maxLength ? text : `${text.slice(0, maxLength - 1)}…`;
 }
 
 function resolveRoot(root, payload) {

package/scripts/cairn-state.sh

@@ -85,6 +85,7 @@ if [ ! -f "$plan" ]; then
 ## Planning Rules
 
 - 모든 에이전트는 배정된 작업을 시작할 때 도메인 지식과 저장소 정책을 위해 프로젝트 루트 `MEMORY.md`를 먼저 읽어야 합니다.
+- 구현 또는 계속 실행 요청은 먼저 `triage-plan`이 active인 초기 계획을 쓰고, 탐색 전에 UI plan/goal과 저장소 goal을 동기화한 뒤 트리아지 결과로 계획을 갱신합니다.
 - 계획은 구현 전에 의사결정이 완료된 상태여야 합니다.
 - 에이전트, 플러그인, 위임 워크플로 지침을 적용하기 전에 복잡도 트리아지를 실행합니다.
 - 선택한 Light Path 또는 Heavy Path와 확인한 Heavy Path 신호를 `docs/plan/<topic>.md`에 기록합니다.
@@ -117,6 +118,7 @@ This file is a short index of active and completed work plans.
 ## Planning Rules
 
 - Every agent must start assigned work by reading the project-root `MEMORY.md` for domain knowledge and repository policy.
+- For implementation or continued execution, first write an initial plan with `triage-plan` active, synchronize it to native UI plan/goal tools and the repository goal before exploration, then update it after triage.
 - Plans must be decision-complete before implementation.
 - Split implementation into small module tasks.
 - Detect repository stack and required LSP/check tools before implementation.

package/scripts/cairn.mjs

@@ -67,6 +67,7 @@ function isCliEntry() {
 
 const planExecutionPolicy = "The user-called/main agent is the orchestrator; implementation edits go to worker subagents whenever subagent tools are available. 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. If subagent tools are unavailable, the main agent takes over implementation directly and records that takeover in evidence.";
 const workExecutionPolicy = "The user-called/main agent orchestrates, while worker subagents perform implementation edits whenever subagent tools are available. 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. If subagent tools are unavailable, the main agent takes over implementation directly and records that takeover in evidence.";
+const tokenEfficientWorkPolicy = "Use a test contract for requirements, invariants, boundaries, and failure modes before the minimum implementation. The tool exit code is authoritative. Run goal verify -- <argv> and expand only failures. Inspect package lifecycle scripts: content-producing or unknown scripts must never use --ignore-scripts; only absent or proven content-neutral scripts may use it while prior full-check evidence remains fresh.";
 const artifactLocalePolicy = "Write user-visible responses and generated or updated documentation, plans, and memory artifacts in the OS locale unless the user asks for another language.";
 const artifactLocalePolicyKo = "사용자가 다른 언어를 요청하지 않는 한, 사용자에게 보이는 응답과 생성 또는 갱신하는 문서, 계획, 메모리 산출물은 OS locale 언어로 작성합니다.";
 
@@ -74,56 +75,56 @@ const messages = {
   en: {
     memory: `Use the cairn-memory skill. Keep MEMORY.md as a short index and write details to docs/memory/<domain>.md. ${artifactLocalePolicy}`,
     plan: `Use the cairn-plan skill before non-trivial implementation. Every agent must first read the project-root MEMORY.md for domain knowledge and repository policy. Understand the whole work first, then classify it into executable tasks and sub-tasks. Keep PLAN.md as an index, write detailed plans to docs/plan/<topic>.md, and record Light/Heavy Path triage before any mutation. ${artifactLocalePolicy} ${planExecutionPolicy}`,
-    work: `Use the cairn-work skill only after a plan exists. Every agent must first read the project-root MEMORY.md for domain knowledge and repository policy. Execute one module task using the recorded Light/Heavy Path route: ${workExecutionPolicy} Capture dry-run/check, module, and surface evidence. ${artifactLocalePolicy} If the user asks a side question while work is active, answer briefly and then resume unless they explicitly ask to pause, stop, or switch tasks.`,
+    work: `Use cairn-work only after a plan exists and every agent reads root MEMORY.md. ${tokenEfficientWorkPolicy} Execute one task through its recorded Light/Heavy Path: ${workExecutionPolicy} ${artifactLocalePolicy} Resume active work after side questions unless asked to pause, stop, or switch.`,
     review: `Use the cairn-review skill. Compare evidence against PLAN.md and MEMORY.md. ${artifactLocalePolicy}`,
     usage: "Usage: cairn install|upgrade|doctor|uninstall|init|memory|plan|work|review|toolcheck|goal|task",
   },
   ko: {
     memory: `cairn-memory 스킬을 사용하세요. MEMORY.md는 짧은 색인으로, 상세 내용은 docs/memory/<domain>.md에 기록합니다. ${artifactLocalePolicyKo}`,
     plan: `중요 구현 전에는 cairn-plan 스킬을 사용하세요. 모든 에이전트는 도메인 지식과 저장소 정책을 위해 프로젝트 루트 MEMORY.md를 먼저 읽어야 합니다. 먼저 전체 작업을 파악한 뒤 실행 가능한 task와 필요한 sub-task로 분류합니다. PLAN.md는 색인으로, 상세 계획은 docs/plan/<topic>.md에 기록하며 파일 변경 전 Light/Heavy Path 트리아지를 남깁니다. ${artifactLocalePolicyKo} ${planExecutionPolicy}`,
-    work: `계획이 있을 때만 cairn-work 스킬을 사용하세요. 모든 에이전트는 도메인 지식과 저장소 정책을 위해 프로젝트 루트 MEMORY.md를 먼저 읽어야 합니다. 기록된 Light/Heavy Path 경로로 하나의 모듈 작업을 실행합니다. ${workExecutionPolicy} dry-run/check, 모듈, 표면 증거를 확보합니다. ${artifactLocalePolicyKo} 작업 중 사용자가 곁가지 질문을 하면 짧게 답한 뒤, 명시적으로 일시중지/중단/작업 전환을 요청한 경우가 아니면 이전 active work를 계속합니다.`,
+    work: `계획이 있고 모든 에이전트가 루트 MEMORY.md를 읽은 뒤에만 cairn-work를 사용하세요. ${tokenEfficientWorkPolicy} 기록된 Light/Heavy Path로 한 task를 수행합니다. ${workExecutionPolicy} ${artifactLocalePolicyKo} 곁가지 질문 뒤에는 일시중지·중단·전환 요청이 없으면 active work를 재개합니다.`,
     review: `cairn-review 스킬을 사용하세요. PLAN.md와 MEMORY.md 기준으로 증거를 비교합니다. ${artifactLocalePolicyKo}`,
     usage: "사용법: cairn install|upgrade|doctor|uninstall|init|memory|plan|work|review|toolcheck|goal|task",
   },
   ja: {
     memory: `cairn-memory スキルを使用してください。MEMORY.md は短い索引にし、詳細は docs/memory/<domain>.md に記録します。${artifactLocalePolicy}`,
     plan: `cairn-plan スキルを使用してください。PLAN.md は索引にし、詳細計画は docs/plan/<topic>.md に記録します。${artifactLocalePolicy} ${planExecutionPolicy}`,
-    work: `cairn-work スキルを使用してください。1つのモジュールスライスを実行し、モジュール証拠と表面証拠を取得します。${workExecutionPolicy} ${artifactLocalePolicy}`,
+    work: `cairn-work スキルを使用してください。1つのモジュールスライスを実行し、モジュール証拠と表面証拠を取得します。${tokenEfficientWorkPolicy} ${workExecutionPolicy} ${artifactLocalePolicy}`,
     review: `cairn-review スキルを使用してください。PLAN.md と MEMORY.md に照らして証拠を比較します。${artifactLocalePolicy}`,
     usage: "使い方: cairn install|upgrade|doctor|uninstall|init|memory|plan|work|review|toolcheck|goal|task",
   },
   zh: {
     memory: `使用 cairn-memory skill。将 MEMORY.md 保持为简短索引，并将详细内容写入 docs/memory/<domain>.md。${artifactLocalePolicy}`,
     plan: `使用 cairn-plan skill。将 PLAN.md 保持为索引，并将详细计划写入 docs/plan/<topic>.md。${artifactLocalePolicy} ${planExecutionPolicy}`,
-    work: `使用 cairn-work skill。执行一个模块切片，并收集模块证据。${workExecutionPolicy} ${artifactLocalePolicy}`,
+    work: `使用 cairn-work skill。执行一个模块切片，并收集模块证据。${tokenEfficientWorkPolicy} ${workExecutionPolicy} ${artifactLocalePolicy}`,
     review: `使用 cairn-review skill。根据 PLAN.md 和 MEMORY.md 对比证据。${artifactLocalePolicy}`,
     usage: "用法: cairn install|upgrade|doctor|uninstall|init|memory|plan|work|review|toolcheck|goal|task",
   },
   es: {
     memory: `Usa la skill cairn-memory. Mantén MEMORY.md como un índice breve y escribe los detalles en docs/memory/<domain>.md. ${artifactLocalePolicy}`,
     plan: `Usa la skill cairn-plan. Mantén PLAN.md como índice y escribe los planes detallados en docs/plan/<topic>.md. ${artifactLocalePolicy} ${planExecutionPolicy}`,
-    work: `Usa la skill cairn-work. Ejecuta un solo segmento de módulo y captura evidencia de módulo y de superficie. ${workExecutionPolicy} ${artifactLocalePolicy}`,
+    work: `Usa la skill cairn-work. Ejecuta un solo segmento de módulo y captura evidencia de módulo y de superficie. ${tokenEfficientWorkPolicy} ${workExecutionPolicy} ${artifactLocalePolicy}`,
     review: `Usa la skill cairn-review. Compara la evidencia con PLAN.md y MEMORY.md. ${artifactLocalePolicy}`,
     usage: "Uso: cairn install|upgrade|doctor|uninstall|init|memory|plan|work|review|toolcheck|goal|task",
   },
   fr: {
     memory: `Utilisez la skill cairn-memory. Gardez MEMORY.md comme index court et écrivez les détails dans docs/memory/<domain>.md. ${artifactLocalePolicy}`,
     plan: `Utilisez la skill cairn-plan. Gardez MEMORY.md comme index et écrivez les plans détaillés dans docs/plan/<topic>.md. ${artifactLocalePolicy} ${planExecutionPolicy}`,
-    work: `Utilisez la skill cairn-work. Exécutez une tranche de module et capturez les preuves de module et de surface. ${workExecutionPolicy} ${artifactLocalePolicy}`,
+    work: `Utilisez la skill cairn-work. Exécutez une tranche de module et capturez les preuves de module et de surface. ${tokenEfficientWorkPolicy} ${workExecutionPolicy} ${artifactLocalePolicy}`,
     review: `Utilisez la skill cairn-review. Comparez les preuves avec PLAN.md et MEMORY.md. ${artifactLocalePolicy}`,
     usage: "Utilisation: cairn install|upgrade|doctor|uninstall|init|memory|plan|work|review|toolcheck|goal|task",
   },
   de: {
     memory: `Verwenden Sie die Skill cairn-memory. Halten Sie MEMORY.md als kurzen Index und schreiben Sie Details nach docs/memory/<domain>.md. ${artifactLocalePolicy}`,
     plan: `Verwenden Sie die Skill cairn-plan. Halten Sie MEMORY.md als Index und schreiben Sie Detailpläne nach docs/plan/<topic>.md. ${artifactLocalePolicy} ${planExecutionPolicy}`,
-    work: `Verwenden Sie die Skill cairn-work. Führen Sie einen Modulabschnitt aus und erfassen Sie Modul- und Oberflächenbelege. ${workExecutionPolicy} ${artifactLocalePolicy}`,
+    work: `Verwenden Sie die Skill cairn-work. Führen Sie einen Modulabschnitt aus und erfassen Sie Modul- und Oberflächenbelege. ${tokenEfficientWorkPolicy} ${workExecutionPolicy} ${artifactLocalePolicy}`,
     review: `Verwenden Sie die Skill cairn-review. Vergleichen Sie Belege mit PLAN.md und MEMORY.md. ${artifactLocalePolicy}`,
     usage: "Verwendung: cairn install|upgrade|doctor|uninstall|init|memory|plan|work|review|toolcheck|goal|task",
   },
   pt: {
     memory: `Use a skill cairn-memory. Mantenha MEMORY.md como um índice curto e escreva detalhes em docs/memory/<domain>.md. ${artifactLocalePolicy}`,
     plan: `Use a skill cairn-plan. Mantenha MEMORY.md como índice e escreva planos detalhados em docs/plan/<topic>.md. ${artifactLocalePolicy} ${planExecutionPolicy}`,
-    work: `Use a skill cairn-work. Execute uma fatia de módulo e capture evidências de módulo e de superfície. ${workExecutionPolicy} ${artifactLocalePolicy}`,
+    work: `Use a skill cairn-work. Execute uma fatia de módulo e capture evidências de módulo e de superfície. ${tokenEfficientWorkPolicy} ${workExecutionPolicy} ${artifactLocalePolicy}`,
     review: `Use a skill cairn-review. Compare evidências com PLAN.md e MEMORY.md. ${artifactLocalePolicy}`,
     usage: "Uso: cairn install|upgrade|doctor|uninstall|init|memory|plan|work|review|toolcheck|goal|task",
   },

package/skills/cairn-plan/SKILL.md

@@ -23,27 +23,33 @@ Resolve Cairn's read-only runtime from `references/cairn-runtime.json` next to t
 
 Use logical resource IDs such as `cairn://templates/work-plan.md` and `cairn://docs/model-guidance/codex.md` in repository plans. Resolve those IDs through `pluginRoot` only while executing. Keep `repoRoot` separate and pass it explicitly as `--root <repoRoot>`.
 
-For an implementation or continued-execution request, treat the request itself as authorization to define stable, ordered task steps and activate the decision-complete plan with the installed CLI, even when the user does not mention a goal:
+For an implementation or continued-execution request, treat the request itself as authorization to create an initial two-phase plan and activate its roadmap, even when the user does not mention a goal. The initial plan is decision-complete for the `triage-plan` task but is not implementation-ready. After writing it and its `PLAN.md` index entry, synchronize the same ordered steps to Codex UI tools when available (`update_plan` first, then `create_goal`) and start the repository goal before exploration, toolcheck, complexity triage, or a non-blocking user question:
 
 ```sh
-node "<pluginRoot>/scripts/cairn.mjs" goal start --root "<repoRoot>" --goal "<objective>" --plan "docs/plan/<topic>.md" --tasks '[{"id":"task-1","title":"<task>"}]' --criteria "<completion criterion>" --session "<current session_id>"
+node "<pluginRoot>/scripts/cairn.mjs" goal start --root "<repoRoot>" --goal "<objective>" --plan "docs/plan/<topic>.md" --tasks '[{"id":"triage-plan","title":"Run planned triage and finalize the plan","requiredEvidence":["planArtifact","triageDecision"]},{"id":"implement","title":"Implement the finalized plan"},{"id":"verify","title":"Verify and review the result"}]' --criteria "<completion criterion>" --session "<current session_id>"
 ```
 
-Use the current Codex hook `session_id` when it is available. If the surface does not expose a stable session ID, omit `--session` and record that the goal is repository-scoped.
+Use the current Codex hook `session_id` when it is available. If the surface does not expose a stable session ID, omit `--session` and record that the goal is repository-scoped. If Codex UI plan/goal tools are unavailable, record that limitation and continue with the repository plan and goal; never claim UI synchronization that did not occur.
 
 ## Procedure
 
 1. Run `node "<pluginRoot>/scripts/cairn.mjs" init --root "<repoRoot>"` through the resolved runtime. If the runtime is unavailable, ensure `MEMORY.md`, `PLAN.md`, `docs/memory`, and `docs/plan` directly and report that `cairn doctor` or `cairn upgrade` is required.
 2. Read the project-root `MEMORY.md` before repository exploration, tool selection, or delegation.
-3. Read only the relevant `docs/memory/*.md` files referenced by `MEMORY.md` or required by the current task.
-4. Based on the active or assigned model, read `cairn://docs/model-guidance/README.md` and only the relevant installed model guidance.
-5. Run `node "<pluginRoot>/scripts/cairn.mjs" toolcheck --root "<repoRoot>"` to identify repository stacks and required tools.
+3. Classify the request as implementation/continued execution versus consultation/explanation/plan-only. For implementation/continued execution, immediately create an initial `docs/plan/<topic>.md` from `cairn://templates/work-plan.md` and add its `PLAN.md` index entry. Based only on the request and `MEMORY.md`, describe the observable outcome, anticipated affected surfaces, and stable top-level roadmap. Make `triage-plan` the first active task and specify its memory inputs, investigation scope, toolcheck, Heavy Path criteria, and exact condition for updating the plan. Mark the plan `initial: decision-complete for triage; not implementation-ready`.
+4. Before reading detailed memory, toolcheck, repository exploration, complexity triage, delegation, or any non-blocking user question, synchronize the initial roadmap:
+   - Call Codex `update_plan` first when available so the UI displays the ordered tasks with `triage-plan` in progress.
+   - Call Codex `create_goal` next when available so the UI displays the active objective. The implementation request plus this developer-level skill instruction is authorization; do not use it for consultation, explanation, or plan-only requests.
+   - Start or attach the repository Cairn goal with the same objective, plan ID, stable task IDs, and current session ID.
+   - If a UI tool is unavailable, record the limitation in the plan and continue with repository state.
+5. Execute the planned `triage-plan` task: read only the relevant `docs/memory/*.md`, read applicable installed model guidance, run toolcheck, and explore the repository with focused search and LSP/symbol tools.
 6. Treat tool installation as a separate external-state change. Do not install during planning without explicit user approval. After approval, use `toolcheck --install --yes --root "<repoRoot>"` only for pinned/supported installers, or the approved repository-native command. Otherwise record the missing tool and proposed command as a blocker.
-7. Explore the repository with focused search and LSP/symbol tools after tool readiness is confirmed.
-8. Summarize the whole work and affected surfaces, then classify the plan into small executable tasks. Use sub-tasks only when a task needs further breakdown to be verifiable.
-9. Identify the closest available dry-run or check mode for every task that can mutate external state.
-10. Run complexity triage before applying workflow guidance from agents, plugins, or delegated roles. Record the route before any implementation task.
-11. Delegate according to the selected path and model guidance instead of asking the user.
+7. Summarize the whole work and affected surfaces, classify it into small executable tasks/sub-tasks, identify dry-run/check modes, and run complexity triage before applying workflow guidance from agents, plugins, or delegated roles.
+8. Update the same repository plan with the selected route, all checked Heavy Path signals, concrete file scope, tool readiness, delegation, verification commands, and fail-closed evidence. Mark it `decision-complete for implementation`, then call Codex `update_plan` again so the UI matches the finalized roadmap.
+   - Spend planning tokens on executable test design: requirements, invariants, boundaries, failure modes, expected initial failure, and authoritative tool result.
+   - Give implementation a bounded test contract and exact file scope; require the minimum passing change rather than renewed broad discovery.
+   - Plan focused tests first, one final full check, and a package dry-run when no change occurred after the full check. Require lifecycle inspection, normal script execution for content-producing or unknown scripts, and `--ignore-scripts` only for absent or proven content-neutral scripts. Mark evidence stale after relevant mutation.
+9. Only after step 8, record bound `planArtifact` and `triageDecision` evidence records, complete the `triage-plan` task, and advance to implementation.
+10. Delegate according to the selected path and model guidance instead of asking the user.
    - Use `explorer` for independent read-only codebase discovery, impact analysis, pattern searches, and read-only verification that can run in parallel when the current tool list supports it.
    - Treat the user-called/main agent as the orchestrator: it plans, assigns, verifies, 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.
@@ -53,10 +59,9 @@ Use the current Codex hook `session_id` when it is available. If the surface doe
    - 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.
    - Keep urgent non-implementation blocking work local when the next step depends immediately on the result.
    - Tell every delegated agent and child subagent to read the project-root `MEMORY.md` before work, keep scope, and tell workers they are not alone in the codebase and must not revert others' edits.
-12. Create `docs/plan/<topic>.md` from `cairn://templates/work-plan.md` resolved through the installed runtime.
-13. Add a short index entry to `PLAN.md`.
-14. Give every plan and ordered task step a stable ID and declare task-level and goal-level required evidence. When the user asked for implementation or continuing execution rather than a consultation, explanation, or plan-only result, treat that request as authorization and start or attach the repository Cairn goal after the plan is decision-complete, even if the user never mentioned a goal. The task order must be sufficient for hook context to show the roadmap and restore the current task after side questions.
-15. Write user-visible responses and generated or updated documentation, plans, and memory artifacts in the OS locale unless the user asks for another language.
+11. Give every plan and ordered task step a stable ID and declare task-level and goal-level required evidence. The task order must be sufficient for both Codex UI and hook context to show the roadmap and restore the current task after side questions.
+12. Advance a Codex UI step only after the matching repository Cairn task transition succeeds with all required bound evidence records. The repository state is the fail-closed transition authority; UI state is its synchronized projection.
+13. Write user-visible responses and generated or updated documentation, plans, and memory artifacts in the OS locale unless the user asks for another language.
 
 ## Complexity Triage
 
@@ -116,7 +121,8 @@ Heavy Path flow: plan -> pre-implementation review -> bounded `worker` implement
 
 ## Planning Rules
 
-- Every plan must be decision-complete.
+- Every initial plan must be decision-complete for its triage task and explicitly not implementation-ready; the post-triage revision must be decision-complete for implementation.
+- Every implementation or continued-execution plan must be shown through Codex `update_plan` and `create_goal` before triage when those tools are available, then synchronized again after triage. Repository plan/goal persistence remains required on every surface.
 - Every plan must describe the whole work first, then classify it into executable tasks and any needed sub-tasks.
 - Every plan must treat the user-called/main agent as the orchestrator and assign actual implementation edits to `worker` whenever subagent tools are available, regardless of Light Path or Heavy Path.
 - Every plan must require subagents to report status when the subagent tool provides a progress-reporting channel. If no mid-run reporting channel exists, the orchestrator must relay observable events such as assignment, waiting, and final completion.
@@ -152,7 +158,7 @@ Do not silently skip LSP, typecheck, lint, dry-run, or verification because the
 Prefer repository-native dry-run and check modes before mutating external state.
 
 - Migrations and database changes: `--pretend`, dry-run, schema diff, rollback feasibility check, or equivalent.
-- Package and release work: `npm pack --dry-run`, publish dry-run, build check, or equivalent.
+- Package and release work: inspect lifecycle scripts first, then use normal `npm pack --dry-run`, publish dry-run, build check, or equivalent. Never skip content-producing or unknown lifecycle scripts with `--ignore-scripts`; it is allowed only for absent or proven content-neutral scripts while prior full-check evidence remains fresh.
 - Infrastructure and deployment: plan, diff, validate, check, or equivalent.
 - Code generation and formatting: check mode before write mode when available.
 - If no dry-run mode exists, record that fact and select the smallest reversible command or test artifact available.

package/skills/cairn-review/SKILL.md

@@ -48,5 +48,5 @@ CONTEXT: docs/plan/<topic>.md, MEMORY.md, relevant docs/memory notes, changed fi
 - Dry-run or check evidence is present when required, or the plan records why no dry-run exists.
 - Failed gates followed the bounded loop policy and did not continue past two verification passes without a recorded blocker.
 - Review evidence exists in `docs/plan/<topic>.md`.
-- Goal-level final review evidence is stored as a successful structured receipt before the goal is marked `completed`.
+- Goal-level final review evidence is stored as a successful structured evidence record before the goal is marked `completed`.
 - The next agent can understand verification without rereading the full conversation.

package/skills/cairn-work/SKILL.md

@@ -31,16 +31,35 @@ Use the installed CLI for durable state. Important forms are:
 
 ```sh
 node "<pluginRoot>/scripts/cairn.mjs" goal status --root "<repoRoot>"
-node "<pluginRoot>/scripts/cairn.mjs" goal assign --root "<repoRoot>" --task "<task-id>" --agent "<agent-id>"
-node "<pluginRoot>/scripts/cairn.mjs" goal receipt --root "<repoRoot>" --task "<task-id>" --kind moduleAcceptance --command "<verification command>" --exit 0
-node "<pluginRoot>/scripts/cairn.mjs" goal receipt --root "<repoRoot>" --task "<task-id>" --kind surfaceIntegration --command "<verification command or QA artifact>" --exit 0
-node "<pluginRoot>/scripts/cairn.mjs" goal task --root "<repoRoot>" --task "<task-id>" --status completed
-node "<pluginRoot>/scripts/cairn.mjs" goal receipt --root "<repoRoot>" --scope goal --kind finalReview --command "<review command>" --exit 0
-node "<pluginRoot>/scripts/cairn.mjs" goal complete --root "<repoRoot>"
+node "<pluginRoot>/scripts/cairn.mjs" goal assign --quiet --root "<repoRoot>" --task "<task-id>" --agent "<agent-id>"
+node "<pluginRoot>/scripts/cairn.mjs" goal verify --quiet --root "<repoRoot>" --task "<task-id>" --kind moduleAcceptance --watch "<path|path>" -- <tool> <arg> ...
+node "<pluginRoot>/scripts/cairn.mjs" goal verify --quiet --root "<repoRoot>" --task "<task-id>" --kind surfaceIntegration --watch "<path|path>" -- <tool> <arg> ...
+node "<pluginRoot>/scripts/cairn.mjs" goal task --quiet --root "<repoRoot>" --task "<task-id>" --status completed
+node "<pluginRoot>/scripts/cairn.mjs" goal verify --quiet --root "<repoRoot>" --scope goal --kind finalReview --watch "<path|path>" -- <tool> <arg> ...
+node "<pluginRoot>/scripts/cairn.mjs" goal complete --quiet --root "<repoRoot>"
 ```
 
+`goal verify` executes the argv after `--` without a shell and records its exit code, bounded tool output, output digest, and watched-workspace fingerprint. The legacy `goal receipt` command imports declared evidence for compatibility; declared evidence does not satisfy a default tool-bound goal.
+
 Use `goal pause`, `goal block --reason "<concrete blocker>"`, or `goal cancel` when that is the truthful state. A task can be blocked with `goal task --task "<task-id>" --status blocked --reason "<concrete blocker>"`.
 
+## Token-Efficient Test Contract
+
+Use the test contract first. Spend reasoning on requirements, invariants, boundaries, and failure modes before implementation. Turn them into focused executable tests, confirm that new tests fail for the intended reason, then make the minimum implementation that passes.
+
+Treat the tool exit code and bounded machine summary as authoritative. On success, retain only the command, exit code, and pass count needed for evidence. Expand diagnostics and repository context only around the failing test; do not reread unrelated files or replay successful output.
+
+Use this verification ladder:
+
+1. Run the focused contract tests.
+2. Implement the minimum change and rerun only those tests while diagnosing.
+3. Run the full repository check once after the final change.
+4. Before package verification, inspect package lifecycle scripts such as `prepack`, `prepare`, and `prepublishOnly` and classify whether they produce package contents.
+5. Run normal `npm pack --dry-run` by default. Content-producing or unknown lifecycle scripts must never be skipped with `--ignore-scripts`; their generated contents are part of the package contract.
+6. Only when lifecycle scripts are absent or proven content-neutral, the full check is still fresh, and the dry-run is only checking the file list may package verification use `npm pack --dry-run --ignore-scripts`.
+
+Any relevant mutation after a gate makes that result stale evidence. Rerun the affected focused gate and, when integration could change, the full gate. Use `--quiet` for successful Cairn state mutations so full state JSON does not consume conversation tokens. `goal status` is read-only and always returns state, including when `--quiet` is supplied.
+
 ## Procedure
 
 1. Read the project-root `MEMORY.md` first.
@@ -54,15 +73,17 @@ Use `goal pause`, `goal block --reason "<concrete blocker>"`, or `goal cancel` w
 9. For Heavy Path, follow the full planning and review pipeline recorded in the plan. Run pre-implementation review before mutation and read-only review after evidence exists.
 10. Delegate implementation to `worker` with exact files, ownership, constraints, and model-specific adjustment rules on both Light Path and Heavy Path whenever subagent tools are available. Tell every delegated agent and child subagent to read the project-root `MEMORY.md` before work, keep scope, preserve others' edits, and report status when the subagent tool provides a progress-reporting channel. Immediately relay received status events to the user. If no mid-run reporting channel exists, relay observable events such as assignment, waiting, and final completion. Require delegated subagents to provide a final report before leaving; after capturing final report and evidence, close or release the completed subagent, then review the final report and evidence before marking the work complete. Use `explorer` for parallel read-only discovery or verification when available and useful. Allow recursive delegation only for bounded sub-tasks when the current surface supports it. If subagent tools are unavailable, the main agent takes over implementation directly and records that takeover in evidence.
 11. Before mutating external state, run the task dry-run or check command when one is recorded. If none exists, record the absence and continue with the smallest reversible command available.
-12. For Heavy Path, run the recorded automated test command and record explicit `Tests:` evidence before claiming completion.
-13. `worker` must return a structured handoff for only its assigned goal/task with changed files, tool readiness result, dry-run or check result when applicable, automated test result for Heavy Path, module acceptance command and result, surface integration command or QA artifact, blocker, and cleanup notes. A worker must not select the next task.
-14. Re-run both verification gates directly. Record each successful command as a structured Cairn receipt bound to the current goal ID, task ID, and plan.
-15. Apply the bounded loop policy when a gate fails. After two failed passes, transition the task or goal to `blocked` with a concrete blocker instead of continuing automatically.
-16. Mark a task complete only after every required receipt passes. Let Cairn advance to the next pending task, then continue the goal without yielding a false completion.
-17. After all tasks complete, run and record the goal-level final review receipt and explicitly complete the goal. `active` is not a completion state; `paused`, `blocked`, and `cancelled` are allowed terminal-for-now states that stop automatic continuation.
-18. Record evidence in the plan file and state before updating `PLAN.md`.
-19. 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.
-20. Write user-visible responses and generated or updated documentation, plans, and memory artifacts in the OS locale unless the user asks for another language.
+12. Design the focused executable test contract before implementation. For behavior changes, run it and confirm the intended failure; for policy-only work, use the closest deterministic assertion or record why a failing test is unavailable.
+13. Give the implementation worker only the contract, failing evidence, exact file scope, and constraints; require the minimum implementation rather than renewed broad discovery.
+14. For Heavy Path, run the recorded automated test command and record explicit `Tests:` evidence before claiming completion.
+15. `worker` must return a structured handoff for only its assigned goal/task with changed files, tool readiness result, dry-run or check result when applicable, automated test result for Heavy Path, module acceptance command and result, surface integration command or QA artifact, blocker, and cleanup notes. A worker must not select the next task.
+16. Re-run both verification gates through `goal verify -- ...`. Treat tool exit codes as authoritative, keep successful output summarized, and expand context only for a failing test. Record each success as evidence bound to the current goal ID, task ID, plan, exact argv, and watched-workspace fingerprint.
+17. Apply the bounded loop policy when a gate fails. After two failed passes, transition the task or goal to `blocked` with a concrete blocker instead of continuing automatically.
+18. Mark a task complete only after every required evidence record passes. Let Cairn advance to the next pending task, then continue the goal without yielding a false completion.
+19. After all tasks complete, run and record goal-level final review evidence and explicitly complete the goal. `active` is not a completion state; `paused`, `blocked`, and `cancelled` are allowed terminal-for-now states that stop automatic continuation.
+20. Record evidence in the plan file and state before updating `PLAN.md`.
+21. 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.
+22. Write user-visible responses and generated or updated documentation, plans, and memory artifacts in the OS locale unless the user asks for another language.
 
 ## Builder Prompt Format
 
@@ -94,7 +115,7 @@ CONTEXT: docs/plan/<topic>.md task, relevant docs/memory notes, applied model gu
 Run the closest available dry-run or check mode before commands that mutate external state.
 
 - Migrations and database changes: `--pretend`, dry-run, schema diff, rollback feasibility check, or equivalent.
-- Package and release work: `npm pack --dry-run`, publish dry-run, build check, or equivalent.
+- Package and release work: inspect lifecycle scripts, then run normal `npm pack --dry-run`, publish dry-run, build check, or equivalent. Use `--ignore-scripts` only for absent or proven content-neutral lifecycle scripts while prior full-check evidence remains fresh.
 - Infrastructure and deployment: plan, diff, validate, check, or equivalent.
 - Code generation and formatting: check mode before write mode when available.
 - If no dry-run mode exists, record that fact in `docs/plan/<topic>.md` before continuing.

package/templates/PLAN.md

@@ -4,6 +4,7 @@ Short index of work plans. Link detailed plans under `docs/plan/`.
 
 ## Planning Rules
 
+- For implementation or continued execution, write an initial plan with `triage-plan` active, synchronize it to native UI plan/goal tools and the repository goal before exploration, then update it after triage.
 - Detect repository stack and required LSP/check tools before implementation.
 - Install or bootstrap missing required tools before declaring them unavailable.
 - Heavy Path completion requires explicit automated test evidence.

package/templates/work-plan.md

@@ -1,5 +1,11 @@
 # Plan: <topic>
 
+## Plan Phase
+
+- Initial: decision-complete for `triage-plan`; not implementation-ready.
+- Finalized: decision-complete for implementation after planned triage.
+- Codex UI synchronization: `update_plan` status and `create_goal` status, or an explicit unavailable reason.
+
 ## Goal
 
 Describe the observable result.
@@ -74,6 +80,10 @@ Describe the observable result.
 
 ## Execution Guardrails
 
+- Test contract first: requirements, invariants, boundaries, failure modes, expected initial failure, and authoritative tool result.
+- Token budget: high reasoning for plan/triage/test design; bounded minimum implementation; concise tool-derived verification summaries.
+- Verification ladder: focused tests, one final full check, then package dry-run if no files changed. Inspect lifecycle scripts first; 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 evidence remains fresh.
+- Evidence freshness: relevant changes after verification make affected evidence stale.
 - Dry-run or check mode before external-state mutation:
 - No dry-run available, if applicable:
 - Verification loop budget: two passes per task by default.
@@ -81,6 +91,15 @@ Describe the observable result.
 
 ## Module Tasks
 
+### Task 0: planned triage and plan finalization
+
+- Task ID: `triage-plan`
+- Initial status: `active`
+- Contract: execute the investigation scope and Heavy Path criteria declared by the initial plan, then update this file and the Codex UI plan to the decision-complete implementation revision.
+- Required evidence records:
+  - `planArtifact`: command, exit code 0, timestamp, goal ID, task ID, and plan ID.
+  - `triageDecision`: command, exit code 0, timestamp, goal ID, task ID, and plan ID.
+
 ### Task 1: <module>
 
 - Task ID: `task-1`
@@ -93,7 +112,7 @@ Describe the observable result.
 - Dry-run or check command:
 - Module acceptance verification:
 - Surface integration verification:
-- Required receipts:
+- Required evidence records:
   - `moduleAcceptance`: command, exit code 0, timestamp, goal ID, task ID, and plan ID.
   - `surfaceIntegration`: command or QA artifact, exit code 0, timestamp, goal ID, task ID, and plan ID.
 - Assigned agent ID, if delegated:
@@ -106,7 +125,7 @@ Describe the observable result.
 - Tests:
 - Module acceptance:
 - Surface integration:
-- Goal final review receipt:
+- Goal final review evidence record:
 - Verification pass count:
 - Blocker after two failed passes: