@tuzi-ince/hi-loop 0.4.1 → 0.6.0

package/src/docsync.js

@@ -0,0 +1,100 @@
+/**
+ * DOC-SYNC (FR-25) — 소스 변경을 문서에 반영하는 단발 패스.
+ *
+ * 자가 치유 루프가 아니다(통과시킬 테스트가 없다). git diff 로 소스 변경을 모아 일꾼
+ * 에이전트에게 주고, **문서만** 소스에 맞춰 갱신하게 한다. 사람이 관리하는 표준 오라클
+ * (docs/DESIGN.md)은 절대 건드리지 않는다. 짧은 단발이라 긴 루프의 블랙박스/타임아웃이 없다.
+ */
+import { execFile } from 'node:child_process';
+import { makeAgentRunner } from './runners.js';
+import { makeCheckpointer, makeChangeLister, isGitRepo } from './checkpoint.js';
+import { docSyncPrompt } from './prompts.js';
+
+function git(args, cwd) {
+  return new Promise((resolve) => {
+    execFile('git', args, { cwd, maxBuffer: 4 * 1024 * 1024 }, (err, stdout) => {
+      resolve(err ? null : String(stdout));
+    });
+  });
+}
+
+const isMd = (f) => /\.md$/i.test(f);
+/** 사람이 관리하는 표준 오라클 — doc-sync 도 손대면 안 된다. */
+export const isOracleDoc = (f) => /(^|\/)(DESIGN|design)\.md$/.test(f);
+/** doc-sync 가 갱신해도 되는 문서인가: 마크다운이되 오라클은 제외. */
+export const isEditableDoc = (f) => isMd(f) && !isOracleDoc(f);
+
+/**
+ * 반영할 **소스(비-문서) 변경**의 diff 를 읽는다. 커밋 안 된 변경(HEAD 대비)을 우선하고,
+ * 없으면 마지막 커밋을 본다. 문서(.md)만 바뀌었으면 트리거가 없으므로 빈 문자열.
+ */
+export function makeSourceDiffReader() {
+  return async ({ cwd }) => {
+    const uncommitted = (await git(['diff', 'HEAD', '--name-only'], cwd)) || '';
+    let range = ['HEAD'];
+    let files = uncommitted.split('\n').filter(Boolean);
+    if (!files.length) {
+      const last = (await git(['diff', 'HEAD~1', 'HEAD', '--name-only'], cwd)) || '';
+      files = last.split('\n').filter(Boolean);
+      range = ['HEAD~1', 'HEAD'];
+    }
+    const sourceFiles = files.filter((f) => !isMd(f));
+    if (!sourceFiles.length) return '';
+    return (await git(['diff', ...range, '--', ...sourceFiles], cwd)) || '';
+  };
+}
+
+/**
+ * doc-sync 한 번 실행. 반환:
+ *   { ok:true, changed:[문서], stray:[문서 외 편집], note, costUsd }
+ *   { ok:false, reason }  — 비-git 등 실행 불가
+ */
+export async function runDocSync({
+  cwd = process.cwd(),
+  logger = () => {},
+  agentRunner = makeAgentRunner(),
+  checkpointer = makeCheckpointer(),
+  changeLister = makeChangeLister(),
+  diffReader = makeSourceDiffReader(),
+  isRepo = isGitRepo,
+  docTargets = null,
+} = {}) {
+  if (!(await isRepo(cwd))) {
+    return { ok: false, reason: 'git 저장소가 아니라 소스 변경(diff)을 읽을 수 없습니다.' };
+  }
+
+  logger('[hi-loop] 🔎 소스 변경 대조 중…');
+  const diffText = await diffReader({ cwd });
+  if (!diffText.trim()) {
+    return { ok: true, changed: [], stray: [], note: '반영할 소스 변경이 없습니다(문서만 바뀌었거나 변경 없음).' };
+  }
+
+  // 안전망: 에이전트가 손대기 전 스냅샷. 잘못 고치면 rollback 으로 되돌린다.
+  await checkpointer({ cwd });
+  const before = new Set((await changeLister({ cwd })) ?? []);
+
+  logger('[hi-loop] 📝 문서 갱신 중…');
+  const result = await agentRunner({ prompt: docSyncPrompt({ diffText, docTargets }), cwd });
+
+  const after = (await changeLister({ cwd })) ?? [];
+  const touched = after.filter((f) => !before.has(f));
+  const changed = touched.filter(isEditableDoc);
+  const stray = touched.filter((f) => !isEditableDoc(f));
+
+  logger(
+    changed.length
+      ? `[hi-loop] ✅ 문서 ${changed.length}개 갱신: ${changed.join(', ')}`
+      : '[hi-loop] ✅ 갱신할 문서 변경이 없었습니다.',
+  );
+  if (stray.length) logger(`[hi-loop] ⚠️ 문서 외 파일이 변경됨(검토 요망): ${stray.join(', ')}`);
+
+  return {
+    ok: true,
+    changed,
+    stray,
+    note: typeof result?.text === 'string' ? result.text.slice(0, 800) : '',
+    costUsd: Number.isFinite(result?.costUsd) ? result.costUsd : 0,
+  };
+}
+
+export default runDocSync;

package/src/loop.js

@@ -23,7 +23,7 @@ import { makeNotifier } from './telegram.js';
 import { makeShipper, makeWatcher, WATCH_DEFAULTS } from './ship.js';
 import { makeCodeReviewer, makeDesignReviewer } from './review.js';
 import { makeDiscoverer } from './discover.js';
-import { formatAsk, createAsk, pauseForAsk, shouldAsk, DEFAULT_ASK_POLICY } from './ask.js';
+import { formatAsk, createAsk, pauseForAsk, shouldAsk, onFailAsk, DEFAULT_ASK_POLICY } from './ask.js';
 import { STAGE_HANDLERS } from './stages.js';
 import { runBuildLoop } from './build.js';
 import { buildStageContext } from './stage-context.js';
@@ -65,6 +65,7 @@ async function runLoopBody({
   flakyProbe = false,
   specPath = null, // --spec: 스펙 오라클을 표준 문서로 고정(FR-19). null=엔진이 경로 결정.
   checks = null,
+  onFail = 'heal', // FR-22: CHECK 실패/불능 시 안쪽 루프 처리. heal(자동) | ask(사람에게) | stop(중단).
   handoffEvery = 4,
   // ---- 라이프사이클 (FR-13, FR-14) ----
   shipCommand = null,
@@ -78,10 +79,10 @@ async function runLoopBody({
   reconcile = null, // FR-21: 문서 정합 게이트. null=자동(--full 또는 reconcileSpec 지정 시 켜짐).
   reconcileSpec = null, // 대조할 표준 문서 경로. null=기본 docs/DESIGN.md.
   full = false,
-  // FR-15: 어느 경로로 들어와도 **같은 상태 머신**을 쓴다. 별도 코드 경로를 만들지 않는다
-  // — 분기가 둘이면 반드시 한쪽이 썩는다.
+  // FR-15: 어느 경로로 들어와도 **같은 상태 머신**을 쓴다 — 분기가 둘이면 한쪽이 썩는다.
   startFrom = null,
   stopAfter = null,
+  step = false, // FR-24 스텝 모드(opt-in): 매 단위(BUILD 회차·각 stage) 후 호출자에게 양보. 기본 false=완료까지 자동(모델 A).
   watchCommand = null,
   watchForMs = WATCH_DEFAULTS.forMs,
   watchEveryMs = WATCH_DEFAULTS.everyMs,
@@ -155,7 +156,7 @@ async function runLoopBody({
   // null 이면 비-git — 관측 자체가 불가능하니 아래에서 조용히 건너뛴다(인프라 fail-open).
   const baselineFiles = await fileLister({ cwd });
 
-  const { finish, stopResult, pauseResult } = makeOutcome({
+  const { finish, stopResult, pauseResult, stepResult } = makeOutcome({
     getState: () => state,
     setState: (v) => { state = v; },
     statePath, cwd, logger, notify, treeKeyReader,
@@ -197,15 +198,12 @@ async function runLoopBody({
     return { pause: true };
   };
 
-  // FR-21: 문서 정합 게이트. 기존 표준 문서(docs/DESIGN.md)가 있고 이번 요청이 그것과 별개
-  // 스펙으로 포크될 참이면, 조용히 갈라지기 전에 모순 여부를 판정한다. 모순이면 사람에게 묻는다.
-  // 대조 대상: 명시(--reconcile-spec)가 최우선. 없으면 사람 관리 표준 문서(docs/DESIGN.md)를
-  // 우선하고, 그다음 스펙 순으로 폴백한다. 대문자=정본, 소문자=구버전(대소문자 구분 FS 대비).
-  // spec 은 PLAN 이 쓴 에이전트 산출물이라 오라클로는 약하다 — 사람 문서가 있으면 그쪽이 옳다.
-  // (게이트 발동 자체는 여전히 opt-in 이다.)
+  // FR-21: 문서 정합 게이트. 표준 문서가 있고 이번 요청이 별개 스펙으로 포크될 참이면, 조용히
+  // 갈라지기 전에 모순 여부를 판정한다(모순이면 사람에게 물음). 대조 대상: --reconcile-spec 최우선,
+  // 없으면 사람 관리 정본(대문자) → 구버전(소문자) 순 폴백. spec 은 PLAN 산출물이라 오라클로는 약하다.
   const firstExisting = (...ps) => ps.find((p) => existsSync(join(cwd, p)));
   const STANDING_SPEC = reconcileSpec
-    || firstExisting('docs/DESIGN.md', 'docs/DESIGN.md', 'docs/SPEC.md', 'docs/DESIGN.md')
+    || firstExisting('docs/DESIGN.md', 'docs/design.md', 'docs/SPEC.md', 'docs/spec.md')
     || 'docs/DESIGN.md';
   if (reconcileEnabled && !state.reconciled && !state.specPinned
       && state.specPath !== STANDING_SPEC && existsSync(join(cwd, STANDING_SPEC))) {
@@ -245,14 +243,13 @@ async function runLoopBody({
       shipCommand, watchCommand, onShipFail, onWatchFail, watchForMs, watchEveryMs,
       watchTolerate, maxReviewRounds, maxLoops, budgetUsd, testCommand, stagnationLimit,
       verifySpec, flakyProbe, checks, handoffEvery, maxDesignRounds, stopAfter,
-      commit, commitMessage, commitStyle,
+      commit, commitMessage, commitStyle, onFail, askPolicy, step,
     },
   });
 
   // ---- stage 머신 ----
   // 다음 stage 를 정하는 권한은 여기 한 곳에만 있다. 핸들러는 지시만 돌려준다.
-  // 재개 시 stage 가 이미 BUILD 이후면 빌드 루프를 다시 돌지 않는다 — 통과한 빌드를
-  // 다시 돌리면 비용을 두 번 내고, 최악의 경우 이미 배포된 코드를 또 고친다.
+  // 재개 시 stage 가 BUILD 이후면 빌드를 다시 안 돈다 — 비용 이중 지불·배포된 코드 재수정 방지.
   if (startFrom) state.stage = startFrom;
   else if (!POST_BUILD_STAGES.includes(state.stage)) {
     state.stage = discoverEnabled && !state.discovery ? 'DISCOVER' : 'BUILD';
@@ -268,11 +265,20 @@ async function runLoopBody({
       state.status = 'running';
       saveState(statePath, state);
       const built = await runBuildLoop(ctx);
+      // FR-22: on-fail ask — 빌드 루프가 실패/불능에서 사람 판단을 요청하며 멈췄다.
+      if (built.paused) {
+        state.ask = createAsk(onFailAsk(built.onFail));
+        state.status = 'awaiting';
+        return pauseResult();
+      }
+      // FR-24: 스텝 모드 — 한 회차만 돌고 제어를 돌려준다(아직 통과 전). resume 으로 이어간다.
+      if (built.continue) return stepResult({ next: 'BUILD', phase: built.phase });
       if (built.stopped) return stopResult('PLAN');
       if (!built.ok) return finish('failed', { stopReason: built.stopReason, detail: built.detail });
       if (shouldStopAfter('BUILD')) return stopResult('BUILD');
       state.stage = nextAfterBuild();
       saveState(statePath, state);
+      if (step && state.stage !== 'DONE') return stepResult({ next: state.stage }); // FR-24: 다음 stage 앞 양보
       continue;
     }
 
@@ -288,7 +294,7 @@ async function runLoopBody({
 
     state.stage = directive.next;
     saveState(statePath, state);
+    if (step && state.stage !== 'DONE') return stepResult({ next: state.stage }); // FR-24: stage 후 양보
   }
 }
-
 export default runLoop;

package/src/mcp-server.js

@@ -4,6 +4,7 @@
  * ⚠️ stdout 은 MCP 프로토콜 채널이다. 로그는 반드시 stderr 로만 낸다 (FR-4.2).
  */
 import { runLoop } from './loop.js';
+import { runDocSync } from './docsync.js';
 import { loadState, saveState, statePathFor, summarizeState, resetState } from './state.js';
 import { applyAnswer, formatAsk } from './ask.js';
 import { rollbackTo } from './checkpoint.js';
@@ -15,22 +16,32 @@ 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 를 명시하면
- * 그것이 최우선이다(각 핸들러의 인자가 이 기본값을 덮는다).
- */
+// MCP 경로의 기본 cwd: 호스트가 주입하는 CLAUDE_PROJECT_DIR 가 "어느 프로젝트인가"의 정답이다
+// (서버 cwd 가 프로젝트 루트와 다를 수 있으므로). 호출자가 cwd 를 명시하면 그것이 최우선.
 const defaultCwd = () => process.env.CLAUDE_PROJECT_DIR || process.cwd();
 
+// MCP progress: 로그 라인마다 진행 알림 전송(progressToken 준 경우만; 없으면 stderr 로만).
+function makeProgressLogger(extra) {
+  const token = extra?._meta?.progressToken;
+  let ticks = 0;
+  return (line) => {
+    log(line);
+    if (token != null && typeof extra?.sendNotification === 'function') {
+      extra
+        .sendNotification({
+          method: 'notifications/progress',
+          params: { progressToken: token, progress: (ticks += 1), message: String(line).replace(/^\[hi-loop[^\]]*\]\s*/, '').slice(0, 200) },
+        })
+        .catch(() => {});
+    }
+  };
+}
+
 /** 도구 구현 (SDK 없이도 단위 테스트 가능하도록 분리) */
 export const tools = {
   hiloop_run: {
     description:
-      '목표(goal)를 받아 PLAN→DO→CHECK→HEAL 자가 치유 루프를 실행한다. spec/테스트를 먼저 만들고, 테스트가 통과할 때까지 최대 maxLoops회 반복한다. full=true 면 발굴·설계리뷰·코드리뷰까지 도는 전체 라이프사이클로 실행한다. ship/watch 를 주면 배포와 헬스체크까지 진행한다.',
+      '목표(goal)를 받아 PLAN→DO→CHECK→HEAL 자가 치유 루프를 실행한다. spec/테스트를 먼저 만들고, 테스트가 통과할 때까지 최대 maxLoops회 반복한다. full=true 면 발굴·설계리뷰·코드리뷰까지 도는 전체 라이프사이클로 실행한다. ship/watch 를 주면 배포와 헬스체크까지 진행한다. step=true 면 매 단위 작업 후 제어를 돌려줘(status:continue) LLM 이 진행을 보이며 이어 호출한다 — 대화형·긴 작업 권장.',
     handler: async ({
       goal,
       testCommand = 'npm test',
@@ -40,17 +51,19 @@ export const tools = {
       ship,
       watch,
       stopAfter,
+      step,
       spec,
       reconcile,
       reconcileSpec,
       checks,
+      onFail,
       cwd = defaultCwd(),
-    }) => {
+    }, extra) => {
       if (!goal) return fail('goal 은 필수입니다.');
-      // 루프를 돌리기 전에 에이전트가 실행 가능한지 확인한다 — 미설치/실행불가면
-      // 회차를 태우지 않고 여기서 행동지침을 돌려준다(호스트 LLM 이 사용자에게 전달).
+      // 루프 전에 에이전트 실행 가능 여부 확인 — 미설치/불가면 회차를 안 태우고 행동지침을 돌려준다.
       const pre = await preflightAgent();
       if (!pre.ok) return fail(pre.message);
+      const runLogger = makeProgressLogger(extra);
       const result = await runLoop({
         goal,
         testCommand,
@@ -60,25 +73,31 @@ export const tools = {
         shipCommand: ship || null,
         watchCommand: watch || null,
         stopAfter: stopAfter ? String(stopAfter).toUpperCase() : null,
+        step: Boolean(step),
         specPath: spec || null,
         reconcile: reconcile === undefined ? null : Boolean(reconcile),
         reconcileSpec: reconcileSpec || null,
-        // 조건부 검사(--check/--when 의 MCP 노출): 주면 testCommand 대신 이 배열이 판정 기준이 된다.
-        // when 글롭에 맞는 파일이 바뀐 회차에만 그 검사를 돌린다(UI 변경 회차에만 e2e 등).
+        // 조건부 검사(MCP 노출): 주면 testCommand 대신 이 배열이 기준. when 글롭에 맞는 파일이 바뀐 회차만.
         checks: Array.isArray(checks) && checks.length ? checks : null,
+        onFail: onFail || 'heal',
         cwd,
-        logger: log,
+        logger: runLogger,
       });
 
-      // 사람이 골라야 하는 지점에서 멈췄다. 호스트 LLM 이 이 질문을 사용자에게 그대로
-      // 제시하고 hiloop_answer 로 답을 돌려주면 재개된다 — MCP 의 단일 요청/응답
-      // 제약과 충돌하지 않는 유일한 방법이다.
+      // 사람이 골라야 하는 지점에서 멈췄다. 질문을 사용자에게 제시하고 hiloop_answer 로 답하면 재개.
       if (result.status === 'awaiting') {
         return text(
           `⏸ 사용자의 선택이 필요합니다. 아래 질문을 그대로 사용자에게 제시하고, 답을 받아 hiloop_answer 를 호출하세요.\n\n${formatAsk(result.ask)}\n\n(hiloop_answer 인자: choice="${(result.ask.options ?? []).map((o) => o.key).join('" 또는 "')}", 필요하면 note)`,
         );
       }
 
+      // FR-24 스텝 모드: 한 단위만 돌고 돌아왔다. 진행을 알리고 같은 goal 로 재호출해 이어간다.
+      if (result.status === 'continue') {
+        return text(
+          `⏭ 스텝 완료 (${result.phase ?? result.next}) — ${result.iterations}회차까지 진행. 아직 미완이니 같은 goal 로 hiloop_run(step:true)을 다시 호출해 이어가세요.\n\n${summarizeState(result.state)}`,
+        );
+      }
+
       const head =
         result.status === 'passed' ? '✅ 통과' : result.status === 'stopped' ? `⏹ ${result.stoppedAt} 까지 진행 후 정지` : '❌ 실패';
       // 통과 시 Gaps 를 붙인다 — 에이전트가 도구로 이 결과를 받을 때 false green 을
@@ -143,13 +162,27 @@ export const tools = {
       return text(report.lines.join('\n'));
     },
   },
+  hiloop_docsync: {
+    description:
+      '소스 변경(git diff)을 읽어 관련 문서(README·docs/*, docs/DESIGN.md 제외)를 소스에 맞춰 갱신하는 단발 패스. 테스트 루프가 아니라 짧게 끝난다(진행 알림 지원). 문서 외 파일이 바뀌면 stray 로 보고한다. 소스 변경 후 문서↔소스 일치를 맞출 때 쓴다.',
+    handler: async ({ cwd = defaultCwd() } = {}, extra) => {
+      const pre = await preflightAgent();
+      if (!pre.ok) return fail(pre.message);
+      const res = await runDocSync({ cwd, logger: makeProgressLogger(extra) });
+      if (!res.ok) return fail(res.reason);
+      const head = res.changed.length ? `✅ 문서 ${res.changed.length}개 갱신` : `· ${res.note || '갱신할 문서 변경 없음'}`;
+      const list = res.changed.length ? `\n갱신: ${res.changed.join(', ')}` : '';
+      const stray = res.stray?.length ? `\n⚠️ 문서 외 파일 변경(검토 요망): ${res.stray.join(', ')}` : '';
+      return text(`${head}${list}${stray}${res.note ? `\n\n${res.note}` : ''}`);
+    },
+  },
 };
 
-/** 예외를 isError 응답으로 감싼다 (FR-4.4) */
+/** 예외를 isError 응답으로 감싼다 (FR-4.4). extra(progress·signal)를 핸들러에 그대로 넘긴다. */
 export function wrap(handler) {
-  return async (args) => {
+  return async (args, extra) => {
     try {
-      return await handler(args ?? {});
+      return await handler(args ?? {}, extra);
     } catch (err) {
       // 환경 오류(에이전트 미설치·인증 만료 등)는 이미 행동지침 메시지다 — 그대로 전달한다.
       if (err?.kind === 'environment') return fail(err.message);
@@ -188,35 +221,17 @@ export async function startMcpServer({ version = '0.1.0' } = {}) {
         goal: z.string().describe('달성할 요구사항'),
         testCommand: z.string().optional().describe('검증 명령 (기본 "npm test")'),
         maxLoops: z.number().int().min(1).max(50).optional().describe('최대 루프 횟수 (기본 10)'),
+        onFail: z.enum(['heal', 'ask', 'stop']).optional().describe('CHECK 실패/불능 시. heal(기본)=maxLoops 안 자동 치유 / ask=사람에게 재시도·종료를 물음(awaiting→hiloop_answer 로 답하고 재호출) / stop=즉시 종료. 대화형엔 ask 권장'),
+        step: z.boolean().optional().describe('스텝 모드. 매 단위 작업(BUILD 회차·각 stage) 후 status:"continue" 로 돌려준다 — 진행이 콘솔에 보이고 콜당 시간이 짧아 타임아웃이 없다. "⏭ 스텝 완료" 응답이 오면 같은 goal 로 다시 호출해 이어간다(✅/❌/⏸ 까지). 대화형·긴 작업에 권장'),
         verifySpec: z.boolean().optional().describe('통과 시 별도 검증자로 스펙 대비 구현을 심판 (하향 전용, 비용 증가)'),
         full: z.boolean().optional().describe('전체 라이프사이클(발굴·설계리뷰·코드리뷰)까지 실행 (비용 증가)'),
         ship: z.string().optional().describe('배포 명령. 주면 테스트 통과 후 실행하고 exit code 로 판정한다 (실행 전 사용자 확인)'),
         watch: z.string().optional().describe('배포 후 헬스체크 명령. 일정 시간 연속 통과해야 성공이다'),
-        stopAfter: z
-          .enum(['DISCOVER', 'PLAN', 'BUILD', 'CODE_REVIEW', 'SHIP', 'WATCH'])
-          .optional()
-          .describe('이 단계까지만 진행하고 멈춘다'),
-        spec: z
-          .string()
-          .optional()
-          .describe('스펙 오라클을 이 파일로 고정한다(예: docs/DESIGN.md). 사람이 관리하는 표준 문서를 여러 요청이 공유하는 오라클로 삼아 문서↔소스 drift 를 막는다. 이미 내용이 있으면 PLAN 이 덮어쓰지 않는다.'),
-        reconcile: z
-          .boolean()
-          .optional()
-          .describe('문서 정합 게이트. 기존 표준 문서와 이 요청이 모순되면 조용히 포크하지 않고 사람에게 묻는다(고정/분기/중단). full=true 또는 reconcileSpec 지정 시 자동 켜짐.'),
-        reconcileSpec: z
-          .string()
-          .optional()
-          .describe('정합 게이트가 대조할 표준 문서 경로(기본 docs/DESIGN.md). 예: docs/DESIGN.md. 지정하면 게이트가 켜진다.'),
-        checks: z
-          .array(z.object({ cmd: z.string(), when: z.string().optional() }))
-          .optional()
-          .describe(
-            '조건부 판정 검사. 주면 testCommand 대신 이 배열이 판정 기준이 된다(첫 항목에 기본 테스트를 넣을 것). ' +
-              'when 글롭(예: "src/**/*.tsx")이 있으면 그 경로가 바뀐 회차에만 그 검사를 돌린다 — ' +
-              '"UI 를 고친 회차에만 e2e" 를 엔진이 강제하는 용도. e2e 는 셸 명령이어야 한다(예: {cmd:"npx playwright test", when:"src/**/*.tsx"}). ' +
-              'short-circuit 하지 않아 유닛이 깨져도 e2e 결과를 같은 회차에 함께 본다.',
-          ),
+        stopAfter: z.enum(['DISCOVER', 'PLAN', 'BUILD', 'CODE_REVIEW', 'SHIP', 'WATCH']).optional().describe('이 단계까지만 진행하고 멈춘다'),
+        spec: z.string().optional().describe('스펙 오라클을 이 파일로 고정(예: docs/DESIGN.md). 사람이 관리하는 표준 문서를 여러 요청이 공유하는 오라클로 삼아 drift 를 막는다. 내용이 있으면 PLAN 이 덮어쓰지 않는다.'),
+        reconcile: z.boolean().optional().describe('문서 정합 게이트. 기존 표준 문서와 이 요청이 모순되면 포크 전에 사람에게 묻는다(고정/분기/중단). full=true 또는 reconcileSpec 지정 시 자동 켜짐.'),
+        reconcileSpec: z.string().optional().describe('정합 게이트가 대조할 표준 문서 경로(기본 docs/DESIGN.md). 지정하면 게이트가 켜진다.'),
+        checks: z.array(z.object({ cmd: z.string(), when: z.string().optional() })).optional().describe('조건부 판정 검사. 주면 testCommand 대신 이 배열이 기준(첫 항목에 기본 테스트). when 글롭(예: "src/**/*.tsx")이 있으면 그 경로가 바뀐 회차에만 그 검사를 돌린다 — "UI 고친 회차에만 e2e" 를 엔진이 강제. e2e 는 셸 명령(예: {cmd:"npx playwright test", when:"src/**/*.tsx"}). short-circuit 안 함.'),
         cwd: cwdSchema,
       },
     },
@@ -272,6 +287,12 @@ export async function startMcpServer({ version = '0.1.0' } = {}) {
     wrap(tools.hiloop_setup.handler),
   );
 
+  server.registerTool(
+    'hiloop_docsync',
+    { description: tools.hiloop_docsync.description, inputSchema: { cwd: cwdSchema } },
+    wrap(tools.hiloop_docsync.handler),
+  );
+
   await server.connect(new StdioServerTransport());
   log('stdio 전송으로 MCP 서버가 기동했습니다.');
   return server;

package/src/outcome.js

@@ -72,5 +72,19 @@ export function makeOutcome({ getState, setState, statePath, cwd, logger, notify
     return { status: 'awaiting', iterations: state.iteration, state: saved, ask: state.ask };
   };
 
-  return { finish, stopResult, pauseResult, setState };
+  /**
+   * 스텝 모드(FR-24) — 한 단위 작업을 끝내고 제어를 호출자(LLM)에게 돌려준다. 실패가 아니다.
+   * 상태는 그대로 저장되어 다음 hiloop_run 호출이 resume 경로로 정확히 이어간다.
+   * 통과 판정을 여기서 하지 않으므로 checkVerdictBinding(false green 게이트)을 우회하지 않는다
+   * — 진짜 통과는 여전히 finish('passed') 한 곳만 지난다.
+   */
+  const stepResult = ({ next, phase } = {}) => {
+    const state = getState();
+    state.status = 'stepping';
+    const saved = saveState(statePath, state);
+    logger(`[hi-loop] ⏭ 한 스텝 진행 (${phase ?? saved.phase ?? saved.stage}). 이어가려면 hiloop_run 을 다시 호출하세요.`);
+    return { status: 'continue', iterations: saved.iteration, state: saved, next: next ?? saved.stage, phase: phase ?? saved.phase };
+  };
+
+  return { finish, stopResult, pauseResult, stepResult, setState };
 }

package/src/prompts.js

@@ -268,3 +268,30 @@ ${truncate(String(diffText ?? '(변경 없음)'), 10000)}
 ## 출력 (반드시 이 JSON 한 줄로만)
 {"verdict": "pass" 또는 "reject", "findings": [{"severity": "high|medium|low", "text": "무엇이 어떤 입력에서 어떻게 깨지는가"}]}`;
 }
+
+/**
+ * DOC-SYNC (FR-25). 소스 변경(diff)을 문서에 반영하는 단발 패스. 테스트 루프가 아니다.
+ * 사람이 관리하는 표준 문서(docs/DESIGN.md)는 오라클이라 **절대 건드리지 않는다**.
+ * 소스에 없는 내용을 지어내면 그게 곧 환각이므로, diff 로 확인되는 것만 반영한다.
+ */
+export function docSyncPrompt({ diffText, docTargets } = {}) {
+  const targets = Array.isArray(docTargets) ? docTargets : [];
+  return `지금은 DOC-SYNC 단계다. 아래 **소스 변경(git diff)**을 읽고, 그 변경에 맞춰 **문서만** 갱신하라.
+
+## 소스 변경 (git diff)
+\`\`\`diff
+${truncate(String(diffText ?? '(변경 없음)'), 12000)}
+\`\`\`
+
+## 갱신 대상 문서 (이 파일들만 수정)
+${targets.length ? targets.map((p) => `- ${p}`).join('\n') : '- README.md\n- docs/*.md (docs/DESIGN.md 제외)'}
+
+## 규칙
+- **문서만 고쳐라.** 소스 코드·테스트(\`src/\`, \`bin/\`, \`tests/\`, \`*.js\`)는 절대 건드리지 마라.
+- **\`docs/DESIGN.md\`(및 소문자 design.md)는 절대 수정하지 마라** — 사람이 관리하는 표준 오라클이다.
+- diff 로 **확인되는 변경만** 반영하라(새 플래그·인자·동작·API·기본값). diff 에 없는 내용을 지어내지 마라.
+- 새 기능이면 해당 문서 관례대로 반영하라(예: SPEC 의 FR 번호 규칙, README 의 사용법·표, guide 의 절).
+- 변경이 문서와 무관하면(내부 리팩터 등) 아무것도 바꾸지 말고 그 사실을 밝혀라.
+
+작업을 마치면 **어떤 문서의 무엇을 왜 고쳤는지** 5줄 이내로 요약해 출력하라.`;
+}

package/src/resume.js

@@ -57,6 +57,7 @@ export function resumeOrCreate({ statePath, goal, testCommand, maxLoops, cwd, sp
       specPath: pinnedSpecPath ?? prev.specPath ?? paths.specPath,
       specPinned: pinnedSpecPath ? true : Boolean(prev.specPinned),
       reconciled: Boolean(prev.reconciled),
+      extraLoops: Number.isFinite(prev.extraLoops) ? prev.extraLoops : 0,
       testPath: prev.testPath ?? paths.testPath,
       costUsd: Number.isFinite(prev.costUsd) ? prev.costUsd : 0,
       // 기준선이 없던 시절의 상태로 재개하면 이번 회차 지문이 곧 기준선이 된다.

package/src/runners.js

@@ -74,13 +74,15 @@ export function buildAgentArgs({ prompt, sessionId, extraArgs = [], permissionMo
  */
 export function makeAgentRunner({
   command = process.env.HILOOP_AGENT_CMD || 'claude',
+  provider = process.env.HILOOP_AGENT_PROVIDER,
   extraArgs = (process.env.HILOOP_AGENT_ARGS || '').split(' ').filter(Boolean),
   permissionMode = process.env.HILOOP_PERMISSION_MODE || DEFAULT_PERMISSION_MODE,
   timeoutMs = envMs('HILOOP_AGENT_TIMEOUT_MS', 30 * 60 * 1000),
 } = {}) {
+  const adapter = getAgentAdapter(provider);
   return ({ prompt, sessionId, cwd }) =>
     new Promise((resolve, reject) => {
-      const args = buildAgentArgs({ prompt, sessionId, extraArgs, permissionMode });
+      const args = adapter.buildArgs({ prompt, sessionId, extraArgs, permissionMode });
 
       const child = spawn(command, args, { cwd, env: process.env });
       let stdout = '';
@@ -133,3 +135,29 @@ export function parseAgentOutput(stdout, fallbackSessionId = null) {
     return { text: stdout, sessionId: fallbackSessionId, costUsd: 0 };
   }
 }
+
+/**
+ * 에이전트 프로바이더 어댑터 (FR-23): claude 외의 CLI 도 루프의 일꾼으로 쓰게,
+ * 인자 구성과 출력 파싱을 프로바이더별로 분리한다. HILOOP_AGENT_PROVIDER 로 고른다.
+ *  - claude(기본): `-p <prompt> --output-format json [--resume sid] [--permission-mode]`,
+ *    result/session_id/total_cost_usd 를 파싱 — 세션 재개·비용 집계 모두 지원.
+ *  - generic: 프롬프트를 마지막 위치인자로 넘기고 stdout 을 그대로 텍스트로 본다.
+ *    세션 재개·비용 집계는 없다(매 호출이 새 세션). opencode 등 단순 CLI 용 최소 계약.
+ *    예: HILOOP_AGENT_CMD=opencode, HILOOP_AGENT_ARGS=run → `opencode run "<prompt>"`.
+ */
+export const AGENT_ADAPTERS = {
+  claude: { buildArgs: buildAgentArgs, parseOutput: parseAgentOutput },
+  generic: {
+    buildArgs: ({ prompt, extraArgs = [] }) => [...extraArgs, prompt],
+    parseOutput: (stdout, fallbackSessionId = null) => ({
+      text: String(stdout),
+      sessionId: fallbackSessionId,
+      costUsd: 0,
+    }),
+  },
+};
+
+/** 이름이 없거나 모르는 값이면 claude 로 조용히 되돌린다(기본 경로 보존). */
+export function getAgentAdapter(name = process.env.HILOOP_AGENT_PROVIDER) {
+  return AGENT_ADAPTERS[String(name || 'claude').toLowerCase()] || AGENT_ADAPTERS.claude;
+}

package/src/state.js

@@ -146,6 +146,8 @@ export function createState({
     specPinned: Boolean(pinnedSpecPath),
     // FR-21: 문서 정합 게이트를 이미 거쳤는가. 같은 goal 재개 시 다시 묻지 않도록.
     reconciled: false,
+    // FR-22: on-fail ask 에서 사용자가 "재시도"를 고를 때마다 +1. maxLoops 위에 얹혀 회차를 늘린다.
+    extraLoops: 0,
     specSummary: '',
     lastError: '',
     costUsd: 0,