cairn-ai 0.2.5 → 0.2.6

package/scripts/cairn-goal.mjs

@@ -2,10 +2,13 @@
 import { spawnSync } from "node:child_process";
 import { createHash, randomUUID } from "node:crypto";
 import { lstatSync, readFileSync, readlinkSync, realpathSync, readdirSync } from "node:fs";
-import { readFile, rename, rm } from "node:fs/promises";
-import { join, relative, resolve, sep } from "node:path";
+import { lstat, readFile, rename, rm } from "node:fs/promises";
+import { dirname, join, relative, resolve, sep } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { assertNoSymlinkComponents, safeMkdir, safeWriteFile, withStateLock } from "./cairn-safe-fs.mjs";
+import { cairnHome, goalStateDirectory, worktreeId } from "./cairn-paths.mjs";
+
+export { worktreeId } from "./cairn-paths.mjs";
 
 export const GOAL_STATE_VERSION = 2;
 export const GOAL_STATUSES = new Set(["active", "paused", "blocked", "cancelled", "completed"]);
@@ -33,17 +36,17 @@ const taskTransitions = {
 };
 
 export function goalStatePath(root = process.cwd()) {
-  return join(resolve(root), ".cairn", "state.json");
+  return join(goalStateDirectory(root), "state.json");
 }
 
 export async function readGoalState({ root = process.cwd() } = {}) {
   try {
     const path = goalStatePath(root);
-    await assertNoSymlinkComponents(root, path);
+    await assertNoSymlinkComponents(cairnHome(), path);
     const text = await readFile(path, "utf8");
     return validateState(migrateState(JSON.parse(text)));
   } catch (error) {
-    if (error?.code === "ENOENT") return null;
+    if (error?.code === "ENOENT") return migrateLegacyGoalState(root);
     if (error instanceof SyntaxError) throw new Error(`Cairn goal state is invalid JSON: ${error.message}`);
     throw error;
   }
@@ -54,8 +57,15 @@ export async function startGoal({ root = process.cwd(), goal, planId, tasks, com
   const normalizedPlanId = boundedRequiredText(planId, "planId", PLAN_ID_MAX_LENGTH);
   if (!Array.isArray(tasks) || tasks.length === 0) throw new Error("tasks must contain at least one task");
 
-  return withStateLock(root, async () => {
-    const existing = await readGoalState({ root });
+  return withGoalStateLock(root, async () => {
+    let existing = await readGoalState({ root });
+    const currentWorktreeId = worktreeId(root);
+    if (existing && existing.goal.worktreeId !== currentWorktreeId) {
+      const path = goalStatePath(root);
+      await assertNoSymlinkComponents(cairnHome(), path, { allowMissing: false });
+      await rm(path);
+      existing = null;
+    }
     if (existing && !terminalGoalStatuses.has(existing.goal.status)) {
       throw new Error(`An active Cairn goal already exists (${existing.goal.id}); pause, block, cancel, or complete it first`);
     }
@@ -75,6 +85,7 @@ export async function startGoal({ root = process.cwd(), goal, planId, tasks, com
         completionCriteria: normalizeCriteria(completionCriteria),
         requiredEvidence: normalizeCriteria(requiredEvidence),
         evidencePolicy: validEvidencePolicy(evidencePolicy),
+        worktreeId: currentWorktreeId,
         ownerSessionId: optionalText(ownerSessionId, "ownerSessionId"),
         blocker: null,
         createdAt: now,
@@ -88,18 +99,36 @@ export async function startGoal({ root = process.cwd(), goal, planId, tasks, com
   });
 }
 
+export async function reconcileWorktreeState({ root = process.cwd() } = {}) {
+  const initial = await readGoalState({ root });
+  if (!initial || initial.goal.worktreeId === worktreeId(root)) {
+    return { state: initial, removed: false };
+  }
+  return withGoalStateLock(root, async () => {
+    const state = await readGoalState({ root });
+    if (!state || state.goal.worktreeId === worktreeId(root)) {
+      return { state, removed: false };
+    }
+    const staleWorktreeId = state.goal.worktreeId;
+    const path = goalStatePath(root);
+    await assertNoSymlinkComponents(cairnHome(), path, { allowMissing: false });
+    await rm(path);
+    return { state: null, removed: true, staleWorktreeId };
+  });
+}
+
 export async function writeGoalState({ root = process.cwd(), state } = {}) {
-  return withStateLock(root, () => writeGoalStateUnlocked({ root, state }));
+  return withGoalStateLock(root, () => writeGoalStateUnlocked({ root, state }));
 }
 
 async function writeGoalStateUnlocked({ root = process.cwd(), state } = {}) {
   const validated = validateState(state);
   const path = goalStatePath(root);
-  await safeMkdir(root, ".cairn");
-  await assertNoSymlinkComponents(root, path);
+  await ensureGoalStateDirectory(root);
+  await assertNoSymlinkComponents(cairnHome(), path);
   const temporaryPath = `${path}.${process.pid}.${randomUUID()}.tmp`;
   try {
-    await safeWriteFile(root, temporaryPath, `${JSON.stringify(validated, null, 2)}\n`, "utf8");
+    await safeWriteFile(cairnHome(), temporaryPath, `${JSON.stringify(validated, null, 2)}\n`, "utf8");
     await rename(temporaryPath, path);
   } catch (error) {
     await rm(temporaryPath, { force: true }).catch(() => {});
@@ -109,21 +138,38 @@ async function writeGoalStateUnlocked({ root = process.cwd(), state } = {}) {
 
 export async function transitionGoal({ root = process.cwd(), status, blocker } = {}) {
   const nextStatus = validGoalStatus(status);
+  if (terminalGoalStatuses.has(nextStatus)) {
+    return withGoalStateLock(root, async () => {
+      const state = await readGoalState({ root });
+      if (!state) throw new Error("No Cairn goal state exists; start a goal first");
+      const next = applyGoalTransition(structuredClone(state), nextStatus, blocker, root);
+      next.revision += 1;
+      validateState(next);
+      const path = goalStatePath(root);
+      await assertNoSymlinkComponents(cairnHome(), path, { allowMissing: false });
+      await rm(path);
+      return next;
+    });
+  }
   return mutateGoal(root, (state) => {
-    const currentStatus = state.goal.status;
-    if (currentStatus === nextStatus) return state;
-    if (!goalTransitions[currentStatus].has(nextStatus)) {
-      throw new Error(`Cannot transition goal from ${currentStatus} to ${nextStatus}`);
-    }
-    if (nextStatus === "completed") ensureGoalCanComplete(state, root);
-    if (nextStatus === "blocked") state.goal.blocker = requiredText(blocker, "blocker");
-    if (nextStatus === "active") state.goal.blocker = null;
-    state.goal.status = nextStatus;
-    state.goal.updatedAt = timestamp();
-    return state;
+    return applyGoalTransition(state, nextStatus, blocker, root);
   });
 }
 
+function applyGoalTransition(state, nextStatus, blocker, root) {
+  const currentStatus = state.goal.status;
+  if (currentStatus === nextStatus) return state;
+  if (!goalTransitions[currentStatus].has(nextStatus)) {
+    throw new Error(`Cannot transition goal from ${currentStatus} to ${nextStatus}`);
+  }
+  if (nextStatus === "completed") ensureGoalCanComplete(state, root);
+  if (nextStatus === "blocked") state.goal.blocker = requiredText(blocker, "blocker");
+  if (nextStatus === "active") state.goal.blocker = null;
+  state.goal.status = nextStatus;
+  state.goal.updatedAt = timestamp();
+  return state;
+}
+
 export async function setTaskStatus({ root = process.cwd(), taskId, status, blocker } = {}) {
   const nextStatus = validTaskStatus(status);
   const normalizedTaskId = requiredText(taskId, "taskId");
@@ -153,6 +199,34 @@ export async function setTaskStatus({ root = process.cwd(), taskId, status, bloc
   });
 }
 
+export async function replanGoal({ root = process.cwd(), tasks } = {}) {
+  if (!Array.isArray(tasks) || tasks.length === 0) {
+    throw new Error("replan tasks must contain at least one incomplete task");
+  }
+
+  return mutateGoal(root, (state) => {
+    assertGoalMutable(state);
+    if (state.goal.status !== "active") throw new Error("Only an active goal can be replanned");
+
+    const completedTasks = state.tasks.filter((task) => task.status === "completed");
+    const completedIds = new Set(completedTasks.map((task) => task.id));
+    const replacementTasks = tasks.map((task, index) => {
+      const source = typeof task === "string" ? task : { ...task, status: undefined, blocker: undefined };
+      const normalized = normalizeTask(source, index, index === 0 ? "active" : "pending");
+      if (completedIds.has(normalized.id)) {
+        throw new Error(`Replanned task conflicts with completed task id: ${normalized.id}`);
+      }
+      return normalized;
+    });
+
+    state.tasks = [...completedTasks, ...replacementTasks];
+    state.receipts = state.receipts.filter((receipt) => receipt.scope === "task" && completedIds.has(receipt.taskId));
+    state.goal.blocker = null;
+    state.goal.updatedAt = timestamp();
+    return state;
+  });
+}
+
 export async function assignTask({ root = process.cwd(), taskId, agentId = null } = {}) {
   const normalizedTaskId = requiredText(taskId, "taskId");
   const normalizedAgentId = agentId === null ? null : requiredText(agentId, "agentId");
@@ -403,6 +477,11 @@ export async function handleGoalCli(args = process.argv.slice(2), { stdout = con
     emit(JSON.stringify(state));
     return state;
   }
+  if (command === "replan") {
+    const state = await replanGoal({ root, tasks: parseTasks(options.tasks ?? positional.slice(0)) });
+    emit(JSON.stringify(state));
+    return state;
+  }
   if (command === "assign") {
     const state = await assignTask({ root, taskId: options.task ?? positional[0], agentId: options.agent ?? positional[1] ?? null });
     emit(JSON.stringify(state));
@@ -452,11 +531,11 @@ export async function handleGoalCli(args = process.argv.slice(2), { stdout = con
     emit(JSON.stringify(state));
     return state;
   }
-  throw new Error("Usage: cairn-goal start|status|task|assign|receipt|verify|pause|resume|block|cancel|complete [--root PATH]");
+  throw new Error("Usage: cairn-goal start|status|task|replan|assign|receipt|verify|pause|resume|block|cancel|complete [--root PATH]");
 }
 
 async function mutateGoal(root, mutate) {
-  return withStateLock(root, async () => {
+  return withGoalStateLock(root, async () => {
     const state = await readGoalState({ root });
     if (!state) throw new Error("No Cairn goal state exists; start a goal first");
     const next = await mutate(structuredClone(state));
@@ -466,6 +545,44 @@ async function mutateGoal(root, mutate) {
   });
 }
 
+async function withGoalStateLock(root, operation) {
+  await ensureGoalStateDirectory(root);
+  return withStateLock(goalStateDirectory(root), operation);
+}
+
+async function ensureGoalStateDirectory(root) {
+  const home = cairnHome();
+  let existingAncestor = home;
+  while (true) {
+    try {
+      const stat = await lstat(existingAncestor);
+      if (!stat.isDirectory()) throw new Error(`Cairn home ancestor is not a directory: ${existingAncestor}`);
+      break;
+    } catch (error) {
+      if (error?.code !== "ENOENT") throw error;
+      const parent = dirname(existingAncestor);
+      if (parent === existingAncestor) throw error;
+      existingAncestor = parent;
+    }
+  }
+  await safeMkdir(existingAncestor, relative(existingAncestor, goalStateDirectory(root)));
+}
+
+async function migrateLegacyGoalState(root) {
+  const legacyPath = join(resolve(root), ".cairn", "state.json");
+  try {
+    await assertNoSymlinkComponents(root, legacyPath, { allowMissing: false });
+    const state = validateState(migrateState(JSON.parse(await readFile(legacyPath, "utf8"))));
+    await writeGoalStateUnlocked({ root, state });
+    await rm(legacyPath);
+    return state;
+  } catch (error) {
+    if (error?.code === "ENOENT") return null;
+    if (error instanceof SyntaxError) throw new Error(`Cairn goal state is invalid JSON: ${error.message}`);
+    throw error;
+  }
+}
+
 function normalizeTask(task, index, defaultStatus) {
   const source = typeof task === "string" ? { title: task } : task;
   if (!source || typeof source !== "object") throw new Error(`tasks[${index}] must be a string or object`);
@@ -516,6 +633,7 @@ function validateState(value) {
   if (!Array.isArray(goal.requiredEvidence) || goal.requiredEvidence.length === 0) throw new Error("goal.requiredEvidence must be a non-empty array");
   goal.requiredEvidence.forEach((kind, index) => requiredText(kind, `goal.requiredEvidence[${index}]`));
   if (goal.ownerSessionId !== null && goal.ownerSessionId !== undefined) requiredText(goal.ownerSessionId, "goal.ownerSessionId");
+  if (goal.worktreeId !== null && goal.worktreeId !== undefined) requiredText(goal.worktreeId, "goal.worktreeId");
   if (goal.blocker !== null && goal.blocker !== undefined) requiredText(goal.blocker, "goal.blocker");
   if (!Array.isArray(value.tasks) || value.tasks.length === 0) throw new Error("Cairn goal state must contain tasks");
   if (!Array.isArray(value.receipts)) throw new Error("Cairn goal state evidence records (receipts) must be an array");
@@ -916,6 +1034,7 @@ function allowedOptions(command) {
     start: ["goal", "plan", "tasks", "criteria", "requiredEvidence", "session", "evidencePolicy", "evidence-policy"],
     status: [],
     task: ["task", "status", "reason"],
+    replan: ["tasks"],
     assign: ["task", "agent"],
     receipt: ["task", "kind", "scope", "command", "exitCode", "exit-code", "exit", "timestamp", "goalId", "goal-id", "plan"],
     verify: ["task", "kind", "scope", "watch", "timeout-ms"],

package/scripts/cairn-paths.mjs

@@ -1,9 +1,55 @@
-import { existsSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { existsSync, lstatSync, readFileSync, realpathSync } from "node:fs";
+import { homedir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
 export const RUNTIME_LOCATOR_SCHEMA_VERSION = 1;
 
+export function cairnHome(env = process.env) {
+  const userHome = env.HOME ?? env.USERPROFILE ?? homedir();
+  return resolve(env.CAIRN_HOME ?? join(userHome, ".cairn"));
+}
+
+export function repositoryId(root = process.cwd()) {
+  return `project-${hashPath(gitLayout(root).commonDir)}`;
+}
+
+export function worktreeId(root = process.cwd()) {
+  return `worktree-${hashPath(gitLayout(root).gitDir)}`;
+}
+
+export function goalStateDirectory(root = process.cwd(), env = process.env) {
+  return join(cairnHome(env), "projects", repositoryId(root), "worktrees", worktreeId(root));
+}
+
+function gitLayout(root) {
+  const workspaceRoot = realpathSync(resolve(root));
+  const gitEntry = join(workspaceRoot, ".git");
+  try {
+    const stat = lstatSync(gitEntry);
+    const gitDir = stat.isDirectory() ? realpathSync(gitEntry) : resolveGitFile(workspaceRoot, gitEntry);
+    const commonFile = join(gitDir, "commondir");
+    const commonDir = existsSync(commonFile)
+      ? realpathSync(resolve(gitDir, readFileSync(commonFile, "utf8").trim()))
+      : gitDir;
+    return { gitDir, commonDir };
+  } catch (error) {
+    if (error?.code !== "ENOENT") throw error;
+    return { gitDir: workspaceRoot, commonDir: workspaceRoot };
+  }
+}
+
+function resolveGitFile(workspaceRoot, gitEntry) {
+  const match = readFileSync(gitEntry, "utf8").match(/^gitdir:\s*(.+)\s*$/m);
+  if (!match) throw new Error(`Invalid Git worktree file: ${gitEntry}`);
+  return realpathSync(resolve(workspaceRoot, match[1]));
+}
+
+function hashPath(value) {
+  return createHash("sha256").update(value).digest("hex");
+}
+
 export function resolvePluginRoot(moduleUrl = import.meta.url) {
   return resolve(dirname(fileURLToPath(moduleUrl)), "..");
 }

package/scripts/cairn-state.mjs

@@ -3,7 +3,7 @@ import { realpathSync } from "node:fs";
 import { readFile } from "node:fs/promises";
 import { join } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
-import { evaluateStop, isGoalOwnedBySession, readGoalState } from "./cairn-goal.mjs";
+import { evaluateStop, isGoalOwnedBySession, readGoalState, reconcileWorktreeState } from "./cairn-goal.mjs";
 import { resolveRepoRoot } from "./cairn-paths.mjs";
 import { assertNoSymlinkComponents, safeMkdir, safeWriteFile } from "./cairn-safe-fs.mjs";
 
@@ -65,11 +65,13 @@ 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.
+- Read project-root \`MEMORY.md\` first when it exists; if it is absent, continue without repository memory.
+- For non-trivial implementation or continuation of planned work, first write or restore a plan with \`triage-plan\` active and synchronize it before exploration. Known-target Git/GitHub operations stay plan/goal-free unless they require code edits, conflict resolution, destructive recovery, release/deploy, or design.
 - 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\`.
+- Record request, planning, and code checkpoints. When the route changes before editing, synchronize the plan artifact, repository goal task roadmap through \`goal replan\`, and native UI plan. After editing starts, a new Heavy Path signal promotes Light Path to Heavy Path; stop further edits, mark affected evidence stale, synchronize all three roadmaps, and repeat the code checkpoint.
+- Keep models inherited. Record requested/effective reasoning effort per task: Light planning/implementation/verification=\`medium\`; Heavy planning/review/implementation=\`high\`; final verification/review=\`xhigh\`. A route change also synchronizes the reasoning effort profile, preserving completed profiles and recalculating incomplete profiles. Unsupported host/value means effective=\`inherited\` with no model/global config change.
 - Split implementation into small module tasks.
 - Detect repository stack and required LSP/check tools before implementation.
 - Record missing required tools and suggested commands. Run only pinned, supported installation steps after explicit user approval.
@@ -97,11 +99,13 @@ const planTemplateKo = `# PLAN
 
 ## Planning Rules
 
-- 모든 에이전트는 배정된 작업을 시작할 때 도메인 지식과 저장소 정책을 위해 프로젝트 루트 \`MEMORY.md\`를 먼저 읽어야 합니다.
-- 구현 또는 계속 실행 요청은 먼저 \`triage-plan\`이 active인 초기 계획을 쓰고, 탐색 전에 UI plan/goal과 저장소 goal을 동기화한 뒤 트리아지 결과로 계획을 갱신합니다.
+- 프로젝트 루트 \`MEMORY.md\`가 있으면 먼저 읽고, 없으면 저장소 메모리 없이 계속 진행합니다.
+- 비단순 구현 또는 계획된 작업 재개는 먼저 \`triage-plan\`이 active인 계획을 쓰거나 복원하고 탐색 전에 동기화합니다. 대상이 확정된 Git/GitHub 운영은 코드 수정·충돌 해결·파괴적 복구·릴리스/배포·설계가 필요하지 않으면 plan/goal 없이 실행합니다.
 - 계획은 구현 전에 의사결정이 완료된 상태여야 합니다.
 - 에이전트, 플러그인, 위임 워크플로 지침을 적용하기 전에 복잡도 트리아지를 실행합니다.
 - 선택한 Light Path 또는 Heavy Path와 확인한 Heavy Path 신호를 \`docs/plan/<topic>.md\`에 기록합니다.
+- 요청, 계획, 코드 체크포인트를 기록합니다. 편집 전에 경로가 바뀌면 plan artifact, 저장소 goal task roadmap, native UI plan을 동기화합니다. 편집 뒤 새 Heavy Path 신호가 나오면 추가 편집을 중단하고 관련 증거를 stale로 표시한 뒤 세 roadmap과 코드 체크포인트를 다시 맞춥니다.
+- 모델은 상속하고 task별 requested/effective reasoning effort를 기록합니다. Light 계획/구현/검증은 \`medium\`, Heavy 계획/검토/구현은 \`high\`, 최종 검증/검토는 \`xhigh\`입니다. 경로 변경 시 reasoning effort profile도 동기화하고 완료 profile은 보존하며 미완료 profile은 재계산합니다. 미지원 host/value는 model/global config 변경 없이 effective=\`inherited\`입니다.
 - 구현은 작은 모듈 작업으로 나눕니다.
 - 구현 전에 저장소 스택과 필요한 LSP/check 도구를 감지합니다.
 - 필요한 도구가 없으면 누락 상태와 제안 명령을 기록합니다. 명시적 사용자 승인 뒤에만 고정된 지원 설치 단계를 실행합니다.
@@ -157,11 +161,17 @@ export async function runStateResult(event = "manual", {
   }
 
   if (event === "session-start" || event === "user-prompt-submit") {
-    const state = await readGoalState({ root: resolvedRoot });
+    const reconciled = await reconcileWorktreeState({ root: resolvedRoot });
+    const state = reconciled.state;
     if (state?.goal?.status === "active" && !isGoalOwnedBySession(state, payload?.session_id)) {
       return foreignSessionContextResult({ ko, event });
     }
-    return contextResult({ ko, state, event });
+    const result = contextResult({ ko, state, event });
+    if (!reconciled.removed) return result;
+    const notice = ko
+      ? "Cairn worktree 점검: 현재 worktree에 속하지 않는 stale Cairn 상태를 제거했습니다."
+      : "Cairn worktree check: removed stale Cairn state that did not belong to this worktree.";
+    return prependContext(result, notice);
   }
 
   if (event === "post-tool-use") {
@@ -181,7 +191,7 @@ export async function runStateResult(event = "manual", {
   }
 
   if (event === "stop" || event === "subagent-stop") {
-    const state = await readGoalState({ root: resolvedRoot });
+    const { state } = await reconcileWorktreeState({ root: resolvedRoot });
     if (!isGoalOwnedBySession(state, payload?.session_id)) return { status: 0, message: "", hookOutput: {} };
     const gate = evaluateStop(state, {
       subagent: event === "subagent-stop",
@@ -223,18 +233,34 @@ async function writeIfMissing(root, path, content) {
   }
 }
 
+function prependContext(result, notice) {
+  const specific = result.hookOutput?.hookSpecificOutput;
+  if (!specific) return { ...result, message: `${notice}\n${result.message}` };
+  return {
+    ...result,
+    message: `${notice}\n${result.message}`,
+    hookOutput: {
+      ...result.hookOutput,
+      hookSpecificOutput: {
+        ...specific,
+        additionalContext: `${notice}\n${specific.additionalContext}`,
+      },
+    },
+  };
+}
+
 function contextResult({ ko, state, event }) {
-  const base = ko ? "Cairn kernel: 루트 MEMORY.md를 먼저 읽으세요." : "Cairn kernel: read root MEMORY.md first.";
+  const base = ko ? "Cairn kernel: 루트 MEMORY.md는 선택 사항이며, 있으면 읽으세요." : "Cairn kernel: root MEMORY.md is optional; read it when present.";
   const idlePolicy = event === "user-prompt-submit"
     ? (ko
-      ? " 구현/계속 실행이면 cairn-plan을 로드하고 active plan과 current task를 복원하거나 생성하세요. 상담·설명·계획 전용은 goal 없이 처리하세요."
-      : " For implementation/continue, load cairn-plan and restore or create the active plan and current task. Keep consultation, explanation, and plan-only requests goal-free.")
+      ? " 비단순 구현이나 계획된 작업 재개는 cairn-plan과 plan/task를 복원·생성하세요. 대상이 확정된 Git/GitHub 상태·fetch·checkout·merge·push·PR 작업은 코드 수정·충돌 해결·파괴적 복구·릴리스/배포·설계가 필요하지 않으면 plan/goal 없이 실행하세요. 상담·설명·계획 전용도 goal 없이 처리하세요."
+      : " For non-trivial implementation or planned-work continuation, load cairn-plan and restore/create its plan and task. Known-target Git/GitHub operations stay plan/goal-free unless they require code edits, conflict resolution, destructive recovery, release/deploy, or design. Consultation, explanation, and plan-only requests are also goal-free.")
     : (ko
       ? " 중요 작업 전에 cairn-plan을 로드하고 active plan과 current task를 복원하세요."
       : " Before non-trivial work, load cairn-plan and restore the active plan and current task.");
   const failClosed = ko
-    ? " state, skill, plan 또는 required reference가 없거나 읽을 수 없거나 일치하지 않으면 수정·위임·완료하지 말고 보고하거나 차단하세요."
-    : " If state, skill, plan, or a required ref is missing, unreadable, or inconsistent, do not edit, delegate, or complete; report/block.";
+    ? " active state와 그 skill·plan·required task reference가 없거나 읽을 수 없거나 일치하지 않을 때만 중단하세요."
+    : " Stop only if active state and its skill, plan, or required task ref is missing, unreadable, or inconsistent.";
   if (!state || state.goal.status !== "active") return contextHookResult({ event, message: `${base}${idlePolicy}${failClosed}` });
   const task = state.tasks.find((item) => item.status === "active")
     ?? state.tasks.find((item) => item.status === "pending")
@@ -273,8 +299,8 @@ function contextResult({ ko, state, event }) {
 
 function foreignSessionContextResult({ ko, event }) {
   const message = ko
-    ? "Cairn kernel: 루트 MEMORY.md를 먼저 읽으세요. 저장소 goal을 다른 session이 소유합니다. cairn goal status로 상태를 확인하고 소유권이 해결될 때까지 Cairn 작업을 시작·수정·위임·완료하지 마세요. 이 capsule은 goal, plan, task 상세를 노출하지 않습니다."
-    : "Cairn kernel: read root MEMORY.md first. A repository goal is owned by another session. Inspect cairn goal status; until ownership is resolved, do not start, edit, delegate, or complete Cairn work. This capsule does not expose goal, plan, or task details.";
+    ? "Cairn kernel: 루트 MEMORY.md는 선택 사항이며, 있으면 읽으세요. 저장소 goal을 다른 session이 소유합니다. cairn goal status로 상태를 확인하고 소유권이 해결될 때까지 Cairn 작업을 시작·수정·위임·완료하지 마세요. 이 capsule은 goal, plan, task 상세를 노출하지 않습니다."
+    : "Cairn kernel: root MEMORY.md is optional; read it when present. A repository goal is owned by another session. Inspect cairn goal status; until ownership is resolved, do not start, edit, delegate, or complete Cairn work. This capsule does not expose goal, plan, or task details.";
   return contextHookResult({ event, message });
 }
 

package/scripts/cairn-state.sh

@@ -84,8 +84,8 @@ if [ ! -f "$plan" ]; then
 
 ## Planning Rules
 
-- 모든 에이전트는 배정된 작업을 시작할 때 도메인 지식과 저장소 정책을 위해 프로젝트 루트 `MEMORY.md`를 먼저 읽어야 합니다.
-- 구현 또는 계속 실행 요청은 먼저 `triage-plan`이 active인 초기 계획을 쓰고, 탐색 전에 UI plan/goal과 저장소 goal을 동기화한 뒤 트리아지 결과로 계획을 갱신합니다.
+- 프로젝트 루트 `MEMORY.md`가 있으면 먼저 읽고, 없으면 저장소 메모리 없이 계속 진행합니다.
+- 비단순 구현 또는 계획된 작업 재개는 먼저 `triage-plan`이 active인 계획을 쓰거나 복원하고 탐색 전에 동기화합니다. 대상이 확정된 Git/GitHub 운영은 코드 수정·충돌 해결·파괴적 복구·릴리스/배포·설계가 필요하지 않으면 plan/goal 없이 실행합니다.
 - 계획은 구현 전에 의사결정이 완료된 상태여야 합니다.
 - 에이전트, 플러그인, 위임 워크플로 지침을 적용하기 전에 복잡도 트리아지를 실행합니다.
 - 선택한 Light Path 또는 Heavy Path와 확인한 Heavy Path 신호를 `docs/plan/<topic>.md`에 기록합니다.
@@ -117,8 +117,8 @@ 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.
+- Read project-root `MEMORY.md` first when it exists; if it is absent, continue without repository memory.
+- For non-trivial implementation or continuation of planned work, first write or restore a plan with `triage-plan` active and synchronize it before exploration. Known-target Git/GitHub operations stay plan/goal-free unless they require code edits, conflict resolution, destructive recovery, release/deploy, or design.
 - Plans must be decision-complete before implementation.
 - Split implementation into small module tasks.
 - Detect repository stack and required LSP/check tools before implementation.
@@ -138,9 +138,9 @@ fi
 case "$event" in
   session-start|user-prompt-submit)
     if is_ko; then
-      printf '%s\n' "Cairn 컨텍스트: 모든 에이전트는 작업 시작 시 도메인 지식과 정책 색인인 프로젝트 루트 MEMORY.md를 먼저 읽어야 합니다."
+      printf '%s\n' "Cairn 컨텍스트: 프로젝트 루트 MEMORY.md가 있으면 읽고, 없으면 저장소 메모리 없이 계속 진행합니다."
     else
-      printf '%s\n' "Cairn context: every agent must start by reading the project-root MEMORY.md for domain knowledge and repository policy."
+      printf '%s\n' "Cairn context: read project-root MEMORY.md first when present; if absent, continue without repository memory."
     fi
     ;;
   post-tool-use)

package/scripts/cairn.mjs

@@ -31,6 +31,11 @@ export async function main(command = "help", args = [], { runner = spawnSync } =
     process.exitCode = result.status ?? 1;
     return;
   }
+  if (command === "cleanup") {
+    const result = runner(process.execPath, [join(scriptDir, "cairn-cleanup.mjs"), ...args], { stdio: "inherit" });
+    process.exitCode = result.status ?? 1;
+    return;
+  }
   if (["memory", "plan", "work", "review"].includes(command)) {
     console.log(message(command));
     return;
@@ -68,65 +73,68 @@ 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 stagedTriagePolicy = "Use request, planning, and code checkpoints. Before the first edit, evidence may change either route; synchronize the plan artifact, repository goal task roadmap through goal replan, and native UI plan. After editing starts, a new Heavy Path signal promotes Light Path to Heavy Path: stop further edits, mark affected evidence stale, synchronize all three roadmaps, and repeat the code checkpoint.";
+const stagedTriagePolicyKo = "요청, 계획, 코드 체크포인트를 사용합니다. 첫 편집 전에는 증거에 따라 어느 경로로든 바꿀 수 있으며 plan artifact, 저장소 goal task roadmap, native UI plan을 동기화합니다. 편집 뒤 새 Heavy Path 신호가 나오면 Light Path를 Heavy Path로 승격하고 추가 편집을 중단하며 관련 증거를 stale로 표시한 뒤 세 roadmap과 코드 체크포인트를 다시 맞춥니다.";
+const reasoningEffortPolicy = "Inherit models; route reasoning effort by task: Light planning/implementation/verification=medium; Heavy planning/review/implementation=high; final verification/review=xhigh. Only new task dispatch may use a supported host option. Unsupported host/value means effective=inherited; never change model/global config.";
 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 언어로 작성합니다.";
 
 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 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.`,
+    plan: `Use the cairn-plan skill before non-trivial implementation. Read project-root MEMORY.md first when present; if absent, continue without repository memory. 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. ${stagedTriagePolicy} ${reasoningEffortPolicy} ${artifactLocalePolicy} ${planExecutionPolicy}`,
+    work: `Use cairn-work only after a plan exists. Read root MEMORY.md when present and continue without it when absent. ${tokenEfficientWorkPolicy} Execute one task through its recorded Light/Heavy Path. ${stagedTriagePolicy} ${reasoningEffortPolicy} ${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",
+    usage: "Usage: cairn install|upgrade|doctor|uninstall|cleanup|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: `계획이 있고 모든 에이전트가 루트 MEMORY.md를 읽은 뒤에만 cairn-work를 사용하세요. ${tokenEfficientWorkPolicy} 기록된 Light/Heavy Path로 한 task를 수행합니다. ${workExecutionPolicy} ${artifactLocalePolicyKo} 곁가지 질문 뒤에는 일시중지·중단·전환 요청이 없으면 active work를 재개합니다.`,
+    plan: `중요 구현 전에는 cairn-plan 스킬을 사용하세요. 프로젝트 루트 MEMORY.md가 있으면 먼저 읽고, 없으면 저장소 메모리 없이 계속 진행합니다. 먼저 전체 작업을 파악한 뒤 실행 가능한 task와 필요한 sub-task로 분류합니다. PLAN.md는 색인으로, 상세 계획은 docs/plan/<topic>.md에 기록하며 파일 변경 전 Light/Heavy Path 트리아지를 남깁니다. ${stagedTriagePolicyKo} ${reasoningEffortPolicy} ${artifactLocalePolicyKo} ${planExecutionPolicy}`,
+    work: `계획이 있으면 cairn-work를 사용하세요. 루트 MEMORY.md가 있으면 읽고 없으면 무시하고 진행합니다. ${tokenEfficientWorkPolicy} 기록된 Light/Heavy Path로 한 task를 수행합니다. ${stagedTriagePolicyKo} ${reasoningEffortPolicy} ${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",
+    usage: "사용법: cairn install|upgrade|doctor|uninstall|cleanup|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つのモジュールスライスを実行し、モジュール証拠と表面証拠を取得します。${tokenEfficientWorkPolicy} ${workExecutionPolicy} ${artifactLocalePolicy}`,
+    plan: `cairn-plan スキルを使用してください。PLAN.md は索引にし、詳細計画は docs/plan/<topic>.md に記録します。${reasoningEffortPolicy} ${artifactLocalePolicy} ${planExecutionPolicy}`,
+    work: `cairn-work スキルを使用してください。1つのモジュールスライスを実行し、モジュール証拠と表面証拠を取得します。${tokenEfficientWorkPolicy} ${reasoningEffortPolicy} ${workExecutionPolicy} ${artifactLocalePolicy}`,
     review: `cairn-review スキルを使用してください。PLAN.md と MEMORY.md に照らして証拠を比較します。${artifactLocalePolicy}`,
-    usage: "使い方: cairn install|upgrade|doctor|uninstall|init|memory|plan|work|review|toolcheck|goal|task",
+    usage: "使い方: cairn install|upgrade|doctor|uninstall|cleanup|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。执行一个模块切片，并收集模块证据。${tokenEfficientWorkPolicy} ${workExecutionPolicy} ${artifactLocalePolicy}`,
+    plan: `使用 cairn-plan skill。将 PLAN.md 保持为索引，并将详细计划写入 docs/plan/<topic>.md。${reasoningEffortPolicy} ${artifactLocalePolicy} ${planExecutionPolicy}`,
+    work: `使用 cairn-work skill。执行一个模块切片，并收集模块证据。${tokenEfficientWorkPolicy} ${reasoningEffortPolicy} ${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",
+    usage: "用法: cairn install|upgrade|doctor|uninstall|cleanup|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. ${tokenEfficientWorkPolicy} ${workExecutionPolicy} ${artifactLocalePolicy}`,
+    plan: `Usa la skill cairn-plan. Mantén PLAN.md como índice y escribe los planes detallados en docs/plan/<topic>.md. ${reasoningEffortPolicy} ${artifactLocalePolicy} ${planExecutionPolicy}`,
+    work: `Usa la skill cairn-work. Ejecuta un solo segmento de módulo y captura evidencia de módulo y de superficie. ${tokenEfficientWorkPolicy} ${reasoningEffortPolicy} ${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",
+    usage: "Uso: cairn install|upgrade|doctor|uninstall|cleanup|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. ${tokenEfficientWorkPolicy} ${workExecutionPolicy} ${artifactLocalePolicy}`,
+    plan: `Utilisez la skill cairn-plan. Gardez MEMORY.md comme index et écrivez les plans détaillés dans docs/plan/<topic>.md. ${reasoningEffortPolicy} ${artifactLocalePolicy} ${planExecutionPolicy}`,
+    work: `Utilisez la skill cairn-work. Exécutez une tranche de module et capturez les preuves de module et de surface. ${tokenEfficientWorkPolicy} ${reasoningEffortPolicy} ${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",
+    usage: "Utilisation: cairn install|upgrade|doctor|uninstall|cleanup|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. ${tokenEfficientWorkPolicy} ${workExecutionPolicy} ${artifactLocalePolicy}`,
+    plan: `Verwenden Sie die Skill cairn-plan. Halten Sie MEMORY.md als Index und schreiben Sie Detailpläne nach docs/plan/<topic>.md. ${reasoningEffortPolicy} ${artifactLocalePolicy} ${planExecutionPolicy}`,
+    work: `Verwenden Sie die Skill cairn-work. Führen Sie einen Modulabschnitt aus und erfassen Sie Modul- und Oberflächenbelege. ${tokenEfficientWorkPolicy} ${reasoningEffortPolicy} ${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",
+    usage: "Verwendung: cairn install|upgrade|doctor|uninstall|cleanup|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. ${tokenEfficientWorkPolicy} ${workExecutionPolicy} ${artifactLocalePolicy}`,
+    plan: `Use a skill cairn-plan. Mantenha MEMORY.md como índice e escreva planos detalhados em docs/plan/<topic>.md. ${reasoningEffortPolicy} ${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. ${tokenEfficientWorkPolicy} ${reasoningEffortPolicy} ${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",
+    usage: "Uso: cairn install|upgrade|doctor|uninstall|cleanup|init|memory|plan|work|review|toolcheck|goal|task",
   },
 };