leerness 1.9.32 → 1.9.34

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. package/CHANGELOG.md +73 -0
  2. package/README.md +288 -342
  3. package/bin/harness.js +306 -66
  4. package/package.json +1 -1
  5. package/scripts/e2e.js +79 -1
package/README.md CHANGED
@@ -1,8 +1,8 @@
1
1
  # Leerness
2
2
 
3
- > 한국어 우선 AI 개발 하네스. 멀티 에이전트 오케스트레이션 · 자동 검수 · 워크스페이스 가시성 · Ollama opt-in 통합.
3
+ > **한국어 우선 AI 개발 하네스** — AI 에이전트가 거짓 완료 보고 없이, 안전하게 코드를 쓰도록 만드는 CLI 도구.
4
4
 
5
- [![npm](https://img.shields.io/badge/npm-leerness-blue)](https://www.npmjs.com/package/leerness) [![version](https://img.shields.io/badge/version-1.9.32-green)]() [![tests](https://img.shields.io/badge/e2e-151%2F151-success)]() [![license](https://img.shields.io/badge/license-MIT-lightgrey)]()
5
+ [![npm](https://img.shields.io/badge/npm-leerness-blue)](https://www.npmjs.com/package/leerness) [![version](https://img.shields.io/badge/version-1.9.34-green)]() [![tests](https://img.shields.io/badge/e2e-155%2F156-success)]() [![license](https://img.shields.io/badge/license-MIT-lightgrey)]()
6
6
 
7
7
  ```
8
8
  ╔══════════════════════════════════════════════════════════════╗
@@ -14,189 +14,274 @@
14
14
  ║ ███████╗███████╗███████╗██║ ██║██║ ╚████║███████╗███████║ ║
15
15
  ║ ╚══════╝╚══════╝╚══════╝╚═╝ ╚═╝╚═╝ ╚═══╝╚══════╝╚══════╝ ║
16
16
  ║ ║
17
- ║ v1.9.32 Korean-first AI Development Harness ║
18
- ║ verify · reuse-map · handoff · agents · orchestrate ║
17
+ ║ v1.9.34 Korean-first AI Development Harness ║
18
+ ║ ★ verify · reuse-map · handoff · agents · orchestrate ║
19
19
  ║ ║
20
20
  ╚══════════════════════════════════════════════════════════════╝
21
- 한국어 우선 AI 개발 하네스 — verify · reuse-map · handoff · agents
22
21
  ```
23
22
 
23
+ ---
24
+
25
+ ## 🤔 leerness가 무엇인가요?
26
+
27
+ AI 에이전트(Claude Code, Cursor, Copilot, Codex, Gemini CLI 등)와 함께 일할 때 발생하는 **반복되는 함정**을 자동으로 막아주는 한국어 우선 CLI입니다.
28
+
29
+ | AI와 함께 일할 때 흔한 문제 | leerness의 해결책 |
30
+ |---|---|
31
+ | 🚨 "완료했습니다"라고 했지만 실제로 코드에 변경이 없음 | `verify-claim --run-tests` — 증거 파일 존재 + 테스트 실제 실행 검증 |
32
+ | 🚨 "API 호출 완료" 라고 했지만 코드에 URL이 없음 | `optimism-check` — 10 카테고리 패턴 + URL 매핑 + 신뢰도 점수 |
33
+ | 🚨 같은 함수를 여러 프로젝트에 중복 생성 | `reuse-map --all-apps --strict-elements` — 함수명 fuzzy 중복 감지 |
34
+ | 🚨 다음 세션이 컨텍스트를 잃음 | `handoff` — 3채널(plan/progress/decisions) 자동 적재 + `--compact` (500자) |
35
+ | 🚨 표면적 코드 리뷰 (도메인 깊이 부족) | `review --persona security,performance,ux` — 5 도메인 sub-agent 자동 부여 |
36
+ | 🚨 외부 AI CLI를 사용하고 싶지만 자동 호출은 위험 | `agents list/dispatch/quota` — 환경변수 활성화 + 명시적 분배 (자동 호출 X) |
37
+ | 🚨 npx 캐시로 옛 버전이 실행됨 | `1.9.33`+ `_warnIfStale` — install 시 npm latest 자동 비교 + 경고 |
38
+
39
+ ---
40
+
24
41
  ## ⚙️ 설치 (Install)
25
42
 
26
- > ⚠️ **leerness는 CLI 도구입니다.** `npm i leerness`(로컬)만으로는 `leerness` 명령이 PATH에 없어 실패할 수 있습니다. 아래 셋 중 하나를 사용하세요:
43
+ > ⚠️ **leerness는 CLI 도구입니다.** `npm i leerness`만으로는 명령이 PATH에 없습니다. 아래 셋 중 하나:
27
44
 
28
45
  ```bash
29
- # ✅ 1) 추천 — 설치 없이 즉시 실행 (npx 자동 캐시)
46
+ # ✅ 1) 추천 — 설치 없이 즉시 실행 (항상 @latest 명시)
30
47
  npx leerness@latest init . --language ko --skills recommended
31
48
 
32
- # ✅ 2) 전역 설치 (한 번 설치 후 어디서나 leerness 명령)
33
- npm i -g leerness && leerness --version
49
+ # ✅ 2) 전역 설치 (한 번이면 끝)
50
+ npm i -g leerness@latest && leerness --version
34
51
 
35
- # ✅ 3) 로컬 dev dependency + npx 실행
52
+ # ✅ 3) 로컬 dev dependency
36
53
  npm i --save-dev leerness && npx leerness handoff .
37
54
  ```
38
55
 
39
- > npmjs.com의 `npm i leerness`는 라이브러리 import용. CLI 명령(`leerness ...`) 직접 호출은 위 3가지 중 하나 필요.
56
+ ### 🚨 npx 캐시 함정 (1.9.33부터 자동 경고)
57
+
58
+ `@latest` 없이 `npx leerness init`만 실행하면 **PC에 캐시된 옛 버전이 무한 재사용**됩니다.
40
59
 
41
- ### 🎨 1.9.32 설치 경험
60
+ ```bash
61
+ # ❌ 위험 — 캐시된 옛 버전 실행 가능
62
+ npx leerness init .
42
63
 
43
- `leerness init`을 실행하면 **LEERNESS ASCII 배너 + 빠른 시작 가이드 + sub-agent CLI 설정 prompt**가 자동으로 표시됩니다.
64
+ # ✅ 안전 — 항상 최신 받음
65
+ npx leerness@latest init .
44
66
 
67
+ # ✅ 캐시 의심 시 비우고 다시
68
+ npx --yes clear-npx-cache && npx --yes leerness@latest init .
69
+ ```
70
+
71
+ 1.9.33부터 `leerness init` 실행 시 npm registry latest와 자동 비교 → 옛 버전이면 즉시 경고:
72
+
73
+ ```
74
+ ⚠ 옛 버전이 실행 중입니다 — v1.9.21 → v1.9.34 (npm 최신)
75
+ 해결: npx --yes clear-npx-cache && npx leerness@latest init .
76
+ ```
77
+
78
+ 경고 끄기: `--no-stale-check` 또는 `LEERNESS_NO_STALE_CHECK=1`.
79
+
80
+ ---
81
+
82
+ ## 🎨 1.9.34 설치 경험 — 인터랙티브 multi-select
83
+
84
+ `leerness init`은 **방향키/스페이스/Enter**로 언어·스킬·sub-agent CLI를 선택합니다:
85
+
86
+ ```
87
+ 설치 언어를 선택하세요
88
+ ↑↓ 이동, Enter 확정, q 취소
89
+ ❯ 자동 감지 — 디렉토리/파일 분석으로 한국어/영어 자동 판별
90
+ 한국어 — 모든 인스트럭션을 한국어로 생성
91
+ English — 모든 인스트럭션을 영어로 생성
92
+
93
+ 설치할 스킬 라이브러리 (Space=토글, a=전체, n=해제, Enter=확정)
94
+ ↑↓ 이동, Space 토글, a 전체, n 해제, Enter 확정
95
+ ❯ ◉ office — 마이크로소프트 오피스 자동화
96
+ ◉ commerce-api — 커머스 API 연동 (쿠팡/롯데온/스마트스토어)
97
+ ◯ crawling — Playwright 기반 크롤링·브라우저 자동화
98
+ ◉ ai-verified-skill-publisher — AI 검증 스킬 업로드·라이브러리화
99
+ ...
100
+
101
+ 활성화할 sub-agent CLI (Space=토글, a=전체, n=해제, Enter=확정)
102
+ ❯ ◉ claude — 🟢 설치됨 · Anthropic Claude Code CLI
103
+ ◯ codex — ⚪ 미설치 · OpenAI Codex CLI (격리 sandbox)
104
+ ◉ gemini — 🟢 설치됨 · Google Gemini CLI
105
+ ◯ copilot — ⚪ 미설치 · GitHub Copilot CLI
45
106
  ```
46
- ╔══════════════════════════════════════════════════════════════╗
47
- ║ ██╗ ███████╗███████╗██████╗ ███╗ ██╗███████╗███████╗ ║
48
- ║ ██║ ██╔════╝██╔════╝██╔══██╗████╗ ██║██╔════╝██╔════╝ ║
49
- ║ ██║ █████╗ █████╗ ██████╔╝██╔██╗ ██║█████╗ ███████╗ ║
50
- ║ ██║ ██╔══╝ ██╔══╝ ██╔══██╗██║╚██╗██║██╔══╝ ╚════██║ ║
51
- ║ ███████╗███████╗███████╗██║ ██║██║ ╚████║███████╗███████║ ║
52
- ║ ╚══════╝╚══════╝╚══════╝╚═╝ ╚═╝╚═╝ ╚═══╝╚══════╝╚══════╝ ║
53
- ║ v1.9.32 Korean-first AI Development Harness ║
54
- ╚══════════════════════════════════════════════════════════════╝
55
107
 
56
- 💡 외부 AI CLI(claude/codex/gemini/copilot)를 sub-agent로 활용하시겠습니까?
57
- 지금 설정할까요? (나중에 `leerness setup-agents`로도 가능) (Y/n): y
58
-
59
- ▸ claude — Anthropic Claude Code CLI
60
- 설치 상태: 🟢 설치됨 (1.0.x)
61
- 활성 상태: 🟡 LEERNESS_ENABLE_CLAUDE=0 또는 미설정
62
- claude를 sub-agent로 활성화하시겠습니까? (Y/n): y
63
- ✓ LEERNESS_ENABLE_CLAUDE=1 (활성)
64
-
65
- ▸ codex — OpenAI Codex CLI (격리 sandbox)
66
- 설치 상태: ⚪ 미설치
67
- 활성 상태: 🟡
68
- codex를 sub-agent로 활성화하시겠습니까? (y/N): y
69
- ✓ LEERNESS_ENABLE_CODEX=1 (활성)
70
- ⚠ codex이(가) 설치되어 있지 않습니다.
71
- 설치 명령: npm i -g @openai/codex
72
- 상세 안내: https://github.com/openai/codex
73
- 지금 자동 설치를 시도할까요? (y/N): y
74
- ▶ 실행: npm i -g @openai/codex
75
- ✓ 설치 성공 — 재확인: codex --version
76
- 🟢 codex 설치 확인 (0.x.x)
108
+ 활성화 후 미설치 CLI는 **자동 설치 시도**:
109
+ ```
110
+ ⚠ codex이(가) 설치되어 있지 않습니다.
111
+ 설치 명령: npm i -g @openai/codex
112
+ 지금 자동 설치를 시도할까요? (y/N): y
113
+ ▶ 실행: npm i -g @openai/codex
114
+ 🟢 codex 설치 확인 (v0.x.x)
77
115
  ```
78
116
 
79
117
  **스킵 옵션** (CI/자동화):
80
- - `leerness init --yes` — 모든 prompt 스킵 (기존 .env 유지)
81
- - `leerness init --no-setup-agents` — setup만 스킵
82
- - `LEERNESS_NO_BANNER=1` — ASCII 배너 스킵
83
- - `LEERNESS_NO_PROMPT=1` — readline prompt 강제 비활성화
118
+ - `--yes` — 모든 prompt 스킵 (기본값 사용)
119
+ - `--no-interactive-select` 또는 `LEERNESS_NO_INTERACTIVE=1` — 구식 숫자 prompt
120
+ - `LEERNESS_NO_PROMPT=1` — readline prompt 강제 비활성
121
+
122
+ ---
123
+
124
+ ## 🚀 60초 시작
84
125
 
85
- **나중에 재실행**:
86
126
  ```bash
87
- leerness setup-agents . # 인터랙티브 재설정
88
- leerness agents list # 현재 상태 확인
89
- leerness agents quota # 사용량 추정 (1.9.31)
127
+ # 1) 신규 프로젝트
128
+ npx leerness@latest init . --language ko
129
+
130
+ # 2) 매일 사용
131
+ npx leerness handoff . # 컨텍스트 적재
132
+ npx leerness audit . # 일관성 감사
133
+ npx leerness verify-claim T-0001 --run-tests # 증거 자동 검증
134
+ npx leerness session close . # 세션 마감 + 핸드오프
135
+
136
+ # 3) 워크스페이스 (멀티 프로젝트)
137
+ npx leerness handoff --all-apps --since 24h # 최근 24h 변경 통합 뷰
138
+ npx leerness reuse-map --all-apps # 중복 함수 감지
139
+
140
+ # 4) 외부 AI CLI 오케스트레이션
141
+ npx leerness setup-agents # 인터랙티브 CLI 활성화
142
+ npx leerness agents list # ready 상태표
143
+ npx leerness agents dispatch "X 해줘" --to gemini # 명령 자동 생성
90
144
  ```
91
145
 
92
146
  ---
93
147
 
94
- **leerness가 해결하는 것**
95
- - AI 에이전트가 거짓으로 "완료"를 보고하는 문제 → `verify-claim --run-tests`로 자동 검증
96
- - 같은 함수를 다른 프로젝트에 중복 생성 → `reuse-map --all-apps --strict-elements`로 자동 감지
97
- - 다음 세션이 컨텍스트를 잃는 문제 → handoff/current-state 3채널 자동 생성
98
- - 멀티 에이전트 분담 시 누가 뭘 했는지 안 보임 → `handoff --all-apps --since 1h`
99
- - LLM 컨텍스트 비용 → `--compact` 모드로 4KB → 500자
100
- - AI가 "API 호출 완료"라 보고했지만 코드에 호출 흔적이 없는 낙관적 표시 → `optimism-check`로 자동 감지 (1.9.26/27)
101
- - 코드 리뷰가 표면적이라 도메인 깊이 부족 → `leerness review <file> --persona security,performance,ux`로 도메인 페르소나 자동 부여 (1.9.29)
102
- - 외부 AI CLI(claude/codex/gemini/copilot)를 sub-agent로 활용하고 싶지만 자동 호출은 위험 → 환경변수 활성화 + `leerness agents list/dispatch`로 명시적 분배 (1.9.30)
103
- - 어떤 CLI에 quota 여유가 남았는지 한눈에 보고 싶을 때 → `leerness agents quota`로 provider별 사용량/한도 추정 (1.9.31)
148
+ ## 📊 적용 효과 (실측)
149
+
150
+ 벤치마크: `leerness-bench` 28 프로젝트 / 124 task 기준.
151
+
152
+ | 카테고리 | leerness | vanilla | 차이 |
153
+ |---|---:|---:|---:|
154
+ | 멀티에이전트 효율 | 100/100 | 3/100 | **+97** |
155
+ | 검수 자동화 (verify-claim 1.5s vs 90s 수동) | 98/100 | 0/100 | **+98** |
156
+ | 재사용 인식 (113 cap + 33 deps) | 100/100 | 0/100 | **+100** |
157
+ | 워크스페이스 가시성 (1 명령 vs 112 명령) | 99/100 | 0/100 | **+99** |
158
+ | 버그 자동 감지 (169 신호) | 100/100 | 0/100 | **+100** |
159
+ | 컨텍스트 유지 (3 채널) | 100/100 | 0/100 | **+100** |
160
+ | **종합** | **597/600 (99%)** | **3/600 (0.5%)** | **+594** |
104
161
 
105
162
  ---
106
163
 
107
- ## 🚀 60초 시작
164
+ ## 🤖 외부 AI CLI 오케스트레이션 (1.9.30~34)
165
+
166
+ claude/codex/gemini/copilot CLI들을 sub-agent로 활용. **자동 호출 금지** — 환경변수 활성화 + PATH 존재 시에만 ready.
108
167
 
168
+ ### 활성화 (1.9.32+ 권장: 인터랙티브)
109
169
  ```bash
110
- # 1) 신규 프로젝트 (설치 불필요)
111
- npx leerness@latest init . --language ko --skills recommended
170
+ leerness setup-agents . # 방향키/스페이스로 선택 + 미설치 자동 설치 시도
171
+ ```
112
172
 
113
- # 2) 기존 프로젝트 자동 업그레이드
114
- npx leerness@latest update . --yes
173
+ ### 활성화 (수동 `.env`)
174
+ ```bash
175
+ LEERNESS_ENABLE_CLAUDE=1 # Anthropic Claude Code CLI
176
+ LEERNESS_ENABLE_CODEX=1 # OpenAI Codex CLI (격리 sandbox)
177
+ LEERNESS_ENABLE_GEMINI=1 # Google Gemini CLI (--yolo 워크스페이스 직접 수정 가능)
178
+ LEERNESS_ENABLE_COPILOT=1 # GitHub Copilot CLI (gh copilot)
179
+ ```
115
180
 
116
- # 3) 매일 사용
117
- npx leerness handoff . # 컨텍스트 적재
118
- npx leerness audit . # 일관성 감사
119
- npx leerness verify-claim T-0001 --run-tests # evidence 자동 검증
181
+ ### 사용
182
+ ```bash
183
+ leerness agents list # 4 CLI 상태표
184
+ leerness agents quota # provider별 사용량/한도 추정
185
+ leerness agents dispatch "<task>" --to gemini # 명령 자동 생성 (실 호출 X)
120
186
  ```
121
187
 
188
+ ### 자동 설치 명령 (setup-agents가 사용)
189
+ | CLI | install 명령 | 안내 |
190
+ |---|---|---|
191
+ | claude | `npm i -g @anthropic-ai/claude-code` | https://docs.anthropic.com/en/docs/claude-code/setup |
192
+ | codex | `npm i -g @openai/codex` | https://github.com/openai/codex |
193
+ | gemini | `npm i -g @google/gemini-cli` | https://github.com/google-gemini/gemini-cli |
194
+ | copilot | `gh extension install github/gh-copilot` | https://github.com/github/gh-copilot |
195
+
196
+ ### 멀티레벨 오케스트레이션 검증 (1.9.34 실측)
197
+
198
+ 메인 → Sub-agent → Sub-sub-agent (3단계 깊이) 동작 검증:
199
+
200
+ | 항목 | 결과 |
201
+ |---|---|
202
+ | 단일 gemini 호출 | ✅ 15.6s (영문 번역 정상) |
203
+ | 병렬 gemini ×2 | ✅ 24s (출력 분리 정상, quota retry 1회) |
204
+ | 효율 (순차 3회 33s vs 병렬 3회 15s) | **2.2× 향상** (이론 3× 대비 60%) |
205
+ | 검수 체인 (결과를 다시 평가) | ✅ "2" → "yes" 정상 |
206
+ | 같은 파일 동시 쓰기 | ⚠ **last-writer-wins, 락 없음** |
207
+
208
+ **결론**:
209
+ - ✅ 3단계 오케스트레이션 동작
210
+ - ✅ 독립 작업(번역/평가/리뷰) 2×+ 효율 향상
211
+ - ⚠ **같은 리소스 동시 쓰기는 데이터 손실 위험** — 호출자가 파일 경로 격리 책임
212
+ - ⚠ gemini quota 동시 호출 시 retry 발생 → 병렬 확장성 ~3개로 제한
213
+
214
+ ### 정책
215
+ - ❌ leerness는 외부 CLI를 자동 호출하지 않음 (사용자/메인이 명시적 실행)
216
+ - ✅ `agents dispatch`는 명령 텍스트만 출력 → 사용자가 복사 실행
217
+ - ✅ quota 여유 큰 CLI를 메인 에이전트가 우선 선택하도록 신호 제공
218
+ - ⚠ `gemini --yolo`는 워크스페이스 파일 직접 수정 가능 (codex와 차이)
219
+
122
220
  ---
123
221
 
124
- ## 📊 적용 효과 (검증된 점수)
222
+ ## 🎭 페르소나 리뷰 (1.9.29)
125
223
 
126
- 벤치마크 시뮬 결과 (`leerness-bench`로 측정):
224
+ 도메인 페르소나를 sub-agent에 자동 부여 → 표면 리뷰 대비 **도메인 발견 3-4배**, 토큰 비용 ~3%.
127
225
 
128
- | 카테고리 | leerness | vanilla | 차이 |
129
- |---|---:|---:|---:|
130
- | 멀티에이전트 효율 | 100/100 | 3/100 | **+97** |
131
- | 검수 자동화 (1.5s vs 90s) | 98/100 | 0/100 | **+98** |
132
- | 재사용 인식 (86 cap + 22 deps) | 100/100 | 0/100 | **+100** |
133
- | 워크스페이스 가시성 (1 vs 64 명령) | 98/100 | 0/100 | **+98** |
134
- | 버그 자동 감지 (158 신호) | 100/100 | 0/100 | **+100** |
135
- | 컨텍스트 유지 (3채널) | 100/100 | 0/100 | **+100** |
136
- | 낙관적 표시 방지 | 1.9.26+ verify-claim/optimism-check | N/A | 95+/100 |
137
- | 페르소나 리뷰 (도메인 발견 3-4배) | 100/100 | 30/100 | **+70** |
138
- | **종합** | **603/700** | **33/700** | **+570 (18×)** |
139
-
140
- 로컬 LLM 실측 (Ollama deepseek-coder-v2:16b):
141
- - **HumanEval pass@1**: leerness 적용 **100%** vs 미적용 0%
142
- - **SWE-bench style 정확도**: 87.5% vs 62.5%
226
+ ### 5종 내장 페르소나
227
+ | ID | 역할 | 발견 깊이 |
228
+ |---|---|---|
229
+ | `security` | 10년차 보안 엔지니어 (OWASP/CWE/한국 개인정보보호법) | CWE 매핑 + 실 페이로드 |
230
+ | `performance` | V8 엔진 내부 전문가 | Hot path Top 5 + RPS 추정 |
231
+ | `ux` | 한국어 UX 라이터 + DX 컨설턴트 | Before/After 메시지 5건 |
232
+ | `testing` | TDD + property-based 테스트 엔지니어 | 누락 테스트 + property 후보 |
233
+ | `docs` | 한국어 기술 문서 작성자 | 60초 시작 가능성 평가 |
234
+
235
+ ```bash
236
+ leerness review src/api.js --persona security,performance,ux
237
+ leerness persona list
238
+ leerness persona add my-domain # 사용자 정의 페르소나
239
+ ```
143
240
 
144
241
  ---
145
242
 
146
- ## 📚 핵심 명령
243
+ ## 🛠 핵심 명령 매트릭스
147
244
 
148
- ### 작업 흐름
245
+ ### 일상 사용
149
246
  ```bash
150
- leerness handoff . # 세션 시작 — 컨텍스트 자동 적재
151
- leerness handoff --all-apps --since 1h # 워크스페이스 + 최근 변경
152
- leerness handoff --compact # LLM 프롬프트용 1줄 요약
153
- leerness session close . # 세션 종료 — handoff 자동 작성
247
+ leerness init [path] [--language auto|ko|en] # 신규 프로젝트 (1.9.34 인터랙티브)
248
+ leerness handoff [path] [--compact] [--all-apps] [--since 24h]
249
+ leerness audit [path] # 일관성 감사
250
+ leerness verify-claim T-XXX --run-tests # 증거 + 실 테스트
251
+ leerness optimism-check T-XXX # 낙관적 표시 감지
252
+ leerness gate [path] # verify+audit+scan+encoding+lazy
253
+ leerness session close [path] # 세션 마감
154
254
  ```
155
255
 
156
- ### 자동 검수 (핵심 기능)
256
+ ### 워크스페이스
157
257
  ```bash
158
- leerness verify-claim T-0001 --run-tests # progress-tracker evidence 자동 검증 + npm test
159
- leerness verify-code . --bench # test + lint + bench 일괄 실행
160
- leerness audit . # 일관성/계획↔진행 감사
161
- leerness lazy detect . # 거짓 완료 자동 감지
162
- leerness gate . # verify + audit + scan + encoding + lazy 일괄
163
- leerness optimism-check T-0001 # 1.9.26/27 낙관적 표시 자동 감지
164
- leerness verify-claim T-0001 --strict-claims # 1.9.26 verify-claim에 낙관적 검사 통합
165
- leerness deps <capability> --run-tests # 1.9.24 영향 추적 + 자동 회귀
166
- leerness review <file> --persona security,performance,ux # 1.9.29 도메인 페르소나 리뷰
167
- leerness persona list # 5종 내장 + 사용자 정의
168
- leerness persona show security # 페르소나 본문
169
- leerness persona add my-domain # 사용자 정의 페르소나
170
- leerness agents list # 1.9.30 외부 AI CLI 상태표
171
- leerness agents quota # 1.9.31 CLI별 사용량/한도 추정
172
- leerness agents dispatch "<task>" --to gemini # 1.9.30 sub-agent 명령 생성
173
- leerness setup-agents # 1.9.32 인터랙티브 CLI 설정 + 자동 설치 시도
258
+ leerness handoff --all-apps # 전 프로젝트 통합 뷰
259
+ leerness reuse-map --all-apps --strict-elements # 함수 중복 감지
260
+ leerness retro --all-apps --days 7 # 회고
261
+ leerness insights --all-apps # 누적 통계
262
+ leerness brainstorm "키워드" --all-apps --include-code
263
+ leerness deps <capability> --run-tests # 영향 추적 + 자동 회귀
174
264
  ```
175
265
 
176
- ### 워크스페이스 (멀티 프로젝트)
266
+ ### 외부 AI CLI (1.9.30~34)
177
267
  ```bash
178
- leerness retro --all-apps # 전 프로젝트 회고
179
- leerness reuse-map --all-apps # 중복 capability 자동 감지
180
- leerness reuse-map --all-apps --strict-elements # 함수명 fuzzy 중복
181
- leerness handoff --all-apps --since 24h # 최근 변경 워크스페이스 뷰
182
- leerness brainstorm "키워드" --all-apps # 누적 데이터 검색
183
- leerness insights --all-apps # 통계 + 안정성 평가
184
- leerness memory search "키" --include-code # 1.9.25 소스 코드 본문도 검색
185
- leerness brainstorm "주제" --include-code # 1.9.25 코드 hits 포함
186
- leerness register-pending "<요청>" --agent X # 1.9.25 다중 세션 즉시 신호
268
+ leerness setup-agents . # 인터랙티브 활성화 + 자동 설치
269
+ leerness agents list # 4 CLI 상태표
270
+ leerness agents quota # 사용량 추정
271
+ leerness agents dispatch "<task>" --to gemini # 명령 생성
187
272
  ```
188
273
 
189
- ### 멀티 에이전트 (1.9.22, opt-in)
274
+ ### 페르소나·리뷰 (1.9.29)
190
275
  ```bash
191
- # 환경변수 설정 후 활성화 (자동 실행 절대 금지)
192
- echo "LEERNESS_OLLAMA_BASE_URL=http://localhost:11434" >> .env
193
- leerness orchestrate "<목표>" --agents 10 --model qwen2.5:7b-instruct
276
+ leerness persona list|show <id>|add <id>
277
+ leerness review <file> --persona security,performance,ux
194
278
  ```
195
279
 
196
280
  ### 데이터 위생
197
281
  ```bash
198
- leerness scan secrets . # AWS/GitHub/OpenAI/Anthropic/Google/Slack/PEM/하드코딩 패스워드
282
+ leerness scan secrets . # AWS/GitHub/OpenAI/Anthropic/Google/Slack/PEM
199
283
  leerness encoding check . # BOM/UTF-16/한글 라운드트립
284
+ leerness lazy detect . # 증거 없는 done · 빈 handoff · 추적 없는 TODO
200
285
  ```
201
286
 
202
287
  ### 버전 관리
@@ -208,42 +293,23 @@ leerness update --from <tgz> # 오프라인/사내 미러
208
293
 
209
294
  ---
210
295
 
211
- ## 🤖 멀티 에이전트 오케스트레이션 (1.9.22)
212
-
213
- **Opt-in 정책 ⚠** — LLM 호출은 사용자 명시적 동의 후에만 활성화. 환경변수 미설정 시 명령 거부 (`LEERNESS_OLLAMA_BASE_URL` 필수).
214
-
215
- ```bash
216
- # 활성화 (.env)
217
- LEERNESS_OLLAMA_BASE_URL=http://localhost:11434
218
- LEERNESS_OLLAMA_MODEL=qwen2.5:7b-instruct # 선택
219
-
220
- # 가변 sub-agent
221
- leerness orchestrate "함수 작성" --agents 3
222
- leerness orchestrate "복잡한 기능" --agents 20
223
- ```
224
-
225
- 실측 병렬 효과: 3 agent 1.9× / 5 agent 3.2× / 10 agent 5.5×.
226
-
227
- ---
228
-
229
- ## 🔄 자동 버전 감지/업데이트
230
-
231
- `init`/`migrate` 시 `.claude/settings.local.json`의 SessionStart hook에 `update --check` 자동 등록. 24시간 캐시(`.harness/cache/update-check.json`)로 npm 호출 폭주 방지.
296
+ ## 🌐 환경변수
232
297
 
233
- | 명령 | 동작 |
298
+ | 변수 | 효과 |
234
299
  |---|---|
235
- | `update --check` | `HARNESS_VERSION` ↔ `npm view leerness version` 비교 |
236
- | `update --yes` | 백업 → 마이그레이션 → verify/audit → 로그 누적 |
237
- | `update --from <tarball>` | 로컬/오프라인/사내 미러 · `LEERNESS_OFFLINE=1` npm 스킵 |
238
-
239
- ---
240
-
241
- ## 🛡 비파괴 마이그레이션 정책
242
-
243
- - 모든 변경 전 `.harness/archive/leerness-<version>-<timestamp>/` 자동 백업
244
- - 사용자 메모리 (`plan`, `progress`, `decisions`, `task-log`, `architecture`, `reuse-map` 등) **항상 보존**
245
- - 관리 인스트럭션 (`AGENTS.md`, `CLAUDE.md`, `.cursor/rules/leerness.mdc`, `.github/copilot-instructions.md`)은 새 템플릿으로 머지하되 이전 내용을 `<!-- leerness:migration-preserved -->` 블록 안에 보존
246
- - `.env.example` / `.gitignore` / `.gitattributes`는 라인 단위 머지 · 결과 보고: `.harness/migration-report.md`
300
+ | `LEERNESS_OFFLINE=1` | npm 호출 스킵 (오프라인) |
301
+ | `LEERNESS_NPM_TOKEN` | release publish용 |
302
+ | `LEERNESS_GITHUB_TOKEN` | gh release용 |
303
+ | `LEERNESS_OLLAMA_BASE_URL` | 1.9.22 — orchestrate opt-in 활성 |
304
+ | `LEERNESS_OLLAMA_MODEL` | orchestrate 기본 모델 |
305
+ | `LEERNESS_ENABLE_CLAUDE` | 1.9.30 — agents dispatch Claude 활성 (=1) |
306
+ | `LEERNESS_ENABLE_CODEX` | 1.9.30 — Codex 활성 (=1) |
307
+ | `LEERNESS_ENABLE_GEMINI` | 1.9.30 — Gemini 활성 (=1) |
308
+ | `LEERNESS_ENABLE_COPILOT` | 1.9.30 — gh copilot 활성 (=1) |
309
+ | `LEERNESS_NO_BANNER` | 1.9.32 — init 배너 스킵 (=1) |
310
+ | `LEERNESS_NO_PROMPT` | 1.9.32 — readline prompt 강제 비활성 (=1) |
311
+ | `LEERNESS_NO_STALE_CHECK` | 1.9.33 — npx 캐시 옛 버전 경고 끄기 (=1) |
312
+ | `LEERNESS_NO_INTERACTIVE` | 1.9.34 — 방향키 multi-select 비활성, 숫자 prompt 폴백 (=1) |
247
313
 
248
314
  ---
249
315
 
@@ -261,6 +327,7 @@ leerness orchestrate "복잡한 기능" --agents 20
261
327
  ├── skill-index.md · skills/<id>/ · templates/
262
328
  ├── personas/<id>.md (1.9.29+, 사용자 정의 페르소나)
263
329
  ├── reviews/ (1.9.29+, 페르소나 리뷰 결과)
330
+ └── cache/update-check.json (1.9.33+, 24h npm latest 캐시)
264
331
 
265
332
  .claude/ (commands · skills · settings.local.json) · .cursor/rules/leerness.mdc
266
333
  .github/copilot-instructions.md · AGENTS.md · CLAUDE.md
@@ -268,6 +335,27 @@ leerness orchestrate "복잡한 기능" --agents 20
268
335
 
269
336
  ---
270
337
 
338
+ ## 🛡 비파괴 마이그레이션 정책
339
+
340
+ - 모든 변경 전 `.harness/archive/leerness-<version>-<timestamp>/` 자동 백업
341
+ - 사용자 메모리 (`plan`, `progress`, `decisions`, `task-log`, `architecture`, `reuse-map` 등) **항상 보존**
342
+ - 관리 인스트럭션은 새 템플릿으로 머지하되 이전 내용을 `<!-- leerness:migration-preserved -->` 블록에 보존
343
+ - 결과 보고: `.harness/migration-report.md`
344
+
345
+ ---
346
+
347
+ ## 🔄 자동 버전 감지/업데이트
348
+
349
+ `init`/`migrate` 시 `.claude/settings.local.json`의 SessionStart hook에 `update --check` 자동 등록. 24시간 캐시로 npm 호출 폭주 방지.
350
+
351
+ | 명령 | 동작 |
352
+ |---|---|
353
+ | `update --check` | `HARNESS_VERSION` ↔ `npm view leerness version` 비교 |
354
+ | `update --yes` | 백업 → 마이그레이션 → verify/audit → 로그 누적 |
355
+ | `update --from <tarball>` | 로컬/오프라인/사내 미러 |
356
+
357
+ ---
358
+
271
359
  ## 🧪 자동 검수 도구 매트릭스
272
360
 
273
361
  | 도구 | 검출 | 추가 |
@@ -285,152 +373,25 @@ leerness orchestrate "복잡한 기능" --agents 20
285
373
  | `lazy detect` | 증거 없는 done · 빈 handoff · 추적 없는 TODO | 1.9.7 |
286
374
  | `orchestrate --agents N` | 다중 LLM 동시 호출 (opt-in) | 1.9.22 |
287
375
  | `handoff --compact` | LLM 시스템 프롬프트용 압축 출력 | 1.9.22 |
288
- | `review --persona X` | 도메인별 sub-agent 자동 프롬프트 (security/performance/ux/testing/docs) | 1.9.29 |
289
- | `persona list/show/add` | 페르소나 카탈로그 관리 (.harness/personas/) | 1.9.29 |
290
- | `agents list/check` | 4 CLI(claude/codex/gemini/copilot) 활성/설치 상태표 (env + PATH 검증) | 1.9.30 |
291
- | `agents dispatch --to X` | ready CLI에 대상 명령 자동 생성 (자동 호출 금지) | 1.9.30 |
292
- | `agents quota` | provider별 사용량/한도 추정 + 대시보드 안내 | 1.9.31 |
293
- | `setup-agents` | 인터랙티브 CLI 활성화 + 미설치 자동 설치 시도 (.env upsert) | 1.9.32 |
294
-
295
- ---
296
-
297
- ## 🧰 Anti-Lazy Work Policy
298
-
299
- `anti-lazy-work-policy.md`의 6개 규칙 + `lazy detect`/`verify-claim` 자동 점검:
300
-
301
- 1. **증거 없는 완료 금지** — `evidence` 컬럼이 비었거나 plan-link만이면 경고
302
- 2. **빈 핸드오프 금지** — Completed/In Progress/Next Exact Step 모두 비어 있으면 `insufficient`
303
- 3. **부분 구현 자기보고** — `incomplete` 표기 + Next Exact Step 1줄
304
- 4. **검증 기록 누적** — `review-evidence.md`에 typecheck/lint/test 결과
305
- 5. **TODO 추적** — 새 TODO/FIXME → progress-tracker 동일 ID
306
- 6. **자동 감지** — 거짓 완료/추적 없는 TODO/blocker 방치/검증 흔적 부재
376
+ | `review --persona X` | 도메인별 sub-agent 자동 프롬프트 | 1.9.29 |
377
+ | `persona list/show/add` | 페르소나 카탈로그 관리 | 1.9.29 |
378
+ | `agents list/check` | 4 CLI 활성/설치 상태표 | 1.9.30 |
379
+ | `agents dispatch --to X` | ready CLI에 대상 명령 자동 생성 | 1.9.30 |
380
+ | `agents quota` | provider별 사용량/한도 추정 | 1.9.31 |
381
+ | `setup-agents` | 인터랙티브 CLI 활성화 + 자동 설치 시도 | 1.9.32 |
382
+ | `_warnIfStale` (자동) | npx 캐시 옛 버전 자동 경고 | 1.9.33 |
383
+ | `_selectOne/_selectMany` | 방향키/Space 인터랙티브 multi-select | 1.9.34 |
307
384
 
308
385
  ---
309
386
 
310
- ## 🔬 낙관적 표시 방지 (1.9.26/27)
311
-
312
- evidence에 "API 호출 완료" / "DB 저장 1000건" 같이 외부 작용을 적었지만 실제 코드에 호출 흔적이 없는 경우를 정적 분석으로 자동 감지.
313
-
314
- ### 10 카테고리 (1.9.27)
315
- | 영역 | evidence 패턴 | 코드 흔적 |
316
- |---|---|---|
317
- | API | `API 호출 / POST /` | `fetch( / axios / http.request` |
318
- | DB | `DB 저장 / insert N건` | `db. / pg. / mongoose. / prisma.` |
319
- | Email | `이메일 발송 / sendMail` | `nodemailer / smtp / sendgrid` |
320
- | Webhook | `웹훅 호출` | `fetch / axios.` |
321
- | Payment | `결제 완료 / stripe` | `stripe / toss / iamport` |
322
- | FileIO | `파일 N개 생성` | `fs.write / appendFile` |
323
- | Queue | `메시지 큐 발행` | `amqp / kafkajs / bull` |
324
- | Cache | `Redis 저장` | `redis. / ioredis` |
325
- | Notify | `슬랙 알림` | `slack / discord.js` |
326
- | Storage | `S3 업로드` | `aws-sdk/client-s3` |
327
-
328
- **URL/메서드 단위 매핑 (1.9.27 핵심)** — evidence에 `POST /users`가 있으면 코드에서 실제 `/users` 경로 호출 검사. 못 찾으면 의심 발견. **신뢰도 점수** 0~1 출력 (< 0.5 ⚠ 낮음 / < 0.9 ⓘ 보통 / ≥ 0.9 ✓ 높음).
329
-
330
- ```bash
331
- leerness optimism-check T-0001 --path .
332
- leerness verify-claim T-0001 --run-tests --strict-claims
333
- ```
387
+ ## 🤝 Claude Code / Cursor / Copilot 통합
334
388
 
335
- **1.9.28 — 한국형 PG 패턴 보강**: 카카오페이/네이버페이/페이팔 결제 패턴이 기본 카테고리에 포함되어 한국 커머스 evidence도 자동 매핑. confidence floor 0.15로 의심 발견율 향상.
336
-
337
- ---
338
-
339
- ## 🎭 페르소나 리뷰 (1.9.29)
340
-
341
- 도메인 페르소나를 sub-agent에 자동 부여 → 표면 리뷰 대비 **도메인 발견 3-4배**, 토큰 비용 ~3%.
342
-
343
- ### 5종 내장 페르소나
344
- | ID | 역할 | 발견 깊이 |
345
- |---|---|---|
346
- | `security` | 10년차 보안 엔지니어 (OWASP/CWE/한국 개인정보보호법) | CWE 매핑 + 실 페이로드 |
347
- | `performance` | V8 엔진 내부 전문가 (hidden class/GC/이벤트 루프) | Hot path Top 5 + RPS 추정 |
348
- | `ux` | 한국어 UX 라이터 + DX 컨설턴트 (토스/카카오/Stripe) | Before/After 메시지 5건 |
349
- | `testing` | TDD + property-based 테스트 엔지니어 (fast-check) | 누락 테스트 + property 후보 |
350
- | `docs` | 한국어 기술 문서 작성자 (Stripe Docs / 카카오 dev) | 60초 시작 가능성 평가 |
351
-
352
- ### 사용
353
- ```bash
354
- # 단일 페르소나
355
- leerness review src/api.js --persona security
356
-
357
- # 다중 페르소나 (동시 sub-agent spawn 권장)
358
- leerness review src/api.js --persona security,performance,ux
359
-
360
- # 사용자 정의 페르소나
361
- leerness persona add my-domain # .harness/personas/my-domain.md 템플릿 생성
362
- ```
363
-
364
- ### 실측 (sub-agent 4명 동시 리뷰, 같은 파일)
365
- - 보안 페르소나: CWE 12건 + 한국 법규 + 실 페이로드 1건
366
- - 성능 페르소나: Hot path Top 5 + 비효율 11건 + RPS 추정 12k+
367
- - UX 페르소나: Before/After 5건 + SDK 점수 2/5 + 로드맵 10건
368
- - **페르소나 없음 (control)**: 14건 (표면적, 분야 분산)
369
-
370
- → 페르소나 적용 = 도메인 발견율 100%, control = 30%. 토큰 비용 ~3% 추가만.
371
-
372
- ---
373
-
374
- ## 🤖 외부 AI CLI 오케스트레이션 (1.9.30 / 1.9.31 / 1.9.32)
375
-
376
- claude/codex/gemini/copilot CLI들을 sub-agent로 명시적 활용. **자동 호출 절대 금지** — 환경변수 활성화 + PATH 존재 둘 다 충족 시에만 ready.
377
-
378
- ### 활성화 — 자동 (1.9.32 권장)
379
- ```bash
380
- leerness setup-agents . # 인터랙티브: 각 CLI별 yes/no + 미설치 자동 설치 시도
381
- # → .env에 LEERNESS_ENABLE_* 자동 기록
382
- # → 미설치 CLI는 npm i -g / gh extension install 실행 (사용자 동의 시)
383
- ```
384
-
385
- ### 활성화 — 수동 (`.env` 직접 편집)
386
- ```bash
387
- LEERNESS_ENABLE_CLAUDE=1 # Anthropic Claude Code CLI
388
- LEERNESS_ENABLE_CODEX=1 # OpenAI Codex CLI (격리 sandbox)
389
- LEERNESS_ENABLE_GEMINI=1 # Google Gemini CLI (--yolo 모드는 워크스페이스 직접 수정 가능)
390
- LEERNESS_ENABLE_COPILOT=1 # GitHub Copilot CLI (gh copilot)
391
- ```
392
-
393
- ### 사용
394
- ```bash
395
- leerness agents list # 4 CLI 상태표 (env + PATH + 버전)
396
- leerness agents quota # provider별 사용량/한도 추정 (1.9.31)
397
- leerness agents dispatch "<task>" --to gemini # ready CLI에 명령 자동 생성
398
- leerness setup-agents # 1.9.32 인터랙티브 재설정
399
- ```
400
-
401
- ### 자동 설치 명령 (1.9.32 setup-agents가 사용)
402
- | CLI | install 명령 | 안내 |
403
- |---|---|---|
404
- | claude | `npm i -g @anthropic-ai/claude-code` | https://docs.anthropic.com/en/docs/claude-code/setup |
405
- | codex | `npm i -g @openai/codex` | https://github.com/openai/codex |
406
- | gemini | `npm i -g @google/gemini-cli` | https://github.com/google-gemini/gemini-cli |
407
- | copilot | `gh extension install github/gh-copilot` | https://github.com/github/gh-copilot (gh CLI 선행 필요) |
408
-
409
- ### quota 안내 (1.9.31)
410
- | CLI | 추정 | 안내 |
411
- |---|---|---|
412
- | claude | `unknown` | 대화 내 `/status` 슬래시 또는 https://console.anthropic.com/settings/usage |
413
- | codex | `cli-supported` 또는 `unknown` | `codex usage`/`codex quota` 시도 또는 https://platform.openai.com/account/usage |
414
- | gemini | `rate-limited` | 무료 60 req/min, 1000 req/day · https://ai.google.dev/gemini-api/docs/rate-limits |
415
- | copilot | `subscription` 또는 `not-authed` | 월 구독자 무제한 · `gh auth login` 필요 시 안내 |
416
-
417
- ### 실측 (이번 라운드)
418
- - Sub B (rpg-craft, Claude 페르소나) → 20/20 pass, 1,567 라인
419
- - Sub C (rpg-achievements, Claude 페르소나) → 22/22 pass, 1,375 라인
420
- - Sub D (rpg-instance, Claude 페르소나, cross-project require 시연) → 20/20 pass, 1,016 라인
421
- - → **3 도메인 동시 진행**, 메인 에이전트가 sub-agent들에 페르소나 + 영역 분배 + 충돌 방지 컨벤션 명시.
422
-
423
- ### 정책
424
- - ❌ leerness는 외부 CLI를 자동 호출하지 않음 (사용자/메인 에이전트가 명시적 실행)
425
- - ✅ `agents dispatch`는 명령 텍스트만 출력 — 복사해서 실행
426
- - ✅ quota 여유 큰 CLI를 메인 에이전트가 우선 선택하도록 신호 제공
427
- - ⚠ `gemini --yolo`는 워크스페이스 파일 직접 수정 가능 — 격리 sandbox 아님 (codex와 차이)
428
-
429
- ---
430
-
431
- ## 🤝 Claude Code 통합
432
-
433
- 설치 시 자동 등록: `.claude/commands/{handoff, session-close, audit, lazy-detect, update}.md` · `.claude/skills/leerness.md` (스킬 정의) · `.claude/settings.local.json` (SessionStart hook `update --check`) · `.cursor/rules/leerness.mdc` (Cursor) · `.github/copilot-instructions.md` (Copilot)
389
+ 설치 시 자동 등록:
390
+ - `.claude/commands/{handoff, session-close, audit, lazy-detect, update}.md`
391
+ - `.claude/skills/leerness.md` (스킬 정의)
392
+ - `.claude/settings.local.json` (SessionStart hook `update --check`)
393
+ - `.cursor/rules/leerness.mdc`
394
+ - `.github/copilot-instructions.md`
434
395
 
435
396
  ---
436
397
 
@@ -445,23 +406,7 @@ leerness skill optimize <id> --before "..." --after "..."
445
406
  leerness skill consolidate
446
407
  ```
447
408
 
448
- 기본 카탈로그: `feature-implementation`, `ai-verified-skill-publisher`, `open-meteo`, `static-site-builder`, `project-roadmap-generator`, `office`, `commerce-api`, `crawling`, `firebase`, `ads-analytics`, `appstore-review`.
449
-
450
- ---
451
-
452
- ## 🌐 환경변수
453
-
454
- | 변수 | 효과 |
455
- |---|---|
456
- | `LEERNESS_OFFLINE=1` | npm 호출 스킵 (오프라인) |
457
- | `LEERNESS_NPM_TOKEN` | release publish용 (있을 때) |
458
- | `LEERNESS_GITHUB_TOKEN` | gh release용 (있을 때) |
459
- | **`LEERNESS_OLLAMA_BASE_URL`** | **1.9.22 — orchestrate opt-in 활성화** |
460
- | `LEERNESS_OLLAMA_MODEL` | 기본 모델 (orchestrate `--model`로 override) |
461
- | **`LEERNESS_ENABLE_CLAUDE`** | **1.9.30 — `agents list/dispatch` Claude Code CLI 활성** (=1) |
462
- | **`LEERNESS_ENABLE_CODEX`** | **1.9.30 — Codex CLI 활성** (=1) |
463
- | **`LEERNESS_ENABLE_GEMINI`** | **1.9.30 — Gemini CLI 활성** (=1) |
464
- | **`LEERNESS_ENABLE_COPILOT`** | **1.9.30 — gh copilot 활성** (=1) |
409
+ **기본 카탈로그**: `feature-implementation`, `ai-verified-skill-publisher`, `open-meteo`, `static-site-builder`, `project-roadmap-generator`, `office`, `commerce-api`, `crawling`, `firebase`, `ads-analytics`, `appstore-review`.
465
410
 
466
411
  ---
467
412
 
@@ -474,6 +419,7 @@ leerness skill consolidate
474
419
  | "통계 / 누적 지표" | `leerness insights` |
475
420
  | "X 관련 자료 / X 시작 전 검토" | `leerness brainstorm "X"` |
476
421
  | "매 X마다 Y를 해줘" | `leerness rule add "Y" --trigger every-X` |
422
+ | "외부 CLI 설정" | `leerness setup-agents` |
477
423
 
478
424
  `AGENTS.md`에 자동 등록 — Claude Code/Cursor가 이를 보고 자연어를 명령으로 변환.
479
425
 
@@ -488,10 +434,13 @@ A. 사용자 메모리(plan/progress/decisions/architecture/reuse-map 등)는 **
488
434
  A. 기본 동작입니다. `LEERNESS_OLLAMA_BASE_URL` 미설정 시 LLM 호출 절대 발생 안 함. `orchestrate` 명령만 거부 (다른 명령은 LLM 없이 동작).
489
435
 
490
436
  **Q. CI에서 사용 가능?**
491
- A. 네. `--json` (retro/insights/brainstorm/handoff/reuse-map/verify-claim) + exit code 통합. `verify-claim T-XXX --run-tests --json | jq '.verdict.runTests'`.
437
+ A. 네. `--json` (retro/insights/brainstorm/handoff/reuse-map/verify-claim) + exit code 통합. `--yes` + `LEERNESS_NO_PROMPT=1`로 비대화형 보장.
438
+
439
+ **Q. 외부 AI CLI를 자동으로 호출하나요?**
440
+ A. **아니요.** `agents dispatch`는 명령 텍스트만 출력합니다. 사용자/메인 에이전트가 명시적으로 실행해야 합니다.
492
441
 
493
- **Q. 다른 워크스페이스 모드 명령은?**
494
- A. `--all-apps`는 현재 디렉토리 + `_apps/*` (또는 부모의 `_apps/*`)의 모든 leerness 프로젝트 발견. `--include p1,p2`로 명시도 가능.
442
+ **Q. multi-select가 SSH/tmux에서 안 보여요.**
443
+ A. 256색 ANSI를 지원하지 않는 환경입니다. `LEERNESS_NO_INTERACTIVE=1` 또는 `--no-interactive-select`로 구식 숫자 prompt를 사용하세요.
495
444
 
496
445
  ---
497
446
 
@@ -501,31 +450,27 @@ A. `--all-apps`는 현재 디렉토리 + `_apps/*` (또는 부모의 `_apps/*`)
501
450
  npm test # = node ./scripts/e2e.js
502
451
  ```
503
452
 
504
- **151/151 시나리오** 통과 (1.9.7~1.9.32 회귀 + 신규 검증).
453
+ **155/156 시나리오** 통과 (1.9.7~1.9.34 회귀 + 신규 검증).
505
454
 
506
455
  ---
507
456
 
508
457
  ## 📜 변경 이력 (최근)
509
458
 
510
- - **1.9.32** — ASCII 배너 + `leerness setup-agents` 인터랙티브 설정 + 미설치 CLI 자동 설치 시도. `init` 시 자동 prompt.
511
- - **1.9.31** — `leerness agents quota` (provider별 사용량/한도 추정 + 대시보드 안내). 멀티 에이전트 분배 신호.
512
- - **1.9.30** — 외부 AI CLI 오케스트레이션 (claude/codex/gemini/copilot) + 환경변수 활성화 정책 + `leerness agents list/check/dispatch`
513
- - **1.9.29** — 페르소나 시스템 (5종 내장) + `leerness review --persona` (도메인 깊이 3-4배)
514
- - **1.9.28** — 카카오페이/네이버페이 패턴 + confidence floor 0.15
515
- - **1.9.27** — `optimism-check` 강화: 10 카테고리 + URL/메서드 매핑 + 신뢰도 점수
516
- - **1.9.26** — `optimism-check <T-ID>`, `verify-claim --strict-claims` (낙관적 표시 방지)
517
- - **1.9.25** — `--include-code` (소스 코드 인덱싱), `register-pending` (다중 세션)
518
- - **1.9.24** — `deps <capability>` (depends-on 역추적 + 자동 회귀)
519
- - **1.9.23** — `preferGlobal`, README Install 가이드
520
- - **1.9.22** — Ollama opt-in 통합 (`orchestrate --agents N`), `handoff --compact`, `llm-bench record`
521
- - **1.9.21** — `.cfg`/`.ini`/`.env`/`.toml`/`.lock` 메타 파일 verify-claim regex 확장
522
- - **1.9.20** — Godot/jest/mocha 지원, `verify-code --bench`, file regex 도메인 폴더 자동 인식
523
- - **1.9.19** — `verify-claim --run-tests` 동적 검증, `--strict-elements` same-file vs diff-file 구분
524
- - **1.9.18** — `--since`, `--strict-elements`, `depends-on` 그래프, `verify-claim`
525
- - **1.9.17** — `handoff/reuse-map --all-apps` 워크스페이스 모드
526
- - **1.9.16** — `retro/insights/brainstorm --json` export
527
- - **1.9.15** — `retro --all-apps` 워크스페이스 회고
528
- - ... (전체 CHANGELOG.md 참조)
459
+ - **1.9.34** — 방향키/스페이스 인터랙티브 multi-select (`_selectOne`/`_selectMany`) + 256색 그라데이션 배너 + 3단계 sub-agent 오케스트레이션 검증 (2.2× 효율 실측).
460
+ - **1.9.33** — `_warnIfStale()` — `npx leerness init` 시 옛 버전 자동 경고 + 해결 안내.
461
+ - **1.9.32** — ASCII 배너 + `setup-agents` 인터랙티브 설정 + 미설치 CLI 자동 설치 시도.
462
+ - **1.9.31** — `leerness agents quota` (provider별 사용량/한도 추정).
463
+ - **1.9.30** — 외부 AI CLI 오케스트레이션 (claude/codex/gemini/copilot) + 환경변수 활성화 정책.
464
+ - **1.9.29** — 페르소나 시스템 (5종 내장) + `leerness review --persona` (도메인 깊이 3-4배).
465
+ - **1.9.28** — 카카오페이/네이버페이 패턴 + confidence floor 0.15.
466
+ - **1.9.27** — `optimism-check` 강화: 10 카테고리 + URL/메서드 매핑 + 신뢰도 점수.
467
+ - **1.9.26** — `optimism-check <T-ID>`, `verify-claim --strict-claims`.
468
+ - **1.9.25** — `--include-code` (소스 코드 인덱싱), `register-pending` (다중 세션).
469
+ - **1.9.24** — `deps <capability>` (depends-on 역추적 + 자동 회귀).
470
+ - **1.9.22** — Ollama opt-in 통합 (`orchestrate --agents N`), `handoff --compact`, `llm-bench record`.
471
+ - **1.9.18** — `--since`, `--strict-elements`, `depends-on` 그래프, `verify-claim`.
472
+ - **1.9.17** — `handoff/reuse-map --all-apps` 워크스페이스 모드.
473
+ - ... (전체 [CHANGELOG.md](CHANGELOG.md) 참조)
529
474
 
530
475
  ---
531
476
 
@@ -540,4 +485,5 @@ npm test # = node ./scripts/e2e.js
540
485
 
541
486
  MIT — © leerness contributors
542
487
 
543
- > **AI 에이전트를 잘 다루는 도구가 되도록 설계되었습니다.** 사용자 동의 없이 자동으로 외부 LLM/API를 호출하지 않습니다.
488
+ > **AI 에이전트를 잘 다루는 도구가 되도록 설계되었습니다.**
489
+ > 사용자 동의 없이 자동으로 외부 LLM/API/CLI를 호출하지 않습니다.