projectops 4.2.7 → 4.2.9

package/README.md

@@ -7,7 +7,7 @@
 > 이슈 등록부터 커밋, 보고서, 배포까지. 개발자는 코드만 작성하세요.
 
 <!-- AUTO-VERSION-SECTION: DO NOT EDIT MANUALLY -->
-## 최신 버전 : v4.2.6 (2026-07-10)
+## 최신 버전 : v4.2.8 (2026-07-10)
 
 [전체 버전 기록 보기](CHANGELOG.md)
 
@@ -93,22 +93,7 @@ npx projectops
 
 > Node.js 20.12+ 만 있으면 별도 설치 없이 대화형 마법사가 실행됩니다. 비대화형: `npx projectops --mode full --type spring,react --force`
 
-<details>
-<summary>대안 — 스크립트 직접 실행 (Node 없이, <b>deprecated</b>)</summary>
-
-> ⚠️ **`template_integrator.sh` / `.ps1`은 deprecated입니다 (#458).** 실행하면 `npx projectops`로 안내하며, 다음 minor에서 제거될 수 있습니다. Node 20.12+를 쓸 수 있으면 위의 `npx projectops`를 사용하세요.
-
-```bash
-# macOS / Linux
-bash <(curl -fsSL "https://raw.githubusercontent.com/Cassiiopeia/projectops/main/template_integrator.sh")
-```
-
-```powershell
-# Windows PowerShell
-$wc=New-Object Net.WebClient;$wc.Encoding=[Text.Encoding]::UTF8;iex $wc.DownloadString("https://raw.githubusercontent.com/Cassiiopeia/projectops/main/template_integrator.ps1")
-```
-
-</details>
+> ⚠️ 구 `template_integrator.sh` / `.ps1`은 **지원 종료(EOF)** 되었습니다 (#458). 실행하면 `npx projectops` 안내만 출력하며, 다음 minor에서 파일이 제거됩니다.
 
 ### Agent Skills만 설치
 
@@ -137,14 +122,7 @@ Codex plugin marketplace를 사용할 수 없는 환경에서는 [Skills 가이
 npx projectops --mode skills
 ```
 
-<details>
-<summary>대안 — 스크립트 직접 실행 (Node 없이)</summary>
-
-```bash
-bash <(curl -fsSL "https://raw.githubusercontent.com/Cassiiopeia/projectops/main/template_integrator.sh") --mode skills
-```
 
-</details>
 
 > Claude Code는 `/projectops:` 자동완성, Gemini는 extension, Codex는 plugin marketplace를 우선 사용합니다. 자세한 설치 방식은 [Skills 가이드](docs/SKILLS.md)를 확인하세요.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "projectops",
-  "version": "4.2.7",
+  "version": "4.2.9",
   "description": "ProjectOps — 완전 자동화 GitHub 프로젝트 관리 템플릿 통합 CLI",
   "keywords": [
     "devops",

package/src/commands/interactive.js

@@ -10,6 +10,7 @@ import { acquireTemplate, readTemplateVersion } from "../core/assets.js";
 import { detectTypes, detectVersion, detectDefaultBranch, detectRepoName, makeResolvers } from "../core/detect-fs.js";
 import { parseExisting } from "../core/version-yml.js";
 import { runBreakingCheck } from "../core/breaking-check.js";
+import { runMigrations } from "../core/migrations/index.js";
 import { resolveProjectPaths } from "../core/paths-resolve.js";
 import { askAllOptionalWorkflows } from "../core/options-ask.js";
 import { promptEnvPlan } from "../ui/env-plan.js";
@@ -243,6 +244,14 @@ export async function runInteractive(baseCtx, { cwd = process.cwd(), source = {
       }
     }
 
+    // 레거시 마이그레이션 (#470) — 워크플로우를 만지는 모드에서만. 대화형은 safe 티어 확인 1회.
+    if (mode === "full" || mode === "workflows") {
+      await runMigrations({
+        targetRoot: cwd,
+        askYesNo: (msg, def) => io.askYesNo(msg, def),
+      });
+    }
+
     let result = null;
     if (mode === "full") result = runFull(ctx, tempDir, cwd, hooks);
     else if (mode === "version") result = runVersion(ctx, tempDir, cwd);

package/src/commands/workflows.js

@@ -7,13 +7,22 @@ import { PATHS } from "../core/paths.js";
 import { copyWorkflows } from "../core/copy/workflows.js";
 import { copyScripts, copyConfigFolder, copySetupGuide } from "../core/copy/simple.js";
 import { copyUtilModules } from "../core/copy/util.js";
+import { convertLegacySingularType } from "../core/version-yml.js";
 
 export function runWorkflows(context, tempDir, targetRoot = ".", hooks = {}) {
   const { types = [], force = true } = context;
   const wf = copyWorkflows(context, tempDir, targetRoot, hooks);
 
-  // update_version_yml_deploy: 기존 version.yml이 있고 ask 값이 있을 때만 deploy 블록 갱신
   const vy = join(targetRoot, PATHS.versionFile);
+
+  // v4.1.0 이전 단수 project_type 최소 변환 (#471) — 여기서 복사되는 신형 version_manager가
+  // 단수 키를 거부하므로, 변환 없이 두면 버전 워크플로우가 전부 실패하는 깨진 상태가 된다.
+  if (existsSync(vy)) {
+    const converted = convertLegacySingularType(readFileSync(vy, "utf8"));
+    if (converted !== null) writeFileSync(vy, converted);
+  }
+
+  // update_version_yml_deploy: 기존 version.yml이 있고 ask 값이 있을 때만 deploy 블록 갱신
   if (existsSync(vy) && wf.deployValues && wf.deployValues.size) {
     writeFileSync(vy, upsertDeployBlock(readFileSync(vy, "utf8"), wf.deployValues));
   }

package/src/core/copy/simple.js

@@ -7,11 +7,16 @@ import { exists, copyFileSync, copyDirSync } from "../fsutil.js";
 
 // 버전관리/릴리스노트 스크립트만 무조건 덮어쓰기 + chmod +x.
 // version_manager는 .sh(위임 shim) + .py(실 로직) 한 쌍 — 둘 다 복사해야 동작 (#448).
+// changelog provider 사다리(.py 5종, #455)는 RELEASE-CHANGELOG 워크플로우 fallback-summary가
+// 호출하므로 함께 복사해야 사용자 프로젝트에서 릴리스 노트 생성이 동작한다.
 export function copyScripts(tempDir, targetRoot = ".") {
   const scripts = [
     "version_manager.sh", "version_manager.py",
     "changelog_manager.py",
     "truncate_release_notes.sh", "truncate_release_notes.py",
+    "changelog_providers/_common.py", "changelog_providers/ladder.py",
+    "changelog_providers/commit.py", "changelog_providers/github_ai.py",
+    "changelog_providers/openai_compatible.py",
   ];
   let copied = 0;
   for (const s of scripts) {

package/src/core/detect-fs.js

@@ -3,7 +3,7 @@
 import { existsSync, readFileSync, readdirSync } from "node:fs";
 import { join, basename } from "node:path";
 import { execFileSync } from "node:child_process";
-import { detectTypesFromMarkers, detectVersionFromFiles } from "./detect.js";
+import { detectTypesFromMarkers, detectVersionFromFiles, suggestTypesByExtScan } from "./detect.js";
 import { parseExisting } from "./version-yml.js";
 
 const hasFile = (root) => (rel) => existsSync(join(root, rel));
@@ -17,14 +17,44 @@ function gitOut(root, args) {
   } catch { return ""; }
 }
 
+// 확장자 스캔용 파일 목록 (.sh suggest_types_by_scan find 등가 — depth≤3, vendor 폴더 프루닝).
+const SCAN_PRUNE = new Set([
+  "node_modules", ".git", "build", "dist", ".dart_tool",
+  "android", "ios", ".gradle", "venv", ".venv", "__pycache__",
+]);
+export function listScanFiles(root, maxDepth = 3) {
+  const files = [];
+  const walk = (rel, depth) => {
+    if (depth > maxDepth) return;
+    let entries;
+    try { entries = readdirSync(join(root, rel), { withFileTypes: true }); } catch { return; }
+    for (const e of entries) {
+      const childRel = rel ? `${rel}/${e.name}` : e.name;
+      if (e.isDirectory()) {
+        if (!SCAN_PRUNE.has(e.name)) walk(childRel, depth + 1);
+      } else {
+        files.push(childRel);
+      }
+    }
+  };
+  walk("", 1);
+  return files;
+}
+
 // 타입 감지 — version.yml의 project_types 최우선(source of truth), 없으면 마커 스캔.
+// 마커도 전혀 없으면(basic 폴백) 확장자 빈도 스캔으로 2차 추천 (.sh suggest_types_by_scan 등가, #458).
 export function detectTypes(root) {
   const vy = join(root, "version.yml");
   if (existsSync(vy)) {
     const { types } = parseExisting(readFileSync(vy, "utf8"));
     if (types.length) return types; // basic 포함, 명시돼 있으면 그대로
   }
-  return detectTypesFromMarkers({ has: hasFile(root), read: readFile(root) });
+  const byMarkers = detectTypesFromMarkers({ has: hasFile(root), read: readFile(root) });
+  if (byMarkers.length === 1 && byMarkers[0] === "basic") {
+    const scanned = suggestTypesByExtScan(listScanFiles(root));
+    if (scanned.length) return scanned; // 추천값 — 마법사 확인/수정 루프에서 사용자가 확정
+  }
+  return byMarkers;
 }
 
 // 버전 감지 — .sh detect_version 순서. jq 유무는 command 존재로 판정.

package/src/core/detect.js

@@ -60,3 +60,19 @@ export function markerForType(type) {
 export function extraMarkers(type) {
   return { python: ["setup.py", "requirements.txt"], spring: ["build.gradle.kts", "pom.xml"] }[type] || [];
 }
+
+// 확장자 빈도 스캔 추천 (.sh suggest_types_by_scan 2단계 등가, #458 npx 이식).
+// 마커가 전혀 없을 때(=basic 폴백)만 쓰는 2차 추천. files = 프루닝된 상대경로 목록.
+// 임계: dart≥1→flutter, java+kt+gradle≥3→spring, tsx+jsx≥3→react, py≥3→python,
+//       아무것도 없고 ts+js≥3→node. 반환은 메뉴 정의 순서로 정렬.
+export function suggestTypesByExtScan(files) {
+  const count = (re) => files.filter((f) => re.test(f)).length;
+  const found = new Set();
+  if (count(/\.dart$/) >= 1) found.add("flutter");
+  if (count(/\.java$/) + count(/\.kt$/) + count(/\.gradle$/) >= 3) found.add("spring");
+  if (count(/\.tsx$/) + count(/\.jsx$/) >= 3) found.add("react");
+  if (count(/\.py$/) >= 3) found.add("python");
+  if (found.size === 0 && count(/\.ts$/) + count(/\.js$/) >= 3) found.add("node");
+  const order = ["spring", "flutter", "react", "react-native", "react-native-expo", "node", "python"];
+  return order.filter((t) => found.has(t));
+}

package/src/core/exclusions.js

@@ -1,6 +1,7 @@
-// 템플릿 다운로드 후 제거하는 항목 — .sh download_template 내부 배열과 동기화
-// ⚠️ CLAUDE.md "3곳 동시 수정" 규칙의 4번째 동기화 지점:
-//    template_initializer.sh / template_integrator.sh / .ps1 / 이 파일
+// 템플릿 다운로드 후 제거하는 항목 (복사 제외 목록).
+// ⚠️ CLAUDE.md "템플릿 전용 파일 추가" 규칙의 동기화 지점:
+//    template_initializer.sh(삭제) / 이 파일(복사 제외)
+//    (구 template_integrator.sh/.ps1의 배열은 #458 EOF로 소멸 — 여기가 유일한 복사 제외 지점)
 export const DOCS_TO_REMOVE = [
   "CONTRIBUTING.md",
   "CLAUDE.md",

package/src/core/migrations/index.js

@@ -0,0 +1,78 @@
+// 레거시 마이그레이션 진입점 (#470) — 신호 기반·멱등.
+// 감지(registry × rules) → 계획 표시 → safe 티어 확인 1회 → 적용 → confirm 티어 안내.
+// 버전 번호를 믿지 않는다: 절반의 레거시 레포는 version.yml에 template 메타가 없다(실측).
+import { MIGRATIONS } from "./registry.js";
+import * as workflowRule from "./rules/obsolete-workflows.js";
+import * as rootFileRule from "./rules/root-files.js";
+
+const RULES = {
+  workflow: workflowRule,
+  "root-file": rootFileRule,
+};
+
+// 대상 레포에서 레거시 잔재 감지. 반환: { safe: [entry], confirm: [entry] }
+export function detectMigrations(targetRoot = ".") {
+  const safe = [];
+  const confirm = [];
+  for (const entry of MIGRATIONS) {
+    const rule = RULES[entry.category];
+    if (!rule || !rule.detect(targetRoot, entry)) continue;
+    (entry.tier === "safe" ? safe : confirm).push(entry);
+  }
+  return { safe, confirm };
+}
+
+// safe 티어 적용. 실패해도 나머지는 계속(부분 실패 허용 — 멱등이라 재실행으로 복구).
+export function applySafeMigrations(targetRoot, entries) {
+  const results = [];
+  for (const entry of entries) {
+    try {
+      results.push({ id: entry.id, ...RULES[entry.category].apply(targetRoot, entry) });
+    } catch (e) {
+      results.push({ id: entry.id, action: "error", from: entry.file, error: e.message });
+    }
+  }
+  return results;
+}
+
+// 마법사 배선 진입점.
+//   askYesNo - async(msg, defaultYes)→bool. null이면 비대화형(--force): safe 자동 적용
+//   log      - 한 줄 출력 함수 (기본 console.log)
+// 반환: { applied: [결과], confirmPending: [entry] }
+export async function runMigrations({ targetRoot = ".", askYesNo = null, log = console.log } = {}) {
+  const { safe, confirm } = detectMigrations(targetRoot);
+  if (safe.length === 0 && confirm.length === 0) return { applied: [], confirmPending: [] };
+
+  let applied = [];
+  if (safe.length > 0) {
+    log(`🧹 레거시 템플릿 파일 ${safe.length}개 감지 — 신형으로 대체되어 공존 시 중복 실행 위험:`);
+    for (const e of safe) {
+      const arrow = e.replacedBy ? ` → ${e.replacedBy}` : "";
+      log(`   • ${e.file}${arrow}`);
+      log(`     (${e.reason}, ${e.since}부터 폐기)`);
+    }
+    const yes = askYesNo
+      ? await askYesNo(`위 ${safe.length}개를 정리할까요? (워크플로우는 .bak 무해화 — 복원 가능)`, 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}개)` : ""}`);
+      for (const f of failed) log(`   ⚠️ ${f.from}: ${f.error}`);
+    } else {
+      log("→ 레거시 정리를 건너뜁니다 (다음 업데이트 때 다시 안내)");
+    }
+  }
+
+  if (confirm.length > 0) {
+    log(`⚠️ 구세대 배포 워크플로우 ${confirm.length}개 발견 — 현역 배포일 수 있어 자동으로 건드리지 않습니다:`);
+    for (const e of confirm) {
+      const arrow = e.replacedBy ? ` (신형: ${e.replacedBy})` : "";
+      log(`   • ${e.file}${arrow} — ${e.reason}`);
+    }
+    log("   신형 워크플로우로 전환을 마친 뒤 구 파일을 직접 삭제하세요.");
+  }
+
+  return { applied, confirmPending: confirm };
+}

package/src/core/migrations/registry.js

@@ -0,0 +1,148 @@
+// 레거시 마이그레이션 단일 레지스트리 (#470) — 유일한 관리 지점.
+//
+// ⚠️ 템플릿에서 워크플로우/루트 파일을 리네임·폐기하면 반드시 여기에 구 이름을 한 줄 추가한다.
+//    (test/migrations.test.js가 "레지스트리 항목이 현행 배포 세트와 겹치지 않는지" 자동 검증)
+//
+// 항목 스키마:
+//   id         - 고유 식별자 (kebab-case)
+//   category   - "workflow" | "root-file"  (rules/ 폴더의 구현이 detect/apply 담당)
+//   tier       - "safe"    : 신형이 같은 기능을 대체(순수 리네임). 공존 시 이중 트리거 실해
+//                            → 확인 1회 후 자동 무해화(.bak) / 삭제
+//                "confirm" : 배포 파이프라인일 수 있음(그 레포의 유일한 현역 배포 가능성)
+//                            → 자동으로 건드리지 않고 안내만. --force에서도 불변
+//   file       - 정확한 파일명 (글롭 금지 — 사용자 커스텀 보호의 핵심)
+//   replacedBy - 대체 신형 파일명 (없으면 null)
+//   since      - 구 파일이 폐기된 템플릿 버전(참고용)
+//   reason     - 계획 카드에 표시할 사유
+//   contentMarker - (선택) 파일명이 범용적일 때 오탐 방지용 내용 마커 — 이 문자열이
+//                   파일 내용에 있을 때만 템플릿 소유로 판정
+//
+// 데이터 출처: git 히스토리 삭제/리네임 전수 + 실제 통합 레포 14개 스캔 (2026-07-11, 설계 문서 참조)
+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세대 리네임 — 공존 시 버전 이중 증가" },
+  { 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 이중 커밋" },
+  { 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세대 리네임 — 공존 시 라벨 동기화 중복" },
+  { 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세대 리네임 — 공존 시 라벨 동기화 중복" },
+  { id: "wf-issue-comment-v1", category: "workflow", tier: "safe",
+    file: "PROJECT-ISSUE-COMMENT.yaml", replacedBy: "PROJECT-COMMON-SUH-ISSUE-HELPER-MODULE.yml",
+    since: "2.x", reason: "이슈 헬퍼 1세대 — 공존 시 이슈 댓글 중복" },
+  { id: "wf-issue-comment-v2", category: "workflow", tier: "safe",
+    file: "PROJECT-COMMON-ISSUE-COMMENT.yaml", replacedBy: "PROJECT-COMMON-SUH-ISSUE-HELPER-API.yaml",
+    since: "2.x", reason: "이슈 헬퍼 2세대 — 공존 시 이슈 댓글 중복" },
+  { 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 이중 처리" },
+  { 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 이중 처리" },
+  { 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 이슈 중복 생성" },
+  { 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 버전 동기화 중복" },
+  { 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 동기화로 대체 — 공존 시 보드 상태 중복 갱신" },
+  { 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: "리브랜딩 리네임 — 공존 시 빌드 트리거 중복" },
+  { 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 흡수)" },
+  { 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 흡수)" },
+  { 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 중복 실행" },
+  { 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 중복 실행" },
+
+  // ── 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 엔진으로 대체됨" },
+  { 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 버전으로 대체됨" },
+  { 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 폐기" },
+  { 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)로 대체됨" },
+  { 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 폐기" },
+  { 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 폐기" },
+  { 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 업로드로 대체됨" },
+  { id: "wf-spring-ci-v1", category: "workflow", tier: "confirm",
+    file: "PROJECT-SPRING-CI.yaml", replacedBy: null,
+    since: "2.x", reason: "1세대 Spring CI — 현행 대체본 없음(CICD에 통합)" },
+  { 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 배포 — 현역 배포일 수 있음" },
+  { 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 배포 — 현역 배포일 수 있음" },
+  { 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 배포 — 현역 배포일 수 있음" },
+  { 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 배포 — 현역 배포일 수 있음" },
+  { 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 워크플로우로 대체 — 현역 배포일 수 있음" },
+  { 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 업로드로 대체 — 운영 업로드 경로일 수 있음" },
+  { 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 업로드로 대체 — 운영 업로드 경로일 수 있음" },
+  { 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 업로드로 대체 — 운영 업로드 경로일 수 있음" },
+  { 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 업로드로 대체 — 운영 업로드 경로일 수 있음" },
+  { 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 배포 — 현역 라이브러리 배포일 수 있음" },
+  { 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" },
+  { 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" },
+  { id: "wf-publish-v0", category: "workflow", tier: "confirm",
+    file: "PROJECT-PUBLISH.yml", replacedBy: "PROJECT-SPRING-NEXUS-PUBLISH.yml",
+    since: "2.x", reason: "0세대 라이브러리 배포 — 현역 배포일 수 있음" },
+  { id: "wf-deploy-trigger", category: "workflow", tier: "confirm",
+    file: "PROJECT-DEPLOY-TRIGGER.yaml", replacedBy: null,
+    since: "3.x", reason: "폐기된 배포 트리거" },
+
+  // ── 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: "리브랜딩으로 구 가이드 대체 — 잔재 문서" },
+  { id: "root-setup-guide-v1", category: "root-file", tier: "safe",
+    file: "SETUP-GUIDE.md", replacedBy: "PROJECTOPS-SETUP-GUIDE.md",
+    since: "2.x", reason: "구 가이드 문서 — 잔재",
+    contentMarker: "SUH" }, // 범용 파일명이라 내용에 템플릿 마커가 있을 때만 소유 판정
+];

package/src/core/migrations/rules/obsolete-workflows.js

@@ -0,0 +1,28 @@
+// workflow 카테고리 규칙 (#470) — .github/workflows/의 구 템플릿 워크플로우를 .bak으로 무해화.
+// GitHub Actions는 .yaml/.yml만 실행하므로 .bak 리네임 = 즉시 무해화 + 복원 가능.
+import { existsSync, readFileSync, renameSync, rmSync } from "node:fs";
+import { join } from "node:path";
+
+const WF_DIR = join(".github", "workflows");
+
+function target(targetRoot, entry) {
+  return join(targetRoot, WF_DIR, entry.file);
+}
+
+export function detect(targetRoot, entry) {
+  const p = target(targetRoot, entry);
+  if (!existsSync(p)) return false;
+  if (entry.contentMarker) {
+    try { return readFileSync(p, "utf8").includes(entry.contentMarker); }
+    catch { return false; }
+  }
+  return true;
+}
+
+export function apply(targetRoot, entry) {
+  const src = target(targetRoot, entry);
+  const bak = `${src}.bak`;
+  if (existsSync(bak)) rmSync(bak, { force: true }); // Windows rename은 대상 존재 시 실패
+  renameSync(src, bak);
+  return { action: "bak", from: entry.file, to: `${entry.file}.bak` };
+}

package/src/core/migrations/rules/root-files.js

@@ -0,0 +1,24 @@
+// root-file 카테고리 규칙 (#470) — 레포 루트의 구 템플릿 문서를 삭제.
+// 문서라 무해화가 필요 없고, 사용자가 매번 수동 삭제하던 잔재라 delete가 기대 동작.
+import { existsSync, readFileSync, rmSync } from "node:fs";
+import { join } from "node:path";
+
+function target(targetRoot, entry) {
+  return join(targetRoot, entry.file);
+}
+
+export function detect(targetRoot, entry) {
+  const p = target(targetRoot, entry);
+  if (!existsSync(p)) return false;
+  // 범용 파일명 오탐 방지 — contentMarker가 있으면 내용까지 확인해야 템플릿 소유로 판정
+  if (entry.contentMarker) {
+    try { return readFileSync(p, "utf8").includes(entry.contentMarker); }
+    catch { return false; }
+  }
+  return true;
+}
+
+export function apply(targetRoot, entry) {
+  rmSync(target(targetRoot, entry), { force: true });
+  return { action: "deleted", from: entry.file, to: null };
+}

package/src/core/version-yml.js

@@ -133,6 +133,29 @@ export function parseTemplateOptions(content) {
   return out;
 }
 
+// v4.1.0 이전 단수 project_type 키 → project_types 배열 최소 변환 (#471).
+// version.yml을 재생성하지 않는 경로(workflows 모드)에서 신형 version_manager(단수 키 명시 거부)와의
+// 정합을 맞춘다 — 해당 라인만 교체하고 나머지 내용은 손대지 않는다.
+// 배열 키가 이미 있으면 남은 단수 키만 제거한다(4.1.0: 공존 시 단수 무시 — 잔재 정리).
+// 반환: 변환된 전체 내용 문자열, 변환할 것이 없으면 null.
+export function convertLegacySingularType(content) {
+  const lines = String(content || "").split(/\r?\n/);
+  let hasArray = false, idx = -1, value = "";
+  lines.forEach((l, i) => {
+    if (/^project_types:/.test(l)) hasArray = true;
+    const m = l.match(/^project_type:\s*["']?([a-z-]+)["']?/);
+    if (m && idx < 0) { idx = i; value = m[1]; }
+  });
+  if (idx < 0) return null;
+  if (hasArray) {
+    lines.splice(idx, 1);
+    return lines.join("\n");
+  }
+  const type = value === "next" ? "react" : value; // next 타입은 4.1.0에서 react로 흡수
+  lines[idx] = `project_types: ["${type}"]   # 멀티타입 배열 — 첫 항목이 primary, 직접 편집 가능`;
+  return lines.join("\n");
+}
+
 // 기존 version.yml에서 값 추출 (.sh grep/sed 등가, 주석 라인 오탐 방지).
 export function parseExisting(content) {
   const text = String(content || "");

package/src/index.js

@@ -12,6 +12,7 @@ import { acquireTemplate, readTemplateVersion } from "./core/assets.js";
 import { detectTypes, detectVersion, detectDefaultBranch, detectRepoName, makeResolvers } from "./core/detect-fs.js";
 import { parseExisting } from "./core/version-yml.js";
 import { runBreakingCheck } from "./core/breaking-check.js";
+import { runMigrations } from "./core/migrations/index.js";
 import { resolveProjectPaths } from "./core/paths-resolve.js";
 import { printBannerCompact } from "./ui/banner.js";
 import { printSummary } from "./ui/summary.js";
@@ -133,6 +134,11 @@ export async function run(argv, { cwd = process.cwd(), source = { type: "git" },
     const proceed = await runBreakingCheck({ cwd, tempDir, templateVersion: context.templateVersion });
     if (!proceed) return 0;
 
+    // 레거시 마이그레이션 (#470) — 워크플로우를 만지는 모드에서만. 비대화형은 safe 티어 자동 적용.
+    if (opts.mode === "full" || opts.mode === "workflows") {
+      await runMigrations({ targetRoot: cwd });
+    }
+
     switch (opts.mode) {
       case "full": result = runFull(context, tempDir, cwd); break;
       case "version": result = runVersion(context, tempDir, cwd); break;