@tuzi-ince/hi-loop 0.3.2 → 0.3.3

package/docs/guide.md

@@ -15,7 +15,7 @@ npm link                       # hi-loop, hi-loop-setup 명령 등록
 
 # 2) 사용할 프로젝트에서 설정 주입
 cd /path/to/my-project
-hi-loop-setup                 # .mcp.json / .gitignore / docs / tests
+hi-loop-setup                 # .mcp.json / .gitignore / docs·tests / CLAUDE.md / docs/design.md
 
 # 3) 두 가지 방식 중 하나로 가동
 hi-loop run --goal "add 함수를 만들어라" --test "npm test"   # 사람이 직접
@@ -91,8 +91,14 @@ hi-loop-setup               # 실제 적용
 | 대상 | 동작 |
 |---|---|
 | `.mcp.json` | `hi-loop` MCP 서버 등록. **기존 다른 서버 항목은 보존** |
-| `.gitignore` | `.agent-state.json` 추가 (중복 없이) |
+| `.gitignore` | `.agent-state.json` · `.agent-state.lock` 추가 (중복 없이) |
 | `docs/`, `tests/` | 없으면 생성 |
+| `docs/design.md` | **표준 설계 문서**를 템플릿으로 생성. **있으면 절대 덮어쓰지 않음**(사람이 관리하는 진실) |
+| `CLAUDE.md` | 기획/설계 요청을 hi-loop 으로 라우팅하는 상시 지침을 마커로 멱등 주입 |
+
+> `docs/design.md` 는 이번 프로젝트의 **오라클**이다 — `--reconcile`(정합 게이트)·`--spec`(스펙 고정)이
+> 이 문서를 기준으로 요청을 판정한다(§4-1 참조). 셋업 직후 이 문서를 채워두면, 이후 단말적 요청이
+> 문서와 어긋날 때 엔진이 잡아준다. 비어 있으면 정합 게이트는 사실상 아무것도 막지 못한다.
 
 생성되는 `.mcp.json` 은 이렇게 **현재 설치본의 절대 경로**를 가리킨다:
 
@@ -132,6 +138,9 @@ hi-loop run --goal "JWT 인증 미들웨어를 만들어라" \
 | `--budget-usd` | — | (없음=무제한) | 누적 **비용** 상한(USD). 넘으면 다음 호출 전에 중단 |
 | `--stagnation` | — | `3` | 같은 실패가 이 횟수 연속이면 조기 종료. `--no-stagnation` 으로 끔 |
 | `--verify-spec` | — | (꺼짐) | 통과 후 별도 검증자로 스펙 대비 구현을 심판 (하향 전용, 비용 증가) |
+| `--spec <path>` | — | (엔진이 결정) | 스펙 오라클을 이 문서로 **고정**. 이미 내용이 있으면 PLAN 이 덮어쓰지 않는다 |
+| `--reconcile` / `--no-reconcile` | — | `--full` 이면 켜짐 | **문서 정합 게이트**: 요청이 표준 문서와 모순되면 구현 전에 멈춰 사람에게 묻는다 |
+| `--reconcile-spec <path>` | — | design.md→spec.md | 정합 게이트가 대조할 문서 지정(지정하면 게이트가 켜진다) |
 | `--cwd` | `-c` | 현재 디렉터리 | 작업 대상 |
 
 > 세 상한의 관계: `--max-loops`(횟수) / `--budget-usd`(비용) / `--stagnation`(반복).
@@ -153,6 +162,14 @@ hi-loop status              # 현재 루프 상태 요약 (누적 비용·정체
 hi-loop --help
 ```
 
+> **문서↔소스 정합 (`--spec` / `--reconcile`)**: 기본적으로 이 엔진의 스펙·테스트는 에이전트
+> **자신이** 쓴 것이라, 통과가 "자기 테스트를 통과"에 그칠 수 있다(완료 보고의 Gaps 가 이를 공개한다).
+> 사람이 관리하는 표준 문서(`docs/design.md`, `hi-loop-setup` 이 만든다)를 오라클로 세우면 그 한계를 좁힌다:
+> - `--spec docs/design.md` — 그 문서를 스펙 오라클로 **고정**(리뷰·검증이 이 문서 기준).
+> - `--reconcile` — 새 요청이 그 문서와 **모순되면 구현 전에 멈춰** 묻는다(고정 / 분기 / 중단).
+>   대상은 `--reconcile-spec` 명시 → `docs/design.md` → `docs/spec.md` 순. `hi-loop-setup` 을 했다면
+>   `--full`/`--reconcile` 만으로 design.md 가 자동 오라클이 된다.
+
 ### 4-1b. 전과정 라이프사이클 (`--full`) 과 배포·감시
 
 기본은 자가 치유 루프 하나다. 앞뒤 단계는 **켤 때만** 돈다 — 켜지 않은 사람의 비용이
@@ -238,17 +255,25 @@ hi-loop rollback --cwd .    # 작업 대상 지정
 
 ### 4-2. MCP 서버 (클로드코드 / 커서)
 
-`hi-loop-setup` 후 에이전트를 재시작하면 도구 3개가 뜬다.
+`hi-loop-setup` 후 에이전트를 재시작하면 도구 6개가 뜬다.
 
 | 도구 | 인자 | 용도 |
 |---|---|---|
-| `hiloop_run` | `goal`(필수), `testCommand`, `maxLoops`, `verifySpec`, `cwd` | 자가 치유 루프 실행 |
+| `hiloop_run` | `goal`(필수), `testCommand`, `maxLoops`, `verifySpec`, `full`, `ship`, `watch`, `stopAfter`, `spec`, `reconcile`, `reconcileSpec`, `cwd` | 자가 치유(+전과정) 루프 실행 |
+| `hiloop_answer` | `choice`, `note`, `cwd` | 대기 중인 질문에 답하고 재개 가능 상태로 되돌림 |
 | `hiloop_status` | `cwd` | 진행 상태 조회 (장시간 루프를 들여다보는 창) |
+| `hiloop_rollback` | `to`, `cwd` | 체크포인트로 파일 복원 |
 | `hiloop_reset` | `cwd` | `.agent-state.json` 초기화 |
+| `hiloop_setup` | `dryRun`, `cwd` | 프로젝트 설정 주입 |
 
 > MCP `hiloop_run`은 CLI와 달리 `--budget-usd`·`--stagnation`을 노출하지 않는다.
 > 예산 상한이 필요하면 CLI(`hi-loop run`)를 쓴다. 정체 감지는 기본값(3회)으로 동작한다.
 
+> **cwd 기본값은 `CLAUDE_PROJECT_DIR || process.cwd()`.** MCP 는 호스트(클로드코드/커서)가 서버를
+> 띄우는 경로라, "어느 프로젝트인가"의 정답은 호스트가 주입하는 `CLAUDE_PROJECT_DIR` 다. 각 도구에
+> `cwd` 를 명시하면 그것이 최우선. (CLI 는 반대로 순수 `process.cwd()` — 터미널에서 cd 한 곳이 의도다.)
+> 상위 폴더에서 여러 하위 프로젝트를 다룰 땐 `cwd` 를 명시하거나 프로젝트별로 `hi-loop-setup` 하라.
+
 수동 기동: `hi-loop mcp` (인자 없이 `hi-loop` 만 쳐도 서버로 뜬다)
 
 ### 4-3. 환경변수
@@ -260,6 +285,8 @@ hi-loop rollback --cwd .    # 작업 대상 지정
 | `HILOOP_PERMISSION_MODE` | `acceptEdits` | 비대화형 편집 허용용. `bypassPermissions` 등으로 확대/축소 |
 | `HILOOP_VERIFY_CMD` | (`HILOOP_AGENT_CMD`→`claude`) | `--verify-spec` 검증자 실행 명령. 구현자와 다른 CLI로 검증 가능 |
 | `HILOOP_VERIFY_MODEL` | (구현자와 동일) | `--verify-spec` 검증자 모델 |
+| `HILOOP_RECONCILE_CMD` | (`HILOOP_VERIFY_CMD`→구현자) | `--reconcile` 정합 판정자 실행 명령 |
+| `HILOOP_RECONCILE_MODEL` | (`HILOOP_VERIFY_MODEL`→구현자) | `--reconcile` 정합 판정자 모델 |
 | `HILOOP_AGENT_TIMEOUT_MS` | `1800000` | 에이전트 호출 타임아웃(30분). 쓰레기값은 기본값으로 되돌림 |
 | `HILOOP_TEST_TIMEOUT_MS` | `600000` | 테스트 실행 타임아웃(10분). 〃 |
 | `TELEGRAM_BOT_TOKEN` | (없음) | 알림용. 미설정 시 조용히 생략 |
@@ -417,8 +444,9 @@ npm install -g @tuzi-ince/hi-loop    # 명령 이름은 그대로 hi-loop / hi-l
 | 증상 | 원인 / 조치 |
 |---|---|
 | 에이전트가 파일을 하나도 안 쓰고 루프만 돈다 | 권한 모드 문제. `HILOOP_PERMISSION_MODE=bypassPermissions` 로 시도 |
-| `에이전트 실행 실패(claude): spawn ... ENOENT` | `claude` 가 PATH 에 없음. `which claude` 확인 후 `HILOOP_AGENT_CMD` 에 절대 경로 지정 |
-| `spawn ... EACCES` | 커스텀 에이전트 스크립트에 실행 권한 없음 → `chmod +x` |
+| `에이전트 명령 'claude' 를 찾을 수 없습니다` | preflight 가 루프 진입 전 잡은 것. Claude Code 설치(`npm i -g @anthropic-ai/claude-code`) 또는 `HILOOP_AGENT_CMD` 에 절대 경로 지정 |
+| `... 를 실행할 권한이 없습니다 (EACCES)` | 커스텀 에이전트 스크립트에 실행 권한 없음 → `chmod +x "$(command -v <명령>)"` |
+| `API 키가 없거나 유효하지 않습니다 / 구독·크레딧 문제로 보입니다` | 에이전트 인증 문제. preflight 는 설치만 보고(비용 0), 인증은 첫 호출에서 감지된다 — `claude` 로그인 상태나 `ANTHROPIC_API_KEY` 를 확인 |
 | MCP 서버가 에이전트에 안 뜬다 | `.mcp.json` 경로가 실재하는지 확인(`hi-loop-setup` 재실행), 에이전트 재시작 |
 | MCP 응답이 깨진다 | stdout 은 프로토콜 채널이다. 커스텀 로거를 stdout 에 물리지 말 것 |
 | 같은 실패를 10회 반복하고 끝난다 | 알려진 한계(design.md L2). `--max-loops` 를 낮춰 비용부터 막고 goal 을 더 구체적으로 |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tuzi-ince/hi-loop",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "description": "CLI와 MCP 모드를 지원하는 초경량 자율형 자가 치유 엔진",
   "type": "module",
   "license": "MIT",

package/skills/{hi-loop → flow}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: hi-loop
+name: flow
 description: >-
   기획·설계가 필요한 기능 개발/개선 요청을 소스만 보고 바로 구현하지 말고, PLAN→DESIGN→DO→CHECK→HEAL
   자율 루프(hiloop_run)로 처리한다. spec/설계를 먼저 세우고 테스트가 통과할 때까지 반복하며, full=true면