@kaydash9999/banker-plugins 0.24.0 → 0.25.0

package/skills/progress-mon/scripts/pm-adr.mjs

@@ -1,27 +1,29 @@
-// pm-adr.mjs: ADR 탭. adr.json 두 층 스키마 검사, 참조 검증과 gap 정리, docs/adr 갈라짐 경고, 밀도, 렌더.
+// pm-adr.mjs: ADR 탭의 검사. adr.json 두 층 스키마 검사, 참조 검증과 gap 정리, docs/adr 갈라짐 경고, 밀도, 집계, check 대조 기록.
+// 화면 렌더는 pm-adr-view.mjs.
 // 두 층: project(검증, 흐름, 증거)는 프로젝트에 하나, decisions[](최적화 로직, 확장 대응, 포기와 얻은 것)는 결정마다.
 // 서버 화면은 참조를 글로만 보이고 파일을 읽거나 링크하지 않는다. 참조 파일은 check 에서만 크기 상한 안의 일반 파일로 읽는다.
 // 스키마 위반은 FAIL, 근거가 없어 비운 항목({ gap: 사유 })은 밀도 WARN, 확인 못 한 참조는 FAIL 이나 WARN(references/adr.md).
+import crypto from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
-import { git, noBom, readRegular, writeAtomic } from './pm-config.mjs';
-import { esc } from './pm-html.mjs';
+import { git, noBom, readRegular, writeAtomic, writeNew } from './pm-config.mjs';
 
 const ADR_FILE = 'adr.json';
+const ADR_CHECK_FILE = 'adr-check.json';
 const REF_READ_MAX = 4 * 1024 * 1024;
-const STATUS = { accepted: '채택', proposed: '제안', superseded: '대체됨' };
+export const STATUS = { accepted: '채택', proposed: '제안', superseded: '대체됨' };
 const REF_KINDS = ['file', 'test', 'commit', 'cmd'];
 const HASH = /^[0-9a-f]{4,40}$/i;
-const DECISION_SLOTS = [
+export const DECISION_SLOTS = [
   ['optimization', '최적화 로직'],
   ['scaling', '확장 대응'],
   ['tradeoffs', '포기와 얻은 것'],
 ];
 
-const arr = (v) => (Array.isArray(v) ? v : []);
-const obj = (v) => (v && typeof v === 'object' && !Array.isArray(v) ? v : null);
-const str = (v) => typeof v === 'string' && v.trim().length > 0;
-const isGap = (v) => Boolean(obj(v)) && Object.hasOwn(v, 'gap');
+export const arr = (v) => (Array.isArray(v) ? v : []);
+export const obj = (v) => (v && typeof v === 'object' && !Array.isArray(v) ? v : null);
+export const str = (v) => typeof v === 'string' && v.trim().length > 0;
+export const isGap = (v) => Boolean(obj(v)) && Object.hasOwn(v, 'gap');
 // json 경로 조각(['decisions', 0, 'scaling']) 을 글(decisions[0].scaling)로.
 const jp = (parts) => parts.reduce((a, k) => (typeof k === 'number' ? `${a}[${k}]` : a ? `${a}.${k}` : k), '') || '$';
 
@@ -338,7 +340,10 @@ function divergence(ctx, v) {
   return names.sort().filter((n) => !pointed.has(`docs/adr/${n}`)).map((n) => `docs/adr/${n} 를 가리키는 결정 없음`);
 }
 
-// adr.json 읽기. 돌려줌: { missing } | { error } | { value }
+// adr.json 글(BOM 을 뗀 뒤)의 sha256. check 대조 기록과 화면이 같은 adr.json 을 보았는지 가린다.
+export const adrSha = (text) => crypto.createHash('sha256').update(text, 'utf8').digest('hex');
+
+// adr.json 읽기. 돌려줌: { missing } | { error } | { value, sha }
 function readAdr(dataDir) {
   let text;
   try {
@@ -346,32 +351,43 @@ function readAdr(dataDir) {
   } catch (e) {
     return e.code === 'ENOENT' ? { missing: true } : { error: `읽기 실패(${e.code || 'error'})` };
   }
+  const body = noBom(text);
   try {
-    return { value: JSON.parse(noBom(text)) };
+    return { value: JSON.parse(body), sha: adrSha(body) };
   } catch (e) {
     return { error: `JSON 아님: ${e.message}` };
   }
 }
 
-// 검사 전체(check 와 정리가 같이 씀). 돌려줌: { missing } | { error } | { value, S, diverge }
+// 검사 전체(check 와 정리가 같이 씀). 돌려줌: { missing } | { error } | { value, sha, S, diverge }
 function inspectAdr(ctx, config) {
   const got = readAdr(ctx.dataDir);
   if (!Object.hasOwn(got, 'value')) return got;
   const S = examine(got.value, ctx, config);
   const diverge = S.schema.length ? [] : divergence(ctx, got.value);
-  return { value: got.value, S, diverge };
+  return { value: got.value, sha: got.sha, S, diverge };
 }
 
-// check 의 ADR 부분. r: pm-check 의 sink. 돌려줌: { value: 밀도에 쓸 값, bare: 참조 없는 서술 칸 } (없거나 깨졌으면 null).
+// check 의 ADR 부분. r: pm-check 의 sink. 돌려줌: { value: 밀도에 쓸 값, bare: 참조 없는 서술 칸, sha: adr.json sha256 }.
+// adr.json 이 없거나 깨졌으면 { value: null, bare: [], sha: null }.
+const NO_ADR = () => ({ value: null, bare: [], sha: null });
 export function checkAdr(ctx, config, r) {
   const got = inspectAdr(ctx, config);
-  if (got.missing) return null;
-  if (got.error) return r.fail(ADR_FILE, '$', got.error), null;
+  if (got.missing) return NO_ADR();
+  if (got.error) return r.fail(ADR_FILE, '$', got.error), NO_ADR();
   for (const x of [...got.S.schema, ...got.S.claim]) r.fail(ADR_FILE, x.p, x.msg);
   for (const x of got.S.refFail) r.fail(ADR_FILE, jp(x.parts), `참조: ${x.msg}`);
   for (const x of got.S.refWarn) r.warn(ADR_FILE, jp(x.parts), `참조: ${x.msg}`);
   for (const msg of got.diverge) r.warn(ADR_FILE, 'sources:', msg);
-  return { value: got.value, bare: bareSlots(got.value, (p) => got.S.good.has(p)) };
+  return { value: got.value, bare: bareSlots(got.value, (p) => got.S.good.has(p)), sha: got.sha };
+}
+
+// check 대조 기록(adr-check.json): check 가 확인을 마친 참조로 센 집계 글과 그때 adr.json 의 sha256.
+// 화면은 파일을 읽지 않고 적힌 참조로 세므로, 이 기록과 대조해 두 수가 다르거나 check 뒤 adr.json 이 바뀌었음을 알린다.
+// rec: { sha, tally }. 쓰기 실패는 UsageError(writeAtomic).
+export async function writeAdrCheck(dataDir, rec, now = Date.now()) {
+  const body = { sha: rec.sha, tally: rec.tally, at: new Date(now).toISOString() };
+  await writeAtomic(path.join(dataDir, ADR_CHECK_FILE), `${JSON.stringify(body, null, 2)}\n`);
 }
 
 // json 경로 조각 자리에 값을 넣는다.
@@ -388,13 +404,16 @@ const stamp = (ms) => {
 };
 
 // 스키마 FAIL 이 남은 adr.json 을 같은 폴더의 adr.json.rejected-<시각>(있으면 -2, -3 ...)으로 옮긴다. 결정 기록을 잃지 않게
-// 지우지 않는다. 새 이름은 COPYFILE_EXCL 로 만들어 있는 파일을 덮지 않고, 사본을 만든 뒤에만 원본을 지운다. 돌려줌: 옮긴 경로.
+// 지우지 않는다. 새 이름은 writeNew 로 만들어 있는 것(끊어진 링크 포함)을 덮거나 따라가지 않고, 사본을 만든 뒤에만 원본을
+// 지운다. 돌려줌: 옮긴 경로.
 function reject(file, now) {
   const base = `${file}.rejected-${stamp(now)}`;
+  const bytes = fs.readFileSync(file);
+  const mode = fs.statSync(file).mode & 0o777; // as COPYFILE_EXCL kept it
   for (let i = 1; ; i++) {
     const dest = i === 1 ? base : `${base}-${i}`;
     try {
-      fs.copyFileSync(file, dest, fs.constants.COPYFILE_EXCL);
+      writeNew(dest, bytes, { mode });
     } catch (e) {
       if (e.code === 'EEXIST') continue;
       throw e;
@@ -497,89 +516,3 @@ export function adrTally(v, bare = bareSlots(v)) {
   const gaps = gapCount(v);
   return { text: `근거 없음 ${gaps}칸, 미검증 ${unverified}, 구현 못 함 ${notImplemented}, 참조 없는 서술 ${bare.length}`, any: gaps + unverified + notImplemented + bare.length > 0 };
 }
-
-// ---------- 렌더 ----------
-
-const gapHtml = (v) => `<span class="b miss">근거 없음: ${esc(v.gap)}</span>`;
-
-// 참조 한 줄 글. 파일을 읽거나 링크하지 않는다.
-export function refText(x) {
-  if (!obj(x)) return '';
-  if (isGap(x)) return gapHtml(x);
-  const note = typeof x.note === 'string' && x.note ? ` <small>${esc(x.note)}</small>` : '';
-  const line = Number.isInteger(x.line) ? `:${x.line}` : '';
-  const out = {
-    file: () => `파일 <code>${esc(x.path)}${line}</code>`,
-    test: () => `시험 <code>${esc(x.path)}</code> 의 ${esc(x.name)}`,
-    commit: () => `커밋 <code>${esc(String(x.hash || '').slice(0, 7))}</code>`,
-    cmd: () => `명령 <code>${esc(x.cmd)}</code>, 출력 ${x.output ? `<code>${esc(x.output)}</code>` : '없음'}`,
-  }[x.kind];
-  return out ? out() + note : esc(JSON.stringify(x)) + note;
-}
-
-const refsHtml = (list) => arr(list).map(refText).filter(Boolean).join('<br>') || '<span class="n">참조 없음</span>';
-const table = (head, rows) => `<table><thead><tr>${head.map((h) => `<th>${esc(h)}</th>`).join('')}</tr></thead><tbody>${rows.join('') || `<tr><td colspan="${head.length}" class="n">없음</td></tr>`}</tbody></table>`;
-const td = (h, cls = '') => `<td${cls ? ` class="${cls}"` : ''}>${h}</td>`;
-const sec = (title, body) => `<h3>${esc(title)}</h3>${body}`;
-// 칸이 gap 이면 근거 없음, 아니면 body(값).
-const slotHtml = (v, body) => (isGap(v) ? `<div>${gapHtml(v)}</div>` : obj(v) || Array.isArray(v) ? body(v) : `<div>${gapHtml({ gap: '칸 없음' })}</div>`);
-
-const evidenceHtml = (x) => (x.status === 'unverified' ? `<span class="b unv">미검증: ${esc(x.why)}</span>${arr(x.evidence).length ? `<br>${refsHtml(x.evidence)}` : ''}` : refsHtml(x.evidence));
-
-function verificationHtml(v) {
-  return table(['id', '단위 기능', '결과', 'evidence'], arr(v).filter(obj).map((x) => `<tr>${td(esc(x.id), 'h')}${td(esc(x.module))}${td(esc(x.result || '-'))}${td(evidenceHtml(x), 'n')}</tr>`));
-}
-
-function flowHtml(f) {
-  const rows = [['입력', f.input], ['처리', f.logic], ['출력', f.output]].map(([k, t]) => `<tr>${td(k, 't')}${td(str(t) ? esc(t) : gapHtml({ gap: '빈 칸' }))}</tr>`);
-  return `${table(['구분', '내용'], rows)}<div class="meta">참조: ${refsHtml(f.refs)}</div>`;
-}
-
-function proofHtml(p) {
-  const impl = arr(p.implemented).filter(obj).map((x) => `<tr>${td(esc(x.feature))}${td(esc(arr(x.modules).join(', ')), 'h')}${td(refsHtml(x.proofs), 'n')}</tr>`);
-  const not = arr(p.notImplemented).filter(obj).map((x) => `<tr>${td(esc(x.feature))}${td(esc(x.why))}</tr>`);
-  return `<div class="meta">구현된 기능과 증명 위치</div>${table(['구현된 기능', '모듈', '증명 위치'], impl)}<div class="meta">구현 못 한 기능</div>${table(['구현 못 한 기능', '사유'], not)}`;
-}
-
-const filled = (d) => DECISION_SLOTS.filter(([k]) => obj(d[k]) && !isGap(d[k])).length;
-const emptyNames = (d) => DECISION_SLOTS.filter(([k]) => !(obj(d[k]) && !isGap(d[k]))).map(([, n]) => n);
-
-function decisionRow(d) {
-  const miss = emptyNames(d);
-  const st = STATUS[d.status] || d.status;
-  return `<tr>${td(esc(d.id), 'h')}${td(esc(d.title))}${td(esc(st))}${td(esc(d.date || '-'), 't')}${td(`${filled(d)}/3`, 'd')}${td(miss.length ? `<span class="b miss">${esc(miss.join(', '))}</span>` : '-', 'n')}</tr>`;
-}
-
-function tradeoffsHtml(t) {
-  const gave = arr(t.gaveUp).filter(obj).map((x) => `<tr>${td(esc(x.what))}${td(esc(x.why))}</tr>`);
-  const got = arr(t.gained).filter(obj).map((x) => `<tr>${td(esc(x.what))}${td(esc(x.purpose))}</tr>`);
-  return `${table(['포기한 것', '이유'], gave)}${table(['얻은 것', '목적'], got)}`;
-}
-
-function decisionHtml(d) {
-  const opts = arr(d.options).filter(obj).map((x) => `<tr>${td(esc(x.name))}${td(esc(x.pros))}${td(esc(x.cons))}</tr>`);
-  const rejected = str(d.rejected) ? `<div class="meta">버린 선택지: ${esc(d.rejected)}</div>` : '';
-  const optim = (o) => `<div>${esc(o.process)}</div><div class="meta">참조한 모듈: ${esc(arr(o.modules).join(', ') || '없음')}</div><div class="meta">참조: ${refsHtml(o.refs)}</div>`;
-  const scale = (s) => `<div>${esc(s.argument)}</div>${str(s.limits) ? `<div class="meta">한계: ${esc(s.limits)}</div>` : ''}<div class="meta">참조: ${refsHtml(s.refs)}</div>`;
-  return `<h2>${esc(d.id)} ${esc(d.title)} <small>${esc(STATUS[d.status] || d.status)}</small></h2>
-<div class="meta">맥락: ${esc(d.context)}</div>${table(['선택지', '장점', '단점'], opts)}${rejected}
-<div><b>결론</b>: ${esc(d.decision)}</div><div class="meta">이유: ${esc(d.why)}</div>
-${sec('최적화 로직', slotHtml(d.optimization, optim))}${sec('확장 대응', slotHtml(d.scaling, scale))}${sec('포기와 얻은 것', slotHtml(d.tradeoffs, tradeoffsHtml))}
-<div class="meta">근거 출처: ${refsHtml(d.sources)}</div>`;
-}
-
-// ADR 탭 본문. 자료가 없거나 깨졌으면 다른 탭처럼 안내와 스키마 문서.
-export function adrBody(m, emptyNotice) {
-  const v = m.adr && obj(m.adr.value);
-  if (!v) return emptyNotice('references/adr.md');
-  const p = obj(v.project) || {};
-  const ds = arr(v.decisions).filter(obj);
-  const tally = adrTally(v);
-  return `<div class="meta">의사 결정 기록. 위는 프로젝트 전체(검증, 흐름, 증거), 아래는 결정마다(최적화 로직, 확장 대응, 포기와 얻은 것). 자료: <code>adr.json</code>. 참조는 위치만 보이고 이 화면은 파일을 열지 않음. 참조 확인은 check.</div>
-<div class="meta"><span class="b ${tally.any ? 'miss' : 'done'}">${esc(tally.text)}</span></div>
-<h2>프로젝트 요약</h2>
-${sec('검증', slotHtml(p.verification, verificationHtml))}${sec('흐름', slotHtml(p.flow, flowHtml))}${sec('증거', slotHtml(p.proof, proofHtml))}
-<h2>결정 목록 <small>${ds.length}건</small></h2>
-${table(['id', '제목', '상태', '날짜', '결정별 3항목', '빈 항목'], ds.map(decisionRow))}
-${ds.map(decisionHtml).join('\n')}`;
-}

package/skills/progress-mon/scripts/pm-check.mjs

@@ -14,7 +14,7 @@ import { ITEM_STATUS, STAGE_STATUS } from './pm-data.mjs';
 import { archLayout, archFlaws, flowLayout, nameFits, FLOW } from './pm-render.mjs';
 import { color, finite, textW, wrap, TABS } from './pm-html.mjs';
 import { memoryWarnings } from './pm-memory.mjs';
-import { checkAdr, adrRows, cleanAdr, adrTally } from './pm-adr.mjs';
+import { checkAdr, adrRows, cleanAdr, adrTally, writeAdrCheck } from './pm-adr.mjs';
 
 const arr = (v) => (Array.isArray(v) ? v : []);
 const obj = (v) => (v && typeof v === 'object' && !Array.isArray(v) ? v : null);
@@ -531,7 +531,7 @@ function memoryInto(r, memory, project, env) {
   }
 }
 
-// 검사 전체. 돌려줌: { lines: [출력 줄], fails }
+// 검사 전체. 자료를 바꾸지 않는다. 돌려줌: { lines: [출력 줄], fails, adr: check 대조 기록 { sha, tally } (adr.json 이 없거나 깨졌으면 null) }
 export function runCheck(ctx, env = process.env) {
   const r = sink();
   const config = checkConfig(ctx, r);
@@ -543,8 +543,8 @@ export function runCheck(ctx, env = process.env) {
   const flow = checkFlow(ctx.dataDir, r);
   const arch = checkArch(ctx.dataDir, r, config.text.plannedPrefix);
   const got = checkAdr(ctx, config, r);
-  const adr = got && got.value;
-  const adrBare = got ? got.bare : [];
+  const adr = got.value;
+  const adrBare = got.bare;
   const inv = checkInventory(ctx, r);
   const memory = memoryOf(ctx);
   memoryInto(r, memory, ctx.project, env);
@@ -553,7 +553,8 @@ export function runCheck(ctx, env = process.env) {
   // 밀도는 init 기록이나 inventory.json 이 있을 때만. 다만 ADR 밀도는 adr.json 이 있으면 늘 낸다
   const dens = inv || memory ? density({ arch, flow, req, items: items.items, inv, storyCount: ids.length, adr, adrBare }) : null;
   const rows = dens ? dens.rows : adr ? adrRows(adr, adrBare) : [];
-  return finish(out, rows, dens, adrTally(adr, adrBare).text);
+  const tally = adrTally(adr, adrBare).text;
+  return { ...finish(out, rows, dens, tally), adr: got.sha ? { sha: got.sha, tally } : null };
 }
 
 // 밀도 미달 줄, 합계 줄, 탭별 밀도 요약, ADR 집계(근거 없음 칸, 미검증, 구현 못 함, 참조 없는 서술. 늘 한 줄)를 붙인다. 돌려줌: { lines, fails }
@@ -566,12 +567,20 @@ function finish(out, rows, dens, tally) {
   return { lines: out, fails };
 }
 
-// --adr-cleanup: 검사 전에 init 정리 단계(pm-adr.mjs cleanAdr)를 적용한다. 그 밖에는 자료를 바꾸지 않는다.
+// --adr-cleanup: 검사 전에 init 정리 단계(pm-adr.mjs cleanAdr)를 적용한다. 그 밖에는 자료를 바꾸지 않고,
+// 화면 대조용 adr-check.json 만 쓴다. 쓰지 못하면 stderr 경고(검사 결과와 종료 코드는 그대로).
 export async function command(cmd, ctx, o, io) {
   if (cmd !== 'check') throw new UsageError(`${cmd} 는 pm-check.mjs 가 맡지 않음`);
   if (o._.length > 1) throw new UsageError(`check 는 위치 인자를 받지 않음: ${o._.slice(1).join(' ')}`);
   if (o['adr-cleanup'] && ctx.exists) for (const l of await cleanAdr(ctx, loadConfig(ctx).config)) io.out(l);
-  const { lines, fails } = runCheck(ctx);
+  const { lines, fails, adr } = runCheck(ctx);
   for (const l of lines) io.out(l);
+  if (adr) {
+    try {
+      await writeAdrCheck(ctx.dataDir, adr);
+    } catch (e) {
+      io.err(`경고: ${e.message}. 화면의 check 대조가 낡을 수 있음`);
+    }
+  }
   return fails ? 1 : 0;
 }

package/skills/progress-mon/scripts/pm-config.mjs

@@ -1,4 +1,5 @@
 // pm-config.mjs: 프로젝트 루트와 자료 폴더 결정, 런타임 판별, config.json 읽기와 기본값, 형식 검사, 원자적 쓰기.
+import os from 'node:os';
 import fs from 'node:fs';
 import path from 'node:path';
 import net from 'node:net';
@@ -52,13 +53,64 @@ export function readRegular(file, encoding = 'utf8', fsx = fs, max = READ_MAX) {
   return fsx.readFileSync(file, encoding);
 }
 
+// 실제 경로. native 먼저(Windows 의 8.3 짧은 이름, macOS 와 Windows 의 디스크 대소문자로 푼다). 아직 없는 꼬리는 있는
+// 조상까지 풀고 붙인다(macOS 의 /var 는 /private/var 로 가는 링크).
+export function realNative(p) {
+  try {
+    return fs.realpathSync.native(p);
+  } catch {
+    try {
+      return fs.realpathSync(p);
+    } catch {
+      const up = path.dirname(p);
+      return up === p ? p : path.join(realNative(up), path.basename(p));
+    }
+  }
+}
+
+// 두 경로가 같은 폴더인지: 장치와 inode(bigint), inode 가 없는 파일 시스템은 realNative 철자(Windows, macOS 는 접어서).
+// 문자열 비교는 대소문자, 8.3 이름, 링크인 부모 폴더처럼 철자만 다른 같은 폴더를 다른 폴더로 본다.
+export function sameFolder(a, b) {
+  try {
+    const x = fs.statSync(a, { bigint: true });
+    const y = fs.statSync(b, { bigint: true });
+    if (x.ino !== 0n && y.ino !== 0n) return x.dev === y.dev && x.ino === y.ino;
+  } catch {
+    return false;
+  }
+  const fold = (p) => (process.platform === 'win32' || process.platform === 'darwin' ? p.toLowerCase() : p);
+  return fold(realNative(a)) === fold(realNative(b));
+}
+
 // 프로젝트 안 자료 폴더의 경로 가운데 링크인 첫 폴더(.omc, progress-mon 등). 없으면 null.
-// 프로젝트 밖(--data)이면 자료 폴더 자체만 본다. 아직 없는 폴더에서 멈춘다.
+// 프로젝트 밖(--data)이면 자료 폴더 자체만 본다. 아직 없는 폴더에서 멈춘다. 안팎은 자료 폴더에서 위로 올라가며
+// 프로젝트 루트와 같은 폴더(sameFolder)를 만나는지로 본다: --data 를 다른 대소문자나 8.3 이름으로 적어도 안으로 본다.
 function linkedDir(root, dataDir) {
-  const rel = path.relative(root, dataDir);
-  const inside = rel && !rel.startsWith('..') && !path.isAbsolute(rel);
-  const parts = inside ? rel.split(path.sep) : [];
-  const dirs = inside ? parts.map((_, i) => path.join(root, ...parts.slice(0, i + 1))) : [dataDir];
+  const isLink = (d) => {
+    try {
+      return fs.lstatSync(d).isSymbolicLink();
+    } catch {
+      return false;
+    }
+  };
+  // 위로 올라가며 루트를 찾는다. 링크가 아닌 루트를 만나면 그 아래가 안이다(.omc -> . 같은 안의 링크도 목록에 남아
+  // 거부된다). 끝까지 못 만나면 루트를 가리키는 첫 링크(루트를 링크 철자로 적은 --data)를 루트로 본다.
+  const up = [];
+  let rootAt = -1;
+  let linkRootAt = -1;
+  for (let d = dataDir; ; d = path.dirname(d)) {
+    if (sameFolder(d, root)) {
+      if (!isLink(d)) {
+        rootAt = up.length;
+        break;
+      }
+      if (linkRootAt < 0) linkRootAt = up.length;
+    }
+    up.push(d);
+    if (path.dirname(d) === d) break;
+  }
+  const cut = rootAt >= 0 ? rootAt : linkRootAt;
+  const dirs = cut > 0 ? up.slice(0, cut).reverse() : [dataDir];
   for (const d of dirs) {
     let st;
     try {
@@ -85,8 +137,11 @@ export function privateIPv4(ip) {
   return a === 10 || (a === 172 && b >= 16 && b <= 31) || (a === 192 && b === 168);
 }
 
-// git 출력(앞뒤 공백 제거). git 이 없거나 실패하면 예외.
-export const git = (cwd, args) => execFileSync('git', args, { cwd, encoding: 'utf8', windowsHide: true, stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+// git 출력(앞뒤 공백 제거). git 이 없거나 실패하면 예외. 홈 폴더에서 git -C 로 부른다: Windows 는 일하는 폴더의
+// 프로그램을 먼저 찾으므로, 프로젝트 안의 git.exe 가 실행되지 않게.
+// 프로그램을 띄울 폴더: 홈 폴더(없으면 임시 폴더).
+export const runDir = () => (fs.existsSync(os.homedir()) ? os.homedir() : os.tmpdir());
+export const git = (cwd, args) => execFileSync('git', ['-C', path.resolve(cwd), ...args], { cwd: runDir(), encoding: 'utf8', windowsHide: true, stdio: ['ignore', 'pipe', 'ignore'] }).trim();
 
 // 프로젝트 루트: --project, 아니면 cwd 의 git 최상위, 실패면 cwd.
 export function projectRoot(cwd, project) {
@@ -123,6 +178,77 @@ function pickContext({ cwd = process.cwd(), project, runtime, data } = {}) {
 // 사용법 오류(종료 1).
 export class UsageError extends Error {}
 
+// 고정 이름(잠금, 백업, 처음 만드는 설정)에 새 파일을 만든다(wx). 그 이름에 무엇이든 있으면 끊어진 링크까지 EEXIST.
+// 까닭: Windows 의 wx 는 끊어진 링크를 따라가 그 너머에 파일을 만든다(macOS, Linux 는 EEXIST). 그래서 먼저 lstat 로
+// 보고, 연 뒤 쓰기 전에 연 파일(fstat)과 이름(lstat)을 대조한다. 이름이 없거나 링크이거나 다른 파일이면 아무것도 쓰지
+// 않고 EEXIST(링크를 따라 만든 빈 파일은 지움). 볼 수 없으면(ESTALE, EPERM 등) 보통의 wx 처럼 그대로 쓴다. 쓰기가
+// 실패하면 이름이 아직 그 파일일 때 지운다(빈 잠금이나 빈 백업이 남지 않게). 처음 lstat 의 EPERM 등(Windows 에서 지우는
+// 중인 파일)은 그대로 던진다. 부른 쪽은 wx 의 같은 코드처럼 기다린다.
+export function writeNew(file, data, opts = {}, fsx = fs) {
+  if (fsx.lstatSync(file, { throwIfNoEntry: false }) !== undefined) throw eexist(file);
+  const fd = fsx.openSync(file, 'wx', opts.mode);
+  try {
+    const made = fstatOr(fd, fsx);
+    if (namesOpened(file, made, fsx) === false) throw eexist(file);
+    try {
+      fsx.writeFileSync(fd, data);
+    } catch (e) {
+      if (namesOpened(file, made, fsx) === true) fsx.rmSync(file, { force: true });
+      throw e;
+    }
+  } finally {
+    fsx.closeSync(fd);
+  }
+}
+
+const fstatOr = (fd, fsx) => {
+  try {
+    return fsx.fstatSync(fd, { bigint: true });
+  } catch {
+    return null;
+  }
+};
+
+// 이름이 연 파일(made)을 가리키는지: 참, 거짓(없음, 링크, 다른 파일), 볼 수 없으면 null. 링크면 그 링크로 만든 빈 파일을 지움.
+function namesOpened(file, made, fsx) {
+  let st;
+  try {
+    st = fsx.lstatSync(file, { bigint: true, throwIfNoEntry: false });
+  } catch {
+    return null;
+  }
+  if (!st) return false;
+  if (st.isSymbolicLink()) {
+    if (made) dropFollowed(file, made, fsx);
+    return false;
+  }
+  if (!made || made.ino === 0n) return null;
+  return st.dev === made.dev && st.ino === made.ino;
+}
+
+// 링크를 따라 연 파일이 아직 그 빈 파일이면 지운다.
+function dropFollowed(file, made, fsx) {
+  try {
+    const target = fsx.realpathSync(file);
+    const at = fsx.statSync(target, { bigint: true });
+    if (at.dev === made.dev && at.ino === made.ino && at.size === 0n) fsx.rmSync(target, { force: true });
+  } catch {
+    // 링크가 또 바뀜: 되돌릴 것을 찾지 못함
+  }
+}
+
+const eexist = (file) => Object.assign(new Error(`EEXIST: file already exists, open '${file}'`), { code: 'EEXIST', syscall: 'open', path: file });
+
+// 그 자리에 일반 파일이 아닌 것(링크, 폴더 등)이 있는지. 없거나 볼 수 없으면 거짓.
+export function notPlainFile(file, fsx = fs) {
+  try {
+    const st = fsx.lstatSync(file, { throwIfNoEntry: false });
+    return st !== undefined && !st.isFile();
+  } catch {
+    return false;
+  }
+}
+
 const RENAME_RETRIES = 5;
 const RENAME_STEP_MS = 50;
 const RENAME_RETRY_CODES = new Set(['EPERM', 'EBUSY', 'EACCES']);

package/skills/progress-mon/scripts/pm-data.mjs

@@ -4,7 +4,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import crypto from 'node:crypto';
-import { dataLabel, defaults, loadConfig, eventsPath, writeAtomic, git, noBom, readRegular, UsageError } from './pm-config.mjs';
+import { dataLabel, defaults, loadConfig, eventsPath, writeAtomic, writeNew, notPlainFile, git, noBom, readRegular, realNative, UsageError } from './pm-config.mjs';
 import { stageList } from './pm-sources.mjs';
 import { planMemory, applyMemory } from './pm-memory.mjs';
 
@@ -58,7 +58,7 @@ function readLock(file, fsx) {
 function breakStale(file, seen, fsx) {
   const brk = `${file}.break`;
   try {
-    fsx.writeFileSync(brk, JSON.stringify({ pid: process.pid, createdAt: new Date().toISOString() }) + '\n', { flag: 'wx' });
+    writeNew(brk, JSON.stringify({ pid: process.pid, createdAt: new Date().toISOString() }) + '\n', {}, fsx);
   } catch (e) {
     if (!BUSY_CODES.has(e.code)) return false;
     try {
@@ -97,6 +97,27 @@ function breakStale(file, seen, fsx) {
   return removed;
 }
 
+// 잠금을 한 번 만들어 본다. 돌려줌: 만들었으면 null, 아니면 기다릴 까닭 코드(EEXIST, Windows 의 EPERM 등).
+// 링크나 폴더가 잠금 자리에 있으면 풀릴 잠금이 아니므로 기다리지 않고 거부한다(끊어진 링크면 읽기가 없음으로 보여 헛돈다).
+function tryLockOnce(file, body, fsx, label) {
+  try {
+    writeNew(file, body, {}, fsx);
+    return null;
+  } catch (e) {
+    if (!BUSY_CODES.has(e.code)) throw new UsageError(`잠금 파일을 만들지 못함(${e.code || e.message})`);
+    if (notPlainFile(file, fsx)) throw new UsageError(`잠금 자리에 일반 파일이 아닌 것(링크나 폴더)이 있어 거부: ${label}items.json.lock`);
+    return e.code;
+  }
+}
+
+// 기다림이 끝났을 때의 오류. 잠금 파일이 끝내 없었으면 다른 쓰기가 아니라 만들지 못한 것(권한 등).
+function lockTimeout(code, seenLock, last, label) {
+  if (!seenLock && code !== 'EEXIST') return new UsageError(`잠금 파일을 만들지 못함(${code})`);
+  return new UsageError(
+    `다른 쓰기가 끝나지 않음(잠금 ${label}items.json.lock, pid ${last.pid ?? '알 수 없음'}, createdAt ${last.createdAt ?? '알 수 없음'}). 그 프로세스가 끝났는데도 남아 있으면 잠금 파일을 지운 뒤 다시 실행`,
+  );
+}
+
 // items.json.lock 을 wx 로 만든다. 있으면 50 ms 간격으로 최대 waitMs 기다린다.
 // Windows 에서 지우는 중인 파일에 wx 하면 EPERM(또는 EACCES, EBUSY)이라 EEXIST 처럼 기다린다.
 // 낡은 잠금은 breakStale 로만 정리한다.
@@ -109,27 +130,15 @@ export async function acquireLock(dataDir, { fsx = fs, waitMs = LOCK_WAIT_MS, la
   let last = {};
   let seenLock = false; // 기다리는 동안 잠금 파일이 한 번이라도 보였는지
   for (;;) {
-    let code;
-    try {
-      fsx.writeFileSync(file, body, { flag: 'wx' });
-      return { file, mine };
-    } catch (e) {
-      code = e.code;
-      if (!BUSY_CODES.has(code)) throw new UsageError(`잠금 파일을 만들지 못함(${code || e.message})`);
-    }
+    const code = tryLockOnce(file, body, fsx, label);
+    if (code === null) return { file, mine };
     const info = readLock(file, fsx);
     // 그 사이 풀림: 바로 다시. 지우는 중(EPERM 등)이면 아래에서 기다린다
     if (info === null && code === 'EEXIST' && Date.now() < until) continue;
     if (info) seenLock = true;
     if (info && info.pid !== undefined) last = info;
     if (staleLock(info, Date.now()) && breakStale(file, info, fsx)) continue;
-    if (Date.now() >= until) {
-      // 잠금 파일이 끝내 없었으면 다른 쓰기가 아니라 만들지 못한 것(권한 등)
-      if (!seenLock && code !== 'EEXIST') throw new UsageError(`잠금 파일을 만들지 못함(${code})`);
-      throw new UsageError(
-        `다른 쓰기가 끝나지 않음(잠금 ${label}items.json.lock, pid ${last.pid ?? '알 수 없음'}, createdAt ${last.createdAt ?? '알 수 없음'}). 그 프로세스가 끝났는데도 남아 있으면 잠금 파일을 지운 뒤 다시 실행`,
-      );
-    }
+    if (Date.now() >= until) throw lockTimeout(code, seenLock, last, label);
     await sleep(STEP_MS);
   }
 }
@@ -287,13 +296,6 @@ function storyChange(o, now, configIds) {
 const NEXT = ['다음 할 일', '  1. references/authoring.md 를 읽고 req-spec.json, reqs.json, flow.json, arch.json, adr.json 작성', '  2. check 로 검사. FAIL 0 까지 최대 3회', '  3. start 로 서버 시작'];
 
 const slash = (p) => p.split(path.sep).join('/');
-const realOr = (p) => {
-  try {
-    return fs.realpathSync(p);
-  } catch {
-    return p;
-  }
-};
 const inside = (rel) => rel && !rel.startsWith('..') && !path.isAbsolute(rel);
 
 // 자료 폴더를 git 제외 목록(git rev-parse --git-path info/exclude)에 한 줄 추가. 추적 파일은 바꾸지 않는다. 실패는 알림만.
@@ -306,8 +308,9 @@ function gitExclude(ctx) {
   } catch {
     return 'git 제외 목록: git 저장소 아님, 건너뜀';
   }
-  // 링크 경로(macOS /var 와 /private/var, Windows junction)로 부른 --project 도 git 최상위(실제 경로)와 맞게 푼다
-  const rel = path.relative(realOr(top), path.join(realOr(path.dirname(ctx.dataDir)), path.basename(ctx.dataDir)));
+  // 링크 경로(macOS /var 와 /private/var, Windows junction), 다른 대소문자, 8.3 이름으로 부른 --project 나 --data 도
+  // git 최상위와 같은 철자로 푼다(realNative: 디스크의 철자)
+  const rel = path.relative(realNative(top), realNative(ctx.dataDir));
   if (!inside(rel)) return 'git 제외 목록: 자료 폴더가 저장소 밖이라 건너뜀';
   const line = `/${slash(rel)}/`;
   const shown = inside(path.relative(ctx.project, excl)) ? slash(path.relative(ctx.project, excl)) : 'info/exclude';
@@ -334,10 +337,13 @@ function gitExclude(ctx) {
   return `git 제외 목록 추가: ${line} (${shown})`;
 }
 
-// 없을 때만 만든다. 돌려줌: 출력 줄.
+// 없을 때만 만든다. 돌려줌: 출력 줄. 가리키는 것이 없는 링크는 거부한다(만들면 링크 너머에 파일이 생긴다).
 function makeOnce(file, label, text) {
-  if (fs.existsSync(file)) return `그대로 둠: ${label}`;
-  fs.writeFileSync(file, text, { flag: 'wx' });
+  if (fs.lstatSync(file, { throwIfNoEntry: false }) !== undefined) {
+    if (fs.existsSync(file)) return `그대로 둠: ${label}`;
+    throw new UsageError(`${label} 자리에 가리키는 것이 없는 링크가 있어 거부`);
+  }
+  writeNew(file, text);
   return `새로 만듦: ${label}`;
 }
 

package/skills/progress-mon/scripts/pm-memory.mjs

@@ -2,10 +2,11 @@
 // 예외: 표식이 붙은 우리 줄(앞머리로 가린 규칙 줄과 색인 줄)이 지금 판과 다르면 그 줄만 제자리에서 바꾼다(첫 원본은 .progress-mon.bak).
 // 대상 파일은 에이전트가 넘긴다(--memory, --memory-dir). 스크립트는 HOME 아래 쓰기 경로를 스스로 만들지 않는다.
 // 덧붙인 뒤 규칙 로드 한도를 재고 경고 줄을 낸다(종료 코드는 그대로). status, check 도 같은 측정을 다시 한다.
+import crypto from 'node:crypto';
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
-import { git, readRegular, UsageError } from './pm-config.mjs';
+import { git, readRegular, realNative, UsageError, writeNew } from './pm-config.mjs';
 
 export const MARKER = '<!-- progress-mon:rule -->';
 export const OMX_OPEN = '<!-- USER:OMX:POLICY:START -->';
@@ -159,8 +160,10 @@ const gitTop = (dir) => {
 // Codex 프로젝트 지시 합계: 저장소 루트에서 프로젝트 루트까지 각 폴더에서 Codex 가 읽는 파일 크기의 합.
 export function measureCodex(project, env = process.env) {
   const limit = codexLimit(env);
-  const proj = path.resolve(project);
-  const top = gitTop(proj);
+  // 둘 다 디스크의 철자로 푼다: 링크나 다른 대소문자로 준 --project 가 저장소 밖으로 보여 지시 파일을 빼먹지 않게
+  const proj = realNative(path.resolve(project));
+  const top0 = gitTop(proj);
+  const top = top0 && realNative(top0);
   const rel = top ? path.relative(top, proj) : '';
   const dirs = [top && !rel.startsWith('..') && !path.isAbsolute(rel) ? top : proj];
   if (dirs[0] !== proj) for (const part of rel.split(path.sep).filter(Boolean)) dirs.push(path.join(dirs[dirs.length - 1], part));
@@ -349,7 +352,8 @@ function rewrite(file, body) {
   const real = fs.realpathSync(file);
   const st = fs.statSync(real);
   if (!st.isFile() || st.nlink > 1) throw changedError(file);
-  const tmp = `${real}.${process.pid}.${Date.now().toString(36)}.tmp`;
+  // 임시 이름은 난수: Windows 의 wx 는 끊어진 링크를 따라가므로, 미리 맞힐 수 있는 이름이면 링크를 심어 둘 수 있다.
+  const tmp = `${real}.${process.pid}.${crypto.randomBytes(6).toString('hex')}.tmp`;
   try {
     fs.writeFileSync(tmp, body, { flag: 'wx', mode: st.mode & 0o777 });
     fs.chmodSync(tmp, st.mode & 0o7777);
@@ -368,13 +372,16 @@ function rewrite(file, body) {
   }
 }
 
-// 첫 원본 백업. 이미 있으면 덮지 않는다. 만들지 못하면 바꾸지 않고 거부.
+// 첫 원본 백업. 이미 있으면 덮지 않는다. 만들지 못하거나 그 자리에 일반 파일이 아닌 것(링크 등)이 있으면 바꾸지 않고 거부.
 function backup(file, buf) {
   const bak = `${file}.progress-mon.bak`;
   try {
-    fs.writeFileSync(bak, buf, { flag: 'wx' });
+    writeNew(bak, buf);
   } catch (e) {
-    if (e.code !== 'EEXIST') throw new UsageError(`${path.basename(bak)} 백업을 만들지 못해 규칙 줄을 바꾸지 않음(${e.code || e.message})`);
+    // EEXIST 는 그 자리에 일반 파일(먼저 남긴 첫 원본)이 있을 때만 통과. 링크, 폴더, 그 사이 사라진 이름은 거부
+    const st = e.code === 'EEXIST' ? fs.lstatSync(bak, { throwIfNoEntry: false }) : null;
+    const why = e.code !== 'EEXIST' ? e.code || e.message : !st ? '만든 뒤 이름이 사라짐' : !st.isFile() ? '일반 파일이 아닌 것(링크나 폴더)이 있음' : null;
+    if (why) throw new UsageError(`${path.basename(bak)} 백업을 만들지 못해 규칙 줄을 바꾸지 않음(${why})`);
   }
   return bak;
 }

package/skills/progress-mon/scripts/pm-render.mjs

@@ -6,7 +6,7 @@ import path from 'node:path';
 import { esc, color, finite, textW, wrap, FAVICON, CSS, TABS, tabsHtml } from './pm-html.mjs';
 import { configOrFail, loadConfig, UsageError, DEFAULT_REQ_RULE, STORYLESS_REQ_RULE } from './pm-config.mjs';
 import { collect, parseTime, agentJudge } from './pm-sources.mjs';
-import { adrBody } from './pm-adr.mjs';
+import { adrBody } from './pm-adr-view.mjs';
 
 const two = (n) => String(n).padStart(2, '0');
 const hm = (ms) => (ms == null ? '-' : Math.floor(ms / 3600e3) + ':' + two(Math.floor((ms % 3600e3) / 60000)));