leerness 1.7.0 → 1.9.0

package/CHANGELOG.md

@@ -0,0 +1,76 @@
+# Changelog
+
+## 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,132 +1,123 @@
 # Leerness
 
-Leerness는 AI 에이전트가 프로젝트의 목표, 계획, 작업 상태, 기술 결정, 디자인/기능 일관성, 검증된 스킬을 유지하며 개발하도록 돕는 AX 최적화 개발 하네스입니다.
+> 한국어 우선 AI 개발 하네스. 비파괴 마이그레이션 / 자동 버전 감지·업데이트 / 계획·진행·핸드오프 자동화 / 게으름·시크릿·인코딩 자동 가드 / Claude Code 슬래시 통합.
 
-## 주요 기능
-
-- `plan.md` 기반 전체 계획과 범위 관리
-- `progress-tracker.md` 기반 사용자 요청 단위 상태 추적
-- `context-routing.md` 기반 작업 유형별 참조 파일 안내
-- `writeback-policy.md` 기반 작업 후 문서 갱신 규칙
-- `session close` 기반 세션 종료 인수인계와 미완료 작업 노출
-- `protected-files.md` 기반 `.harness/` 및 핵심 문서 삭제 방지
-- `design-system.md`, `consistency-policy.md`, `reuse-map.md` 기반 디자인/기능 일관성 유지
-- `readme sync` 기반 루트 `README.md` Leerness 관리 섹션 최신화
-- 한글명과 가능한 작업이 표시되는 스킬 라이브러리
-- AI 검증 스킬 업로드를 위한 토큰 게이트와 dry-run 우선 정책
-
-## 설치
+## 빠르게 시작
 
 ```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
-npx leerness init --language en
-npx leerness init --language auto
-```
-
-추천 스킬 포함:
+## 핵심 명령
 
 ```bash
-npx leerness init --skills recommended
+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
-leerness status .
-leerness verify .
-leerness debug .
-leerness route planning
-leerness route consistency
-leerness session close .
-```
+## 자동 버전 감지·업데이트
 
-계획 관리:
+`init`/`migrate`가 끝나면 `.claude/settings.local.json`의 SessionStart hook에 `leerness update --check`이 자동 등록됩니다 (`--no-auto-update`로 끄기 가능). 24시간 캐시(`.harness/cache/update-check.json`)로 npm 호출 폭주를 막습니다.
 
-```bash
-leerness plan show
-leerness plan init --goal "프로젝트 목적"
-leerness plan add "결제 기능 구현" --status planned
-leerness plan drop "관리자 대시보드" --reason "이번 버전 범위 제외"
-leerness plan progress
-leerness plan sync
-```
+| 명령 | 동작 |
+|---|---|
+| `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 호출 건너뜀 |
 
-작업 추적:
+## 비파괴 마이그레이션 정책
 
-```bash
-leerness task list
-leerness task add "사용자 요청" --status requested
-leerness task update T-0001 --status in-progress
-leerness task drop T-0001 --reason "사용자가 제외"
-```
+- 모든 변경 전에 `.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`.
 
-README 동기화:
+## 디렉토리 구조
 
-```bash
-leerness readme sync .
+```
+.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)
 
-```bash
-leerness consistency check .
-leerness consistency merge-design-guide .
-```
+`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 방치, 검증 흔적 부재
 
-```bash
-leerness skill list
-leerness skill info commerce-api
-leerness skill add ai-verified-skill-publisher --path .
-```
+## 시크릿/인코딩 자동 가드
 
-최신 버전 확인:
+- `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 라운드트립.
 
-```bash
-leerness self check .
-```
+## Claude Code 통합
 
-## 생성 구조
+설치 시 자동 등록:
+- `.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
 
-```text
-.harness/
-  plan.md
-  progress-tracker.md
-  guideline.md
-  plan-progress-boundary.md
-  project-brief.md
-  current-state.md
-  context-routing.md
-  writeback-policy.md
-  protected-files.md
-  consistency-policy.md
-  design-system.md
-  reuse-map.md
-  session-close-policy.md
-  anti-lazy-work-policy.md
-  leerness-maintenance.md
-  skills/
-  library/
-  archive/
-```
+## 스킬 라이브러리
 
-## 계획과 진행률의 역할 분리
+`leerness skill list` / `leerness skill info <id>` / `leerness skill add <id>`.
 
-- `plan.md`: 프로젝트 목표, 범위, milestone, 제외/드랍 항목, 계획 변경 이력
-- `progress-tracker.md`: 사용자 요청 단위 상태, 증거, 다음 액션
-- `guideline.md`: 계획과 진행률을 어떻게 따라야 하는지에 대한 실행 기준
+기본 카탈로그: `office`, `commerce-api`, `crawling`, `firebase`, `ads-analytics`, `appstore-review`, `ai-verified-skill-publisher`, `feature-implementation`.
 
-## 보호 정책
+## E2E
+
+```bash
+npm test
+# = node ./scripts/e2e.js
+```
 
-AI 에이전트는 `.harness/`, `AGENTS.md`, `CLAUDE.md`, `.cursor/rules/leerness.mdc`, `.github/copilot-instructions.md`, 루트 `README.md`의 Leerness 관리 섹션을 임의 삭제하거나 초기화하지 않아야 합니다. 정리가 필요하면 삭제보다 병합, 아카이브, deprecated 표시를 우선합니다.
+빈 임시 디렉토리에서 30+개 시나리오 실측 (B1 in-place upsert 회귀 검증 포함).
 
 ## 라이선스
 
-MIT
+MIT.