@tuzi-ince/hi-loop 0.1.1

package/src/runners.js

@@ -0,0 +1,129 @@
+/**
+ * I/O 경계 어댑터 (NFR-3): 에이전트 호출 / 테스트 실행.
+ * 루프 엔진은 이 함수들을 주입받으므로, 테스트에서는 스텁으로 대체된다.
+ */
+import { spawn } from 'node:child_process';
+
+/**
+ * 양의 정수 환경변수를 읽되, 없거나 쓰레기값이면 기본값으로 조용히 되돌린다.
+ * 타임아웃을 0 이나 음수로 잘못 주면 즉시 죽는 러너가 되므로 방어한다.
+ */
+function envMs(name, fallback) {
+  const v = Number(process.env[name]);
+  return Number.isFinite(v) && v > 0 ? v : fallback;
+}
+
+/** 쉘 명령을 실행하고 exit code 로 성패를 판정한다 (FR-2.3) */
+export function makeTestRunner({ timeoutMs = envMs('HILOOP_TEST_TIMEOUT_MS', 10 * 60 * 1000) } = {}) {
+  return ({ command, cwd }) =>
+    new Promise((resolve) => {
+      const child = spawn(command, { cwd, shell: true, env: process.env });
+      let stdout = '';
+      let stderr = '';
+      let timedOut = false;
+      const timer = setTimeout(() => {
+        timedOut = true;
+        child.kill('SIGKILL');
+      }, timeoutMs);
+
+      child.stdout?.on('data', (d) => {
+        stdout += d;
+      });
+      child.stderr?.on('data', (d) => {
+        stderr += d;
+      });
+      child.on('error', (err) => {
+        clearTimeout(timer);
+        resolve({ ok: false, code: -1, stdout, stderr: `${stderr}\n${err.message}` });
+      });
+      child.on('close', (code) => {
+        clearTimeout(timer);
+        if (timedOut) {
+          resolve({ ok: false, code: -1, stdout, stderr: `${stderr}\n[hi-loop] 테스트가 ${timeoutMs}ms 안에 끝나지 않아 강제 종료했습니다.` });
+          return;
+        }
+        resolve({ ok: code === 0, code, stdout, stderr });
+      });
+    });
+}
+
+/**
+ * 기본 권한 모드의 `claude -p` 는 비대화형이라 파일 편집 권한 요청을 물어볼 상대가 없고,
+ * 그 결과 편집이 거부된다. 그러면 루프는 아무 파일도 못 쓴 채 헛돌기만 한다.
+ * 자가 치유 엔진의 전제가 "에이전트가 코드를 고친다"이므로 편집 허용이 기본값이어야 한다.
+ * 더 넓히거나(bypassPermissions) 좁히려면 HILOOP_PERMISSION_MODE 로 덮어쓴다.
+ */
+export const DEFAULT_PERMISSION_MODE = 'acceptEdits';
+
+/** 사용자가 이미 권한 모드를 직접 넘겼으면 우리가 끼어들지 않는다. */
+export function buildAgentArgs({ prompt, sessionId, extraArgs = [], permissionMode }) {
+  const args = ['-p', prompt, '--output-format', 'json'];
+  if (sessionId) args.push('--resume', sessionId);
+  if (permissionMode && !extraArgs.includes('--permission-mode')) {
+    args.push('--permission-mode', permissionMode);
+  }
+  args.push(...extraArgs);
+  return args;
+}
+
+/**
+ * 에이전트 CLI 러너. 기본은
+ * `claude -p <prompt> --output-format json --permission-mode acceptEdits`.
+ * 세션 유지는 --resume <sessionId>, 핸드오프는 sessionId=null 로 새 세션 시작.
+ */
+export function makeAgentRunner({
+  command = process.env.HILOOP_AGENT_CMD || 'claude',
+  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),
+} = {}) {
+  return ({ prompt, sessionId, cwd }) =>
+    new Promise((resolve, reject) => {
+      const args = buildAgentArgs({ prompt, sessionId, extraArgs, permissionMode });
+
+      const child = spawn(command, args, { cwd, env: process.env });
+      let stdout = '';
+      let stderr = '';
+      const timer = setTimeout(() => child.kill('SIGKILL'), timeoutMs);
+
+      child.stdout.on('data', (d) => {
+        stdout += d;
+      });
+      child.stderr.on('data', (d) => {
+        stderr += d;
+      });
+      child.on('error', (err) => {
+        clearTimeout(timer);
+        reject(new Error(`에이전트 실행 실패(${command}): ${err.message}`));
+      });
+      child.on('close', (code) => {
+        clearTimeout(timer);
+        if (code !== 0) {
+          reject(new Error(`에이전트가 코드 ${code}로 종료했습니다.\n${stderr.slice(-2000)}`));
+          return;
+        }
+        resolve(parseAgentOutput(stdout, sessionId));
+      });
+    });
+}
+
+/**
+ * `--output-format json` 응답에서 결과 텍스트와 session_id, 비용을 뽑는다.
+ *
+ * 비용을 읽는 이유: 실측상 사소한 호출 1회도 새 세션이면 ~$0.43(캐시 생성 42k 토큰),
+ * "add 함수를 만들어라" 2회전이 $2.58~$4.67 이었다. 같은 goal·같은 iteration 수인데도
+ * 1.8배 차이가 났다 — maxLoops 는 비용 상한이 아니다. 엔진이 직접 세지 않으면
+ * 아무도 세지 않는다.
+ */
+export function parseAgentOutput(stdout, fallbackSessionId = null) {
+  try {
+    const json = JSON.parse(stdout);
+    return {
+      text: typeof json.result === 'string' ? json.result : stdout,
+      sessionId: json.session_id ?? fallbackSessionId,
+      costUsd: Number.isFinite(json.total_cost_usd) ? json.total_cost_usd : 0,
+    };
+  } catch {
+    return { text: stdout, sessionId: fallbackSessionId, costUsd: 0 };
+  }
+}

package/src/state.js

@@ -0,0 +1,230 @@
+/**
+ * .agent-state.json 상태 저장소 (FR-3, NFR-4)
+ * - 원자적 쓰기(tmp -> rename)
+ * - 컨텍스트 다이어트: 저장 시 필드 길이를 강제로 자른다.
+ */
+import { readFileSync, writeFileSync, renameSync, existsSync, rmSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { createHash } from 'node:crypto';
+
+export const STATE_VERSION = 1;
+export const STATE_FILENAME = '.agent-state.json';
+
+export const DEFAULT_SPEC_PATH = 'docs/spec.md';
+export const DEFAULT_TEST_PATH = 'tests/app.test.js';
+
+export const LIMITS = {
+  specSummary: 1200,
+  lastError: 2000,
+  historyKeep: 5,
+  historySummary: 300,
+  checkpointKeep: 10, // 최근 10개 체크포인트만 유지 (L3)
+};
+
+export function truncate(text, max) {
+  if (typeof text !== 'string') return '';
+  if (text.length <= max) return text;
+  // 에러는 뒷부분(실제 실패 지점)이 중요하므로 꼬리를 남긴다.
+  return `…(앞부분 ${text.length - max}자 생략)\n${text.slice(-max)}`;
+}
+
+/**
+ * 실패의 **안정적 지문** (L2 정체 감지용).
+ *
+ * lastError 전체를 해시하면 매번 달라진다 — 소요시간(`duration_ms 47.8`), 임시경로,
+ * 줄번호가 실행마다 바뀌기 때문이다. 그러면 같은 오답을 반복해도 "매번 다른 에러"로 보여
+ * 정체를 놓친다. 그래서 변하는 것(숫자·경로·16진수)을 지운 뼈대만 남긴다.
+ * 남는 것은 "무엇이 어떻게 깨졌는가"의 형태다 — `AssertionError`, `ReferenceError: X`,
+ * 무결성 위반 종류 같은 것.
+ */
+export function errorSignature(text) {
+  return String(text ?? '')
+    .replace(/0x[0-9a-f]+/gi, '') // 포인터/해시
+    .replace(/\b[0-9a-f]{8,}\b/gi, '') // 긴 16진수(세션id 등)
+    .replace(/\d+(?:\.\d+)?\s*ms\b/g, '') // 소요시간
+    .replace(/:\d+:\d+/g, '') // :줄:열
+    .replace(/\/[^\s'"]+/g, '') // 절대경로
+    .replace(/\d+/g, '') // 남은 숫자 전부
+    .replace(/\s+/g, ' ')
+    .trim()
+    .slice(0, 500);
+}
+
+export function statePathFor(cwd) {
+  return join(cwd, STATE_FILENAME);
+}
+
+/**
+ * PLAN 이 쓸 spec/테스트 경로를 고른다.
+ *
+ * 기본 경로가 비어 있으면 그대로 쓴다. 이미 뭔가 있으면 goal 별 경로로 **비켜간다**.
+ * 이유: PLAN 프롬프트는 원래 `docs/spec.md` 와 `tests/app.test.js` 를 하드코딩했다.
+ * 그래서 (a) 그 파일들이 이미 있는 프로젝트에서 돌리면 남의 스펙·테스트를 덮어썼고,
+ * (b) 같은 프로젝트에서 goal 만 바꿔 두 번 돌리면 1회차의 산출물이 2회차에 파괴됐다.
+ * 롤백도 없다. 실측으로 확인된 동작이지 가정이 아니다 — 빈 디렉터리에서 돌리면
+ * 에이전트는 실제로 그 두 경로에 쓴다.
+ *
+ * goal 해시를 쓰는 이유: 같은 goal 이면 같은 경로가 나와야 resume 이 이어지고,
+ * 다른 goal 끼리는 충돌하지 않는다. 한국어 goal 도 파일명이 깨지지 않는다.
+ */
+export function planPathsFor({ cwd, goal }) {
+  const slug = createHash('sha1').update(String(goal)).digest('hex').slice(0, 8);
+  return {
+    specPath: existsSync(join(cwd, DEFAULT_SPEC_PATH)) ? `docs/spec-${slug}.md` : DEFAULT_SPEC_PATH,
+    testPath: existsSync(join(cwd, DEFAULT_TEST_PATH)) ? `tests/app-${slug}.test.js` : DEFAULT_TEST_PATH,
+  };
+}
+
+export function createState({
+  goal,
+  testCommand,
+  maxLoops,
+  cwd = process.cwd(),
+  now = new Date().toISOString(),
+}) {
+  // 경로는 **한 번만** 정하고 상태에 박아둔다. 매번 다시 계산하면 PLAN 이 만든 파일 때문에
+  // 2회차부터 경로가 밀려난다.
+  const { specPath, testPath } = planPathsFor({ cwd, goal });
+  return {
+    version: STATE_VERSION,
+    goal,
+    testCommand,
+    status: 'running',
+    phase: 'PLAN',
+    iteration: 0,
+    maxLoops,
+    sessionId: null,
+    sessionSerial: 1,
+    specPath,
+    testPath,
+    specSummary: '',
+    lastError: '',
+    costUsd: 0,
+    testFingerprint: {}, // L1 가드의 기준선. 빈 값 = 아직 비교할 대상 없음.
+    errorSig: '',        // L2: 직전 실패의 안정적 지문. 정체 감지용.
+    stagnantRuns: 0,     // L2: errorSig 가 연속 동일한 횟수.
+    checkpoints: [],     // L3: [{iteration, sha}] git stash create 스냅샷.
+    deletedFiles: [],    // L8: 에이전트가 지운 baseline 파일(관측용, 누적).
+    history: [],
+    startedAt: now,
+    updatedAt: now,
+  };
+}
+
+/**
+ * 동일 goal 이면 auto-resume, 아니면 새 상태 (FR-3.5).
+ * resume 은 상태 로직이므로 state.js 가 제자리다 — loadState/createState/planPathsFor 를 여기서 쓴다.
+ */
+export function resumeOrCreate({ statePath, goal, testCommand, maxLoops, cwd }) {
+  const prev = existsSync(statePath) ? loadState(statePath) : null;
+  if (prev && prev.goal === goal && prev.status !== 'passed') {
+    // 필드가 없던 시절의 상태 파일도 이어받는다. 경로는 절대 다시 계산하지 않는다 —
+    // PLAN 이 이미 만든 파일 때문에 경로가 밀려나기 때문이다.
+    const paths = prev.specPath && prev.testPath ? {} : planPathsFor({ cwd, goal });
+    return {
+      ...paths,
+      ...prev,
+      specPath: prev.specPath ?? paths.specPath,
+      testPath: prev.testPath ?? paths.testPath,
+      costUsd: Number.isFinite(prev.costUsd) ? prev.costUsd : 0,
+      // 기준선이 없던 시절의 상태로 재개하면 이번 회차 지문이 곧 기준선이 된다.
+      // 그 사이에 벌어진 약화는 못 잡는다 — resume 은 과거를 복원하지 못한다.
+      testFingerprint: prev.testFingerprint ?? {},
+      errorSig: prev.errorSig ?? '',
+      stagnantRuns: Number.isFinite(prev.stagnantRuns) ? prev.stagnantRuns : 0,
+      checkpoints: Array.isArray(prev.checkpoints) ? prev.checkpoints : [],
+      deletedFiles: Array.isArray(prev.deletedFiles) ? prev.deletedFiles : [],
+      testCommand,
+      maxLoops,
+      status: 'running',
+    };
+  }
+  return createState({ goal, testCommand, maxLoops, cwd });
+}
+
+export function loadState(path) {
+  if (!existsSync(path)) return null;
+  try {
+    const parsed = JSON.parse(readFileSync(path, 'utf8'));
+    if (!parsed || parsed.version !== STATE_VERSION) return null;
+    return parsed;
+  } catch {
+    return null; // 손상된 상태 파일은 무시하고 새로 시작한다.
+  }
+}
+
+/** 원자적 저장 + 컨텍스트 다이어트 (FR-3.1, FR-3.3) */
+export function saveState(path, state, { now = new Date().toISOString() } = {}) {
+  const compact = {
+    ...state,
+    specSummary: truncate(state.specSummary, LIMITS.specSummary),
+    lastError: truncate(state.lastError, LIMITS.lastError),
+    history: (state.history ?? []).slice(-LIMITS.historyKeep).map((h) => ({
+      ...h,
+      summary: truncate(h.summary ?? '', LIMITS.historySummary),
+    })),
+    updatedAt: now,
+  };
+  const tmp = join(dirname(path), `.${STATE_FILENAME}.${process.pid}.tmp`);
+  writeFileSync(tmp, `${JSON.stringify(compact, null, 2)}\n`, 'utf8');
+  renameSync(tmp, path); // 같은 디렉터리 내 rename == 원자적
+  return compact;
+}
+
+export function resetState(path) {
+  if (existsSync(path)) {
+    rmSync(path);
+    return true;
+  }
+  return false;
+}
+
+/**
+ * 완료 보고: 무엇을 관측했고 무엇을 안 했는가 (L10, moai 의 5-섹션 규약 중 Evidence+Gaps).
+ *
+ * 이 엔진의 `passed` 는 조용한 거짓말이 될 수 있다 — 테스트를 PLAN 단계에서 에이전트
+ * 자신이 썼기 때문이다. exit 0 의 실제 의미는 "에이전트가 자기가 쓴 테스트를 자기가
+ * 통과시켰다"이고, 스펙의 수용 기준 중 무엇이 테스트로 커버 안 됐는지는 아무도 안 본다.
+ *
+ * moai: "빈 Gaps 섹션은 '관측하지 않은 것이 없다'는 강한 주장이며, 그 주장 자체가
+ * 참이어야 한다." 그래서 숨기는 대신 매 완료에 공개한다. false green 을 disclosed green 으로.
+ */
+export function reportGaps(state) {
+  const lines = ['', '## 검증 현황 (hi-loop 는 자기 판정의 한계를 숨기지 않는다)'];
+
+  const deleted = state.deletedFiles ?? [];
+
+  lines.push('관측한 것(Evidence):');
+  lines.push(`- ${state.testCommand} 종료 코드로 판정 (iteration ${state.iteration})`);
+  lines.push('- 테스트 파일 무결성 위반 없음 (직전 회차 대비 지문 비교)');
+  lines.push(`- 누적 비용 $${(state.costUsd ?? 0).toFixed(2)}`);
+  if (state.specVerified) lines.push('- 스펙 대비 구현을 별도 검증자가 심판(2단 판정 통과)');
+
+  lines.push('관측하지 않은 것(Gaps):');
+  lines.push(`- 이 테스트는 PLAN 단계에서 에이전트 자신이 \`${state.testPath || 'tests/app.test.js'}\`에 작성했다. 외부 오라클이 아니다.`);
+  if (!state.specVerified) {
+    lines.push(`- \`${state.specPath || 'docs/spec.md'}\`의 수용 기준 중 무엇이 테스트로 커버되지 않았는지는 검증하지 않았다(--verify-spec 로 켤 수 있다).`);
+  }
+  lines.push('- 런타임 동작·성능·보안은 관측 범위 밖이다.');
+  if (deleted.length) {
+    lines.push(`- ⚠️ 에이전트가 baseline 파일 ${deleted.length}개를 삭제했다(차단 안 함): ${deleted.slice(0, 5).join(', ')}${deleted.length > 5 ? ' …' : ''}. hi-loop rollback 으로 복원 가능.`);
+  }
+
+  return lines.join('\n');
+}
+
+export function summarizeState(state) {
+  if (!state) return '진행 중인 hi-loop 루프 상태가 없습니다.';
+  const lines = [
+    `goal: ${state.goal}`,
+    `status: ${state.status}${state.stopReason ? ` (${state.stopReason})` : ''} / phase: ${state.phase}`,
+    `iteration: ${state.iteration}/${state.maxLoops} (session #${state.sessionSerial})`,
+    `cost: $${(state.costUsd ?? 0).toFixed(2)}`,
+    ...(state.stagnantRuns > 1 ? [`stagnant: 같은 실패 ${state.stagnantRuns}회 연속`] : []),
+    `testCommand: ${state.testCommand}`,
+    `updatedAt: ${state.updatedAt}`,
+  ];
+  if (state.specSummary) lines.push(`spec: ${truncate(state.specSummary, 200)}`);
+  if (state.lastError) lines.push(`lastError: ${truncate(state.lastError, 400)}`);
+  return lines.join('\n');
+}

package/src/telegram.js

@@ -0,0 +1,54 @@
+/**
+ * 텔레그램 비동기 알림 (FR-5)
+ * 설계 원칙: 알림은 절대 루프를 깨뜨리지 않는다. 모든 실패를 삼킨다.
+ */
+export const TELEGRAM_MAX = 4096;
+
+export function isConfigured(env = process.env) {
+  return Boolean(env.TELEGRAM_BOT_TOKEN && env.TELEGRAM_CHAT_ID);
+}
+
+/**
+ * @returns {Promise<{ok:boolean, skipped?:boolean, error?:string, status?:number}>}
+ */
+export async function sendMessage(text, { env = process.env, fetchImpl = globalThis.fetch } = {}) {
+  if (!isConfigured(env)) return { ok: false, skipped: true };
+  if (typeof fetchImpl !== 'function') return { ok: false, error: 'fetch 사용 불가 (Node 18+ 필요)' };
+
+  const body = {
+    chat_id: env.TELEGRAM_CHAT_ID,
+    text: truncateForTelegram(text),
+    disable_web_page_preview: true,
+  };
+
+  try {
+    const res = await fetchImpl(`https://api.telegram.org/bot${env.TELEGRAM_BOT_TOKEN}/sendMessage`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify(body),
+    });
+    if (!res?.ok) return { ok: false, status: res?.status, error: `텔레그램 API ${res?.status}` };
+    return { ok: true, status: res.status };
+  } catch (err) {
+    return { ok: false, error: err?.message ?? String(err) };
+  }
+}
+
+export function truncateForTelegram(text) {
+  const s = typeof text === 'string' ? text : String(text);
+  if (s.length <= TELEGRAM_MAX) return s;
+  return `${s.slice(0, TELEGRAM_MAX - 1)}…`;
+}
+
+const ICON = { start: '🚀', handoff: '♻️', passed: '✅', failed: '❌', check: '🔍' };
+
+/** 루프 이벤트를 사람이 읽을 문장으로 바꿔 전송한다 (FR-5.5) */
+export function makeNotifier(options = {}) {
+  return async (event) => {
+    const icon = ICON[event.type] ?? 'ℹ️';
+    const lines = [`${icon} [hi-loop] ${event.type}`, `goal: ${event.goal ?? '-'}`];
+    if (event.iteration != null) lines.push(`iteration: ${event.iteration}/${event.maxLoops ?? '?'}`);
+    if (event.detail) lines.push(String(event.detail));
+    return sendMessage(lines.join('\n'), options);
+  };
+}

package/src/verify.js

@@ -0,0 +1,96 @@
+/**
+ * 스펙 오라클 (P6, L9) — bkit 의 중심 명제 이식.
+ *
+ * bkit: "코드와 스펙이 어긋나면, 틀린 쪽은 코드다." hi-loop 의 판정은 exit code 하나뿐인데,
+ * 그 테스트를 에이전트 자신이 썼다(L9). 즉 exit 0 은 "에이전트가 자기 테스트를 통과시켰다"일
+ * 뿐, 스펙의 수용 기준을 실제로 달성했는지는 아무도 안 봤다.
+ *
+ * 2단 판정으로 이걸 닫는다 (분석 §5, moai 의 goal evaluator 구조):
+ * - Tier 1 (기계, 최종 권한): exit code + 무결성. 실패면 끝. 어떤 모델도 못 뒤집는다.
+ * - Tier 2 (모델, 하향 전용): 스펙 대비 구현 심판. **오직 기각만 가능** — Tier 1 통과를
+ *   되돌릴 수는 있어도, Tier 1 실패를 통과로 올릴 권한은 절대 없다.
+ *
+ * 검증자 격리 (bkit 의 context:fork + disallowedTools):
+ * - 쓰기 권한 없음: `--permission-mode plan` — 검증 대상을 물리적으로 못 고친다.
+ * - 새 세션: sessionId 없이 호출 — 구현자의 추론에 오염되지 않는다.
+ *
+ * opt-in 이다(--verify-spec). 검증자 호출이 붙어 비용이 늘기 때문. G1(판정 주체는 엔진)은
+ * 유지된다 — 최종 권한은 여전히 Tier 1 이고, Tier 2 는 기각만 하는 심판이다.
+ */
+import { spawn } from 'node:child_process';
+import { execFile } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { buildAgentArgs, parseAgentOutput } from './runners.js';
+import { verifyPrompt } from './prompts.js';
+
+function gitDiff(cwd) {
+  return new Promise((resolve) => {
+    // 워킹트리 전체 diff (추적 파일). 스펙·테스트 대비 구현이 무엇을 했는지.
+    execFile('git', ['diff', 'HEAD'], { cwd, maxBuffer: 4 * 1024 * 1024 }, (err, stdout) => {
+      resolve(err ? '' : String(stdout));
+    });
+  });
+}
+
+/** JSON 판정을 관대하게 파싱한다. 형식이 깨지면 "통과"로 흘린다(하향 전용이므로 안전). */
+export function parseVerdict(text) {
+  try {
+    const m = String(text).match(/\{[\s\S]*"verdict"[\s\S]*\}/);
+    const obj = JSON.parse(m ? m[0] : text);
+    const verdict = obj.verdict === 'reject' ? 'reject' : 'pass';
+    return { verdict, reason: typeof obj.reason === 'string' ? obj.reason : '' };
+  } catch {
+    // 판정 형식을 못 읽으면 기각하지 않는다 — 검증자가 헛소리를 했다고 통과를
+    // 막으면, 잘못된 입력이 방어를 "더 약하게"가 아니라 "더 세게" 만드는 게 아니라
+    // 반대가 된다. Tier 2 는 하향 전용이고 확신 없으면 통과가 원칙이다.
+    return { verdict: 'pass', reason: '검증자 응답을 파싱하지 못해 통과로 처리(하향 전용)' };
+  }
+}
+
+/**
+ * 주입 가능한 스펙 검증 포트 (NFR-3). `({ specPath, cwd }) => { verdict, reason }`
+ * 기본 구현은 별도 claude 를 plan 모드·새 세션으로 spawn 한다.
+ */
+export function makeSpecVerifier({
+  command = process.env.HILOOP_VERIFY_CMD || process.env.HILOOP_AGENT_CMD || 'claude',
+  model = process.env.HILOOP_VERIFY_MODEL || '',
+  timeoutMs = 10 * 60 * 1000,
+} = {}) {
+  return ({ specPath, cwd }) =>
+    new Promise((resolve) => {
+      const specFull = specPath ? join(cwd, specPath) : null;
+      if (!specFull || !existsSync(specFull)) {
+        // 스펙이 없으면 대조할 오라클이 없다 → 기각할 근거 없음 → 통과.
+        resolve({ verdict: 'pass', reason: '스펙 파일이 없어 검증 생략' });
+        return;
+      }
+      const specText = readFileSync(specFull, 'utf8');
+      gitDiff(cwd).then((diffText) => {
+        const prompt = verifyPrompt({ specText, diffText });
+        // 새 세션(sessionId 없음) + plan 모드(쓰기 금지). 모델을 따로 지정할 수 있다.
+        const extraArgs = model ? ['--model', model] : [];
+        const args = buildAgentArgs({ prompt, sessionId: null, extraArgs, permissionMode: 'plan' });
+        const child = spawn(command, args, { cwd, env: process.env });
+        let stdout = '';
+        let stderr = '';
+        const timer = setTimeout(() => child.kill('SIGKILL'), timeoutMs);
+        child.stdout.on('data', (d) => (stdout += d));
+        child.stderr.on('data', (d) => (stderr += d));
+        child.on('error', () => {
+          clearTimeout(timer);
+          // 검증자 실행 자체가 실패하면 통과를 막지 않는다(인프라 장애가 판정을 뒤집으면 안 됨).
+          resolve({ verdict: 'pass', reason: `검증자 실행 실패 — 통과로 처리` });
+        });
+        child.on('close', (code) => {
+          clearTimeout(timer);
+          if (code !== 0) {
+            resolve({ verdict: 'pass', reason: `검증자가 코드 ${code}로 종료 — 통과로 처리` });
+            return;
+          }
+          const { text } = parseAgentOutput(stdout);
+          resolve(parseVerdict(text));
+        });
+      });
+    });
+}