projectops 4.31.5 → 4.33.0

package/src/core/migration-guide.js

@@ -11,34 +11,34 @@ export const GUIDE_FILE = `${MIGRATION_DIR}/PROJECTOPS-MIGRATION-GUIDE.md`;
 export const GUIDE_SCHEMA = 1;
 
 // 고정 헤더 — 문서 목적 + AI Agent 해석 가이드라인. 최초 생성 시 1회만 쓴다 (엔트리와 분리).
-const HEADER = `# ProjectOps 마이그레이션 가이드
+const HEADER = `# ProjectOps Migration Guide
 
-이 문서는 projectops 마법사(\`npx projectops\`)가 **실행을 마칠 때마다 자동으로 기록**하는
-마이그레이션 이력입니다. 실행 엔트리는 아래에 시간순으로 append되며, 기존 엔트리는 수정되지 않습니다.
+This document is **written automatically every time a run finishes** by the projectops wizard (\`npx projectops\`).
+Run entries are appended below in chronological order, and existing entries are never modified.
 
-## 사람이 읽는 법
+## How humans read it
 
-- 각 엔트리의 **확인 체크리스트**가 그 실행 이후 사람이 마무리해야 하는 수동 작업입니다.
-- 체크리스트는 실행에서 실제 발생한 것만 나옵니다. 항목이 없으면 할 일이 없다는 뜻입니다.
-- 상세 실행 기록(파일별 결정과 치환 전후값)은 엔트리 메타의 \`trace_file\`(JSONL)과 \`log_file\`(터미널 원문)에 있습니다.
+- The **checklist** in each entry lists the manual work a person still has to finish after that run.
+- The checklist only contains things that actually happened in the run. No items means nothing to do.
+- Detailed run records (per-file decisions and before/after values) are in the entry metadata: \`trace_file\` (JSONL) and \`log_file\` (raw terminal output).
 
-## AI Agent 해석 가이드라인
+## Guidelines for AI agents
 
-각 엔트리의 \`\`\`yaml 메타 블록(\`# projectops-migration\`)을 파싱해 아래 규칙으로 판단하고 조치한다.
+Parse the \`\`\`yaml metadata block (\`# projectops-migration\`) of each entry and decide and act with the rules below.
 
-| 필드 | 의미 | 권장 조치 |
-|------|------|----------|
-| \`workflows.leftover_old_gen\` | 구세대 워크플로우가 현역 가능성으로 보존됨 | 신형과 트리거 중복 여부 검사 → 전환 확인 후 구 파일 삭제 제안 |
-| \`workflows.skipped_conflict\` | 사용자 수정본이 유지됨 (신형 미적용) | 사용자본과 신형 템플릿 diff → 병합 제안 |
-| \`workflows.replaced_bak\` | .bak 백업 후 신형으로 교체됨 | .bak과 신형 비교 → 사용자 커스텀 유실분 복원 검토 후 .bak 정리 |
-| \`env_applied\` | 워크플로우에 적용된 환경값 | 실제 워크플로우 env와 대조 → 드리프트 발견 시 경고 |
-| \`breaking_traversed\` | 이 실행이 통과한 호환성 변경 (조치 방법 전문은 사람용 섹션) | \`action_required: true\` 항목의 조치 완료 여부 확인 |
-| \`manual_actions_pending\` | 남은 수동 작업 코드 목록 | 비어 있지 않으면 사용자에게 상기 |
-| \`trace_file\` | 파일별 결정과 치환 전후값 JSONL (Layer 2) | "왜 이 파일이 이렇게 됐나"는 파일명으로 grep |
-| \`log_file\` | 터미널 출력 원문 (Layer 3) | 실행 재현, 포렌식 디버깅용 |
+| Field | Meaning | Recommended action |
+|-------|---------|--------------------|
+| \`workflows.leftover_old_gen\` | Old-generation workflows kept because they may be live | Check for trigger overlap with the new ones, then suggest deleting the old file once the switch is confirmed |
+| \`workflows.skipped_conflict\` | The user's modified file was kept (new template not applied) | Diff the user's file against the new template and suggest a merge |
+| \`workflows.replaced_bak\` | Replaced by the new one after a .bak backup | Compare .bak with the new file, review any lost customizations, then clean up the .bak |
+| \`env_applied\` | Environment values applied to workflows | Compare with the real workflow env and warn on drift |
+| \`breaking_traversed\` | Breaking changes this run passed through (full action steps are in the human section) | Check that items with \`action_required: true\` were handled |
+| \`manual_actions_pending\` | Codes of the remaining manual work | If not empty, remind the user |
+| \`trace_file\` | JSONL of per-file decisions and before/after values (Layer 2) | To learn why a file ended up this way, grep by file name |
+| \`log_file\` | Raw terminal output (Layer 3) | For reproducing the run and forensic debugging |
 
-- 스키마는 \`schema\` 필드로 버저닝된다. 모르는 필드는 무시하고, 아는 필드만 사용한다.
-- 여러 엔트리가 있으면 **가장 최근 엔트리**가 현재 상태의 기준이다. 과거 엔트리는 이력 참고용.
+- The schema is versioned by the \`schema\` field. Ignore unknown fields and use only the ones you know.
+- When there are several entries, the **latest entry** is the reference for the current state. Older entries are history.
 `;
 
 // ── yaml 렌더 헬퍼 (외부 의존성 없이 수동 직렬화 — version-yml.js와 동일 원칙) ──
@@ -98,45 +98,45 @@ export function renderGuideEntry(report) {
   L.push("");
   L.push(`## ${r.now || ""} - v${from} → v${to} (${r.mode || "full"})`);
   L.push("");
-  L.push(`- 타입: ${(r.types ?? []).join(", ") || "-"} / 배포: ${r.options?.deploy ?? "-"} / publish: ${(r.options?.publish ?? []).join(",") || "없음"}`);
-  L.push(`- 워크플로우: 신규/갱신 ${wf.added.length + wf.replacedBak.length}개, 유지(unchanged/충돌스킵) ${(r.counters?.skipped ?? 0)}개`);
+  L.push(`- Types: ${(r.types ?? []).join(", ") || "-"} / deploy: ${r.options?.deploy ?? "-"} / publish: ${(r.options?.publish ?? []).join(",") || "none"}`);
+  L.push(`- Workflows: ${wf.added.length + wf.replacedBak.length} new/updated, ${(r.counters?.skipped ?? 0)} kept (unchanged or skipped on conflict)`);
   L.push("");
 
   // ── 확인 체크리스트 (동적 — 실제 발생분만) ──
   const checklist = [];
   if (leftoverOldGen.length) {
-    checklist.push(`- [ ] **구세대 배포 워크플로우 ${leftoverOldGen.length}개 전환 후 삭제** (현역 배포일 수 있어 마법사가 건드리지 않았습니다):`);
-    for (const o of leftoverOldGen) checklist.push(`  - \`${o.file}\`${o.replacement ? ` → 신형 \`${o.replacement}\`` : ""}`);
+    checklist.push(`- [ ] **Switch to the new workflow, then delete ${leftoverOldGen.length} old-generation deploy workflow(s)** (they may be live deployments, so the wizard left them alone):`);
+    for (const o of leftoverOldGen) checklist.push(`  - \`${o.file}\`${o.replacement ? ` → new \`${o.replacement}\`` : ""}`);
   }
   if (wf.replacedBak.length || legacyNeutralized.length) {
-    checklist.push(`- [ ] **.bak 백업 파일 확인 후 정리** (커스텀 유실분이 없는지 신형과 비교하세요):`);
-    for (const f of wf.replacedBak) checklist.push(`  - \`${f}.bak\` (충돌 교체 백업)`);
-    for (const a of legacyNeutralized) if (a.to && String(a.to).endsWith(".bak")) checklist.push(`  - \`${a.to}\` (레거시 무해화)`);
+    checklist.push(`- [ ] **Review the .bak backup files, then clean them up** (compare with the new file to be sure no customization was lost):`);
+    for (const f of wf.replacedBak) checklist.push(`  - \`${f}.bak\` (backup from conflict replacement)`);
+    for (const a of legacyNeutralized) if (a.to && String(a.to).endsWith(".bak")) checklist.push(`  - \`${a.to}\` (legacy neutralized)`);
   }
   if (wf.skippedConflict.length) {
-    checklist.push(`- [ ] **기존 수정본 유지 ${wf.skippedConflict.length}개, 신형과 병합 검토**: ${wf.skippedConflict.map((f) => `\`${f}\``).join(", ")}`);
+    checklist.push(`- [ ] **Kept ${wf.skippedConflict.length} modified file(s), review a merge with the new template**: ${wf.skippedConflict.map((f) => `\`${f}\``).join(", ")}`);
     // #654 — 새 템플릿 사본이 있으면 비교 방법까지 적는다
     for (const d of wf.skippedConflictDetails.filter((x) => x.incoming)) {
-      const cnt = d.added != null && d.removed != null ? ` (추가 ${d.added}줄, 삭제 ${d.removed}줄)` : "";
+      const cnt = d.added != null && d.removed != null ? ` (+${d.added} / -${d.removed} lines)` : "";
       checklist.push(`  - \`${d.file}\`${cnt}: \`diff -u .github/workflows/${d.file} ${d.incoming}\``);
     }
   }
   if (wf.added.length || wf.replacedBak.length) {
-    checklist.push(`- [ ] **새/갱신 CICD가 요구하는 GitHub Secrets 등록 확인** (Settings → Secrets → Actions, \`_GITHUB_PAT_TOKEN\` 포함)`);
+    checklist.push(`- [ ] **Check that the GitHub Secrets required by the new/updated CICD are registered** (Settings → Secrets → Actions, including \`_GITHUB_PAT_TOKEN\`)`);
   }
   if (envByType.size) {
-    checklist.push(`- [ ] **적용된 배포 환경값 검증** (실제 환경과 다르면 워크플로우 env를 직접 수정):`);
+    checklist.push(`- [ ] **Verify the applied deploy environment values** (edit the workflow env directly if they differ from your real environment):`);
     for (const [t, kv] of envByType) {
       for (const [k, v] of kv) checklist.push(`  - ${t} \`${k}\` = \`${v}\``);
     }
   }
   if (r.branches?.created === true) {
-    checklist.push(`- [x] 개발(릴리스 소스) 브랜치 \`${r.branches?.deployBranch ?? "develop"}\`: 마법사가 생성 및 확인 완료`);
+    checklist.push(`- [x] Development (release source) branch \`${r.branches?.deployBranch ?? "develop"}\`: created and verified by the wizard`);
   } else if (r.branches?.ready === false) {
-    checklist.push(`- [ ] 개발(릴리스 소스) 브랜치 \`${r.branches?.deployBranch ?? "develop"}\` 생성 (릴리스 PR이 동작하려면 필요합니다)`);
+    checklist.push(`- [ ] Create the development (release source) branch \`${r.branches?.deployBranch ?? "develop"}\` (required for the release PR to work)`);
   }
   if (checklist.length) {
-    L.push("### 확인 체크리스트");
+    L.push("### Checklist");
     L.push("");
     L.push(...checklist);
     L.push("");
@@ -144,7 +144,7 @@ export function renderGuideEntry(report) {
 
   // ── 버전 점프에서 통과한 호환성 변경 (조치 방법 전문 — 터미널에서 스킵해도 여기 남는다) ──
   if (breakingAll.length) {
-    L.push(`### 통과한 호환성 변경 (v${breaking.current} → v${breaking.target})`);
+    L.push(`### Breaking changes passed through (v${breaking.current} → v${breaking.target})`);
     L.push("");
     for (const it of breakingAll) {
       const sev = (breaking.critical ?? []).includes(it) ? "CRITICAL" : "WARNING";
@@ -155,7 +155,7 @@ export function renderGuideEntry(report) {
   }
 
   // ── AI 메타데이터 ──
-  L.push("### AI 메타데이터");
+  L.push("### AI metadata");
   L.push("");
   L.push("```yaml");
   L.push("# projectops-migration (machine-readable)");
@@ -164,7 +164,7 @@ export function renderGuideEntry(report) {
   L.push(`template: { from: ${yq(from)}, to: ${yq(to)} }`);
   L.push(`mode: ${r.mode || "full"}`);
   L.push(`types: ${ylist(r.types)}`);
-  L.push(`options: { deploy: ${yq(r.options?.deploy ?? "")}, publish: ${ylist(r.options?.publish)}, secret_backup: ${r.options?.secretBackup === true}, coderabbit: ${r.options?.coderabbit === true}, changelog_provider: ${yq(r.options?.changelogProvider ?? "")}, intent: ${yq(r.options?.intent ?? "")}, semver_auto: ${r.options?.semverAuto === true}, app_release: ${r.options?.appRelease === true} }`);
+  L.push(`options: { deploy: ${yq(r.options?.deploy ?? "")}, publish: ${ylist(r.options?.publish)}, secret_backup: ${r.options?.secretBackup === true}, coderabbit: ${r.options?.coderabbit === true}, changelog_provider: ${yq(r.options?.changelogProvider ?? "")}, intent: ${yq(r.options?.intent ?? "")}, semver_auto: ${r.options?.semverAuto === true}, language: ${yq(r.options?.language ?? "")}, label_style: ${yq(r.options?.labelStyle ?? "")}, close_on_release: ${r.options?.closeOnRelease === true}, app_release: ${r.options?.appRelease === true} }`);
   L.push(`branches: { default: ${yq(r.branches?.defaultBranch ?? "main")}, deploy: ${yq(r.branches?.deployBranch ?? "develop")}, deploy_branch_created: ${r.branches?.created === true} }`);
   L.push("workflows:");
   L.push(`  added: ${ylist(wf.added)}`);

package/src/core/migrations/index.js

@@ -2,10 +2,14 @@
 // 감지(registry × rules) → 계획 표시 → safe 티어 확인 1회 → 적용 → confirm 티어 안내.
 // 버전 번호를 믿지 않는다: 절반의 레거시 레포는 version.yml에 template 메타가 없다(실측).
 import { MIGRATIONS } from "./registry.js";
+import { t } from "../../i18n/index.js";
 import * as workflowRule from "./rules/obsolete-workflows.js";
 import * as rootFileRule from "./rules/root-files.js";
 import * as legacyDirRule from "./rules/legacy-dirs.js";
 
+// 사유는 화면 언어로 번역(reasonKey), 키가 없으면 원문 그대로
+const reasonOf = (e) => (e.reasonKey ? t(e.reasonKey) : e.reason);
+
 const RULES = {
   workflow: workflowRule,
   "root-file": rootFileRule,
@@ -53,60 +57,60 @@ export async function runMigrations({ targetRoot = ".", askYesNo = null, log = c
 
   let applied = [];
   if (safe.length > 0) {
-    log(`🧹 레거시 템플릿 파일 ${safe.length}개 감지 — 신형으로 대체되어 공존 시 중복 실행 위험:`);
+    log(t("migrate.safe.found", { n: safe.length }));
     for (const e of safe) {
       const arrow = e.replacedBy ? ` → ${e.replacedBy}` : "";
       log(`   • ${e.file}${arrow}`);
-      log(`     (${e.reason}, ${e.since}부터 폐기)`);
+      log(t("migrate.safe.reason", { reason: reasonOf(e), since: e.since }));
     }
     const yes = askYesNo
-      ? await askYesNo(`위 ${safe.length}개를 정리할까요? (워크플로우는 .bak 무해화 — 복원 가능)`, true)
+      ? await askYesNo(t("migrate.safe.ask", { n: safe.length }), true)
       : true;
     if (yes) {
       applied = applySafeMigrations(targetRoot, safe);
       const ok = applied.filter((r) => r.action !== "error");
       const failed = applied.filter((r) => r.action === "error");
-      log(`✅ 레거시 정리 완료: ${ok.length}개${failed.length ? ` (실패 ${failed.length}개)` : ""}`);
+      log(t("migrate.safe.done", { n: ok.length, failed: failed.length ? t("migrate.safe.failed", { n: failed.length }) : "" }));
       for (const f of failed) log(`   ⚠️ ${f.from}: ${f.error}`);
     } else {
-      log("→ 레거시 정리를 건너뜁니다 (다음 업데이트 때 다시 안내)");
+      log(t("migrate.safe.skip"));
     }
   }
 
   // ask 티어 (#476) — 사용자 문서가 담긴 구명칭 폴더: 대화형은 확인 후 이동, 비대화형은 안내만
   let askPending = [];
   if (ask.length > 0) {
-    log(`📁 구명칭 산출물 폴더 ${ask.length}개 감지 — 사용자 문서가 들어 있어 확인 후 이동합니다:`);
+    log(t("migrate.dir.found", { n: ask.length }));
     for (const e of ask) {
       log(`   • ${e.file}/ → ${e.replacedBy}/`);
-      log(`     (${e.reason})`);
+      log(`     (${reasonOf(e)})`);
     }
     if (askYesNo) {
-      const yes = await askYesNo("위 폴더를 새 이름으로 이동할까요? (파일 손실 없음 — 충돌 시 원본 유지)", true);
+      const yes = await askYesNo(t("migrate.dir.ask"), true);
       if (yes === true) {
         const results = applySafeMigrations(targetRoot, ask);
         applied = applied.concat(results);
         for (const r of results) {
           if (r.action === "error") log(`   ⚠️ ${r.from}: ${r.error}`);
-          else log(`   ✅ ${r.from}/ → ${r.to}/ (이동 ${r.moved ?? 0}개${r.skipped ? `, 충돌 유지 ${r.skipped}개` : ""})`);
+          else log(t("migrate.dir.moved", { from: r.from, to: r.to, moved: r.moved ?? 0, kept: r.skipped ? t("migrate.dir.kept", { n: r.skipped }) : "" }));
         }
       } else {
         askPending = ask;
-        log("→ 폴더 이동을 건너뜁니다 (다음 업데이트 때 다시 안내)");
+        log(t("migrate.dir.skip"));
       }
     } else {
       askPending = ask;
-      log("   비대화형 실행이라 자동으로 이동하지 않습니다 — 대화형 마법사(npx projectops)에서 확인 후 이동하세요.");
+      log(t("migrate.dir.nonInteractive"));
     }
   }
 
   if (confirm.length > 0) {
-    log(`⚠️ 구세대 배포 워크플로우 ${confirm.length}개 발견 — 현역 배포일 수 있어 자동으로 건드리지 않습니다:`);
+    log(t("migrate.confirm.found", { n: confirm.length }));
     for (const e of confirm) {
-      const arrow = e.replacedBy ? ` (신형: ${e.replacedBy})` : "";
-      log(`   • ${e.file}${arrow} — ${e.reason}`);
+      const arrow = e.replacedBy ? t("migrate.confirm.newer", { name: e.replacedBy }) : "";
+      log(`   • ${e.file}${arrow}: ${reasonOf(e)}`);
     }
-    log("   신형 워크플로우로 전환을 마친 뒤 구 파일을 직접 삭제하세요.");
+    log(t("migrate.confirm.hint"));
   }
 
   return { applied, confirmPending: confirm, askPending };

package/src/core/migrations/registry.js

@@ -24,183 +24,198 @@
 //                       (rules/settings-extractors.js의 EXTRACTORS 키)
 //
 // 데이터 출처: git 히스토리 삭제/리네임 전수 + 실제 통합 레포 14개 스캔 (2026-07-11, 설계 문서 참조)
+import { tEn } from "../../i18n/index.js";
+
 export const MIGRATIONS = [
   // ── workflow / safe — 순수 리네임·대체 (공존 시 중복 실행 실해) ──────────────
   { id: "wf-version-control", category: "workflow", tier: "safe",
     file: "PROJECT-VERSION-CONTROL.yaml", replacedBy: "PROJECT-COMMON-VERSION-CONTROL.yaml",
-    since: "2.x", reason: "1세대 리네임 — 공존 시 버전 이중 증가" },
+    since: "2.x", reasonKey: "migrate.reason.gen1VersionControl" },
   { id: "wf-readme-version-update", category: "workflow", tier: "safe",
     file: "PROJECT-README-VERSION-UPDATE.yaml", replacedBy: "PROJECT-COMMON-README-VERSION-UPDATE.yaml",
-    since: "2.x", reason: "1세대 리네임 — 공존 시 README 이중 커밋" },
+    since: "2.x", reasonKey: "migrate.reason.gen1Readme" },
   { id: "wf-sync-issue-labels-v1", category: "workflow", tier: "safe",
     file: "PROJECT-SYNC-ISSUE-LABELS.yaml", replacedBy: "PROJECT-COMMON-SYNC-ISSUE-LABELS.yaml",
-    since: "2.x", reason: "1세대 리네임 — 공존 시 라벨 동기화 중복" },
+    since: "2.x", reasonKey: "migrate.reason.gen1Labels" },
   { id: "wf-sync-issue-labels-v0", category: "workflow", tier: "safe",
     file: "sync-issue-labels.yaml", replacedBy: "PROJECT-COMMON-SYNC-ISSUE-LABELS.yaml",
-    since: "2.x", reason: "0세대 리네임 — 공존 시 라벨 동기화 중복" },
+    since: "2.x", reasonKey: "migrate.reason.gen0Labels" },
   { id: "wf-issue-comment-v1", category: "workflow", tier: "safe",
     file: "PROJECT-ISSUE-COMMENT.yaml", replacedBy: "PROJECT-COMMON-SUH-ISSUE-HELPER.yaml",
-    since: "2.x", reason: "이슈 헬퍼 1세대 — 공존 시 이슈 댓글 중복" },
+    since: "2.x", reasonKey: "migrate.reason.helperGen1" },
   { id: "wf-issue-comment-v2", category: "workflow", tier: "safe",
     file: "PROJECT-COMMON-ISSUE-COMMENT.yaml", replacedBy: "PROJECT-COMMON-SUH-ISSUE-HELPER.yaml",
-    since: "2.x", reason: "이슈 헬퍼 2세대 — 공존 시 이슈 댓글 중복" },
+    since: "2.x", reasonKey: "migrate.reason.helperGen2" },
   { id: "wf-issue-helper-api", category: "workflow", tier: "safe",
     file: "PROJECT-COMMON-SUH-ISSUE-HELPER-API.yaml", replacedBy: "PROJECT-COMMON-SUH-ISSUE-HELPER.yaml",
-    since: "4.3.0", reason: "이슈 헬퍼 API 버전 폐기 (dispatch 전용 비활성 잔재)" },
+    since: "4.3.0", reasonKey: "migrate.reason.helperApi" },
   { id: "wf-issue-helper-module", category: "workflow", tier: "safe",
     file: "PROJECT-COMMON-SUH-ISSUE-HELPER-MODULE.yml", replacedBy: "PROJECT-COMMON-SUH-ISSUE-HELPER.yaml",
-    since: "4.3.0", reason: "외부 액션 내재화(#478) — 공존 시 이슈 댓글 중복",
+    since: "4.3.0", reasonKey: "migrate.reason.helperModule",
     settingsExtractor: "suh-issue-helper-module" }, // 무해화 전 with: 커스텀 값을 version.yml로 이관
   { id: "wf-auto-changelog-v1", category: "workflow", tier: "safe",
     file: "PROJECT-AUTO-CHANGELOG-CONTROL.yaml", replacedBy: "PROJECT-COMMON-RELEASE-CHANGELOG.yaml",
-    since: "2.x", reason: "릴리스 워크플로우 1세대 — 공존 시 릴리스 PR 이중 처리" },
+    since: "2.x", reasonKey: "migrate.reason.releaseGen1" },
   { id: "wf-auto-changelog-v2", category: "workflow", tier: "safe",
     file: "PROJECT-COMMON-AUTO-CHANGELOG-CONTROL.yaml", replacedBy: "PROJECT-COMMON-RELEASE-CHANGELOG.yaml",
-    since: "4.3.0", reason: "RELEASE-CHANGELOG로 리네임 — 공존 시 릴리스 PR 이중 처리" },
+    since: "4.3.0", reasonKey: "migrate.reason.releaseRename" },
   { id: "wf-comqa-bot", category: "workflow", tier: "safe",
     file: "COMQA-ISSUE-CREATION-BOT.yaml", replacedBy: "PROJECT-COMMON-QA-ISSUE-CREATION-BOT.yaml",
-    since: "2.x", reason: "QA 봇 구명칭 — 공존 시 QA 이슈 중복 생성" },
+    since: "2.x", reasonKey: "migrate.reason.qaBot" },
   { id: "wf-template-util-sync", category: "workflow", tier: "safe",
     file: "TEMPLATE-UTIL-VERSION-SYNC.yml", replacedBy: "PROJECT-COMMON-TEMPLATE-UTIL-VERSION-SYNC.yml",
-    since: "2.x", reason: "구명칭 — 공존 시 util 버전 동기화 중복" },
+    since: "2.x", reasonKey: "migrate.reason.utilSync" },
   { id: "wf-backlog-manager", category: "workflow", tier: "safe",
     file: "PROJECT-COMMON-PROJECT-BACKLOG-MANAGER.yaml", replacedBy: "PROJECT-COMMON-PROJECTS-SYNC-MANAGER.yaml",
-    since: "3.x", reason: "Projects 동기화로 대체 — 공존 시 보드 상태 중복 갱신" },
+    since: "3.x", reasonKey: "migrate.reason.projectsSync" },
   { id: "wf-suh-lab-build-trigger", category: "workflow", tier: "safe",
     file: "PROJECT-FLUTTER-SUH-LAB-APP-BUILD-TRIGGER.yaml", replacedBy: "PROJECT-FLUTTER-PROJECTOPS-APP-BUILD-TRIGGER.yaml",
-    since: "4.3.0", reason: "리브랜딩 리네임 — 공존 시 빌드 트리거 중복" },
+    since: "4.3.0", reasonKey: "migrate.reason.buildTrigger" },
   { id: "wf-next-ci", category: "workflow", tier: "safe",
     file: "PROJECT-NEXT-CI.yaml", replacedBy: "PROJECT-REACT-CI.yaml",
-    since: "4.1.0", reason: "next 타입 폐지 (react 흡수)" },
+    since: "4.1.0", reasonKey: "migrate.reason.nextType" },
   { id: "wf-next-cicd", category: "workflow", tier: "safe",
     file: "PROJECT-NEXT-CICD.yaml", replacedBy: "PROJECT-REACT-CICD.yaml",
-    since: "4.1.0", reason: "next 타입 폐지 (react 흡수)" },
+    since: "4.1.0", reasonKey: "migrate.reason.nextType" },
   { id: "wf-flutter-ci-yml-ext", category: "workflow", tier: "safe",
     file: "PROJECT-FLUTTER-CI.yml", replacedBy: "PROJECT-FLUTTER-CI.yaml",
-    since: "2.x", reason: "구 확장자(.yml) — 현행 .yaml과 공존 시 CI 중복 실행" },
+    since: "2.x", reasonKey: "migrate.reason.ymlExt" },
   { id: "wf-flutter-android-pr-ci", category: "workflow", tier: "safe",
     file: "PROJECT-FLUTTER-ANDROID-PR-CI.yaml", replacedBy: "PROJECT-FLUTTER-CI.yaml",
-    since: "3.x", reason: "통합 CI로 흡수 — 공존 시 PR CI 중복 실행" },
+    since: "3.x", reasonKey: "migrate.reason.mergedCi" },
 
   // ── workflow / confirm — 배포/업로드 계열 (현역 배포일 수 있어 자동 조치 금지) ──
   { id: "wf-syn-spring-simple", category: "workflow", tier: "confirm",
     file: "PROJECT-SPRING-SYNOLOGY-SIMPLE-CICD.yaml", replacedBy: "PROJECT-SPRING-SIMPLE-CICD.yaml",
-    since: "3.0.137", reason: "SYNOLOGY 폐기 — SSH+Docker 엔진으로 대체됨" },
+    since: "3.0.137", reasonKey: "migrate.reason.synSsh" },
   { id: "wf-syn-spring-nonstop", category: "workflow", tier: "confirm",
     file: "PROJECT-SPRING-SYNOLOGY-NONSTOP-CICD.yaml", replacedBy: "PROJECT-SPRING-NONSTOP-NGINX-CICD.yaml",
-    since: "3.0.137", reason: "SYNOLOGY 폐기 — 무중단 배포는 NGINX/TRAEFIK 버전으로 대체됨" },
+    since: "3.0.137", reasonKey: "migrate.reason.synNonstop" },
   { id: "wf-syn-spring-preview", category: "workflow", tier: "confirm",
     file: "PROJECT-SPRING-SYNOLOGY-PR-PREVIEW.yaml", replacedBy: "PROJECT-SPRING-PR-PREVIEW.yaml",
-    since: "3.0.137", reason: "SYNOLOGY 폐기" },
+    since: "3.0.137", reasonKey: "migrate.reason.syn" },
   { id: "wf-syn-flutter-android", category: "workflow", tier: "confirm",
     file: "PROJECT-FLUTTER-ANDROID-SYNOLOGY-CICD.yaml", replacedBy: "PROJECT-FLUTTER-ANDROID-SELFHOSTED-CICD.yaml",
-    since: "3.0.137", reason: "SYNOLOGY 폐기 — SELFHOSTED(SMB)로 대체됨" },
+    since: "3.0.137", reasonKey: "migrate.reason.synSmb" },
   { id: "wf-syn-python-cicd", category: "workflow", tier: "confirm",
     file: "PROJECT-PYTHON-SYNOLOGY-CICD.yaml", replacedBy: "PROJECT-PYTHON-SIMPLE-CICD.yaml",
-    since: "3.0.137", reason: "SYNOLOGY 폐기" },
+    since: "3.0.137", reasonKey: "migrate.reason.syn" },
   { id: "wf-syn-python-preview", category: "workflow", tier: "confirm",
     file: "PROJECT-PYTHON-SYNOLOGY-PR-PREVIEW.yaml", replacedBy: "PROJECT-PYTHON-PR-PREVIEW.yaml",
-    since: "3.0.137", reason: "SYNOLOGY 폐기" },
+    since: "3.0.137", reasonKey: "migrate.reason.syn" },
   { id: "wf-syn-secret-upload", category: "workflow", tier: "confirm",
     file: "PROJECT-COMMON-SYNOLOGY-SECRET-FILE-UPLOAD.yaml", replacedBy: "PROJECT-COMMON-SECRET-FILE-UPLOAD.yaml",
-    since: "3.0.137", reason: "SYNOLOGY 폐기 — 공통 Secret 업로드로 대체됨" },
+    since: "3.0.137", reasonKey: "migrate.reason.synSecret" },
+  // #661 — 템플릿에서 사라졌는데 레거시로 잡히지 않던 릴리스 워크플로우. 이 파일의 trunk-based 분기는
+  // 지금은 없는 `changelog_manager.py ai-summary` 를 불러 릴리스 때 실패한다. 그 레포의 유일한
+  // 릴리스 경로일 수 있어 자동으로 건드리지 않고 안내만 한다. 같은 파일명을 쓰는 사용자 파일을
+  // 오탐하지 않도록 내용 마커로 한 번 더 확인한다.
+  { id: "wf-release-publish-v1", category: "workflow", tier: "confirm",
+    file: "PROJECT-COMMON-RELEASE-PUBLISH.yaml", replacedBy: "PROJECT-COMMON-RELEASE-CHANGELOG.yaml",
+    since: "2.x", reasonKey: "migrate.reason.releasePublish1", contentMarker: "ai-summary" },
   { id: "wf-spring-ci-v1", category: "workflow", tier: "confirm",
     file: "PROJECT-SPRING-CI.yaml", replacedBy: null,
-    since: "2.x", reason: "1세대 Spring CI — 현행 대체본 없음(CICD에 통합)" },
+    since: "2.x", reasonKey: "migrate.reason.springCi1" },
   { id: "wf-spring-cicd-v1", category: "workflow", tier: "confirm",
     file: "PROJECT-SPRING-CICD.yaml", replacedBy: "PROJECT-SPRING-SIMPLE-CICD.yaml",
-    since: "2.x", reason: "1세대 Spring 배포 — 현역 배포일 수 있음" },
+    since: "2.x", reasonKey: "migrate.reason.springDeploy1" },
   { id: "wf-python-cicd-v1", category: "workflow", tier: "confirm",
     file: "PROJECT-PYTHON-CICD.yaml", replacedBy: "PROJECT-PYTHON-SIMPLE-CICD.yaml",
-    since: "3.x", reason: "구 Python 배포 — 현역 배포일 수 있음" },
+    since: "3.x", reasonKey: "migrate.reason.pythonDeploy1" },
   { id: "wf-android-cicd-v1", category: "workflow", tier: "confirm",
     file: "PROJECT-ANDROID-CICD.yaml", replacedBy: "PROJECT-FLUTTER-ANDROID-PLAYSTORE-CICD.yaml",
-    since: "2.x", reason: "1세대 Android 배포 — 현역 배포일 수 있음" },
+    since: "2.x", reasonKey: "migrate.reason.androidDeploy1" },
   { id: "wf-ios-testflight-v1", category: "workflow", tier: "confirm",
     file: "PROJECT-IOS-TESTFLIGHT-CICD.yml", replacedBy: "PROJECT-FLUTTER-IOS-TESTFLIGHT.yaml",
-    since: "2.x", reason: "1세대 iOS 배포 — 현역 배포일 수 있음" },
+    since: "2.x", reasonKey: "migrate.reason.iosDeploy1" },
   { id: "wf-flutter-ios-cicd", category: "workflow", tier: "confirm",
     file: "PROJECT-FLUTTER-IOS-CICD.yaml", replacedBy: "PROJECT-FLUTTER-IOS-TESTFLIGHT.yaml",
-    since: "3.x", reason: "TESTFLIGHT 워크플로우로 대체 — 현역 배포일 수 있음" },
+    since: "3.x", reasonKey: "migrate.reason.iosTestflight" },
   { id: "wf-file-upload-spring", category: "workflow", tier: "confirm",
     file: "PROJECT-SPRING-AUTO-FILE-UPLOAD.yaml", replacedBy: "PROJECT-COMMON-SECRET-FILE-UPLOAD.yaml",
-    since: "3.x", reason: "공통 Secret 업로드로 대체 — 운영 업로드 경로일 수 있음" },
+    since: "3.x", reasonKey: "migrate.reason.secretUpload" },
   { id: "wf-file-upload-flutter", category: "workflow", tier: "confirm",
     file: "PROJECT-FLUTTER-AUTO-FILE-UPLOAD.yaml", replacedBy: "PROJECT-COMMON-SECRET-FILE-UPLOAD.yaml",
-    since: "3.x", reason: "공통 Secret 업로드로 대체 — 운영 업로드 경로일 수 있음" },
+    since: "3.x", reasonKey: "migrate.reason.secretUpload" },
   { id: "wf-file-upload-python", category: "workflow", tier: "confirm",
     file: "PROJECT-PYTHON-AUTO-FILE-UPLOAD.yaml", replacedBy: "PROJECT-COMMON-SECRET-FILE-UPLOAD.yaml",
-    since: "3.x", reason: "공통 Secret 업로드로 대체 — 운영 업로드 경로일 수 있음" },
+    since: "3.x", reasonKey: "migrate.reason.secretUpload" },
   { id: "wf-file-upload-v1", category: "workflow", tier: "confirm",
     file: "PROJECT-FILE-AUTO-UPLOAD.yaml", replacedBy: "PROJECT-COMMON-SECRET-FILE-UPLOAD.yaml",
-    since: "2.x", reason: "공통 Secret 업로드로 대체 — 운영 업로드 경로일 수 있음" },
+    since: "2.x", reasonKey: "migrate.reason.secretUpload" },
   { id: "wf-nexus-publish-v1", category: "workflow", tier: "confirm",
     file: "PROJECT-NEXUS-PUBLISH.yml", replacedBy: "PROJECT-SPRING-NEXUS-PUBLISH.yml",
-    since: "2.x", reason: "구 Nexus 배포 — 현역 라이브러리 배포일 수 있음" },
+    since: "2.x", reasonKey: "migrate.reason.nexusPublish" },
   { id: "wf-nexus-ci-v1", category: "workflow", tier: "confirm",
     file: "PROJECT-NEXUS-MODULE-CI-BUILD-CHECK.yml", replacedBy: "PROJECT-SPRING-NEXUS-CI.yml",
-    since: "2.x", reason: "구 Nexus CI" },
+    since: "2.x", reasonKey: "migrate.reason.nexusCi" },
   { id: "wf-ci-build-check-v0", category: "workflow", tier: "confirm",
     file: "PROJECT-CI-BUILD-CHECK.yml", replacedBy: "PROJECT-SPRING-NEXUS-CI.yml",
-    since: "2.x", reason: "0세대 라이브러리 CI" },
+    since: "2.x", reasonKey: "migrate.reason.libCi0" },
   { id: "wf-publish-v0", category: "workflow", tier: "confirm",
     file: "PROJECT-PUBLISH.yml", replacedBy: "PROJECT-SPRING-NEXUS-PUBLISH.yml",
-    since: "2.x", reason: "0세대 라이브러리 배포 — 현역 배포일 수 있음" },
+    since: "2.x", reasonKey: "migrate.reason.libPublish0" },
   { id: "wf-deploy-trigger", category: "workflow", tier: "confirm",
     file: "PROJECT-DEPLOY-TRIGGER.yaml", replacedBy: null,
-    since: "3.x", reason: "폐기된 배포 트리거" },
+    since: "3.x", reasonKey: "migrate.reason.deployTrigger" },
 
   // ── root-file / safe — 구 설치 가이드 (사용자가 매번 수동 삭제하던 것) ─────────
   { id: "root-setup-guide-v2", category: "root-file", tier: "safe",
     file: "SUH-DEVOPS-TEMPLATE-SETUP-GUIDE.md", replacedBy: "PROJECTOPS-SETUP-GUIDE.md",
-    since: "4.3.0", reason: "리브랜딩으로 구 가이드 대체 — 잔재 문서" },
+    since: "4.3.0", reasonKey: "migrate.reason.guideRebrand" },
   { id: "root-setup-guide-v1", category: "root-file", tier: "safe",
     file: "SETUP-GUIDE.md", replacedBy: "PROJECTOPS-SETUP-GUIDE.md",
-    since: "2.x", reason: "구 가이드 문서 — 잔재",
+    since: "2.x", reasonKey: "migrate.reason.guideOld",
     contentMarker: "SUH" }, // 범용 파일명이라 내용에 템플릿 마커가 있을 때만 소유 판정
 
   // ── legacy-dir / ask — 구명칭 산출물 폴더 (사용자 문서 보존 이동, #476) ────────
   { id: "dir-docs-suh-template", category: "legacy-dir", tier: "ask",
     file: "docs/suh-template", replacedBy: "docs/projectops",
-    since: "4.2.9", reason: "리브랜딩 — 스킬 산출물(이슈·보고서) 폴더 구명칭. 신 스킬은 docs/projectops/에 저장" },
+    since: "4.2.9", reasonKey: "migrate.reason.docsDir" },
 
   // ── util-file / safe — Flutter 마법사 스크립트 Python 단일화 (#500) ──────────
   // 로컬 실행 도구라 CI 중복 실행 위험은 없지만, 신형 py와 공존 시 사용자가 구 스크립트를
   // 실행해 갈라진 동작을 볼 수 있다. 마법사 폴더에 사용자 상태가 없어 삭제가 기대 동작.
   { id: "util-playstore-setup-sh", category: "util-file", tier: "safe",
     file: ".github/util/flutter/playstore-wizard/playstore-wizard-setup.sh", replacedBy: "playstore-wizard.py",
-    since: "4.3.0", reason: "마법사 스크립트 Python 단일화 — setup 서브커맨드로 대체" },
+    since: "4.3.0", reasonKey: "migrate.reason.wizSetup" },
   { id: "util-playstore-setup-ps1", category: "util-file", tier: "safe",
     file: ".github/util/flutter/playstore-wizard/playstore-wizard-setup.ps1", replacedBy: "playstore-wizard.py",
-    since: "4.3.0", reason: "마법사 스크립트 Python 단일화 — setup 서브커맨드로 대체" },
+    since: "4.3.0", reasonKey: "migrate.reason.wizSetup" },
   { id: "util-playstore-apply-sh", category: "util-file", tier: "safe",
     file: ".github/util/flutter/playstore-wizard/playstore-wizard-apply.sh", replacedBy: "playstore-wizard.py",
-    since: "4.3.0", reason: "마법사 스크립트 Python 단일화 — apply 서브커맨드로 대체" },
+    since: "4.3.0", reasonKey: "migrate.reason.wizApply" },
   { id: "util-playstore-apply-ps1", category: "util-file", tier: "safe",
     file: ".github/util/flutter/playstore-wizard/playstore-wizard-apply.ps1", replacedBy: "playstore-wizard.py",
-    since: "4.3.0", reason: "마법사 스크립트 Python 단일화 — apply 서브커맨드로 대체" },
+    since: "4.3.0", reasonKey: "migrate.reason.wizApply" },
   { id: "util-playstore-detect-sh", category: "util-file", tier: "safe",
     file: ".github/util/flutter/playstore-wizard/detect-application-id.sh", replacedBy: "playstore-wizard.py",
-    since: "4.3.0", reason: "마법사 스크립트 Python 단일화 — detect-app-id 서브커맨드로 대체" },
+    since: "4.3.0", reasonKey: "migrate.reason.wizDetect" },
   { id: "util-playstore-detect-ps1", category: "util-file", tier: "safe",
     file: ".github/util/flutter/playstore-wizard/detect-application-id.ps1", replacedBy: "playstore-wizard.py",
-    since: "4.3.0", reason: "마법사 스크립트 Python 단일화 — detect-app-id 서브커맨드로 대체" },
+    since: "4.3.0", reasonKey: "migrate.reason.wizDetect" },
   { id: "util-playstore-patch-py", category: "util-file", tier: "safe",
     file: ".github/util/flutter/playstore-wizard/patch-build-gradle.py", replacedBy: "playstore-wizard.py",
-    since: "4.3.0", reason: "마법사 스크립트 Python 단일화 — 내부 함수로 흡수" },
+    since: "4.3.0", reasonKey: "migrate.reason.wizPatch" },
   { id: "util-firebase-setup-sh", category: "util-file", tier: "safe",
     file: ".github/util/flutter/firebase-wizard/firebase-wizard-setup.sh", replacedBy: "firebase-wizard.py",
-    since: "4.3.0", reason: "마법사 스크립트 Python 단일화 — setup 서브커맨드로 대체" },
+    since: "4.3.0", reasonKey: "migrate.reason.wizSetup" },
   { id: "util-firebase-setup-ps1", category: "util-file", tier: "safe",
     file: ".github/util/flutter/firebase-wizard/firebase-wizard-setup.ps1", replacedBy: "firebase-wizard.py",
-    since: "4.3.0", reason: "마법사 스크립트 Python 단일화 — setup 서브커맨드로 대체" },
+    since: "4.3.0", reasonKey: "migrate.reason.wizSetup" },
   { id: "util-firebase-test-sh", category: "util-file", tier: "safe",
     file: ".github/util/flutter/firebase-wizard/test/setup-script-test.sh", replacedBy: "test/setup-script-test.py",
-    since: "4.3.0", reason: "마법사 테스트 Python 단일화" },
+    since: "4.3.0", reasonKey: "migrate.reason.wizTest" },
   { id: "util-firebase-test-ps1", category: "util-file", tier: "safe",
     file: ".github/util/flutter/firebase-wizard/test/setup-script-test.ps1", replacedBy: "test/setup-script-test.py",
-    since: "4.3.0", reason: "마법사 테스트 Python 단일화" },
+    since: "4.3.0", reasonKey: "migrate.reason.wizTest" },
   { id: "util-testflight-setup-sh", category: "util-file", tier: "safe",
     file: ".github/util/flutter/testflight-wizard/testflight-wizard-setup.sh", replacedBy: "testflight-wizard.py",
-    since: "4.3.0", reason: "마법사 스크립트 Python 단일화 — setup 서브커맨드로 대체" },
+    since: "4.3.0", reasonKey: "migrate.reason.wizSetup" },
 ];
+
+// 사유는 영문 정본(tEn)으로 노출해 실행 로그·가이드에 그대로 쓰고,
+// 화면 표시는 reasonKey를 t()로 번역해 쓴다.
+for (const m of MIGRATIONS) {
+  Object.defineProperty(m, "reason", { enumerable: true, get: () => tEn(m.reasonKey) });
+}