@tuzi-ince/hi-loop 0.4.3 → 0.6.1

package/README.md

@@ -34,8 +34,14 @@ npm install -g @tuzi-ince/hi-loop
 # 2) 프로젝트에 주입 (멱등 — 여러 번 돌려도 안전)
 cd /path/to/my-project
 hi-loop-setup            # .mcp.json / .gitignore / docs·tests / CLAUDE.md / docs/DESIGN.md 자동 주입
+hi-loop-setup --host cursor     # Cursor 용 .cursor/mcp.json 에 등록
+hi-loop-setup --host opencode   # opencode 용 opencode.json 에 등록
 ```
 
+> MCP 서버는 표준 stdio 라 Cursor·opencode 등 다른 호스트에도 `--host` 로 등록된다. 단 스킬·CLAUDE.md
+> 자동 라우팅은 **Claude Code 전용**이고, 다른 호스트에선 루프의 일꾼도 claude 가 아니라면 `HILOOP_AGENT_PROVIDER=generic`
+> 이 필요하다(claude 외 CLI 이식 — 세션·비용 미지원). 자세히는 [가이드 §4-2/§4-3](docs/guide.md).
+
 `hi-loop-setup` 은 **표준 설계 문서 `docs/DESIGN.md`** 를 함께 만든다(있으면 보존). 이 문서를 채우면
 문서↔소스 정합 장치(`--reconcile-spec` / `--spec`)의 오라클이 된다 — 아래 [문서↔소스 정합](#문서를-상시-오라클로--표준-문서-고정---spec) 참조.
 
@@ -61,7 +67,7 @@ hi-loop mcp
 hi-loop status           # 현재 루프 상태 요약
 ```
 
-MCP 도구: `hiloop_run`, `hiloop_answer`, `hiloop_status`, `hiloop_reset`, `hiloop_rollback`, `hiloop_setup`.
+MCP 도구: `hiloop_run`, `hiloop_answer`, `hiloop_status`, `hiloop_reset`, `hiloop_rollback`, `hiloop_setup`, `hiloop_docsync`.
 
 ## 동작 원리
 
@@ -293,7 +299,8 @@ hi-loop run --goal "..." --start-from BUILD --stop-after CODE_REVIEW
 
 | 사용자가 이렇게 말하면 | LLM이 하는 일 |
 |---|---|
-| `/hi-loop:flow 로그인 폼 만들어줘` (슬래시 스킬) | `flow` 스킬 기동 → `hiloop_run(full=true)` 실행 (bare `/hi-loop` 은 명령이지 이 스킬이 아님) |
+| `/flow 로그인 폼 만들어줘` (슬래시 스킬, `/hi-loop:flow` 도 동일) | `flow` 스킬 기동 → `hiloop_run(full=true, step=true)` 실행 — 대화형이라 스텝 모드로 매 스텝을 보이며 진행 |
+| `/flow plan 로그인 폼` (단계어) | 첫 단어가 단계면 그 단계까지만: `stopAfter:"PLAN"` → 스펙·테스트만 만들고 멈춰 **다음(구현) 제안**. `do`/`review`/`ship` 등도 동일 |
 | "hiloop_run 도구로 결제 버그 고쳐줘" | 지목된 MCP 도구를 로드해 바로 호출 |
 | 터미널에서 `hi-loop run --goal "..." --full` | 엔진을 CLI로 직접 구동(LLM 개입 없음) |
 
@@ -304,7 +311,7 @@ hi-loop run --goal "..." --start-from BUILD --stop-after CODE_REVIEW
 
 | 사용자가 이렇게 말하면 | 어디에 걸리나 | LLM이 하는 일 |
 |---|---|---|
-| "워크스페이스 폴더 드래그앤드롭 **개선**해줘" | 트리거 `개선` | hi-loop 스킬 후보로 뜸 → 기획·설계 필요 판단 → `hiloop_run(full=true)` 제안·실행 |
+| "워크스페이스 폴더 드래그앤드롭 **개선**해줘" | 트리거 `개선` | `flow` 스킬 후보로 뜸 → 기획·설계 필요 판단 → `flow` 실행(대화형이라 `step` 으로 매 스텝 보이며 진행) |
 | "장바구니 **기능** 하나 **만들어**줘" | 트리거 `기능/design` | 발굴→스펙·테스트 우선(PLAN)→구현·리뷰 루프 |
 | "결제 모듈 **리팩터**해줘" | 트리거 `리팩터` | 기존 테스트를 가드레일로 `--verify-spec` 성격의 개선 루프 |
 | "동시 요청 시 잔액 음수 **버그** 고쳐줘" | 트리거 `구현/버그성` | **재현 테스트 먼저** → HEAL 루프로 수정 |
@@ -468,6 +475,20 @@ hi-loop run --goal "결제에서 음수 잔액도 허용하라" --reconcile   #
 > 이것이 "단말적 요청이 문서와 상이하게 들어와 갭이 벌어지는" 상황을 **엔진 차원에서** 막는
 > 장치다. `--spec`(고정)과 `--reconcile`(감지)은 짝으로 쓰면 문서↔소스 정합이 가장 단단하다.
 
+### 소스를 바꿨으면 문서도 맞춘다 — `hiloop_docsync` / `hi-loop docsync` / `/flow doc-sync`
+
+`--spec`/`--reconcile`이 drift를 **예방**하는 게이트라면, doc-sync는 **이미 바뀐 소스에 맞춰 문서를
+갱신**하는 단발 패스다. `git diff`로 소스 변경을 읽어 일꾼 에이전트가 **문서만**(README·docs/*) 고친다.
+
+```bash
+hi-loop docsync            # 소스 변경 → 문서 반영 (한 번의 패스, 진행 표시)
+# 또는 스킬: /flow doc-sync   ·   MCP: hiloop_docsync
+```
+
+- **`docs/DESIGN.md`(사람 오라클)와 소스·테스트는 건드리지 않는다.** 문서 외 편집은 `stray`로 경고.
+- diff로 확인되는 것만 반영한다(없는 내용을 지어내지 않음). 커밋은 사람이 판단한다.
+- 자가 치유 루프가 아니라 짧은 단발이라 타임아웃/블랙박스가 없다. MCP/CLI라 소비 프로젝트에서도 동작.
+
 ### 에이전트를 못 부르면 스택이 아니라 지침을 준다 (preflight)
 
 에이전트(claude) 미설치·인증 만료·API 키 부재는 이 엔진의 버그가 아니라 환경 문제다.
@@ -501,6 +522,24 @@ MCP 도구의 `cwd` 기본값은 `CLAUDE_PROJECT_DIR || process.cwd()` 다 —
 `ask` 는 비싼 e2e 루프에 특히 유용하다 — 8.5분·수달러짜리 회차를 무인으로 반복하지 않고,
 **판정 불능(무결성·환경)**까지 사람에게 표면화한다. 무인(`--ask never`)에선 물을 수 없으니 안전하게 종료한다.
 
+### ⏭ 스텝 모드 — LLM 이 루프를 몰고, 매 스텝이 보인다 (`step`)
+
+기본은 **한 콜에서 엔진이 루프 전체**를 돈다(모델 A: 무인·결정론에 최적). 대화형에선 이게
+불투명하고(진행이 콘솔에 안 보임) 길어서 타임아웃 위험이 있으며 에이전트를 두 번(바깥 LLM +
+서브프로세스 claude) 쓴다. `step` 을 주면 **매 단위 작업(BUILD 회차·각 stage) 후 제어를 LLM 에게
+돌려준다**(모델 B):
+
+```
+hiloop_run({ goal, step: true })
+  └▶ ⏭ 스텝 완료 (PLAN) → LLM 이 진행을 알리고 같은 goal 로 재호출
+  └▶ ⏭ 스텝 완료 (DO) …  └▶ ✅ 통과 / ❌ 실패 / ⏸ awaiting
+```
+
+매 스텝이 콘솔에 보이고, 콜당 에이전트 1콜이라 타임아웃이 없다. 상태가 STATE.json 에 저장돼
+**재개는 자동**이며, 통과 판정은 그대로 엄격하다(`continue` 는 통과가 아니다). `flow` 스킬이
+대화형에서 이 모드를 기본으로 쓴다. CLI 는 `--step`(스텝 후 exit 3, 재실행으로 이어감).
+무인·완료까지 자동은 `step` 을 빼면 모델 A 그대로다.
+
 ### 💸 비용은 엔진이 센다 — 그리고 싸지 않다
 
 **`--max-loops` 는 비용 상한이 아니다.** 실패 루프가 10회를 다 쓰면 비용이 크게 뛸 수 있다.
@@ -519,7 +558,8 @@ hi-loop run --goal "..." --max-loops 5 --budget-usd 1 --no-stagnation
 | 변수 | 설명 |
 |---|---|
 | `HILOOP_AGENT_CMD` | 에이전트 실행 명령 (기본 `claude`) |
-| `HILOOP_AGENT_ARGS` | 에이전트에 덧붙일 인자 (공백 구분). 예: `--model sonnet` — 비용에 직결된다 |
+| `HILOOP_AGENT_PROVIDER` | 에이전트 CLI 계약 (기본 `claude`). `generic` 은 프롬프트를 마지막 위치인자로, stdout 을 결과로 읽는 최소 계약 — opencode 등 claude 외 CLI 를 일꾼으로 쓸 때. 단 **세션 재개·비용 집계는 없다** |
+| `HILOOP_AGENT_ARGS` | 에이전트에 덧붙일 인자 (공백 구분). 예: `--model sonnet` — 비용에 직결된다. `generic` 에선 프롬프트 앞 서브커맨드로 쓰임(예: `run`) |
 | `HILOOP_PERMISSION_MODE` | 권한 모드 (기본 `acceptEdits`). 편집 허용이 이 엔진의 전제다 |
 | `HILOOP_VERIFY_CMD` / `HILOOP_VERIFY_MODEL` | `--verify-spec` 검증자의 실행 명령·모델 (미설정 시 구현자와 동일). 검증에 더 센 모델을 쓸 수 있다 |
 | `HILOOP_REVIEW_CMD` / `HILOOP_REVIEW_MODEL` | 설계·코드 리뷰어의 실행 명령·모델 (미설정 시 `HILOOP_VERIFY_*` → 구현자 순으로 폴백) |

package/bin/hi-loop.js

@@ -28,7 +28,7 @@ const USAGE = `hi-loop — 초경량 자율형 자가 치유 엔진
 사용법:
   hi-loop run --goal "<요구사항>" [--test "npm test"] [--max-loops 10] [--budget-usd 5]
                [--stagnation 3 | --no-stagnation] [--on-fail heal|ask|stop] [--verify-spec]
-               [--spec docs/DESIGN.md] [--cwd .]
+               [--step] [--spec docs/DESIGN.md] [--cwd .]
                [--ship "<배포 명령>"] [--on-ship-fail stop|heal]
                [--review | --no-review] [--max-review-rounds 2]
                [--design-review | --no-design-review] [--max-design-rounds 2]
@@ -53,6 +53,7 @@ const USAGE = `hi-loop — 초경량 자율형 자가 치유 엔진
   hi-loop answer <선택> [--note "..."] 대기 중인 질문에 답하고 루프를 재개 가능 상태로 되돌림
   hi-loop rollback [--to N] [--cwd .]  N회차 직전 체크포인트로 파일 복원 (기본: 최신)
   hi-loop setup [--dry-run]        프로젝트/클로드코드 설정 자동 주입
+  hi-loop docsync [--cwd .]        소스 변경(git diff)을 문서에 반영하는 단발 패스(DESIGN.md 제외)
   hi-loop config [set <k> <v> | add-branch <b> | remove-branch <b>]
                                    브랜치·커밋 정책(.hi-loop.json) 조회·변경
   hi-loop --help | --version
@@ -81,7 +82,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', 'reconcile', 'no-reconcile', 'commit'],
+    boolean: ['help', 'version', 'dry-run', 'no-stagnation', 'verify-spec', 'flaky-probe', 'yes', 'review', 'no-review', 'design-review', 'no-design-review', 'full', 'discover', 'no-discover', 'reconcile', 'no-reconcile', 'commit', 'step'],
     // 개수가 정해지지 않은 입력. `--check A --when X --check B` 처럼 위치로 짝을 맺는다.
     repeat: ['check', 'when'],
   });
@@ -165,9 +166,9 @@ export async function main(argv = process.argv.slice(2)) {
         ...options,
         logger: (line) => process.stdout.write(`${line}\n`),
       });
-      // awaiting 은 성공도 실패도 아니다. 0 을 주면 `hi-loop run && 배포` 같은 스크립트가
-      // 질문에 답도 안 한 채 다음 단계로 넘어간다. 1 을 주면 진짜 실패와 구분이 안 된다.
-      if (result.status === 'awaiting') return 3;
+      // awaiting/continue 는 "종료가 아니라 재호출이 필요"한 상태다(전자는 답을, 후자는 다음 스텝을).
+      // 0 을 주면 `hi-loop run && 배포` 가 미완인데 넘어가고, 1 을 주면 진짜 실패와 구분이 안 된다.
+      if (result.status === 'awaiting' || result.status === 'continue') return 3;
       // stopped 는 시킨 것을 다 한 것이다. 실패가 아니다.
       if (result.status === 'stopped') return 0;
       return result.status === 'passed' ? 0 : 1;
@@ -196,6 +197,18 @@ export async function main(argv = process.argv.slice(2)) {
       process.stdout.write(`${report.lines.join('\n')}\n`);
       return 0;
     }
+    case 'docsync': {
+      // FR-25: 소스 변경을 문서에 반영하는 단발 패스(루프 아님). 문서만 고친다.
+      const { runDocSync } = await import('../src/docsync.js');
+      const res = await runDocSync({ cwd, logger: (l) => process.stdout.write(`${l}\n`) });
+      if (!res.ok) {
+        process.stderr.write(`${res.reason}\n`);
+        return 1;
+      }
+      if (res.stray?.length) process.stdout.write(`⚠️ 문서 외 파일 변경(검토 요망): ${res.stray.join(', ')}\n`);
+      if (res.note) process.stdout.write(`\n${res.note}\n`);
+      return 0;
+    }
     default:
       process.stderr.write(`알 수 없는 명령: ${command}\n\n${USAGE}\n`);
       return 2;

package/bin/setup.js

@@ -24,7 +24,10 @@ export const CLAUDE_MD_BLOCK = `${CLAUDE_MD_BEGIN}
 ## hi-loop 워크플로
 
 기능 추가·개선·리팩터처럼 **기획/설계가 선행되어야 하는 요청**은 소스만 보고 바로 구현하지 말고,
-\`hi-loop\` 스킬(또는 MCP 도구 \`hiloop_run\`, \`full: true\`)로 PLAN→DESIGN→DO→CHECK→HEAL 루프를 돌린다.
+**\`flow\` 스킬(\`/hi-loop:flow\`)** 로 PLAN→DESIGN→DO→CHECK→HEAL 자율 루프를 돌린다 — 스킬이 브랜치
+게이트·스텝 진행·ask 재개·e2e·커밋까지 프로토콜로 감싼다. 스킬을 거치지 않고 MCP 도구 \`hiloop_run\`
+을 직접 부를 땐 **대화형이면 \`step: true\` 를 반드시 준다**(매 단위 후 제어를 돌려받아 진행을 사용자에게
+보이며 이어 호출 — 빼면 루프 전체가 한 콜에서 조용히 돌아 진행이 안 보이고 타임아웃 위험). 전과정은 \`full: true\`.
 
 **응답 언어는 사용자의 요청 언어에 맞춘다** — 한국어 요청엔 한국어로, 영어 요청엔 영어로 답한다. hi-loop 도구·서브에이전트 결과(리포트·Gaps 등)를 옮길 때도 사용자 언어로 전한다.
 
@@ -91,13 +94,36 @@ function readJson(path) {
   }
 }
 
-/** `.mcp.json` 병합 — 기존 서버 항목 보존 (FR-6.1, FR-6.4) */
+/** `.mcp.json` 병합 — 기존 서버 항목 보존 (FR-6.1, FR-6.4). Claude Code·Cursor 공용 스키마 */
 export function mergeMcpConfig(existing) {
   const base = existing && typeof existing === 'object' ? existing : {};
   const servers = base.mcpServers && typeof base.mcpServers === 'object' ? base.mcpServers : {};
   return { ...base, mcpServers: { ...servers, [MCP_SERVER_KEY]: serverEntry() } };
 }
 
+/** opencode 는 `mcp` 키에 `type:'local'` + command 배열 스키마를 쓴다 (FR-6.8) */
+export const opencodeServerEntry = (entry = cliEntryPath()) => ({
+  type: 'local',
+  command: [process.execPath, entry, 'mcp'],
+  environment: {},
+});
+export function mergeOpencodeConfig(existing) {
+  const base = existing && typeof existing === 'object' ? existing : {};
+  const mcp = base.mcp && typeof base.mcp === 'object' ? base.mcp : {};
+  return { ...base, mcp: { ...mcp, [MCP_SERVER_KEY]: opencodeServerEntry() } };
+}
+
+/**
+ * MCP 서버를 어느 호스트 설정에 쓸지 (FR-6.8, `--host`).
+ * `claudeMd`=true 인 호스트만 CLAUDE.md 자동 라우팅 지침을 심는다 — 스킬·CLAUDE.md 는
+ * Claude Code 전용이라 다른 호스트에선 도구를 직접 호출한다.
+ */
+export const HOSTS = {
+  claude: { label: 'Claude Code', path: '.mcp.json', merge: mergeMcpConfig, claudeMd: true },
+  cursor: { label: 'Cursor', path: '.cursor/mcp.json', merge: mergeMcpConfig, claudeMd: false },
+  opencode: { label: 'opencode', path: 'opencode.json', merge: mergeOpencodeConfig, claudeMd: false },
+};
+
 /** `.gitignore` 항목 추가 — 중복 없이 (FR-6.2) */
 export function mergeGitignore(content) {
   let text = typeof content === 'string' ? content : '';
@@ -133,25 +159,28 @@ export function mergeClaudeMd(content) {
   return { changed: true, content: `${text}${prefix}${CLAUDE_MD_BLOCK}\n` };
 }
 
-export function runSetup({ cwd = process.cwd(), dryRun = false } = {}) {
+export function runSetup({ cwd = process.cwd(), dryRun = false, host = 'claude' } = {}) {
   const root = resolve(cwd);
+  const spec = HOSTS[host] || HOSTS.claude;
   const lines = [];
   const changes = [];
   const write = (path, content) => {
-    if (!dryRun) writeFileSync(path, content, 'utf8');
+    if (dryRun) return;
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, content, 'utf8');
   };
 
-  // 1) .mcp.json
-  const mcpPath = join(root, '.mcp.json');
+  // 1) 호스트 MCP 설정 (--host: claude=.mcp.json / cursor=.cursor/mcp.json / opencode=opencode.json)
+  const mcpPath = join(root, spec.path);
   const before = readJson(mcpPath);
-  const merged = mergeMcpConfig(before);
+  const merged = spec.merge(before);
   const mcpChanged = JSON.stringify(before) !== JSON.stringify(merged);
   if (mcpChanged) {
     write(mcpPath, `${JSON.stringify(merged, null, 2)}\n`);
-    changes.push('.mcp.json');
-    lines.push(`${dryRun ? '[dry-run] ' : ''}✓ .mcp.json 에 hi-loop MCP 서버를 등록했습니다.`);
+    changes.push(spec.path);
+    lines.push(`${dryRun ? '[dry-run] ' : ''}✓ ${spec.path} 에 hi-loop MCP 서버를 등록했습니다 (${spec.label}).`);
   } else {
-    lines.push('· .mcp.json 은 이미 최신입니다.');
+    lines.push(`· ${spec.path} 은 이미 최신입니다 (${spec.label}).`);
   }
 
   // 2) .gitignore
@@ -188,22 +217,29 @@ export function runSetup({ cwd = process.cwd(), dryRun = false } = {}) {
     lines.push(`· ${DESIGN_DOC_PATH} 이미 존재합니다 (내용 보존).`);
   }
 
-  // 5) 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 워크플로 지침을 주입했습니다.`);
+  // 5) CLAUDE.md — 기획/설계 요청을 hi-loop 으로 라우팅하는 상시 지침 (FR-6.5).
+  // 스킬·CLAUDE.md 자동 라우팅은 Claude Code 전용이라 다른 호스트에선 건너뛴다.
+  if (spec.claudeMd) {
+    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 지침은 이미 최신입니다.');
+    }
   } else {
-    lines.push('· CLAUDE.md 지침은 이미 최신입니다.');
+    lines.push(`· ${spec.label} 은 CLAUDE.md 자동 라우팅 대상이 아닙니다 — 에이전트에서 hiloop_run 을 직접 호출하세요.`);
   }
 
   lines.push(
     '',
     '이제 사용하세요:',
     '  hi-loop run --goal "요구사항" --test "npm test"',
-    '  또는 에이전트에서 MCP 도구 hiloop_run 호출 (스킬: /hi-loop)',
+    spec.claudeMd
+      ? '  또는 에이전트에서 MCP 도구 hiloop_run 호출 (스킬: /hi-loop:flow)'
+      : `  또는 ${spec.label} 에서 MCP 도구 hiloop_run 을 직접 호출`,
     `  · ${DESIGN_DOC_PATH} 를 채우면 --reconcile-spec/--spec 오라클로 문서↔소스 정합을 지킵니다.`,
   );
   return { changes, lines, dryRun };
@@ -211,6 +247,10 @@ export function runSetup({ cwd = process.cwd(), dryRun = false } = {}) {
 
 if (isMain(import.meta.url)) {
   const args = parseArgs(process.argv.slice(2), { alias: { c: 'cwd' }, boolean: ['dry-run'] });
-  const report = runSetup({ cwd: args.cwd ?? process.cwd(), dryRun: Boolean(args['dry-run']) });
+  const host = args.host && HOSTS[args.host] ? args.host : 'claude';
+  if (args.host && !HOSTS[args.host]) {
+    process.stderr.write(`알 수 없는 --host '${args.host}'. 지원: ${Object.keys(HOSTS).join(', ')}. claude 로 진행합니다.\n`);
+  }
+  const report = runSetup({ cwd: args.cwd ?? process.cwd(), dryRun: Boolean(args['dry-run']), host });
   process.stdout.write(`${report.lines.join('\n')}\n`);
 }

package/docs/DESIGN.md

@@ -56,9 +56,10 @@
 | `src/state.js` | 상태 스키마·저장·절단·산출물 경로·resume·에러 지문·Gaps 보고 | 230 |
 | `bin/hi-loop.js` | CLI 진입점 (+rollback) | 161 |
 | `src/integrity.js` | 테스트 무결성 지문·비교 (L1) | 131 |
-| `src/runners.js` | 프로세스 spawn (+타임아웃 env), 응답·비용 파싱 (L6) | 129 |
-| `src/prompts.js` | 단계별 프롬프트 + 검증자 프롬프트 조립 | 125 |
+| `src/runners.js` | 프로세스 spawn (+타임아웃 env), 응답·비용 파싱 (L6), 프로바이더 어댑터 (FR-23) | 163 |
+| `src/prompts.js` | 단계별 프롬프트 + 검증자 + doc-sync 프롬프트 조립 | 296 |
 | `bin/setup.js` | 설정 주입 진입점 | 115 |
+| `src/docsync.js` | DOC-SYNC 단발 패스 — diff 수집·문서 갱신·stray 검증 (FR-25) | 100 |
 | `src/mcp-server.js` | MCP 도구 등록/응답 포맷 | 102 |
 | `src/verify.js` | 스펙 오라클 — Tier 2 검증자 (L9) | 96 |
 | `src/checkpoint.js` | git stash 체크포인트·롤백 (L3) + 삭제 관측 (L8) | 94 |
@@ -495,13 +496,17 @@ runLoop({ agentRunner, testRunner, notifier, logger, statePath })
 
 | 포트 | 계약 | 프로덕션 어댑터 | 테스트 스텁 |
 |---|---|---|---|
-| `agentRunner` | `({prompt, sessionId, cwd}) => {text, sessionId}` | `claude -p … --output-format json [--resume]` | 호출 기록 배열 |
+| `agentRunner` | `({prompt, sessionId, cwd}) => {text, sessionId}` | 프로바이더 어댑터(`claude` 기본 / `generic`), spawn·타임아웃은 공유 | 호출 기록 배열 |
 | `testRunner` | `({command, cwd}) => {ok, code, stdout, stderr}` | `spawn(cmd, {shell:true})` | 정해둔 성패 시퀀스 |
 | `notifier` | `(event) => void` | 텔레그램 | 이벤트 타입 수집 |
 
 - **세션 왕복**: 러너가 `sessionId` 를 돌려주고 엔진이 그것을 다음 호출에 넣는다.
   엔진은 세션이 CLI 플래그인지 HTTP 헤더인지 모른다 → `claude` 외 다른 에이전트로 교체 가능
   (`HILOOP_AGENT_CMD`).
+- **프로바이더 어댑터**(FR-23): 인자 구성·출력 파싱을 `HILOOP_AGENT_PROVIDER` 로 고르는
+  `{buildArgs, parseOutput}` 쌍으로 분리. `claude`(세션·비용 지원, 기본)와 `generic`(프롬프트를
+  마지막 위치인자로, stdout=텍스트, 세션·비용 없음 — opencode 등). `makeAgentRunner` 는 어댑터
+  두 함수만 호출하고 spawn·타임아웃·에러 분기는 공유한다.
 - **에이전트 응답 파싱**: `--output-format json` 의 `{result, session_id}` 를 읽되,
   JSON 이 아니면 원문을 텍스트로 쓰고 기존 세션을 유지한다(관대한 파싱).
 - **실패 처리 비대칭**: `testRunner` 의 실패는 **정상 입력**(치유할 재료)이라 resolve 로 흘리고,
@@ -638,6 +643,9 @@ hi-loop run --goal "두 수를 더하는 add 함수를 만들어라" --test "npm
 | FR-4 MCP 서버 | §7 | `src/mcp-server.js` | AC-20 |
 | FR-5 텔레그램 | §8 | `src/telegram.js` | AC-12~14 |
 | FR-6 setup | — | `bin/setup.js` | AC-17, 18 |
+| FR-23 에이전트 프로바이더 어댑터 | §9 | `src/runners.js` (`AGENT_ADAPTERS`, `getAgentAdapter`) | app.test.js 어댑터 4종 |
+| FR-24 스텝 모드(LLM 드리븐) | §4 | `src/loop.js`·`src/build.js`·`src/outcome.js` (`stepResult`) | tests/step.test.js |
+| FR-25 DOC-SYNC(소스→문서 단발 패스) | §9 | `src/docsync.js`·`src/prompts.js`(`docSyncPrompt`)·`src/mcp-server.js`·`bin/hi-loop.js` | tests/docsync.test.js |
 | NFR-3 주입 가능 | §6 | `src/runners.js` | 전 테스트가 네트워크 없이 동작 |
 | NFR-4 원자적 저장 | §4.4 | `src/state.js` | AC-19 |
 

package/docs/SPEC.md

@@ -258,9 +258,18 @@ runLoop({
   않는다**(사람이 관리하는 진실). FR-21 정합 게이트·FR-19 스펙 고정의 오라클 대상이다. PLAN 이
   쓰는 `SPEC.md` 와 달리 엔진은 이 파일을 손대지 않는다.
 - FR-6.7 `CLAUDE.md` 에 hi-loop 워크플로 라우팅 지침을 마커(`<!-- hi-loop:begin/end -->`)로 감싸
-  멱등 주입한다. 코드 변경 루프가 `docs/DESIGN.md` 와 정합하도록(`--reconcile-spec`/`--spec`) 안내하고,
-  **응답 언어를 사용자의 요청 언어에 맞추라는 지시**를 포함한다 — 영어 스킬/도구/프레임워크 표면이
-  많아도 한국어 요청엔 한국어로 답하도록(언어 드리프트 방지).
+  멱등 주입한다. **`flow` 스킬(`/hi-loop:flow`)을 1순위 경로로 지목**한다 — 스킬명을 실제와 일치시켜야
+  LLM 이 "스킬을 못 찾아 도구로 새는" 오라우팅을 막는다(실측 근본원인: 존재하지 않는 "hi-loop 스킬"을
+  가리켜 `hiloop_run` 직접 호출로 샜다). 스킬을 거치지 않고 도구를 직접 부를 땐 **대화형이면 `step:true`
+  를 강제**한다(모델 B — 진행 가시성·타임아웃 제거, FR-24). 코드 변경 루프가 `docs/DESIGN.md` 와
+  정합하도록(`--reconcile-spec`/`--spec`) 안내하고, **응답 언어를 사용자의 요청 언어에 맞추라는 지시**를
+  포함한다 — 영어 스킬/도구/프레임워크 표면이 많아도 한국어 요청엔 한국어로 답하도록(언어 드리프트 방지).
+- FR-6.8 `--host claude|cursor|opencode` — MCP 서버를 어느 호스트 설정에 등록할지 고른다(기본 `claude`).
+  - `claude`: `.mcp.json`(`mcpServers` 스키마) + CLAUDE.md 라우팅 지침(FR-6.7).
+  - `cursor`: `.cursor/mcp.json`(claude 와 **같은** `mcpServers` 스키마). CLAUDE.md 는 건너뛴다.
+  - `opencode`: `opencode.json` 의 `mcp` 키에 `{type:'local', command:[node, entry, 'mcp'], environment:{}}`.
+  - CLAUDE.md·스킬 자동 라우팅은 **Claude Code 전용**이라 claude 외 호스트에선 심지 않는다(도구 직접 호출).
+    기존 `mcp`/`mcpServers` 항목은 보존(멱등). 미상값은 `claude` 로 폴백. gitignore·docs·DESIGN.md 는 공통.
 
 ---
 
@@ -466,6 +475,59 @@ DISCOVER → PLAN → DESIGN_REVIEW → DO ⇄ CHECK ⇄ HEAL → CODE_REVIEW
 - FR-22.4 **무인 안전**: `--ask never`(물을 사람 없음)에서 `on-fail ask` 는 pause 하지 않고
   안전하게 종료한다 — 답을 못 받는데 멈춰 있으면 무한/폭주가 된다.
 
+### FR-23. 에이전트 프로바이더 어댑터 — claude 외 CLI 이식 (`HILOOP_AGENT_PROVIDER`, `src/runners.js`)
+
+MCP 서버는 표준 stdio 라 어느 호스트에든 뜨지만, 루프의 **실제 일꾼**은 `claude -p …` 서브프로세스에
+고정돼 있었다(인자 구성·출력 파싱이 claude 계약 전용). 그래서 opencode 같은 다른 에이전트 CLI 를
+일꾼으로 쓸 수 없었다. 이 결합을 프로바이더 어댑터로 끊는다.
+
+- FR-23.1 `HILOOP_AGENT_PROVIDER` 로 어댑터 선택(기본 `claude`). 어댑터는 `{buildArgs, parseOutput}`
+  한 쌍이다 — `makeAgentRunner` 는 이 둘만 호출하고 spawn·타임아웃·에러 처리는 공유한다.
+- FR-23.2 `claude` 어댑터 = 종전 `buildAgentArgs`/`parseAgentOutput` **그대로**(기존 동작 불변):
+  `-p <prompt> --output-format json [--resume sid] [--permission-mode]`, `result/session_id/total_cost_usd` 파싱.
+- FR-23.3 `generic` 어댑터 = 프롬프트를 **마지막 위치인자**로(`[...extraArgs, prompt]`), stdout 을 그대로
+  텍스트로 본다. **세션 재개·비용 집계는 지원 안 함**(매 호출 새 세션, `costUsd:0`). 예: `HILOOP_AGENT_CMD=opencode`
+  `HILOOP_AGENT_ARGS=run` `HILOOP_AGENT_PROVIDER=generic` → `opencode run "<prompt>"`.
+- FR-23.4 이름이 없거나 미상값이면 `claude` 로 조용히 되돌린다(기본 경로 보존). 기능이 온전한 경로는
+  claude 이며 generic 은 이식용 최소 계약임을 문서로 명시한다(guide §4-2/§4-3).
+
+### FR-24. 스텝 모드 — LLM 이 루프를 모는 실행 (`step`, `src/loop.js`·`src/build.js`·`src/outcome.js`)
+
+기본 실행(모델 A)은 `hiloop_run` **한 콜 안에서 엔진이 루프 전체**를 돈다(BUILD 는 PLAN+DO+HEAL×
+maxLoops 를 통짜로). 이 구조의 대가: (1) 진행이 콘솔에 안 보임(바깥 LLM 이 콜 반환까지 정지),
+(2) 한 콜이 길어 MCP 클라이언트 타임아웃에 걸림(고아 루프·비용 폭주), (3) 바깥 LLM 과 서브프로세스
+claude 로 **에이전트를 두 번** 씀. 스텝 모드(모델 B)는 제어를 매 단위마다 LLM 에게 돌려준다.
+
+- FR-24.1 `step` (기본 false). true 면 **매 단위 작업 후** `status:'continue'` 로 반환한다. 단위 =
+  BUILD 안의 **한 회차**(에이전트 1콜: PLAN/DO/HEAL 각각), 그리고 outer stage 머신의 **각 stage**
+  (DISCOVER/CODE_REVIEW/SHIP/WATCH/COMMIT). 다음이 DONE 이면 양보하지 않고 그대로 통과 처리한다.
+- FR-24.2 **재개는 새 기능이 아니다** — 상태는 이미 매 지점 STATE.json 에 저장되므로, `continue` 후
+  같은 goal 로 재호출하면 기존 resume 경로가 정확히 다음 단위를 이어간다. 별도 코드 경로 없음(FR-15).
+- FR-24.3 **통과 판정 우회 금지**: `continue` 는 실패도 통과도 아니다. `stepResult` 는 상태만 저장하고
+  돌려주며, 진짜 통과는 여전히 `finish('passed')` 한 곳만 지나 checkVerdictBinding(false green 게이트)을
+  통과해야 한다. 스텝이 늘어도 통과 주장 지점은 하나다.
+- FR-24.4 **기존 동작 불변**: 기본 false 라 모델 A(무인·완료까지 자동)와 전체 회귀 스위트가 그대로다.
+  CLI `--step`, MCP `step`, 그리고 flow 스킬이 대화형에서 이 모드를 기본으로 쓴다(진행 가시성).
+- FR-24.5 MCP 응답은 `continue` 를 "⏭ 스텝 완료 … 같은 goal 로 다시 호출" 로 표면화해 LLM 이
+  진행을 사용자에게 알리고 이어 호출하게 한다. CLI 는 awaiting 과 같은 계열(종료 아님)로 exit 3.
+
+### FR-25. DOC-SYNC — 소스 변경을 문서에 반영하는 단발 패스 (`hiloop_docsync`, `src/docsync.js`)
+
+hi-loop 은 소스↔문서 drift 를 **예방**하는 게이트(FR-19/21)는 있었지만, 이미 바뀐 소스에 맞춰 문서를
+**갱신**하는 장치는 없었다(문서 동기화는 사람/어시스턴트의 수동 규율에 의존). doc-sync 는 이걸 엔진
+동작으로 만든다 — MCP/CLI 라 소비 프로젝트에서도, claude 외 일꾼으로도 동작한다(FR-23).
+
+- FR-25.1 **단발 패스**(자가 치유 루프 아님). `git diff` 로 소스 변경을 모아 일꾼 에이전트에게 주고
+  문서만 갱신하게 한다. 통과시킬 테스트가 없으므로 회차·정체·예산 개념이 없다. 짧아서 타임아웃/블랙박스가 없고 진행 알림을 보낸다.
+- FR-25.2 **diff 범위**: 커밋 안 된 변경(HEAD 대비) 우선, 없으면 마지막 커밋(HEAD~1..HEAD). 문서(.md)만
+  바뀌었으면 트리거가 없으므로(반영할 소스 변경 없음) 에이전트를 부르지 않고 종료한다(비용 0).
+- FR-25.3 **갱신 대상은 문서뿐**: `README.md`·`docs/*.md`. **`docs/DESIGN.md`(사람 오라클)와 소스·테스트는
+  건드리지 않는다**(프롬프트로 명시 + 사후 분류로 강제). diff 로 확인되는 것만 반영한다(환각 방지).
+- FR-25.4 **stray 검증**: doc-sync 실행 전후 변경 파일 집합을 비교해, 이번에 새로 바뀐 것 중 문서가
+  아닌 파일(소스·테스트·오라클)은 `stray` 로 분리 보고한다 — 어시스턴트가 경고로 표면화한다.
+- FR-25.5 표면: MCP `hiloop_docsync`, CLI `hi-loop docsync`, 스킬 `/flow doc-sync`(goal 불필요).
+  안전망으로 실행 전 체크포인트를 뜬다(잘못 고치면 `hiloop_rollback`). 커밋은 하지 않는다(사람이 판단).
+
 ---
 
 ## 3. 비기능 요구사항