@tuzi-ince/hi-loop 0.1.1

package/src/lock.js

@@ -0,0 +1,83 @@
+/**
+ * 동시 실행 락 (L4) — 같은 cwd 에서 두 루프가 상태를 덮어쓰는 것을 막는다.
+ *
+ * `.agent-state.json` 은 단일 루프를 가정한다(락 없음). 같은 디렉터리에서 두 번째
+ * `hi-loop run` 이 뜨면 두 프로세스가 같은 파일을 번갈아 저장해 resume 이 깨진다.
+ * 그래서 락 파일 하나로 배타를 강제한다.
+ *
+ * 설계:
+ * - 락은 `wx`(exclusive create)로 만든다 — 이미 있으면 실패한다. 이게 원자성이다.
+ * - 락 안에 pid 를 적어둔다. 죽은 프로세스의 락은 stale 로 보고 뺏는다(크래시/SIGKILL
+ *   후 남은 락 때문에 영영 못 도는 것이 더 나쁘다).
+ * - 락 해제는 finally 에서. 하지만 SIGKILL 은 finally 를 안 태우므로 stale 회수가
+ *   최종 안전망이다.
+ */
+import { writeFileSync, readFileSync, rmSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+export const LOCK_FILENAME = '.agent-state.lock';
+
+export function lockPathFor(cwd) {
+  return join(cwd, LOCK_FILENAME);
+}
+
+/** pid 가 살아 있는가. 신호 0 은 프로세스를 안 건드리고 존재만 확인한다. */
+function isAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    // EPERM = 남의 프로세스지만 살아 있음. ESRCH = 없음.
+    return err.code === 'EPERM';
+  }
+}
+
+/**
+ * 락을 잡는다. 성공하면 해제 함수를 반환하고, 실패하면 던진다.
+ * 호출자는 반환된 함수를 finally 에서 부른다.
+ */
+export function acquireLock(cwd, { pid = process.pid, now = () => new Date().toISOString() } = {}) {
+  const path = lockPathFor(cwd);
+  const payload = `${JSON.stringify({ pid, at: now() })}\n`;
+
+  const tryCreate = () => {
+    writeFileSync(path, payload, { flag: 'wx' }); // wx: 이미 있으면 EEXIST
+  };
+
+  try {
+    tryCreate();
+  } catch (err) {
+    if (err.code !== 'EEXIST') throw err;
+
+    // 락이 이미 있다. 주인이 살아 있으면 양보하고, 죽었으면 뺏는다.
+    const holder = readHolder(path);
+    if (holder && isAlive(holder.pid) && holder.pid !== pid) {
+      throw new Error(
+        `다른 hi-loop 루프가 이미 이 디렉터리에서 실행 중입니다 (pid ${holder.pid}). ` +
+          `끝나길 기다리거나, 그 프로세스가 죽었다면 ${LOCK_FILENAME} 을 지우세요.`,
+      );
+    }
+    // stale 이거나 우리 자신의 락 — 뺏어서 다시 만든다.
+    rmSync(path, { force: true });
+    tryCreate();
+  }
+
+  let released = false;
+  return function release() {
+    if (released) return;
+    released = true;
+    // 우리 락일 때만 지운다. 뺏긴 뒤 남의 락을 지우면 안 된다.
+    const holder = readHolder(path);
+    if (holder && holder.pid === pid) rmSync(path, { force: true });
+  };
+}
+
+function readHolder(path) {
+  if (!existsSync(path)) return null;
+  try {
+    return JSON.parse(readFileSync(path, 'utf8'));
+  } catch {
+    return null; // 손상된 락은 stale 로 본다.
+  }
+}

package/src/loop.js

@@ -0,0 +1,296 @@
+/**
+ * 자가 치유 핵심 오케스트레이션 루프 (FR-2, FR-3)
+ *
+ * PLAN -> DO -> CHECK -> ACT(HEAL) -> CHECK -> ...
+ * CHECK 는 엔진이 직접 testCommand 를 돌려 판정한다. 에이전트의 자기보고는 믿지 않는다.
+ */
+import {
+  saveState,
+  statePathFor,
+  resumeOrCreate,
+  truncate,
+  errorSignature,
+  reportGaps,
+  LIMITS,
+} from './state.js';
+import { promptFor } from './prompts.js';
+import { makeAgentRunner, makeTestRunner } from './runners.js';
+import { makeIntegrityChecker, compareFingerprints, violationMessage } from './integrity.js';
+import { acquireLock } from './lock.js';
+import { makeCheckpointer, makeFileLister, detectDeletions } from './checkpoint.js';
+import { makeSpecVerifier } from './verify.js';
+import { makeNotifier } from './telegram.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);
+}
+
+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;
+}
+
+/**
+ * 얇은 락 래퍼 (L4). 같은 cwd 에서 두 루프가 상태를 덮어쓰지 못하게 배타를 강제한다.
+ * body 는 return 지점이 여럿이라 여기서 한 번 감싸 finally 로 확실히 푼다.
+ * acquireLock 은 테스트를 위해 주입 가능하다.
+ */
+export async function runLoop(opts = {}) {
+  const cwd = opts.cwd ?? process.cwd();
+  const acquire = opts.acquireLock ?? acquireLock;
+  const release = acquire(cwd); // 실패(다른 루프 실행 중)면 여기서 던진다 — release 없음.
+  try {
+    return await runLoopBody(opts);
+  } finally {
+    release();
+  }
+}
+
+async function runLoopBody({
+  goal,
+  testCommand = 'npm test',
+  cwd = process.cwd(),
+  maxLoops = 10,
+  budgetUsd = null,
+  stagnationLimit = 3,
+  verifySpec = false,
+  handoffEvery = 4,
+  agentRunner = makeAgentRunner(),
+  testRunner = makeTestRunner(),
+  integrityChecker = makeIntegrityChecker(),
+  checkpointer = makeCheckpointer(),
+  fileLister = makeFileLister(),
+  specVerifier = makeSpecVerifier(),
+  notifier = makeNotifier(),
+  logger = (line) => process.stderr.write(`${line}\n`),
+  statePath = statePathFor(cwd),
+} = {}) {
+  if (!goal || typeof goal !== 'string' || !goal.trim()) {
+    throw new TypeError('goal 은 비어 있지 않은 문자열이어야 합니다.');
+  }
+  if (!Number.isInteger(maxLoops) || maxLoops < 1) {
+    throw new TypeError('maxLoops 는 1 이상의 정수여야 합니다.');
+  }
+  if (budgetUsd != null && !(Number.isFinite(budgetUsd) && budgetUsd > 0)) {
+    throw new TypeError('budgetUsd 는 0 보다 큰 숫자여야 합니다.');
+  }
+
+  const state = resumeOrCreate({ statePath, goal, testCommand, maxLoops, cwd });
+  saveState(statePath, state);
+
+  const notify = async (event) => {
+    try {
+      await notifier({ goal, maxLoops, ...event });
+    } catch {
+      /* 알림 실패는 루프에 영향 없음 (FR-5.3) */
+    }
+  };
+
+  await notify({ type: 'start', iteration: state.iteration, detail: `testCommand: ${testCommand}` });
+
+  // L8 baseline: 루프 시작 시점의 추적 파일 목록. 이 뒤로 사라진 파일 = 에이전트가 삭제.
+  // 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';
+
+    // 체크포인트: 에이전트가 손대기 **전** 상태를 스냅샷. 이 호출이 망친 것을 되돌릴 수 있게.
+    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;
+    }
+
+    // ---- 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.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 };
+    }
+
+    // ---- 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) {
+      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

@@ -0,0 +1,159 @@
+/**
+ * MCP 프로토콜 표준 규격 통신 모듈 (FR-4)
+ *
+ * ⚠️ stdout 은 MCP 프로토콜 채널이다. 로그는 반드시 stderr 로만 낸다 (FR-4.2).
+ */
+import { runLoop } from './loop.js';
+import { loadState, statePathFor, summarizeState, resetState } from './state.js';
+import { rollbackTo } from './checkpoint.js';
+import { runSetup } from '../bin/setup.js';
+
+const log = (line) => process.stderr.write(`[hi-loop-mcp] ${line}\n`);
+
+const text = (t) => ({ content: [{ type: 'text', text: t }] });
+const fail = (t) => ({ content: [{ type: 'text', text: t }], isError: true });
+
+/** 도구 구현 (SDK 없이도 단위 테스트 가능하도록 분리) */
+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() }) => {
+      if (!goal) return fail('goal 은 필수입니다.');
+      const result = await runLoop({ goal, testCommand, maxLoops, verifySpec, cwd, logger: log });
+      const head = result.status === 'passed' ? '✅ 통과' : '❌ 실패';
+      // 통과 시 Gaps 를 붙인다 — 에이전트가 도구로 이 결과를 받을 때 false green 을
+      // 사실로 착각하지 않도록. summarizeState 는 상태 요약, report 는 검증 한계.
+      const gaps = result.report ? `\n\n${result.report}` : '';
+      return text(
+        `${head} — ${result.iterations}회 반복\n\n${summarizeState(result.state)}${gaps}`,
+      );
+    },
+  },
+  hiloop_status: {
+    description: '현재 워크스페이스의 .agent-state.json 루프 상태 요약을 반환한다.',
+    handler: async ({ cwd = process.cwd() } = {}) => text(summarizeState(loadState(statePathFor(cwd)))),
+  },
+  hiloop_reset: {
+    description: '.agent-state.json 을 삭제해 루프 상태를 초기화한다.',
+    handler: async ({ cwd = process.cwd() } = {}) =>
+      text(resetState(statePathFor(cwd)) ? '상태를 초기화했습니다.' : '초기화할 상태가 없습니다.'),
+  },
+  hiloop_rollback: {
+    description:
+      'git 체크포인트로 파일을 되돌린다. to(회차)를 주면 그 회차 직전 스냅샷으로, 없으면 가장 최근 체크포인트로 복원한다.',
+    handler: async ({ to, cwd = process.cwd() } = {}) => {
+      const state = loadState(statePathFor(cwd));
+      const checkpoints = state?.checkpoints ?? [];
+      if (checkpoints.length === 0)
+        return fail('되돌릴 체크포인트가 없습니다 (git 저장소가 아니거나 아직 스냅샷이 없음).');
+      const toIter = Number.isInteger(to) ? to : null;
+      const cp =
+        toIter != null
+          ? checkpoints.find((c) => c.iteration === toIter)
+          : checkpoints[checkpoints.length - 1];
+      if (!cp)
+        return fail(
+          `${toIter}회차 체크포인트가 없습니다. 있는 회차: ${checkpoints.map((c) => c.iteration).join(', ')}`,
+        );
+      const res = await rollbackTo({ cwd, sha: cp.sha });
+      if (!res.ok) return fail(`롤백 실패: ${res.reason}`);
+      const safety = res.safetySha ? `\n되돌리기 전 상태는 ${res.safetySha.slice(0, 8)} 에 스냅샷됨.` : '';
+      return text(`✅ ${cp.iteration}회차 직전 상태로 파일을 복원했습니다 (${cp.sha.slice(0, 8)}).${safety}`);
+    },
+  },
+  hiloop_setup: {
+    description:
+      '프로젝트에 hi-loop 설정(.mcp.json MCP 서버 등록, .gitignore 항목, docs/tests 디렉터리)을 자동 주입한다. dryRun 이면 변경 없이 계획만 보여준다.',
+    handler: async ({ dryRun = false, cwd = process.cwd() } = {}) => {
+      const report = runSetup({ cwd, dryRun: Boolean(dryRun) });
+      return text(report.lines.join('\n'));
+    },
+  },
+};
+
+/** 예외를 isError 응답으로 감싼다 (FR-4.4) */
+export function wrap(handler) {
+  return async (args) => {
+    try {
+      return await handler(args ?? {});
+    } catch (err) {
+      return fail(`hi-loop 오류: ${err?.message ?? String(err)}`);
+    }
+  };
+}
+
+export async function startMcpServer({ version = '0.1.0' } = {}) {
+  let McpServer;
+  let StdioServerTransport;
+  let z;
+  try {
+    ({ McpServer } = await import('@modelcontextprotocol/sdk/server/mcp.js'));
+    ({ StdioServerTransport } = await import('@modelcontextprotocol/sdk/server/stdio.js'));
+    ({ z } = await import('zod'));
+  } catch (err) {
+    // FR-4.5: SDK 없이도 CLI 모드는 살아 있어야 하므로 여기서만 죽는다.
+    process.stderr.write(
+      `MCP 모드에는 @modelcontextprotocol/sdk 가 필요합니다. \`npm install\` 후 다시 시도하세요.\n${err?.message}\n`,
+    );
+    process.exit(1);
+  }
+
+  const server = new McpServer({ name: 'hi-loop', version });
+  const cwdSchema = z.string().optional().describe('작업 디렉터리 (기본: 서버 프로세스의 cwd)');
+
+  server.registerTool(
+    'hiloop_run',
+    {
+      description: tools.hiloop_run.description,
+      inputSchema: {
+        goal: z.string().describe('달성할 요구사항'),
+        testCommand: z.string().optional().describe('검증 명령 (기본 "npm test")'),
+        maxLoops: z.number().int().min(1).max(50).optional().describe('최대 루프 횟수 (기본 10)'),
+        verifySpec: z.boolean().optional().describe('통과 시 별도 검증자로 스펙 대비 구현을 심판 (하향 전용, 비용 증가)'),
+        cwd: cwdSchema,
+      },
+    },
+    wrap(tools.hiloop_run.handler),
+  );
+
+  server.registerTool(
+    'hiloop_status',
+    { description: tools.hiloop_status.description, inputSchema: { cwd: cwdSchema } },
+    wrap(tools.hiloop_status.handler),
+  );
+
+  server.registerTool(
+    'hiloop_reset',
+    { description: tools.hiloop_reset.description, inputSchema: { cwd: cwdSchema } },
+    wrap(tools.hiloop_reset.handler),
+  );
+
+  server.registerTool(
+    'hiloop_rollback',
+    {
+      description: tools.hiloop_rollback.description,
+      inputSchema: {
+        to: z.number().int().min(1).optional().describe('되돌릴 회차 (미지정 시 가장 최근 체크포인트)'),
+        cwd: cwdSchema,
+      },
+    },
+    wrap(tools.hiloop_rollback.handler),
+  );
+
+  server.registerTool(
+    'hiloop_setup',
+    {
+      description: tools.hiloop_setup.description,
+      inputSchema: {
+        dryRun: z.boolean().optional().describe('변경 없이 계획만 출력'),
+        cwd: cwdSchema,
+      },
+    },
+    wrap(tools.hiloop_setup.handler),
+  );
+
+  await server.connect(new StdioServerTransport());
+  log('stdio 전송으로 MCP 서버가 기동했습니다.');
+  return server;
+}

package/src/prompts.js

@@ -0,0 +1,125 @@
+/**
+ * PDCA 각 단계의 프롬프트 빌더 (FR-2.1 ~ FR-2.4, FR-3.3)
+ * 전체 대화 로그는 절대 넣지 않는다. 압축본만 넣는다.
+ */
+import { truncate, LIMITS, DEFAULT_SPEC_PATH, DEFAULT_TEST_PATH } from './state.js';
+
+const RULES = `## 불변 규칙
+- 작업 디렉터리 바깥을 건드리지 마라.
+- 지정된 산출물 경로 외의 기존 파일을 덮어쓰거나 지우지 마라.
+- 테스트를 통과시키려고 테스트 자체를 무력화(skip/삭제/always-true)하지 마라.
+- 완료 보고 대신 실제 파일을 남겨라. 검증은 엔진이 직접 한다.`;
+
+/** 경로는 엔진이 정한다(state.planPathsFor). 프롬프트는 받아 쓰기만 한다. */
+const specPathOf = (state) => state.specPath || DEFAULT_SPEC_PATH;
+const testPathOf = (state) => state.testPath || DEFAULT_TEST_PATH;
+
+/** 핸드오프 이후 새 세션에 넘길 압축 컨텍스트 (FR-3.3) */
+export function contextBlock(state) {
+  const parts = [`## 목표(goal)\n${state.goal}`];
+  if (state.specSummary) {
+    parts.push(`## 지금까지의 스펙 요약\n${truncate(state.specSummary, LIMITS.specSummary)}`);
+  }
+  if (state.history?.length) {
+    const recent = state.history
+      .slice(-LIMITS.historyKeep)
+      .map((h) => `- #${h.iteration} ${h.phase}: ${h.ok ? 'PASS' : 'FAIL'} — ${truncate(h.summary ?? '', 160)}`)
+      .join('\n');
+    parts.push(`## 최근 이력\n${recent}`);
+  }
+  if (state.lastError) {
+    parts.push(`## 마지막 빌드/테스트 에러\n\`\`\`\n${truncate(state.lastError, LIMITS.lastError)}\n\`\`\``);
+  }
+  parts.push(`## 현재 위치\niteration ${state.iteration}/${state.maxLoops}, session #${state.sessionSerial}`);
+  return parts.join('\n\n');
+}
+
+/** PLAN: 코드보다 spec.md + 테스트 먼저 (FR-2.1) */
+export function planPrompt(state) {
+  return `당신은 TDD를 강제하는 수석 아키텍트다. 지금은 PLAN 단계다.
+
+${contextBlock(state)}
+
+## PLAN 단계에서 할 일 (이것만)
+1. \`${specPathOf(state)}\` 를 작성하라: 목표 해석, 상세 요구사항, 공개 API 시그니처, 수용 기준 목록.
+2. \`${testPathOf(state)}\` 를 작성하라: 위 수용 기준을 검증하는 실행 가능한 테스트.
+   - Node 내장 \`node:test\` + \`node:assert/strict\` 를 사용하라.
+   - 아직 존재하지 않는 구현을 import 해도 된다(이 단계에서 테스트는 실패하는 게 정상이다).
+3. **구현 코드는 절대 작성하지 마라.** 이번 단계 산출물은 spec과 테스트뿐이다.
+4. 위 두 경로에만 써라. 다른 기존 파일은 건드리지 마라.
+
+작업을 마치면 스펙 핵심을 15줄 이내로 요약해 마지막에 출력하라.
+
+${RULES}`;
+}
+
+/** DO: 테스트를 통과시킬 최소 구현 (FR-2.2) */
+export function doPrompt(state) {
+  return `지금은 DO 단계다. 검증 명령: \`${state.testCommand}\`
+
+${contextBlock(state)}
+
+## DO 단계에서 할 일
+- \`${specPathOf(state)}\` 와 \`${testPathOf(state)}\` 를 만족시키는 **최소한의 실제 구현**을 작성하라.
+- 요구되지 않은 기능/추상화/최적화를 넣지 마라.
+- 테스트를 고치지 말고 구현으로 통과시켜라.
+
+${RULES}`;
+}
+
+/** ACT/HEAL: 에러 로그를 들이밀고 고치게 한다 (FR-2.4) */
+export function healPrompt(state) {
+  return `지금은 HEAL 단계다. \`${state.testCommand}\` 가 실패했다. 이 에러를 고쳐라.
+
+${contextBlock(state)}
+
+## HEAL 단계에서 할 일
+- 위 "마지막 빌드/테스트 에러"의 **근본 원인**을 짚고 구현을 수정하라.
+- 테스트를 삭제/skip/무력화해서 통과시키는 것은 실패로 간주한다.
+- 같은 수정을 반복하고 있다면 접근 자체를 바꿔라(이미 ${state.iteration - 1}회 시도했다).${
+  state.stagnantRuns >= 2
+    ? `\n- ⚠️ **같은 실패가 ${state.stagnantRuns}회 연속이다.** 지금 방식은 막혔다. 미봉책을 반복하지 말고,
+  이 실패가 애초에 **해결 불가능한 요구(모순된 테스트, 잘못된 환경)** 는 아닌지 먼저 판단하라.
+  그렇다면 왜 불가능한지 근거를 명확히 남겨라 — 규칙을 어겨 우회하지 마라.`
+    : ''
+}
+
+${RULES}`;
+}
+
+export function promptFor(state) {
+  if (state.phase === 'PLAN') return planPrompt(state);
+  if (state.phase === 'DO') return doPrompt(state);
+  return healPrompt(state);
+}
+
+/**
+ * Tier 2 검증자 프롬프트 (P6, L9). 스펙 대비 구현을 심판한다.
+ *
+ * 이 프롬프트를 받는 에이전트는 **쓰기 권한이 없고**(--permission-mode plan) **새 세션**이다
+ * (구현자 컨텍스트를 상속하지 않는다 — bkit 의 context:fork). 오직 기각만 할 수 있다.
+ *
+ * bkit 의 가중치 교훈: 구조 일치("파일이 있는가")는 덜 중요하고, **의도 일치**("코드 로직이
+ * 스펙이 요구한 동작을 실제로 달성하는가")가 핵심이다. 키워드 grep 이 아니라 로직을 읽어라.
+ */
+export function verifyPrompt({ specText, diffText }) {
+  return `당신은 스펙 대비 구현을 심판하는 독립 검증자다. 코드를 고치지 마라 — 판정만 한다.
+
+## 스펙 (docs/spec)
+${truncate(String(specText ?? '(스펙 없음)'), 6000)}
+
+## 이번 루프의 구현 변경 (git diff)
+\`\`\`diff
+${truncate(String(diffText ?? '(변경 없음)'), 8000)}
+\`\`\`
+
+## 판정 기준
+- **구조가 아니라 의도를 봐라.** "함수가 있는가"가 아니라 "그 함수가 스펙이 요구한 동작을
+  실제로 하는가"다. 코드 로직을 읽고 추론하라. 키워드 매칭으로 통과시키지 마라.
+- 테스트는 이미 통과했다(그건 엔진이 확인했다). 당신이 볼 것은 **테스트가 놓쳤을 수 있는
+  스펙 요구사항** — 커버되지 않은 수용 기준, 스펙과 어긋난 동작, 명백히 빠진 것.
+- 확신이 없으면 통과시켜라. 당신은 하향 전용이다: 명백한 어긋남만 기각하라.
+
+## 출력 (반드시 이 JSON 한 줄로만)
+{"verdict": "pass" 또는 "reject", "reason": "한 문장 근거"}`;
+}