projectops 4.2.15 → 4.2.17

package/README.md

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

package/package.json

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

package/src/commands/interactive.js

@@ -14,6 +14,8 @@ import { runMigrations } from "../core/migrations/index.js";
 import { detectOrphanWorkflows, applyOrphanCleanup } from "../core/orphan-workflows.js";
 import { resolveProjectPaths, filterExcludedTypes } from "../core/paths-resolve.js";
 import { askAllOptionalWorkflows, OPTION_AXES } from "../core/options-ask.js";
+import { createRunTrace } from "../core/run-trace.js";
+import { appendGuideEntry } from "../core/migration-guide.js";
 import { promptEnvPlan } from "../ui/env-plan.js";
 import { listWorkflowConflicts } from "../core/copy/workflows.js";
 import { createContext, VALID_TYPES } from "../context.js";
@@ -31,6 +33,9 @@ const isCancel = (v) => v === CANCEL || typeof v === "symbol";
 // skills = runSkills 주입 지점(테스트가 실제 IDE CLI를 안 건드리게). 기본은 실제 runSkills.
 export async function runInteractive(baseCtx, { cwd = process.cwd(), source = { type: "git" }, clock, io = prompts, skills = runSkills } = {}) {
   const tempDir = join(cwd, PATHS.tempDir);
+  // 실행 트레이스 (#494) — 실제 CLI(io=prompts)에서만 터미널 미러를 켠다 (테스트 스텁 io는 이벤트만).
+  const trace = createRunTrace();
+  if (io === prompts) trace.mirrorStart();
   try {
     // 템플릿 먼저 획득 — 배너에 실제 템플릿 버전을 표시 (.sh는 원격 version.yml fetch L4270~4280 등가)
     acquireTemplate({ tempDir, source });
@@ -53,9 +58,11 @@ export async function runInteractive(baseCtx, { cwd = process.cwd(), source = {
     if (mode === CANCEL || mode == null) { io.cancelMessage?.("설치를 취소했습니다."); return 0; }
 
     // Breaking Changes 게이트 (.sh execute_integration L4415~4420 — 모든 모드 공통, 대화형은 확인 질문)
+    let breakingReport = null; // #493 — 통과 구간 항목을 가이드에 조치 방법 전문으로 임베드
     const proceed = await runBreakingCheck({
       cwd, tempDir, templateVersion,
       askYesNo: (msg, def) => io.askYesNo(msg, def),
+      onItems: (items) => { breakingReport = items; },
     });
     if (!proceed) { io.cancelMessage?.("통합을 안전하게 취소했습니다."); return 0; }
 
@@ -89,6 +96,8 @@ export async function runInteractive(baseCtx, { cwd = process.cwd(), source = {
     let changelogProvider = existing?.options?.changelogProvider ?? "github-ai";
     let changelogBaseUrl = existing?.options?.changelogBaseUrl ?? "";
     let deployBranch = existing?.options?.deployBranch ?? "develop"; // #456
+    let deployBranchReady = null; // #490 — 이번 실행에서 개발 브랜치 존재/생성이 확인됐는지
+    let deployBranchCreated = null; // #493 — 마법사가 직접 생성했는지 (가이드 기록용)
     let intent = existing?.options?.intent ?? null; // #485 프로젝트 성격
     const showOptional = mode === "full" || mode === "workflows";
     const realTty = process.stdout.isTTY === true;
@@ -123,6 +132,8 @@ export async function runInteractive(baseCtx, { cwd = process.cwd(), source = {
       changelogProvider = r.changelogProvider;
       changelogBaseUrl = r.changelogBaseUrl;
       deployBranch = r.deployBranch;
+      deployBranchReady = r.deployBranchReady ?? deployBranchReady; // #490
+      deployBranchCreated = r.deployBranchCreated ?? deployBranchCreated; // #493
       intent = r.intent;
     }
 
@@ -186,6 +197,8 @@ export async function runInteractive(baseCtx, { cwd = process.cwd(), source = {
           changelogProvider = r.changelogProvider;
           changelogBaseUrl = r.changelogBaseUrl;
           deployBranch = r.deployBranch;
+          deployBranchReady = r.deployBranchReady ?? deployBranchReady; // #490
+          deployBranchCreated = r.deployBranchCreated ?? deployBranchCreated; // #493
           intent = r.intent;
         }
       }
@@ -249,14 +262,18 @@ export async function runInteractive(baseCtx, { cwd = process.cwd(), source = {
     }
 
     // 레거시 마이그레이션 (#470) — 워크플로우를 만지는 모드에서만. 대화형은 safe 티어 확인 1회.
+    let migrationsResult = null; // #493 — 가이드 기록용
     if (mode === "full" || mode === "workflows") {
-      await runMigrations({
+      migrationsResult = await runMigrations({
         targetRoot: cwd,
         askYesNo: (msg, def) => io.askYesNo(msg, def),
       });
+      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 ?? "" });
     }
 
     // 고아 타입 워크플로우 정리 (#487) — 타입 변경으로 선택에서 빠진 타입의 잔존 워크플로우
+    const orphanReport = { cleaned: [], pending: [] }; // #493 — 가이드 기록용
     if (mode === "full" || mode === "workflows") {
       const orphans = detectOrphanWorkflows({ tempDir, targetRoot: cwd, selectedTypes: types });
       if (orphans.length > 0) {
@@ -269,28 +286,48 @@ export async function runInteractive(baseCtx, { cwd = process.cwd(), source = {
           const results = applyOrphanCleanup(cwd, orphans);
           const ok = results.filter((r) => r.action === "bak");
           const failed = results.filter((r) => r.action === "error");
+          orphanReport.cleaned = ok.map((r) => r.filename);
+          for (const r of ok) trace.event("orphan", "neutralized", r.filename);
           io.note?.(`✅ 고아 워크플로우 정리: ${ok.length}개${failed.length ? ` (실패 ${failed.length}개)` : ""}`, "정리 완료");
+        } else {
+          orphanReport.pending = orphans.map((o) => o.filename);
         }
       }
     }
 
     let result = null;
-    if (mode === "full") result = runFull(ctx, tempDir, cwd, hooks);
+    if (mode === "full") result = runFull(ctx, tempDir, cwd, { ...hooks, trace });
     else if (mode === "version") result = runVersion(ctx, tempDir, cwd);
-    else if (mode === "workflows") result = runWorkflows(ctx, tempDir, cwd, hooks);
+    else if (mode === "workflows") result = runWorkflows(ctx, tempDir, cwd, { ...hooks, trace });
 
     // 통합 후 IDE 스킬 제안 (.sh L4557 offer_ide_tools_install — 사전 질문 게이트, 기본 N)
     const wantSkills = await io.askYesNo("AI 에이전트 스킬(Claude·Cursor·Gemini·Codex·PI)도 설치/업데이트할까요?", false);
     if (wantSkills === true) await skills({ templateVersion, tempDir, interactive: true });
 
+    // 마이그레이션 기록 (#493/#494) — Layer 2/3 트레이스 파일 + Layer 1 가이드 엔트리 (full/workflows만)
+    let migrationGuidePath = null;
+    if (mode === "full" || mode === "workflows") {
+      const files = trace.write({ targetRoot: cwd, fromVersion: existing?.templateVersion || "", toVersion: templateVersion, now });
+      migrationGuidePath = appendGuideEntry(cwd, {
+        now, mode, types, repoName,
+        templateFrom: existing?.templateVersion || "", templateTo: templateVersion,
+        options: { deploy: deployTarget, publish: publishTargets, secretBackup: includeSecretBackup, coderabbit: codeReviewCoderabbit, changelogProvider, intent },
+        branches: { defaultBranch: branch, deployBranch, ready: deployBranchReady, created: deployBranchCreated },
+        breaking: breakingReport, migrations: migrationsResult, orphans: orphanReport,
+        events: trace.events, counters: { skipped: result?.workflows?.skipped ?? 0 },
+        traceFile: files?.traceFile ?? "", logFile: files?.logFile ?? "",
+      }).guidePath;
+    }
+
     // 완료 요약 (.sh print_summary L5438)
     io.summary?.({
-      mode, types, version, deployBranch,
+      mode, types, version, deployBranch, deployBranchReady, migrationGuidePath,
       counters: { workflows: result?.workflows?.copied ?? 0, workflowFiles: result?.workflows?.copiedFiles ?? [], utilModules: 0 },
     }, cwd);
     io.outro?.(`통합 완료 — ${mode} 모드로 설치했습니다.`);
     return 0;
   } finally {
+    trace.mirrorStop();
     remove(tempDir);
   }
 }

package/src/core/breaking-check.js

@@ -27,7 +27,9 @@ export async function loadBreakingJson(tempDir) {
 //   templateVersion - 설치하려는 템플릿 버전 (.sh의 DEFAULT_VERSION 고정 버그를 실버전으로 교정 — 설계 D2)
 //   askYesNo        - async(message, defaultYes)→bool. null이면 비대화형: 경고만 출력 후 진행
 //   loader          - 테스트 주입용 (기본 loadBreakingJson)
-export async function runBreakingCheck({ cwd, tempDir, templateVersion, askYesNo = null, loader = loadBreakingJson }) {
+//   onItems         - (#493) 통과 구간 항목 콜백 ({current, target, critical, warnings}) —
+//                     마이그레이션 가이드가 조치 방법 전문을 임베드하는 데 쓴다 (표시 여부와 무관하게 호출)
+export async function runBreakingCheck({ cwd, tempDir, templateVersion, askYesNo = null, loader = loadBreakingJson, onItems = null }) {
   const vy = join(cwd, "version.yml");
   if (!existsSync(vy)) return true; // 신규 통합 — 비교 기준 없음
   const { templateVersion: current } = parseExisting(readFileSync(vy, "utf8"));
@@ -37,6 +39,7 @@ export async function runBreakingCheck({ cwd, tempDir, templateVersion, askYesNo
   if (!json) return true;
 
   const { critical, warnings } = collectBreaking(json, current, templateVersion);
+  if (critical.length || warnings.length) onItems?.({ current, target: templateVersion, critical, warnings });
   if (critical.length === 0 && warnings.length === 0) return true;
 
   // 요약 리스트 표시 (#473 — 전문 통덤프는 벽글이 되어 정작 CRITICAL이 안 읽혔고,

package/src/core/copy/workflows.js

@@ -11,11 +11,27 @@ import { substituteBranches } from "../branch-sub.js";
 
 // 한 파일에 env 치환을 적용해 대상 파일을 갱신 (.sh configure_workflow_env 등가).
 // values/useDefaults: env 계획(promptEnvPlan) 결과 — 미지정이면 기본값 경로(현행 force 동작).
-function configureEnv(targetPath, { type, projectPath = ".", repoName = "", resolvers = {}, collectAsks = null, values = new Map(), useDefaults = true }) {
+// trace(#494): 치환 1건당 env.substituted 이벤트 (before/after 포함 — 치환 불일치류 버그의 즉시 발견 근거).
+function configureEnv(targetPath, filename, { type, projectPath = ".", repoName = "", resolvers = {}, collectAsks = null, values = new Map(), useDefaults = true, trace = null }) {
   const content = readFileSync(targetPath, "utf8");
   if (!content.includes("@wizard")) return;
-  const out = substituteEnv(content, { type, useDefaults, values, projectPath, repoName, resolvers, collectAsks });
+  const collectSubs = trace ? [] : null;
+  const out = substituteEnv(content, { type, useDefaults, values, projectPath, repoName, resolvers, collectAsks, collectSubs });
   writeFileSync(targetPath, out);
+  if (trace && collectSubs) {
+    for (const s of collectSubs) trace.event("env", "substituted", filename, { type, ...s });
+  }
+}
+
+// util 버전 동기화 워크플로우 (#491) — .github/util/ 모듈(version.json)이 있는 레포에서만 의미가 있다.
+// util이 없는 레포(예: spring 단독)에 복사하면 트리거가 영원히 안 걸리는 no-op 오염이 된다.
+const UTIL_VERSION_SYNC = "PROJECT-COMMON-TEMPLATE-UTIL-VERSION-SYNC.yml";
+
+// 이 통합에서 util 모듈이 존재하게 되는가 — 대상에 이미 있거나(업데이트),
+// 선택 타입의 util이 템플릿에 있어 곧 복사될 예정(runFull 6단계)이면 true.
+function utilSyncApplies(tempDir, targetRoot, types) {
+  if (exists(join(targetRoot, ".github", "util"))) return true;
+  return types.some((t) => exists(join(tempDir, ".github", "util", t)));
 }
 
 // 3분류 (신규/unchanged/changed) — 대상 워크플로우 디렉토리 기준.
@@ -46,6 +62,7 @@ function classify(srcDir, workflowsDir, envOpts) {
 export function copyWorkflows(context, tempDir, targetRoot = ".", hooks = {}) {
   const { types = [], paths = new Map(), deployTarget = "docker-ssh", publishTargets = [], includeSecretBackup = false, repoName = "", resolvers = {}, envValues = new Map(), envUseDefaults = true, branch = "", deployBranch = "" } = context;
   const decisions = hooks.decisions instanceof Map ? hooks.decisions : new Map();
+  const trace = hooks.trace ?? null; // #494 — 실행 트레이스 (null-safe: 미주입이면 전 이벤트 no-op)
   const workflowsDir = join(targetRoot, PATHS.workflowsDir);
   const projectTypesDir = join(tempDir, PATHS.workflowsDir, PATHS.projectTypesDir);
   if (!exists(projectTypesDir)) throw new Error("템플릿 저장소 구조 오류 — project-types 폴더를 찾지 못했습니다.");
@@ -62,22 +79,29 @@ export function copyWorkflows(context, tempDir, targetRoot = ".", hooks = {}) {
   const commonDir = join(projectTypesDir, "common");
   if (exists(commonDir)) {
     for (const filename of listYamlFiles(commonDir)) {
+      // #491 — util 동기화 워크플로우는 util 모듈이 있(게 되)는 레포에만 복사
+      if (filename === UTIL_VERSION_SYNC && !utilSyncApplies(tempDir, targetRoot, types)) {
+        trace?.event("copy", "excluded", filename, { reason: "util-modules-absent" });
+        continue;
+      }
       const src = join(commonDir, filename);
       const dst = join(workflowsDir, filename);
       if (existsSync(dst) && isUnchanged(readFileSync(src, "utf8"), readFileSync(dst, "utf8"), envOptsFor("common"))) {
         counters.skipped++;
+        trace?.event("copy", "skipped-unchanged", filename, { group: "common" });
         continue;
       }
       copyFileSync(src, dst);
       counters.copied++;
       counters.copiedFiles.push(filename);
+      trace?.event("copy", "copied", filename, { group: "common" });
     }
   }
 
   // (2~4) 타입별
   for (const type of types) {
     const asks = new Map();
-    copyWorkflowsForType(type, projectTypesDir, workflowsDir, { deployTarget, publishTargets, ...context, envOptsFor, collectAsks: asks, decisions }, counters);
+    copyWorkflowsForType(type, projectTypesDir, workflowsDir, { deployTarget, publishTargets, ...context, envOptsFor, collectAsks: asks, decisions, trace }, counters);
     if (asks.size) deployValues.set(type, asks);
   }
 
@@ -89,13 +113,16 @@ export function copyWorkflows(context, tempDir, targetRoot = ".", hooks = {}) {
       const dst = join(workflowsDir, filename);
       if (existsSync(dst) && isUnchanged(readFileSync(src, "utf8"), readFileSync(dst, "utf8"), envOptsFor("common"))) {
         counters.skipped++;
+        trace?.event("copy", "skipped-unchanged", filename, { group: "common-deploy" });
         continue;
       }
-      if (existsSync(dst)) renameSync(dst, dst + ".bak");
+      const backedUp = existsSync(dst);
+      if (backedUp) renameSync(dst, dst + ".bak");
       copyFileSync(src, dst);
       counters.optionalCopied++;
       counters.copied++;
       counters.copiedFiles.push(filename);
+      trace?.event("copy", backedUp ? "replaced-bak" : "copied", filename, { group: "common-deploy" });
     }
   }
 
@@ -109,6 +136,7 @@ export function copyWorkflows(context, tempDir, targetRoot = ".", hooks = {}) {
       counters.optionalCopied++;
       counters.copied++;
       counters.copiedFiles.push(filename);
+      trace?.event("copy", "copied", filename, { group: "secret-backup" });
     }
   }
 
@@ -120,7 +148,10 @@ export function copyWorkflows(context, tempDir, targetRoot = ".", hooks = {}) {
       if (!existsSync(p)) continue;
       const before = readFileSync(p, "utf8");
       const after = substituteBranches(before, branches);
-      if (after !== before) writeFileSync(p, after);
+      if (after !== before) {
+        writeFileSync(p, after);
+        trace?.event("env", "branch-substituted", f, { defaultBranch: branches.defaultBranch, deployBranch: branches.deployBranch });
+      }
     }
   }
 
@@ -129,7 +160,7 @@ export function copyWorkflows(context, tempDir, targetRoot = ".", hooks = {}) {
 
 // changed(기존에 있고 내용이 바뀐) 파일 1개를 결정에 따라 처리 (.sh 3440~3508 3지선 case 등가).
 // 'skip'(기본): 기존 유지. 'backup': 기존→.bak 후 교체. 'template': 기존 유지 + 새 버전을 .template.yaml로.
-function applyDecision(decision, srcDir, workflowsDir, filename, counters) {
+function applyDecision(decision, srcDir, workflowsDir, filename, counters, trace = null) {
   const src = join(srcDir, filename);
   const dst = join(workflowsDir, filename);
   if (decision === "backup") {
@@ -138,6 +169,7 @@ function applyDecision(decision, srcDir, workflowsDir, filename, counters) {
     copyFileSync(src, dst);
     counters.copied++;
     counters.copiedFiles?.push(filename);
+    trace?.event("copy", "replaced-bak", filename, { decision });
     return;
   }
   if (decision === "template") {
@@ -145,9 +177,11 @@ function applyDecision(decision, srcDir, workflowsDir, filename, counters) {
     const templateName = (filename.endsWith(".yaml") ? filename.slice(0, -".yaml".length) : filename) + ".template.yaml";
     copyFileSync(src, join(workflowsDir, templateName)); // cp가 기존 .template.yaml 덮어씀(.sh rm -f + cp 등가)
     counters.templateAdded++;
+    trace?.event("copy", "template-added", templateName, { original: filename });
     return;
   }
   counters.skipped++; // 'skip'/미지정/ESC → 기존 유지 (.sh S)·force 기본)
+  trace?.event("copy", "skipped-conflict", filename, { decision: decision ?? "skip", note: "사용자 수정본 유지 — 병합 검토 후보" });
 }
 
 // 대상 워크플로우 디렉토리에서 changed(충돌) 파일 목록만 뽑는다 — copyWorkflowsInteractive의 사전 조사용.
@@ -190,7 +224,7 @@ export async function copyWorkflowsInteractive(context, tempDir, targetRoot = ".
 const PUBLISH_TARGETS = ["nexus", "npm", "github-packages"];
 
 function copyWorkflowsForType(type, projectTypesDir, workflowsDir, ctx, counters) {
-  const { deployTarget = "docker-ssh", publishTargets = [], force = false, paths = new Map(), repoName = "", resolvers = {}, envOptsFor, collectAsks = null, decisions = new Map() } = ctx;
+  const { deployTarget = "docker-ssh", publishTargets = [], force = false, paths = new Map(), repoName = "", resolvers = {}, envOptsFor, collectAsks = null, decisions = new Map(), trace = null } = ctx;
   const typeDir = join(projectTypesDir, type);
   const envOpts = envOptsFor(type);
   let unchangedNames = [];
@@ -199,19 +233,19 @@ function copyWorkflowsForType(type, projectTypesDir, workflowsDir, ctx, counters
   if (exists(typeDir)) {
     const { newFiles, unchanged, changed } = classify(typeDir, workflowsDir, envOpts);
     unchangedNames = unchanged.slice();
-    for (const f of unchanged) counters.skipped++;
-    for (const f of newFiles) { copyFileSync(join(typeDir, f), join(workflowsDir, f)); counters.copied++; counters.copiedFiles.push(f); }
+    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 }); }
     // changed: 결정 Map에 따라 처리 (미지정=skip → 현행 force 동작과 동일)
-    for (const f of changed) applyDecision(decisions.get(f), typeDir, workflowsDir, f, counters);
+    for (const f of changed) applyDecision(decisions.get(f), typeDir, workflowsDir, f, counters, trace);
   }
 
   // server-deploy — deploy=docker-ssh일 때만 포함 (#439)
   const serverDeployDir = join(typeDir, "server-deploy");
   if (exists(serverDeployDir) && (deployTarget || "docker-ssh") === "docker-ssh") {
     const { newFiles, unchanged, changed } = classify(serverDeployDir, workflowsDir, envOpts);
-    for (const f of unchanged) counters.skipped++;
-    for (const f of newFiles) { copyFileSync(join(serverDeployDir, f), join(workflowsDir, f)); counters.copied++; counters.copiedFiles.push(f); }
-    for (const f of changed) applyDecision(decisions.get(f), serverDeployDir, workflowsDir, f, counters);
+    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 changed) applyDecision(decisions.get(f), serverDeployDir, workflowsDir, f, counters, trace);
   }
 
   // publish/<target> (opt-in — #439 publish 축. 타입은 파일 위치일 뿐 게이트가 아니다)
@@ -225,13 +259,16 @@ function copyWorkflowsForType(type, projectTypesDir, workflowsDir, ctx, counters
       const dst = join(workflowsDir, filename);
       if (existsSync(dst) && isUnchanged(readFileSync(src, "utf8"), readFileSync(dst, "utf8"), envOpts)) {
         counters.skipped++;
+        trace?.event("copy", "skipped-unchanged", filename, { group: `${type}/publish/${target}` });
         continue;
       }
-      if (existsSync(dst)) renameSync(dst, dst + ".bak");
+      const backedUp = existsSync(dst);
+      if (backedUp) renameSync(dst, dst + ".bak");
       copyFileSync(src, dst);
       counters.optionalCopied++;
       counters.copied++;
       counters.copiedFiles.push(filename);
+      trace?.event("copy", backedUp ? "replaced-bak" : "copied", filename, { group: `${type}/publish/${target}` });
     }
   }
 
@@ -242,7 +279,7 @@ function copyWorkflowsForType(type, projectTypesDir, workflowsDir, ctx, counters
       const target = join(workflowsDir, filename);
       if (!existsSync(target)) continue;            // 건너뛴 파일 제외
       if (unchangedNames.includes(filename)) continue; // unchanged 제외
-      configureEnv(target, { ...envOpts, collectAsks }); // env 계획 values/useDefaults 포함
+      configureEnv(target, filename, { ...envOpts, collectAsks, trace }); // env 계획 values/useDefaults 포함
     }
   }
 }

package/src/core/migration-guide.js

@@ -0,0 +1,224 @@
+// 마이그레이션 가이드 (#493) — Layer 1 큐레이션 문서.
+// 마법사(full/workflows) 실행이 끝나면 대상 레포의 docs/projectops/migration/PROJECTOPS-MIGRATION-GUIDE.md에
+// "고정 헤더(최초 1회) + 실행 엔트리(append-only)"를 남긴다. 사람용 동적 체크리스트와
+// AI Agent용 yaml 메타데이터를 한 엔트리에 담고, run-trace(#494)의 events를 단일 소스로 소비한다.
+import { join } from "node:path";
+import { existsSync, readFileSync, appendFileSync } from "node:fs";
+import { writeText } from "./fsutil.js";
+import { MIGRATION_DIR } from "./run-trace.js";
+
+export const GUIDE_FILE = `${MIGRATION_DIR}/PROJECTOPS-MIGRATION-GUIDE.md`;
+export const GUIDE_SCHEMA = 1;
+
+// 고정 헤더 — 문서 목적 + AI Agent 해석 가이드라인. 최초 생성 시 1회만 쓴다 (엔트리와 분리).
+const HEADER = `# ProjectOps 마이그레이션 가이드
+
+이 문서는 projectops 마법사(\`npx projectops\`)가 **실행을 마칠 때마다 자동으로 기록**하는
+마이그레이션 이력입니다. 실행 엔트리는 아래에 시간순으로 append되며, 기존 엔트리는 수정되지 않습니다.
+
+## 사람이 읽는 법
+
+- 각 엔트리의 **확인 체크리스트**가 그 실행 이후 사람이 마무리해야 하는 수동 작업입니다.
+- 체크리스트는 실행에서 실제 발생한 것만 나옵니다 — 항목이 없으면 할 일이 없다는 뜻입니다.
+- 상세 실행 기록(파일별 결정·치환 전후값)은 엔트리 메타의 \`trace_file\`(JSONL)·\`log_file\`(터미널 원문)에 있습니다.
+
+## AI Agent 해석 가이드라인
+
+각 엔트리의 \`\`\`yaml 메타 블록(\`# projectops-migration\`)을 파싱해 아래 규칙으로 판단·조치한다.
+
+| 필드 | 의미 | 권장 조치 |
+|------|------|----------|
+| \`workflows.leftover_old_gen\` | 구세대 워크플로우가 현역 가능성으로 보존됨 | 신형과 트리거 중복 여부 검사 → 전환 확인 후 구 파일 삭제 제안 |
+| \`workflows.skipped_conflict\` | 사용자 수정본이 유지됨 (신형 미적용) | 사용자본과 신형 템플릿 diff → 병합 제안 |
+| \`workflows.replaced_bak\` | .bak 백업 후 신형으로 교체됨 | .bak과 신형 비교 → 사용자 커스텀 유실분 복원 검토 후 .bak 정리 |
+| \`env_applied\` | 워크플로우에 적용된 환경값 | 실제 워크플로우 env와 대조 → 드리프트 발견 시 경고 |
+| \`breaking_traversed\` | 이 실행이 통과한 호환성 변경 (조치 방법 전문은 사람용 섹션) | \`action_required: true\` 항목의 조치 완료 여부 확인 |
+| \`manual_actions_pending\` | 남은 수동 작업 코드 목록 | 비어 있지 않으면 사용자에게 상기 |
+| \`trace_file\` | 파일별 결정·치환 전후값 JSONL (Layer 2) | "왜 이 파일이 이렇게 됐나"는 파일명으로 grep |
+| \`log_file\` | 터미널 출력 원문 (Layer 3) | 실행 재현·포렌식 디버깅용 |
+
+- 스키마는 \`schema\` 필드로 버저닝된다. 모르는 필드는 무시하고, 아는 필드만 사용한다.
+- 여러 엔트리가 있으면 **가장 최근 엔트리**가 현재 상태의 기준이다. 과거 엔트리는 이력 참고용.
+`;
+
+// ── yaml 렌더 헬퍼 (외부 의존성 없이 수동 직렬화 — version-yml.js와 동일 원칙) ──
+const yq = (s) => `"${String(s ?? "").replaceAll('"', '\\"')}"`;
+const ylist = (arr) => (arr && arr.length ? `[${arr.map(yq).join(", ")}]` : "[]");
+
+// trace events → 가이드용 파일 목록 파생 (단일 소스 — 이벤트에서 유도).
+export function deriveWorkflowLists(events = []) {
+  const pick = (action) => events.filter((e) => e.phase === "copy" && e.action === action).map((e) => e.target);
+  return {
+    added: pick("copied"),
+    replacedBak: pick("replaced-bak"),
+    skippedConflict: pick("skipped-conflict"),
+    templateAdded: pick("template-added"),
+    excluded: pick("excluded"),
+  };
+}
+
+// trace events → 타입별 적용 env 값 파생.
+export function deriveEnvApplied(events = []) {
+  const byType = new Map();
+  for (const e of events) {
+    if (e.phase !== "env" || e.action !== "substituted") continue;
+    const t = e.detail?.type ?? "";
+    if (!byType.has(t)) byType.set(t, new Map());
+    byType.get(t).set(e.detail?.key ?? "", e.detail?.after ?? "");
+  }
+  return byType;
+}
+
+// 실행 엔트리 렌더링. report:
+//   { now, mode, types, repoName, templateFrom, templateTo,
+//     options: {deploy, publish, secretBackup, coderabbit, changelogProvider, intent},
+//     branches: {defaultBranch, deployBranch, ready, created},
+//     breaking: {current, target, critical:[], warnings:[]} | null,
+//     migrations: {applied:[], confirmPending:[], askPending:[]} | null,
+//     orphans: {cleaned:[], pending:[]} | null,
+//     events: [], counters: {}, traceFile, logFile }
+export function renderGuideEntry(report) {
+  const r = report ?? {};
+  const from = r.templateFrom || "new";
+  const to = r.templateTo || "unknown";
+  const wf = deriveWorkflowLists(r.events);
+  const envByType = deriveEnvApplied(r.events);
+  const breaking = r.breaking ?? null;
+  const breakingAll = breaking ? [...(breaking.critical ?? []), ...(breaking.warnings ?? [])] : [];
+  const mig = r.migrations ?? null;
+  const leftoverOldGen = (mig?.confirmPending ?? []).map((e) => ({ file: e.file, replacement: e.replacedBy || "", reason: e.reason || "" }));
+  const legacyNeutralized = (mig?.applied ?? []).filter((a) => a.action !== "error");
+  const orphanCleaned = (r.orphans?.cleaned ?? []);
+
+  const L = [];
+  L.push("---");
+  L.push("");
+  L.push(`## ${r.now || ""} — v${from} → v${to} (${r.mode || "full"})`);
+  L.push("");
+  L.push(`- 타입: ${(r.types ?? []).join(", ") || "-"} · 배포: ${r.options?.deploy ?? "-"} · publish: ${(r.options?.publish ?? []).join(",") || "없음"}`);
+  L.push(`- 워크플로우: 신규/갱신 ${wf.added.length + wf.replacedBak.length}개 · 유지(unchanged/충돌스킵) ${(r.counters?.skipped ?? 0)}개`);
+  L.push("");
+
+  // ── 확인 체크리스트 (동적 — 실제 발생분만) ──
+  const checklist = [];
+  if (leftoverOldGen.length) {
+    checklist.push(`- [ ] **구세대 배포 워크플로우 ${leftoverOldGen.length}개 전환 후 삭제** — 현역 배포일 수 있어 마법사가 건드리지 않았습니다:`);
+    for (const o of leftoverOldGen) checklist.push(`  - \`${o.file}\`${o.replacement ? ` → 신형 \`${o.replacement}\`` : ""}`);
+  }
+  if (wf.replacedBak.length || legacyNeutralized.length) {
+    checklist.push(`- [ ] **.bak 백업 파일 확인 후 정리** — 커스텀 유실분이 없는지 신형과 비교하세요:`);
+    for (const f of wf.replacedBak) checklist.push(`  - \`${f}.bak\` (충돌 교체 백업)`);
+    for (const a of legacyNeutralized) if (a.to && String(a.to).endsWith(".bak")) checklist.push(`  - \`${a.to}\` (레거시 무해화)`);
+  }
+  if (wf.skippedConflict.length) {
+    checklist.push(`- [ ] **기존 수정본 유지 ${wf.skippedConflict.length}개 — 신형과 병합 검토**: ${wf.skippedConflict.map((f) => `\`${f}\``).join(", ")}`);
+  }
+  if (wf.added.length || wf.replacedBak.length) {
+    checklist.push(`- [ ] **새/갱신 CICD가 요구하는 GitHub Secrets 등록 확인** (Settings → Secrets → Actions, \`_GITHUB_PAT_TOKEN\` 포함)`);
+  }
+  if (envByType.size) {
+    checklist.push(`- [ ] **적용된 배포 환경값 검증** — 실제 환경과 다르면 워크플로우 env를 직접 수정:`);
+    for (const [t, kv] of envByType) {
+      for (const [k, v] of kv) checklist.push(`  - ${t} · \`${k}\` = \`${v}\``);
+    }
+  }
+  if (r.branches?.created === true) {
+    checklist.push(`- [x] 개발(릴리스 소스) 브랜치 \`${r.branches?.deployBranch ?? "develop"}\` — 마법사가 생성·확인 완료`);
+  } else if (r.branches?.ready === false) {
+    checklist.push(`- [ ] 개발(릴리스 소스) 브랜치 \`${r.branches?.deployBranch ?? "develop"}\` 생성 — 릴리스 PR이 동작하려면 필요합니다`);
+  }
+  if (checklist.length) {
+    L.push("### 확인 체크리스트");
+    L.push("");
+    L.push(...checklist);
+    L.push("");
+  }
+
+  // ── 버전 점프에서 통과한 호환성 변경 (조치 방법 전문 — 터미널에서 스킵해도 여기 남는다) ──
+  if (breakingAll.length) {
+    L.push(`### 통과한 호환성 변경 (v${breaking.current} → v${breaking.target})`);
+    L.push("");
+    for (const it of breakingAll) {
+      const sev = (breaking.critical ?? []).includes(it) ? "CRITICAL" : "WARNING";
+      L.push(`#### ${sev === "CRITICAL" ? "❗" : "⚠️"} [${sev}] ${it.version} — ${it.title || ""}`);
+      if (it.message) L.push(`${it.message}`);
+      L.push("");
+    }
+  }
+
+  // ── AI 메타데이터 ──
+  L.push("### AI 메타데이터");
+  L.push("");
+  L.push("```yaml");
+  L.push("# projectops-migration (machine-readable)");
+  L.push(`schema: ${GUIDE_SCHEMA}`);
+  L.push(`run_at: ${yq(r.now || "")}`);
+  L.push(`template: { from: ${yq(from)}, to: ${yq(to)} }`);
+  L.push(`mode: ${r.mode || "full"}`);
+  L.push(`types: ${ylist(r.types)}`);
+  L.push(`options: { deploy: ${yq(r.options?.deploy ?? "")}, publish: ${ylist(r.options?.publish)}, secret_backup: ${r.options?.secretBackup === true}, coderabbit: ${r.options?.coderabbit === true}, changelog_provider: ${yq(r.options?.changelogProvider ?? "")}, intent: ${yq(r.options?.intent ?? "")} }`);
+  L.push(`branches: { default: ${yq(r.branches?.defaultBranch ?? "main")}, deploy: ${yq(r.branches?.deployBranch ?? "develop")}, deploy_branch_created: ${r.branches?.created === true} }`);
+  L.push("workflows:");
+  L.push(`  added: ${ylist(wf.added)}`);
+  L.push(`  replaced_bak: ${ylist(wf.replacedBak)}`);
+  L.push(`  skipped_conflict: ${ylist(wf.skippedConflict)}`);
+  L.push(`  template_added: ${ylist(wf.templateAdded)}`);
+  if (legacyNeutralized.length) {
+    L.push("  legacy_neutralized:");
+    for (const a of legacyNeutralized) L.push(`    - { file: ${yq(a.from ?? a.id ?? "")}, to: ${yq(a.to ?? "")}, action: ${yq(a.action ?? "")} }`);
+  } else {
+    L.push("  legacy_neutralized: []");
+  }
+  if (leftoverOldGen.length) {
+    L.push("  leftover_old_gen:");
+    for (const o of leftoverOldGen) L.push(`    - { file: ${yq(o.file)}, replacement: ${yq(o.replacement)} }`);
+  } else {
+    L.push("  leftover_old_gen: []");
+  }
+  if (orphanCleaned.length) L.push(`  orphan_neutralized: ${ylist(orphanCleaned)}`);
+  if (envByType.size) {
+    L.push("env_applied:");
+    for (const [t, kv] of envByType) {
+      L.push(`  ${t}:`);
+      for (const [k, v] of kv) L.push(`    ${k}: ${yq(v)}`);
+    }
+  } else {
+    L.push("env_applied: {}");
+  }
+  if (breakingAll.length) {
+    L.push("breaking_traversed:");
+    for (const it of breakingAll) {
+      const sev = (breaking.critical ?? []).includes(it) ? "critical" : "warning";
+      L.push(`  - { version: ${yq(it.version)}, severity: ${sev}, title: ${yq(it.title ?? "")}, action_required: ${sev === "critical"} }`);
+    }
+  } else {
+    L.push("breaking_traversed: []");
+  }
+  const pending = [];
+  if (leftoverOldGen.length) pending.push("delete-old-gen-workflows");
+  if (wf.replacedBak.length || legacyNeutralized.some((a) => a.to && String(a.to).endsWith(".bak"))) pending.push("review-bak-files");
+  if (wf.skippedConflict.length) pending.push("merge-skipped-conflicts");
+  if (wf.added.length || wf.replacedBak.length) pending.push("register-secrets");
+  if (r.branches?.ready === false) pending.push("create-deploy-branch");
+  L.push(`manual_actions_pending: ${ylist(pending)}`);
+  L.push(`trace_file: ${yq(r.traceFile ?? "")}`);
+  L.push(`log_file: ${yq(r.logFile ?? "")}`);
+  L.push("```");
+  L.push("");
+  return L.join("\n");
+}
+
+// 가이드 파일에 엔트리 append (파일 없으면 헤더부터 생성). 반환: { guidePath, created }.
+export function appendGuideEntry(targetRoot, report) {
+  const guidePath = join(targetRoot, GUIDE_FILE);
+  const entry = renderGuideEntry(report);
+  const created = !existsSync(guidePath);
+  if (created) {
+    writeText(guidePath, HEADER + "\n" + entry);
+  } else {
+    // append-only — 기존 엔트리 불변 (이력 보존 계약)
+    const prev = readFileSync(guidePath, "utf8");
+    appendFileSync(guidePath, (prev.endsWith("\n") ? "" : "\n") + entry);
+  }
+  return { guidePath: GUIDE_FILE, created };
+}

package/src/core/options-ask.js

@@ -16,34 +16,39 @@ import { branchStatus, createBranch, pushBranch } from "./git-branch.js";
 // 개발(배포) 브랜치 존재 확인 + 생성 제안 (#477) — 대화형 전용.
 // 로컬에 없고 원격에도 없(거나 불명이)면 기본 브랜치에서 생성을 제안하고, 생성 후 push 여부도 묻는다.
 // git 미설치·비레포·질문 불가(io.confirm 없음)면 조용히 통과 — 마법사 진행을 막지 않는다.
+// 반환 ready (#490 — 완료 요약이 "브랜치 만들어라" 재지시를 접을지 판단):
+//   true  = 브랜치가 이미 있거나 이번 실행에서 생성함 → 요약에서 생성 안내 불필요
+//   false = 없는데 사용자가 거절/생성 실패 → 안내 유지
+//   null  = 확인 자체를 못 함(비레포·질문 불가) → 안내 유지(보수적)
 export async function ensureDeployBranch({ targetRoot = ".", deployBranch = "", defaultBranch = "", io = {}, say = () => {} }) {
-  if (!deployBranch || typeof io.confirm !== "function") return { created: false, pushed: false };
+  if (!deployBranch || typeof io.confirm !== "function") return { created: false, pushed: false, ready: null };
   const st = branchStatus(targetRoot, deployBranch);
-  if (!st.isRepo || st.local) return { created: false, pushed: false };
+  if (!st.isRepo) return { created: false, pushed: false, ready: null };
+  if (st.local) return { created: false, pushed: false, ready: true };
   if (st.remote === true) {
     say(`ℹ️ '${deployBranch}' 브랜치가 원격에는 있고 로컬에 없습니다 — 필요 시 'git switch ${deployBranch}'로 가져오세요.`);
-    return { created: false, pushed: false };
+    return { created: false, pushed: false, ready: true };
   }
   say(`⚠️ 개발(릴리스 소스) 브랜치 '${deployBranch}'가 없습니다 — 릴리스(${deployBranch}→${defaultBranch || "기본 브랜치"} PR)가 동작하려면 필요합니다.`);
   const mk = await io.confirm({ message: `${defaultBranch || "현재"} 브랜치에서 '${deployBranch}' 브랜치를 만들까요?`, initialValue: true });
   if (mk !== true) {
     say(`→ 건너뜁니다. 나중에 직접: git checkout -b ${deployBranch} && git push -u origin ${deployBranch}`);
-    return { created: false, pushed: false };
+    return { created: false, pushed: false, ready: false };
   }
   if (!createBranch(targetRoot, deployBranch, defaultBranch)) {
     say(`⚠️ 브랜치 생성 실패 — 직접 실행해주세요: git branch ${deployBranch}${defaultBranch ? ` ${defaultBranch}` : ""}`);
-    return { created: false, pushed: false };
+    return { created: false, pushed: false, ready: false };
   }
   say(`✅ 로컬 브랜치 '${deployBranch}' 생성 완료 (checkout은 하지 않았습니다)`);
   // #481 — push 질문에 브랜치명 명시 ("어느 브랜치를 push하는지" 불명확 방지)
   const up = await io.confirm({ message: `원격(origin)에 '${deployBranch}' 브랜치도 push할까요?`, initialValue: true });
-  if (up !== true) return { created: true, pushed: false };
+  if (up !== true) return { created: true, pushed: false, ready: true };
   if (pushBranch(targetRoot, deployBranch)) {
     say(`✅ origin/${deployBranch} push 완료`);
-    return { created: true, pushed: true };
+    return { created: true, pushed: true, ready: true };
   }
   say(`⚠️ push 실패(자격/네트워크) — 직접 실행해주세요: git push -u origin ${deployBranch}`);
-  return { created: true, pushed: false };
+  return { created: true, pushed: false, ready: true };
 }
 
 // 재노출 — 파서 본체는 version-yml.js에 있다 (순환 import 방지: options-ask → version-yml 방향만 허용)
@@ -115,6 +120,8 @@ export async function askAllOptionalWorkflows({
   let changelogProvider = current.changelogProvider ?? null;
   let changelogBaseUrl = current.changelogBaseUrl ?? null;
   let deployBranch = current.deployBranch ?? null; // #456 릴리스 PR head 브랜치
+  let deployBranchReady = null; // #490 — 이번 실행에서 브랜치 존재/생성이 확인됐는지 (null=확인 안 함)
+  let deployBranchCreated = null; // #493 — 이번 실행에서 마법사가 직접 생성했는지 (가이드 기록용)
   let intent = current.intent ?? null; // #485 프로젝트 성격 (app/library/both/none/manual)
 
   // basic 단독 타입은 서버 배포도 라이브러리 publish도 개념상 성립하지 않는다.
@@ -328,7 +335,10 @@ export async function askAllOptionalWorkflows({
       deployBranch = (typeof ans === "string" && !isCancel(ans) && ans.trim()) ? ans.trim() : (deployBranch ?? "develop");
       say(`개발(릴리스 소스) 브랜치: ${deployBranch}`);
       // 브랜치 존재 확인 + 생성 제안 (#477) — 없으면 릴리스 파이프라인이 조용히 놀게 된다
-      await ensureDeployBranch({ targetRoot, deployBranch, defaultBranch, io, say });
+      // #490 — 결과(ready)를 완료 요약에 전달해 이미 생성/확인한 브랜치를 재지시하지 않는다
+      const br = await ensureDeployBranch({ targetRoot, deployBranch, defaultBranch, io, say });
+      deployBranchReady = br.ready;
+      deployBranchCreated = br.created;
     }
   }
 
@@ -349,6 +359,9 @@ export async function askAllOptionalWorkflows({
     changelogProvider: changelogProvider ?? "github-ai",
     changelogBaseUrl: changelogBaseUrl ?? "",
     deployBranch: deployBranch ?? "develop",
+    deployBranchReady, // #490 — true=존재/생성 확인됨, false=거절/실패, null=확인 안 함
+    deployBranchCreated, // #493 — true=이번 실행에서 마법사가 생성, null=확인 안 함
+
     // #485 intent — 확정값 우선, 없으면 최종 deploy/publish에서 역추론(basic·비대화형 경로 보정)
     intent: intent ?? inferIntent(finalDeploy, finalPublish) ?? "manual",
   };

package/src/core/run-trace.js

@@ -0,0 +1,89 @@
+// 마법사 실행 트레이스 (#494) — 3계층 기록의 Layer 2(JSONL 이벤트) + Layer 3(터미널 미러).
+// 마법사의 모든 결정·행동을 이벤트 한 줄씩 남겨, 나중에 사람·AI Agent가 파일명 grep 한 번으로
+// "이 파일에 마법사가 한 모든 일"을 시간순 추적할 수 있게 한다 (v4.2.15 수동 로그 복사 진단의 자동화).
+// Layer 1(큐레이션 가이드)은 migration-guide.js — 이 모듈의 events를 단일 소스로 소비한다.
+import { join } from "node:path";
+import { writeText } from "./fsutil.js";
+
+export const MIGRATION_DIR = "docs/projectops/migration";
+export const TRACE_SCHEMA = 1;
+
+// 민감값 가드 — PAT·토큰·시크릿·비밀번호는 어떤 이벤트에도 남기지 않는다 (#494 안전 규칙).
+const SENSITIVE_KEY_RE = /pat|token|secret|password|credential/i;
+export function scrubDetail(detail) {
+  if (detail == null || typeof detail !== "object" || Array.isArray(detail)) return detail;
+  const out = {};
+  for (const [k, v] of Object.entries(detail)) {
+    if (SENSITIVE_KEY_RE.test(k)) continue;
+    out[k] = (v != null && typeof v === "object" && !Array.isArray(v)) ? scrubDetail(v) : v;
+  }
+  return out;
+}
+
+// now("YYYY-MM-DD HH:MM:SS") → 파일명 스탬프 "YYYYMMDD_HHMMSS". 형식이 아니면 "run" 폴백(테스트 주입 clock 안전).
+export function stampFromNow(now) {
+  const digits = String(now ?? "").replace(/[^0-9]/g, "");
+  if (digits.length < 14) return "run";
+  return `${digits.slice(0, 8)}_${digits.slice(8, 14)}`;
+}
+
+// 트레이스 팩토리. clockIso 주입 가능(테스트 결정성) — 기본은 실제 UTC.
+export function createRunTrace({ clockIso = null } = {}) {
+  const events = [];
+  const lines = [];
+  let restore = null;
+
+  const nowIso = () => clockIso ?? new Date().toISOString().replace(/\.\d+Z$/, "Z");
+
+  return {
+    events,
+    lines,
+
+    // 이벤트 1건 기록. detail은 민감키 스크럽 후 저장.
+    event(phase, action, target = "", detail = null) {
+      const e = { ts: nowIso(), phase, action, target };
+      const d = scrubDetail(detail);
+      if (d != null && (typeof d !== "object" || Object.keys(d).length > 0)) e.detail = d;
+      events.push(e);
+      return e;
+    },
+
+    // 터미널 출력 미러 시작 — stdout/stderr write를 감싸 사본만 수집(출력 자체는 그대로 통과).
+    // 실제 CLI 실행에서만 켠다 (테스트 스텁 io 경로는 호출하지 않음).
+    mirrorStart() {
+      if (restore) return;
+      const so = process.stdout.write; // 원본 참조 보관 — 복원 시 identity 유지
+      const se = process.stderr.write;
+      const capture = (chunk) => {
+        try { lines.push(typeof chunk === "string" ? chunk : chunk.toString("utf8")); } catch { /* 미러 실패는 실행에 영향 없음 */ }
+      };
+      process.stdout.write = function (chunk, ...rest) { capture(chunk); return so.apply(process.stdout, [chunk, ...rest]); };
+      process.stderr.write = function (chunk, ...rest) { capture(chunk); return se.apply(process.stderr, [chunk, ...rest]); };
+      restore = () => { process.stdout.write = so; process.stderr.write = se; };
+    },
+
+    mirrorStop() {
+      if (restore) { restore(); restore = null; }
+    },
+
+    // Layer 2/3 파일 기록 — docs/projectops/migration/{stamp}_v{from}_to_v{to}.{jsonl,log}
+    // 반환: { traceFile, logFile } (targetRoot 기준 상대 경로 — 가이드 메타 포인터용).
+    // 이벤트가 0건이면 기록하지 않는다(no-op 실행 오염 방지) — null 반환.
+    write({ targetRoot = ".", fromVersion = "", toVersion = "", now = "" } = {}) {
+      if (events.length === 0) return null;
+      const stamp = stampFromNow(now);
+      const from = String(fromVersion || "new").replace(/[^0-9a-zA-Z.-]/g, "");
+      const to = String(toVersion || "unknown").replace(/[^0-9a-zA-Z.-]/g, "");
+      const base = `${stamp}_v${from}_to_v${to}`;
+      const traceFile = `${MIGRATION_DIR}/${base}.jsonl`;
+      const header = JSON.stringify({ schema: TRACE_SCHEMA, kind: "projectops-migration-trace", from, to, started: events[0]?.ts ?? "" });
+      writeText(join(targetRoot, traceFile), [header, ...events.map((e) => JSON.stringify(e))].join("\n") + "\n");
+      let logFile = null;
+      if (lines.length > 0) {
+        logFile = `${MIGRATION_DIR}/${base}.log`;
+        writeText(join(targetRoot, logFile), lines.join(""));
+      }
+      return { traceFile, logFile };
+    },
+  };
+}

package/src/core/wizard-env.js

@@ -41,6 +41,13 @@ export function resolveToken(name, type, resolvers = {}) {
   return typeof fn === "function" ? (fn(type) ?? "") : "";
 }
 
+// 잔여 전역 토큰 치환 (.sh 3347~3351) — 파일 본문·수집값(#489)·카드 표시가 전부 같은 규칙을 쓴다.
+// 파일에 실제 써지는 값과 version.yml deploy 블록 기억값이 어긋나지 않게 하는 단일 지점.
+export function resolveGlobalTokens(s, repoName = "") {
+  if (typeof s !== "string" || (!s.includes("__PROJECT_NAME__") && !s.includes("__APP_ARTIFACT_NAME__"))) return s;
+  return s.replaceAll("__PROJECT_NAME__", repoName).replaceAll("__APP_ARTIFACT_NAME__", repoName);
+}
+
 // 파일 전체 치환 (configure_workflow_env 등가).
 // content: 원본 워크플로우 텍스트. 반환: 치환된 텍스트.
 // opts:
@@ -50,8 +57,9 @@ export function resolveToken(name, type, resolvers = {}) {
 //   resolvers     - resolveToken용
 //   repoName      - __PROJECT_NAME__/__APP_ARTIFACT_NAME__ 치환값
 //   projectPath   - paths-anchor 치환용 ('.'이면 anchor 미변경)
+//   collectSubs   - 배열이면 치환 1건당 {key, action, before, after}를 push (#494 트레이스용)
 export function substituteEnv(content, opts = {}) {
-  const { type = "", values = new Map(), useDefaults = true, resolvers = {}, repoName = "", projectPath = ".", collectAsks = null } = opts;
+  const { type = "", values = new Map(), useDefaults = true, resolvers = {}, repoName = "", projectPath = ".", collectAsks = null, collectSubs = null } = opts;
   if (!content.includes("@wizard")) return content;
 
   // CRLF 안전: EOL을 분리해 LF 기준으로 파싱·치환하고, 원래 EOL 스타일을 복원한다.
@@ -70,16 +78,21 @@ export function substituteEnv(content, opts = {}) {
       if (chosen != null && chosen !== "" && !useDefaults) val = chosen;
       else val = def;
       // ask 키만 수집 (.sh wf_deploy_set — auto는 저장 안 함). deploy 블록용.
-      if (collectAsks) collectAsks.set(p.key, val);
+      // #489 — 파일 본문은 아래 전역 토큰 치환을 거치므로 수집값도 동일 치환해
+      //        version.yml deploy 블록이 설치본과 항상 바이트 일치하게 한다.
+      if (collectAsks) collectAsks.set(p.key, resolveGlobalTokens(val, repoName));
+    }
+    // #494 트레이스 — 치환 전후값 기록 (after는 파일 최종형과 동일하게 전역 토큰까지 해석)
+    if (Array.isArray(collectSubs) && val !== "" && val != null) {
+      const before = (lines[i].match(/:\s*"([^"]*)"/) || [])[1] ?? "";
+      collectSubs.push({ key: p.key, action: p.action, before, after: resolveGlobalTokens(val, repoName) });
     }
     lines[i] = setEnvLine(lines[i], p.key, val);
   }
   let out = lines.join(usesCRLF ? "\r\n" : "\n");
 
   // 잔여 전역 토큰 (.sh 3347~3351)
-  if (out.includes("__PROJECT_NAME__") || out.includes("__APP_ARTIFACT_NAME__")) {
-    out = out.replaceAll("__PROJECT_NAME__", repoName).replaceAll("__APP_ARTIFACT_NAME__", repoName);
-  }
+  out = resolveGlobalTokens(out, repoName);
 
   // paths-anchor (.sh 3353~3360): 경로가 '.'이 아니면 주석 라인 전체를 paths 라인으로 교체
   if (PATHS_ANCHOR_RE.test(out) && projectPath && projectPath !== ".") {

package/src/index.js

@@ -14,6 +14,8 @@ import { parseExisting } from "./core/version-yml.js";
 import { runBreakingCheck } from "./core/breaking-check.js";
 import { runMigrations } from "./core/migrations/index.js";
 import { detectOrphanWorkflows } from "./core/orphan-workflows.js";
+import { createRunTrace } from "./core/run-trace.js";
+import { appendGuideEntry } from "./core/migration-guide.js";
 import { resolveProjectPaths } from "./core/paths-resolve.js";
 import { printBannerCompact } from "./ui/banner.js";
 import { printSummary } from "./ui/summary.js";
@@ -135,6 +137,13 @@ export async function run(argv, { cwd = process.cwd(), source = { type: "git" },
   });
 
   let result = null;
+  // 실행 트레이스 (#494) — 비대화형도 이벤트 기록 (터미널 미러는 CLI 실행에서만 유의미하므로 함께 켠다)
+  const trace = createRunTrace();
+  const recordArtifacts = opts.mode === "full" || opts.mode === "workflows";
+  let breakingReport = null;
+  let migrationsResult = null;
+  let orphanPending = [];
+  if (recordArtifacts) trace.mirrorStart();
   try {
     acquireTemplate({ tempDir, source });
     context.templateVersion = readTemplateVersion(tempDir);
@@ -143,38 +152,60 @@ export async function run(argv, { cwd = process.cwd(), source = { type: "git" },
     printBannerCompact({ version: context.templateVersion, mode: opts.mode });
 
     // Breaking Changes 게이트 (.sh execute_integration L4415~4420 등가 — 비대화형은 경고 후 진행)
-    const proceed = await runBreakingCheck({ cwd, tempDir, templateVersion: context.templateVersion });
+    const proceed = await runBreakingCheck({
+      cwd, tempDir, templateVersion: context.templateVersion,
+      onItems: (items) => { breakingReport = items; },
+    });
     if (!proceed) return 0;
 
     // 레거시 마이그레이션 (#470) — 워크플로우를 만지는 모드에서만. 비대화형은 safe 티어 자동 적용.
-    if (opts.mode === "full" || opts.mode === "workflows") {
-      await runMigrations({ targetRoot: cwd });
+    if (recordArtifacts) {
+      migrationsResult = await runMigrations({ targetRoot: cwd });
+      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 ?? "" });
     }
 
     // 고아 타입 워크플로우 안내 (#487) — 비대화형은 자동 무해화 금지(배포 파이프라인일 수 있음), 안내만
-    if (opts.mode === "full" || opts.mode === "workflows") {
+    if (recordArtifacts) {
       const orphans = detectOrphanWorkflows({ tempDir, targetRoot: cwd, selectedTypes: types });
+      orphanPending = orphans.map((o) => o.filename);
       for (const o of orphans) {
         console.error(`⚠️ 선택되지 않은 타입(${o.type})의 워크플로우가 남아있습니다: ${o.filename} — 대화형 마법사(npx projectops)에서 정리할 수 있습니다.`);
       }
     }
 
     switch (opts.mode) {
-      case "full": result = runFull(context, tempDir, cwd); break;
+      case "full": result = runFull(context, tempDir, cwd, { trace }); break;
       case "version": result = runVersion(context, tempDir, cwd); break;
-      case "workflows": result = runWorkflows(context, tempDir, cwd); break;
+      case "workflows": result = runWorkflows(context, tempDir, cwd, { trace }); break;
       case "issues": result = runIssues(context, tempDir, cwd); break;
       default:
         // 알 수 없는 모드 → .sh와 동일하게 복사 0건, 에러 아님
         break;
     }
   } finally {
+    trace.mirrorStop();
     remove(tempDir);
   }
 
+  // 마이그레이션 기록 (#493/#494) — Layer 2/3 트레이스 파일 + Layer 1 가이드 엔트리
+  let migrationGuidePath = null;
+  if (recordArtifacts) {
+    const files = trace.write({ targetRoot: cwd, fromVersion: existing?.templateVersion || "", toVersion: context.templateVersion, now });
+    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 },
+      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 },
+      traceFile: files?.traceFile ?? "", logFile: files?.logFile ?? "",
+    }).guidePath;
+  }
+
   // 완료 요약 (.sh print_summary — CLI 모드에서도 출력)
   printSummary({
-    mode: opts.mode, types, version, deployBranch: context.deployBranch,
+    mode: opts.mode, types, version, deployBranch: context.deployBranch, migrationGuidePath,
     counters: { workflows: result?.workflows?.copied ?? 0, workflowFiles: result?.workflows?.copiedFiles ?? [], utilModules: 0 },
   }, cwd);
   return 0;

package/src/ui/env-plan.js

@@ -8,7 +8,7 @@ import { readFileSync } from "node:fs";
 import { stdin, stderr } from "node:process";
 import { PATHS } from "../core/paths.js";
 import { exists, listYamlFiles } from "../core/fsutil.js";
-import { parseWizardLine, resolveToken } from "../core/wizard-env.js";
+import { parseWizardLine, resolveToken, resolveGlobalTokens } from "../core/wizard-env.js";
 import { loadWizardPrompts, wfField, workflowDisplayName } from "../core/wizard-labels.js";
 import * as engine from "./readline-engine.js";
 
@@ -39,7 +39,7 @@ export function scopeString(usages = []) {
 // 반환: { keys:[], defaults:Map<key,default>, typeDefaults:Map<"type|key",default>,
 //        usages:Map<key,[{type,workflowName}]> }
 export function collectAsks(tempDir, types = [], opts = {}) {
-  const { resolvers = {}, deployTarget = "docker-ssh", publishTargets = [], prompts = null } = opts;
+  const { resolvers = {}, deployTarget = "docker-ssh", publishTargets = [], prompts = null, repoName = "" } = opts;
   const baseDir = join(tempDir, PATHS.workflowsDir, PATHS.projectTypesDir);
   const keys = [];
   const defaults = new Map();
@@ -64,9 +64,13 @@ export function collectAsks(tempDir, types = [], opts = {}) {
           const p = parseWizardLine(line); // KEY 정규식 [A-Z_]+ (.sh와 동일)
           if (!p || p.action !== "ask") continue;
           // 타입별 기본값: @접두면 resolver 해석, 아니면 리터럴 (.sh _type_default 등가)
-          const typeDefault = p.arg.startsWith("@")
-            ? resolveToken(p.arg.slice(1), type, resolvers)
-            : p.arg;
+          // #489 — __PROJECT_NAME__ 등 전역 토큰은 카드 표시 전에 미리 해석한다.
+          //        설치본(파일 복사 시 전역 치환)과 동일한 값을 보여주지 않으면
+          //        사용자가 "리터럴이 그대로 박히나?" 오해하게 된다.
+          const typeDefault = resolveGlobalTokens(
+            p.arg.startsWith("@") ? resolveToken(p.arg.slice(1), type, resolvers) : p.arg,
+            repoName,
+          );
           typeDefaults.set(`${type}|${p.key}`, typeDefault);
           if (!defaults.has(p.key)) { keys.push(p.key); defaults.set(p.key, typeDefault); }
           const list = usages.get(p.key) || [];
@@ -140,7 +144,7 @@ export async function promptEnvPlan({
   deployTarget = "docker-ssh", publishTargets = [], targetRoot = ".", repoName = "", log = defaultLog,
 } = {}) {
   const prompts = loadWizardPrompts(targetRoot, tempDir);
-  const asks = collectAsks(tempDir, types, { resolvers, deployTarget, publishTargets, prompts });
+  const asks = collectAsks(tempDir, types, { resolvers, deployTarget, publishTargets, prompts, repoName });
   const defaults = asks.defaults;
 
   // 수집 키 0개 → 질문 자체가 없음 (.sh `[ ${#WF_ASK_KEYS[@]} -eq 0 ]` 등가)

package/src/ui/summary.js

@@ -9,6 +9,7 @@ const SEPARATOR = "────────────────────
 export function printSummary(ctx, targetRoot = ".") {
   const { mode, types = [], version = "", counters = {} } = ctx || {};
   const deployBranchName = ctx?.deployBranch || "develop"; // #477 — 설정된 배포 브랜치명으로 안내
+  const deployBranchReady = ctx?.deployBranchReady === true; // #490 — 마법사가 이번 실행에서 존재/생성 확인함
   const err = (s = "") => process.stderr.write(`${s}\n`);
   // 색상은 TTY일 때만 (.sh YELLOW/CYAN/NC 등가)
   const isTty = !!process.stderr.isTTY;
@@ -127,6 +128,11 @@ export function printSummary(ctx, targetRoot = ".") {
 
   err("  📖 TEMPLATE REPO: https://github.com/Cassiiopeia/projectops");
   err("  📚 워크플로우 가이드: .github/workflows/project-types/README.md");
+  // #493 — 이번 실행의 마이그레이션 기록 (수동 체크리스트·breaking 조치·AI 메타데이터)
+  if (ctx?.migrationGuidePath) {
+    err(`  🧭 마이그레이션 가이드: ${ctx.migrationGuidePath}`);
+    err("     (이번 실행의 변경 내역·수동 확인 체크리스트·AI Agent용 메타데이터가 기록됐습니다)");
+  }
   err("");
 
   // 필수 3가지 작업 안내 (.sh L5605~5625 — 원문 유지)
@@ -139,8 +145,13 @@ export function printSummary(ctx, targetRoot = ".") {
   err("     → Secret Name: _GITHUB_PAT_TOKEN");
   err("     → Scopes: repo, workflow");
   err("");
-  err(`  2️⃣  ${deployBranchName} 브랜치 생성 (아직 없다면)`);
-  err(`     → git checkout -b ${deployBranchName} && git push -u origin ${deployBranchName}`);
+  // #490 — 마법사가 브랜치를 직접 생성(또는 존재 확인)했으면 같은 작업을 재지시하지 않는다
+  if (deployBranchReady) {
+    err(`  2️⃣  ✅ ${deployBranchName} 브랜치 준비 완료 — 마법사가 확인·생성했습니다 (추가 작업 불필요)`);
+  } else {
+    err(`  2️⃣  ${deployBranchName} 브랜치 생성 (아직 없다면)`);
+    err(`     → git checkout -b ${deployBranchName} && git push -u origin ${deployBranchName}`);
+  }
   err("");
   err("  3️⃣  CodeRabbit 활성화 (코드 리뷰를 켰다면)");
   err("     → https://coderabbit.ai 로그인 → GitHub 앱 설치 → 이 저장소에 접근 권한(grant access) 부여");