@tuzi-ince/hi-loop 0.1.1 → 0.2.0

package/src/loop.js

@@ -1,48 +1,36 @@
 /**
- * 자가 치유 핵심 오케스트레이션 루프 (FR-2, FR-3)
+ * 라이프사이클 stage 머신 (FR-10 ~ FR-15) + 실행 맥락 조립.
  *
- * PLAN -> DO -> CHECK -> ACT(HEAL) -> CHECK -> ...
- * CHECK 는 엔진이 직접 testCommand 를 돌려 판정한다. 에이전트의 자기보고는 믿지 않는다.
+ * 안쪽 자가 치유 루프는 build.js 에, 각 stage 핸들러는 stages.js 에 있다.
+ * 이 파일이 하는 일은 **다음 stage 를 정하는 것 하나**다 — 그 권한이 흩어지면
+ * 전체 흐름을 한눈에 볼 수 없게 된다.
+ *
+ *   DISCOVER → BUILD(PLAN⇄DO⇄CHECK⇄HEAL) → CODE_REVIEW → SHIP → WATCH → DONE
+ *
+ * 새 stage 는 전부 안쪽 루프의 **앞뒤에 붙는 껍질**이다. 안쪽 루프의 판정 규칙
+ * (무결성 L1, 정체 L2, 체크포인트 L3, 예산, 핸드오프)은 그대로다.
  */
-import {
-  saveState,
-  statePathFor,
-  resumeOrCreate,
-  truncate,
-  errorSignature,
-  reportGaps,
-  LIMITS,
-} from './state.js';
-import { promptFor } from './prompts.js';
+import { saveState, statePathFor, resumeOrCreate, reportGaps } from './state.js';
 import { makeAgentRunner, makeTestRunner } from './runners.js';
-import { makeIntegrityChecker, compareFingerprints, violationMessage } from './integrity.js';
+import { makeIntegrityChecker } from './integrity.js';
 import { acquireLock } from './lock.js';
-import { makeCheckpointer, makeFileLister, detectDeletions } from './checkpoint.js';
+import { makeCheckpointer, makeFileLister } from './checkpoint.js';
 import { makeSpecVerifier } from './verify.js';
 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 { STAGE_HANDLERS } from './stages.js';
+import { runBuildLoop } from './build.js';
 
-export { createState, loadState, saveState, statePathFor, summarizeState, resetState } from './state.js';
-
-/** iteration -> PDCA phase (1회차 PLAN, 2회차 DO, 이후 전부 HEAL) */
-export function phaseForIteration(iteration) {
-  if (iteration === 1) return 'PLAN';
-  if (iteration === 2) return 'DO';
-  return 'ACT';
-}
-
-function summarizeSpec(text) {
-  return truncate(String(text ?? '').trim(), LIMITS.specSummary);
-}
+// loop.js 는 이 엔진의 정문이다. 호출부가 내부 파일 배치를 알 필요가 없도록 여기서 모아 낸다.
+export { phaseForIteration } from './build.js';
+export { createState, loadState, saveState, statePathFor, summarizeState, resetState, migrateState } from './state.js';
+export { applyAnswer, formatAsk, normalizeAskPolicy } from './ask.js';
 
-function combineOutput({ stdout, stderr }) {
-  return [stderr, stdout].filter(Boolean).join('\n').trim();
-}
-
-/** 부동소수 드리프트를 막으려 6자리에서 끊는다. 러너가 비용을 안 주면 0으로 친다. */
-function addCost(prev, delta) {
-  const next = (Number.isFinite(prev) ? prev : 0) + (Number.isFinite(delta) ? delta : 0);
-  return Math.round(next * 1e6) / 1e6;
-}
+/** BUILD 이후의 stage. 이 상태로 저장돼 있으면 재개 시 빌드 루프를 다시 돌지 않는다. */
+export const POST_BUILD_STAGES = ['CODE_REVIEW', 'SHIP', 'WATCH'];
 
 /**
  * 얇은 락 래퍼 (L4). 같은 cwd 에서 두 루프가 상태를 덮어쓰지 못하게 배타를 강제한다.
@@ -69,12 +57,38 @@ async function runLoopBody({
   stagnationLimit = 3,
   verifySpec = false,
   handoffEvery = 4,
+  // ---- 라이프사이클 (FR-13, FR-14) ----
+  shipCommand = null,
+  onShipFail = 'stop',
+  // 기본값이 "배포할 때만 켜짐"인 이유는 §CODE_REVIEW 주석 참조.
+  codeReview = null,
+  maxReviewRounds = 2,
+  designReview = null,
+  maxDesignRounds = 2,
+  discover = null,
+  full = false,
+  // FR-15: 어느 경로로 들어와도 **같은 상태 머신**을 쓴다. 별도 코드 경로를 만들지 않는다
+  // — 분기가 둘이면 반드시 한쪽이 썩는다.
+  startFrom = null,
+  stopAfter = null,
+  watchCommand = null,
+  watchForMs = WATCH_DEFAULTS.forMs,
+  watchEveryMs = WATCH_DEFAULTS.everyMs,
+  watchTolerate = WATCH_DEFAULTS.tolerate,
+  onWatchFail = 'stop',
+  askPolicy = DEFAULT_ASK_POLICY,
+  yes = false,
   agentRunner = makeAgentRunner(),
   testRunner = makeTestRunner(),
   integrityChecker = makeIntegrityChecker(),
   checkpointer = makeCheckpointer(),
   fileLister = makeFileLister(),
   specVerifier = makeSpecVerifier(),
+  codeReviewer = makeCodeReviewer(),
+  designReviewer = makeDesignReviewer(),
+  discoverer = makeDiscoverer(),
+  shipper = makeShipper(),
+  watcher = makeWatcher(),
   notifier = makeNotifier(),
   logger = (line) => process.stderr.write(`${line}\n`),
   statePath = statePathFor(cwd),
@@ -89,7 +103,16 @@ async function runLoopBody({
     throw new TypeError('budgetUsd 는 0 보다 큰 숫자여야 합니다.');
   }
 
-  const state = resumeOrCreate({ statePath, goal, testCommand, maxLoops, cwd });
+  let state = resumeOrCreate({ statePath, goal, testCommand, maxLoops, cwd });
+
+  // 답 안 받은 질문이 남아 있으면 여기서 끝이다. 재개하려면 `hi-loop answer` 를 거쳐야 한다.
+  // 이 관문이 없으면 run 을 다시 부르는 것만으로 사람이 고르라던 분기를 건너뛰게 된다.
+  if (state.ask) {
+    const saved = saveState(statePath, state);
+    logger(formatAsk(state.ask));
+    return { status: 'awaiting', iterations: state.iteration, state: saved, ask: state.ask };
+  }
+
   saveState(statePath, state);
 
   const notify = async (event) => {
@@ -106,191 +129,170 @@ async function runLoopBody({
   // null 이면 비-git — 관측 자체가 불가능하니 아래에서 조용히 건너뛴다(인프라 fail-open).
   const baselineFiles = await fileLister({ cwd });
 
-  while (state.iteration < maxLoops) {
-    // 예산은 **다음 호출 앞**에서 막는다. 이미 쓴 돈은 되돌릴 수 없으므로
-    // 할 수 있는 일은 "더 쓰지 않는 것"뿐이다.
-    if (budgetUsd != null && state.costUsd >= budgetUsd) {
-      state.status = 'failed';
-      state.phase = 'DONE';
-      state.stopReason = 'budget';
-      const saved = saveState(statePath, state);
-      logger(`[hi-loop] 💸 예산 $${budgetUsd} 소진 (누적 $${state.costUsd.toFixed(2)}) — ${state.iteration}회차에서 중단합니다.`);
-      await notify({
-        type: 'failed',
-        iteration: state.iteration,
-        detail: `예산 소진: $${state.costUsd.toFixed(2)} / $${budgetUsd}`,
-      });
-      return { status: 'failed', iterations: state.iteration, state: saved };
-    }
-
-    state.iteration += 1;
-    state.phase = phaseForIteration(state.iteration);
-    state.status = 'running';
+  /** 완료 보고는 한 곳에서만 만든다. stage 가 늘어도 Gaps 공개 지점은 하나여야 한다. */
+  const finish = async (status, { stopReason = null, detail = '' } = {}) => {
+    state.status = status;
+    state.phase = 'DONE';
+    state.stage = 'DONE';
+    if (stopReason) state.stopReason = stopReason;
+    const saved = saveState(statePath, state);
+    await notify({ type: status === 'passed' ? 'passed' : 'failed', iteration: state.iteration, detail });
+    // Gaps 는 passed 에만 붙인다. false green 이 조용히 지나가는 지점이 거기이기 때문이다.
+    // 실패는 stopReason 만으로 이미 정직하다 — 거기에 Gaps 를 얹으면 소음이다.
+    if (status !== 'passed') return { status, iterations: state.iteration, state: saved };
+    const gaps = reportGaps(saved);
+    logger(gaps);
+    return { status, iterations: state.iteration, state: saved, report: gaps };
+  };
 
-    // 체크포인트: 에이전트가 손대기 **전** 상태를 스냅샷. 이 호출이 망친 것을 되돌릴 수 있게.
-    const sha = await checkpointer({ cwd });
-    if (sha) {
-      state.checkpoints = [...(state.checkpoints ?? []), { iteration: state.iteration, sha }].slice(-LIMITS.checkpointKeep);
-    }
-    saveState(statePath, state);
 
-    logger(`[hi-loop] iteration ${state.iteration}/${maxLoops} — ${state.phase} (session #${state.sessionSerial})`);
+  /**
+   * 단계 기본값 (FR-17) — 조용히 비용을 얹지 않는다.
+   *
+   * 새 단계는 전부 에이전트 호출 1회씩을 더한다(SHIP/WATCH 는 예외로 0). 전역 기본 ON 으로
+   * 하면 업데이트만 한 기존 사용자의 실행 비용이 조용히 는다. 그래서: 플래그가 없으면 종전대로
+   * BUILD 하나, `--full` 이면 셋 다, `--ship` 이면 리뷰만("리뷰 없는 자동 배포가 위험하다"는
+   * 근거가 거기서만 성립한다). 개별 플래그가 이 자동을 양방향으로 덮는다.
+   */
+  const reviewEnabled = codeReview === null ? full || Boolean(shipCommand) : Boolean(codeReview);
+  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');
+
+  /**
+   * 사람이 골라야 하는 지점에서 멈춘다. 이미 답한 질문이면 그 답을 돌려준다.
+   * 반환: `{ pause }` 면 호출자는 즉시 종료해야 한다.
+   */
+  const gate = ({ stage, question, options, required = true }) => {
+    const answered = [...(state.answers ?? [])].reverse().find((a) => a.stage === stage);
+    if (answered) return { pause: false, choice: answered.choice, note: answered.note };
+    if (!shouldAsk({ policy: askPolicy, required }) || yes) return { pause: false, choice: null };
+    state = pauseForAsk(state, createAsk({ stage, question, options }));
+    return { pause: true };
+  };
 
-    const prompt = promptFor(state);
-    const result = await agentRunner({ prompt, sessionId: state.sessionId, cwd });
-    state.sessionId = result?.sessionId ?? state.sessionId ?? null;
-    state.costUsd = addCost(state.costUsd, result?.costUsd);
+  const pauseResult = () => {
+    const saved = saveState(statePath, state);
+    logger(formatAsk(state.ask));
+    return { status: 'awaiting', iterations: state.iteration, state: saved, ask: state.ask };
+  };
 
-    if (state.phase === 'PLAN') {
-      state.specSummary = summarizeSpec(result?.text) || state.specSummary;
-    }
+  /**
+   * `--stop-after` 로 멈춘 결과. 실패가 아니다 — 시킨 것을 다 했을 뿐이다.
+   * status 를 passed 로 하면 "테스트가 통과했다"는 거짓말이 되므로 별도 값을 쓴다.
+   */
+  const stopResult = (stage) => {
+    state.status = 'stopped';
+    state.stopReason = `stop-after:${stage}`;
+    const saved = saveState(statePath, state);
+    logger(`[hi-loop] ⏹ ${stage} 까지 진행하고 멈췄습니다 (--stop-after).`);
+    return { status: 'stopped', iterations: state.iteration, state: saved, stoppedAt: stage };
+  };
 
-    // ---- CHECK: 엔진이 직접 검증 (FR-2.3) ----
-    // 2단 판정이다. exit code 는 "테스트가 통과했는가"만 답한다. 그 테스트가
-    // **그대로인가**는 별도 문제이고, 그걸 안 물으면 에이전트는 테스트를 지워서 통과한다(L1).
-    state.phase = 'CHECK';
-    saveState(statePath, state);
-    const check = await testRunner({ command: testCommand, cwd });
-    const output = combineOutput(check);
+  /** 방금 끝낸 stage 가 정지 지점인가. 다음 stage 로 넘어가기 직전에만 묻는다. */
+  const shouldStopAfter = (stage) => stopAfter === stage;
+
+  /**
+   * stage 핸들러가 받는 실행 맥락. `state` 는 getter/setter 라 핸들러가 재대입해도
+   * 여기 변수에 반영된다(가정 기록은 순수 함수라 새 객체를 만든다).
+   */
+  const ctx = {
+    get state() {
+      return state;
+    },
+    set state(v) {
+      state = v;
+    },
+    goal,
+    cwd,
+    logger,
+    notify,
+    gate,
+    nextAfterReview,
+    statePath,
+    baselineFiles,
+    designReviewEnabled,
+    save: () => saveState(statePath, state),
+    ports: {
+      discoverer,
+      codeReviewer,
+      designReviewer,
+      shipper,
+      watcher,
+      agentRunner,
+      testRunner,
+      integrityChecker,
+      checkpointer,
+      fileLister,
+      specVerifier,
+    },
+    opts: {
+      shipCommand,
+      watchCommand,
+      onShipFail,
+      onWatchFail,
+      watchForMs,
+      watchEveryMs,
+      watchTolerate,
+      maxReviewRounds,
+      maxLoops,
+      budgetUsd,
+      testCommand,
+      stagnationLimit,
+      verifySpec,
+      handoffEvery,
+      maxDesignRounds,
+      stopAfter,
+    },
+  };
 
-    const fingerprint = integrityChecker({ cwd, testPath: state.testPath });
-    const integrity = compareFingerprints(state.testFingerprint, fingerprint);
-    // 위반이 없을 때만 기준선을 갱신한다. 갱신해버리면 약화된 상태가 다음 회차의
-    // 기준이 되어 에이전트가 그대로 빠져나간다.
-    if (integrity.ok) state.testFingerprint = fingerprint;
+  // ---- stage 머신 ----
+  // 다음 stage 를 정하는 권한은 여기 한 곳에만 있다. 핸들러는 지시만 돌려준다.
+  // 재개 시 stage 가 이미 BUILD 이후면 빌드 루프를 다시 돌지 않는다 — 통과한 빌드를
+  // 다시 돌리면 비용을 두 번 내고, 최악의 경우 이미 배포된 코드를 또 고친다.
+  if (startFrom) state.stage = startFrom;
+  else if (!POST_BUILD_STAGES.includes(state.stage)) {
+    state.stage = discoverEnabled && !state.discovery ? 'DISCOVER' : 'BUILD';
+  }
 
-    // L8: baseline 에 있던 파일이 사라졌는가 = 에이전트가 기존 파일을 삭제. 차단하지 않고
-    // 경고만 한다(체크포인트로 되돌릴 수 있고 판단은 사람 몫). 누적 관측이라 Gaps 에도 실린다.
-    if (baselineFiles) {
-      const deleted = detectDeletions(baselineFiles, await fileLister({ cwd }));
-      const fresh = deleted.filter((f) => !(state.deletedFiles ?? []).includes(f));
-      if (fresh.length) {
-        state.deletedFiles = [...(state.deletedFiles ?? []), ...fresh];
-        logger(`[hi-loop] ⚠️ 지정 경로 밖 파일 ${fresh.length}개가 삭제됐습니다 (차단 안 함 — hi-loop rollback 으로 복원 가능):`);
-        for (const f of fresh) logger(`[hi-loop]    - ${f}`);
-      }
+  while (true) {
+    if (state.stage === 'DONE') {
+      return finish('passed', { detail: `누적 비용 $${state.costUsd.toFixed(2)}` });
     }
 
-    // Tier 1 (기계, 최종 권한): exit code + 무결성.
-    let passed = Boolean(check?.ok) && integrity.ok;
-
-    // Tier 2 (모델, 하향 전용): Tier 1 통과일 때만 호출. 스펙 대비 구현을 심판한다.
-    // Tier 1 실패를 통과로 올릴 수는 절대 없다 — reject 만 가능하다(L9, bkit 중심 명제).
-    let specReject = '';
-    if (passed && verifySpec) {
-      const verdict = await specVerifier({ specPath: state.specPath, cwd });
-      if (verdict?.verdict === 'reject') {
-        passed = false;
-        specReject = verdict.reason || '스펙과 어긋남';
-        logger(`[hi-loop] 🔬 스펙 검증 기각 — 테스트는 통과했으나 스펙 요구를 못 채웠습니다: ${truncate(specReject, 200)}`);
-      } else {
-        state.specVerified = true; // Gaps 보고가 "스펙 미검증" 대신 "검증 통과"를 쓰게 한다.
-        logger(`[hi-loop] 🔬 스펙 검증 통과.`);
-      }
+    if (state.stage === 'BUILD') {
+      state.stage = 'BUILD';
+      state.status = 'running';
+      saveState(statePath, state);
+      const built = await runBuildLoop(ctx);
+      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);
+      continue;
     }
 
-    state.history.push({
-      iteration: state.iteration,
-      phase: 'CHECK',
-      ok: passed,
-      summary: passed
-        ? 'tests passed + spec verified'
-        : truncate(
-            specReject
-              ? `스펙 검증 기각: ${specReject}`
-              : integrity.ok
-                ? output
-                : violationMessage(integrity.violations),
-            LIMITS.historySummary,
-          ),
-    });
+    const handler = STAGE_HANDLERS[state.stage];
+    if (!handler) throw new Error(`알 수 없는 stage: ${state.stage}`);
 
-    if (!integrity.ok) {
-      logger(`[hi-loop] 🚨 테스트 무결성 위반 — ${integrity.violations.length}건. 통과로 인정하지 않습니다.`);
-      for (const v of integrity.violations) logger(`[hi-loop]    - ${v}`);
-    }
-
-    if (passed) {
-      state.status = 'passed';
-      state.phase = 'DONE';
-      state.lastError = '';
-      const saved = saveState(statePath, state);
-      logger(`[hi-loop] ✅ ${state.iteration}회차에 통과했습니다. (누적 $${state.costUsd.toFixed(2)})`);
-      // passed 야말로 Gaps 를 붙여야 할 자리다 — false green 이 조용히 지나가는 지점이므로.
-      const gaps = reportGaps(saved);
-      logger(gaps);
-      await notify({ type: 'passed', iteration: state.iteration, detail: `누적 비용 $${state.costUsd.toFixed(2)}` });
-      return { status: 'passed', iterations: state.iteration, state: saved, report: gaps };
-    }
+    const done = state.stage;
+    const directive = await handler(ctx);
 
-    // ---- ACT: 에러를 다음 루프의 연료로 (FR-2.4) ----
-    // 무결성 위반은 에러 **뒤**에 붙인다. 절단이 tail-biased 이므로(§5.2) 꼬리가 살아남는다.
-    // 앞에 붙이면 여기서든 saveState 에서든 위반 사실이 먼저 잘려나가고, 에이전트는
-    // 자기가 뭘 어겼는지 모른 채 같은 짓을 반복한다.
-    // 실패의 정체를 셋 중 하나로 조립한다: 스펙 기각 / 무결성 위반 / 테스트 에러.
-    // 스펙 기각이면 테스트는 통과했으니 output 대신 스펙 사유가 다음 루프의 연료다.
-    let failure;
-    if (specReject) {
-      failure = `스펙 검증이 이 구현을 기각했다. 테스트는 통과했지만 스펙 요구를 못 채웠다:\n${specReject}\n스펙(${state.specPath})을 다시 읽고 그 요구를 충족하도록 구현을 고쳐라. 테스트만 통과시키는 것으로는 부족하다.`;
-    } else {
-      const body = output || `테스트가 코드 ${check?.code}로 실패했습니다.`;
-      failure = integrity.ok ? body : `${body}\n\n${violationMessage(integrity.violations)}`;
-    }
-    state.lastError = truncate(failure, LIMITS.lastError);
-    state.phase = 'ACT';
+    if (directive.pause) return pauseResult();
+    if (directive.finish) return finish('failed', directive.finish);
+    if (shouldStopAfter(done)) return stopResult(done);
 
-    // ---- 정체 감지 (L2) ----
-    // 판정 신호는 스펙 기각이면 기각 사유, 무결성 위반이면 그 위반, 아니면 에러 지문이다.
-    // 같은 실패가 stagnationLimit 회 연속이면 이 접근으로는 못 고친다는 뜻 —
-    // 같은 값을 태우며 maxLoops 를 다 쓰는 것은 순수한 낭비다(실측: 함정에 $3.07).
-    const sig = specReject
-      ? `SPEC:${errorSignature(specReject)}`
-      : integrity.ok
-        ? errorSignature(output)
-        : `INTEGRITY:${integrity.violations.join('|')}`;
-    state.stagnantRuns = sig && sig === state.errorSig ? state.stagnantRuns + 1 : 1;
-    state.errorSig = sig;
+    state.stage = directive.next;
     saveState(statePath, state);
-
-    if (integrity.ok) {
-      logger(`[hi-loop] ❌ 테스트 실패 (code ${check?.code}) — 치유를 시도합니다.`);
-    }
-
-    if (stagnationLimit != null && state.stagnantRuns >= stagnationLimit && state.iteration < maxLoops) {
-      state.status = 'failed';
-      state.phase = 'DONE';
-      state.stopReason = 'stagnated';
-      const saved = saveState(statePath, state);
-      logger(`[hi-loop] 🔁 같은 실패가 ${state.stagnantRuns}회 반복 — 접근이 막혔습니다. ${state.iteration}회차에서 중단합니다. (누적 $${state.costUsd.toFixed(2)})`);
-      await notify({
-        type: 'failed',
-        iteration: state.iteration,
-        detail: `정체: 같은 실패 ${state.stagnantRuns}회 반복`,
-      });
-      return { status: 'failed', iterations: state.iteration, state: saved };
-    }
-
-    // ---- 세션 핸드오프 & 컨텍스트 다이어트 (FR-3.2) ----
-    if (state.iteration % handoffEvery === 0 && state.iteration < maxLoops) {
-      state.sessionId = null;
-      state.sessionSerial += 1;
-      saveState(statePath, state);
-      logger(`[hi-loop] ♻️ 세션 핸드오프 — 압축 상태만 session #${state.sessionSerial}에 넘깁니다.`);
-      await notify({
-        type: 'handoff',
-        iteration: state.iteration,
-        detail: `session #${state.sessionSerial} 로 컨텍스트 다이어트 후 재개`,
-      });
-    }
   }
-
-  state.status = 'failed';
-  state.phase = 'DONE';
-  state.stopReason = 'maxLoops';
-  const saved = saveState(statePath, state);
-  logger(`[hi-loop] 한도(${maxLoops}회)를 소진했지만 테스트가 통과하지 못했습니다. (누적 $${state.costUsd.toFixed(2)})`);
-  await notify({ type: 'failed', iteration: state.iteration, detail: truncate(state.lastError, 500) });
-  return { status: 'failed', iterations: state.iteration, state: saved };
 }
 
 export default runLoop;
+

package/src/mcp-server.js

@@ -4,7 +4,8 @@
  * ⚠️ stdout 은 MCP 프로토콜 채널이다. 로그는 반드시 stderr 로만 낸다 (FR-4.2).
  */
 import { runLoop } from './loop.js';
-import { loadState, statePathFor, summarizeState, resetState } from './state.js';
+import { loadState, saveState, statePathFor, summarizeState, resetState } from './state.js';
+import { applyAnswer, formatAsk } from './ask.js';
 import { rollbackTo } from './checkpoint.js';
 import { runSetup } from '../bin/setup.js';
 
@@ -17,11 +18,43 @@ const fail = (t) => ({ content: [{ type: 'text', text: t }], isError: true });
 export const tools = {
   hiloop_run: {
     description:
-      '목표(goal)를 받아 PLAN→DO→CHECK→HEAL 자가 치유 루프를 실행한다. spec/테스트를 먼저 만들고, 테스트가 통과할 때까지 최대 maxLoops회 반복한다.',
-    handler: async ({ goal, testCommand = 'npm test', maxLoops = 10, verifySpec = false, cwd = process.cwd() }) => {
+      '목표(goal)를 받아 PLAN→DO→CHECK→HEAL 자가 치유 루프를 실행한다. spec/테스트를 먼저 만들고, 테스트가 통과할 때까지 최대 maxLoops회 반복한다. full=true 면 발굴·설계리뷰·코드리뷰까지 도는 전체 라이프사이클로 실행한다. ship/watch 를 주면 배포와 헬스체크까지 진행한다.',
+    handler: async ({
+      goal,
+      testCommand = 'npm test',
+      maxLoops = 10,
+      verifySpec = false,
+      full = false,
+      ship,
+      watch,
+      stopAfter,
+      cwd = process.cwd(),
+    }) => {
       if (!goal) return fail('goal 은 필수입니다.');
-      const result = await runLoop({ goal, testCommand, maxLoops, verifySpec, cwd, logger: log });
-      const head = result.status === 'passed' ? '✅ 통과' : '❌ 실패';
+      const result = await runLoop({
+        goal,
+        testCommand,
+        maxLoops,
+        verifySpec,
+        full: Boolean(full),
+        shipCommand: ship || null,
+        watchCommand: watch || null,
+        stopAfter: stopAfter ? String(stopAfter).toUpperCase() : null,
+        cwd,
+        logger: log,
+      });
+
+      // 사람이 골라야 하는 지점에서 멈췄다. 호스트 LLM 이 이 질문을 사용자에게 그대로
+      // 제시하고 hiloop_answer 로 답을 돌려주면 재개된다 — MCP 의 단일 요청/응답
+      // 제약과 충돌하지 않는 유일한 방법이다.
+      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)`,
+        );
+      }
+
+      const head =
+        result.status === 'passed' ? '✅ 통과' : result.status === 'stopped' ? `⏹ ${result.stoppedAt} 까지 진행 후 정지` : '❌ 실패';
       // 통과 시 Gaps 를 붙인다 — 에이전트가 도구로 이 결과를 받을 때 false green 을
       // 사실로 착각하지 않도록. summarizeState 는 상태 요약, report 는 검증 한계.
       const gaps = result.report ? `\n\n${result.report}` : '';
@@ -30,6 +63,20 @@ export const tools = {
       );
     },
   },
+  hiloop_answer: {
+    description:
+      'hiloop_run 이 반환한 대기 중인 질문에 답한다. choice 는 제시된 선택지의 키(a, b, ...)이고, note 로 자유 서술을 덧붙이거나 대신할 수 있다. 답한 뒤 hiloop_run 을 같은 goal 로 다시 호출하면 이어서 진행된다.',
+    handler: async ({ choice, note = '', cwd = process.cwd() } = {}) => {
+      const statePath = statePathFor(cwd);
+      const state = loadState(statePath);
+      if (!state?.ask) return fail('대기 중인 질문이 없습니다.');
+      const res = applyAnswer(state, { choice, note });
+      if (!res.ok) return fail(res.reason);
+      saveState(statePath, res.state);
+      const last = res.state.assumptions[res.state.assumptions.length - 1];
+      return text(`✅ 기록했습니다: ${last.text}\n같은 goal 로 hiloop_run 을 다시 호출하면 이어서 진행합니다.`);
+    },
+  },
   hiloop_status: {
     description: '현재 워크스페이스의 .agent-state.json 루프 상태 요약을 반환한다.',
     handler: async ({ cwd = process.cwd() } = {}) => text(summarizeState(loadState(statePathFor(cwd)))),
@@ -111,12 +158,32 @@ export async function startMcpServer({ version = '0.1.0' } = {}) {
         testCommand: z.string().optional().describe('검증 명령 (기본 "npm test")'),
         maxLoops: z.number().int().min(1).max(50).optional().describe('최대 루프 횟수 (기본 10)'),
         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('이 단계까지만 진행하고 멈춘다'),
         cwd: cwdSchema,
       },
     },
     wrap(tools.hiloop_run.handler),
   );
 
+  server.registerTool(
+    'hiloop_answer',
+    {
+      description: tools.hiloop_answer.description,
+      inputSchema: {
+        choice: z.string().optional().describe('선택지 키 (a, b, ...) 또는 선택지 라벨'),
+        note: z.string().optional().describe('자유 서술. 선택지에 없는 답을 줄 때는 이것만으로도 된다'),
+        cwd: cwdSchema,
+      },
+    },
+    wrap(tools.hiloop_answer.handler),
+  );
+
   server.registerTool(
     'hiloop_status',
     { description: tools.hiloop_status.description, inputSchema: { cwd: cwdSchema } },