@tuzi-ince/hi-loop 0.3.1 → 0.3.3

package/src/cli-commands.js

@@ -0,0 +1,100 @@
+/**
+ * CLI 보조 명령 구현 — answer / rollback / config (bin/hi-loop.js 에서 분리, NFR-5).
+ *
+ * bin 은 인자 파싱과 라우팅만 맡고, 각 명령의 실제 동작은 여기 있다. 각 함수는 stdout/stderr 로
+ * 직접 내고 **exit code 를 반환**한다 — bin 은 그 코드를 그대로 돌려주기만 한다.
+ *
+ * 정적 import 를 쓴다: 여기서 부르는 모듈(state·ask·checkpoint·config)은 MCP SDK 에 의존하지
+ * 않으므로 CLI 경량성(NFR-1)을 해치지 않는다. bin 은 이 파일 자체를 명령별로 lazy import 한다.
+ */
+import { loadState, saveState, statePathFor } from './state.js';
+import { applyAnswer } from './ask.js';
+import { rollbackTo } from './checkpoint.js';
+import * as cfg from './config.js';
+
+/** hi-loop answer <선택> [--note "..."] — 대기 중인 질문에 답하고 루프를 재개 가능 상태로 되돌린다. */
+export async function runAnswer({ cwd, args }) {
+  const statePath = statePathFor(cwd);
+  const state = loadState(statePath);
+  if (!state?.ask) {
+    process.stderr.write('대기 중인 질문이 없습니다.\n');
+    return 1;
+  }
+  const note = args.note && args.note !== true ? String(args.note) : '';
+  const res = applyAnswer(state, { choice: args._[1], note });
+  if (!res.ok) {
+    process.stderr.write(`${res.reason}\n`);
+    return 2;
+  }
+  saveState(statePath, res.state);
+  const last = res.state.assumptions[res.state.assumptions.length - 1];
+  process.stdout.write(`✅ 기록했습니다: ${last.text}\n   이어서 진행하려면 같은 goal 로 hi-loop run 을 다시 실행하세요.\n`);
+  return 0;
+}
+
+/** hi-loop rollback [--to N] — N회차 직전 체크포인트로 추적 파일을 복원한다(기본: 최신). */
+export async function runRollback({ cwd, args }) {
+  const state = loadState(statePathFor(cwd));
+  const checkpoints = state?.checkpoints ?? [];
+  if (checkpoints.length === 0) {
+    process.stderr.write('되돌릴 체크포인트가 없습니다 (git 저장소가 아니거나 아직 스냅샷이 없음).\n');
+    return 1;
+  }
+  // --to N 이면 N회차 직전 체크포인트, 없으면 가장 최근.
+  const toIter = args.to !== undefined && args.to !== true ? Number(args.to) : null;
+  const cp = toIter != null ? checkpoints.find((c) => c.iteration === toIter) : checkpoints[checkpoints.length - 1];
+  if (!cp) {
+    process.stderr.write(`${toIter}회차 체크포인트가 없습니다. 있는 회차: ${checkpoints.map((c) => c.iteration).join(', ')}\n`);
+    return 1;
+  }
+  const res = await rollbackTo({ cwd, sha: cp.sha });
+  if (!res.ok) {
+    process.stderr.write(`롤백 실패: ${res.reason}\n`);
+    return 1;
+  }
+  process.stdout.write(`✅ ${cp.iteration}회차 직전 상태로 추적 파일을 복원했습니다 (${cp.sha.slice(0, 8)}).\n`);
+  // 되돌리지 못한 것을 되돌렸다고 말하지 않는다. git 은 추적 밖 파일을 트리 연산으로
+  // 지우지 않고, `git clean` 은 사용자의 정상 파일까지 지운다 — 그래서 판단은 사람에게 준다.
+  if (res.untrackedRemain?.length) {
+    process.stdout.write(
+      `⚠️ 추적되지 않는 파일 ${res.untrackedRemain.length}개는 그대로 남아 있습니다(에이전트가 새로 만든 것일 수 있습니다):\n` +
+        res.untrackedRemain.slice(0, 10).map((f) => `   - ${f}\n`).join('') +
+        (res.untrackedRemain.length > 10 ? `   … 외 ${res.untrackedRemain.length - 10}개\n` : '') +
+        '   필요하면 직접 지우세요. hi-loop 은 사용자의 정상 파일을 지울 수 없어 판단하지 않습니다.\n',
+    );
+  }
+  if (res.safetySha) process.stdout.write(`   되돌리기 전 상태는 ${res.safetySha.slice(0, 8)} 에 스냅샷됨.\n`);
+  return 0;
+}
+
+/**
+ * hi-loop config [set <k> <v> | add-branch <b> | remove-branch <b>] — 브랜치·커밋 정책(.hi-loop.json).
+ * 인자 없으면 현재 정책을 출력한다.
+ */
+export async function runConfig({ cwd, args }) {
+  const sub = args._[1];
+  if (!sub) {
+    process.stdout.write(`${JSON.stringify(cfg.loadConfig(cwd), null, 2)}\n`);
+    return 0;
+  }
+  if (sub === 'set') {
+    const r = cfg.setPolicy(cwd, args._[2], args._[3]);
+    if (!r.ok) {
+      process.stderr.write(`${r.reason}\n`);
+      return 2;
+    }
+    process.stdout.write(`✓ ${args._[2]} = ${args._[3]}\n`);
+    return 0;
+  }
+  if (sub === 'add-branch' || sub === 'remove-branch') {
+    const r = sub === 'add-branch' ? cfg.addBranch(cwd, args._[2]) : cfg.removeBranch(cwd, args._[2]);
+    if (!r.ok) {
+      process.stderr.write(`${r.reason}\n`);
+      return 2;
+    }
+    process.stdout.write(`✓ 보호 브랜치: ${r.config.protectedBranches.join(', ')}\n`);
+    return 0;
+  }
+  process.stderr.write(`알 수 없는 config 하위명령: ${sub} (가능: set, add-branch, remove-branch)\n`);
+  return 2;
+}

package/src/cli-options.js

@@ -118,6 +118,9 @@ export function parseRunOptions(args, { staged = {} } = {}) {
     ok: true,
     options: {
       testCommand: str('test') ?? 'npm test',
+      // FR-19: 스펙 오라클을 이 경로로 고정한다. goal 해시 분기를 끄고, 여러 요청이
+      // 같은 표준 문서를 오라클로 공유하게 해 문서↔소스 drift 를 막는다.
+      specPath: str('spec'),
       budgetUsd,
       stagnationLimit,
       verifySpec: Boolean(args['verify-spec']),
@@ -141,6 +144,9 @@ export function parseRunOptions(args, { staged = {} } = {}) {
       codeReview: triState('review', 'no-review'),
       designReview: triState('design-review', 'no-design-review'),
       discover: triState('discover', 'no-discover'),
+      reconcile: triState('reconcile', 'no-reconcile'),
+      // FR-21: 정합 게이트가 대조할 표준 문서 경로(기본 docs/spec.md). 지정하면 게이트가 켜진다.
+      reconcileSpec: str('reconcile-spec'),
       startFrom,
       stopAfter,
       ...durations,

package/src/loop.js

@@ -26,6 +26,10 @@ 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';
+import { buildStageContext } from './stage-context.js';
+import { makeReconciler, reconcileAsk } from './reconcile.js';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
 
 // loop.js 는 이 엔진의 정문이다. 호출부가 내부 파일 배치를 알 필요가 없도록 여기서 모아 낸다.
 export { phaseForIteration } from './build.js';
@@ -59,6 +63,7 @@ async function runLoopBody({
   stagnationLimit = 3,
   verifySpec = false,
   flakyProbe = false,
+  specPath = null, // --spec: 스펙 오라클을 표준 문서로 고정(FR-19). null=엔진이 경로 결정.
   checks = null,
   handoffEvery = 4,
   // ---- 라이프사이클 (FR-13, FR-14) ----
@@ -70,6 +75,8 @@ async function runLoopBody({
   designReview = null,
   maxDesignRounds = 2,
   discover = null,
+  reconcile = null, // FR-21: 문서 정합 게이트. null=자동(--full 또는 reconcileSpec 지정 시 켜짐).
+  reconcileSpec = null, // 대조할 표준 문서 경로. null=기본 docs/spec.md.
   full = false,
   // FR-15: 어느 경로로 들어와도 **같은 상태 머신**을 쓴다. 별도 코드 경로를 만들지 않는다
   // — 분기가 둘이면 반드시 한쪽이 썩는다.
@@ -99,6 +106,7 @@ async function runLoopBody({
   codeReviewer = makeCodeReviewer(),
   designReviewer = makeDesignReviewer(),
   discoverer = makeDiscoverer(),
+  reconciler = makeReconciler(),
   shipper = makeShipper(),
   watcher = makeWatcher(),
   brancher = makeBrancher(),
@@ -117,7 +125,7 @@ async function runLoopBody({
     throw new TypeError('budgetUsd 는 0 보다 큰 숫자여야 합니다.');
   }
 
-  let state = resumeOrCreate({ statePath, goal, testCommand, maxLoops, cwd });
+  let state = resumeOrCreate({ statePath, goal, testCommand, maxLoops, cwd, specPath });
 
   // 답 안 받은 질문이 남아 있으면 여기서 끝이다. 재개하려면 `hi-loop answer` 를 거쳐야 한다.
   // 이 관문이 없으면 run 을 다시 부르는 것만으로 사람이 고르라던 분기를 건너뛰게 된다.
@@ -164,6 +172,8 @@ async function runLoopBody({
   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);
+  // 표준 문서를 명시(reconcileSpec)하면 게이트를 쓰겠다는 뜻이므로 자동으로 켜진다(--no-reconcile 이 덮는다).
+  const reconcileEnabled = reconcile === null ? full || Boolean(reconcileSpec) : Boolean(reconcile);
 
   // 라우팅: 켜진 다음 단계로만 넘어간다(기본은 BUILD 하나). 커밋이 켜지면 리뷰된 코드를 먼저 커밋한다.
   const commitEnabled = Boolean(commit);
@@ -187,6 +197,29 @@ async function runLoopBody({
     return { pause: true };
   };
 
+  // FR-21: 문서 정합 게이트. 기존 표준 문서(docs/spec.md)가 있고 이번 요청이 그것과 별개
+  // 스펙으로 포크될 참이면, 조용히 갈라지기 전에 모순 여부를 판정한다. 모순이면 사람에게 묻는다.
+  // 대조 대상: 명시(--reconcile-spec)가 최우선. 없으면 사람이 관리하는 표준 문서(docs/design.md)를
+  // 우선하고, 그것도 없으면 docs/spec.md 로 폴백한다. spec.md 는 PLAN 이 쓴 에이전트 산출물이라
+  // 오라클로는 약하다 — 사람 문서가 있으면 그쪽이 옳다. (게이트 발동 자체는 여전히 opt-in 이다.)
+  const STANDING_SPEC = reconcileSpec
+    || (existsSync(join(cwd, 'docs/design.md')) ? 'docs/design.md' : 'docs/spec.md');
+  if (reconcileEnabled && !state.reconciled && !state.specPinned
+      && state.specPath !== STANDING_SPEC && existsSync(join(cwd, STANDING_SPEC))) {
+    // 이미 답한 재개면 판정기를 다시 부르지 않는다(비용 0). gate 가 저장된 답을 돌려준다.
+    const answered = [...(state.answers ?? [])].some((a) => a.stage === 'RECONCILE');
+    const v = answered ? { verdict: 'conflict', reason: '' } : await reconciler({ goal, specPath: STANDING_SPEC, cwd });
+    if (v.verdict === 'conflict') {
+      const g = gate(reconcileAsk({ standingSpec: STANDING_SPEC, reason: v.reason }));
+      if (g.pause) return pauseResult();
+      if (g.choice === 'a') { state.specPath = STANDING_SPEC; state.specPinned = true; }
+      else if (g.choice === 'c') return finish('failed', { stopReason: 'reconcile-aborted', detail: '문서 정리를 위해 중단' });
+      // 'b' 또는 null(ask never): 포크 경로를 그대로 쓴다. 미해결은 Gaps 에 남는다.
+    }
+    state.reconciled = true;
+    saveState(statePath, state);
+  }
+
   /** 방금 끝낸 stage 가 정지 지점인가. 다음 stage 로 넘어가기 직전에만 묻는다. */
   const shouldStopAfter = (stage) => stopAfter === stage;
 
@@ -194,65 +227,24 @@ async function runLoopBody({
    * stage 핸들러가 받는 실행 맥락. `state` 는 getter/setter 라 핸들러가 재대입해도
    * 여기 변수에 반영된다(가정 기록은 순수 함수라 새 객체를 만든다).
    */
-  const ctx = {
-    get state() {
-      return state;
-    },
-    set state(v) {
-      state = v;
-    },
-    goal,
-    cwd,
-    logger,
-    notify,
-    gate,
-    nextAfterReview,
-    nextAfterCommit,
-    statePath,
-    baselineFiles,
-    designReviewEnabled,
+  const ctx = buildStageContext({
+    getState: () => state,
+    setState: (v) => { state = v; },
     save: () => saveState(statePath, state),
+    goal, cwd, logger, notify, gate,
+    nextAfterReview, nextAfterCommit, statePath, baselineFiles, designReviewEnabled,
     ports: {
-      discoverer,
-      codeReviewer,
-      designReviewer,
-      shipper,
-      watcher,
-      brancher,
-      committer,
-      agentRunner,
-      testRunner,
-      integrityChecker,
-      checkpointer,
-      fileLister,
-      changeLister,
-      treeKeyReader,
-      specVerifier,
+      discoverer, codeReviewer, designReviewer, shipper, watcher, brancher, committer,
+      agentRunner, testRunner, integrityChecker, checkpointer, fileLister, changeLister,
+      treeKeyReader, specVerifier,
     },
     opts: {
-      shipCommand,
-      watchCommand,
-      onShipFail,
-      onWatchFail,
-      watchForMs,
-      watchEveryMs,
-      watchTolerate,
-      maxReviewRounds,
-      maxLoops,
-      budgetUsd,
-      testCommand,
-      stagnationLimit,
-      verifySpec,
-      flakyProbe,
-      checks,
-      handoffEvery,
-      maxDesignRounds,
-      stopAfter,
-      commit,
-      commitMessage,
-      commitStyle,
+      shipCommand, watchCommand, onShipFail, onWatchFail, watchForMs, watchEveryMs,
+      watchTolerate, maxReviewRounds, maxLoops, budgetUsd, testCommand, stagnationLimit,
+      verifySpec, flakyProbe, checks, handoffEvery, maxDesignRounds, stopAfter,
+      commit, commitMessage, commitStyle,
     },
-  };
+  });
 
   // ---- stage 머신 ----
   // 다음 stage 를 정하는 권한은 여기 한 곳에만 있다. 핸들러는 지시만 돌려준다.
@@ -297,4 +289,3 @@ async function runLoopBody({
 }
 
 export default runLoop;
-

package/src/mcp-server.js

@@ -8,6 +8,7 @@ import { loadState, saveState, statePathFor, summarizeState, resetState } from '
 import { applyAnswer, formatAsk } from './ask.js';
 import { rollbackTo } from './checkpoint.js';
 import { runSetup } from '../bin/setup.js';
+import { preflightAgent } from './preflight.js';
 
 const log = (line) => process.stderr.write(`[hi-loop-mcp] ${line}\n`);
 
@@ -39,9 +40,16 @@ export const tools = {
       ship,
       watch,
       stopAfter,
+      spec,
+      reconcile,
+      reconcileSpec,
       cwd = defaultCwd(),
     }) => {
       if (!goal) return fail('goal 은 필수입니다.');
+      // 루프를 돌리기 전에 에이전트가 실행 가능한지 확인한다 — 미설치/실행불가면
+      // 회차를 태우지 않고 여기서 행동지침을 돌려준다(호스트 LLM 이 사용자에게 전달).
+      const pre = await preflightAgent();
+      if (!pre.ok) return fail(pre.message);
       const result = await runLoop({
         goal,
         testCommand,
@@ -51,6 +59,9 @@ export const tools = {
         shipCommand: ship || null,
         watchCommand: watch || null,
         stopAfter: stopAfter ? String(stopAfter).toUpperCase() : null,
+        specPath: spec || null,
+        reconcile: reconcile === undefined ? null : Boolean(reconcile),
+        reconcileSpec: reconcileSpec || null,
         cwd,
         logger: log,
       });
@@ -136,6 +147,8 @@ export function wrap(handler) {
     try {
       return await handler(args ?? {});
     } catch (err) {
+      // 환경 오류(에이전트 미설치·인증 만료 등)는 이미 행동지침 메시지다 — 그대로 전달한다.
+      if (err?.kind === 'environment') return fail(err.message);
       return fail(`hi-loop 오류: ${err?.message ?? String(err)}`);
     }
   };
@@ -179,6 +192,18 @@ export async function startMcpServer({ version = '0.1.0' } = {}) {
           .enum(['DISCOVER', 'PLAN', 'BUILD', 'CODE_REVIEW', 'SHIP', 'WATCH'])
           .optional()
           .describe('이 단계까지만 진행하고 멈춘다'),
+        spec: z
+          .string()
+          .optional()
+          .describe('스펙 오라클을 이 파일로 고정한다(예: docs/spec.md). 사람이 관리하는 표준 문서를 여러 요청이 공유하는 오라클로 삼아 문서↔소스 drift 를 막는다. 이미 내용이 있으면 PLAN 이 덮어쓰지 않는다.'),
+        reconcile: z
+          .boolean()
+          .optional()
+          .describe('문서 정합 게이트. 기존 표준 문서와 이 요청이 모순되면 조용히 포크하지 않고 사람에게 묻는다(고정/분기/중단). full=true 또는 reconcileSpec 지정 시 자동 켜짐.'),
+        reconcileSpec: z
+          .string()
+          .optional()
+          .describe('정합 게이트가 대조할 표준 문서 경로(기본 docs/spec.md). 예: docs/design.md. 지정하면 게이트가 켜진다.'),
         cwd: cwdSchema,
       },
     },

package/src/preflight.js

@@ -0,0 +1,119 @@
+/**
+ * 에이전트 실행 환경 사전 점검(preflight) 및 실패 진단 — CLI/MCP 공용.
+ *
+ * 목적: "claude 가 없다 / 인증이 끊겼다 / 키가 없다"를 루프 한복판의 스택트레이스가 아니라
+ * **실행 전(또는 첫 실패 시) 한 줄의 행동지침**으로 바꾼다. 이 엔진의 전제는 "에이전트가
+ * 코드를 고친다"이므로, 에이전트를 못 부르는 것은 버그가 아니라 환경 문제다 — 그렇게 보여줘야 한다.
+ *
+ * 두 갈래로 나눠 본다(하나로 못 합치는 이유가 있다):
+ *  - 설치/PATH/권한 문제(ENOENT·EACCES)는 API 를 때리지 않고 `--version` 으로 **공짜로** 잡힌다.
+ *    그래서 루프 시작 전에 미리(preflight) 확인한다.
+ *  - 인증/구독/키 문제는 실제 호출 전에는 알 수 없다(`--version` 은 인증을 요구하지 않는다).
+ *    비용을 들여 사전 점검하지 않는다 — 대신 첫 호출의 stderr 를 패턴으로 읽어 힌트로 번역한다.
+ */
+import { spawn } from 'node:child_process';
+
+/**
+ * 환경/설정 오류임을 표시하는 에러. `kind==='environment'` 를 보고 CLI 최상위 핸들러는
+ * 스택트레이스 대신 메시지 한 줄만 내고, MCP 래퍼는 "hi-loop 오류:" 접두 없이 그대로 전달한다.
+ */
+export class AgentEnvError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'AgentEnvError';
+    this.kind = 'environment';
+  }
+}
+
+/** spawn 자체가 실패한 원인(ENOENT 등)을 행동지침으로 번역한다. */
+export function describeSpawnError(err, command) {
+  if (err?.code === 'ENOENT') {
+    return (
+      `에이전트 명령 '${command}' 를 찾을 수 없습니다.\n` +
+      `  - Claude Code CLI 설치를 확인하세요: npm i -g @anthropic-ai/claude-code\n` +
+      `  - 다른 에이전트/경로를 쓰려면 HILOOP_AGENT_CMD 로 지정하세요 (예: HILOOP_AGENT_CMD=/usr/local/bin/claude)`
+    );
+  }
+  if (err?.code === 'EACCES') {
+    return `에이전트 명령 '${command}' 를 실행할 권한이 없습니다 (EACCES). 실행 권한을 확인하세요: chmod +x "$(command -v ${command})"`;
+  }
+  return `에이전트 실행 실패(${command}): ${err?.message ?? String(err)}`;
+}
+
+/**
+ * 비정상 종료 stderr 에서 인증/구독/키 문제의 신호를 찾아 힌트를 만든다.
+ * 못 찾으면 null — 그때는 원문을 그대로 보여준다(우리가 모르는 실패를 인증 문제로 감추지 않는다).
+ * 순서가 곧 우선순위다: 구체적인 신호(키·결제)를 일반적인 신호(로그인)보다 먼저 맞춘다.
+ */
+const AUTH_PATTERNS = [
+  [/invalid api key|authentication_error|x-api-key|unauthorized|\b401\b/i, 'API 키가 없거나 유효하지 않습니다.'],
+  [/credit balance|insufficient|quota|billing|payment required|402/i, '크레딧/결제 한도 문제로 보입니다.'],
+  [/subscription|expired|plan (?:limit|expired)|entitlement/i, '구독/플랜이 만료됐거나 유효하지 않을 수 있습니다.'],
+  [/\/login|please log ?in|not logged in|run .*login|re-?authenticate|sign in/i, '로그인이 필요합니다.'],
+  [/api key|anthropic_api_key/i, 'API 키 설정을 확인하세요.'],
+];
+
+export function detectAuthFailure(stderr) {
+  const text = typeof stderr === 'string' ? stderr : '';
+  for (const [re, hint] of AUTH_PATTERNS) {
+    if (re.test(text)) {
+      return `${hint} 에이전트 인증 상태를 확인하세요 — 예: 'claude' 로 로그인하거나 ANTHROPIC_API_KEY 를 설정하세요.`;
+    }
+  }
+  return null;
+}
+
+/**
+ * 에이전트 바이너리가 실제로 실행 가능한지 `--version` 으로 확인한다(설치/PATH/권한).
+ * 인증을 요구하지 않으므로 비용 0. 인증은 여기서 검증하지 않는다.
+ * runner 를 주입할 수 있어 테스트에서 실제 spawn 없이 검증한다.
+ *
+ * 반환: `{ ok: true, code }` | `{ ok: false, err }` (spawn 실패) | `{ ok: false, code }` (비정상 종료)
+ */
+export function makeVersionProbe({ timeoutMs = 15000 } = {}) {
+  return (command) =>
+    new Promise((resolve) => {
+      let child;
+      try {
+        child = spawn(command, ['--version'], { env: process.env });
+      } catch (err) {
+        resolve({ ok: false, err });
+        return;
+      }
+      const timer = setTimeout(() => {
+        child.kill('SIGKILL');
+        resolve({ ok: false, err: new Error(`'${command} --version' 이 ${timeoutMs}ms 안에 응답하지 않았습니다.`) });
+      }, timeoutMs);
+      child.on('error', (err) => {
+        clearTimeout(timer);
+        resolve({ ok: false, err });
+      });
+      child.on('close', (code) => {
+        clearTimeout(timer);
+        resolve({ ok: code === 0, code });
+      });
+    });
+}
+
+/**
+ * 루프 시작 전 에이전트 실행 가능성을 확인한다.
+ *
+ * **오탐 방지 원칙**: 진짜로 못 부르는 경우(spawn 실패=ENOENT·EACCES)에만 막는다.
+ * 바이너리가 실행은 됐는데 `--version` 이 0 이 아니면, 커스텀 에이전트가 `--version` 을
+ * 지원 안 하는 것일 수 있으므로 **막지 않는다** — 존재는 이미 증명됐다. 멀쩡한 셋업을
+ * preflight 가 죽이는 것이 못 잡는 것보다 나쁘다.
+ *
+ * 반환: `{ ok: true, warning? }` | `{ ok: false, message }`
+ */
+export async function preflightAgent({
+  command = process.env.HILOOP_AGENT_CMD || 'claude',
+  probe = makeVersionProbe(),
+} = {}) {
+  const res = await probe(command);
+  if (res.ok) return { ok: true };
+  if (res.err) return { ok: false, message: describeSpawnError(res.err, command) };
+  return {
+    ok: true,
+    warning: `'${command} --version' 이 code ${res.code} 로 끝났지만 명령은 존재하므로 진행합니다.`,
+  };
+}

package/src/prompts.js

@@ -42,19 +42,26 @@ export function contextBlock(state) {
   return parts.join('\n\n');
 }
 
-/** PLAN: 코드보다 spec.md + 테스트 먼저 (FR-2.1) */
+/** PLAN: 코드보다 spec.md + 테스트 먼저 (FR-2.1). --spec 고정 시 표준 문서를 오라클로 삼는다(FR-17). */
 export function planPrompt(state) {
+  // 고정된 스펙(--spec)은 사람이 관리하는 표준 문서일 수 있다 — PLAN 이 덮어쓰면 오라클이 오염된다.
+  // 그래서 "이미 내용이 있으면 수정하지 말고 그대로 오라클로 삼으라"고 지시한다. 비었을 때만 작성한다.
+  const specStep = state.specPinned
+    ? `1. \`${specPathOf(state)}\` 는 사용자가 **고정한 표준 스펙 문서(오라클)**다.
+   - 이미 내용이 있으면 **절대 수정하지 마라.** 그대로 진실로 받아들이고, 이 스펙에 맞춰 아래 테스트만 작성하라.
+   - 비어 있거나 없을 때만 이 경로에 스펙을 작성하라.`
+    : `1. \`${specPathOf(state)}\` 를 작성하라: 목표 해석, 상세 요구사항, 공개 API 시그니처, 수용 기준 목록.`;
   return `당신은 TDD를 강제하는 수석 아키텍트다. 지금은 PLAN 단계다.
 
 ${contextBlock(state)}
 
 ## PLAN 단계에서 할 일 (이것만)
-1. \`${specPathOf(state)}\` 를 작성하라: 목표 해석, 상세 요구사항, 공개 API 시그니처, 수용 기준 목록.
+${specStep}
 2. \`${testPathOf(state)}\` 를 작성하라: 위 수용 기준을 검증하는 실행 가능한 테스트.
    - Node 내장 \`node:test\` + \`node:assert/strict\` 를 사용하라.
    - 아직 존재하지 않는 구현을 import 해도 된다(이 단계에서 테스트는 실패하는 게 정상이다).
 3. **구현 코드는 절대 작성하지 마라.** 이번 단계 산출물은 spec과 테스트뿐이다.
-4. 위 두 경로에만 써라. 다른 기존 파일은 건드리지 마라.
+4. 위 경로에만 써라. 다른 기존 파일은 건드리지 마라.
 
 작업을 마치면 스펙 핵심을 15줄 이내로 요약해 마지막에 출력하라.
 

package/src/reconcile.js

@@ -0,0 +1,101 @@
+/**
+ * 문서 정합 게이트 (FR-21) — 새 요청이 기존 표준 문서와 모순되는가.
+ *
+ * 기본 동작은 goal 마다 스펙을 새로 포크한다(state.planPathsFor). 그래서 단말적 요청이
+ * 기존 `docs/spec.md` 와 어긋나도 조용히 갈라져 나갈 뿐, 아무도 그 모순을 보지 못한다 —
+ * 문서↔소스 갭의 근원이고, 그 갭이 환각의 빌미가 된다.
+ *
+ * 판정이 아니라 **표면화**다. 모순이면 상호배타 분기(ask, FR-16)로 멈춰 사람이 고른다:
+ * 기존 문서를 오라클로 고정(FR-19) / 새 스펙으로 분기 / 중단. `--verify-spec` 처럼 별도
+ * 세션·plan 모드(쓰기 금지)로 부르므로 구현자의 추론에 오염되지 않는다. opt-in(비용 증가).
+ */
+import { spawn } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { buildAgentArgs, parseAgentOutput } from './runners.js';
+
+const truncate = (s, n) => (String(s ?? '').length > n ? `${String(s).slice(0, n)}…` : String(s ?? ''));
+
+export function reconcilePrompt({ goal, specText }) {
+  return `당신은 새 요청과 기존 표준 스펙 문서의 **정합성**만 판정하는 독립 심판자다. 코드를 고치지 마라 — 판정만 한다.
+
+## 기존 표준 스펙 문서
+${truncate(specText, 6000)}
+
+## 새 요청(goal)
+${truncate(goal, 2000)}
+
+## 판정
+- 이 요청이 위 문서와 **모순**되는가? 문서가 정한 동작·제약·범위를 뒤집거나 어기면 모순이다.
+- 문서에 없는 것을 **추가**하는 것은 모순이 아니다(확장은 정상). 확신이 없으면 ok 로 판정하라.
+
+JSON 한 줄로만 답하라:
+{"verdict": "ok" 또는 "conflict", "reason": "무엇이 어긋나는가(한국어 1~2문장)"}`;
+}
+
+/** 판정을 관대하게 파싱한다. 형식이 깨지면 ok 로 흘린다(애매한 것까지 막으면 정상 작업이 멈춘다). */
+export function parseReconcile(text) {
+  try {
+    const m = String(text).match(/\{[\s\S]*"verdict"[\s\S]*\}/);
+    const obj = JSON.parse(m ? m[0] : text);
+    return {
+      verdict: obj.verdict === 'conflict' ? 'conflict' : 'ok',
+      reason: typeof obj.reason === 'string' ? obj.reason : '',
+    };
+  } catch {
+    return { verdict: 'ok', reason: '정합 판정을 파싱하지 못해 통과로 처리' };
+  }
+}
+
+/** gate() 에 넘길 ask 스펙 — 상호배타 3지선다(고정 / 분기 / 중단). */
+export function reconcileAsk({ standingSpec, reason }) {
+  return {
+    stage: 'RECONCILE',
+    question: `기존 표준 문서(${standingSpec})와 이 요청이 어긋납니다:\n${reason}\n어떻게 진행할까요?`,
+    options: [
+      { key: 'a', label: `${standingSpec} 를 오라클로 고정하고 진행`, impact: '요청을 문서에 맞춘다' },
+      { key: 'b', label: '새 스펙으로 분기해 진행', impact: '요청이 문서를 갱신/대체한다' },
+      { key: 'c', label: '중단 — 문서를 먼저 정리하겠다', impact: '아무것도 실행하지 않는다' },
+    ],
+  };
+}
+
+/**
+ * 주입 가능한 정합 판정 포트 (NFR-3). `({ goal, specPath, cwd }) => { verdict, reason }`.
+ * 별도 claude 를 plan 모드·새 세션으로 spawn 한다. 검증 계열과 같은 env 폴백 사슬을 쓴다.
+ */
+export function makeReconciler({
+  command = process.env.HILOOP_RECONCILE_CMD || process.env.HILOOP_VERIFY_CMD || process.env.HILOOP_AGENT_CMD || 'claude',
+  model = process.env.HILOOP_RECONCILE_MODEL || process.env.HILOOP_VERIFY_MODEL || '',
+  timeoutMs = 5 * 60 * 1000,
+} = {}) {
+  return ({ goal, specPath, cwd }) =>
+    new Promise((resolve) => {
+      const full = specPath ? join(cwd, specPath) : null;
+      if (!full || !existsSync(full)) {
+        resolve({ verdict: 'ok', reason: '표준 문서가 없어 정합 검사 생략' });
+        return;
+      }
+      const prompt = reconcilePrompt({ goal, specText: readFileSync(full, 'utf8') });
+      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 = '';
+      const timer = setTimeout(() => child.kill('SIGKILL'), timeoutMs);
+      child.stdout.on('data', (d) => (stdout += d));
+      child.stderr.on('data', () => {});
+      child.on('error', () => {
+        clearTimeout(timer);
+        // 판정기 실행 실패가 정상 작업을 막으면 안 된다(인프라 fail-open).
+        resolve({ verdict: 'ok', reason: '정합 판정기 실행 실패 — 통과로 처리' });
+      });
+      child.on('close', (code) => {
+        clearTimeout(timer);
+        if (code !== 0) {
+          resolve({ verdict: 'ok', reason: `정합 판정기가 코드 ${code}로 종료 — 통과로 처리` });
+          return;
+        }
+        resolve(parseReconcile(parseAgentOutput(stdout).text));
+      });
+    });
+}

package/src/resume.js

@@ -34,7 +34,7 @@ function carryOver(prev) {
   };
 }
 
-export function resumeOrCreate({ statePath, goal, testCommand, maxLoops, cwd }) {
+export function resumeOrCreate({ statePath, goal, testCommand, maxLoops, cwd, specPath: pinnedSpecPath = null }) {
   const raw = existsSync(statePath) ? loadState(statePath) : null;
   // L16: 디스크의 상태는 신뢰 경계 밖이다. 봉인이 깨졌으면 게이트를 여는 필드만
   // 안전값으로 되돌린다 — goal·회차·비용 같은 나머지는 판정을 열지 않으므로 그대로 둔다.
@@ -44,16 +44,19 @@ export function resumeOrCreate({ statePath, goal, testCommand, maxLoops, cwd })
     prev.sealBroken = true;
   }
   if (prev && prev.goal === goal && prev.status === 'passed') {
-    return { ...createState({ goal, testCommand, maxLoops, cwd }), ...carryOver(prev) };
+    return { ...createState({ goal, testCommand, maxLoops, cwd, specPath: pinnedSpecPath }), ...carryOver(prev) };
   }
   if (prev && prev.goal === goal && prev.status !== 'passed') {
     // 필드가 없던 시절의 상태 파일도 이어받는다. 경로는 절대 다시 계산하지 않는다 —
     // PLAN 이 이미 만든 파일 때문에 경로가 밀려나기 때문이다.
-    const paths = prev.specPath && prev.testPath ? {} : planPathsFor({ cwd, goal });
+    const paths = prev.specPath && prev.testPath ? {} : planPathsFor({ cwd, goal, specPath: pinnedSpecPath });
     return {
       ...paths,
       ...prev,
-      specPath: prev.specPath ?? paths.specPath,
+      // 명시 고정(--spec)은 저장된 경로보다 우선한다 — 사용자가 이번에 오라클을 바꾼 것이다.
+      specPath: pinnedSpecPath ?? prev.specPath ?? paths.specPath,
+      specPinned: pinnedSpecPath ? true : Boolean(prev.specPinned),
+      reconciled: Boolean(prev.reconciled),
       testPath: prev.testPath ?? paths.testPath,
       costUsd: Number.isFinite(prev.costUsd) ? prev.costUsd : 0,
       // 기준선이 없던 시절의 상태로 재개하면 이번 회차 지문이 곧 기준선이 된다.
@@ -89,5 +92,5 @@ export function resumeOrCreate({ statePath, goal, testCommand, maxLoops, cwd })
       status: prev.ask ? 'awaiting' : 'running',
     };
   }
-  return createState({ goal, testCommand, maxLoops, cwd });
+  return createState({ goal, testCommand, maxLoops, cwd, specPath: pinnedSpecPath });
 }

package/src/runners.js

@@ -3,6 +3,7 @@
  * 루프 엔진은 이 함수들을 주입받으므로, 테스트에서는 스텁으로 대체된다.
  */
 import { spawn } from 'node:child_process';
+import { AgentEnvError, describeSpawnError, detectAuthFailure } from './preflight.js';
 
 /**
  * 양의 정수 환경변수를 읽되, 없거나 쓰레기값이면 기본값으로 조용히 되돌린다.
@@ -94,12 +95,17 @@ export function makeAgentRunner({
       });
       child.on('error', (err) => {
         clearTimeout(timer);
-        reject(new Error(`에이전트 실행 실패(${command}): ${err.message}`));
+        // spawn 실패(미설치·권한)는 환경 오류다 — 스택 대신 행동지침으로 표시한다.
+        reject(new AgentEnvError(describeSpawnError(err, command)));
       });
       child.on('close', (code) => {
         clearTimeout(timer);
         if (code !== 0) {
-          reject(new Error(`에이전트가 코드 ${code}로 종료했습니다.\n${stderr.slice(-2000)}`));
+          // 비정상 종료의 stderr 에서 인증/구독/키 신호를 찾으면 힌트를 앞에 붙이고
+          // 환경 오류로 분류한다. 못 찾으면 우리가 모르는 실패이므로 원문 tail 을 그대로 던진다.
+          const hint = detectAuthFailure(stderr);
+          const tail = `에이전트가 코드 ${code}로 종료했습니다.\n${stderr.slice(-2000)}`;
+          reject(hint ? new AgentEnvError(`${hint}\n\n${tail}`) : new Error(tail));
           return;
         }
         resolve(parseAgentOutput(stdout, sessionId));