project-auto-wizard 0.1.14 → 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.13 (2026-08-04)
+## 최신 버전 : v0.1.14 (2026-08-04)
 
 [전체 버전 기록 보기](CHANGELOG.md)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "project-auto-wizard",
-  "version": "0.1.14",
+  "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

@@ -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,15 +75,35 @@ 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}`);
@@ -114,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/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/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/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

@@ -74,24 +74,21 @@ export function copyWorkflows(context, payloadRoot, targetRoot = ".", hooks = {}
   // 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(filename);
+      counters.copiedFiles.push(f);
     }
+    for (const f of changed.filter(notExcluded)) applyDecision(decisions.get(f), commonDir, workflowsDir, f, counters, srcText);
   }
 
   // (2~4) 타입별
@@ -144,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);
@@ -248,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

@@ -240,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({