projectops 4.4.1 → 4.6.0

package/src/core/copy/workflows.js

@@ -7,6 +7,7 @@ import { existsSync, readFileSync, writeFileSync, renameSync } from "node:fs";
 import { PATHS } from "../paths.js";
 import { exists, copyFileSync, listYamlFiles } from "../fsutil.js";
 import { isUnchanged, substituteEnv } from "../wizard-env.js";
+import { isUserModified, readBaseline, writeBaseline, sha256 } from "../baseline.js";
 import { substituteBranches } from "../branch-sub.js";
 
 // 한 파일에 env 치환을 적용해 대상 파일을 갱신 (.sh configure_workflow_env 등가).
@@ -34,16 +35,25 @@ function utilSyncApplies(tempDir, targetRoot, types) {
   return types.some((t) => exists(join(tempDir, ".github", "util", t)));
 }
 
-// 3분류 (신규/unchanged/changed) — 대상 워크플로우 디렉토리 기준.
-function classify(srcDir, workflowsDir, envOpts) {
-  const result = { newFiles: [], unchanged: [], changed: [] };
+// 4분류 (신규/unchanged/upstream/changed) — 대상 워크플로우 디렉토리 기준.
+//
+// upstream(#557): 사용자가 손대지 않았는데 템플릿만 바뀐 파일. 질문할 이유가 없으므로
+// 그냥 최신으로 올린다. baseline(설치 시점 해시)이 있어야 판정할 수 있다.
+// baseline이 없거나 그 파일 기록이 없으면 판정 불가 → 종전대로 changed로 떨어뜨린다
+// (기존 통합 레포의 동작이 바뀌지 않는다).
+function classify(srcDir, workflowsDir, envOpts, baseline = null) {
+  const result = { newFiles: [], unchanged: [], changed: [], upstream: [] };
   for (const filename of listYamlFiles(srcDir)) {
     const src = join(srcDir, filename);
     const dst = join(workflowsDir, filename);
     if (existsSync(dst)) {
       const tpl = readFileSync(src, "utf8");
       const inst = readFileSync(dst, "utf8");
-      if (isUnchanged(tpl, inst, envOpts)) result.unchanged.push(filename);
+      if (isUnchanged(tpl, inst, envOpts)) { result.unchanged.push(filename); continue; }
+      // 여기 왔다는 건 "지금 템플릿 렌더 결과 ≠ 설치본" — 사용자 수정이거나 업스트림 변경이다.
+      // baseline이 그 둘을 가른다.
+      const modified = isUserModified(baseline, filename, inst);
+      if (modified === false) result.upstream.push(filename);
       else result.changed.push(filename);
     } else {
       result.newFiles.push(filename);
@@ -64,6 +74,8 @@ export function copyWorkflows(context, tempDir, targetRoot = ".", hooks = {}) {
   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);
+  // 설치 시점 기준점(#557) — 없으면 null이고 classify가 종전 2-way로 폴백한다.
+  const baseline = readBaseline(targetRoot);
   const projectTypesDir = join(tempDir, PATHS.workflowsDir, PATHS.projectTypesDir);
   if (!exists(projectTypesDir)) throw new Error("템플릿 저장소 구조 오류 — project-types 폴더를 찾지 못했습니다.");
 
@@ -75,33 +87,59 @@ 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);
     }
   }
 
   // (2~4) 타입별
   for (const type of types) {
     const asks = new Map();
-    copyWorkflowsForType(type, projectTypesDir, workflowsDir, { deployTarget, publishTargets, ...context, envOptsFor, collectAsks: asks, decisions, trace }, counters);
+    copyWorkflowsForType(type, projectTypesDir, workflowsDir, { deployTarget, publishTargets, ...context, envOptsFor, collectAsks: asks, decisions, trace, baseline }, counters);
     if (asks.size) deployValues.set(type, asks);
   }
 
@@ -155,9 +193,39 @@ export function copyWorkflows(context, tempDir, targetRoot = ".", hooks = {}) {
     }
   }
 
+  // (7) 기준점 기록 (#557) — 다음 업데이트가 "누가 바꿨는지"를 가릴 근거.
+  //     이번에 실제로 쓴 파일만 installed를 갱신한다. 유지(skip)한 파일에 우리가 쓴 것처럼
+  //     기록하면 다음 업데이트에서 사용자 수정이 조용히 덮인다.
+  recordBaseline(workflowsDir, targetRoot, counters, baseline, context.templateVersion, context.now, trace);
+
   return counters;
 }
 
+// 설치 직후의 디스크 내용을 기준점으로 남긴다. 실패해도 통합을 막지 않는다 —
+// 기준점이 없으면 다음 업데이트가 종전 2-way 판정으로 폴백할 뿐이다.
+function recordBaseline(workflowsDir, targetRoot, counters, previous, templateVersion, now, trace = null) {
+  try {
+    const entries = new Map();
+    for (const f of counters.copiedFiles || []) {
+      const p = join(workflowsDir, f);
+      if (!existsSync(p)) continue;
+      const content = readFileSync(p, "utf8");
+      // 치환까지 끝난 최종 디스크 내용이 곧 우리가 쓴 것이자, 이 시점의 렌더 결과다.
+      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 || "",
+      entries,
+      previous,
+    });
+  } catch {
+    // 기준점 기록 실패는 통합 실패가 아니다
+  }
+}
+
 // changed(기존에 있고 내용이 바뀐) 파일 1개를 결정에 따라 처리 (.sh 3440~3508 3지선 case 등가).
 // 'skip'(기본): 기존 유지. 'backup': 기존→.bak 후 교체. 'template': 기존 유지 + 새 버전을 .template.yaml로.
 function applyDecision(decision, srcDir, workflowsDir, filename, counters, trace = null) {
@@ -189,18 +257,34 @@ function applyDecision(decision, srcDir, workflowsDir, filename, counters, trace
 export function listWorkflowConflicts(context, tempDir, targetRoot = ".") {
   const { types = [], paths = new Map(), deployTarget = "docker-ssh", repoName = "", resolvers = {}, branch = "", deployBranch = "" } = context;
   const workflowsDir = join(targetRoot, PATHS.workflowsDir);
+  // 설치 시점 기준점(#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);
     if (exists(typeDir)) {
-      for (const f of classify(typeDir, workflowsDir, envOpts).changed) conflicts.push({ filename: f, type });
+      for (const f of classify(typeDir, workflowsDir, envOpts, baseline).changed) conflicts.push({ filename: f, type });
     }
     const serverDeployDir = join(typeDir, "server-deploy");
     if (exists(serverDeployDir) && (deployTarget || "docker-ssh") === "docker-ssh") {
-      for (const f of classify(serverDeployDir, workflowsDir, envOpts).changed) conflicts.push({ filename: f, type });
+      for (const f of classify(serverDeployDir, workflowsDir, envOpts, baseline).changed) conflicts.push({ filename: f, type });
     }
   }
   return conflicts;
@@ -224,17 +308,19 @@ 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(), trace = null } = ctx;
+  const { deployTarget = "docker-ssh", publishTargets = [], force = false, paths = new Map(), repoName = "", resolvers = {}, envOptsFor, collectAsks = null, decisions = new Map(), trace = null, baseline = null } = ctx;
   const typeDir = join(projectTypesDir, type);
   const envOpts = envOptsFor(type);
   let unchangedNames = [];
 
   // 타입별 워크플로우 (직하위)
   if (exists(typeDir)) {
-    const { newFiles, unchanged, changed } = classify(typeDir, workflowsDir, envOpts);
+    const { newFiles, unchanged, changed, upstream } = classify(typeDir, workflowsDir, envOpts, baseline);
     unchangedNames = unchanged.slice();
     for (const f of unchanged) { counters.skipped++; trace?.event("copy", "skipped-unchanged", f, { group: type }); }
     for (const f of newFiles) { copyFileSync(join(typeDir, f), join(workflowsDir, f)); counters.copied++; counters.copiedFiles.push(f); trace?.event("copy", "copied", f, { group: type }); }
+    // upstream(#557): 사용자가 손대지 않았고 템플릿만 바뀐 파일 — 물어볼 것 없이 최신으로 올린다.
+    for (const f of upstream) { copyFileSync(join(typeDir, f), join(workflowsDir, f)); counters.copied++; counters.copiedFiles.push(f); trace?.event("copy", "upstream-updated", f, { group: type, reason: "baseline-match" }); }
     // changed: 결정 Map에 따라 처리 (미지정=skip → 현행 force 동작과 동일)
     for (const f of changed) applyDecision(decisions.get(f), typeDir, workflowsDir, f, counters, trace);
   }
@@ -242,9 +328,10 @@ function copyWorkflowsForType(type, projectTypesDir, workflowsDir, ctx, counters
   // 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);
+    const { newFiles, unchanged, changed, upstream } = classify(serverDeployDir, workflowsDir, envOpts, baseline);
     for (const f of unchanged) { counters.skipped++; trace?.event("copy", "skipped-unchanged", f, { group: `${type}/server-deploy` }); }
     for (const f of newFiles) { copyFileSync(join(serverDeployDir, f), join(workflowsDir, f)); counters.copied++; counters.copiedFiles.push(f); trace?.event("copy", "copied", f, { group: `${type}/server-deploy` }); }
+    for (const f of upstream) { copyFileSync(join(serverDeployDir, f), join(workflowsDir, f)); counters.copied++; counters.copiedFiles.push(f); trace?.event("copy", "upstream-updated", f, { group: `${type}/server-deploy`, reason: "baseline-match" }); }
     for (const f of 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 };
     },
   };
 }