@tuzi-ince/hi-loop 0.2.1 → 0.3.0

package/README.md

@@ -4,26 +4,44 @@
 
 날것의 아이디어(goal)를 던지면, AI 에이전트를 PDCA 루프로 반복 구동해
 **테스트가 실제로 통과할 때까지** 스스로 고쳐 나간다.
+
 - 요구사항(무엇을): [`docs/spec.md`](docs/spec.md)
 - 설계(어떻게·왜): [`docs/design.md`](docs/design.md)
 - 배포·설치·사용: [`docs/guide.md`](docs/guide.md)
 
-> 현재 상태: 실제 `claude`(2.1.212) 와의 통합 **검증 완료** — 편집 권한, 세션 재개,
-> 전체 루프, 예산 상한을 실측했다([`docs/design.md`](docs/design.md) §10).
-> 아직 안 본 것도 그 표에 적어뒀다(핸드오프 실측, MCP 모드 실제 spawn, 10회 장시간 루프).
+## 루프 엔지니어링 — 우리의 개발 철학
+
+이 엔진은 "AI가 코드를 잘 짜준다"에 기대지 않는다. AI는 자주 틀리고, 더 자주
+**틀린 것을 다 됐다고 말한다.** 그래서 우리는 모델의 자기보고를 판정에서 배제하고,
+기계가 검증할 수 있는 종료 조건 위에 루프를 세운다. 세 문장이 전부다.
+
+1. **산문은 요청이고, 메커니즘은 사실이다.**
+   보고서에 "이건 검증 안 됨"이라고 적는 것은 요청일 뿐이다. 한 번 더 돌려서 측정하면
+   그 문장이 사실이 된다. 그래서 이 엔진은 문장을 늘리기보다 검사를 하나 더 돌린다.
+2. **에이전트의 "다 됐어요"는 판정이 아니다.**
+   성패는 언제나 `testCommand`의 exit code다. 엔진이 직접 실행해서 확인한다.
+3. **종료 조건 없는 단계는 엔진의 단계가 아니라 문서 생성기다.**
+   모든 단계는 기계가 판정할 통과 기준을 가진다. 없으면 그 단계는 만들지 않는다.
+
+이 세 원칙에서 뒤의 [안전장치](#안전장치--루프-엔지니어링-원칙)들이 전부 파생된다.
 
 ## 설치
 
-> ⚠️ `npm install -g handoff` 를 하지 마라. npm 의 `handoff` 는 이 프로젝트와 무관한
-> **제3자의 redis 래퍼 패키지**다. 이름만 같다. 아직 미배포이므로 소스에서 설치한다.
+```bash
+# 1) 전역 설치 — hi-loop / hi-loop-setup 명령 등록
+npm install -g @tuzi-ince/hi-loop
+
+# 2) 프로젝트에 주입 (멱등 — 여러 번 돌려도 안전)
+cd /path/to/my-project
+hi-loop-setup            # .mcp.json / .gitignore / docs / tests 자동 주입
+```
+
+소스에서 개발용으로 설치하려면:
 
 ```bash
 git clone <이 저장소> hi-loop && cd hi-loop
-npm install && npm test   # 104개 통과
+npm install && npm test   # node:test, devDependency 0개
 npm link                  # hi-loop / hi-loop-setup 명령 등록
-
-cd /path/to/my-project
-hi-loop-setup            # .mcp.json / .gitignore / docs / tests 자동 주입 (멱등)
 ```
 
 자세한 절차·문제해결·배포는 [`docs/guide.md`](docs/guide.md).
@@ -51,30 +69,22 @@ CHECK ──► 엔진이 testCommand 를 직접 실행 (에이전트의 "다
 ACT   ──► stderr 를 그대로 에이전트에 들이밀고 "이 에러를 고쳐라" (최대 10회)
 ```
 
-## 전과정 라이프사이클 (`--full`)
-
-기본은 위의 자가 치유 루프 하나다. `--full` 을 붙이면 앞뒤 단계까지 돈다.
+기본은 이 자가 치유 루프 하나다. `--full` 을 붙이면 앞뒤 단계까지 돈다.
 
 ```
-DISCOVER → PLAN → DESIGN_REVIEW → DO ⇄ CHECK ⇄ HEAL → CODE_REVIEW → SHIP → WATCH → DONE
-             ▲          │                                   │                  │
-             └── reject ┘                          reject ──┘        fail ─────┘
-```
-
-```bash
-# 아이디어 한 줄 → 발굴 → 스펙 → 구현 → 리뷰 → 배포 → 감시. 사람 개입 최소.
-hi-loop run --goal "JWT 인증 미들웨어" --full \
-  --ship "npm publish --access public" \
-  --watch "curl -f https://api.example.com/health" --watch-for 5m
+DISCOVER → PLAN → DESIGN_REVIEW → BUILD(DO ⇄ CHECK ⇄ HEAL) → CODE_REVIEW → SHIP → WATCH → DONE
+             ▲          │                                          │                │
+             └── reject ┘                                 reject ──┘       fail ────┘
 ```
 
-**추가되는 모든 단계는 기계가 판정할 종료 조건을 가진다.** 없으면 그건 엔진의 단계가
-아니라 문서 생성기다.
+**추가되는 모든 단계는 기계가 판정할 종료 조건을 가진다.**
 
 | 단계 | 무엇을 하는가 | 종료 조건 |
 |---|---|---|
 | DISCOVER | goal 의 모호함을 **가정으로 확정**하고 문서화 | 가정 목록 확정 |
+| PLAN | 스펙 + 테스트를 먼저 쓴다 (구현 금지) | 산출물 작성 |
 | DESIGN_REVIEW | 구현 착수 **전** 스펙을 심판 | 독립 검증자 pass |
+| BUILD | DO ⇄ CHECK ⇄ HEAL 자가 치유 루프 | testCommand exit 0 |
 | CODE_REVIEW | diff 를 정확성·보안·YAGNI 축으로 심판 | 독립 검증자 pass |
 | SHIP | 배포 명령 실행 | **exit code 0** |
 | WATCH | 헬스체크 반복 | 지정 시간 동안 버팀 |
@@ -82,106 +92,287 @@ hi-loop run --goal "JWT 인증 미들웨어" --full \
 배포·감시는 **에이전트를 부르지 않는다.** "배포했다고 모델이 말했다"가 아니라
 "헬스체크 exit code 가 0이다"가 통과 조건이다. 그래서 이 두 단계의 비용은 0이다.
 
-### 기본은 무중단, 필연적 선택에서만 묻는다
+---
 
-리뷰 단계들은 **모델이 심판하고 엔진이 되돌린다.** 사람을 안 부른다 —
-설계 리뷰가 기각하면 PLAN 을 다시 쓰고, 코드 리뷰가 기각하면 그 지적이 HEAL 의 연료가 된다.
+# 실전 활용 가이드 (프로젝트 관리 관점)
 
-사람이 멈춰 서는 곳은 둘뿐이다:
-1. DISCOVER 가 **상호배타 분기**를 만났을 때 (가정으로 답할 수 없는 지점)
-2. SHIP 직전 (비가역 외부 행위. `--yes` 로 생략)
+무엇을 하려는지에 따라 **어떻게 goal을 쓰고 어떤 플래그를 켜는지**가 달라진다.
+아래는 실제 프로젝트를 굴리며 자주 만나는 상황별 레시피다.
 
+## 1. 프로젝트 생성 — 아이디어 한 줄 → 동작하는 코드
+
+모호한 요구를 발굴부터 구현·리뷰까지 한 번에 돌린다. `--full` 이 앞뒤 단계를 켠다.
+
+```bash
+hi-loop run --goal "JWT 인증 미들웨어를 만들어라" --full --budget-usd 5
 ```
-$ hi-loop run --goal "..." --full
-  ⏸ 선택이 필요합니다 [DISCOVER]
-     인증 저장소를 어디에 둘까?
-     a) 기존 users 테이블 확장     — 마이그레이션 필요
-     b) 별도 auth_tokens 테이블 신규 — 조인 비용
-  → hi-loop answer <a|b> [--note "..."]
-
-$ hi-loop answer a          # 고른 것도 "가정"으로 기록돼 이후 프롬프트에 실린다
+
+- **DISCOVER** 가 goal의 빈칸(토큰 저장 위치, 만료 정책 등)을 가정으로 확정하고 문서화한다.
+- **PLAN** 이 스펙과 테스트를 먼저 쓴다 — 구현보다 판정 기준이 앞선다.
+- **DESIGN_REVIEW → BUILD → CODE_REVIEW** 순으로 만들고, 만든 것을 스스로 심판한다.
+- 상호배타 분기(예: "users 확장 vs auth_tokens 신설")를 만나면 거기서만 사람에게 묻는다.
+
+**기존 파일을 덮어쓰지 않는다.** `docs/spec.md` / `tests/app.test.js` 가 비어 있으면 그대로
+쓰고, 이미 뭔가 있으면 goal 해시로 비켜간다(`docs/spec-5d88cc7f.md`). 같은 프로젝트에서
+goal만 바꿔 여러 번 돌려도 앞의 산출물이 살아남는다.
+
+> 발굴 단계만 먼저 돌려 요구사항을 확정하고 싶다면:
+> ```bash
+> hi-loop discover --goal "..."   # 가정 확정 + 문서만, 구현은 안 함
+> ```
+
+## 2. 프로젝트 개선 — 기존 코드베이스 손질
+
+리팩터링·성능 개선·기술부채 정리처럼 **이미 테스트가 있는 코드**를 고칠 때.
+기존 테스트를 가드레일로 두고, 스펙 대비 검증을 더 얹는다.
+
+```bash
+hi-loop run --goal "결제 모듈의 중복 검증 로직을 하나로 합쳐라" \
+  --test "npm test" \
+  --verify-spec
 ```
 
-차단형 입력을 쓰지 않고 **상태를 저장하고 종료**한다(exit 3). 그래서 MCP·백그라운드
-데몬·텔레그램 봇에서도 그대로 성립한다. MCP 에서는 호스트 LLM 이 질문을 사용자에게
-제시하고 `hiloop_answer` 로 답을 돌려준다.
+- 기존 `npm test` 가 회귀 방지선이다 — 개선하다 무언가 깨면 Tier 1에서 걸린다.
+- `--verify-spec` 은 테스트 통과 **후** 별도 검증자가 스펙 대비 구현을 심판한다.
+  구조가 아니라 **의도**를 본다("리팩터링했다"는데 동작이 달라졌으면 기각).
+- 개선 중 락파일·설정·마이그레이션을 건드리면 보고서 Gaps에 ⚠️로 공개된다
+  (→ [영향도 분석](#4-영향도-분석--변경-위험-파악)).
 
-`--ask never` 면 분기에서도 안 멈춘다(CI·봇용). 대신 **미해결이라는 사실이 Gaps 에 남는다.**
+## 3. 장애 분석 — 버그·회귀 재현 → 수정
 
-### 단계별로 따로 부를 수도 있다
+버그를 "고쳤다"가 아니라 "재현 테스트로 못박고 고쳤다"로 끝낸다. 회귀 방지가 공짜로 남는다.
+
+```bash
+hi-loop run --goal "재현 테스트를 먼저 작성하고, 동시 요청 시 잔액이 음수가 되는 버그를 고쳐라" \
+  --test "npm test" \
+  --stagnation 3
+```
+
+- PLAN이 **실패하는 재현 테스트**를 먼저 강제한다 → 버그가 테스트로 고정된다.
+- HEAL이 실제 stderr를 연료로 삼아 고친다. 모델의 추측이 아니라 진짜 에러를 본다.
+- **같은 벽에 열 번 부딪히지 않는다**: 같은 실패가 3회 연속이면 `stagnated` 로 조기 종료한다
+  — "이 접근으론 안 된다"를 `--max-loops` 소진 전에 잡는다. `--no-stagnation` 으로 끈다.
+- 에이전트가 멀쩡한 코드를 오히려 망가뜨렸으면 되돌린다:
+  ```bash
+  hi-loop rollback            # 최신 체크포인트로 파일 복원
+  hi-loop rollback --to 3     # 3회차 직전 상태로
+  ```
+
+## 4. 영향도 분석 — 변경 위험 파악
+
+이 변경이 **어디까지 번지는가**를 두 층위로 잡는다.
+
+**(a) 블라스트 반경 — 자동, 비용 0.** 실행이 위험 분류 파일을 건드리면 판정과 무관하게
+보고서 Gaps에 ⚠️로 공개한다. 분류: 의존성(lock/package.json), 스키마 마이그레이션,
+CI·배포 설정, 빌드·러너 설정, 환경 변수. "테스트는 통과했는데 왜 락파일이 바뀌었지"를
+사람이 놓치지 않게 한다.
+
+**(b) 조건부 검사 — 바뀐 파일에 따라 게이트를 켠다.** 무거운 검사(e2e 등)를 매 회차 돌리는
+대신, 특정 경로가 바뀐 회차에만 돌린다.
+
+```bash
+hi-loop run --goal "..." \
+  --check "npm test" \
+  --check "npm run typecheck" \
+  --check "npx playwright test" --when "src/ui/**"
+```
+
+- 검사는 **short-circuit 하지 않는다.** 유닛이 깨져도 typecheck·e2e 결과를 같은 회차에 다 본다
+  (`&&` 로 이으면 첫 실패에서 멈춰 나머지를 영영 모른다).
+- `--when` 글롭에 안 맞은 검사는 **건너뜀으로 기록**된다 — 안 돌린 것이 통과처럼 보이지 않게
+  Gaps에 남는다.
+
+**diff만 리뷰하고 싶다면** — 지금 워킹트리 변경분을 정확성·보안·YAGNI 축으로 심판:
+
+```bash
+hi-loop review              # 현재 변경분만 코드 리뷰 (구현/배포는 안 함)
+```
+
+## 5. 테스트·품질 게이트
+
+**테스트 설계만** 뽑고 싶을 때 (구현은 사람이 하거나 나중에):
+
+```bash
+hi-loop plan --goal "장바구니 할인 규칙"   # 스펙 + 테스트까지만, 구현 전
+```
+
+**플레이키(불안정) 테스트를 걸러내고 싶을 때:**
+
+```bash
+hi-loop run --goal "..." --flaky-probe
+```
+
+- 통과한 회차에서만 같은 테스트를 **한 번 더** 돌린다. 두 번의 결과가 갈리면 통과로 인정하지
+  않는다("두 번 돌려 갈리는 초록불은 초록불이 아니다"). 에이전트 호출 0 — 비용은 테스트 한 번뿐.
+
+**여러 게이트를 한 판정에 묶고 싶을 때** — 위 [조건부 검사](#4-영향도-분석--변경-위험-파악)의
+`--check` 를 여러 번 준다. lint·typecheck·유닛·e2e를 각각 독립된 게이트로 세운다.
+
+## 6. 배포 & 감시 — 사람 개입 최소
+
+리뷰를 통과한 변경을 배포하고, 배포 후 일정 시간 헬스체크로 버티는지 지켜본다.
+
+```bash
+hi-loop run --goal "..." --full \
+  --ship "npm publish --access public" \
+  --watch "curl -f https://api.example.com/health" --watch-for 5m
+```
+
+- `--ship` 을 주면 리뷰 단계들이 **자동으로 켜진다** ("리뷰 없는 자동 배포는 위험하다"의
+  근거가 여기서만 성립).
+- SHIP/WATCH는 에이전트를 부르지 않는다 — 통과 조건은 오직 exit code다.
+- 실패 대응을 지정할 수 있다: `--on-ship-fail stop|heal`, `--on-watch-fail stop|rollback|heal`.
+- 비가역 배포 직전에는 사람에게 확인을 구한다. CI·봇에서는 `--yes` 로 생략.
+
+## 7. 단계별로 따로 부르기
+
+전체를 한 번에 돌리지 않고, 필요한 구간만 실행할 수 있다. 어느 경로로 들어와도 **같은 상태
+머신**을 쓴다.
 
 ```bash
 hi-loop discover --goal "..."     # 발굴만 (가정 확정 + 문서)
-hi-loop plan --goal "..."         # 스펙·테스트까지만 (구현 전)
+hi-loop plan     --goal "..."     # 스펙·테스트까지만 (구현 전)
 hi-loop review                    # 현재 변경분만 코드 리뷰
-hi-loop ship --ship "npm publish" # 배포 단계만
-hi-loop watch --watch "curl -f ..."
+hi-loop ship     --ship "npm publish"
+hi-loop watch    --watch "curl -f ..."
 ```
 
-어느 경로로 들어와도 **같은 상태 머신**을 쓴다. 후반 단계는 `--goal` 을 다시 안 받는다 —
-저장된 상태에서 읽는다(한 글자만 달라도 새 루프로 인식돼 진행 상황이 버려지기 때문).
+또는 `--start-from` / `--stop-after` 로 한 실행의 구간을 자른다:
 
-### 왜 기본값이 "꺼짐"인가
+```bash
+hi-loop run --goal "..." --start-from BUILD --stop-after CODE_REVIEW
+```
+
+> 후반 단계는 `--goal` 을 다시 받지 않는다 — 저장된 상태에서 읽는다(goal이 한 글자만 달라도
+> 새 루프로 인식돼 진행 상황이 버려진다). PLAN은 BUILD 안쪽의 회차라 `--start-from` 대상이
+> 아니다 — BUILD로 시작하면 자연히 PLAN부터 돈다.
 
-새 단계는 각각 에이전트 호출을 1회씩 더한다. 전역 기본 ON 으로 하면 업데이트만 한
-기존 사용자의 실행 비용이 조용히 는다. 그래서:
+## 8. MCP에서 팀으로 쓰기 (클로드코드/커서)
 
-- 플래그가 없으면 **종전 그대로** 자가 치유 루프 하나만 돈다.
-- `--full` → 발굴·설계리뷰·코드리뷰 켜짐.
-- `--ship` → 리뷰들만 자동 켜짐 ("리뷰 없는 자동 배포가 위험하다"는 근거가 여기서만 성립).
-- `--review/--no-review`, `--design-review/--no-design-review`, `--discover/--no-discover`
-  가 위 자동을 양방향으로 덮는다.
+`hi-loop mcp` 로 띄우면 호스트 LLM이 위 시나리오를 도구로 호출한다. 차단형 입력을 쓰지 않고
+**상태를 저장하고 종료**하므로(exit 3) 대화형 세션·백그라운드 데몬·봇에서 그대로 성립한다.
 
-### 세션 핸드오프 & 컨텍스트 다이어트 (bkit 철학)
+```
+호스트 LLM ──hiloop_run──► 루프 구동
+           ◄──분기 질문─── (상호배타 선택 필요)
+           ──hiloop_answer──► 사람의 선택을 "가정"으로 기록하고 재개
+           ──hiloop_status──► 진행/비용/Gaps 조회
+```
 
-에이전트는 같은 세션에서 오래 굴릴수록 토큰이 쌓여 멍청해진다.
-그래서 4회마다 세션을 **버리고**, `.agent-state.json`에 압축된 상태
-(goal / 스펙 요약 / 마지막 에러 / 최근 이력 5건)만 새 세션에 넘겨 이어서 작업한다(auto-resume).
-같은 goal로 다시 실행하면 중단 지점부터 재개한다.
+## 9. 코드 어시스턴트가 요청을 처리하는 방식 — 직접 호출 vs 평문 요청
 
-### TDD 자가 치유 (MoAI 철학)
+클로드코드·커서 같은 코드 어시스턴트(호스트 LLM) 안에서 hi-loop은 두 갈래로 불린다.
+**핵심은 "LLM이 요청을 읽는 순간, hi-loop을 떠올릴 근거가 눈앞에 있느냐"** 다.
 
-성패 판정은 항상 `testCommand`의 exit code다. 에이전트의 자기보고는 판정에 쓰지 않는다.
+### (a) 직접 호출 — 명시적으로 엔진을 지목
+사용자가 hi-loop을 대놓고 부른다. LLM은 **바로 `hiloop_run`을 구동**한다(목표만 확정).
 
-### 💸 비용은 엔진이 센다 — 그리고 싸지 않다
+| 사용자가 이렇게 말하면 | LLM이 하는 일 |
+|---|---|
+| `/hi-loop 로그인 폼 만들어줘` (슬래시 스킬) | hi-loop 스킬 기동 → `hiloop_run(full=true)` 실행 |
+| "hiloop_run 도구로 결제 버그 고쳐줘" | 지목된 MCP 도구를 로드해 바로 호출 |
+| 터미널에서 `hi-loop run --goal "..." --full` | 엔진을 CLI로 직접 구동(LLM 개입 없음) |
+
+### (b) 평문 요청 — 그냥 하고 싶은 일을 말함
+사용자는 hi-loop을 언급하지 않는다. 이때 자동으로 hi-loop에 걸리는 건 **트리거가 박힌
+스킬 description + `CLAUDE.md` 지침**이 매 세션 떠 있기 때문이다(설치 + `hi-loop-setup` 전제).
+그 표면이 없으면 LLM은 hi-loop을 모른 채 그냥 직접 구현한다.
 
-**실측**: "두 수를 더하는 add 함수를 만들어라"가 2회차에 통과하는 데 **$2.58~$4.67**
-(claude-opus-4-8). 같은 goal·같은 회차인데 컨텍스트 크기 때문에 1.8배 갈렸다.
-새 세션은 일을 안 시켜도 바닥값이 ~$0.43이다(캐시 생성).
+| 사용자가 이렇게 말하면 | 어디에 걸리나 | LLM이 하는 일 |
+|---|---|---|
+| "워크스페이스 폴더 드래그앤드롭 **개선**해줘" | 트리거 `개선` | hi-loop 스킬 후보로 뜸 → 기획·설계 필요 판단 → `hiloop_run(full=true)` 제안·실행 |
+| "장바구니 **기능** 하나 **만들어**줘" | 트리거 `기능/design` | 발굴→스펙·테스트 우선(PLAN)→구현·리뷰 루프 |
+| "결제 모듈 **리팩터**해줘" | 트리거 `리팩터` | 기존 테스트를 가드레일로 `--verify-spec` 성격의 개선 루프 |
+| "동시 요청 시 잔액 음수 **버그** 고쳐줘" | 트리거 `구현/버그성` | **재현 테스트 먼저** → HEAL 루프로 수정 |
+| "이 **오타** 고쳐줘" / "변수명 바꿔줘" | 예외(사소) | 루프 없이 **바로** 처리 — README·CLAUDE.md가 사소한 작업은 제외하라고 명시 |
+
+### 왜 이렇게 갈리나 (push vs pull)
+- **트리거 스킬 description·CLAUDE.md = push 표면.** LLM이 찾지 않아도 매 세션 상주하며,
+  평문에 `개선/설계/버그` 같은 단어가 있으면 **자동으로** hi-loop을 후보로 올린다.
+- **MCP 도구 = pull 표면.** 세션에선 이름만 있고(때로 deferred), LLM이 먼저 "hi-loop이
+  필요하다"고 떠올려 `ToolSearch`로 끌어와야 설명이 보인다.
+- 그래서 **평문 요청이 자동 라우팅되려면 push 표면이 반드시 있어야 한다.** `hi-loop-setup`이
+  `CLAUDE.md` 지침을 심고, 플러그인이 트리거 스킬을 등록하는 이유가 이것이다. 이게 없으면
+  "개선해줘"라고 해도 LLM은 hi-loop을 거치지 않고 곧장 코드부터 짠다.
+
+> 확실히 hi-loop을 태우고 싶으면 **(a) 직접 호출**이 가장 안전하다. **(b) 평문 자동 라우팅**은
+> 편하지만, 설치·주입이 안 됐거나 트리거에 안 걸리는 표현이면 우회될 수 있다.
+
+## 브랜치 & 커밋 워크플로 (FR-16)
+
+코드 변경 작업을 **보호 브랜치에서 분기 → 구현·테스트 → 로컬 커밋**으로 감싼다. push/PR 은 하지 않는다.
+
+**정책은 커밋되는 `.hi-loop.json` 한 파일**에 산다(팀 공유, 스킬·엔진 공용). `.agent-state.json`
+(임시·gitignore)과 다르다. 기본값:
+
+```json
+{
+  "protectedBranches": ["main", "master", "develop", "dev"],
+  "branchPolicy": "ask",     // always=자동 분기 | ask=매번 확인 | never
+  "commitPolicy": "confirm", // confirm=메시지+diff 확인 후 | auto | off
+  "commitStyle": "match-log" // match-log=git log 관행 미러 | conventional | korean
+}
+```
 
-**`--max-loops`는 비용 상한이 아니다.** 실패 루프가 10회를 다 쓰면 $20을 넘길 수 있다.
-그래서 `--budget-usd`를 쓴다 — 누적이 상한에 닿으면 **다음 에이전트 호출 전에** 멈춘다
-(이미 쓴 돈은 못 돌리니 할 수 있는 건 더 안 쓰는 것뿐이다).
+**두 실행 층 (같은 정책 파일):**
+- **대화형(스킬/코드 어시스턴트)**: 코드변경 요청 시 `.hi-loop.json` 이 없으면 **최초 1회** 정책을
+  묻고 저장(지연 발동). 이후 보호 브랜치면 분기 게이트, 테스트 통과 후 커밋 게이트(diff 보여주고
+  승인)를 태운다. "이번만 커밋하지 마"(일회성)와 "앞으로 커밋하지 마"(정책 변경)를 구분한다.
+- **헤드리스(CLI/봇/CI)**: 물어볼 수 없으니 **플래그 = 동의**.
 
 ```bash
-hi-loop run --goal "..." --max-loops 5 --budget-usd 1 --no-stagnation
-# [hi-loop] 💸 예산 $1 소진 (누적 $1.61) — 2회차에서 중단합니다.
+hi-loop run --goal "..." --branch --commit          # 보호 브랜치면 자동 분기 + 통과 후 자동 커밋
+hi-loop run --goal "..." --branch feature/login     # 브랜치명 지정
+hi-loop run --goal "..." --commit --commit-message "feat: 로그인"
 ```
 
-`hi-loop status`와 완료 로그에 누적 비용이 찍힌다. 모델은 사용자 기본값을 상속하므로
-`HILOOP_AGENT_ARGS="--model sonnet"`으로 낮출 수 있다.
+`.hi-loop.json` 의 `branchPolicy: always` / `commitPolicy: auto` 는 CLI 에서 플래그 없이도 발동한다
+(플래그가 우선). 커밋 스테이지는 상태 머신에서 `CODE_REVIEW → COMMIT → SHIP` 사이에 든다 —
+리뷰된 코드를 커밋한 뒤 배포한다.
 
-### 기존 파일을 덮어쓰지 않는다
+**정책 관리:**
 
-PLAN 산출물 경로는 **엔진이 정한다.** `docs/spec.md`/`tests/app.test.js`가 비어 있으면
-그대로 쓰고, 이미 뭔가 있으면 goal 해시로 비켜간다(`docs/spec-5d88cc7f.md`).
-같은 프로젝트에서 goal만 바꿔 두 번 돌려도 앞의 산출물이 살아남는다.
+```bash
+hi-loop config                          # 현재 정책 출력
+hi-loop config set commitPolicy auto    # 정책 변경 (branchPolicy|commitPolicy|commitStyle)
+hi-loop config add-branch release       # 보호 브랜치 추가
+hi-loop config remove-branch dev        # 보호 브랜치 제거
+```
 
-### 테스트를 지워서 통과하는 것을 막는다 (bkit 철학)
+## 상태 초기화
 
-CHECK는 2단이다 — `check.ok && integrity.ok`여야 통과. 판정 기준인 테스트를 에이전트가
-지우거나 skip/always-true로 무력화하면 exit 0이 나와도 **통과로 인정하지 않는다.**
-탐지 패턴(케이스 감소, `.skip`, `.only`, `assert.ok(true)`)은 bkit gap-detector의
-가짜 완료 분류학에서 가져왔다. 테스트 **추가**는 위반이 아니다.
+새 goal로 깨끗이 다시 시작하려면 상태 파일을 지운다:
+
+```bash
+hi-loop reset               # .agent-state.json 삭제 (CLI)
+# MCP: hiloop_reset
+```
+
+---
 
-### 같은 벽에 열 번 부딪히지 않는다
+# 안전장치 — 루프 엔지니어링 원칙
 
-같은 실패가 3회 연속이면 `stopReason: 'stagnated'`로 조기 종료한다 — "이 접근으론 안 된다"를
-`--max-loops` 소진 전에 잡는다. `--stagnation N` 으로 조절, `--no-stagnation` 으로 끈다.
+위 세 원칙에서 파생된, 이 엔진이 **false green을 막는** 구체적 장치들이다.
 
-### 통과가 무엇을 확인 안 했는지 공개한다 (MoAI 철학)
+### 세션 핸드오프 & 컨텍스트 다이어트
+
+에이전트는 같은 세션에서 오래 굴릴수록 토큰이 쌓여 멍청해진다. 그래서 4회마다 세션을
+**버리고**, `.agent-state.json` 에 압축된 상태(goal / 스펙 요약 / 마지막 에러 / 최근 이력 5건)만
+새 세션에 넘겨 이어서 작업한다(auto-resume). 같은 goal로 다시 실행하면 중단 지점부터 재개한다.
+
+### TDD 자가 치유
+
+성패 판정은 항상 `testCommand` 의 exit code다. 에이전트의 자기보고는 판정에 쓰지 않는다.
+
+### 테스트를 지워서 통과하는 것을 막는다
+
+CHECK는 2단이다 — `check.ok && integrity.ok` 여야 통과. 판정 기준인 테스트를 에이전트가
+지우거나 skip/always-true로 무력화하면 exit 0이 나와도 **통과로 인정하지 않는다.**
+탐지 패턴은 케이스 감소, `.skip`, `.only`, `assert.ok(true)` 등이다. 테스트 **추가**는 위반이 아니다.
 
-이 엔진의 `passed`는 조용한 거짓말이 될 수 있다 — 테스트를 PLAN 단계에서 **에이전트 자신이**
+### 통과가 무엇을 확인 안 했는지 공개한다
+
+이 엔진의 `passed` 는 조용한 거짓말이 될 수 있다 — 테스트를 PLAN 단계에서 **에이전트 자신이**
 썼기 때문이다. 그래서 통과할 때마다 Evidence와 Gaps를 함께 출력한다:
 
 ```
@@ -191,33 +382,38 @@ CHECK는 2단이다 — `check.ok && integrity.ok`여야 통과. 판정 기준
 - 런타임·성능·보안은 관측 범위 밖이다.
 ```
 
-moai의 5-섹션 보고 규약에서 왔다. false green을 disclosed green으로 바꾼다.
+false green을 disclosed green으로 바꾼다.
 
-### 망가뜨려도 되돌린다 (bkit 철학)
+### 망가뜨려도 되돌린다
 
-각 에이전트 호출 **전에** `git stash create`로 워킹트리를 스냅샷한다(비파괴 — 워킹트리를
-안 건드리고 SHA만 남긴다). 에이전트가 멀쩡한 코드를 망가뜨리면:
+각 에이전트 호출 **전에** `git stash create` 로 워킹트리를 스냅샷한다(비파괴 — 워킹트리를
+안 건드리고 SHA만 남긴다). 에이전트가 멀쩡한 코드를 망가뜨리면 `hi-loop rollback` 으로
+복원한다. **자동 롤백은 없다** — 전경 실행이 기본이라 사람이 본다. git 저장소가 아니면
+조용히 생략한다.
 
-```bash
-hi-loop rollback            # 최신 체크포인트로 파일 복원
-hi-loop rollback --to 3     # 3회차 직전 상태로
-```
+### 스펙을 오라클로 — 2단 판정 (`--verify-spec`)
 
-**자동 롤백은 없다** — 전경 실행이 기본이라 사람이 본다(bkit도 자동 되돌리기를 무인 L4에만
-건다). git 저장소가 아니면 조용히 생략한다.
+이 엔진의 exit 0은 "에이전트가 자기가 쓴 테스트를 통과시켰다"일 뿐이다. `--verify-spec` 을
+켜면 통과 후 **별도 검증자**가 스펙 대비 구현을 심판한다.
 
-### 스펙을 오라클로 — 2단 판정 (bkit 중심 명제)
+- **Tier 1 (기계)**: exit code + 무결성. 최종 권한. 실패면 끝.
+- **Tier 2 (모델)**: 스펙 대조. **오직 기각만 가능** — 통과를 되돌릴 순 있어도 Tier 1 실패를
+  통과로 못 올린다. 쓰기 권한 없이(`--permission-mode plan`) 새 세션으로 호출.
 
-`--verify-spec`을 켜면 테스트 통과 후 **별도 검증자**가 스펙 대비 구현을 심판한다.
-이 엔진의 exit 0은 "에이전트가 자기가 쓴 테스트를 통과시켰다"일 뿐이므로:
+구조가 아니라 의도를 본다. 비용이 늘어 opt-in이다.
 
-- **Tier 1 (기계)**: exit code + 무결성. 최종 권한. 실패면 끝.
-- **Tier 2 (모델)**: 스펙 대조. **오직 기각만 가능** — 통과를 되돌릴 순 있어도
-  Tier 1 실패를 통과로 못 올린다. 쓰기 권한 없이(`--permission-mode plan`) 새 세션으로 호출.
+### 💸 비용은 엔진이 센다 — 그리고 싸지 않다
+
+**`--max-loops` 는 비용 상한이 아니다.** 실패 루프가 10회를 다 쓰면 비용이 크게 뛸 수 있다.
+그래서 `--budget-usd` 를 쓴다 — 누적이 상한에 닿으면 **다음 에이전트 호출 전에** 멈춘다.
+
+```bash
+hi-loop run --goal "..." --max-loops 5 --budget-usd 1 --no-stagnation
+# [hi-loop] 💸 예산 $1 소진 (누적 $1.61) — 2회차에서 중단합니다.
+```
 
-**실측**: 스펙이 "음수는 TypeError"를 요구하는데 테스트는 양수만 검사하고 구현이
-`(a,b)=>a+b`인 경우 — 테스트는 초록이었지만 검증자가 *"add(-1,2)는 예외 대신 1을
-반환한다"*고 정확히 기각했다. 구조가 아니라 의도를 본다. opt-in(비용 증가).
+`hi-loop status` 와 완료 로그에 누적 비용이 찍힌다. 모델은 사용자 기본값을 상속하므로
+`HILOOP_AGENT_ARGS="--model sonnet"` 으로 낮출 수 있다.
 
 ## 환경변수
 
@@ -226,7 +422,7 @@ hi-loop rollback --to 3     # 3회차 직전 상태로
 | `HILOOP_AGENT_CMD` | 에이전트 실행 명령 (기본 `claude`) |
 | `HILOOP_AGENT_ARGS` | 에이전트에 덧붙일 인자 (공백 구분). 예: `--model sonnet` — 비용에 직결된다 |
 | `HILOOP_PERMISSION_MODE` | 권한 모드 (기본 `acceptEdits`). 편집 허용이 이 엔진의 전제다 |
-| `HILOOP_VERIFY_CMD` / `HILOOP_VERIFY_MODEL` | `--verify-spec` 검증자의 실행 명령·모델 (미설정 시 구현자와 동일). bkit처럼 검증에 더 센 모델을 쓸 수 있다 |
+| `HILOOP_VERIFY_CMD` / `HILOOP_VERIFY_MODEL` | `--verify-spec` 검증자의 실행 명령·모델 (미설정 시 구현자와 동일). 검증에 더 센 모델을 쓸 수 있다 |
 | `HILOOP_REVIEW_CMD` / `HILOOP_REVIEW_MODEL` | 설계·코드 리뷰어의 실행 명령·모델 (미설정 시 `HILOOP_VERIFY_*` → 구현자 순으로 폴백) |
 | `HILOOP_DISCOVER_CMD` / `HILOOP_DISCOVER_MODEL` | 발굴 단계의 실행 명령·모델 |
 | `HILOOP_AGENT_TIMEOUT_MS` / `HILOOP_TEST_TIMEOUT_MS` | 에이전트(30분)·테스트(10분) 타임아웃. 쓰레기값은 기본값으로 되돌림 |
@@ -241,24 +437,28 @@ npm test        # node:test, devDependency 0개
 ## 구조
 
 ```
-bin/hi-loop.js    CLI 엔트리포인트 (CLI / MCP 분기 + rollback + answer + 단계별 실행)
+bin/hi-loop.js     CLI 엔트리포인트 (CLI / MCP 분기 + rollback + answer + 단계별 실행)
 bin/setup.js       프로젝트·클로드코드 설정 자동 주입
 src/loop.js        라이프사이클 stage 머신 — 다음 stage 를 정하는 권한은 여기 한 곳뿐
 src/build.js       안쪽 자가 치유 루프 — 예산·정체·무결성·2단 판정·핸드오프 집행
 src/stages.js      DISCOVER / CODE_REVIEW / SHIP / WATCH 핸들러 (지시만 반환)
-src/discover.js    DISCOVER — 요구사항 발굴, 가정 확정, 분기 감지 (FR-10)
-src/review.js      DESIGN_REVIEW / CODE_REVIEW — 격리된 Tier 2 심판 (FR-11, FR-12)
-src/ship.js        SHIP / WATCH — 배포·헬스체크. 에이전트를 부르지 않는다 (FR-13, FR-14)
-src/ask.js         ask 모드 — pause/resume 상태머신, 가정 기록 (FR-16)
-src/report.js      완료 보고 — Gaps 공개(L10) + 상태 요약
+src/discover.js    DISCOVER — 요구사항 발굴, 가정 확정, 분기 감지
+src/review.js      DESIGN_REVIEW / CODE_REVIEW — 격리된 Tier 2 심판
+src/ship.js        SHIP / WATCH — 배포·헬스체크. 에이전트를 부르지 않는다
+src/vcs.js         브랜치·커밋 메커니즘 — 프리스텝·COMMIT 스테이지·git log 스타일 감지
+src/config.js      .hi-loop.json 정책 저장소 — 브랜치·커밋 정책의 단일 진실 원천
+src/ask.js         ask 모드 — pause/resume 상태머신, 가정 기록
+src/checks.js      다중 조건 검사 — --check/--when, short-circuit 없음
+src/blast.js       블라스트 반경 — 변경의 위험 분류를 공개
+src/report.js      완료 보고 — Gaps 공개 + 상태 요약
 src/cli-options.js CLI 인자 → runLoop 옵션 번역 (잘못된 값은 조용히 흘리지 않는다)
 src/state.js       .agent-state.json (원자적 저장 + 다이어트 + 산출물 경로 + resume + Gaps)
-src/runners.js     에이전트/테스트 실행 어댑터 (주입 가능) + 비용 파싱 + 타임아웃 (L6)
+src/runners.js     에이전트/테스트 실행 어댑터 (주입 가능) + 비용 파싱 + 타임아웃
 src/prompts.js     PDCA 단계별 프롬프트 + 검증자 프롬프트
-src/integrity.js   테스트 무결성 지문·비교 — 보상 해킹 방어 (L1)
-src/checkpoint.js  git stash 체크포인트·롤백 (L3) + 삭제 관측 (L8)
-src/verify.js      스펙 오라클 — Tier 2 검증자 (L9)
-src/lock.js        동시 실행 pid 락 (L4)
+src/integrity.js   테스트 무결성 지문·비교 — 보상 해킹 방어
+src/checkpoint.js  git stash 체크포인트·롤백 + 삭제 관측
+src/verify.js      스펙 오라클 — Tier 2 검증자
+src/lock.js        동시 실행 pid 락
 src/mcp-server.js  MCP 프로토콜 통신
 src/telegram.js    텔레그램 비동기 알림
 src/args.js        의존성 없는 인자 파서