leerness 1.9.354 → 1.9.355

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 1.9.355 — 2026-06-05 — UR-0075 Phase A: 크로스버전 마이그레이션 가이드 + migrate/update --path
+
+**🧩 AI 에이전트용 크로스버전 마이그레이션 가이드(`migrate --guide`) + init/migrate/update `--path` 지원.** (UR-0075 Phase A — 비전 착수, 외부리뷰 버그 전량 해소 후)
+
+### 배경
+외부리뷰 P0~P3 전량 해소로 안전 기반 마련 → 비전 착수. 마이그레이션은 leerness 핵심 가치("비파괴 마이그레이션"). 가이드가 `update --path`/`migrate --path` 를 권하므로 정확성 위해 --path 지원을 함께 보강(UR-0059 확장).
+
+### 구현
+1. **`_migrationGuideText(version)`**(순수) + **`leerness migrate --guide`/`migrate guide`** — AI 에이전트용 안전 워크플로: 안전 스냅샷(git) → `npx leerness@latest update --check --path <project>`(감지) → `--yes`(임시설치·.harness/archive 백업·신 스키마) → `git diff`/`selftest`/`check` 검증 → canonical JSON 백필 메모 → 롤백.
+2. **init/migrate/update `--path` 지원** (UR-0059 확장): `install(arg('--path', args[1] || cwd))` / `updateCmd(arg('--path', ...))` — 이전엔 `args[1] || cwd` 로 positional 전용·`--path` 무시. 이제 --path > positional > cwd. (가이드의 `update --path` 정확성)
+
+### 검증
+- **selftest 102/102 PASS** · **E2E 299→300 PASS** (회귀 0).
+- 실측: `migrate --guide` 가이드 출력(0.원칙~6.롤백) · `migrate guide` subcommand 동일 · `update --check --path B`(cwd A) → B 의 HARNESS_VERSION(1.9.6) 읽음(=--path 동작, 이전 cwd A).
+
 ## 1.9.354 — 2026-06-05 — 외부리뷰 P3 클러스터 (UR-0072) · 외부리뷰 백로그 소진
 
 **🧩 외부 리뷰 P3 핵심 4종 — compareVer pre-release · _classifyCJK 일본어 오판 · scan secrets 파일경로 · requests drop 아이콘.**

package/README.md

@@ -3,7 +3,7 @@
 > **AI 코딩 에이전트의 거짓 완료·중복·망각·충돌을 막아주는 검수·기억·협업 CLI 하네스.**
 > **A CLI harness that stops AI coding agents from faking completion, duplicating work, forgetting context, and colliding.**
 
-[![npm](https://img.shields.io/badge/npm-leerness-blue)](https://www.npmjs.com/package/leerness) [![version](https://img.shields.io/badge/version-1.9.354-green)]() [![tests](https://img.shields.io/badge/e2e-299%2F299-success)]() [![selftest](https://img.shields.io/badge/selftest-101-success)]() [![mcp](https://img.shields.io/badge/MCP--tools-83-brightgreen)]() [![providers](https://img.shields.io/badge/AI_providers-10-brightgreen)]() [![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.355-green)]() [![tests](https://img.shields.io/badge/e2e-300%2F300-success)]() [![selftest](https://img.shields.io/badge/selftest-102-success)]() [![mcp](https://img.shields.io/badge/MCP--tools-83-brightgreen)]() [![providers](https://img.shields.io/badge/AI_providers-10-brightgreen)]() [![license](https://img.shields.io/badge/license-MIT-lightgrey)]()
 
 ```
   ╔══════════════════════════════════════════════════════════════╗
@@ -471,7 +471,7 @@ MIT — © leerness contributors
 <!-- leerness:project-readme:start -->
 ## Leerness Project Harness
 
-이 프로젝트는 Leerness v1.9.354 하네스를 사용합니다. AI 에이전트는 작업 전 `leerness handoff`로 컨텍스트를 적재하고, 작업 후 `leerness check`/`leerness audit`/`leerness session close`를 수행해야 합니다.
+이 프로젝트는 Leerness v1.9.355 하네스를 사용합니다. AI 에이전트는 작업 전 `leerness handoff`로 컨텍스트를 적재하고, 작업 후 `leerness check`/`leerness audit`/`leerness session close`를 수행해야 합니다.
 
 ### 정체성 — AI 에이전트 운영 레이어 (UR-0030)
 
@@ -525,7 +525,7 @@ leerness memory restore decision <date|title>
 
 ### MCP server (외부 AI 통합)
 
-Leerness v1.9.354는 stdio JSON-RPC MCP server를 내장합니다 — Claude Code · Cursor · Codex CLI 등 외부 AI에 **83개 도구**를 노출:
+Leerness v1.9.355는 stdio JSON-RPC MCP server를 내장합니다 — Claude Code · Cursor · Codex CLI 등 외부 AI에 **83개 도구**를 노출:
 
 ```jsonc
 // 카테고리별
@@ -546,7 +546,7 @@ Leerness v1.9.354는 stdio JSON-RPC MCP server를 내장합니다 — Claude Cod
 `<<autonomous-loop-dynamic>>` 신호만 보내면 AI가:
 1) 다음 라운드 후보 선정 → 2) 코드 변경 → 3) stress-v* 신규 작성 + 누적 회귀 → 4) e2e 219/219 → 5) npm pack + git tag + GitHub release → 6) main 자동 push (1.9.140+) → 7) session close → 8) 다음 라운드 예약.
 
-현재 누적: **70 라운드 (1.9.40 → 1.9.354)** · 매 라운드 GitHub release/태그 생성 · _reports/는 비공개 보존.
+현재 누적: **70 라운드 (1.9.40 → 1.9.355)** · 매 라운드 GitHub release/태그 생성 · _reports/는 비공개 보존.
 
 ### 성능 가이드 (1.9.140 측정)
 
@@ -584,6 +584,6 @@ leerness release pack --close --auto-main-push
 - `.harness/session-handoff.md`: 다음 세션 인수인계 (자동 작성)
 - `.harness/lessons.md` / `decisions.md` / `rules.md`: 영구 메모리 (5 surface)
 
-Last synced by Leerness v1.9.354: 2026-06-05
+Last synced by Leerness v1.9.355: 2026-06-05
 <!-- leerness:project-readme:end -->
 

package/bin/harness.js

@@ -21,13 +21,14 @@ const { _isSecretKey, compareVer, parseHarnessVersion, _classifyCJK, _riskLabel,
   _detectOptimism: _puDetectOptimism, _computeConfidence: _puComputeConfidence,
   _personaSummaries, _translate,
   _decisionsFromMd, _renderDecisionsMd, _renderLessonsMd,
-  _withBuiltinSource, _esc, _roadmapTokenStyles, _parseSkillMd } = require('../lib/pure-utils');  // 1.9.318~347 (UR-0025/0053): 순수 유틸 모듈 분리
+  _withBuiltinSource, _esc, _roadmapTokenStyles, _parseSkillMd,
+  _migrationGuideText } = require('../lib/pure-utils');  // 1.9.318~355 (UR-0025/0053/0075): 순수 유틸 모듈 분리
 // 1.9.304 (UR-0025): 순수 분석/검증 함수 모듈 분리.
 const { _evidenceQuality, _parseEvidenceStats, _shellGuardAnalyze, _claimFileInGit, _epistemicHonestyCheck } = require('../lib/analyzers');
 // 1.9.295 (UR-0025 4단계): 정적 데이터 카탈로그 모듈 분리 (비파괴, require-based).
 const { CAPABILITY_SURFACE, POWERFUL_COMMANDS, ADAPTERS, REUSE_CATEGORIES, REUSE_CHECKLIST, _DEFAULT_PLATFORM_CONSTRAINTS, _DEFAULT_DOMAIN_CATALOG, _LSP_LANG_PATTERNS, OPTIMISM_PATTERNS, BUILT_IN_PERSONAS, STRINGS, BUILTIN_CATALOG, ROADMAP_STATUS_LABEL, ROADMAP_STATUS_COLOR, SECRET_PATTERNS, SKILL_CATALOG_PRESETS } = require('../lib/catalogs');  // 1.9.344 (UR-0025): SKILL_CATALOG_PRESETS 분리
 
-const VERSION = '1.9.354';
+const VERSION = '1.9.355';
 
 // 1.9.290 (UR-0037, Codex gpt-5.5 #4 수렴): CLI 전용 부작용은 require 시 실행하지 않는다.
 //   이전: warning listener 제거 / NODE_OPTIONS 변경 / chcp IIFE 가 top-level 즉시 실행 → require('harness') 시 호스트 프로세스 오염.
@@ -3058,6 +3059,7 @@ function _selfTestCases() {
     { name: 'UR-0068(외부리뷰 P2): _roadmapParseMilestones 블록 경계 — 다음 milestone status 누출 차단', run: () => { const m = require('../lib/pure-utils'); const r = m._roadmapParseMilestones('### M-0001. A\n\n### M-0002. B\nStatus: done\nProgress: 80%\n'); return r.length === 2 && r[0].status === 'planned' && r[0].progress === 0 && r[1].status === 'done' && r[1].progress === 80; } },
     { name: 'UR-0066(외부리뷰 P2): shell:true 주입 가드 — agents bench task _shellQuoteArg + fetchNpmLatest npm.cmd', run: () => { const m = require('../lib/pure-utils'); const src = read(__filename); const benchQuoted = src.includes('const qTask = ' + '_shellQuoteArg(task)'); const npmCmd = /'win32' \? 'npm\.cmd' : 'npm'/.test(src); const q = m._shellQuoteArg('a & b'); const safe = (process.platform === 'win32' ? q === '"a & b"' : q === "'a & b'"); return benchQuoted && npmCmd && safe; } },
     { name: 'UR-0072(외부리뷰 P3): compareVer pre-release + _classifyCJK 한자 kana 귀속', run: () => { const m = require('../lib/pure-utils'); const verOk = m.compareVer('1.9.0-beta', '1.9.0') === -1 && m.compareVer('1.9.0', '1.9.0-beta') === 1 && m.compareVer('1.9.5', '1.9.5') === 0 && m.compareVer('1.9.6', '1.9.5') === 1; const jp = Buffer.from([0xE3, 0x81, 0x82, 0xE6, 0x97, 0xA5, 0xE6, 0x9C, 0xAC]); const cn = Buffer.from([0xE4, 0xB8, 0xAD, 0xE5, 0x9B, 0xBD]); const rj = m._classifyCJK(jp, jp.length); const rc = m._classifyCJK(cn, cn.length); const cjkOk = rj.japanese > rj.chinese && rc.chinese > 0 && rc.japanese === 0; return verOk && cjkOk; } },
+    { name: 'UR-0075 Phase A: 마이그레이션 가이드(_migrationGuideText) + migrate --guide 와이어 + init/migrate/update --path', run: () => { const m = require('../lib/pure-utils'); const g = m._migrationGuideText('1.9.355'); const guideOk = typeof g === 'string' && g.includes('마이그레이션 가이드') && g.includes('update --check --path') && g.includes('selftest') && g.includes('canonical JSON') && g.includes('롤백') && g.includes('1.9.355'); const src = read(__filename); const wired = src.includes("has('--guide') || args[1] === " + "'guide'") && src.includes('install(arg(' + "'--path', args[1] || process.cwd())") && src.includes('updateCmd(arg(' + "'--path', args[1] || process.cwd())"); return guideOk && wired; } },
     { name: 'VERSION 형식 (x.y.z)', run: () => /^\d+\.\d+\.\d+$/.test(VERSION) }
   ];
 }
@@ -20998,7 +21000,7 @@ async function main() {
     } catch {}
   }
   // 1.9.276 (GPT-5.5 2차 리뷰): init --dry-run(미리보기) / --minimal(핵심 파일만) / --no-env(.env 생략)
-  if (cmd === 'init')      return await install(args[1] || process.cwd(), { force:has('--force'), dry:has('--dry-run'), migration:false, minimal:has('--minimal'), noEnv:has('--no-env') });
+  if (cmd === 'init')      return await install(arg('--path', args[1] || process.cwd()), { force:has('--force'), dry:has('--dry-run'), migration:false, minimal:has('--minimal'), noEnv:has('--no-env') });  // 1.9.355 (UR-0075): --path 지원
   // 1.9.64: install <skill-id-or-url> 별칭 (= skill install). 자주 쓰는 명령 단축형.
   // 단, init이 leerness install . 같은 형태로도 동작하던 옛 호환은 유지 — args[1]이 디렉토리면 init으로 라우팅.
   if (cmd === 'install') {
@@ -21016,8 +21018,9 @@ async function main() {
     fail(`알 수 없는 install 대상: ${arg1}\n  SKILL.md 파일/URL/SKILL.md 포함 디렉토리 필요`);
     return process.exit(1);
   }
-  if (cmd === 'migrate')   return await install(args[1] || process.cwd(), { force:has('--force'), dry:has('--dry-run'), migration:true });
-  if (cmd === 'update')    return await updateCmd(args[1] || process.cwd(), { checkOnly: has('--check'), yes: has('--yes'), force: has('--force') });
+  if (cmd === 'migrate' && (has('--guide') || args[1] === 'guide')) { log(_migrationGuideText(VERSION)); return; }  // 1.9.355 (UR-0075 Phase A): 크로스버전 마이그레이션 가이드
+  if (cmd === 'migrate')   return await install(arg('--path', args[1] || process.cwd()), { force:has('--force'), dry:has('--dry-run'), migration:true });  // 1.9.355 (UR-0075): --path 지원
+  if (cmd === 'update')    return await updateCmd(arg('--path', args[1] || process.cwd()), { checkOnly: has('--check'), yes: has('--yes'), force: has('--force') });  // 1.9.355 (UR-0075): --path 지원
   if (cmd === 'auto-update' && args[1] === 'install') return autoUpdateInstall(arg('--path', args[2] || process.cwd()));
   if (cmd === 'status')    return status(arg('--path', args[1] || process.cwd()));
   if (cmd === 'verify')    return verify(arg('--path', args[1] || process.cwd()));

package/lib/pure-utils.js

@@ -661,5 +661,48 @@ module.exports = {
   // 1.9.338 (UR-0025 심층): i18n 순수 조회
   _translate,
   // 1.9.339 (UR-0053): decisions canonical 파서/렌더 (JSON canonical, MD projection)
-  _parseDecisionBlock, _decisionsFromMd, _renderDecisionsMd
+  _parseDecisionBlock, _decisionsFromMd, _renderDecisionsMd,
+  // 1.9.355 (UR-0075 Phase A): 크로스버전 마이그레이션 가이드
+  _migrationGuideText
 };
+
+// 1.9.355 (UR-0075 Phase A): AI 에이전트용 크로스버전 마이그레이션 안전 워크플로 가이드 (순수 텍스트). 임시설치 + --path + 백업 + diff 검증.
+function _migrationGuideText(version) {
+  const v = version || 'latest';
+  const L = [
+    '# leerness 크로스버전 마이그레이션 가이드 (UR-0075, AI 에이전트용)',
+    '',
+    '아주 오래된 구버전부터 신규(' + v + ')까지 — 기존 프로젝트의 .harness 내용을 안전·비파괴로 마이그레이션.',
+    '',
+    '## 0. 원칙',
+    '- 비파괴: leerness 는 migrate/update 시 .harness/archive 에 자동 백업. 그래도 git 커밋/브랜치 선행 권장.',
+    '- dry-run 우선: 먼저 --check 로 감지, diff 로 확인 후 적용.',
+    '',
+    '## 1. 안전 스냅샷 (권장)',
+    '  git add -A && git commit -m "chore: pre-leerness-migration snapshot"   # 또는 브랜치: git checkout -b chore/leerness-migrate',
+    '',
+    '## 2. 신규 버전 감지 (구버전 프로젝트 대상)',
+    '  npx leerness@latest update --check --path <project>      # 현재 버전 vs 최신 비교 (네트워크 비차단, 비파괴)',
+    '',
+    '## 3. 마이그레이션 적용 (임시설치 = npx 캐시, 격리)',
+    '  npx leerness@latest update --yes --path <project>        # 자동 마이그레이션 (.harness/archive 백업 + 신 스키마 반영)',
+    '  # 또는: npx leerness@latest migrate <project> --force    # 강제 재스캐폴딩(비파괴, 기존 내용 보존)',
+    '',
+    '## 4. 검증 (필수)',
+    '  git -C <project> diff                                    # 생성/수정 파일 전수 확인 (예상치 못한 변경 점검)',
+    '  npx leerness@latest selftest                             # 코어 무결성 (위치독립, 어디서든 통과)',
+    '  npx leerness@latest check --path <project>               # 프로젝트 무결성',
+    '  npx leerness@latest doctor                               # 설치 진단',
+    '',
+    '## 5. 크로스버전 메모',
+    '- decisions/lessons: 구 MD-only → canonical JSON 자동 백필(첫 write 시). decisions.json/lessons.json 이 진실소스, .md 는 projection.',
+    '- 아주 구버전: update 가 단계적으로 누적 마이그레이션. 한 번에 안 되면 update --yes 재실행.',
+    '- 보호 파일(.harness/protected-files.md): 삭제 금지 — merge/archive/deprecated 마커 사용.',
+    '',
+    '## 6. 롤백',
+    '  git -C <project> checkout -- .                           # git 스냅샷 복원',
+    '  # 또는 .harness/archive/<timestamp> 에서 수동 복구 · leerness memory restore <surface> <target>',
+    ''
+  ];
+  return L.join('\n');
+}

package/package.json

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

package/scripts/e2e.js

@@ -4751,5 +4751,31 @@ total++;
   if (!ok) failed++;
 }
 
+// 1.9.355 회귀 (UR-0075 Phase A): migrate --guide 가이드 출력 + update/init/migrate --path 타깃(이전 positional 전용)
+total++;
+{
+  let ok = false;
+  try {
+    const m = require(path.resolve(__dirname, '..', 'lib', 'pure-utils.js'));
+    const g = m._migrationGuideText('9.9.9');
+    const pureOk = g.includes('마이그레이션 가이드') && g.includes('update --check --path') && g.includes('selftest') && g.includes('9.9.9');
+    const gr = cp.spawnSync(process.execPath, [CLI, 'migrate', '--guide'], { encoding: 'utf8', timeout: 20000 });
+    const guideOk = /마이그레이션 가이드/.test(gr.stdout || '') && /git/.test(gr.stdout || '');
+    // update --path: A(cwd) 에서 --path B 가 B 의 HARNESS_VERSION 을 읽음(=--path 동작, 이전엔 cwd A)
+    const A = fs.mkdtempSync(path.join(os.tmpdir(), 'leerness-mga-'));
+    const Bd = fs.mkdtempSync(path.join(os.tmpdir(), 'leerness-mgb-'));
+    cp.spawnSync(process.execPath, [CLI, 'init', A, '--yes', '--language', 'ko'], { encoding: 'utf8', timeout: 30000 });
+    cp.spawnSync(process.execPath, [CLI, 'init', Bd, '--yes', '--language', 'ko'], { encoding: 'utf8', timeout: 30000 });
+    fs.writeFileSync(path.join(Bd, '.harness', 'HARNESS_VERSION'), '1.9.6\n');
+    const ur = cp.spawnSync(process.execPath, [CLI, 'update', '--check', '--path', Bd], { cwd: A, encoding: 'utf8', timeout: 30000, env: { ...process.env, LEERNESS_OFFLINE: '1' } });
+    const pathOk = /1\.9\.6/.test((ur.stdout || '') + (ur.stderr || ''));
+    fs.rmSync(A, { recursive: true, force: true });
+    fs.rmSync(Bd, { recursive: true, force: true });
+    ok = pureOk && guideOk && pathOk;
+  } catch {}
+  console.log(ok ? '✓ B(1.9.355) UR-0075 Phase A: 마이그레이션 가이드 + update --path 타깃 (UR-0075)' : '✗ UR-0075 가이드 실패');
+  if (!ok) failed++;
+}
+
 console.log(`\nE2E result: ${total - failed}/${total} passed · ${((Date.now() - _e2eStart) / 1000).toFixed(0)}s`);
 if (failed > 0) process.exit(1);