leerness 1.9.36 → 1.9.38

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 +69 -0
  2. package/README.md +245 -338
  3. package/bin/harness.js +296 -1
  4. package/package.json +1 -1
  5. package/scripts/e2e.js +149 -0
package/README.md CHANGED
@@ -1,330 +1,268 @@
1
1
  # Leerness
2
2
 
3
- > **AI 에이전트 검수·다중 협업 CLI 하네스** — 거짓 완료 차단, 멀티 에이전트 오케스트레이션, 사양 ↔ 구현 일치 검증, 워크스페이스 통합 가시성. **한국어 우선**.
3
+ > **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.36-green)]() [![tests](https://img.shields.io/badge/e2e-166%2F166-success)]() [![license](https://img.shields.io/badge/license-MIT-lightgrey)]()
6
-
7
- > Claude Code · Cursor · Copilot · Codex · Gemini CLI — 어떤 AI 에이전트로 코드를 짜든, leerness는 **"진짜로 했나? 중복 아닌가? 합의된 사양인가?"** 를 자동으로 검수합니다.
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.38-green)]() [![tests](https://img.shields.io/badge/e2e-174%2F174-success)]() [![license](https://img.shields.io/badge/license-MIT-lightgrey)]()
8
6
 
9
7
  ```
10
8
  ╔══════════════════════════════════════════════════════════════╗
11
- ║ ║
12
9
  ║ ██╗ ███████╗███████╗██████╗ ███╗ ██╗███████╗███████╗ ║
13
10
  ║ ██║ ██╔════╝██╔════╝██╔══██╗████╗ ██║██╔════╝██╔════╝ ║
14
11
  ║ ██║ █████╗ █████╗ ██████╔╝██╔██╗ ██║█████╗ ███████╗ ║
15
12
  ║ ██║ ██╔══╝ ██╔══╝ ██╔══██╗██║╚██╗██║██╔══╝ ╚════██║ ║
16
13
  ║ ███████╗███████╗███████╗██║ ██║██║ ╚████║███████╗███████║ ║
17
14
  ║ ╚══════╝╚══════╝╚══════╝╚═╝ ╚═╝╚═╝ ╚═══╝╚══════╝╚══════╝ ║
18
- ║ ║
19
- ║ v1.9.34 Korean-first AI Development Harness ║
20
- ║ ★ verify · reuse-map · handoff · agents · orchestrate ║
21
- ║ ║
15
+ ║ v1.9.38 AI Agent Reliability Harness ║
16
+ ║ verify · remember · orchestrate · audit · prevent drift ║
22
17
  ╚══════════════════════════════════════════════════════════════╝
23
18
  ```
24
19
 
25
20
  ---
26
21
 
27
- ## 🤔 leerness가 해결하는 문제
28
-
29
- AI 에이전트(Claude Code, Cursor, Copilot, Codex, Gemini CLI 등)는 **빠르게 코드를 쓰지만, 다음 함정에 반복해서 빠집니다**:
30
-
31
- | AI와 함께 일할 때 흔한 함정 | leerness의 해결책 |
32
- |---|---|
33
- | 🚨 "완료했습니다"라고 했지만 실제로 코드에 변경이 없음 | `verify-claim --run-tests` — 증거 파일 존재 + 테스트 실제 실행 검증 |
34
- | 🚨 "API 호출 완료" 라고 했지만 코드에 URL이 없음 | `optimism-check` — 10 카테고리 패턴 + URL 매핑 + 신뢰도 점수 |
35
- | 🚨 같은 함수를 여러 프로젝트에 중복 생성 | `reuse-map --all-apps --strict-elements` — 함수명 fuzzy 중복 감지 |
36
- | 🚨 다음 세션이 컨텍스트를 잃음 | `handoff` — plan/progress/decisions 3채널 자동 적재 + `--compact` (500자) |
37
- | 🚨 표면적 코드 리뷰 (도메인 깊이 부족) | `review --persona security,performance,ux` — 5 도메인 sub-agent 자동 부여 |
38
- | 🚨 외부 AI CLI를 자동 호출하면 위험 | `agents list/dispatch/quota` — 환경변수 활성화 + 명시적 분배 (자동 호출 X) |
39
- | 🚨 npx 캐시로 옛 버전이 실행됨 | `_warnIfStale` — install 시 npm latest 자동 비교 + 경고 (1.9.33+) |
40
- | 🚨 멀티 sub-agent가 같은 파일을 동시에 써서 작업 손실 | 프롬프트 템플릿에 **파일 경로 격리 의무**, `agents dispatch` 안내문이 자동 추가 (1.9.34/35) |
41
- | 🚨 sub-agent마다 사양 해석이 달라 통합 시 BUG 양산 | **`leerness contract verify <spec.md> <impl.js>`** — 명세 ↔ 구현 함수/필드 자동 검사 (1.9.35) |
42
- | 🚨 신규 모듈의 capability가 reuse-map에 등록 안 됨 | **`leerness reuse autodetect`** — `module.exports` 스캔 + 자동 등록 (1.9.35) |
43
- | 🚨 신규 디렉토리에서 sub-agent가 컨텍스트 없이 작업 시작 | `handoff` 호출 시 **.harness 부재 자동 경고** (1.9.35) |
44
- | 🚨 audit warning이 쌓이지만 수동 fix가 번거로움 | **`audit --fix`** — session-handoff/current-state 자동 갱신 (1.9.35) |
45
-
46
- ---
47
-
48
- ## ⚙️ 설치 (Install)
49
-
50
- > ⚠️ **leerness는 CLI 도구입니다.** `npm i leerness`만으로는 명령이 PATH에 없습니다. 아래 셋 중 하나:
51
-
52
- ```bash
53
- # ✅ 1) 추천 — 설치 없이 즉시 실행 (항상 @latest 명시)
54
- npx leerness@latest init . --language ko --skills recommended
55
-
56
- # ✅ 2) 전역 설치 (한 번이면 끝)
57
- npm i -g leerness@latest && leerness --version
58
-
59
- # ✅ 3) 로컬 dev dependency
60
- npm i --save-dev leerness && npx leerness handoff .
61
- ```
62
-
63
- ### 🚨 npx 캐시 함정 (1.9.33부터 자동 경고)
64
-
65
- `@latest` 없이 `npx leerness init`만 실행하면 **PC에 캐시된 옛 버전이 무한 재사용**됩니다.
66
-
67
- ```bash
68
- # ❌ 위험 — 캐시된 옛 버전 실행 가능
69
- npx leerness init .
22
+ ## leerness는 무엇인가요?
70
23
 
71
- # ✅ 안전 — 항상 최신 받음
72
- npx leerness@latest init .
73
-
74
- # ✅ 캐시 의심 시 비우고 다시
75
- npx --yes clear-npx-cache && npx --yes leerness@latest init .
76
- ```
24
+ Claude Code · Cursor · Copilot · Codex · Gemini CLI 같은 **AI 코딩 에이전트와 함께 일할 때 발생하는 구조적 문제**를 자동으로 막는 CLI 하네스입니다.
77
25
 
78
- 1.9.33부터 `leerness init` 실행 시 npm registry latest와 자동 비교 → 옛 버전이면 즉시 경고:
26
+ AI 에이전트는 빠르게 코드를 쓰지만, 다음 **5가지 함정**에 반복해서 빠집니다:
79
27
 
80
28
  ```
81
- ⚠ 옛 버전이 실행 중입니다 — v1.9.21 → v1.9.34 (npm 최신)
82
- 해결: npx --yes clear-npx-cache && npx leerness@latest init .
29
+ 1. 거짓 완료 — "구현했습니다"는데 코드에 변경이 없거나 테스트 미실행
30
+ 2. 중복 생성 — 이미 있는 함수를 다른 프로젝트에 또 만듦
31
+ 3. 망각 — 다음 세션에서 컨텍스트(plan/decisions)를 잃음
32
+ 4. 충돌 — 멀티 에이전트가 같은 파일을 동시에 써서 작업 손실
33
+ 5. 도구 drift — 시간이 지날수록 메인 에이전트가 도구·메타파일을 잊음
83
34
  ```
84
35
 
85
- 경고 끄기: `--no-stale-check` 또는 `LEERNESS_NO_STALE_CHECK=1`.
36
+ leerness는 이 5가지를 모두 **자동으로 감지·차단·회복**합니다.
86
37
 
87
38
  ---
88
39
 
89
- ## 🎨 1.9.34 설치 경험 — 인터랙티브 multi-select
40
+ ## 어떻게 작동하나요?
90
41
 
91
- `leerness init`은 **방향키/스페이스/Enter**로 언어·스킬·sub-agent CLI를 선택합니다:
42
+ ### 1. 워크스페이스에 4개 채널을 만듭니다
92
43
 
93
44
  ```
94
- 설치 언어를 선택하세요
95
- ↑↓ 이동, Enter 확정, q 취소
96
- ❯ 자동 감지 — 디렉토리/파일 분석으로 한국어/영어 자동 판별
97
- 한국어 — 모든 인스트럭션을 한국어로 생성
98
- English — 모든 인스트럭션을 영어로 생성
99
-
100
- 설치할 스킬 라이브러리 (Space=토글, a=전체, n=해제, Enter=확정)
101
- ↑↓ 이동, Space 토글, a 전체, n 해제, Enter 확정
102
- ❯ ◉ office — 마이크로소프트 오피스 자동화
103
- ◉ commerce-api — 커머스 API 연동 (쿠팡/롯데온/스마트스토어)
104
- ◯ crawling — Playwright 기반 크롤링·브라우저 자동화
105
- ◉ ai-verified-skill-publisher — AI 검증 스킬 업로드·라이브러리화
106
- ...
107
-
108
- 활성화할 sub-agent CLI (Space=토글, a=전체, n=해제, Enter=확정)
109
- ❯ ◉ claude — 🟢 설치됨 · Anthropic Claude Code CLI
110
- ◯ codex — ⚪ 미설치 · OpenAI Codex CLI (격리 sandbox)
111
- ◉ gemini — 🟢 설치됨 · Google Gemini CLI
112
- ◯ copilot — ⚪ 미설치 · GitHub Copilot CLI
45
+ .harness/
46
+ ├── plan.md ← 무엇을 할 것인가
47
+ ├── progress-tracker.md ← 무엇을 했는가 (증거 포함)
48
+ ├── decisions.md ← 왜 그렇게 했는가
49
+ └── session-handoff.md ← 다음 세션에 무엇을 전달하는가
113
50
  ```
114
51
 
115
- 활성화 후 미설치 CLI는 **자동 설치 시도**:
52
+ 이 4개 파일은 사용자 메모리로 보호됩니다. leerness가 자동 업데이트하지만, 사용자/AI가 직접 편집한 내용은 **항상 보존**됩니다.
53
+
54
+ ### 2. AI가 작업할 때마다 자동 검증
55
+
116
56
  ```
117
- ⚠ codex이(가) 설치되어 있지 않습니다.
118
- 설치 명령: npm i -g @openai/codex
119
- 지금 자동 설치를 시도할까요? (y/N): y
120
- ▶ 실행: npm i -g @openai/codex
121
- 🟢 codex 설치 확인 (v0.x.x)
57
+ AI: "T-0042 API 호출 구현 완료했습니다"
58
+ ↓
59
+ leerness verify-claim T-0042 --run-tests
60
+ ↓
61
+ evidence 파일 확인 → 테스트 실제 실행 → URL 코드 매칭
62
+ ↓
63
+ ✓ 검증 통과 또는 ✗ "코드에 fetch 호출 흔적 없음 (confidence 0.85)"
122
64
  ```
123
65
 
124
- **스킵 옵션** (CI/자동화):
125
- - `--yes` — 모든 prompt 스킵 (기본값 사용)
126
- - `--no-interactive-select` 또는 `LEERNESS_NO_INTERACTIVE=1` — 구식 숫자 prompt
127
- - `LEERNESS_NO_PROMPT=1` — readline prompt 강제 비활성
66
+ ### 3. 워크스페이스 전체에서 중복·관계 추적
128
67
 
129
- ---
68
+ ```bash
69
+ leerness reuse-map --all-apps --strict-elements
70
+ → escapeHtml in 3 projects (project-a:42, project-b:18, project-c:103)
71
+ → useCart depends on AuthContext (cycle detected)
72
+ ```
130
73
 
131
- ## 🚀 60초 시작
74
+ ### 4. 다중 AI 에이전트 안전 협업
132
75
 
133
76
  ```bash
134
- # 1) 신규 프로젝트
135
- npx leerness@latest init . --language ko
136
-
137
- # 2) 매일 사용
138
- npx leerness handoff . # 컨텍스트 적재
139
- npx leerness audit . # 일관성 감사
140
- npx leerness verify-claim T-0001 --run-tests # 증거 자동 검증
141
- npx leerness session close . # 세션 마감 + 핸드오프
142
-
143
- # 3) 워크스페이스 (멀티 프로젝트)
144
- npx leerness handoff --all-apps --since 24h # 최근 24h 변경 통합 뷰
145
- npx leerness reuse-map --all-apps # 중복 함수 감지
146
-
147
- # 4) 외부 AI CLI 오케스트레이션
148
- npx leerness setup-agents # 인터랙티브 CLI 활성화
149
- npx leerness agents list # ready 상태표
150
- npx leerness agents dispatch "X 해줘" --to gemini # 명령 자동 생성
77
+ leerness agents list # claude/codex/gemini/copilot 상태
78
+ leerness agents dispatch "<task>" --to gemini --write # 권장 플래그 자동 첨부
79
+ leerness agents bench "<task>" # 3 CLI 동시 호출 + 시간/품질 비교
80
+ leerness contract verify SPEC.md src/x.js # 사양 ↔ 구현 함수/필드 일치 검증
151
81
  ```
152
82
 
153
- ---
83
+ ### 5. 도구 drift 자동 감지 (1.9.37+)
154
84
 
155
- ## 📊 적용 효과 (실측)
85
+ 라운드가 길어지면 AI가 leerness를 "점점 안 쓰는" 현상을 자동 감지:
156
86
 
157
- 벤치마크: `leerness-bench` 28 프로젝트 / 124 task 기준.
87
+ ```bash
88
+ leerness drift check .
89
+ → 🔴 critical (100/200) — session close 4.6일 누락, task update 3.6일 stale
90
+ → 권장: leerness session close .
91
+ ```
158
92
 
159
- | 카테고리 | leerness | vanilla | 차이 |
160
- |---|---:|---:|---:|
161
- | 멀티에이전트 효율 | 100/100 | 3/100 | **+97** |
162
- | 검수 자동화 (verify-claim 1.5s vs 90s 수동) | 98/100 | 0/100 | **+98** |
163
- | 재사용 인식 (113 cap + 33 deps) | 100/100 | 0/100 | **+100** |
164
- | 워크스페이스 가시성 (1 명령 vs 112 명령) | 99/100 | 0/100 | **+99** |
165
- | 버그 자동 감지 (169 신호) | 100/100 | 0/100 | **+100** |
166
- | 컨텍스트 유지 (3 채널) | 100/100 | 0/100 | **+100** |
167
- | **종합** | **597/600 (99%)** | **3/600 (0.5%)** | **+594** |
93
+ → `handoff` 호출 시 inline 경고 자동, severe 시 `.harness/agent-reminders.md` 자동 생성.
168
94
 
169
95
  ---
170
96
 
171
- ## 🤖 외부 AI CLI 오케스트레이션 (1.9.30~34)
172
-
173
- claude/codex/gemini/copilot CLI들을 sub-agent로 활용. **자동 호출 금지** — 환경변수 활성화 + PATH 존재 시에만 ready.
97
+ ## 60초 시작
174
98
 
175
- ### 활성화 (1.9.32+ 권장: 인터랙티브)
176
99
  ```bash
177
- leerness setup-agents . # 방향키/스페이스로 선택 + 미설치 자동 설치 시도
178
- ```
100
+ # 1) 설치 + 초기화 (방향키/스페이스 인터랙티브)
101
+ npx leerness@latest init .
179
102
 
180
- ### 활성화 (수동 `.env`)
181
- ```bash
182
- LEERNESS_ENABLE_CLAUDE=1 # Anthropic Claude Code CLI
183
- LEERNESS_ENABLE_CODEX=1 # OpenAI Codex CLI (격리 sandbox)
184
- LEERNESS_ENABLE_GEMINI=1 # Google Gemini CLI (--yolo 워크스페이스 직접 수정 가능)
185
- LEERNESS_ENABLE_COPILOT=1 # GitHub Copilot CLI (gh copilot)
186
- ```
103
+ # 2) AI 세션 시작 — 컨텍스트 자동 적재
104
+ npx leerness handoff .
187
105
 
188
- ### 사용
189
- ```bash
190
- leerness agents list # 4 CLI 상태표
191
- leerness agents quota # provider별 사용량/한도 추정
192
- leerness agents dispatch "<task>" --to gemini # 명령 자동 생성 (실 호출 X)
106
+ # 3) AI 작업 끝 — 증거 자동 검증
107
+ npx leerness verify-claim T-0001 --run-tests
108
+
109
+ # 4) 세션 마감 — 다음 세션 인계
110
+ npx leerness session close .
193
111
  ```
194
112
 
195
- ### 자동 설치 명령 (setup-agents가 사용)
196
- | CLI | install 명령 | 안내 |
197
- |---|---|---|
198
- | claude | `npm i -g @anthropic-ai/claude-code` | https://docs.anthropic.com/en/docs/claude-code/setup |
199
- | codex | `npm i -g @openai/codex` | https://github.com/openai/codex |
200
- | gemini | `npm i -g @google/gemini-cli` | https://github.com/google-gemini/gemini-cli |
201
- | copilot | `gh extension install github/gh-copilot` | https://github.com/github/gh-copilot |
113
+ ---
202
114
 
203
- ### 멀티레벨 오케스트레이션 검증 (1.9.34 실측)
115
+ ## 적용시 효과 — 정량 데이터
204
116
 
205
- 메인 → Sub-agent → Sub-sub-agent (3단계 깊이) 동작 검증:
117
+ `leerness-bench` 28 프로젝트 124 task 측정 결과:
206
118
 
207
- | 항목 | 결과 |
208
- |---|---|
209
- | 단일 gemini 호출 | ✅ 15.6s (영문 번역 정상) |
210
- | 병렬 gemini ×2 | ✅ 24s (출력 분리 정상, quota retry 1회) |
211
- | 효율 (순차 3회 33s vs 병렬 3회 15s) | **2.2× 향상** (이론 3× 대비 60%) |
212
- | 검수 체인 (결과를 다시 평가) | ✅ "2" → "yes" 정상 |
213
- | 같은 파일 동시 쓰기 | ⚠ **last-writer-wins, 락 없음** |
214
-
215
- **결론**:
216
- - ✅ 3단계 오케스트레이션 동작
217
- - ✅ 독립 작업(번역/평가/리뷰) 2×+ 효율 향상
218
- - ⚠ **같은 리소스 동시 쓰기는 데이터 손실 위험** — 호출자가 파일 경로 격리 책임
219
- - ⚠ gemini quota 동시 호출 시 retry 발생 → 병렬 확장성 ~3개로 제한
220
-
221
- ### 정책
222
- - ❌ leerness는 외부 CLI를 자동 호출하지 않음 (사용자/메인이 명시적 실행)
223
- - ✅ `agents dispatch`는 명령 텍스트만 출력 → 사용자가 복사 실행
224
- - ✅ quota 여유 큰 CLI를 메인 에이전트가 우선 선택하도록 신호 제공
225
- - ⚠ `gemini --yolo`는 워크스페이스 파일 직접 수정 가능 (codex와 차이)
119
+ | 카테고리 | 적용 | 미적용 | 개선 |
120
+ |---|---:|---:|---:|
121
+ | 다중 에이전트 효율 | 100/100 | 3/100 | **+97** |
122
+ | 자동 검수 (verify-claim) | 98/100 | 0/100 | +98 |
123
+ | 재사용 인식 | 100/100 | 0/100 | +100 |
124
+ | 워크스페이스 가시성 | 99/100 | 0/100 | +99 |
125
+ | 자동 BUG 감지 | 100/100 | 0/100 | +100 |
126
+ | 컨텍스트 유지 | 100/100 | 0/100 | +100 |
127
+ | **종합** | **597/600 (99%)** | 3/600 (0.5%) | **+594** |
128
+
129
+ ### 실제 작업 시간 절감
130
+ - **수동 검수 90s → 자동 1.5s** (`verify-claim --run-tests`)
131
+ - **워크스페이스 28 프로젝트 1 명령** (vs 112 개별 명령)
132
+ - **컨텍스트 적재 500자** (`handoff --compact`, AI 토큰 비용 90% 절감)
133
+
134
+ ### 실제 BUG 자동 발견 사례
135
+ - **거짓 완료**: 5건 (모두 verify-claim에서 evidence 누락 감지)
136
+ - **사양 불일치**: rpg-replay에서 `tick.damage` vs `tick.amount` 필드명 충돌 자동 감지 (contract verify)
137
+ - **보안 위험**: `contract verify`가 require()로 임의 코드 실행 → 정적 분석으로 즉시 수정 (1.9.36)
138
+ - **drift**: 실 워크스페이스에서 4.6일 stale 자동 감지 → session close 1회로 70점 회복 (1.9.37/38)
226
139
 
227
140
  ---
228
141
 
229
- ## 🎭 페르소나 리뷰 (1.9.29)
230
-
231
- 도메인 페르소나를 sub-agent에 자동 부여 → 표면 리뷰 대비 **도메인 발견 3-4배**, 토큰 비용 ~3%.
142
+ ## 어떤 함정을 어떻게 막나요?
232
143
 
233
- ### 5종 내장 페르소나
234
- | ID | 역할 | 발견 깊이 |
144
+ | AI와 일할 때 함정 | leerness 도구 | 효과 |
235
145
  |---|---|---|
236
- | `security` | 10년차 보안 엔지니어 (OWASP/CWE/한국 개인정보보호법) | CWE 매핑 + 실 페이로드 |
237
- | `performance` | V8 엔진 내부 전문가 | Hot path Top 5 + RPS 추정 |
238
- | `ux` | 한국어 UX 라이터 + DX 컨설턴트 | Before/After 메시지 5건 |
239
- | `testing` | TDD + property-based 테스트 엔지니어 | 누락 테스트 + property 후보 |
240
- | `docs` | 한국어 기술 문서 작성자 | 60초 시작 가능성 평가 |
241
-
242
- ```bash
243
- leerness review src/api.js --persona security,performance,ux
244
- leerness persona list
245
- leerness persona add my-domain # 사용자 정의 페르소나
246
- ```
146
+ | "완료했습니다"인데 코드 변경이 없음 | `verify-claim --run-tests` | 증거 파일 + 테스트 실제 실행 검증 |
147
+ | "API 호출 완료"인데 URL 코드 없음 | `optimism-check` | 10 카테고리 패턴 + URL 매핑 + 신뢰도 점수 |
148
+ | 같은 함수를 여러 프로젝트에 중복 | `reuse-map --strict-elements` | 함수명 fuzzy 중복 감지 |
149
+ | 다음 세션이 컨텍스트 잃음 | `handoff` 3채널 자동 적재 | 500자 압축 (`--compact`) |
150
+ | 표면적 코드 리뷰 (도메인 깊이 부족) | `review --persona security,performance,ux` | 도메인 sub-agent 자동 부여 |
151
+ | 외부 AI CLI 자동 호출 위험 | `agents list/dispatch/quota` | 환경변수 활성화 + 명시적 분배 |
152
+ | npx 캐시로 옛 버전 실행 | `_warnIfStale` 자동 (1.9.33+) | npm latest 자동 비교 + 경고 |
153
+ | 멀티 sub-agent 파일 충돌 | `agents dispatch` 안내 + 경로 격리 | last-writer-wins 위험 사전 차단 |
154
+ | sub-agent마다 사양 해석 다름 | **`contract verify`** | 명세 ↔ 구현 함수/필드 자동 검사 |
155
+ | 신규 모듈 capability 미등록 | **`reuse autodetect`** | `module.exports` 정적 분석 + 자동 등록 |
156
+ | 라운드 길어지며 메인이 leerness 잊음 | **`drift check`** + `agent-reminders.md` 자동 | 4 신호 + 자동 reminder + 학습 |
157
+ | TodoWrite ↔ progress-tracker 분리 | **`task sync --from`** (1.9.38) | TodoWrite JSON 자동 import |
247
158
 
248
159
  ---
249
160
 
250
- ## 🛠 핵심 명령 매트릭스
161
+ ## 핵심 명령
251
162
 
252
- ### 일상 사용
163
+ ### 일상
253
164
  ```bash
254
- leerness init [path] [--language auto|ko|en] # 신규 프로젝트 (1.9.34 인터랙티브)
255
- leerness handoff [path] [--compact] [--all-apps] [--since 24h]
256
- leerness audit [path] # 일관성 감사
257
- leerness verify-claim T-XXX --run-tests # 증거 + 실 테스트
258
- leerness optimism-check T-XXX # 낙관적 표시 감지
259
- leerness gate [path] # verify+audit+scan+encoding+lazy
260
- leerness session close [path] # 세션 마감
165
+ leerness init [path] [--language ko|en] # 신규 프로젝트 (방향키 multi-select)
166
+ leerness handoff [path] [--compact] # 컨텍스트 적재 (drift 자동 경고)
167
+ leerness verify-claim T-XXX --run-tests # 증거 + 실 테스트
168
+ leerness optimism-check T-XXX # 낙관적 표시 감지
169
+ leerness audit [path] [--fix] # 일관성 감사 (--fix: 자동 갱신)
170
+ leerness session close [path] # 세션 마감
171
+ leerness drift check [path] # drift 점수 + 4단계 레벨
172
+ leerness usage stats [path] # 명령별 누적 카운터
261
173
  ```
262
174
 
263
- ### 워크스페이스
175
+ ### 워크스페이스 (멀티 프로젝트)
264
176
  ```bash
265
- leerness handoff --all-apps # 전 프로젝트 통합 뷰
266
- leerness reuse-map --all-apps --strict-elements # 함수 중복 감지
267
- leerness retro --all-apps --days 7 # 회고
268
- leerness insights --all-apps # 누적 통계
269
- leerness brainstorm "키워드" --all-apps --include-code
270
- leerness deps <capability> --run-tests # 영향 추적 + 자동 회귀
177
+ leerness handoff --all-apps # 전 프로젝트 통합 뷰
178
+ leerness reuse-map --all-apps --strict-elements
179
+ leerness reuse autodetect [--apply] # src/bin/lib/app 정적 스캔 + 등록
180
+ leerness contract verify <spec> <impl> # 명세 ↔ 구현 검증
181
+ leerness deps <capability> --run-tests # 영향 추적 + 자동 회귀
182
+ leerness retro --all-apps --days 7 # 회고
183
+ leerness insights --all-apps # 통계
184
+ leerness task sync --from <todo.json> # TodoWrite import
271
185
  ```
272
186
 
273
- ### 외부 AI CLI · 멀티 에이전트 (1.9.30~35)
187
+ ### 외부 AI CLI · 멀티 에이전트
274
188
  ```bash
275
- leerness setup-agents . # 인터랙티브 활성화 + 자동 설치
276
- leerness agents list # 4 CLI 상태표
277
- leerness agents quota # 사용량 추정
278
- leerness agents dispatch "<task>" --to gemini --write # 1.9.36 --write: --yolo 자동 첨부
279
- leerness agents bench "<task>" [--timeout N] # 1.9.36 ready CLI 모두 병렬 호출 + 비교표
280
- leerness contract verify <spec.md> <impl.js> # 1.9.35/36 명세 ↔ 구현 일치 검사 (정적 분석)
281
- leerness reuse autodetect [path] [--apply] # 1.9.35/36 capability 자동 등록 (src/bin/lib/app)
282
- leerness audit . --fix # 1.9.35 누락 메타 자동 갱신
189
+ leerness setup-agents # 인터랙티브 활성화 + 자동 설치
190
+ leerness agents list / check / quota # 상태/한도
191
+ leerness agents dispatch "<task>" --to gemini --write
192
+ leerness agents bench "<task>" # 3 CLI 동시 호출 + 비교표
283
193
  ```
284
194
 
285
- ### 페르소나·리뷰 (1.9.29)
195
+ ### 페르소나·리뷰
286
196
  ```bash
287
- leerness persona list|show <id>|add <id>
197
+ leerness persona list / show <id> / add <id>
288
198
  leerness review <file> --persona security,performance,ux
289
199
  ```
290
200
 
291
- ### 데이터 위생
201
+ ### 보안·인코딩
292
202
  ```bash
293
203
  leerness scan secrets . # AWS/GitHub/OpenAI/Anthropic/Google/Slack/PEM
294
204
  leerness encoding check . # BOM/UTF-16/한글 라운드트립
295
205
  leerness lazy detect . # 증거 없는 done · 빈 handoff · 추적 없는 TODO
206
+ leerness gate [path] # verify + audit + scan + encoding + lazy 통합
296
207
  ```
297
208
 
298
209
  ### 버전 관리
299
210
  ```bash
300
211
  leerness update --check # 24h 캐시로 새 버전 감지
301
212
  leerness update --yes # 자동 마이그레이션 + 검증
302
- leerness update --from <tgz> # 오프라인/사내 미러
303
213
  ```
304
214
 
305
215
  ---
306
216
 
307
- ## 🌐 환경변수
217
+ ## 사용 시나리오
308
218
 
309
- | 변수 | 효과 |
310
- |---|---|
311
- | `LEERNESS_OFFLINE=1` | npm 호출 스킵 (오프라인) |
312
- | `LEERNESS_NPM_TOKEN` | release publish용 |
313
- | `LEERNESS_GITHUB_TOKEN` | gh release용 |
314
- | `LEERNESS_OLLAMA_BASE_URL` | 1.9.22 — orchestrate opt-in 활성 |
315
- | `LEERNESS_OLLAMA_MODEL` | orchestrate 기본 모델 |
316
- | `LEERNESS_ENABLE_CLAUDE` | 1.9.30 — agents dispatch Claude 활성 (=1) |
317
- | `LEERNESS_ENABLE_CODEX` | 1.9.30 — Codex 활성 (=1) |
318
- | `LEERNESS_ENABLE_GEMINI` | 1.9.30 — Gemini 활성 (=1) |
319
- | `LEERNESS_ENABLE_COPILOT` | 1.9.30 — gh copilot 활성 (=1) |
320
- | `LEERNESS_NO_BANNER` | 1.9.32 — init 배너 스킵 (=1) |
321
- | `LEERNESS_NO_PROMPT` | 1.9.32 — readline prompt 강제 비활성 (=1) |
322
- | `LEERNESS_NO_STALE_CHECK` | 1.9.33 — npx 캐시 옛 버전 경고 끄기 (=1) |
323
- | `LEERNESS_NO_INTERACTIVE` | 1.9.34 — 방향키 multi-select 비활성, 숫자 prompt 폴백 (=1) |
219
+ ### 시나리오 1: AI에게 작업 시키고 거짓 완료 검증
220
+ ```bash
221
+ # AI에게 작업 지시 후
222
+ leerness verify-claim T-0042 --run-tests --strict-claims
223
+ # → evidence 파일 존재 + 실제 npm test 실행 + 낙관적 표시 자동 감지
224
+ # → 거짓이면 exit 1, 진짜면 진행
225
+ ```
226
+
227
+ ### 시나리오 2: 멀티 AI 에이전트 협업
228
+ ```bash
229
+ # 1) 외부 CLI 활성화
230
+ leerness setup-agents . # 방향키로 claude/codex/gemini 선택
231
+
232
+ # 2) 같은 task를 3 CLI에 동시 호출 → 비교
233
+ leerness agents bench "rpg-core/combat.js useSkill 함수 한 줄 요약"
234
+ # | claude | 7s | "..." | ← 가장 빠름
235
+ # | codex | 21s | "..." | ← 가장 상세
236
+ # | gemini | 19s | "..." | ← 중간
237
+
238
+ # 3) 작업 유형별 최적 CLI에 분배
239
+ leerness agents dispatch "파일 생성" --to gemini --write
240
+ # → --yolo 자동 첨부, 안전 규칙 안내
241
+ ```
242
+
243
+ ### 시나리오 3: 라운드가 길어지며 drift 감지
244
+ ```bash
245
+ # 며칠 후 새 세션 시작
246
+ leerness handoff .
247
+ # ⚠ leerness drift 감지 — 메타파일이 stale합니다
248
+ # session-handoff.md: 4.6일 stale
249
+ # → 권장: leerness session close .
250
+
251
+ # 권장 명령 1회 실행으로 회복
252
+ leerness session close .
253
+ # 🔴 critical (100/200) → 🟠 attention (30/200)
254
+ ```
255
+
256
+ ### 시나리오 4: TodoWrite ↔ leerness 동기화
257
+ ```bash
258
+ # Claude Code의 TodoWrite를 JSON으로 export 후
259
+ leerness task sync --from /path/to/todos.json
260
+ # → completed → done, in_progress → in-progress, pending → planned로 자동 mirror
261
+ ```
324
262
 
325
263
  ---
326
264
 
327
- ## 📁 디렉토리 구조
265
+ ## 디렉토리 구조
328
266
 
329
267
  ```
330
268
  .harness/
@@ -338,94 +276,46 @@ leerness update --from <tgz> # 오프라인/사내 미러
338
276
  ├── skill-index.md · skills/<id>/ · templates/
339
277
  ├── personas/<id>.md (1.9.29+, 사용자 정의 페르소나)
340
278
  ├── reviews/ (1.9.29+, 페르소나 리뷰 결과)
341
- └── cache/update-check.json (1.9.33+, 24h npm latest 캐시)
342
-
343
- .claude/ (commands · skills · settings.local.json) · .cursor/rules/leerness.mdc
344
- .github/copilot-instructions.md · AGENTS.md · CLAUDE.md
279
+ ├── cache/
280
+ │ ├── update-check.json (1.9.33+)
281
+ │ └── usage-stats.json (1.9.38+ 명령 카운터)
282
+ └── agent-reminders.md (1.9.38+, drift critical 시 자동 생성)
283
+
284
+ .claude/ (commands · skills · settings.local.json)
285
+ .cursor/rules/leerness.mdc
286
+ .github/copilot-instructions.md
287
+ AGENTS.md · CLAUDE.md
345
288
  ```
346
289
 
347
290
  ---
348
291
 
349
- ## 🛡 비파괴 마이그레이션 정책
350
-
351
- - 모든 변경 전 `.harness/archive/leerness-<version>-<timestamp>/` 자동 백업
352
- - 사용자 메모리 (`plan`, `progress`, `decisions`, `task-log`, `architecture`, `reuse-map` 등) **항상 보존**
353
- - 관리 인스트럭션은 새 템플릿으로 머지하되 이전 내용을 `<!-- leerness:migration-preserved -->` 블록에 보존
354
- - 결과 보고: `.harness/migration-report.md`
355
-
356
- ---
292
+ ## 환경변수
357
293
 
358
- ## 🔄 자동 버전 감지/업데이트
359
-
360
- `init`/`migrate` 시 `.claude/settings.local.json`의 SessionStart hook에 `update --check` 자동 등록. 24시간 캐시로 npm 호출 폭주 방지.
361
-
362
- | 명령 | 동작 |
294
+ | 변수 | 효과 |
363
295
  |---|---|
364
- | `update --check` | `HARNESS_VERSION` ↔ `npm view leerness version` 비교 |
365
- | `update --yes` | 백업 → 마이그레이션 → verify/audit → 로그 누적 |
366
- | `update --from <tarball>` | 로컬/오프라인/사내 미러 |
367
-
368
- ---
369
-
370
- ## 🧪 자동 검수 도구 매트릭스
371
-
372
- | 도구 | 검출 | 추가 |
373
- |---|---|---|
374
- | `verify-claim T-XXX` | evidence 파일 존재 + 테스트 카운트 ≥ 주장 | 1.9.18 |
375
- | `verify-claim --run-tests` | + 실제 `npm test` 실행 + pass 파싱 | 1.9.19/20 |
376
- | `verify-claim --strict-claims` | + 낙관적 표시 검사 통합 | 1.9.26 |
377
- | `optimism-check T-XXX` | 10 카테고리 + URL 매핑 + 신뢰도 점수 | 1.9.26/27 |
378
- | `deps <capability>` | depends-on 역추적 + 자동 회귀 sweep | 1.9.24 |
379
- | `memory search --include-code` | 소스 코드 본문 인덱싱/검색 | 1.9.25 |
380
- | `register-pending` | 다중 세션 즉시 신호 | 1.9.25 |
381
- | `reuse-map --strict-elements` | 함수명 동일 / capability 다른 잠재 중복 | 1.9.18 |
382
- | `handoff --since 24h` | 최근 변경 T-row 자동 강조 | 1.9.18 |
383
- | `verify-code --bench` | `scripts.bench` 자동 실행 + 누적 | 1.9.20 |
384
- | `lazy detect` | 증거 없는 done · 빈 handoff · 추적 없는 TODO | 1.9.7 |
385
- | `orchestrate --agents N` | 다중 LLM 동시 호출 (opt-in) | 1.9.22 |
386
- | `handoff --compact` | LLM 시스템 프롬프트용 압축 출력 | 1.9.22 |
387
- | `review --persona X` | 도메인별 sub-agent 자동 프롬프트 | 1.9.29 |
388
- | `persona list/show/add` | 페르소나 카탈로그 관리 | 1.9.29 |
389
- | `agents list/check` | 4 CLI 활성/설치 상태표 | 1.9.30 |
390
- | `agents dispatch --to X` | ready CLI에 대상 명령 자동 생성 | 1.9.30 |
391
- | `agents quota` | provider별 사용량/한도 추정 | 1.9.31 |
392
- | `setup-agents` | 인터랙티브 CLI 활성화 + 자동 설치 시도 | 1.9.32 |
393
- | `contract verify <spec> <impl>` | 명세 ↔ 구현 함수/필드 일치 자동 검사 | 1.9.35 |
394
- | `reuse autodetect [--apply]` | `module.exports` 스캔 → reuse-map 후보 등록 | 1.9.35 |
395
- | `audit --fix` | session-handoff/current-state 자동 갱신 | 1.9.35 |
396
- | `handoff` (init 부재 경고) | 신규 디렉토리에서 즉시 init 안내 | 1.9.35 |
397
- | `_warnIfStale` (자동) | npx 캐시 옛 버전 자동 경고 | 1.9.33 |
398
- | `_selectOne/_selectMany` | 방향키/Space 인터랙티브 multi-select | 1.9.34 |
296
+ | `LEERNESS_OFFLINE=1` | npm 호출 스킵 (오프라인) |
297
+ | `LEERNESS_OLLAMA_BASE_URL` | orchestrate opt-in (1.9.22+) |
298
+ | `LEERNESS_ENABLE_CLAUDE/CODEX/GEMINI/COPILOT` | 외부 CLI 활성화 (1.9.30+) |
299
+ | `LEERNESS_NO_BANNER` | ASCII 배너 스킵 (1.9.32+) |
300
+ | `LEERNESS_NO_PROMPT` | readline prompt 비활성 (1.9.32+) |
301
+ | `LEERNESS_NO_STALE_CHECK` | npx 옛 버전 경고 끄기 (1.9.33+) |
302
+ | `LEERNESS_NO_INTERACTIVE` | 방향키 multi-select 비활성 (1.9.34+) |
303
+ | `LEERNESS_NO_DRIFT_CHECK` | drift 자동 경고 끄기 (1.9.37+) |
399
304
 
400
305
  ---
401
306
 
402
- ## 🤝 Claude Code / Cursor / Copilot 통합
307
+ ## Claude Code / Cursor / Copilot 통합
403
308
 
404
309
  설치 시 자동 등록:
405
310
  - `.claude/commands/{handoff, session-close, audit, lazy-detect, update}.md`
406
311
  - `.claude/skills/leerness.md` (스킬 정의)
407
- - `.claude/settings.local.json` (SessionStart hook `update --check`)
408
- - `.cursor/rules/leerness.mdc`
409
- - `.github/copilot-instructions.md`
410
-
411
- ---
412
-
413
- ## 📦 스킬 라이브러리
414
-
415
- ```bash
416
- leerness skill list
417
- leerness skill info <id>
418
- leerness skill add <id>
419
- leerness skill learn <id> --doc <url> --command "..." --capability "..."
420
- leerness skill optimize <id> --before "..." --after "..."
421
- leerness skill consolidate
422
- ```
423
-
424
- **기본 카탈로그**: `feature-implementation`, `ai-verified-skill-publisher`, `open-meteo`, `static-site-builder`, `project-roadmap-generator`, `office`, `commerce-api`, `crawling`, `firebase`, `ads-analytics`, `appstore-review`.
312
+ - `.claude/settings.local.json` (SessionStart hook = `update --check`)
313
+ - `.cursor/rules/leerness.mdc` · `.github/copilot-instructions.md`
314
+ - `AGENTS.md` · `CLAUDE.md`
425
315
 
426
316
  ---
427
317
 
428
- ## 🔧 자연어 트리거 → 명령 자동 매핑
318
+ ## 자연어 트리거
429
319
 
430
320
  | 사용자 발화 | 자동 실행 |
431
321
  |---|---|
@@ -435,63 +325,80 @@ leerness skill consolidate
435
325
  | "X 관련 자료 / X 시작 전 검토" | `leerness brainstorm "X"` |
436
326
  | "매 X마다 Y를 해줘" | `leerness rule add "Y" --trigger every-X` |
437
327
  | "외부 CLI 설정" | `leerness setup-agents` |
328
+ | "drift 점검 / leerness를 잘 쓰고 있나?" | `leerness drift check` |
329
+
330
+ `AGENTS.md`에 자동 등록 — AI 에이전트가 자연어를 명령으로 변환.
331
+
332
+ ---
333
+
334
+ ## 설치 시 함정 주의
335
+
336
+ ### `@latest` 명시 권장
337
+ ```bash
338
+ # ❌ npx 캐시로 옛 버전 실행 가능
339
+ npx leerness init .
340
+
341
+ # ✅ 항상 최신 받음
342
+ npx leerness@latest init .
343
+
344
+ # ✅ 캐시 의심 시
345
+ npx --yes clear-npx-cache && npx --yes leerness@latest init .
346
+ ```
438
347
 
439
- `AGENTS.md`에 자동 등록 — Claude Code/Cursor가 이를 보고 자연어를 명령으로 변환.
348
+ 1.9.33+ 부터 `leerness init` 시 npm latest와 자동 비교 → 옛 버전 경고.
440
349
 
441
350
  ---
442
351
 
443
- ## ❓ FAQ
352
+ ## FAQ
444
353
 
445
- **Q. leerness가 내 코드를 변경하나요?**
446
- A. 사용자 메모리(plan/progress/decisions/architecture/reuse-map 등)는 **항상 보존**. 관리 인스트럭션은 머지 + preserved 블록 보존. 모든 변경 전 `.harness/archive/`에 자동 백업.
354
+ **Q. leerness가 코드를 변경하나요?**
355
+ A. 사용자 메모리(plan/progress/decisions 등)는 **항상 보존**. 관리 인스트럭션은 머지 + preserved 블록 보존. 모든 변경 전 `.harness/archive/`에 자동 백업.
447
356
 
448
- **Q. 로컬 LLM을 사용하지 않고 싶어요.**
449
- A. 기본 동작입니다. `LEERNESS_OLLAMA_BASE_URL` 미설정 시 LLM 호출 절대 발생 안 함. `orchestrate` 명령만 거부 (다른 명령은 LLM 없이 동작).
357
+ **Q. AI 에이전트 없이 사용 가능한가요?**
358
+ A. 네. 1인 개발자도 자기 자신의 작업 검증·기억·중복 감지에 활용 가능. `verify-claim` / `audit` / `reuse-map`은 모두 AI 무관.
450
359
 
451
360
  **Q. CI에서 사용 가능?**
452
- A. 네. `--json` (retro/insights/brainstorm/handoff/reuse-map/verify-claim) + exit code 통합. `--yes` + `LEERNESS_NO_PROMPT=1`로 비대화형 보장.
361
+ A. 네. 모든 명령이 exit code + `--json` 출력 + `--yes` 비대화형 지원. 임의 `LEERNESS_NO_*` env로 prompt 강제 비활성.
453
362
 
454
- **Q. 외부 AI CLI를 자동으로 호출하나요?**
455
- A. **아니요.** `agents dispatch`는 명령 텍스트만 출력합니다. 사용자/메인 에이전트가 명시적으로 실행해야 합니다.
363
+ **Q. 외부 AI CLI를 자동 호출하나요?**
364
+ A. **절대 아니요.** `agents dispatch`는 명령 텍스트만 생성합니다. 사용자/메인이 명시적으로 spawn.
456
365
 
457
- **Q. multi-select가 SSH/tmux에서 안 보여요.**
458
- A. 256색 ANSI를 지원하지 않는 환경입니다. `LEERNESS_NO_INTERACTIVE=1` 또는 `--no-interactive-select`로 구식 숫자 prompt를 사용하세요.
366
+ **Q. 멀티 언어 프로젝트는?**
367
+ A. 영어 인스트럭션 옵션 (`--language en`). 단 도구 출력 메시지/안내는 한국어가 풍부합니다.
459
368
 
460
369
  ---
461
370
 
462
- ## 🧪 E2E
371
+ ## E2E
463
372
 
464
373
  ```bash
465
374
  npm test # = node ./scripts/e2e.js
466
375
  ```
467
376
 
468
- **161/161 시나리오** 통과 (1.9.7~1.9.35 회귀 + 신규 검증).
377
+ **174/174 시나리오** 통과 (1.9.7~1.9.38 회귀 + 신규 검증).
469
378
 
470
379
  ---
471
380
 
472
- ## 📜 변경 이력 (최근)
473
-
474
- - **1.9.36** — 외부 AI CLI 오케스트레이션 강화: `agents bench` (3 CLI 동시 비교) + `dispatch --write` 자동 권장 플래그 + 작업 유형 키워드 추천. stress test에서 발견한 `contract verify` require() side-effect (보안 위험 + 25× 속도 회복) 즉시 수정.
475
- - **1.9.35** — 파이프라인 메타-감사에서 도출된 5개 개선 통합: `contract verify` · `reuse autodetect` · `audit --fix` · `handoff` init 부재 경고 · `agents dispatch` 안전 규칙 안내.
476
- - **1.9.34** — 방향키/스페이스 인터랙티브 multi-select (`_selectOne`/`_selectMany`) + 256색 그라데이션 배너 + 3단계 sub-agent 오케스트레이션 검증 (2.2× 효율 실측).
477
- - **1.9.33** — `_warnIfStale()` — `npx leerness init` 시 옛 버전 자동 경고 + 해결 안내.
478
- - **1.9.32** — ASCII 배너 + `setup-agents` 인터랙티브 설정 + 미설치 CLI 자동 설치 시도.
479
- - **1.9.31** — `leerness agents quota` (provider별 사용량/한도 추정).
480
- - **1.9.30** — 외부 AI CLI 오케스트레이션 (claude/codex/gemini/copilot) + 환경변수 활성화 정책.
481
- - **1.9.29** — 페르소나 시스템 (5종 내장) + `leerness review --persona` (도메인 깊이 3-4배).
482
- - **1.9.28** — 카카오페이/네이버페이 패턴 + confidence floor 0.15.
483
- - **1.9.27** — `optimism-check` 강화: 10 카테고리 + URL/메서드 매핑 + 신뢰도 점수.
484
- - **1.9.26** — `optimism-check <T-ID>`, `verify-claim --strict-claims`.
485
- - **1.9.25** — `--include-code` (소스 코드 인덱싱), `register-pending` (다중 세션).
486
- - **1.9.24** — `deps <capability>` (depends-on 역추적 + 자동 회귀).
487
- - **1.9.22** — Ollama opt-in 통합 (`orchestrate --agents N`), `handoff --compact`, `llm-bench record`.
488
- - **1.9.18** — `--since`, `--strict-elements`, `depends-on` 그래프, `verify-claim`.
489
- - **1.9.17** — `handoff/reuse-map --all-apps` 워크스페이스 모드.
381
+ ## 변경 이력 (최근)
382
+
383
+ - **1.9.38** — drift 자동 reminder (`agent-reminders.md`) · `usage stats` 명령 · `task sync --from <todo.json>` · drift 임계 학습 (skip ≥5 → 임계 완화).
384
+ - **1.9.37** — `leerness drift check` (4 신호 + 4단계 레벨) — 라운드 길어지며 메인이 leerness 잊는 현상 자동 감지.
385
+ - **1.9.36** — `agents bench` (3 CLI 동시 비교) · `dispatch --write` (CLI별 권장 플래그) · 작업 유형 추천 · `contract verify` require() side-effect 25× 속도 회복.
386
+ - **1.9.35** — `contract verify` · `reuse autodetect` · `audit --fix` · `handoff` init 부재 경고 · `agents dispatch` 안전 규칙.
387
+ - **1.9.34** — 방향키/스페이스 인터랙티브 multi-select · 256색 그라데이션 배너 · 3단계 sub-agent 오케스트레이션 검증 (2.2× 효율).
388
+ - **1.9.33** — npx 캐시 옛 버전 자동 경고.
389
+ - **1.9.32** — ASCII 배너 · `setup-agents` 인터랙티브 + 자동 설치.
390
+ - **1.9.31** — `agents quota` (provider별 사용량 추정).
391
+ - **1.9.30** — 외부 AI CLI 오케스트레이션 (claude/codex/gemini/copilot).
392
+ - **1.9.29** — 페르소나 리뷰 (5종 내장).
393
+ - **1.9.24** — `deps <capability>` 영향 추적 + 자동 회귀.
394
+ - **1.9.22** — Ollama opt-in · `handoff --compact` · `llm-bench`.
395
+ - **1.9.18** — `verify-claim` · `--strict-elements` · depends-on 그래프.
396
+ - **1.9.17** — `--all-apps` 워크스페이스 모드.
490
397
  - ... (전체 [CHANGELOG.md](CHANGELOG.md) 참조)
491
398
 
492
399
  ---
493
400
 
494
- ## 🤝 기여
401
+ ## 기여
495
402
 
496
403
  - **이슈**: https://github.com/gugu9999gu/leerness/issues
497
404
  - **PR**: e2e 통과 + 한국어 주석 + UTF-8 BOM 없음
@@ -502,5 +409,5 @@ npm test # = node ./scripts/e2e.js
502
409
 
503
410
  MIT — © leerness contributors
504
411
 
505
- > **AI 에이전트를 잘 다루는 도구가 되도록 설계되었습니다.**
506
- > 사용자 동의 없이 자동으로 외부 LLM/API/CLI를 호출하지 않습니다.
412
+ > **AI 에이전트가 신뢰할 수 있게 일하도록 만드는 도구.**
413
+ > 사용자 동의 없이 외부 LLM/API/CLI를 자동 호출하지 않습니다.