leerness 1.9.253 → 1.9.255

package/CHANGELOG.md

@@ -1,5 +1,77 @@
 # Changelog
 
+## 1.9.255 — 2026-05-29 — UR-0019 2단계: PATH 등록 실제 테스트/디버그 + require.main 가드
+
+**🧪 사용자 명시 (UR-0019 후속 "테스트 및 디버그 다음라운드 참고"): PATH 자동 등록 실제 동작 검증 + 테스트 인프라.**
+
+### 배경
+1.9.254에서 `path-setup` 구현 후, 실제 `--apply` 등록 로직(Unix shell-rc append, Windows PS-script)의 깊은 테스트/디버그가 필요. 단, 실 PATH 변경은 위험 → 단위 테스트 가능하도록 리팩터링.
+
+### 구현 (테스트 가능성 + 안전 검증)
+1. **`require.main === module` 가드** (footgun fix):
+   - `node harness.js` / `npx leerness` CLI 직접 실행 시에만 `main()` 호출
+   - `require('harness.js')` 시 init 부작용 없이 내부 함수 import 가능 → 단위 테스트 활성화
+   - 기존 CLI 동작 100% 보존 (e2e 217 검증)
+2. **순수 함수 추출** (테스트/디버그 가능):
+   - `_winPathPsScript(bin)` — Windows User PATH 등록 PowerShell 스크립트 생성 (실행과 분리)
+   - `_unixPathBlock(bin)` — Unix shell-rc export 블록 생성 (마커 멱등)
+   - `_registerPath` — `process.platform` → `diag.platform` (테스트 시 플랫폼 주입 가능)
+3. **8종 헬퍼 module.exports** (test 인프라)
+
+### 실제 테스트/디버그 결과 (stress-v200, 실 PATH 미변경)
+- **Unix shell-rc 실제 등록**: temp 파일에 1차 등록(shell-rc) → 2차 멱등(already, export 1줄만) → 마커 존재 → 기존 rc 내용 보존(append-only) ✓
+- **Windows PS-script**: User scope SetEnvironmentVariable / setx 미사용(truncation 회피) / -notcontains 멱등 가드 / bin JSON 이스케이프 ✓
+- **edge**: globalBin null → ok=false / shellRc null → ok=false / _dirInPath trailing-slash 정규화 ✓
+
+### stress-v200 — **27/27 PASS · 100%**
+- 테스트 인프라 (4): require.main 가드 + 8종 export + CLI 동작
+- Unix 실제 등록 (5) + Windows PS (4) + edge (5) + 성능/누적 회귀 (9)
+
+### 자동 release (117 main-push streak · 78 npm publish streak · R211)
+
+🧪 **PATH 등록 실증 + 테스트 인프라** — require.main 가드로 내부 함수 단위 테스트 가능 (이후 라운드 회귀 강화 기반).
+
+---
+
+## 1.9.254 — 2026-05-29 — UR-0019 leerness CLI PATH 자동 등록
+
+**🔗 사용자 명시 (UR-0019): "leerness 설치 시 leerness CLI가 PATH를 자동으로 등록될 수 있게 구현". (테스트/디버그는 다음 라운드 참고)**
+
+### 배경
+`npm i -g leerness` 설치 후 npm global bin 디렉토리가 PATH에 없으면 `leerness` 명령이 동작하지 않음 (특히 Windows nvm/수동 Node 설치 환경). 설치 직후 자동 감지 + 안전 등록.
+
+### 구현 (`leerness path-setup [--apply] [--json]` + install 자동 안내)
+1. **진단 헬퍼 5종**:
+   - `_npmGlobalBin()` — `npm prefix -g` 기반 global bin 감지 (Windows=prefix, Unix=prefix/bin, fallback=node dir)
+   - `_dirInPath(dir)` — 플랫폼별 정규화(대소문자/구분자/trailing slash) 후 PATH 포함 확인
+   - `_leernessResolvable()` — `where`/`which` 로 실제 실행 가능 여부
+   - `_pathDiagnose()` — globalBin/inPath/resolvable/shellRc 종합
+   - `_registerPath(diag)` — 플랫폼별 안전 등록
+2. **플랫폼별 안전 등록**:
+   - **Windows**: PowerShell `[Environment]::SetEnvironmentVariable('PATH', ..., 'User')` — User scope (관리자 권한 불요), `setx`의 1024자 truncation 회피, 멱등(중복 시 EXISTS)
+   - **Unix**: shell rc(`.zshrc`/`.bashrc`/`.profile`) 에 `export PATH` 블록 append — 마커(`# >>> leerness PATH`)로 멱등
+3. **안전 원칙** (글로벌 룰: 안정성 > 성능, 엄격 처리):
+   - **dry-run 기본** — `--apply` 명시해야 실제 등록
+   - **멱등** — 이미 등록/PATH 포함 시 "등록 불필요"
+   - **append-only** — 기존 PATH 덮어쓰기 절대 없음
+4. **install 완료 자동 안내**: PATH 미등록 감지 시 `🔗 leerness CLI PATH 미등록` + `path-setup --apply` 안내. opt-out `LEERNESS_NO_PATH_CHECK=1`
+5. **env summary 힌트** + `path` 별칭
+
+### 다음 라운드 참고 (사용자 명시)
+- 실제 `--apply` 등록 동작 깊은 테스트/디버그 (Windows User PATH 반영 확인, Unix rc source 후 동작)
+- 신규 셸 세션에서 PATH 반영 검증
+
+### stress-v199 — **25/25 PASS · 100%**
+- 1.9.254 (12): VERSION + 헬퍼 5종 + dispatch + Windows PS/Unix rc 등록 + dry-run + install 안내 + 실제 실행(진단/json/별칭/정규화) + env 힌트
+- 성능 (1): cold start avg 434ms
+- 누적 회귀 (12): 1.9.207~253
+
+### 자동 release (116 main-push streak · 77 npm publish streak · R210)
+
+🔗 **설치 후 즉시 사용 가능** — npm global bin PATH 누락 자동 감지 + 안전 등록 (opt-in).
+
+---
+
 ## 1.9.253 — 2026-05-29 — CLAUDE/AGENTS 문서 누적 갱신 (1.9.238~252 drift 차단)
 
 **📚 문서 drift 차단: 메타 지침서가 1.9.237에 멈춰 있어 15 라운드(1.9.238~252) 미반영 → 누적 갱신.**

package/README.md

@@ -2,7 +2,7 @@
 
 > **AI 코딩 에이전트의 거짓 완료·중복·망각·충돌을 막아주는 검수·기억·협업 CLI 하네스.**
 
-[![npm](https://img.shields.io/badge/npm-leerness-blue)](https://www.npmjs.com/package/leerness) [![version](https://img.shields.io/badge/version-1.9.253-green)]() [![tests](https://img.shields.io/badge/e2e-217%2F217-success)]() [![stress](https://img.shields.io/badge/stress--v198-21%2F21-success)]() [![mcp](https://img.shields.io/badge/MCP--tools-70-brightgreen)]() [![cli](https://img.shields.io/badge/CLI_commands-57-brightgreen)]() [![json-fields](https://img.shields.io/badge/JSON_통합-11_필드-blueviolet)]() [![rounds](https://img.shields.io/badge/autonomous_R-209-blueviolet)]() [![main-push](https://img.shields.io/badge/🎉_main--push_streak-115_rounds-success)]() [![npm-streak](https://img.shields.io/badge/🎉_npm--publish-76_streak-success)]() [![encoding](https://img.shields.io/badge/🌐_인코딩보호-Windows%2BPOSIX-blueviolet)]() [![perf](https://img.shields.io/badge/cold_start-368ms-success)]() [![license](https://img.shields.io/badge/license-MIT-lightgrey)]()
+[![npm](https://img.shields.io/badge/npm-leerness-blue)](https://www.npmjs.com/package/leerness) [![version](https://img.shields.io/badge/version-1.9.255-green)]() [![tests](https://img.shields.io/badge/e2e-217%2F217-success)]() [![stress](https://img.shields.io/badge/stress--v200-27%2F27-success)]() [![mcp](https://img.shields.io/badge/MCP--tools-70-brightgreen)]() [![cli](https://img.shields.io/badge/CLI_commands-57-brightgreen)]() [![json-fields](https://img.shields.io/badge/JSON_통합-11_필드-blueviolet)]() [![rounds](https://img.shields.io/badge/autonomous_R-211-blueviolet)]() [![main-push](https://img.shields.io/badge/🎉_main--push_streak-117_rounds-success)]() [![npm-streak](https://img.shields.io/badge/🎉_npm--publish-78_streak-success)]() [![encoding](https://img.shields.io/badge/🌐_인코딩보호-Windows%2BPOSIX-blueviolet)]() [![perf](https://img.shields.io/badge/cold_start-368ms-success)]() [![license](https://img.shields.io/badge/license-MIT-lightgrey)]()
 
 ```
   ╔══════════════════════════════════════════════════════════════╗
@@ -12,9 +12,9 @@
   ║  ██║     ██╔══╝  ██╔══╝  ██╔══██╗██║╚██╗██║██╔══╝  ╚════██║  ║
   ║  ███████╗███████╗███████╗██║  ██║██║ ╚████║███████╗███████║  ║
   ║  ╚══════╝╚══════╝╚══════╝╚═╝  ╚═╝╚═╝  ╚═══╝╚══════╝╚══════╝  ║
-  ║  v1.9.253  AI Agent Reliability Harness + Sandbox            ║
+  ║  v1.9.255  AI Agent Reliability Harness + Sandbox            ║
   ║  verify · remember · orchestrate · audit · sandbox · drift   ║
-  ║  📚 AI 핸드오프 지침 최신화 (UR-0013~0018 · R209)             ║
+  ║  🧪 PATH 등록 실증 + require.main 가드 (UR-0019 · R211)        ║
   ╚══════════════════════════════════════════════════════════════╝
 ```
 

package/bin/harness.js

@@ -7,7 +7,7 @@ const cp = require('child_process');
 const os = require('os');  // 1.9.178: _publishToNpm 에서 os.tmpdir() 사용 (전역 import)
 const readline = require('readline');
 
-const VERSION = '1.9.253';
+const VERSION = '1.9.255';
 
 // 1.9.184: DEP0190 (child_process shell: true) deprecation warning 억제 (사용자 명시).
 //   leerness 는 cross-platform PATH resolution 을 위해 shell: true 를 의도적으로 사용 (claude.cmd / ollama.cmd 등 Windows .cmd 처리).
@@ -1069,6 +1069,19 @@ async function install(root, opts = {}) {
         }
       } catch {}
     }
+    // 1.9.254 (UR-0019): init 완료 시 leerness CLI 가 PATH 에서 안 찾아지면 자동 등록 안내 (사용자 명시)
+    //   opt-out: LEERNESS_NO_PATH_CHECK=1. 자동 등록은 강제하지 않고 안내만 (--apply 명시 필요).
+    if (!opts.migration && process.env.LEERNESS_NO_PATH_CHECK !== '1') {
+      try {
+        const diag = _pathDiagnose();
+        if (!diag.resolvable && !diag.inPath && diag.globalBin) {
+          log('');
+          log(`\x1b[33m🔗 leerness CLI PATH 미등록 (1.9.254, UR-0019)\x1b[0m`);
+          log(`\x1b[2m   npm global bin (${diag.globalBin}) 이 PATH 에 없어 'leerness' 명령이 안 먹힐 수 있음\x1b[0m`);
+          log(`\x1b[36m   → 자동 등록: leerness path-setup --apply\x1b[0m`);
+        }
+      } catch {}
+    }
     // 1.9.1 P7: 디폴트 M-0001이 plan에 있고 progress에 row가 없으면 자동 추가
     try {
       const planText = exists(planPath(root)) ? read(planPath(root)) : '';
@@ -2699,9 +2712,176 @@ function envCmd(root, sub) {
   }
   log('');
   log(dm(`  → 인코딩 검사: leerness env encoding-check (셸 스크립트 .ps1/.bat 위험 감지)`));
+  log(dm(`  → PATH 등록: leerness path-setup (leerness CLI 가 PATH 에서 안 찾아질 때)`));
   log(dm(`  → JSON 출력: leerness env --json`));
 }
 
+// 1.9.254: leerness CLI PATH 자동 등록 (사용자 명시 UR-0019)
+//   배경: `npm i -g leerness` 했는데 npm global bin 이 PATH 에 없으면 `leerness` 명령이 안 먹힘.
+//   해결: global bin 경로 감지 + PATH 포함 여부 확인 → 미등록 시 플랫폼별 안전 등록 (opt-in --apply).
+//   안전 원칙 (글로벌 룰: 안정성 > 성능, 엄격 처리): dry-run 기본 / 멱등 / append-only / 덮어쓰기 금지.
+
+// npm global bin 디렉토리 감지 (npm prefix -g + bin, fallback: process.execPath 기반)
+function _npmGlobalBin() {
+  // 1) npm prefix -g (가장 정확) — Windows 는 prefix 자체가 bin, Unix 는 prefix/bin
+  try {
+    const r = cp.spawnSync('npm', ['prefix', '-g'], { encoding: 'utf8', shell: true, timeout: 5000 });
+    if (r.status === 0) {
+      const prefix = (r.stdout || '').trim().split(/\r?\n/).pop();
+      if (prefix) return process.platform === 'win32' ? prefix : path.join(prefix, 'bin');
+    }
+  } catch {}
+  // 2) fallback: 현재 실행 중인 node 의 디렉토리 (global bin 이 보통 같은 위치)
+  try { return path.dirname(process.execPath); } catch {}
+  return null;
+}
+
+// 주어진 디렉토리가 현재 PATH 에 포함되어 있는지 (대소문자/구분자 정규화)
+function _dirInPath(dir) {
+  if (!dir) return false;
+  const sep = process.platform === 'win32' ? ';' : ':';
+  const norm = s => {
+    let p = (s || '').trim().replace(/["']/g, '');
+    try { p = path.normalize(p); } catch {}
+    p = p.replace(/[\\/]+$/, '');
+    return process.platform === 'win32' ? p.toLowerCase() : p;
+  };
+  const want = norm(dir);
+  return (process.env.PATH || '').split(sep).map(norm).filter(Boolean).includes(want);
+}
+
+// leerness 가 PATH 에서 실행 가능한지 (which/where 사용)
+function _leernessResolvable() {
+  try {
+    const probe = process.platform === 'win32' ? 'where' : 'which';
+    const r = cp.spawnSync(probe, ['leerness'], { encoding: 'utf8', shell: true, timeout: 5000 });
+    return r.status === 0 && /leerness/i.test((r.stdout || ''));
+  } catch { return false; }
+}
+
+// PATH 등록 상태 진단 (반환: { globalBin, inPath, resolvable, platform, shellRc })
+function _pathDiagnose() {
+  const globalBin = _npmGlobalBin();
+  const inPath = _dirInPath(globalBin);
+  const resolvable = _leernessResolvable();
+  let shellRc = null;
+  if (process.platform !== 'win32') {
+    const home = os.homedir();
+    const shell = process.env.SHELL || '';
+    if (/zsh/.test(shell)) shellRc = path.join(home, '.zshrc');
+    else if (/bash/.test(shell)) shellRc = path.join(home, '.bashrc');
+    else shellRc = path.join(home, '.profile');
+  }
+  return { globalBin, inPath, resolvable, platform: process.platform, shellRc };
+}
+
+// 1.9.255 (UR-0019 2단계): Windows User PATH 등록용 PowerShell 스크립트 생성 (순수 함수 — 테스트/디버그 가능)
+//   setx 의 1024자 truncation 회피 위해 [Environment]::SetEnvironmentVariable User scope 사용.
+//   멱등: 현재 User PATH 에 이미 있으면 EXISTS, 없으면 append 후 ADDED. 시스템 PATH 불변 (관리자 권한 불요).
+function _winPathPsScript(bin) {
+  return [
+    "$b = " + JSON.stringify(bin) + ";",
+    "$u = [Environment]::GetEnvironmentVariable('PATH','User'); if (-not $u) { $u = '' }",
+    "$parts = $u.Split(';') | Where-Object { $_ -ne '' }",
+    "if ($parts -notcontains $b) {",
+    "  $nu = if ($u -eq '') { $b } else { $u.TrimEnd(';') + ';' + $b }",
+    "  [Environment]::SetEnvironmentVariable('PATH', $nu, 'User')",
+    "  Write-Output 'ADDED'",
+    "} else { Write-Output 'EXISTS' }"
+  ].join(' ');
+}
+
+// 1.9.255 (UR-0019 2단계): Unix shell rc 등록 블록 마커 (순수 — 테스트/디버그 가능, 멱등 키)
+const _UNIX_PATH_MARKER = '# >>> leerness PATH (managed) >>>';
+const _UNIX_PATH_END = '# <<< leerness PATH <<<';
+function _unixPathBlock(bin) {
+  return `\n${_UNIX_PATH_MARKER}\nexport PATH="$PATH:${bin}"\n${_UNIX_PATH_END}\n`;
+}
+
+// PATH 에 globalBin 등록 (플랫폼별 안전 방법). 반환: { ok, method, detail }
+//   1.9.255: process.platform → diag.platform 으로 변경 (테스트 가능 — diag.platform 은 실사용 시 process.platform 과 동일).
+function _registerPath(diag) {
+  const bin = diag.globalBin;
+  if (!bin) return { ok: false, method: 'none', detail: 'npm global bin 경로를 찾을 수 없음' };
+  const platform = diag.platform || process.platform;
+  if (platform === 'win32') {
+    // Windows: PowerShell [Environment]::SetEnvironmentVariable User scope (멱등, 관리자 권한 불요)
+    try {
+      const ps = _winPathPsScript(bin);
+      const r = cp.spawnSync('powershell', ['-NoProfile', '-Command', ps], { encoding: 'utf8', timeout: 10000 });
+      const out = (r.stdout || '').trim();
+      if (r.status === 0 && /ADDED/.test(out)) return { ok: true, method: 'powershell-user-path', detail: `User PATH 에 추가됨 (새 터미널부터 적용): ${bin}` };
+      if (r.status === 0 && /EXISTS/.test(out)) return { ok: true, method: 'already', detail: `User PATH 에 이미 존재: ${bin}` };
+      return { ok: false, method: 'powershell-user-path', detail: `등록 실패 (exit ${r.status}): ${(r.stderr || out || '').trim().slice(0, 200)}` };
+    } catch (e) { return { ok: false, method: 'powershell-user-path', detail: `예외: ${e.message}` }; }
+  }
+  // Unix: shell rc 파일에 export 블록 append (멱등 — 마커로 중복 차단)
+  try {
+    const rc = diag.shellRc;
+    if (!rc) return { ok: false, method: 'shell-rc', detail: 'shell rc 경로 미확인' };
+    let cur = '';
+    try { cur = fs.readFileSync(rc, 'utf8'); } catch {}
+    if (cur.includes(_UNIX_PATH_MARKER)) return { ok: true, method: 'already', detail: `${rc} 에 이미 등록됨` };
+    fs.appendFileSync(rc, _unixPathBlock(bin), 'utf8');
+    return { ok: true, method: 'shell-rc', detail: `${rc} 에 추가됨 (source 또는 새 터미널부터 적용): ${bin}` };
+  } catch (e) { return { ok: false, method: 'shell-rc', detail: `예외: ${e.message}` }; }
+}
+
+function pathSetupCmd(root, opts = {}) {
+  const isTty = process.stdout && process.stdout.isTTY;
+  const cy = s => isTty ? `\x1b[36m${s}\x1b[0m` : s;
+  const gr = s => isTty ? `\x1b[32m${s}\x1b[0m` : s;
+  const yl = s => isTty ? `\x1b[33m${s}\x1b[0m` : s;
+  const dm = s => isTty ? `\x1b[2m${s}\x1b[0m` : s;
+  const diag = _pathDiagnose();
+  if (opts.json) {
+    let applied = null;
+    if (opts.apply && !diag.resolvable && !diag.inPath) applied = _registerPath(diag);
+    log(JSON.stringify({ ...diag, applied }, null, 2));
+    return;
+  }
+  log(cy(`# leerness path-setup (1.9.254, UR-0019) — CLI PATH 자동 등록`));
+  log('');
+  log(`  npm global bin: ${diag.globalBin ? gr(diag.globalBin) : yl('감지 실패')}`);
+  log(`  PATH 포함 여부: ${diag.inPath ? gr('✓ 포함됨') : yl('✗ 미포함')}`);
+  log(`  leerness 실행 가능: ${diag.resolvable ? gr('✓ 가능 (which/where 성공)') : yl('✗ 불가')}`);
+  log('');
+  if (diag.resolvable || diag.inPath) {
+    log(gr(`  ✓ leerness CLI 가 이미 PATH 에서 정상 동작합니다 — 등록 불필요`));
+    return;
+  }
+  if (!diag.globalBin) {
+    log(yl(`  ⚠ npm global bin 경로를 찾을 수 없어 자동 등록 불가`));
+    log(dm(`     → 수동: npm prefix -g 로 경로 확인 후 PATH 에 추가`));
+    return;
+  }
+  if (!opts.apply) {
+    // dry-run (기본)
+    log(yl(`  ⚠ leerness 가 PATH 에 없습니다 — 'leerness' 명령이 동작하지 않을 수 있음`));
+    log(`  ${dm('적용 시 추가될 경로:')} ${diag.globalBin}`);
+    if (diag.platform === 'win32') {
+      log(dm(`     방법: PowerShell [Environment]::SetEnvironmentVariable('PATH', ..., 'User')  (관리자 권한 불요)`));
+    } else {
+      log(dm(`     방법: ${diag.shellRc} 에 export PATH 블록 append (멱등)`));
+    }
+    log('');
+    log(cy(`  → 자동 등록: leerness path-setup --apply`));
+    return;
+  }
+  // --apply
+  const res = _registerPath(diag);
+  if (res.ok) {
+    log(gr(`  ✓ PATH 등록 완료 (${res.method})`));
+    log(`     ${res.detail}`);
+    log('');
+    if (diag.platform === 'win32') log(dm(`  → 새 터미널을 열면 'leerness' 명령을 바로 쓸 수 있습니다.`));
+    else log(dm(`  → source ${diag.shellRc} 또는 새 터미널에서 'leerness' 명령 사용 가능.`));
+  } else {
+    log(yl(`  ⚠ 자동 등록 실패 (${res.method}): ${res.detail}`));
+    log(dm(`     → 수동 등록: PATH 에 ${diag.globalBin} 추가`));
+  }
+}
+
 // 1.9.245: API skill cache — 공식 문서 + 관련 링크 자동 정리 (사용자 명시 UR-0015)
 //   .harness/api-skills/<id>.md 에 frontmatter + 본문 저장. handoff 자동 매칭.
 //   Node built-in https (의존성 0), depth=1 same-domain crawl, max 10 links.
@@ -19713,6 +19893,9 @@ async function main() {
   //   기존 env check/sync/detect (1.9.71) 와 충돌하지 않음 — summary/encoding 신규 서브
   if (cmd === 'env' && (args[1] === 'summary' || args[1] === 'encoding' || args[1] === 'encoding-check'))
     return envCmd(arg('--path', process.cwd()), args[1] === 'summary' ? null : 'encoding-check');
+  // 1.9.254: leerness path-setup [--apply] — CLI PATH 자동 등록 (사용자 명시 UR-0019)
+  //   npm global bin 경로 감지 + leerness 가 PATH 에서 찾아지는지 확인 → 미등록 시 플랫폼별 등록
+  if (cmd === 'path-setup' || cmd === 'path')        return pathSetupCmd(arg('--path', process.cwd()), { apply: has('--apply'), json: has('--json') });
   // 1.9.245: API skill cache — 공식 문서·관련링크 자동 정리 (사용자 명시 UR-0015)
   if (cmd === 'api-skill')                           return apiSkillCmd(arg('--path', process.cwd()), args[1] || 'help');
   // 1.9.208: leerness constraints <list|check|add> — 플랫폼/API 제약 사전 체크 (사용자 명시)
@@ -19854,6 +20037,18 @@ async function main() {
 }
 
 // 1.9.4 B: main 종료 후 exitCode를 명시적으로 process.exit으로 강제 (셸/wrapper 차 무시).
-main()
-  .then(() => { if (process.exitCode && process.exitCode !== 0) process.exit(process.exitCode); })
-  .catch(err => { fail(err && err.message ? err.message : String(err)); process.exit(1); });
+// 1.9.255 (UR-0019 2단계): require.main 가드 — `require('harness.js')` 시 main() 미실행 (init 부작용 차단 + 내부 함수 단위 테스트 가능).
+//   CLI 직접 실행 (node harness.js / npx leerness) 시에만 main() 호출. 기존 동작 100% 보존.
+if (require.main === module) {
+  main()
+    .then(() => { if (process.exitCode && process.exitCode !== 0) process.exit(process.exitCode); })
+    .catch(err => { fail(err && err.message ? err.message : String(err)); process.exit(1); });
+}
+
+// 1.9.255: 테스트/디버그용 내부 함수 export (require.main 가드 덕분에 require 시 CLI 미실행).
+//   PATH 등록 (UR-0019) 검증 + 향후 단위 테스트 확장에 사용.
+module.exports = {
+  VERSION,
+  _npmGlobalBin, _dirInPath, _leernessResolvable, _pathDiagnose, _registerPath,
+  _winPathPsScript, _unixPathBlock, pathSetupCmd
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "leerness",
-  "version": "1.9.253",
+  "version": "1.9.255",
   "description": "Leerness: 비파괴 마이그레이션, 자동 버전 감지·업데이트, 계획/진행/핸드오프 자동화, 게으름·시크릿·인코딩 자동 가드, Claude Code 슬래시 통합을 갖춘 한국어 우선 AI 개발 하네스.",
   "keywords": [
     "leerness",