leerness 1.9.297 → 1.9.298

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## 1.9.298 — 2026-06-04 — UR-0038: writeUtf8 원자적 쓰기 (외부 AI 리뷰 3중수렴 #1)
+
+**🔒 외부 AI 리뷰 3종(Codex gpt-5.5 · Sonnet 4.8 · Opus 4.8)이 공통 high로 지적한 최우선 신뢰성 이슈 해소 — 모든 상태 파일 쓰기를 원자적(temp→rename)으로 전환해 부분쓰기 손상을 근본 차단. "메모리 항상 보존" 약속을 코드로 보증.**
+
+### 배경
+세 리뷰가 독립적으로 동일 지적: `writeUtf8()`(중앙 쓰기 헬퍼, 109곳 사용)가 `fs.writeFileSync` 직접 호출이라 crash/타임아웃 kill/동시쓰기 중 **부분 기록으로 상태 파일이 손상**될 수 있음. 실제로 1.9.293에서 progress-tracker.md 69줄 손상 전례. README/FAQ가 "사용자 메모리 항상 보존"을 핵심 약속으로 내세우나 코드 보증이 없었음.
+
+### 구현 (UR-0038 — 원자적 쓰기 부분)
+1. **`writeUtf8()` 원자화** — temp 파일(`<path>.tmp-<pid>-<seq>`)에 기록 후 `fs.renameSync(tmp, path)` 원자 교체. rename 은 동일 디렉토리(=동일 FS)라 POSIX/NTFS 모두 원자적(Node renameSync = MOVEFILE_REPLACE_EXISTING). 109개 모든 호출처(progress-tracker/decisions/rules/plan/session-handoff/.leerness 상태)가 자동 보호.
+2. **실패 안전** — 쓰기 실패 시 temp 정리(unlink) 후 throw. temp 이름이 확장자 끝이 아니라(`.tmp-PID-SEQ`) `*.md` glob 에 안 걸림(파서 오염 방지).
+3. selftest 45→46 (원자 패턴 소스 검증) · e2e 242→243 (반복쓰기 후 무손상 + 헤더 1개 + temp 잔여 0 실측).
+
+### 검증
+- **selftest 46/46 PASS** · **E2E 243/243 PASS** (회귀 0).
+- 실측: init + task add×3 + decision add×3 반복 후 progress-tracker 정확(중복/손상 0) · `.harness` 전체에 `.tmp-` 잔여 0 · 헤더 1줄 유지.
+
+### 남은 부분 (UR-0038 후속)
+- 동시 writer **lost-update**(read-modify-write 경합) 방지를 위한 상태 파일 락 — 별도 후속 라운드(원자 쓰기로 손상 클래스는 이미 제거됨, 락은 rare 한 동시쓰기 유실 대비).
+
 ## 1.9.297 — 2026-06-04 — UR-0025 (5단계): MCP 도구 정의 → lib/mcp-tools.js 단일출처 (Codex #5 영구 해소)
 
 **🧩 모놀리스 분리 5단계 — 첫 "기능 영역" 분리. MCP 도구 정의 81종을 단일출처 모듈로 분리하며 `_mcpToolCount` 의 `__filename` regex self-count(Codex #5 취약성)를 영구 해소.**

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.297-green)]() [![tests](https://img.shields.io/badge/e2e-242%2F242-success)]() [![selftest](https://img.shields.io/badge/selftest-45-success)]() [![mcp](https://img.shields.io/badge/MCP--tools-81-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.298-green)]() [![tests](https://img.shields.io/badge/e2e-243%2F243-success)]() [![selftest](https://img.shields.io/badge/selftest-46-success)]() [![mcp](https://img.shields.io/badge/MCP--tools-81-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.297 하네스를 사용합니다. AI 에이전트는 작업 전 `leerness handoff`로 컨텍스트를 적재하고, 작업 후 `leerness check`/`leerness audit`/`leerness session close`를 수행해야 합니다.
+이 프로젝트는 Leerness v1.9.298 하네스를 사용합니다. 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.297는 stdio JSON-RPC MCP server를 내장합니다 — Claude Code · Cursor · Codex CLI 등 외부 AI에 **81개 도구**를 노출:
+Leerness v1.9.298는 stdio JSON-RPC MCP server를 내장합니다 — Claude Code · Cursor · Codex CLI 등 외부 AI에 **81개 도구**를 노출:
 
 ```jsonc
 // 카테고리별
@@ -546,7 +546,7 @@ Leerness v1.9.297는 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.297)** · 매 라운드 GitHub release/태그 생성 · _reports/는 비공개 보존.
+현재 누적: **70 라운드 (1.9.40 → 1.9.298)** · 매 라운드 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.297: 2026-06-04
+Last synced by Leerness v1.9.298: 2026-06-04
 <!-- leerness:project-readme:end -->
 

package/bin/harness.js

@@ -12,7 +12,7 @@ const { _isSecretKey, compareVer, parseHarnessVersion, _classifyCJK, _riskLabel,
 // 1.9.295 (UR-0025 4단계): 정적 데이터 카탈로그 모듈 분리 (비파괴, require-based).
 const { CAPABILITY_SURFACE, POWERFUL_COMMANDS, ADAPTERS, REUSE_CATEGORIES, REUSE_CHECKLIST } = require('../lib/catalogs');
 
-const VERSION = '1.9.297';
+const VERSION = '1.9.298';
 
 // 1.9.290 (UR-0037, Codex gpt-5.5 #4 수렴): CLI 전용 부작용은 require 시 실행하지 않는다.
 //   이전: warning listener 제거 / NODE_OPTIONS 변경 / chcp IIFE 가 top-level 즉시 실행 → require('harness') 시 호스트 프로세스 오염.
@@ -172,7 +172,22 @@ function read(p) {
 }
 function readBuf(p) { return fs.readFileSync(p); }
 function mkdirp(p) { fs.mkdirSync(p, { recursive: true }); }
-function writeUtf8(p, s) { mkdirp(path.dirname(p)); fs.writeFileSync(p, s, { encoding: 'utf8' }); }
+// 1.9.298 (UR-0038, 외부리뷰 3중수렴): 원자적 쓰기 — temp 파일에 기록 후 rename(원자 교체)으로 부분쓰기 손상 방지.
+//   crash/타임아웃 kill/동시쓰기 중에도 대상 파일에 깨진 부분파일이 남지 않음 ('메모리 항상 보존' 코드 보증).
+//   rename 은 동일 디렉토리(=동일 FS) 라 POSIX/NTFS 모두 원자적(Node renameSync = MOVEFILE_REPLACE_EXISTING).
+//   temp 이름은 확장자 끝이 아니라 .tmp-PID-SEQ 라 *.md glob 에 안 걸림. 실패 시 temp 정리.
+let _writeSeq = 0;
+function writeUtf8(p, s) {
+  mkdirp(path.dirname(p));
+  const tmp = `${p}.tmp-${process.pid}-${++_writeSeq}`;
+  try {
+    fs.writeFileSync(tmp, s, { encoding: 'utf8' });
+    fs.renameSync(tmp, p);
+  } catch (e) {
+    try { if (fs.existsSync(tmp)) fs.unlinkSync(tmp); } catch {}
+    throw e;
+  }
+}
 function append(p, s) { mkdirp(path.dirname(p)); fs.appendFileSync(p, s, 'utf8'); }
 function rel(root, p) { return path.relative(root, p).replace(/\\/g, '/') || '.'; }
 function today() { return new Date().toISOString().slice(0, 10); }
@@ -3018,6 +3033,7 @@ function _selfTestCases() {
     { name: 'lib/catalogs: CAPABILITY/ADAPTERS/REUSE 모듈 단일출처 분리 (UR-0025 1.9.295)', run: () => { const m = require('../lib/catalogs'); return m.CAPABILITY_SURFACE === CAPABILITY_SURFACE && m.ADAPTERS === ADAPTERS && m.REUSE_CATEGORIES === REUSE_CATEGORIES && m.REUSE_CHECKLIST === REUSE_CHECKLIST && m.POWERFUL_COMMANDS === POWERFUL_COMMANDS && Object.keys(m.CAPABILITY_SURFACE).length === 6 && !/const CAPABILITY_SURFACE = \{/.test(read(__filename)); } },
     { name: 'about: 정체성 verb(AI 운영 레이어) + MCP leerness_about 등록 (UR-0030 1.9.296)', run: () => { const id = _leernessIdentity(); const src = read(__filename); return typeof aboutCmd === 'function' && /운영 레이어/.test(id.identity) && id.layers.length === 5 && id.surface.mcpTools >= 81 && require('../lib/mcp-tools').some(t => t.name === 'leerness_about') && /case 'leerness_about':/.test(src) && /cmd === 'about' \|\| cmd === 'identity'/.test(src); } },
     { name: 'lib/mcp-tools: MCP 도구 정의 모듈 단일출처 (_mcpToolCount=모듈 length, Codex #5 영구해소) (UR-0025 1.9.297)', run: () => { const T = require('../lib/mcp-tools'); return Array.isArray(T) && T.length >= 81 && T.every(t => t.name && t.description && t.inputSchema) && T[0].name === 'leerness_handoff' && _mcpToolCount() === T.length && !/const TOOLS = \[/.test(read(__filename)); } },
+    { name: 'writeUtf8: 원자적 쓰기(temp→rename) 손상방지 (UR-0038 외부리뷰 3중수렴 1.9.298)', run: () => { const src = read(__filename); return /function writeUtf8\(p, s\)/.test(src) && /fs\.writeFileSync\(tmp,/.test(src) && /fs\.renameSync\(tmp, p\)/.test(src) && /\.tmp-\$\{process\.pid\}/.test(src) && /fs\.unlinkSync\(tmp\)/.test(src); } },
     { name: 'VERSION 형식 (x.y.z)', run: () => /^\d+\.\d+\.\d+$/.test(VERSION) }
   ];
 }

package/package.json

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

package/scripts/e2e.js

@@ -3269,5 +3269,33 @@ total++;
   if (!ok) failed++;
 }
 
+// 1.9.298 회귀 (UR-0038 외부리뷰): writeUtf8 원자적 쓰기 — 반복 쓰기 후 무손상 + temp 잔여 0
+total++;
+{
+  let ok = false;
+  try {
+    const aDir = fs.mkdtempSync(path.join(os.tmpdir(), 'leerness-atomic-'));
+    cp.spawnSync(process.execPath, [CLI, 'init', aDir, '--yes', '--language', 'ko', '--skills', 'recommended'], { encoding: 'utf8', timeout: 30000 });
+    // writeUtf8 경유 명령 반복 (progress-tracker/decisions 갱신)
+    for (let i = 0; i < 3; i++) {
+      cp.spawnSync(process.execPath, [CLI, 'task', 'add', `원자성 테스트 T-${i}`, '--path', aDir], { encoding: 'utf8', timeout: 15000 });
+      cp.spawnSync(process.execPath, [CLI, 'decision', 'add', `결정 ${i}`, '--reason', 'r', '--path', aDir], { encoding: 'utf8', timeout: 15000 });
+    }
+    const pt = fs.readFileSync(path.join(aDir, '.harness', 'progress-tracker.md'), 'utf8');
+    // (1) 3개 task 모두 기록 + 구분자 라인 1개(중복/손상 없음). 라인 기준 카운트(|---|---| 한 줄에 부분매치 다수 방지).
+    const sepLines = pt.split('\n').filter(l => /^\|---\|/.test(l)).length;
+    const tasksOk = /원자성 테스트 T-0/.test(pt) && /원자성 테스트 T-2/.test(pt) && sepLines === 1;
+    // (2) .harness 어디에도 .tmp- 잔여 파일 없음 (rename 완료)
+    const walk = (d) => fs.readdirSync(d, { withFileTypes: true }).flatMap(e => e.isDirectory() ? walk(path.join(d, e.name)) : [path.join(d, e.name)]);
+    const tmpLeftover = walk(path.join(aDir, '.harness')).filter(f => /\.tmp-\d+-\d+$/.test(f));
+    // (3) 소스에 renameSync 원자 패턴 존재
+    const srcOk = /fs\.renameSync\(tmp, p\)/.test(fs.readFileSync(path.resolve(__dirname, '..', 'bin', 'harness.js'), 'utf8'));
+    ok = tasksOk && tmpLeftover.length === 0 && srcOk;
+    fs.rmSync(aDir, { recursive: true, force: true });
+  } catch {}
+  console.log(ok ? '✓ B(1.9.298) writeUtf8 원자적 쓰기: 반복쓰기 무손상 + temp 잔여 0 (UR-0038 외부리뷰)' : '✗ writeUtf8 원자성 실패');
+  if (!ok) failed++;
+}
+
 console.log(`\nE2E result: ${total - failed}/${total} passed · ${((Date.now() - _e2eStart) / 1000).toFixed(0)}s`);
 if (failed > 0) process.exit(1);