projectops 4.36.4 → 4.37.0

package/src/core/options-schema.js

@@ -0,0 +1,145 @@
+// projectops 옵션 정본 (AI agent·사람·문서가 같은 표를 본다).
+//
+// 왜 필요한가: 옵션 설명이 문서 6곳(NPX-WIZARD, VERSION-CONTROL, ISSUE-AUTOMATION ...)에 흩어져 있어
+// agent가 "이 옵션이 있나, 기본값이 뭔가"를 확인하려면 문서를 뒤져야 했다. 이제 한 호출로 읽는다:
+//   npx projectops --mode options --json
+//
+// 이 표는 손으로 쓰되, test/options-schema.test.js 가 실제 코드와 대조한다.
+//   - args.js 의 모든 CLI 플래그가 flags 에 있어야 한다
+//   - parseTemplateOptions 가 읽는 모든 키가 versionYml 에 있어야 한다
+// 새 플래그·옵션을 추가하고 여기에 안 쓰면 테스트가 실패한다.
+//
+// 설명은 영문이다 — 기계가 읽는 표이고, 화면 언어(i18n)와 무관하게 같아야 한다.
+
+export const SCHEMA_VERSION = 1;
+
+export const MODES = [
+  { name: "interactive", description: "Default. Asks questions in the terminal. Do not use from an agent or CI." },
+  { name: "full", description: "Install everything: version.yml, workflows, scripts, templates, setup guide." },
+  { name: "version", description: "Only version.yml, README version section and version scripts." },
+  { name: "workflows", description: "Only GitHub Actions workflows (+ scripts, config, util). Existing version.yml is kept." },
+  { name: "issues", description: "Only issue and discussion templates." },
+  { name: "skills", description: "Install or update agent skills for supported IDEs." },
+  { name: "doctor", description: "Read-only diagnosis of the install and repository settings. Safe to run any time." },
+  { name: "options", description: "Print this option table (add --json for machine-readable output). Read-only, no network." },
+];
+
+// 프로젝트 타입은 context.js 의 VALID_TYPES 와 같아야 한다 (테스트가 대조).
+export const FLAGS = [
+  { flag: "--mode", alias: "-m", value: "MODE", values: MODES.map((m) => m.name), default: "interactive",
+    description: "What to do. Agents and CI should always pass an explicit non-interactive mode together with --force." },
+  { flag: "--type", alias: "-t", value: "CSV", default: "auto-detected",
+    description: "Project types, comma separated. The first one is the primary type.",
+    values: ["spring", "flutter", "react", "react-native", "react-native-expo", "node", "python", "basic"] },
+  { flag: "--project-version", value: "VERSION", default: "auto-detected",
+    description: "Initial version of the target project (x.y.z)." },
+  { flag: "--paths", value: "type=path,...", default: "repo root",
+    description: "Per-type project folders for monorepos, e.g. flutter=app,react=client.", versionYml: "project_paths" },
+  { flag: "--intent", value: "KIND", values: ["app", "library", "both", "none", "manual"], default: "inferred from --deploy/--publish",
+    description: "Project kind. Decides whether deploy and publish questions are asked.", versionYml: "metadata.template.options.intent" },
+  { flag: "--deploy", value: "TARGET", values: ["docker-ssh", "vercel", "none"], default: "docker-ssh",
+    description: "Where the app is deployed. Pick one.", versionYml: "metadata.template.options.deploy" },
+  { flag: "--publish", value: "CSV", values: ["nexus", "npm", "github-packages"], default: "none",
+    description: "Registries a library is published to. Several allowed.", versionYml: "metadata.template.options.publish" },
+  { flag: "--deploy-branch", value: "NAME", default: "develop",
+    description: "Development branch: the head of the release PR. Not the repository default branch.", versionYml: "metadata.deploy_branch" },
+  { flag: "--language", value: "LANG", values: ["en", "ko"], default: "en for new installs, ko for existing installs",
+    description: "Language of issue/PR templates and bot messages written into the repo.", versionYml: "metadata.template.options.language" },
+  { flag: "--label-style", value: "STYLE", values: ["en", "ko"], default: "en for new installs, ko for existing installs",
+    description: "Status label names: en = 'status: todo', ko = legacy Korean names.", versionYml: "metadata.template.options.label_style" },
+  { flag: "--secret-backup", negation: "--no-secret-backup",
+    description: "Include / exclude the workflow that uploads GitHub Secrets to a server over SSH.", default: "excluded",
+    versionYml: "metadata.template.options.secret_backup" },
+  { flag: "--ai-summary", negation: "--no-ai-summary",
+    description: "Include / exclude the workflow that comments an AI summary on work PRs.", default: "included",
+    versionYml: "metadata.template.options.code_review.ai_summary" },
+  { flag: "--projects-sync", negation: "--no-projects-sync",
+    description: "Include / exclude the GitHub Projects status sync workflow. Needs a PAT secret and PROJECT_URL variable.",
+    default: "excluded for new installs; kept if already installed", versionYml: "metadata.template.options.projects_sync" },
+  { flag: "--remove-legacy",
+    description: "Rename retired old-generation workflows to .bak. Without it they are only listed in the summary and in doctor.", default: "off" },
+  { flag: "--force", alias: "-y", aliases: ["-y", "--yes"], description: "Skip every confirmation and use non-interactive defaults. Required for agents and CI.", default: "off" },
+  { flag: "--lang", value: "LANG", values: ["en", "ko"], default: "system language; pinned to en in CI and with --force",
+    description: "Language of the CLI screen. Not the language written into the repo (that is --language)." },
+  { flag: "--json", description: "With --mode options: print machine-readable JSON instead of a table.", default: "off" },
+  { flag: "--version", alias: "-v", description: "Print the projectops package version and exit." },
+  { flag: "--help", alias: "-h", description: "Print the human-readable help and exit." },
+  // 지원 종료 예정 — 새 설정에는 쓰지 않는다
+  { flag: "--nexus", negation: "--no-nexus", deprecated: "Use --publish nexus. Also implies --deploy none." },
+  { flag: "--npm-publish", negation: "--no-npm-publish", deprecated: "Use --publish npm." },
+];
+
+// version.yml 의 키. path 는 파일 안의 위치, parserKey 는 parseTemplateOptions 가 돌려주는 이름.
+export const VERSION_YML = [
+  { path: "version", type: "string", description: "Project version (x.y.z). The single source of truth; workflows sync it into build files.", edit: "workflow-managed" },
+  { path: "version_code", type: "integer", description: "App build number. +1 on every release. Android release only; iOS and test builds use build_number.py.", edit: "workflow-managed" },
+  { path: "project_types", type: "string[]", description: "Project types; the first is primary. Do not change after setup.", edit: "wizard" },
+  { path: "project_paths", type: "map", description: "Per-type project folder relative to the repo root (monorepo).", edit: "wizard (--paths)" },
+  { path: "metadata.default_branch", type: "string", default: "main", description: "Repository default (production) branch. Pushes here deploy.", edit: "wizard" },
+  { path: "metadata.deploy_branch", parserKey: "deployBranch", type: "string", default: "develop",
+    description: "Development branch: head of the release PR. Despite the name it is NOT where deploys run.", edit: "wizard (--deploy-branch)" },
+  { path: "metadata.template.options.intent", parserKey: "intent", type: "enum", values: ["app", "library", "both", "none", "manual"],
+    description: "Project kind; derives the deploy and publish questions.", edit: "wizard (--intent)" },
+  { path: "metadata.template.options.deploy", parserKey: "deploy", type: "enum", values: ["docker-ssh", "vercel", "none"], default: "docker-ssh",
+    description: "Where the app is deployed.", edit: "wizard (--deploy)" },
+  { path: "metadata.template.options.publish", parserKey: "publish", type: "enum[]", values: ["nexus", "npm", "github-packages"], default: [],
+    description: "Library registries.", edit: "wizard (--publish)" },
+  { path: "metadata.template.options.secret_backup", parserKey: "secretBackup", type: "boolean", default: false,
+    description: "Secret-to-server upload workflow installed.", edit: "wizard (--secret-backup)" },
+  { path: "metadata.template.options.semver_auto", parserKey: "semverAuto", type: "boolean",
+    default: true,
+    description: "Decide the release bump from commit titles: 'type!:' = major, 'feat:' = minor, anything else = patch. Applies both to the release PR and to direct pushes to the default branch.",
+    edit: "by hand" },
+  { path: "metadata.template.options.close_on_release", parserKey: "closeOnRelease", type: "boolean", default: "true for new installs; missing for existing installs",
+    description: "A release merge closes issues that carry the done label and are referenced by a release commit.", edit: "by hand" },
+  { path: "metadata.template.options.language", parserKey: "language", type: "enum", values: ["en", "ko"], description: "Issue/PR template and bot message language.", edit: "wizard (--language)" },
+  { path: "metadata.template.options.label_style", parserKey: "labelStyle", type: "enum", values: ["en", "ko"], description: "Status label names.", edit: "wizard (--label-style)" },
+  { path: "metadata.template.options.projects_sync", parserKey: "projectsSync", type: "boolean", description: "Projects status sync workflow installed.", edit: "wizard (--projects-sync)" },
+  { path: "metadata.template.options.app_release", parserKey: "appRelease", type: "boolean",
+    description: "Releases go through App Store / Play Store review. Release notes get a review warning banner. Never auto-enabled.", edit: "by hand" },
+  { path: "metadata.template.options.excluded_workflows", parserKey: "excludedWorkflows", type: "string[]",
+    description: "Workflow file names the update must never install. Deleted files are also not restored; a copy is kept in .github/.projectops/incoming/.",
+    edit: "by hand" },
+  { path: "metadata.template.options.code_review.coderabbit", parserKey: "codeReviewCoderabbit", type: "boolean", description: "CodeRabbit config installed.", edit: "wizard" },
+  { path: "metadata.template.options.code_review.ai_summary", parserKey: "aiPrSummary", type: "boolean", default: true, description: "AI PR summary workflow installed.", edit: "wizard (--ai-summary)" },
+  { path: "metadata.template.options.changelog.provider", parserKey: "changelogProvider", type: "enum",
+    values: ["commit", "openai", "gemini", "claude", "groq", "mistral", "ollama", "copilot", "coderabbit"], default: "commit",
+    description: "Release note generator. 'commit' is free and always works; AI keys are picked up automatically when registered as secrets.", edit: "by hand" },
+  { path: "metadata.template.options.changelog.base_url", parserKey: "changelogBaseUrl", type: "string", description: "Only for provider ollama.", edit: "by hand" },
+];
+
+export function buildSchema(packageVersion = "") {
+  return {
+    tool: "projectops",
+    packageVersion,
+    schemaVersion: SCHEMA_VERSION,
+    usage: "npx projectops --mode <mode> [--type csv] [--force] ...   (agents: always pass --force and an explicit --mode)",
+    modes: MODES,
+    flags: FLAGS,
+    versionYml: VERSION_YML,
+    related: {
+      diagnose: "npx projectops --mode doctor",
+      optionsJson: "npx projectops --mode options --json",
+      docs: "https://cassiiopeia.github.io/projectops/",
+    },
+  };
+}
+
+// 사람이 읽는 표 — JSON 이 아닐 때 출력한다.
+export function renderText(schema) {
+  const lines = [`projectops ${schema.packageVersion} — options (schema v${schema.schemaVersion})`, "", schema.usage, "", "MODES"];
+  for (const m of schema.modes) lines.push(`  ${m.name.padEnd(12)} ${m.description}`);
+  lines.push("", "FLAGS");
+  for (const f of schema.flags) {
+    const name = [...(f.aliases ?? [f.alias]), f.flag + (f.value ? ` ${f.value}` : ""), f.negation].filter(Boolean).join(", ");
+    const desc = f.deprecated ? `(deprecated) ${f.deprecated}` : f.description;
+    const extra = [f.values ? `values: ${f.values.join("|")}` : "", f.default !== undefined ? `default: ${f.default}` : ""].filter(Boolean).join("; ");
+    lines.push(`  ${name}`, `      ${desc}${extra ? `  [${extra}]` : ""}`);
+  }
+  lines.push("", "VERSION.YML KEYS");
+  for (const k of schema.versionYml) {
+    const extra = [k.type, k.values ? k.values.join("|") : "", k.default !== undefined ? `default: ${JSON.stringify(k.default)}` : ""].filter(Boolean).join("; ");
+    lines.push(`  ${k.path}  [${extra}]`, `      ${k.description}`);
+  }
+  return lines.join("\n");
+}

package/src/core/version-yml.js

@@ -1,8 +1,9 @@
 // version.yml 파싱·생성 (.sh create_version_yml 등가, 전체 재생성 전략 D4).
 // ⚠️ YAML 재직렬화 금지 — 주석이 데이터. .sh heredoc과 바이트 동일한 템플릿 문자열.
 // 실측 기준: template_integrator.sh 2184~2354.
+import { execFileSync } from "node:child_process";
 
-const HEADER = `# ===================================================================
+const HEADER_EN = `# ===================================================================
 # Project version management file
 # ===================================================================
 #
@@ -45,6 +46,98 @@ const HEADER = `# ==============================================================
 # ===================================================================
 `;
 
+// 한국어 레포(options.language: ko)는 주석도 한국어로 쓴다 (#811).
+// 업데이트(--force 는 화면이 en 고정)마다 한국어 주석이 영문으로 바뀌어 version.yml diff 가 86줄이 됐다.
+const HEADER_KO = `# ===================================================================
+# 프로젝트 버전 관리 파일
+# ===================================================================
+#
+# 이 파일은 다양한 프로젝트 타입에서 버전 정보를 중앙 관리하기 위한 파일입니다.
+# GitHub Actions 워크플로우가 이 파일을 읽어 자동으로 버전을 관리합니다.
+#
+# 사용법:
+# 1. version: "1.0.0" - 사용자에게 표시되는 버전
+# 2. version_code: 1 - Play Store/App Store 빌드 번호 (1부터 자동 증가)
+# 3. project_types: 프로젝트 타입 배열 — 첫 항목이 primary
+# 4. project_paths: 타입별 프로젝트 폴더 (레포 루트 기준 상대경로, 모노레포용)
+#
+# 자동 버전 업데이트:
+# - version_code: 매 빌드마다 자동으로 1씩 증가 (아래 판정과 무관)
+# - 버전 승격 폭은 metadata.template.options.semver_auto 가 정합니다
+#   semver_auto: true  -> 릴리스 구간 커밋 제목으로 판정
+#                         "제목 : feat! : 내용" 또는 "feat!:" -> major (x+1.0.0)
+#                         "제목 : feat : 내용"  또는 "feat:"  -> minor (x.y+1.0)
+#                         그 외(fix/docs/chore/refactor/test) -> patch (x.y.z+1)
+#   키 없음 / false     -> 항상 patch +1
+# - 위 판정과 무관하게 version 값을 직접 수정해도 됩니다
+#
+# 프로젝트 타입별 동기화 파일:
+# - spring: build.gradle (version = "x.y.z")
+# - flutter: pubspec.yaml (version: x.y.z+i, buildNumber 포함)
+# - react/node: package.json ("version": "x.y.z")
+# - react-native: iOS Info.plist 또는 Android build.gradle
+# - react-native-expo: app.json (expo.version)
+# - python: pyproject.toml (version = "x.y.z")
+# - basic/기타: version.yml 파일만 사용
+#
+# 연관된 워크플로우:
+# - .github/workflows/PROJECT-VERSION-CONTROL.yaml
+# - .github/workflows/PROJECT-README-VERSION-UPDATE.yaml
+# - .github/workflows/PROJECT-RELEASE-CHANGELOG.yaml
+#
+# 주의사항:
+# - project_types는 최초 설정 후 변경하지 마세요
+# - 버전은 항상 높은 버전으로 자동 동기화됩니다
+# ===================================================================
+`;
+
+// 키 옆 한 줄 주석. 언어는 화면 언어가 아니라 레포 문구 언어(options.language)를 따른다.
+const COMMENTS = {
+  en: {
+    versionCode: "app build number",
+    projectTypes: "array of types, first entry is primary, safe to edit by hand",
+    projectPaths: "project folder per type (relative to the repo root)",
+    mode: "install scope (full/version/workflows), used when re-running update mode",
+    intent: "project kind (app/library/both/none/manual), drives the deploy questions",
+    semverAuto: "decide the version bump from commit titles (false means always patch)",
+    projectsSync: "include the GitHub Projects status sync workflow",
+    closeOnRelease: "close issues labelled done when a release is merged (false or missing means do not close)",
+    language: "issue/PR template language (en | ko)",
+    labelStyle: "status label style (en: status: todo / ko: Korean names)",
+    appRelease: "whether releases go through App Store / Play Store review",
+    deploy: "deploy settings remembered by the wizard (non-sensitive, safe to edit by hand)",
+    excluded: "workflow files the update must never install (safe to edit by hand)",
+  },
+  ko: {
+    versionCode: "app build number",
+    projectTypes: "멀티타입 배열 — 첫 항목이 primary, 직접 편집 가능",
+    projectPaths: "타입별 프로젝트 폴더 (레포 루트 기준 상대경로)",
+    mode: "통합 범위(full/version/workflows) — 업데이트 모드 재실행 기준",
+    intent: "프로젝트 성격(app/library/both/none/manual) — 배포 질문 유도 기준",
+    semverAuto: "커밋 제목으로 버전 승격 폭 결정 (false면 항상 patch)",
+    projectsSync: "GitHub Projects 상태 동기화 워크플로우 포함 여부",
+    closeOnRelease: "릴리스 머지 때 완료 라벨 이슈를 닫는다 (false/미기재면 닫지 않음)",
+    language: "이슈/PR 템플릿 언어 (en | ko)",
+    labelStyle: "상태 라벨 표기 (en: status: todo / ko: 작업전)",
+    appRelease: "앱스토어·플레이스토어 심사로 이어지는 배포인가",
+    deploy: "마법사가 기억하는 배포 설정 (비민감 / 직접 수정 가능)",
+    excluded: "업데이트가 절대 설치하지 않을 워크플로우 파일 (직접 수정 가능)",
+  },
+};
+const commentsFor = (lang) => COMMENTS[lang === "ko" ? "ko" : "en"];
+
+// last_updated_by 결정 (#811): 실행한 git 사용자 → 기존 값 → template_integrator.
+// 예전엔 업데이트마다 "template_integrator"로 덮어써 누가 바꿨는지가 사라졌다.
+export function resolveUpdatedBy(existingContent = "", cwd = ".") {
+  try {
+    const name = execFileSync("git", ["config", "user.name"],
+      { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+    if (name) return name;
+  } catch { /* git 없음·설정 없음(CI) — 기존 값으로 */ }
+  const m = String(existingContent || "").match(/^\s+last_updated_by:\s*"([^"]*)"/m);
+  return m && m[1] ? m[1] : "template_integrator";
+}
+
 // metadata.template.options 상태머신 파싱 (.sh read_template_options L2361~2416 등가).
 // 반환(#439 배포/publish 축): { deploy: string|null, publish: string[]|null, secretBackup: bool|null }
 //   deploy: 'docker-ssh'|'vercel'|'none', publish: ['nexus','npm','github-packages'] 부분집합. null=미기재.
@@ -57,7 +150,7 @@ const HEADER = `# ==============================================================
 export function parseTemplateOptions(content) {
   const out = { deploy: null, publish: null, secretBackup: null,
                 changelogProvider: null, changelogBaseUrl: null, codeReviewCoderabbit: null, aiPrSummary: null, projectsSync: null,
-                deployBranch: null, intent: null, semverAuto: null, appRelease: null, labelStyle: null, closeOnRelease: null, language: null };
+                deployBranch: null, intent: null, semverAuto: null, appRelease: null, labelStyle: null, closeOnRelease: null, language: null, excludedWorkflows: null };
   // deploy_branch는 metadata 직속(#456) — template.options 밖이라 별도로 스캔한다.
   for (const line of String(content || "").split("\n")) {
     if (line.startsWith("#")) continue;
@@ -159,6 +252,12 @@ export function parseTemplateOptions(content) {
         out.closeOnRelease = m[1] === "true";
         continue;
       }
+      // 설치하지 않을 워크플로우 (#810) — 인라인 배열. 업데이트가 지운 파일을 되살리지 않게 하는 명시 수단이다.
+      m = line.match(/^\s+excluded_workflows:\s*\[([^\]]*)\]/);
+      if (m) {
+        out.excludedWorkflows = m[1].split(",").map((s) => s.trim().replace(/^["']|["']$/g, "")).filter(Boolean);
+        continue;
+      }
       // 프로젝트 성격(#553) — 앱 심사로 이어지는 레포인가. 워크플로우와 스킬이 같은 값을 본다.
       m = line.match(/^\s+app_release:\s*["']?(true|false)["']?/);
       if (m) {
@@ -329,17 +428,19 @@ export function mergeDeployValues(existingContent, fresh) {
 //   today = "YYYY-MM-DD" (UTC)
 //   pathMarkers = Map<type, markerFilename> (project_paths 주석용)
 //   templateOptions = { templateVersion, deployTarget, publishTargets, includeSecretBackup, optionsDate } (template 블록)
-export function buildVersionYml({ version, types = [], paths = new Map(), pathMarkers = new Map(), branch = "main", deployBranch = "", versionCode = 1, now, today, templateOptions = null, deployValues = new Map() }) {
+export function buildVersionYml({ version, types = [], paths = new Map(), pathMarkers = new Map(), branch = "main", deployBranch = "", versionCode = 1, now, today, templateOptions = null, deployValues = new Map(), updatedBy = "template_integrator" }) {
+  const lang = templateOptions?.language === "ko" ? "ko" : "en";
+  const C = commentsFor(lang);
   const typesJson = types.length ? `[${types.map((t) => `"${t}"`).join(",")}]` : `["basic"]`;
 
-  let out = HEADER + "\n";
+  let out = (lang === "ko" ? HEADER_KO : HEADER_EN) + "\n";
   out += `version: "${version}"\n`;
-  out += `version_code: ${versionCode}  # app build number\n`;
-  out += `project_types: ${typesJson}   # array of types, first entry is primary, safe to edit by hand\n`;
+  out += `version_code: ${versionCode}  # ${C.versionCode}\n`;
+  out += `project_types: ${typesJson}   # ${C.projectTypes}\n`;
 
   // project_paths 블록. pathMarkers: Map<type, markerFilename> (있으면 "  type: "path"   # path/marker" 주석).
   if (paths.size) {
-    out += `project_paths:                # project folder per type (relative to the repo root)\n`;
+    out += `project_paths:                # ${C.projectPaths}\n`;
     for (const [t, p] of paths) {
       const marker = pathMarkers.get(t) || "";
       const pf = p === "." ? marker : (marker ? `${p}/${marker}` : p);
@@ -349,7 +450,7 @@ export function buildVersionYml({ version, types = [], paths = new Map(), pathMa
 
   out += `metadata:\n`;
   out += `  last_updated: "${now}"\n`;
-  out += `  last_updated_by: "template_integrator"\n`;
+  out += `  last_updated_by: "${String(updatedBy || "template_integrator").replace(/"/g, "")}"\n`;
   out += `  default_branch: "${branch}"\n`;
   // deploy_branch: 릴리스 PR의 head 브랜치(#456). default_branch(레포 기본)와 별개 개념.
   // 지정된 경우에만 출력 — 미지정이면 스킬이 develop로 폴백(하위호환).
@@ -361,7 +462,7 @@ export function buildVersionYml({ version, types = [], paths = new Map(), pathMa
   if (templateOptions) {
     const { templateVersion = "unknown", deployTarget = "docker-ssh", publishTargets = [], includeSecretBackup = false, optionsDate = today,
             changelogProvider = "commit", changelogBaseUrl = "", codeReviewCoderabbit = true, aiPrSummary = true, intent = null, mode = null,
-            semverAuto = true, appRelease = null, labelStyle = null, closeOnRelease = null, projectsSync = null, language = null } = templateOptions;
+            semverAuto = true, appRelease = null, labelStyle = null, closeOnRelease = null, projectsSync = null, language = null, excludedWorkflows = null } = templateOptions;
     const publishJson = `[${publishTargets.map((t) => `"${t}"`).join(",")}]`;
     // intent(프로젝트 성격, #485) — 미지정이면 deploy/publish에서 역추론해 기록 (재통합 시 진입 질문 생략용)
     const intentVal = intent || inferIntent(deployTarget, publishTargets) || "manual";
@@ -369,27 +470,29 @@ export function buildVersionYml({ version, types = [], paths = new Map(), pathMa
     out += `    source: "projectops"\n`;
     out += `    version: "${templateVersion}"\n`;
     // mode(#502) — 이 레포에 통합된 범위. 업데이트 모드가 같은 범위를 재실행하는 기준.
-    if (mode) out += `    mode: "${mode}"   # install scope (full/version/workflows), used when re-running update mode\n`;
+    if (mode) out += `    mode: "${mode}"   # ${C.mode}\n`;
     out += `    integrated_date: "${optionsDate}"\n`;
     out += `    last_update_date: "${optionsDate}"\n`;
     out += `    options:\n`;
-    out += `      intent: "${intentVal}"   # project kind (app/library/both/none/manual), drives the deploy questions\n`;
+    out += `      intent: "${intentVal}"   # ${C.intent}\n`;
     out += `      deploy: "${deployTarget}"\n`;
     out += `      publish: ${publishJson}\n`;
     out += `      secret_backup: ${includeSecretBackup}\n`;
     // semver 자동 승격(#546) — 릴리스 시 커밋 제목으로 major/minor/patch 결정. false면 항상 patch.
-    out += `      semver_auto: ${semverAuto}   # decide the version bump from commit titles (false means always patch)\n`;
+    out += `      semver_auto: ${semverAuto}   # ${C.semverAuto}\n`;
     // Projects 보드 동기화(#716) — 미지정이면 키를 쓰지 않는다.
-    if (projectsSync !== null) out += `      projects_sync: ${projectsSync}   # GitHub Projects 상태 동기화 워크플로우 포함 여부\n`;
+    if (projectsSync !== null) out += `      projects_sync: ${projectsSync}   # ${C.projectsSync}\n`;
     // 릴리스 시 완료 이슈 닫기(#771) — 미지정이면 키를 쓰지 않는다(기존 레포는 현행 유지).
-    if (closeOnRelease !== null) out += `      close_on_release: ${closeOnRelease}   # close issues labelled done when a release is merged (false or missing means do not close)\n`;
+    if (closeOnRelease !== null) out += `      close_on_release: ${closeOnRelease}   # ${C.closeOnRelease}\n`;
     // 상태 라벨 표기(#776) — 미지정이면 키를 쓰지 않는다(기존 레포 무변화).
     // 레포 문구 언어(#769) — 미지정이면 키를 쓰지 않는다(기존 레포 무변화).
-    if (language) out += `      language: ${language}   # issue/PR template language (en | ko)\n`;
-    if (labelStyle) out += `      label_style: ${labelStyle}   # status label style (en: status: todo / ko: Korean names)\n`;
+    // 설치 제외 목록(#810) — 전체 재생성이라 다시 쓰지 않으면 사용자가 적은 목록이 사라진다.
+    if (excludedWorkflows && excludedWorkflows.length) out += `      excluded_workflows: [${excludedWorkflows.map((f) => `"${f}"`).join(", ")}]   # ${C.excluded}\n`;
+    if (language) out += `      language: ${language}   # ${C.language}\n`;
+    if (labelStyle) out += `      label_style: ${labelStyle}   # ${C.labelStyle}\n`;
     // 앱 심사 배포 레포 여부(#553) — 미지정이면 키를 쓰지 않는다(기존 레포 무변화).
     if (appRelease !== null) {
-      out += `      app_release: ${appRelease}   # whether releases go through App Store / Play Store review\n`;
+      out += `      app_release: ${appRelease}   # ${C.appRelease}\n`;
     }
     out += `      code_review:\n`;
     out += `        coderabbit: ${codeReviewCoderabbit}\n`;
@@ -405,7 +508,7 @@ export function buildVersionYml({ version, types = [], paths = new Map(), pathMa
   const deployTypes = [...deployValues.keys()].filter((t) => deployValues.get(t) && deployValues.get(t).size > 0);
   if (deployTypes.length) {
     out += `\n`;
-    out += `deploy:                          # deploy settings remembered by the wizard (non-sensitive, safe to edit by hand)\n`;
+    out += `deploy:                          # ${C.deploy}\n`;
     for (const t of deployTypes) {
       out += `  ${t}:\n`;
       for (const [k, v] of deployValues.get(t)) out += `    ${k}: "${v}"\n`;

package/src/core/wizard-env.js

@@ -47,6 +47,13 @@ export function extractEnvValues(installedContent) {
   return values;
 }
 
+// 예시용 기본값 (#810) — 그대로 배포되면 남의 도메인으로 요청이 간다.
+// 사용자가 값을 고르지 않은 경로(--force·기본값 사용)에서는 채우지 않고 __KEY__ 를 남긴다.
+// 그러면 설치 후 검증(verify.js)이 미치환으로 잡아 완료 화면에 "직접 채울 것"으로 보여준다.
+export function isPlaceholderDefault(value) {
+  return /(^|\.)example\.(com|org|net)$/i.test(String(value || "").trim());
+}
+
 // resolver — .sh resolve_token 등가. 값 계산은 주입된 resolvers로 위임(순수성 유지).
 // resolvers: { repo, "spring-app-yml-dir"(type), "spring-app-yml-path"(type), "flutter-root" }
 export function resolveToken(name, type, resolvers = {}) {
@@ -89,6 +96,7 @@ export function substituteEnv(content, opts = {}) {
       let def = p.arg.startsWith("@") ? resolveToken(p.arg.slice(1), type, resolvers) : p.arg;
       const chosen = values.get(p.key);
       if (chosen != null && chosen !== "" && !useDefaults) val = chosen;
+      else if (isPlaceholderDefault(def)) continue; // 예시값은 쓰지 않는다 — 토큰·마커 그대로 (#810)
       else val = def;
       // ask 키만 수집 (.sh wf_deploy_set — auto는 저장 안 함). deploy 블록용.
       // #489 — 파일 본문은 아래 전역 토큰 치환을 거치므로 수집값도 동일 치환해

package/src/i18n/doctor.en.js

@@ -40,6 +40,10 @@ export default {
   "doctor.pd.l1": "These run other workflows but permissions has no 'actions: write'.",
   "doctor.pd.l2": "Even if the repository setting is Read and write, the API returns 403 without this declaration.",
   "doctor.pd.l3": "Fix: add 'actions: write' to the permissions block of each file",
+  "doctor.legacy.name": "Retired workflows",
+  "doctor.legacy.purpose": "Old-generation files that run next to their replacements",
+  "doctor.legacy.l1": "They react to the same events as the new workflows, so every run happens twice. Delete them:",
+  "doctor.legacy.l2": "Or run `npx projectops --mode workflows --force --remove-legacy` to rename them to .bak.",
   "doctor.bl.name": "Update baseline",
   "doctor.bl.purpose": "Basis for telling your edits apart on the next update",
   "doctor.bl.recorded": "{n} files recorded",

package/src/i18n/doctor.ko.js

@@ -40,6 +40,10 @@ export default {
   "doctor.pd.l1": "다른 워크플로우를 실행하는데 permissions에 'actions: write'가 없습니다.",
   "doctor.pd.l2": "저장소 설정이 Read and write여도 이 선언이 없으면 API가 403을 반환합니다.",
   "doctor.pd.l3": "조치: 해당 파일의 permissions 블록에 'actions: write' 추가",
+  "doctor.legacy.name": "은퇴한 워크플로우",
+  "doctor.legacy.purpose": "신형과 함께 실행되는 구세대 파일",
+  "doctor.legacy.l1": "신형과 같은 이벤트에 반응해 모든 실행이 두 번 일어납니다. 지우려면:",
+  "doctor.legacy.l2": "또는 `npx projectops --mode workflows --force --remove-legacy` 로 .bak 으로 치웁니다.",
   "doctor.bl.name": "업데이트 기준점",
   "doctor.bl.purpose": "다음 업데이트가 내 수정을 구분할 근거",
   "doctor.bl.recorded": "{n}개 파일 기록됨",

package/src/i18n/migrate.en.js

@@ -58,6 +58,9 @@ export default {
   "migrate.confirm.found": "Found {n} old-generation deploy workflow(s). They may be live deployments, so they are left untouched:",
   "migrate.confirm.newer": " (new: {name})",
   "migrate.confirm.hint": "   Delete the old files yourself once you have switched to the new workflows.",
+  "migrate.confirm.hintForce": "   Delete the old files yourself once you have switched, or rerun with --remove-legacy to rename them to .bak.",
+  "migrate.confirm.ask": "Rename these {n} old workflow(s) to .bak so they stop running? (restore by removing .bak)",
+  "migrate.confirm.done": "✅ Renamed {n} old workflow(s) to .bak.",
   "breaking.title": "BREAKING CHANGES (v{current} -> v{target}) - CRITICAL {critical}, WARNING {warnings}",
   "breaking.askDetail": "Show the details (action steps) for each item?",
   "breaking.seeJson": "  Details and action steps: see .github/config/breaking-changes.json",

package/src/i18n/migrate.ko.js

@@ -58,6 +58,9 @@ export default {
   "migrate.confirm.found": "⚠️ 구세대 배포 워크플로우 {n}개 발견 — 현역 배포일 수 있어 자동으로 건드리지 않습니다:",
   "migrate.confirm.newer": " (신형: {name})",
   "migrate.confirm.hint": "   신형 워크플로우로 전환을 마친 뒤 구 파일을 직접 삭제하세요.",
+  "migrate.confirm.hintForce": "   전환을 마친 뒤 구 파일을 직접 삭제하거나, --remove-legacy 로 다시 실행하면 .bak 으로 치웁니다.",
+  "migrate.confirm.ask": "구세대 워크플로우 {n}개를 .bak 으로 바꿔 실행을 멈출까요? (.bak 을 지우면 복원)",
+  "migrate.confirm.done": "✅ 구세대 워크플로우 {n}개를 .bak 으로 바꿨습니다.",
   "breaking.title": "⚠️  BREAKING CHANGES (v{current} -> v{target}) - CRITICAL {critical}건, WARNING {warnings}건",
   "breaking.askDetail": "각 항목의 상세 내용(조치 방법)을 볼까요?",
   "breaking.seeJson": "  상세 내용, 조치 방법: .github/config/breaking-changes.json 참고",

package/src/i18n/summary.en.js

@@ -23,6 +23,16 @@ export default {
   "done.keptHint1": "Copies of the new templates are in .github/.projectops/incoming/ (not tracked by git).",
   "done.keptHint2": "Move only the changes you want into your workflows.",
   "done.replacedTitle": "Could not tell whether {count} workflows were modified, so they were replaced with the new template and the originals saved as .bak",
+  "done.semverTitle": "Automatic version bump (semver_auto) is now ON for this repo",
+  "done.semverBody": "The next release picks the bump from commit titles: 'feat:' raises the minor version, 'type!:' the major one, anything else the patch.",
+  "done.semverOff": "To keep patch-only bumps, set metadata.template.options.semver_auto: false in version.yml.",
+  "done.notInstalledTitle": "{count} template workflow(s) were not installed",
+  "done.notInstalled.excluded": "listed in excluded_workflows",
+  "done.notInstalled.deleted-by-user": "you deleted it earlier",
+  "done.notInstalled.no-dev-branch": "only runs on {branch}, which this repo does not have",
+  "done.notInstalledHint": "To install one anyway, copy the file shown above. To stop being told, add it to options.excluded_workflows in version.yml.",
+  "done.legacyTitle": "{count} retired workflow(s) are still installed and run alongside their replacements",
+  "done.legacyHint": "Delete them once the new workflow works, or rerun with --remove-legacy to rename them to .bak.",
   "done.replacedHint": "If you had edits, copy them over from the .bak files. (The update baseline is recorded by this run.)",
   "done.utilTitle": "Utility modules:",
   "done.spring.title": "Extra setup for Spring projects:",

package/src/i18n/summary.ko.js

@@ -23,6 +23,16 @@ export default {
   "done.keptHint1": "새 템플릿 사본은 저장소에 추적되지 않는 .github/.projectops/incoming/ 에 있습니다.",
   "done.keptHint2": "필요한 변경만 워크플로에 직접 옮겨 반영하세요.",
   "done.replacedTitle": "수정 여부를 확인할 수 없어 {count}개 워크플로를 새 템플릿으로 교체하고 원본을 .bak 으로 백업했습니다",
+  "done.semverTitle": "이 레포의 자동 버전 승격(semver_auto)이 켜졌습니다",
+  "done.semverBody": "다음 릴리스부터 커밋 제목으로 올리는 폭을 정합니다: 'feat:'는 minor, 'type!:'는 major, 그 외는 patch.",
+  "done.semverOff": "patch만 올리고 싶으면 version.yml 의 metadata.template.options.semver_auto: false 로 두세요.",
+  "done.notInstalledTitle": "템플릿 워크플로우 {count}개를 설치하지 않았습니다",
+  "done.notInstalled.excluded": "excluded_workflows 에 적혀 있음",
+  "done.notInstalled.deleted-by-user": "예전에 직접 지운 파일",
+  "done.notInstalled.no-dev-branch": "{branch} 브랜치에서만 실행되는데 이 레포에는 그 브랜치가 없음",
+  "done.notInstalledHint": "그래도 쓰려면 위에 적힌 파일을 복사하세요. 안내를 그만 보려면 version.yml 의 options.excluded_workflows 에 추가하세요.",
+  "done.legacyTitle": "은퇴한 구세대 워크플로우 {count}개가 남아 신형과 함께 실행됩니다",
+  "done.legacyHint": "신형이 동작하는 걸 확인한 뒤 지우거나, --remove-legacy 로 다시 실행하면 .bak 으로 치웁니다.",
   "done.replacedHint": "직접 수정한 내용이 있었다면 .bak 에서 옮겨 오세요. (업데이트 기준점은 이번 실행으로 새로 기록됩니다)",
   "done.utilTitle": "유틸리티 모듈:",
   "done.spring.title": "Spring 프로젝트 추가 설정:",

package/src/index.js

@@ -79,6 +79,14 @@ async function runCore(argv, { cwd = process.cwd(), source = { type: "git" }, cl
   if (opts.showVersion) { console.log(readPkgVersion()); return 0; }
   if (opts.help) { console.log(helpText()); return 0; }
 
+  // options 모드 — 옵션 정본 출력. AI agent 가 문서를 뒤지지 않고 한 번에 읽는다. 읽기 전용·네트워크 없음.
+  if (opts.mode === "options") {
+    const { buildSchema, renderText } = await import("./core/options-schema.js");
+    const schema = buildSchema(readPkgVersion());
+    console.log(opts.json ? JSON.stringify(schema, null, 2) : renderText(schema));
+    return 0;
+  }
+
   // doctor 모드 (#558) — 읽기 전용 진단. 템플릿을 내려받지 않으므로 네트워크 없이도 동작한다.
   if (opts.mode === "doctor") {
     const { runDoctor } = await import("./commands/doctor.js");
@@ -247,10 +255,12 @@ async function runCore(argv, { cwd = process.cwd(), source = { type: "git" }, cl
     codeReviewCoderabbit: existing?.options?.codeReviewCoderabbit ?? false,
     // semver 자동 승격(#546): 저장값 → (기존 통합 레포면 false / 신규면 true).
     // 이미 통합된 레포의 버전이 업데이트만으로 예고 없이 minor로 튀지 않게 하는 안전장치다.
-    semverAuto: existing?.options?.semverAuto ?? (existing ? false : true),
+    // 저장값(명시적 false 포함)은 존중하고, 키가 없으면 기존 레포도 켠다. 켜진 사실은 완료 화면이 알린다.
+    semverAuto: existing?.options?.semverAuto ?? true,
     // 앱 심사 배포 레포 여부(#553): 저장값만 보존한다. 마법사가 묻지 않으므로 새로 켜지 않는다
     // (사용자가 version.yml에 직접 쓰거나 스킬이 기록한 값을 그대로 유지).
     appRelease: existing?.options?.appRelease ?? null,
+    excludedWorkflows: existing?.options?.excludedWorkflows ?? null, // #810 저장값 보존
     // 상태 라벨 표기(#776): 플래그 > 저장값 > (신규 en / 기존 ko). 기존 레포의 라벨 이름은 업데이트만으로 바뀌지 않는다.
     // 릴리스 시 완료 이슈 닫기(#771): 저장값 보존, 없으면 신규만 true. 기존 레포는 키를 만들지 않아 현행 유지.
     closeOnRelease: existing?.options?.closeOnRelease ?? (existing ? null : true),
@@ -275,7 +285,7 @@ async function runCore(argv, { cwd = process.cwd(), source = { type: "git" }, cl
   });
   trace.event("resolve", "semver-auto", String(context.semverAuto), {
     reason: existing?.options?.semverAuto != null ? "stored value in version.yml kept"
-      : (existing ? "existing integrated repo, false to avoid unannounced version jumps"
+      : (existing ? "existing integrated repo without the key, turned on by default (announced in the summary)"
                   : "new integration, true"),
   });
   trace.event("resolve", "app-release", String(context.appRelease), {
@@ -313,7 +323,7 @@ async function runCore(argv, { cwd = process.cwd(), source = { type: "git" }, cl
 
     // 레거시 마이그레이션 (#470) — 워크플로우를 만지는 모드에서만. 비대화형은 safe 티어 자동 적용.
     if (recordArtifacts) {
-      migrationsResult = await trace.stepAsync("legacy-migrations", () => runMigrations({ targetRoot: cwd }));
+      migrationsResult = await trace.stepAsync("legacy-migrations", () => runMigrations({ targetRoot: cwd, removeLegacy: opts.removeLegacy === true }));
       for (const a of migrationsResult.applied ?? []) trace.event("legacy", a.action === "error" ? "error" : "neutralized", a.from ?? a.id ?? "", { to: a.to ?? "", id: a.id ?? "" });
       for (const e of migrationsResult.confirmPending ?? []) trace.event("legacy", "leftover-old-gen", e.file, { replacement: e.replacedBy ?? "", reason: e.reason ?? "" });
     }
@@ -352,7 +362,7 @@ async function runCore(argv, { cwd = process.cwd(), source = { type: "git" }, cl
       migrationGuidePath = appendGuideEntry(cwd, {
         now, mode: opts.mode, types, repoName,
         templateFrom: existing?.templateVersion || "", templateTo: context.templateVersion,
-        options: { deploy: deployTarget, publish: publishTargets, secretBackup: context.includeSecretBackup, coderabbit: context.codeReviewCoderabbit, changelogProvider: context.changelogProvider, intent, semverAuto: context.semverAuto , appRelease: context.appRelease, language: context.language, labelStyle: context.labelStyle, closeOnRelease: context.closeOnRelease, projectsSync: context.projectsSync },
+        options: { deploy: deployTarget, publish: publishTargets, secretBackup: context.includeSecretBackup, coderabbit: context.codeReviewCoderabbit, changelogProvider: context.changelogProvider, intent, semverAuto: context.semverAuto , appRelease: context.appRelease, language: context.language, labelStyle: context.labelStyle, closeOnRelease: context.closeOnRelease, projectsSync: context.projectsSync, excludedWorkflows: context.excludedWorkflows },
         branches: { defaultBranch: branch, deployBranch: context.deployBranch || "develop", ready: null, created: null },
         breaking: breakingReport, migrations: migrationsResult, orphans: { cleaned: [], pending: orphanPending },
         events: trace.events, counters: { skipped: result?.workflows?.skipped ?? 0 },
@@ -366,6 +376,9 @@ async function runCore(argv, { cwd = process.cwd(), source = { type: "git" }, cl
       counters: { workflows: result?.workflows?.copied ?? 0, workflowFiles: result?.workflows?.copiedFiles ?? [], utilModules: 0 },
       skippedConflicts: result?.workflows?.skippedConflicts ?? [],   // #654 병합 안내
       replacedBak: result?.workflows?.replacedBak ?? [],             // #673 기준점 없이 교체한 파일 안내
+      legacyLeftover: migrationsResult?.confirmPending ?? [],         // #809 신·구 세대 동시 실행 안내
+      notInstalled: result?.workflows?.notInstalled ?? [],            // #810 깔지 않은 워크플로우 안내
+      semverAutoNewlyOn: !!existing && existing?.options?.semverAuto == null && context.semverAuto === true, // 업데이트가 켠 사실 안내
       verification: result?.verification,   // #549 설치 후 검증 결과 (full/workflows 모드에서만 존재)
       // #569 — 고른 것만 안내하려면 선택값이 필요하다
       aiPrSummary: context.aiPrSummary, codeReviewCoderabbit: context.codeReviewCoderabbit,

package/src/ui/summary.js

@@ -120,6 +120,38 @@ export function printSummary(ctx, targetRoot = ".", write = null) {
     err(`     ${t("done.replacedHint")}`);
   }
 
+  // The update turned on automatic semver for a repo that did not have the key: tell them, because the next release can jump.
+  if (ctx?.semverAutoNewlyOn) {
+    err("");
+    err(`  ${YELLOW}⚠️  ${t("done.semverTitle")}${NC}`);
+    err(`     ${t("done.semverBody")}`);
+    err(`     ${t("done.semverOff")}`);
+  }
+
+  // Workflows left out on purpose (#810): deleted by the user, listed in excluded_workflows, or needing a branch this repo lacks.
+  const skippedNew = ctx?.notInstalled ?? [];
+  if (skippedNew.length > 0) {
+    err("");
+    err(`  ${CYAN}ℹ️  ${t("done.notInstalledTitle", { count: skippedNew.length })}${NC}`);
+    for (const s of skippedNew) {
+      err(`     ⏭️  ${s.filename}  (${t(`done.notInstalled.${s.reason}`, { branch: ctx?.deployBranch || "develop" })})`);
+      if (s.incoming) err(`        cp ${s.incoming} .github/workflows/${s.filename}`);
+    }
+    err(`     ${t("done.notInstalledHint")}`);
+  }
+
+  // Retired old-generation workflows still installed: they run next to their replacements (#809).
+  const legacy = ctx?.legacyLeftover ?? [];
+  if (legacy.length > 0) {
+    err("");
+    err(`  ${YELLOW}⚠️  ${t("done.legacyTitle", { count: legacy.length })}${NC}`);
+    for (const e of legacy) {
+      err(`     🗑️  ${e.file}${e.replacedBy ? `  →  ${e.replacedBy}` : ""}`);
+      err(`        git rm .github/workflows/${e.file}`);
+    }
+    err(`     ${t("done.legacyHint")}`);
+  }
+
   err("");
   err("  🔧 .github/scripts/");
   err("     ├─ version_manager.sh");