leerness 1.8.0 → 1.9.1

package/CHANGELOG.md

@@ -0,0 +1,96 @@
+# Changelog
+
+## 1.9.1 — 2026-05-08
+
+1.9.0을 실 프로젝트(memo-cli)에서 운영하며 발견한 **5개 메타 감사 사항**을 패치합니다.
+
+### Fixed
+
+- **P1**: `autoUpdateInstall`이 legacy `leerness-plus update --check` SessionStart hook을 자동 정리. fork 시절 잔재로 인해 매 세션 npm 호출이 2회 발생하던 문제 해소.
+- **P2**: `managedMerge`에 `MERGE_OVERWRITE_FILES` 화이트리스트 추가 (`skill-index.md`, `manifest.json`, `skills-lock.json`, `HARNESS_VERSION`, `LANGUAGE`, `context-routing.md`). 다단계 migrate를 거쳐도 표/메타데이터가 누적되지 않음.
+- **P4**: `audit`이 `<!-- leerness:na <reason> -->` 마커를 인식. CLI 패키지 등 디자인 토큰/재사용 맵이 NA인 프로젝트에서 영구 경고가 사라짐.
+- **P6**: `lazy detect`의 evidence 정규식을 `/^plan:M-\d{4}\s*$/`로 좁힘. `plan:M-XXXX` 단독은 부족 판정, `tests:32/32 (plan:M-0002)`처럼 검증 키워드 동반 시 통과.
+- **P7**: `install`이 끝날 때 디폴트 `M-0001`이 plan에 있는데 progress에 row가 없으면 `T-XXXX` 자동 생성. audit "milestones without progress entry: M-0001" 경고가 init 직후 사라짐.
+
+### Added
+
+- `leerness skill list [path]` 출력에 **설치됨** 컬럼 추가 (root가 인자/현재 디렉토리에 있을 때).
+
+### Migration
+
+기존 1.9.0 설치본은 `npx leerness@latest update . --yes`로 즉시 자동 마이그레이션됩니다.
+
+## 1.9.0 — 2026-05-08
+
+이번 minor 릴리스는 1.8.0의 6개 결함을 수정하고, 자동 감지·자동 업데이트·핸드오프 자동 작성·게으름/시크릿/인코딩 자동 가드를 흡수한 큰 강화입니다. 기존 `npx leerness init` 흐름은 그대로 유지됩니다.
+
+### Fixed (vs 1.8.0)
+
+- B1: `task update`가 in-place 갱신하도록 progress-tracker를 구조화 파싱.
+- B2: `plan add`의 milestone ID와 progress task ID 분리. evidence 컬럼에 `plan:M-XXXX` 링크.
+- B3: `plan add --status/--progress/--next/--evidence` 인자가 progress row에 일관 반영.
+- B4: `task list`가 표만 정돈 출력 (frontmatter 노출 안 함).
+- B5: `routes.feature`이 참조하는 `feature-implementation` 스킬을 카탈로그에 추가하고 init이 `.harness/skills/feature-implementation/{README.md,skill.json}`을 자동 생성.
+- B6: `session close`가 progress-tracker를 구조화 파싱하여 status 컬럼 정확 매칭.
+
+### Added — 자동 감지·업데이트
+
+- `leerness update [--check|--yes|--force|--from <tarball>]`
+  - 현재 `.harness/HARNESS_VERSION` 자동 파싱 (1.8.0 bare, `leerness@1.8.0+plus@x.y.z` legacy plus 표기 모두 인식).
+  - `npm view leerness version`으로 최신 비교 (24h 캐시).
+  - 새 버전 발견 시 `npx leerness@latest migrate .`에 자동 위임 → 백업·머지·검증.
+  - post-migration 으로 `status`/`verify`/`audit`을 자동 실행, `task-log.md`/`review-evidence.md` 자동 누적.
+- `leerness auto-update install` — `.claude/settings.local.json`의 SessionStart hook + `/update` 슬래시 커맨드 자동 등록.
+- `init`/`migrate`가 끝나면 위 hook을 기본 등록 (`--no-auto-update`로 끌 수 있음).
+- `LEERNESS_OFFLINE=1` 환경변수로 npm 호출 건너뜀 (CI/오프라인 호환).
+
+### Added — 컨텍스트·핸드오프 자동화
+
+- `leerness handoff [path]` — 세션 시작 컨텍스트 자동 적재 + `current-state.md` 스탬프 자동 갱신.
+- `leerness check [path]` — pre-action 정합 검증 (필수 파일·보호 정책).
+- `leerness session close`가 `session-handoff.md`와 `current-state.md`를 **자동 작성** (이전엔 출력만 했음).
+- `.harness/templates/{end-of-session-report.md, decision.md, task-row.md}` 표준 템플릿 추가.
+
+### Added — 자동 가드
+
+- `leerness audit [path]` — 디자인 가이드 중복·design 토큰·reuse-map·plan↔progress 정렬·handoff 신선도 감사.
+- `leerness scan secrets [path]` — AWS/GitHub/GitHub fine-grained/OpenAI/Anthropic/Google/Slack/PEM/하드코딩 password 9개 패턴.
+- `leerness encoding check [path]` — UTF-8 BOM, UTF-16 BOM, NUL, .bat의 chcp 65001 누락, 한글 라운드트립.
+- `leerness lazy detect [path]` — 증거 없는 done, 빈 handoff, 추적 없는 TODO/FIXME, blocker 방치 자동 감지.
+- `leerness memory search "키"` — decisions/log/handoff/plan/progress/evidence/architecture grep.
+
+### Added — 정책 강화
+
+- `.harness/anti-lazy-work-policy.md` — 1줄 선언 → 6개 규칙 + 자동 점검 항목.
+- `.harness/secret-policy.md` — 패턴 목록 명시.
+- `.harness/encoding-policy.md` — BOM/UTF-8/.bat chcp/Python coding/LF 통일.
+- `.harness/test-evidence-policy.md` — 검증 기록 누적 형식.
+- `.harness/review-evidence.md` — 자동 누적 evidence 파일.
+- `.harness/guardrails.md` — 5개 파일 이상 리팩토링 사전 승인, destructive Git 가드.
+- `.harness/task-type-map.md` — `bugfix`, `refactor`, `research`, `session-start` 작업 유형 추가.
+
+### Added — Claude Code 통합
+
+- `.claude/commands/{handoff, session-close, audit, lazy-detect, update, viewwork-ping}.md` 슬래시 커맨드.
+- `.claude/skills/leerness.md` Claude Code 스킬 정의.
+- `.claude/settings.local.json` SessionStart + Stop hook 자동 등록.
+
+### Added — ViewWork 통합
+
+- `leerness viewwork install` — `.viewwork/` 셋업 + Claude Code Stop hook 등록.
+- `leerness viewwork emit` — JSONL 1줄 추가 (`.viewwork/agent-events.jsonl`).
+- `session close`가 자동으로 viewwork emit.
+
+### Changed
+
+- `.gitignore`에 `.harness/archive/`, `.harness/migration-report.md`, `.harness/cache/` 라인 머지.
+- `.gitattributes` 자동 생성 (`* text=auto eol=lf`, `*.bat eol=crlf`, `*.ps1 eol=crlf`).
+- `routes.feature`이 가리키는 경로를 `.harness/skills/feature-implementation/README.md`로 정정.
+
+### E2E
+
+`npm test` (= `node scripts/e2e.js`)가 빈 임시 디렉토리에서 30+개 시나리오를 실측합니다 (B1 in-place upsert 회귀 + offline `update --check` + SessionStart hook 검증 포함).
+
+## 1.8.0 — 2026-05-07
+
+(이전 메인테이너의 릴리스. https://github.com/gugu9999gu/leerness 참고.)

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 gugu9999gu
+Copyright (c) 2026 leerness contributors
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,85 +1,123 @@
 # Leerness
 
-Leerness는 AI 에이전트가 프로젝트의 목적, 계획, 진행 상태, 설계 결정, 디자인/기능 일관성, 검증된 스킬을 지속적으로 참조하며 개발하도록 돕는 AX 최적화 개발 하네스입니다.
+> 한국어 우선 AI 개발 하네스. 비파괴 마이그레이션 / 자동 버전 감지·업데이트 / 계획·진행·핸드오프 자동화 / 게으름·시크릿·인코딩 자동 가드 / Claude Code 슬래시 통합.
 
-## 주요 기능
-
-- `.harness/` 기반 장기 맥락 유지
-- `plan.md`와 `progress-tracker.md` 기반 계획/작업 추적
-- 언어 자동 감지 또는 선택 설치
-- 스킬 라이브러리 선택 설치와 한글 스킬 정보 표시
-- AI 검증 스킬의 라이브러리화, 병합, 마이그레이션, 배포 흐름 지원
-- 기존 하네스/스킬/지침 파일 비파괴 마이그레이션
-- `.env.example`, `.gitignore`, README managed section 병합 업데이트
-- 디자인 가이드 병합, 재사용 맵, 일관성 정책 제공
-- 세션 종료 인수인계와 미완료 작업 추적
-
-## 설치
+## 빠르게 시작
 
 ```bash
-npx leerness init
+# 신규 프로젝트
+npx leerness init . --language ko --skills recommended
+
+# 기존 leerness 1.x.x 프로젝트 자동 업그레이드
+npx leerness@latest update . --yes
+# 또는 비파괴 마이그레이션만
+npx leerness@latest migrate . --dry-run
+npx leerness@latest migrate .
 ```
 
-언어와 스킬을 명시하려면:
+대화식 init 흐름은 언어(한/영/자동) 및 스킬 라이브러리 (추천/전체/직접) 선택을 안내합니다.
+
+## 핵심 명령
 
 ```bash
-npx leerness init --language ko --skills recommended
-npx leerness init --language en --skills office,commerce-api
+leerness handoff .              # 세션 시작 컨텍스트 자동 적재
+leerness status .               # 설치 상태
+leerness verify .               # 필수 파일 검증
+leerness audit .                # 디자인/재사용/계획↔진행 정렬 감사
+leerness check .                # pre-action 체크
+leerness scan secrets .         # AWS/GitHub/OpenAI/Anthropic/Google/Slack/PEM/하드코딩 password 패턴
+leerness encoding check .       # UTF-8/BOM/UTF-16 BOM/NUL/.bat의 chcp 65001/한글 라운드트립
+leerness lazy detect .          # 증거 없는 done, 빈 handoff, 추적 없는 TODO/FIXME 자동 감지
+leerness memory search "키"     # decisions/log/handoff/plan/progress 즉시 grep
+leerness session close .        # 세션 종료 + handoff/current-state 자동 작성
+leerness update --check         # 24h 캐시 자동 버전 감지
+leerness update --yes           # 새 버전 자동 마이그레이션 + verify/audit
 ```
 
-기존 프로젝트 마이그레이션:
+`leerness route <type>` 으로 작업 유형별 read/update 라우트 확인 (`planning, feature, bugfix, refactor, research, consistency, release, migration, session-start, session-close, harness-maintenance`).
 
-```bash
-npx leerness migrate --dry-run
-npx leerness migrate
-```
+## 자동 버전 감지·업데이트
 
-## 설치 시 선택 흐름
+`init`/`migrate`가 끝나면 `.claude/settings.local.json`의 SessionStart hook에 `leerness update --check`이 자동 등록됩니다 (`--no-auto-update`로 끄기 가능). 24시간 캐시(`.harness/cache/update-check.json`)로 npm 호출 폭주를 막습니다.
 
-대화형 터미널에서 `--yes`, `--language`, `--skills`를 생략하면 Leerness가 설치 언어와 스킬 라이브러리 설치 여부를 묻습니다.
+| 명령 | 동작 |
+|---|---|
+| `leerness update --check` | 현재 `.harness/HARNESS_VERSION` ↔ `npm view leerness version` 비교 |
+| `leerness update --yes` | 새 버전 발견 시 `npx leerness@latest migrate .`에 위임 → 백업·머지 후 `status`/`verify`/`audit` 자동 실행 → `task-log.md`/`review-evidence.md`에 누적 |
+| `leerness update --from <tarball>` | 로컬 tarball / 오프라인 / 사내 미러 |
+| `LEERNESS_OFFLINE=1` 환경변수 | npm 호출 건너뜀 |
 
-- 언어: 자동 감지, 한국어, English
-- 스킬: 기본 하네스만, 추천 스킬, 전체 스킬, 직접 입력
+## 비파괴 마이그레이션 정책
 
-CI 또는 자동화 환경에서는 프롬프트 없이 명시 옵션을 사용하세요.
+- 모든 변경 전에 `.harness/archive/leerness-<version>-<timestamp>/` 백업 자동 생성.
+- 사용자 메모리(plan / progress / current-state / decisions / task-log / architecture / context-map / feature-contracts / reuse-map / design-system 등) 기본 보존.
+- 관리되는 인스트럭션(AGENTS.md, CLAUDE.md, .cursor/rules/leerness.mdc, .github/copilot-instructions.md)은 새 템플릿으로 머지하되 이전 내용을 `<!-- leerness:migration-preserved -->` 블록으로 보존.
+- `.env.example`, `.gitignore`, `.gitattributes`는 라인 단위 머지.
+- 결과 보고서: `.harness/migration-report.md`.
 
-```bash
-npx leerness init --yes --language ko --skills recommended
+## 디렉토리 구조
+
+```
+.harness/
+├── plan.md / progress-tracker.md / current-state.md / session-handoff.md
+├── decisions.md / task-log.md / review-evidence.md
+├── guideline.md / writeback-policy.md / context-routing.md / task-type-map.md
+├── architecture.md / context-map.md / feature-contracts.md
+├── design-system.md / consistency-policy.md / reuse-map.md
+├── anti-lazy-work-policy.md / secret-policy.md / encoding-policy.md
+├── test-evidence-policy.md / session-close-policy.md / review-checklist.md / release-checklist.md
+├── protected-files.md / guardrails.md / language-policy.md / leerness-maintenance.md
+├── plan-progress-boundary.md
+├── AX_PLAN_GUIDE.md / AX_MIGRATION_GUIDE.md / AX_NEW_PROJECT_GUIDE.md / AX_SKILL_LIBRARY_GUIDE.md
+├── skill-index.md / skills/<id>/{README.md, skill.json}
+└── templates/{end-of-session-report.md, decision.md, task-row.md}
+.claude/
+├── commands/{handoff, session-close, audit, lazy-detect, update, viewwork-ping}.md
+├── skills/leerness.md
+└── settings.local.json (SessionStart + Stop hooks)
+.cursor/rules/leerness.mdc
+.github/copilot-instructions.md
+AGENTS.md / CLAUDE.md
 ```
 
-## 비파괴 마이그레이션 정책
+## 게으름 방지 (Anti-Lazy)
+
+`anti-lazy-work-policy.md`의 6개 규칙 + `lazy detect` 자동 점검:
+
+1. 증거 없는 완료 금지 (`evidence` 컬럼이 비었거나 plan-link만이면 경고)
+2. 빈 핸드오프 금지
+3. 부분 구현 자기보고 (`incomplete` 표기 + Next Exact Step 1줄)
+4. 검증 기록 누적 (`review-evidence.md`)
+5. 새 TODO/FIXME → progress-tracker에 동일 ID로 추적
+6. 자동 감지: 증거 없는 done, 추적 없는 TODO, blocker 방치, 검증 흔적 부재
+
+## 시크릿/인코딩 자동 가드
 
-Leerness는 마이그레이션 전에 기존 하네스, 스킬, 지침, README, 환경 예시 파일을 `.harness/archive/`에 백업합니다.
+- `scan secrets`: 9개 패턴 (AWS/GitHub PAT/GitHub fine-grained/OpenAI/Anthropic/Google/Slack/PEM private key/하드코딩 password).
+- `encoding check`: BOM, UTF-16 BOM, NUL, .bat의 chcp 65001 누락, 한글 텍스트의 UTF-8 라운드트립.
 
-덮어쓰기 위험이 있는 파일은 다음 정책을 따릅니다.
+## Claude Code 통합
 
-- 프로젝트 메모리 파일은 기본 보존
-- `AGENTS.md`, `CLAUDE.md`, Copilot/Cursor 지침은 새 템플릿과 기존 내용을 병합
-- `.env.example`, `.gitignore`는 기존 내용을 유지하고 필요한 줄만 추가
-- README는 Leerness managed marker 구간만 갱신
-- 작업 결과는 `.harness/migration-report.md`에 기록
+설치 시 자동 등록:
+- `.claude/commands/handoff.md`, `session-close.md`, `audit.md`, `lazy-detect.md`, `update.md`, `viewwork-ping.md`
+- `.claude/skills/leerness.md` — Claude Code 스킬 정의
+- `.claude/settings.local.json` — SessionStart (`update --check`) + Stop (`viewwork emit`) hook
 
-## 주요 명령어
+## 스킬 라이브러리
+
+`leerness skill list` / `leerness skill info <id>` / `leerness skill add <id>`.
+
+기본 카탈로그: `office`, `commerce-api`, `crawling`, `firebase`, `ads-analytics`, `appstore-review`, `ai-verified-skill-publisher`, `feature-implementation`.
+
+## E2E
 
 ```bash
-leerness status .
-leerness verify .
-leerness debug .
-leerness route <task-type>
-leerness session close .
-
-leerness plan show
-leerness plan add "작업명" --status planned
-leerness task list
-leerness task drop T-0001 --reason "사용자 요청으로 제외"
-
-leerness skill list
-leerness skill info commerce-api
-
-leerness consistency check .
-leerness readme sync .
+npm test
+# = node ./scripts/e2e.js
 ```
 
+빈 임시 디렉토리에서 30+개 시나리오 실측 (B1 in-place upsert 회귀 검증 포함).
+
 ## 라이선스
 
-MIT
+MIT.