leerness 1.36.50 → 1.36.51

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 1.36.51 — 2026-07-21 — 모호성 질문 + 미리보기 승인 워크플로 (사용자 요청 UR-0061)
+
+사용자 요청: "자연어에 판단 모호한 부분이 있으면 사용자에게 질문하고, 신규 기능은 코드 작성 전 디자인/기능 미리보기를 제시해 승인/수정을 받도록".
+
+- **`leerness clarify "<요청>"`** (lib/clarify.js 신설): 모호성 신호 6종(모호 수식어/지시대명사/복수 선택지/불명 범위/불명 수량/불명 시점) 감지 → **AI 가 사용자에게 그대로 물을 질문 목록** 생성. 신호 없으면 무질문(false-PASS 편향 — "잘"은 요청동사 동반 시만, 과질문으로 흐름 차단 금지). --json 지원.
+- **`leerness preview add|list|show|approve|revise`**: 신규 기능 미리보기 스토어(.harness/previews.json, P-XXXX). add(--design/--features) → proposed → 사용자 제시 → approve(구현 허가) / revise --note(수정요구, 이력 누적). **approve 전 코드 작성 금지가 계약**. 손상 스토어 위 변경 fail-closed. 플래그 값의 제목 흡수 차단(원시 argv 파싱).
+- **지시 레이어 강제**: 신규 init 의 AGENTS.md Required behavior 에 "모호성 질문 의무"+"미리보기 승인 의무(①등록 ②제시·질문 ③approve 후 구현)" 주입 — 자연어만 쓰는 에이전트도 절차를 따르게 됨.
+- **handoff 헤드라인**: 미승인 미리보기 N건 노출("approve 전 코드 금지") — 세션이 바뀌어도 대기 상태가 이월.
+- 검증: selftest 325(+2 행위: 신호→질문/무신호, add→revise→approve 이력+손상거부), e2e +1 라운드트립(제목 미흡수·헤드라인·not_found JSON·AGENTS 주입).
+
 ## 1.36.50 — 2026-07-21 — 결함 클래스 3종 전수 스윕: 발견이 아니라 클래스를 고친다 (시스템적 진입점 3곳)
 
 6차 헌트의 개별 결함 3건을 클래스로 확장해 코드베이스 전수 스윕(교훈: fix-class call-site sweep). 개별 지점 수선 대신 시스템적 진입점 수정으로 현재+미래 지점까지 커버.

package/README.md

@@ -122,7 +122,7 @@ MIT
 <!-- leerness:project-readme:start -->
 ## Leerness Project Harness
 
-이 프로젝트는 Leerness v1.36.50 하네스를 사용합니다. AI 에이전트는 작업 전 `leerness handoff`로 컨텍스트를 적재하고, 작업 후 `leerness check`/`leerness audit`/`leerness session close`를 수행해야 합니다.
+이 프로젝트는 Leerness v1.36.51 하네스를 사용합니다. AI 에이전트는 작업 전 `leerness handoff`로 컨텍스트를 적재하고, 작업 후 `leerness check`/`leerness audit`/`leerness session close`를 수행해야 합니다.
 
 ### 정체성 — AI 에이전트 운영 레이어 (UR-0030)
 
@@ -176,7 +176,7 @@ leerness memory restore decision <date|title>
 
 ### MCP server (외부 AI 통합)
 
-Leerness v1.36.50는 stdio JSON-RPC MCP server를 내장합니다 — Claude Code · Cursor · Codex CLI 등 외부 AI에 **86개 도구**를 노출:
+Leerness v1.36.51는 stdio JSON-RPC MCP server를 내장합니다 — Claude Code · Cursor · Codex CLI 등 외부 AI에 **86개 도구**를 노출:
 
 ```jsonc
 // 카테고리별
@@ -197,7 +197,7 @@ Leerness v1.36.50는 stdio JSON-RPC MCP server를 내장합니다 — Claude Cod
 `<<autonomous-loop-dynamic>>` 신호만 보내면 AI가:
 1) 다음 라운드 후보 선정 → 2) 코드 변경 → 3) 회귀 테스트 갱신 → 4) 전체 e2e 스위트 통과 → 5) npm publish + git tag → 6) main push → 7) session close → 8) 다음 라운드 예약.
 
-현재 누적: **v1.9.x → 1.36.50 릴리스 태그 이력** (수백 라운드) · _reports/는 비공개 보존.
+현재 누적: **v1.9.x → 1.36.51 릴리스 태그 이력** (수백 라운드) · _reports/는 비공개 보존.
 
 ### 성능 가이드
 
@@ -235,6 +235,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.36.50: 2026-07-21
+Last synced by Leerness v1.36.51: 2026-07-21
 <!-- leerness:project-readme:end -->
 

package/bin/leerness.js

@@ -34,7 +34,7 @@ const { CAPABILITY_SURFACE, POWERFUL_COMMANDS, ADAPTERS, REUSE_CATEGORIES, REUSE
 const { tokenizeForRank: _tokenizeForRank, expandQuery: _expandQuery, scoreHits: _scoreHits, suggestTerms: _suggestTerms } = require('../lib/search-core');  // 1.36.23: memory search 랭킹 코어(순수·0-deps)
 const { findCorruptedStateJson: _findCorruptedStateJson } = require('../lib/state-integrity');  // 1.36.1 (클린룸 리뷰 FN): .harness/*.json 상태 무결성 (audit/health/check 공유)
 
-const VERSION = '1.36.50';
+const VERSION = '1.36.51';
 
 // 1.9.290 (UR-0037, Codex gpt-5.5 #4 수렴): CLI 전용 부작용은 require 시 실행하지 않는다.
 //   이전: warning listener 제거 / NODE_OPTIONS 변경 / chcp IIFE 가 top-level 즉시 실행 → require('harness') 시 호스트 프로세스 오염.
@@ -429,7 +429,7 @@ function coreFiles(root, lang = 'ko', selectedSkills = [], opts = {}) {
   const project = detectProjectName(root);
   const skillRows = Object.entries(skillCatalog).map(([k, v]) => `| ${k} | ${v.displayNameKo} | ${v.capabilities.join(', ')} | ${v.lastUpdated} | ${v.verification} |`).join('\n');
   const _files = {
-    'AGENTS.md': `${MARK}\n# Leerness Agent Instructions\n\n## ⭐ 매 세션 첫 행동\n**반드시 \`.harness/session-workflow.md\`를 먼저 읽고 6단계 워크플로를 따른다**: 요청분석→계획→분배→sub-agent작업→종합검증→마감. 라운드 길이/복잡도 무관, drift 방지를 위해 모든 작업에 동일 흐름 유지.\n\n## 정적 vs 동적 — leerness 역할 경계\n**AGENTS.md = 정적 프로젝트 지침** (코딩 규칙·테스트 명령·금지 사항·배포 절차 — 자주 안 변함).\n**leerness = 동적 작업 상태·기억·검증·인수인계** (현재 목표·수정 파일·실패 시도·검증 결과·다음 에이전트 인계 — 매 작업 변함).\n- 규칙/명령/금지는 여기 AGENTS.md 에 적는다.\n- 동적 상태(결정/교훈/계획/진행/검증/인수인계)는 leerness 가 **기본 워크스페이스 \`.harness/\`** 에 기록한다 (decisions.md / lessons.md / plan.md / progress-tracker.md / session-handoff.md). \`leerness handoff\` · \`decision add\` · \`lesson save\` 등이 여기에 쓴다.\n- (선택) \`leerness state show|start|record|verify|handoff\` (또는 MCP \`leerness_state_*\`) 의 JSON 상태 substrate 는 \`.leerness/\` (에이전트 간 인수인계 표준 — state 명령 사용 시 생성). 메인 워크스페이스(.harness)와 별개.\n- leerness 는 AGENTS.md 를 **대체하지 않고 보완**한다. 정적 지침은 여기, 동적 상태는 leerness.\n\n## Mandatory read order (session start)\n1. **.harness/session-workflow.md** (6단계 워크플로 — 최우선)\n2. .harness/context-routing.md\n3. .harness/session-handoff.md\n4. .harness/current-state.md\n5. .harness/plan.md\n6. .harness/progress-tracker.md\n7. .harness/guideline.md\n8. .harness/protected-files.md\n9. .harness/writeback-policy.md\n10. .harness/anti-lazy-work-policy.md\n11. **.harness/rules.md** (사용자 정의 영구 룰 — 매 세션 반드시 따름)\n\n## Required behavior\n- 작업 시작 시 \`leerness handoff .\`를 실행해 컨텍스트를 적재합니다 (handoff가 active rules를 자동 출력).\n- 작업 분류는 \`leerness route <task-type>\`로 확인합니다 (planning, feature, bugfix, refactor, research, consistency, release, migration, session-start, session-close, harness-maintenance).\n- 보호 파일/관리 섹션을 삭제하지 않습니다. 머지·아카이브·deprecated 표시를 사용합니다.\n- 의미 있는 변경 후 progress-tracker, current-state, task-log, session-handoff를 갱신합니다.\n- 완료 선언 전 \`leerness check .\` 또는 \`leerness lazy detect .\`로 자기검증하고, \`leerness lens\`의 분야별 자기질문에 답합니다 (코드: "선임 개발자가 복잡하다고 느끼지 않을까?" / 디자인: "선임 디자이너와 일반 사용자가 이쁘고 직관적이라 느낄까?").\n- 변경 전 secret/encoding 가드: \`leerness scan secrets .\`, \`leerness encoding check .\`.\n- 같은 기능 중복 생성 전 design-system.md, consistency-policy.md, reuse-map.md를 확인합니다.\n- 매 세션 종료 시 \`leerness session close .\`로 9개 카테고리(완료/진행중/미완료/예정/대기/보류/차단/드랍/검증) + **활성 룰 검증 결과**를 보고합니다.\n- 업데이트는 \`leerness update --check\` (감지) → \`leerness update --yes\` (자동 마이그레이션).\n\n## 자연어 회고/통찰/브레인스토밍\n사용자가 자연어로 회고/통찰/브레인스토밍을 요청하면 즉시 leerness 명령으로 호출합니다.\n\n| 사용자 발화 (자연어) | 즉시 실행할 명령 |\n|---|---|\n| "회고해줘 / 돌아보자 / 정리해줘" | \`leerness retro\` |\n| "최근 N일 회고" | \`leerness retro --days N\` |\n| "통계 / 누적 지표 / insights" | \`leerness insights\` |\n| "X에 대해 브레인스토밍 / X 관련 자료 / X 시작 전 검토" | \`leerness brainstorm "X"\` |\n\nsession close가 매번 자동으로 한 줄 요약을 출력하고, 5세션마다 자동 깊은 회고를 실행합니다. 사용자가 명시 요청 시 즉시 호출.\n\n## 자연어 룰 처리\n사용자가 자연어로 영구 룰을 요청하면 즉시 leerness rule 명령으로 등록합니다.\n\n| 사용자 발화 (자연어) | 즉시 실행할 명령 |\n|---|---|\n| "매 업데이트마다 버전 bump해줘" | \`leerness rule add "버전을 patch로 bump" --trigger every-update\` |\n| "매 커밋마다 패치노트 추가해줘" | \`leerness rule add "패치노트 추가" --trigger every-commit\` |\n| "세션 종료마다 배포해줘" | \`leerness rule add "배포 (release publish)" --trigger session-close\` |\n| "X 룰 중지/그만/끄기" | \`leerness rule pause <ID>\` (해당 룰 ID는 list로 확인) |\n| "X 룰 제거/삭제" | \`leerness rule remove <ID>\` |\n| "모든 룰 중지" | \`leerness rule stop\` |\n| "룰 다시 켜줘" | \`leerness rule resume-all\` 또는 \`leerness rule resume <ID>\` |\n\n룰을 등록한 후 사용자에게 등록 결과(ID + trigger + 설명)를 보고하고, 그 이후 매 세션마다 자동 적용합니다. 사용자가 "중지" 또는 "제거"를 명시적으로 말하기 전까지는 룰을 비활성화하지 않습니다.\n\n## 룰 자동 적용\nleerness가 자동 검증 가능한 trigger:\n- **every-update / version bump 키워드 룰**: package.json의 version이 갱신됐는지 검사 (handoff/session close가 baseline 캐시와 비교).\n- **CHANGELOG / 패치노트 키워드 룰**: CHANGELOG.md의 mtime이 갱신됐는지 검사.\n- **test / 테스트 / verify 키워드 룰**: review-evidence.md에 오늘 verify-code 흔적이 있는지 검사.\n- **배포 / publish / push 키워드 룰**: 자동 검증 불가 → 사용자에게 release publish 명령을 안내.\n\n자동 검증 가능한 룰의 실행은 \`leerness release bump\`, \`leerness release note "..."\`, \`leerness release publish\`를 사용해 자동화합니다.\n`,
+    'AGENTS.md': `${MARK}\n# Leerness Agent Instructions\n\n## ⭐ 매 세션 첫 행동\n**반드시 \`.harness/session-workflow.md\`를 먼저 읽고 6단계 워크플로를 따른다**: 요청분석→계획→분배→sub-agent작업→종합검증→마감. 라운드 길이/복잡도 무관, drift 방지를 위해 모든 작업에 동일 흐름 유지.\n\n## 정적 vs 동적 — leerness 역할 경계\n**AGENTS.md = 정적 프로젝트 지침** (코딩 규칙·테스트 명령·금지 사항·배포 절차 — 자주 안 변함).\n**leerness = 동적 작업 상태·기억·검증·인수인계** (현재 목표·수정 파일·실패 시도·검증 결과·다음 에이전트 인계 — 매 작업 변함).\n- 규칙/명령/금지는 여기 AGENTS.md 에 적는다.\n- 동적 상태(결정/교훈/계획/진행/검증/인수인계)는 leerness 가 **기본 워크스페이스 \`.harness/\`** 에 기록한다 (decisions.md / lessons.md / plan.md / progress-tracker.md / session-handoff.md). \`leerness handoff\` · \`decision add\` · \`lesson save\` 등이 여기에 쓴다.\n- (선택) \`leerness state show|start|record|verify|handoff\` (또는 MCP \`leerness_state_*\`) 의 JSON 상태 substrate 는 \`.leerness/\` (에이전트 간 인수인계 표준 — state 명령 사용 시 생성). 메인 워크스페이스(.harness)와 별개.\n- leerness 는 AGENTS.md 를 **대체하지 않고 보완**한다. 정적 지침은 여기, 동적 상태는 leerness.\n\n## Mandatory read order (session start)\n1. **.harness/session-workflow.md** (6단계 워크플로 — 최우선)\n2. .harness/context-routing.md\n3. .harness/session-handoff.md\n4. .harness/current-state.md\n5. .harness/plan.md\n6. .harness/progress-tracker.md\n7. .harness/guideline.md\n8. .harness/protected-files.md\n9. .harness/writeback-policy.md\n10. .harness/anti-lazy-work-policy.md\n11. **.harness/rules.md** (사용자 정의 영구 룰 — 매 세션 반드시 따름)\n\n## Required behavior\n- 작업 시작 시 \`leerness handoff .\`를 실행해 컨텍스트를 적재합니다 (handoff가 active rules를 자동 출력).\n- **모호성 질문 의무**: 사용자 요청에 판단이 갈리는 부분(모호한 수식어/지시대명사/복수 선택지/불명확한 범위)이 있으면 **추측으로 구현하지 말고 먼저 사용자에게 질문**합니다. \`leerness clarify "<요청>"\` 이 감지한 질문 목록을 그대로 사용자에게 물어보세요. 신호가 없어도 스스로 판단이 갈리면 질문이 우선입니다.\n- **미리보기 승인 의무 (신규 기능)**: 사용자가 신규 기능 추가/구현을 요청하면 **코드를 먼저 작성하지 않습니다**. ① \`leerness preview add "<기능>" --design "<디자인/UX 설명>" --features "<기능 목록>"\` 으로 미리보기를 등록하고 ② 그 내용을 사용자에게 제시해 승인 또는 수정사항을 질문으로 받습니다. ③ 사용자가 승인하면 \`leerness preview approve <P-ID>\`, 수정 요구면 \`leerness preview revise <P-ID> --note "..."\` 후 미리보기를 고쳐 다시 제시합니다. **approve 전에는 해당 기능의 코드를 작성하지 않습니다.**\n- 작업 분류는 \`leerness route <task-type>\`로 확인합니다 (planning, feature, bugfix, refactor, research, consistency, release, migration, session-start, session-close, harness-maintenance).\n- 보호 파일/관리 섹션을 삭제하지 않습니다. 머지·아카이브·deprecated 표시를 사용합니다.\n- 의미 있는 변경 후 progress-tracker, current-state, task-log, session-handoff를 갱신합니다.\n- 완료 선언 전 \`leerness check .\` 또는 \`leerness lazy detect .\`로 자기검증하고, \`leerness lens\`의 분야별 자기질문에 답합니다 (코드: "선임 개발자가 복잡하다고 느끼지 않을까?" / 디자인: "선임 디자이너와 일반 사용자가 이쁘고 직관적이라 느낄까?").\n- 변경 전 secret/encoding 가드: \`leerness scan secrets .\`, \`leerness encoding check .\`.\n- 같은 기능 중복 생성 전 design-system.md, consistency-policy.md, reuse-map.md를 확인합니다.\n- 매 세션 종료 시 \`leerness session close .\`로 9개 카테고리(완료/진행중/미완료/예정/대기/보류/차단/드랍/검증) + **활성 룰 검증 결과**를 보고합니다.\n- 업데이트는 \`leerness update --check\` (감지) → \`leerness update --yes\` (자동 마이그레이션).\n\n## 자연어 회고/통찰/브레인스토밍\n사용자가 자연어로 회고/통찰/브레인스토밍을 요청하면 즉시 leerness 명령으로 호출합니다.\n\n| 사용자 발화 (자연어) | 즉시 실행할 명령 |\n|---|---|\n| "회고해줘 / 돌아보자 / 정리해줘" | \`leerness retro\` |\n| "최근 N일 회고" | \`leerness retro --days N\` |\n| "통계 / 누적 지표 / insights" | \`leerness insights\` |\n| "X에 대해 브레인스토밍 / X 관련 자료 / X 시작 전 검토" | \`leerness brainstorm "X"\` |\n\nsession close가 매번 자동으로 한 줄 요약을 출력하고, 5세션마다 자동 깊은 회고를 실행합니다. 사용자가 명시 요청 시 즉시 호출.\n\n## 자연어 룰 처리\n사용자가 자연어로 영구 룰을 요청하면 즉시 leerness rule 명령으로 등록합니다.\n\n| 사용자 발화 (자연어) | 즉시 실행할 명령 |\n|---|---|\n| "매 업데이트마다 버전 bump해줘" | \`leerness rule add "버전을 patch로 bump" --trigger every-update\` |\n| "매 커밋마다 패치노트 추가해줘" | \`leerness rule add "패치노트 추가" --trigger every-commit\` |\n| "세션 종료마다 배포해줘" | \`leerness rule add "배포 (release publish)" --trigger session-close\` |\n| "X 룰 중지/그만/끄기" | \`leerness rule pause <ID>\` (해당 룰 ID는 list로 확인) |\n| "X 룰 제거/삭제" | \`leerness rule remove <ID>\` |\n| "모든 룰 중지" | \`leerness rule stop\` |\n| "룰 다시 켜줘" | \`leerness rule resume-all\` 또는 \`leerness rule resume <ID>\` |\n\n룰을 등록한 후 사용자에게 등록 결과(ID + trigger + 설명)를 보고하고, 그 이후 매 세션마다 자동 적용합니다. 사용자가 "중지" 또는 "제거"를 명시적으로 말하기 전까지는 룰을 비활성화하지 않습니다.\n\n## 룰 자동 적용\nleerness가 자동 검증 가능한 trigger:\n- **every-update / version bump 키워드 룰**: package.json의 version이 갱신됐는지 검사 (handoff/session close가 baseline 캐시와 비교).\n- **CHANGELOG / 패치노트 키워드 룰**: CHANGELOG.md의 mtime이 갱신됐는지 검사.\n- **test / 테스트 / verify 키워드 룰**: review-evidence.md에 오늘 verify-code 흔적이 있는지 검사.\n- **배포 / publish / push 키워드 룰**: 자동 검증 불가 → 사용자에게 release publish 명령을 안내.\n\n자동 검증 가능한 룰의 실행은 \`leerness release bump\`, \`leerness release note "..."\`, \`leerness release publish\`를 사용해 자동화합니다.\n`,
     'CLAUDE.md': `${MARK}\n# Claude Code Instructions\n\nFollow AGENTS.md. Always run \`leerness handoff .\` at the start and \`leerness session close .\` before ending a session.\n\n**⭐ 매 세션 첫 행동**: \`.harness/session-workflow.md\`의 6단계 워크플로(요청분석→계획→분배→sub-agent→종합검증→마감)를 따라야 함. drift critical 시 \`leerness drift check --auto-fix\`로 자동 회복.\n\nProtected files must not be deleted. Read .harness/anti-lazy-work-policy.md before claiming completion.\n\n## 자연어 영구 룰\n사용자가 "매 X마다 Y를 해줘" 같은 자연어 룰을 말하면 즉시 \`leerness rule add "Y" --trigger every-X\`로 등록하세요. 등록된 룰은 매 세션 \`handoff\`가 자동 출력하고, \`session close\`가 자동 검증해 보고합니다. 사용자가 "중지" / "그만" / "끄기"를 명시할 때만 \`rule pause/remove\`를 호출합니다.\n\n자세한 매핑은 AGENTS.md의 "자연어 룰 처리" 표를 참고하세요.\n`,
     '.cursor/rules/leerness.mdc': `${MARK}\n---\nalwaysApply: true\n---\nFollow AGENTS.md and .harness/context-routing.md.\nRun: \`leerness handoff .\` at session start.\nRun: \`leerness session close .\` at session end.\nPreserve Leerness protected files.\n`,
     '.github/copilot-instructions.md': `${MARK}\n# Copilot Instructions\n\nUse AGENTS.md and .harness/ as project memory.\nDo not remove protected Leerness files.\nBefore completion, ensure plan.md, progress-tracker.md, current-state.md, session-handoff.md are updated.\n`,
@@ -4984,6 +4984,41 @@ function _selfTestCases() {
         const human = outs.length === 1 && outs[0] === '✗ 사람용';
         return passThru && demoted && humanExplicit && human;
       } finally { console.log = _log; console.error = _err; process.argv = saveArgv; io.setQuiet(false); process.exitCode = saveExit; }
+    } },
+    { name: 'clarify 모호성 감지 (1.36.51, UR-0061): 신호어→질문 생성 + 무신호 false-PASS 편향 — 순수 행위검사', run: () => {
+      const c = require('../lib/clarify');
+      const r1 = c._clarifySignals('로그인 화면 적당히 이쁘게 만들어줘, 그리고 그거도 고쳐줘');
+      const hit = r1.ambiguous && r1.signals.some(s => s.kind === 'vague-quality') && r1.signals.some(s => s.kind === 'pronoun') && r1.questions.length >= 2 && r1.questions.every(q => q.includes('?') || q.includes('요'));
+      const r2 = c._clarifySignals('src/login.js 의 validateEmail 함수가 빈 문자열에서 true 를 반환하는 버그를 수정');
+      const clean = !r2.ambiguous && r2.questions.length === 0;   // 구체 요청은 무질문 (false-BLOCK 방지)
+      const wired = read(__filename).includes("cmd === 'clarify'") && read(__filename).includes('모호성 질문 의무');
+      return hit && clean && wired;
+    } },
+    { name: 'preview 승인 워크플로 (1.36.51, UR-0061): add→proposed→pending 노출→approve/revise 이력 + 손상 스토어 거부 — 행위검사', run: () => {
+      const c = require('../lib/clarify');
+      const tmp = fs.mkdtempSync(path.join(os.tmpdir(), '__leerness_pv_'));
+      const _w = process.stdout.write; const _ce = console.error;
+      try {
+        process.stdout.write = () => true; console.error = () => {};
+        fs.mkdirSync(path.join(tmp, '.harness'), { recursive: true });
+        const deps = { has: () => false, arg: (k, d) => (k === '--design' ? '카드형 목록 UI' : k === '--features' ? '검색,정렬' : d) };
+        c.previewCmd(tmp, 'add', ['주문', '목록'], deps);
+        let list = c._loadPreviews(tmp);
+        const added = list.length === 1 && list[0].id === 'P-0001' && list[0].status === 'proposed' && list[0].design === '카드형 목록 UI' && list[0].features.length === 2;
+        const pending1 = c.pendingPreviews(tmp).length === 1;
+        c.previewCmd(tmp, 'revise', ['P-0001'], { has: () => false, arg: (k, d) => (k === '--note' ? '색상 변경 요청' : d) });
+        list = c._loadPreviews(tmp);
+        const revised = list[0].status === 'revision-requested' && list[0].history.some(h => h.note === '색상 변경 요청') && c.pendingPreviews(tmp).length === 1;
+        c.previewCmd(tmp, 'approve', ['P-0001'], deps);
+        const approved = c._loadPreviews(tmp)[0].status === 'approved' && c.pendingPreviews(tmp).length === 0;
+        // 손상 스토어 위 변경 거부 (fail-closed) — 원본 보존
+        fs.writeFileSync(c._previewsPath(tmp), '[{"id":"P-0001",');
+        const saveExit = process.exitCode;
+        c.previewCmd(tmp, 'add', ['새기능'], deps);
+        process.exitCode = saveExit;
+        const preserved = fs.readFileSync(c._previewsPath(tmp), 'utf8') === '[{"id":"P-0001",';
+        return added && pending1 && revised && approved && preserved;
+      } finally { process.stdout.write = _w; console.error = _ce; try { fs.rmSync(tmp, { recursive: true, force: true }); } catch {} }
     } }
   ];
 }
@@ -6122,6 +6157,8 @@ function commandsCmd(root) {
       { cmd: 'release channel [--json]', desc: '릴리스 채널 정책 (latest 안정 / next 실험 / 버전 고정) — 1.9.275' },
       { cmd: 'slash-commands [agent] [--json --record --detect --refresh]', desc: 'CLI 에이전트 슬래시 명령 레지스트리 + --help probe 자동 갱신 (1.9.265~267, UR-0021)' },
       { cmd: 'review-request "<request>"', desc: '사용자 요청 사전 검토 (1.9.176)' },
+      { cmd: 'clarify "<사용자 요청>" [--json]', desc: '요청 모호성 신호 감지 → 사용자에게 물을 질문 생성 (추측 구현 방지) — 1.36.51 UR-0061' },
+      { cmd: 'preview add|list|show|approve|revise', desc: '신규 기능 미리보기 승인 워크플로 — approve 전 코드 작성 금지 계약 — 1.36.51 UR-0061' },
       { cmd: 'review <file> --persona <ids>', desc: '페르소나 리뷰 (1.9.29)' },
       { cmd: 'brainstorm "<topic>" [--include-code]', desc: '워크스페이스 회수 + 코드 grep' }
     ],
@@ -8511,6 +8548,7 @@ function _saveTeams(root, teams) {
 //   harness 는 deps(VERSION · 공유 저장 _loadTeams/_saveTeams · _detectShellCtx · argv 파서 arg/has)를 구성해 위임(thin wrapper). 호출부/동작 무변경.
 const _team = require('../lib/team');
 const _tgl = require('../lib/toggles');   // 1.36.30: 기능 토글 (그래프 ⚙ 탭 연동 — gate/lens/auto-graph/delegation-brief)
+const _clar = require('../lib/clarify');  // 1.36.51 (UR-0061): 모호성 질문 + 미리보기 승인 워크플로
 function teamCmd(root, sub, id, opts = {}) { return _team.teamCmd(root, sub, id, opts, { VERSION, _loadTeams, _saveTeams, _detectShellCtx, arg, has, _withLock }); }   // 1.36.31: add 경합 락
 
 // 1.9.112: 전용 lessons.md (Memory Write Surface 5번째)
@@ -10485,6 +10523,11 @@ function handoff(root) {
           parts.push(t(`📥 요청 ${audit.open} (tracked)`, `📥 ${audit.open} request(s) (tracked)`));
         }
       } catch {}
+      // 1.36.51 (UR-0061): 미승인 미리보기 — 사용자 답을 기다리는 기능이 있으면 헤드라인 노출 (코드 작성 보류 계약)
+      try {
+        const _pp = _clar.pendingPreviews(root);
+        if (_pp.length) parts.push(t(`🎨 미승인 미리보기 ${_pp.length}건 (approve 전 코드 금지)`, `🎨 ${_pp.length} preview(s) awaiting approval (no code before approve)`));
+      } catch {}
       // 14) 1.9.209: pre-wake-audit 최근 보고서 (사용자 명시) — 깨어남 직후 자동 노출
       try {
         const pwState = _loadPreWakeReport(root);
@@ -22437,6 +22480,17 @@ async function main() {
   if (cmd === 'enforce')                           return enforceCmd(arg('--path', null) || _taskPositionalPath(args, 2) || process.cwd(), args[1]);   // 1.36.43: 사용 강제 (git pre-commit)
   if (cmd === 'anchors')                           return anchorsCmd(arg('--path', null) || _taskPositionalPath(args, 1) || process.cwd(), args[1] && !args[1].startsWith('-') ? args[1] : null);   // 1.36.36: 정체성앵커 초안
   if (cmd === 'toggle')                            return _tgl.toggleCmd(arg('--path', process.cwd()), args[1], args[2], args[3], { has, VERSION });   // 1.36.30: 기능 토글 (그래프 ⚙ 탭 연동)
+  // 1.36.51 (사용자 요청 UR-0061): 모호성 질문 + 미리보기 승인 워크플로
+  if (cmd === 'clarify')                           return _clar.clarifyCmd(arg('--path', process.cwd()), args.slice(1).filter(x => !x.startsWith('-')).join(' '), { has });
+  if (cmd === 'preview') {
+    // 미지 플래그(--design/--features/--note)의 값이 positional 로 새는 것 차단 — 원시 argv 에서 플래그+값 스킵 (1.36.49 release note 패턴)
+    const _pvRaw = process.argv.slice(2); const _pvI = _pvRaw.indexOf('preview'); const _pvToks = [];
+    for (let i = _pvI + 1; i < _pvRaw.length && _pvI >= 0; i++) {
+      if (_pvRaw[i].startsWith('--')) { if (['--design', '--features', '--note', '--path'].includes(_pvRaw[i]) && _pvRaw[i + 1]) i++; continue; }
+      _pvToks.push(_pvRaw[i]);
+    }
+    return _clar.previewCmd(arg('--path', process.cwd()), _pvToks[0], _pvToks.slice(1), { has, arg });
+  }
   if (cmd === 'lens')                               return lensCmd(args[1]);  // 1.18.3 (UR-0003): 분야별 자기질문 품질 렌즈
   // 1.9.233: leerness commands — 카테고리화된 전체 CLI 명령 목록
   if (cmd === 'commands')                           return commandsCmd(arg('--path', null) || _taskPositionalPath(args, 1) || process.cwd());

package/lib/clarify.js

@@ -0,0 +1,148 @@
+// lib/clarify.js — 모호성 질문 + 미리보기 승인 워크플로 (1.36.51, 사용자 요청 UR-0061).
+//   ① clarify: 사용자 요청 텍스트에서 판단-모호 신호를 감지해 "AI 가 사용자에게 그대로 물을 질문"을 생성.
+//      원칙: 휴리스틱은 false-PASS 편향(신호어 없으면 명확 판정) — 과질문(false-BLOCK)으로 흐름을 막지 않는다.
+//   ② preview: 신규 기능은 코드 작성 전 디자인/기능 미리보기를 제시하고 사용자 승인(approve)/수정요구(revise)를
+//      기록하는 스토어(.harness/previews.json). 승인 전 코드 작성 금지가 지시 레이어 계약.
+'use strict';
+const path = require('path');
+const { absRoot, exists, read, writeUtf8, log, ok, warn, fail, failJson, now, today } = require('./io');
+
+// ── ① 모호성 신호 카탈로그 (kind → { re, q(match) }) ──────────────────────────
+const CLARIFY_SIGNALS = [
+  // '잘'은 "잘 통과하는지" 같은 정상 문장에 흔해 뒤따르는 요청동사가 있을 때만 (false-PASS 편향)
+  { kind: 'vague-quality', re: /(적당히|알아서|이쁘게|예쁘게|깔끔하게|멋지게|잘\s?(?:좀|만들|해줘|해 줘|부탁)|as appropriate|make it nice|make it pretty)/,
+    q: (m) => `「${m.trim()}」의 기대 수준이 불명확합니다 — 참고할 예시(스크린샷/사이트/기존 화면)나 구체 기준이 있나요?` },
+  { kind: 'pronoun', re: /(그거|이거|저거|아까\s?그|그 부분|위에서 말한|the one before)/,
+    q: (m) => `「${m.trim()}」가 무엇을 가리키는지 확인이 필요합니다 — 대상(파일/화면/기능 이름)을 지정해 주세요.` },
+  { kind: 'alternative', re: /(\S+)\s?(?:이나|나|또는|혹은)\s(\S+)|(\b\w+\b) or (\b\w+\b)/,
+    q: (m) => `복수 선택지(${m.trim()})가 언급됐습니다 — 어느 쪽을 원하시나요, 아니면 둘 다인가요?` },
+  { kind: 'vague-scope', re: /(전부 다|전부|모두 다|모든 걸|싹 다|everything|all of (?:it|them))/,
+    q: (m) => `「${m.trim()}」의 범위가 넓습니다 — 포함/제외할 대상을 구체적으로 확인해도 될까요?` },
+  { kind: 'vague-amount', re: /(약간|조금|살짝|몇 ?개|여러 ?개|어느 ?정도|a few|some of)/,
+    q: (m) => `「${m.trim()}」의 수량/정도가 불명확합니다 — 대략적인 숫자나 기준을 주실 수 있나요?` },
+  { kind: 'undefined-later', re: /(나중에|이따가?|추후|필요하면|여차하면|later|eventually)/,
+    q: (m) => `「${m.trim()}」 시점 조건이 모호합니다 — 지금 범위에 포함할지, 이번엔 제외할지 확인이 필요합니다.` },
+];
+
+// 순수 감지 코어 — 텍스트에서 신호와 질문 목록 생성 (신호 없으면 ambiguous:false)
+function _clarifySignals(text) {
+  const t = String(text || '');
+  const signals = [];
+  for (const s of CLARIFY_SIGNALS) {
+    const m = t.match(s.re);
+    if (m) signals.push({ kind: s.kind, match: m[0], question: s.q(m[0]) });
+  }
+  return { ambiguous: signals.length > 0, signals, questions: signals.map(s => s.question) };
+}
+
+// `leerness clarify "<사용자 요청>" [--json]`
+function clarifyCmd(root, text, deps = {}) {
+  const { has } = deps;
+  const json = !!(has && has('--json'));
+  if (!text || !String(text).trim()) { failJson(json, 'text_required', 'clarify "<사용자 요청 텍스트>" 필요 — 모호성 신호를 감지해 사용자에게 물을 질문을 생성'); return; }
+  const r = _clarifySignals(text);
+  if (json) { log(JSON.stringify({ ok: true, ambiguous: r.ambiguous, signals: r.signals, questions: r.questions }, null, 2)); return; }
+  log(`# leerness clarify — 요청 모호성 점검`);
+  if (!r.ambiguous) { ok('  모호 신호 없음 — 그대로 진행 가능 (판단이 갈리면 그래도 물어보는 것이 안전)'); return; }
+  warn(`  모호 신호 ${r.signals.length}건 — 작업 시작 전 사용자에게 아래 질문을 하세요:`);
+  r.questions.forEach((q, i) => log(`  ${i + 1}. ${q}`));
+  log(`\n  ⓘ 계약: 답을 받기 전에는 추측으로 구현하지 않는다 (AGENTS.md 모호성 규칙)`);
+}
+
+// ── ② 미리보기 승인 스토어 ─────────────────────────────────────────────────
+function _previewsPath(root) { return path.join(absRoot(root), '.harness', 'previews.json'); }
+
+function _loadPreviews(root) {
+  const f = _previewsPath(root);
+  if (!exists(f)) return [];
+  try { const j = JSON.parse(read(f)); return Array.isArray(j) ? j : []; } catch { return []; }
+}
+
+function _savePreviews(root, list, json) {
+  const f = _previewsPath(root);
+  // 변경 진입점 fail-closed (1.36.28 스토어 손상 클래스) — 손상 파일 위 저장 거부
+  if (exists(f)) { try { JSON.parse(read(f)); } catch { failJson(json, 'store_corrupt', `previews.json 손상 — 덮어쓰기 거부: ${f} (복구/삭제 후 재시도)`); return false; } }
+  writeUtf8(f, JSON.stringify(list, null, 2) + '\n');
+  return true;
+}
+
+function _nextPreviewId(list) {
+  let max = 0;
+  for (const p of list) { const m = String(p.id || '').match(/^P-(\d{4,})$/); if (m) max = Math.max(max, Number(m[1])); }
+  return `P-${String(max + 1).padStart(4, '0')}`;
+}
+
+function pendingPreviews(root) { return _loadPreviews(root).filter(p => p.status === 'proposed' || p.status === 'revision-requested'); }
+
+// `leerness preview add "<제목>" [--design "..."] [--features "a,b"] | list | show <id> | approve <id> | revise <id> --note "..."`
+function previewCmd(root, sub, rest, deps = {}) {
+  const { has, arg } = deps;
+  root = absRoot(root);
+  const json = !!(has && has('--json'));
+  if (!exists(path.join(root, '.harness'))) { failJson(json, 'harness_missing', `leerness 미설치: ${root} — 먼저 leerness init`); return; }
+  const list = _loadPreviews(root);
+  sub = sub || 'list';
+
+  if (sub === 'add') {
+    const title = (rest || []).join(' ').trim();
+    if (!title) { failJson(json, 'title_required', 'preview add "<기능 제목>" 필요 (+ --design "설명" --features "a,b")'); return; }
+    const design = arg ? (arg('--design', '') || '') : '';
+    const features = (arg ? (arg('--features', '') || '') : '').split(',').map(s => s.trim()).filter(Boolean);
+    const p = { id: _nextPreviewId(list), title, design, features, status: 'proposed', createdAt: now(), history: [{ at: now(), event: 'proposed' }] };
+    list.push(p);
+    if (!_savePreviews(root, list, json)) return;
+    if (json) { log(JSON.stringify({ ok: true, ...p }, null, 2)); return; }
+    ok(`preview 등록: ${p.id} 「${title}」 (status: proposed)`);
+    log(`  → 사용자에게 이 미리보기(디자인/기능)를 제시하고 승인/수정 답을 받으세요.`);
+    log(`  → 승인: leerness preview approve ${p.id}  ·  수정요구: leerness preview revise ${p.id} --note "..."`);
+    log(`  ⓘ 계약: approve 전에는 이 기능의 코드를 작성하지 않는다.`);
+    return;
+  }
+
+  if (sub === 'list') {
+    if (json) { log(JSON.stringify({ ok: true, total: list.length, pending: pendingPreviews(root).length, previews: list }, null, 2)); return; }
+    log(`# leerness preview — 기능 미리보기 승인 상태 (${list.length}건)`);
+    if (!list.length) { log('  (없음) — 신규 기능 착수 전: leerness preview add "<제목>" --design "..." --features "a,b"'); return; }
+    for (const p of list) {
+      const icon = p.status === 'approved' ? '✅' : (p.status === 'revision-requested' ? '📝' : '⏳');
+      log(`  ${icon} ${p.id} ${p.title}  [${p.status}]`);
+    }
+    const pend = pendingPreviews(root).length;
+    if (pend) warn(`  미승인 ${pend}건 — 사용자 답을 받기 전 해당 기능 코드 작성 금지`);
+    return;
+  }
+
+  const id = (rest || [])[0];
+  const p = list.find(x => x.id === id);
+  if (sub === 'show' || sub === 'approve' || sub === 'revise') {
+    if (!id) { failJson(json, 'id_required', `preview ${sub} <P-ID> 필요 (leerness preview list 로 확인)`); return; }
+    if (!p) { failJson(json, 'not_found', `preview 없음: ${id}`); return; }
+  }
+
+  if (sub === 'show') {
+    if (json) { log(JSON.stringify({ ok: true, ...p }, null, 2)); return; }
+    log(`# ${p.id} 「${p.title}」  [${p.status}]`);
+    if (p.design) log(`  디자인: ${p.design}`);
+    if (p.features && p.features.length) { log('  기능:'); p.features.forEach(f => log(`    - ${f}`)); }
+    (p.history || []).forEach(h => log(`  · ${h.at} ${h.event}${h.note ? ` — ${h.note}` : ''}`));
+    return;
+  }
+  if (sub === 'approve') {
+    p.status = 'approved'; (p.history = p.history || []).push({ at: now(), event: 'approved' });
+    if (!_savePreviews(root, list, json)) return;
+    if (json) { log(JSON.stringify({ ok: true, id: p.id, status: p.status }, null, 2)); return; }
+    ok(`${p.id} 승인 — 이제 구현을 시작해도 됩니다.`);
+    return;
+  }
+  if (sub === 'revise') {
+    const note = arg ? (arg('--note', '') || '') : '';
+    p.status = 'revision-requested'; (p.history = p.history || []).push({ at: now(), event: 'revision-requested', note });
+    if (!_savePreviews(root, list, json)) return;
+    if (json) { log(JSON.stringify({ ok: true, id: p.id, status: p.status, note }, null, 2)); return; }
+    ok(`${p.id} 수정요구 기록${note ? ` — ${note}` : ''} — 미리보기를 수정해 다시 제시하세요 (코드 작성은 계속 보류).`);
+    return;
+  }
+  failJson(json, 'unknown_subcommand', `알 수 없는 preview 하위명령: ${sub} (가능: add, list, show, approve, revise)`);
+}
+
+module.exports = { CLARIFY_SIGNALS, _clarifySignals, clarifyCmd, previewCmd, pendingPreviews, _previewsPath, _loadPreviews };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "leerness",
-  "version": "1.36.50",
+  "version": "1.36.51",
   "description": "The AI-coding operations layer that makes \"done\" require evidence — persistent memory, evidence-gated completion checks, and clean handoffs for any AI agent (Claude Code, Codex, Cursor). State lives as plain files in your repo. CLI + MCP, 0 runtime dependencies.",
   "keywords": [
     "leerness",

package/scripts/e2e.js

@@ -6994,5 +6994,39 @@ total++;
   if (!ok) failed++;
 }
 
+// 1.36.51 (사용자 요청 UR-0061): clarify 모호성 질문 + preview 승인 워크플로 — CLI 라운드트립
+total++;
+{
+  let ok = false;
+  try {
+    const d = fs.mkdtempSync(path.join(os.tmpdir(), 'leerness-clarify-'));
+    cp.spawnSync(process.execPath, [CLI, 'init', d, '--yes'], { encoding: 'utf8', timeout: 30000 });
+    const R = (a) => cp.spawnSync(process.execPath, [CLI, ...a, '--path', d], { encoding: 'utf8', timeout: 15000 });
+    // clarify: 모호 요청 → ambiguous + 질문 / 구체 요청 → 무신호
+    const c1 = JSON.parse(R(['clarify', '메인 화면 적당히 이쁘게 바꿔줘, 그거도 같이', '--json']).stdout);
+    const c2 = JSON.parse(R(['clarify', 'src/a.js 의 sum 함수 오버플로 버그 수정', '--json']).stdout);
+    const clarifyOk = c1.ambiguous === true && c1.questions.length >= 2 && c2.ambiguous === false;
+    // preview: add(플래그 값 제목 미흡수) → pending 헤드라인 → approve → pending 해소
+    const pAdd = JSON.parse(R(['preview', 'add', '주문 목록 화면', '--design', '카드형 그리드', '--features', '검색,정렬', '--json']).stdout);
+    const addOk = pAdd.id === 'P-0001' && pAdd.title === '주문 목록 화면' && pAdd.design === '카드형 그리드' && pAdd.features.length === 2 && pAdd.status === 'proposed';
+    const ho1 = cp.spawnSync(process.execPath, [CLI, 'handoff', d], { encoding: 'utf8', timeout: 25000 });
+    const headlineOk = /미승인 미리보기 1건|1 preview\(s\) awaiting/.test((ho1.stdout || '') + (ho1.stderr || ''));
+    const ap = JSON.parse(R(['preview', 'approve', 'P-0001', '--json']).stdout);
+    const lst = JSON.parse(R(['preview', 'list', '--json']).stdout);
+    const approveOk = ap.status === 'approved' && lst.pending === 0 && lst.total === 1;
+    // 오류경로 JSON 계약: 미존재 id
+    const nf = R(['preview', 'show', 'P-9999', '--json']);
+    let nfOk = false; try { const j = JSON.parse(nf.stdout); nfOk = j.ok === false && j.code === 'not_found' && nf.status === 1; } catch {}
+    // 신규 init 산출물에 의무 절차 지시 존재
+    const agents = fs.readFileSync(path.join(d, 'AGENTS.md'), 'utf8');
+    const docOk = agents.includes('모호성 질문 의무') && agents.includes('미리보기 승인 의무') && agents.includes('approve 전에는 해당 기능의 코드를 작성하지 않습니다');
+    fs.rmSync(d, { recursive: true, force: true });
+    ok = clarifyOk && addOk && headlineOk && approveOk && nfOk && docOk;
+    if (!ok) console.log(`   [clarify 디버그] c=${clarifyOk} a=${addOk} h=${headlineOk} ap=${approveOk} nf=${nfOk} doc=${docOk}`);
+  } catch (e) {}
+  console.log(ok ? '✓ B(1.36.51) UR-0061: clarify 모호성 질문 생성(+구체요청 무신호) + preview add/approve 워크플로(제목 미흡수·헤드라인·not_found JSON) + AGENTS 의무 절차 주입' : '✗ clarify/preview 워크플로 실패');
+  if (!ok) failed++;
+}
+
 console.log(`\nE2E result: ${total - failed}/${total} passed · ${((Date.now() - _e2eStart) / 1000).toFixed(0)}s`);
 if (failed > 0) process.exit(1);