@tuzi-ince/hi-loop 0.1.2 → 0.2.1

package/src/ask.js

@@ -0,0 +1,152 @@
+/**
+ * ask 모드 (제안서 §4) — 취사선택이 필연일 때만 사람을 부른다.
+ *
+ * 설계 제약이 방식을 정한다. 차단형 stdin 을 쓰지 않는 이유:
+ * - MCP 는 단일 요청/응답이다. 서버가 stdin 을 붙잡고 사람을 기다릴 자리가 없다.
+ * - 백그라운드 데몬·텔레그램 봇 구동에서는 답할 터미널 자체가 없다.
+ * 그래서 **상태를 저장하고 종료**한다(pause/resume). 세션이 끊겨도 질문은 파일에 남는다.
+ *
+ * MCP 에서는 이 구조가 오히려 자연스럽다: `hiloop_run` 이 status='awaiting' + ask 를
+ * 반환하면 호스트 LLM 이 그 질문을 사용자에게 그대로 제시하고 `hiloop_answer` 를 부른다.
+ *
+ * 이 모듈은 state.js 를 import 하지 않는다(순환 방지). 상태를 받아 새 상태를 돌려주는
+ * 순수 함수만 둔다.
+ */
+import { randomBytes } from 'node:crypto';
+
+/** `--ask` 정책. 기본은 auto — 상호배타 분기와 비가역 행위에서만 묻는다. */
+export const ASK_POLICIES = ['auto', 'never', 'always'];
+export const DEFAULT_ASK_POLICY = 'auto';
+
+export function normalizeAskPolicy(value) {
+  if (value === undefined || value === null || value === true) return DEFAULT_ASK_POLICY;
+  const v = String(value).toLowerCase();
+  return ASK_POLICIES.includes(v) ? v : null; // null = 잘못된 값. 호출자가 exit 2 로 거른다.
+}
+
+/**
+ * 이 시점에 사람을 부를 것인가.
+ *
+ * `required` 는 "엔진이 판단하기에 이건 사람 몫"이라는 뜻이다(상호배타 분기 FR-10.3,
+ * 비가역 배포 FR-13.4). auto 는 이때만 묻는다. never 는 그래도 안 묻는다 —
+ * CI·봇처럼 답할 사람이 아예 없는 환경에서 멈추는 게 더 나쁘기 때문이다.
+ */
+export function shouldAsk({ policy = DEFAULT_ASK_POLICY, required = false } = {}) {
+  if (policy === 'never') return false;
+  if (policy === 'always') return true;
+  return Boolean(required);
+}
+
+export function createAsk({ stage, question, options = [], now = new Date().toISOString() }) {
+  if (!question || typeof question !== 'string' || !question.trim()) {
+    throw new TypeError('ask 에는 비어 있지 않은 question 이 필요합니다.');
+  }
+  const normalized = options
+    .map((o, i) => ({
+      // 키가 없으면 a, b, c … 를 붙인다. 사람이 `hi-loop answer a` 로 답하는 손잡이다.
+      key: String(o.key ?? String.fromCharCode(97 + i)).toLowerCase(),
+      label: String(o.label ?? o),
+      impact: o.impact ? String(o.impact) : '',
+    }))
+    .filter((o) => o.label.trim());
+  return {
+    id: `ask_${randomBytes(4).toString('hex')}`,
+    stage: stage ?? 'BUILD',
+    question: question.trim(),
+    options: normalized,
+    askedAt: now,
+  };
+}
+
+/** 질문을 상태에 걸고 멈춘다. 상태를 직접 바꾸지 않고 새 객체를 돌려준다. */
+export function pauseForAsk(state, ask) {
+  return { ...state, status: 'awaiting', ask };
+}
+
+/**
+ * 답을 적용한다. 고른 선택지는 **가정으로 승격**된다 — 사람이 고른 것도 결국 가정이고,
+ * 기록되지 않은 가정은 없어야 한다(FR-10.2). 이 기록이 나중 단계 프롬프트에 실린다.
+ *
+ * 반환: `{ ok, state, reason }`. 실패해도 던지지 않는다 — CLI/MCP 양쪽이 같은 방식으로
+ * 사용자에게 사유를 돌려줘야 하기 때문이다.
+ */
+export function applyAnswer(state, { choice, note = '', now = new Date().toISOString() } = {}) {
+  const ask = state?.ask;
+  if (!ask) return { ok: false, state, reason: '대기 중인 질문이 없습니다.' };
+
+  const key = choice === undefined || choice === null ? '' : String(choice).toLowerCase().trim();
+  const options = ask.options ?? [];
+  const picked = options.find((o) => o.key === key || o.label.toLowerCase() === key);
+
+  // 선택지가 있는 질문인데 못 고르면 진행하지 않는다. 여기서 관대해지면 엔진이 사람의
+  // 오타를 임의 해석해 분기를 골라버린다 — ask 로 막으려던 바로 그 일이다.
+  if (options.length && !picked) {
+    if (!note.trim()) {
+      return {
+        ok: false,
+        state,
+        reason: `선택지에 없는 답입니다: "${choice}". 가능한 값: ${options.map((o) => o.key).join(', ')} (또는 --note 로 자유 서술)`,
+      };
+    }
+  }
+
+  const decision = picked ? picked.label : note.trim();
+  // stage 를 남겨야 재개할 때 "이 관문은 이미 답을 받았다"를 알 수 있다.
+  // 없으면 같은 질문을 매 재개마다 다시 묻는다.
+  const answered = {
+    id: ask.id,
+    stage: ask.stage,
+    choice: picked ? picked.key : '',
+    note: note.trim(),
+    at: now,
+  };
+
+  return {
+    ok: true,
+    reason: '',
+    state: {
+      ...state,
+      ask: null,
+      status: 'running',
+      answers: [...(state.answers ?? []), answered],
+      assumptions: [
+        ...(state.assumptions ?? []),
+        {
+          text: note.trim() && picked ? `${decision} (단서: ${note.trim()})` : decision,
+          source: 'ask',
+          stage: ask.stage,
+          decidedBy: 'human',
+          at: now,
+        },
+      ],
+    },
+  };
+}
+
+/** 에이전트가 스스로 세운 가정을 기록한다 (policy=never 또는 분기가 아닌 모호성). */
+export function recordAssumption(state, { text, stage, now = new Date().toISOString() }) {
+  const clean = String(text ?? '').trim();
+  if (!clean) return state;
+  return {
+    ...state,
+    assumptions: [
+      ...(state.assumptions ?? []),
+      { text: clean, source: 'discover', stage: stage ?? state.stage, decidedBy: 'agent', at: now },
+    ],
+  };
+}
+
+/** CLI·MCP·텔레그램이 공유하는 표시 형식. 한 곳에만 둔다. */
+export function formatAsk(ask) {
+  if (!ask) return '';
+  const lines = [`⏸ 선택이 필요합니다 [${ask.stage}]`, `   ${ask.question}`];
+  for (const o of ask.options ?? []) {
+    lines.push(`   ${o.key}) ${o.label}${o.impact ? `  — ${o.impact}` : ''}`);
+  }
+  lines.push(
+    (ask.options ?? []).length
+      ? `→ hi-loop answer <${(ask.options ?? []).map((o) => o.key).join('|')}> [--note "..."]`
+      : '→ hi-loop answer --note "<답>"',
+  );
+  return lines.join('\n');
+}

package/src/build.js

@@ -0,0 +1,252 @@
+/**
+ * 안쪽 자가 치유 루프 (FR-2, FR-3) — 이 엔진의 검증된 심장이다.
+ *
+ * PLAN -> DO -> CHECK -> ACT(HEAL) -> CHECK -> ...
+ * CHECK 는 엔진이 직접 testCommand 를 돌려 판정한다. 에이전트의 자기보고는 믿지 않는다.
+ *
+ * loop.js 의 stage 머신이 이 함수를 부르고, 반환값으로 다음 stage 를 정한다.
+ * CODE_REVIEW·SHIP·WATCH 가 기각하면 이 함수를 **다시** 부른다 — 새 치유 경로를
+ * 만들지 않고 HEAL 을 재사용하는 것이 확장의 규칙이다.
+ *
+ * 반환:
+ *   { ok: true }                          테스트 통과
+ *   { ok: false, stopReason, detail }     예산·정체·한도 소진
+ *   { stopped: true }                     --stop-after PLAN 으로 멈춤
+ */
+import { saveState, truncate, errorSignature, LIMITS } from './state.js';
+import { promptFor } from './prompts.js';
+import { compareFingerprints, violationMessage } from './integrity.js';
+import { detectDeletions } from './checkpoint.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);
+}
+
+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;
+}
+
+export async function runBuildLoop(ctx) {
+  const { goal, cwd, logger, notify, statePath, baselineFiles, designReviewEnabled, ports, opts } = ctx;
+  const { maxLoops, budgetUsd, testCommand, stagnationLimit, verifySpec, handoffEvery, maxDesignRounds, stopAfter } = opts;
+  const { agentRunner, testRunner, integrityChecker, checkpointer, fileLister, specVerifier, designReviewer } = ports;
+  // state 는 이 루프에서 속성만 바뀌고 재대입되지 않는다 — 참조를 그대로 잡아도 안전하다.
+  const state = ctx.state;
+
+    state.stage = 'BUILD';
+    state.status = 'running';
+    saveState(statePath, state);
+
+    while (state.iteration < maxLoops) {
+      // 예산은 **다음 호출 앞**에서 막는다. 이미 쓴 돈은 되돌릴 수 없으므로
+      // 할 수 있는 일은 "더 쓰지 않는 것"뿐이다.
+      if (budgetUsd != null && state.costUsd >= budgetUsd) {
+        logger(`[hi-loop] 💸 예산 $${budgetUsd} 소진 (누적 $${state.costUsd.toFixed(2)}) — ${state.iteration}회차에서 중단합니다.`);
+        return {
+          ok: false,
+          stopReason: 'budget',
+          detail: `예산 소진: $${state.costUsd.toFixed(2)} / $${budgetUsd}`,
+        };
+      }
+
+      state.iteration += 1;
+      state.phase = phaseForIteration(state.iteration);
+      state.status = 'running';
+
+      // 체크포인트: 에이전트가 손대기 **전** 상태를 스냅샷. 이 호출이 망친 것을 되돌릴 수 있게.
+      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})`);
+
+      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);
+
+      if (state.phase === 'PLAN') {
+        state.specSummary = summarizeSpec(result?.text) || state.specSummary;
+
+        // ---- DESIGN_REVIEW (FR-11): 구현 착수 **전** 가장 값싼 교정 지점 ----
+        // 스펙이 goal 을 잘못 읽었으면 그 뒤 전부가 틀린 것을 향해 간다. CHECK 는 이걸
+        // 못 잡는다 — 테스트도 같은 스펙에서 나왔으니 사이좋게 통과하기 때문이다.
+        if (designReviewEnabled && (state.designRounds ?? 0) < maxDesignRounds) {
+          const verdict = await designReviewer({
+            goal,
+            assumptions: state.assumptions ?? [],
+            specPath: state.specPath,
+            testPath: state.testPath,
+            cwd,
+          });
+          if (verdict?.verdict === 'reject') {
+            state.designRounds = (state.designRounds ?? 0) + 1;
+            state.lastError = truncate(
+              `설계 리뷰가 이 스펙을 기각했다. 구현으로 넘어가지 말고 스펙과 테스트를 먼저 고쳐라:\n${verdict.reason || '사유 없음'}`,
+              LIMITS.lastError,
+            );
+            // PLAN 을 한 번 더 돌린다. phase 는 iteration 에서 나오므로 회차를 되돌려야
+            // 다음 바퀴가 다시 PLAN 이 된다. CHECK 는 건너뛴다 — 아직 구현이 없어서
+            // 테스트를 돌려봐야 확정적으로 실패하고, 그 실패는 아무것도 알려주지 않는다.
+            state.iteration -= 1;
+            saveState(statePath, state);
+            logger(`[hi-loop] 📐 설계 리뷰 기각 (${state.designRounds}/${maxDesignRounds}) — 스펙을 다시 씁니다: ${truncate(verdict.reason ?? '', 200)}`);
+            continue;
+          }
+          logger('[hi-loop] 📐 설계 리뷰 통과.');
+        }
+
+        // `hi-loop plan` — 스펙과 테스트만 만들고 멈춘다. PLAN 은 안쪽 루프의 회차라
+        // 정지 지점도 여기다(바깥 stage 머신에는 PLAN 이라는 자리가 없다).
+        if (stopAfter === 'PLAN') {
+          saveState(statePath, state);
+          return { ok: false, stopped: true };
+        }
+      }
+
+      // ---- 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);
+
+      const fingerprint = integrityChecker({ cwd, testPath: state.testPath });
+      const integrity = compareFingerprints(state.testFingerprint, fingerprint);
+      // 위반이 없을 때만 기준선을 갱신한다. 갱신해버리면 약화된 상태가 다음 회차의
+      // 기준이 되어 에이전트가 그대로 빠져나간다.
+      if (integrity.ok) state.testFingerprint = fingerprint;
+
+      // 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}`);
+        }
+      }
+
+      // 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] 🔬 스펙 검증 통과.`);
+        }
+      }
+
+      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,
+            ),
+      });
+
+      if (!integrity.ok) {
+        logger(`[hi-loop] 🚨 테스트 무결성 위반 — ${integrity.violations.length}건. 통과로 인정하지 않습니다.`);
+        for (const v of integrity.violations) logger(`[hi-loop]    - ${v}`);
+      }
+
+      if (passed) {
+        state.lastError = '';
+        saveState(statePath, state);
+        logger(`[hi-loop] ✅ ${state.iteration}회차에 통과했습니다. (누적 $${state.costUsd.toFixed(2)})`);
+        return { ok: true };
+      }
+
+      // ---- 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';
+
+      // ---- 정체 감지 (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;
+      saveState(statePath, state);
+
+      if (integrity.ok) {
+        logger(`[hi-loop] ❌ 테스트 실패 (code ${check?.code}) — 치유를 시도합니다.`);
+      }
+
+      if (stagnationLimit != null && state.stagnantRuns >= stagnationLimit && state.iteration < maxLoops) {
+        logger(`[hi-loop] 🔁 같은 실패가 ${state.stagnantRuns}회 반복 — 접근이 막혔습니다. ${state.iteration}회차에서 중단합니다. (누적 $${state.costUsd.toFixed(2)})`);
+        return {
+          ok: false,
+          stopReason: 'stagnated',
+          detail: `정체: 같은 실패 ${state.stagnantRuns}회 반복`,
+        };
+      }
+
+      // ---- 세션 핸드오프 & 컨텍스트 다이어트 (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} 로 컨텍스트 다이어트 후 재개`,
+        });
+      }
+    }
+
+    logger(`[hi-loop] 한도(${maxLoops}회)를 소진했지만 테스트가 통과하지 못했습니다. (누적 $${state.costUsd.toFixed(2)})`);
+    return { ok: false, stopReason: 'maxLoops', detail: truncate(state.lastError, 500) };
+}

package/src/cli-options.js

@@ -0,0 +1,134 @@
+/**
+ * `run` 계열 명령의 인자 → runLoop 옵션 번역 (FR-1.4, FR-13 ~ FR-15).
+ *
+ * bin/hi-loop.js 에서 뺀 이유는 크기(NFR-5)만이 아니다. 이 파일의 규칙은 하나로 요약된다:
+ * **잘못된 값을 조용히 기본값으로 흘리지 않는다.**
+ * "5분"이라 쓴 게 5ms 로 해석되면 감시했다는 착각만 남고, 잘못된 예산이 무제한으로
+ * 해석되면 비용 통제가 침묵 속에 실패한다. 그래서 전부 exit 2 로 거른다.
+ *
+ * 반환: `{ ok: true, options }` 또는 `{ ok: false, message }` — 던지지 않는다.
+ * CLI 는 message 를 stderr 로 내고 2를 돌려주기만 하면 된다.
+ */
+import { parseDuration, WATCH_DEFAULTS } from './ship.js';
+import { normalizeAskPolicy } from './ask.js';
+
+export const STAGE_NAMES = ['DISCOVER', 'PLAN', 'BUILD', 'CODE_REVIEW', 'SHIP', 'WATCH'];
+
+const bad = (message) => ({ ok: false, message });
+
+/** 값이 실제로 주어졌는가. `--flag` 만 쓰면 파서가 true 를 넣으므로 그것도 "없음"이다. */
+const given = (v) => v !== undefined && v !== true && v !== '';
+
+export function parseRunOptions(args, { staged = {} } = {}) {
+  const str = (k) => (given(args[k]) ? String(args[k]) : null);
+
+  const intOpt = (k, { min = 1, fallback }) => {
+    if (!given(args[k])) return fallback;
+    const n = Number(args[k]);
+    if (!(Number.isInteger(n) && n >= min)) return { error: `--${k} 는 ${min} 이상의 정수여야 합니다: ${args[k]}` };
+    return n;
+  };
+
+  const enumOpt = (k, allowed, fallback) => {
+    const v = str(k);
+    if (v === null) return fallback;
+    if (!allowed.includes(v)) return { error: `--${k} 는 ${allowed.join('|')} 중 하나여야 합니다: ${v}` };
+    return v;
+  };
+
+  const stageOpt = (k) => {
+    const v = str(k);
+    if (v === null) return null;
+    const upper = v.toUpperCase();
+    if (!STAGE_NAMES.includes(upper)) return { error: `--${k} 는 ${STAGE_NAMES.join('|')} 중 하나여야 합니다: ${v}` };
+    return upper;
+  };
+
+  const askPolicy = normalizeAskPolicy(args.ask);
+  if (askPolicy === null) return bad(`--ask 는 auto|never|always 중 하나여야 합니다: ${args.ask}`);
+
+  // 예산은 명시할 때만 건다. 잘못된 값이 조용히 "무제한"이 되면 안 된다.
+  let budgetUsd = null;
+  if (given(args['budget-usd'])) {
+    budgetUsd = Number(args['budget-usd']);
+    if (!(Number.isFinite(budgetUsd) && budgetUsd > 0)) {
+      return bad(`--budget-usd 는 0 보다 큰 숫자여야 합니다: ${args['budget-usd']}`);
+    }
+  }
+
+  // 정체 상한: --no-stagnation 으로 끄거나 --stagnation N 으로 조절. 기본 3.
+  let stagnationLimit = 3;
+  if (args['no-stagnation']) stagnationLimit = null;
+  else {
+    const n = intOpt('stagnation', { fallback: 3 });
+    if (n?.error) return bad(n.error);
+    stagnationLimit = n;
+  }
+
+  // 기간은 조용히 기본값으로 흘리지 않는다.
+  const durations = {};
+  for (const [flag, key, fallback] of [
+    ['watch-for', 'watchForMs', WATCH_DEFAULTS.forMs],
+    ['watch-every', 'watchEveryMs', WATCH_DEFAULTS.everyMs],
+  ]) {
+    const ms = parseDuration(args[flag], { fallback });
+    if (ms === null) return bad(`--${flag} 형식이 잘못됐습니다 (예: 5m, 30s, 1500): ${args[flag]}`);
+    durations[key] = ms;
+  }
+
+  const numbers = {};
+  for (const [flag, key, min] of [
+    ['max-loops', 'maxLoops', 1],
+    ['max-review-rounds', 'maxReviewRounds', 1],
+    ['max-design-rounds', 'maxDesignRounds', 1],
+    ['watch-tolerate', 'watchTolerate', 0],
+  ]) {
+    const v = intOpt(flag, { min, fallback: undefined });
+    if (v?.error) return bad(v.error);
+    if (v !== undefined) numbers[key] = v;
+  }
+
+  const onShipFail = enumOpt('on-ship-fail', ['stop', 'heal'], 'stop');
+  if (onShipFail?.error) return bad(onShipFail.error);
+  const onWatchFail = enumOpt('on-watch-fail', ['stop', 'rollback', 'heal'], 'stop');
+  if (onWatchFail?.error) return bad(onWatchFail.error);
+
+  // 서브커맨드가 정한 구간이 우선한다 — `hi-loop ship` 은 배포 단계를 하라는 명령이다.
+  const startFrom = staged.startFrom ?? stageOpt('start-from');
+  if (startFrom?.error) return bad(startFrom.error);
+  const stopAfter = staged.stopAfter ?? stageOpt('stop-after');
+  if (stopAfter?.error) return bad(stopAfter.error);
+  // PLAN 은 안쪽 루프의 회차라 시작점이 될 수 없다. BUILD 로 들어가면 자연히 PLAN 부터다.
+  if (startFrom === 'PLAN') {
+    return bad('--start-from 에는 PLAN 을 쓸 수 없습니다. BUILD 로 시작하면 PLAN 부터 돕니다.');
+  }
+
+  // null = 자동(--full 또는 --ship 이면 켜짐). 명시 플래그가 그 자동을 양방향으로 덮는다.
+  const triState = (onKey, offKey) => (args[offKey] ? false : args[onKey] ? true : null);
+
+  return {
+    ok: true,
+    options: {
+      testCommand: str('test') ?? 'npm test',
+      budgetUsd,
+      stagnationLimit,
+      verifySpec: Boolean(args['verify-spec']),
+      shipCommand: str('ship'),
+      watchCommand: str('watch'),
+      onShipFail,
+      onWatchFail,
+      askPolicy,
+      yes: Boolean(args.yes),
+      full: Boolean(args.full),
+      codeReview: triState('review', 'no-review'),
+      designReview: triState('design-review', 'no-design-review'),
+      discover: triState('discover', 'no-discover'),
+      startFrom,
+      stopAfter,
+      ...durations,
+      ...numbers,
+      // 서브커맨드는 그 단계를 **하라는 명령**이다. 자동 기본값이 그걸 끄면 안 된다.
+      ...(staged.force ?? {}),
+    },
+  };
+}

package/src/discover.js

@@ -0,0 +1,118 @@
+/**
+ * DISCOVER — 요구사항 발굴/기획 (FR-10).
+ *
+ * goal 은 보통 한 줄이다. 그 한 줄과 실제로 만들어야 할 것 사이의 간극을 메우는 게 이 단계다.
+ * 하지만 이 엔진의 기본은 무중단이므로, 발굴의 결론은 **질문 목록이 아니라 가정 목록**이다:
+ * 모호한 지점은 에이전트가 가정을 세우고 **기록한 뒤 진행**한다(FR-10.2).
+ * 기록되지 않은 가정이 없다는 것 — 그게 이 단계의 진짜 산출물이다.
+ *
+ * 사람을 부르는 경우는 하나뿐이다(FR-10.3): **상호 배타적이고 스펙을 실질적으로 가르는
+ * 분기.** "둘 다 가정으로 적고 진행"이 성립하지 않는 지점. 그마저도 한 번에 하나만 묻는다 —
+ * 질문을 쌓으면 무중단이라는 기본이 무너진다.
+ *
+ * 산출물 문서는 **엔진이 쓴다.** 에이전트에게 쓰게 하면 경로를 못 지키거나 남의 파일을
+ * 건드릴 수 있고, 무엇보다 "썼다고 말했지만 안 썼다"를 검증할 방법이 없다.
+ * 그래서 이 단계의 에이전트는 쓰기 권한 없이(plan) 돌고, 판정 가능한 JSON 만 돌려준다.
+ */
+import { spawn } from 'node:child_process';
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { buildAgentArgs, parseAgentOutput } from './runners.js';
+import { discoverPrompt } from './prompts.js';
+
+/** 관대한 파싱. 형식이 깨지면 "가정도 분기도 없음" — 발굴 실패가 루프를 막지는 않는다. */
+export function parseDiscovery(text) {
+  try {
+    const m = String(text).match(/\{[\s\S]*"assumptions"[\s\S]*\}/);
+    const obj = JSON.parse(m ? m[0] : text);
+    const assumptions = (Array.isArray(obj.assumptions) ? obj.assumptions : [])
+      .map((a) => String(a?.text ?? a ?? '').trim())
+      .filter(Boolean);
+
+    // 분기는 **하나만** 받는다. 선택지가 2개 미만이면 분기가 아니다 — 고를 게 없으면
+    // 그건 그냥 질문이고, 질문은 가정으로 답해야 할 대상이다.
+    const raw = Array.isArray(obj.forks) ? obj.forks : obj.fork ? [obj.fork] : [];
+    const fork = raw
+      .map((f) => ({
+        question: String(f?.question ?? '').trim(),
+        options: (Array.isArray(f?.options) ? f.options : [])
+          .map((o) => ({ label: String(o?.label ?? o ?? '').trim(), impact: String(o?.impact ?? '').trim() }))
+          .filter((o) => o.label),
+      }))
+      .find((f) => f.question && f.options.length >= 2) ?? null;
+
+    return { assumptions, fork, summary: String(obj.summary ?? '').trim() };
+  } catch {
+    return { assumptions: [], fork: null, summary: '' };
+  }
+}
+
+/** 발굴 결과를 사람이 읽을 문서로 만든다. 이 문서가 나중 단계들이 참조할 근거가 된다. */
+export function renderDiscoveryDoc({ goal, assumptions, fork, summary, now }) {
+  const lines = [
+    '# 요구사항 발굴 (DISCOVER)',
+    '',
+    `> hi-loop 이 자동 생성했습니다. 생성 시각: ${now}`,
+    '',
+    '## 목표(goal)',
+    goal,
+    '',
+  ];
+  if (summary) lines.push('## 해석', summary, '');
+  lines.push('## 확정된 가정');
+  if (assumptions.length) {
+    lines.push('goal 만으로는 정해지지 않아 엔진이 확정한 것들이다. 틀렸다면 여기를 고치고 다시 실행하라.', '');
+    for (const a of assumptions) lines.push(`- ${a}`);
+  } else {
+    lines.push('(없음 — goal 이 이미 충분히 정밀하다고 판단했다)');
+  }
+  lines.push('');
+  if (fork) {
+    lines.push('## 사람에게 물은 분기', `**${fork.question}**`, '');
+    for (const o of fork.options) lines.push(`- ${o.label}${o.impact ? ` — ${o.impact}` : ''}`);
+    lines.push('');
+  }
+  return lines.join('\n');
+}
+
+export function writeDiscoveryDoc({ cwd, relPath, content }) {
+  const full = join(cwd, relPath);
+  mkdirSync(dirname(full), { recursive: true });
+  writeFileSync(full, `${content}\n`, 'utf8');
+  return relPath;
+}
+
+/**
+ * 주입 가능한 발굴 포트 (NFR-3). `({ goal, cwd }) => { assumptions[], fork, summary }`
+ * 기본 구현은 claude 를 plan 모드(쓰기 금지)·새 세션으로 spawn 한다.
+ */
+export function makeDiscoverer({
+  command = process.env.HILOOP_DISCOVER_CMD || process.env.HILOOP_AGENT_CMD || 'claude',
+  model = process.env.HILOOP_DISCOVER_MODEL || '',
+  timeoutMs = 10 * 60 * 1000,
+} = {}) {
+  return ({ goal, cwd }) =>
+    new Promise((resolve) => {
+      const extraArgs = model ? ['--model', model] : [];
+      const args = buildAgentArgs({
+        prompt: discoverPrompt({ goal }),
+        sessionId: null,
+        extraArgs,
+        permissionMode: 'plan',
+      });
+      const child = spawn(command, args, { cwd, env: process.env });
+      let stdout = '';
+      const timer = setTimeout(() => child.kill('SIGKILL'), timeoutMs);
+      child.stdout.on('data', (d) => (stdout += d));
+      child.stderr.on('data', () => {});
+      // 발굴 실패는 루프를 막지 않는다. 발굴은 정확도를 높이는 단계지 통과 조건이 아니다.
+      child.on('error', () => {
+        clearTimeout(timer);
+        resolve({ assumptions: [], fork: null, summary: '' });
+      });
+      child.on('close', (code) => {
+        clearTimeout(timer);
+        resolve(code === 0 ? parseDiscovery(parseAgentOutput(stdout).text) : { assumptions: [], fork: null, summary: '' });
+      });
+    });
+}