@tuzi-ince/hi-loop 0.2.1 → 0.2.2

package/bin/hi-loop.js

@@ -61,12 +61,24 @@ const USAGE = `hi-loop — 초경량 자율형 자가 치유 엔진
   HILOOP_DISCOVER_CMD/MODEL 발굴 단계의 실행 명령·모델
   HILOOP_AGENT_TIMEOUT_MS 에이전트 타임아웃 (기본: 1800000 = 30분)
   HILOOP_TEST_TIMEOUT_MS  테스트 타임아웃 (기본: 600000 = 10분)
-  TELEGRAM_BOT_TOKEN/CHAT_ID 텔레그램 알림 (미설정 시 생략)`;
+  TELEGRAM_BOT_TOKEN/CHAT_ID 텔레그램 알림 (미설정 시 생략)
+
+검사를 여러 개 걸기 (--test 대신):
+  --check "<cmd>"        판정 명령. 여러 번 줄 수 있고 short-circuit 하지 않는다.
+  --when "<glob>"        바로 앞 --check 를 이 경로가 바뀐 회차에만 실행한다.
+  --flaky-probe          통과한 회차에서 같은 명령을 한 번 더 돌려 플레이키를 잡는다.
+
+  예) UI 를 건드린 회차에만 e2e 까지 돌린다:
+      hi-loop run --goal "..." \\
+        --check "npm test" \\
+        --check "npx playwright test" --when "src/**/*.tsx"`;
 
 export async function main(argv = process.argv.slice(2)) {
   const args = parseArgs(argv, {
     alias: { g: 'goal', t: 'test', c: 'cwd', h: 'help', v: 'version', m: 'max-loops' },
-    boolean: ['help', 'version', 'dry-run', 'no-stagnation', 'verify-spec', 'yes', 'review', 'no-review', 'design-review', 'no-design-review', 'full', 'discover', 'no-discover'],
+    boolean: ['help', 'version', 'dry-run', 'no-stagnation', 'verify-spec', 'flaky-probe', 'yes', 'review', 'no-review', 'design-review', 'no-design-review', 'full', 'discover', 'no-discover'],
+    // 개수가 정해지지 않은 입력. `--check A --when X --check B` 처럼 위치로 짝을 맺는다.
+    repeat: ['check', 'when'],
   });
   const command = args._[0] ?? (args.help || args.version ? null : 'mcp');
 
@@ -189,7 +201,17 @@ export async function main(argv = process.argv.slice(2)) {
         process.stderr.write(`롤백 실패: ${res.reason}\n`);
         return 1;
       }
-      process.stdout.write(`✅ ${cp.iteration}회차 직전 상태로 파일을 복원했습니다 (${cp.sha.slice(0, 8)}).\n`);
+      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;
     }

package/docs/design.md

@@ -552,7 +552,18 @@ try/catch 로 감싼다. **텔레그램 장애로 빌드가 죽는 것은 설계
 | ~~L7~~ | ~~실제 `claude` 에이전트와의 통합이 미검증~~ | ✅ **해소** — claude 2.1.212 로 실측. 편집 권한·세션 재개·JSON 파싱·전체 루프 전부 확인(§10). **차단 사유였던 "개발 환경 실행 가드"는 사실이 아니었다** — 막고 있던 것은 기술적 불가능이 아니라 실행되지 않은 절차였다 |
 | ~~L8~~ | ~~경로 회피는 강제가 아니다~~ | ✅ **관측으로 완화**(§4.14) — baseline 대비 삭제된 파일을 경고(차단 안 함, 되돌림 가능). 수정은 정당할 수 있어 삭제만 본다. 실측: 에이전트가 시킨 대로 legacy.js 삭제 → 경고 발동 |
 | ~~L9~~ | ~~스펙이 오라클이 아니다~~ | ✅ **해소**(§4.12, opt-in) — 2단 판정. Tier 1(기계) 최종 권한, Tier 2(모델) 하향 전용. 검증자는 plan 모드·새 세션으로 격리. 실측: 테스트 통과 + 스펙 AC 미충족을 실제 claude 가 41초 만에 기각 |
-| ~~L10~~ | ~~산출물이 미관측을 공개하지 않는다~~ | ✅ **해소**(§4.10) — `reportGaps` 가 passed 마다 Evidence+Gaps 를 출력. CLI·MCP 양쪽. 실패엔 안 붙임(이미 stopReason 으로 정직) |
+| ~~L10~~ | ~~산출물이 미관측을 공개하지 않는다~~ | ✅ **해소**(§4.10) — `reportGaps` 가 5섹션(Claim/Evidence/Baseline-attribution/Gaps/Residual-risk)을 출력. CLI·MCP 양쪽. **실패에도 붙인다** — 예전 판단("실패는 stopReason 으로 이미 정직")을 뒤집었다. 예산 소진·정체로 멈춘 순간이야말로 워킹트리에 무엇이 반쯤 적용됐는지 알아야 할 때다 |
+| ~~L11~~ | ~~판정이 불리언 하나다 — 통과 수가 무너져도 exit 0~~ | ✅ **해소**(`metrics.js`) — 러너 출력에서 통과/실패 수를 읽어 비회귀 게이트. 지문(L1)은 파일을 보고 이쪽은 실행 결과를 봐서 케이스를 안 지우는 축소를 잡는다. 언어 무관이라 Python·Go 프로젝트의 무결성 사각도 메운다. 정체 판정도 지표 벡터를 함께 본다 |
+| ~~L12~~ | ~~에이전트가 아무것도 안 쓴 회차를 모른다~~ | ✅ **해소**(`treekey.js`) — `git stash create` 트리 SHA 로 앞뒤 비교. 트리가 같으면 결과가 같다는 것은 관측이 아니라 증명이므로 2회차에 정체로 잡는다 |
+| ~~L13~~ | ~~디스크엔 있고 git 엔 없는 테스트~~ | ✅ **해소**(`integrity.js`) — 지문은 디스크를 읽으므로 gitignore 된 테스트도 완벽한 지문을 갖는다. CI 는 그 테스트를 못 보고 체크포인트로도 복구되지 않는다. 측정이라 fail-closed |
+| ~~L14~~ | ~~돌지 않은 게이트가 Evidence 를 만든다~~ | ✅ **해소**(`gates.js`) — 게이트가 평가되는 그 자리에서만 원장에 남고, 보고서는 원장에서 렌더한다. `unobservable`·`off` 는 통과와 구분돼 Gaps 로 간다 |
+| ~~L15~~ | ~~게이트를 하나도 안 거치고 passed 에 도달한다~~ | ✅ **해소**(`outcome.js`) — `--start-from CODE_REVIEW` 가 테스트를 한 번도 안 돌리고 통과를 주장했다. 통과한 트리를 박아두고 최종 판정 시점 트리와 대조한다. 종료 지점을 한 파일에 모아 새 stage 가 이 검사를 우회할 수 없게 했다 |
+| ~~L16~~ | ~~게이트 기준선이 에이전트의 쓰기 범위 안에 있다~~ | ✅ **해소**(`seal.js`) — 상태 파일은 gitignore 되고 cwd 에 있다. 게이트를 여는 필드에 HMAC(키는 cwd 밖). 불일치면 기준선 없음으로 되돌리고 보고서에 밝힌다 |
+| ~~L17~~ | ~~"한 번만 쟀다"가 산문으로만 있다~~ | ✅ **해소**(`--flaky-probe`) — 통과 회차에서만 재실행. 에이전트 호출 0. 두 번 돌려 갈리는 초록불은 초록불이 아니다 |
+| ~~L18~~ | ~~판정 명령이 하나뿐이다~~ | ✅ **해소**(`checks.js`, `--check`/`--when`) — short-circuit 없이 전부 실행. 경로 글롭으로 무거운 검사(e2e)를 해당 회차에만. 건너뛴 것은 통과가 아니라 `skipped` 로 공개 |
+| L19 | 만들었지만 제품 경로에서 안 불리는 파일 | ⚠️ **관측으로 완화**(`wiring.js`) — 테스트만 부르는 새 파일을 Gaps 에 공개. 차단하지 않는다(다음 회차에 배선할 수 있어 오탐이 루프를 죽인다) |
+| L20 | 수정이 실패에 비해 과도한가 | ⚠️ **관측으로 완화**(`blast.js`) — 의존성·마이그레이션·CI·러너 설정 변경을 Gaps 에 공개. bkit 도 경고로만 쓴다 |
+| L21 | 복구 경로 자체가 무방비 | ⚠️ **관측으로 완화**(`checkpoint.js`) — 에이전트는 cwd 에서 Bash 를 갖는다. `rm -rf .git` 한 번이면 L3 가 사라진다. 자식의 Bash 를 가로채는 CC 훅 주입은 **훅 발동을 검증하지 못한 채 배송**하는 것이라 택하지 않았다. 대신 매 회차 복구 경로 생존을 직접 잰다 — 막지는 못해도 모른 채 진행하지 않는다 |
 
 ---
 

package/docs/spec.md

@@ -393,7 +393,9 @@ DISCOVER → PLAN → DESIGN_REVIEW → DO ⇄ CHECK ⇄ HEAL → CODE_REVIEW
 - NFR-3 모든 I/O 경계(에이전트 호출, 테스트 실행, 알림)는 주입 가능해야 하며
   테스트는 네트워크/실제 에이전트 없이 통과해야 한다.
 - NFR-4 상태 파일 쓰기는 원자적이어야 한다(중단 시 손상 금지).
-- NFR-5 코드 파일당 300줄 이내, 모듈 단일 책임.
+- NFR-5 코드 파일당 300줄 이내, 모듈 단일 책임. **`tests/nfr.test.js` 가 이 값을 강제한다** —
+  선언만 있고 재는 사람이 없던 동안 `build.js` 가 309줄, `loop.js` 가 303줄로 조용히 넘어갔다.
+  같은 파일이 NFR-4(런타임 의존성 2개)와 "아무도 안 읽는 export 금지"도 함께 강제한다.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tuzi-ince/hi-loop",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "CLI와 MCP 모드를 지원하는 초경량 자율형 자가 치유 엔진",
   "type": "module",
   "license": "MIT",

package/src/args.js

@@ -1,8 +1,21 @@
-/** 의존성 없는 최소 인자 파서 (FR-1.4) — `--k v`, `--k=v`, `-g v`, `--flag` 지원 */
-export function parseArgs(argv, { alias = {}, boolean: booleans = [] } = {}) {
+/**
+ * 의존성 없는 최소 인자 파서 (FR-1.4) — `--k v`, `--k=v`, `-g v`, `--flag` 지원.
+ *
+ * `repeat` 에 든 키는 여러 번 줘도 덮어쓰지 않고 **배열로 쌓는다**. `--check` 처럼 개수가
+ * 정해지지 않은 입력에 필요하다. 기본은 덮어쓰기다 — 모든 키를 배열로 만들면 호출부가
+ * 전부 `Array.isArray` 를 신경 써야 한다.
+ */
+export function parseArgs(argv, { alias = {}, boolean: booleans = [], repeat = [] } = {}) {
   const out = { _: [] };
   const isBool = (k) => booleans.includes(k);
   const norm = (k) => alias[k] ?? k;
+  const put = (k, v) => {
+    if (!repeat.includes(k)) {
+      out[k] = v;
+      return;
+    }
+    out[k] = out[k] === undefined ? [v] : [...(Array.isArray(out[k]) ? out[k] : [out[k]]), v];
+  };
 
   for (let i = 0; i < argv.length; i += 1) {
     const token = argv[i];
@@ -14,15 +27,15 @@ export function parseArgs(argv, { alias = {}, boolean: booleans = [] } = {}) {
       const raw = token.replace(/^--?/, '');
       const eq = raw.indexOf('=');
       if (eq !== -1) {
-        out[norm(raw.slice(0, eq))] = raw.slice(eq + 1);
+        put(norm(raw.slice(0, eq)), raw.slice(eq + 1));
         continue;
       }
       const key = norm(raw);
       const next = argv[i + 1];
       if (isBool(key) || next === undefined || next.startsWith('--')) {
-        out[key] = true;
+        put(key, true);
       } else {
-        out[key] = next;
+        put(key, next);
         i += 1;
       }
       continue;

package/src/blast.js

@@ -0,0 +1,42 @@
+/**
+ * 블라스트 반경 (L20) — 수정이 실패에 비해 과도한가.
+ *
+ * 이 엔진의 HEAL 루프에는 "고침의 크기"라는 개념이 없었다. 단언 하나가 깨진 것을 고치려고
+ * 에이전트가 `package.json` 을 다시 쓰거나, 마이그레이션을 추가하거나, 러너 설정을 바꿔도
+ * 테스트만 통과하면 전부 통과다. L8(삭제 관측)은 **지운 것**만 본다.
+ *
+ * 판정이 아니라 **공개**다. 큰 변경이 정당한 경우가 흔하고(리팩터링 goal, 초기 스캐폴딩),
+ * 차단하면 오탐이 루프를 죽인다. bkit 도 이 분류를 경고로만 쓴다
+ * (`lib/control/blast-radius.js:202` — warning 문자열을 돌려줄 뿐 차단하지 않는다).
+ * 사람이 보고서에서 "테스트는 통과했는데 왜 락파일이 바뀌었지"를 알아채게 하는 것이 목적이다.
+ */
+
+/** 위험 분류. 순서가 곧 우선순위다 — 먼저 맞는 것이 이긴다. */
+const CLASSES = [
+  [/(?:^|\/)(?:package|pnpm|yarn)-lock\.(?:json|yaml)$|(?:^|\/)package\.json$|(?:^|\/)go\.(?:mod|sum)$|(?:^|\/)Cargo\.(?:toml|lock)$|requirements\.txt$|pyproject\.toml$/, '의존성'],
+  [/(?:^|\/)migrations?\//i, '스키마 마이그레이션'],
+  [/(?:^|\/)\.github\/|(?:^|\/)Dockerfile|docker-compose|(?:^|\/)\.gitlab-ci/i, 'CI·배포 설정'],
+  [/\.(?:config|conf)\.[cm]?[jt]s$|(?:^|\/)tsconfig|(?:^|\/)vite\.config|(?:^|\/)vitest\.config|(?:^|\/)jest\.config|(?:^|\/)eslint/i, '빌드·러너 설정'],
+  [/(?:^|\/)\.env/, '환경 변수'],
+];
+
+/** 변경 파일들을 위험 분류로 묶는다. `{분류: [파일…]}` — 해당 없으면 빈 객체. */
+export function classifyChanges(files) {
+  const out = {};
+  for (const f of Array.isArray(files) ? files : []) {
+    for (const [re, label] of CLASSES) {
+      if (!re.test(f)) continue;
+      (out[label] ??= []).push(f);
+      break;
+    }
+  }
+  return out;
+}
+
+/** 보고서 Gaps 에 실을 줄. 위험 분류가 없으면 빈 배열이다(소음을 만들지 않는다). */
+export function blastLines(classified) {
+  return Object.entries(classified ?? {}).map(
+    ([label, files]) =>
+      `- ⚠️ 이번 실행이 **${label}** 파일을 건드렸다: ${files.slice(0, 5).join(', ')}${files.length > 5 ? ` 외 ${files.length - 5}개` : ''}. 테스트 통과와 별개로 사람이 봐야 한다.`,
+  );
+}

package/src/build.js

@@ -13,10 +13,15 @@
  *   { ok: false, stopReason, detail }     예산·정체·한도 소진
  *   { stopped: true }                     --stop-after PLAN 으로 멈춤
  */
-import { saveState, truncate, errorSignature, LIMITS } from './state.js';
+import { saveState, truncate, LIMITS } from './state.js';
 import { promptFor } from './prompts.js';
-import { compareFingerprints, violationMessage } from './integrity.js';
-import { detectDeletions } from './checkpoint.js';
+import { violationMessage } from './integrity.js';
+import { isNoOp } from './treekey.js';
+import { isImproved, isSameMetrics } from './metrics.js';
+import { composeFailure, stagnationSignature } from './verdict.js';
+import { runCheck } from './check.js';
+import { isGitRepo } from './checkpoint.js';
+import { failingSet } from './checks.js';
 
 /** iteration -> PDCA phase (1회차 PLAN, 2회차 DO, 이후 전부 HEAL) */
 export function phaseForIteration(iteration) {
@@ -42,12 +47,18 @@ function addCost(prev, delta) {
 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;
+  const { agentRunner, testRunner, integrityChecker, checkpointer, fileLister, specVerifier, designReviewer, treeKeyReader } = ports;
   // state 는 이 루프에서 속성만 바뀌고 재대입되지 않는다 — 참조를 그대로 잡아도 안전하다.
   const state = ctx.state;
 
     state.stage = 'BUILD';
     state.status = 'running';
+    // L21 의 기준점: **루프가 시작될 때** git 저장소였는가. 주입 가능한 포트가 아니라
+    // 직접 관측한다 — 이 값이 스텁에서 오면 "복구 경로가 사라졌다"는 판정이 테스트 설정에
+    // 좌우된다. 한 번만 재고 상태에 박아둔다(재개해도 기준이 흔들리지 않게).
+    if (state.wasGitRepo === undefined || state.wasGitRepo === null) {
+      state.wasGitRepo = await isGitRepo(cwd);
+    }
     saveState(statePath, state);
 
     while (state.iteration < maxLoops) {
@@ -75,11 +86,21 @@ export async function runBuildLoop(ctx) {
 
       logger(`[hi-loop] iteration ${state.iteration}/${maxLoops} — ${state.phase} (session #${state.sessionSerial})`);
 
+      // L12: 에이전트 호출 전후의 트리 키. 같으면 이번 회차는 **증명된 무변경**이다.
+      const keyBefore = await treeKeyReader({ cwd });
+
       const prompt = promptFor(state);
       const result = await agentRunner({ prompt, sessionId: state.sessionId, cwd });
       state.sessionId = result?.sessionId ?? state.sessionId ?? null;
       state.costUsd = addCost(state.costUsd, result?.costUsd);
 
+      const keyAfter = await treeKeyReader({ cwd });
+      state.treeKey = keyAfter ?? state.treeKey ?? null;
+      const noop = isNoOp(keyBefore, keyAfter);
+      if (noop) {
+        logger('[hi-loop] 🫥 에이전트가 파일을 하나도 바꾸지 않았습니다 — 이 회차는 결과가 같습니다.');
+      }
+
       if (state.phase === 'PLAN') {
         state.specSummary = summarizeSpec(result?.text) || state.specSummary;
 
@@ -119,50 +140,9 @@ export async function runBuildLoop(ctx) {
         }
       }
 
-      // ---- 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] 🔬 스펙 검증 통과.`);
-        }
-      }
-
+      const { passed, integrity, metrics, regressed, specReject, output, fuel, check, suite, recovery } = await runCheck({
+        state, cwd, statePath, logger, ports, opts, baselineFiles,
+      });
       state.history.push({
         iteration: state.iteration,
         phase: 'CHECK',
@@ -184,7 +164,23 @@ export async function runBuildLoop(ctx) {
         for (const v of integrity.violations) logger(`[hi-loop]    - ${v}`);
       }
 
+      if (regressed.length) {
+        logger(
+          `[hi-loop] 📉 비회귀 위반 — 통과 수가 ${state.metricBaseline.passed}개 → ${metrics.passed}개로 줄었습니다. 초록불이지만 통과로 인정하지 않습니다.`,
+        );
+      }
+
+      // 복구 경로가 완전히 끊겼으면 더 돌리지 않는다. 되돌릴 수 없는 상태에서 에이전트를
+      // 또 부르는 것은 손해를 키우는 것뿐이다.
+      if (!recovery.ok) {
+        saveState(statePath, state);
+        return { ok: false, stopReason: 'recovery-lost', detail: recovery.reason };
+      }
+
       if (passed) {
+        // L15: 게이트를 통과한 **그 트리**를 박아둔다. 이 값과 최종 판정 시점의 트리가
+        // 다르면 passed 를 주장하지 않는다(BUILD 를 건너뛴 경로 차단).
+        state.passedTreeKey = (await treeKeyReader({ cwd })) ?? null;
         state.lastError = '';
         saveState(statePath, state);
         logger(`[hi-loop] ✅ ${state.iteration}회차에 통과했습니다. (누적 $${state.costUsd.toFixed(2)})`);
@@ -197,27 +193,43 @@ export async function runBuildLoop(ctx) {
       // 자기가 뭘 어겼는지 모른 채 같은 짓을 반복한다.
       // 실패의 정체를 셋 중 하나로 조립한다: 스펙 기각 / 무결성 위반 / 테스트 에러.
       // 스펙 기각이면 테스트는 통과했으니 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)}`;
-      }
+      const failure = composeFailure({
+        specReject,
+        output: fuel,
+        checkCode: check?.code,
+        specPath: state.specPath,
+        integrity,
+        regressed,
+        baseline: state.metricBaseline,
+        metrics,
+      });
       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;
+      // 검사가 둘 이상이면 **실패한 명령의 집합**이 출력 텍스트보다 안정적인 신호다.
+      // 세 검사의 잡음을 이어붙여 해시하면 매번 달라져 정체를 영영 못 잡는다.
+      const sig =
+        suite.ran.length > 1 && !suite.ok
+          ? `CHECKS:${failingSet(suite.results)}`
+          : stagnationSignature({ specReject, integrity, regressed, output });
+
+      // 에러 지문만으로는 정체를 두 방향으로 오판한다(moai `internal/loop/feedback.go:43,54`):
+      //  · 위음성 — 진짜 제자리인데 에러 텍스트가 매번 달라지면(줄 번호·파일·타이밍) 지문이
+      //    계속 바뀌어 카운터가 리셋되고, maxLoops 와 예산을 전부 태운다.
+      //  · 위양성 — 실패 12 → 7 → 3 으로 **줄고 있는데** 첫 실패 줄이 그대로면 지문이 같아
+      //    수렴 중인 실행을 조기 종료한다.
+      // 그래서 판단 근거를 둘로 늘린다: 지표가 나아졌으면 지문과 무관하게 리셋하고,
+      // 지표 벡터가 완전히 동일하면 지문이 달라도 정체로 센다.
+      const prevMetrics = state.metrics ?? null;
+      const improved = isImproved(prevMetrics, metrics);
+      // no-op 회차(L12)는 무조건 정체다 — 트리가 그대로면 결과가 같다는 것은 증명이다.
+      const stuck = noop || (sig && sig === state.errorSig) || isSameMetrics(prevMetrics, metrics);
+      state.stagnantRuns = improved ? 1 : stuck ? state.stagnantRuns + 1 : 1;
       state.errorSig = sig;
+      if (metrics) state.metrics = metrics;
       saveState(statePath, state);
 
       if (integrity.ok) {

package/src/check.js

@@ -0,0 +1,169 @@
+/**
+ * CHECK 단계 — Tier 1 게이트를 전부 평가하고 하나의 판정으로 합친다.
+ *
+ * build.js 에서 뺀 이유는 크기(NFR-5)만이 아니다. 게이트는 앞으로도 는다(무결성 → 유령 →
+ * 비회귀 → 스펙 → 플레이키…). 그 목록이 루프 본문 안에 있으면 회차 관리·핸드오프·예산 같은
+ * **다른 관심사와 섞여** 어떤 게이트가 어떤 순서로 평가되는지 한눈에 안 보인다.
+ * 여기 있으면 "이 실행이 무엇을 근거로 통과를 말하는가"가 한 파일에 모인다.
+ *
+ * 원칙: 게이트를 평가한 **그 자리에서** 원장(gates.js)에 기록한다. 나중에 몰아 쓰면
+ * "돌지 않은 게이트가 기록되는" 경로가 다시 열린다 — 그게 감사에서 잡힌 결함이었다.
+ */
+import { saveState, truncate } from './state.js';
+import { compareFingerprints, detectUntrackedTests, untrackedMessage } from './integrity.js';
+import { parseMetrics, regressions, nextBaseline } from './metrics.js';
+import { composeIntegrity } from './verdict.js';
+import { recordGate } from './gates.js';
+import { normalizeChecks, runChecks, failureSummary, failingSet } from './checks.js';
+import { detectUnwired } from './wiring.js';
+import { classifyChanges } from './blast.js';
+import { detectDeletions, verifyRecoveryPath } from './checkpoint.js';
+
+function combineOutput({ stdout, stderr }) {
+  return [stderr, stdout].filter(Boolean).join('\n').trim();
+}
+
+/**
+ * 반환: `{ passed, integrity, metrics, regressed, specReject, output, check }`
+ * state 를 직접 갱신한다(기준선·원장·삭제 관측) — 이것들은 회차를 넘어 누적되는 사실이라
+ * 호출부로 돌려보내 다시 쓰게 하면 빠뜨리기 쉽다.
+ */
+export async function runCheck({ state, cwd, statePath, logger, ports, opts, baselineFiles }) {
+  const { testRunner, integrityChecker, fileLister, specVerifier, changeLister } = ports;
+  const { testCommand, verifySpec } = opts;
+  // ---- CHECK: 엔진이 직접 검증 (FR-2.3) ----
+  // 2단 판정이다. exit code 는 "테스트가 통과했는가"만 답한다. 그 테스트가
+  // **그대로인가**는 별도 문제이고, 그걸 안 물으면 에이전트는 테스트를 지워서 통과한다(L1).
+  state.phase = 'CHECK';
+  saveState(statePath, state);
+  // L18: 검사는 배열이다. short-circuit 하지 않고 전부 돌린다 — 그래야 "3개 중 2개가
+  // 깨졌다"를 한 회차에 알 수 있다. `--check` 가 없으면 종전대로 testCommand 하나다.
+  const checks = normalizeChecks({ testCommand, checks: opts.checks });
+  const changedFiles = checks.some((c) => c.when) ? await changeLister({ cwd }) : null;
+  const suite = await runChecks({ checks, cwd, runner: testRunner, changedFiles });
+  const check = { ok: suite.ok, code: suite.ok ? 0 : 1 };
+  // 지표 파싱과 에러 연료는 **실제로 돈 검사들의 출력**에서 나온다.
+  const output = suite.ran.map((r) => [r.stderr, r.stdout].filter(Boolean).join('\n')).join('\n').trim();
+  for (const s2 of suite.skipped) {
+    logger(`[hi-loop] ⏭  \`${s2.cmd}\` 는 건너뜁니다 — 변경 파일이 \`${s2.when}\` 에 맞지 않습니다.`);
+  }
+
+  // 추적 목록은 여기서 한 번만 얻는다 — 아래 삭제 검출(L8)과 유령 테스트(L13)가 같이 쓴다.
+  const trackedFiles = await fileLister({ cwd });
+
+  const fingerprint = integrityChecker({ cwd, testPath: state.testPath });
+  const fpCompare = compareFingerprints(state.testFingerprint, fingerprint);
+  // L13: 지문은 디스크를 읽으므로 git 이 모르는 테스트도 완벽한 지문을 갖는다.
+  // 추적되지 않은 테스트는 CI 에 존재하지 않는 테스트이고, 체크포인트로도 복구되지 않는다.
+  const ghosts = detectUntrackedTests(Object.keys(fingerprint), trackedFiles);
+  const integrity = composeIntegrity(fpCompare.violations, ghosts.map(untrackedMessage));
+  const it = state.iteration;
+  state.gates = recordGate(state.gates, 'integrity', fpCompare.violations.length ? 'fail' : 'pass', { iteration: it });
+  // 유령 검사는 추적 목록이 있어야만 성립한다. 비-git 이면 통과가 아니라 **미관측**이다.
+  state.gates = trackedFiles
+    ? recordGate(state.gates, 'ghost', ghosts.length ? 'fail' : 'pass', { iteration: it })
+    : recordGate(state.gates, 'ghost', 'unobservable', { iteration: it, detail: 'git 저장소가 아니라 추적 여부를 볼 수 없다' });
+  // 위반이 없을 때만 기준선을 갱신한다. 갱신해버리면 약화된 상태가 다음 회차의
+  // 기준이 되어 에이전트가 그대로 빠져나간다.
+  if (integrity.ok) state.testFingerprint = fingerprint;
+
+  // L8: baseline 에 있던 파일이 사라졌는가 = 에이전트가 기존 파일을 삭제. 차단하지 않고
+  // 경고만 한다(체크포인트로 되돌릴 수 있고 판단은 사람 몫). 누적 관측이라 Gaps 에도 실린다.
+  if (baselineFiles) {
+    const deleted = detectDeletions(baselineFiles, trackedFiles);
+    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}`);
+    }
+  }
+
+  // L11: 초록불의 **범위**를 본다. exit code 는 "통과했는가"만 답하고 "몇 개가
+  // 통과했는가"는 답하지 않는다. 통과 수가 무너져도 exit 0 이다. 지문(integrity)은
+  // 파일을 보고 이쪽은 실행 결과를 보므로, 케이스를 지우지 않는 축소를 여기서만 잡는다.
+  // 파싱 불가(null)면 의견 없음 — 막지도 통과시키지도 않는다(측정의 부재는 fail-open).
+  const metrics = parseMetrics(output);
+  const regressed = regressions(state.metricBaseline, metrics);
+
+  // Tier 1 (기계, 최종 권한): exit code + 무결성 + 비회귀.
+  let passed = Boolean(check?.ok) && integrity.ok && regressed.length === 0;
+
+  state.gates = metrics
+    ? recordGate(state.gates, 'nonRegression', regressed.length ? 'fail' : 'pass', { iteration: it })
+    : recordGate(state.gates, 'nonRegression', 'unobservable', { iteration: it, detail: '러너 출력에서 통과/실패 수를 읽지 못했다' });
+  state.gates = recordGate(state.gates, 'exitCode', check?.ok ? 'pass' : 'fail', { iteration: it });
+  state.metricBaseline = nextBaseline(state.metricBaseline, metrics, { integrityOk: integrity.ok, regressed });
+
+  // L19: 이번 루프가 만든 제품 파일 중 제품 경로에서 안 불리는 것. 차단하지 않고 공개한다 —
+  // 다음 회차에 배선할 수도 있어서 차단하면 오탐이 루프를 죽인다. 누적 관측이라 Gaps 에 실린다.
+  if (baselineFiles && trackedFiles) {
+    const unwired = detectUnwired({ cwd, baselineFiles, currentFiles: trackedFiles });
+    const fresh = unwired.filter((f) => !(state.unwiredFiles ?? []).includes(f));
+    if (fresh.length) {
+      state.unwiredFiles = [...(state.unwiredFiles ?? []), ...fresh];
+      logger(`[hi-loop] 🔌 제품 경로에서 안 불리는 새 파일 ${fresh.length}개: ${fresh.join(', ')}`);
+    }
+  }
+
+  // L21: 복구 경로가 아직 살아 있는가. 사라졌으면 이 실행은 되돌릴 수 없는 상태다 —
+  // 계속 돌리면 에이전트가 더 망가뜨려도 손쓸 방법이 없다. 즉시 멈추는 편이 낫다.
+  const recovery = await verifyRecoveryPath({ cwd, checkpoints: state.checkpoints, expectGit: state.wasGitRepo === true });
+  if (recovery.reason) {
+    state.recoveryWarning = recovery.reason;
+    logger(`[hi-loop] 🧨 복구 경로 이상 — ${recovery.reason}`);
+  }
+
+  // L20: 이번 트리가 건드린 위험 분류(의존성·마이그레이션·CI·러너 설정). 차단하지 않고 공개한다.
+  const touched = changedFiles ?? (await changeLister({ cwd }));
+  if (touched) state.blastClasses = classifyChanges(touched);
+
+  // 플레이키 프로브 (L17): 통과 회차에서만 같은 명령을 한 번 더 돌린다.
+  //
+  // Residual-risk 에 "테스트가 플레이키하면 이 판정은 재현되지 않는다"고 **적어만 두는** 것은
+  // 이 엔진의 원칙(산문은 요청이고 메커니즘은 사실이다)에 어긋난다. 재실행 한 번이면 그 문장이
+  // 측정이 된다. 에이전트 호출은 0 이라 비용은 테스트 한 번뿐이고, 통과했을 때만 낸다.
+  //
+  // 불일치는 Tier 1 실패다 — 두 번 돌려 결과가 갈리는 초록불은 초록불이 아니다.
+  if (passed && opts.flakyProbe) {
+    const again = await testRunner({ command: testCommand, cwd });
+    if (!again?.ok) {
+      passed = false;
+      state.gates = recordGate(state.gates, 'flaky', 'fail', { iteration: it });
+      logger('[hi-loop] 🎲 플레이키 감지 — 같은 트리에서 두 번째 실행이 실패했습니다. 통과로 인정하지 않습니다.');
+    } else {
+      state.gates = recordGate(state.gates, 'flaky', 'pass', { iteration: it, detail: '같은 트리에서 2회 연속 통과' });
+    }
+  } else if (!opts.flakyProbe) {
+    state.gates = recordGate(state.gates, 'flaky', 'off', { detail: '--flaky-probe 로 켤 수 있다' });
+  }
+
+  // Tier 2 (모델, 하향 전용): Tier 1 통과일 때만 호출. 스펙 대비 구현을 심판한다.
+  // Tier 1 실패를 통과로 올릴 수는 절대 없다 — reject 만 가능하다(L9, bkit 중심 명제).
+  let specReject = '';
+  if (!verifySpec) state.gates = recordGate(state.gates, 'specVerify', 'off', { detail: '--verify-spec 로 켤 수 있다' });
+  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 {
+      // 검증자는 인프라 실패(스펙 파일 없음·spawn 실패·파싱 실패)에도 pass 를 돌려준다.
+      // 게이트 판정으로는 옳지만(2단은 하향 전용) **증거로 쓰면 거짓말**이다 — 심판이
+      // 열리지도 않았는데 "심판이 통과시켰다"가 된다. verified 로 그 둘을 가른다.
+      const judged = verdict?.verified !== false;
+      state.specVerified = judged;
+      state.gates = recordGate(state.gates, 'specVerify', judged ? 'pass' : 'unobservable', {
+        iteration: it,
+        detail: judged ? '' : verdict?.reason || '검증자가 실제로 심판하지 못했다',
+      });
+      logger(`[hi-loop] 🔬 스펙 검증 통과.`);
+    }
+  }
+
+  // 에이전트에게 줄 연료는 검사가 둘 이상일 때 **어느 검사가 실패했는지**를 명시한다.
+  // 하나뿐이면 종전대로 원본 출력이다(불필요한 껍데기를 씌우지 않는다).
+  const fuel = suite.ran.length > 1 ? failureSummary(suite.results) : output;
+  return { passed, integrity, metrics, regressed, specReject, output, fuel, check, suite, recovery };
+}