@tuzi-ince/hi-loop 0.2.1 → 0.2.2

package/src/checkpoint.js

@@ -87,8 +87,92 @@ export async function rollbackTo({ cwd, sha }) {
   // 되돌리기 전 안전망: 지금 상태를 스냅샷으로 남긴다(롤백을 되돌릴 수 있게).
   const safety = await git(['stash', 'create', '--include-untracked'], cwd);
 
-  // 그 시점 트리를 워킹트리로 복원. checkout <sha> -- . 는 커밋 트리의 파일들을 꺼낸다.
-  const done = await git(['checkout', sha, '--', '.'], cwd);
-  if (done === null) return { ok: false, reason: 'checkout 실패 — SHA 가 유효하지 않거나 접근 불가.' };
-  return { ok: true, safetySha: safety || null };
+  // `git checkout <sha> -- .` 은 워킹트리만 건드리고 인덱스를 남긴다. `read-tree -u --reset`
+  // 은 인덱스와 워킹트리를 함께 그 트리로 맞춘다 — 스테이징된 추가까지 되돌린다.
+  //
+  // **그래도 되돌리지 못하는 것이 있다: 추적되지 않는 새 파일.** git 의 어떤 트리 연산도
+  // 추적 밖 파일을 지우지 않고, `git clean` 은 사용자의 정상 파일(.env, 로컬 스크립트)까지
+  // 지운다. 지우는 것보다 **남아 있다고 밝히는 것**이 맞다 — 이 엔진의 규칙은
+  // "관측하지 않은 것을 관측 결과로 발행하지 않는다"이고, 여기서는 "되돌리지 못한 것을
+  // 되돌렸다고 말하지 않는다"가 같은 규칙이다.
+  const reset = await git(['read-tree', '-u', '--reset', sha], cwd);
+  if (reset === null) {
+    // 인덱스를 못 건드리는 상황(충돌 중 등)에서는 예전 방식으로라도 되돌린다 —
+    // 부분 복원이 무복원보다 낫다. 다만 무엇이 덜 됐는지 호출부가 알아야 한다.
+    const done = await git(['checkout', sha, '--', '.'], cwd);
+    if (done === null) return { ok: false, reason: 'checkout 실패 — SHA 가 유효하지 않거나 접근 불가.' };
+    return { ok: true, safetySha: safety || null, partial: true };
+  }
+  // 되돌린 뒤에도 남아 있는 추적 밖 파일. 호출부가 사람에게 보여줘야 한다.
+  const untracked = await git(['ls-files', '--others', '--exclude-standard'], cwd);
+  return {
+    ok: true,
+    safetySha: safety || null,
+    partial: false,
+    untrackedRemain: untracked ? untracked.split('\n').filter(Boolean) : [],
+  };
+}
+
+/**
+ * 이번 워킹트리에서 **바뀐 파일들** (L18 경로 조건부 검사용).
+ *
+ * `git status --porcelain` 은 추적 파일의 수정·추가와 추적 안 되는 새 파일을 모두 준다.
+ * HEAD 대비가 아니라 워킹트리 대비라, 루프가 시작되기 전부터 더러웠던 파일도 포함된다 —
+ * 그게 맞다. 조건부 검사가 답해야 할 질문은 "이 트리에 UI 변경이 있는가"이지
+ * "이번 회차가 UI 를 건드렸는가"가 아니다. 후자로 하면 2회차에 e2e 가 사라진다.
+ *
+ * 주입 가능한 포트 (NFR-3). `({cwd}) => string[] | null` (null = 비-git, 관측 불가)
+ */
+export function makeChangeLister() {
+  return async ({ cwd }) => {
+    if (!(await isGitRepo(cwd))) return null;
+    const out = await git(['status', '--porcelain', '--untracked-files=all'], cwd);
+    if (out === null) return null;
+    return out
+      .split('\n')
+      .filter(Boolean)
+      .map((l) => l.slice(3).trim())
+      // 이름이 바뀐 항목은 `old -> new` 로 온다. 새 이름이 판정 대상이다.
+      .map((p) => (p.includes(' -> ') ? p.split(' -> ')[1] : p))
+      .filter(Boolean);
+  };
+}
+
+/**
+ * 복구 경로 생존 확인 (L21).
+ *
+ * L3(체크포인트)는 에이전트가 코드를 망가뜨렸을 때의 **유일한** 복구 경로다. 그런데 그
+ * 경로 자체는 무방비였다 — 에이전트는 cwd 에서 `acceptEdits` 로 돌고 Bash 를 갖는다.
+ * `git reset --hard`, `rm -rf .git`, `git gc --prune=now` 한 번이면 체크포인트 사슬이
+ * 통째로 사라지고, 엔진은 그 사실을 롤백을 시도하는 순간까지 모른다.
+ *
+ * 자식 에이전트의 Bash 호출을 가로채는 방법(CC 훅 주입)도 있지만, 그건 훅이 실제로
+ * 발동하는지 검증하지 못한 채 배송하는 것이 된다. 검증 안 된 방어는 이 엔진이 거부하는
+ * 형태다. 대신 **엔진이 직접 소유할 수 있는 측정**으로 바꾼다: 매 회차 복구 경로가
+ * 아직 살아 있는지 확인한다. 막지는 못해도 **모른 채 진행하지는 않는다.**
+ *
+ * 반환: `{ ok, reason }`. 관측 불가(애초에 비-git)면 ok — 인프라는 fail-open.
+ */
+export async function verifyRecoveryPath({ cwd, checkpoints, expectGit = false }) {
+  const isRepo = await isGitRepo(cwd);
+  // **루프 시작 시점에 git 을 관측했는데 지금 아니라면 그건 손실이다.** 이 구분이 없으면
+  // 둘 중 하나를 포기해야 한다: 비-git 프로젝트 전체를 오탐으로 막거나(그러면 못 쓴다),
+  // `.git` 이 통째로 사라진 최악의 경우를 못 잡거나(그러면 이 함수가 무의미하다).
+  if (expectGit && !isRepo) {
+    return { ok: false, reason: 'git 저장소가 사라졌다 — 체크포인트를 되돌릴 수 없다.' };
+  }
+  if (!Array.isArray(checkpoints) || checkpoints.length === 0) return { ok: true, reason: '' };
+  if (!isRepo) return { ok: true, reason: '' }; // 애초에 git 이 아니었다 — 관측 불가는 손실이 아니다.
+  const dead = [];
+  for (const cp of checkpoints) {
+    const seen = await git(['cat-file', '-e', `${cp.sha}^{commit}`], cwd);
+    if (seen === null) dead.push(cp.iteration);
+  }
+  if (dead.length === checkpoints.length) {
+    return { ok: false, reason: `체크포인트 ${dead.length}개가 모두 접근 불가다(gc 되었거나 저장소가 초기화됐다).` };
+  }
+  if (dead.length) {
+    return { ok: true, reason: `체크포인트 ${dead.length}개가 접근 불가다(회차 ${dead.join(', ')}).` };
+  }
+  return { ok: true, reason: '' };
 }

package/src/checks.js

@@ -0,0 +1,122 @@
+/**
+ * 다중 조건 검사 (L18) — 판정 명령이 하나뿐이던 문제.
+ *
+ * 지금까지 이 엔진의 Tier 1 입력은 `testCommand` **하나**였다. 유닛 테스트 말고 lint·typecheck·
+ * e2e 까지 게이트로 쓰려면 사용자가 `npm test && npm run lint && npx playwright test` 라고
+ * 써야 했는데, 그건 셋 다 나쁘다:
+ *
+ *  1. `&&` 는 short-circuit 이다. 유닛이 깨지면 **e2e 상태를 영원히 모른다.** 고치고 다시
+ *     돌려야 비로소 두 번째 실패를 발견하고, 그때 또 한 회차를 태운다.
+ *  2. UI 와 무관한 회차에도 e2e 가 매번 돈다. playwright 를 10회 루프에 물리면 비용이
+ *     에이전트 호출을 넘어선다.
+ *  3. 세 실패가 **하나의 지문으로 뭉개져** 정체 감지(L2)가 오작동한다.
+ *
+ * 설계(moai `internal/goal/schema.go:29` 의 조건 배열): 검사를 배열로 받고 **short-circuit
+ * 하지 않는다.** 전부 돌리고, 조건별로 실패 꼬리를 따로 보관해 에이전트에게 "3개 중 2번이
+ * 이렇게 실패했다"를 준다. 그리고 각 검사에 `when` 글롭을 달 수 있다 — 이번 회차가 건드린
+ * 파일이 하나도 안 맞으면 **건너뛴다.** 이것이 "UI 를 고쳤을 때만 e2e" 를 가능하게 한다.
+ *
+ * 건너뛴 검사는 통과가 아니다. 원장에 'skipped' 로 남고 보고서 Gaps 에 나온다 —
+ * 안 돌린 것이 통과처럼 보이면 이 엔진의 존재 이유가 무너진다.
+ */
+
+/** 꼬리 길이. 실패 출력 전체를 물고 다니면 핸드오프 압축이 무의미해진다. */
+export const TAIL_LEN = 800;
+
+/**
+ * 글롭 → 정규식. `**` 는 경로 구분자를 넘고, `*` 는 안 넘는다.
+ * 의존성을 늘리지 않으려고 직접 만든다(NFR-4). 지원하는 것은 `**`, `*`, `?` 뿐이다 —
+ * 더 필요해지면 그때 늘린다. 지금 없는 문법을 미리 만들면 검증 안 된 코드가 는다.
+ */
+export function globToRegExp(pattern) {
+  let out = '';
+  for (let i = 0; i < pattern.length; i += 1) {
+    const c = pattern[i];
+    if (c === '*') {
+      if (pattern[i + 1] === '*') {
+        // `**/` 는 "0개 이상의 디렉터리"다. 슬래시까지 삼켜야 `src/**/*.ts` 가 `src/a.ts` 에도 맞는다.
+        if (pattern[i + 2] === '/') {
+          out += '(?:.*/)?';
+          i += 2;
+        } else {
+          out += '.*';
+          i += 1;
+        }
+      } else out += '[^/]*';
+    } else if (c === '?') out += '[^/]';
+    else out += c.replace(/[.+^${}()|[\]\\]/g, '\\$&');
+  }
+  return new RegExp(`^${out}$`);
+}
+
+/** 변경 파일 중 하나라도 패턴에 맞는가. 패턴이 없으면 항상 참(무조건 실행). */
+export function matchesAny(pattern, files) {
+  if (!pattern) return true;
+  if (!Array.isArray(files)) return true; // 변경 목록을 못 얻으면 **건너뛰지 않는다** — 미실행보다 과실행이 안전하다.
+  const re = globToRegExp(pattern);
+  return files.some((f) => re.test(f));
+}
+
+/**
+ * CLI/MCP 입력을 검사 배열로 정규화한다.
+ *
+ * `--check` 가 하나도 없으면 종전대로 `testCommand` 하나다 — 기존 사용자에게 아무것도
+ * 바뀌지 않는다. 이 하위 호환이 없으면 업데이트만 한 사람의 판정 규칙이 조용히 달라진다.
+ */
+export function normalizeChecks({ testCommand, checks }) {
+  if (!Array.isArray(checks) || checks.length === 0) return [{ cmd: testCommand, when: null }];
+  return checks
+    .map((c) => (typeof c === 'string' ? { cmd: c, when: null } : { cmd: c?.cmd, when: c?.when ?? null }))
+    .filter((c) => typeof c.cmd === 'string' && c.cmd.trim());
+}
+
+/**
+ * 검사를 전부 돌린다. **short-circuit 하지 않는다** — 그게 이 모듈의 존재 이유다.
+ *
+ * 반환: `{ ok, results, ran, skipped }`
+ *   results: `[{ cmd, when, ok, code, tail, skipped }]`
+ */
+export async function runChecks({ checks, cwd, runner, changedFiles }) {
+  const results = [];
+  for (const c of checks) {
+    if (!matchesAny(c.when, changedFiles)) {
+      results.push({ ...c, skipped: true, ok: true, code: null, tail: '' });
+      continue;
+    }
+    const r = await runner({ command: c.cmd, cwd });
+    const out = [r?.stderr, r?.stdout].filter(Boolean).join('\n').trim();
+    results.push({ ...c, skipped: false, ok: Boolean(r?.ok), code: r?.code ?? null, tail: out.slice(-TAIL_LEN), stdout: r?.stdout ?? '', stderr: r?.stderr ?? '' });
+  }
+  const ran = results.filter((r) => !r.skipped);
+  return {
+    ok: ran.every((r) => r.ok),
+    results,
+    ran,
+    skipped: results.filter((r) => r.skipped),
+  };
+}
+
+/**
+ * 에이전트에게 줄 실패 요약. **어느 검사가 실패했는지**를 명시한다 —
+ * `&&` 로 이어붙였을 때는 알 수 없던 정보다.
+ */
+export function failureSummary(results) {
+  const failed = results.filter((r) => !r.skipped && !r.ok);
+  if (!failed.length) return '';
+  const head = `검사 ${results.filter((r) => !r.skipped).length}개 중 ${failed.length}개가 실패했다.`;
+  return [head, ...failed.map((r) => `\n### \`${r.cmd}\` (exit ${r.code})\n${r.tail || '(출력 없음)'}`)].join('\n');
+}
+
+/**
+ * 정체 지문용 키. 실패한 **명령의 집합**으로 만든다.
+ *
+ * 출력 텍스트를 이어붙여 해시하면 세 검사의 잡음이 섞여 매번 달라진다. 어느 검사가
+ * 실패하고 있는가는 그보다 훨씬 안정적인 신호이고, "lint 만 계속 깨진다"를 정확히 짚는다.
+ */
+export function failingSet(results) {
+  return results
+    .filter((r) => !r.skipped && !r.ok)
+    .map((r) => r.cmd)
+    .sort()
+    .join('|');
+}

package/src/cli-options.js

@@ -103,6 +103,14 @@ export function parseRunOptions(args, { staged = {} } = {}) {
     return bad('--start-from 에는 PLAN 을 쓸 수 없습니다. BUILD 로 시작하면 PLAN 부터 돕니다.');
   }
 
+  // `--check` / `--when` 을 위치로 짝짓는다. when 이 모자라면 나머지는 무조건 실행이다.
+  const pairChecks = (check, when) => {
+    if (check === undefined) return null;
+    const cmds = (Array.isArray(check) ? check : [check]).filter((c) => typeof c === 'string');
+    const globs = when === undefined ? [] : Array.isArray(when) ? when : [when];
+    return cmds.map((cmd, i) => ({ cmd, when: typeof globs[i] === 'string' ? globs[i] : null }));
+  };
+
   // null = 자동(--full 또는 --ship 이면 켜짐). 명시 플래그가 그 자동을 양방향으로 덮는다.
   const triState = (onKey, offKey) => (args[offKey] ? false : args[onKey] ? true : null);
 
@@ -113,6 +121,11 @@ export function parseRunOptions(args, { staged = {} } = {}) {
       budgetUsd,
       stagnationLimit,
       verifySpec: Boolean(args['verify-spec']),
+      flakyProbe: Boolean(args['flaky-probe']),
+      // L18: `--check "<cmd>"` 를 여러 번 줄 수 있고, 각 뒤의 `--when "<glob>"` 이
+      // 그 검사에 붙는다. 짝을 이렇게 위치로 맺는 이유는 플래그 이름을 늘리지 않기 위해서다
+      // (`--check-e2e`, `--when-e2e` 식으로 가면 검사 개수만큼 플래그가 는다).
+      checks: pairChecks(args.check, args.when),
       shipCommand: str('ship'),
       watchCommand: str('watch'),
       onShipFail,

package/src/gates.js

@@ -0,0 +1,104 @@
+/**
+ * 게이트 원장 (L14) — 어떤 게이트가 **실제로** 평가됐는지 기록한다.
+ *
+ * 문제: `reportGaps` 의 Evidence 는 하드코딩 문자열이었다. "무결성 위반 없음", "유령 테스트
+ * 없음" 같은 줄이 `status === 'passed'` 하나만 보고 인쇄됐다. 그런데 비-git 프로젝트에서는
+ * 유령 테스트 검사가 **수행 자체가 불가능**하고, 스펙 검증자는 스펙 파일이 없으면 검사 없이
+ * pass 를 돌려준다. 그 둘 다 보고서에는 "검사했고 깨끗했다"로 찍혔다.
+ *
+ * 즉 **관측하지 않은 것이 관측 결과로 발행됐다** — 이 엔진이 존재하는 이유인 바로 그 병이,
+ * 그 병을 막으려고 만든 보고 메커니즘 안에 있었다.
+ *
+ * 설계: 게이트가 평가되는 그 순간에만 원장에 한 줄이 남는다. 보고서는 문자열을 짓지 않고
+ * **원장을 읽어서** 렌더한다. 그러면 돌지 않은 게이트가 Evidence 를 만드는 일이 구조적으로
+ * 불가능해진다. 판정 근거를 지어내려면 원장에 없는 키를 읽어야 하는데, 그건 undefined 다.
+ *
+ * 결과값의 뜻:
+ *   'pass'         — 평가했고 통과
+ *   'fail'         — 평가했고 위반
+ *   'unobservable' — **평가할 수 없었다**(비-git 등). 통과가 아니다. Gaps 로 간다.
+ *   'off'          — 사용자가 켜지 않았다(예: --verify-spec 없음). Gaps 로 간다.
+ */
+
+/** 원장에 실릴 수 있는 게이트. 여기 없는 이름을 쓰면 보고서가 조용히 빠뜨린다. */
+export const GATE_NAMES = ['exitCode', 'integrity', 'ghost', 'nonRegression', 'specVerify', 'flaky'];
+
+/** 사람이 읽는 이름. 보고서 Evidence/Gaps 양쪽에서 같은 문구를 쓴다. */
+const LABEL = {
+  exitCode: '테스트 명령 종료 코드',
+  integrity: '테스트 파일 무결성(직전 회차 대비 지문)',
+  ghost: '유령 테스트(git 추적 여부)',
+  nonRegression: '비회귀(통과 수 축소)',
+  specVerify: '스펙 대비 구현 심판(2단 판정)',
+  flaky: '플레이키 프로브(통과 회차 재실행)',
+};
+
+/**
+ * 게이트 평가 결과를 기록한다. **평가한 그 자리에서만** 부른다 —
+ * 나중에 몰아서 쓰면 "돌지 않은 게이트가 기록되는" 경로가 다시 열린다.
+ */
+export function recordGate(ledger, name, result, { iteration = null, detail = '' } = {}) {
+  if (!GATE_NAMES.includes(name)) throw new Error(`알 수 없는 게이트: ${name}`);
+  return { ...(ledger ?? {}), [name]: { result, iteration, detail } };
+}
+
+/** 원장에서 Evidence 줄들을 만든다. 평가된 것만 나온다. */
+export function evidenceLines(ledger) {
+  const out = [];
+  for (const name of GATE_NAMES) {
+    const e = ledger?.[name];
+    if (!e || e.result !== 'pass') continue;
+    out.push(`- ${LABEL[name]} 통과${e.iteration ? ` (iteration ${e.iteration})` : ''}${e.detail ? ` — ${e.detail}` : ''}`);
+  }
+  return out;
+}
+
+/**
+ * 원장에서 Gaps 줄들을 만든다.
+ *
+ * **관측 불가와 미사용을 구분해서 밝힌다.** 둘 다 "검사 안 함"이지만 사용자가 할 일이
+ * 다르다 — 전자는 환경을 고쳐야 하고(git 저장소가 아님), 후자는 플래그를 켜면 된다.
+ */
+export function gapLines(ledger) {
+  const out = [];
+  for (const name of GATE_NAMES) {
+    const e = ledger?.[name];
+    if (!e) {
+      out.push(`- ${LABEL[name]}: 이번 실행에서 평가되지 않았다.`);
+      continue;
+    }
+    if (e.result === 'unobservable') {
+      out.push(`- ${LABEL[name]}: **관측 불가**라 검사하지 못했다${e.detail ? ` (${e.detail})` : ''}. 통과가 아니라 미관측이다.`);
+    } else if (e.result === 'off') {
+      out.push(`- ${LABEL[name]}: 켜지 않아 검사하지 않았다${e.detail ? ` (${e.detail})` : ''}.`);
+    }
+  }
+  return out;
+}
+
+/**
+ * 판정↔트리 결속 (L15) — "통과한 트리"와 "지금 트리"가 같은가.
+ *
+ * 이게 없으면 `--start-from CODE_REVIEW` 처럼 BUILD 를 건너뛴 경로가 게이트를 **하나도**
+ * 통과하지 않고 `passed` 에 도달했다. 그리고 보고서는 "무결성·비회귀 게이트를 모두 넘었다"고
+ * 인쇄했다 — false green 을 막으려 만든 공개 메커니즘이 false green 을 생산한 것이다.
+ *
+ * 반환: `{ ok, reason }`. ok=false 면 호출부는 `passed` 를 주장해선 안 된다.
+ *
+ * 관측 불가(비-git)일 때는 결속을 **강제하지 못한다**. 그때도 "빌드가 통과했다"는 사실
+ * 자체는 원장에 있으므로 그것만 요구하고, 트리 일치는 건너뛴다(인프라 fail-open).
+ * 하지만 빌드를 아예 안 돈 것은 인프라 문제가 아니라 **측정의 부재**이므로 fail-closed 다.
+ */
+export function checkVerdictBinding({ ledger, passedTreeKey, currentTreeKey }) {
+  if (ledger?.exitCode?.result !== 'pass') {
+    return { ok: false, reason: '이번 실행에서 테스트 게이트를 통과한 적이 없다(BUILD 를 건너뛰었다).' };
+  }
+  if (!passedTreeKey || !currentTreeKey) return { ok: true, reason: '' }; // 트리 관측 불가 — 강제 불가
+  if (passedTreeKey !== currentTreeKey) {
+    return {
+      ok: false,
+      reason: `게이트를 통과한 트리(${passedTreeKey.slice(0, 12)})와 지금 트리(${currentTreeKey.slice(0, 12)})가 다르다.`,
+    };
+  }
+  return { ok: true, reason: '' };
+}

package/src/integrity.js

@@ -7,7 +7,9 @@
  * 지금까지의 방어는 프롬프트 한 줄이었다("테스트를 무력화하지 마라"). 산문은 요청이지
  * 메커니즘이 아니다 — 그리고 실측에서 에이전트가 프롬프트를 어길 수 있음이 확인됐다.
  *
- * 설계: git 을 쓰지 않는다. iteration 마다 테스트 파일의 **지문**을 떠서 직전 회차와 비교한다.
+ * 설계: 지문 비교는 git 을 쓰지 않는다. iteration 마다 테스트 파일의 **지문**을 떠서 직전 회차와
+ * 비교한다. (아래 유령 테스트 검출만 추적 목록을 필요로 하는데, 그것도 이 모듈이 git 을 부르지
+ * 않고 호출부가 이미 갖고 있는 목록을 인자로 받는다 — 이 파일은 여전히 순수하다.)
  * - git 저장소가 아니어도 동작한다 (fail-open 예외 처리가 통째로 필요 없다).
  * - 기준선이 HEAD 가 아니라 **직전 iteration** 이라, 실행 시작 시점의 더러운 워킹트리가
  *   오탐을 만들지 않는다. 재는 것은 정확히 "이 루프가 테스트를 약화시켰는가"다.
@@ -118,6 +120,33 @@ export function compareFingerprints(before, after) {
   return { ok: violations.length === 0, violations };
 }
 
+/**
+ * 유령 테스트 (L13) — 디스크에는 있는데 git 이 모르는 테스트 파일.
+ *
+ * 위 지문 비교는 파일을 **디스크에서** 읽는다. 그래서 에이전트가 테스트를 `.gitignore` 된
+ * 경로에 쓰거나 `tests/` 를 `.gitignore` 에 추가해버리면, 지문은 완벽하고 exit code 는
+ * 초록불인데 **사용자의 CI 에는 테스트가 하나도 없다.** 체크포인트(L3)로도 복구할 수 없다 —
+ * `git stash create` 가 담는 것은 git 이 아는 파일뿐이기 때문이다.
+ * L1 이 지키려던 바로 그 실패를, L1 이 보지 않는 문으로 통과시킨다.
+ *
+ * bkit 은 이걸 CI 하드 게이트로 갖고 있다(`scripts/check-test-tracking.js:92-112`,
+ * `git ls-files` 집합과의 차집합 → exit 1). 실제로 v2.1.14~v2.1.16 릴리스에서 CI 가
+ * 참조하는 테스트 파일이 추적되지 않은 채 나간 사고의 재발 방지책이다.
+ *
+ * 이건 **측정**이므로 fail-closed 다(통과로 인정하지 않는다). 다만 추적 목록 자체를
+ * 못 얻으면(비-git) 관측 불가이므로 조용히 빈 배열 — 인프라는 fail-open.
+ */
+export function detectUntrackedTests(testFiles, trackedFiles) {
+  if (!Array.isArray(trackedFiles) || !Array.isArray(testFiles)) return [];
+  const tracked = new Set(trackedFiles);
+  return testFiles.filter((f) => !tracked.has(f));
+}
+
+/** 유령 테스트를 위반 문장으로. 차단은 대안과 함께 배송한다(bkit). */
+export function untrackedMessage(file) {
+  return `${file}: 테스트 파일이 git 에 추적되지 않는다 — CI 는 이 테스트를 보지 못하고 롤백으로도 복구되지 않는다. \`git add ${file}\` 로 추적에 넣어라(.gitignore 에 걸려 있다면 그 규칙을 고쳐라).`;
+}
+
 /** 위반을 에이전트에게 들이밀 텍스트로. 차단은 대안과 함께 배송한다(bkit). */
 export function violationMessage(violations) {
   return [

package/src/loop.js

@@ -14,7 +14,9 @@ import { saveState, statePathFor, resumeOrCreate, reportGaps } from './state.js'
 import { makeAgentRunner, makeTestRunner } from './runners.js';
 import { makeIntegrityChecker } from './integrity.js';
 import { acquireLock } from './lock.js';
-import { makeCheckpointer, makeFileLister } from './checkpoint.js';
+import { makeCheckpointer, makeFileLister, makeChangeLister } from './checkpoint.js';
+import { makeTreeKeyReader } from './treekey.js';
+import { makeOutcome } from './outcome.js';
 import { makeSpecVerifier } from './verify.js';
 import { makeNotifier } from './telegram.js';
 import { makeShipper, makeWatcher, WATCH_DEFAULTS } from './ship.js';
@@ -35,7 +37,6 @@ export const POST_BUILD_STAGES = ['CODE_REVIEW', 'SHIP', 'WATCH'];
 /**
  * 얇은 락 래퍼 (L4). 같은 cwd 에서 두 루프가 상태를 덮어쓰지 못하게 배타를 강제한다.
  * body 는 return 지점이 여럿이라 여기서 한 번 감싸 finally 로 확실히 푼다.
- * acquireLock 은 테스트를 위해 주입 가능하다.
  */
 export async function runLoop(opts = {}) {
   const cwd = opts.cwd ?? process.cwd();
@@ -56,6 +57,8 @@ async function runLoopBody({
   budgetUsd = null,
   stagnationLimit = 3,
   verifySpec = false,
+  flakyProbe = false,
+  checks = null,
   handoffEvery = 4,
   // ---- 라이프사이클 (FR-13, FR-14) ----
   shipCommand = null,
@@ -83,6 +86,8 @@ async function runLoopBody({
   integrityChecker = makeIntegrityChecker(),
   checkpointer = makeCheckpointer(),
   fileLister = makeFileLister(),
+  changeLister = makeChangeLister(),
+  treeKeyReader = makeTreeKeyReader(),
   specVerifier = makeSpecVerifier(),
   codeReviewer = makeCodeReviewer(),
   designReviewer = makeDesignReviewer(),
@@ -129,22 +134,11 @@ async function runLoopBody({
   // null 이면 비-git — 관측 자체가 불가능하니 아래에서 조용히 건너뛴다(인프라 fail-open).
   const baselineFiles = await fileLister({ cwd });
 
-  /** 완료 보고는 한 곳에서만 만든다. stage 가 늘어도 Gaps 공개 지점은 하나여야 한다. */
-  const finish = async (status, { stopReason = null, detail = '' } = {}) => {
-    state.status = status;
-    state.phase = 'DONE';
-    state.stage = 'DONE';
-    if (stopReason) state.stopReason = stopReason;
-    const saved = saveState(statePath, state);
-    await notify({ type: status === 'passed' ? 'passed' : 'failed', iteration: state.iteration, detail });
-    // Gaps 는 passed 에만 붙인다. false green 이 조용히 지나가는 지점이 거기이기 때문이다.
-    // 실패는 stopReason 만으로 이미 정직하다 — 거기에 Gaps 를 얹으면 소음이다.
-    if (status !== 'passed') return { status, iterations: state.iteration, state: saved };
-    const gaps = reportGaps(saved);
-    logger(gaps);
-    return { status, iterations: state.iteration, state: saved, report: gaps };
-  };
-
+  const { finish, stopResult, pauseResult } = makeOutcome({
+    getState: () => state,
+    setState: (v) => { state = v; },
+    statePath, cwd, logger, notify, treeKeyReader,
+  });
 
   /**
    * 단계 기본값 (FR-17) — 조용히 비용을 얹지 않는다.
@@ -172,29 +166,15 @@ async function runLoopBody({
   const gate = ({ stage, question, options, required = true }) => {
     const answered = [...(state.answers ?? [])].reverse().find((a) => a.stage === stage);
     if (answered) return { pause: false, choice: answered.choice, note: answered.note };
-    if (!shouldAsk({ policy: askPolicy, required }) || yes) return { pause: false, choice: null };
+    // `--yes` 는 **명시적 포괄 승인**이므로 승인('a')으로 친다.
+    // `--ask never` 는 "답할 사람이 없다"일 뿐 승인이 아니다 — null 을 돌려주고,
+    // 비가역 행위 쪽에서 그걸 거절로 해석한다. 되돌릴 수 있는 지점은 종전대로 진행한다.
+    if (yes) return { pause: false, choice: 'a' };
+    if (!shouldAsk({ policy: askPolicy, required })) return { pause: false, choice: null };
     state = pauseForAsk(state, createAsk({ stage, question, options }));
     return { pause: true };
   };
 
-  const pauseResult = () => {
-    const saved = saveState(statePath, state);
-    logger(formatAsk(state.ask));
-    return { status: 'awaiting', iterations: state.iteration, state: saved, ask: state.ask };
-  };
-
-  /**
-   * `--stop-after` 로 멈춘 결과. 실패가 아니다 — 시킨 것을 다 했을 뿐이다.
-   * status 를 passed 로 하면 "테스트가 통과했다"는 거짓말이 되므로 별도 값을 쓴다.
-   */
-  const stopResult = (stage) => {
-    state.status = 'stopped';
-    state.stopReason = `stop-after:${stage}`;
-    const saved = saveState(statePath, state);
-    logger(`[hi-loop] ⏹ ${stage} 까지 진행하고 멈췄습니다 (--stop-after).`);
-    return { status: 'stopped', iterations: state.iteration, state: saved, stoppedAt: stage };
-  };
-
   /** 방금 끝낸 stage 가 정지 지점인가. 다음 stage 로 넘어가기 직전에만 묻는다. */
   const shouldStopAfter = (stage) => stopAfter === stage;
 
@@ -230,6 +210,8 @@ async function runLoopBody({
       integrityChecker,
       checkpointer,
       fileLister,
+      changeLister,
+      treeKeyReader,
       specVerifier,
     },
     opts: {
@@ -246,6 +228,8 @@ async function runLoopBody({
       testCommand,
       stagnationLimit,
       verifySpec,
+      flakyProbe,
+      checks,
       handoffEvery,
       maxDesignRounds,
       stopAfter,

package/src/metrics.js

@@ -0,0 +1,140 @@
+/**
+ * 테스트 지표 파싱과 비회귀 게이트 (L11) — 판정을 불리언에서 벡터로.
+ *
+ * 문제: 이 엔진의 Tier 1 판정은 exit code 하나다. 그런데 exit 0 은 "몇 개가 통과했는가"를
+ * 말하지 않는다. 테스트 120개 통과 → 1개 통과 / 0개 실패로 붕괴해도 **exit 0 이고, passed 다.**
+ * `integrity.js` 가 이걸 막을 것 같지만 막지 못한다 — 그쪽은 파일의 지문(케이스 선언 수)을
+ * 보고, 이쪽은 **실행 결과**를 본다. 케이스를 지우지 않고도 통과 수는 무너질 수 있다
+ * (조건부 스킵, 파라미터 축소, 러너 설정 변경, import 실패로 스위트 통째 미수집).
+ *
+ * 그리고 더 중요한 사각: `integrity.js` 의 TEST_FILE_RE 는 `.test.js|.spec.ts` 계열만 안다.
+ * **Python·Go·Rust 프로젝트에서 무결성 가드는 0 이다.** 이 모듈은 파일이 아니라 러너의
+ * 표준출력을 읽으므로 언어에 무관하다 — 그 사각을 메우는 것이 이 파일의 두 번째 목적이다.
+ *
+ * 출처: moai 의 비회귀 게이트(`internal/harness/regression_gate.go:50` MetricTriple.Regressions
+ * → `applier.go:544` 회귀 시 RestoreSnapshot)와 지표 벡터 정체 판정(`internal/loop/feedback.go:43`
+ * IsImproved / `:54` IsStagnant). 둘 다 moai 에서 실제 배선된 경로다.
+ *
+ * 두 fail-safe 규칙은 moai 에서 그대로 가져온다. 이게 없으면 게이트가 오탐 기계가 된다:
+ *   1. 기준선이 없으면 절대 막지 않는다 (regression_gate.go:124-127).
+ *   2. 파싱 불가면 "의견 없음"이다 — 막지도, 통과시키지도 않는다.
+ * 즉 **측정은 fail-closed 이되, 측정의 부재는 fail-open** 이다. 지표를 못 읽는다는 이유로
+ * 루프가 죽으면 러너를 바꾼 사용자 전원이 피해자가 된다.
+ */
+
+/**
+ * 러너별 추출기. 위에서부터 시도하고 **먼저 걸리는 것이 이긴다.**
+ *
+ * 순서가 중요하다: 구체적인 포맷을 먼저 두고 일반 패턴을 뒤에 둔다. 반대로 하면
+ * jest 의 "Tests: 1 failed, 205 passed" 를 느슨한 패턴이 먼저 반쪽만 집어간다.
+ */
+const EXTRACTORS = [
+  // node:test — `ℹ pass 206` / `ℹ fail 0`
+  (t) => {
+    const p = /^\s*(?:ℹ\s*)?pass\s+(\d+)\s*$/m.exec(t);
+    const f = /^\s*(?:ℹ\s*)?fail\s+(\d+)\s*$/m.exec(t);
+    return p ? { passed: +p[1], failed: f ? +f[1] : 0 } : null;
+  },
+  // jest — `Tests:  1 failed, 205 passed, 206 total`
+  (t) => {
+    const m = /Tests:\s+(?:(\d+)\s+failed,\s*)?(?:\d+\s+skipped,\s*)?(\d+)\s+passed/.exec(t);
+    return m ? { passed: +m[2], failed: m[1] ? +m[1] : 0 } : null;
+  },
+  // vitest — `Tests  1 failed | 205 passed (206)`
+  (t) => {
+    const m = /Tests\s+(?:(\d+)\s+failed\s*\|\s*)?(\d+)\s+passed/.exec(t);
+    return m ? { passed: +m[2], failed: m[1] ? +m[1] : 0 } : null;
+  },
+  // pytest — `===== 3 failed, 12 passed in 1.20s =====`
+  (t) => {
+    const p = /(\d+)\s+passed/.exec(t);
+    const f = /(\d+)\s+failed/.exec(t);
+    return p || f ? { passed: p ? +p[1] : 0, failed: f ? +f[1] : 0 } : null;
+  },
+  // go test — 개별 결과 줄을 센다. 요약 줄이 없는 러너의 마지막 보루.
+  (t) => {
+    const p = (t.match(/^\s*--- PASS:/gm) ?? []).length;
+    const f = (t.match(/^\s*--- FAIL:/gm) ?? []).length;
+    return p + f > 0 ? { passed: p, failed: f } : null;
+  },
+  // TAP — `# pass 12` / `# fail 0`
+  (t) => {
+    const p = /^#\s*pass\s+(\d+)/m.exec(t);
+    const f = /^#\s*fail\s+(\d+)/m.exec(t);
+    return p ? { passed: +p[1], failed: f ? +f[1] : 0 } : null;
+  },
+];
+
+/**
+ * 러너 출력에서 `{passed, failed}` 를 뽑는다. 못 읽으면 **null** — 0 이 아니다.
+ * 이 구분이 게이트 전체를 떠받친다. 0 을 돌려주면 "전부 사라졌다"는 회귀로 오독된다.
+ */
+export function parseMetrics(text) {
+  if (typeof text !== 'string' || !text) return null;
+  for (const extract of EXTRACTORS) {
+    let got;
+    try {
+      got = extract(text);
+    } catch {
+      continue; // 추출기 하나가 죽어도 다음으로 넘어간다 — 인프라는 fail-open.
+    }
+    if (got && Number.isFinite(got.passed) && Number.isFinite(got.failed)) return got;
+  }
+  return null;
+}
+
+/**
+ * 기준선 대비 후퇴한 차원의 이름들. 빈 배열이면 회귀 없음.
+ *
+ * **통과 수 감소만 회귀로 친다.** 실패 수 증가는 어차피 exit code 가 잡으므로 여기서
+ * 또 세면 같은 사실을 두 번 벌하는 셈이고, 무엇보다 "고치는 중이라 실패가 잠깐 는다"는
+ * 정상 경로를 막아버린다. 이 게이트가 겨냥하는 것은 정확히 하나다 —
+ * **초록불인데 측정 범위가 쪼그라든 경우.**
+ */
+export function regressions(base, candidate) {
+  if (!base || !candidate) return []; // 기준선 없음 = 절대 막지 않는다 (fail-safe 1)
+  const out = [];
+  if (candidate.passed < base.passed) out.push('passed');
+  return out;
+}
+
+/**
+ * 다음 기준선. **무결성이 깨끗하고** 회귀가 없을 때만 올린다.
+ *
+ * `integrityOk` 조건이 빠지면 두 가드가 서로를 무력화한다(실측으로 재현했다):
+ *   · 가짜 단언 60개를 주입한 회차는 무결성 위반으로 차단되지만, 출력은 `pass 260` 이고
+ *     회귀도 아니므로 기준선이 260 으로 오염된다.
+ *   · 다음 회차에 에이전트가 지시대로 가짜를 걷어내면 `pass 200` 이 되고, 이번엔
+ *     **비회귀 게이트가 그 정직한 수정을 차단**한다.
+ * 그러면 엔진이 받아들이는 유일한 상태가 "가짜를 유지한 상태"다 — 무결성 가드가 벌하는
+ * 바로 그 보상 해킹을 비회귀 가드가 보상하게 된다. 정직한 수정을 막는 게이트는 게이트가 아니다.
+ */
+export function nextBaseline(current, metrics, { integrityOk, regressed }) {
+  return metrics && integrityOk && !(regressed ?? []).length ? metrics : current;
+}
+
+/** 이번 회차가 직전보다 나아졌는가. 하나라도 좋아지면 참이다. */
+export function isImproved(prev, curr) {
+  if (!prev || !curr) return false;
+  return curr.failed < prev.failed || curr.passed > prev.passed;
+}
+
+/** 지표 벡터가 완전히 동일한가 = 이번 회차가 아무것도 바꾸지 못했다. */
+export function isSameMetrics(prev, curr) {
+  if (!prev || !curr) return false;
+  return prev.passed === curr.passed && prev.failed === curr.failed;
+}
+
+/** 회귀를 에이전트에게 들이밀 텍스트로. 차단은 대안과 함께 배송한다(bkit). */
+export function regressionMessage(base, candidate, regressed) {
+  return [
+    '[hi-loop] 비회귀 게이트 위반 — 테스트는 초록불이지만 통과로 인정하지 않는다.',
+    `- 통과 수가 ${base.passed}개 → ${candidate.passed}개로 줄었다 (실패 ${base.failed} → ${candidate.failed}).`,
+    `- 후퇴한 차원: ${regressed.join(', ')}`,
+    '',
+    '초록불은 "테스트가 통과했다"는 뜻이지 "측정 범위가 그대로다"라는 뜻이 아니다.',
+    '테스트가 수집되지 않거나 조건부로 건너뛰어져 통과 수가 줄면 exit 0 이 나온다.',
+    '사라진 테스트가 다시 실행되도록 되돌린 뒤, 구현을 고쳐서 통과시켜라.',
+    '테스트를 정말 지워야 한다면 왜인지 근거를 남기고 같은 범위를 덮는 것으로 교체하라.',
+  ].join('\n');
+}