projectops 4.36.4 → 4.37.0

package/README.md

@@ -9,7 +9,7 @@
 **Status: actively maintained.** New versions ship often, sometimes several a day. To stay on a version you have tested, run `npx projectops@<version>` ([releases](https://github.com/Cassiiopeia/projectops/releases)).
 
 <!-- AUTO-VERSION-SECTION: DO NOT EDIT MANUALLY -->
-## Latest version : v4.36.3 (2026-10-07)
+## Latest version : v4.36.4 (2026-10-07)
 
 [View full version history](CHANGELOG.md)
 
@@ -178,7 +178,7 @@ flowchart TD
     K --> L["/pro-changelog-deploy<br/>Release PR + automerge"]
 ```
 
-> Full list of Skills and usage: **[docs/SKILLS.md](docs/SKILLS.md)** (Korean)
+> Full list of Skills and usage: **[docs/en/skills.md](docs/en/skills.md)**
 
 ### GitHub Actions pipeline
 
@@ -215,14 +215,14 @@ codex plugin marketplace add Cassiiopeia/projectops
 
 The `--mode skills` wizard registers the Codex marketplace and also prepares the native skills fallback. Use `/plugins` only to check or manage the install.
 
-Where the Codex plugin marketplace is unavailable, use the fallback install described in the [Skills guide](docs/SKILLS.md).
+Where the Codex plugin marketplace is unavailable, use the fallback install described in the [Skills guide](docs/en/skills.md).
 
 ```bash
 # Cursor / the full Agent Skills install menu (recommended: npx)
 npx projectops --mode skills
 ```
 
-> Claude Code prefers `/pro-` autocomplete, Gemini prefers its extension, and Codex prefers its plugin marketplace. See the [Skills guide](docs/SKILLS.md) for details.
+> Claude Code prefers `/pro-` autocomplete, Gemini prefers its extension, and Codex prefers its plugin marketplace. See the [Skills guide](docs/en/skills.md) for details.
 
 </details>
 
@@ -257,7 +257,7 @@ Run automation by commenting on an issue or PR.
 | `@projectops ios build` | Build iOS only | Flutter |
 | `@projectops create qa` | Create a QA issue automatically | All projects |
 
-> Details: [PR Preview](docs/PR-PREVIEW.md) | [Flutter builds](docs/FLUTTER-TEST-BUILD-TRIGGER.md) | [Issue automation](docs/ISSUE-AUTOMATION.md)
+> Details: [PR Preview](docs/en/pr-preview.md) | [Flutter builds](docs/FLUTTER-TEST-BUILD-TRIGGER.md) | [Issue automation](docs/en/issue-automation.md)
 
 ---
 
@@ -307,18 +307,18 @@ We would rather tell you up front when this is not a fit.
 
 ## Documentation
 
-Browse and search everything on the **[docs site](https://cassiiopeia.github.io/projectops/en/)**. Most guides are currently Korean only.
+Browse and search everything on the **[docs site](https://cassiiopeia.github.io/projectops/en/)**. The main guides are in English. A few wizard pages are still Korean only (translations are welcome, see [#799](https://github.com/Cassiiopeia/projectops/issues/799)).
 
 - [Getting started](https://cassiiopeia.github.io/projectops/en/getting-started)
 - [CLI reference](https://cassiiopeia.github.io/projectops/en/cli)
-- [Agent Skills guide (Korean)](https://cassiiopeia.github.io/projectops/SKILLS)
-- [Versioning (Korean)](https://cassiiopeia.github.io/projectops/VERSION-CONTROL)
-- [Changelog automation (Korean)](https://cassiiopeia.github.io/projectops/CHANGELOG-AUTOMATION)
-- [PR Preview (Korean)](https://cassiiopeia.github.io/projectops/PR-PREVIEW)
-- [Issue automation (Korean)](https://cassiiopeia.github.io/projectops/ISSUE-AUTOMATION)
-- [SSH + Docker deploy (Korean)](https://cassiiopeia.github.io/projectops/SSH-DOCKER-DEPLOYMENT-GUIDE)
-- [Flutter CI/CD (Korean)](https://cassiiopeia.github.io/projectops/FLUTTER-CICD-OVERVIEW)
-- [Troubleshooting (Korean)](https://cassiiopeia.github.io/projectops/TROUBLESHOOTING)
+- [Agent Skills guide](https://cassiiopeia.github.io/projectops/en/skills)
+- [Versioning](https://cassiiopeia.github.io/projectops/en/version-control)
+- [Changelog automation](https://cassiiopeia.github.io/projectops/en/changelog-automation)
+- [PR Preview](https://cassiiopeia.github.io/projectops/en/pr-preview)
+- [Issue automation](https://cassiiopeia.github.io/projectops/en/issue-automation)
+- [SSH + Docker deploy](https://cassiiopeia.github.io/projectops/en/ssh-docker-deployment-guide)
+- [Flutter CI/CD](https://cassiiopeia.github.io/projectops/en/flutter-cicd-overview)
+- [Troubleshooting](https://cassiiopeia.github.io/projectops/en/troubleshooting)
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "projectops",
-  "version": "4.36.4",
+  "version": "4.37.0",
   "description": "ProjectOps: installer CLI for a fully automated GitHub project management template (versioning, CI/CD, release notes, agent skills)",
   "keywords": [
     "devops",

package/src/cli/args.js

@@ -15,7 +15,7 @@ const SEMVER_RE = /^\d+\.\d+\.\d+$/;
 // 유니코드 글자·숫자 허용 (#719) — 공백·셸 메타문자는 문자 클래스에 없어 그대로 거부된다.
 const BRANCH_RE = /^[\p{L}\p{N}][\p{L}\p{N}._/-]*$/u;
 // 허용 실행 모드 (#665) — 오타가 조용히 "복사 0건 성공"으로 끝나지 않게 한다.
-export const MODE_VALUES = ["full", "version", "workflows", "issues", "skills", "doctor", "interactive"];
+export const MODE_VALUES = ["full", "version", "workflows", "issues", "skills", "doctor", "options", "interactive"];
 
 // argv(process.argv.slice(2)) → 파싱 결과. 오류 시 throw(호출부에서 exit 1).
 export function parseArgs(argv) {
@@ -33,6 +33,8 @@ export function parseArgs(argv) {
     includeSecretBackup: null,
     aiPrSummary: null,   // #566 — AI 변경 요약 워크플로우 포함 여부
     projectsSync: null,  // #716 — Projects 보드 동기화 워크플로우 포함 여부 (null=미지정)
+    json: false,         // --json: 기계가 읽는 출력 (--mode options)
+    removeLegacy: false, // #809 — 구세대 배포 워크플로우(confirm 티어)도 .bak 으로 치운다
     pathsCsv: "",            // "flutter=app,react=client" 원문 (정규화는 resolve 단계)
     force: false,
     lang: null,              // --lang en|ko (null = decided by src/i18n resolveLang)
@@ -170,6 +172,8 @@ export function parseArgs(argv) {
       case "--no-ai-summary": result.aiPrSummary = false; break;
       case "--projects-sync": result.projectsSync = true; break;
       case "--no-projects-sync": result.projectsSync = false; break;
+      case "--remove-legacy": result.removeLegacy = true; break;
+      case "--json": result.json = true; break;
       case "--npm-publish":
         process.stderr.write(t("args.npmPublishDeprecated") + "\n");
         result.publishTargets = [...new Set([...(result.publishTargets ?? []), "npm"])];

package/src/cli/help.js

@@ -7,8 +7,9 @@ Usage:
   npx projectops [options]
 
 Options:
-  -m, --mode MODE          Mode (full | version | workflows | issues | skills | doctor)
+  -m, --mode MODE          Mode (full | version | workflows | issues | skills | doctor | options)
                            doctor: diagnose the installation and repository settings (read-only)
+                           options: print every flag and version.yml key; add --json for agents
                            default: interactive
   -t, --type CSV           Project types, comma separated (e.g. spring,react,python)
                            supported: spring flutter react react-native
@@ -26,7 +27,9 @@ Options:
       --secret-backup / --no-secret-backup   Include / exclude the secret backup workflow
       --ai-summary / --no-ai-summary         Include / exclude the PR summary workflow
       --projects-sync / --no-projects-sync   Include / exclude the GitHub Projects status sync workflow (default: off for new installs)
+      --remove-legacy      Rename retired old-generation workflows to .bak (otherwise only listed)
       --nexus / --npm-publish  (deprecated: use --publish nexus / --publish npm)
+      --json               With --mode options: machine-readable output
       --force, -y, --yes   Skip every confirmation and use non-interactive defaults
       --lang en|ko         Display language (default: system language, pinned to en in CI and with --force)
   -v, --version            Print the projectops version
@@ -45,8 +48,9 @@ const HELP_KO = `projectops — GitHub 프로젝트 자동화 템플릿 통합 C
   npx projectops [옵션]
 
 옵션:
-  -m, --mode MODE          통합 모드 (full | version | workflows | issues | skills | doctor)
+  -m, --mode MODE          통합 모드 (full | version | workflows | issues | skills | doctor | options)
                            doctor: 통합 상태·저장소 설정 진단 (읽기 전용)
+                           options: 모든 플래그·version.yml 키 출력 (--json 이면 agent용 JSON)
                            기본: interactive (대화형)
   -t, --type CSV           프로젝트 타입 csv (예: spring,react,python)
                            지원: spring flutter react react-native
@@ -64,7 +68,9 @@ const HELP_KO = `projectops — GitHub 프로젝트 자동화 템플릿 통합 C
       --secret-backup / --no-secret-backup   Secret 백업 워크플로우 포함/제외
       --ai-summary / --no-ai-summary         PR 변경 요약 워크플로우 포함/제외
       --projects-sync / --no-projects-sync   GitHub Projects 상태 동기화 워크플로우 포함/제외 (신규 설치 기본 제외)
+      --remove-legacy      은퇴한 구세대 워크플로우를 .bak 으로 치움 (없으면 목록만 안내)
       --nexus / --npm-publish  (deprecated — --publish nexus / --publish npm 사용)
+      --json               --mode options 와 함께: 기계가 읽는 JSON 출력
       --force, -y, --yes   모든 확인 생략, 비대화형 기본값 사용
       --lang en|ko         화면 언어 (기본: 시스템 언어, CI/--force 는 en 고정)
   -v, --version            projectops 버전 출력

package/src/commands/doctor.js

@@ -19,6 +19,7 @@ import { parseExisting } from "../core/version-yml.js";
 import { verifyInstall } from "../core/verify.js";
 import { readBaseline } from "../core/baseline.js";
 import { detectRepoName } from "../core/detect-fs.js";
+import { detectMigrations } from "../core/migrations/index.js";
 import { t } from "../i18n/index.js";
 
 // 언어 전환(withLang 등) 시점에 평가되도록 함수로 둔다
@@ -149,6 +150,21 @@ export function localChecks(cwd = ".") {
     });
   }
 
+  // 은퇴한 구세대 워크플로우 (#809) — 업데이트는 감지만 하고 남겨 두므로 신형과 함께 돈다.
+  // 예전엔 로그에만 남아 doctor 가 "문제 없음"이라 했다.
+  const legacy = detectMigrations(cwd).confirm;
+  add({
+    name: t("doctor.legacy.name"), purpose: t("doctor.legacy.purpose"),
+    status: legacy.length ? "WARN" : "OK",
+    value: legacy.length ? t("doctor.count", { n: legacy.length }) : t("doctor.none"),
+    detail: legacy.length ? [
+      ...legacy.map((e) => `  ${e.file}${e.replacedBy ? `  →  ${e.replacedBy}` : ""}`),
+      t("doctor.legacy.l1"),
+      ...legacy.map((e) => `  git rm .github/workflows/${e.file}`),
+      t("doctor.legacy.l2"),
+    ] : null,
+  });
+
   const baseline = readBaseline(cwd);
   add({
     name: t("doctor.bl.name"), purpose: t("doctor.bl.purpose"),

package/src/commands/full.js

@@ -5,7 +5,8 @@ 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, mergeDeployValues } from "../core/version-yml.js";
+import { installAgentGuide } from "../core/agent-guide.js";
+import { buildVersionYml, mergeDeployValues, resolveUpdatedBy } from "../core/version-yml.js";
 import { markerForType } from "../core/detect.js";
 import { addVersionSectionToReadme } from "../core/copy/readme.js";
 import { copyWorkflows } from "../core/copy/workflows.js";
@@ -29,7 +30,7 @@ export function runFull(context, tempDir, targetRoot = ".", hooks = {}) {
     force = true, now, today, templateVersion = "unknown",
     deployTarget = "docker-ssh", publishTargets = [], includeSecretBackup = false, aiPrSummary = true,
     changelogProvider = "commit", changelogBaseUrl = "", codeReviewCoderabbit = true,
-    deployBranch = "", intent = null, semverAuto = true , appRelease = null, labelStyle = "en", closeOnRelease = null, projectsSync = null, language = "en" } = context;
+    deployBranch = "", intent = null, semverAuto = true , appRelease = null, labelStyle = "en", closeOnRelease = null, projectsSync = null, language = "en", excludedWorkflows = null } = context;
 
   // project_paths 마커 계산 (.sh existing_marker_in_dir 등가 — 대표 마커명)
   const pathMarkers = new Map();
@@ -50,8 +51,9 @@ export function runFull(context, tempDir, targetRoot = ".", hooks = {}) {
     buildVersionYml({
       version, types, paths, pathMarkers, branch, deployBranch, versionCode, now, today,
       deployValues,
+      updatedBy: resolveUpdatedBy(existsSync(vyFile) ? readFileSync(vyFile, "utf8") : "", targetRoot), // #811
       templateOptions: { templateVersion, deployTarget, publishTargets, includeSecretBackup, aiPrSummary, optionsDate: today,
-        changelogProvider, changelogBaseUrl, codeReviewCoderabbit, intent, mode: "full", semverAuto, appRelease, labelStyle, closeOnRelease, projectsSync, language },
+        changelogProvider, changelogBaseUrl, codeReviewCoderabbit, intent, mode: "full", semverAuto, appRelease, labelStyle, closeOnRelease, projectsSync, language, excludedWorkflows },
     })), { version, versionCode });
 
   // 2. README 버전 섹션
@@ -86,6 +88,7 @@ export function runFull(context, tempDir, targetRoot = ".", hooks = {}) {
     { enabled: codeReviewCoderabbit });
   step("ensure-gitignore", () => ensureGitignore(targetRoot));
   step("copy-setup-guide", () => copySetupGuide(tempDir, targetRoot));
+  step("install-agent-guide", () => installAgentGuide(targetRoot, templateVersion)); // agent 가 옵션을 확인하는 법 안내
 
   // 상태 라벨 표기(#776) — 템플릿 원본은 영문이라, 한글 레포는 복사가 끝난 뒤 이름만 되돌린다.
   step("apply-label-style", () => applyLabelStyle(targetRoot, labelStyle), { labelStyle });

package/src/commands/interactive.js

@@ -137,11 +137,13 @@ export async function runInteractive(baseCtx, { cwd = process.cwd(), source = {
     let deployBranchCreated = null; // #493 — 마법사가 직접 생성했는지 (가이드 기록용)
     let intent = existing?.options?.intent ?? null; // #485 프로젝트 성격
     // semver 자동 승격(#546) — 질문하지 않는다(#485 질문 부담 축소 방향 유지).
-    // 저장값이 있으면 보존, 없으면 신규 통합만 ON. 기존 레포는 업데이트만으로 버전이 튀지 않는다.
-    const semverAuto = existing?.options?.semverAuto ?? (existing ? false : true);
+    // 저장값(명시적 false 포함)은 보존하고, 키가 없으면 기존 레포도 ON. 켜진 사실은 완료 화면이 알린다.
+    const semverAuto = existing?.options?.semverAuto ?? true;
+    const semverAutoNewlyOn = !!existing && existing?.options?.semverAuto == null;
     const appRelease = existing?.options?.appRelease ?? null; // #553 저장값 보존 (묻지 않음)
     // 상태 라벨 표기(#776): 저장값 > (신규 en / 기존 ko). 기존 한글 레포에는 영문 전환을 한 번 제안한다(아래).
     const closeOnRelease = existing?.options?.closeOnRelease ?? (existing ? null : true); // #771 묻지 않는다
+    const excludedWorkflows = existing?.options?.excludedWorkflows ?? null; // #810 저장값 보존
     // Projects 보드 동기화(#716): 묻지 않는다. 저장값 > 이미 설치돼 있으면 유지 > 신규는 제외 (index.js 와 같은 규칙).
     const projectsSync = existing?.options?.projectsSync
       ?? existsSync(join(cwd, ".github/workflows/PROJECT-COMMON-PROJECTS-SYNC-MANAGER.yaml"));
@@ -328,7 +330,7 @@ export async function runInteractive(baseCtx, { cwd = process.cwd(), source = {
     const { now, today } = clock || utcNow();
     const ctx = createContext({
       mode, force: true, types, version, versionCode, branch, paths, deployTarget, publishTargets, includeSecretBackup,
-      codeReviewCoderabbit, changelogProvider, changelogBaseUrl, deployBranch, intent, semverAuto, appRelease, labelStyle, closeOnRelease, projectsSync, language,
+      codeReviewCoderabbit, changelogProvider, changelogBaseUrl, deployBranch, intent, semverAuto, appRelease, labelStyle, closeOnRelease, projectsSync, language, excludedWorkflows,
       repoName, templateVersion, resolvers, envValues, envUseDefaults, now, today,
       // #502 — version 모드가 기존 full 기록을 강등하지 않도록 (full이 우세)
       recordMode: existing?.templateMode === "full" ? "full" : "version",
@@ -423,7 +425,7 @@ export async function runInteractive(baseCtx, { cwd = process.cwd(), source = {
       migrationGuidePath = appendGuideEntry(cwd, {
         now, mode, types, repoName,
         templateFrom: existing?.templateVersion || "", templateTo: templateVersion,
-        options: { deploy: deployTarget, publish: publishTargets, secretBackup: includeSecretBackup, coderabbit: codeReviewCoderabbit, changelogProvider, intent, semverAuto , appRelease, labelStyle, closeOnRelease, projectsSync, language },
+        options: { deploy: deployTarget, publish: publishTargets, secretBackup: includeSecretBackup, coderabbit: codeReviewCoderabbit, changelogProvider, intent, semverAuto , appRelease, labelStyle, closeOnRelease, projectsSync, language, excludedWorkflows },
         branches: { defaultBranch: branch, deployBranch, ready: deployBranchReady, created: deployBranchCreated },
         breaking: breakingReport, migrations: migrationsResult, orphans: orphanReport,
         events: trace.events, counters: { skipped: result?.workflows?.skipped ?? 0 },
@@ -437,6 +439,9 @@ export async function runInteractive(baseCtx, { cwd = process.cwd(), source = {
       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,
       verification: result?.verification,      // #549 설치 검증 결과
       aiPrSummary, codeReviewCoderabbit,       // #569 — 고른 것만 안내
       logDir: files ? MIGRATION_DIR : null,    // #561 기록 위치 안내

package/src/commands/version.js

@@ -5,7 +5,8 @@ import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { writeText } from "../core/fsutil.js";
 import { PATHS } from "../core/paths.js";
-import { buildVersionYml, mergeDeployValues } from "../core/version-yml.js";
+import { installAgentGuide } from "../core/agent-guide.js";
+import { buildVersionYml, mergeDeployValues, resolveUpdatedBy } from "../core/version-yml.js";
 import { markerForType } from "../core/detect.js";
 import { addVersionSectionToReadme } from "../core/copy/readme.js";
 import { applyLabelStyle } from "../core/label-style.js";
@@ -16,7 +17,7 @@ export function runVersion(context, tempDir, targetRoot = ".") {
   const { version, types = [], paths = new Map(), branch = "main", versionCode = 1,
     now, today, templateVersion = "unknown", deployTarget = "docker-ssh", publishTargets = [], includeSecretBackup = false,
     changelogProvider = "commit", changelogBaseUrl = "", codeReviewCoderabbit = true,
-    deployBranch = "", recordMode = "version", semverAuto = true , appRelease = null, labelStyle = "en", closeOnRelease = null, projectsSync = null, language = null } = context;
+    deployBranch = "", recordMode = "version", semverAuto = true , appRelease = null, labelStyle = "en", closeOnRelease = null, projectsSync = null, language = null, excludedWorkflows = null } = context;
 
   const pathMarkers = new Map();
   for (const [t] of paths) pathMarkers.set(t, markerForType(t));
@@ -29,10 +30,11 @@ export function runVersion(context, tempDir, targetRoot = ".") {
     buildVersionYml({
       version, types, paths, pathMarkers, branch, deployBranch, versionCode, now, today,
       deployValues,
+      updatedBy: resolveUpdatedBy(existsSync(vyFile) ? readFileSync(vyFile, "utf8") : "", targetRoot), // #811
       // mode(#502): version 모드가 기존 full 통합 기록을 "version"으로 강등하지 않도록
       // 호출부가 recordMode로 기존 값을 넘긴다 (full이 우세 — 업데이트 재실행 범위 축소 방지).
       templateOptions: { templateVersion, deployTarget, publishTargets, includeSecretBackup, optionsDate: today,
-        changelogProvider, changelogBaseUrl, codeReviewCoderabbit, mode: recordMode, semverAuto, appRelease, labelStyle, closeOnRelease, projectsSync, language },
+        changelogProvider, changelogBaseUrl, codeReviewCoderabbit, mode: recordMode, semverAuto, appRelease, labelStyle, closeOnRelease, projectsSync, language, excludedWorkflows },
     }));
   addVersionSectionToReadme(version, targetRoot);
   copyScripts(tempDir, targetRoot);
@@ -40,4 +42,5 @@ export function runVersion(context, tempDir, targetRoot = ".") {
   applyLabelStyle(targetRoot, labelStyle); // #776
   ensureGitignore(targetRoot);
   copySetupGuide(tempDir, targetRoot);
+  installAgentGuide(targetRoot, templateVersion);
 }

package/src/commands/workflows.js

@@ -9,6 +9,7 @@ import { applyLabelStyle } from "../core/label-style.js";
 import { copyScripts, copyConfigFolder, copySetupGuide } from "../core/copy/simple.js";
 import { copyUtilModules } from "../core/copy/util.js";
 import { convertLegacySingularType, mergeDeployValues } from "../core/version-yml.js";
+import { installAgentGuide } from "../core/agent-guide.js";
 import { verifyInstall } from "../core/verify.js";
 
 export function runWorkflows(context, tempDir, targetRoot = ".", hooks = {}) {
@@ -35,6 +36,7 @@ export function runWorkflows(context, tempDir, targetRoot = ".", hooks = {}) {
   applyLabelStyle(targetRoot, labelStyle); // #776 — 워크플로우(QA 봇)와 라벨 정의를 같은 표기로 맞춘다
   for (const t of types) copyUtilModules(tempDir, t, { force }, targetRoot);
   copySetupGuide(tempDir, targetRoot);
+  installAgentGuide(targetRoot, context.templateVersion);
 
   // 설치 후 검증 (#549) — 워크플로우만 설치하는 모드라 오히려 더 필요하다.
   const verification = verifyInstall(targetRoot);

package/src/context.js

@@ -31,6 +31,7 @@ export function createContext(overrides = {}) {
     closeOnRelease: null,    // 릴리스 시 완료 이슈 닫기 (#771). null=미설정(신규 true / 기존 레포 키 없음)
     language: null,          // 레포 문구 언어 (#769). null=미설정(신규 en / 기존 레포 ko)
     labelStyle: null,        // 상태 라벨 표기 (#776). null=미설정(신규 en / 기존 레포 ko)
+    excludedWorkflows: null, // 설치하지 않을 워크플로우 파일명 (#810). null=없음
     appRelease: null,        // 앱 심사 배포 레포인가 (#553). null=미설정(키 기록 안 함)
     templateVersion: "",
     tempDir: "",

package/src/core/agent-guide.js

@@ -0,0 +1,44 @@
+// 사용자 레포에 설치하는 AI agent 안내문 (.github/.projectops/AGENT-GUIDE.md).
+//
+// 왜 파일인가: 이 레포의 AGENTS.md 는 템플릿 전용이라 사용자 프로젝트로 가지 않는다. 그래서 projectops 가
+// 깔린 레포에서 일하는 agent 는 "이 레포가 무엇으로 관리되는지, 옵션을 어디서 확인하는지"를 알 길이 없었다.
+// 레포 루트의 AGENTS.md·CLAUDE.md 는 사용자 것이라 건드리지 않고, 폴더 안에 두고 한 줄 포인터만 안내한다.
+//
+// 내용에 옵션 표를 박지 않는다 — 박으면 곧 낡는다. 표는 항상 `npx projectops --mode options --json` 이 정본이다.
+import { join } from "node:path";
+import { writeText } from "./fsutil.js";
+
+export const AGENT_GUIDE_PATH = ".github/.projectops/AGENT-GUIDE.md";
+
+export function agentGuideText(templateVersion = "") {
+  return `# projectops — guide for AI agents
+
+This repository is managed with [projectops](https://github.com/Cassiiopeia/projectops)${templateVersion ? ` (installed template ${templateVersion})` : ""}.
+GitHub Actions workflows in \`.github/workflows/PROJECT-*\` handle versioning, release notes, CI/CD and issue automation.
+This file is generated by the installer and overwritten on update. Do not edit it.
+
+## Ask the tool, do not guess
+
+\`\`\`bash
+npx projectops --mode options --json   # every CLI flag and every version.yml key, with allowed values and defaults
+npx projectops --mode doctor           # read-only diagnosis of this install and the repository settings
+\`\`\`
+
+Both are read-only and need no network.
+
+## Rules
+
+- Settings live in \`version.yml\` under \`metadata.template.options\`. The options table says which keys are safe to edit by hand.
+- \`version\` in \`version.yml\` is the single source of the project version. Workflows bump it on release; do not bump it by hand unless asked.
+- Commit titles decide the release bump when \`semver_auto\` is on: \`feat:\` = minor, \`feat!:\` = major, anything else = patch.
+- Running the installer again updates workflows. Files you changed are kept (a copy of the new version is saved in \`.github/.projectops/incoming/\`). Files you deleted are not restored.
+- To stop a template workflow from ever being installed, list its file name in \`options.excluded_workflows\`.
+- Run the installer from an agent or CI only with an explicit mode and \`--force\`, e.g. \`npx projectops --mode workflows --force\`. Without \`--force\` it asks questions and blocks.
+- Do not edit \`.github/.projectops/logs\`, \`baseline.json\` or \`incoming/\`. They are diagnostics for the next update.
+`;
+}
+
+export function installAgentGuide(targetRoot = ".", templateVersion = "") {
+  writeText(join(targetRoot, AGENT_GUIDE_PATH), agentGuideText(templateVersion));
+  return AGENT_GUIDE_PATH;
+}

package/src/core/copy/simple.js

@@ -1,6 +1,6 @@
 // 단순 복사 함수 (무조건 덮어쓰기류) — .sh copy_scripts/config/issue/discussion/setup_guide 등가.
 // 실측: template_integrator.sh 3818, 3845, 3872, 3895, 4114.
-import { join } from "node:path";
+import { join, basename } from "node:path";
 import { chmodSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
 import { PATHS } from "../paths.js";
 import { exists, copyFileSync, copyDirSync } from "../fsutil.js";
@@ -97,7 +97,8 @@ export function stripIssueTemplateAssignees(targetRoot = ".") {
 // .github/ISSUE_TEMPLATE/ 전체 + PULL_REQUEST_TEMPLATE.md 덮어쓰기.
 export function copyIssueTemplates(tempDir, targetRoot = ".") {
   const srcIssue = join(tempDir, ".github", "ISSUE_TEMPLATE");
-  if (exists(srcIssue)) copyDirSync(srcIssue, join(targetRoot, ".github", "ISSUE_TEMPLATE"));
+  // `projectops-` 로 시작하는 파일은 이 저장소(projectops 자체)의 이슈 양식이라 사용자 레포로 복사하지 않는다 (#797).
+  if (exists(srcIssue)) copyDirSync(srcIssue, join(targetRoot, ".github", "ISSUE_TEMPLATE"), { filter: (src) => !basename(src).startsWith("projectops-") });
   const srcPr = join(tempDir, ".github", "PULL_REQUEST_TEMPLATE.md");
   if (exists(srcPr)) copyFileSync(srcPr, join(targetRoot, ".github", "PULL_REQUEST_TEMPLATE.md"));
 }

package/src/core/copy/workflows.js

@@ -6,10 +6,29 @@ import { join, basename } from "node:path";
 import { existsSync, readFileSync, writeFileSync, renameSync } from "node:fs";
 import { PATHS } from "../paths.js";
 import { exists, copyFileSync, listYamlFiles } from "../fsutil.js";
-import { isUnchanged, substituteEnv, resolveGlobalTokens } from "../wizard-env.js";
+import { isUnchanged, substituteEnv, resolveGlobalTokens, extractEnvValues } from "../wizard-env.js";
 import { isUserModified, readBaseline, writeBaseline, sha256 } from "../baseline.js";
 import { substituteBranches } from "../branch-sub.js";
 import { saveIncoming, lineDiffCounts } from "../incoming.js";
+import { branchStatus } from "../git-branch.js";
+
+// on: 블록의 브랜치 필터가 전부 develop 뿐인가 (#810).
+// 개발 브랜치가 없는 레포에 깔면 영영 실행되지 않는 워크플로우를 가린다.
+// workflow_dispatch 외의 다른 이벤트(schedule·issues 등)가 있으면 그것만으로도 돌 수 있으니 false.
+export function onlyTriggersOnDevelop(content) {
+  const m = String(content).match(/^on:\s*\n((?:[ \t]+.*\n|\s*\n)+)/m);
+  if (!m) return false;
+  const block = m[1];
+  const events = [...block.matchAll(/^ {2}([a-z_]+):/gm)].map((x) => x[1]);
+  if (!events.length || events.some((e) => !["push", "pull_request", "workflow_dispatch"].includes(e))) return false;
+  const branches = [];
+  for (const b of block.matchAll(/^\s+branches:\s*\[([^\]]*)\]/gm)) branches.push(...b[1].split(",").map((s) => s.trim().replace(/["']/g, "")).filter(Boolean));
+  for (const b of block.matchAll(/^\s+branches:\s*\n((?:\s+-\s*.*\n)+)/gm)) branches.push(...[...b[1].matchAll(/-\s*["']?([^"'\s#]+)/g)].map((x) => x[1]));
+  // push/pull_request 마다 branches 필터가 있어야 한다 — 필터 없는 push 는 모든 브랜치에서 돈다
+  const filtered = (block.match(/^\s+branches:/gm) || []).length;
+  const needFilter = events.filter((e) => e !== "workflow_dispatch").length;
+  return branches.length > 0 && filtered >= needFilter && branches.every((b) => b === "develop");
+}
 
 // 한 파일에 env 치환을 적용해 대상 파일을 갱신 (.sh configure_workflow_env 등가).
 // values/useDefaults: env 계획(promptEnvPlan) 결과 — 미지정이면 기본값 경로(현행 force 동작).
@@ -90,6 +109,43 @@ export function copyWorkflows(context, tempDir, targetRoot = ".", hooks = {}) {
   // values/useDefaults는 치환 경로에서만 의미 (isUnchanged는 내부에서 useDefaults:true 강제 — 가상 비교 무손상)
   const envOptsFor = (type) => ({ type, projectPath: paths.get(type) || ".", repoName, resolvers, values: envValues, useDefaults: envUseDefaults, branches });
 
+  // 설치하지 않을 새 파일 (#810) — 깔 때마다 다시 생기던 것들.
+  //   excluded        : version.yml options.excluded_workflows 에 사용자가 적은 파일
+  //   deleted-by-user : 우리가 깐 기록(baseline)이 있는데 지금 없다 = 사용자가 지웠다 (.bak 은 우리가 치운 것이라 제외)
+  //   no-dev-branch   : 개발 브랜치가 원격에 확실히 없는데 그 브랜치에서만 도는 워크플로우
+  const notInstalled = [];
+  Object.defineProperty(counters, "notInstalled", { value: notInstalled, enumerable: false });
+  const excludedSet = new Set(context.excludedWorkflows || []);
+  const devName = branches.deployBranch;
+  let devMissing = null; // 필요할 때 한 번만 원격을 조회한다
+  const isDevMissing = () => {
+    if (devMissing === null) {
+      const st = devName === branches.defaultBranch ? null : branchStatus(targetRoot, devName);
+      devMissing = !!(st && st.isRepo && !st.local && st.remote === false);
+    }
+    return devMissing;
+  };
+  const skipNew = (srcDir, filename, group) => {
+    const dst = join(workflowsDir, filename);
+    if (existsSync(dst)) return false;
+    let reason = null;
+    if (excludedSet.has(filename)) reason = "excluded";
+    else if (baseline?.files?.[filename] && !existsSync(dst + ".bak")) reason = "deleted-by-user";
+    else if (onlyTriggersOnDevelop(readFileSync(join(srcDir, filename), "utf8")) && isDevMissing()) reason = "no-dev-branch";
+    if (!reason) return false;
+    const info = { filename, reason, incoming: "" };
+    try {
+      // 마음이 바뀌면 cp 한 번으로 되살릴 수 있게 렌더본을 incoming 에 남긴다
+      const rendered = substituteBranches(substituteEnv(readFileSync(join(srcDir, filename), "utf8"),
+        { ...envOptsFor(group.split("/")[0]), useDefaults: true }), branches);
+      info.incoming = saveIncoming(targetRoot, filename, rendered);
+    } catch { /* 안내만 빠진다 */ }
+    notInstalled.push(info);
+    trace?.event("copy", "not-installed", filename, { group, reason });
+    return true;
+  };
+  Object.defineProperty(counters, "skipNew", { value: skipNew, enumerable: false });
+
   // 사용자 수정본을 유지할 때 새 템플릿 사본을 incoming에 남긴다 (#654).
   // 실패는 경고 한 줄로 흡수한다 — 병합 안내 때문에 복사 전체가 죽으면 안 된다.
   const onSkip = (srcDir, filename, type) => {
@@ -133,6 +189,7 @@ export function copyWorkflows(context, tempDir, targetRoot = ".", hooks = {}) {
         continue;
       }
       // 사용자가 손댄 적 없고 템플릿만 바뀐 파일 — 물어볼 것 없이 최신으로 올린다(종전과 동일).
+      if (commonClass.newFiles.includes(filename) && skipNew(commonDir, filename, "common")) continue;
       if (commonClass.newFiles.includes(filename) || commonClass.upstream.includes(filename)) {
         copyFileSync(join(commonDir, filename), join(workflowsDir, filename));
         counters.copied++;
@@ -179,6 +236,7 @@ export function copyWorkflows(context, tempDir, targetRoot = ".", hooks = {}) {
         trace?.event("copy", "skipped-unchanged", filename, { group: "common-deploy" });
         continue;
       }
+      if (skipNew(commonDeployDir, filename, "common-deploy")) continue;
       const backedUp = existsSync(dst);
       if (backedUp) renameSync(dst, dst + ".bak");
       copyFileSync(src, dst);
@@ -207,6 +265,7 @@ export function copyWorkflows(context, tempDir, targetRoot = ".", hooks = {}) {
         trace?.event("copy", "skipped-unchanged", filename, { group: groupName });
         continue;
       }
+      if (skipNew(prSummaryDir, filename, groupName)) continue;
       const backedUp = existsSync(dst);
       if (backedUp) renameSync(dst, dst + ".bak");
       copyFileSync(src, dst);
@@ -225,6 +284,7 @@ export function copyWorkflows(context, tempDir, targetRoot = ".", hooks = {}) {
     for (const filename of listYamlFiles(secretDir)) {
       const dst = join(workflowsDir, filename);
       if (existsSync(dst)) continue; // 이미 존재하면 스킵
+      if (skipNew(secretDir, filename, "secret-backup")) continue;
       copyFileSync(join(secretDir, filename), dst);
       // PROJECT_NAME 이 고정값이면 모든 프로젝트가 서버의 같은 폴더에 Secret 을 덮어쓴다 (#729) —
       // 다른 배포 워크플로처럼 레포 이름으로 채운다. 이름을 알 수 없으면 기존 기본값을 쓴다.
@@ -377,15 +437,25 @@ function copyWorkflowsForType(type, projectTypesDir, workflowsDir, ctx, counters
   const typeDir = join(projectTypesDir, type);
   const envOpts = envOptsFor(type);
   let unchangedNames = [];
+  // upstream 갱신 전 설치본의 env 실값 (#810 조사 중 발견). 템플릿만 바뀐 파일을 새로 깔 때
+  // 기본값으로 다시 치환해, 사용자가 고른 값(JAVA_VERSION 17 등)이 조용히 21로 돌아갔다.
+  const carried = new Map(); // Map<filename, Map<key,value>>
+  const upstreamCopy = (srcDir, f, group) => {
+    const dst = join(workflowsDir, f);
+    try { carried.set(f, extractEnvValues(readFileSync(dst, "utf8"))); } catch { /* 읽기 실패 — 기본값으로 */ }
+    copyFileSync(join(srcDir, f), dst);
+    counters.copied++; counters.copiedFiles.push(f);
+    trace?.event("copy", "upstream-updated", f, { group, reason: "baseline-match", carried: carried.get(f)?.size ?? 0 });
+  };
 
   // 타입별 워크플로우 (직하위)
   if (exists(typeDir)) {
     const { newFiles, unchanged, changed, upstream } = classify(typeDir, workflowsDir, envOpts, baseline);
     unchangedNames = unchanged.slice();
     for (const f of unchanged) { counters.skipped++; trace?.event("copy", "skipped-unchanged", f, { group: type }); }
-    for (const f of newFiles) { copyFileSync(join(typeDir, f), join(workflowsDir, f)); counters.copied++; counters.copiedFiles.push(f); trace?.event("copy", "copied", f, { group: type }); }
+    for (const f of newFiles) { if (counters.skipNew(typeDir, f, type)) continue; copyFileSync(join(typeDir, f), join(workflowsDir, f)); counters.copied++; counters.copiedFiles.push(f); trace?.event("copy", "copied", f, { group: type }); }
     // upstream(#557): 사용자가 손대지 않았고 템플릿만 바뀐 파일 — 물어볼 것 없이 최신으로 올린다.
-    for (const f of upstream) { copyFileSync(join(typeDir, f), join(workflowsDir, f)); counters.copied++; counters.copiedFiles.push(f); trace?.event("copy", "upstream-updated", f, { group: type, reason: "baseline-match" }); }
+    for (const f of upstream) upstreamCopy(typeDir, f, type);
     // changed: 결정 Map에 따라 처리 (미지정=skip → 현행 force 동작과 동일)
     for (const f of changed) applyDecision(decisions.get(f), typeDir, workflowsDir, f, counters, trace, type);
   }
@@ -395,8 +465,8 @@ function copyWorkflowsForType(type, projectTypesDir, workflowsDir, ctx, counters
   if (exists(serverDeployDir) && (deployTarget || "docker-ssh") === "docker-ssh") {
     const { newFiles, unchanged, changed, upstream } = classify(serverDeployDir, workflowsDir, envOpts, baseline);
     for (const f of unchanged) { counters.skipped++; trace?.event("copy", "skipped-unchanged", f, { group: `${type}/server-deploy` }); }
-    for (const f of newFiles) { copyFileSync(join(serverDeployDir, f), join(workflowsDir, f)); counters.copied++; counters.copiedFiles.push(f); trace?.event("copy", "copied", f, { group: `${type}/server-deploy` }); }
-    for (const f of upstream) { copyFileSync(join(serverDeployDir, f), join(workflowsDir, f)); counters.copied++; counters.copiedFiles.push(f); trace?.event("copy", "upstream-updated", f, { group: `${type}/server-deploy`, reason: "baseline-match" }); }
+    for (const f of newFiles) { if (counters.skipNew(serverDeployDir, f, `${type}/server-deploy`)) continue; copyFileSync(join(serverDeployDir, f), join(workflowsDir, f)); counters.copied++; counters.copiedFiles.push(f); trace?.event("copy", "copied", f, { group: `${type}/server-deploy` }); }
+    for (const f of upstream) upstreamCopy(serverDeployDir, f, `${type}/server-deploy`);
     for (const f of changed) applyDecision(decisions.get(f), serverDeployDir, workflowsDir, f, counters, trace, type);
   }
 
@@ -414,6 +484,7 @@ function copyWorkflowsForType(type, projectTypesDir, workflowsDir, ctx, counters
         trace?.event("copy", "skipped-unchanged", filename, { group: `${type}/publish/${target}` });
         continue;
       }
+      if (counters.skipNew(pubDir, filename, `${type}/publish/${target}`)) continue;
       const backedUp = existsSync(dst);
       if (backedUp) renameSync(dst, dst + ".bak");
       copyFileSync(src, dst);
@@ -432,7 +503,14 @@ function copyWorkflowsForType(type, projectTypesDir, workflowsDir, ctx, counters
       const target = join(workflowsDir, filename);
       if (!existsSync(target)) continue;            // 건너뛴 파일 제외
       if (unchangedNames.includes(filename)) continue; // unchanged 제외
-      configureEnv(target, filename, { ...envOpts, collectAsks, trace }); // env 계획 values/useDefaults 포함
+      const prev = carried.get(filename);
+      if (prev && prev.size) {
+        // 이월값 위에 이번 실행에서 명시로 고른 값을 덮는다 (명시 선택이 이긴다)
+        const values = new Map([...prev, ...(envOpts.useDefaults ? [] : envOpts.values)]);
+        configureEnv(target, filename, { ...envOpts, values, useDefaults: false, collectAsks, trace });
+      } else {
+        configureEnv(target, filename, { ...envOpts, collectAsks, trace }); // env 계획 values/useDefaults 포함
+      }
     }
   }
 }

package/src/core/exclusions.js

@@ -9,6 +9,7 @@ export const DOCS_TO_REMOVE = [
   "CLAUDE.md",
   "AGENTS.md",
   "GEMINI.md",
+  "llms.txt",
   "gemini-extension.json",
   // 릴리스마다 changelog-deploy 파이프라인이 재생성하는 이 레포 전용 작업 산출물.
   // 사용자 프로젝트에는 의미가 없으므로 복사하지 않는다.

package/src/core/fsutil.js

@@ -20,9 +20,9 @@ export function copyFileSync(src, dst) {
 }
 
 // 디렉토리 재귀 복사 (내용을 dst 하위로)
-export function copyDirSync(src, dst) {
+export function copyDirSync(src, dst, { filter } = {}) {
   mkdirSync(dst, { recursive: true });
-  cpSync(src, dst, { recursive: true });
+  cpSync(src, dst, { recursive: true, ...(filter ? { filter } : {}) });
 }
 
 // 파일/폴더 삭제 (없어도 무해)

package/src/core/migrations/index.js

@@ -48,8 +48,9 @@ export function applySafeMigrations(targetRoot, entries) {
 // 마법사 배선 진입점.
 //   askYesNo - async(msg, defaultYes)→bool. null이면 비대화형(--force): safe 자동 적용
 //   log      - 한 줄 출력 함수 (기본 console.log)
+//   removeLegacy - true면 confirm 티어(구세대 배포 워크플로우)도 .bak 무해화 (--remove-legacy, #809)
 // 반환: { applied: [결과], confirmPending: [entry], askPending: [entry] }
-export async function runMigrations({ targetRoot = ".", askYesNo = null, log = console.log } = {}) {
+export async function runMigrations({ targetRoot = ".", askYesNo = null, log = console.log, removeLegacy = false } = {}) {
   const { safe, confirm, ask } = detectMigrations(targetRoot);
   if (safe.length === 0 && confirm.length === 0 && ask.length === 0) {
     return { applied: [], confirmPending: [], askPending: [] };
@@ -110,7 +111,21 @@ export async function runMigrations({ targetRoot = ".", askYesNo = null, log = c
       const arrow = e.replacedBy ? t("migrate.confirm.newer", { name: e.replacedBy }) : "";
       log(`   • ${e.file}${arrow}: ${reasonOf(e)}`);
     }
-    log(t("migrate.confirm.hint"));
+    // 신·구 세대가 함께 돌면 같은 이벤트에 두 번 반응한다 (#809 — PR 닫힘마다 PREVIEW 두 벌).
+    // 현역 배포일 수 있어 기본은 손대지 않되, 명시 플래그나 대화형 확인이 있으면 .bak 으로 치운다(복원 가능).
+    const yes = removeLegacy
+      ? true
+      : askYesNo ? await askYesNo(t("migrate.confirm.ask", { n: confirm.length }), false) : false;
+    if (yes === true) {
+      const results = applySafeMigrations(targetRoot, confirm);
+      applied = applied.concat(results);
+      const failed = results.filter((r) => r.action === "error");
+      log(t("migrate.confirm.done", { n: results.length - failed.length }));
+      for (const f of failed) log(`   ⚠️ ${f.from}: ${f.error}`);
+      const failedIds = new Set(failed.map((f) => f.id));
+      return { applied, confirmPending: confirm.filter((e) => failedIds.has(e.id)), askPending };
+    }
+    log(t(askYesNo ? "migrate.confirm.hint" : "migrate.confirm.hintForce"));
   }
 
   return { applied, confirmPending: confirm, askPending };