project-auto-wizard 0.1.12 → 0.1.16

package/README.md

@@ -16,7 +16,7 @@ npx project-auto-wizard
 [![node](https://img.shields.io/badge/node-%3E%3D20.12-brightgreen)](package.json)
 
 <!-- AUTO-VERSION-SECTION: DO NOT EDIT MANUALLY -->
-## 최신 버전 : v0.1.11 (2026-08-03)
+## 최신 버전 : v0.1.14 (2026-08-04)
 
 [전체 버전 기록 보기](CHANGELOG.md)
 
@@ -46,6 +46,7 @@ npx project-auto-wizard --mode full --force --type spring,react   # CI에서 비
 
 - **멀티타입**: `--type spring,react,python` — 한 레포에 여러 타입 공존
 - **모노레포**: `--paths "flutter=app,react=client"` — 타입별 서브폴더 지정 (마커 파일 자동 감지)
+- `spring`/`flutter`/`react`/`next`/`python` 5개 타입은 아래 "타입별 워크플로우 구성"처럼 전용 CI/CD가 설치됩니다. `node`/`react-native`/`react-native-expo`/`basic`은 타입 전용 CI 없이 릴리스 자동화(버전 관리·체인지로그·AI 요약)를 담당하는 공통 워크플로우만 설치됩니다 — 빌드/배포 CI는 직접 추가해서 확장할 수 있습니다.
 
 ### 질문 문구 커스터마이징
 
@@ -65,13 +66,14 @@ flutter.APP_ARTIFACT_NAME:
 `spring`/`flutter`는 아래처럼 단일 CI 이상으로 깊게 구성되어 있습니다:
 
 - **flutter**: Android(Firebase/Playstore/Selfhosted/TestAPK 배포), iOS(TestFlight/Test-TestFlight), CI, Lab 트리거까지 8종
-- **spring**: 무중단 배포 2종(Nginx/Traefik) + 단일 서버 배포 + PR 프리뷰 + Nexus publish(opt-in)
+- **spring**: 단일 서버 배포(SIMPLE-CICD, **기본 활성**) + 무중단 배포 2종(Nginx/Traefik, opt-in) + PR 프리뷰 + GitHub Packages publish(항상 설치) + Nexus publish(`--nexus` opt-in)
+  - 무중단 배포 워크플로우는 파일은 설치되지만 `push` 트리거가 기본적으로 비활성(`workflow_dispatch`만 활성)입니다. 기본 배포는 SIMPLE-CICD가 담당하며, 무중단 배포로 전환하려면 해당 워크플로우 YAML의 `push.branches` 주석을 해제하고 SIMPLE-CICD의 `push` 트리거는 주석 처리해야 합니다(각 YAML 상단 주석에 안내되어 있습니다).
 - **react/next**: CI와 CI+CD 분리 구성
 - **python**: CI / PR 프리뷰 / SimpleCICD
 
 ### 되돌리기(`--mode revert`)
 
-`npx project-auto-wizard --mode revert`는 payload가 설치한 파일명과 **정확히 일치하는 것만** 제거합니다. 사용자가 직접 만든 워크플로우, `version.yml`, `README.md`, `.gitignore`는 건드리지 않습니다. 설치 시 충돌 처리로 생성된 `.bak`/`.template.yaml` 파생 파일도 함께 정리됩니다.
+`npx project-auto-wizard --mode revert --force`는 payload가 설치한 파일명과 **정확히 일치하는 것만** 제거합니다. 사용자가 직접 만든 워크플로우, `version.yml`, `README.md`, `.gitignore`는 건드리지 않습니다. 설치 시 충돌 처리로 생성된 `.bak`/`.template.yaml` 파생 파일도 함께 정리됩니다.
 
 ### 완전 삭제(`--mode uninstall`)
 
@@ -137,7 +139,7 @@ npx project-auto-wizard [옵션]
       --purge-readme        --mode uninstall --force 시 README.md 버전 섹션도 제거
       --purge-gitignore     --mode uninstall --force 시 .gitignore 자동 추가 항목도 제거
       --purge-version       --mode uninstall --force 시 version.yml도 제거
-      --force              전 질문 생략 (CI용)
+      --force              full/version/workflows/revert 실행에 필수 (전 질문 생략, CI용)
 ```
 
 ## 설치 상태 확인 · 진단 · 미리보기
@@ -205,7 +207,7 @@ flowchart TB
 ## 개발
 
 ```bash
-npm test          # node --test + python unittest (node 219 + py 87)
+npm test          # node --test + python unittest (node 222 + py 87)
 npm run test:node
 npm run test:py
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "project-auto-wizard",
-  "version": "0.1.12",
+  "version": "0.1.16",
   "description": "One command DevOps: npx wizard that installs GitHub-native AI Release Automation into any project",
   "license": "MIT",
   "type": "module",

package/payload/workflows/common/PROJECT-COMMON-AI-PR-SUMMARY.yaml

@@ -1,3 +1,4 @@
+# project-auto-wizard:managed-workflow
 # ===================================================================
 # PROJECT-COMMON-AI-PR-SUMMARY.yaml
 # Self-hosted AI PR summary bot — no third-party service required.

package/payload/workflows/common/PROJECT-COMMON-AUTO-CHANGELOG-CONTROL.yaml

@@ -1,3 +1,4 @@
+# project-auto-wizard:managed-workflow
 # ===================================================================
 # PROJECT-COMMON-AUTO-CHANGELOG-CONTROL.yaml
 # Release PR pipeline: version confirm + AI changelog + automerge

package/payload/workflows/common/PROJECT-COMMON-README-VERSION-UPDATE.yaml

@@ -1,3 +1,4 @@
+# project-auto-wizard:managed-workflow
 # ===================================================================
 # PROJECT-COMMON-README-VERSION-UPDATE.yaml
 # Automatic README version update workflow

package/payload/workflows/common/PROJECT-COMMON-RELEASE-PUBLISH.yaml

@@ -1,3 +1,4 @@
+# project-auto-wizard:managed-workflow
 # ===================================================================
 # PROJECT-COMMON-RELEASE-PUBLISH.yaml
 # Tag + GitHub Release publisher (dual-mode)

package/payload/workflows/common/PROJECT-COMMON-VERSION-CONTROL.yaml

@@ -1,3 +1,4 @@
+# project-auto-wizard:managed-workflow
 # ===================================================================
 # PROJECT-COMMON-VERSION-CONTROL.yaml
 # Safety-net automatic version bump

package/payload/workflows/common/secret-backup/PROJECT-COMMON-SECRET-FILE-UPLOAD.yaml

@@ -1,3 +1,4 @@
+# project-auto-wizard:managed-workflow
 # ===================================================================
 # PROJECT-COMMON-SECRET-FILE-UPLOAD.yaml
 # GitHub Secret 파일 서버(SSH) 자동 업로드

package/payload/workflows/flutter/PROJECT-FLUTTER-ANDROID-FIREBASE-CICD.yaml

@@ -1,3 +1,4 @@
+# project-auto-wizard:managed-workflow
 # ===================================================================
 # Flutter Android Firebase App Distribution 배포
 # ===================================================================

package/payload/workflows/flutter/PROJECT-FLUTTER-ANDROID-PLAYSTORE-CICD.yaml

@@ -1,3 +1,4 @@
+# project-auto-wizard:managed-workflow
 # ===================================================================
 # Flutter Android Play Store 내부 테스트 배포 워크플로우
 # ===================================================================

package/payload/workflows/flutter/PROJECT-FLUTTER-ANDROID-SELFHOSTED-CICD.yaml

@@ -1,3 +1,4 @@
+# project-auto-wizard:managed-workflow
 # ===================================================================
 # Flutter Android 자체 서버(SMB) 배포 워크플로우
 # ===================================================================

package/payload/workflows/flutter/PROJECT-FLUTTER-ANDROID-TEST-APK.yaml

@@ -1,3 +1,4 @@
+# project-auto-wizard:managed-workflow
 # ===================================================================
 # Flutter Android 테스트용 APK 빌드 워크플로우
 # ===================================================================

package/payload/workflows/flutter/PROJECT-FLUTTER-CI.yaml

@@ -1,3 +1,4 @@
+# project-auto-wizard:managed-workflow
 # ==========================================================================================
 # Flutter CI (코드 분석 및 빌드 검증) 워크플로우
 # ==========================================================================================

package/payload/workflows/flutter/PROJECT-FLUTTER-IOS-TEST-TESTFLIGHT.yaml

@@ -1,3 +1,4 @@
+# project-auto-wizard:managed-workflow
 # ===================================================================
 # Flutter iOS 테스트용 TestFlight 배포 워크플로우
 # ===================================================================

package/payload/workflows/flutter/PROJECT-FLUTTER-IOS-TESTFLIGHT.yaml

@@ -1,3 +1,4 @@
+# project-auto-wizard:managed-workflow
 # ===================================================================
 # Flutter iOS TestFlight 자동 배포 워크플로우
 # ===================================================================

package/payload/workflows/flutter/PROJECT-FLUTTER-SUH-LAB-APP-BUILD-TRIGGER.yaml

@@ -1,3 +1,4 @@
+# project-auto-wizard:managed-workflow
 # ===================================================================
 # Flutter 테스트 앱 빌드 트리거 워크플로우 (SUH-LAB)
 # ===================================================================

package/payload/workflows/next/PROJECT-NEXT-CI.yaml

@@ -1,3 +1,4 @@
+# project-auto-wizard:managed-workflow
 # ===================================================================
 # Next.js CI (코드 분석 및 빌드 검증)
 # ===================================================================

package/payload/workflows/next/PROJECT-NEXT-CICD.yaml

@@ -1,3 +1,4 @@
+# project-auto-wizard:managed-workflow
 # ===================================================================
 # Next.js CI/CD 배포
 # ===================================================================

package/payload/workflows/python/PROJECT-PYTHON-CI.yaml

@@ -1,3 +1,4 @@
+# project-auto-wizard:managed-workflow
 # ===================================================================
 # Python FastAPI 빌드 검증 워크플로우 (CI Only)
 # ===================================================================

package/payload/workflows/python/PROJECT-PYTHON-PR-PREVIEW.yaml

@@ -1,3 +1,4 @@
+# project-auto-wizard:managed-workflow
 # ===================================================================
 # Python/FastAPI PR Preview (SSH + Docker + Traefik)
 # ===================================================================

package/payload/workflows/python/PROJECT-PYTHON-SIMPLE-CICD.yaml

@@ -1,3 +1,4 @@
+# project-auto-wizard:managed-workflow
 # ===================================================================
 # Python FastAPI CI/CD 배포 (SSH + Docker)
 # ===================================================================

package/payload/workflows/react/PROJECT-REACT-CI.yaml

@@ -1,3 +1,4 @@
+# project-auto-wizard:managed-workflow
 # ===================================================================
 # React CI (코드 분석 및 빌드 검증)
 # ===================================================================

package/payload/workflows/react/PROJECT-REACT-CICD.yaml

@@ -1,3 +1,4 @@
+# project-auto-wizard:managed-workflow
 # ===================================================================
 # React CI/CD 배포
 # ===================================================================

package/payload/workflows/spring/PROJECT-SPRING-GITHUB-PACKAGES-PUBLISH.yml

@@ -1,3 +1,4 @@
+# project-auto-wizard:managed-workflow
 # ===================================================================
 # Spring GitHub Packages 라이브러리 배포 워크플로우
 # ===================================================================

package/payload/workflows/spring/nexus/PROJECT-SPRING-NEXUS-CI.yml

@@ -1,3 +1,4 @@
+# project-auto-wizard:managed-workflow
 # ===================================================================
 # Spring Nexus CI 워크플로우
 # ===================================================================

package/payload/workflows/spring/nexus/PROJECT-SPRING-NEXUS-PUBLISH.yml

@@ -1,3 +1,4 @@
+# project-auto-wizard:managed-workflow
 # ===================================================================
 # Spring Nexus 라이브러리 배포 워크플로우
 # ===================================================================

package/payload/workflows/spring/server-deploy/PROJECT-SPRING-NONSTOP-NGINX-CICD.yaml

@@ -1,3 +1,4 @@
+# project-auto-wizard:managed-workflow
 # ===================================================================
 # Spring Boot 무중단 배포 (Nginx Blue-Green, SSH + Docker)
 # ===================================================================

package/payload/workflows/spring/server-deploy/PROJECT-SPRING-NONSTOP-TRAEFIK-CICD.yaml

@@ -1,3 +1,4 @@
+# project-auto-wizard:managed-workflow
 # ===================================================================
 # Spring Boot 무중단 배포 (Traefik Blue-Green, SSH + Docker)
 # ===================================================================

package/payload/workflows/spring/server-deploy/PROJECT-SPRING-PR-PREVIEW.yaml

@@ -1,3 +1,4 @@
+# project-auto-wizard:managed-workflow
 # ===================================================================
 # Spring Boot PR/Issue Preview 시스템 (SSH + Docker)
 # ===================================================================

package/payload/workflows/spring/server-deploy/PROJECT-SPRING-SIMPLE-CICD.yaml

@@ -1,3 +1,4 @@
+# project-auto-wizard:managed-workflow
 # ===================================================================
 # Spring Boot CI/CD 배포 (SSH + Docker)
 # ===================================================================

package/src/cli/args.js

@@ -1,5 +1,5 @@
 // CLI 인자 파싱 (.sh top-level while-case 등가) — template_integrator.sh 842~920.
-import { VALID_TYPES } from "../context.js";
+import { VALID_TYPES, VALID_MODES } from "../context.js";
 
 // argv(process.argv.slice(2)) → 파싱 결과. 오류 시 throw(호출부에서 exit 1).
 export function parseArgs(argv) {
@@ -32,6 +32,7 @@ export function parseArgs(argv) {
     keepScripts: false,
   };
   const args = [...argv];
+  const seenFlags = new Set(); // L7: --nexus류 상호 모순 플래그 검증용
   while (args.length > 0) {
     const a = args.shift();
     switch (a) {
@@ -74,20 +75,45 @@ export function parseArgs(argv) {
       case "--keep-changelog": result.keepChangelog = true; break;
       case "--keep-workflows": result.keepWorkflows = true; break;
       case "--keep-scripts": result.keepScripts = true; break;
-      case "--nexus": result.includeNexus = true; break;
-      case "--no-nexus": result.includeNexus = false; break;
-      case "--secret-backup": result.includeSecretBackup = true; break;
-      case "--no-secret-backup": result.includeSecretBackup = false; break;
-      case "--semver-auto": result.includeSemverAuto = true; break;
-      case "--no-semver-auto": result.includeSemverAuto = false; break;
+      case "--nexus":
+        if (seenFlags.has("--no-nexus")) throw new CliError("--nexus와 --no-nexus는 동시에 지정할 수 없습니다");
+        seenFlags.add("--nexus"); result.includeNexus = true; break;
+      case "--no-nexus":
+        if (seenFlags.has("--nexus")) throw new CliError("--nexus와 --no-nexus는 동시에 지정할 수 없습니다");
+        seenFlags.add("--no-nexus"); result.includeNexus = false; break;
+      case "--secret-backup":
+        if (seenFlags.has("--no-secret-backup")) throw new CliError("--secret-backup과 --no-secret-backup은 동시에 지정할 수 없습니다");
+        seenFlags.add("--secret-backup"); result.includeSecretBackup = true; break;
+      case "--no-secret-backup":
+        if (seenFlags.has("--secret-backup")) throw new CliError("--secret-backup과 --no-secret-backup은 동시에 지정할 수 없습니다");
+        seenFlags.add("--no-secret-backup"); result.includeSecretBackup = false; break;
+      case "--semver-auto":
+        if (seenFlags.has("--no-semver-auto")) throw new CliError("--semver-auto와 --no-semver-auto는 동시에 지정할 수 없습니다");
+        seenFlags.add("--semver-auto"); result.includeSemverAuto = true; break;
+      case "--no-semver-auto":
+        if (seenFlags.has("--semver-auto")) throw new CliError("--semver-auto와 --no-semver-auto는 동시에 지정할 수 없습니다");
+        seenFlags.add("--no-semver-auto"); result.includeSemverAuto = false; break;
       case "--paths": result.pathsCsv = args.shift() ?? ""; break;
-      case "--main-branch": result.mainBranch = args.shift() ?? ""; break;
-      case "--develop-branch": result.developBranch = args.shift() ?? ""; break;
+      case "--main-branch": {
+        const v = args.shift();
+        if (!v) throw new CliError("--main-branch에 빈 값을 지정할 수 없습니다");
+        result.mainBranch = v; break;
+      }
+      case "--develop-branch": {
+        const v = args.shift();
+        if (!v) throw new CliError("--develop-branch에 빈 값을 지정할 수 없습니다");
+        result.developBranch = v; break;
+      }
       case "-h": case "--help": result.help = true; break;
       default:
         throw new CliError(`알 수 없는 옵션: ${a}`);
     }
   }
+  if (!VALID_MODES.includes(result.mode)) {
+    throw new CliError(
+      `지원하지 않는 모드: '${result.mode}'\n지원 모드: interactive full version workflows revert uninstall status doctor`
+    );
+  }
   return result;
 }
 
@@ -109,7 +135,7 @@ export function parsePathsCsv(csv) {
   for (const pair of csv.split(",")) {
     if (pair.trim() === "") continue;
     const eq = pair.indexOf("=");
-    const type = (eq >= 0 ? pair.slice(0, eq) : pair).trim();
+    const type = (eq >= 0 ? pair.slice(0, eq) : pair).replace(/\s/g, "");
     const rawPath = eq >= 0 ? pair.slice(eq + 1) : "";
     if (!VALID_TYPES.includes(type)) {
       throw new CliError(`--paths에 지원하지 않는 타입: '${type}'`);

package/src/cli/help.js

@@ -19,7 +19,7 @@ export const HELP_TEXT = `project-auto-wizard — One command DevOps: GitHub-nat
       --nexus / --no-nexus            Nexus 라이브러리 publish 워크플로우 포함/제외
       --secret-backup / --no-secret-backup   Secret 백업 워크플로우 포함/제외
       --semver-auto / --no-semver-auto  커밋 타입 기반 자동 major/minor/patch 승격 (기본: 사용함)
-      --force              모든 확인 생략, 비대화형 기본값 사용
+      --force              full/version/workflows/revert 실행에 필수 (모든 확인 생략, 비대화형 기본값 사용)
       --dry-run            실제 파일 변경 없이 무엇이 바뀔지만 미리 보여줌 (full/version/workflows/revert/uninstall 전체 지원)
       --purge-readme        --mode uninstall --force 시 README.md 버전 섹션도 제거
       --purge-gitignore     --mode uninstall --force 시 .gitignore 자동 추가 항목도 제거
@@ -29,7 +29,7 @@ export const HELP_TEXT = `project-auto-wizard — One command DevOps: GitHub-nat
 
 예시:
   npx project-auto-wizard --mode full --force --type spring,react
-  npx project-auto-wizard --mode workflows --type flutter --paths "flutter=app"
+  npx project-auto-wizard --mode workflows --force --type flutter --paths "flutter=app"
   npx project-auto-wizard --mode status
   npx project-auto-wizard --mode doctor
   npx project-auto-wizard --mode full --force --type node --dry-run

package/src/commands/dry-run.js

@@ -6,7 +6,7 @@ import { PATHS } from "../core/paths.js";
 import { planWorkflows } from "../core/copy/workflows.js";
 import { planRevert } from "./revert.js";
 import { planUninstall } from "./uninstall.js";
-import { buildVersionYml } from "../core/version-yml.js";
+import { buildVersionYml, parseExisting } from "../core/version-yml.js";
 import { readVersionYmlTemplate } from "../core/assets.js";
 import { markerForType } from "../core/detect.js";
 
@@ -17,18 +17,22 @@ function versionYmlPreview(context, payloadRoot, targetRoot) {
     includeSemverAuto } = context;
   const pathMarkers = new Map();
   for (const [t] of paths) pathMarkers.set(t, markerForType(t));
+
+  const vyPath = join(targetRoot, PATHS.versionFile);
+  const existingRaw = existsSync(vyPath) ? readFileSync(vyPath, "utf8") : null;
+  const extraTopLevel = existingRaw !== null ? parseExisting(existingRaw).extraTopLevel : [];
+
   const wouldBe = buildVersionYml({
     templateText: readVersionYmlTemplate(payloadRoot),
     version, types, paths, pathMarkers, branch, branches: context.branches, versionCode, now, today,
+    extraTopLevel,
     templateOptions: {
       templateVersion, includeNexus, includeSecretBackup,
       includeSemverAuto: includeSemverAuto !== false,
       optionsDate: today,
     },
   });
-  const vyPath = join(targetRoot, PATHS.versionFile);
-  const existing = existsSync(vyPath) ? readFileSync(vyPath, "utf8") : null;
-  return { existed: existing !== null, changed: existing !== wouldBe };
+  return { existed: existingRaw !== null, changed: existingRaw !== wouldBe };
 }
 
 // mode: "full" | "version" | "workflows" | "revert" | "uninstall". 읽기 전용 — 아무 파일도 쓰지 않는다.

package/src/commands/full.js

@@ -3,9 +3,10 @@
 // gitignore는 충돌 백업 부산물(.bak/.template.yaml)이 이번 실행에서 실제로 생겼을 때만 갱신한다 — issue #7.
 // (원본의 util/issue/discussion/setup-guide/config 설치는 project-auto-wizard 스코프에서 제외 — DESIGN-SPEC §2)
 import { join } from "node:path";
+import { existsSync, readFileSync } from "node:fs";
 import { writeText } from "../core/fsutil.js";
 import { PATHS } from "../core/paths.js";
-import { buildVersionYml } from "../core/version-yml.js";
+import { buildVersionYml, parseExisting } from "../core/version-yml.js";
 import { readVersionYmlTemplate } from "../core/assets.js";
 import { markerForType } from "../core/detect.js";
 import { addVersionSectionToReadme } from "../core/copy/readme.js";
@@ -31,12 +32,16 @@ export function runFull(context, payloadRoot, targetRoot = ".", hooks = {}) {
   const wfCounters = copyWorkflows(context, payloadRoot, targetRoot, hooks);
   const deployValues = wfCounters.deployValues || new Map(); // Map<type, Map<key,value>>
 
+  // 기존 version.yml의 알려지지 않은 최상위 필드를 재생성 시 보존한다 (issue #20 M8).
+  const vyPath = join(targetRoot, PATHS.versionFile);
+  const extraTopLevel = existsSync(vyPath) ? parseExisting(readFileSync(vyPath, "utf8")).extraTopLevel : [];
+
   // 2. version.yml 생성 (payload/version.yml.template 렌더링 — 전체 재생성 전략 D4)
   writeText(join(targetRoot, PATHS.versionFile),
     buildVersionYml({
       templateText: readVersionYmlTemplate(payloadRoot),
       version, types, paths, pathMarkers, branch, branches: context.branches, versionCode, now, today,
-      deployValues,
+      deployValues, extraTopLevel,
       templateOptions: { templateVersion, includeNexus, includeSecretBackup, includeSemverAuto: includeSemverAuto !== false, optionsDate: today },
     }));
 

package/src/commands/interactive.js

@@ -240,9 +240,9 @@ export async function runInteractive(baseCtx, { cwd = process.cwd(), payloadRoot
   // 완료 요약 (.sh print_summary L5438)
   io.summary?.({
     mode, types, version, branches,
-    counters: { workflows: result?.workflows?.copied ?? 0 },
+    copiedFiles: result?.workflows?.copiedFiles ?? [],
     gitignoreUpdated: result?.gitignoreUpdated === true,
-  }, cwd);
+  });
   io.outro?.(`통합 완료 — ${mode} 모드로 설치했습니다.`);
   return 0;
 }

package/src/commands/revert.js

@@ -1,12 +1,21 @@
-// revert 모드 — payload 유래 파일만 제거 (DESIGN-SPEC §4 되돌리기).
-// 원칙: payload에 존재하는 파일명과 정확히 일치하는 것만 지운다.
+// revert 모드 — payload 유래 파일 + 마커로 식별되는 파일을 제거 (DESIGN-SPEC §4 되돌리기).
+// 원칙: (a) 현재 payload에 존재하는 파일명과 정확히 일치하는 것, (b) 설치된 워크플로우 파일 중
+// 마법사 관리 마커(MANAGED_WORKFLOW_MARKER)로 시작하는 것 — 이 둘의 합집합을 제거 대상으로 삼는다.
+// (a)만으로는 과거 버전에서 설치된 뒤 이후 릴리스에서 payload 파일명이 바뀌거나 삭제된 파일을
+// 인식하지 못했다 (issue #20 L12 원래 버그). 반대로 (b)만으로는 이 수정 이전에 설치되어 마커가
+// 없는(그러나 파일명은 여전히 현재 payload와 일치하는) 기존 설치 전체를 인식하지 못하는 회귀가
+// 생긴다 — 그래서 두 방식을 합집합으로 병행한다. 마커는 이 수정 이후 배포되는 payload 템플릿부터
+// 포함되므로, (b) 경로가 실제로 새로 잡아내는 것은 "이름이 바뀌거나 삭제된, 마커가 있는" 파일뿐이다.
 // 사용자가 직접 만든 워크플로우·version.yml·README·.gitignore는 건드리지 않는다
 // (version.yml은 사용자 버전 데이터 — 제거 대상이 아니라 산출물이다).
 import { join } from "node:path";
-import { existsSync, readdirSync } from "node:fs";
+import { existsSync, readFileSync, readdirSync } from "node:fs";
 import { PATHS, PAYLOAD } from "../core/paths.js";
 import { remove } from "../core/fsutil.js";
 
+// payload/workflows/**/*.yaml 첫 줄에 심어둔 고정 마커 — 이 값이 바뀌면 과거 설치분과의 매칭이 끊긴다.
+export const MANAGED_WORKFLOW_MARKER = "# project-auto-wizard:managed-workflow";
+
 // payload/workflows/** 전체(하위 폴더 포함)의 yaml 파일명 집합.
 function payloadWorkflowNames(payloadRoot) {
   const names = new Set();
@@ -18,26 +27,41 @@ function payloadWorkflowNames(payloadRoot) {
   return names;
 }
 
-// payload에 존재하는 파일명과 정확히 일치하는 것만 제거 대상으로 계획한다.
+// 설치된 워크플로우 디렉토리(평면 구조)에서 관리 마커로 시작하는 파일명 집합.
+// .bak/.template.yaml 백업본도 원본 텍스트를 그대로 복사한 것이라 마커를 그대로 갖고 있어
+// 확장자나 파일명 유추 없이 동일한 방식으로 인식된다 (issue #20 L12).
+function markedWorkflowNames(wfDir) {
+  const names = new Set();
+  if (!existsSync(wfDir)) return names;
+  for (const entry of readdirSync(wfDir, { withFileTypes: true })) {
+    if (!entry.isFile()) continue;
+    const firstLine = readFileSync(join(wfDir, entry.name), "utf8").split("\n", 1)[0].replace(/\r$/, "");
+    if (firstLine === MANAGED_WORKFLOW_MARKER) names.add(entry.name);
+  }
+  return names;
+}
+
 // 아무것도 지우지 않는 순수 함수 — --dry-run과 status류 기능에서 재사용.
 export function planRevert(payloadRoot, targetRoot = ".") {
-  const removedWf = [];
+  const removedWf = new Set();
   const removedScripts = [];
   const wfDir = join(targetRoot, PATHS.workflowsDir);
-  const names = payloadWorkflowNames(payloadRoot);
   if (existsSync(wfDir)) {
-    for (const name of names) {
+    // (a) 현재 payload와 파일명이 일치하는 것 — 기존 동작 그대로(마커 유무 무관, 기존 설치 회귀 방지).
+    for (const name of payloadWorkflowNames(payloadRoot)) {
       const p = join(wfDir, name);
-      if (existsSync(p)) removedWf.push(name);
+      if (existsSync(p)) removedWf.add(name);
       const templateName = (name.endsWith(".yaml") ? name.slice(0, -".yaml".length) : name) + ".template.yaml";
-      if (existsSync(join(wfDir, templateName))) removedWf.push(templateName);
-      if (existsSync(p + ".bak")) removedWf.push(name + ".bak");
+      if (existsSync(join(wfDir, templateName))) removedWf.add(templateName);
+      if (existsSync(p + ".bak")) removedWf.add(name + ".bak");
     }
+    // (b) 관리 마커로 시작하는 것 — payload에서 이름이 바뀌거나 삭제된 파일도 인식 (issue #20 L12).
+    for (const name of markedWorkflowNames(wfDir)) removedWf.add(name);
   }
   for (const s of ["version_manager.py", "changelog_manager.py"]) {
     if (existsSync(join(targetRoot, PATHS.scriptsDir, s))) removedScripts.push(s);
   }
-  return { workflows: removedWf, scripts: removedScripts };
+  return { workflows: [...removedWf], scripts: removedScripts };
 }
 
 // 반환: { workflows: [...제거된 파일명], scripts: [...] } — planRevert와 동일한 형태.

package/src/commands/version.js

@@ -3,9 +3,10 @@
 // (워크플로우를 복사하지 않으므로 충돌 백업 부산물이 생길 수 없다 — gitignore 갱신 대상 없음, issue #7.
 //  util·issue·setup-guide는 스코프 제외.)
 import { join } from "node:path";
+import { existsSync, readFileSync } from "node:fs";
 import { writeText } from "../core/fsutil.js";
 import { PATHS } from "../core/paths.js";
-import { buildVersionYml } from "../core/version-yml.js";
+import { buildVersionYml, parseExisting } from "../core/version-yml.js";
 import { readVersionYmlTemplate } from "../core/assets.js";
 import { markerForType } from "../core/detect.js";
 import { addVersionSectionToReadme } from "../core/copy/readme.js";
@@ -20,10 +21,15 @@ export function runVersion(context, payloadRoot, targetRoot = ".") {
   const pathMarkers = new Map();
   for (const [t] of paths) pathMarkers.set(t, markerForType(t));
 
+  // 기존 version.yml의 알려지지 않은 최상위 필드를 재생성 시 보존한다 (issue #20 M8).
+  const vyPath = join(targetRoot, PATHS.versionFile);
+  const extraTopLevel = existsSync(vyPath) ? parseExisting(readFileSync(vyPath, "utf8")).extraTopLevel : [];
+
   writeText(join(targetRoot, PATHS.versionFile),
     buildVersionYml({
       templateText: readVersionYmlTemplate(payloadRoot),
       version, types, paths, pathMarkers, branch, branches: context.branches, versionCode, now, today,
+      extraTopLevel,
       templateOptions: { templateVersion, includeNexus, includeSecretBackup, includeSemverAuto: includeSemverAuto !== false, optionsDate: today },
     }));
   addVersionSectionToReadme(version, targetRoot);

package/src/commands/workflows.js

@@ -7,6 +7,7 @@ import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { PATHS } from "../core/paths.js";
 import { copyWorkflows } from "../core/copy/workflows.js";
 import { copyScripts } from "../core/copy/simple.js";
+import { escapeYamlDoubleQuoted } from "../core/wizard-env.js";
 
 export function runWorkflows(context, payloadRoot, targetRoot = ".", hooks = {}) {
   const wf = copyWorkflows(context, payloadRoot, targetRoot, hooks);
@@ -42,7 +43,9 @@ export function upsertDeployBlock(content, deployValues) {
     text += `\ndeploy:                          # 마법사가 기억하는 배포 설정 (비민감 / 직접 수정 가능)\n`;
     for (const t of deployTypes) {
       text += `  ${t}:\n`;
-      for (const [k, v] of deployValues.get(t)) text += `    ${k}: "${v}"\n`;
+      // 동일한 이스케이프를 재사용 — deploy 값도 @wizard ask 값과 같은 경로로 들어오므로
+      // 큰따옴표가 섞이면 YAML이 깨진다 (issue #20 L9, 세 번째 지점).
+      for (const [k, v] of deployValues.get(t)) text += `    ${k}: "${escapeYamlDoubleQuoted(v)}"\n`;
     }
   }
   return text;

package/src/context.js

@@ -4,6 +4,13 @@ export const VALID_TYPES = [
   "react-native", "react-native-expo", "node", "python", "basic",
 ];
 
+// --mode 화이트리스트 (issue #19) — 알 수 없는 값은 부수효과(브랜치 조회 등) 이전에 즉시 거부해야 한다.
+// purge는 --help/대화형 메뉴에 노출하지 않는 숨김 모드(issue #6)이지만 검증 대상에는 포함한다.
+export const VALID_MODES = [
+  "interactive", "full", "version", "workflows",
+  "revert", "uninstall", "status", "doctor", "purge",
+];
+
 export const DEFAULT_VERSION = "0.0.0"; // 패키지 버전 읽기 실패 시 폴백 (배너용 — breaking 비교엔 안 씀)
 
 export function createContext(overrides = {}) {

package/src/core/copy/gitignore.js

@@ -1,10 +1,11 @@
 // .gitignore 보장 — 마법사 자신이 만드는 충돌 백업 부산물(*.bak, *.template.yaml)만 대상으로 한다.
 // 마법사가 설치하는 것과 무관한 개인 개발환경 설정(IDE 등)은 마법사 책임 범위 밖 — issue #7.
-// 주의(의도된 트레이드오프): 이 변경 이전 버전으로 설치해 /.idea·/.claude/settings.local.json이 이미
-// 배너 블록에 남아있는 레포에서 removeAutoAddedEntriesFromGitignore()를 실행하면, 배너는 제거되지만
-// REQUIRED_ENTRIES가 더 이상 옛 항목과 일치하지 않아 그 두 줄은 지워지지 않고 배너 표시 없이 남는다.
-// 이슈 #7이 "이미 설치된 레포의 .gitignore는 소급 처리하지 않고 사용자 판단에 맡긴다"고 명시하므로
-// 별도 마이그레이션 로직을 추가하지 않는다 — 남은 항목은 무해하며 필요하면 사용자가 직접 지운다.
+// 배너 블록은 종료 마커(BANNER_END)로 범위가 명확히 구분되어 있어, 그 안에 사용자가 다른 줄을
+// 끼워넣어도 REQUIRED_ENTRIES만 정확히 개별 제거하고 나머지는 보존한다 (issue #20 M7).
+// 주의(의도된 트레이드오프): 이 수정 이전 버전으로 설치되어 종료 마커가 없는 배너가 이미 있는
+// 레포에서는, 배너 직후 REQUIRED_ENTRIES가 연속으로 이어지는 동안만 제거하는 구 방식으로
+// 폴백한다 — issue #7이 "이미 설치된 레포의 .gitignore는 소급 처리하지 않고 사용자 판단에
+// 맡긴다"고 명시하므로 별도 마이그레이션 로직을 추가하지 않는다.
 import { join } from "node:path";
 import { existsSync, readFileSync, writeFileSync, rmSync } from "node:fs";
 
@@ -57,19 +58,28 @@ export function ensureGitignore(targetRoot = ".") {
   content += "# project-auto-wizard: Auto-added entries\n";
   content += "# ====================================================================\n";
   for (const e of toAdd) content += e + "\n";
+  content += BANNER_END;
   writeFileSync(p, content);
   return { created: false, added: toAdd };
 }
 
 // ensureGitignore가 기존 파일에 배너 블록을 추가할 때 항상 이 정확한 시퀀스로 시작한다
-// (빈 줄 하나 + 3줄 배너). 배너 직후, REQUIRED_ENTRIES와 일치하는 라인이 연속되는 동안만
-// "마법사가 추가한 항목"이다 — 그 뒤에 사용자가 나중에 추가한 항목은 절대 건드리지 않는다.
+// (빈 줄 하나 + 3줄 배너), 그리고 REQUIRED_ENTRIES 뒤에 BANNER_END로 끝난다. 배너~BANNER_END
+// 범위 안에서 REQUIRED_ENTRIES와 일치하는 줄만 개별 제거하고, 사용자가 그 사이/뒤에 추가한
+// 줄은 절대 건드리지 않는다 (issue #20 M7).
 const BANNER =
   "\n" +
   "# ====================================================================\n" +
   "# project-auto-wizard: Auto-added entries\n" +
   "# ====================================================================\n";
 
+// REQUIRED_ENTRIES 뒤에 오는 종료 마커 — 배너 블록의 "끝"을 명확히 구분해, 그 사이에 사용자가
+// 다른 줄을 끼워넣어도 removeAutoAddedEntriesFromGitignore가 정확한 범위 안에서 개별 제거할 수
+// 있게 한다 (issue #20 M7). ensureGitignore가 기존 파일에 배너를 추가할 때만 함께 쓴다
+// (신규 파일 생성 케이스는 NEW_FILE_CONTENT를 통째로 쓰고 종료 마커는 쓰지 않는다 —
+// startsWith 전체 prefix 매칭이라 별도 마커가 필요 없다).
+const BANNER_END = "# ==== project-auto-wizard: end of auto-added entries ====\n";
+
 // .gitignore에 마법사가 추가한 항목이 있는지 확인 (체크리스트 노출 판단용).
 // 두 케이스: (1) 원래 없던 파일을 통째로(또는 그 뒤에 사용자가 이어 쓴 형태로) 새로 만든 경우
 // (2) 기존 파일에 배너 블록을 붙인 경우.
@@ -97,11 +107,26 @@ export function removeAutoAddedEntriesFromGitignore(targetRoot = ".") {
     return "removed";
   }
 
-  // 기존 파일에 배너 블록이 붙은 경우 — 배너 직후 REQUIRED_ENTRIES와 일치하는 라인이 연속되는
-  // 동안만 제거하고, 그 뒤(사용자가 나중에 추가한 항목)는 그대로 둔다.
+  // 기존 파일에 배너 블록이 붙은 경우.
   const idx = content.indexOf(BANNER);
   if (idx === -1) return "skip-not-found";
   const afterBanner = idx + BANNER.length;
+
+  // 종료 마커가 있으면(이 수정 이후 설치분) 그 범위 안에서 REQUIRED_ENTRIES만 개별적으로
+  // 제거하고, 사용자가 그 사이에 끼워넣은 줄은 순서·연속 여부와 무관하게 그대로 보존한다
+  // (issue #20 M7).
+  const endIdx = content.indexOf(BANNER_END, afterBanner);
+  if (endIdx !== -1) {
+    const region = content.slice(afterBanner, endIdx).split("\n");
+    const kept = region.filter((line) =>
+      !REQUIRED_ENTRIES.some((e) => normalizeGitignoreEntry(line) === normalizeGitignoreEntry(e)));
+    const afterEndMarker = content.slice(endIdx + BANNER_END.length);
+    writeFileSync(p, content.slice(0, idx) + kept.join("\n") + afterEndMarker);
+    return "removed";
+  }
+
+  // 종료 마커가 없는 구버전 설치(이 수정 이전) — 배너 직후 REQUIRED_ENTRIES가 연속으로
+  // 이어지는 동안만 제거하는 기존 방식으로 폴백한다 (issue #7과 동일한 소급 미처리 원칙).
   const lines = content.slice(afterBanner).split("\n");
   let consumed = 0;
   for (const line of lines) {

package/src/core/copy/workflows.js

@@ -69,27 +69,26 @@ export function copyWorkflows(context, payloadRoot, targetRoot = ".", hooks = {}
   const counters = { copied: 0, skipped: 0, templateAdded: 0, optionalCopied: 0, backupAdded: 0 };
   const deployValues = new Map(); // Map<type, Map<key,value>> — deploy 블록용 ask 값
   counters.deployValues = deployValues;
+  counters.copiedFiles = []; // 이번 실행에서 실제로 새로 쓰여진 파일명 (issue #19 — printSummary 정확성용)
   const srcText = makeSrcText(context.branches || null);
   // values/useDefaults는 치환 경로에서만 의미 (isUnchanged는 내부에서 useDefaults:true 강제 — 가상 비교 무손상)
   const envOptsFor = (type) => ({ type, projectPath: paths.get(type) || ".", repoName, resolvers, values: envValues, useDefaults: envUseDefaults });
 
-  // (1) common — unchanged면 스킵, 아니면 무조건 덮어쓰기.
+  // (1) common — 타입별 워크플로우와 동일한 3지선(README 계약, issue #20 H3): unchanged면 스킵,
+  //     changed면 decisions Map 결정에 따름(미지정 시 skip — 기존 사용자 수정 보존).
   //     trunk-based 모드는 VERSION-CONTROL·AUTO-CHANGELOG 미설치 (RELEASE-PUBLISH 단독).
   const branchMode = context.branches?.mode || "pr-flow";
   const commonDir = join(projectTypesDir, "common");
   if (exists(commonDir)) {
-    for (const filename of listYamlFiles(commonDir)) {
-      if (branchMode === "trunk-based" && TRUNK_BASED_EXCLUDED.has(filename)) continue;
-      const src = join(commonDir, filename);
-      const dst = join(workflowsDir, filename);
-      const body = srcText(src);
-      if (existsSync(dst) && isUnchanged(body, readFileSync(dst, "utf8"), envOptsFor("common"))) {
-        counters.skipped++;
-        continue;
-      }
-      writeText(dst, body);
+    const notExcluded = (filename) => !(branchMode === "trunk-based" && TRUNK_BASED_EXCLUDED.has(filename));
+    const { newFiles, unchanged, changed } = classify(commonDir, workflowsDir, envOptsFor("common"), srcText);
+    counters.skipped += unchanged.filter(notExcluded).length;
+    for (const f of newFiles.filter(notExcluded)) {
+      writeText(join(workflowsDir, f), srcText(join(commonDir, f)));
       counters.copied++;
+      counters.copiedFiles.push(f);
     }
+    for (const f of changed.filter(notExcluded)) applyDecision(decisions.get(f), commonDir, workflowsDir, f, counters, srcText);
   }
 
   // (2~4) 타입별
@@ -108,6 +107,7 @@ export function copyWorkflows(context, payloadRoot, targetRoot = ".", hooks = {}
       writeText(dst, srcText(join(secretDir, filename)));
       counters.optionalCopied++;
       counters.copied++;
+      counters.copiedFiles.push(filename);
     }
   }
 
@@ -125,6 +125,7 @@ function applyDecision(decision, srcDir, workflowsDir, filename, counters, srcTe
     writeText(dst, srcText(src));
     counters.copied++;
     counters.backupAdded++;
+    counters.copiedFiles.push(filename);
     return;
   }
   if (decision === "template") {
@@ -132,6 +133,7 @@ function applyDecision(decision, srcDir, workflowsDir, filename, counters, srcTe
     const templateName = (filename.endsWith(".yaml") ? filename.slice(0, -".yaml".length) : filename) + ".template.yaml";
     writeText(join(workflowsDir, templateName), srcText(src)); // 기존 .template.yaml 덮어씀(.sh rm -f + cp 등가)
     counters.templateAdded++;
+    counters.copiedFiles.push(templateName);
     return;
   }
   counters.skipped++; // 'skip'/미지정/ESC → 기존 유지 (.sh S)·force 기본)
@@ -139,12 +141,24 @@ function applyDecision(decision, srcDir, workflowsDir, filename, counters, srcTe
 
 // 대상 워크플로우 디렉토리에서 changed(충돌) 파일 목록만 뽑는다 — copyWorkflowsInteractive의 사전 조사용.
 // copyWorkflows 본체와 동일한 classify 기준을 써야 결정 Map이 실제 처리 대상과 1:1로 맞는다.
+// common도 타입별과 동일하게 스캔한다 (issue #20 H3 — 이전에는 common 충돌이 질문조차 되지 않았다).
 export function listWorkflowConflicts(context, payloadRoot, targetRoot = ".") {
   const { types = [], paths = new Map(), includeNexus = false, repoName = "", resolvers = {} } = context;
   const workflowsDir = join(targetRoot, PATHS.workflowsDir);
   const projectTypesDir = join(payloadRoot, PAYLOAD.workflowsDir);
   const srcText = makeSrcText(context.branches || null);
-  const conflicts = []; // [{ filename, type }] — 엔진 처리 순서와 동일 (타입 순회 → 직하위 → server-deploy)
+  const branchMode = context.branches?.mode || "pr-flow";
+  const conflicts = []; // [{ filename, type }] — 엔진 처리 순서와 동일 (common → 타입 순회 → 직하위 → server-deploy)
+
+  const commonDir = join(projectTypesDir, "common");
+  if (exists(commonDir)) {
+    const envOpts = { type: "common", projectPath: ".", repoName, resolvers };
+    for (const f of classify(commonDir, workflowsDir, envOpts, srcText).changed) {
+      if (branchMode === "trunk-based" && TRUNK_BASED_EXCLUDED.has(f)) continue;
+      conflicts.push({ filename: f, type: "common" });
+    }
+  }
+
   for (const type of types) {
     const envOpts = { type, projectPath: paths.get(type) || ".", repoName, resolvers };
     const typeDir = join(projectTypesDir, type);
@@ -185,7 +199,11 @@ function copyWorkflowsForType(type, projectTypesDir, workflowsDir, ctx, counters
     const { newFiles, unchanged, changed } = classify(typeDir, workflowsDir, envOpts, srcText);
     unchangedNames = unchanged.slice();
     for (const f of unchanged) counters.skipped++;
-    for (const f of newFiles) { writeText(join(workflowsDir, f), srcText(join(typeDir, f))); counters.copied++; }
+    for (const f of newFiles) {
+      writeText(join(workflowsDir, f), srcText(join(typeDir, f)));
+      counters.copied++;
+      counters.copiedFiles.push(f);
+    }
     // changed: 결정 Map에 따라 처리 (미지정=skip → 현행 force 동작과 동일)
     for (const f of changed) applyDecision(decisions.get(f), typeDir, workflowsDir, f, counters, srcText);
   }
@@ -198,7 +216,11 @@ function copyWorkflowsForType(type, projectTypesDir, workflowsDir, ctx, counters
     } else {
       const { newFiles, unchanged, changed } = classify(serverDeployDir, workflowsDir, envOpts, srcText);
       for (const f of unchanged) counters.skipped++;
-      for (const f of newFiles) { writeText(join(workflowsDir, f), srcText(join(serverDeployDir, f))); counters.copied++; }
+      for (const f of newFiles) {
+        writeText(join(workflowsDir, f), srcText(join(serverDeployDir, f)));
+        counters.copied++;
+        counters.copiedFiles.push(f);
+      }
       for (const f of changed) applyDecision(decisions.get(f), serverDeployDir, workflowsDir, f, counters, srcText);
     }
   }
@@ -218,6 +240,7 @@ function copyWorkflowsForType(type, projectTypesDir, workflowsDir, ctx, counters
       writeText(dst, body);
       counters.optionalCopied++;
       counters.copied++;
+      counters.copiedFiles.push(filename);
     }
   }
 
@@ -234,8 +257,8 @@ function copyWorkflowsForType(type, projectTypesDir, workflowsDir, ctx, counters
 }
 
 // 전체 워크플로우 분류(common + 타입별 + server-deploy + nexus opt-in) — status/dry-run 공용.
-// listWorkflowConflicts와 달리 common 디렉토리도 포함하고, changed뿐 아니라
-// newFiles/unchanged까지 전부 반환한다(읽기 전용 — 실제로 아무 파일도 쓰지 않는다).
+// changed뿐 아니라 newFiles/unchanged까지 전부 반환한다는 점이 listWorkflowConflicts(changed만
+// 반환)와 다르다(읽기 전용 — 실제로 아무 파일도 쓰지 않는다).
 export function planWorkflows(context, payloadRoot, targetRoot = ".") {
   const { types = [], paths = new Map(), includeNexus = false, includeSecretBackup = false, repoName = "", resolvers = {} } = context;
   const workflowsDir = join(targetRoot, PATHS.workflowsDir);

package/src/core/paths-resolve.js

@@ -10,7 +10,7 @@
 import { existsSync, readdirSync } from "node:fs";
 import { join } from "node:path";
 import { markerForType as baseMarkerForType, extraMarkers } from "./detect.js";
-import { normalizePath } from "../cli/args.js";
+import { normalizePath, CliError } from "../cli/args.js";
 
 // 취소(ESC/Ctrl+C)는 CANCEL 심볼 — ui를 import하지 않고 심볼 여부로만 판정 (core→ui 역참조 방지)
 const isCancel = (v) => typeof v === "symbol";
@@ -119,7 +119,7 @@ export function findTypePathCandidates(root, type) {
 //   ② 루트에 마커 존재 → "." 자동
 //   ③ existingPaths(version.yml 저장값)
 //   ④ 후보 스캔
-//   ⑤ 분기 — 비대화형: 기존값→후보1개→루트 폴백 / 대화형: 확인·선택·직접입력
+//   ⑤ 분기 — 비대화형: 기존값→후보1개→에러 / 대화형: 확인·선택·직접입력
 export async function resolveProjectPaths({
   root, types = [], paths = new Map(), existingPaths = new Map(),
   force = false, tty = true, io = {},
@@ -146,7 +146,11 @@ export async function resolveProjectPaths({
 
     // ① --paths 등으로 이미 지정됨 → 최우선 (.sh L1441~1446)
     if (result.get(t)) {
-      say(`  ${t} → ${result.get(t)} (--paths 지정)`);
+      const p = result.get(t);
+      if (!existsSync(join(root, p))) {
+        throw new CliError(`--paths로 지정한 경로가 존재하지 않습니다: '${t}=${p}'`);
+      }
+      say(`  ${t} → ${p} (--paths 지정)`);
       continue;
     }
 
@@ -165,7 +169,7 @@ export async function resolveProjectPaths({
     const candidates = findTypePathCandidates(root, t);
     let chosen = "";
 
-    // ── ⑤-a 비대화형 (--force 또는 TTY 없음, .sh L1476~1489) ──
+    // ── ⑤-a 비대화형 (--force 또는 TTY 없음, .sh L1476~1489 — M4: root 폴백 의도적 불포함) ──
     if (force || !tty) {
       if (existing) {
         chosen = existing;
@@ -173,9 +177,10 @@ export async function resolveProjectPaths({
       } else if (candidates.length === 1) {
         chosen = candidates[0];
         say(`  ${t} → ${chosen} (자동 감지)`);
+      } else if (candidates.length === 0) {
+        throw new CliError(`${t}: 프로젝트 경로를 찾지 못했습니다. --paths "${t}=경로"로 직접 지정하세요.`);
       } else {
-        chosen = ".";
-        say(`  ⚠️ ${t} → 후보 ${candidates.length}개로 자동 확정 불가, 루트(.)로 기록 (--paths "${t}=경로"로 지정 가능)`);
+        throw new CliError(`${t}: 경로 후보가 ${candidates.length}개로 모호합니다(${candidates.join(", ")}). --paths "${t}=경로"로 직접 지정하세요.`);
       }
       result.set(t, chosen);
       continue;

package/src/core/version-yml.js

@@ -1,7 +1,35 @@
+import { escapeYamlDoubleQuoted } from "./wizard-env.js";
+
 // version.yml 파싱·생성 (.sh create_version_yml 등가, 전체 재생성 전략 D4).
 // ⚠️ YAML 재직렬화 금지 — 주석이 데이터.
 // 레이아웃 단일 진실 = payload/version.yml.template (호출부가 templateText로 주입).
 
+// version.yml.template이 아는 최상위 키 — 이 밖의 최상위 키는 사용자가 직접 추가한 것으로 간주한다.
+const KNOWN_TOP_LEVEL_KEYS = new Set([
+  "version", "version_code", "project_types", "project_type", "project_paths", "metadata", "deploy",
+]);
+
+// 최상위 레벨의 알려지지 않은 필드(사용자가 직접 추가한 임의 필드)를 원본 그대로 보존한다
+// (issue #20 M8). 각 알려지지 않은 최상위 키부터 다음 최상위 키 직전까지를 통째로 한 블록으로
+// 캡처한다(중첩 구조가 있어도 유효한 YAML로 남기기 위함). metadata/project_paths/deploy처럼
+// 이 모듈이 이미 아는 블록 "내부"의 알려지지 않은 하위 키는 대상이 아니다(범위 밖 — issue #20 결정).
+export function parseExtraTopLevel(content) {
+  const blocks = [];
+  let current = null;
+  for (const line of String(content || "").split("\n")) {
+    // 최상위 키는 하이픈을 포함할 수 있다(YAML 관례) — issue #20 M8 리뷰에서 지적된 놓침 방지.
+    const m = line.match(/^([a-zA-Z_][a-zA-Z0-9_-]*):/);
+    if (m) {
+      if (current) blocks.push(current.join("\n"));
+      current = KNOWN_TOP_LEVEL_KEYS.has(m[1]) ? null : [line];
+      continue;
+    }
+    if (current) current.push(line);
+  }
+  if (current) blocks.push(current.join("\n"));
+  return blocks;
+}
+
 // metadata.template.options 상태머신 파싱 (.sh read_template_options L2361~2416 등가).
 // 반환: { nexus: bool|null, secretBackup: bool|null } — null=미기재.
 // 구 synology·coderabbit 키 등 다른 키는 어느 분기에도 안 걸려 자연히 무시된다(파싱 에러 없음).
@@ -92,7 +120,7 @@ export function parseExisting(content) {
   const options = parseTemplateOptions(text);
   // metadata.template.branches — main/develop/mode (업데이트 모드 재질문 생략용)
   const branches = parseTemplateBranches(text);
-  return { version, versionCode, types, paths, templateVersion, options, branches };
+  return { version, versionCode, types, paths, templateVersion, options, branches, extraTopLevel: parseExtraTopLevel(text) };
 }
 
 // metadata.template.branches 블록 파싱. 셋 다 있어야 유효 — 아니면 null.
@@ -120,7 +148,8 @@ export function parseTemplateBranches(content) {
 
 // version.yml 전체 생성 — payload/version.yml.template 렌더링.
 // opts: { templateText, version, types:[], primaryType?, paths:Map, pathMarkers?:Map,
-//         branch, branches?, versionCode, now, today, templateOptions?, deployValues? }
+//         branch, branches?, versionCode, now, today, templateOptions?, deployValues?,
+//         extraTopLevel?:string[] }  ← 기존 version.yml의 알려지지 않은 최상위 필드 보존 (issue #20 M8)
 //   templateText = payload/version.yml.template 원문 (readVersionYmlTemplate — 필수)
 //   now   = "YYYY-MM-DD HH:MM:SS" (UTC) — 결정성 위해 주입 / today = "YYYY-MM-DD"
 //   branches = { main, develop, mode } (resolveBranchConfig 결과. 없으면 branch 기반 기본값)
@@ -129,7 +158,7 @@ export function parseTemplateBranches(content) {
 export function buildVersionYml({
   templateText, version, types = [], primaryType, paths = new Map(), pathMarkers = new Map(),
   branch = "main", branches = null, versionCode = 1, now, today,
-  templateOptions = null, deployValues = new Map(),
+  templateOptions = null, deployValues = new Map(), extraTopLevel = [],
 }) {
   if (!templateText) throw new Error("version.yml.template 원문이 필요합니다 (payload/version.yml.template 누락?)");
   const typesJson = types.length ? `[${types.map((t) => `"${t}"`).join(", ")}]` : `["basic"]`;
@@ -159,7 +188,9 @@ export function buildVersionYml({
     const rows = ["", "deploy: # 마법사가 기억하는 배포 설정 (비민감 / 직접 수정 가능)"];
     for (const t of deployTypes) {
       rows.push(`  ${t}:`);
-      for (const [k, v] of deployValues.get(t)) rows.push(`    ${k}: "${v}"`);
+      // 동일한 이스케이프를 재사용 — deploy 값도 @wizard ask 값과 같은 경로로 들어오므로
+      // 큰따옴표가 섞이면 setEnvLine과 동일하게 YAML이 깨진다 (issue #20 L9, 두 번째 지점).
+      for (const [k, v] of deployValues.get(t)) rows.push(`    ${k}: "${escapeYamlDoubleQuoted(v)}"`);
     }
     deployBlock = rows.join("\n");
   }
@@ -185,6 +216,10 @@ export function buildVersionYml({
     }));
   }
   let text = out.join("\n");
+  if (extraTopLevel.length) {
+    if (!text.endsWith("\n")) text += "\n";
+    text += "\n" + extraTopLevel.join("\n\n");
+  }
   if (!text.endsWith("\n")) text += "\n";
   return text.replace(/\n{3,}$/, "\n"); // 말미 과잉 빈 줄 정리
 }

package/src/core/wizard-env.js

@@ -16,6 +16,14 @@ export function parseWizardLine(line) {
   return { indent: km[1], key: km[2], action: marker[1], arg: marker[2].trim() };
 }
 
+// YAML 큰따옴표 문자열 안에 안전하게 넣기 위한 이스케이프(백슬래시 우선 — 그래야 그 다음에 붙이는
+// 큰따옴표 이스케이프가 깨지지 않는다). @wizard 치환(setEnvLine)과 version.yml의 deploy 블록
+// (buildVersionYml, src/core/version-yml.js) 양쪽에서 재사용한다 — issue #20 L9는 두 지점 모두에서
+// 발생하는 동일한 버그다.
+export function escapeYamlDoubleQuoted(value) {
+  return String(value).replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+}
+
 // .sh _wf_set_env 등가: `KEY: "..."` 따옴표 안 값 치환 + 그 줄 끝 `# @wizard ...` 주석 제거.
 // 라인 하나에 대해 수행. value가 빈문자면 (.sh는 [ -n "$_val" ] 가드) 치환 스킵.
 export function setEnvLine(line, key, value) {
@@ -23,10 +31,11 @@ export function setEnvLine(line, key, value) {
   // CRLF 안전: 라인 끝 \r을 분리해 처리 후 복원 (autocrlf 프로젝트 대응)
   const cr = line.endsWith("\r") ? "\r" : "";
   const body = cr ? line.slice(0, -1) : line;
+  const escaped = escapeYamlDoubleQuoted(value);
   // 값 치환: KEY: "기존값" → KEY: "value"
   let out = body.replace(
     new RegExp(`^(\\s*${key}:\\s*")[^"]*(")`),
-    (_m, p1, p2) => `${p1}${value}${p2}`,
+    (_m, p1, p2) => `${p1}${escaped}${p2}`,
   );
   // 그 줄 끝 # @wizard ... 주석 제거 (앞 공백째)
   out = out.replace(/(\S)[^\S\r\n]*#[^\S\r\n]*@wizard[^\S\r\n].*$/, "$1");

package/src/index.js

@@ -93,9 +93,10 @@ export async function run(argv, {
 
   // revert 모드 — payload 유래 파일 제거 (감지·질문 불필요, --force 게이트만)
   if (opts.mode === "revert") {
+    // TTY 여부와 무관하게 --force가 없으면 거부한다 (issue #19 — TTY에서 확인 없이 즉시 실행되던 결함 수정).
     // --dry-run은 파일을 쓰지 않으므로 --force 게이트를 우회한다 (status/doctor와 동일한 안전성).
-    if (!opts.force && !opts.dryRun && !process.stdout.isTTY) {
-      console.error("비대화형 환경에서는 --force 옵션이 필요합니다.");
+    if (!opts.force && !opts.dryRun) {
+      console.error("revert 모드는 --force 없이 실행할 수 없습니다 (확인 절차가 없습니다).");
       return 1;
     }
     if (opts.dryRun) {
@@ -220,10 +221,11 @@ export async function run(argv, {
     printDoctorReport(runDoctor(cwd));
     return 0;
   }
-  // 명시 모드인데 --force 없으면 (비대화형 CLI는 --force 필요)
+  // 명시 모드(full/version/workflows)인데 --force 없으면 TTY 여부와 무관하게 즉시 거부한다
+  // (issue #19 — TTY에서 확인 없이 즉시 설치되던 결함 수정).
   // --dry-run은 파일을 쓰지 않으므로 --force 게이트를 우회한다 (status/doctor와 동일한 안전성).
-  if (!opts.force && !opts.dryRun && !process.stdout.isTTY) {
-    console.error("비대화형 환경에서는 --force 옵션이 필요합니다.");
+  if (!opts.force && !opts.dryRun) {
+    console.error("--force 없이는 이 모드를 실행할 수 없습니다 (확인 절차가 없습니다).");
     return 1;
   }
 
@@ -238,11 +240,17 @@ export async function run(argv, {
   const versionCode = existing?.versionCode ?? 1; // 기존 빌드번호 보존 (.sh L2208~2221)
   const branch = detectDefaultBranch(cwd);
   const repoName = detectRepoName(cwd);
-  // 경로 확정 (.sh resolve_project_paths 비대화형 경로 — --paths 우선 → 저장값 → 후보 1개 자동 → 루트 폴백)
-  const paths = await resolveProjectPaths({
-    root: cwd, types, paths: parsePathsCsv(opts.pathsCsv),
-    existingPaths: existing?.paths ?? new Map(), force: true, tty: false, io: {},
-  });
+  // 경로 확정 (.sh resolve_project_paths 비대화형 경로 — --paths 우선 → 저장값 → 후보 1개 자동 → 에러)
+  let paths;
+  try {
+    paths = await resolveProjectPaths({
+      root: cwd, types, paths: parsePathsCsv(opts.pathsCsv),
+      existingPaths: existing?.paths ?? new Map(), force: true, tty: false, io: {},
+    });
+  } catch (e) {
+    if (e instanceof CliError) { console.error(e.message); return 1; }
+    throw e;
+  }
 
   // 브랜치 구성 (--main-branch/--develop-branch → version.yml 저장값 → 감지 default → main/develop)
   const branches = resolveBranchConfig({
@@ -265,7 +273,7 @@ export async function run(argv, {
   const { now, today } = clock || utcNow();
 
   const context = createContext({
-    mode: opts.mode, force: true, types, version, versionCode, branch,
+    mode: opts.mode, force: opts.force, types, version, versionCode, branch,
     branches,
     paths,
     // 옵션 워크플로우: CLI 플래그 최우선 → version.yml 저장 옵션(.sh read_template_options 등가) → false
@@ -295,21 +303,20 @@ export async function run(argv, {
     return 0;
   }
 
+  // opts.mode는 parseArgs()에서 화이트리스트 검증을 통과했고, interactive/revert/purge/uninstall/status/doctor는
+  // 전부 위에서 조기 반환했으므로 이 시점엔 full/version/workflows 중 하나로 보장된다(issue #19 — default 분기 제거).
   let result = null;
   switch (opts.mode) {
     case "full": result = runFull(context, payload, cwd); break;
     case "version": result = runVersion(context, payload, cwd); break;
     case "workflows": result = runWorkflows(context, payload, cwd); break;
-    default:
-      // 알 수 없는 모드 → .sh와 동일하게 복사 0건, 에러 아님
-      break;
   }
 
   // 완료 요약 (.sh print_summary — CLI 모드에서도 출력)
   printSummary({
     mode: opts.mode, types, version, branches,
-    counters: { workflows: result?.workflows?.copied ?? 0 },
+    copiedFiles: result?.workflows?.copiedFiles ?? [],
     gitignoreUpdated: result?.gitignoreUpdated === true,
-  }, cwd);
+  });
   return 0;
 }

package/src/ui/prompts.js

@@ -89,7 +89,7 @@ export function banner(info) { _printBanner(info); }
 export function detectionLog(info) { _detLog(info); }
 export function analysisCard(info) { _card(info); }
 export function installKind(info) { _installKind(info); }
-export function summary(ctx, targetRoot) { _summary(ctx, targetRoot); }
+export function summary(ctx) { _summary(ctx); }
 
 // env 계획·경로 해석·충돌 메뉴가 쓰는 저수준 엔진 io (env-plan/paths-resolve의 io 계약)
 export const engineIo = {

package/src/ui/summary.js

@@ -1,21 +1,17 @@
 // 완료 요약 출력 (.sh print_summary 등가). 전부 stderr.
-// ctx: { mode, types:[], version, counters:{ workflows }, branches? }
-import { existsSync } from "node:fs";
-import { join } from "node:path";
-import { PATHS, WORKFLOW_PREFIX, WORKFLOW_COMMON_PREFIX } from "../core/paths.js";
-import { listYamlFiles } from "../core/fsutil.js";
+// ctx: { mode, types:[], version, copiedFiles:[], branches?, gitignoreUpdated? }
+import { WORKFLOW_PREFIX, WORKFLOW_COMMON_PREFIX } from "../core/paths.js";
 
 const SEPARATOR = "────────────────────────────────────────";
 
-export function printSummary(ctx, targetRoot = ".") {
-  const { mode, types = [], version = "", counters = {}, branches = null, gitignoreUpdated = false } = ctx || {};
+export function printSummary(ctx) {
+  const { mode, types = [], version = "", copiedFiles = [], branches = null, gitignoreUpdated = false } = ctx || {};
   const err = (s = "") => process.stderr.write(`${s}\n`);
   // 색상은 TTY일 때만 (.sh YELLOW/CYAN/NC 등가)
   const isTty = !!process.stderr.isTTY;
   const YELLOW = isTty ? "\x1b[1;33m" : "";
   const CYAN = isTty ? "\x1b[0;36m" : "";
   const NC = isTty ? "\x1b[0m" : "";
-  const workflowsCopied = counters.workflows ?? 0;
 
   err("");
   err(SEPARATOR);
@@ -66,24 +62,22 @@ export function printSummary(ctx, targetRoot = ".") {
   err("");
   err("추가된 워크플로우:");
 
-  // 실제 복사된 워크플로우 분류
+  // 실제로 이번 실행에서 복사된 파일만 분류한다 (copyWorkflows()가 반환한 copiedFiles —
+  // 디렉터리 재스캔은 재실행 시 skip된 파일까지 "새로 설치됨"으로 보여주는 결함이 있었다, issue #19).
   const commonWorkflows = [];
   const typeWorkflows = [];
-  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.startsWith(`${WORKFLOW_COMMON_PREFIX}-`)) {
-        commonWorkflows.push(filename);
-      } else if (typePrefixes.some((p) => filename.startsWith(p))) {
-        typeWorkflows.push(filename);
-      }
+  const typePrefixes = types.map((t) => `${WORKFLOW_PREFIX}-${t.toUpperCase()}-`);
+  for (const filename of copiedFiles) {
+    if (!filename.startsWith(`${WORKFLOW_PREFIX}-`)) continue; // PROJECT-*만
+    if (filename.startsWith(`${WORKFLOW_COMMON_PREFIX}-`)) {
+      commonWorkflows.push(filename);
+    } else if (typePrefixes.some((p) => filename.startsWith(p))) {
+      typeWorkflows.push(filename);
     }
   }
 
   if (commonWorkflows.length > 0 || typeWorkflows.length > 0) {
-    err(`  📦 새로 설치됨 (${workflowsCopied}개):`);
+    err(`  📦 새로 설치됨 (${commonWorkflows.length + typeWorkflows.length}개):`);
     for (const wf of commonWorkflows) err(`     📌 ${wf}`);
     for (const wf of typeWorkflows) err(`     🎯 ${wf}`);
   }