leerness 1.17.0 → 1.19.0

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 (10) hide show
  1. package/CHANGELOG.md +172 -0
  2. package/README.ko.md +187 -0
  3. package/README.md +50 -134
  4. package/SECURITY.md +66 -56
  5. package/bin/leerness.js +417 -84
  6. package/lib/audit.js +336 -322
  7. package/lib/pure-utils.js +1 -1
  8. package/lib/session-close.js +17 -1
  9. package/package.json +1 -1
  10. package/scripts/e2e.js +15 -13
package/README.md CHANGED
@@ -9,184 +9,100 @@
9
9
  ╚══════╝╚══════╝╚══════╝╚═╝ ╚═╝╚═╝ ╚═══╝╚══════╝╚══════╝
10
10
  ```
11
11
 
12
- > **AI 코딩 에이전트를 위한 운영 레이어(operating layer).** 코드를 대신 쓰는 도구가 아니라, AI 에이전트의 **기억·인수인계·검증·감사·보안 가드**를 프로젝트에 영속화하는 CLI + MCP 서버입니다.
12
+ > **The AI-coding operations layer that makes "done" require evidence — for any language, any AI agent.**
13
+ > leerness does not write code. It gives your AI agent persistent memory, verified completion, and clean handoffs — stored inside your repo as plain files, exposed via CLI + MCP.
13
14
 
14
- [![npm](https://img.shields.io/npm/v/leerness)](https://www.npmjs.com/package/leerness) · ![MCP tools](https://img.shields.io/badge/MCP--tools-85-blue) · **런타임 의존성 0** · **install-script 0** · offline-first · Node ≥ 18 · MIT
15
+ [![npm](https://img.shields.io/npm/v/leerness)](https://www.npmjs.com/package/leerness) · ![MCP tools](https://img.shields.io/badge/MCP--tools-85-blue) · **0 runtime deps** · **0 install scripts** · offline-first · Node ≥ 18 · MIT
15
16
 
16
- > 이 문서는 **외부 다중 모델(Codex / Claude Sonnet / Claude Opus)이 README 를 보지 않고 leerness 를 직접 설치·실행·소스 분석한 객관 리뷰**를 바탕으로 재구성되었습니다. 매 릴리스마다 자동 갱신됩니다.
17
+ **🇰🇷 한국어 전문: [README.ko.md](./README.ko.md)**
17
18
 
18
19
  ---
19
20
 
20
- ## leerness가 뭔가요?
21
-
22
- AI 코딩 에이전트(Claude Code, Cursor, Codex, Aider, Goose 등)는 코드를 잘 쓰지만 세 가지 약점이 있습니다.
23
-
24
- 1. **기억하지 못합니다** — 세션이 바뀌면 현재 상태·결정·다음 작업을 잊습니다.
25
- 2. **거짓 완료를 선언합니다** — 증거(파일·테스트·로그) 없이 "완료했습니다"라고 말합니다.
26
- 3. **표준이 없습니다** — 여러 에이전트 간 인수인계, 보안/인코딩 점검, 드리프트 관리가 제각각입니다.
27
-
28
- leerness는 이 문제들을 해결하는 **외부 운영 substrate**입니다. 어떤 에이전트 위에도 얹어, 프로젝트의 상태를 `.harness/` 파일로 영속화하고 CLI · MCP 도구로 노출합니다. **leerness 자체는 LLM을 호출하거나 코드를 실행하지 않습니다.**
29
-
30
- ---
31
-
32
- ## 해결하는 문제
33
-
34
- | 문제 | leerness의 해법 |
35
- |---|---|
36
- | 세션 간 맥락·결정·다음 작업 유실 | `task`/`decision`/`lesson`/`plan`/`rule` 메모리를 영속화하고, 세션 시작 시 `handoff` 1콜로 회수 |
37
- | 증거 없는 "완료" 주장 | `verify-claim --require-evidence`, `lazy detect`, anti-lazy 정책으로 차단 |
38
- | Claude → Codex → Cursor 교체 시 맥락 소실 | 표준 세션 워크플로(handoff → 작업 → session close)로 에이전트 독립 인수인계 |
39
- | 하드코딩 시크릿 · 인코딩 깨짐(BOM/CP949) | `scan secrets`, `encoding check` 자동 감지 (CI 게이트) |
40
- | 워크스페이스 노화(drift)를 에이전트가 모름 | `drift check [--auto-fix]` 점수화 + 자동 회복 |
41
- | 명세 ↔ 구현 불일치 | `contract verify spec.md impl.js` 함수/필드 일치 검사 |
42
- | 여러 AI CLI의 역할/분배 표준 부재 | `agents`/`roles`/`team` 오케스트레이션(기본 opt-in, dispatch는 실행이 아닌 명령 생성) |
43
-
44
- ---
45
-
46
- ## 빠른 시작
21
+ ## Try it in 30 seconds
47
22
 
48
23
  ```bash
49
- # 설치 (런타임 의존성 0 — 추가 패키지 없음)
50
- npm install -g leerness
51
-
52
- # 프로젝트 초기화 (.harness/ 거버넌스 문서 + .claude/.cursor/.github 어댑터 생성)
53
- leerness init .
54
-
55
- # 세션 시작 — 이전 맥락/기억/다음 작업을 1콜로 회수
56
- leerness handoff .
57
-
58
- # ... 에이전트가 작업 ...
59
- leerness task add "사용자 인증 API 구현"
60
- leerness gate . # verify + audit + scan secrets + encoding + lazy 통합 게이트
61
-
62
- # 세션 종료 — 마감 통계 + 다음 라운드 추천 + 인수인계 문서 자동 생성
63
- leerness session close .
24
+ npx -y leerness init . --yes # adds .harness/ memory + guard files to your project
25
+ npx leerness handoff . # everything your AI should know right now, in one call
64
26
  ```
65
27
 
66
- CLAUDE.md / AGENTS.md 에 `세션 시작 시 leerness handoff .`, `종료 전 leerness session close .` 지침을 추가하면 에이전트가 자동으로 호출합니다.
67
-
68
- ---
69
-
70
- ## 거짓 완료 차단 — 핵심 차별점
71
-
72
- 세 모델의 블라인드 리뷰가 공통으로 꼽은 leerness의 핵심 가치입니다. AI 에이전트가 가장 자주 하는 거짓말 "다 했어요"를, leerness는 **완료 주장을 실제 코드와 대조**해 검증합니다.
28
+ Your project now has agent-independent memory. To see the flagship feature — catching a false "done" claim:
73
29
 
74
30
  ```bash
75
- # 에이전트가 "결제 API 연동 완료"라고 주장하지만 코드엔 호출 흔적이 없으면:
76
- leerness verify-claim T-0001 --require-evidence
77
- # ⚠ FAIL (낙관 1) · [Payment] 결제: evidence에 주장 있으나 코드에 호출 흔적 없음 → exit 1
31
+ npx leerness task add "Implement payment API"
32
+ npx leerness task update T-0001 --status done --evidence "payment.js done, 5 tests passed"
33
+ npx leerness verify-claim T-0001 # exit 1 — payment.js does not exist, no tests ran. Claim rejected.
78
34
  ```
79
35
 
80
- - `optimism-check` · `verify-claim` — evidence의 도메인 주장(API·DB·결제·이메일·큐·캐시·알림·스토리지 등 10종)을 실제 소스 호출과 대조. **JavaScript뿐 아니라 Python·Ruby·Go·C#·Java·PHP·Rust 구현도 인식**합니다(1.13).
81
- - `lazy detect` — 증거 없는 done, 빈 handoff, 테스트 미실행, 미추적 TODO를 탐지.
82
- - 정직한 완료는 통과하고 가짜 완료만 exit 1로 차단 — `gate` 또는 CI에 그대로 연결됩니다.
36
+ Write the real file with a real test and the same command passes. That is the whole idea: **"done" must match reality.**
83
37
 
84
- ---
85
-
86
- ## 핵심 개념 — 5계층
87
-
88
- - **기억(Memory)** — `task`/`plan`/`decision`/`lesson`/`rule`/`feature`(그래프). canonical JSON 을 단일 진실소스로 저장하고 마크다운은 projection. archive/restore 지원.
89
- - **인수인계(Handoff)** — `handoff`(세션 시작 컨텍스트), `session close`(마감 보고). 에이전트 교체에도 맥락 보존.
90
- - **검증(Verification)** — `verify-claim`(증거 강제), `contract verify`(명세↔구현), `verify-code`(테스트/빌드 실행 + 증거 기록).
91
- - **감사(Audit)** — `scan secrets`, `encoding check`, `lazy detect`, `drift check`, `audit`, 그리고 이를 묶는 `gate`.
92
- - **정책/보안(Policy)** — 8단계 권한 등급 enforce, 외부 에이전트 opt-in, 자연어 영구 룰(`rule add ... --trigger`).
38
+ > Want a smaller footprint? `leerness init . --minimal` installs only the core memory + verification files instead of the full set.
93
39
 
94
40
  ---
95
41
 
96
- ## 명령 카테고리
42
+ ## No terminal? Let your AI run it
97
43
 
98
- - **초기화/진단**: `init` · `status` · `which` · `doctor` · `selftest` · `capabilities`
99
- - **메모리**: `task` · `plan` · `decision` · `lesson` · `rule` · `feature` · `memory status/search`
100
- - **인수인계/세션**: `handoff` · `session close` · `pulse` · `health`
101
- - **검증/감사**: `check` · `gate` · `audit` · `drift check` · `lazy detect` · `scan secrets` · `encoding check` · `verify-code` · `verify-claim` · `contract verify`
102
- - **외부 에이전트**: `agents list/check/dispatch` · `provider` · `roles` · `adapter`
103
- - **운영/확장**: `release` · `migrate` · `team` · `install-safety` · `route` · `review`(페르소나)
104
- - **브리지(opt-in)**: `web`(playwright) · `pc`(robotjs) · `lsp`
105
- - **MCP**: `mcp serve` — stdio JSON-RPC 서버로 85개 도구 노출
44
+ You never have to type a command yourself. Paste this into Claude Code, Cursor, Codex, or any coding agent:
106
45
 
107
- 전체 명령은 `leerness commands` 또는 `leerness --help` 로 확인하세요.
46
+ > Set up leerness in this project by running `npx -y leerness init . --yes`. From now on, run `leerness handoff .` at the start of every session, verify finished work with `leerness verify-claim`, and run `leerness session close .` before you finish.
108
47
 
109
- > **경로 규칙** — 대부분 명령은 `[path]` 위치 인자를 받습니다. `task`/`decision`/`lesson` 등 메모리 명령에 다른 폴더를 지정할 땐 `--path <dir>` 또는 `./dir` 형태를 쓰세요(맨 폴더 이름만 주면 현재 폴더로 처리됩니다). 출력은 한국어가 기본이며 `--language en` 으로 영어를 늘릴 수 있습니다(일부 메시지는 한국어 유지).
48
+ The agent installs and operates it for you — `leerness init` also writes the instructions into CLAUDE.md / AGENTS.md so future sessions pick them up automatically.
49
+
50
+ Prefer pure natural language? leerness ships an **MCP server with 85 tools** (`leerness mcp serve`). Connect it once to Claude Desktop / Claude Code and just ask: *"what was I working on?"*, *"did the AI actually finish T-0001?"*
110
51
 
111
52
  ---
112
53
 
113
- ## 대표 워크플로
54
+ ## Claude and Codex already have memory. Why leerness?
114
55
 
115
- **기본 세션 사이클**
116
- ```bash
117
- leerness handoff . # 이전 맥락 자동 로드
118
- leerness task add "API 응답 검증 로직 구현"
119
- leerness task update T-0001 --status in-progress --evidence "검증 함수 구현"
120
- leerness gate . # 배포 전 통합 품질 게이트
121
- leerness session close . # 마감 + 다음 에이전트 인수인계
122
- ```
123
-
124
- **보안·검증 게이트 (CI)**
125
- ```bash
126
- leerness scan secrets . # 커밋 대상 하드코딩 시크릿 → exit 1
127
- leerness contract verify spec.md src/api.js # 명세 함수/필드 누락 → exit 1
128
- leerness verify-claim T-0001 --require-evidence
129
- ```
56
+ Built-in harnesses remember what the AI **said**. leerness verifies what the AI **did** — and keeps working when you switch agents.
130
57
 
131
- **다중 에이전트 조율**
132
- ```bash
133
- leerness agents list # 설치된 외부 AI CLI 가용성
134
- leerness agents dispatch "코드 리뷰" --to codex # 실행 명령 생성(직접 실행은 사용자/메인 에이전트)
135
- ```
58
+ | | Built-in (CLAUDE.md, agent memory) | leerness |
59
+ |---|---|---|
60
+ | Memory | per-agent, free-form notes | structured tasks / decisions / lessons / rules — agent-independent files in your repo |
61
+ | "Done" claims | trusted as written | **evidence-gated**: claimed files, test counts, and run output are checked against reality — bluffs exit 1 |
62
+ | Switching agents (Claude → Codex → Cursor) | context lost | same `.harness/` state, same one-call handoff |
63
+ | Secrets · encoding · drift guards | none | `scan secrets` · `encoding check` · `drift check --auto-fix` — CI-ready |
64
+ | Lock-in | one vendor | any agent, any language, 0 runtime dependencies |
136
65
 
137
- **MCP (외부 AI 에이전트에 도구로 노출)**
138
- ```bash
139
- leerness mcp serve # JSON-RPC over stdio, 85 도구
140
- ```
66
+ This positioning was verified by **5 independent clean-room evaluations** — real Python/Node/Rust development, agent swaps, and adversarial attacks against the verifier itself (fake tests, comment-only stubs, inflated test counts — all rejected).
141
67
 
142
68
  ---
143
69
 
144
- ## 아키텍처 (외부 리뷰 검증)
70
+ ## Guidance vs enforcement (be honest about this)
145
71
 
146
- - **런타임 의존성 0 / install-script 0** — `package.json` 의 dependencies/optional/peer 가 전부 비어 있고 postinstall 도 없습니다. 순수 Node stdlib(`fs`/`path`/`child_process`/`readline`). 공급망 공격면 최소. `leerness install-safety` 로 확인 가능.
147
- - **canonical JSON 단일 진실소스 + 마크다운 projection** — 메모리는 JSON 으로 저장하고 사람이 읽는 `.md` 는 파생물. 파이프(`|`)·개행·백틱·이모지·한글이 마크다운 테이블에서도 안전(셀 이스케이프 + round-trip).
148
- - **원자적 UTF-8 쓰기** — temp + rename 으로 부분쓰기 손상 방지, BOM 자동 strip.
149
- - **shell 미경유 MCP** — `mcp serve` 의 도구 호출은 셸을 거치지 않고 인자를 직접 전달(명령 주입 차단).
150
- - **순수 `--json` / 일관 exit code** — 성공·실패·미존재 경로 모두 파싱 가능한 JSON(`{ok,error,code}`) + 실패 시 exit 1. 자동화·CI 친화.
151
- - **모듈 분리(DI)** + **내장 자가검증** — `lib/` 순수 유틸/IO/카탈로그 분리, `selftest` 210 케이스로 설치 무결성 검증(`doctor` 가 함께 실행). 문서(README) 부재에도 코어 무결성 진단은 통과.
72
+ By default leerness is **cooperative**: your AI agent runs the commands because CLAUDE.md / AGENTS.md tell it to. A determined agent could skip them. To make verification **enforced**, not optional:
152
73
 
153
- ---
154
-
155
- ## 차별점
74
+ ```bash
75
+ leerness ci init # writes .github/workflows/leerness-gate.yml — runs `leerness gate` on every PR
76
+ ```
156
77
 
157
- - **진짜 0-dependency** — SaaS 가 아니라 파일 기반 로컬 운영 메모리. 네트워크 불필요(업데이트 확인 제외).
158
- - **에이전트 중립** — Claude / Codex / Cursor / Aider / Goose 등 어디에나 적용.
159
- - **거짓 완료 방지** — 완료 주장에 evidence 를 요구하는 anti-lazy 흐름.
160
- - **통합 게이트** — 보안·인코딩·드리프트·검증을 `gate` 하나로.
161
- - **한국어 우선 + Windows/인코딩 1급 시민** — CP949/BOM 가드, 한국어 출력 기본(`--language en` 지원).
162
- - **자기기술(self-describing)** — `about`/`commands`/`capabilities`/`doctor` 로 도구가 스스로 설명.
163
- - **지속적 외부 검증** — 다중 모델 클린룸 리뷰로 회귀 0 을 유지하며 진화.
78
+ Then make that check **required** in GitHub branch protection. Now a PR that skips verification (or whose claims fail) **cannot merge** — the gate runs independently of the agent, returns a non-zero exit code, and blocks. That is the difference between a guideline and a guardrail.
164
79
 
165
80
  ---
166
81
 
167
- ## 보안
82
+ ## What is inside (the 60-second tour)
168
83
 
169
- - 시크릿/키/토큰을 소스에 하드코딩하지 마세요. `.env` 사용 + `.gitignore` 포함. `scan secrets`/`gate` 가 커밋 대상 시크릿을 차단합니다.
170
- - 외부 AI CLI 연동은 **기본 비활성**입니다(`LEERNESS_ENABLE_*` opt-in). 브리지(web/pc/lsp)도 opt-in.
171
- - 자세한 권한 표면은 [SECURITY.md](./SECURITY.md) 참고.
84
+ - **Memory** — `task` / `plan` / `decision` / `lesson` / `rule`: canonical JSON + markdown projections, archive/restore.
85
+ - **Handoff** — `handoff` (session start context) · `session close` (closing report). Survives agent swaps.
86
+ - **Verification** — `verify-claim` (evidence vs reality, stub/fake-test/inflated-count detection, `--run-tests --test-cmd` for any language) · `contract verify` (spec ↔ impl) · `gate` (one-call CI gate).
87
+ - **Audit** — `audit` · `lazy detect` · `drift check` keep the workspace honest over time.
88
+ - **Security** — `scan secrets` (committed-secret detection) · `encoding check` (BOM/CP949) — also runs at `session close`.
172
89
 
173
- ---
90
+ Full command reference, workflows, and architecture: **[README.ko.md](./README.ko.md)** (Korean) · `leerness commands` · `leerness help`.
174
91
 
175
- ## 링크
92
+ ## Links
176
93
 
177
- - 홈페이지: https://leerness.com
178
94
  - npm: https://www.npmjs.com/package/leerness
179
- - GitHub: https://github.com/gugu9999gu/leerness
180
- - 변경 이력: [CHANGELOG.md](./CHANGELOG.md)
95
+ - Site & release videos: https://leerness.pages.dev
96
+ - Changelog: [CHANGELOG.md](./CHANGELOG.md)
181
97
 
182
- ## 라이선스
98
+ ## License
183
99
 
184
100
  MIT
185
101
 
186
102
  <!-- leerness:project-readme:start -->
187
103
  ## Leerness Project Harness
188
104
 
189
- 이 프로젝트는 Leerness v1.17.0 하네스를 사용합니다. AI 에이전트는 작업 전 `leerness handoff`로 컨텍스트를 적재하고, 작업 후 `leerness check`/`leerness audit`/`leerness session close`를 수행해야 합니다.
105
+ 이 프로젝트는 Leerness v1.19.0 하네스를 사용합니다. AI 에이전트는 작업 전 `leerness handoff`로 컨텍스트를 적재하고, 작업 후 `leerness check`/`leerness audit`/`leerness session close`를 수행해야 합니다.
190
106
 
191
107
  ### 정체성 — AI 에이전트 운영 레이어 (UR-0030)
192
108
 
@@ -240,7 +156,7 @@ leerness memory restore decision <date|title>
240
156
 
241
157
  ### MCP server (외부 AI 통합)
242
158
 
243
- Leerness v1.17.0는 stdio JSON-RPC MCP server를 내장합니다 — Claude Code · Cursor · Codex CLI 등 외부 AI에 **85개 도구**를 노출:
159
+ Leerness v1.19.0는 stdio JSON-RPC MCP server를 내장합니다 — Claude Code · Cursor · Codex CLI 등 외부 AI에 **85개 도구**를 노출:
244
160
 
245
161
  ```jsonc
246
162
  // 카테고리별
@@ -261,7 +177,7 @@ Leerness v1.17.0는 stdio JSON-RPC MCP server를 내장합니다 — Claude Code
261
177
  `<<autonomous-loop-dynamic>>` 신호만 보내면 AI가:
262
178
  1) 다음 라운드 후보 선정 → 2) 코드 변경 → 3) stress-v* 신규 작성 + 누적 회귀 → 4) e2e 219/219 → 5) npm pack + git tag + GitHub release → 6) main 자동 push (1.9.140+) → 7) session close → 8) 다음 라운드 예약.
263
179
 
264
- 현재 누적: **70 라운드 (1.9.40 → 1.17.0)** · 매 라운드 GitHub release/태그 생성 · _reports/는 비공개 보존.
180
+ 현재 누적: **70 라운드 (1.9.40 → 1.19.0)** · 매 라운드 GitHub release/태그 생성 · _reports/는 비공개 보존.
265
181
 
266
182
  ### 성능 가이드 (1.9.140 측정)
267
183
 
@@ -299,6 +215,6 @@ leerness release pack --close --auto-main-push
299
215
  - `.harness/session-handoff.md`: 다음 세션 인수인계 (자동 작성)
300
216
  - `.harness/lessons.md` / `decisions.md` / `rules.md`: 영구 메모리 (5 surface)
301
217
 
302
- Last synced by Leerness v1.17.0: 2026-06-09
218
+ Last synced by Leerness v1.19.0: 2026-06-14
303
219
  <!-- leerness:project-readme:end -->
304
220
 
package/SECURITY.md CHANGED
@@ -1,56 +1,66 @@
1
- # Security & Transparency / 보안·투명성
2
-
3
- > `leerness capabilities` 로 언제든 아래 표면을 CLI 에서 확인할 수 있습니다 (`--json` 지원).
4
- > Run `leerness capabilities` anytime to view this surface from the CLI (`--json` supported).
5
-
6
- leerness 는 **권한이 큰 CLI 하네스**입니다 (child_process · git · 외부 AI CLI · 자동화 브리지 · hook 설치). 신뢰를 위해 **할 수 있는 전부와 각 항목의 끄는 법(opt-out)** 을 공개합니다.
7
-
8
- leerness is a **powerful CLI harness** (child_process, git, external AI CLIs, automation bridges, hook install). For trust, we disclose **everything it can do and how to opt out of each**.
9
-
10
- ## 설계 원칙 / Design principles
11
-
12
- - **런타임 의존성 0** — `npm audit` 취약점 0. / Zero runtime dependencies.
13
- - **postinstall 없음** — 설치만으로 코드가 실행되지 않음. / No postinstall scripts.
14
- - **변경 전 자동 백업** — 모든 메타파일 변경 전 `.harness/archive/` 에 백업. / Auto-backup before any change.
15
- - **동의 없는 자동 호출 금지** — 사용자 동의 없이 외부 LLM/API/CLI 를 자동 호출하지 않음. / Never auto-calls external LLMs/APIs/CLIs without consent.
16
-
17
- ## 권한 표면 / Capability surface
18
-
19
- | 영역 / Area | 위험 / Risk | 설명 / What | opt-out |
20
- |---|---|---|---|
21
- | filesystem | 🟢 low | `.harness/` 메타파일 생성·갱신, 변경 전 백업. 소스코드 직접 수정 안 함. | 핵심 동작 (백업으로 보호) |
22
- | network | 🟢 low | `update --check` 의 npm 최신 버전 비교만. 외부 URL 자동 fetch 안 함. | `LEERNESS_OFFLINE=1` |
23
- | childProcess | 🟡 medium | git(명시 명령 시), `npm test`(verify-code), 외부 CLI `--version` 감지. | verify 계열 한정 · 외부 CLI 는 opt-in |
24
- | externalAgents | 🟡 medium | `agents dispatch/multi` — 기본은 명령 텍스트만 생성, `multi --execute` 시 실제 spawn. | `LEERNESS_ENABLE_*` 미설정 시 비활성 (기본 off) |
25
- | automationBridges | 🔴 high | `web`(playwright)/`pc`(robotjs)/`lsp`(typescript) — opt-in 의존성. `pc` 는 마우스/키보드 제어. | 의존성 미설치 시 비활성 (기본 off) |
26
- | claudeHook | 🟢 low | `init` 시 `.claude/settings.local.json` 에 SessionStart hook(`update --check`) 설치. | `leerness init . --no-auto-update` |
27
-
28
- ## ⚠ 주의해서 쓸 명령 / Use with caution
29
-
30
- 회사·운영 코드에서는 아래 명령을 먼저 검토하세요. / Review these before using on company/production code.
31
-
32
- | 명령 / Command | 동작 / Action |
33
- |---|---|
34
- | `init` | `.harness/` 50+ 파일 + `.claude` hook 생성 (변경 전 백업) |
35
- | `update --yes` | 자동 마이그레이션 — 메타파일 갱신 |
36
- | `agents multi --execute` | 외부 AI CLI 실제 spawn (병렬) |
37
- | `release publish` / `sync-main` | git push + npm publish + GitHub release |
38
- | `pc <click|type>` | 마우스/키보드 제어 (robotjs, full 권한) |
39
- | `web <...>` | 헤드리스 브라우저 자동화 (playwright) |
40
- | `setup-agents` | 외부 CLI 활성화 + 자동 설치 시도 |
41
-
42
- ## 권장 도입 방식 / Recommended adoption
43
-
44
- 전역 자동 적용보다, 먼저 한 프로젝트에서 확인 후 커밋하세요.
45
- Prefer per-project trial over global auto-adoption.
46
-
47
- ```bash
48
- npx leerness@latest init . --yes --language ko # 또는 --language en
49
- git diff && git status # 생성 파일 검토 후 커밋
50
- leerness capabilities # 권한 표면 확인
51
- ```
52
-
53
- ## 취약점 보고 / Reporting
54
-
55
- 보안 이슈는 공개 이슈 대신 비공개로 알려주세요 / Report security issues privately (not public issues):
56
- https://github.com/gugu9999gu/leerness/issues (보안 라벨 / security label)
1
+ # Security & Transparency / 보안·투명성
2
+
3
+ > `leerness capabilities` 로 언제든 아래 표면을 CLI 에서 확인할 수 있습니다 (`--json` 지원).
4
+ > Run `leerness capabilities` anytime to view this surface from the CLI (`--json` supported).
5
+
6
+ leerness 는 **권한이 큰 CLI 하네스**입니다 (child_process · git · 외부 AI CLI · 자동화 브리지 · hook 설치). 신뢰를 위해 **할 수 있는 전부와 각 항목의 끄는 법(opt-out)** 을 공개합니다.
7
+
8
+ leerness is a **powerful CLI harness** (child_process, git, external AI CLIs, automation bridges, hook install). For trust, we disclose **everything it can do and how to opt out of each**.
9
+
10
+ ## 설계 원칙 / Design principles
11
+
12
+ - **런타임 의존성 0** — `npm audit` 취약점 0. / Zero runtime dependencies.
13
+ - **postinstall 없음** — 설치만으로 코드가 실행되지 않음. / No postinstall scripts.
14
+ - **변경 전 자동 백업** — 모든 메타파일 변경 전 `.harness/archive/` 에 백업. / Auto-backup before any change.
15
+ - **동의 없는 자동 호출 금지** — 사용자 동의 없이 외부 LLM/API/CLI 를 자동 호출하지 않음. / Never auto-calls external LLMs/APIs/CLIs without consent.
16
+
17
+ ## 권한 표면 / Capability surface
18
+
19
+ | 영역 / Area | 위험 / Risk | 설명 / What | opt-out |
20
+ |---|---|---|---|
21
+ | filesystem | 🟢 low | `.harness/` 메타파일 생성·갱신, 변경 전 백업. 소스코드 직접 수정 안 함. | 핵심 동작 (백업으로 보호) |
22
+ | network | 🟢 low | `update --check` 의 npm 최신 버전 비교만. 외부 URL 자동 fetch 안 함. | `LEERNESS_OFFLINE=1` |
23
+ | childProcess | 🟡 medium | git(명시 명령 시), `npm test`(verify-code), 외부 CLI `--version` 감지. | verify 계열 한정 · 외부 CLI 는 opt-in |
24
+ | externalAgents | 🟡 medium | `agents dispatch/multi` — 기본은 명령 텍스트만 생성, `multi --execute` 시 실제 spawn. | `LEERNESS_ENABLE_*` 미설정 시 비활성 (기본 off) |
25
+ | automationBridges | 🔴 high | `web`(playwright)/`pc`(robotjs)/`lsp`(typescript) — opt-in 의존성. `pc` 는 마우스/키보드 제어. | 의존성 미설치 시 비활성 (기본 off) |
26
+ | claudeHook | 🟢 low | `init` 시 `.claude/settings.local.json` 에 SessionStart hook(`update --check`) 설치. | `leerness init . --no-auto-update` |
27
+
28
+ ## ⚠ 주의해서 쓸 명령 / Use with caution
29
+
30
+ 회사·운영 코드에서는 아래 명령을 먼저 검토하세요. / Review these before using on company/production code.
31
+
32
+ | 명령 / Command | 동작 / Action |
33
+ |---|---|
34
+ | `init` | `.harness/` 50+ 파일 + `.claude` hook 생성 (변경 전 백업) |
35
+ | `update --yes` | 자동 마이그레이션 — 메타파일 갱신 |
36
+ | `agents multi --execute` | 외부 AI CLI 실제 spawn (병렬) |
37
+ | `release publish` / `sync-main` | git push + npm publish + GitHub release |
38
+ | `pc <click|type>` | 마우스/키보드 제어 (robotjs, full 권한) |
39
+ | `web <...>` | 헤드리스 브라우저 자동화 (playwright) |
40
+ | `setup-agents` | 외부 CLI 활성화 + 자동 설치 시도 |
41
+
42
+ ## 권장 도입 방식 / Recommended adoption
43
+
44
+ 전역 자동 적용보다, 먼저 한 프로젝트에서 확인 후 커밋하세요.
45
+ Prefer per-project trial over global auto-adoption.
46
+
47
+ ```bash
48
+ npx leerness@latest init . --yes --language ko # 또는 --language en
49
+ git diff && git status # 생성 파일 검토 후 커밋
50
+ leerness capabilities # 권한 표면 확인
51
+ ```
52
+
53
+ ## 취약점 보고 / Reporting
54
+
55
+ 보안 취약점은 **공개 이슈로 올리지 마세요** — 공개 이슈는 내용이 모두에게 노출됩니다.
56
+ **Do NOT open a public issue for security vulnerabilities** — public issues are visible to everyone.
57
+
58
+ 대신 아래 **비공개 채널** 중 하나로 알려주세요 / Use one of these **private** channels instead:
59
+
60
+ 1. **GitHub Private Vulnerability Reporting** (권장 / preferred):
61
+ https://github.com/gugu9999gu/leerness/security/advisories/new
62
+ — GitHub 의 비공개 보안 권고 폼. 저장소 Security 탭 → "Report a vulnerability".
63
+ 2. **보안 이메일 / Security email**: adstore3869@gmail.com (제목에 `[leerness security]` 표기 / prefix the subject with `[leerness security]`)
64
+
65
+ 48 시간 내 접수 확인을 목표로 합니다. 수정 전까지 세부 내용은 공개하지 말아 주세요 (책임 있는 공개).
66
+ We aim to acknowledge within 48 hours. Please keep details private until a fix ships (responsible disclosure).