projectops 4.4.1 → 4.5.0

package/README.md

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "projectops",
-  "version": "4.4.1",
+  "version": "4.5.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/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;
+}

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 폴더를 찾지 못했습니다.");
 
@@ -101,7 +113,7 @@ export function copyWorkflows(context, tempDir, targetRoot = ".", hooks = {}) {
   // (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 +167,38 @@ export function copyWorkflows(context, tempDir, targetRoot = ".", hooks = {}) {
     }
   }
 
+  // (7) 기준점 기록 (#557) — 다음 업데이트가 "누가 바꿨는지"를 가릴 근거.
+  //     이번에 실제로 쓴 파일만 installed를 갱신한다. 유지(skip)한 파일에 우리가 쓴 것처럼
+  //     기록하면 다음 업데이트에서 사용자 수정이 조용히 덮인다.
+  recordBaseline(workflowsDir, targetRoot, counters, baseline, context.templateVersion, context.now);
+
   return counters;
 }
 
+// 설치 직후의 디스크 내용을 기준점으로 남긴다. 실패해도 통합을 막지 않는다 —
+// 기준점이 없으면 다음 업데이트가 종전 2-way 판정으로 폴백할 뿐이다.
+function recordBaseline(workflowsDir, targetRoot, counters, previous, templateVersion, now) {
+  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; // 새로 쓴 게 없으면 기존 기준점을 건드리지 않는다
+    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,6 +230,8 @@ 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 branches = { defaultBranch: branch || "main", deployBranch: deployBranch || "develop" }; // #477 — 엔진과 동일 기준
@@ -196,11 +239,11 @@ export function listWorkflowConflicts(context, tempDir, targetRoot = ".") {
     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 +267,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 }); }
     // changed: 결정 Map에 따라 처리 (미지정=skip → 현행 force 동작과 동일)
     for (const f of changed) applyDecision(decisions.get(f), typeDir, workflowsDir, f, counters, trace);
   }
@@ -242,9 +287,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` }); }
     for (const f of changed) applyDecision(decisions.get(f), serverDeployDir, workflowsDir, f, counters, trace);
   }
 

package/src/index.js

@@ -60,6 +60,13 @@ export async function run(argv, { cwd = process.cwd(), source = { type: "git" },
   if (opts.showVersion) { console.log(readPkgVersion()); return 0; }
   if (opts.help) { console.log(HELP_TEXT); return 0; }
 
+  // doctor 모드 (#558) — 읽기 전용 진단. 템플릿을 내려받지 않으므로 네트워크 없이도 동작한다.
+  if (opts.mode === "doctor") {
+    const { runDoctor } = await import("./commands/doctor.js");
+    await runDoctor({ cwd });
+    return 0;   // 진단은 실패가 아니다 — 살펴볼 항목이 있어도 0으로 끝낸다
+  }
+
   // skills 모드 — IDE 스킬 설치/업데이트/제거 (템플릿 통합 없음).
   // Cursor 복사용 skills/ 소스가 필요하므로 템플릿을 획득한 뒤 실행한다.
   if (opts.mode === "skills") {