leerness 1.9.305 → 1.9.307

package/CHANGELOG.md

@@ -1,5 +1,43 @@
 # Changelog
 
+## 1.9.307 — 2026-06-04 — UR-0055 (1단계): 프로젝트 청사진 brief (README 개요 + 복사용 blueprint)
+
+**📘 사용자 명시 — 프로젝트 개요/소개/목적/기능을 README 에 작성·유지하고, 그 내용만 복사하면 신규 프로젝트를 기초부터 재시작할 수 있는 자기완결 청사진(blueprint) 생성. 기존 `.harness/project-brief.md` 비파괴 확장.**
+
+### 배경 (사용자 명시)
+"개발 중인 프로그램/프로젝트의 소개·목적·설명을 README 에 쓰고, 개발 방향 변경/확대 시 업데이트, 복사하면 신규 프로젝트 계획으로 쓸 수 있게(기초부터 재시작)". 기존 project-brief.md(Project/Purpose/Users/Success)는 빈약 → 10필드로 확장 + README 동기화 + export.
+
+### 구현 (UR-0055 1단계)
+1. **`.harness/project-brief.md` 10필드 확장** — intro/purpose/problem/features/stack/architecture/users/success/nonGoals/currentState (`## Section` 블록, 파서/직렬화, frontmatter 보존, 비파괴).
+2. **`leerness brief set --intro/--purpose/--features/--stack/...`** — 정본 갱신 + README `## 프로젝트 개요` 관리 섹션(`<!-- leerness:project-brief:start/end -->`) 자동 동기화. **멱등 업데이트**(주어진 필드만 갱신, 나머지 보존 → 개발 방향 변경/확대 반영).
+3. **`leerness brief show [--json]`** — 채움 현황(N/10) + 필드 표시.
+4. **`leerness brief export [--out plan.md]`** — 자기완결 blueprint(소개+목적+문제+기능+아키텍처+스택+성공기준+비목표+현재상태 + "신규 프로젝트 시작 가이드") → 복사하면 기초부터 재시작 가능.
+5. selftest 54→55 · e2e 251→252.
+
+### 검증
+- **selftest 55/55 PASS** · **E2E 252/252 PASS** (회귀 0).
+- 실측: `brief set` → project-brief.md(## Intro/Features) + README 개요 섹션 동기화 · 멱등 업데이트(--purpose 만 갱신 시 intro/features 보존) · README 섹션 중복 0(재sync) · `brief export` blueprint(방향 변경 반영 + 신규프로젝트 가이드).
+
+### 남은 부분 (UR-0055 2단계)
+- `brief update --direction "..."`(개발 방향 변경 이력 누적) + handoff/context 청사진 노출 확장 + MCP `leerness_brief` 도구.
+
+## 1.9.306 — 2026-06-04 — UR-0045: exit code 일관성 (설치리뷰 3중수렴 high)
+
+**🚦 clean-install 리뷰에서 Codex·Sonnet·Opus 가 공통 high 로 지적한 "실패가 exit 0" 문제 수정 — CI·MCP·AI 에이전트가 실패를 성공으로 오판하던 근본 신뢰 결함. (직전 라운드의 인식론적 정직성과 직결: 에이전트가 거짓 성공을 믿지 않게.)**
+
+### 배경 (Codex#1 · Sonnet#1 · Opus)
+설치 후 실측: `leerness unknowncmd`/`decision add`(인자 누락)/`task badsubcmd` 가 오류 메시지를 내면서도 **exit 0** 반환. 원인: `fail(s)` 가 `✗ s` 로그만 하고 exit code 미설정(243개 호출 전부), unknown 명령은 help 로 fall-through. CI/스크립트/MCP/에이전트가 실패를 성공으로 오인.
+
+### 구현 (UR-0045)
+1. **`fail()` → `process.exitCode = 1`** — 243개 모든 오류 경로가 실패 신호. `process.exit` 즉시종료가 아니라 exitCode 설정(후속 출력/정리 보존, main 종료 wrapper 가 강제). 비치명 경고는 기존 `warn()` 유지.
+2. **unknown 명령 fall-through** — 명시적 `help`/`commands`/`--help` 는 exit 0(의도), 그 외 미인식 명령은 `✗ 알 수 없는 명령: <cmd>` 안내 + exit 1. unknown 서브커맨드(task badsubcmd 등)도 fall-through → exit 1.
+3. selftest 53→54 · e2e 250→251.
+
+### 검증
+- **selftest 54/54 PASS** · **E2E 251/251 PASS** (회귀 0).
+- **fail() 변경 회귀 0 실증**: 251개 e2e 중 정상 종료해야 할 명령(status/task list/verify/audit/context/about/handoff/selftest…) 전부 exit 0 유지. 오류 경로(unknown/인자누락/badsub) exit 1, --help/--version exit 0.
+- 범위: 입력값 스키마 검증(rule trigger/task status 등 무효값 거부)은 UR-0046(별도), 이번은 exit code 신호 일관성에 집중.
+
 ## 1.9.305 — 2026-06-04 — honesty-check: AI 인식론적 정직성 점검 (사용자 명시)
 
 **🧠 사용자 요청 — AI 가 (1) 모르는 걸 아는 척, (2) 정보를 안 모으고, (3) 검증 없이 섣부르게 판단하는지를 점검하는 인식론적 정직성 가드 신설.**

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

package/bin/harness.js

@@ -14,7 +14,7 @@ const { _evidenceQuality, _parseEvidenceStats, _shellGuardAnalyze, _claimFileInG
 // 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.305';
+const VERSION = '1.9.307';
 
 // 1.9.290 (UR-0037, Codex gpt-5.5 #4 수렴): CLI 전용 부작용은 require 시 실행하지 않는다.
 //   이전: warning listener 제거 / NODE_OPTIONS 변경 / chcp IIFE 가 top-level 즉시 실행 → require('harness') 시 호스트 프로세스 오염.
@@ -61,6 +61,9 @@ if (require.main === module) _cliBootstrap();
 const MARK = '<!-- leerness:managed -->';
 const README_START = '<!-- leerness:project-readme:start -->';
 const README_END = '<!-- leerness:project-readme:end -->';
+// 1.9.307 (UR-0055 사용자명시): 프로젝트 청사진(brief) — README 개요 섹션 마커.
+const BRIEF_START = '<!-- leerness:project-brief:start -->';
+const BRIEF_END = '<!-- leerness:project-brief:end -->';
 
 // 1.9.10: leerness-skillpack 동적 로드 (선택). 없으면 BUILTIN 사용.
 function _tryLoadSkillpack() {
@@ -149,7 +152,9 @@ const STATUSES = ['requested','planned','in-progress','waiting','on-hold','block
 function log(s = '') { console.log(s); }
 function ok(s) { log('✓ ' + s); }
 function warn(s) { log('⚠ ' + s); }
-function fail(s) { log('✗ ' + s); }
+// 1.9.306 (UR-0045, 설치리뷰 3중수렴): fail() 은 오류 신호 → exit code 1 설정 (CI/MCP/에이전트가 실패를 성공으로 오판 방지).
+//   비치명 경고는 warn() 사용. process.exit 즉시종료가 아니라 exitCode 설정(후속 출력/정리 보존, main 종료 wrapper 가 강제).
+function fail(s) { log('✗ ' + s); process.exitCode = 1; }
 // 1.9.287 (Codex 리뷰 수렴): 임베딩 텍스트의 코드펜스(```)를 중립화해 외부 마크다운(session-handoff)이 깨지지 않게.
 //   ``` → ''' (펜스가 아닌 표시), 인라인 백틱은 보존. 순수 함수.
 function _sanitizeFences(s) { return String(s || '').replace(/```+/g, "'''"); }
@@ -3072,6 +3077,8 @@ function _selfTestCases() {
     { name: '_withLock/_updateRun: lost-update 락(O_EXCL+재진입) + 적용 (UR-0043 외부리뷰 1.9.303)', run: () => { const src = read(__filename); const fnOk = typeof _withLock === 'function' && typeof _sleepSyncMs === 'function' && typeof _updateRun === 'function'; const reentrant = /if \(_heldLocks\.has\(lockPath\)\) return fn\(\)/.test(src); const excl = /fs\.openSync\(lockPath, 'wx'\)/.test(src); const applied = /const id = _withLock\(progressPath\(root\)/.test(src) && /_updateRun\(root, curId/.test(src); return fnOk && reentrant && excl && applied; } },
     { name: 'lib/analyzers: 분석/검증 함수 4종 모듈 단일출처 분리 (UR-0025 1.9.304)', run: () => { const m = require('../lib/analyzers'); return m._evidenceQuality === _evidenceQuality && m._shellGuardAnalyze === _shellGuardAnalyze && m._parseEvidenceStats === _parseEvidenceStats && m._claimFileInGit === _claimFileInGit && !/function _evidenceQuality\(evidence\) \{/.test(read(__filename)) && !/function _shellGuardAnalyze\(cmd, ctx\) \{/.test(read(__filename)); } },
     { name: 'honesty-check: AI 인식론적 정직성 3차원 + MCP/CLI/strict 통합 (사용자명시 1.9.305)', run: () => { const h = _epistemicHonestyCheck; const d1 = h('이 기능은 항상 정상 동작합니다').findings.some(f => f.dim === 'pretend-knowledge'); const d2 = h('아마 될 것 같습니다. 구현 완료했습니다').findings.some(f => f.dim === 'premature-judgment'); const d3 = h('이 API 의 rate limit 은 초당 5회입니다').findings.some(f => f.dim === 'no-info-gathering'); const clean = h('src/api.js 수정, 12/12 통과 (Exit: 0)').ok === true; const src = read(__filename); const wired = require('../lib/mcp-tools').some(t => t.name === 'leerness_honesty_check') && /if \(cmd === 'honesty-check'\)/.test(src) && /honestyFindings = _epistemicHonestyCheck/.test(src); return d1 && d2 && d3 && clean && wired; } },
+    { name: 'exit code 일관성: fail()→exitCode 1 + unknown 명령 안내 (UR-0045 설치리뷰 1.9.306)', run: () => { const src = read(__filename); return /function fail\(s\) \{ log\('✗ ' \+ s\); process\.exitCode = 1; \}/.test(src) && /알 수 없는 명령: \$\{cmd\}/.test(src) && /if \(cmd === 'help' \|\| cmd === 'commands'/.test(src); } },
+    { name: 'brief: 프로젝트 청사진 set/show/export + README 개요 섹션 (UR-0055 사용자명시 1.9.307)', run: () => { const src = read(__filename); const fnOk = typeof briefCmd === 'function' && typeof _loadBrief === 'function' && typeof _briefBlueprint === 'function' && _BRIEF_FIELDS.length === 10; const b = { project: 'X', intro: 'i', purpose: 'p', problem: '', features: ['f1', 'f2'], stack: ['s'], architecture: '', users: [], success: [], nonGoals: [], currentState: '' }; const bp = _briefBlueprint('.', b); const bpOk = /Blueprint/.test(bp) && /소개 \(Intro\)/.test(bp) && /f1/.test(bp) && /신규 프로젝트 시작 가이드/.test(bp); const rb = _briefReadmeBlock(b); const rbOk = rb.includes(BRIEF_START) && rb.includes(BRIEF_END) && /프로젝트 개요/.test(rb) && /\*\*목적\*\*/.test(rb); return fnOk && bpOk && rbOk && /if \(cmd === 'brief'\)/.test(src); } },
     { name: 'VERSION 형식 (x.y.z)', run: () => /^\d+\.\d+\.\d+$/.test(VERSION) }
   ];
 }
@@ -18216,6 +18223,119 @@ function aboutCmd(opts = {}) {
   log(`표면: MCP ${id.surface.mcpTools} 도구 · 어댑터 ${id.surface.adapters.length} · provider ${id.surface.providers} · 런타임 의존성 ${id.surface.runtimeDeps} · offline-first ${id.surface.offlineFirst ? '✓' : '✗'}`);
   return id;
 }
+// ===== 1.9.307 (UR-0055 사용자명시): 프로젝트 청사진(brief) =====
+//   프로젝트 개요/소개/목적/기능을 .harness/project-brief.md(정본)에 유지 + README 개요 섹션 동기화 + 복사용 blueprint export.
+//   "복사하면 신규 프로젝트를 기초부터 재시작할 수 있는" 자기완결 청사진. 기존 project-brief.md 확장(비파괴).
+const _BRIEF_FIELDS = [
+  { key: 'intro', h: 'Intro', label: '소개', flag: 'intro', multi: false },
+  { key: 'purpose', h: 'Purpose', label: '목적', flag: 'purpose', multi: false },
+  { key: 'problem', h: 'Problem', label: '해결 문제', flag: 'problem', multi: false },
+  { key: 'features', h: 'Features', label: '핵심 기능', flag: 'features', multi: true },
+  { key: 'stack', h: 'Tech Stack', label: '기술 스택', flag: 'stack', multi: true },
+  { key: 'architecture', h: 'Architecture', label: '아키텍처', flag: 'architecture', multi: false },
+  { key: 'users', h: 'Users', label: '사용자', flag: 'users', multi: true },
+  { key: 'success', h: 'Success Criteria', label: '성공 기준', flag: 'success', multi: true },
+  { key: 'nonGoals', h: 'Non-Goals', label: '비목표', flag: 'non-goals', multi: true },
+  { key: 'currentState', h: 'Current State', label: '현재 상태', flag: 'current-state', multi: false },
+];
+function _briefPath(root) { return path.join(absRoot(root), '.harness', 'project-brief.md'); }
+function _loadBrief(root) {
+  const brief = { project: detectProjectName(absRoot(root)) };
+  for (const f of _BRIEF_FIELDS) brief[f.key] = f.multi ? [] : '';
+  const p = _briefPath(root);
+  if (!exists(p)) return brief;
+  for (const b of read(p).split(/\n(?=## )/)) {
+    const m = b.match(/^## (.+?)\n([\s\S]*)$/);
+    if (!m) continue;
+    const head = m[1].trim(), body = m[2].trim();
+    if (head === 'Project') { brief.project = (body.replace(/^[-*]\s*/, '').split('\n')[0] || '').trim() || brief.project; continue; }
+    const f = _BRIEF_FIELDS.find(x => x.h === head);
+    if (!f) continue;
+    if (f.multi) brief[f.key] = body.split('\n').map(l => l.replace(/^[-*]\s*/, '').trim()).filter(l => l && l !== '-' && !/업데이트하세요/.test(l));
+    else { const v = body.replace(/^[-*]\s*/, '').trim(); brief[f.key] = /업데이트하세요/.test(v) ? '' : v; }
+  }
+  return brief;
+}
+function _saveBrief(root, brief) {
+  let body = `# Project Brief\n\n## Project\n${brief.project || detectProjectName(absRoot(root))}\n`;
+  for (const f of _BRIEF_FIELDS) {
+    const v = brief[f.key];
+    body += `\n## ${f.h}\n`;
+    if (f.multi) body += (v && v.length ? v.map(x => `- ${x}`).join('\n') : '-') + '\n';
+    else body += (v ? v : '- 이 항목을 실제 내용으로 업데이트하세요.') + '\n';
+  }
+  writeUtf8(_briefPath(root), fm('project-brief', ['프로젝트 목적 확인', '신규 기능 판단', '계획 수립'], ['프로젝트 목적 변경', '사용자/범위 변경'], body));
+}
+function _briefFilled(brief) { return _BRIEF_FIELDS.filter(f => (f.multi ? (brief[f.key] && brief[f.key].length) : brief[f.key])).length; }
+function _briefReadmeBlock(brief) {
+  const L = [BRIEF_START, '## 프로젝트 개요', ''];
+  if (brief.intro) L.push(brief.intro, '');
+  if (brief.purpose) L.push(`**목적**: ${brief.purpose}`, '');
+  if (brief.problem) L.push(`**해결 문제**: ${brief.problem}`, '');
+  if (brief.features && brief.features.length) { L.push('**핵심 기능**'); brief.features.forEach(x => L.push(`- ${x}`)); L.push(''); }
+  if (brief.stack && brief.stack.length) L.push(`**기술 스택**: ${brief.stack.join(', ')}`, '');
+  if (_briefFilled(brief) === 0) L.push('_아직 개요 미입력 — `leerness brief set --intro "..." --purpose "..."` 로 작성._', '');
+  L.push('<sub>이 섹션은 `leerness brief` 로 관리됩니다. 전체 청사진(복사용): `leerness brief export`.</sub>', BRIEF_END);
+  return L.join('\n');
+}
+function _syncBriefReadme(root, brief) {
+  const p = path.join(absRoot(root), 'README.md');
+  const existing = exists(p) ? read(p) : '';
+  const block = _briefReadmeBlock(brief);
+  const s = existing.indexOf(BRIEF_START), e = existing.indexOf(BRIEF_END);
+  let updated;
+  if (s >= 0 && e >= s) updated = existing.slice(0, s).trimEnd() + '\n\n' + block + '\n' + existing.slice(e + BRIEF_END.length).trimStart();
+  else if (existing.trim()) updated = existing.trimEnd() + '\n\n' + block + '\n';
+  else updated = `# ${brief.project}\n\n${block}\n`;
+  writeUtf8(p, updated);
+}
+function _briefBlueprint(root, brief) {
+  const L = [`# ${brief.project} — 프로젝트 청사진 (Blueprint)`,
+    `> 이 문서만으로 프로젝트를 기초부터 재구성할 수 있도록 작성. \`leerness brief export\` 생성 (leerness v${VERSION}).`, ''];
+  const sec = (h, v, multi) => { if (multi ? (v && v.length) : v) { L.push(`## ${h}`, multi ? v.map(x => `- ${x}`).join('\n') : v, ''); } };
+  sec('소개 (Intro)', brief.intro); sec('목적 (Purpose)', brief.purpose); sec('해결 문제 (Problem)', brief.problem);
+  sec('핵심 기능 (Features)', brief.features, true); sec('기술 스택 (Tech Stack)', brief.stack, true);
+  sec('아키텍처 (Architecture)', brief.architecture); sec('사용자 (Users)', brief.users, true);
+  sec('성공 기준 (Success Criteria)', brief.success, true); sec('비목표 (Non-Goals)', brief.nonGoals, true);
+  sec('현재 상태 (Current State)', brief.currentState);
+  L.push('---', '## 신규 프로젝트 시작 가이드', '', '1. 위 소개·목적·기능·아키텍처·스택을 신규 레포의 계획으로 복사.', '2. `leerness init .` 후 이 파일을 `.harness/project-brief.md` 로 복사하거나 `leerness brief set` 으로 재입력.', '3. Features 를 `leerness plan add` / `leerness task add` 로 분해.', '');
+  return L.join('\n');
+}
+function briefCmd(root, sub) {
+  root = absRoot(root || process.cwd());
+  const isTty = process.stdout && process.stdout.isTTY;
+  const cy = s => isTty ? `\x1b[36m${s}\x1b[0m` : s, gr = s => isTty ? `\x1b[32m${s}\x1b[0m` : s, dm = s => isTty ? `\x1b[2m${s}\x1b[0m` : s;
+  sub = sub || 'show';
+  if (sub === 'set') {
+    const brief = _loadBrief(root);
+    let changed = 0;
+    const proj = arg('--project', null); if (proj != null) { brief.project = proj; changed++; }
+    for (const f of _BRIEF_FIELDS) { const v = arg('--' + f.flag, null); if (v != null) { brief[f.key] = f.multi ? _splitList(v) : v; changed++; } }
+    if (!changed) { fail('brief set: 최소 하나의 필드 필요 (--intro --purpose --problem --features --stack --architecture --users --success --non-goals --current-state --project)'); return; }
+    _saveBrief(root, brief);
+    _syncBriefReadme(root, brief);
+    ok(`brief 갱신 (${changed}개 필드) → .harness/project-brief.md + README 개요 섹션 동기화`);
+    return;
+  }
+  if (sub === 'show') {
+    const brief = _loadBrief(root);
+    if (has('--json')) { log(JSON.stringify(brief, null, 2)); return; }
+    log(cy(`# leerness brief — ${brief.project}`));
+    for (const f of _BRIEF_FIELDS) { const v = brief[f.key]; const filled = f.multi ? (v && v.length) : v; log(`  ${filled ? gr('✓') : dm('·')} ${f.label}: ${filled ? (f.multi ? v.join(', ') : v).slice(0, 90) : dm('(미입력)')}`); }
+    log('');
+    log(dm(`  채움 ${_briefFilled(brief)}/${_BRIEF_FIELDS.length} · 설정: leerness brief set --intro "..." · 복사용: leerness brief export`));
+    return;
+  }
+  if (sub === 'export') {
+    const brief = _loadBrief(root);
+    const bp = _briefBlueprint(root, brief);
+    const out = arg('--out', null);
+    if (out) { const op = path.isAbsolute(out) ? out : path.join(root, out); writeUtf8(op, bp); ok(`blueprint export → ${rel(root, op)} (${_briefFilled(brief)}/${_BRIEF_FIELDS.length} 필드)`); return; }
+    log(bp);
+    return;
+  }
+  fail(`brief: 알 수 없는 sub: ${sub} (set | show | export)`);
+}
 function contextCmd(root, opts = {}) {
   root = absRoot(root);
   const rows = readProgressRows(root);
@@ -21455,6 +21575,7 @@ async function main() {
   // 1.9.278 (UR-0032): leerness state <show|start|record|verify|handoff> — .leerness/ 구조화 상태 substrate
   if (cmd === 'state')                              return stateCmd(arg('--path', process.cwd()), args[1], ...args.slice(2));
   if (cmd === 'context')                            return contextCmd(arg('--path', process.cwd()), { json: has('--json') });
+  if (cmd === 'brief')                              return briefCmd(arg('--path', process.cwd()), args[1]);
   if (cmd === 'about' || cmd === 'identity')        return aboutCmd({ json: has('--json') });
   // 1.9.281 (UR-0034): leerness policy <show|set|check> — 권한 등급 (opt-in enforced)
   if (cmd === 'policy')                             return policyCmd(arg('--path', process.cwd()), args[1], ...args.slice(2));
@@ -21605,7 +21726,10 @@ async function main() {
     }
     return fail('decision add "<title>" --reason "..." --alternatives "..." --impact "..." | decision list [--json] | decision drop <date|title>');
   }
-  return help();
+  // 1.9.306 (UR-0045): 명시적 help 요청은 exit 0, 그 외 미인식 명령은 안내 + exit 1 (실패를 성공으로 오판 방지).
+  if (cmd === 'help' || cmd === 'commands' || cmd === '--help' || cmd === '-h') { help(); return; }
+  fail(`알 수 없는 명령: ${cmd}  (leerness --help 로 전체 명령 확인)`);
+  return;
 }
 
 // 1.9.4 B: main 종료 후 exitCode를 명시적으로 process.exit으로 강제 (셸/wrapper 차 무시).

package/package.json

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

package/scripts/e2e.js

@@ -3477,5 +3477,58 @@ total++;
   if (!ok) failed++;
 }
 
+// 1.9.306 회귀 (UR-0045 설치리뷰): exit code 일관성 — 오류 경로 exit 1, 정상/help exit 0
+total++;
+{
+  let ok = false;
+  try {
+    const eDir = fs.mkdtempSync(path.join(os.tmpdir(), 'leerness-exit-'));
+    cp.spawnSync(process.execPath, [CLI, 'init', eDir, '--yes', '--language', 'ko', '--skills', 'recommended'], { encoding: 'utf8', timeout: 30000 });
+    const ex = (args) => cp.spawnSync(process.execPath, [CLI, ...args], { cwd: eDir, encoding: 'utf8', timeout: 20000 }).status;
+    // 오류 경로 → exit 1
+    const unknownOk = ex(['definitely-not-a-cmd']) === 1;
+    const missingArgOk = ex(['decision', 'add', '--path', eDir]) === 1;
+    const badSubOk = ex(['task', 'zzznotreal', '--path', eDir]) === 1;
+    // 정상/help/version → exit 0 (fail() 변경 회귀 방지)
+    const okStatus = ex(['status', eDir]) === 0;
+    const okList = ex(['task', 'list', '--path', eDir]) === 0;
+    const okHelp = ex(['--help']) === 0;
+    const okVer = ex(['--version']) === 0;
+    ok = unknownOk && missingArgOk && badSubOk && okStatus && okList && okHelp && okVer;
+    fs.rmSync(eDir, { recursive: true, force: true });
+  } catch {}
+  console.log(ok ? '✓ B(1.9.306) exit code 일관성: 오류 exit 1(unknown/인자누락/badsub) + 정상·help·version exit 0 (UR-0045)' : '✗ exit code 일관성 실패');
+  if (!ok) failed++;
+}
+
+// 1.9.307 회귀 (UR-0055 사용자명시): brief — 프로젝트 청사진 set/show/export + README 섹션 + 멱등 업데이트
+total++;
+{
+  let ok = false;
+  try {
+    const bDir = fs.mkdtempSync(path.join(os.tmpdir(), 'leerness-brief-'));
+    cp.spawnSync(process.execPath, [CLI, 'init', bDir, '--yes', '--language', 'ko', '--skills', 'recommended'], { encoding: 'utf8', timeout: 30000 });
+    const run = (...a) => cp.spawnSync(process.execPath, [CLI, ...a], { cwd: bDir, encoding: 'utf8', timeout: 20000 });
+    run('brief', 'set', '--path', bDir, '--intro', '할 일 관리 앱', '--purpose', '팀 생산성', '--features', '태스크CRUD, 알림');
+    const briefMd = fs.readFileSync(path.join(bDir, '.harness', 'project-brief.md'), 'utf8');
+    const readme = fs.readFileSync(path.join(bDir, 'README.md'), 'utf8');
+    const setOk = /## Intro\n할 일 관리 앱/.test(briefMd) && /태스크CRUD/.test(briefMd) && readme.includes('<!-- leerness:project-brief:start -->') && /## 프로젝트 개요/.test(readme) && /할 일 관리 앱/.test(readme);
+    // 멱등 업데이트: 방향 변경(--purpose 만 갱신) → intro/features 보존
+    run('brief', 'set', '--path', bDir, '--purpose', '엔터프라이즈 확대');
+    const md2 = fs.readFileSync(path.join(bDir, '.harness', 'project-brief.md'), 'utf8');
+    const updateOk = /엔터프라이즈 확대/.test(md2) && /할 일 관리 앱/.test(md2) && /태스크CRUD/.test(md2);
+    // README 섹션 중복 없음 (재sync)
+    const readme2 = fs.readFileSync(path.join(bDir, 'README.md'), 'utf8');
+    const noDup = (readme2.match(/<!-- leerness:project-brief:start -->/g) || []).length === 1;
+    // export: 복사용 blueprint
+    const exp = run('brief', 'export', '--path', bDir);
+    const exportOk = exp.status === 0 && /Blueprint/.test(exp.stdout) && /신규 프로젝트 시작 가이드/.test(exp.stdout) && /엔터프라이즈 확대/.test(exp.stdout);
+    ok = setOk && updateOk && noDup && exportOk;
+    fs.rmSync(bDir, { recursive: true, force: true });
+  } catch {}
+  console.log(ok ? '✓ B(1.9.307) brief: 청사진 set→README+brief 동기화 + 멱등 업데이트 + export blueprint (UR-0055)' : '✗ brief 청사진 실패');
+  if (!ok) failed++;
+}
+
 console.log(`\nE2E result: ${total - failed}/${total} passed · ${((Date.now() - _e2eStart) / 1000).toFixed(0)}s`);
 if (failed > 0) process.exit(1);