@graypark/loophaus 3.8.1 → 3.9.0

package/README.ko.md

@@ -10,34 +10,65 @@
   <a href="https://github.com/vcz-Gray/loophaus/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square" alt="license" /></a>
   <img src="https://img.shields.io/badge/node-%3E%3D20-brightgreen.svg?style=flat-square" alt="node version" />
   <img src="https://img.shields.io/badge/platform-Claude%20Code%20%7C%20Codex%20CLI%20%7C%20Kiro%20CLI-purple.svg?style=flat-square" alt="platform" />
-  <img src="https://img.shields.io/badge/tests-296%20passing-brightgreen.svg?style=flat-square" alt="tests" />
+  <img src="https://img.shields.io/badge/tests-359%20passing-brightgreen.svg?style=flat-square" alt="tests" />
 </p>
 
+<h3 align="center">AI 코딩 에이전트를 자율 루프로 실행 — 매 반복마다 신선한 컨텍스트, PRD 기반 진행 추적, 자동 품질 게이트.</h3>
+
 <p align="center">
-  <b>코딩 에이전트를 위한 컨트롤 플레인 — Claude Code, Codex CLI, Kiro CLI에서 동작하는 반복형 개발 루프.</b>
-  <br/>
   <sub><a href="https://ghuntley.com/ralph/">Geoffrey Huntley의 Ralph Wiggum 기법</a> 기반</sub>
 </p>
 
 ---
 
-## 왜 loophaus인가?
+## 문제
+
+AI 코딩 에이전트는 긴 작업에서 어려움을 겪습니다:
+
+- **컨텍스트 부패** — 10회 이상 반복하면 에이전트가 혼란에 빠짐
+- **목표 이탈** — 에이전트가 스펙을 잊고 엉뚱한 문제를 해결
+- **품질 신호 부재** — 에이전트가 "완료"라 하지만 테스트는 여전히 실패
+- **토큰 낭비** — 매번 같은 컨텍스트를 다시 설명해야 함
 
-AI 코딩 에이전트는 다음과 같은 문제를 겪습니다:
+## 해결책
 
-| 문제 | 현상 |
-| --- | --- |
-| **컨텍스트 부패** | 긴 대화가 노이즈를 축적, 에이전트가 혼란에 빠짐 |
-| **체크포인트 없음** | 전부 아니면 전무 — 중단 후 재개 불가 |
-| **학습 손실** | 이전 반복의 인사이트가 새 컨텍스트에 덮어쓰임 |
-| **완료 모호성** | 에이전트가 "완료"라 하지만 테스트는 실패 |
+- **반복마다 신선한 컨텍스트** — 매 사이클마다 디스크에서 PRD + 진행 상황을 읽어, 20회 이상 반복해도 품질 저하 없음
+- **PRD 연동 진행 추적** — `prd.json`에 스토리별 pass/fail 상태 추적, "끝난 것 같다"가 아닌 구조화된 추적
+- **품질 측정과 유지/폐기** — Autoresearch 패턴에서 영감을 받은 개선 루프가 품질(0-100)을 측정하고 퇴보를 되돌림
+- **범용 Stop hook** — 하나의 Node.js hook이 Claude Code, Codex CLI, Kiro CLI 모두에서 동작
+
+## 빠른 시작
 
-loophaus는 이렇게 해결합니다:
+```bash
+npm install -g @graypark/loophaus
+loophaus install
+```
 
-- **반복마다 신선한 컨텍스트** — 매 사이클마다 디스크에서 PRD + 진행 상황을 읽어, 품질 저하 없음
-- **Git 기반 안전장치** — 스토리별 원자적 커밋, 언제든 롤백 가능
-- **추가 전용 학습** — `progress.txt`가 반복을 거듭하며 지식을 축적
-- **테스트 검증 완료** — `<promise>COMPLETE</promise>`가 실제로 참일 때만 종료 가능
+> **참고:** `npx @graypark/loophaus install`은 일부 npm 버전에서 bin 해석 캐시 버그로 실패할 수 있습니다. 위의 글로벌 설치 방식을 권장합니다.
+
+설치기가 호스트(Claude Code, Codex CLI, Kiro CLI)를 자동 감지하고 stop hook, 커맨드, 스킬을 모두 설정합니다.
+
+이후 AI 코딩 세션에서:
+
+```
+/loop-plan JWT, bcrypt, 로그인 UI를 포함한 사용자 인증 추가
+```
+
+그게 전부입니다. 인터뷰가 PRD를 생성하고, 루프를 활성화하고, 스토리별로 구현을 시작합니다.
+
+## 안전장치
+
+- 매 반복마다 **git 체크포인트** 생성 — 언제든 원자적 되돌리기
+- **최대 반복 제한** (기본 20, 설정 가능)
+- **품질 임계값 = 서킷 브레이커** — score < 80이면 개선 또는 중단
+- **비용 추적**과 정책 적용 (최대 $5, 최대 30분)
+- `loophaus clean`으로 데이터 생명주기 관리
+
+## 스크립트로 하면 안 되나요?
+
+1. **신선한 컨텍스트 격리** — 20회 반복 후에도 저하 없음; 매 사이클이 퇴화하는 대화가 아닌 디스크에서 시작
+2. **PRD 연동 진행 추적** — 스토리별 pass/fail이 있는 구조화된 `prd.json`, "끝난 것 같다"가 아님
+3. **품질 측정과 유지/폐기** — autoresearch 패턴: 측정, 개선 유지, 퇴보 되돌리기
 
 ## 동작 원리
 
@@ -72,91 +103,70 @@ AI 에이전트가 연속 루프에서 태스크를 수행합니다. 매 반복
               │                                 │
               │  모든 스토리 통과?               │
               │  → <promise>COMPLETE</promise>  │
+              │                                 │
+              │  /loop-pulse → 상태 확인        │
+              │  /loop-stop  → 언제든 취소      │
               └─────────────────────────────────┘
 ```
 
-## 빠른 시작
-
-```bash
-npm install -g @graypark/loophaus
-loophaus install
-```
-
-> **참고:** `npx @graypark/loophaus install`은 일부 npm 버전에서 bin 해석 캐시 버그로 실패할 수 있습니다. 위의 글로벌 설치 방식을 권장합니다.
-
-이후 AI 코딩 세션에서:
-
-```
-/loop-plan JWT, bcrypt, 로그인 UI를 포함한 사용자 인증 추가
-```
-
-그게 전부입니다. 인터뷰가 PRD를 생성하고, 루프를 활성화하고, 스토리별로 구현을 시작합니다.
-
 ## 커맨드
 
-> **Bauhaus** — 형태는 기능을 따른다.
-
 | 커맨드 | 설명 |
-| --- | --- |
-| `/loop-plan` | 인터뷰 → PRD 생성 → 루프 시작 |
-| `/loop` | 반복 실행 |
-| `/loop-stop` | 루프 중단 |
-| `/loop-pulse` | 상태 확인 |
-
-### `/loop-plan` — 메인 진입점
-
-태스크에 대해 인터뷰하고, 적절한 크기의 스토리로 PRD를 생성하고, 루프를 활성화한 다음 즉시 작업을 시작합니다.
-
-```
-/loop-plan 프론트엔드와 백엔드에 걸친 인증 모듈 리팩토링
-```
-
-**동작 과정:**
-
-1. 3~5개의 타겟 질문 (범위, 검증, 병렬성 등)
-2. 적절한 크기와 순서의 스토리가 포함된 `prd.json` 생성
-3. 반복 추적을 위한 `progress.txt` 작성
-4. Stop hook 활성화 및 US-001 구현 시작
+|---------|-------------|
+| `/loop-plan` | 인터뷰 → PRD 생성 → 루프 활성화 |
+| `/loop` | 직접 반복 실행 (PRD가 이미 있을 때) |
+| `/loop-stop` | 활성 루프 즉시 중단 |
+| `/loop-pulse` | 현재 루프 상태, 반복 횟수, 진행 상황 확인 |
 
-**즉시 실행** — "준비됐나요?" 프롬프트 생략:
-
-```
-/loop-plan 사용자 API에 페이지네이션 추가, 바로 실행
-```
-
-### `/loop` — 직접 루프
-
-이미 PRD가 있거나 직접 프롬프트를 작성하고 싶을 때:
+## Quality Loop (v3.4.0+)
 
-```
-/loop "prd.json 읽기, 다음 스토리 선택, 구현, 검증, 커밋" --max-iterations 20 --completion-promise "COMPLETE"
-```
+v3.4.0에서 도입된 **Quality Loop** — [karpathy/autoresearch](https://github.com/karpathy/autoresearch)의 실험-측정-유지/폐기 패턴을 코드 품질 개선에 적용.
 
-### `/loop-stop` — 중단
+테스트가 통과하면 "완료"로 처리하던 기존 방식 대신, `/loop-plan`이 이제 **품질을 측정**(0-100)하고 임계값을 충족할 때까지 **반복 개선**합니다.
 
 ```
-/loop-stop
+Phase 4: 구현
+     ↓
+Phase 5: 측정 (score 0-100)
+     ↓           ↑
+Phase 6: 개선 루프
+  점수 향상? → 유지 (commit)
+  점수 하락? → 폐기 (git reset)
+  최대 시도 도달? → 다음으로
+     ↓
+Phase 7: 보고서 (품질 점수 포함)
 ```
 
-### `/loop-pulse` — 상태 확인
+| autoresearch | loophaus |
+|-------------|----------|
+| `val_bpb` | quality score (가중치: tests, typecheck, lint, verify, diff, custom) |
+| `results.tsv` | `.loophaus/results.tsv` |
+| keep → advance | 점수 향상 → commit |
+| discard → revert | 점수 하락 → `git reset --hard` |
+| NEVER STOP | 스토리당 최대 3회 시도 (설정 가능) |
 
-현재 루프의 진행 상황, 완료된 스토리 수, 남은 반복 수를 확인합니다.
+### 설정
 
-```
-/loop-pulse
+```json
+{
+  "qualityThreshold": 80,
+  "maxRefineAttempts": 3,
+  "qualityConfig": {
+    "weights": { "tests": 30, "typecheck": 25, "lint": 15, "verify": 15, "diff": 10, "custom": 5 }
+  }
+}
 ```
 
 ## 플랫폼 지원
 
-loophaus는 세 개의 주요 코딩 에이전트 플랫폼을 지원합니다:
+| | Claude Code | Codex CLI | Kiro CLI |
+|---|---|---|---|
+| **Stop Hook** | Node.js | Node.js | Node.js |
+| **설치 대상** | Plugin cache | `hooks.json` | `agents/` + `steering/` |
+| **커맨드** | `/reload-plugins` | native | steering manual mode |
+| **멀티 에이전트** | Agent tool | subprocesses | steering agents |
 
-| 기능 | Claude Code | Codex CLI | Kiro CLI |
-| --- | --- | --- | --- |
-| 자동 감지 설치 | `~/.claude/` | `~/.codex/` | `~/.kiro/` |
-| Stop hook | Node.js 기반 | Node.js 기반 | Node.js 기반 |
-| 루프 실행 | Skill tool | 네이티브 커맨드 | 네이티브 커맨드 |
-| 멀티 에이전트 | Agent tool | 서브에이전트 | 서브에이전트 |
-| 상태 파일 | `.loophaus/state.json` | `.loophaus/state.json` | `.loophaus/state.json` |
+세 플랫폼 모두 같은 코어 엔진(`core/engine.ts`)과 상태 저장소(`store/state-store.ts`)를 공유합니다. 플랫폼별 어댑터가 차이를 처리합니다.
 
 Windows에서도 PowerShell/CMD 기준으로 `install`, `upgrade`, `/loop` 초기화가 동작합니다. Git Bash나 WSL은 선택사항입니다.
 
@@ -181,94 +191,32 @@ npx @graypark/loophaus install
 
 ### 호스트별 설치
 
-특정 호스트만 대상으로 설치:
-
 ```bash
-loophaus install --claude              # Claude Code만
-loophaus install --host codex-cli      # Codex CLI만
-loophaus install --kiro                # Kiro CLI만
+loophaus install --host claude-code
+loophaus install --host codex-cli
+loophaus install --host kiro-cli
 ```
 
+### 플래그
+
 | 플래그 | 설명 |
-| --- | --- |
-| `--host <name>` | 특정 호스트 대상 지정 |
-| `--claude` | `--host claude-code` 축약형 |
-| `--kiro` | `--host kiro-cli` 축약형 |
-| `--local` | 프로젝트 로컬 `.codex/`에 설치 (Codex만) |
-| `--dry-run` | 변경 없이 미리보기 |
+|------|-------------|
 | `--force` | 기존 파일 덮어쓰기 |
-
-<details>
-<summary>설치되는 항목</summary>
-
-```
-~/.codex/                          # (또는 ~/.claude/, ~/.kiro/)
-├── plugins/loophaus/              # 핵심 플러그인 파일
-├── hooks.json                     # Stop hook (기존 설정과 병합)
-└── skills/
-    ├── loop/                      # /loop — 루프 실행
-    ├── loop-plan/                 # /loop-plan — PRD 생성 + 루프 시작
-    ├── loop-stop/                 # /loop-stop — 루프 중단
-    └── loop-pulse/                # /loop-pulse — 상태 확인
-```
-
-</details>
+| `--dry-run` | 변경 없이 미리보기 |
+| `--local` | 프로젝트 로컬 설치 (Codex CLI만) |
 
 ## CLI
 
 ```bash
-loophaus install     # 자동 감지 설치
-loophaus status      # 설치 상태 확인
-loophaus stats       # 루프 실행 통계
-loophaus quality     # 품질 점수 측정
-loophaus uninstall   # 제거
-loophaus --version   # 버전 확인
-```
-
-## Quality Loop (v3.4.0+)
-
-v3.4.0에서 도입된 **Quality Loop** — [karpathy/autoresearch](https://github.com/karpathy/autoresearch)의 실험→측정→유지/폐기 패턴을 코드 품질 개선에 적용.
-
-테스트가 통과하면 "완료"로 처리하던 기존 방식 대신, `/loop-plan`이 이제 **품질을 측정**(0-100)하고 임계값을 충족할 때까지 **반복 개선**합니다.
-
-```
-Phase 4: 구현
-     ↓
-Phase 5: 측정 (score 0-100)
-     ↓           ↑
-Phase 6: 개선 루프
-  점수 향상? → 유지 (commit)
-  점수 하락? → 폐기 (git reset)
-  최대 시도 도달? → 다음으로
-     ↓
-Phase 7: 보고서 (품질 점수 포함)
-```
-
-| autoresearch | loophaus |
-|-------------|----------|
-| `val_bpb` | quality score (가중치: tests, typecheck, lint, verify, diff, custom) |
-| `results.tsv` | `.loophaus/results.tsv` |
-| keep → advance | 점수 향상 → commit |
-| discard → revert | 점수 하락 → `git reset --hard` |
-| NEVER STOP | 스토리당 최대 3회 시도 (설정 가능) |
-
-### 설정
-
-```json
-{
-  "qualityThreshold": 80,
-  "maxRefineAttempts": 3,
-  "qualityConfig": {
-    "weights": { "tests": 30, "typecheck": 25, "lint": 15, "verify": 15, "diff": 10, "custom": 5 }
-  }
-}
-```
-
-### CLI
-
-```bash
-loophaus quality                # 전체 스토리 품질 측정
-loophaus quality --story US-001 # 특정 스토리 품질 측정
+loophaus install          # 자동 감지 설치
+loophaus status           # 설치 상태 확인
+loophaus stats            # 루프 실행 통계
+loophaus quality          # 품질 점수 측정
+loophaus demo             # 대화형 데모 실행
+loophaus config           # 설정 확인/수정
+loophaus update-check     # 새 버전 확인
+loophaus upgrade          # 최신 버전으로 업그레이드
+loophaus uninstall        # 제거
 ```
 
 ## 아키텍처
@@ -276,41 +224,41 @@ loophaus quality --story US-001 # 특정 스토리 품질 측정
 ```
 loophaus/
 ├── bin/
-│   ├── loophaus.ts                   # CLI 진입점
-│   ├── install.ts                    # 크로스 플랫폼 설치기
-│   └── uninstall.ts                  # 제거기
+│   ├── loophaus.ts               # CLI 진입점
+│   ├── install.ts                # 크로스 플랫폼 설치기
+│   └── uninstall.ts              # 제거기
 ├── core/
-│   ├── types.ts                      # 공유 TypeScript 인터페이스
-│   ├── engine.ts                     # 핵심 루프 엔진
-│   ├── event-logger.ts              # 이벤트 추적
-│   ├── quality-scorer.ts            # 품질 측정 (점수, 평가, 로깅)
-│   ├── refine-loop.ts               # 유지/폐기 개선 로직
-│   ├── validate.ts                  # PRD + 상태 스키마 검증
-│   ├── policy.ts                    # 루프 정책 평가
-│   ├── cost-tracker.ts              # 토큰 비용 추정
-│   ├── trace-analyzer.ts            # 트레이스 분석 + 비교
-│   ├── worktree.ts                  # Git 워크트리 관리
-│   ├── merge-strategy.ts            # 병렬 머지 전략
-│   ├── parallel-runner.ts           # 멀티 워크트리 오케스트레이션
-│   ├── session.ts                   # 체크포인트 / 세션 관리
-│   └── loop-registry.ts             # 멀티 루프 레지스트리
+│   ├── types.ts                  # 공유 TypeScript 인터페이스
+│   ├── engine.ts                 # 핵심 루프 엔진
+│   ├── event-logger.ts           # 이벤트 추적
+│   ├── quality-scorer.ts         # 품질 측정 (점수, 평가, 로깅)
+│   ├── refine-loop.ts            # 유지/폐기 개선 로직
+│   ├── validate.ts               # PRD + 상태 스키마 검증
+│   ├── policy.ts                 # 루프 정책 평가
+│   ├── cost-tracker.ts           # 토큰 비용 추정
+│   ├── trace-analyzer.ts         # 트레이스 분석 + 비교
+│   ├── worktree.ts               # Git 워크트리 관리
+│   ├── merge-strategy.ts         # 병렬 머지 전략
+│   ├── parallel-runner.ts        # 멀티 워크트리 오케스트레이션
+│   ├── session.ts                # 체크포인트 / 세션 관리
+│   └── loop-registry.ts          # 멀티 루프 레지스트리
 ├── store/
-│   └── state-store.ts               # 루프 상태 저장소
+│   └── state-store.ts            # 루프 상태 저장소
 ├── lib/
-│   ├── paths.ts                     # 크로스 플랫폼 경로
-│   └── stop-hook-core.ts            # 테스트 가능한 hook 로직
+│   ├── paths.ts                  # 크로스 플랫폼 경로
+│   └── stop-hook-core.ts         # 테스트 가능한 hook 로직
 ├── platforms/
-│   ├── claude-code/installer.mjs    # 플러그인 캐시 설치기
-│   ├── codex-cli/installer.mjs      # hooks.json 설치기
-│   └── kiro-cli/installer.mjs       # agents/ + steering/ 설치기
+│   ├── claude-code/installer.mjs # 플러그인 캐시 설치기
+│   ├── codex-cli/installer.mjs   # hooks.json 설치기
+│   └── kiro-cli/installer.mjs    # agents/ + steering/ 설치기
 ├── hooks/
-│   └── stop-hook.mjs                # 범용 Stop hook (Node.js)
-├── commands/                        # 슬래시 커맨드 정의
-├── skills/                          # 플랫폼별 스킬 정의
+│   └── stop-hook.mjs             # 범용 Stop hook (Node.js)
+├── commands/                     # 슬래시 커맨드 정의
+├── skills/                       # 플랫폼별 스킬 정의
 ├── .claude-plugin/
-│   └── plugin.json                  # Claude Code 마켓플레이스 매니페스트
-├── dist/                            # 컴파일 출력 (tsc)
-└── tests/                           # 296개 테스트 케이스 (vitest)
+│   └── plugin.json               # Claude Code 마켓플레이스 매니페스트
+├── dist/                         # 컴파일 출력 (tsc)
+└── tests/                        # 359개 테스트 케이스 (vitest)
 ```
 
 ## PRD 포맷
@@ -340,33 +288,7 @@ loophaus는 `prd.json` 포맷을 사용합니다:
 }
 ```
 
-각 스토리는 **한 번의 반복**(하나의 컨텍스트 윈도우)에서 완료할 수 있는 크기입니다. 의존성은 priority 순으로 정렬됩니다.
-
-## 멀티 에이전트 오케스트레이션
-
-여러 서비스에 걸치거나 광범위한 탐색이 필요한 태스크에 사용합니다:
-
-```
-Phase 1 — 병렬 스캔 (3 에이전트):
-├── 에이전트 "fe-scan": frontend/** 인증 취약점 탐색
-├── 에이전트 "be-scan": backend/** 인증 취약점 탐색
-└── 에이전트 "db-scan": 스키마의 누락된 제약조건 검토
-
-Phase 2 — 순차 수정 (루프):
-└── 병합된 발견사항 읽기 → 스토리별로 수정 구현
-```
-
-인터뷰 과정에서 병렬성 잠재력을 점수 매트릭스로 자동 평가합니다.
-
-5가지 오케스트레이션 패턴:
-
-| 패턴 | 사용 시점 |
-| --- | --- |
-| 병렬 탐색 → 순차 구현 | 대규모 코드베이스 조사 후 수정 |
-| 소유권 분할 | 멀티 서비스 변경 (fe + be + auth) |
-| Fan-Out / Fan-In | 병렬 감사 (보안 + 성능 + 접근성) |
-| 정찰 후 실행 | 익숙하지 않은 코드베이스 |
-| 체크포인트가 있는 파이프라인 | 다단계 변환 |
+각 스토리는 **한 번의 반복**(하나의 컨텍스트 윈도우)에서 완료할 수 있는 크기입니다. 의존성은 priority 순으로 정렬됩니다. 루프 엔진이 `passes`가 `false`인 다음 스토리를 선택해 검증이 성공할 때까지 작업합니다.
 
 ## 업데이트
 
@@ -391,10 +313,13 @@ npm uninstall -g @graypark/loophaus
 ## 개발
 
 ```bash
-npm install && npm test
-npm run typecheck          # TypeScript strict 모드
-npm run build              # dist/로 컴파일
-npx vitest                # watch 모드
+git clone https://github.com/vcz-Gray/loophaus.git
+cd loophaus
+npm install
+npm test               # 359개 테스트
+npm run typecheck      # TypeScript strict 모드
+npm run build          # dist/로 컴파일
+npx vitest             # watch 모드
 ```
 
 ## 라이선스