@tuzi-ince/hi-loop 0.1.1

package/docs/guide.md

@@ -0,0 +1,432 @@
+# hi-loop — 배포·설치·사용 가이드
+
+> 이 문서는 **실제로 실행해 확인한 절차**만 담는다. 확인 못 한 것은 §7 에 그렇다고 적어뒀다.
+> 요구사항은 [`spec.md`](spec.md), 설계 근거는 [`design.md`](design.md) 참조.
+
+---
+
+## 0. 5분 요약
+
+```bash
+# 1) 설치 (npm 레지스트리 아님 — 소스에서 전역 링크)
+cd /path/to/hi-loop
+npm install
+npm link                       # hi-loop, hi-loop-setup 명령 등록
+
+# 2) 사용할 프로젝트에서 설정 주입
+cd /path/to/my-project
+hi-loop-setup                 # .mcp.json / .gitignore / docs / tests
+
+# 3) 두 가지 방식 중 하나로 가동
+hi-loop run --goal "add 함수를 만들어라" --test "npm test"   # 사람이 직접
+# 또는 클로드코드/커서에서 MCP 도구 hiloop_run 호출         # 에이전트가
+```
+
+---
+
+## 1. 사전 요구사항
+
+| 항목 | 요구 | 확인 |
+|---|---|---|
+| Node.js | >= 18 (ESM, 내장 `fetch`, `node:test`) | `node -v` |
+| 에이전트 CLI | `claude` (기본값). 다른 도구로 교체 가능(§4) | `which claude` |
+| Git | 선택 (롤백/리뷰용) | `git --version` |
+
+> ⚠️ **`npm install -g handoff` 를 하지 마라.** 무스코프 `handoff` 는 이 프로젝트와
+> 무관한 **제3자의 redis lua 래퍼 패키지**(v0.1.3)다. 이 프로젝트의 이름은
+> **`@tuzi-ince/hi-loop`** 이며 아직 배포 전이다. 설치는 아래 §2 의 방법을 쓴다.
+
+---
+
+## 2. 설치
+
+### 2-A. 로컬 개발 (권장 — 코드 수정하며 쓸 때)
+
+```bash
+git clone <이 저장소> hi-loop && cd hi-loop
+npm install          # @modelcontextprotocol/sdk, zod
+npm test             # 104개 통과 확인
+npm link             # 전역에 hi-loop / hi-loop-setup 심볼릭 링크
+hi-loop --version   # 0.1.0
+```
+
+해제: `npm unlink -g @tuzi-ince/hi-loop`
+
+### 2-B. 경로로 전역 설치 (링크 없이 고정 설치)
+
+```bash
+npm install -g /absolute/path/to/hi-loop
+```
+
+### 2-C. tarball 배포 (다른 머신/서버로 옮길 때)
+
+```bash
+# 보내는 쪽
+npm pack                     # tuzi-ince-hi-loop-0.1.0.tgz 생성 (~26kB)
+
+# 받는 쪽
+npm install -g ./tuzi-ince-hi-loop-0.1.0.tgz
+```
+
+### 2-D. 설치 없이 직접 실행
+
+```bash
+node /path/to/hi-loop/bin/hi-loop.js run --goal "..." --test "npm test"
+```
+
+---
+
+## 3. 프로젝트에 붙이기: `hi-loop-setup`
+
+대상 프로젝트에서 한 번 실행한다. **멱등**이라 여러 번 돌려도 안전하다.
+
+```bash
+cd /path/to/my-project
+hi-loop-setup --dry-run     # 무엇이 바뀔지 먼저 보기
+hi-loop-setup               # 실제 적용
+```
+
+하는 일:
+
+| 대상 | 동작 |
+|---|---|
+| `.mcp.json` | `hi-loop` MCP 서버 등록. **기존 다른 서버 항목은 보존** |
+| `.gitignore` | `.agent-state.json` 추가 (중복 없이) |
+| `docs/`, `tests/` | 없으면 생성 |
+
+생성되는 `.mcp.json` 은 이렇게 **현재 설치본의 절대 경로**를 가리킨다:
+
+```json
+{
+  "mcpServers": {
+    "hi-loop": {
+      "command": "/usr/local/bin/node",
+      "args": ["/path/to/hi-loop/bin/hi-loop.js", "mcp"]
+    }
+  }
+}
+```
+
+> 왜 `npx -y handoff mcp` 가 아닌가: 그러면 npm 에서 §1 의 **남의 redis 패키지**를
+> 받아 실행한다. 그래서 실제 진입점 경로를 박아 넣는다.
+> 단점은 hi-loop 를 다른 곳으로 옮기면 경로가 깨진다는 것 — 그때는 `hi-loop-setup` 을 다시 돌린다.
+
+---
+
+## 4. 사용법
+
+### 4-1. CLI 직접 실행 (사람 / 데몬 / 텔레그램 봇)
+
+```bash
+hi-loop run --goal "JWT 인증 미들웨어를 만들어라" \
+             --test "npm test" \
+             --max-loops 10 \
+             --cwd .
+```
+
+| 플래그 | 별칭 | 기본값 | 설명 |
+|---|---|---|---|
+| `--goal` | `-g` | (필수) | 달성할 요구사항 |
+| `--test` | `-t` | `npm test` | 성패를 판정할 명령 |
+| `--max-loops` | `-m` | `10` | 최대 루프(=에이전트 호출) **횟수** 상한 |
+| `--budget-usd` | — | (없음=무제한) | 누적 **비용** 상한(USD). 넘으면 다음 호출 전에 중단 |
+| `--stagnation` | — | `3` | 같은 실패가 이 횟수 연속이면 조기 종료. `--no-stagnation` 으로 끔 |
+| `--verify-spec` | — | (꺼짐) | 통과 후 별도 검증자로 스펙 대비 구현을 심판 (하향 전용, 비용 증가) |
+| `--cwd` | `-c` | 현재 디렉터리 | 작업 대상 |
+
+> 세 상한의 관계: `--max-loops`(횟수) / `--budget-usd`(비용) / `--stagnation`(반복).
+> 셋 중 먼저 닿는 것이 이긴다. 매번 같은 실패면 대개 정체(3회)가 제일 먼저 끊는다 —
+> "이 접근으론 안 된다"를 비용·횟수 소진보다 빨리 잡는 게 싸다.
+
+> ⚠️ **`--max-loops` 는 비용 상한이 아니다.** 실측: 같은 goal 이 같은 2회차에 통과했는데
+> 한 번은 $2.58, 한 번은 $4.67 이었다(컨텍스트 크기 차이). 호출 횟수로는 비용을 못 막는다.
+> 돈을 막으려면 `--budget-usd` 를 써라. 자세한 실측치는 §7.
+
+exit code: `0` 통과 / `1` 실패(한도 소진 또는 예산 소진) / `2` 잘못된 사용.
+→ CI·스크립트에서 `hi-loop run … && echo OK` 로 바로 쓸 수 있다.
+
+```bash
+hi-loop status              # 현재 루프 상태 요약 (누적 비용·정체 포함)
+hi-loop --help
+```
+
+### 4-1a. 롤백 — 에이전트가 망가뜨린 것을 되돌린다 (L3)
+
+각 에이전트 호출 **전에** `git stash create`로 워킹트리를 비파괴 스냅샷한다. 에이전트가
+멀쩡한 코드를 망가뜨렸으면 되돌린다:
+
+```bash
+hi-loop rollback            # 가장 최근 체크포인트로 파일 복원
+hi-loop rollback --to 3     # 3회차 직전 상태로 복원
+hi-loop rollback --cwd .    # 작업 대상 지정
+```
+
+- **자동 롤백은 없다** — 전경 실행이 기본이라 사람이 판단한다. 되돌리기 전 현재 상태도
+  안전망 스냅샷으로 한 번 더 떠두므로, 롤백 자체를 잘못 눌러도 다시 앞으로 갈 수 있다.
+- git 저장소가 아니면 체크포인트가 없으니 롤백도 조용히 no-op이다.
+
+### 4-2. MCP 서버 (클로드코드 / 커서)
+
+`hi-loop-setup` 후 에이전트를 재시작하면 도구 3개가 뜬다.
+
+| 도구 | 인자 | 용도 |
+|---|---|---|
+| `hiloop_run` | `goal`(필수), `testCommand`, `maxLoops`, `verifySpec`, `cwd` | 자가 치유 루프 실행 |
+| `hiloop_status` | `cwd` | 진행 상태 조회 (장시간 루프를 들여다보는 창) |
+| `hiloop_reset` | `cwd` | `.agent-state.json` 초기화 |
+
+> MCP `hiloop_run`은 CLI와 달리 `--budget-usd`·`--stagnation`을 노출하지 않는다.
+> 예산 상한이 필요하면 CLI(`hi-loop run`)를 쓴다. 정체 감지는 기본값(3회)으로 동작한다.
+
+수동 기동: `hi-loop mcp` (인자 없이 `hi-loop` 만 쳐도 서버로 뜬다)
+
+### 4-3. 환경변수
+
+| 변수 | 기본값 | 설명 |
+|---|---|---|
+| `HILOOP_AGENT_CMD` | `claude` | 에이전트 실행 명령. 다른 CLI 로 교체 가능 |
+| `HILOOP_AGENT_ARGS` | (없음) | 에이전트에 덧붙일 인자 (공백 구분) |
+| `HILOOP_PERMISSION_MODE` | `acceptEdits` | 비대화형 편집 허용용. `bypassPermissions` 등으로 확대/축소 |
+| `HILOOP_VERIFY_CMD` | (`HILOOP_AGENT_CMD`→`claude`) | `--verify-spec` 검증자 실행 명령. 구현자와 다른 CLI로 검증 가능 |
+| `HILOOP_VERIFY_MODEL` | (구현자와 동일) | `--verify-spec` 검증자 모델 |
+| `HILOOP_AGENT_TIMEOUT_MS` | `1800000` | 에이전트 호출 타임아웃(30분). 쓰레기값은 기본값으로 되돌림 |
+| `HILOOP_TEST_TIMEOUT_MS` | `600000` | 테스트 실행 타임아웃(10분). 〃 |
+| `TELEGRAM_BOT_TOKEN` | (없음) | 알림용. 미설정 시 조용히 생략 |
+| `TELEGRAM_CHAT_ID` | (없음) | 〃 |
+
+> `--permission-mode acceptEdits` 를 기본 주입하는 이유: 기본 권한 모드의 `claude -p` 는
+> 비대화형이라 편집 권한을 물어볼 상대가 없어 편집이 **거부**된다. 그러면 에이전트가
+> 파일을 하나도 못 쓴 채 루프만 돈다.
+
+### 4-4. 텔레그램 알림 붙이기
+
+```bash
+# 1) @BotFather 에게 /newbot → 토큰 발급
+# 2) 봇에게 아무 메시지나 보낸 뒤 chat id 확인
+curl -s "https://api.telegram.org/bot<TOKEN>/getUpdates" | jq '.result[0].message.chat.id'
+
+# 3) 환경변수 설정
+export TELEGRAM_BOT_TOKEN="123456:ABC..."
+export TELEGRAM_CHAT_ID="987654321"
+```
+
+알림 시점은 4개뿐이다: 🚀시작 / ♻️핸드오프 / ✅성공 / ❌실패.
+(매 루프마다 울리면 폰이 시끄러워서 의도적으로 뺐다.)
+**알림 실패는 루프를 절대 중단시키지 않는다** — 미설정이면 그냥 생략된다.
+
+---
+
+## 4-5. 검증 루프: 배포하지 않고 "설치된 상태"를 검증하기 ★
+
+> "배포해야 검증할 수 있는 것 아닌가?" — 아니다. **배포(publish)와 패키지화(pack)는 다르다.**
+> 검증에 필요한 건 **아티팩트(tarball)** 이지 레지스트리가 아니다.
+>
+> ```
+> npm pack     → 아티팩트 생성   ← 검증에 필요한 건 여기까지
+> npm publish  → 그 아티팩트를 레지스트리에 영구 등록  ← 되돌릴 수 없음
+> ```
+>
+> `npm publish` 가 하는 일은 **이미 만들어진 tarball 을 업로드**하는 것뿐이다.
+> 업로드가 코드를 바꾸지 않는다. 그러므로 배포 전에 전부 검증할 수 있다.
+
+### 왜 이게 hi-loop 의 철학 그 자체인가
+
+hi-loop 의 CHECK 단계는 **에이전트가 "다 됐다"고 말해도 믿지 않고 직접 테스트를 돌린다.**
+"일단 배포하고 문제 생기면 고치자"는 그 원칙을 정확히 뒤집는다 — CHECK 전에 DO 를 확정하는 것이다.
+
+게다가 루프의 HEAL 과 달리 **배포는 되돌릴 수 없다**. 루프는 10번 실패해도 상태만 남지만,
+잘못 배포된 버전은 72시간 후 unpublish 조차 불가능하고 그 버전 번호는 영원히 태워진다.
+자가 치유가 안 되는 유일한 단계이므로, 여기서만큼은 CHECK 를 앞에 둬야 한다.
+
+### 실제로 돌아가는 로컬 검증 루프 (PDCA)
+
+```bash
+# ── PLAN: 무엇이 통과해야 하는가
+#     tests/app.test.js + 아래 스모크 기준
+
+# ── DO: 코드 수정 + 버전 올리기
+npm version patch --no-git-tag-version     # 0.1.0 -> 0.1.1
+
+# ── CHECK 1: 소스에서 테스트
+npm test                                   # 104개
+
+# ── CHECK 2: 아티팩트로 만든다 (레지스트리 안 건드림)
+npm pack                                   # tuzi-ince-hi-loop-0.1.1.tgz
+
+# ── CHECK 3: 진짜 "설치된 상태"로 검증한다 ★ 핵심
+#     --prefix 로 임시 위치에 설치 → 전역 오염 없고 언제든 rm 으로 폐기
+rm -rf /tmp/lev-prefix
+npm install -g --prefix /tmp/lev-prefix ./tuzi-ince-hi-loop-0.1.1.tgz
+
+#     설치본을 실제로 실행 (bin 심링크 경유 = 전역 설치와 동일 조건)
+/tmp/lev-prefix/bin/hi-loop --version
+cd /tmp/consumer && /tmp/lev-prefix/bin/hi-loop-setup
+/tmp/lev-prefix/bin/hi-loop run --goal "add 함수" --test "npm test" --max-loops 3
+
+# ── ACT: 실패하면 고치고 다시 CHECK 2 로. 통과할 때까지 반복
+# ── 다 통과한 뒤에야: npm publish
+rm -rf /tmp/lev-prefix                     # 정리
+```
+
+`npm install -g --prefix <임시경로>` 가 이 루프의 심장이다. 레지스트리 없이
+**진짜 설치**(파일 배치, bin 심링크 생성, 의존성 해석)를 그대로 재현하면서
+전역 환경을 건드리지 않고 `rm -rf` 로 폐기할 수 있다.
+
+### 이 루프가 실제로 잡아낸 버그
+
+이 절차는 이론이 아니다. **소스에서는 104개 테스트가 다 통과하는데 설치본에서는
+모든 명령이 아무 일도 안 하고 조용히 `exit 0` 으로 끝나는** 버그를 이 루프가 잡았다.
+
+원인: `bin/*.js` 의 "직접 실행인가?" 판정이
+`resolve(process.argv[1]) === fileURLToPath(import.meta.url)` 였는데,
+**npm 의 전역 bin 은 언제나 심링크**다:
+
+```
+/tmp/lev-prefix/bin/hi-loop -> ../lib/node_modules/@tuzi-ince/hi-loop/bin/hi-loop.js
+```
+
+Node 는 `import.meta.url` 을 realpath 로 주지만 `process.argv[1]` 은 심링크 경로 그대로다.
+→ 두 값이 달라짐 → `main()` 미호출 → **에러도 없이 exit 0**.
+CI 는 exit 0 을 성공으로 읽으므로, 루프가 돈 적 없는데 "통과"로 보고됐을 것이다.
+
+이 버그는 **소스 트리에서는 절대 재현되지 않는다.** `npm test` 를 몇 번 돌려도,
+E2E 를 돌려도 안 나온다. 오직 설치된 상태에서만 나온다.
+→ 그래서 §7 의 "설치본 검증"이 체크리스트에 있는 것이고,
+→ 그리고 이건 **배포하지 않고도** 잡을 수 있었다. (`src/is-main.js` 로 수정, 회귀 테스트 3개 추가)
+
+### 배포해야만 검증되는 것 (진짜 짧다)
+
+| 항목 | 배포 필요? |
+|---|---|
+| 패키징 파일 누락, bin 매핑, 심링크 실행, 의존성 해석, 실제 루프 동작 | ❌ pack + `--prefix` 설치로 전부 |
+| `npm install -g @tuzi-ince/hi-loop` 가 레지스트리에서 받아지는지 | ✅ |
+| `npx -y @tuzi-ince/hi-loop` 해석 | ✅ |
+| npmjs.com 의 README 렌더링 | ✅ |
+
+배포 후에만 되는 것들은 **버전 하나 태우고 patch 올리면 되는 사소한 것들**이다.
+반면 배포 전에 잡을 수 있는 것을 안 잡고 내보내면, 위 심링크 버그처럼
+**"성공했다고 거짓말하는 도구"** 를 사용자에게 배포하게 된다.
+
+---
+
+## 5. npm 공개 배포 (미수행)
+
+패키지명은 **`@tuzi-ince/hi-loop`** 다. 무스코프 `handoff` 는 제3자의 redis 래퍼가
+이미 점유 중이라(§1) 스코프를 쓴다. `publishConfig.access: "public"` 을 넣어뒀으므로
+`--access public` 을 잊어도 공개로 나간다(스코프 패키지의 기본값은 private 이고,
+유료 계정이 아니면 오류가 난다).
+
+```bash
+npm login                 # 계정: tuzi-ince
+npm publish               # publishConfig 덕에 --access public 불필요
+```
+
+배포 후 설치는 이렇게 된다:
+
+```bash
+npm install -g @tuzi-ince/hi-loop    # 명령 이름은 그대로 hi-loop / hi-loop-setup
+```
+
+> 배포 후에는 `bin/setup.js` 의 `.mcp.json` 항목을 `npx -y @tuzi-ince/hi-loop mcp` 로
+> 바꾸는 선택지가 생긴다(경로 의존이 사라져 이식성이 좋아진다). **스코프 이름이 반드시
+> 정확해야 한다** — 무스코프로 되돌리면 남의 redis 패키지를 실행하게 된다.
+
+배포 전 체크리스트:
+
+- [ ] `npm test` 통과 (104개)
+- [ ] **§7 의 실제 에이전트 스모크 테스트 통과** ← 아직 안 된 항목. **이게 통과하기 전엔 배포하지 마라**
+- [ ] `npm pack --dry-run` 으로 포함 파일 확인 (bin, src, docs, README)
+- [ ] `version` 갱신
+- [ ] `npm publish` 는 되돌릴 수 없다(72시간 후 unpublish 불가). 이름·버전 확인 필수
+
+---
+
+## 6. 문제 해결
+
+| 증상 | 원인 / 조치 |
+|---|---|
+| 에이전트가 파일을 하나도 안 쓰고 루프만 돈다 | 권한 모드 문제. `HILOOP_PERMISSION_MODE=bypassPermissions` 로 시도 |
+| `에이전트 실행 실패(claude): spawn ... ENOENT` | `claude` 가 PATH 에 없음. `which claude` 확인 후 `HILOOP_AGENT_CMD` 에 절대 경로 지정 |
+| `spawn ... EACCES` | 커스텀 에이전트 스크립트에 실행 권한 없음 → `chmod +x` |
+| MCP 서버가 에이전트에 안 뜬다 | `.mcp.json` 경로가 실재하는지 확인(`hi-loop-setup` 재실행), 에이전트 재시작 |
+| MCP 응답이 깨진다 | stdout 은 프로토콜 채널이다. 커스텀 로거를 stdout 에 물리지 말 것 |
+| 같은 실패를 10회 반복하고 끝난다 | 알려진 한계(design.md L2). `--max-loops` 를 낮춰 비용부터 막고 goal 을 더 구체적으로 |
+| 테스트를 지워서 통과시켰다 | 알려진 한계(design.md L1). 프롬프트 규칙이 1차 방어선일 뿐 — `git diff tests/` 로 반드시 확인 |
+| 이어서 하지 말고 처음부터 하고 싶다 | `rm .agent-state.json` 또는 `hiloop_reset` |
+| `hi-loop` 를 옮긴 뒤 MCP 가 깨졌다 | `.mcp.json` 이 절대 경로라서 그렇다. `hi-loop-setup` 재실행 |
+
+상태 파일을 직접 들여다보는 게 가장 빠른 디버깅이다:
+
+```bash
+cat .agent-state.json | jq '{status, phase, iteration, sessionId, sessionSerial, lastError}'
+```
+
+---
+
+## 7. ⚠️ 이 가이드에서 검증된 것 / 안 된 것
+
+정직하게 구분한다. (design.md §10 과 동일)
+
+**실제로 실행해 확인함**
+
+- `npm test` 104개 통과
+- `npm pack` → tarball 생성 (bin/src/docs/README 포함)
+- **`npm install -g --prefix /tmp/lev-prefix ./tarball` 로 진짜 설치 → 설치본 실행 확인**
+  - `bin/hi-loop` 가 심링크로 생성됨을 `ls -l` 로 확인
+  - **심링크 bin 경유** `hi-loop --version` → `0.1.0`, `run`(goal 없음) → exit 2
+  - 설치본으로 전체 루프 E2E: PLAN→실패→DO→통과→exit 0
+  - 설치본 `hi-loop-setup` → `.mcp.json` 이 설치 위치를 정확히 가리킴
+- `hi-loop-setup` 멱등, `--dry-run` 무기록
+- MCP stdio 왕복: initialize → tools/list(3종) → tools/call
+- npm 레지스트리의 무스코프 `handoff` 가 제3자 패키지임
+
+**실제 `claude`(2.1.212) 로 확인함** — 이전 판의 "개발 환경 실행 가드가 spawn 을 차단"은
+**사실이 아니었다.** 막고 있던 것은 기술적 불가능이 아니라 실행되지 않은 절차였다.
+
+- **에이전트 왕복 전체**: PLAN→CHECK(실패)→DO→CHECK(통과)→exit 0
+- **`acceptEdits` 실효**: 에이전트가 실제로 `docs/spec.md`·`tests/app.test.js`·`src/add.js` 를 썼다
+- **세션 재개(`--resume`)**: 세션 파일 하나에 PLAN 프롬프트와 DO 프롬프트가 둘 다 들어 있다
+- **예산 상한**: `--budget-usd 1` → `maxLoops 5` 중 2회차에 중단, 누적 $1.61
+- **경로 회피**: 보호 대상 파일이 있는 디렉터리에서 원본 무수정, 해시 경로에 산출
+
+**비용 (실측)**
+
+| 실행 | 비용 |
+|---|---:|
+| 사소한 호출 1회 (새 세션 바닥값) | $0.434 |
+| add 함수, 빈 디렉터리, 2회차 통과 | $2.58 |
+| add 함수, 큰 저장소, 2회차 통과 | $4.67 |
+
+같은 goal·같은 회차인데 1.8배 차이다. **`--max-loops` 는 비용 상한이 아니다** —
+`--budget-usd` 를 써라.
+
+**아직 확인 못 함**
+
+- **핸드오프(4회차 세션 폐기)를 실제 에이전트로** — 가짜 에이전트로만 확인했다.
+  `iteration % 4 === 0 && iteration < maxLoops` 이므로 `--max-loops 3` 으로는
+  **산술적으로 관측 불가능**하다. 5 이상 + 계속 실패해야 한다.
+- **MCP 모드에서 실제 에이전트 spawn** — 도구 왕복(initialize/tools/call)만 확인
+- 장시간(10회) 실제 루프
+- 텔레그램 실제 발송
+- 레지스트리 경유 설치(`npm install -g @tuzi-ince/hi-loop`) — 배포 후에만 가능
+
+**재현 절차**
+
+```bash
+mkdir -p /tmp/hi-loop-smoke/s1 && cd /tmp/hi-loop-smoke/s1
+npm init -y && npm pkg set scripts.test="node --test"   # ⚠️ 이 줄을 빼면 안 된다
+git init -q && git add -A && git commit -qm baseline
+hi-loop run --goal "두 수를 더하는 add 함수를 만들어라" --test "npm test" \
+             --max-loops 3 --budget-usd 5
+```
+
+> ⚠️ **`npm pkg set scripts.test` 를 빼지 마라.** `npm init -y` 의 기본 test 스크립트는
+> `echo "Error: no test specified" && exit 1` 이라 에이전트가 무엇을 하든 실패한다.
+> 그러면 "권한 모드가 되는가" 대신 "에이전트가 함정을 눈치채는가"를 측정하게 된다.
+
+> ⚠️ **일회용 디렉터리에서 돌려라.** 산출물 경로 회피가 기존 파일은 지켜주지만,
+> 작업 디렉터리 이탈 방지는 여전히 프롬프트 규칙뿐이다(design.md L8).
+
+확인할 것: (1) 파일이 실제로 쓰였는가, (2) `.agent-state.json` 의 `sessionId`·`costUsd`,
+(3) 최종 exit code. 핸드오프까지 보려면 `--max-loops 5` + 에이전트가 못 고치는
+실패 명령(`--test "node -e 'process.exit(1)'"`).