@tuzi-ince/hi-loop 0.2.2 → 0.3.1

package/bin/hi-loop.js

@@ -34,9 +34,10 @@ const USAGE = `hi-loop — 초경량 자율형 자가 치유 엔진
                [--full] [--discover | --no-discover]
                [--watch "<헬스체크 명령>"] [--watch-for 5m] [--watch-every 30s]
                [--watch-tolerate 1] [--on-watch-fail stop|rollback|heal]
+               [--branch [name]] [--commit] [--commit-message "..."]
                [--ask auto|never|always] [--yes]
                [--start-from <stage>] [--stop-after <stage>]
-                 stage: DISCOVER | PLAN | BUILD | CODE_REVIEW | SHIP | WATCH
+                 stage: DISCOVER | PLAN | BUILD | CODE_REVIEW | COMMIT | SHIP | WATCH
 
 단계별 실행 (전부 같은 상태 머신을 쓴다):
   hi-loop discover --goal "<요구사항>"  발굴만 하고 멈춤 (가정 확정 + 문서 생성)
@@ -50,6 +51,8 @@ const USAGE = `hi-loop — 초경량 자율형 자가 치유 엔진
   hi-loop answer <선택> [--note "..."] 대기 중인 질문에 답하고 루프를 재개 가능 상태로 되돌림
   hi-loop rollback [--to N] [--cwd .]  N회차 직전 체크포인트로 파일 복원 (기본: 최신)
   hi-loop setup [--dry-run]        프로젝트/클로드코드 설정 자동 주입
+  hi-loop config [set <k> <v> | add-branch <b> | remove-branch <b>]
+                                   브랜치·커밋 정책(.hi-loop.json) 조회·변경
   hi-loop --help | --version
 
 환경변수:
@@ -76,7 +79,7 @@ const USAGE = `hi-loop — 초경량 자율형 자가 치유 엔진
 export async function main(argv = process.argv.slice(2)) {
   const args = parseArgs(argv, {
     alias: { g: 'goal', t: 'test', c: 'cwd', h: 'help', v: 'version', m: 'max-loops' },
-    boolean: ['help', 'version', 'dry-run', 'no-stagnation', 'verify-spec', 'flaky-probe', 'yes', 'review', 'no-review', 'design-review', 'no-design-review', 'full', 'discover', 'no-discover'],
+    boolean: ['help', 'version', 'dry-run', 'no-stagnation', 'verify-spec', 'flaky-probe', 'yes', 'review', 'no-review', 'design-review', 'no-design-review', 'full', 'discover', 'no-discover', 'commit'],
     // 개수가 정해지지 않은 입력. `--check A --when X --check B` 처럼 위치로 짝을 맺는다.
     repeat: ['check', 'when'],
   });
@@ -133,11 +136,19 @@ export async function main(argv = process.argv.slice(2)) {
         return 2;
       }
 
+      // 정책 병합 (FR-16): 플래그가 우선, 없으면 `.hi-loop.json`.
+      // 헤드리스라 물어볼 수 없으므로 'always'/'auto' 만 자동 발동한다('ask'/'confirm' 은 스킬 몫).
+      const { loadConfig } = await import('../src/config.js');
+      const config = loadConfig(cwd);
+      const options = { ...parsed.options, protectedBranches: config.protectedBranches, commitStyle: config.commitStyle };
+      if (options.branch == null && config.branchPolicy === 'always') options.branch = true;
+      if (!options.commit && config.commitPolicy === 'auto') options.commit = true;
+
       const { runLoop } = await import('../src/loop.js');
       const result = await runLoop({
         goal,
         cwd,
-        ...parsed.options,
+        ...options,
         logger: (line) => process.stdout.write(`${line}\n`),
       });
       // awaiting 은 성공도 실패도 아니다. 0 을 주면 `hi-loop run && 배포` 같은 스크립트가
@@ -221,6 +232,38 @@ export async function main(argv = process.argv.slice(2)) {
       process.stdout.write(`${report.lines.join('\n')}\n`);
       return 0;
     }
+    case 'config': {
+      // hi-loop config                        현재 정책 출력
+      // hi-loop config set <key> <value>       정책 변경 (branchPolicy|commitPolicy|commitStyle)
+      // hi-loop config add-branch <name>       보호 브랜치 추가
+      // hi-loop config remove-branch <name>    보호 브랜치 제거
+      const cfg = await import('../src/config.js');
+      const sub = args._[1];
+      if (!sub) {
+        process.stdout.write(`${JSON.stringify(cfg.loadConfig(cwd), null, 2)}\n`);
+        return 0;
+      }
+      if (sub === 'set') {
+        const r = cfg.setPolicy(cwd, args._[2], args._[3]);
+        if (!r.ok) {
+          process.stderr.write(`${r.reason}\n`);
+          return 2;
+        }
+        process.stdout.write(`✓ ${args._[2]} = ${args._[3]}\n`);
+        return 0;
+      }
+      if (sub === 'add-branch' || sub === 'remove-branch') {
+        const r = sub === 'add-branch' ? cfg.addBranch(cwd, args._[2]) : cfg.removeBranch(cwd, args._[2]);
+        if (!r.ok) {
+          process.stderr.write(`${r.reason}\n`);
+          return 2;
+        }
+        process.stdout.write(`✓ 보호 브랜치: ${r.config.protectedBranches.join(', ')}\n`);
+        return 0;
+      }
+      process.stderr.write(`알 수 없는 config 하위명령: ${sub} (가능: set, add-branch, remove-branch)\n`);
+      return 2;
+    }
     default:
       process.stderr.write(`알 수 없는 명령: ${command}\n\n${USAGE}\n`);
       return 2;

package/bin/setup.js

@@ -14,6 +14,27 @@ export const GITIGNORE_ENTRY = '.agent-state.json';
 // 런타임 부산물 — 커밋되면 안 된다. 락(L4)은 pid 마다 다르고, 상태는 캐시다.
 export const GITIGNORE_ENTRIES = ['.agent-state.json', '.agent-state.lock'];
 
+// CLAUDE.md 에 심는 상시 지침 — LLM 이 "기획/설계가 필요한 요청"을 hi-loop 으로
+// 라우팅하도록 하는 push 표면이다. MCP 도구는 pull(모델이 먼저 떠올려야 호출)이라
+// 이것만으로는 부족하다(근본원인). 마커로 감싸 멱등 갱신한다.
+export const CLAUDE_MD_BEGIN = '<!-- hi-loop:begin -->';
+export const CLAUDE_MD_END = '<!-- hi-loop:end -->';
+export const CLAUDE_MD_BLOCK = `${CLAUDE_MD_BEGIN}
+## hi-loop 워크플로
+
+기능 추가·개선·리팩터처럼 **기획/설계가 선행되어야 하는 요청**은 소스만 보고 바로 구현하지 말고,
+\`hi-loop\` 스킬(또는 MCP 도구 \`hiloop_run\`, \`full: true\`)로 PLAN→DESIGN→DO→CHECK→HEAL 루프를 돌린다.
+
+- 트리거: 기획, 설계, 구현, 개선, 기능 추가, 리팩터, plan, design, feature, PDCA, TDD
+- 예외: 오타·1줄 수정·문구 변경 등 사소한 작업은 루프 없이 바로 처리한다.
+- MCP 도구가 세션에서 deferred 이면 ToolSearch 로 \`hiloop_run\` 스키마를 먼저 로드한다.
+- 문법·기능 테스트 통과 후 **UI 변경이 있었으면** 사용자에게 e2e 진행 여부와 결과 화면
+  저장 여부를 확인하고, 결과서·스크린샷을 test 폴더에 저장한다. e2e 도구(Playwright MCP·
+  프로젝트 셋업)가 없으면 **임의 설치하지 말고 스킵**한다 — 통과한 루프를 실패로 만들지 않는다.
+- 코드 변경 요청은 보호 브랜치(main/master/develop/dev)면 feature 로 분기하고, 테스트 통과 후
+  **로컬 커밋**한다(정책은 커밋되는 \`.hi-loop.json\`; push/PR 은 안 함). "이번만"과 "앞으로"를 구분한다.
+${CLAUDE_MD_END}`;
+
 /** 이 setup 파일과 나란히 있는 실제 CLI 진입점의 절대 경로 */
 export function cliEntryPath() {
   return join(dirname(fileURLToPath(import.meta.url)), 'hi-loop.js');
@@ -60,6 +81,27 @@ export function mergeGitignore(content) {
   return { changed, content: text };
 }
 
+/**
+ * `CLAUDE.md` 에 hi-loop 지침 블록을 병합한다 (FR-6.5).
+ * 마커가 없으면 파일 끝에 붙이고, 있으면 그 사이를 최신 블록으로 교체한다(버전 갱신).
+ * 그 외 사용자 내용은 건드리지 않는다.
+ */
+export function mergeClaudeMd(content) {
+  const text = typeof content === 'string' ? content : '';
+  const start = text.indexOf(CLAUDE_MD_BEGIN);
+  if (start !== -1) {
+    const endMarker = text.indexOf(CLAUDE_MD_END, start);
+    if (endMarker !== -1) {
+      const end = endMarker + CLAUDE_MD_END.length;
+      const current = text.slice(start, end);
+      if (current === CLAUDE_MD_BLOCK) return { changed: false, content: text };
+      return { changed: true, content: `${text.slice(0, start)}${CLAUDE_MD_BLOCK}${text.slice(end)}` };
+    }
+  }
+  const prefix = text.length === 0 ? '' : text.endsWith('\n\n') ? '' : text.endsWith('\n') ? '\n' : '\n\n';
+  return { changed: true, content: `${text}${prefix}${CLAUDE_MD_BLOCK}\n` };
+}
+
 export function runSetup({ cwd = process.cwd(), dryRun = false } = {}) {
   const root = resolve(cwd);
   const lines = [];
@@ -104,7 +146,18 @@ export function runSetup({ cwd = process.cwd(), dryRun = false } = {}) {
     }
   }
 
-  lines.push('', '이제 사용하세요:', '  hi-loop run --goal "요구사항" --test "npm test"', '  또는 에이전트에서 MCP 도구 hiloop_run 호출');
+  // 4) CLAUDE.md — 기획/설계 요청을 hi-loop 으로 라우팅하는 상시 지침 (FR-6.5)
+  const cmdPath = join(root, 'CLAUDE.md');
+  const cmd = mergeClaudeMd(existsSync(cmdPath) ? readFileSync(cmdPath, 'utf8') : '');
+  if (cmd.changed) {
+    write(cmdPath, cmd.content);
+    changes.push('CLAUDE.md');
+    lines.push(`${dryRun ? '[dry-run] ' : ''}✓ CLAUDE.md 에 hi-loop 워크플로 지침을 주입했습니다.`);
+  } else {
+    lines.push('· CLAUDE.md 지침은 이미 최신입니다.');
+  }
+
+  lines.push('', '이제 사용하세요:', '  hi-loop run --goal "요구사항" --test "npm test"', '  또는 에이전트에서 MCP 도구 hiloop_run 호출 (스킬: /hi-loop)');
   return { changes, lines, dryRun };
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tuzi-ince/hi-loop",
-  "version": "0.2.2",
+  "version": "0.3.1",
   "description": "CLI와 MCP 모드를 지원하는 초경량 자율형 자가 치유 엔진",
   "type": "module",
   "license": "MIT",
@@ -24,6 +24,7 @@
   "files": [
     "bin",
     "src",
+    "skills",
     "docs",
     "README.md"
   ],

package/skills/hi-loop/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: hi-loop
+description: >-
+  기획·설계가 필요한 기능 개발/개선 요청을 소스만 보고 바로 구현하지 말고, PLAN→DESIGN→DO→CHECK→HEAL
+  자율 루프(hiloop_run)로 처리한다. spec/설계를 먼저 세우고 테스트가 통과할 때까지 반복하며, full=true면
+  발굴·설계리뷰·코드리뷰까지 전체 라이프사이클을 돈다. Use this whenever the user asks to build or improve
+  a feature that benefits from planning/design before coding, or mentions the hi-loop/PDCA/TDD lifecycle.
+  Triggers: 기획, 설계, 구현, 개선, 기능 추가, 리팩터, plan, design, implement, feature, improve, refactor,
+  PDCA, TDD, lifecycle, 자가치유, self-healing, hi-loop, hiloop.
+user-invocable: true
+---
+
+# hi-loop 라이프사이클
+
+기능 추가·개선처럼 **기획/설계가 선행되어야 하는 작업**을 자율 자가치유 루프로 몰고 간다.
+소스만 훑고 바로 코드부터 짜는 대신, spec→설계→구현→검증→치유를 hi-loop 엔진이 돌게 한다.
+
+## 언제 이 스킬을 쓰나
+- 사용자가 새 기능/개선/리팩터를 요청했고, 곧장 구현하기보다 **기획·설계 단계가 필요할 때**.
+- 사용자가 hi-loop / PDCA / TDD 라이프사이클을 명시했을 때.
+- 예외(루프 없이 바로 처리): 오타·1줄 수정·문구 변경 같은 사소한 작업.
+
+## 실행 절차
+
+1. **목표(goal) 확정.** 사용자의 요청을 한 문장의 goal로 정리한다.
+   모호하면 먼저 짧게 확인한다(무엇을·어디서·성공 기준).
+
+2. **정책 확인 & 브랜치 게이트 (git 워크플로).** 코드를 바꾸는 요청이면 루프 전에 정책을 본다.
+   git 저장소가 아니면 이 단계를 건너뛴다.
+   - `.hi-loop.json` 을 읽는다. **없으면** 아래 "정책 관리 → 최초 1회"를 먼저 수행해 만든다.
+   - 현재 브랜치: `git rev-parse --abbrev-ref HEAD`.
+   - 현재 브랜치가 `protectedBranches`(기본 main/master/develop/dev)에 **속하면** `branchPolicy` 대로:
+     - `always` → `feature/<slug>` 생성·전환(`git switch -c`) 후 알린다.
+     - `ask` → "지금 `<브랜치>`입니다. feature 브랜치로 분기할까요? (제안: `feature/<slug>`)" 물어 승인 시 분기.
+     - `never` → 분기하지 않는다.
+   - 이미 feature 브랜치(보호 대상 아님)면 조용히 진행한다.
+
+3. **MCP 도구 로드.** hi-loop MCP 도구는 세션에서 *deferred*(이름만)일 수 있다.
+   먼저 스키마를 불러온다:
+   `ToolSearch` → `select:mcp__plugin_hi-loop_hi-loop__hiloop_run,mcp__plugin_hi-loop_hi-loop__hiloop_answer`
+
+4. **루프 실행.** `hiloop_run` 을 호출한다:
+   - `goal`: 위에서 정한 목표
+   - `full: true` — 발굴·설계리뷰·코드리뷰를 포함한 전체 라이프사이클
+   - `testCommand`: 프로젝트의 테스트 명령(기본 `npm test`)
+   - 필요 시 `maxLoops`, `ship`, `watch`
+
+5. **사용자 선택 처리.** 응답이 `⏸ 사용자의 선택이 필요합니다` 로 오면,
+   그 질문을 **그대로 사용자에게 제시**하고 답을 받는다. 답을 `hiloop_answer`
+   (`choice`, 필요하면 `note`)로 전달한 뒤, **같은 goal 로 `hiloop_run` 을 다시 호출**해 이어간다.
+
+6. **결과 보고.** `✅ 통과` / `❌ 실패` 와 반복 횟수, 그리고 함께 온 Gaps(검증 한계)를
+   사용자에게 전한다. false green(테스트만 초록이고 실제 미완)을 통과로 포장하지 않는다.
+
+7. **UI 변경 시 e2e 게이트.** 문법·기능 테스트가 통과(✅)한 뒤, 이번 변경이
+   **UI(프론트엔드 화면·컴포넌트·라우팅·스타일)** 를 건드렸는지 판단한다.
+   - UI 변경이 **없으면** 이 단계를 건너뛴다(그대로 종료).
+   - UI 변경이 **있으면** 사용자에게 **먼저 묻는다**: "UI 변경이 있었습니다. e2e 테스트를
+     진행할까요?" — 임의로 실행하지 않는다.
+
+   **e2e 실행 능력을 순서대로 탐지한다(강등 사다리).** e2e는 이미 통과한 루프의 *부가* 게이트다 —
+   없다고 루프를 실패로 만들지 않는다.
+   1. **Playwright MCP 도구가 세션에 있으면** 그걸로 실행한다(브라우저 구동·스크린샷 네이티브 지원).
+   2. 없지만 **프로젝트에 e2e 셋업이 있으면**(`@playwright/test` devDep + `test:e2e` 스크립트,
+      또는 `playwright.config.*`, 또는 `e2e` 스킬) 그 경로로 실행한다.
+   3. **둘 다 없으면** e2e 도구를 **임의로 설치하지 않는다** — Playwright + 브라우저 바이너리는
+      수백 MB다. 사용자에게 상황을 알리고 선택지를 준다: (a) 설치 후 진행, (b) 이미 있는 다른
+      도구 사용, (c) 건너뛰기. 어느 쪽도 강요하지 않고, **이 게이트를 "스킵"으로 기록**한다.
+
+   - e2e를 실제로 실행하기로 했으면 **결과 화면(스크린샷) 저장 여부도 사용자에게 묻는다**.
+     스크린샷은 **브라우저를 구동하는 도구(1·2)가 있을 때만** 가능하다 — 없으면 저장할 화면이
+     없음을 밝힌다.
+   - 완료되면 **테스트 결과서와 스크린샷을 프로젝트의 test 폴더에 저장**한다
+     (예: 리포트 `tests/e2e/report-<날짜시각>.md`, 스크린샷 `tests/e2e/screenshots/`).
+     날짜·시각은 실제 값으로 채운다. 저장 경로를 사용자에게 알린다.
+
+8. **커밋 게이트 (git 워크플로).** 테스트가 통과(✅)하고 e2e 게이트까지 끝나면 `commitPolicy` 대로
+   **로컬** 커밋한다. **push/PR 은 하지 않는다.** git 저장소가 아니면 건너뛴다.
+   - `off` → 커밋하지 않는다(사용자가 직접).
+   - 메시지는 **기존 `git log` 스타일에 맞춘다**(`git log --oneline -20` 로 언어·규칙 파악).
+     `commitStyle` 이 `conventional`/`korean` 이면 그 형식.
+   - `confirm` → `git status` 와 diff 요약을 제시하고 승인받는다. **미관련 변경이 섞였으면 반드시
+     드러낸다**(몰래 `git add -A` 하지 않는다). 승인 시 커밋.
+   - `auto` → 확인 없이 커밋.
+   - 커밋 후 SHA·메시지를 알린다.
+
+## 정책 관리 (.hi-loop.json)
+
+브랜치·커밋 정책은 프로젝트 루트의 **커밋되는** `.hi-loop.json` 하나에 산다(팀 공유, 스킬·엔진 공용).
+`.agent-state.json`(임시·gitignore)과 다르다.
+
+### 최초 1회 (지연 발동)
+코드변경 요청인데 `.hi-loop.json` 이 **없으면**, 진행 전에 딱 한 번 묻고 저장한다:
+> "보호 브랜치(main/master/develop/dev)일 때 매 요청을 feature 브랜치로 분기·관리할까요?
+>  (always/ask/never)  그리고 테스트 통과 후 커밋은? (auto/confirm/off)"
+
+답을 `branchPolicy`·`commitPolicy` 로 파일에 쓴다. 파일을 직접 작성하거나
+`hi-loop config set <key> <value>` 를 쓴다(둘 다 같은 파일). 이후엔 조용히 적용한다(다시 안 묻는다).
+
+### 정책 변경 요청 (평문)
+사용자가 말로 정책을 바꾸면 `.hi-loop.json` 을 갱신하고 확인한다:
+- "release 도 보호 대상에 넣어줘" → `protectedBranches` 에 추가 (`hi-loop config add-branch release`)
+- "dev는 보호에서 빼줘" → 제거 (`hi-loop config remove-branch dev`)
+- "앞으로 커밋 자동으로" → `commitPolicy = auto`  ·  "auto commit 꺼줘" → `commitPolicy = off`
+
+### 🔴 "이번만" vs "앞으로" — 반드시 구분
+- **"이번엔 커밋/분기 하지 마"** → 저장된 정책은 **그대로 두고** 이번 요청만 건너뛴다(일회성).
+- **"앞으로 커밋/분기 하지 마"** → `.hi-loop.json` 을 **영구 변경**한다.
+
+일회성 지시가 팀 공유 정책을 실수로 바꾸지 않게 한다.
+우선순위: **이번 요청 지시 > `.hi-loop.json` > 기본값**.
+
+## 보조 도구
+- `hiloop_status` — 현재 `.agent-state.json` 루프 상태 요약
+- `hiloop_rollback` — git 체크포인트로 파일 복원(회차 지정 가능)
+- `hiloop_reset` — 루프 상태 초기화
+- `hiloop_setup` — 프로젝트에 `.mcp.json`·`.gitignore`·`docs/`·`tests/`·CLAUDE.md 규칙 주입

package/src/cli-options.js

@@ -12,7 +12,7 @@
 import { parseDuration, WATCH_DEFAULTS } from './ship.js';
 import { normalizeAskPolicy } from './ask.js';
 
-export const STAGE_NAMES = ['DISCOVER', 'PLAN', 'BUILD', 'CODE_REVIEW', 'SHIP', 'WATCH'];
+export const STAGE_NAMES = ['DISCOVER', 'PLAN', 'BUILD', 'CODE_REVIEW', 'COMMIT', 'SHIP', 'WATCH'];
 
 const bad = (message) => ({ ok: false, message });
 
@@ -128,6 +128,11 @@ export function parseRunOptions(args, { staged = {} } = {}) {
       checks: pairChecks(args.check, args.when),
       shipCommand: str('ship'),
       watchCommand: str('watch'),
+      // git 워크플로 (FR-16). --branch 단독=자동명(true), --branch <name>=지정명.
+      // 값 병합(config 의 branchPolicy/commitPolicy)은 bin/hi-loop.js 가 한다 — 여기선 플래그만.
+      branch: args.branch === undefined ? null : given(args.branch) ? String(args.branch) : true,
+      commit: Boolean(args.commit),
+      commitMessage: str('commit-message'),
       onShipFail,
       onWatchFail,
       askPolicy,

package/src/config.js

@@ -0,0 +1,112 @@
+/**
+ * 프로젝트 정책 저장소 `.hi-loop.json` (FR-16) — 브랜치·커밋 워크플로의 단일 진실 원천.
+ *
+ * `.agent-state.json`(임시·gitignore, goal 마다 리셋)과 **다르다**: 이 파일은 팀이 공유하는
+ * **영속 정책**이라 커밋 대상이다(그래서 .gitignore 에 넣지 않는다).
+ *
+ * 스킬 층(대화형)과 엔진 층(헤드리스)이 같은 파일을 읽어 정책을 일관되게 적용한다.
+ * 손상된 JSON 에도 죽지 않고 기본값으로 폴백한다 — 정책 파일 하나가 루프를 막으면 안 된다.
+ */
+import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+export const CONFIG_FILE = '.hi-loop.json';
+
+/** 보호 브랜치일 때: always=자동 분기 | ask=매번 확인 | never=분기 안 함 */
+export const BRANCH_POLICIES = ['ask', 'always', 'never'];
+/** 테스트 통과 후: confirm=메시지+diff 확인 후 | auto=자동 | off=커밋 안 함 */
+export const COMMIT_POLICIES = ['confirm', 'auto', 'off'];
+/** 커밋 메시지 형식: match-log=git log 스타일 미러 | conventional | korean */
+export const COMMIT_STYLES = ['match-log', 'conventional', 'korean'];
+
+export const DEFAULT_CONFIG = Object.freeze({
+  version: 1,
+  protectedBranches: ['main', 'master', 'develop', 'dev'],
+  branchPolicy: 'ask',
+  commitPolicy: 'confirm',
+  commitStyle: 'match-log',
+});
+
+export function configPathFor(cwd) {
+  return join(cwd, CONFIG_FILE);
+}
+
+/** 파일이 있으면 기본값 위에 병합, 없거나 손상되면 기본값. 알 수 없는 값은 기본값으로 교정. */
+export function loadConfig(cwd) {
+  const path = configPathFor(cwd);
+  let raw = null;
+  if (existsSync(path)) {
+    try {
+      raw = JSON.parse(readFileSync(path, 'utf8'));
+    } catch {
+      raw = null; // 손상된 정책 파일은 무시하고 기본값 (루프를 막지 않는다)
+    }
+  }
+  return normalizeConfig(raw);
+}
+
+/** 신뢰할 수 없는 입력을 스키마에 맞춰 교정한다 — 잘못된 값이 조용히 통과하지 않게. */
+export function normalizeConfig(raw) {
+  const r = raw && typeof raw === 'object' ? raw : {};
+  const branches = Array.isArray(r.protectedBranches)
+    ? [...new Set(r.protectedBranches.filter((b) => typeof b === 'string' && b.trim()).map((b) => b.trim()))]
+    : [...DEFAULT_CONFIG.protectedBranches];
+  const pick = (v, allowed, def) => (allowed.includes(v) ? v : def);
+  return {
+    version: 1,
+    protectedBranches: branches,
+    branchPolicy: pick(r.branchPolicy, BRANCH_POLICIES, DEFAULT_CONFIG.branchPolicy),
+    commitPolicy: pick(r.commitPolicy, COMMIT_POLICIES, DEFAULT_CONFIG.commitPolicy),
+    commitStyle: pick(r.commitStyle, COMMIT_STYLES, DEFAULT_CONFIG.commitStyle),
+  };
+}
+
+/** 병합된(정규화된) 정책을 파일에 쓴다. 항상 정규화 후 저장해 파일이 스키마를 벗어나지 않게. */
+export function saveConfig(cwd, config) {
+  const normalized = normalizeConfig(config);
+  writeFileSync(configPathFor(cwd), `${JSON.stringify(normalized, null, 2)}\n`, 'utf8');
+  return normalized;
+}
+
+/**
+ * 정책 한 항목 변경 (`hi-loop config set <key> <value>` / 평문 요청).
+ * 반환: `{ ok, config }` 또는 `{ ok:false, reason }` — 던지지 않는다.
+ */
+export function setPolicy(cwd, key, value) {
+  const allowed = {
+    branchPolicy: BRANCH_POLICIES,
+    commitPolicy: COMMIT_POLICIES,
+    commitStyle: COMMIT_STYLES,
+  };
+  if (!(key in allowed)) {
+    return { ok: false, reason: `알 수 없는 정책 키: ${key} (가능: ${Object.keys(allowed).join(', ')})` };
+  }
+  if (!allowed[key].includes(value)) {
+    return { ok: false, reason: `--${key} 는 ${allowed[key].join('|')} 중 하나여야 합니다: ${value}` };
+  }
+  const config = { ...loadConfig(cwd), [key]: value };
+  return { ok: true, config: saveConfig(cwd, config) };
+}
+
+/** 보호 브랜치 추가 (중복 무시). */
+export function addBranch(cwd, name) {
+  const branch = String(name ?? '').trim();
+  if (!branch) return { ok: false, reason: '브랜치 이름이 비어 있습니다.' };
+  const config = loadConfig(cwd);
+  if (config.protectedBranches.includes(branch)) {
+    return { ok: true, config, changed: false };
+  }
+  config.protectedBranches.push(branch);
+  return { ok: true, config: saveConfig(cwd, config), changed: true };
+}
+
+/** 보호 브랜치 제거. */
+export function removeBranch(cwd, name) {
+  const branch = String(name ?? '').trim();
+  const config = loadConfig(cwd);
+  if (!config.protectedBranches.includes(branch)) {
+    return { ok: true, config, changed: false };
+  }
+  config.protectedBranches = config.protectedBranches.filter((b) => b !== branch);
+  return { ok: true, config: saveConfig(cwd, config), changed: true };
+}

package/src/loop.js

@@ -15,6 +15,7 @@ import { makeAgentRunner, makeTestRunner } from './runners.js';
 import { makeIntegrityChecker } from './integrity.js';
 import { acquireLock } from './lock.js';
 import { makeCheckpointer, makeFileLister, makeChangeLister } from './checkpoint.js';
+import { makeBrancher, makeCommitter, branchPreStep } from './vcs.js';
 import { makeTreeKeyReader } from './treekey.js';
 import { makeOutcome } from './outcome.js';
 import { makeSpecVerifier } from './verify.js';
@@ -32,7 +33,7 @@ export { createState, loadState, saveState, statePathFor, summarizeState, resetS
 export { applyAnswer, formatAsk, normalizeAskPolicy } from './ask.js';
 
 /** BUILD 이후의 stage. 이 상태로 저장돼 있으면 재개 시 빌드 루프를 다시 돌지 않는다. */
-export const POST_BUILD_STAGES = ['CODE_REVIEW', 'SHIP', 'WATCH'];
+export const POST_BUILD_STAGES = ['CODE_REVIEW', 'COMMIT', 'SHIP', 'WATCH'];
 
 /**
  * 얇은 락 래퍼 (L4). 같은 cwd 에서 두 루프가 상태를 덮어쓰지 못하게 배타를 강제한다.
@@ -79,6 +80,12 @@ async function runLoopBody({
   watchEveryMs = WATCH_DEFAULTS.everyMs,
   watchTolerate = WATCH_DEFAULTS.tolerate,
   onWatchFail = 'stop',
+  // git 워크플로 (FR-16) — opt-in. branch: null=안 함 | true=자동명 | '<name>'=지정명.
+  branch = null,
+  protectedBranches = null,
+  commit = false,
+  commitMessage = null,
+  commitStyle = 'match-log',
   askPolicy = DEFAULT_ASK_POLICY,
   yes = false,
   agentRunner = makeAgentRunner(),
@@ -94,6 +101,8 @@ async function runLoopBody({
   discoverer = makeDiscoverer(),
   shipper = makeShipper(),
   watcher = makeWatcher(),
+  brancher = makeBrancher(),
+  committer = makeCommitter(),
   notifier = makeNotifier(),
   logger = (line) => process.stderr.write(`${line}\n`),
   statePath = statePathFor(cwd),
@@ -120,6 +129,10 @@ async function runLoopBody({
 
   saveState(statePath, state);
 
+  // 브랜치 프리스텝 (FR-16, opt-in): 보호 브랜치일 때만 분기. 비-git·feature·재개엔 no-op.
+  const branchedTo = await branchPreStep({ brancher, cwd, branch, goal, protectedBranches, logger });
+  if (branchedTo) { state.branch = branchedTo; saveState(statePath, state); }
+
   const notify = async (event) => {
     try {
       await notifier({ goal, maxLoops, ...event });
@@ -152,12 +165,11 @@ async function runLoopBody({
   const designReviewEnabled = designReview === null ? full || Boolean(shipCommand) : Boolean(designReview);
   const discoverEnabled = discover === null ? full : Boolean(discover);
 
-  /** BUILD 다음에 갈 곳. 켜지 않은 단계는 건너뛴다 — 기본은 종전대로 BUILD 하나뿐이다. */
-  const nextAfterBuild = () =>
-    reviewEnabled ? 'CODE_REVIEW' : shipCommand ? 'SHIP' : watchCommand ? 'WATCH' : 'DONE';
-
-  /** 리뷰를 통과했거나 상한을 소진한 뒤 갈 곳. */
-  const nextAfterReview = () => (shipCommand ? 'SHIP' : watchCommand ? 'WATCH' : 'DONE');
+  // 라우팅: 켜진 다음 단계로만 넘어간다(기본은 BUILD 하나). 커밋이 켜지면 리뷰된 코드를 먼저 커밋한다.
+  const commitEnabled = Boolean(commit);
+  const nextAfterCommit = () => (shipCommand ? 'SHIP' : watchCommand ? 'WATCH' : 'DONE');
+  const nextAfterBuild = () => (reviewEnabled ? 'CODE_REVIEW' : commitEnabled ? 'COMMIT' : nextAfterCommit());
+  const nextAfterReview = () => (commitEnabled ? 'COMMIT' : nextAfterCommit());
 
   /**
    * 사람이 골라야 하는 지점에서 멈춘다. 이미 답한 질문이면 그 답을 돌려준다.
@@ -195,6 +207,7 @@ async function runLoopBody({
     notify,
     gate,
     nextAfterReview,
+    nextAfterCommit,
     statePath,
     baselineFiles,
     designReviewEnabled,
@@ -205,6 +218,8 @@ async function runLoopBody({
       designReviewer,
       shipper,
       watcher,
+      brancher,
+      committer,
       agentRunner,
       testRunner,
       integrityChecker,
@@ -233,6 +248,9 @@ async function runLoopBody({
       handoffEvery,
       maxDesignRounds,
       stopAfter,
+      commit,
+      commitMessage,
+      commitStyle,
     },
   };
 

package/src/mcp-server.js

@@ -14,6 +14,17 @@ const log = (line) => process.stderr.write(`[hi-loop-mcp] ${line}\n`);
 const text = (t) => ({ content: [{ type: 'text', text: t }] });
 const fail = (t) => ({ content: [{ type: 'text', text: t }], isError: true });
 
+/**
+ * MCP 경로의 기본 작업 디렉터리.
+ *
+ * CLI 는 `process.cwd()` 만 본다 — 터미널에서 cd 한 곳이 곧 사용자의 명시 의도이기 때문이다.
+ * 그러나 MCP 는 호스트(클로드코드/커서)가 서버를 띄우는 경로이고, "어느 프로젝트인가"의
+ * 정답은 호스트가 주입하는 `CLAUDE_PROJECT_DIR` 다. 서버 프로세스의 cwd 가 프로젝트 루트와
+ * 다른 호스트에서도 올바른 루트를 잡으려면 이 env 를 먼저 본다. 호출자가 cwd 를 명시하면
+ * 그것이 최우선이다(각 핸들러의 인자가 이 기본값을 덮는다).
+ */
+const defaultCwd = () => process.env.CLAUDE_PROJECT_DIR || process.cwd();
+
 /** 도구 구현 (SDK 없이도 단위 테스트 가능하도록 분리) */
 export const tools = {
   hiloop_run: {
@@ -28,7 +39,7 @@ export const tools = {
       ship,
       watch,
       stopAfter,
-      cwd = process.cwd(),
+      cwd = defaultCwd(),
     }) => {
       if (!goal) return fail('goal 은 필수입니다.');
       const result = await runLoop({
@@ -66,7 +77,7 @@ export const tools = {
   hiloop_answer: {
     description:
       'hiloop_run 이 반환한 대기 중인 질문에 답한다. choice 는 제시된 선택지의 키(a, b, ...)이고, note 로 자유 서술을 덧붙이거나 대신할 수 있다. 답한 뒤 hiloop_run 을 같은 goal 로 다시 호출하면 이어서 진행된다.',
-    handler: async ({ choice, note = '', cwd = process.cwd() } = {}) => {
+    handler: async ({ choice, note = '', cwd = defaultCwd() } = {}) => {
       const statePath = statePathFor(cwd);
       const state = loadState(statePath);
       if (!state?.ask) return fail('대기 중인 질문이 없습니다.');
@@ -79,17 +90,17 @@ export const tools = {
   },
   hiloop_status: {
     description: '현재 워크스페이스의 .agent-state.json 루프 상태 요약을 반환한다.',
-    handler: async ({ cwd = process.cwd() } = {}) => text(summarizeState(loadState(statePathFor(cwd)))),
+    handler: async ({ cwd = defaultCwd() } = {}) => text(summarizeState(loadState(statePathFor(cwd)))),
   },
   hiloop_reset: {
     description: '.agent-state.json 을 삭제해 루프 상태를 초기화한다.',
-    handler: async ({ cwd = process.cwd() } = {}) =>
+    handler: async ({ cwd = defaultCwd() } = {}) =>
       text(resetState(statePathFor(cwd)) ? '상태를 초기화했습니다.' : '초기화할 상태가 없습니다.'),
   },
   hiloop_rollback: {
     description:
       'git 체크포인트로 파일을 되돌린다. to(회차)를 주면 그 회차 직전 스냅샷으로, 없으면 가장 최근 체크포인트로 복원한다.',
-    handler: async ({ to, cwd = process.cwd() } = {}) => {
+    handler: async ({ to, cwd = defaultCwd() } = {}) => {
       const state = loadState(statePathFor(cwd));
       const checkpoints = state?.checkpoints ?? [];
       if (checkpoints.length === 0)
@@ -112,7 +123,7 @@ export const tools = {
   hiloop_setup: {
     description:
       '프로젝트에 hi-loop 설정(.mcp.json MCP 서버 등록, .gitignore 항목, docs/tests 디렉터리)을 자동 주입한다. dryRun 이면 변경 없이 계획만 보여준다.',
-    handler: async ({ dryRun = false, cwd = process.cwd() } = {}) => {
+    handler: async ({ dryRun = false, cwd = defaultCwd() } = {}) => {
       const report = runSetup({ cwd, dryRun: Boolean(dryRun) });
       return text(report.lines.join('\n'));
     },
@@ -147,7 +158,10 @@ export async function startMcpServer({ version = '0.1.0' } = {}) {
   }
 
   const server = new McpServer({ name: 'hi-loop', version });
-  const cwdSchema = z.string().optional().describe('작업 디렉터리 (기본: 서버 프로세스의 cwd)');
+  const cwdSchema = z
+    .string()
+    .optional()
+    .describe('작업 디렉터리 (기본: CLAUDE_PROJECT_DIR → 없으면 서버 프로세스의 cwd)');
 
   server.registerTool(
     'hiloop_run',

package/src/stages.js

@@ -105,6 +105,36 @@ export async function runCodeReviewStage(ctx) {
   return { next: ctx.nextAfterReview() };
 }
 
+/**
+ * COMMIT (FR-16) — 테스트·리뷰를 통과한 코드를 로컬에 커밋한다. 에이전트를 부르지 않는다(비용 0).
+ *
+ * 헤드리스 opt-in(`--commit`)이므로 여기서 게이트를 걸지 않는다 — 플래그 자체가 동의다.
+ * 대화형 확인(diff 보고 승인)은 스킬 층이 LLM 레벨에서 담당한다(역할 분리).
+ * 커밋은 되돌릴 수 있으므로(로컬), 변경이 없거나 비-git 이면 실패로 만들지 않고 조용히 지나간다.
+ */
+export async function runCommitStage(ctx) {
+  const { goal, cwd, logger, ports, opts } = ctx;
+  ctx.state.status = 'running';
+  ctx.save();
+
+  const res = await ports.committer({
+    cwd,
+    goal,
+    message: opts.commitMessage ?? null,
+    styleConfig: opts.commitStyle ?? 'match-log',
+    logger,
+  });
+
+  if (res.committed) {
+    ctx.state.commit = { sha: res.sha, message: res.message, at: new Date().toISOString() };
+    ctx.save();
+  } else if (res.reason && res.reason !== 'non-git') {
+    // 변경 없음 등은 실패가 아니다 — 이유만 남기고 진행한다.
+    logger(`[hi-loop] · 커밋하지 않았습니다 — ${res.reason}`);
+  }
+  return { next: ctx.nextAfterCommit() };
+}
+
 /** SHIP (FR-13) — 판정은 exit code 뿐. 에이전트를 부르지 않으므로 비용은 0이다. */
 export async function runShipStage(ctx) {
   const { cwd, logger, ports, opts, gate, notify } = ctx;
@@ -223,6 +253,7 @@ export async function runWatchStage(ctx) {
 export const STAGE_HANDLERS = {
   DISCOVER: runDiscoverStage,
   CODE_REVIEW: runCodeReviewStage,
+  COMMIT: runCommitStage,
   SHIP: runShipStage,
   WATCH: runWatchStage,
 };