projectops 4.2.11 → 4.2.13

package/README.md

@@ -7,7 +7,7 @@
 > 이슈 등록부터 커밋, 보고서, 배포까지. 개발자는 코드만 작성하세요.
 
 <!-- AUTO-VERSION-SECTION: DO NOT EDIT MANUALLY -->
-## 최신 버전 : v4.2.10 (2026-07-12)
+## 최신 버전 : v4.2.12 (2026-07-12)
 
 [전체 버전 기록 보기](CHANGELOG.md)
 

package/package.json

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

package/src/commands/interactive.js

@@ -12,7 +12,7 @@ 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 { askAllOptionalWorkflows, OPTION_AXES } from "../core/options-ask.js";
 import { promptEnvPlan } from "../ui/env-plan.js";
 import { listWorkflowConflicts } from "../core/copy/workflows.js";
 import { createContext, VALID_TYPES } from "../context.js";
@@ -97,7 +97,7 @@ export async function runInteractive(baseCtx, { cwd = process.cwd(), source = {
     // 배포/publish 축 + Secret 백업 질문 (#439 — full/workflows만)
     if (showOptional) {
       const r = await askAllOptionalWorkflows({
-        tempDir, types, targetRoot: cwd,
+        tempDir, types, targetRoot: cwd, defaultBranch: branch,
         current: {
           deploy: existing?.options?.deploy ?? null, publish: existing?.options?.publish ?? null, secretBackup: existing?.options?.secretBackup ?? null,
           codeReviewCoderabbit: existing?.options?.codeReviewCoderabbit ?? null,
@@ -159,15 +159,15 @@ export async function runInteractive(baseCtx, { cwd = process.cwd(), source = {
         } else if (what === "branch") {
           const b = await io.askText("기본 브랜치", branch);
           if (!isCancel(b) && b) branch = b;
-        } else if (what === "deploy-publish") {
-          // 배포/publish 축 재질문 (#439 — forceAsk)
+        } else if (OPTION_AXES.includes(what)) {
+          // #483 — 선택한 축 하나만 재질문 (scope). 나머지 옵션은 현재값 그대로 유지.
           const r = await askAllOptionalWorkflows({
-            tempDir, types, targetRoot: cwd,
+            tempDir, types, targetRoot: cwd, defaultBranch: branch,
             current: {
               deploy: deployTarget, publish: publishTargets, secretBackup: includeSecretBackup,
               codeReviewCoderabbit, changelogProvider, changelogBaseUrl, deployBranch,
             },
-            force: false, tty: realTty, forceAsk: true,
+            force: false, tty: realTty, forceAsk: true, scope: [what],
             io: {
               confirm: ({ message, initialValue }) => io.askYesNo(message, initialValue),
               select: io.engineIo?.select,
@@ -182,9 +182,6 @@ export async function runInteractive(baseCtx, { cwd = process.cwd(), source = {
           changelogProvider = r.changelogProvider;
           changelogBaseUrl = r.changelogBaseUrl;
           deployBranch = r.deployBranch;
-        } else if (what === "secret") {
-          const y = await io.askYesNo("Secret 백업 워크플로우를 포함할까요?", includeSecretBackup);
-          if (!isCancel(y)) includeSecretBackup = y === true;
         }
       }
     }
@@ -263,8 +260,8 @@ export async function runInteractive(baseCtx, { cwd = process.cwd(), source = {
 
     // 완료 요약 (.sh print_summary L5438)
     io.summary?.({
-      mode, types, version,
-      counters: { workflows: result?.workflows?.copied ?? 0, utilModules: 0 },
+      mode, types, version, deployBranch,
+      counters: { workflows: result?.workflows?.copied ?? 0, workflowFiles: result?.workflows?.copiedFiles ?? [], utilModules: 0 },
     }, cwd);
     io.outro?.(`통합 완료 — ${mode} 모드로 설치했습니다.`);
     return 0;

package/src/core/branch-sub.js

@@ -0,0 +1,41 @@
+// 워크플로우 브랜치 치환 (#477) — 대상 레포의 브랜치 전략이 표준(main/develop)과 다를 때
+// 복사된 워크플로우의 브랜치 리터럴을 설정값으로 교체한다.
+// 표준값이면 입력을 그대로 반환(no-op) — 템플릿 원본과 바이트 동일이 유지되어야
+// isUnchanged 스킵 로직과 "표준 레포 무변화" 계약이 깨지지 않는다.
+//
+// 치환 대상은 실측 전수조사(#477)된 패턴만 다룬다 (글롭·전면 replace 금지 — 오살 방지):
+//   1) 트리거 인라인:   branches: ["main"] / [develop] / [ develop ] / ["develop"]
+//   2) 트리거 멀티라인: "  - main" / "  - develop" 단독 라인 (뒤 주석 허용)
+//   3) 릴리스 가드:     == 'develop'  (RELEASE-CHANGELOG automerge head 가드)
+//   4) step 내부:       git fetch origin main  (RELEASE-CHANGELOG 커밋 분석)
+
+// main(기본 브랜치) 계열 치환
+function subDefault(s, db) {
+  s = s.replace(/^(\s*branches:\s*\[\s*["']?)main(["']?\s*\])/gm, `$1${db}$2`);
+  s = s.replace(/^(\s*-\s*)main(\s*(?:#.*)?)$/gm, `$1${db}$2`);
+  s = s.replace(/\bgit fetch origin main\b/g, `git fetch origin ${db}`);
+  return s;
+}
+
+// develop(개발/릴리스 head 브랜치) 계열 치환
+function subDeploy(s, dev) {
+  s = s.replace(/^(\s*branches:\s*\[\s*["']?)develop(["']?\s*\])/gm, `$1${dev}$2`);
+  s = s.replace(/^(\s*-\s*)develop(\s*(?:#.*)?)$/gm, `$1${dev}$2`);
+  s = s.replace(/== 'develop'/g, `== '${dev}'`);
+  return s;
+}
+
+// content에 브랜치 설정을 적용한 결과를 반환. branches 미지정/표준값이면 원본 그대로.
+// 플레이스홀더 2단 치환: 값 충돌 방지 (예: 기본 브랜치=develop인 레포에서 main→develop 치환 결과가
+// 곧이어 develop→X 치환에 다시 걸리는 연쇄 오염을 차단).
+export function substituteBranches(content, branches = null) {
+  if (!branches) return content;
+  const db = branches.defaultBranch || "main";
+  const dev = branches.deployBranch || "develop";
+  let s = String(content);
+  const T_DB = "__PJOPS_DEFAULT__";
+  const T_DEV = "__PJOPS_DEPLOY__";
+  if (dev !== "develop") s = subDeploy(s, T_DEV);
+  if (db !== "main") s = subDefault(s, T_DB);
+  return s.replaceAll(T_DEV, dev).replaceAll(T_DB, db);
+}

package/src/core/breaking-check.js

@@ -39,17 +39,32 @@ export async function runBreakingCheck({ cwd, tempDir, templateVersion, askYesNo
   const { critical, warnings } = collectBreaking(json, current, templateVersion);
   if (critical.length === 0 && warnings.length === 0) return true;
 
-  // 박스 표시 (.sh L2580~2603)
+  // 요약 리스트 표시 (#473 — 전문 통덤프는 벽글이 되어 정작 CRITICAL이 안 읽혔고,
+  // 긴 본문 래핑이 ║ 박스 경계를 붕괴시켰다. 버전·제목만 한 줄씩, 전문은 선택 열람.)
   const e = (s = "") => process.stderr.write(s + "\n");
   e("");
-  e("╔══════════════════════════════════════════════════════════════════╗");
-  e(`║  ⚠️  BREAKING CHANGES (v${current} → v${templateVersion})`);
-  e("╠══════════════════════════════════════════════════════════════════╣");
-  for (const c of critical) { e("║"); e(`║  [CRITICAL] ${c.version} - ${c.title || ""}`); e(`║  → ${c.message || ""}`); }
-  for (const w of warnings) { e("║"); e(`║  [WARNING] ${w.version} - ${w.title || ""}`); e(`║  → ${w.message || ""}`); }
-  e("║");
-  e("╚══════════════════════════════════════════════════════════════════╝");
+  e(`⚠️  BREAKING CHANGES (v${current} → v${templateVersion}) — CRITICAL ${critical.length}건 · WARNING ${warnings.length}건`);
   e("");
+  for (const c of critical) e(`  ❗ [CRITICAL] ${c.version} — ${c.title || ""}`);
+  for (const w of warnings) e(`  ⚠️ [WARNING]  ${w.version} — ${w.title || ""}`);
+  e("");
+
+  if (askYesNo) {
+    // 대화형: 전문(조치 방법)은 원할 때만 펼친다
+    const detail = await askYesNo("각 항목의 상세 내용(조치 방법)을 볼까요?", false);
+    if (detail === true) {
+      for (const it of [...critical, ...warnings]) {
+        e("");
+        e(`■ ${it.version} — ${it.title || ""}`);
+        e(`  ${it.message || ""}`);
+      }
+      e("");
+    }
+  } else {
+    e("  상세 내용·조치 방법: .github/config/breaking-changes.json 참고");
+    e(`  (${BC_URL})`);
+    e("");
+  }
 
   if (critical.length > 0) {
     if (askYesNo) {

package/src/core/copy/simple.js

@@ -9,11 +9,13 @@ import { exists, copyFileSync, copyDirSync } from "../fsutil.js";
 // version_manager는 .sh(위임 shim) + .py(실 로직) 한 쌍 — 둘 다 복사해야 동작 (#448).
 // changelog provider 사다리(.py 5종, #455)는 RELEASE-CHANGELOG 워크플로우 fallback-summary가
 // 호출하므로 함께 복사해야 사용자 프로젝트에서 릴리스 노트 생성이 동작한다.
+// issue_helper.py는 SUH-ISSUE-HELPER 워크플로우가 호출 — 함께 복사 필수 (#478).
 export function copyScripts(tempDir, targetRoot = ".") {
   const scripts = [
     "version_manager.sh", "version_manager.py",
     "changelog_manager.py",
     "truncate_release_notes.sh", "truncate_release_notes.py",
+    "issue_helper.py",
     "changelog_providers/_common.py", "changelog_providers/ladder.py",
     "changelog_providers/commit.py", "changelog_providers/github_ai.py",
     "changelog_providers/openai_compatible.py",

package/src/core/copy/workflows.js

@@ -7,6 +7,7 @@ import { existsSync, readFileSync, writeFileSync, renameSync } from "node:fs";
 import { PATHS } from "../paths.js";
 import { exists, copyFileSync, listYamlFiles } from "../fsutil.js";
 import { isUnchanged, substituteEnv } from "../wizard-env.js";
+import { substituteBranches } from "../branch-sub.js";
 
 // 한 파일에 env 치환을 적용해 대상 파일을 갱신 (.sh configure_workflow_env 등가).
 // values/useDefaults: env 계획(promptEnvPlan) 결과 — 미지정이면 기본값 경로(현행 force 동작).
@@ -41,19 +42,21 @@ function classify(srcDir, workflowsDir, envOpts) {
 //   deployTarget(#439 택1): 'docker-ssh'(기본) | 'vercel' | 'none' — server-deploy는 docker-ssh일 때만,
 //   common/deploy/<target>/은 해당 타겟일 때 복사. publishTargets(#439 다중): 'nexus'|'npm'|'github-packages'.
 // hooks: { decisions?: Map<filename, 'skip'|'backup'|'template'> } — 기존 파일(changed) 충돌 결정.
-// 반환: {copied, skipped, templateAdded, optionalCopied}
+// 반환: {copied, skipped, templateAdded, optionalCopied, copiedFiles[]} — copiedFiles는 실제 복사·교체된 파일명 (#473 요약용)
 export function copyWorkflows(context, tempDir, targetRoot = ".", hooks = {}) {
-  const { types = [], paths = new Map(), deployTarget = "docker-ssh", publishTargets = [], includeSecretBackup = false, repoName = "", resolvers = {}, envValues = new Map(), envUseDefaults = true } = context;
+  const { types = [], paths = new Map(), deployTarget = "docker-ssh", publishTargets = [], includeSecretBackup = false, repoName = "", resolvers = {}, envValues = new Map(), envUseDefaults = true, branch = "", deployBranch = "" } = context;
   const decisions = hooks.decisions instanceof Map ? hooks.decisions : new Map();
   const workflowsDir = join(targetRoot, PATHS.workflowsDir);
   const projectTypesDir = join(tempDir, PATHS.workflowsDir, PATHS.projectTypesDir);
   if (!exists(projectTypesDir)) throw new Error("템플릿 저장소 구조 오류 — project-types 폴더를 찾지 못했습니다.");
 
-  const counters = { copied: 0, skipped: 0, templateAdded: 0, optionalCopied: 0 };
+  const counters = { copied: 0, skipped: 0, templateAdded: 0, optionalCopied: 0, copiedFiles: [] };
   const deployValues = new Map(); // Map<type, Map<key,value>> — deploy 블록용 ask 값
   counters.deployValues = deployValues;
+  // 브랜치 전략 (#477) — 표준(main/develop)이면 치환·가상비교 모두 no-op
+  const branches = { defaultBranch: branch || "main", deployBranch: deployBranch || "develop" };
   // values/useDefaults는 치환 경로에서만 의미 (isUnchanged는 내부에서 useDefaults:true 강제 — 가상 비교 무손상)
-  const envOptsFor = (type) => ({ type, projectPath: paths.get(type) || ".", repoName, resolvers, values: envValues, useDefaults: envUseDefaults });
+  const envOptsFor = (type) => ({ type, projectPath: paths.get(type) || ".", repoName, resolvers, values: envValues, useDefaults: envUseDefaults, branches });
 
   // (1) common — unchanged면 스킵, 아니면 무조건 덮어쓰기
   const commonDir = join(projectTypesDir, "common");
@@ -67,6 +70,7 @@ export function copyWorkflows(context, tempDir, targetRoot = ".", hooks = {}) {
       }
       copyFileSync(src, dst);
       counters.copied++;
+      counters.copiedFiles.push(filename);
     }
   }
 
@@ -91,6 +95,7 @@ export function copyWorkflows(context, tempDir, targetRoot = ".", hooks = {}) {
       copyFileSync(src, dst);
       counters.optionalCopied++;
       counters.copied++;
+      counters.copiedFiles.push(filename);
     }
   }
 
@@ -103,6 +108,19 @@ export function copyWorkflows(context, tempDir, targetRoot = ".", hooks = {}) {
       copyFileSync(join(secretDir, filename), dst);
       counters.optionalCopied++;
       counters.copied++;
+      counters.copiedFiles.push(filename);
+    }
+  }
+
+  // (6) 브랜치 치환 post-pass (#477) — 표준과 다른 브랜치 전략일 때만 복사된 파일에 적용.
+  // isUnchanged 가상 비교에도 같은 branches가 들어가므로 다음 업데이트에서 재복사 churn이 없다.
+  if (branches.defaultBranch !== "main" || branches.deployBranch !== "develop") {
+    for (const f of counters.copiedFiles) {
+      const p = join(workflowsDir, f);
+      if (!existsSync(p)) continue;
+      const before = readFileSync(p, "utf8");
+      const after = substituteBranches(before, branches);
+      if (after !== before) writeFileSync(p, after);
     }
   }
 
@@ -119,6 +137,7 @@ function applyDecision(decision, srcDir, workflowsDir, filename, counters) {
     renameSync(dst, dst + ".bak");
     copyFileSync(src, dst);
     counters.copied++;
+    counters.copiedFiles?.push(filename);
     return;
   }
   if (decision === "template") {
@@ -134,12 +153,13 @@ function applyDecision(decision, srcDir, workflowsDir, filename, counters) {
 // 대상 워크플로우 디렉토리에서 changed(충돌) 파일 목록만 뽑는다 — copyWorkflowsInteractive의 사전 조사용.
 // copyWorkflows 본체와 동일한 classify 기준을 써야 결정 Map이 실제 처리 대상과 1:1로 맞는다.
 export function listWorkflowConflicts(context, tempDir, targetRoot = ".") {
-  const { types = [], paths = new Map(), deployTarget = "docker-ssh", repoName = "", resolvers = {} } = context;
+  const { types = [], paths = new Map(), deployTarget = "docker-ssh", repoName = "", resolvers = {}, branch = "", deployBranch = "" } = context;
   const workflowsDir = join(targetRoot, PATHS.workflowsDir);
   const projectTypesDir = join(tempDir, PATHS.workflowsDir, PATHS.projectTypesDir);
   const conflicts = []; // [{ filename, type }] — 엔진 처리 순서와 동일 (타입 순회 → 직하위 → server-deploy)
+  const branches = { defaultBranch: branch || "main", deployBranch: deployBranch || "develop" }; // #477 — 엔진과 동일 기준
   for (const type of types) {
-    const envOpts = { type, projectPath: paths.get(type) || ".", repoName, resolvers };
+    const envOpts = { type, projectPath: paths.get(type) || ".", repoName, resolvers, branches };
     const typeDir = join(projectTypesDir, type);
     if (exists(typeDir)) {
       for (const f of classify(typeDir, workflowsDir, envOpts).changed) conflicts.push({ filename: f, type });
@@ -180,7 +200,7 @@ function copyWorkflowsForType(type, projectTypesDir, workflowsDir, ctx, counters
     const { newFiles, unchanged, changed } = classify(typeDir, workflowsDir, envOpts);
     unchangedNames = unchanged.slice();
     for (const f of unchanged) counters.skipped++;
-    for (const f of newFiles) { copyFileSync(join(typeDir, f), join(workflowsDir, f)); counters.copied++; }
+    for (const f of newFiles) { copyFileSync(join(typeDir, f), join(workflowsDir, f)); counters.copied++; counters.copiedFiles.push(f); }
     // changed: 결정 Map에 따라 처리 (미지정=skip → 현행 force 동작과 동일)
     for (const f of changed) applyDecision(decisions.get(f), typeDir, workflowsDir, f, counters);
   }
@@ -190,7 +210,7 @@ function copyWorkflowsForType(type, projectTypesDir, workflowsDir, ctx, counters
   if (exists(serverDeployDir) && (deployTarget || "docker-ssh") === "docker-ssh") {
     const { newFiles, unchanged, changed } = classify(serverDeployDir, workflowsDir, envOpts);
     for (const f of unchanged) counters.skipped++;
-    for (const f of newFiles) { copyFileSync(join(serverDeployDir, f), join(workflowsDir, f)); counters.copied++; }
+    for (const f of newFiles) { copyFileSync(join(serverDeployDir, f), join(workflowsDir, f)); counters.copied++; counters.copiedFiles.push(f); }
     for (const f of changed) applyDecision(decisions.get(f), serverDeployDir, workflowsDir, f, counters);
   }
 
@@ -211,6 +231,7 @@ function copyWorkflowsForType(type, projectTypesDir, workflowsDir, ctx, counters
       copyFileSync(src, dst);
       counters.optionalCopied++;
       counters.copied++;
+      counters.copiedFiles.push(filename);
     }
   }
 

package/src/core/detect-fs.js

@@ -73,6 +73,9 @@ export function detectDefaultBranch(root) {
   const show = gitOut(root, ["remote", "show", "origin"]);
   const m = show.match(/HEAD branch:\s*(\S+)/);
   if (m) return m[1];
+  // origin 없는 로컬 레포(#477) — 현재 HEAD 브랜치가 최선의 추정 (대화형 수정 메뉴로 교정 가능)
+  const head = gitOut(root, ["branch", "--show-current"]);
+  if (head) return head;
   return "main";
 }
 

package/src/core/git-branch.js

@@ -0,0 +1,34 @@
+// 브랜치 존재 확인·생성 헬퍼 (#477) — 마법사의 개발 브랜치 생성 제안에 사용.
+// 모든 함수는 실패 시 조용히 false/null을 반환한다 (git 미설치·비레포·원격 없음에서 마법사가 죽지 않게).
+import { execFileSync } from "node:child_process";
+
+function git(root, args) {
+  try {
+    return execFileSync("git", args, { cwd: root, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+  } catch { return null; }
+}
+
+// 브랜치 존재 상태. remote는 origin 조회 실패(원격 없음·네트워크) 시 null(불명).
+export function branchStatus(root, name) {
+  const isRepo = git(root, ["rev-parse", "--git-dir"]) !== null;
+  if (!isRepo || !name) return { isRepo, local: false, remote: null };
+  const local = git(root, ["show-ref", "--verify", `refs/heads/${name}`]) !== null;
+  const ls = git(root, ["ls-remote", "--heads", "origin", name]);
+  const remote = ls === null ? null : ls.length > 0;
+  return { isRepo, local, remote };
+}
+
+// fromBranch(기본 브랜치)에서 로컬 브랜치 생성 — checkout하지 않는다.
+// 로컬에 fromBranch가 없으면 origin/fromBranch → HEAD 순으로 폴백.
+export function createBranch(root, name, fromBranch = "") {
+  if (fromBranch) {
+    if (git(root, ["branch", name, fromBranch]) !== null) return true;
+    if (git(root, ["branch", name, `origin/${fromBranch}`]) !== null) return true;
+  }
+  return git(root, ["branch", name]) !== null;
+}
+
+// 원격(origin)에 브랜치 push (-u). 자격/네트워크 실패 시 false.
+export function pushBranch(root, name) {
+  return git(root, ["push", "-u", "origin", name]) !== null;
+}

package/src/core/migrations/index.js

@@ -4,25 +4,30 @@
 import { MIGRATIONS } from "./registry.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";
 
 const RULES = {
   workflow: workflowRule,
   "root-file": rootFileRule,
+  "legacy-dir": legacyDirRule,
 };
 
-// 대상 레포에서 레거시 잔재 감지. 반환: { safe: [entry], confirm: [entry] }
+// 대상 레포에서 레거시 잔재 감지. 반환: { safe: [entry], confirm: [entry], ask: [entry] }
 export function detectMigrations(targetRoot = ".") {
   const safe = [];
   const confirm = [];
+  const ask = [];
   for (const entry of MIGRATIONS) {
     const rule = RULES[entry.category];
     if (!rule || !rule.detect(targetRoot, entry)) continue;
-    (entry.tier === "safe" ? safe : confirm).push(entry);
+    if (entry.tier === "safe") safe.push(entry);
+    else if (entry.tier === "ask") ask.push(entry);
+    else confirm.push(entry);
   }
-  return { safe, confirm };
+  return { safe, confirm, ask };
 }
 
-// safe 티어 적용. 실패해도 나머지는 계속(부분 실패 허용 — 멱등이라 재실행으로 복구).
+// 항목 일괄 적용 실행기 (safe·ask 티어 공용). 실패해도 나머지는 계속(부분 실패 허용 — 멱등이라 재실행으로 복구).
 export function applySafeMigrations(targetRoot, entries) {
   const results = [];
   for (const entry of entries) {
@@ -38,10 +43,12 @@ export function applySafeMigrations(targetRoot, entries) {
 // 마법사 배선 진입점.
 //   askYesNo - async(msg, defaultYes)→bool. null이면 비대화형(--force): safe 자동 적용
 //   log      - 한 줄 출력 함수 (기본 console.log)
-// 반환: { applied: [결과], confirmPending: [entry] }
+// 반환: { applied: [결과], confirmPending: [entry], askPending: [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: [] };
+  const { safe, confirm, ask } = detectMigrations(targetRoot);
+  if (safe.length === 0 && confirm.length === 0 && ask.length === 0) {
+    return { applied: [], confirmPending: [], askPending: [] };
+  }
 
   let applied = [];
   if (safe.length > 0) {
@@ -65,6 +72,33 @@ export async function runMigrations({ targetRoot = ".", askYesNo = null, log = c
     }
   }
 
+  // ask 티어 (#476) — 사용자 문서가 담긴 구명칭 폴더: 대화형은 확인 후 이동, 비대화형은 안내만
+  let askPending = [];
+  if (ask.length > 0) {
+    log(`📁 구명칭 산출물 폴더 ${ask.length}개 감지 — 사용자 문서가 들어 있어 확인 후 이동합니다:`);
+    for (const e of ask) {
+      log(`   • ${e.file}/ → ${e.replacedBy}/`);
+      log(`     (${e.reason})`);
+    }
+    if (askYesNo) {
+      const yes = await askYesNo("위 폴더를 새 이름으로 이동할까요? (파일 손실 없음 — 충돌 시 원본 유지)", 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 {
+        askPending = ask;
+        log("→ 폴더 이동을 건너뜁니다 (다음 업데이트 때 다시 안내)");
+      }
+    } else {
+      askPending = ask;
+      log("   비대화형 실행이라 자동으로 이동하지 않습니다 — 대화형 마법사(npx projectops)에서 확인 후 이동하세요.");
+    }
+  }
+
   if (confirm.length > 0) {
     log(`⚠️ 구세대 배포 워크플로우 ${confirm.length}개 발견 — 현역 배포일 수 있어 자동으로 건드리지 않습니다:`);
     for (const e of confirm) {
@@ -74,5 +108,5 @@ export async function runMigrations({ targetRoot = ".", askYesNo = null, log = c
     log("   신형 워크플로우로 전환을 마친 뒤 구 파일을 직접 삭제하세요.");
   }
 
-  return { applied, confirmPending: confirm };
+  return { applied, confirmPending: confirm, askPending };
 }

package/src/core/migrations/registry.js

@@ -5,17 +5,21 @@
 //
 // 항목 스키마:
 //   id         - 고유 식별자 (kebab-case)
-//   category   - "workflow" | "root-file"  (rules/ 폴더의 구현이 detect/apply 담당)
+//   category   - "workflow" | "root-file" | "legacy-dir"  (rules/ 폴더의 구현이 detect/apply 담당)
 //   tier       - "safe"    : 신형이 같은 기능을 대체(순수 리네임). 공존 시 이중 트리거 실해
 //                            → 확인 1회 후 자동 무해화(.bak) / 삭제
 //                "confirm" : 배포 파이프라인일 수 있음(그 레포의 유일한 현역 배포 가능성)
 //                            → 자동으로 건드리지 않고 안내만. --force에서도 불변
+//                "ask"     : 사용자 콘텐츠가 담긴 폴더 등 — 손실 없는 이동이지만 사용자 소유물 (#476)
+//                            → 대화형: 확인 후 이동 / 비대화형: 자동 조치 없이 안내만
 //   file       - 정확한 파일명 (글롭 금지 — 사용자 커스텀 보호의 핵심)
 //   replacedBy - 대체 신형 파일명 (없으면 null)
 //   since      - 구 파일이 폐기된 템플릿 버전(참고용)
 //   reason     - 계획 카드에 표시할 사유
 //   contentMarker - (선택) 파일명이 범용적일 때 오탐 방지용 내용 마커 — 이 문자열이
 //                   파일 내용에 있을 때만 템플릿 소유로 판정
+//   settingsExtractor - (선택) 무해화 직전 실행할 설정 이관기 이름
+//                       (rules/settings-extractors.js의 EXTRACTORS 키)
 //
 // 데이터 출처: git 히스토리 삭제/리네임 전수 + 실제 통합 레포 14개 스캔 (2026-07-11, 설계 문서 참조)
 export const MIGRATIONS = [
@@ -33,11 +37,18 @@ export const MIGRATIONS = [
     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",
+    file: "PROJECT-ISSUE-COMMENT.yaml", replacedBy: "PROJECT-COMMON-SUH-ISSUE-HELPER.yaml",
     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",
+    file: "PROJECT-COMMON-ISSUE-COMMENT.yaml", replacedBy: "PROJECT-COMMON-SUH-ISSUE-HELPER.yaml",
     since: "2.x", reason: "이슈 헬퍼 2세대 — 공존 시 이슈 댓글 중복" },
+  { 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 전용 비활성 잔재)" },
+  { 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) — 공존 시 이슈 댓글 중복",
+    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 이중 처리" },
@@ -145,4 +156,9 @@ export const MIGRATIONS = [
     file: "SETUP-GUIDE.md", replacedBy: "PROJECTOPS-SETUP-GUIDE.md",
     since: "2.x", reason: "구 가이드 문서 — 잔재",
     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/에 저장" },
 ];

package/src/core/migrations/rules/legacy-dirs.js

@@ -0,0 +1,36 @@
+// legacy-dir 카테고리 규칙 (#476) — 구명칭 산출물 폴더를 신명칭으로 이동.
+// 폴더 안은 사용자가 작성한 문서(이슈·보고서)라 삭제·무해화 대상이 아니다 — 손실 없는 이동만 한다.
+// 대상 폴더가 이미 있으면 재귀 병합하되 충돌 파일은 원위치에 남긴다(사용자 판단 존중).
+import { existsSync, statSync, readdirSync, renameSync, mkdirSync, rmdirSync } from "node:fs";
+import { join } from "node:path";
+
+export function detect(targetRoot, entry) {
+  const p = join(targetRoot, entry.file);
+  try { return existsSync(p) && statSync(p).isDirectory(); }
+  catch { return false; }
+}
+
+// 재귀 병합: 파일은 대상에 없을 때만 이동, 하위 폴더는 재귀. 다 비운 원본 폴더는 제거.
+function mergeDir(from, to) {
+  mkdirSync(to, { recursive: true });
+  let moved = 0, skipped = 0;
+  for (const e of readdirSync(from, { withFileTypes: true })) {
+    const s = join(from, e.name);
+    const d = join(to, e.name);
+    if (e.isDirectory()) {
+      const r = mergeDir(s, d);
+      moved += r.moved; skipped += r.skipped;
+    } else if (existsSync(d)) {
+      skipped++; // 동명 파일 충돌 — 원위치에 남긴다
+    } else {
+      renameSync(s, d); moved++;
+    }
+  }
+  try { rmdirSync(from); } catch { /* 충돌 잔여로 비어있지 않으면 남긴다 */ }
+  return { moved, skipped };
+}
+
+export function apply(targetRoot, entry) {
+  const { moved, skipped } = mergeDir(join(targetRoot, entry.file), join(targetRoot, entry.replacedBy));
+  return { action: "moved", from: entry.file, to: entry.replacedBy, moved, skipped };
+}

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

@@ -2,6 +2,7 @@
 // GitHub Actions는 .yaml/.yml만 실행하므로 .bak 리네임 = 즉시 무해화 + 복원 가능.
 import { existsSync, readFileSync, renameSync, rmSync } from "node:fs";
 import { join } from "node:path";
+import { EXTRACTORS } from "./settings-extractors.js";
 
 const WF_DIR = join(".github", "workflows");
 
@@ -20,9 +21,17 @@ export function detect(targetRoot, entry) {
 }
 
 export function apply(targetRoot, entry) {
+  // 무해화 전 설정 이관 (실패해도 무해화는 진행 — 부분 실패 허용 원칙)
+  let carried = [];
+  if (entry.settingsExtractor && EXTRACTORS[entry.settingsExtractor]) {
+    try { carried = EXTRACTORS[entry.settingsExtractor](targetRoot, entry).carried; }
+    catch { carried = []; }
+  }
   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` };
+  const result = { action: "bak", from: entry.file, to: `${entry.file}.bak` };
+  if (carried.length > 0) result.carried = carried;
+  return result;
 }

package/src/core/migrations/rules/settings-extractors.js

@@ -0,0 +1,65 @@
+// 설정 이관기 (#470 확장, #478) — 구 워크플로우의 커스텀 설정을 무해화 전에 version.yml로 이관.
+// 원칙: 기본값과 다른 값만 이관 / issue_helper 섹션이 이미 있으면 불변(신형 우선·멱등)
+//       / version.yml 없으면 skip / 실패해도 무해화를 막지 않는다(호출부에서 try-catch).
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+// 구 MODULE 워크플로우 배포본의 with: 기본값 — 이 값 그대로면 사용자 커스텀이 아니다
+const OLD_DEFAULTS = {
+  branch_prefix: "",
+  max_branch_length: "100",
+  commit_template: "${issueTitle} : feat : {변경 사항에 대한 설명} ${issueUrl}",
+  comment_marker: "<!-- 이 댓글은 SUH-ISSUE-HELPER 에 의해 자동으로 생성되었습니다. - https://github.com/Cassiiopeia/github-issue-helper -->",
+};
+
+const KEYS = Object.keys(OLD_DEFAULTS);
+
+function unquote(v) { return v.trim().replace(/^["']|["']$/g, ""); }
+
+function parseWithValues(content) {
+  const out = {};
+  for (const key of KEYS) {
+    const m = content.match(new RegExp(`^\\s*${key}:\\s*(.+)$`, "m"));
+    if (m) out[key] = unquote(m[1].replace(/\s+#.*$/, ""));
+  }
+  return out;
+}
+
+// version.yml에 issue_helper 블록 삽입. 계층(metadata/template/options)이 없으면 만든다.
+function insertIssueHelperBlock(vyText, carried) {
+  const lines = Object.entries(carried)
+    .map(([k, v]) => `        ${k}: "${v.replace(/"/g, '\\"')}"`);
+  const block = ["      issue_helper:", ...lines].join("\n");
+
+  if (/^\s{4}options:\s*$/m.test(vyText))
+    return vyText.replace(/^(\s{4}options:\s*)$/m, `$1\n${block}`);
+  if (/^\s{2}template:\s*$/m.test(vyText))
+    return vyText.replace(/^(\s{2}template:\s*)$/m, `$1\n    options:\n${block}`);
+  if (/^metadata:\s*$/m.test(vyText))
+    return vyText.replace(/^(metadata:\s*)$/m, `$1\n  template:\n    options:\n${block}`);
+  return `${vyText.replace(/\n*$/, "\n")}metadata:\n  template:\n    options:\n${block}\n`;
+}
+
+// 구 SUH-ISSUE-HELPER-MODULE의 with: → options.issue_helper 이관. 반환: { carried: [키...] }
+export function extractIssueHelperModule(targetRoot, entry) {
+  const wf = join(targetRoot, ".github", "workflows", entry.file);
+  const vy = join(targetRoot, "version.yml");
+  if (!existsSync(wf) || !existsSync(vy)) return { carried: [] };
+
+  const vyText = readFileSync(vy, "utf8");
+  if (/^\s*issue_helper:/m.test(vyText)) return { carried: [] }; // 신형 설정 우선
+
+  const vals = parseWithValues(readFileSync(wf, "utf8"));
+  const carried = {};
+  for (const [k, v] of Object.entries(vals)) {
+    if (v !== OLD_DEFAULTS[k]) carried[k] = v; // 기본값과 다른 것만
+  }
+  if (Object.keys(carried).length === 0) return { carried: [] };
+
+  writeFileSync(vy, insertIssueHelperBlock(vyText, carried));
+  return { carried: Object.keys(carried) };
+}
+
+export const EXTRACTORS = {
+  "suh-issue-helper-module": extractIssueHelperModule,
+};

package/src/core/options-ask.js

@@ -11,6 +11,40 @@ import { join } from "node:path";
 import { listYamlFiles } from "./fsutil.js";
 import { PATHS } from "./paths.js";
 import { parseTemplateOptions } from "./version-yml.js";
+import { branchStatus, createBranch, pushBranch } from "./git-branch.js";
+
+// 개발(배포) 브랜치 존재 확인 + 생성 제안 (#477) — 대화형 전용.
+// 로컬에 없고 원격에도 없(거나 불명이)면 기본 브랜치에서 생성을 제안하고, 생성 후 push 여부도 묻는다.
+// git 미설치·비레포·질문 불가(io.confirm 없음)면 조용히 통과 — 마법사 진행을 막지 않는다.
+export async function ensureDeployBranch({ targetRoot = ".", deployBranch = "", defaultBranch = "", io = {}, say = () => {} }) {
+  if (!deployBranch || typeof io.confirm !== "function") return { created: false, pushed: false };
+  const st = branchStatus(targetRoot, deployBranch);
+  if (!st.isRepo || st.local) return { created: false, pushed: false };
+  if (st.remote === true) {
+    say(`ℹ️ '${deployBranch}' 브랜치가 원격에는 있고 로컬에 없습니다 — 필요 시 'git switch ${deployBranch}'로 가져오세요.`);
+    return { created: false, pushed: false };
+  }
+  say(`⚠️ 개발(릴리스 소스) 브랜치 '${deployBranch}'가 없습니다 — 릴리스(${deployBranch}→${defaultBranch || "기본 브랜치"} PR)가 동작하려면 필요합니다.`);
+  const mk = await io.confirm({ message: `${defaultBranch || "현재"} 브랜치에서 '${deployBranch}' 브랜치를 만들까요?`, initialValue: true });
+  if (mk !== true) {
+    say(`→ 건너뜁니다. 나중에 직접: git checkout -b ${deployBranch} && git push -u origin ${deployBranch}`);
+    return { created: false, pushed: false };
+  }
+  if (!createBranch(targetRoot, deployBranch, defaultBranch)) {
+    say(`⚠️ 브랜치 생성 실패 — 직접 실행해주세요: git branch ${deployBranch}${defaultBranch ? ` ${defaultBranch}` : ""}`);
+    return { created: false, pushed: false };
+  }
+  say(`✅ 로컬 브랜치 '${deployBranch}' 생성 완료 (checkout은 하지 않았습니다)`);
+  // #481 — push 질문에 브랜치명 명시 ("어느 브랜치를 push하는지" 불명확 방지)
+  const up = await io.confirm({ message: `원격(origin)에 '${deployBranch}' 브랜치도 push할까요?`, initialValue: true });
+  if (up !== true) return { created: true, pushed: false };
+  if (pushBranch(targetRoot, deployBranch)) {
+    say(`✅ origin/${deployBranch} push 완료`);
+    return { created: true, pushed: true };
+  }
+  say(`⚠️ push 실패(자격/네트워크) — 직접 실행해주세요: git push -u origin ${deployBranch}`);
+  return { created: true, pushed: false };
+}
 
 // 재노출 — 파서 본체는 version-yml.js에 있다 (순환 import 방지: options-ask → version-yml 방향만 허용)
 export { parseTemplateOptions };
@@ -52,15 +86,23 @@ async function askOptionalWorkflow({ dir, icon, short, desc, current, force, tty
   return include;
 }
 
+// 옵션 질문의 축 키 (#483 수정 스코프 단위) — 수정 메뉴가 이 단위로 한 축만 재질문한다.
+export const OPTION_AXES = ["deploy", "publish", "code-review", "changelog", "release-branch", "secret"];
+
 // 배포/publish 축 + Secret 백업을 순서대로 질문 (.sh ask_all_optional_workflows 등가).
 // tempDir: 템플릿 다운로드 루트 — project-types는 {tempDir}/.github/workflows/project-types
 // current: { deploy: string|null, publish: string[]|null, secretBackup: bool|null } — CLI 명시값
-// 반환: { deploy: string, publish: string[], secretBackup: bool }
+// scope: null이면 전 축(초기 통합·전체 재질문). Set/배열이면 그 축만 forceAsk 대상 (#483 수정 메뉴 격리).
+//        스코프 밖 축은 forceAsk여도 current/저장값을 그대로 유지하고 다시 묻지 않는다.
+// 반환: { deploy, publish, secretBackup, codeReviewCoderabbit, changelogProvider, changelogBaseUrl, deployBranch }
 export async function askAllOptionalWorkflows({
   tempDir, types = [], current = {}, targetRoot = ".",
-  force = false, tty = true, io = {}, forceAsk = false,
+  force = false, tty = true, io = {}, forceAsk = false, defaultBranch = "", scope = null,
 }) {
   const say = io.log || ((m) => process.stderr.write(`${m}\n`));
+  // 축별 재질문 여부: 전역 forceAsk이고, scope가 없거나 그 축을 포함할 때만 강제 질문.
+  const scopeSet = scope == null ? null : new Set(scope);
+  const ask = (axis) => forceAsk && (scopeSet === null || scopeSet.has(axis));
   let deploy = current.deploy ?? null;
   let publish = current.publish ?? null;
   let secretBackup = current.secretBackup ?? null;
@@ -106,36 +148,47 @@ export async function askAllOptionalWorkflows({
     if (deploy === null) deploy = "none";
     if (publish === null) publish = [];
   } else {
-    if (forceAsk || deploy === null) {
+    const willAskDeploy = ask("deploy") || deploy === null;
+    const willAskPublish = ask("publish") || publish === null;
+    // #480 — deploy·publish는 서로 다른 두 축이다. 둘 다 물을 참이면 먼저 큰 그림을 한 번 안내한다.
+    // (수정 메뉴로 한 축만 고칠 때는 맥락이 이미 명확하므로 생략)
+    if (willAskDeploy && willAskPublish && tty && typeof io.select === "function") {
+      say("");
+      say("🧭 배포는 두 가지가 따로 있습니다 — 서로 독립이라 각각 답하시면 됩니다:");
+      say("   1) 실행물 배포 — 서버/호스팅에 올려 돌리는 것 (Docker, Vercel …)");
+      say("   2) 라이브러리 배포(publish) — 남이 가져다 쓰게 레지스트리에 내는 것 (Nexus, npm …)");
+      say("   먼저 (1) 실행물 배포부터 물어보고, 이어서 (2) 라이브러리 배포를 물어봅니다.");
+    }
+    if (willAskDeploy) {
       if (force || !tty || typeof io.select !== "function") {
         deploy = deploy ?? "docker-ssh";
       } else {
         say("");
-        say("🚀 이 프로젝트를 어디에 배포하나요?");
-        say("   서버·호스팅에 올릴 계획이 있으면 고르고, 지금 없으면 '배포 안 함'으로 두면 됩니다.");
+        say("🚀 (1) 실행물(서버/앱)을 어디에 올리나요?");
+        say("   서버·호스팅에 올릴 계획이 있으면 고르고, 없으면 '서버에 올리지 않음'으로 두세요.");
         const ans = await io.select({
-          message: "배포 방식을 선택하세요",
+          message: "실행물 배포 방식을 선택하세요",
           options: [
             { value: "docker-ssh", label: "Docker + SSH 서버 배포 (기본)" },
             { value: "vercel", label: "Vercel" },
-            { value: "none", label: "배포하지 않음 (라이브러리/CI 전용)" },
+            { value: "none", label: "서버에 올리지 않음 (빌드 검증만 · 라이브러리는 다음에서 선택)" },
           ],
         });
         deploy = (!isCancel(ans) && DEPLOY_TARGETS.includes(ans)) ? ans : (deploy ?? "docker-ssh");
-        say(`배포 방식: ${deploy}`);
+        say(`실행물 배포: ${deploy}`);
       }
     }
 
     // ── ③ publish 타겟 (다중 선택) ──
-    if (forceAsk || publish === null) {
+    if (willAskPublish) {
       if (force || !tty || typeof io.multiselect !== "function") {
         publish = publish ?? [];
       } else {
         say("");
-        say("📦 라이브러리로 배포(publish)할 계획이 있나요?");
-        say("   사내 Nexus·npmjs·GitHub Packages 중 해당되는 걸 고르세요. 없으면 그냥 Enter.");
+        say("📦 (2) 이 프로젝트를 남이 가져다 쓰는 라이브러리로도 배포(publish)하나요?");
+        say("   (1) 실행물 배포와 별개입니다. 해당되는 걸 고르고, 라이브러리 배포를 안 하면 아무것도 고르지 말고 Enter.");
         const ans = await io.multiselect({
-          message: "publish 타겟을 선택하세요 (Space 토글, Enter 확정)",
+          message: "라이브러리 배포 타겟 (없으면 선택 없이 Enter = 배포 안 함)",
           options: [
             { value: "nexus", label: "사내 Maven(Nexus) 라이브러리 배포" },
             { value: "npm", label: "공개 npmjs 패키지 배포 (NPM_TOKEN)" },
@@ -147,13 +200,13 @@ export async function askAllOptionalWorkflows({
         publish = (!isCancel(ans) && Array.isArray(ans))
           ? ans.filter((t) => PUBLISH_TARGETS.includes(t))
           : (publish ?? []);
-        say(`Publish 타겟: ${publish.join(",") || "없음"}`);
+        say(publish.length ? `라이브러리 배포: ${publish.join(", ")}` : "라이브러리 배포: 안 함");
       }
     }
   }
 
   // ── code_review: CodeRabbit AI 코드 리뷰 (changelog와 무관 — #455) ──
-  if (forceAsk || codeReviewCoderabbit === null) {
+  if (ask("code-review") || codeReviewCoderabbit === null) {
     if (force || !tty || typeof io.confirm !== "function") {
       codeReviewCoderabbit = codeReviewCoderabbit ?? false;
     } else {
@@ -162,24 +215,33 @@ export async function askAllOptionalWorkflows({
       const ans = await io.confirm({ message: "CodeRabbit AI 코드 리뷰 사용", initialValue: false });
       codeReviewCoderabbit = (ans === true && !isCancel(ans));
       say(`CodeRabbit 코드 리뷰: ${codeReviewCoderabbit ? "사용" : "미사용"}`);
+      // #481 — "사용"만으로는 안 붙는다. 앱 설치 + 레포 접근 권한이 있어야 실제로 리뷰가 달린다.
+      if (codeReviewCoderabbit) {
+        say("   ⚠️ 실제로 리뷰가 붙으려면 추가 설정이 필요합니다:");
+        say("      1) https://coderabbit.ai 접속 → GitHub으로 로그인");
+        say("      2) CodeRabbit GitHub 앱 설치 → 이 저장소에 접근 권한(grant access) 부여");
+        say("      (이 단계를 안 하면 워크플로우는 켜져도 PR에 리뷰 댓글이 달리지 않습니다)");
+      }
     }
   }
 
   // ── changelog: 릴리스 노트 생성기 (기본 커서 = github-ai — #455) ──
-  if (forceAsk || changelogProvider === null) {
+  if (ask("changelog") || changelogProvider === null) {
     if (force || !tty || typeof io.select !== "function") {
       changelogProvider = changelogProvider ?? "github-ai";
     } else {
       say("");
-      say("📝 릴리스 노트(changelog)는 뭘로 만들까요?");
+      say("📝 릴리스 노트(changelog)는 1순위로 뭘로 만들까요?");
       say("   GitHub AI는 설정 없이 바로 됩니다. 나머지는 나중에 GitHub Secret 등록이 필요할 수 있어요.");
+      // #481 — 하나만 골라야 하는 게 아니다. 고른 게 실패하면 자동 폴백하므로 안심하고 고르라고 안내.
+      say("   ✅ 고른 방식이 실패해도 자동으로 GitHub AI → 커밋 분석 순으로 폴백하니 릴리스 노트는 항상 생성됩니다.");
       const ans = await io.select({
-        message: "changelog 생성기를 선택하세요",
+        message: "1순위 changelog 생성기를 선택하세요 (실패 시 자동 폴백)",
         options: [
           { value: "github-ai", label: "GitHub AI (추천 · 설정 불필요)" },
           { value: "coderabbit", label: "CodeRabbit" },
           { value: "openai", label: "OpenAI 호환 API (키 등록 필요)" },
-          { value: "commit", label: "커밋 분석만 (AI 없음)" },
+          { value: "commit", label: "커밋 분석만 (AI 없음 · 최후 안전망)" },
         ],
       });
       changelogProvider = (!isCancel(ans) && CHANGELOG_PROVIDERS.includes(ans)) ? ans : (changelogProvider ?? "github-ai");
@@ -188,7 +250,7 @@ export async function askAllOptionalWorkflows({
   }
 
   // ollama 선택 시에만 base_url 질문 (나머지 provider는 preset base_url 자동 — #455)
-  if (changelogProvider === "ollama" && (forceAsk || changelogBaseUrl === null || changelogBaseUrl === "")) {
+  if (changelogProvider === "ollama" && (ask("changelog") || changelogBaseUrl === null || changelogBaseUrl === "")) {
     if (force || !tty || typeof io.text !== "function") {
       changelogBaseUrl = changelogBaseUrl ?? "";
     } else {
@@ -200,18 +262,23 @@ export async function askAllOptionalWorkflows({
     changelogBaseUrl = "";
   }
 
-  // ── deploy_branch: 릴리스 PR의 head 브랜치 (#456 — default_branch와 별개) ──
-  //    대부분 develop→main 릴리스 구조라 기본값 develop. 다른 head를 쓰는 레포를 위해 물어본다.
-  if (forceAsk || deployBranch === null) {
+  // ── 릴리스 소스(개발) 브랜치 (#456 필드 deploy_branch — 이름과 달리 "개발 브랜치"다, #482) ──
+  //    이 값은 릴리스 PR(개발→기본)의 head, 즉 개발한 걸 모아 기본 브랜치로 올리는 브랜치다.
+  //    "배포 브랜치"가 아니다 — 배포가 도는 곳은 기본 브랜치(default) 쪽 개념. #482 참조.
+  if (ask("release-branch") || deployBranch === null) {
     if (force || !tty || typeof io.text !== "function") {
       deployBranch = deployBranch ?? "develop";
     } else {
+      const base = defaultBranch || "main"; // git으로 감지된 기본 브랜치 (#481 동적 안내)
       say("");
-      say("🌿 릴리스 배포 브랜치(릴리스 PR의 head)는 무엇인가요?");
-      say("   develop→main 릴리스 구조면 develop 그대로 두세요. 배포 브랜치가 따로면 그 이름을 적어주세요.");
-      const ans = await io.text({ message: "배포 브랜치", initialValue: deployBranch ?? "develop" });
+      say("🌿 개발한 코드를 모아서 배포로 올리는 '개발 브랜치'는 무엇인가요?");
+      say(`   감지된 기본(배포) 브랜치는 '${base}'입니다. 개발은 보통 그 앞단 브랜치(예: develop)에서 모아 올립니다.`);
+      say("   특별한 이유가 없으면 develop 그대로 두세요.");
+      const ans = await io.text({ message: "개발(릴리스 소스) 브랜치", initialValue: deployBranch ?? "develop" });
       deployBranch = (typeof ans === "string" && !isCancel(ans) && ans.trim()) ? ans.trim() : (deployBranch ?? "develop");
-      say(`배포 브랜치: ${deployBranch}`);
+      say(`개발(릴리스 소스) 브랜치: ${deployBranch}`);
+      // 브랜치 존재 확인 + 생성 제안 (#477) — 없으면 릴리스 파이프라인이 조용히 놀게 된다
+      await ensureDeployBranch({ targetRoot, deployBranch, defaultBranch, io, say });
     }
   }
 
@@ -221,7 +288,7 @@ export async function askAllOptionalWorkflows({
   secretBackup = await askOptionalWorkflow({
     dir: join(ptDir, "common", "secret-backup"), icon: "🔐", short: "Secret 서버 백업",
     desc: "GitHub Secret에 저장한 설정 파일을 SSH로 서버에 업로드·이력관리하는 워크플로우입니다.",
-    current: secretBackup, force, tty, io, forceAsk, say,
+    current: secretBackup, force, tty, io, forceAsk: ask("secret"), say,
   });
 
   return {

package/src/core/version-yml.js

@@ -43,10 +43,11 @@ const HEADER = `# ==============================================================
 // metadata.template.options 상태머신 파싱 (.sh read_template_options L2361~2416 등가).
 // 반환(#439 배포/publish 축): { deploy: string|null, publish: string[]|null, secretBackup: bool|null }
 //   deploy: 'docker-ssh'|'vercel'|'none', publish: ['nexus','npm','github-packages'] 부분집합. null=미기재.
-// 구 키(nexus/npm_publish)는 신 축으로 자동 마이그레이션해 읽는다 (v4.2.0 이전 파일 호환):
+// 구 키(nexus/npm_publish/synology)는 신 축으로 자동 마이그레이션해 읽는다 (v4.2.0 이전 파일 호환):
 //   nexus:true → publish에 'nexus' + deploy 미기재면 'none' (구 동작: nexus면 서버 배포 제외)
 //   npm_publish:true → publish에 'npm'
-// 구 synology 키 등 다른 키는 어느 분기에도 안 걸려 자연히 무시된다.
+//   synology:true → secret_backup 미기재면 true (#473 — 구 Synology 옵션은 Secret 업로드를 포함했으므로
+//                   승계하지 않으면 비대화형 업데이트에서 Secret 백업 워크플로우를 조용히 잃는다)
 // (options-ask.js가 이 함수를 import한다 — 순환 방지 위해 여기(version-yml)에 정의.)
 export function parseTemplateOptions(content) {
   const out = { deploy: null, publish: null, secretBackup: null,
@@ -60,6 +61,7 @@ export function parseTemplateOptions(content) {
   }
   let legacyNexus = null;
   let legacyNpm = null;
+  let legacySynology = null;
   // 값 정규화: 따옴표 제거 + 트림 (.sh tr -d '"' | tr -d "'" | xargs 등가)
   const strip = (s) => String(s).replace(/["']/g, "").trim();
   let inTemplate = false;
@@ -115,6 +117,13 @@ export function parseTemplateOptions(content) {
         if (v === "false") legacyNpm = false;
         continue;
       }
+      m = line.match(/^\s+synology:\s*(.+)/);
+      if (m) {
+        const v = strip(m[1]);
+        if (v === "true") legacySynology = true;
+        if (v === "false") legacySynology = false;
+        continue;
+      }
       // 들여쓰기 0~4칸의 다른 키 → options 섹션 종료 (.sh L2404~2408)
       if (/^\s{0,4}[a-z_]+:/.test(line)) { inOptions = false; inTemplate = false; }
     }
@@ -130,6 +139,8 @@ export function parseTemplateOptions(content) {
     }
     if (legacyNpm === true) out.publish.push("npm");
   }
+  // 구 synology 키 → secret_backup 승계 (#473) — 신 키가 명시된 경우는 신 키 우선
+  if (out.secretBackup === null && legacySynology === true) out.secretBackup = true;
   return out;
 }
 

package/src/core/wizard-env.js

@@ -1,6 +1,7 @@
 // @wizard env 토큰 엔진 (.sh configure_workflow_env / _wf_set_env / _wf_is_unchanged 등가).
 // ⚠️ YAML 파싱/재직렬화 금지 — 라인 단위 문자열 처리 (포맷·주석 보존이 unchanged 판정 전제).
 // 실측 기준: template_integrator.sh 3282~3360, 3003~3012.
+import { substituteBranches } from "./branch-sub.js";
 
 // KEY 정규식: .sh는 [A-Z_]+ (대문자+언더스코어만). ask/auto 마커가 있는 라인만 대상.
 const MARKER_RE = /#\s*@wizard\s+(ask|auto):(.*)$/;
@@ -96,6 +97,11 @@ export function substituteEnv(content, opts = {}) {
 
 // .sh _wf_is_unchanged 등가: 원본을 "기본값으로 가상 치환한 최종형"과 설치본을 바이트 비교.
 export function isUnchanged(templateContent, installedContent, opts = {}) {
-  const virtual = substituteEnv(templateContent, { ...opts, useDefaults: true });
+  // 브랜치 치환(#477)도 가상 비교에 포함 — 치환 설치본이 "변경됨"으로 오판되어 매 업데이트마다
+  // 재복사(.bak churn)되는 것을 막는다. opts.branches 미지정/표준값이면 no-op.
+  const virtual = substituteBranches(
+    substituteEnv(templateContent, { ...opts, useDefaults: true }),
+    opts.branches ?? null,
+  );
   return virtual === installedContent;
 }

package/src/index.js

@@ -154,8 +154,8 @@ export async function run(argv, { cwd = process.cwd(), source = { type: "git" },
 
   // 완료 요약 (.sh print_summary — CLI 모드에서도 출력)
   printSummary({
-    mode: opts.mode, types, version,
-    counters: { workflows: result?.workflows?.copied ?? 0, utilModules: 0 },
+    mode: opts.mode, types, version, deployBranch: context.deployBranch,
+    counters: { workflows: result?.workflows?.copied ?? 0, workflowFiles: result?.workflows?.copiedFiles ?? [], utilModules: 0 },
   }, cwd);
   return 0;
 }

package/src/ui/prompts.js

@@ -39,7 +39,12 @@ export async function editMenu({ showOptional = false } = {}) {
     { value: "branch", label: "기본 브랜치" },
   ];
   if (showOptional) {
-    options.push({ value: "deploy-publish", label: "배포/Publish 방식" });
+    // #483 — 항목별 격리: 한 축만 골라 그 축만 재질문한다 (통짜 "배포/Publish 방식" 분해)
+    options.push({ value: "deploy", label: "배포 방식 (서버 실행물)" });
+    options.push({ value: "publish", label: "라이브러리 배포(publish) 타겟" });
+    options.push({ value: "code-review", label: "CodeRabbit 코드 리뷰" });
+    options.push({ value: "changelog", label: "릴리스 노트(changelog) 생성기" });
+    options.push({ value: "release-branch", label: "릴리스 소스(개발) 브랜치" });
     options.push({ value: "secret", label: "Secret 백업 포함 여부" });
   }
   options.push({ value: "done", label: "모두 맞음, 계속" });

package/src/ui/summary.js

@@ -2,15 +2,13 @@
 // ctx: { mode, types:[], version, counters:{ workflows, utilModules } }
 import { existsSync, readdirSync } from "node:fs";
 import { join } from "node:path";
-import {
-  PATHS, WORKFLOW_PREFIX, WORKFLOW_COMMON_PREFIX, WORKFLOW_TEMPLATE_INIT,
-} from "../core/paths.js";
-import { listYamlFiles } from "../core/fsutil.js";
+import { WORKFLOW_COMMON_PREFIX } from "../core/paths.js";
 
 const SEPARATOR = "────────────────────────────────────────";
 
 export function printSummary(ctx, targetRoot = ".") {
   const { mode, types = [], version = "", counters = {} } = ctx || {};
+  const deployBranchName = ctx?.deployBranch || "develop"; // #477 — 설정된 배포 브랜치명으로 안내
   const err = (s = "") => process.stderr.write(`${s}\n`);
   // 색상은 TTY일 때만 (.sh YELLOW/CYAN/NC 등가)
   const isTty = !!process.stderr.isTTY;
@@ -18,7 +16,6 @@ export function printSummary(ctx, targetRoot = ".") {
   const CYAN = isTty ? "\x1b[0;36m" : "";
   const NC = isTty ? "\x1b[0m" : "";
   const utilModulesCopied = counters.utilModules ?? 0;
-  const workflowsCopied = counters.workflows ?? 0;
 
   err("");
   err(SEPARATOR);
@@ -77,35 +74,18 @@ export function printSummary(ctx, targetRoot = ".") {
   err("");
   err("추가된 워크플로우:");
 
-  // 실제 복사된 워크플로우와 기존 파일 구분 (.sh L5505~5534)
-  const commonWorkflows = [];
-  const typeWorkflows = [];
-  const existingWorkflows = [];
-  const workflowsDir = join(targetRoot, PATHS.workflowsDir);
-  if (existsSync(workflowsDir)) {
-    const typePrefixes = types.map((t) => `${WORKFLOW_PREFIX}-${t.toUpperCase()}-`);
-    for (const filename of listYamlFiles(workflowsDir)) {
-      if (!filename.startsWith(`${WORKFLOW_PREFIX}-`)) continue; // PROJECT-*.{yaml,yml}만
-      if (filename === WORKFLOW_TEMPLATE_INIT) {
-        // TEMPLATE-INITIALIZER는 템플릿 전용 기존 파일로 분류
-        existingWorkflows.push(filename);
-      } else if (filename.startsWith(`${WORKFLOW_COMMON_PREFIX}-`)) {
-        commonWorkflows.push(filename);
-      } else if (typePrefixes.some((p) => filename.startsWith(p))) {
-        typeWorkflows.push(filename);
-      }
-    }
-  }
+  // 실제 복사·교체된 파일 목록만 출력 (#473 — 디렉토리 스캔은 존재 파일 전부를 "새로 설치됨"으로
+  // 오표기했고 카운터와 소스가 달라 (0개) 불일치가 났다. 복사 엔진의 copiedFiles가 유일한 소스.)
+  const copiedFiles = counters.workflowFiles ?? [];
+  const commonWorkflows = copiedFiles.filter((f) => f.startsWith(`${WORKFLOW_COMMON_PREFIX}-`));
+  const typeWorkflows = copiedFiles.filter((f) => !f.startsWith(`${WORKFLOW_COMMON_PREFIX}-`));
 
-  if (commonWorkflows.length > 0 || typeWorkflows.length > 0) {
-    err(`  📦 새로 설치됨 (${workflowsCopied}개):`);
+  if (copiedFiles.length > 0) {
+    err(`  📦 새로 설치·갱신됨 (${copiedFiles.length}개):`);
     for (const wf of commonWorkflows) err(`     📌 ${wf}`);
     for (const wf of typeWorkflows) err(`     🎯 ${wf}`);
-  }
-  if (existingWorkflows.length > 0) {
-    err("");
-    err("  🔧 기존 파일 유지됨:");
-    for (const wf of existingWorkflows) err(`     📌 ${wf} (템플릿 전용)`);
+  } else {
+    err("  📦 새로 설치·갱신된 워크플로우 없음 — 모두 최신 상태");
   }
 
   err("");
@@ -159,11 +139,11 @@ export function printSummary(ctx, targetRoot = ".") {
   err("     → Secret Name: _GITHUB_PAT_TOKEN");
   err("     → Scopes: repo, workflow");
   err("");
-  err("  2️⃣  develop 브랜치 생성");
-  err("     → git checkout -b develop && git push -u origin develop");
+  err(`  2️⃣  ${deployBranchName} 브랜치 생성 (아직 없다면)`);
+  err(`     → git checkout -b ${deployBranchName} && git push -u origin ${deployBranchName}`);
   err("");
-  err("  3️⃣  CodeRabbit 활성화");
-  err("     → https://coderabbit.ai 방문하여 저장소 활성화");
+  err("  3️⃣  CodeRabbit 활성화 (코드 리뷰를 켰다면)");
+  err("     → https://coderabbit.ai 로그인 → GitHub 앱 설치 → 이 저장소에 접근 권한(grant access) 부여");
   err("");
   err(SEPARATOR);
   err("");