cairn-ai 0.2.5 → 0.2.7

package/scripts/cairn-paths.mjs

@@ -1,9 +1,55 @@
-import { existsSync } from "node:fs";
-import { dirname, join, resolve } from "node:path";
+import { createHash } from "node:crypto";
+import { existsSync, lstatSync, readFileSync, realpathSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, relative, 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)), "..");
 }
@@ -87,12 +133,42 @@ export function createRuntimeLocator(pluginRoot) {
   };
 }
 
+const runtimeEntryRelativePaths = [
+  join("scripts", "cairn.mjs"),
+  join("scripts", "cairn-lifecycle.mjs"),
+  join("scripts", "cairn-state.mjs"),
+  join("scripts", "cairn-toolcheck.mjs"),
+  join("scripts", "cairn-goal.mjs"),
+  join("scripts", "cairn-cleanup.mjs"),
+];
+const localModuleSpecifier = /^(?:import|export)\s+(?:(?:\{[^}]*\}|\*\s+as\s+\w+|[\w$]+)(?:\s*,\s*(?:\{[^}]*\}|\*\s+as\s+\w+))?\s+from\s+)?["'](\.[^"']+)["']/gm;
+
+export function runtimeRequiredRelativePaths(pluginRoot) {
+  const root = resolve(pluginRoot);
+  const pending = runtimeEntryRelativePaths.map((path) => join(root, path));
+  const closure = new Set();
+
+  while (pending.length > 0) {
+    const path = pending.pop();
+    if (closure.has(path)) continue;
+    closure.add(path);
+    const source = readFileSync(path, "utf8");
+    for (const match of source.matchAll(localModuleSpecifier)) pending.push(resolve(dirname(path), match[1]));
+  }
+
+  return [...closure].map((path) => relative(root, path)).sort();
+}
+
 export function runtimeRequiredPaths(locator) {
-  if (!locator || locator.schemaVersion !== RUNTIME_LOCATOR_SCHEMA_VERSION || locator.plugin !== "cairn") return [];
+  if (!locator || locator.schemaVersion !== RUNTIME_LOCATOR_SCHEMA_VERSION || locator.plugin !== "cairn"
+      || typeof locator.pluginRoot !== "string") return [];
+  const root = locator.pluginRoot;
   return [
-    locator.entrypoints?.cli,
-    locator.entrypoints?.state,
-    locator.entrypoints?.toolcheck,
+    join(root, "package.json"),
+    join(root, ".codex-plugin", "plugin.json"),
+    join(root, "hooks", "hooks.json"),
+    ...runtimeRequiredRelativePaths(root).map((path) => join(root, path)),
+    join(root, "scripts", "release-integrity-0.2.2.json"),
     locator.resources?.commands,
     locator.resources?.agents,
     locator.resources?.skills,

package/scripts/cairn-safe-fs.mjs

@@ -1,6 +1,6 @@
 import { randomUUID } from "node:crypto";
 import { hostname } from "node:os";
-import { link, lstat, mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { lstat, mkdir, readFile, readdir, rename, rm, writeFile } from "node:fs/promises";
 import { dirname, join, relative, resolve, sep } from "node:path";
 
 const LOCK_SCHEMA_VERSION = 1;
@@ -100,7 +100,7 @@ export async function withStateLock(root, operation, {
     try {
       await safeWriteFile(workspaceRoot, lockPath, `${JSON.stringify(owner)}\n`, { encoding: "utf8", flag: "wx" });
       await testHooks.afterLockWritten?.({ lockPath, owner: structuredClone(owner) });
-      if (await confirmsLockOwnership(lockPath, owner.nonce)) break;
+      if (await confirmsUnclaimedLockOwnership(workspaceRoot, lockPath, owner.nonce)) break;
     } catch (error) {
       if (isTransientLockError(error)) {
         // Windows can briefly deny a lock file that another process is closing.
@@ -108,8 +108,8 @@ export async function withStateLock(root, operation, {
       } else if (error?.code === "EEXIST") {
         try {
           await testHooks.beforeContendedLockConfirmation?.({ lockPath });
-          if (await confirmsLockOwnership(lockPath, owner.nonce)) break;
-          const reclaimed = await reclaimStaleLock(workspaceRoot, lockPath, malformedStaleMs, testHooks);
+          if (await confirmsUnclaimedLockOwnership(workspaceRoot, lockPath, owner.nonce)) break;
+          const reclaimed = await reclaimStaleLock(workspaceRoot, lockPath, owner, malformedStaleMs, testHooks);
           if (reclaimed) continue;
         } catch (inspectionError) {
           if (!isTransientLockError(inspectionError)) throw inspectionError;
@@ -129,7 +129,7 @@ export async function withStateLock(root, operation, {
   }
 }
 
-async function reclaimStaleLock(root, lockPath, malformedStaleMs, testHooks) {
+async function reclaimStaleLock(root, lockPath, owner, malformedStaleMs, testHooks) {
   let observed;
   let stat;
   try {
@@ -140,44 +140,47 @@ async function reclaimStaleLock(root, lockPath, malformedStaleMs, testHooks) {
   }
   if (stat.isSymbolicLink()) throw symlinkError(lockPath);
   const record = parseLockRecord(observed);
-  if (record) {
-    if (record.hostname !== hostname()) return false;
-    if (pidIsAlive(record.pid)) return false;
-  } else if (Date.now() - stat.mtimeMs <= malformedStaleMs) {
-    return false;
-  }
+  if (!isReclaimableLock(record, stat, malformedStaleMs)) return false;
 
   await testHooks.afterStaleObserved?.({ lockPath, observed, record: record ? structuredClone(record) : null });
-  const quarantine = safePath(root, `.cairn/state.lock.stale.${record?.nonce ?? "malformed"}.${randomUUID()}`);
+  const claimPath = safePath(root, `.cairn/state.lock.reclaim.${owner.nonce}`);
+  await safeWriteFile(root, claimPath, `${JSON.stringify(owner)}\n`, { encoding: "utf8", flag: "wx" });
   try {
-    await rename(lockPath, quarantine);
-  } catch (error) {
-    if (error?.code === "ENOENT") return true;
-    throw error;
-  }
-  const moved = await readFile(quarantine, "utf8");
-  if (moved !== observed) {
-    const restored = await restoreMovedCandidate(lockPath, quarantine);
-    await testHooks.afterReclaimMismatch?.({ lockPath, restored });
-    return false;
-  }
-  await rm(quarantine, { force: true });
-  return true;
-}
+    await testHooks.afterReclaimInterlock?.({ lockPath });
+    let claimed;
+    let claimedStat;
+    try {
+      [claimed, claimedStat] = await Promise.all([readFile(lockPath, "utf8"), lstat(lockPath)]);
+    } catch (error) {
+      if (error?.code === "ENOENT") return true;
+      throw error;
+    }
+    if (claimedStat.isSymbolicLink()) throw symlinkError(lockPath);
+    const claimedRecord = parseLockRecord(claimed);
+    if (!isReclaimableLock(claimedRecord, claimedStat, malformedStaleMs)) return false;
 
-async function restoreMovedCandidate(lockPath, quarantine) {
-  try {
-    await link(quarantine, lockPath);
-    await rm(quarantine);
-    return true;
-  } catch (error) {
-    if (error?.code !== "EEXIST") throw error;
+    const quarantine = safePath(root, `.cairn/state.lock.stale.${claimedRecord?.nonce ?? "malformed"}.${randomUUID()}`);
+    try {
+      await rename(lockPath, quarantine);
+    } catch (error) {
+      if (error?.code === "ENOENT") return true;
+      throw error;
+    }
+    const movedStat = await lstat(quarantine);
     await rm(quarantine, { force: true });
-    return false;
+    return movedStat.dev === claimedStat.dev && movedStat.ino === claimedStat.ino;
+  } finally {
+    await releaseOwnedLock(claimPath, owner.nonce);
   }
 }
 
-async function confirmsLockOwnership(lockPath, nonce) {
+function isReclaimableLock(record, stat, malformedStaleMs) {
+  if (record) return record.hostname === hostname() && !pidIsAlive(record.pid);
+  return Date.now() - stat.mtimeMs > malformedStaleMs;
+}
+
+async function confirmsUnclaimedLockOwnership(root, lockPath, nonce) {
+  if (await activeReclaimClaimExists(root)) return false;
   try {
     return parseLockRecord(await readFile(lockPath, "utf8"))?.nonce === nonce;
   } catch (error) {
@@ -186,6 +189,29 @@ async function confirmsLockOwnership(lockPath, nonce) {
   }
 }
 
+async function activeReclaimClaimExists(root) {
+  const claimNames = (await readdir(safePath(root, ".cairn")))
+    .filter((name) => name.startsWith("state.lock.reclaim."));
+  for (const name of claimNames) {
+    const claimPath = safePath(root, `.cairn/${name}`);
+    let stat;
+    let record;
+    try {
+      [stat, record] = await Promise.all([lstat(claimPath), readFile(claimPath, "utf8").then(parseLockRecord)]);
+    } catch (error) {
+      if (error?.code === "ENOENT") continue;
+      throw error;
+    }
+    if (stat.isSymbolicLink()) throw symlinkError(claimPath);
+    if (record?.hostname === hostname() && !pidIsAlive(record.pid)) {
+      await releaseOwnedLock(claimPath, record.nonce);
+      continue;
+    }
+    return true;
+  }
+  return false;
+}
+
 async function releaseOwnedLock(lockPath, nonce) {
   for (let attempt = 0; attempt < 8; attempt += 1) {
     try {

package/scripts/cairn-state-context.mjs

@@ -0,0 +1,148 @@
+const contextLimits = {
+  goalTitle: 64,
+  roadmapTaskId: 24,
+  taskTitle: 40,
+  roadmapWindow: 3,
+};
+
+export 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}`,
+      },
+    },
+  };
+}
+
+export function contextResult({ ko, state, event }) {
+  const base = kernelBase(ko);
+  const idlePolicy = event === "user-prompt-submit"
+    ? (ko
+      ? " 비단순 구현이나 계획된 작업 재개는 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
+    ? " 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 === "paused" || state.goal.status === "blocked")) {
+    return interruptedContextResult(event, ko, state);
+  }
+  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")
+    ?? state.tasks.find((item) => item.status === "blocked");
+  const planId = state.goal.planId;
+  const phase = task ? "cairn-work" : "cairn-review";
+  const activeHeader = ko
+    ? `${base} ${phase}를 로드하고 정확한 plan ${planId}${task ? "과 아래 current task" : "의 완료 기준"}를 복원하세요. 압축·재시작·handoff·위임 뒤 다시 읽으세요.${failClosed}`
+    : `${base} Load ${phase}; restore exact plan ${planId}${task ? " and the current task below" : " completion criteria"}. Re-read after compaction/restart/handoff/delegation.${failClosed}`;
+  if (!task) {
+    return contextHookResult({
+      event,
+      message: [activeHeader, taskRoadmap(ko, state), activeGoalCompletionMessage(ko, state)].join("\n"),
+    });
+  }
+  const taskId = task.id;
+  const taskTitle = clipText(task.title, contextLimits.taskTitle);
+  const continuation = taskId.length > 48
+    ? (ko
+      ? `정확한 current task: ${taskId}. 바인딩된 증거 뒤에만 완료하세요.`
+      : `Exact task: ${taskId}. Complete after bound evidence.`)
+    : (ko
+      ? `현재: ${taskId} (${taskTitle}). 바인딩된 증거 뒤에만 완료하세요.`
+      : `Current: ${taskId} (${taskTitle}). Complete only after bound evidence.`);
+  const resume = event === "user-prompt-submit"
+    ? (taskId.length > 48
+      ? (ko
+        ? "곁가지 질문 뒤 일시정지·중단·전환 요청이 없으면 위의 정확한 task를 재개하세요."
+        : "Resume that exact task after side questions unless paused, stopped, or switched.")
+      : (ko
+        ? `곁가지 질문 뒤 일시정지·중단·전환 요청이 없으면 ${taskId}를 재개하세요.`
+        : `After a side question, resume ${taskId} unless asked to pause, stop, or switch.`))
+    : "";
+  return contextHookResult({ event, message: [activeHeader, taskRoadmap(ko, state), continuation, resume].filter(Boolean).join("\n") });
+}
+
+function kernelBase(ko) {
+  return ko ? "Cairn kernel: 루트 MEMORY.md는 선택 사항이며, 있으면 읽으세요." : "Cairn kernel: root MEMORY.md is optional; read it when present.";
+}
+
+function interruptedContextResult(event, ko, state) {
+  const task = state.tasks.find((item) => item.status === "active")
+    ?? state.tasks.find((item) => item.status === "pending")
+    ?? state.tasks.find((item) => item.status === "blocked");
+  const taskContext = task
+    ? (ko
+      ? `현재 task: ${task.id} (${clipText(task.title, contextLimits.taskTitle)}), 상태 ${task.status}.`
+      : `Current task: ${task.id} (${clipText(task.title, contextLimits.taskTitle)}), status ${task.status}.`)
+    : (ko ? "현재 task: 없음." : "Current task: none.");
+  const blocker = state.goal.blocker ?? task?.blocker ?? (ko ? "없음" : "none");
+  const recovery = ko
+    ? "자동으로 재개하지 마세요. 정확한 context를 복원하고 원인을 처리한 뒤 명시적으로 resume하세요."
+    : "Do not resume automatically. Restore this exact context, address the interruption, then resume explicitly.";
+  const message = ko
+    ? `${kernelBase(ko)} 정확한 plan: ${state.goal.planId}. ${taskContext} Goal 상태: ${state.goal.status}. Blocker: ${blocker}. ${recovery}`
+    : `${kernelBase(ko)} Exact plan: ${state.goal.planId}. ${taskContext} Goal status: ${state.goal.status}. Blocker: ${blocker}. ${recovery}`;
+  return contextHookResult({ event, message });
+}
+
+export function foreignSessionContextResult({ ko, event }) {
+  const message = ko
+    ? "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 });
+}
+
+function taskRoadmap(ko, state) {
+  const formatTask = (task, index) => `${index + 1}. ${clipText(task.id, contextLimits.roadmapTaskId)} [${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 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 - 1;
+  const header = ko
+    ? `작업 단계 (${state.tasks.length}개; ${countSummary})`
+    : `Work steps (${state.tasks.length}; ${countSummary})`;
+  const omission = ko ? `… ${omitted}개 단계 생략` : `… ${omitted} steps omitted`;
+  const currentPosition = currentIndex + 1;
+  return `${header}. ${ko ? `현재 위치 ${currentPosition}` : `Current position ${currentPosition}`}; ${omission}`;
+}
+
+function contextHookResult({ event, message }) {
+  return {
+    status: 0,
+    message,
+    hookOutput: {
+      hookSpecificOutput: {
+        hookEventName: event === "session-start" ? "SessionStart" : "UserPromptSubmit",
+        additionalContext: message,
+      },
+    },
+  };
+}
+
+function activeGoalCompletionMessage(ko, state) {
+  const goalTitle = clipText(state.goal.title, contextLimits.goalTitle);
+  return ko
+    ? `활성 목표 "${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)}…`;
+}

package/scripts/cairn-state-hook.mjs

@@ -0,0 +1,24 @@
+export function continuationReason(reason, payload) {
+  const continuation = payload?.stop_hook_active ? " This turn was already continued; the active goal remains persisted for the next session." : "";
+  return `${reason}${continuation}`;
+}
+
+export function stopHookOutput(gate, payload) {
+  if (!gate.block) return { continue: true };
+  const reason = continuationReason(gate.reason, payload);
+  if (payload?.stop_hook_active) {
+    return { continue: true, systemMessage: reason };
+  }
+  return { decision: "block", reason };
+}
+
+export function stopAllowedMessage({ ko, state, event }) {
+  if (state?.goal?.status) {
+    return ko
+      ? `Cairn 종료 게이트: 목표 상태가 ${state.goal.status}이므로 종료를 허용합니다.`
+      : `Cairn stop gate: goal status is ${state.goal.status}; allowing stop.`;
+  }
+  return ko
+    ? `${event === "subagent-stop" ? "서브에이전트" : "작업"} 종료 게이트: 활성 Cairn 목표가 없어 종료를 허용합니다.`
+    : `${event === "subagent-stop" ? "Subagent" : "Turn"} stop gate: no active Cairn goal; allowing stop.`;
+}

package/scripts/cairn-state-init.mjs

@@ -0,0 +1,137 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { assertNoSymlinkComponents, safeMkdir, safeWriteFile } from "./cairn-safe-fs.mjs";
+
+const memoryTemplate = `# MEMORY
+
+This file is a short index of persistent repository knowledge.
+
+## Domain Knowledge
+
+- Link detailed notes under \`docs/memory/\`.
+
+## Policy
+
+- Prefer precise repository exploration before implementation.
+- Preserve proper nouns, file names, variable names, service names, alert names, MCP tool names, and agent names exactly as written.
+- Read only the detailed memory files needed for the current task.
+- Write user-visible responses and generated or updated documentation, plans, and memory artifacts in the OS locale unless the user asks for another language.
+
+## Update Rules
+
+- Keep root files short.
+- Move detailed domain knowledge to \`docs/memory/<domain>.md\`.
+- Record facts with source paths, commands, and observed behavior.
+`;
+
+const memoryTemplateKo = `# MEMORY
+
+이 파일은 지속적으로 필요한 저장소 지식의 짧은 색인입니다.
+
+## Domain Knowledge
+
+- 자세한 기록은 \`docs/memory/\` 아래에 연결합니다.
+
+## Policy
+
+- 구현 전에는 저장소를 정확히 탐색합니다.
+- 고유명사, 파일 이름, 변수 이름, 서비스 이름, 알림 이름, MCP 도구 이름, 에이전트 이름은 쓰인 그대로 보존합니다.
+- 현재 작업에 필요한 상세 메모리 파일만 읽습니다.
+- 사용자가 다른 언어를 요청하지 않는 한, 사용자에게 보이는 응답과 생성 또는 갱신하는 문서, 계획, 메모리 산출물은 OS locale 언어로 작성합니다.
+
+## Update Rules
+
+- 루트 파일은 짧게 유지합니다.
+- 자세한 도메인 지식은 \`docs/memory/<domain>.md\`로 옮깁니다.
+- 사실은 출처 경로, 명령, 관찰된 동작과 함께 기록합니다.
+`;
+
+const planTemplate = `# PLAN
+
+This file is a short index of active and completed work plans.
+
+## Active Plans
+
+- Link detailed plans under \`docs/plan/\`.
+
+## Completed Plans
+
+- Move completed topics here with evidence links.
+
+## Planning Rules
+
+- 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.
+- Each task normally passes exactly two gates.
+  - Module acceptance verification.
+  - Surface integration verification.
+- Run dry-run or check mode before external-state mutation when available.
+- Write user-visible responses and generated or updated documentation, plans, and memory artifacts in the OS locale unless the user asks for another language.
+- Use at most two verification passes per task by default.
+- If a gate fails, diagnose once, shrink the task or split it into sub-tasks, and rerun both gates.
+- After two failed passes, record the blocker in \`docs/plan/<topic>.md\`.
+`;
+
+const planTemplateKo = `# PLAN
+
+이 파일은 진행 중이거나 완료된 작업 계획의 짧은 색인입니다.
+
+## Active Plans
+
+- 상세 계획은 \`docs/plan/\` 아래에 연결합니다.
+
+## Completed Plans
+
+- 완료된 주제는 증거 링크와 함께 이곳으로 옮깁니다.
+
+## Planning Rules
+
+- 프로젝트 루트 \`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 도구를 감지합니다.
+- 필요한 도구가 없으면 누락 상태와 제안 명령을 기록합니다. 명시적 사용자 승인 뒤에만 고정된 지원 설치 단계를 실행합니다.
+- 각 작업은 보통 정확히 두 게이트를 통과합니다.
+  - 모듈 수용 검증.
+  - 표면 통합 검증.
+- 외부 상태 변경 전에는 가능한 경우 dry-run 또는 check mode를 실행합니다.
+- 사용자가 다른 언어를 요청하지 않는 한, 사용자에게 보이는 응답과 생성 또는 갱신하는 문서, 계획, 메모리 산출물은 OS locale 언어로 작성합니다.
+- 기본적으로 작업당 검증은 최대 두 번만 수행합니다.
+- 게이트가 실패하면 한 번 진단하고, 작업을 줄이거나 sub-task로 나눈 뒤 두 게이트를 다시 실행합니다.
+- 두 번 실패한 뒤에는 blocker를 \`docs/plan/<topic>.md\`에 기록합니다.
+`;
+
+export async function initializeProject(root, ko) {
+  await safeMkdir(root, "docs/memory");
+  await safeMkdir(root, "docs/plan");
+  await writeIfMissing(root, join(root, "MEMORY.md"), ko ? memoryTemplateKo : memoryTemplate);
+  await writeIfMissing(root, join(root, "PLAN.md"), ko ? planTemplateKo : planTemplate);
+}
+
+async function writeIfMissing(root, path, content) {
+  await assertNoSymlinkComponents(root, path);
+  try {
+    await readFile(path, "utf8");
+  } catch (error) {
+    if (error?.code !== "ENOENT") throw error;
+    try {
+      await safeWriteFile(root, path, content, { encoding: "utf8", flag: "wx" });
+    } catch (writeError) {
+      if (writeError?.code !== "EEXIST") throw writeError;
+      await assertNoSymlinkComponents(root, path, { allowMissing: false });
+    }
+  }
+}