projectops 4.4.1 → 4.6.0

package/README.md

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

package/package.json

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

package/src/cli/help.js

@@ -5,7 +5,8 @@ export const HELP_TEXT = `projectops — GitHub 프로젝트 자동화 템플릿
   npx projectops [옵션]
 
 옵션:
-  -m, --mode MODE          통합 모드 (full | version | workflows | issues | skills)
+  -m, --mode MODE          통합 모드 (full | version | workflows | issues | skills | doctor)
+                           doctor: 통합 상태·저장소 설정 진단 (읽기 전용)
                            기본: interactive (대화형)
   -t, --type CSV           프로젝트 타입 csv (예: spring,react,python)
                            지원: spring flutter react react-native
@@ -27,4 +28,6 @@ export const HELP_TEXT = `projectops — GitHub 프로젝트 자동화 템플릿
 예시:
   npx projectops --mode full --force --type spring,react
   npx projectops --mode workflows --type flutter --paths "flutter=app"
+  npx projectops --mode doctor                       # 설정 진단
+  GITHUB_TOKEN=ghp_... npx projectops --mode doctor  # 저장소 설정까지 진단
 `;

package/src/commands/doctor.js

@@ -0,0 +1,257 @@
+// doctor 명령 (#558) — 통합 상태·저장소 설정 진단. 읽기 전용, 파일을 건드리지 않는다.
+//
+// 출력 설계:
+//   ① 항목 이름에 purpose("무엇을 위한 설정인지")를 병기한다. `actions: write`만 보고는
+//      그게 자기 릴리스 흐름의 무엇을 담당하는지 알 수 없다.
+//   ② 도구가 "고쳐야 한다"고 판정하지 않는다. 발견한 사실만 진술하고 그것이 자신에게
+//      문제인지는 사용자가 판단한다 — 쓰지 않는 워크플로우의 Secret은 등록할 이유가 없다.
+//   ③ 문제 항목만 `현상 → 영향 → 조치` 로 펼치고, 정상 항목은 한 줄로 압축한다.
+//   ④ GitHub 설정 화면에 실제로 표시되는 문자열("Read and write permissions" 등)은
+//      번역하지 않는다. 번역하면 설명은 읽히지만 정작 화면에서 그 항목을 찾지 못한다.
+//
+// 원격 점검은 GITHUB_TOKEN이 있을 때만 한다. 없다고 실패시키지 않는다 — 로컬 점검만으로도
+// 대부분의 흔한 사고(치환 실패·Secret 누락)를 잡을 수 있다.
+import { join } from "node:path";
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { PATHS } from "../core/paths.js";
+import { parseExisting } from "../core/version-yml.js";
+import { verifyInstall } from "../core/verify.js";
+import { readBaseline } from "../core/baseline.js";
+import { detectRepoName } from "../core/detect-fs.js";
+
+const PERM_PURPOSE = "자동 커밋·태그·후속 워크플로우 실행";
+
+// GitHub REST 호출. 실패는 예외가 아니라 {ok:false}로 돌려 진단이 중단되지 않게 한다.
+async function gh(path, token) {
+  try {
+    const res = await fetch(`https://api.github.com${path}`, {
+      headers: { Authorization: `token ${token}`, Accept: "application/vnd.github+json",
+                 "User-Agent": "projectops-doctor" },
+    });
+    if (!res.ok) return { ok: false, status: res.status };
+    return { ok: true, data: await res.json() };
+  } catch (e) {
+    return { ok: false, error: e?.message || String(e) };
+  }
+}
+
+// git remote에서 owner/repo 추출. 없으면 null.
+function detectSlug(cwd) {
+  try {
+    const url = execFileSync("git", ["remote", "get-url", "origin"],
+      { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+    const m = url.match(/github\.com[:/]([^/]+)\/([^/.]+)(\.git)?$/);
+    return m ? `${m[1]}/${m[2]}` : null;
+  } catch {
+    return null;
+  }
+}
+
+// ── 로컬 점검 ─────────────────────────────────────────────────────────
+export function localChecks(cwd = ".") {
+  const rows = [];
+  const add = (r) => rows.push(r);
+
+  const vyPath = join(cwd, PATHS.versionFile);
+  const existing = existsSync(vyPath) ? parseExisting(readFileSync(vyPath, "utf8")) : null;
+
+  if (!existing) {
+    add({ name: "통합 상태", purpose: "이 폴더의 템플릿 설치 여부", status: "INFO",
+          value: "version.yml 없음",
+          detail: ["이 폴더에는 템플릿이 통합되어 있지 않습니다.",
+                   "통합하려면: npx projectops"] });
+    return rows; // 통합 전이면 나머지 점검이 의미 없다
+  }
+
+  add({ name: "통합 상태", purpose: "이 폴더의 템플릿 설치 여부", status: "OK",
+        value: `템플릿 v${existing.templateVersion || "unknown"} / 프로젝트 v${existing.version}` });
+
+  const wfDir = join(cwd, PATHS.workflowsDir);
+  const files = existsSync(wfDir)
+    ? readdirSync(wfDir).filter((f) => /\.ya?ml$/.test(f))
+    : [];
+  add({ name: "설치된 워크플로우", purpose: "이 저장소에서 도는 자동화", status: files.length ? "OK" : "WARN",
+        value: `${files.length}개`,
+        detail: files.length ? null : ["워크플로우가 하나도 없습니다.",
+                                       "통합 모드를 workflows 또는 full로 다시 실행해 보세요."] });
+
+  // 치환·Secret 판정은 설치 후 검증(#549)과 같은 모듈을 쓴다 — 두 곳에 두면 기준이 갈라진다.
+  const v = verifyInstall(cwd);
+  add({
+    name: "치환되지 않은 값", purpose: "배포 시점에 실패할 자리",
+    status: v.unresolved.length === 0 ? "OK" : "WARN",
+    value: v.unresolved.length === 0 ? "없음" : `${v.unresolved.length}건`,
+    detail: v.unresolved.length === 0 ? null : [
+      "아래 위치에 템플릿 값이 그대로 남아 있습니다.",
+      ...v.unresolved.slice(0, 8).map((u) => `  ${u.filename}:${u.line}  ${u.token}`),
+      ...(v.unresolved.length > 8 ? [`  … 외 ${v.unresolved.length - 8}건`] : []),
+      "그대로 두면 해당 워크플로우가 배포 단계에서 실패합니다. 직접 값을 채워주세요.",
+    ],
+  });
+
+  const secretNames = [...v.secrets.keys()];
+  add({
+    name: "필요한 Secret", purpose: "설치된 워크플로우가 요구하는 값",
+    status: "INFO", value: secretNames.length ? `${secretNames.length}개` : "없음",
+    detail: secretNames.length ? [
+      ...secretNames.map((n) => `  ${n}  ← ${v.secrets.get(n).length}개 워크플로우`),
+      "쓰지 않는 워크플로우의 값은 등록하지 않아도 됩니다.",
+    ] : null,
+  });
+
+  // 워크플로우 파일의 permissions 선언 점검 (#558).
+  // 저장소 설정(Settings > Actions)은 "요청할 수 있는 최대 범위"이고, 워크플로우의
+  // permissions 블록은 "실제로 요청한 범위"다. 둘은 다른 층이라 저장소 설정이 정상이어도
+  // 선언이 빠지면 API가 403을 준다 — #555가 정확히 그 사고였다.
+  const needsActionsWrite = [];
+  for (const f of files) {
+    const body = readFileSync(join(wfDir, f), "utf8");
+    if (!body.includes("dispatch_downstream.py")) continue;     // 다른 워크플로우를 깨우는 파일만
+    const perm = body.match(/^permissions:\n((?:\s+.*\n)+)/m);
+    const hasActionsWrite = perm ? /^\s+actions:\s*write/m.test(perm[1]) : false;
+    if (!hasActionsWrite) needsActionsWrite.push(f);
+  }
+  if (files.length) {
+    add({
+      name: "워크플로우 권한 선언", purpose: "다른 워크플로우를 실행할 권한",
+      status: needsActionsWrite.length ? "WARN" : "OK",
+      value: needsActionsWrite.length ? `${needsActionsWrite.length}건 누락` : "정상",
+      detail: needsActionsWrite.length ? [
+        ...needsActionsWrite.map((f) => `  ${f}`),
+        "다른 워크플로우를 실행하는데 permissions에 'actions: write'가 없습니다.",
+        "저장소 설정이 Read and write여도 이 선언이 없으면 API가 403을 반환합니다.",
+        "조치: 해당 파일의 permissions 블록에 'actions: write' 추가",
+      ] : null,
+    });
+  }
+
+  const baseline = readBaseline(cwd);
+  add({
+    name: "업데이트 기준점", purpose: "다음 업데이트가 내 수정을 구분할 근거",
+    status: baseline ? "OK" : "INFO",
+    value: baseline ? `${Object.keys(baseline.files).length}개 파일 기록됨` : "없음",
+    detail: baseline ? null : [
+      "기준점이 없어 다음 업데이트는 변경된 파일을 모두 물어봅니다.",
+      "통합을 한 번 실행하면 기록되고, 그 다음 업데이트부터 내 수정과 템플릿 개선을 구분합니다.",
+    ],
+  });
+
+  return rows;
+}
+
+// ── 원격 점검 ─────────────────────────────────────────────────────────
+export async function remoteChecks(slug, token, requiredSecrets = []) {
+  const rows = [];
+  const add = (r) => rows.push(r);
+
+  const perm = await gh(`/repos/${slug}/actions/permissions/workflow`, token);
+  if (!perm.ok) {
+    add({ name: "Workflow permissions", purpose: PERM_PURPOSE, status: "INFO",
+          value: perm.status === 403 ? "조회 권한 없음" : "조회 실패",
+          detail: ["토큰에 저장소 관리 권한이 없어 확인하지 못했습니다.",
+                   "Settings > Actions > General > Workflow permissions 에서 직접 확인하세요."] });
+  } else if (perm.data?.default_workflow_permissions === "write") {
+    add({ name: "Workflow permissions", purpose: PERM_PURPOSE, status: "OK",
+          value: "Read and write permissions" });
+  } else {
+    add({
+      name: "Workflow permissions", purpose: PERM_PURPOSE, status: "WARN",
+      value: "Read repository contents permission (읽기 전용)",
+      detail: [
+        "워크플로우가 저장소에 쓰거나 다른 워크플로우를 실행할 수 없습니다.",
+        "버전 확정 커밋·릴리스 태그·후속 워크플로우 실행이 전부 실패합니다.",
+        "조치: Settings > Actions > General > Workflow permissions",
+        "      → 'Read and write permissions' 선택",
+      ],
+    });
+  }
+
+  const repo = await gh(`/repos/${slug}`, token);
+  if (repo.ok) {
+    const allowed = repo.data?.allow_merge_commit === true;
+    add({
+      name: "merge commit 허용", purpose: "릴리스 PR 자동 머지 조건",
+      status: allowed ? "OK" : "WARN",
+      value: allowed ? "허용됨" : "꺼져 있음",
+      detail: allowed ? null : [
+        "릴리스 PR 자동 머지는 merge commit 방식을 사용합니다.",
+        "꺼져 있으면 자동 머지가 실패하고 PR이 열린 채 남습니다.",
+        "조치: Settings > General > Pull Requests → 'Allow merge commits' 체크",
+      ],
+    });
+  }
+
+  if (requiredSecrets.length) {
+    const sec = await gh(`/repos/${slug}/actions/secrets?per_page=100`, token);
+    if (!sec.ok) {
+      add({ name: "Secret 등록 여부", purpose: "배포에 필요한 값", status: "INFO",
+            value: "조회 권한 없음",
+            detail: ["토큰에 Secret 조회 권한이 없어 확인하지 못했습니다."] });
+    } else {
+      const have = new Set((sec.data?.secrets || []).map((s) => s.name));
+      const missing = requiredSecrets.filter((n) => !have.has(n));
+      add({
+        name: "Secret 등록 여부", purpose: "배포에 필요한 값",
+        status: missing.length ? "WARN" : "OK",
+        value: missing.length ? `${missing.length}개 미등록` : "전부 등록됨",
+        detail: missing.length ? [
+          ...missing.map((n) => `  ${n}`),
+          "해당 워크플로우를 쓰지 않는다면 등록하지 않아도 됩니다.",
+          "조치: Settings > Secrets and variables > Actions > New repository secret",
+        ] : null,
+      });
+    }
+  }
+
+  return rows;
+}
+
+// ── 렌더 ──────────────────────────────────────────────────────────────
+const ICON = { OK: "✅", WARN: "⚠️", FAIL: "❌", INFO: "ℹ️" };
+
+export function renderRows(rows, write = (s) => process.stderr.write(s + "\n")) {
+  const head = (r) => `${r.name}${r.purpose ? ` — ${r.purpose}` : ""}`;
+  for (const r of rows) {
+    write(`${ICON[r.status] || "·"} ${head(r)}: ${r.value}`);
+    // 정상 항목은 한 줄로 압축한다. 펼치는 것은 사용자가 무언가 해야 할 때뿐이다.
+    if (r.detail && r.status !== "OK") {
+      for (const line of r.detail) write(`     ${line}`);
+      write("");
+    }
+  }
+  const warn = rows.filter((r) => r.status === "WARN" || r.status === "FAIL").length;
+  write("");
+  write(warn === 0
+    ? "확인된 문제 없음."
+    : `살펴볼 항목 ${warn}건. 위 조치를 참고하세요 (쓰지 않는 기능이라면 넘어가도 됩니다).`);
+  return warn;
+}
+
+// 진입점. 반환: 살펴볼 항목 수 (exit code로 쓰지 않는다 — 진단은 실패가 아니다)
+export async function runDoctor({ cwd = ".", token = process.env.GITHUB_TOKEN || "" } = {}) {
+  const write = (s) => process.stderr.write(s + "\n");
+  write("");
+  write("projectops doctor — 통합 상태 및 저장소 설정 진단");
+  write("────────────────────────────────────────");
+  write("");
+
+  const rows = localChecks(cwd);
+  const slug = detectSlug(cwd);
+  const repoName = detectRepoName(cwd);
+  rows.push({ name: "GitHub 원격", purpose: "점검 대상 저장소", status: slug ? "OK" : "INFO",
+              value: slug || `origin 없음${repoName ? ` (폴더명: ${repoName})` : ""}`,
+              detail: slug ? null : ["원격 저장소를 찾지 못해 저장소 설정은 점검하지 않습니다."] });
+
+  if (slug && token) {
+    const v = verifyInstall(cwd);
+    rows.push(...await remoteChecks(slug, token, [...v.secrets.keys()]));
+  } else if (slug) {
+    rows.push({ name: "저장소 설정 점검", purpose: "권한·머지 방식·Secret", status: "INFO",
+                value: "건너뜀 (토큰 없음)",
+                detail: ["GITHUB_TOKEN 환경변수를 주면 저장소 설정까지 점검합니다.",
+                         "  GITHUB_TOKEN=ghp_... npx projectops --mode doctor"] });
+  }
+
+  return renderRows(rows, write);
+}

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/baseline.js

@@ -0,0 +1,85 @@
+// 설치 시점 baseline (#557) — 업데이트에서 "누가 바꿨는지"를 가르는 기준점.
+//
+// 왜 필요한가: isUnchanged()는 템플릿(theirs)과 설치본(ours)을 2-way로 비교한다.
+// base가 없으니 업스트림이 한 글자만 고쳐도 사용자가 손대지 않은 파일이 changed로 떨어지고,
+// 결국 "전부 skip(업데이트 못 받음)" 아니면 "전부 overwrite(사용자 수정 전멸)" 둘 중 하나만
+// 고를 수 있게 된다. 정작 가려내야 할 진짜 충돌이 나머지에 묻힌다.
+//
+// 파일 사본이 아니라 해시만 남긴다 — 분류가 목적이지 자동 병합이 목적이 아니다.
+//
+// 해시를 두 개 두는 이유: env 치환으로 사용자 값이 들어간 파일은 디스크 내용과 "기본값으로
+// 렌더한 결과"가 애초에 다르다. 하나로는 두 질문에 동시에 답할 수 없다.
+//   - installed : 설치 시점 우리가 디스크에 쓴 내용     → "사용자가 그 뒤에 손댔는가"
+//   - rendered  : 그 시점 템플릿을 기본값 치환한 결과   → "업스트림이 그 뒤에 바뀌었는가"
+//
+// installed는 우리가 실제로 쓴 파일에만 채운다. 사용자 수정본을 installed로 기록하면
+// "우리가 쓴 것"이라고 거짓말하는 셈이고, 다음 업데이트에서 그 파일이 조용히 덮인다.
+import { createHash } from "node:crypto";
+import { join } from "node:path";
+import { existsSync, readFileSync } from "node:fs";
+import { writeText } from "./fsutil.js";
+
+export const BASELINE_DIR = ".github/.projectops";
+export const BASELINE_PATH = ".github/.projectops/baseline.json";
+
+export function sha256(text) {
+  return "sha256:" + createHash("sha256").update(String(text), "utf8").digest("hex");
+}
+
+// 없거나 깨졌으면 null — 호출부는 "base 미상"으로 폴백한다(조용히 빈 baseline을 쓰지 않는다.
+// 빈 baseline은 "기록이 없다"가 아니라 "전부 삭제됐다"로 오해될 수 있다).
+export function readBaseline(targetRoot = ".") {
+  const p = join(targetRoot, BASELINE_PATH);
+  if (!existsSync(p)) return null;
+  try {
+    const data = JSON.parse(readFileSync(p, "utf8"));
+    if (!data || typeof data !== "object" || typeof data.files !== "object" || data.files === null) return null;
+    return data;
+  } catch {
+    return null; // 손상된 baseline은 없는 것으로 취급 — 업데이트를 막지 않는다
+  }
+}
+
+// entries: Map<filename, {installed?:string|null, rendered:string}>
+// 기존 baseline은 병합 대상이다 — 이번 실행에서 건드리지 않은 파일의 기준점을 잃지 않는다.
+export function writeBaseline(targetRoot, { templateVersion, installedAt, entries, previous = null }) {
+  const files = { ...(previous?.files || {}) };
+  for (const [filename, entry] of entries) {
+    const prev = files[filename] || {};
+    files[filename] = {
+      // installed는 이번에 실제로 쓴 경우에만 갱신. 유지(skip)한 파일은 예전 기준점을 지킨다.
+      installed: entry.installed ?? prev.installed ?? null,
+      rendered: entry.rendered,
+    };
+  }
+  const out = {
+    templateVersion: templateVersion || "unknown",
+    installedAt: installedAt || "",
+    files,
+  };
+  writeText(join(targetRoot, BASELINE_PATH), JSON.stringify(out, null, 2) + "\n");
+  return out;
+}
+
+// 사용자가 이 파일을 설치 후 손댔는가.
+// baseline이 없거나 그 파일 기록이 없으면 null — "모른다"이지 "안 건드렸다"가 아니다.
+// 호출부는 null을 현행 2-way 판정으로 폴백시켜야 한다.
+export function isUserModified(baseline, filename, installedContent) {
+  const rec = baseline?.files?.[filename];
+  if (!rec || !rec.installed) return null;
+  return rec.installed !== sha256(installedContent);
+}
+
+// baseline에는 있는데 디스크에 없는 파일 = 사용자가 지운 것.
+// 별도의 삭제 이력 파일이 필요 없다는 것이 이 설계의 부산물이다.
+// candidates: 템플릿이 이번에 설치하려는 파일명 목록 (그 밖의 baseline 항목은 관심 없다)
+export function detectRemoved(baseline, candidates, workflowsDir) {
+  if (!baseline) return [];
+  const removed = [];
+  for (const filename of candidates) {
+    if (!baseline.files[filename]) continue;      // 우리가 설치한 적 없는 파일 — 판단 근거 없음
+    if (existsSync(join(workflowsDir, filename))) continue;
+    removed.push(filename);
+  }
+  return removed;
+}