@spectrabrain/eds 0.3.0 → 0.3.1

package/consumer/align-plan.mjs

@@ -1,22 +1,81 @@
-import { conventionsFileName, edsLucideVersion, installRanges, mockDevDependencies, templateDevDependencies } from "./align-rules.mjs";
+import {
+  conventionsFileName,
+  edsLucideVersion,
+  installRanges,
+  maximumSupportedViteMajor,
+  minimumPluginReactVersion,
+  minimumTailwindViteVersion,
+  minimumVersions,
+  rolldownBabelPackage,
+  stateFileName,
+  templateDevDependencies,
+} from "./align-rules.mjs";
 import { cliCommand, runnerCommand } from "./paths.mjs";
 
 const installPrefixes = {
-  npm: { add: "npm install", dev: "npm install -D", remove: "npm uninstall", dlx: "npx", exec: "npx" },
-  pnpm: { add: "pnpm add", dev: "pnpm add -D", remove: "pnpm remove", dlx: "pnpm dlx", exec: "pnpm exec" },
-  yarn: { add: "yarn add", dev: "yarn add -D", remove: "yarn remove", dlx: "yarn dlx", exec: "yarn" },
-  bun: { add: "bun add", dev: "bun add -d", remove: "bun remove", dlx: "bunx", exec: "bunx" },
+  npm: {
+    add: "npm install",
+    dev: "npm install -D",
+    remove: "npm uninstall",
+    dlx: "npx",
+  },
+  pnpm: {
+    add: "pnpm add",
+    dev: "pnpm add -D",
+    remove: "pnpm remove",
+    dlx: "pnpm dlx",
+  },
+  yarn: {
+    add: "yarn add",
+    dev: "yarn add -D",
+    remove: "yarn remove",
+    dlx: "yarn dlx",
+  },
+  bun: { add: "bun add", dev: "bun add -d", remove: "bun remove", dlx: "bunx" },
 };
 
-// @vitejs/plugin-react 6 requires Vite 8; 4 still covers Vite 4–7 on Node 18.
+// The Babel template uses a plugin-react release whose peer range covers the selected Vite major.
 export function pluginReactRange(viteMajor) {
-  return viteMajor !== null && viteMajor >= 8 ? "^6" : "^4";
+  if (viteMajor !== null && viteMajor > maximumSupportedViteMajor) {
+    throw new RangeError(
+      "eds align supports Vite 5.2.0–" + maximumSupportedViteMajor + ".x only."
+    );
+  }
+  return viteMajor === 8
+    ? "^" + minimumVersions.pluginReactForVite8
+    : "^" + minimumPluginReactVersion(viteMajor);
 }
 
-export function packageManagerCommands(packageManager, { viteMajor = null } = {}) {
+export function packageManagerCommands(
+  packageManager,
+  { viteMajor = null } = {}
+) {
   const prefixes = installPrefixes[packageManager?.name] ?? installPrefixes.npm;
-  const dlx = packageManager?.name === "yarn" && !packageManager.berry ? "npx" : prefixes.dlx;
-  const ranges = { ...installRanges, "@vitejs/plugin-react": pluginReactRange(viteMajor), ...(edsLucideVersion ? { "lucide-react": edsLucideVersion } : {}) };
+  const dlx =
+    packageManager?.name === "yarn" && !packageManager.berry
+      ? "npx"
+      : prefixes.dlx;
+  const exec =
+    packageManager?.name === "pnpm"
+      ? "pnpm exec"
+      : packageManager?.name === "yarn"
+      ? "yarn"
+      : packageManager?.name === "bun"
+      ? "bunx"
+      : "npx";
+  const ranges = {
+    ...installRanges,
+    vite:
+      viteMajor === 8
+        ? "^8"
+        : installRanges.vite,
+    "@vitejs/plugin-react": pluginReactRange(viteMajor),
+    "@tailwindcss/vite":
+      minimumTailwindViteVersion(viteMajor) !== null
+        ? "^" + minimumTailwindViteVersion(viteMajor)
+        : installRanges["@tailwindcss/vite"],
+    ...(edsLucideVersion ? { "lucide-react": edsLucideVersion } : {}),
+  };
   const withRange = (name) => (ranges[name] ? name + "@" + ranges[name] : name);
   return {
     run: (script) => runnerCommand(packageManager, script),
@@ -25,12 +84,25 @@ export function packageManagerCommands(packageManager, { viteMajor = null } = {}
     remove: (names) => prefixes.remove + " " + names.join(" "),
     eds: (args) => cliCommand(packageManager, args),
     dlx: (command) => dlx + " " + command,
-    // A binary of an installed package (for example msw init).
-    exec: (command) => prefixes.exec + " " + command,
+    exec: (command) => exec + " " + command,
   };
 }
 
-const kindOrder = ["protected", "outside", "backend-script", "backend-dependency", "structure", "language", "import", "dependency", "config", "script", "pattern", "agents"];
+const kindOrder = [
+  "protected",
+  "preserved",
+  "outside",
+  "backend-script",
+  "backend-dependency",
+  "structure",
+  "language",
+  "import",
+  "dependency",
+  "config",
+  "script",
+  "pattern",
+  "agents",
+];
 
 export function countFindings(findings) {
   const errors = new Map();
@@ -39,9 +111,19 @@ export function countFindings(findings) {
     const counts = finding.level === "error" ? errors : warnings;
     counts.set(finding.kind, (counts.get(finding.kind) ?? 0) + 1);
   }
-  const format = (counts) => kindOrder.filter((kind) => counts.has(kind)).map((kind) => kind + " " + counts.get(kind)).join(", ");
-  const total = (counts) => [...counts.values()].reduce((sum, count) => sum + count, 0);
-  return { errors: total(errors), warnings: total(warnings), errorSummary: format(errors), warningSummary: format(warnings) };
+  const format = (counts) =>
+    kindOrder
+      .filter((kind) => counts.has(kind))
+      .map((kind) => kind + " " + counts.get(kind))
+      .join(", ");
+  const total = (counts) =>
+    [...counts.values()].reduce((sum, count) => sum + count, 0);
+  return {
+    errors: total(errors),
+    warnings: total(warnings),
+    errorSummary: format(errors),
+    warningSummary: format(warnings),
+  };
 }
 
 function code(text) {
@@ -76,7 +158,9 @@ export function renderNotes() {
     "## 진행",
     "",
     "- commit: (1단계에서 `허용` 또는 `안 함`으로 적습니다)",
-    "- 완료한 단계: 0 / " + stepCount + " (단계의 완료 기준을 모두 만족한 뒤에만 번호를 올립니다)",
+    "- 완료한 단계: 0 / " +
+      stepCount +
+      " (단계의 완료 기준을 모두 만족한 뒤에만 번호를 올립니다)",
     "",
     "## 기준선",
     "",
@@ -84,6 +168,8 @@ export function renderNotes() {
     "",
     "## 보호 경로 확인",
     "",
+    "## 기존 리소스 확인",
+    "",
     "## 단계별 기록",
     "",
     "## 보류 사항",
@@ -96,105 +182,283 @@ function numbered(items) {
 }
 
 // PLAN.md: the facts of this repository and the ordered steps. The rules themselves live in FRONTEND_CONVENTIONS.md.
-export function renderPlan({ version, createdAt, base, packageManager, frontend, analysis, templates, alignLabel, conventionsPath = null }) {
+export function renderPlan({
+  version,
+  createdAt,
+  base,
+  packageManager,
+  frontend,
+  analysis,
+  templates,
+  alignLabel,
+  conventionsPath = null,
+}) {
   const { app, dependencies, protectedInfo, majors } = analysis;
-  const commands = packageManagerCommands(packageManager, { viteMajor: majors.vite });
+  const commands = packageManagerCommands(packageManager, {
+    viteMajor: majors.vite,
+  });
   const alignCheck = commands.eds("align --check");
   const counts = countFindings(analysis.findings);
-  const packageLabel = frontend.packageRelative === "" ? "repository root" : code(frontend.packageRelative);
-  const conventions = conventionsPath === null ? "EDS package root의 " + code(conventionsFileName) : code(conventionsPath);
-  const findingsOf = (kinds) => analysis.findings.filter((finding) => kinds.includes(finding.kind));
+  const packageLabel =
+    frontend.packageRelative === ""
+      ? "repository root"
+      : code(frontend.packageRelative);
+  const conventions =
+    conventionsPath === null
+      ? "EDS package root의 " + code(conventionsFileName)
+      : code(conventionsPath);
+  const findingsOf = (kinds) =>
+    analysis.findings.filter((finding) => kinds.includes(finding.kind));
   const scripts = analysis.packageJson?.scripts ?? {};
 
   const protectedRows = protectedInfo.inside.map((entry) => [
     code(entry),
-    entry === "shared" ? "backend와 프론트엔드가 함께 쓰는 코드(import 허용, 수정 금지)" : "backend·배포 코드 또는 설정",
+    entry === "shared"
+      ? "backend와 프론트엔드가 함께 쓰는 코드(import 허용, 수정 금지)"
+      : "backend·배포 코드 또는 설정",
   ]);
   if (frontend.packageRelative !== "") {
-    protectedRows.push(["프론트엔드 package 밖 전체", "다른 package와 backend" + (protectedInfo.repositoryOnly.length > 0 ? "(" + protectedInfo.repositoryOnly.map(code).join(", ") + " 포함)" : "")]);
+    protectedRows.push([
+      "프론트엔드 package 밖 전체(저장소 루트 lockfile 제외)",
+      "다른 package와 backend" +
+        (protectedInfo.repositoryOnly.length > 0
+          ? "(" + protectedInfo.repositoryOnly.map(code).join(", ") + " 포함)"
+          : ""),
+    ]);
   }
-  const backendScriptEntries = Object.entries(protectedInfo.backendScripts ?? {});
-  const backendScripts = backendScriptEntries.map(([name, command]) => code(name) + ": " + code(command));
+  const backendScriptEntries = Object.entries(
+    protectedInfo.backendScripts ?? {}
+  );
+  const backendScripts = backendScriptEntries.map(
+    ([name, command]) => code(name) + ": " + code(command)
+  );
 
   const structureRows = analysis.structure.map((entry) => [
     code(entry.name + (entry.type === "directory" ? "/" : "")),
     String(entry.files),
-    entry.hint ?? (entry.fsd ? "FSD 위치입니다. 하위 규칙은 check 경고를 따릅니다." : "역할을 보고 app·pages·widgets·features·entities·shared 중 한 곳으로 옮깁니다."),
+    entry.hint ??
+      (entry.fsd
+        ? "FSD 위치입니다. 하위 규칙은 check 경고를 따릅니다."
+        : "역할을 보고 app·pages·widgets·features·entities·shared 중 한 곳으로 옮깁니다."),
   ]);
 
-  const replacementRows = dependencies.replacements.filter((entry) => !entry.keptForBackend).map((entry) => [
-    entry.category,
-    code(entry.name),
-    entry.target === "lucide-react" ? entry.label + "(" + code(commands.add(["lucide-react"])) + ")" : entry.label,
+  const replacementRows = dependencies.replacements
+    .filter((entry) => !entry.keptForBackend)
+    .map((entry) => [
+      entry.category,
+      code(entry.name),
+      entry.target === "lucide-react"
+        ? entry.label + "(" + code(commands.add(["lucide-react"])) + ")"
+        : entry.label,
+    ]);
+  const keptForBackend = dependencies.replacements
+    .filter((entry) => entry.keptForBackend)
+    .map((entry) => code(entry.name));
+  const replacedCategories = new Set(
+    replacementRows.map(([category]) => category)
+  );
+  const viteCompilerPeerPackages = new Set([
+    rolldownBabelPackage,
+    "babel-plugin-react-compiler",
+    "@babel/core",
   ]);
-  const keptForBackend = dependencies.replacements.filter((entry) => entry.keptForBackend).map((entry) => code(entry.name));
-  const replacedCategories = new Set(replacementRows.map(([category]) => category));
-  const reactOutdated = dependencies.outdated.find((entry) => entry.name === "react") ?? null;
-  const laterUpgrades = dependencies.outdated.filter((entry) => entry.name !== "react" && entry.name !== "tailwindcss");
+  const reactOutdated =
+    dependencies.outdated.find((entry) => entry.name === "react") ?? null;
+  const pluginReactOutdated =
+    dependencies.outdated.find(
+      (entry) => entry.name === "@vitejs/plugin-react"
+    ) ?? null;
+  const viteOutdated =
+    dependencies.outdated.find((entry) => entry.name === "vite") ?? null;
+  const tailwindViteOutdated =
+    dependencies.outdated.find((entry) => entry.name === "@tailwindcss/vite") ??
+    null;
+  const viteMissing = dependencies.missing.some((entry) => entry.name === "vite");
+  const reactMigrationTargets = analysis.reactMigrationTargets ?? [];
+  const laterUpgrades = dependencies.outdated.filter(
+    (entry) =>
+      entry.name !== "react" &&
+      entry.name !== "tailwindcss" &&
+      entry.name !== "@vitejs/plugin-react" &&
+      entry.name !== "vite" &&
+      entry.name !== "@tailwindcss/vite" &&
+      !viteCompilerPeerPackages.has(entry.name)
+  );
   const upgrades = dependencies.outdated.map((entry) => {
-    const step = entry.name === "react" || entry.name === "tailwindcss" ? "2단계" : "4단계";
-    return "- " + code(entry.name) + " " + entry.major + " → " + entry.minimum + " (" + step + ")";
+    const step =
+      viteCompilerPeerPackages.has(entry.name)
+        ? "3단계"
+        : entry.name === "react" ||
+          entry.name === "tailwindcss" ||
+          entry.name === "@vitejs/plugin-react" ||
+          entry.name === "vite" ||
+          entry.name === "@tailwindcss/vite"
+        ? "2단계"
+        : "4단계";
+    return (
+      "- " +
+      code(entry.name) +
+      " " +
+      (entry.version ?? entry.major) +
+      " → " +
+      (entry.allowedRange ?? entry.minimum) +
+      " (" +
+      step +
+      ")"
+    );
   });
-  const missingRuntime = dependencies.missing.filter((entry) => !entry.dev && entry.name !== "@spectrabrain/eds").map((entry) => entry.name);
+  const missingRuntime = dependencies.missing
+    .filter((entry) => !entry.dev && entry.name !== "@spectrabrain/eds")
+    .map((entry) => entry.name);
   // Step 2 already installs Tailwind and, when React is upgraded, the React 19 types.
-  const installedInStep2 = new Set(["tailwindcss", "@tailwindcss/vite", ...(dependencies.outdated.some((entry) => entry.name === "react") ? ["@types/react", "@types/react-dom"] : [])]);
+  const installedInStep2 = new Set([
+    "vite",
+    "tailwindcss",
+    "@tailwindcss/vite",
+    ...(dependencies.outdated.some((entry) => entry.name === "react")
+      ? ["@types/react", "@types/react-dom"]
+      : []),
+  ]);
   const missingDev = [
-    ...dependencies.missing.filter((entry) => entry.dev && !installedInStep2.has(entry.name)).map((entry) => entry.name),
-    ...templateDevDependencies.filter((name) => !analysis.declared.has(name) && !(dependencies.sdkOnly && name === "msw")),
+    ...dependencies.missing
+      .filter((entry) => entry.dev && !installedInStep2.has(entry.name))
+      .map((entry) => entry.name),
+    ...templateDevDependencies.filter((name) => !analysis.declared.has(name)),
     ...(dependencies.outdatedTools ?? []).map((entry) => entry.name),
+    ...dependencies.outdated
+      .filter((entry) => entry.compilerPeer)
+      .map((entry) => entry.name),
   ];
   const edsDeclared = analysis.declared.has("@spectrabrain/eds");
   const tailwindMajor = majors.tailwindcss;
   const viteLabel = majors.vite === null ? "Vite" : "Vite " + majors.vite;
+  const tailwindViteMinimum = minimumTailwindViteVersion(majors.vite);
   const reactLabel = majors.react === null ? "React" : "React " + majors.react;
-  const configFindings = findingsOf(["config", "script"]).map((finding) => "- " + finding.message);
+  const configFindings = findingsOf(["config", "script"]).map(
+    (finding) => "- " + finding.message
+  );
   const importedFrontend = protectedInfo.importedFrontendFiles.map(code);
-  const backendImportsViteConfig = protectedInfo.importedFrontendFiles.some((file) => /^vite\.config\.[cm]?[jt]s$/.test(file));
-  const backendStartScript = backendScriptEntries.find(([name]) => name === "start")?.[0] ?? backendScriptEntries[0]?.[0] ?? null;
+  const backendImportsViteConfig = protectedInfo.importedFrontendFiles.some(
+    (file) => /^vite\.config\.[cm]?[jt]s$/.test(file)
+  );
+  const backendStartScript =
+    backendScriptEntries.find(([name]) => name === "start")?.[0] ??
+    backendScriptEntries[0]?.[0] ??
+    null;
   const appPrefix = app.appDir === "." ? "" : app.appDir + "/";
-  const entryLabel = app.entry === null ? appPrefix + "index.html" : appPrefix + app.entry.replace(/^\//, "");
-  const templatesOf = (relativePath) => code(alignLabel + "/templates/" + relativePath);
+  const entryLabel =
+    app.entry === null
+      ? appPrefix + "index.html"
+      : appPrefix + app.entry.replace(/^\//, "");
+  const templatesOf = (relativePath) =>
+    code(alignLabel + "/templates/" + relativePath);
   // Config templates are the files outside the source and public trees; package.scripts.json is merged, not copied.
-  const configTemplates = templates.filter((target) => !(dependencies.sdkOnly && target.endsWith(".env.mock")) &&
-    target !== "package.scripts.json" && !target.startsWith(app.srcDir + "/") && !target.startsWith(appPrefix + "public/") &&
-    !target.startsWith("public/")).map(code);
+  const configTemplates = templates
+    .filter(
+      (target) =>
+        target !== "package.scripts.json" &&
+        !target.startsWith(app.srcDir + "/") &&
+        !target.startsWith(appPrefix + "public/") &&
+        !target.startsWith("public/")
+    )
+    .map(code);
   const srcPath = (relativePath) => app.srcDir + "/" + relativePath;
   const sdkClients = dependencies.dataClients ?? [];
   const uiDependents = dependencies.uiDependents ?? [];
-  const inProgressAgentsLine = "- " + alignLabel + "/PLAN.md가 있으면 작업 전에 PLAN.md와 NOTES.md를 읽고 「진행」의 다음 단계부터 이어갑니다.";
+  const preservedDependents = dependencies.preservedDependents ?? [];
+  const inProgressAgentsLine =
+    "- " +
+    alignLabel +
+    "/PLAN.md가 있으면 작업 전에 PLAN.md와 NOTES.md를 읽고 「진행」의 다음 단계부터 이어갑니다.";
 
   return [
     "# EDS align 계획",
     "",
-    "<!-- @spectrabrain/eds@" + version + " eds align이 생성했습니다. 다시 실행하면 이 파일과 templates/를 새로 씁니다. -->",
-    "",
-    "이 문서는 `eds align`이 이 저장소를 분석해 만든 일회성 작업 계획입니다. AI 에이전트는 이 계획의 단계를 순서대로 진행해 프론트엔드를 EVA 프론트엔드 컨벤션에 맞춥니다. 규칙의 원천은 " + conventions + "이며, 이 문서는 이 저장소에 해당하는 사실과 순서만 담습니다.",
-    "",
-    "- 기준 commit: " + code(base.slice(0, 12)) + " (" + createdAt.slice(0, 10) + " 생성)",
-    "- 프론트엔드 package: " + packageLabel + " · " + viteLabel + " · " + reactLabel + " · 패키지 매니저 " + packageManager.name,
-    "- 작업 디렉터리: " + code(frontend.packageRelative || ".") + "(git root 기준). 이 문서의 모든 명령은 이 디렉터리에서 실행합니다.",
-    "- 소스 디렉터리: " + code(app.srcDir) + " · Vite root(`index.html`): " + code(app.appDir),
-    "- 검증: " + code(alignCheck) + "(이하 check)는 기준 commit 이후의 보호 경로 변경과 구조·import·의존성·설정·script를 점검합니다. 1~5단계에서는 각 단계 완료 기준에 적힌 종류의 줄만 사라지면 되고, exit 0은 6단계부터 요구합니다.",
-    "- 작업 기록: " + code(alignLabel + "/NOTES.md") + "에 진행, 기준선, domain 목록, 결정, 보류 사항을 적습니다.",
-    "- 템플릿: " + code(alignLabel + "/templates/") + "에 이 저장소의 경로로 채운 설정·소스 파일 " + templates.length + "개가 대상 경로 그대로 있습니다.",
-    "- 테스트: 테스트 파일·테스트 디렉터리·테스트 도구·설정은 제자리에 둡니다. 소스를 옮겨 깨진 테스트의 import 경로와 `jest.mock`·`vi.mock` 경로 문자열은 고치고, 그 밖의 원인으로 테스트 파일에서 나는 lint·typecheck 오류는 고치지 않고 NOTES.md에 적은 뒤 사용자에게 확인합니다. 옛 디렉터리에 테스트만 남아도 되며 check는 테스트 파일을 점검하지 않습니다.",
+    "<!-- @spectrabrain/eds@" +
+      version +
+      " eds align이 생성했습니다. 다시 실행하면 이 파일과 templates/를 새로 씁니다. -->",
+    "",
+    "이 문서는 `eds align`이 이 저장소를 분석해 만든 일회성 작업 계획입니다. AI 에이전트는 이 계획의 단계를 순서대로 진행해 프론트엔드를 EVA 프론트엔드 컨벤션에 맞춥니다. 규칙의 원천은 " +
+      conventions +
+      "이며, 이 문서는 이 저장소에 해당하는 사실과 순서만 담습니다.",
+    "",
+    "- 기준 commit: " +
+      code(base.slice(0, 12)) +
+      " (" +
+      createdAt.slice(0, 10) +
+      " 생성)",
+    "- 프론트엔드 package: " +
+      packageLabel +
+      " · " +
+      viteLabel +
+      " · " +
+      reactLabel +
+      " · 패키지 매니저 " +
+      packageManager.name,
+    "- 작업 디렉터리: " +
+      code(frontend.packageRelative || ".") +
+      "(git root 기준). 이 문서의 모든 명령은 이 디렉터리에서 실행합니다.",
+    "- 소스 디렉터리: " +
+      code(app.srcDir) +
+      " · Vite root(`index.html`): " +
+      code(app.appDir),
+    "- 검증: " +
+      code(alignCheck) +
+      "(이하 check)는 보호 경로, frontend package 밖의 변경(저장소 루트 lockfile 제외), 기준선에 있던 보존 파일의 수정·삭제, tsconfig 파일 삭제와 기준 항목 누락, 구조·import·의존성·설정·script를 점검합니다. 새 리소스 파일 추가는 오류가 아닙니다. 1~5단계에서는 각 단계 완료 기준에 적힌 종류의 줄만 사라지면 되고, exit 0은 6단계부터 요구합니다.",
+    "- 작업 기록: " +
+      code(alignLabel + "/NOTES.md") +
+      "에 진행, 기준선, domain 목록, 결정, 보류 사항을 적습니다.",
+    "- 템플릿: " +
+      code(alignLabel + "/templates/") +
+      "에 이 저장소의 경로로 채운 설정·소스 파일 " +
+      templates.length +
+      "개가 대상 경로 그대로 있습니다.",
+    "- 기존 테스트·mock·다국어 파일과 설정은 원래 위치와 내용 그대로 둡니다. 자동 감지되지 않는 경로는 `state.json`의 `preservedPaths`에 git 저장소 루트 기준으로 추가한 뒤 `eds align`을 다시 실행합니다. 계획 재생성은 기존 기준 commit과 NOTES.md를 유지하고, 새로 보존하는 파일을 기준선에 기록합니다. `check`는 기준선에 있던 보존 파일의 수정·삭제를 `preserved:` 오류로 보고하며 새 파일 추가는 허용합니다.",
+    "",
+    "## API 계약",
+    "",
+    "요청 URL·method·header·payload, 응답 해석, 인증 흐름, backend와 배포가 읽는 환경 변수 이름은 그대로 둡니다. check는 frontend service 코드의 요청·응답 의미를 비교하지 않으므로 수동으로 확인합니다.",
     "",
     "## 보호 경로",
     "",
     "아래 경로는 읽기만 합니다. check가 기준 commit 이후의 변경을 `protected:`·`outside:`로 보고합니다.",
     "",
     ...(protectedRows.length === 0
-      ? ["- 감지된 backend 경로가 없습니다. backend가 다른 저장소에 있거나 이 package가 프론트엔드 전용인지 1단계에서 확인합니다.", ""]
+      ? [
+          "- 감지된 backend 경로가 없습니다. backend가 다른 저장소에 있거나 이 package가 프론트엔드 전용인지 1단계에서 확인합니다.",
+          "",
+        ]
       : table(["경로", "이유"], protectedRows)),
-    "- API 계약을 유지합니다. 요청 URL·method·header·payload, 응답 해석, 인증 흐름, backend와 배포가 읽는 환경 변수 이름은 그대로 두고, 코드를 옮겨도 같은 요청을 보냅니다.",
-    ...(backendScripts.length > 0 ? ["- backend를 실행하는 script는 그대로 둡니다: " + backendScripts.join(", ")] : []),
-    ...(protectedInfo.backendUsed.length > 0 ? ["- backend 코드가 쓰는 의존성은 package.json에서 지우지 않습니다: " + protectedInfo.backendUsed.map(code).join(", ")] : []),
-    ...(importedFrontend.length > 0 ? ["- backend 코드가 import하는 프론트엔드 파일은 export 형태를 유지합니다: " + importedFrontend.join(", ")] : []),
+    ...(backendScripts.length > 0
+      ? [
+          "- backend를 실행하는 script는 그대로 둡니다: " +
+            backendScripts.join(", "),
+        ]
+      : []),
+    ...(protectedInfo.backendUsed.length > 0
+      ? [
+          "- backend 코드가 쓰는 의존성은 package.json에서 지우지 않습니다: " +
+            protectedInfo.backendUsed.map(code).join(", "),
+        ]
+      : []),
+    ...(importedFrontend.length > 0
+      ? [
+          "- backend 코드가 import하는 프론트엔드 파일은 export 형태를 유지합니다: " +
+            importedFrontend.join(", "),
+        ]
+      : []),
     "",
     "## 현재 상태",
     "",
-    "check 기준 오류 " + counts.errors + "개" + (counts.errorSummary ? "(" + counts.errorSummary + ")" : "") +
-      ", 경고 " + counts.warnings + "개" + (counts.warningSummary ? "(" + counts.warningSummary + ")" : "") + "입니다.",
+    "check 기준 오류 " +
+      counts.errors +
+      "개" +
+      (counts.errorSummary ? "(" + counts.errorSummary + ")" : "") +
+      ", 경고 " +
+      counts.warnings +
+      "개" +
+      (counts.warningSummary ? "(" + counts.warningSummary + ")" : "") +
+      "입니다.",
     "",
     "### 구조 (" + code(app.srcDir) + ")",
     "",
@@ -202,16 +466,50 @@ export function renderPlan({ version, createdAt, base, packageManager, frontend,
     "### 의존성",
     "",
     ...(replacementRows.length > 0
-      ? ["교체할 라이브러리입니다(4단계).", "", ...table(["범주", "패키지", "대체"], replacementRows)]
-      : keptForBackend.length > 0 ? [] : ["교체할 라이브러리가 없습니다.", ""]),
+      ? [
+          "교체할 라이브러리입니다(4단계).",
+          "",
+          ...table(["범주", "패키지", "대체"], replacementRows),
+        ]
+      : keptForBackend.length > 0
+      ? []
+      : ["교체할 라이브러리가 없습니다.", ""]),
     ...(keptForBackend.length > 0
-      ? ["backend 코드도 쓰는 교체 대상입니다. 패키지는 package.json에 남기고 프론트엔드 코드의 사용만 대체 라이브러리로 옮기며, backend가 import하는 파일은 그대로 둡니다(4단계): " + keptForBackend.join(", "), ""]
+      ? [
+          "backend 코드도 쓰는 교체 대상입니다. 패키지는 package.json에 남기고 프론트엔드 코드의 사용만 대체 라이브러리로 옮기며, backend가 import하는 파일은 그대로 둡니다(4단계): " +
+            keptForBackend.join(", "),
+          "",
+        ]
+      : []),
+    ...(upgrades.length > 0
+      ? ["업그레이드할 라이브러리입니다.", "", ...upgrades, ""]
       : []),
-    ...(upgrades.length > 0 ? ["업그레이드할 라이브러리입니다.", "", ...upgrades, ""] : []),
     ...(dependencies.backendClients.length > 0
-      ? ["backend client SDK는 교체하지 않습니다(6단계 service): " + dependencies.backendClients.map(code).join(", "), ""]
+      ? [
+          "backend client SDK는 교체하지 않습니다(6단계 service): " +
+            dependencies.backendClients.map(code).join(", "),
+          "",
+        ]
+      : []),
+    ...(dependencies.others.length > 0
+      ? [
+          "표준 스택 밖의 의존성입니다(4단계): " +
+            dependencies.others.map(code).join(", "),
+          "",
+        ]
       : []),
-    ...(dependencies.others.length > 0 ? ["표준 스택 밖의 의존성입니다(4단계): " + dependencies.others.map(code).join(", "), ""] : []),
+    ...(reactOutdated === null
+      ? []
+      : [
+          "### React 19 codemod 대상",
+          "",
+          ...(reactMigrationTargets.length > 0
+            ? reactMigrationTargets.map((file) => "- " + code(file))
+            : [
+                "- 보존 대상이 아닌 기존 JavaScript·TypeScript 파일이 없습니다.",
+              ]),
+          "",
+        ]),
     "### 설정과 script",
     "",
     ...list(configFindings, "- 설정과 script 오류가 없습니다."),
@@ -223,8 +521,22 @@ export function renderPlan({ version, createdAt, base, packageManager, frontend,
     "- 보호 경로, API 계약, backend script·의존성을 바꿔야만 진행할 수 있을 때",
     "- 교체할 라이브러리의 기능을 표준 스택으로 표현할 수 없을 때(예: 표준에 없는 UI 컴포넌트), 또는 교체하면 검증 규칙·오류 메시지·제출 동작 중 하나가 달라질 때",
     ...(uiDependents.length > 0
-      ? ["- 교체할 패키지를 shadcn ui 파일이 import할 때: " + uiDependents.map((entry) => code(entry.file) + "(" + code(entry.name) + ")").join(", ")]
+      ? [
+          "- 교체할 패키지를 shadcn ui 파일이 import할 때: " +
+            uiDependents
+              .map((entry) => code(entry.file) + "(" + code(entry.name) + ")")
+              .join(", "),
+        ]
       : []),
+    ...(preservedDependents.length > 0
+      ? [
+          "- 교체 대상 패키지를 보존 대상 파일이 import할 때: " +
+            preservedDependents
+              .map((entry) => code(entry.file) + "(" + code(entry.name) + ")")
+              .join(", "),
+        ]
+      : []),
+    "- 기준선에 있던 테스트·mock·다국어 파일이나 설정을 수정·삭제해야 해당 단계의 검증을 통과할 수 있을 때",
     "- 업그레이드가 다른 의존성 때문에 막힐 때",
     "- 파일이 프론트엔드인지 backend인지 판단할 수 없을 때",
     "- 검증 실패의 원인이 프론트엔드 밖(backend·배포 설정)에 있을 때",
@@ -234,7 +546,9 @@ export function renderPlan({ version, createdAt, base, packageManager, frontend,
     "",
     "새 세션을 시작했거나 이전 대화가 요약되었으면 NOTES.md의 「진행」을 읽고 그다음 단계부터 이어갑니다. 각 단계는 완료 기준을 모두 만족해야 끝납니다. 단계를 마치면 check를 실행하고, 「진행」의 완료한 단계 번호를 올린 뒤 결과와 결정을 「단계별 기록」에 적습니다. 「진행」이 `commit: 허용`이면 단계를 마칠 때마다 commit하고, `commit: 안 함`이면 `git status --short` 출력을 「단계별 기록」에 붙입니다.",
     "",
-    "`protected:`·`outside:`·`backend-script:`·`backend-dependency:` 오류는 어느 단계에서 나오든 그 단계를 끝내지 못하게 하므로 해당 변경을 되돌립니다. 검증을 통과시키려고 lint 규칙을 끄거나 `eslint-disable`·`@ts-ignore`·`@ts-expect-error`·`any` 캐스팅·ignore 경로를 새로 넣지 않습니다. 명령은 이 저장소의 패키지 매니저(" + packageManager.name + ") 기준입니다.",
+    "`protected:`·`outside:`·`backend-script:`·`backend-dependency:` 오류는 어느 단계에서 나오든 그 단계를 끝내지 못하게 하므로 해당 변경을 되돌립니다. 검증을 통과시키려고 lint 규칙을 끄거나 `eslint-disable`·`@ts-ignore`·`@ts-expect-error`·`any` 캐스팅·ignore 경로를 새로 넣지 않습니다. 명령은 이 저장소의 패키지 매니저(" +
+      packageManager.name +
+      ") 기준입니다.",
     "",
     "### 1. 준비",
     "",
@@ -242,127 +556,321 @@ export function renderPlan({ version, createdAt, base, packageManager, frontend,
       conventions + "를 끝까지 읽습니다.",
       "「보호 경로」가 실제 backend·배포 코드와 맞는지 확인합니다. 프론트엔드가 보호 경로(예: backend와 함께 쓰는 package root `shared/`의 schema·type)를 import하는 것은 정상이므로 import와 alias를 그대로 둡니다. 보호 경로 안에 프론트엔드에서만 쓰는 파일이 있거나 backend·배포 경로가 목록에 없으면 멈추고 사용자에게 확인합니다. 답은 NOTES.md 「보호 경로 확인」에 적고, 목록에 없던 backend 경로는 끝까지 수정하지 않습니다(check는 그 경로를 점검하지 않습니다). 보호 경로 안의 프론트엔드 전용 파일은 사용자가 옮기라고 답해도 옮기지 않고 「보류 사항」에 남깁니다(check가 보호 경로의 변경을 오류로 보고합니다).",
       "작업 branch를 만들고(예: `git switch -c eds-align`), 단계마다 commit해도 되는지 사용자에게 한 번 묻고 답을 NOTES.md 「진행」의 `commit:` 줄에 `허용` 또는 `안 함`으로 적습니다.",
-      "`AGENTS.md`의 EDS managed block 밖에 다음 줄을 추가합니다: `" + inProgressAgentsLine + "`",
-      "프론트엔드의 API 호출을 모두 찾아 domain 목록을 정하고 NOTES.md 「domain 목록」에 적습니다. domain 이름은 backend resource를 소문자 복수형으로 씁니다(예: `/api/users` → `users`, `supabase.from(\"profiles\")` → `profiles`).",
-      scripts.build === undefined ? null : code(commands.run("build")) + "의 exit code와 오류 수를 NOTES.md 「기준선」에 적습니다.",
+      "`AGENTS.md`의 EDS managed block 밖에 다음 줄을 추가합니다: `" +
+        inProgressAgentsLine +
+        "`",
+      '프론트엔드의 API 호출을 모두 찾아 domain 목록을 정하고 NOTES.md 「domain 목록」에 적습니다. domain 이름은 backend resource를 소문자 복수형으로 씁니다(예: `/api/users` → `users`, `supabase.from("profiles")` → `profiles`).',
+      "기존 test·mock·다국어 파일과 설정을 파일명, import, package.json, tsconfig, Vite 설정에서 찾습니다. 자동 감지되지 않은 경로는 " +
+        code(alignLabel + "/" + stateFileName) +
+        "의 `preservedPaths`에 git 저장소 루트 기준으로 추가한 뒤 `eds align`을 다시 실행합니다. 검색 범위와 경로를 NOTES.md 「기존 리소스 확인」에 적습니다.",
+      scripts.build === undefined
+        ? null
+        : code(commands.run("build")) +
+          "의 exit code와 오류 수를 NOTES.md 「기준선」에 적습니다.",
     ]),
     "",
-    "완료 기준: 「진행」의 `commit:` 줄에 답이 있고, `AGENTS.md`에 4의 줄이 있고, 「domain 목록」·「보호 경로 확인」" + (scripts.build === undefined ? "" : "·「기준선」") + "이 채워져 있습니다.",
+    "완료 기준: 「진행」의 `commit:` 줄에 답이 있고, `AGENTS.md`에 4의 줄이 있고, 「domain 목록」·「보호 경로 확인」·「기존 리소스 확인」" +
+      (scripts.build === undefined ? "" : "·「기준선」") +
+      "이 채워져 있습니다.",
     "",
     "### 2. 스타일 기반과 EDS",
     "",
     ...numbered([
       reactOutdated === null
         ? null
-        : "`react` " + reactOutdated.major + " → 19: " + code(commands.add(["react", "react-dom"])) + "와 " + code(commands.addDev(["@types/react", "@types/react-dom"])) +
-          "를 실행한 뒤 " + code(commands.dlx("codemod@latest react/19/migration-recipe")) + "와 " + code(commands.dlx("types-react-codemod@latest preset-19 ./" + app.srcDir)) + "로 코드를 옮깁니다.",
-      (tailwindMajor === null
-        ? "Tailwind CSS v4를 설치하고(" + code(commands.addDev(["tailwindcss", "@tailwindcss/vite"])) + ") `vite.config.ts`의 plugins에 `tailwindcss()`를 추가합니다(템플릿 참고)."
+        : "`react` " +
+          reactOutdated.major +
+          " → 19: " +
+          code(commands.add(["react", "react-dom"])) +
+          "와 " +
+          code(commands.addDev(["@types/react", "@types/react-dom"])) +
+          "를 실행합니다." +
+          (reactMigrationTargets.length > 0
+            ? " 이어서 " +
+              code(
+                commands.dlx("types-react-codemod@latest preset-19 <path...>")
+              ) +
+              "를 「React 19 codemod 대상」에 적힌 파일만 인자로 전달해 실행합니다."
+            : " 보존 대상이 아닌 JavaScript·TypeScript 파일이 없어 codemod는 생략합니다."),
+      viteMissing || viteOutdated !== null
+        ? (viteOutdated === null
+            ? "`vite`가 선언되어 있지 않아 "
+            : "Vite " + viteOutdated.version + "이 최소 버전보다 낮아 ") +
+          code(commands.addDev(["vite"])) +
+          "로 Vite " +
+          minimumVersions.vite +
+          " 이상으로 맞춥니다. Tailwind CSS v4 plugin을 설치하기 전에 실행합니다."
+        : null,
+      pluginReactOutdated !== null
+        ? "`@vitejs/plugin-react`가 현재 Vite와 호환되지 않아 " +
+          code(commands.addDev(["@vitejs/plugin-react"])) +
+          "를 실행합니다."
+        : null,
+      tailwindMajor === null
+        ? "Tailwind CSS v4를 설치하고(" +
+          code(commands.addDev(["tailwindcss", "@tailwindcss/vite"])) +
+          ") `vite.config.ts`의 plugins에 `tailwindcss()`를 추가합니다(템플릿 참고)."
         : (tailwindMajor < 4
-          ? "Tailwind CSS를 v4로 올리고(" + code(commands.dlx("@tailwindcss/upgrade")) + "), Tailwind를 `@tailwindcss/vite` plugin으로 실행합니다(" + code(commands.addDev(["@tailwindcss/vite"])) + ")."
-          : "Tailwind CSS v4를 `@tailwindcss/vite` plugin으로 실행합니다" + (analysis.declared.has("@tailwindcss/vite") ? "." : "(" + code(commands.addDev(["@tailwindcss/vite"])) + ").")) +
-          " upgrade 도구가 추가했거나 기존에 쓰던 `@tailwindcss/postcss`와 `postcss.config`의 Tailwind 항목은 지웁니다(PostCSS 경로는 EDS font 파일을 번들에 넣지 않습니다)."),
-      "전역 CSS를 " + code(srcPath("app/styles/index.css")) + " 하나로 모으고(템플릿 같은 경로), 현재 entry " + code(entryLabel) + "가 이 파일을 import하게 합니다. 기존 `@import`와 EDS가 넣은 줄은 유지합니다. 컴포넌트별 CSS 규칙은 6단계에서 className으로 옮깁니다.",
-      (edsDeclared ? "" : code(commands.add(["@spectrabrain/eds"])) + "로 EDS를 dependencies에 선언하고, ") + code(commands.eds("init")) + "로 EDS script 등록과 첫 sync를 실행합니다. Tailwind root 후보가 여러 개라서 exit 2이면, 나머지 후보가 3번에서 합친 옛 전역 CSS일 때만 " + code("EDS_TAILWIND_ROOT=" + srcPath("app/styles/index.css") + " " + commands.run("sync:eds")) + "를 실행하고, 그렇지 않으면 사용자에게 root를 확인합니다.",
+            ? "Tailwind CSS를 v4로 올리고(" +
+              code(commands.dlx("@tailwindcss/upgrade")) +
+              "), Tailwind를 `@tailwindcss/vite` plugin으로 실행합니다(" +
+              code(commands.addDev(["@tailwindcss/vite"])) +
+              ")."
+            : "Tailwind CSS v4를 `@tailwindcss/vite` plugin으로 실행합니다" +
+              (analysis.declared.has("@tailwindcss/vite") &&
+              tailwindViteOutdated === null
+                ? "."
+                : "(" + code(commands.addDev(["@tailwindcss/vite"])) + ").")) +
+          " upgrade 도구가 추가했거나 기존에 쓰던 `@tailwindcss/postcss`와 `postcss.config`의 Tailwind 항목은 지웁니다(PostCSS 경로는 EDS font 파일을 번들에 넣지 않습니다).",
+      "전역 CSS를 " +
+        code(srcPath("app/styles/index.css")) +
+        " 하나로 모으고(템플릿 같은 경로), 현재 entry " +
+        code(entryLabel) +
+        "가 이 파일을 import하게 합니다. 기존 `@import`와 EDS가 넣은 줄은 유지합니다. 컴포넌트별 CSS 규칙은 6단계에서 className으로 옮깁니다.",
+      (edsDeclared
+        ? ""
+        : code(commands.add(["@spectrabrain/eds"])) +
+          "로 EDS를 dependencies에 선언하고, ") +
+        code(commands.eds("init")) +
+        "로 EDS script 등록과 첫 sync를 실행합니다. Tailwind root 후보가 여러 개라서 exit 2이면, 나머지 후보가 3번에서 합친 옛 전역 CSS일 때만 " +
+        code(
+          "EDS_TAILWIND_ROOT=" +
+            srcPath("app/styles/index.css") +
+            " " +
+            commands.run("sync:eds")
+        ) +
+        "를 실행하고, 그렇지 않으면 사용자에게 root를 확인합니다.",
     ]),
     "",
-    "완료 기준: " + code(commands.run("eds:doctor")) + "가 `[EDS] synced with` 줄을 출력하고 " + code(commands.run("build")) + "가 exit 0이며, check 출력에 `@tailwindcss/vite`·`@tailwindcss/postcss` 줄이 없습니다." +
-      (reactOutdated === null ? "" : " package.json의 `react` major가 19입니다."),
+    "완료 기준: " +
+      code(commands.run("eds:doctor")) +
+      "가 `[EDS] synced with` 줄을 출력하고 " +
+      code(commands.run("build")) +
+      "가 exit 0이며, Vite가 " +
+      minimumVersions.vite +
+      " 이상이며" +
+      (tailwindViteMinimum !== null
+        ? " `@tailwindcss/vite`가 " +
+          tailwindViteMinimum +
+          " 이상이고"
+        : "") +
+      " check 출력에 `@tailwindcss/vite`·`@tailwindcss/postcss` 줄이 없습니다." +
+      (reactOutdated === null
+        ? ""
+        : " package.json의 `react` major가 19입니다."),
     "",
     "### 3. 개발 도구와 설정",
     "",
     ...numbered([
       missingDev.length > 0
-        ? "개발 도구를 설치합니다(템플릿보다 오래된 도구는 다시 설치합니다): " + code(commands.addDev(missingDev))
+        ? "개발 도구를 설치합니다(템플릿보다 오래된 도구는 다시 설치합니다): " +
+          code(commands.addDev(missingDev))
         : "필요한 개발 도구가 모두 선언되어 있습니다.",
-      "`templates/`의 설정 파일(" + configTemplates.join(", ") + ")을 같은 경로로 복사합니다. 설정 값의 기준은 " + conventions + " 「개발 규칙」입니다. 이미 있는 파일은 다음처럼 합칩니다.",
+      majors.vite === 8
+        ? "Vite 8 React Compiler 설정에는 Node 22.12.0 이상이 필요합니다. frontend package의 `package.json`에서 `engines.node`를 `>=22.12.0`으로 설정합니다. CI Node 설정은 이 계획에서 바꾸지 않으므로 별도로 확인·갱신합니다. CI 파일이 frontend package 밖에 있으면 align 완료 후 처리합니다."
+        : null,
+      "`templates/`의 설정 파일(" +
+        configTemplates.join(", ") +
+        ")을 같은 경로로 복사합니다. 설정 값의 기준은 " +
+        conventions +
+        " 「개발 규칙」입니다. 이미 있는 파일은 다음처럼 합칩니다.",
     ]),
-    "   - `vite.config.ts`: 기존 설정의 키와 값은 모두 유지합니다(`root`·`envDir`·`base`·`server`·`build.outDir`·기존 alias·`test` 등). 템플릿에서 없는 것만 추가합니다: `@tailwindcss/vite`·svgr plugin" + (majors.vite !== null && majors.vite >= 8 ? "·`@rolldown/plugin-babel`의 React Compiler plugin" : "") + ", `resolve.alias[\"@\"]`, `resolve.dedupe`(기존 배열이 있으면 합침), `build.minify`·`terserOptions`. " +
-      (majors.vite !== null && majors.vite >= 8 ? "" : "기존 `react()` 호출에는 React Compiler의 `babel` 옵션을 넣습니다. ") + "같은 키에 다른 값이 이미 있으면 기존 값을 두고 NOTES.md에 적습니다." +
-      (replacedCategories.has("build-plugin") ? " `@vitejs/plugin-react-swc`·`@vitejs/plugin-react-oxc`를 쓰고 있으면 React Compiler를 위해 `@vitejs/plugin-react`로 바꿉니다(패키지 제거는 4단계)." : ""),
-    "   - `tsconfig.json`: `include`에 「보호 경로」의 경로가 있으면 compilerOptions는 그대로 두고 `paths[\"@/*\"]`만 템플릿처럼 맞춥니다. 보호 경로가 없으면 템플릿 기준으로 바꾸고, 테스트 도구가 쓰는 설정(`types`의 `vitest/globals` 등)만 유지합니다. `tsconfig.app.json`·`tsconfig.node.json`의 프론트엔드 설정은 합친 뒤 지웁니다.",
+    "   - `vite.config.ts`: 기존 설정의 키와 값은 모두 유지합니다(`root`·`envDir`·`base`·`server`·`build.outDir`·alias 등). 템플릿에서 없는 것만 추가합니다: `@tailwindcss/vite`·svgr plugin" +
+      (majors.vite === 8
+        ? "·`@rolldown/plugin-babel`의 React Compiler plugin"
+        : "") +
+      ', `resolve.alias["@"]`, `resolve.dedupe`(기존 배열이 있으면 합침), `build.minify`·`terserOptions`. ' +
+      (majors.vite === 8
+        ? ""
+        : "기존 `react()` 호출에는 React Compiler의 `babel` 옵션을 넣습니다. ") +
+      "같은 키에 다른 값이 이미 있으면 기존 값을 두고 NOTES.md에 적습니다." +
+      (replacedCategories.has("build-plugin")
+        ? " `@vitejs/plugin-react-swc`·`@vitejs/plugin-react-oxc`를 쓰고 있으면 React Compiler를 위해 `@vitejs/plugin-react`로 바꿉니다(패키지 제거는 4단계)."
+        : ""),
+    '   - `tsconfig*.json`: 각 파일의 `include`·`exclude`·`compilerOptions.types`·project references를 그대로 둡니다. `paths["@/*"]`만 앱의 새 `src` 경로에 맞춥니다. 기존 tsconfig 파일과 설정을 다른 파일로 옮기거나 삭제하지 않습니다. `check`는 위 설정이 각 원래 파일에서 빠지면 `preserved:`로 보고합니다.',
+    "   - `.prettierignore`: 기존 항목을 모두 유지하고 생성 CSS·보호 경로에 필요한 항목만 추가합니다.",
     "   - `components.json`: `aliases`와 `tailwind.css`만 템플릿 값으로 바꾸고 `style`·`baseColor`는 유지합니다.",
-    "   - `package.json` scripts: `package.scripts.json`에서 없는 script만 추가하고, 추가한 뒤 " + code(commands.eds("init --no-sync")) + "로 `pretypecheck`·`prebuild` hook을 등록합니다. backend를 실행하는 script는 바꾸지 않습니다.",
-    "   - 이전 lint·format 설정(`.eslintrc*`, `biome.json`, 중복 Prettier 설정)은 규칙을 옮긴 뒤 지웁니다" + (replacedCategories.has("lint-format") ? "(패키지 제거는 4단계)." : "."),
+    "   - `package.json` scripts: `package.scripts.json`에서 없는 script만 추가하고, 추가한 뒤 " +
+      code(commands.eds("init --no-sync")) +
+      "로 `pretypecheck`·`prebuild` hook을 등록합니다. backend를 실행하는 script는 바꾸지 않습니다.",
+    "   - 이전 lint·format 설정(`.eslintrc*`, `biome.json`, 중복 Prettier 설정)은 규칙을 옮긴 뒤 정리합니다" +
+      (replacedCategories.has("lint-format") ? "(패키지 제거는 4단계)." : ".") +
+      " 테스트·mock·다국어 파일과 설정은 그대로 둡니다. 기준선에 있던 항목을 바꾸지 않고 적용할 수 없으면 멈추고 사용자에게 확인합니다.",
     // Items 1 and 2 above always exist, so the numbering continues at 3.
-    "3. " + code(commands.run("format")) + "로 전체를 한 번 포맷합니다. 이 변경은 다른 변경과 섞지 않고 따로 commit하거나(`commit: 허용`) 따로 기록합니다(`commit: 안 함`).",
-    "4. " + code(commands.run("typecheck")) + "·" + code(commands.run("lint")) + "를 처음 실행한 결과(오류 수)를 NOTES.md 「기준선」에 적습니다. lint 오류는 4~6단계에서 파일을 옮기거나 코드를 고치면서 함께 줄입니다.",
-    "",
-    "완료 기준: check에 `config:`·`script:` 오류가 없고, " + [commands.run("format:check"), commands.run("typecheck"), commands.run("build")].map(code).join("·") + "가 exit 0입니다. 기존 `build.outDir`·`base`·`server.proxy`가 병합 전과 같고, " + (packageManager.berry ? "`typecheck` script가 `eds doctor && `로 시작하며" : "`package.json`의 `pretypecheck`가 `eds doctor`를 실행하며") + ", 「기준선」에 typecheck·lint 결과가 있습니다.",
+    "3. " +
+      code(commands.exec("prettier --write <변경 파일>")) +
+      "로 정렬 중 수정한 파일만 포맷합니다.",
+    "4. " +
+      code(commands.run("typecheck")) +
+      "·" +
+      code(commands.run("lint")) +
+      "를 처음 실행한 결과(오류 수)를 NOTES.md 「기준선」에 적습니다. lint 오류는 4~6단계에서 파일을 옮기거나 코드를 고치면서 함께 줄입니다.",
+    "",
+    "완료 기준: check에 `config:`·`script:` 오류가 없고, " +
+      [
+        commands.run("format:check"),
+        commands.run("typecheck"),
+        commands.run("build"),
+      ]
+        .map(code)
+        .join("·") +
+      "가 exit 0입니다. 기존 `build.outDir`·`base`·`server.proxy`가 병합 전과 같고, " +
+      (packageManager.berry
+        ? "`typecheck` script가 `eds doctor && `로 시작하며"
+        : "`package.json`의 `pretypecheck`가 `eds doctor`를 실행하며") +
+      ", 「기준선」에 typecheck·lint 결과가 있습니다.",
     "",
     "### 4. 라이브러리 정렬",
     "",
     ...numbered([
-      missingRuntime.length > 0 ? "표준 라이브러리를 추가합니다: " + code(commands.add(missingRuntime)) + (dependencies.sdkOnly ? ". backend는 SDK로만 호출하므로 axios는 설치하지 않습니다." : "") : "표준 라이브러리가 모두 선언되어 있습니다.",
+      missingRuntime.length > 0
+        ? "표준 라이브러리를 추가합니다: " +
+          code(commands.add(missingRuntime)) +
+          (dependencies.sdkOnly
+            ? ". backend는 SDK로만 호출하므로 axios는 설치하지 않습니다."
+            : "")
+        : "표준 라이브러리가 모두 선언되어 있습니다.",
       replacementRows.length > 0 || keptForBackend.length > 0
-        ? "「의존성」의 교체 대상을 범주 하나씩 처리합니다. 코드를 대체 라이브러리로 옮기고, 표에 있는 원래 패키지를 제거하고(" + code(commands.remove(["<패키지>"])) + "), typecheck·build를 통과시킨 뒤 서두의 commit 규칙을 적용합니다. 범주별 방법은 " + conventions + " 「라이브러리 스택」을 따릅니다. routing·provider처럼 `app/main.tsx`·`app/router/`·`app/providers/`에 둘 코드는 현재 entry에서 동작만 옮기고, 파일 위치와 템플릿 적용은 5단계에서 합니다."
+        ? "「의존성」의 교체 대상을 범주 하나씩 처리합니다. 코드를 대체 라이브러리로 옮기고, 표에 있는 원래 패키지를 제거하고(" +
+          code(commands.remove(["<패키지>"])) +
+          "), typecheck·build를 통과시킨 뒤 서두의 commit 규칙을 적용합니다. 범주별 방법은 " +
+          conventions +
+          " 「라이브러리 스택」을 따릅니다. routing·provider처럼 `app/main.tsx`·`app/router/`·`app/providers/`에 둘 코드는 현재 entry에서 동작만 옮기고, 파일 위치와 템플릿 적용은 5단계에서 합니다."
+        : null,
+      laterUpgrades.length > 0
+        ? "「의존성」에서 4단계로 표시한 업그레이드를 하나씩 올리고 검증합니다."
+        : null,
+      dependencies.others.length > 0
+        ? "「의존성」의 표준 스택 밖 의존성마다 쓰임을 확인해, 쓰이지 않으면 제거하고 유지·제거 결정을 NOTES.md에 적습니다."
         : null,
-      laterUpgrades.length > 0 ? "「의존성」에서 4단계로 표시한 업그레이드를 하나씩 올리고 검증합니다." : null,
-      dependencies.others.length > 0 ? "「의존성」의 표준 스택 밖 의존성마다 쓰임을 확인해, 쓰이지 않으면 제거하고 유지·제거 결정을 NOTES.md에 적습니다." : null,
     ]),
     "",
-    "완료 기준: check에 `dependency:` 오류가 없고, " + [commands.run("typecheck"), commands.run("build")].map(code).join("·") + "가 exit 0입니다." +
-      (dependencies.others.length > 0 ? " 표준 스택 밖 의존성마다 NOTES.md에 결정이 있습니다." : ""),
+    "완료 기준: check에 `dependency:` 오류가 없고, " +
+      [commands.run("typecheck"), commands.run("build")].map(code).join("·") +
+      "가 exit 0입니다." +
+      (dependencies.others.length > 0
+        ? " 표준 스택 밖 의존성마다 NOTES.md에 결정이 있습니다."
+        : ""),
     "",
     "### 5. FSD 구조",
     "",
     ...numbered([
-      "「구조」 표를 따라 파일을 `git mv`로 옮겨 이력을 보존합니다. 컴포넌트를 역할별로 나누는 기준은 " + conventions + " 「FSD 계층」입니다.",
-      "기존 route 경로와 provider 목록을 NOTES.md에 적습니다. entry를 " + code(srcPath("app/main.tsx")) + "로 옮기고 " + code(appPrefix + "index.html") + "의 module script를 `/src/app/main.tsx`로 바꿉니다.",
-      "기존 entry의 내용을 템플릿 `main.tsx`·`App.tsx` 구조로 합칩니다. 기존 provider는 모두 유지하고, 템플릿과 같은 역할(Router, QueryClient, 오류 처리)의 provider만 템플릿 것으로 바꿉니다. 기존 route는 모두 `router/index.tsx`로 옮기고 예시 `HomePage` route는 지웁니다. 기존 오류 처리 provider가 i18n 호출로 문구를 표시하고 있으면 그 호출은 유지합니다." +
-        (dependencies.sdkOnly ? " 이 저장소는 MSW를 쓰지 않으므로 템플릿 `main.tsx`의 `VITE_API_MOCKING` 블록은 옮기지 않습니다." : ""),
-      [srcPath("app/"), srcPath("shared/"), srcPath("vite-env.d.ts"), ...(dependencies.sdkOnly ? [] : [srcPath("mocks/")])].map(templatesOf).join("·") + "의 파일은 같은 경로에 같은 이름의 파일이 없을 때만 복사하고, 있으면 합칩니다. " +
+      "「구조」 표를 따라 파일을 `git mv`로 옮겨 이력을 보존합니다. 컴포넌트를 역할별로 나누는 기준은 " +
+        conventions +
+        " 「FSD 계층」입니다.",
+      "기존 route 경로와 provider 목록을 NOTES.md에 적습니다. entry를 " +
+        code(srcPath("app/main.tsx")) +
+        "로 옮기고 " +
+        code(appPrefix + "index.html") +
+        "의 module script를 `/src/app/main.tsx`로 바꿉니다.",
+      "기존 entry의 모든 초기화 import·호출과 provider를 유지하면서 템플릿 `main.tsx`·`App.tsx` 구조로 합칩니다. 템플릿과 같은 역할(Router, QueryClient, 오류 처리)의 provider만 템플릿 것으로 바꿉니다. 기존 route는 모두 `router/index.tsx`로 옮기고 예시 `HomePage` route는 지웁니다.",
+      [srcPath("app/"), srcPath("shared/"), srcPath("vite-env.d.ts")]
+        .map(templatesOf)
+        .join("·") +
+        "의 파일은 같은 경로에 같은 이름의 파일이 없을 때만 복사하고, 있으면 합칩니다. " +
         (dependencies.sdkOnly
-          ? code(srcPath("shared/api/index.ts")) + "는 템플릿 대신 기존 SDK client(" + sdkClients.map(code).join(", ") + ")를 한 번 만들어 export하고, `queryClient.ts`·`ErrorHandler.tsx`의 `isAxiosError`·`error.response?.status` 판별은 SDK의 오류 타입 판별로 바꿉니다."
-          : code(srcPath("shared/api/index.ts")) + "에는 기존 요청의 base URL·header·credentials를 옮겨 채웁니다."),
-      "import 경로와 barrel(`index.ts`)은 " + conventions + " 「FSD 계층」의 import·이름 규칙을 따릅니다.",
-      code(app.srcDir) + " 안의 JavaScript 파일(`.js`·`.jsx`)은 TypeScript로 바꿉니다. 테스트 파일은 그대로 둡니다.",
+          ? code(srcPath("shared/api/index.ts")) +
+            "는 템플릿 대신 기존 SDK client(" +
+            sdkClients.map(code).join(", ") +
+            ")를 한 번 만들어 export하고, `queryClient.ts`·`ErrorHandler.tsx`의 `isAxiosError`·`error.response?.status` 판별은 SDK의 오류 타입 판별로 바꿉니다."
+          : code(srcPath("shared/api/index.ts")) +
+            "에는 기존 요청의 base URL·header·credentials를 옮겨 채웁니다."),
+      "import 경로와 barrel(`index.ts`)은 " +
+        conventions +
+        " 「FSD 계층」의 import·이름 규칙을 따릅니다.",
+      code(app.srcDir) +
+        " 안의 정렬 대상 JavaScript 파일(`.js`·`.jsx`)은 TypeScript로 바꿉니다. 보존 대상 파일은 제외합니다.",
     ]),
     "",
-    "완료 기준: check에 `structure:`·`import:`·`language:` 오류가 없고, " + [commands.run("typecheck"), commands.run("build")].map(code).join("·") + "가 exit 0이며, NOTES.md에 적은 route와 provider가 모두 옮겨져 있습니다.",
+    "완료 기준: check에 `structure:`·`import:`·`language:` 오류가 없고, " +
+      [commands.run("typecheck"), commands.run("build")].map(code).join("·") +
+      "가 exit 0이며, NOTES.md에 적은 route와 provider가 모두 옮겨져 있습니다.",
     "",
     "### 6. 코드 패턴",
     "",
     "방법은 " + conventions + " 「코드 패턴」의 해당 절을 따릅니다.",
     "",
     ...numbered([
-      "앱 전역을 먼저 한 번 설정합니다: " + code(srcPath("shared/api")) + (dependencies.sdkOnly ? "의 SDK client" : " instance") + ", 오류 처리(ErrorBoundary·ErrorHandler·sonner·eventBus), " + code(srcPath("app/router/index.tsx")) + "의 lazy page" +
-        (dependencies.sdkOnly
-          ? "."
-          : ". 「domain 목록」에 REST API domain이 있으면 " + code(commands.addDev(mockDevDependencies)) + "를 설치하고 `dev:mock` script를 확인한 뒤 " +
-            code(commands.exec("msw init " + appPrefix + "public --save")) + "로 worker를 Vite root의 `public/`에 만듭니다."),
-      "NOTES.md 「domain 목록」의 domain마다 `types/api.ts`·`types/enums.ts` → `<domain>Service.ts` → query·mutation hook → (필요하면) store" + (dependencies.sdkOnly ? "" : " → (REST API면) " + code(srcPath("mocks/<domain>")) + " handler") + " → form·component·page 순으로 옮깁니다. UI 문구는 " + conventions + " 「UI 문구」를 따릅니다." +
-        (dependencies.backendClients.length > 0 ? " backend client SDK(" + dependencies.backendClients.map(code).join(", ") + ")는 교체하지 않으며, SDK client는 " + code(srcPath("shared/api")) + "에서 한 번만 만들고 entity service만 그 client를 import합니다." : "") +
-        " domain 하나를 마칠 때마다 typecheck·build를 실행하고 「단계별 기록」에 `<domain>: service·hook·store·mock 경로, 완료`를 적습니다.",
+      "앱 전역을 한 번 설정합니다: " +
+        code(srcPath("shared/api")) +
+        (dependencies.sdkOnly ? "의 SDK client" : " instance") +
+        ", 오류 처리(ErrorBoundary·ErrorHandler·sonner·eventBus), " +
+        code(srcPath("app/router/index.tsx")) +
+        "의 lazy page를 둡니다.",
+      "NOTES.md 「domain 목록」의 domain마다 `types/api.ts`·`types/enums.ts` → `<domain>Service.ts` → query·mutation hook → (필요하면) store → form·component·page 순으로 옮깁니다." +
+        (dependencies.backendClients.length > 0
+          ? " backend client SDK(" +
+            dependencies.backendClients.map(code).join(", ") +
+            ")는 교체하지 않으며, SDK client는 " +
+            code(srcPath("shared/api")) +
+            "에서 한 번만 만들고 entity service만 그 client를 import합니다."
+          : "") +
+        " domain 하나를 마칠 때마다 typecheck·build를 실행하고 「단계별 기록」에 `<domain>: service·hook·store 경로, 완료`를 적습니다.",
       "남은 " + code(commands.run("lint")) + " 오류를 고칩니다.",
     ]),
     "",
-    "완료 기준: 「domain 목록」의 모든 domain에 service·hook 경로와 완료 표시가 있고, 이 저장소 코드의 fetch()·axios 호출은 " + code(srcPath("shared/api")) + "와 entity service에만 있습니다. check가 exit 0이고, 8단계에서 해소하는 `warning agents:`를 뺀 나머지 경고는 모두 고치거나 이유를 NOTES.md에 적었습니다. " +
-      [commands.run("lint"), commands.run("typecheck"), commands.run("build")].map(code).join("·") + "가 exit 0입니다.",
+    "완료 기준: 「domain 목록」의 모든 domain에 service·hook 경로와 완료 표시가 있고, 이 저장소 코드의 fetch()·axios 호출은 " +
+      code(srcPath("shared/api")) +
+      "와 entity service에만 있습니다. check가 exit 0이고, 8단계에서 해소하는 `warning agents:`를 뺀 나머지 경고는 모두 고치거나 이유를 NOTES.md에 적었습니다. " +
+      [commands.run("lint"), commands.run("typecheck"), commands.run("build")]
+        .map(code)
+        .join("·") +
+      "가 exit 0입니다.",
     "",
     "### 7. EDS 컴포넌트와 token",
     "",
     ...numbered([
       "`QUICKSTART.md` 규칙대로 버튼을 EDS `Button`으로, 색상·typography를 EDS token class로 바꿉니다. shadcn `button.tsx`는 다른 shadcn 컴포넌트가 쓸 때만 남깁니다. 기존 로컬 Button wrapper를 남길지는 `dist/components/Button/README.md` 「문서와 검증」을 따릅니다.",
-      code(commands.run("eds:doctor") + " -- --scan") + "을 실행해 보고된 raw 색상 class를 공개 token class로 바꿉니다. 바꿀 수 없는 항목은 파일·class·이유를 NOTES.md에 적습니다.",
+      code(commands.run("eds:doctor") + " -- --scan") +
+        "을 실행해 보고된 raw 색상 class를 공개 token class로 바꿉니다. 바꿀 수 없는 항목은 파일·class·이유를 NOTES.md에 적습니다.",
     ]),
     "",
-    "완료 기준: " + code(commands.run("eds:doctor")) + "가 `[EDS] synced with` 줄을 출력하고, `-- --scan` 출력이 `[EDS] scan: no raw color classes found`이거나 남은 class마다 NOTES.md에 이유가 있습니다. " +
-      code("grep -rn \"<button\" " + app.srcDir) + "의 결과가 " + code(srcPath("shared/ui/")) + " 안의 shadcn 컴포넌트뿐입니다.",
+    "완료 기준: " +
+      code(commands.run("eds:doctor")) +
+      "가 `[EDS] synced with` 줄을 출력하고, `-- --scan` 출력이 `[EDS] scan: no raw color classes found`이거나 남은 class마다 NOTES.md에 이유가 있습니다. " +
+      code('grep -rn "<button" ' + app.srcDir) +
+      "의 결과가 " +
+      code(srcPath("shared/ui/")) +
+      " 안의 shadcn 컴포넌트뿐입니다.",
     "",
     "### 8. 최종 검증과 마무리",
     "",
     ...numbered([
-      "`AGENTS.md`에서 1단계에 넣은 줄을 다음 줄로 바꿉니다: `- 파일을 만들거나 옮길 때, 의존성을 추가하거나 바꿀 때, service·hook·store·component·page와 화면 문구를 쓸 때 EDS package root의 " + conventionsFileName +
-        " 해당 절을 읽고, 완료 전에 " + alignCheck + "를 실행합니다.`",
-      [commands.run("format:check"), commands.run("lint"), commands.run("typecheck"), commands.run("build"), commands.run("eds:doctor"), alignCheck].map(code).join(", ") + "을 실행해 모두 exit 0이고 " + code(commands.run("eds:doctor")) + "가 `[EDS] synced with` 줄을 출력하는지 확인합니다.",
+      "`AGENTS.md`에서 1단계에 넣은 줄을 다음 줄로 바꿉니다: `- 파일을 만들거나 옮길 때, 의존성을 추가하거나 바꿀 때, service·hook·store·component·page를 작성하거나 수정할 때 EDS package root의 " +
+        conventionsFileName +
+        " 해당 절을 읽고, 완료 전에 " +
+        alignCheck +
+        "를 실행합니다.`",
+      [
+        commands.run("format:check"),
+        commands.run("lint"),
+        commands.run("typecheck"),
+        commands.run("build"),
+        commands.run("eds:doctor"),
+        alignCheck,
+      ]
+        .map(code)
+        .join(", ") +
+        "을 실행해 모두 exit 0이고 " +
+        code(commands.run("eds:doctor")) +
+        "가 `[EDS] synced with` 줄을 출력하는지 확인합니다.",
       backendImportsViteConfig && backendStartScript !== null
-        ? "backend가 `vite.config.ts`를 import하므로 build 뒤 " + code(commands.run(backendStartScript)) + "를 실행해 설정을 불러오는 단계에서 오류 없이 기동되는지 확인합니다."
+        ? "backend가 `vite.config.ts`를 import하므로 build 뒤 " +
+          code(commands.run(backendStartScript)) +
+          "를 실행해 설정을 불러오는 단계에서 오류 없이 기동되는지 확인합니다."
         : null,
-      "아래 「완료 보고」를 사용자에게 보내는 최종 응답으로 작성합니다. NOTES.md의 결정·보류 사항과 기록한 수치를 보고에 옮긴 뒤 " + code(alignLabel + "/") + "를 지웁니다.",
+      "아래 「완료 보고」를 사용자에게 보내는 최종 응답으로 작성합니다. NOTES.md의 결정·보류 사항과 기록한 수치를 보고에 옮긴 뒤 " +
+        code(alignLabel + "/") +
+        "를 지웁니다.",
     ]),
     "",
-    "완료 기준: 2의 명령이 모두 exit 0이고 doctor가 `[EDS] synced with` 줄을 출력하고" + (backendImportsViteConfig && backendStartScript !== null ? ", backend가 기동되고" : "") + ", `AGENTS.md`에 1의 줄이 있고 1단계에 넣은 줄은 없으며, " + code(alignLabel + "/") + "가 없습니다.",
+    "완료 기준: 2의 명령이 모두 exit 0이고 doctor가 `[EDS] synced with` 줄을 출력하고" +
+      (backendImportsViteConfig && backendStartScript !== null
+        ? ", backend가 기동되고"
+        : "") +
+      ", `AGENTS.md`에 1의 줄이 있고 1단계에 넣은 줄은 없으며, " +
+      code(alignLabel + "/") +
+      "가 없습니다.",
     "",
     "## 완료 보고",
     "",