leerness 1.18.0 → 1.19.0

package/CHANGELOG.md

@@ -1,5 +1,84 @@
 # Changelog
 
+## 1.19.0 — 2026-06-14 — 🛡️ [안정화/Stable] 검증 하네스 강화 + 정직한 프레이밍 안정 minor
+
+**🛡️ 안정화(Stable) minor — "거짓 완료를 못 하게" 만드는 검증 계층을 한층 더 단단하게.** 직전 minor(1.18.0) 이후 누적된 패치 4건(1.18.1~1.18.4)을 검증·통합해 npm 공개. R-0011 정책의 10번째 stable minor. 핵심 테마: **검증 계층 강화(비-JS 거짓FAIL 해소 + 위장 스텁 차단) + AI 자기질문 품질 렌즈 + 정직한 프레이밍(협조 vs 강제, 영문 우선)**.
+
+### 이번 minor 통합 (1.18.1~1.18.4)
+- **🌐 비-JS `--test-cmd` 거짓 FAIL 해소 (P1, 1.18.1)**: 기본 권한(basic)이 `python/pytest` 등 사용자 명시 테스트 명령을 막아(exit 126) 초록 프로젝트를 "주장 불일치 FAIL"로 오판하던 것 — 명시 `--test-cmd`/config `testCommand`는 명시 권한으로 실행 허용(cwd jail 유지), 차단 시엔 FAIL 아닌 skip. + task update 위치인자 status 무시 차단 + 종합 라벨 정직화.
+- **🛡️ 위장 스텁 차단 (P2, 1.18.2)**: `module.exports = {}` 같은 빈 export 껍데기가 "구현 실체 ✓"를 통과하던 우회 폐쇄. 적대 워크플로로 한-단어 우회 9종(Object.freeze/new Object/async fn/exports.default/인라인 주석/`()=>({})`/class{}) 재발견·차단. 과탐 0(이름붙은 export·재노출·실코드 통과). `.java/.php/.mjs/.cjs` 추출 정합.
+- **🧭 분야별 자기질문 품질 렌즈 (1.18.3)**: `leerness lens [code|design|docs|test|security]` — 완료 선언 전 AI가 스스로 답하는 질문(코드: "선임 개발자가 복잡하다 느끼지 않을까?" / 디자인: "선임 디자이너+일반 사용자가 이쁘고 직관적인가?") + 분야간 인과관계. AGENTS.md/anti-lazy 정책 통합. README 영문 우선 재작성(README.ko.md 분리) + 설치 직후 REPL 문항 제거.
+- **🔒 보안 제보 비공개화 + 자기정합 (1.18.4)**: SECURITY.md를 GitHub Private Vulnerability Reporting + 보안 이메일로(공개 이슈 안내 모순 해소). README 관리블록 버전 자기정합 + audit가 동적 배지 README의 관리블록 lag도 감지. README "Guidance vs enforcement"(협조형 기본, `ci init`+branch protection으로 강제) + `init --minimal` 노출.
+
+### 검증 (회귀 0)
+- **selftest 222→231** · **E2E 365/365** · 각 패치 행위 재현(공격 차단 + 정직 작업 과탐 0) + 위장 스텁 적대 워크플로 + 게시본 재실증(1.18.1 P1) 완료.
+
+### 안정화 표시 (R-0006)
+CHANGELOG [안정화/Stable] · git tag (Stable) · GitHub release (`--latest`) · npm dist-tag `stable` 시도.
+
+## 1.18.4 — 2026-06-14 — GPT-5.5 외부평가 채택: 보안 제보 비공개화 + 자기정합 + 정직한 강제 프레이밍
+
+**🔎 외부평가(GPT-5.5)를 맹신 X로 검증해 진짜 결함만 채택.** 8개 한계 지적을 리포지토리에서 직접 확인 — #3(오케스트레이션 과대홍보)은 현 포지셔닝상 **기각**(이미 "operations/verification layer"), #6(채택 증거)은 범위 밖. 검증된 결함을 이번 패치에 반영.
+
+### 변경 (채택)
+- **🔒 SECURITY.md 비공개 제보 채널 (#8, P1, UR-0005)**: "비공개로 알려주세요" 하면서 **공개** GitHub Issues+보안라벨로 안내하던 모순 해소(공개 이슈는 모두에게 노출). → **GitHub Private Vulnerability Reporting**(`/security/advisories/new`) + 보안 이메일(`[leerness security]`)로 교체, "공개 이슈 금지" 명시 + 책임 있는 공개 안내. 권한 큰 하네스의 기본 위생.
+- **🪞 README 자기정합 (#7, P2, UR-0006)**: 관리블록 버전이 package.json(1.18.x)과 어긋나던 것(v1.18.0 표기) 해소 — `readme sync` 로 1.18.4 재스탬프. 게다가 audit 이 **동적 npm 배지 README 에서 못 잡던 갭**을 닫음: 배지뿐 아니라 "Last synced by Leerness vX" 관리블록 버전도 package.json 과 대조(`readme_synced_version_stale`, `--fix` 자동). 정합성 관리 도구가 자기 정합부터.
+- **🛡️ 정직한 강제 프레이밍 (#2, P2, UR-0007)**: README 에 "Guidance vs enforcement" 섹션 — leerness 는 **기본 협조형**(에이전트가 자발 실행)이며, **강제**하려면 `leerness ci init`(PR 게이트 워크플로) + branch protection required check 로 검증 건너뛴 PR 머지 차단. 가이드라인과 가드레일의 차이를 솔직히 명시.
+- **🪶 가벼운 진입 (#4, P2, UR-0008)**: README 30초 퀵스타트에 `init --minimal`(핵심 메모리+검증 파일만) 노출 — 사용자 "가볍게" 철학과 정합. 핵심8 vs 플러그인 경계 분리는 백로그.
+- 백로그(UR-0009): 클린룸 평가 요약 공개 + 커버리지 측정.
+
+### 검증 (회귀 0)
+- **selftest 229→231** (SECURITY.md 비공개 채널 행위 + audit 관리블록 lag 소스 가드) · audit 행위 재현(인위적 stale → 감지+`--fix`) · **E2E 365/365**.
+- patch(1.18.4) — npm 미배포(R-0011, GitHub/CHANGELOG 누적).
+
+## 1.18.3 — 2026-06-12 — 품질 렌즈(분야별 자기질문) + README 영문 우선 + 설치 REPL 문항 제거 (사용자 명시 3종)
+
+**🧭 "AI가 스스로 질문하고 행동하도록".** 사용자 명시 지시 3종을 한 패치로: (1) 분야별 자기질문 품질 렌즈, (2) README 영어권 우선 재작성, (3) 설치 직후 REPL 진입 문항 제거.
+
+### 변경
+- **`leerness lens [code|design|docs|test|security]` 신설 (UR-0003)**: 완료 선언 전 AI가 스스로 답하는 분야별 질문 + **분야간 인과관계**(↔ affects). 사용자 원문 그대로 — 코드: *"선임 개발자가 이 코드를 보고 복잡하다고 느끼지 않을까?"* / 디자인: *"선임 디자이너와 일반 사용자가 봤을 때 이쁘고 편하고 직관적이며 헷갈리지 않는가?"* / 문서: *"30초 안에 뭘 해보면 되지?"*. "그렇다(통과)"라고 답할 수 없으면 완료가 아님. `--json` 지원. AGENTS.md 템플릿 Required behavior + anti-lazy-work-policy 규칙 7로 통합(새 init 워크스페이스부터 AI가 자동으로 읽음).
+- **README 영어권 우선 재작성 (UR-0004)**: 첫 화면 영문 — *Try it in 30 seconds*(즉시 해볼 명령) / *No terminal? Let your AI run it*(비개발자: AI에게 붙여넣는 한 문단 + MCP 85 도구) / *Why leerness?*(자체 하네스 대비 차별점 표 — "기억은 말한 것, leerness는 한 것을 검증"). 한국어 전문은 `README.ko.md` 분리. 관리 블록(project-readme) 보존.
+- **설치 직후 REPL agent 모드 진입 문항 제거 (사용자 명시)**: REPL은 완성도가 올라가면 구현 예정 — 설치 흐름에서 질문·자동 진입 삭제(수동 `leerness agent`는 유지). 설치 문항이 한 개 줄어 더 단순.
+- **운영**: leerness 영상(쇼츠) 생성 당분간 중지 — site release-pipeline의 렌더/검증/업로드 3단계에 `LEERNESS_VIDEO_ENABLED` 가드(레포 변수로 재개). 룰 R-0006(토큰 예산 고려)/R-0007(영상 중지) 등록.
+
+### 기록만 (토큰 예산 고려 — 다음 라운드 후보, UR-0003 완전판)
+- 렌즈 워크스페이스 커스텀(`.harness/quality-lenses.json` — 프로젝트별 질문 추가/수정), handoff 헤드라인에 in-progress task 키워드 → 관련 렌즈 자동 힌트, verify-claim/session close에 렌즈 자가답변 기록(advisory), MCP `leerness_lens` 노출, 인과관계 그래프 자동 추론(변경 파일 확장자 → 영향 분야 매핑).
+
+### 검증 (회귀 0)
+- **selftest 227→229** (카탈로그 무결성·사용자 원문·affects 상호참조 행위 + 표면 등재/REPL 제거 소스 가드 — 자기참조 함정 1건 즉시 수정) · **E2E 365/365** · lens 행위 확인(유효/무효 도메인 exit 0/1).
+- patch(1.18.3) — npm 미배포(R-0011, GitHub/CHANGELOG 누적).
+
+## 1.18.2 — 2026-06-11 — 위장 스텁(빈 export 껍데기) 차단 — 거짓완료 우회 폐쇄 + 적대 강화
+
+**🛡️ "거짓완료 차단"의 위장 스텁 우회 폐쇄 — 적대 워크플로로 강화.** 1.18.1 재실증에서 정직한 한계로 남겼던 위장 스텁을 닫고, 적대 헌터(우회·오탐 병렬)로 1차 수정의 우회를 재발견해 함께 폐쇄. `module.exports = {};` 한 줄 "빈 껍데기 구현"이 `verify-claim` "구현 실체 ✓"를 통과하고 `require` 만 하는 가짜 테스트와 결합하면 **`--strict-claims` 에서도 exit 0** 으로 통과하던 우회(맹신 X 클린룸 케이스 B).
+
+### 변경 (재실증 후속 + 적대 강화)
+- **빈 export 껍데기 = 스텁 판정**: 비주석 코드가 빈 값(zero-logic) producer 뿐이면 스텁 → done 주장 기본 게이팅 FAIL. 순수 함수 `_vcImplIsEmpty` 분리(단위 테스트). 적대 헌터가 찾은 우회형까지 포함: `{}`·`[]`·`Object.freeze({})`·`new Object()`·`(async) function(){}`·`(async)()=>{}`·`()=>({})`·`class {}`·`export default {}`·`export {}`·`exports.default = {}`·`pass`, TS 캐스트(`{} as any`) 허용.
+- **인라인 주석 우회 차단**: 같은 줄 트레일링 주석(`module.exports = {}; // ...`)이 앵커를 깨던 가장 사소한 누수 — 줄별 인라인 `//` 제거(따옴표 없는 줄 한정, 문자열 보호) 후 판정.
+- **확장자 정합(`FILE_EXTS`)**: `java`·`php`·`mjs`·`cjs` 추가 — 이전엔 `.java`/`.php` 임플 주장이 추출조차 안 돼 스텁/존재 검사를 무검사 통과하던 불일치 버그 해소.
+- **과탐 0(오탐 헌터 ~45 합법패턴 확인)**: 이름붙은 export(`{ a, b }`)·재노출(`require('./x')`/`export * from`)·멤버 객체(`{ port: 3000 }`)·`Object.freeze({a:1})`·메서드 있는 클래스·비어있지 않은 화살표(`(a,b)=>a+b`)·`class Foo {}` + 별도 export(스펙 FP-가드)는 전부 정상 통과.
+- 참고: 재실증이 의심했던 "테스트-구현 연결 OR 우회"는 **실재하지 않음**(내용 기반 검사가 미연결 테스트를 정확히 잡음 — 클린룸 케이스 A strict=exit 1).
+- 정직한 잔여(백로그): 호출식 다중 인자(`Object.assign({},{})`), Python def/class-wrapped `pass`·`...`·`raise NotImplementedError`, 다언어(Ruby/Go/Rust `todo!()`) 빈 본문 — 정규식 누적보다 경량 토큰/AST 기반 "빈 컨테이너" 재설계로 미룸.
+
+### 검증 (회귀 0)
+- **selftest 225→227** (빈 껍데기 기본+우회형 8종+정상 10종 행위 단위 + 소스/확장자 가드) · **E2E 365/365** · **적대 워크플로 2회**(우회 9건 isReal 재현 → 수정 → CLI 행위 14/14 재확인; 오탐 0).
+- **행위 재현(맹신 X)**: Object.freeze/new Object/async fn/exports.default/=>({})/class{}/인라인주석/리터럴 8종 → strict exit 1(이전 0); 진짜 구현·배럴·freeze({a:1})·메서드 클래스·설정 객체 6종 → exit 0(오탐 0).
+- patch(1.18.2) — npm 미배포(R-0011, GitHub/CHANGELOG 누적).
+
+## 1.18.1 — 2026-06-11 — 재실증 후속: --test-cmd 비-JS 거짓차단 해소 (P1) + 정합 구멍 2건
+
+**🔁 1.18.0 을 게시본에서 다시 검증(맹신 X)했더니, "범용" 약속의 핵심인 비-JS 사용자에게 새 P1 이 보였다.** 독립 클린룸 3곳(파이썬 재개발·적대 재공격·Node 회귀)으로 1.18.0 의 5격차를 재실증한 결과 4건은 닫혔으나, `verify-claim --run-tests --test-cmd "python ..."` 이 권한 차단(126)으로 막혀 **초록 프로젝트에 거짓 "✗ 불일치 FAIL"**(exit 1)을 내던 것을 발견·수정.
+
+### 변경 (재실증 발견)
+- **🌐 --test-cmd 비-JS 인터프리터 거짓차단 해소 (P1)**: `leerness init` 기본 권한(basic, `shell.exec=false`)의 allowList 가 JS 도구(git/npm/node…)만 허용해 `python/py/pytest/uv` 등이 status 126 으로 막히고, 그게 "테스트 실패→주장 불일치" 거짓 판정으로 둔갑했음. 이제 **사용자가 명시한 `--test-cmd`/설정 `testCommand` 는 명시 권한(userAuthorized)** 으로 인터프리터 실행 허용(cwd jail 은 유지). 추가 방어: 권한/jail 로 막힌 실행은 **"테스트 실패"가 아니라 "측정 불가(skip, 불일치 판정 아님)"** 로 처리 — 차단이 절대 거짓 FAIL 로 바뀌지 않음.
+- **🔚 task update 위치인자 status 무시 차단 (P2)**: `task update T-0003 done` 처럼 상태를 위치인자로 주면 조용히 무시되고 "✓ updated"가 출력돼 **done 이 안 되고 verify-claim/마감 정직성 검사가 통째로 건너뛰던** 데이터 정합 구멍 해소 — id 뒤 떠도는 positional 거부 + did-you-mean(`--status done`). 정상 `--status`/`--next` 는 과탐 0.
+- **🏷 종합 라벨 정직화 (P3)**: 커스텀 `--test-cmd` 인데도 종합 줄이 "npm test 실행"으로 하드코딩되던 것 → 실제 실행 명령 표기.
+
+### 검증 (회귀 0)
+- **selftest 222→225** (권한 결정 `_isCommandPermitted` 행위 단위 + 정합 가드) · **E2E 365/365** (대기 중 갱신).
+- **행위 재현(맹신 X)**: 초록 파이썬 프로젝트에서 `verify-claim --run-tests --test-cmd "python test_todo.py"` → exit 0 + "python test_todo.py 실행: ✓ all passed" + 일치 판정(이전: 126/거짓 FAIL/exit 1). `task update T-0001 done` → 명확 에러+exit 1, status 는 그대로(done 아님), `--status done`/`--next` 정상.
+- patch(1.18.1) — npm 미배포(R-0011, GitHub/CHANGELOG 누적). 다음 minor 때 묶음 공개.
+
 ## 1.18.0 — 2026-06-10 — 🛡️ [안정화/Stable] 범용 검증 하네스 안정 minor
 
 **🛡️ 안정화(Stable) minor — "범용 AI 코딩 하네스" 실증 격차 전부 해소.** 5개 독립 클린룸 실사용 평가(Python/Node/Rust 실개발·에이전트 교대·적대 공격)가 찾은 P1 2건 + P2 3건(1.17.2~1.17.6)을 검증·통합해 npm 공개. R-0011 정책의 9번째 minor. 새 포지셔닝: **"어떤 언어, 어떤 AI 에이전트로 작업하든 — 증거 없이는 끝났다고 말할 수 없게."**

package/README.ko.md

@@ -0,0 +1,187 @@
+> **English version: [README.md](./README.md)** — 영어권 우선 정책에 따라 첫 화면은 영문이며, 이 문서가 한국어 전문입니다.
+
+# leerness
+
+```
+██╗     ███████╗███████╗██████╗ ███╗   ██╗███████╗███████╗
+██║     ██╔════╝██╔════╝██╔══██╗████╗  ██║██╔════╝██╔════╝
+██║     █████╗  █████╗  ██████╔╝██╔██╗ ██║█████╗  ███████╗
+██║     ██╔══╝  ██╔══╝  ██╔══██╗██║╚██╗██║██╔══╝  ╚════██║
+███████╗███████╗███████╗██║  ██║██║ ╚████║███████╗███████║
+╚══════╝╚══════╝╚══════╝╚═╝  ╚═╝╚═╝  ╚═══╝╚══════╝╚══════╝
+```
+
+> **어떤 언어, 어떤 AI 에이전트로 작업하든 — "증거 없이는 끝났다고 말할 수 없게" 만드는 AI 코딩 운영 레이어.** 코드를 대신 쓰는 도구가 아니라, AI 에이전트의 **기억·인수인계·검증·감사·보안 가드**를 프로젝트에 영속화하는 CLI + MCP 서버입니다. (이 포지셔닝은 5개 독립 클린룸 실사용 평가 — Python/Node/Rust 실개발·에이전트 교대·적대 공격 — 로 검증됐습니다.)
+
+[![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
+
+> 이 문서는 **외부 다중 모델(Codex / Claude Sonnet / Claude Opus)이 README 를 보지 않고 leerness 를 직접 설치·실행·소스 분석한 객관 리뷰**를 바탕으로 재구성되었습니다. 매 릴리스마다 자동 갱신됩니다.
+
+---
+
+## leerness가 뭔가요?
+
+AI 코딩 에이전트(Claude Code, Cursor, Codex, Aider, Goose 등)는 코드를 잘 쓰지만 세 가지 약점이 있습니다.
+
+1. **기억하지 못합니다** — 세션이 바뀌면 현재 상태·결정·다음 작업을 잊습니다.
+2. **거짓 완료를 선언합니다** — 증거(파일·테스트·로그) 없이 "완료했습니다"라고 말합니다.
+3. **표준이 없습니다** — 여러 에이전트 간 인수인계, 보안/인코딩 점검, 드리프트 관리가 제각각입니다.
+
+leerness는 이 문제들을 해결하는 **외부 운영 substrate**입니다. 어떤 에이전트 위에도 얹어, 프로젝트의 상태를 `.harness/` 파일로 영속화하고 CLI · MCP 도구로 노출합니다. **leerness 자체는 LLM을 호출하거나 코드를 실행하지 않습니다.**
+
+---
+
+## 해결하는 문제
+
+| 문제 | leerness의 해법 |
+|---|---|
+| 세션 간 맥락·결정·다음 작업 유실 | `task`/`decision`/`lesson`/`plan`/`rule` 메모리를 영속화하고, 세션 시작 시 `handoff` 1콜로 회수 |
+| 증거 없는 "완료" 주장 | `verify-claim --require-evidence`, `lazy detect`, anti-lazy 정책으로 차단 |
+| Claude → Codex → Cursor 교체 시 맥락 소실 | 표준 세션 워크플로(handoff → 작업 → session close)로 에이전트 독립 인수인계 |
+| 하드코딩 시크릿 · 인코딩 깨짐(BOM/CP949) | `scan secrets`, `encoding check` 자동 감지 (CI 게이트) |
+| 워크스페이스 노화(drift)를 에이전트가 모름 | `drift check [--auto-fix]` 점수화 + 자동 회복 |
+| 명세 ↔ 구현 불일치 | `contract verify spec.md impl.js` 함수/필드 일치 검사 |
+| 여러 AI CLI의 역할/분배 표준 부재 | `agents`/`roles`/`team` 오케스트레이션(기본 opt-in, dispatch는 실행이 아닌 명령 생성) |
+
+---
+
+## 빠른 시작
+
+```bash
+# 설치 (런타임 의존성 0 — 추가 패키지 없음)
+npm install -g leerness
+
+# 프로젝트 초기화 (.harness/ 거버넌스 문서 + .claude/.cursor/.github 어댑터 생성)
+leerness init .
+
+# 세션 시작 — 이전 맥락/기억/다음 작업을 1콜로 회수
+leerness handoff .
+
+#   ... 에이전트가 작업 ...
+leerness task add "사용자 인증 API 구현"
+leerness gate .                 # verify + audit + scan secrets + encoding + lazy 통합 게이트
+
+# 세션 종료 — 마감 통계 + 다음 라운드 추천 + 인수인계 문서 자동 생성
+leerness session close .
+```
+
+CLAUDE.md / AGENTS.md 에 `세션 시작 시 leerness handoff .`, `종료 전 leerness session close .` 지침을 추가하면 에이전트가 자동으로 호출합니다.
+
+---
+
+## 거짓 완료 차단 — 핵심 차별점
+
+세 모델의 블라인드 리뷰가 공통으로 꼽은 leerness의 핵심 가치입니다. AI 에이전트가 가장 자주 하는 거짓말 "다 했어요"를, leerness는 **완료 주장을 실제 코드와 대조**해 검증합니다.
+
+```bash
+# 에이전트가 "결제 API 연동 완료"라고 주장하지만 코드엔 호출 흔적이 없으면:
+leerness verify-claim T-0001 --require-evidence
+#   ⚠ FAIL (낙관 1) · [Payment] 결제: evidence에 주장 있으나 코드에 호출 흔적 없음 → exit 1
+```
+
+- `optimism-check` · `verify-claim` — evidence의 도메인 주장(API·DB·결제·이메일·큐·캐시·알림·스토리지 등 10종)을 실제 소스 호출과 대조. **JavaScript뿐 아니라 Python·Ruby·Go·C#·Java·PHP·Rust 구현도 인식**합니다(1.13).
+- `lazy detect` — 증거 없는 done, 빈 handoff, 테스트 미실행, 미추적 TODO를 탐지.
+- 정직한 완료는 통과하고 가짜 완료만 exit 1로 차단 — `gate` 또는 CI에 그대로 연결됩니다.
+
+---
+
+## 핵심 개념 — 5계층
+
+- **기억(Memory)** — `task`/`plan`/`decision`/`lesson`/`rule`/`feature`(그래프). canonical JSON 을 단일 진실소스로 저장하고 마크다운은 projection. archive/restore 지원.
+- **인수인계(Handoff)** — `handoff`(세션 시작 컨텍스트), `session close`(마감 보고). 에이전트 교체에도 맥락 보존.
+- **검증(Verification)** — `verify-claim`(증거 강제), `contract verify`(명세↔구현), `verify-code`(테스트/빌드 실행 + 증거 기록).
+- **감사(Audit)** — `scan secrets`, `encoding check`, `lazy detect`, `drift check`, `audit`, 그리고 이를 묶는 `gate`.
+- **정책/보안(Policy)** — 8단계 권한 등급 enforce, 외부 에이전트 opt-in, 자연어 영구 룰(`rule add ... --trigger`).
+
+---
+
+## 명령 카테고리
+
+- **초기화/진단**: `init` · `status` · `which` · `doctor` · `selftest` · `capabilities`
+- **메모리**: `task` · `plan` · `decision` · `lesson` · `rule` · `feature` · `memory status/search`
+- **인수인계/세션**: `handoff` · `session close` · `pulse` · `health`
+- **검증/감사**: `check` · `gate` · `audit` · `drift check` · `lazy detect` · `scan secrets` · `encoding check` · `verify-code` · `verify-claim` · `contract verify`
+- **외부 에이전트**: `agents list/check/dispatch` · `provider` · `roles` · `adapter`
+- **운영/확장**: `release` · `migrate` · `team` · `install-safety` · `route` · `review`(페르소나)
+- **브리지(opt-in)**: `web`(playwright) · `pc`(robotjs) · `lsp`
+- **MCP**: `mcp serve` — stdio JSON-RPC 서버로 85개 도구 노출
+
+전체 명령은 `leerness commands` 또는 `leerness --help` 로 확인하세요.
+
+> **경로 규칙** — 대부분 명령은 `[path]` 위치 인자를 받습니다. `task`/`decision`/`lesson` 등 메모리 명령에 다른 폴더를 지정할 땐 `--path <dir>` 또는 `./dir` 형태를 쓰세요(맨 폴더 이름만 주면 현재 폴더로 처리됩니다). 출력은 한국어가 기본이며 `--language en` 으로 영어를 늘릴 수 있습니다(일부 메시지는 한국어 유지).
+
+---
+
+## 대표 워크플로
+
+**기본 세션 사이클**
+```bash
+leerness handoff .                          # 이전 맥락 자동 로드
+leerness task add "API 응답 검증 로직 구현"
+leerness task update T-0001 --status in-progress --evidence "검증 함수 구현"
+leerness gate .                             # 배포 전 통합 품질 게이트
+leerness session close .                    # 마감 + 다음 에이전트 인수인계
+```
+
+**보안·검증 게이트 (CI)**
+```bash
+leerness scan secrets .                     # 커밋 대상 하드코딩 시크릿 → exit 1
+leerness contract verify spec.md src/api.js # 명세 함수/필드 누락 → exit 1
+leerness verify-claim T-0001 --require-evidence
+```
+
+**다중 에이전트 조율**
+```bash
+leerness agents list                        # 설치된 외부 AI CLI 가용성
+leerness agents dispatch "코드 리뷰" --to codex   # 실행 명령 생성(직접 실행은 사용자/메인 에이전트)
+```
+
+**MCP (외부 AI 에이전트에 도구로 노출)**
+```bash
+leerness mcp serve                          # JSON-RPC over stdio, 85 도구
+```
+
+---
+
+## 아키텍처 (외부 리뷰 검증)
+
+- **런타임 의존성 0 / install-script 0** — `package.json` 의 dependencies/optional/peer 가 전부 비어 있고 postinstall 도 없습니다. 순수 Node stdlib(`fs`/`path`/`child_process`/`readline`). 공급망 공격면 최소. `leerness install-safety` 로 확인 가능.
+- **canonical JSON 단일 진실소스 + 마크다운 projection** — 메모리는 JSON 으로 저장하고 사람이 읽는 `.md` 는 파생물. 파이프(`|`)·개행·백틱·이모지·한글이 마크다운 테이블에서도 안전(셀 이스케이프 + round-trip).
+- **원자적 UTF-8 쓰기** — temp + rename 으로 부분쓰기 손상 방지, BOM 자동 strip.
+- **shell 미경유 MCP** — `mcp serve` 의 도구 호출은 셸을 거치지 않고 인자를 직접 전달(명령 주입 차단).
+- **순수 `--json` / 일관 exit code** — 성공·실패·미존재 경로 모두 파싱 가능한 JSON(`{ok,error,code}`) + 실패 시 exit 1. 자동화·CI 친화.
+- **모듈 분리(DI)** + **내장 자가검증** — `lib/` 순수 유틸/IO/카탈로그 분리, `selftest` 210 케이스로 설치 무결성 검증(`doctor` 가 함께 실행). 문서(README) 부재에도 코어 무결성 진단은 통과.
+
+---
+
+## 차별점
+
+- **진짜 0-dependency** — SaaS 가 아니라 파일 기반 로컬 운영 메모리. 네트워크 불필요(업데이트 확인 제외).
+- **에이전트 중립** — Claude / Codex / Cursor / Aider / Goose 등 어디에나 적용.
+- **거짓 완료 방지** — 완료 주장에 evidence 를 요구하는 anti-lazy 흐름.
+- **통합 게이트** — 보안·인코딩·드리프트·검증을 `gate` 하나로.
+- **한국어 우선 + Windows/인코딩 1급 시민** — CP949/BOM 가드, 한국어 출력 기본(`--language en` 지원).
+- **자기기술(self-describing)** — `about`/`commands`/`capabilities`/`doctor` 로 도구가 스스로 설명.
+- **지속적 외부 검증** — 다중 모델 클린룸 리뷰로 회귀 0 을 유지하며 진화.
+
+---
+
+## 보안
+
+- 시크릿/키/토큰을 소스에 하드코딩하지 마세요. `.env` 사용 + `.gitignore` 포함. `scan secrets`/`gate` 가 커밋 대상 시크릿을 차단합니다.
+- 외부 AI CLI 연동은 **기본 비활성**입니다(`LEERNESS_ENABLE_*` opt-in). 브리지(web/pc/lsp)도 opt-in.
+- 자세한 권한 표면은 [SECURITY.md](./SECURITY.md) 참고.
+
+---
+
+## 링크
+
+- 홈페이지: https://leerness.com
+- npm: https://www.npmjs.com/package/leerness
+- GitHub: https://github.com/gugu9999gu/leerness
+- 변경 이력: [CHANGELOG.md](./CHANGELOG.md)
+
+## 라이선스
+
+MIT
+

package/README.md

@@ -9,184 +9,100 @@
 ╚══════╝╚══════╝╚══════╝╚═╝  ╚═╝╚═╝  ╚═══╝╚══════╝╚══════╝
 ```
 
-> **어떤 언어, 어떤 AI 에이전트로 작업하든 — "증거 없이는 끝났다고 말할 수 없게" 만드는 AI 코딩 운영 레이어.** 코드를 대신 쓰는 도구가 아니라, AI 에이전트의 **기억·인수인계·검증·감사·보안 가드**를 프로젝트에 영속화하는 CLI + MCP 서버입니다. (이 포지셔닝은 5개 독립 클린룸 실사용 평가 — Python/Node/Rust 실개발·에이전트 교대·적대 공격 — 로 검증됐습니다.)
+> **The AI-coding operations layer that makes "done" require evidence — for any language, any AI agent.**
+> 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.
 
-[![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
+[![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
 
-> 이 문서는 **외부 다중 모델(Codex / Claude Sonnet / Claude Opus)이 README 를 보지 않고 leerness 를 직접 설치·실행·소스 분석한 객관 리뷰**를 바탕으로 재구성되었습니다. 매 릴리스마다 자동 갱신됩니다.
+**🇰🇷 한국어 전문: [README.ko.md](./README.ko.md)**
 
 ---
 
-## leerness가 뭔가요?
-
-AI 코딩 에이전트(Claude Code, Cursor, Codex, Aider, Goose 등)는 코드를 잘 쓰지만 세 가지 약점이 있습니다.
-
-1. **기억하지 못합니다** — 세션이 바뀌면 현재 상태·결정·다음 작업을 잊습니다.
-2. **거짓 완료를 선언합니다** — 증거(파일·테스트·로그) 없이 "완료했습니다"라고 말합니다.
-3. **표준이 없습니다** — 여러 에이전트 간 인수인계, 보안/인코딩 점검, 드리프트 관리가 제각각입니다.
-
-leerness는 이 문제들을 해결하는 **외부 운영 substrate**입니다. 어떤 에이전트 위에도 얹어, 프로젝트의 상태를 `.harness/` 파일로 영속화하고 CLI · MCP 도구로 노출합니다. **leerness 자체는 LLM을 호출하거나 코드를 실행하지 않습니다.**
-
----
-
-## 해결하는 문제
-
-| 문제 | leerness의 해법 |
-|---|---|
-| 세션 간 맥락·결정·다음 작업 유실 | `task`/`decision`/`lesson`/`plan`/`rule` 메모리를 영속화하고, 세션 시작 시 `handoff` 1콜로 회수 |
-| 증거 없는 "완료" 주장 | `verify-claim --require-evidence`, `lazy detect`, anti-lazy 정책으로 차단 |
-| Claude → Codex → Cursor 교체 시 맥락 소실 | 표준 세션 워크플로(handoff → 작업 → session close)로 에이전트 독립 인수인계 |
-| 하드코딩 시크릿 · 인코딩 깨짐(BOM/CP949) | `scan secrets`, `encoding check` 자동 감지 (CI 게이트) |
-| 워크스페이스 노화(drift)를 에이전트가 모름 | `drift check [--auto-fix]` 점수화 + 자동 회복 |
-| 명세 ↔ 구현 불일치 | `contract verify spec.md impl.js` 함수/필드 일치 검사 |
-| 여러 AI CLI의 역할/분배 표준 부재 | `agents`/`roles`/`team` 오케스트레이션(기본 opt-in, dispatch는 실행이 아닌 명령 생성) |
-
----
-
-## 빠른 시작
+## Try it in 30 seconds
 
 ```bash
-# 설치 (런타임 의존성 0 — 추가 패키지 없음)
-npm install -g leerness
-
-# 프로젝트 초기화 (.harness/ 거버넌스 문서 + .claude/.cursor/.github 어댑터 생성)
-leerness init .
-
-# 세션 시작 — 이전 맥락/기억/다음 작업을 1콜로 회수
-leerness handoff .
-
-#   ... 에이전트가 작업 ...
-leerness task add "사용자 인증 API 구현"
-leerness gate .                 # verify + audit + scan secrets + encoding + lazy 통합 게이트
-
-# 세션 종료 — 마감 통계 + 다음 라운드 추천 + 인수인계 문서 자동 생성
-leerness session close .
+npx -y leerness init . --yes   # adds .harness/ memory + guard files to your project
+npx leerness handoff .         # everything your AI should know right now, in one call
 ```
 
-CLAUDE.md / AGENTS.md 에 `세션 시작 시 leerness handoff .`, `종료 전 leerness session close .` 지침을 추가하면 에이전트가 자동으로 호출합니다.
-
----
-
-## 거짓 완료 차단 — 핵심 차별점
-
-세 모델의 블라인드 리뷰가 공통으로 꼽은 leerness의 핵심 가치입니다. AI 에이전트가 가장 자주 하는 거짓말 "다 했어요"를, leerness는 **완료 주장을 실제 코드와 대조**해 검증합니다.
+Your project now has agent-independent memory. To see the flagship feature — catching a false "done" claim:
 
 ```bash
-# 에이전트가 "결제 API 연동 완료"라고 주장하지만 코드엔 호출 흔적이 없으면:
-leerness verify-claim T-0001 --require-evidence
-#   ⚠ FAIL (낙관 1) · [Payment] 결제: evidence에 주장 있으나 코드에 호출 흔적 없음 → exit 1
+npx leerness task add "Implement payment API"
+npx leerness task update T-0001 --status done --evidence "payment.js done, 5 tests passed"
+npx leerness verify-claim T-0001   # exit 1 — payment.js does not exist, no tests ran. Claim rejected.
 ```
 
-- `optimism-check` · `verify-claim` — evidence의 도메인 주장(API·DB·결제·이메일·큐·캐시·알림·스토리지 등 10종)을 실제 소스 호출과 대조. **JavaScript뿐 아니라 Python·Ruby·Go·C#·Java·PHP·Rust 구현도 인식**합니다(1.13).
-- `lazy detect` — 증거 없는 done, 빈 handoff, 테스트 미실행, 미추적 TODO를 탐지.
-- 정직한 완료는 통과하고 가짜 완료만 exit 1로 차단 — `gate` 또는 CI에 그대로 연결됩니다.
+Write the real file with a real test and the same command passes. That is the whole idea: **"done" must match reality.**
 
----
-
-## 핵심 개념 — 5계층
-
-- **기억(Memory)** — `task`/`plan`/`decision`/`lesson`/`rule`/`feature`(그래프). canonical JSON 을 단일 진실소스로 저장하고 마크다운은 projection. archive/restore 지원.
-- **인수인계(Handoff)** — `handoff`(세션 시작 컨텍스트), `session close`(마감 보고). 에이전트 교체에도 맥락 보존.
-- **검증(Verification)** — `verify-claim`(증거 강제), `contract verify`(명세↔구현), `verify-code`(테스트/빌드 실행 + 증거 기록).
-- **감사(Audit)** — `scan secrets`, `encoding check`, `lazy detect`, `drift check`, `audit`, 그리고 이를 묶는 `gate`.
-- **정책/보안(Policy)** — 8단계 권한 등급 enforce, 외부 에이전트 opt-in, 자연어 영구 룰(`rule add ... --trigger`).
+> Want a smaller footprint? `leerness init . --minimal` installs only the core memory + verification files instead of the full set.
 
 ---
 
-## 명령 카테고리
+## No terminal? Let your AI run it
 
-- **초기화/진단**: `init` · `status` · `which` · `doctor` · `selftest` · `capabilities`
-- **메모리**: `task` · `plan` · `decision` · `lesson` · `rule` · `feature` · `memory status/search`
-- **인수인계/세션**: `handoff` · `session close` · `pulse` · `health`
-- **검증/감사**: `check` · `gate` · `audit` · `drift check` · `lazy detect` · `scan secrets` · `encoding check` · `verify-code` · `verify-claim` · `contract verify`
-- **외부 에이전트**: `agents list/check/dispatch` · `provider` · `roles` · `adapter`
-- **운영/확장**: `release` · `migrate` · `team` · `install-safety` · `route` · `review`(페르소나)
-- **브리지(opt-in)**: `web`(playwright) · `pc`(robotjs) · `lsp`
-- **MCP**: `mcp serve` — stdio JSON-RPC 서버로 85개 도구 노출
+You never have to type a command yourself. Paste this into Claude Code, Cursor, Codex, or any coding agent:
 
-전체 명령은 `leerness commands` 또는 `leerness --help` 로 확인하세요.
+> 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.
 
-> **경로 규칙** — 대부분 명령은 `[path]` 위치 인자를 받습니다. `task`/`decision`/`lesson` 등 메모리 명령에 다른 폴더를 지정할 땐 `--path <dir>` 또는 `./dir` 형태를 쓰세요(맨 폴더 이름만 주면 현재 폴더로 처리됩니다). 출력은 한국어가 기본이며 `--language en` 으로 영어를 늘릴 수 있습니다(일부 메시지는 한국어 유지).
+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.
+
+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?"*
 
 ---
 
-## 대표 워크플로
+## Claude and Codex already have memory. Why leerness?
 
-**기본 세션 사이클**
-```bash
-leerness handoff .                          # 이전 맥락 자동 로드
-leerness task add "API 응답 검증 로직 구현"
-leerness task update T-0001 --status in-progress --evidence "검증 함수 구현"
-leerness gate .                             # 배포 전 통합 품질 게이트
-leerness session close .                    # 마감 + 다음 에이전트 인수인계
-```
-
-**보안·검증 게이트 (CI)**
-```bash
-leerness scan secrets .                     # 커밋 대상 하드코딩 시크릿 → exit 1
-leerness contract verify spec.md src/api.js # 명세 함수/필드 누락 → exit 1
-leerness verify-claim T-0001 --require-evidence
-```
+Built-in harnesses remember what the AI **said**. leerness verifies what the AI **did** — and keeps working when you switch agents.
 
-**다중 에이전트 조율**
-```bash
-leerness agents list                        # 설치된 외부 AI CLI 가용성
-leerness agents dispatch "코드 리뷰" --to codex   # 실행 명령 생성(직접 실행은 사용자/메인 에이전트)
-```
+| | Built-in (CLAUDE.md, agent memory) | leerness |
+|---|---|---|
+| Memory | per-agent, free-form notes | structured tasks / decisions / lessons / rules — agent-independent files in your repo |
+| "Done" claims | trusted as written | **evidence-gated**: claimed files, test counts, and run output are checked against reality — bluffs exit 1 |
+| Switching agents (Claude → Codex → Cursor) | context lost | same `.harness/` state, same one-call handoff |
+| Secrets · encoding · drift guards | none | `scan secrets` · `encoding check` · `drift check --auto-fix` — CI-ready |
+| Lock-in | one vendor | any agent, any language, 0 runtime dependencies |
 
-**MCP (외부 AI 에이전트에 도구로 노출)**
-```bash
-leerness mcp serve                          # JSON-RPC over stdio, 85 도구
-```
+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).
 
 ---
 
-## 아키텍처 (외부 리뷰 검증)
+## Guidance vs enforcement (be honest about this)
 
-- **런타임 의존성 0 / install-script 0** — `package.json` 의 dependencies/optional/peer 가 전부 비어 있고 postinstall 도 없습니다. 순수 Node stdlib(`fs`/`path`/`child_process`/`readline`). 공급망 공격면 최소. `leerness install-safety` 로 확인 가능.
-- **canonical JSON 단일 진실소스 + 마크다운 projection** — 메모리는 JSON 으로 저장하고 사람이 읽는 `.md` 는 파생물. 파이프(`|`)·개행·백틱·이모지·한글이 마크다운 테이블에서도 안전(셀 이스케이프 + round-trip).
-- **원자적 UTF-8 쓰기** — temp + rename 으로 부분쓰기 손상 방지, BOM 자동 strip.
-- **shell 미경유 MCP** — `mcp serve` 의 도구 호출은 셸을 거치지 않고 인자를 직접 전달(명령 주입 차단).
-- **순수 `--json` / 일관 exit code** — 성공·실패·미존재 경로 모두 파싱 가능한 JSON(`{ok,error,code}`) + 실패 시 exit 1. 자동화·CI 친화.
-- **모듈 분리(DI)** + **내장 자가검증** — `lib/` 순수 유틸/IO/카탈로그 분리, `selftest` 210 케이스로 설치 무결성 검증(`doctor` 가 함께 실행). 문서(README) 부재에도 코어 무결성 진단은 통과.
+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:
 
----
-
-## 차별점
+```bash
+leerness ci init          # writes .github/workflows/leerness-gate.yml — runs `leerness gate` on every PR
+```
 
-- **진짜 0-dependency** — SaaS 가 아니라 파일 기반 로컬 운영 메모리. 네트워크 불필요(업데이트 확인 제외).
-- **에이전트 중립** — Claude / Codex / Cursor / Aider / Goose 등 어디에나 적용.
-- **거짓 완료 방지** — 완료 주장에 evidence 를 요구하는 anti-lazy 흐름.
-- **통합 게이트** — 보안·인코딩·드리프트·검증을 `gate` 하나로.
-- **한국어 우선 + Windows/인코딩 1급 시민** — CP949/BOM 가드, 한국어 출력 기본(`--language en` 지원).
-- **자기기술(self-describing)** — `about`/`commands`/`capabilities`/`doctor` 로 도구가 스스로 설명.
-- **지속적 외부 검증** — 다중 모델 클린룸 리뷰로 회귀 0 을 유지하며 진화.
+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.
 
 ---
 
-## 보안
+## What is inside (the 60-second tour)
 
-- 시크릿/키/토큰을 소스에 하드코딩하지 마세요. `.env` 사용 + `.gitignore` 포함. `scan secrets`/`gate` 가 커밋 대상 시크릿을 차단합니다.
-- 외부 AI CLI 연동은 **기본 비활성**입니다(`LEERNESS_ENABLE_*` opt-in). 브리지(web/pc/lsp)도 opt-in.
-- 자세한 권한 표면은 [SECURITY.md](./SECURITY.md) 참고.
+- **Memory** — `task` / `plan` / `decision` / `lesson` / `rule`: canonical JSON + markdown projections, archive/restore.
+- **Handoff** — `handoff` (session start context) · `session close` (closing report). Survives agent swaps.
+- **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).
+- **Audit** — `audit` · `lazy detect` · `drift check` keep the workspace honest over time.
+- **Security** — `scan secrets` (committed-secret detection) · `encoding check` (BOM/CP949) — also runs at `session close`.
 
----
+Full command reference, workflows, and architecture: **[README.ko.md](./README.ko.md)** (Korean) · `leerness commands` · `leerness help`.
 
-## 링크
+## Links
 
-- 홈페이지: https://leerness.com
 - npm: https://www.npmjs.com/package/leerness
-- GitHub: https://github.com/gugu9999gu/leerness
-- 변경 이력: [CHANGELOG.md](./CHANGELOG.md)
+- Site & release videos: https://leerness.pages.dev
+- Changelog: [CHANGELOG.md](./CHANGELOG.md)
 
-## 라이선스
+## License
 
 MIT
 
 <!-- leerness:project-readme:start -->
 ## Leerness Project Harness
 
-이 프로젝트는 Leerness v1.18.0 하네스를 사용합니다. AI 에이전트는 작업 전 `leerness handoff`로 컨텍스트를 적재하고, 작업 후 `leerness check`/`leerness audit`/`leerness session close`를 수행해야 합니다.
+이 프로젝트는 Leerness v1.19.0 하네스를 사용합니다. AI 에이전트는 작업 전 `leerness handoff`로 컨텍스트를 적재하고, 작업 후 `leerness check`/`leerness audit`/`leerness session close`를 수행해야 합니다.
 
 ### 정체성 — AI 에이전트 운영 레이어 (UR-0030)
 
@@ -240,7 +156,7 @@ leerness memory restore decision <date|title>
 
 ### MCP server (외부 AI 통합)
 
-Leerness v1.18.0는 stdio JSON-RPC MCP server를 내장합니다 — Claude Code · Cursor · Codex CLI 등 외부 AI에 **85개 도구**를 노출:
+Leerness v1.19.0는 stdio JSON-RPC MCP server를 내장합니다 — Claude Code · Cursor · Codex CLI 등 외부 AI에 **85개 도구**를 노출:
 
 ```jsonc
 // 카테고리별
@@ -261,7 +177,7 @@ Leerness v1.18.0는 stdio JSON-RPC MCP server를 내장합니다 — Claude Code
 `<<autonomous-loop-dynamic>>` 신호만 보내면 AI가:
 1) 다음 라운드 후보 선정 → 2) 코드 변경 → 3) stress-v* 신규 작성 + 누적 회귀 → 4) e2e 219/219 → 5) npm pack + git tag + GitHub release → 6) main 자동 push (1.9.140+) → 7) session close → 8) 다음 라운드 예약.
 
-현재 누적: **70 라운드 (1.9.40 → 1.18.0)** · 매 라운드 GitHub release/태그 생성 · _reports/는 비공개 보존.
+현재 누적: **70 라운드 (1.9.40 → 1.19.0)** · 매 라운드 GitHub release/태그 생성 · _reports/는 비공개 보존.
 
 ### 성능 가이드 (1.9.140 측정)
 
@@ -299,6 +215,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.18.0: 2026-06-10
+Last synced by Leerness v1.19.0: 2026-06-14
 <!-- leerness:project-readme:end -->