projectops 4.5.0 → 4.6.0

package/README.md

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

package/package.json

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

package/src/commands/full.js

@@ -33,46 +33,63 @@ export function runFull(context, tempDir, targetRoot = ".", hooks = {}) {
 
   // 3. 워크플로우 복사 (+ env 치환) — deploy 블록에 쓸 ask 값을 수집한다.
   //    hooks.decisions: 대화형 충돌 3지선 결정 Map (미지정=skip — 현행 force 동작)
-  const wfCounters = copyWorkflows(context, tempDir, targetRoot, hooks);
+  const step = (name, fn, d) => (hooks.trace ? hooks.trace.step(name, fn, d) : fn());
+  const wfCounters = step("copy-workflows", () => copyWorkflows(context, tempDir, targetRoot, hooks),
+    { types, deploy: deployTarget, publish: publishTargets });
   const deployValues = wfCounters.deployValues || new Map(); // Map<type, Map<key,value>>
 
   // 1. version.yml 생성 (전체 재생성 — metadata → deploy → template 순, .sh 최종형과 동일)
-  writeText(join(targetRoot, PATHS.versionFile),
+  step("write-version-yml", () => writeText(join(targetRoot, PATHS.versionFile),
     buildVersionYml({
       version, types, paths, pathMarkers, branch, deployBranch, versionCode, now, today,
       deployValues,
       templateOptions: { templateVersion, deployTarget, publishTargets, includeSecretBackup, optionsDate: today,
         changelogProvider, changelogBaseUrl, codeReviewCoderabbit, intent, mode: "full", semverAuto, appRelease },
-    }));
+    })), { version, versionCode });
 
   // 2. README 버전 섹션
-  addVersionSectionToReadme(version, targetRoot);
+  step("update-readme", () => addVersionSectionToReadme(version, targetRoot), { version });
 
   // 5. scripts / config
-  copyScripts(tempDir, targetRoot);
-  copyConfigFolder(tempDir, targetRoot);
+  //    워크플로우 밖 영역도 기록한다 (#561) — 종전에는 "내 스크립트가 갱신됐나"를
+  //    로그만 보고 알 수 없었다.
+  step("copy-scripts", () => copyScripts(tempDir, targetRoot));
+  step("copy-config", () => copyConfigFolder(tempDir, targetRoot));
 
   // 6. util (타입별)
-  for (const t of types) copyUtilModules(tempDir, t, { force }, targetRoot);
+  for (const t of types) step("copy-util", () => copyUtilModules(tempDir, t, { force }, targetRoot), { type: t });
 
   // 7. issue / discussion 템플릿
-  copyIssueTemplates(tempDir, targetRoot);
-  copyDiscussionTemplates(tempDir, targetRoot);
+  step("copy-templates", () => {
+    copyIssueTemplates(tempDir, targetRoot);
+    copyDiscussionTemplates(tempDir, targetRoot);
+  });
 
   // 8. coderabbit / gitignore / setup guide
   //    CodeRabbit 코드리뷰 미사용 선택(#457)이면 .coderabbit.yaml을 복사하지 않는다.
-  copyCoderabbit(tempDir, { force, enabled: codeReviewCoderabbit }, targetRoot);
-  ensureGitignore(targetRoot);
-  copySetupGuide(tempDir, targetRoot);
+  step("copy-coderabbit", () => copyCoderabbit(tempDir, { force, enabled: codeReviewCoderabbit }, targetRoot),
+    { enabled: codeReviewCoderabbit });
+  step("ensure-gitignore", () => ensureGitignore(targetRoot));
+  step("copy-setup-guide", () => copySetupGuide(tempDir, targetRoot));
 
   // 9. 설치 후 검증 (#549) — 디스크에 쓰인 최종 결과물을 다시 읽는다.
   //    치환은 파일 단위로 흩어져 일어나고 auto 토큰은 resolver 결과에 의존하므로,
   //    최종 내용을 보는 것이 실제 배포될 것과 같은 것을 보는 유일한 방법이다.
-  const verification = verifyInstall(targetRoot);
-  hooks.trace?.emit?.("verify", "scan", {
+  const verification = step("verify-install", () => verifyInstall(targetRoot));
+  // detail 키 이름 주의: run-trace의 민감값 가드가 pat|token|secret|password|credential을
+  // 키에서 걸러낸다(#494). 여기서 다루는 값은 비밀이 아니라 "치환 플레이스홀더 이름"과
+  // "등록이 필요한 키 이름"이라 가드에 걸리지 않는 이름을 쓴다 — 가드 자체는 우회하지 않는다.
+  hooks.trace?.event("verify", "scan", "", {
     unresolved: verification.unresolved.length,
-    secrets: verification.secrets.size,
+    requiredKeys: verification.secrets.size,
   });
+  // 미치환 값은 배포 시점에 실패할 자리다 — 어느 파일 몇 번째 줄인지 로그에 남긴다.
+  for (const u of verification.unresolved) {
+    hooks.trace?.event("verify", "unresolved", u.filename, { line: u.line, placeholder: u.token });
+  }
+  for (const [name, users] of verification.secrets) {
+    hooks.trace?.event("verify", "required-key", name, { workflows: users });
+  }
 
   return { workflows: wfCounters, verification };
 }

package/src/commands/interactive.js

@@ -14,7 +14,7 @@ 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, applicableTargets } from "../core/options-ask.js";
-import { createRunTrace } from "../core/run-trace.js";
+import { createRunTrace, MIGRATION_DIR } 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";
@@ -36,11 +36,17 @@ export async function runInteractive(baseCtx, { cwd = process.cwd(), source = {
   const tempDir = join(cwd, PATHS.tempDir);
   // 실행 트레이스 (#494) — 실제 CLI(io=prompts)에서만 터미널 미러를 켠다 (테스트 스텁 io는 이벤트만).
   const trace = createRunTrace();
+  // Ctrl+C로 끊어도 기록이 남는다 (#561) — 대화형은 사람이 중간에 끊는 일이 잦다.
+  const disarmSignals = trace.armSignals({ targetRoot: cwd, now: clock?.now || "" });
+  // finally에서 기록할 때 쓰는 값 — try 안에서 확정되기 전에 취소될 수 있으므로 바깥에 둔다 (#561).
+  let traceFrom = "";
+  let traceTo = "";
   if (io === prompts) trace.mirrorStart();
   try {
     // 템플릿 먼저 획득 — 배너에 실제 템플릿 버전을 표시 (.sh는 원격 version.yml fetch L4270~4280 등가)
-    acquireTemplate({ tempDir, source });
+    trace.step("acquire-template", () => acquireTemplate({ tempDir, source }), { source: source?.type || "git" });
     const templateVersion = readTemplateVersion(tempDir);
+    traceTo = templateVersion;
 
     // 층1 — 시작 배너 (#446 확정 시안 A). 스텁엔 banner 없음 → intro 폴백.
     if (io.banner) io.banner({ version: templateVersion, modeLabel: "대화형 통합 마법사" });
@@ -49,6 +55,7 @@ export async function runInteractive(baseCtx, { cwd = process.cwd(), source = {
     // 기존 version.yml — version/version_code/paths/옵션 보존의 단일 진실 (.sh SSoT L2208~2239)
     const vyPath = join(cwd, "version.yml");
     const existing = existsSync(vyPath) ? parseExisting(readFileSync(vyPath, "utf8")) : null;
+    traceFrom = existing?.templateVersion || "";
 
     // 층4 — IDE Skills 현재 상태 · 층5 — 신규/업데이트 판별 (#446)
     io.ideStatus?.();
@@ -56,8 +63,11 @@ export async function runInteractive(baseCtx, { cwd = process.cwd(), source = {
 
     // 1) 모드 선택 — 기존 통합 레포면 업데이트 항목을 맨 위에 노출 (#502)
     const updateInfo = existing?.templateVersion ? { from: existing.templateVersion, to: templateVersion } : null;
+    // 실행 경계(#561) — 대화형은 사람이 무엇을 골랐는지가 핵심 기록이다.
+    trace.event("run", "start", "interactive", { templateVersion, isUpdate: !!updateInfo });
     const picked = await io.selectMode(updateInfo ? { update: updateInfo } : {});
-    if (picked === CANCEL || picked == null) { io.cancelMessage?.("설치를 취소했습니다."); return 0; }
+    trace.event("prompt", "mode", String(picked ?? ""), { update: !!updateInfo });
+    if (picked === CANCEL || picked == null) { trace.event("run", "cancelled", "mode-select", { reason: "user-cancel" }); io.cancelMessage?.("설치를 취소했습니다."); return 0; }
     // 업데이트 모드(#502): 저장된 통합 범위(templateMode, 없으면 full)를 재실행하고
     // 이하 updateRun 분기가 질문을 최소화한다 ("저장된 설정 그대로 반영"이 계약).
     const updateRun = picked === "update";
@@ -65,12 +75,12 @@ export async function runInteractive(baseCtx, { cwd = process.cwd(), source = {
 
     // Breaking Changes 게이트 (.sh execute_integration L4415~4420 — 모든 모드 공통, 대화형은 확인 질문)
     let breakingReport = null; // #493 — 통과 구간 항목을 가이드에 조치 방법 전문으로 임베드
-    const proceed = await runBreakingCheck({
+    const proceed = await trace.stepAsync("breaking-check", () => runBreakingCheck({
       cwd, tempDir, templateVersion,
       askYesNo: (msg, def) => io.askYesNo(msg, def),
       onItems: (items) => { breakingReport = items; },
-    });
-    if (!proceed) { io.cancelMessage?.("통합을 안전하게 취소했습니다."); return 0; }
+    }));
+    if (!proceed) { trace.event("run", "cancelled", "breaking-gate", { reason: "user-declined" }); io.cancelMessage?.("통합을 안전하게 취소했습니다."); return 0; }
 
     // skills 모드 — IDE 스킬 설치 (템플릿 통합 없음). 대화형으로 실행.
     if (mode === "skills") {
@@ -172,7 +182,7 @@ export async function runInteractive(baseCtx, { cwd = process.cwd(), source = {
         io.note?.(summarize({ mode, types, version, branch, deployTarget, publishTargets, includeSecretBackup, showOptional, changelogProvider, codeReviewCoderabbit }), "프로젝트 분석 결과");
       }
       const choice = await io.confirmProjectMenu();
-      if (choice === "cancel") { io.cancelMessage?.("설치를 취소했습니다."); return 0; }
+      if (choice === "cancel") { trace.event("run", "cancelled", "confirm-loop", { reason: "user-cancel" }); io.cancelMessage?.("설치를 취소했습니다."); return 0; }
       if (isCancel(choice) || choice == null) continue; // ESC = 머무르기 (루프 재출력)
       if (choice === "continue") { confirmed = true; break; }
       // edit 루프
@@ -183,6 +193,7 @@ export async function runInteractive(baseCtx, { cwd = process.cwd(), source = {
         if (isCancel(what) || what === "done") { editing = false; break; }
         if (what === "type") {
           const t = await io.selectTypes(types);
+          trace.event("prompt", "types", (Array.isArray(t) ? t : []).join(",") || "", { before: types });
           if (!isCancel(t) && Array.isArray(t) && t.length) {
             // 타입 집합이 실제로 바뀌면 경로 재해석 대상으로 초기화 (.sh L1984~1992 — 정렬 집합 비교)
             const oldSorted = [...types].sort().join(",");
@@ -264,6 +275,7 @@ export async function runInteractive(baseCtx, { cwd = process.cwd(), source = {
       if (conflicts.length) {
         io.note?.(conflicts.map((c) => `• ${c.filename}`).join("\n"), `♻️ 템플릿이 갱신된 워크플로우 ${conflicts.length}개`);
         const yes = await io.askYesNo(`위 ${conflicts.length}개를 .bak 백업 후 새 버전으로 교체할까요? (기존 설정값은 유지됩니다)`, true);
+        trace.event("prompt", "conflict-bulk", yes ? "backup" : "skip", { count: conflicts.length, files: conflicts.map((c) => c.filename) });
         const decision = yes === true ? "backup" : "skip";
         updateDecisions = new Map();
         for (const { filename } of conflicts) updateDecisions.set(filename, decision);
@@ -336,6 +348,7 @@ export async function runInteractive(baseCtx, { cwd = process.cwd(), source = {
           `🧹 선택되지 않은 타입의 워크플로우 ${orphans.length}개 발견`,
         );
         const yes = await io.askYesNo(`위 ${orphans.length}개를 정리할까요? (.bak 무해화 — 복원 가능)`, true);
+        trace.event("prompt", "orphan-cleanup", yes ? "clean" : "keep", { count: orphans.length });
         if (yes === true) {
           const results = applyOrphanCleanup(cwd, orphans);
           const ok = results.filter((r) => r.action === "bak");
@@ -350,9 +363,9 @@ export async function runInteractive(baseCtx, { cwd = process.cwd(), source = {
     }
 
     let result = null;
-    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, trace });
+    if (mode === "full") result = trace.step("install-full", () => runFull(ctx, tempDir, cwd, { ...hooks, trace }));
+    else if (mode === "version") result = trace.step("install-version", () => runVersion(ctx, tempDir, cwd));
+    else if (mode === "workflows") result = trace.step("install-workflows", () => runWorkflows(ctx, tempDir, cwd, { ...hooks, trace }));
 
     // 통합 후 IDE 스킬 제안 (.sh L4557 offer_ide_tools_install — 사전 질문 게이트, 기본 N)
     // 업데이트 모드(#502): 이미 설치된 IDE 스킬만 질문 없이 최신화 (미설치 IDE는 건드리지 않음)
@@ -365,12 +378,16 @@ export async function runInteractive(baseCtx, { cwd = process.cwd(), source = {
 
     // 마이그레이션 기록 (#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 });
+    const recordArtifacts = mode === "full" || mode === "workflows";
+    // 경로는 먼저 계산하고 실제 쓰기는 완료 화면 뒤로 미룬다 — 요약까지 터미널 미러에 담기 위함 (#561)
+    const files = recordArtifacts
+      ? trace.paths({ fromVersion: existing?.templateVersion || "", toVersion: templateVersion, now })
+      : null;
+    if (recordArtifacts) {
       migrationGuidePath = appendGuideEntry(cwd, {
         now, mode, types, repoName,
         templateFrom: existing?.templateVersion || "", templateTo: templateVersion,
-        options: { deploy: deployTarget, publish: publishTargets, secretBackup: includeSecretBackup, coderabbit: codeReviewCoderabbit, changelogProvider, intent, semverAuto },
+        options: { deploy: deployTarget, publish: publishTargets, secretBackup: includeSecretBackup, coderabbit: codeReviewCoderabbit, changelogProvider, intent, semverAuto , appRelease },
         branches: { defaultBranch: branch, deployBranch, ready: deployBranchReady, created: deployBranchCreated },
         breaking: breakingReport, migrations: migrationsResult, orphans: orphanReport,
         events: trace.events, counters: { skipped: result?.workflows?.skipped ?? 0 },
@@ -382,11 +399,35 @@ export async function runInteractive(baseCtx, { cwd = process.cwd(), source = {
     io.summary?.({
       mode, types, version, deployBranch, deployBranchReady, migrationGuidePath,
       counters: { workflows: result?.workflows?.copied ?? 0, workflowFiles: result?.workflows?.copiedFiles ?? [], utilModules: 0 },
+      verification: result?.verification,      // #549 설치 검증 결과
+      logDir: files ? MIGRATION_DIR : null,    // #561 기록 위치 안내
+      logFile: files?.logFile ?? null,
+      traceFile: files?.traceFile ?? null,
     }, cwd);
     io.outro?.(`통합 완료 — ${mode} 모드로 설치했습니다.`);
+
+    // 완료 화면까지 캡처한 뒤 종료하고 기록한다 (#561)
+    trace.event("run", "end", mode || "", {
+      workflowsCopied: result?.workflows?.copied ?? 0,
+      workflowsSkipped: result?.workflows?.skipped ?? 0,
+    });
+    if (recordArtifacts) {
+      trace.finalize({ targetRoot: cwd, fromVersion: existing?.templateVersion || "", toVersion: templateVersion, now });
+    } else {
+      trace.mirrorStop();
+    }
     return 0;
+  } catch (err) {
+    trace.event("run", "error", "interactive", {
+      message: err?.message || String(err),
+      stack: String(err?.stack || "").split("\n").slice(0, 3).join(" | "),
+    });
+    throw err;
   } finally {
-    trace.mirrorStop();
+    // 어떤 경로로 빠져나가든 기록을 남긴다 (#561) — 중간 취소·예외 포함.
+    // finalize는 멱등이라 정상 경로에서 이미 호출됐으면 여기서는 아무 일도 하지 않는다.
+    trace.finalize({ targetRoot: cwd, fromVersion: traceFrom, toVersion: traceTo, now: clock?.now || "" });
+    disarmSignals();
     remove(tempDir);
   }
 }

package/src/commands/workflows.js

@@ -35,10 +35,20 @@ export function runWorkflows(context, tempDir, targetRoot = ".", hooks = {}) {
 
   // 설치 후 검증 (#549) — 워크플로우만 설치하는 모드라 오히려 더 필요하다.
   const verification = verifyInstall(targetRoot);
-  hooks.trace?.emit?.("verify", "scan", {
+  // detail 키 이름 주의: run-trace의 민감값 가드가 pat|token|secret|password|credential을
+  // 키에서 걸러낸다(#494). 여기서 다루는 값은 비밀이 아니라 "치환 플레이스홀더 이름"과
+  // "등록이 필요한 키 이름"이라 가드에 걸리지 않는 이름을 쓴다 — 가드 자체는 우회하지 않는다.
+  hooks.trace?.event("verify", "scan", "", {
     unresolved: verification.unresolved.length,
-    secrets: verification.secrets.size,
+    requiredKeys: verification.secrets.size,
   });
+  // 미치환 값은 배포 시점에 실패할 자리다 — 어느 파일 몇 번째 줄인지 로그에 남긴다.
+  for (const u of verification.unresolved) {
+    hooks.trace?.event("verify", "unresolved", u.filename, { line: u.line, placeholder: u.token });
+  }
+  for (const [name, users] of verification.secrets) {
+    hooks.trace?.event("verify", "required-key", name, { workflows: users });
+  }
 
   return { workflows: wf, verification };
 }

package/src/core/copy/workflows.js

@@ -87,26 +87,52 @@ 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 });
 
-  // (1) common — unchanged면 스킵, 아니면 무조건 덮어쓰기
+  // (1) common — 타입별과 동일한 판정·보호를 받는다 (#560).
+  //
+  // 종전에는 "unchanged면 스킵, 아니면 무조건 덮어쓰기"였다. 그런데 릴리스 파이프라인처럼
+  // 프로젝트마다 뒤에 붙일 일이 다른 워크플로우는 common에 있어도 사용자가 고쳐 쓸 수밖에
+  // 없다. 고치지 않고는 쓸 수 없는 파일을, 고치면 백업도 없이 날아가는 규칙으로 관리하고
+  // 있었다. common/deploy조차 .bak을 남기는데 본체만 아무것도 남기지 않았다.
   const commonDir = join(projectTypesDir, "common");
   if (exists(commonDir)) {
+    const commonEnv = envOptsFor("common");
+    const commonClass = classify(commonDir, workflowsDir, commonEnv, baseline);
     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"))) {
+      if (commonClass.unchanged.includes(filename)) {
         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" });
+      // 사용자가 손댄 적 없고 템플릿만 바뀐 파일 — 물어볼 것 없이 최신으로 올린다(종전과 동일).
+      if (commonClass.newFiles.includes(filename) || commonClass.upstream.includes(filename)) {
+        copyFileSync(join(commonDir, filename), join(workflowsDir, filename));
+        counters.copied++;
+        counters.copiedFiles.push(filename);
+        trace?.event("copy", commonClass.upstream.includes(filename) ? "upstream-updated" : "copied",
+                     filename, { group: "common" });
+        continue;
+      }
+      // 여기부터는 changed — "지금 템플릿 렌더 결과 ≠ 설치본"이다. 둘로 갈린다.
+      const dst = join(workflowsDir, filename);
+      const modified = isUserModified(baseline, filename, readFileSync(dst, "utf8"));
+      if (modified === null) {
+        // 판정 불가(기준점 없음 = 기존 통합 레포). common의 종전 계약은 "항상 최신으로 갱신"이라
+        // 여기서 skip하면 기존 레포가 업데이트를 영영 못 받는다. 계약은 지키되 되돌릴 수단을
+        // 남긴다 — 덮어쓰기 전 .bak. (#560: common/deploy조차 .bak을 남기는데 본체만 없었다)
+        renameSync(dst, dst + ".bak");
+        copyFileSync(join(commonDir, filename), dst);
+        counters.copied++;
+        counters.copiedFiles.push(filename);
+        trace?.event("copy", "replaced-bak", filename, { group: "common", reason: "baseline-absent" });
+        continue;
+      }
+      // 사용자가 손댄 것이 확인된 파일 — 결정에 따라 처리(미지정이면 유지).
+      applyDecision(decisions.get(filename), commonDir, workflowsDir, filename, counters, trace);
     }
   }
 
@@ -170,14 +196,14 @@ export function copyWorkflows(context, tempDir, targetRoot = ".", hooks = {}) {
   // (7) 기준점 기록 (#557) — 다음 업데이트가 "누가 바꿨는지"를 가릴 근거.
   //     이번에 실제로 쓴 파일만 installed를 갱신한다. 유지(skip)한 파일에 우리가 쓴 것처럼
   //     기록하면 다음 업데이트에서 사용자 수정이 조용히 덮인다.
-  recordBaseline(workflowsDir, targetRoot, counters, baseline, context.templateVersion, context.now);
+  recordBaseline(workflowsDir, targetRoot, counters, baseline, context.templateVersion, context.now, trace);
 
   return counters;
 }
 
 // 설치 직후의 디스크 내용을 기준점으로 남긴다. 실패해도 통합을 막지 않는다 —
 // 기준점이 없으면 다음 업데이트가 종전 2-way 판정으로 폴백할 뿐이다.
-function recordBaseline(workflowsDir, targetRoot, counters, previous, templateVersion, now) {
+function recordBaseline(workflowsDir, targetRoot, counters, previous, templateVersion, now, trace = null) {
   try {
     const entries = new Map();
     for (const f of counters.copiedFiles || []) {
@@ -188,6 +214,7 @@ function recordBaseline(workflowsDir, targetRoot, counters, previous, templateVe
       entries.set(f, { installed: sha256(content), rendered: sha256(content) });
     }
     if (entries.size === 0 && previous) return; // 새로 쓴 게 없으면 기존 기준점을 건드리지 않는다
+    trace?.event("baseline", "recorded", "", { files: entries.size, hadPrevious: !!previous });
     writeBaseline(targetRoot, {
       templateVersion: templateVersion || "unknown",
       installedAt: now || "",
@@ -233,8 +260,22 @@ export function listWorkflowConflicts(context, tempDir, targetRoot = ".") {
   // 설치 시점 기준점(#557) — 없으면 null이고 classify가 종전 2-way로 폴백한다.
   const baseline = readBaseline(targetRoot);
   const projectTypesDir = join(tempDir, PATHS.workflowsDir, PATHS.projectTypesDir);
-  const conflicts = []; // [{ filename, type }] — 엔진 처리 순서와 동일 (타입 순회 → 직하위 → server-deploy)
+  const conflicts = []; // [{ filename, type }] — 엔진 처리 순서와 동일 (common → 타입 순회 → server-deploy)
   const branches = { defaultBranch: branch || "main", deployBranch: deployBranch || "develop" }; // #477 — 엔진과 동일 기준
+
+  // common (#560) — 사용자가 손댄 것이 "확인된" 파일만 질문 대상이다.
+  // 기준점이 없어 판정 불가인 파일은 엔진이 .bak을 남기고 덮어쓰므로 질문하지 않는다.
+  const commonDir = join(projectTypesDir, "common");
+  if (exists(commonDir)) {
+    const commonEnv = { type: "common", projectPath: ".", repoName, resolvers, branches };
+    for (const f of classify(commonDir, workflowsDir, commonEnv, baseline).changed) {
+      const dst = join(workflowsDir, f);
+      if (!existsSync(dst)) continue;
+      if (isUserModified(baseline, f, readFileSync(dst, "utf8")) !== true) continue;
+      conflicts.push({ filename: f, type: "common" });
+    }
+  }
+
   for (const type of types) {
     const envOpts = { type, projectPath: paths.get(type) || ".", repoName, resolvers, branches };
     const typeDir = join(projectTypesDir, type);
@@ -279,7 +320,7 @@ function copyWorkflowsForType(type, projectTypesDir, workflowsDir, ctx, counters
     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 }); }
     // 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 }); }
+    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" }); }
     // changed: 결정 Map에 따라 처리 (미지정=skip → 현행 force 동작과 동일)
     for (const f of changed) applyDecision(decisions.get(f), typeDir, workflowsDir, f, counters, trace);
   }
@@ -290,7 +331,7 @@ function copyWorkflowsForType(type, projectTypesDir, workflowsDir, ctx, counters
     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` }); }
+    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 changed) applyDecision(decisions.get(f), serverDeployDir, workflowsDir, f, counters, trace);
   }
 

package/src/core/migration-guide.js

@@ -1,5 +1,5 @@
 // 마이그레이션 가이드 (#493) — Layer 1 큐레이션 문서.
-// 마법사(full/workflows) 실행이 끝나면 대상 레포의 docs/projectops/migration/PROJECTOPS-MIGRATION-GUIDE.md에
+// 마법사(full/workflows) 실행이 끝나면 대상 레포의 .github/.projectops/logs/PROJECTOPS-MIGRATION-GUIDE.md에
 // "고정 헤더(최초 1회) + 실행 엔트리(append-only)"를 남긴다. 사람용 동적 체크리스트와
 // AI Agent용 yaml 메타데이터를 한 엔트리에 담고, run-trace(#494)의 events를 단일 소스로 소비한다.
 import { join } from "node:path";
@@ -156,7 +156,7 @@ export function renderGuideEntry(report) {
   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 ?? "")}, semver_auto: ${r.options?.semverAuto === true} }`);
+  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 ?? "")}, semver_auto: ${r.options?.semverAuto === true}, app_release: ${r.options?.appRelease === true} }`);
   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)}`);

package/src/core/run-trace.js

@@ -5,7 +5,18 @@
 import { join } from "node:path";
 import { writeText } from "./fsutil.js";
 
-export const MIGRATION_DIR = "docs/projectops/migration";
+// 진단 로그 위치 (#561). docs/ 아래(추적 대상)에서 옮겼다 — 이 기록은 사람이 읽는 문서가
+// 아니라 Agent가 "지난 실행에서 무슨 일이 있었나"를 확인하는 자료다.
+// 폴더 안에 .gitignore를 함께 써서 폴더가 자기 규칙을 들고 다닌다(루트 .gitignore 무수정).
+// 형제인 .github/.projectops/baseline.json은 팀원 공유 자산이라 계속 추적된다.
+export const MIGRATION_DIR = ".github/.projectops/logs";
+export const LOGS_GITIGNORE = [
+  "# projectops 실행 진단 로그 — 저장소에 추적하지 않습니다.",
+  "# 이 폴더는 마법사가 실행할 때마다 기록을 남기며, 커밋 대상이 아닙니다.",
+  "*",
+  "!.gitignore",
+  "",
+].join("\n");
 export const TRACE_SCHEMA = 1;
 
 // 민감값 가드 — PAT·토큰·시크릿·비밀번호는 어떤 이벤트에도 남기지 않는다 (#494 안전 규칙).
@@ -20,6 +31,60 @@ export function scrubDetail(detail) {
   return out;
 }
 
+// 단계 소요 시간. 시계를 고정 주입한 경우(테스트)는 생략해 결과가 흔들리지 않게 한다.
+function elapsed(t0, clockIso) {
+  return clockIso ? {} : { ms: Date.now() - t0 };
+}
+
+// 이벤트를 서버 로그 스타일 한 줄로 만든다 (#561).
+//   [시각] 레벨 phase/action  대상  key=value ...
+// 레벨은 action에서 유추한다 — 조치가 필요한 것(미치환·취소·실패)만 눈에 띄어야 한다.
+// 레벨은 "무엇을 먼저 봐야 하는가"로 나눈다.
+//   ERROR — 실패. 반드시 조치해야 한다.
+//   WARN  — 그대로 두면 나중에 실패할 수 있는 것, 사용자가 판단해야 하는 것.
+//   INFO  — 실행의 큰 줄기. 단계 경계와 확정된 판단.
+//   DEBUG — 건별 상세(파일 하나, 치환 하나). 기본값은 INFO지만 전부 파일에는 남는다.
+//
+// DEBUG가 파일에 남는 이유: 문제가 터진 뒤에 "그때 DEBUG를 켰더라면"은 소용이 없다.
+// 화면은 조용히 두되 파일에는 전부 적는다.
+const ERROR_ACTIONS = new Set(["error", "failed"]);
+const WARN_ACTIONS = new Set([
+  "unresolved", "cancelled", "skipped-conflict", "leftover-old-gen",
+  "neutralized", "detected", "replaced-bak",
+]);
+const DEBUG_ACTIONS = new Set([
+  "copied", "skipped-unchanged", "excluded", "substituted", "branch-substituted",
+  "required-key", "project-path", "upstream-updated", "template-added",
+  "scripts", "config", "util", "templates",
+]);
+export function levelOf(action) {
+  if (ERROR_ACTIONS.has(action)) return "ERROR";
+  if (WARN_ACTIONS.has(action)) return "WARN";
+  if (DEBUG_ACTIONS.has(action)) return "DEBUG";
+  return "INFO";
+}
+export function formatLogLine(e) {
+  const time = String(e.ts || "").replace(/^.*T/, "").replace(/Z$/, "");
+  const level = levelOf(e.action).padEnd(5);
+  const tag = `${e.phase}/${e.action}`.padEnd(24);
+  const parts = [`[${time}] ${level} ${tag} ${e.target || ""}`.trimEnd()];
+  if (e.detail && typeof e.detail === "object") {
+    const kv = Object.entries(e.detail)
+      .filter(([, v]) => v !== null && v !== undefined)
+      .map(([k, v]) => `${k}=${Array.isArray(v) ? (v.join("|") || "[]") : v}`);
+    if (kv.length) parts.push(`  ${kv.join(" ")}`);
+  }
+  return parts.join("") + "\n";
+}
+
+// 색상·커서 제어 시퀀스 제거 (#561). 로그 파일은 에디터·Agent가 읽으므로 이스케이프가
+// 그대로 남으면 판독을 방해한다. 터미널 출력 자체는 건드리지 않는다(사본만 정제).
+// eslint-disable-next-line no-control-regex
+const ANSI_RE = /\u001b\[[0-9;]*[A-Za-z]/g;
+export function stripAnsi(text) {
+  return String(text).replace(ANSI_RE, "");
+}
+
 // now("YYYY-MM-DD HH:MM:SS") → 파일명 스탬프 "YYYYMMDD_HHMMSS". 형식이 아니면 "run" 폴백(테스트 주입 clock 안전).
 export function stampFromNow(now) {
   const digits = String(now ?? "").replace(/[^0-9]/g, "");
@@ -32,6 +97,8 @@ export function createRunTrace({ clockIso = null } = {}) {
   const events = [];
   const lines = [];
   let restore = null;
+  let finalized = false;
+  let signalsArmed = false;
 
   const nowIso = () => clockIso ?? new Date().toISOString().replace(/\.\d+Z$/, "Z");
 
@@ -40,11 +107,14 @@ export function createRunTrace({ clockIso = null } = {}) {
     lines,
 
     // 이벤트 1건 기록. detail은 민감키 스크럽 후 저장.
+    // 같은 내용을 사람이 읽는 로그 라인으로도 남긴다 (#561) — 터미널에 보이지 않는 내부
+    // 동작까지 .log 한 파일에서 시간순으로 따라갈 수 있어야, 문제가 생겼을 때 바로 대응된다.
     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);
+      lines.push(formatLogLine(e));
       return e;
     },
 
@@ -55,7 +125,10 @@ export function createRunTrace({ clockIso = null } = {}) {
       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 { /* 미러 실패는 실행에 영향 없음 */ }
+        try {
+          const s = typeof chunk === "string" ? chunk : chunk.toString("utf8");
+          lines.push(stripAnsi(s));
+        } 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]); };
@@ -66,24 +139,106 @@ export function createRunTrace({ clockIso = null } = {}) {
       if (restore) { restore(); restore = null; }
     },
 
-    // Layer 2/3 파일 기록 — docs/projectops/migration/{stamp}_v{from}_to_v{to}.{jsonl,log}
+    // 단계 실행 래퍼 (#561) — 서버 로그처럼 "어디에 들어갔다 언제 나왔고 얼마 걸렸는지"를
+    // 자동으로 남긴다. 개별 호출부에 start/done을 흩뿌리면 빠뜨리는 자리가 생긴다.
+    // 예외가 나면 failed로 기록하고 그대로 던진다 — 삼키지 않는다.
+    step(name, fn, detail = null) {
+      this.event("step", "start", name, detail);
+      const t0 = Date.now();
+      try {
+        const out = fn();
+        this.event("step", "done", name, elapsed(t0, clockIso));
+        return out;
+      } catch (err) {
+        this.event("step", "failed", name, { ...elapsed(t0, clockIso), message: err?.message || String(err) });
+        throw err;
+      }
+    },
+
+    // async 버전 — 대화형 단계(질문 대기 포함)에 쓴다.
+    async stepAsync(name, fn, detail = null) {
+      this.event("step", "start", name, detail);
+      const t0 = Date.now();
+      try {
+        const out = await fn();
+        this.event("step", "done", name, elapsed(t0, clockIso));
+        return out;
+      } catch (err) {
+        this.event("step", "failed", name, { ...elapsed(t0, clockIso), message: err?.message || String(err) });
+        throw err;
+      }
+    },
+
+    // 강제 종료(Ctrl+C)에도 기록을 남긴다 (#561).
+    // SIGINT 기본 동작으로 프로세스가 즉사하면 finally가 돌지 않는다 — 사용자가 끊었을 때야말로
+    // "어디까지 갔는지"가 가장 궁금한 순간이라, 여기서 놓치면 로그의 쓸모가 절반이다.
+    // 핸들러는 기록만 하고 원래대로 종료시킨다(동작을 바꾸지 않는다).
+    armSignals(opts = {}) {
+      if (signalsArmed) return () => {};
+      signalsArmed = true;
+      const self = this;
+      const handlers = [];
+      for (const sig of ["SIGINT", "SIGTERM"]) {
+        const h = () => {
+          self.event("run", "cancelled", sig, { reason: "사용자 강제 종료(신호 수신)" });
+          self.finalize(opts);
+          process.removeListener(sig, h);
+          process.kill(process.pid, sig);   // 원래 종료 동작으로 넘긴다
+        };
+        process.on(sig, h);
+        handlers.push([sig, h]);
+      }
+      return () => {
+        for (const [sig, h] of handlers) process.removeListener(sig, h);
+        signalsArmed = false;
+      };
+    },
+
+    // 어떤 경로로 끝나든 기록을 남긴다 (#561) — 정상 완주·중간 취소·예외·강제 종료.
+    // 사용자가 중간에 끊었을 때야말로 "어디까지 갔는지"가 가장 궁금한 순간이라,
+    // 완주했을 때만 남기는 기록은 쓸모가 절반이다.
+    //
+    // 두 번 불려도 한 번만 쓴다(정상 경로 + finally 중복 호출 대비). 실패는 삼킨다 —
+    // 기록 실패가 종료를 막아선 안 된다.
+    finalize(opts = {}) {
+      if (finalized) return null;
+      finalized = true;
+      try {
+        this.mirrorStop();
+        return this.write(opts);
+      } catch {
+        return null;
+      }
+    },
+
+    // 기록 파일 경로만 계산한다 (쓰지 않음). 완료 화면까지 캡처하려면 write를 화면 출력 뒤로
+    // 미뤄야 하는데, 가이드 엔트리는 그 전에 traceFile 경로를 참조해야 해서 둘을 분리했다.
+    paths({ fromVersion = "", toVersion = "", now = "" } = {}) {
+      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}`;
+      return { base, traceFile: `${MIGRATION_DIR}/${base}.jsonl`, logFile: `${MIGRATION_DIR}/${base}.log` };
+    },
+
+    // Layer 2/3 파일 기록 — .github/.projectops/logs/{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 planned = this.paths({ fromVersion, toVersion, now });
+      // 폴더 규칙을 매번 보장한다 — 사용자가 지웠거나 폴더가 새로 생겨도 추적되지 않게.
+      writeText(join(targetRoot, `${MIGRATION_DIR}/.gitignore`), LOGS_GITIGNORE);
       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");
+      writeText(join(targetRoot, planned.traceFile), [header, ...events.map((e) => JSON.stringify(e))].join("\n") + "\n");
       let logFile = null;
       if (lines.length > 0) {
-        logFile = `${MIGRATION_DIR}/${base}.log`;
+        logFile = planned.logFile;
         writeText(join(targetRoot, logFile), lines.join(""));
       }
-      return { traceFile, logFile };
+      return { traceFile: planned.traceFile, logFile };
     },
   };
 }

package/src/index.js

@@ -14,9 +14,9 @@ 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 { createRunTrace, MIGRATION_DIR } from "./core/run-trace.js";
 import { appendGuideEntry } from "./core/migration-guide.js";
-import { resolveProjectPaths } from "./core/paths-resolve.js";
+import { resolveProjectPaths, markerForType } from "./core/paths-resolve.js";
 import { applicableTargets } from "./core/options-ask.js";
 import { printBannerCompact } from "./ui/banner.js";
 import { printSummary } from "./ui/summary.js";
@@ -94,23 +94,59 @@ export async function run(argv, { cwd = process.cwd(), source = { type: "git" },
     return 1;
   }
 
+  // 실행 트레이스 (#494/#561) — 감지·판단 단계부터 기록해야 "왜 이렇게 정해졌는지"가 남는다.
+  const trace = createRunTrace();
+  const recordArtifacts = opts.mode === "full" || opts.mode === "workflows";
+  let disarmSignals = () => {};
+  if (recordArtifacts) {
+    trace.mirrorStart();
+    // Ctrl+C로 끊어도 여기까지의 기록이 남는다 (#561). 경로는 아래에서 확정되지만
+    // 신호는 언제든 올 수 있으므로 targetRoot만으로 먼저 무장한다.
+    disarmSignals = trace.armSignals({ targetRoot: cwd, now: "" });
+  }
+
   // 기존 version.yml 로드 — version/version_code/project_paths 보존의 단일 진실 (.sh L2208~2239 SSoT)
   const vyPath = join(cwd, "version.yml");
   const existing = existsSync(vyPath) ? parseExisting(readFileSync(vyPath, "utf8")) : null;
+  trace.event("detect", "existing-install", existing ? "found" : "none", {
+    templateVersion: existing?.templateVersion || null,
+    version: existing?.version || null,
+    types: existing?.types || null,
+  });
 
   // 감지 (CLI 인자 우선, 없으면 자동 감지 — version.yml 우선 규칙은 detectTypes/detectVersion 내부)
   const types = opts.types.length ? opts.types : detectTypes(cwd);
+  trace.event("detect", "types", types.join(",") || "(없음)", {
+    source: opts.types.length ? "cli-flag(--type)" : "auto-detect(마커 파일 스캔)",
+  });
   // version: 기존 version.yml 최우선(SSoT — 재실행 시 덮어쓰기 방지) → CLI 지정 → 파일 감지
   const version = (existing?.version) || opts.version || detectVersion(cwd);
+  trace.event("detect", "version", version, {
+    source: existing?.version ? "version.yml(기존값 보존)"
+      : (opts.version ? "cli-flag(--project-version)" : "프로젝트 파일 감지"),
+  });
   const versionCode = existing?.versionCode ?? 1; // 기존 빌드번호 보존 (.sh L2208~2221)
   const branch = detectDefaultBranch(cwd);
   const repoName = detectRepoName(cwd);
+  trace.event("detect", "repo", repoName || "(미상)", { defaultBranch: branch, versionCode });
   // 경로 확정 (.sh resolve_project_paths 비대화형 경로 — --paths 우선 → 저장값 → 후보 1개 자동 → 루트 폴백)
   const paths = await resolveProjectPaths({
     root: cwd, types, paths: parsePathsCsv(opts.pathsCsv),
     existingPaths: existing?.paths ?? new Map(), force: true, tty: false, io: {},
   });
 
+  for (const [ty, pth] of paths) {
+    // 근거로 "무엇을 보고 그 경로로 정했는지"까지 남긴다 — 경로가 틀렸을 때 추적의 시작점이다.
+    const marker = markerForType(ty);
+    const at = pth === "." ? marker : `${pth}/${marker}`;
+    trace.event("detect", "project-path", ty, {
+      path: pth,
+      marker: existsSync(join(cwd, at)) ? at : `${at} (없음)`,
+      source: parsePathsCsv(opts.pathsCsv).has(ty) ? "cli-flag(--paths)"
+        : (existing?.paths?.has(ty) ? "version.yml(저장값)" : "마커 파일 탐색"),
+    });
+  }
+
   const { now, today } = clock || utcNow();
   const tempDir = join(cwd, PATHS.tempDir);
 
@@ -129,10 +165,32 @@ export async function run(argv, { cwd = process.cwd(), source = { type: "git" },
   }
   // 적용 불가 타겟 조용한 정리 (#498) — 대화형과 동일 규칙. 타입에 성립하지 않는 축 값은
   // 복사 결과가 동일하므로 경고 없이 none/교집합으로 정리한다 (모바일 앱/basic 단독 등).
+  const beforeCleanup = { deploy: deployTarget, publish: [...publishTargets] };
   if (deployTarget !== "none" && !applicable.deploy.includes(deployTarget)) deployTarget = "none";
   publishTargets = publishTargets.filter((t) => applicable.publish.includes(t));
   if (types.length > 0 && applicable.deploy.length === 0 && applicable.publish.length === 0) intent = "none";
 
+  // 축 확정 근거 (#561) — "왜 이 값인가"가 가장 헷갈리는 자리다.
+  // CLI 플래그 / 저장값 / intent 유도 / 타입 적용성 정리 중 무엇이 이겼는지 남긴다.
+  trace.event("resolve", "intent", String(intent ?? "(미설정)"), {
+    source: opts.intent != null ? "cli-flag(--intent)"
+      : (existing?.options?.intent ? "version.yml(저장값)" : "미지정 → deploy/publish에서 역추론"),
+  });
+  trace.event("resolve", "deploy", deployTarget, {
+    source: opts.deployTarget != null ? "cli-flag(--deploy)"
+      : (existing?.options?.deploy ? "version.yml(저장값)" : "기본값"),
+    applicableForTypes: applicable.deploy,
+    adjusted: beforeCleanup.deploy !== deployTarget
+      ? `${beforeCleanup.deploy} → ${deployTarget} (선택 타입에 적용 불가)` : null,
+  });
+  trace.event("resolve", "publish", publishTargets.join(",") || "(없음)", {
+    source: opts.publishTargets != null ? "cli-flag(--publish)"
+      : (existing?.options?.publish ? "version.yml(저장값)" : "기본값"),
+    applicableForTypes: applicable.publish,
+    adjusted: beforeCleanup.publish.join(",") !== publishTargets.join(",")
+      ? `${beforeCleanup.publish.join(",") || "(없음)"} → ${publishTargets.join(",") || "(없음)"} (적용 불가 정리)` : null,
+  });
+
   const context = createContext({
     mode: opts.mode, force: true, types, version, versionCode, branch,
     paths,
@@ -160,66 +218,111 @@ export async function run(argv, { cwd = process.cwd(), source = { type: "git" },
     now, today,
   });
 
+  // 최종 확정값 스냅샷 (#561) — 이 한 줄로 "무엇이 어떻게 설치될 것인지"가 고정된다.
+  trace.event("resolve", "context", opts.mode || "", {
+    types, version, versionCode, branch,
+    deploy: deployTarget, publish: publishTargets, intent,
+    secretBackup: context.includeSecretBackup,
+    changelogProvider: context.changelogProvider,
+    coderabbit: context.codeReviewCoderabbit,
+    deployBranch: context.deployBranch || "(미지정 → develop 폴백)",
+    recordMode: context.recordMode,
+  });
+  trace.event("resolve", "semver-auto", String(context.semverAuto), {
+    reason: existing?.options?.semverAuto != null ? "version.yml 저장값 보존"
+      : (existing ? "기존 통합 레포 → 예고 없는 버전 상승 방지를 위해 false"
+                  : "신규 통합 → true"),
+  });
+  trace.event("resolve", "app-release", String(context.appRelease), {
+    reason: existing?.options?.appRelease != null ? "version.yml 저장값 보존" : "미설정(키를 쓰지 않음)",
+  });
+
   let result = null;
-  // 실행 트레이스 (#494) — 비대화형도 이벤트 기록 (터미널 미러는 CLI 실행에서만 유의미하므로 함께 켠다)
-  const trace = createRunTrace();
-  const recordArtifacts = opts.mode === "full" || opts.mode === "workflows";
+  // trace/recordArtifacts는 감지 단계 기록을 위해 위에서 이미 생성했다 (#561)
   let breakingReport = null;
   let migrationsResult = null;
   let orphanPending = [];
-  if (recordArtifacts) trace.mirrorStart();
+  // 실행 경계(#561) — 로그만 보고 "무엇을 어떤 인자로 돌렸는지"를 알 수 있어야 한다.
+  trace.event("run", "start", opts.mode || "", {
+    cli: "non-interactive", types, version, branch,
+    force: true, deploy: deployTarget, publish: publishTargets, intent,
+  });
   try {
-    acquireTemplate({ tempDir, source });
+    trace.step("acquire-template", () => acquireTemplate({ tempDir, source }), { source: source?.type || "git" });
     context.templateVersion = readTemplateVersion(tempDir);
+    trace.event("detect", "template-version", context.templateVersion, { tempDir: PATHS.tempDir });
 
     // 비대화형 축약 배너 (#446 확정 — 1줄, 로그 오염 최소)
     printBannerCompact({ version: context.templateVersion, mode: opts.mode });
 
     // Breaking Changes 게이트 (.sh execute_integration L4415~4420 등가 — 비대화형은 경고 후 진행)
-    const proceed = await runBreakingCheck({
+    const proceed = await trace.stepAsync("breaking-check", () => runBreakingCheck({
       cwd, tempDir, templateVersion: context.templateVersion,
       onItems: (items) => { breakingReport = items; },
-    });
-    if (!proceed) return 0;
+    }));
+    trace.event("breaking", "result", proceed ? "proceed" : "halt", { items: (breakingReport ?? []).length });
+    if (!proceed) {
+      trace.event("run", "cancelled", "breaking-gate", { reason: "호환성 경고로 중단" });
+      return 0;
+    }
 
     // 레거시 마이그레이션 (#470) — 워크플로우를 만지는 모드에서만. 비대화형은 safe 티어 자동 적용.
     if (recordArtifacts) {
-      migrationsResult = await runMigrations({ targetRoot: cwd });
+      migrationsResult = await trace.stepAsync("legacy-migrations", () => 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 (recordArtifacts) {
-      const orphans = detectOrphanWorkflows({ tempDir, targetRoot: cwd, selectedTypes: types });
+      const orphans = trace.step("orphan-scan",
+        () => detectOrphanWorkflows({ tempDir, targetRoot: cwd, selectedTypes: types }),
+        { selectedTypes: types });
       orphanPending = orphans.map((o) => o.filename);
+      for (const o of orphans) trace.event("orphan", "detected", o.filename, { type: o.type, action: "안내만(비대화형)" });
       for (const o of orphans) {
         console.error(`⚠️ 선택되지 않은 타입(${o.type})의 워크플로우가 남아있습니다: ${o.filename} — 대화형 마법사(npx projectops)에서 정리할 수 있습니다.`);
       }
     }
 
     switch (opts.mode) {
-      case "full": result = runFull(context, tempDir, cwd, { trace }); break;
-      case "version": result = runVersion(context, tempDir, cwd); break;
-      case "workflows": result = runWorkflows(context, tempDir, cwd, { trace }); break;
-      case "issues": result = runIssues(context, tempDir, cwd); break;
+      case "full": result = trace.step("install-full", () => runFull(context, tempDir, cwd, { trace })); break;
+      case "version": result = trace.step("install-version", () => runVersion(context, tempDir, cwd)); break;
+      case "workflows": result = trace.step("install-workflows", () => runWorkflows(context, tempDir, cwd, { trace })); break;
+      case "issues": result = trace.step("install-issues", () => runIssues(context, tempDir, cwd)); break;
       default:
         // 알 수 없는 모드 → .sh와 동일하게 복사 0건, 에러 아님
         break;
     }
+  } catch (err) {
+    // 실패 원인을 로그에 남긴다 (#561) — 서버 로그처럼 사후에 바로 짚을 수 있어야 한다.
+    trace.event("run", "error", opts.mode || "", {
+      message: err?.message || String(err),
+      stack: String(err?.stack || "").split("\n").slice(0, 3).join(" | "),
+    });
+    throw err;
   } finally {
-    trace.mirrorStop();
+    // 예외로 빠져나가도 기록을 남긴다 (#561). finalize는 멱등 — 정상 경로에서 이미
+    // 호출됐으면 여기서는 아무 일도 하지 않는다.
+    if (recordArtifacts) {
+      trace.finalize({ targetRoot: cwd, fromVersion: existing?.templateVersion || "", toVersion: context.templateVersion, now });
+    }
+    disarmSignals();
     remove(tempDir);
   }
 
   // 마이그레이션 기록 (#493/#494) — Layer 2/3 트레이스 파일 + Layer 1 가이드 엔트리
   let migrationGuidePath = null;
+  // 기록 파일 경로는 먼저 계산하고(가이드가 참조), 실제 쓰기는 완료 화면 출력 뒤로 미룬다 —
+  // 그래야 터미널 미러에 완료 화면까지 담긴다 (#561).
+  const files = recordArtifacts
+    ? trace.paths({ fromVersion: existing?.templateVersion || "", toVersion: context.templateVersion, now })
+    : 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, semverAuto: context.semverAuto },
+      options: { deploy: deployTarget, publish: publishTargets, secretBackup: context.includeSecretBackup, coderabbit: context.codeReviewCoderabbit, changelogProvider: context.changelogProvider, intent, semverAuto: context.semverAuto , appRelease: context.appRelease },
       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 },
@@ -232,6 +335,20 @@ export async function run(argv, { cwd = process.cwd(), source = { type: "git" },
     mode: opts.mode, types, version, deployBranch: context.deployBranch, migrationGuidePath,
     counters: { workflows: result?.workflows?.copied ?? 0, workflowFiles: result?.workflows?.copiedFiles ?? [], utilModules: 0 },
     verification: result?.verification,   // #549 설치 후 검증 결과 (full/workflows 모드에서만 존재)
+    logDir: files ? MIGRATION_DIR : null,   // #561 기록 위치 안내
+    logFile: files?.logFile ?? null,
+    traceFile: files?.traceFile ?? null,
   }, cwd);
+
+  // 완료 화면까지 캡처한 뒤 종료하고 기록한다 (#561)
+  trace.event("run", "end", opts.mode || "", {
+    workflowsCopied: result?.workflows?.copied ?? 0,
+    workflowsSkipped: result?.workflows?.skipped ?? 0,
+  });
+  if (recordArtifacts) {
+    trace.finalize({ targetRoot: cwd, fromVersion: existing?.templateVersion || "", toVersion: context.templateVersion, now });
+  } else {
+    trace.mirrorStop();
+  }
   return 0;
 }

package/src/ui/summary.js

@@ -130,6 +130,17 @@ export function printSummary(ctx, targetRoot = ".") {
   err("  📖 TEMPLATE REPO: https://github.com/Cassiiopeia/projectops");
   err("  📚 워크플로우 가이드: .github/workflows/project-types/README.md");
   // #493 — 이번 실행의 마이그레이션 기록. "뭐가 남았고 AI에게 어떻게 시키는지"가 바로 보이게 행동 유도형으로 안내.
+  // 실행 기록 위치 (#561) — 무슨 일이 있었는지 나중에 확인할 자리를 알린다.
+  // 폴더가 아니라 이번 실행의 파일을 정확히 짚어준다 — 실행이 쌓이면 어느 것이 이번 건인지
+  // 모른다. 붙여넣어 바로 열 수 있는 경로가 목적이다.
+  if (ctx?.logFile || ctx?.logDir) {
+    err(`  📁 실행 로그: ${ctx.logFile || `${ctx.logDir}/`}`);
+    if (ctx.traceFile) err(`     이벤트(JSONL): ${ctx.traceFile}`);
+    err("     이번 실행에서 무엇을 어떤 근거로 정했는지 전부 기록돼 있습니다.");
+    err("     문제가 생기면 이 파일을 확인하세요 (저장소에 추적되지 않습니다).");
+    err("     💡 AI Agent에게 \"실행 로그 확인해줘\"라고 요청하면 원인을 짚어줍니다.");
+    err("");
+  }
   if (ctx?.migrationGuidePath) {
     err(`  🧭 마이그레이션 가이드: ${ctx.migrationGuidePath}`);
     err("     이번 설치에서 바뀐 내용과 직접 확인해야 할 작업이 이 파일에 정리되어 있습니다.");