@tuzi-ince/hi-loop 0.1.1

package/README.md

@@ -0,0 +1,175 @@
+# hi-loop
+
+**CLI와 MCP 모드를 지원하는 초경량 자율형 자가 치유 엔진.**
+
+날것의 아이디어(goal)를 던지면, AI 에이전트를 PDCA 루프로 반복 구동해
+**테스트가 실제로 통과할 때까지** 스스로 고쳐 나간다.
+- 요구사항(무엇을): [`docs/spec.md`](docs/spec.md)
+- 설계(어떻게·왜): [`docs/design.md`](docs/design.md)
+- 배포·설치·사용: [`docs/guide.md`](docs/guide.md)
+
+> 현재 상태: 실제 `claude`(2.1.212) 와의 통합 **검증 완료** — 편집 권한, 세션 재개,
+> 전체 루프, 예산 상한을 실측했다([`docs/design.md`](docs/design.md) §10).
+> 아직 안 본 것도 그 표에 적어뒀다(핸드오프 실측, MCP 모드 실제 spawn, 10회 장시간 루프).
+
+## 설치
+
+> ⚠️ `npm install -g handoff` 를 하지 마라. npm 의 `handoff` 는 이 프로젝트와 무관한
+> **제3자의 redis 래퍼 패키지**다. 이름만 같다. 아직 미배포이므로 소스에서 설치한다.
+
+```bash
+git clone <이 저장소> hi-loop && cd hi-loop
+npm install && npm test   # 104개 통과
+npm link                  # hi-loop / hi-loop-setup 명령 등록
+
+cd /path/to/my-project
+hi-loop-setup            # .mcp.json / .gitignore / docs / tests 자동 주입 (멱등)
+```
+
+자세한 절차·문제해결·배포는 [`docs/guide.md`](docs/guide.md).
+
+## 두 가지 실행 모드
+
+```bash
+# 1) CLI 직접 실행 — 터미널, 백그라운드 데몬, 텔레그램 봇에서 구동
+hi-loop run --goal "JWT 인증 미들웨어를 만들어라" --test "npm test" --max-loops 10 --budget-usd 5
+
+# 2) MCP 서버 — 클로드코드/커서가 도구로 로드 (인자 없으면 기본 동작)
+hi-loop mcp
+
+hi-loop status           # 현재 루프 상태 요약
+```
+
+MCP 도구: `hiloop_run`, `hiloop_status`, `hiloop_reset`.
+
+## 동작 원리
+
+```
+PLAN  ──► spec.md + tests/app.test.js 를 먼저 강제 (구현 코드 금지)
+DO    ──► 테스트를 통과시킬 최소 구현
+CHECK ──► 엔진이 testCommand 를 직접 실행 (에이전트의 "다 됐어요"는 안 믿는다)
+ACT   ──► stderr 를 그대로 에이전트에 들이밀고 "이 에러를 고쳐라" (최대 10회)
+```
+
+### 세션 핸드오프 & 컨텍스트 다이어트 (bkit 철학)
+
+에이전트는 같은 세션에서 오래 굴릴수록 토큰이 쌓여 멍청해진다.
+그래서 4회마다 세션을 **버리고**, `.agent-state.json`에 압축된 상태
+(goal / 스펙 요약 / 마지막 에러 / 최근 이력 5건)만 새 세션에 넘겨 이어서 작업한다(auto-resume).
+같은 goal로 다시 실행하면 중단 지점부터 재개한다.
+
+### TDD 자가 치유 (MoAI 철학)
+
+성패 판정은 항상 `testCommand`의 exit code다. 에이전트의 자기보고는 판정에 쓰지 않는다.
+
+### 💸 비용은 엔진이 센다 — 그리고 싸지 않다
+
+**실측**: "두 수를 더하는 add 함수를 만들어라"가 2회차에 통과하는 데 **$2.58~$4.67**
+(claude-opus-4-8). 같은 goal·같은 회차인데 컨텍스트 크기 때문에 1.8배 갈렸다.
+새 세션은 일을 안 시켜도 바닥값이 ~$0.43이다(캐시 생성).
+
+**`--max-loops`는 비용 상한이 아니다.** 실패 루프가 10회를 다 쓰면 $20을 넘길 수 있다.
+그래서 `--budget-usd`를 쓴다 — 누적이 상한에 닿으면 **다음 에이전트 호출 전에** 멈춘다
+(이미 쓴 돈은 못 돌리니 할 수 있는 건 더 안 쓰는 것뿐이다).
+
+```bash
+hi-loop run --goal "..." --max-loops 5 --budget-usd 1 --no-stagnation
+# [hi-loop] 💸 예산 $1 소진 (누적 $1.61) — 2회차에서 중단합니다.
+```
+
+`hi-loop status`와 완료 로그에 누적 비용이 찍힌다. 모델은 사용자 기본값을 상속하므로
+`HILOOP_AGENT_ARGS="--model sonnet"`으로 낮출 수 있다.
+
+### 기존 파일을 덮어쓰지 않는다
+
+PLAN 산출물 경로는 **엔진이 정한다.** `docs/spec.md`/`tests/app.test.js`가 비어 있으면
+그대로 쓰고, 이미 뭔가 있으면 goal 해시로 비켜간다(`docs/spec-5d88cc7f.md`).
+같은 프로젝트에서 goal만 바꿔 두 번 돌려도 앞의 산출물이 살아남는다.
+
+### 테스트를 지워서 통과하는 것을 막는다 (bkit 철학)
+
+CHECK는 2단이다 — `check.ok && integrity.ok`여야 통과. 판정 기준인 테스트를 에이전트가
+지우거나 skip/always-true로 무력화하면 exit 0이 나와도 **통과로 인정하지 않는다.**
+탐지 패턴(케이스 감소, `.skip`, `.only`, `assert.ok(true)`)은 bkit gap-detector의
+가짜 완료 분류학에서 가져왔다. 테스트 **추가**는 위반이 아니다.
+
+### 같은 벽에 열 번 부딪히지 않는다
+
+같은 실패가 3회 연속이면 `stopReason: 'stagnated'`로 조기 종료한다 — "이 접근으론 안 된다"를
+`--max-loops` 소진 전에 잡는다. `--stagnation N` 으로 조절, `--no-stagnation` 으로 끈다.
+
+### 통과가 무엇을 확인 안 했는지 공개한다 (MoAI 철학)
+
+이 엔진의 `passed`는 조용한 거짓말이 될 수 있다 — 테스트를 PLAN 단계에서 **에이전트 자신이**
+썼기 때문이다. 그래서 통과할 때마다 Evidence와 Gaps를 함께 출력한다:
+
+```
+관측하지 않은 것(Gaps):
+- 이 테스트는 에이전트 자신이 작성했다. 외부 오라클이 아니다.
+- 스펙의 어떤 수용 기준이 커버 안 됐는지는 검증하지 않았다.
+- 런타임·성능·보안은 관측 범위 밖이다.
+```
+
+moai의 5-섹션 보고 규약에서 왔다. false green을 disclosed green으로 바꾼다.
+
+### 망가뜨려도 되돌린다 (bkit 철학)
+
+각 에이전트 호출 **전에** `git stash create`로 워킹트리를 스냅샷한다(비파괴 — 워킹트리를
+안 건드리고 SHA만 남긴다). 에이전트가 멀쩡한 코드를 망가뜨리면:
+
+```bash
+hi-loop rollback            # 최신 체크포인트로 파일 복원
+hi-loop rollback --to 3     # 3회차 직전 상태로
+```
+
+**자동 롤백은 없다** — 전경 실행이 기본이라 사람이 본다(bkit도 자동 되돌리기를 무인 L4에만
+건다). git 저장소가 아니면 조용히 생략한다.
+
+### 스펙을 오라클로 — 2단 판정 (bkit 중심 명제)
+
+`--verify-spec`을 켜면 테스트 통과 후 **별도 검증자**가 스펙 대비 구현을 심판한다.
+이 엔진의 exit 0은 "에이전트가 자기가 쓴 테스트를 통과시켰다"일 뿐이므로:
+
+- **Tier 1 (기계)**: exit code + 무결성. 최종 권한. 실패면 끝.
+- **Tier 2 (모델)**: 스펙 대조. **오직 기각만 가능** — 통과를 되돌릴 순 있어도
+  Tier 1 실패를 통과로 못 올린다. 쓰기 권한 없이(`--permission-mode plan`) 새 세션으로 호출.
+
+**실측**: 스펙이 "음수는 TypeError"를 요구하는데 테스트는 양수만 검사하고 구현이
+`(a,b)=>a+b`인 경우 — 테스트는 초록이었지만 검증자가 *"add(-1,2)는 예외 대신 1을
+반환한다"*고 정확히 기각했다. 구조가 아니라 의도를 본다. opt-in(비용 증가).
+
+## 환경변수
+
+| 변수 | 설명 |
+|---|---|
+| `HILOOP_AGENT_CMD` | 에이전트 실행 명령 (기본 `claude`) |
+| `HILOOP_AGENT_ARGS` | 에이전트에 덧붙일 인자 (공백 구분). 예: `--model sonnet` — 비용에 직결된다 |
+| `HILOOP_PERMISSION_MODE` | 권한 모드 (기본 `acceptEdits`). 편집 허용이 이 엔진의 전제다 |
+| `HILOOP_VERIFY_CMD` / `HILOOP_VERIFY_MODEL` | `--verify-spec` 검증자의 실행 명령·모델 (미설정 시 구현자와 동일). bkit처럼 검증에 더 센 모델을 쓸 수 있다 |
+| `HILOOP_AGENT_TIMEOUT_MS` / `HILOOP_TEST_TIMEOUT_MS` | 에이전트(30분)·테스트(10분) 타임아웃. 쓰레기값은 기본값으로 되돌림 |
+| `TELEGRAM_BOT_TOKEN` / `TELEGRAM_CHAT_ID` | 시작/핸드오프/성공/실패 알림. 미설정 시 조용히 생략 |
+
+## 개발
+
+```bash
+npm test        # node:test, devDependency 0개
+```
+
+## 구조
+
+```
+bin/hi-loop.js    CLI 엔트리포인트 (CLI / MCP 분기 + rollback)
+bin/setup.js       프로젝트·클로드코드 설정 자동 주입
+src/loop.js        자가 치유 오케스트레이션 루프 + 예산·정체·2단 판정·락·삭제 관측 집행
+src/state.js       .agent-state.json (원자적 저장 + 다이어트 + 산출물 경로 + resume + Gaps)
+src/runners.js     에이전트/테스트 실행 어댑터 (주입 가능) + 비용 파싱 + 타임아웃 (L6)
+src/prompts.js     PDCA 단계별 프롬프트 + 검증자 프롬프트
+src/integrity.js   테스트 무결성 지문·비교 — 보상 해킹 방어 (L1)
+src/checkpoint.js  git stash 체크포인트·롤백 (L3) + 삭제 관측 (L8)
+src/verify.js      스펙 오라클 — Tier 2 검증자 (L9)
+src/lock.js        동시 실행 pid 락 (L4)
+src/mcp-server.js  MCP 프로토콜 통신
+src/telegram.js    텔레그램 비동기 알림
+src/args.js        의존성 없는 인자 파서
+src/is-main.js     "직접 실행인가?" 판정 (심링크 안전)
+```

package/bin/hi-loop.js

@@ -0,0 +1,164 @@
+#!/usr/bin/env node
+/**
+ * CLI 엔트리포인트 (FR-1) — CLI Command 와 MCP Server 분기 처리
+ *
+ *   hi-loop run --goal "..." [--test "npm test"] [--max-loops 10] [--cwd .]
+ *   hi-loop mcp        (인자 없으면 기본값)
+ *   hi-loop status
+ *   hi-loop setup
+ */
+import { readFileSync } from 'node:fs';
+import { resolve, dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parseArgs } from '../src/args.js';
+import { isMain } from '../src/is-main.js';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+
+function pkgVersion() {
+  try {
+    return JSON.parse(readFileSync(join(HERE, '..', 'package.json'), 'utf8')).version;
+  } catch {
+    return '0.0.0';
+  }
+}
+
+const USAGE = `hi-loop — 초경량 자율형 자가 치유 엔진
+
+사용법:
+  hi-loop run --goal "<요구사항>" [--test "npm test"] [--max-loops 10] [--budget-usd 5]
+               [--stagnation 3 | --no-stagnation] [--verify-spec] [--cwd .]
+  hi-loop mcp                      MCP 서버(stdio)로 기동. 인자가 없으면 기본 동작.
+  hi-loop status [--cwd .]         현재 루프 상태 요약
+  hi-loop rollback [--to N] [--cwd .]  N회차 직전 체크포인트로 파일 복원 (기본: 최신)
+  hi-loop setup [--dry-run]        프로젝트/클로드코드 설정 자동 주입
+  hi-loop --help | --version
+
+환경변수:
+  HILOOP_AGENT_CMD        에이전트 실행 명령 (기본: claude)
+  HILOOP_AGENT_ARGS       에이전트에 덧붙일 인자 (공백 구분, 예: --model sonnet)
+  HILOOP_PERMISSION_MODE  권한 모드 (기본: acceptEdits)
+  HILOOP_VERIFY_CMD/MODEL --verify-spec 검증자의 실행 명령·모델 (기본: 구현자와 동일)
+  HILOOP_AGENT_TIMEOUT_MS 에이전트 타임아웃 (기본: 1800000 = 30분)
+  HILOOP_TEST_TIMEOUT_MS  테스트 타임아웃 (기본: 600000 = 10분)
+  TELEGRAM_BOT_TOKEN/CHAT_ID 텔레그램 알림 (미설정 시 생략)`;
+
+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'],
+  });
+  const command = args._[0] ?? (args.help || args.version ? null : 'mcp');
+
+  if (args.version) {
+    process.stdout.write(`${pkgVersion()}\n`);
+    return 0;
+  }
+  if (args.help || command === 'help') {
+    process.stdout.write(`${USAGE}\n`);
+    return 0;
+  }
+
+  const cwd = resolve(args.cwd ?? process.cwd());
+
+  switch (command) {
+    case 'run': {
+      if (!args.goal || args.goal === true) {
+        process.stderr.write(`--goal 이 필요합니다.\n\n${USAGE}\n`);
+        return 2;
+      }
+      const { runLoop } = await import('../src/loop.js');
+      const maxLoops = Number(args['max-loops'] ?? 10);
+      // 예산은 명시할 때만 건다. 잘못된 값으로 조용히 무제한이 되지 않도록 exit 2 로 거른다.
+      const budgetRaw = args['budget-usd'];
+      let budgetUsd = null;
+      if (budgetRaw !== undefined && budgetRaw !== true) {
+        budgetUsd = Number(budgetRaw);
+        if (!(Number.isFinite(budgetUsd) && budgetUsd > 0)) {
+          process.stderr.write(`--budget-usd 는 0 보다 큰 숫자여야 합니다: ${budgetRaw}\n`);
+          return 2;
+        }
+      }
+      // 정체 상한: --no-stagnation 으로 끄거나 --stagnation N 으로 조절. 기본 3.
+      let stagnationLimit = 3;
+      if (args['no-stagnation']) stagnationLimit = null;
+      else if (args.stagnation !== undefined && args.stagnation !== true) {
+        const n = Number(args.stagnation);
+        if (!(Number.isInteger(n) && n > 0)) {
+          process.stderr.write(`--stagnation 은 1 이상의 정수여야 합니다: ${args.stagnation}\n`);
+          return 2;
+        }
+        stagnationLimit = n;
+      }
+      const result = await runLoop({
+        goal: String(args.goal),
+        testCommand: args.test && args.test !== true ? String(args.test) : 'npm test',
+        maxLoops: Number.isInteger(maxLoops) && maxLoops > 0 ? maxLoops : 10,
+        budgetUsd,
+        stagnationLimit,
+        verifySpec: Boolean(args['verify-spec']),
+        cwd,
+        logger: (line) => process.stdout.write(`${line}\n`),
+      });
+      return result.status === 'passed' ? 0 : 1;
+    }
+    case 'mcp': {
+      const { startMcpServer } = await import('../src/mcp-server.js');
+      await startMcpServer({ version: pkgVersion() });
+      return null; // 서버는 계속 살아 있는다.
+    }
+    case 'status': {
+      const { loadState, statePathFor, summarizeState } = await import('../src/state.js');
+      process.stdout.write(`${summarizeState(loadState(statePathFor(cwd)))}\n`);
+      return 0;
+    }
+    case 'rollback': {
+      const { loadState, statePathFor } = await import('../src/state.js');
+      const { rollbackTo } = await import('../src/checkpoint.js');
+      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`);
+      if (res.safetySha) process.stdout.write(`   되돌리기 전 상태는 ${res.safetySha.slice(0, 8)} 에 스냅샷됨.\n`);
+      return 0;
+    }
+    case 'setup': {
+      const { runSetup } = await import('./setup.js');
+      const report = runSetup({ cwd, dryRun: Boolean(args['dry-run']) });
+      process.stdout.write(`${report.lines.join('\n')}\n`);
+      return 0;
+    }
+    default:
+      process.stderr.write(`알 수 없는 명령: ${command}\n\n${USAGE}\n`);
+      return 2;
+  }
+}
+
+if (isMain(import.meta.url)) {
+  main()
+    .then((code) => {
+      if (code !== null && code !== undefined) process.exit(code);
+    })
+    .catch((err) => {
+      process.stderr.write(`[hi-loop] 치명적 오류: ${err?.stack ?? err}\n`);
+      process.exit(1);
+    });
+}

package/bin/setup.js

@@ -0,0 +1,115 @@
+#!/usr/bin/env node
+/**
+ * 클로드코드 및 프로젝트 설정을 자동 주입하는 스크립트 (FR-6)
+ * 멱등하며, 기존 설정을 파괴하지 않고 병합한다.
+ */
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
+import { join, resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parseArgs } from '../src/args.js';
+import { isMain } from '../src/is-main.js';
+
+export const MCP_SERVER_KEY = 'hi-loop';
+export const GITIGNORE_ENTRY = '.agent-state.json';
+// 런타임 부산물 — 커밋되면 안 된다. 락(L4)은 pid 마다 다르고, 상태는 캐시다.
+export const GITIGNORE_ENTRIES = ['.agent-state.json', '.agent-state.lock'];
+
+/** 이 setup 파일과 나란히 있는 실제 CLI 진입점의 절대 경로 */
+export function cliEntryPath() {
+  return join(dirname(fileURLToPath(import.meta.url)), 'hi-loop.js');
+}
+
+/**
+ * ⚠️ `npx -y handoff mcp` 를 쓰면 안 된다. 무스코프 `handoff` 는 이 프로젝트와
+ * 무관한 제3자의 redis 래퍼 패키지이고, npx 는 그것을 받아 실행해버린다.
+ * (이 패키지의 이름은 @tuzi-ince/hi-loop 다.)
+ * 그래서 지금 실행 중인 바로 이 설치본의 절대 경로를 박아 넣는다.
+ * 배포 후에는 `npx -y @tuzi-ince/hi-loop mcp` 로 바꿀 수 있다 — 스코프를 반드시 붙일 것.
+ */
+export const serverEntry = (entry = cliEntryPath()) => ({
+  command: process.execPath,
+  args: [entry, 'mcp'],
+});
+
+function readJson(path) {
+  try {
+    return JSON.parse(readFileSync(path, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/** `.mcp.json` 병합 — 기존 서버 항목 보존 (FR-6.1, FR-6.4) */
+export function mergeMcpConfig(existing) {
+  const base = existing && typeof existing === 'object' ? existing : {};
+  const servers = base.mcpServers && typeof base.mcpServers === 'object' ? base.mcpServers : {};
+  return { ...base, mcpServers: { ...servers, [MCP_SERVER_KEY]: serverEntry() } };
+}
+
+/** `.gitignore` 항목 추가 — 중복 없이 (FR-6.2) */
+export function mergeGitignore(content) {
+  let text = typeof content === 'string' ? content : '';
+  const has = () => text.split('\n').map((l) => l.trim());
+  let changed = false;
+  for (const entry of GITIGNORE_ENTRIES) {
+    if (has().includes(entry)) continue;
+    const prefix = text.length && !text.endsWith('\n') ? '\n' : '';
+    text = `${text}${prefix}${entry}\n`;
+    changed = true;
+  }
+  return { changed, content: text };
+}
+
+export function runSetup({ cwd = process.cwd(), dryRun = false } = {}) {
+  const root = resolve(cwd);
+  const lines = [];
+  const changes = [];
+  const write = (path, content) => {
+    if (!dryRun) writeFileSync(path, content, 'utf8');
+  };
+
+  // 1) .mcp.json
+  const mcpPath = join(root, '.mcp.json');
+  const before = readJson(mcpPath);
+  const merged = mergeMcpConfig(before);
+  const mcpChanged = JSON.stringify(before) !== JSON.stringify(merged);
+  if (mcpChanged) {
+    write(mcpPath, `${JSON.stringify(merged, null, 2)}\n`);
+    changes.push('.mcp.json');
+    lines.push(`${dryRun ? '[dry-run] ' : ''}✓ .mcp.json 에 hi-loop MCP 서버를 등록했습니다.`);
+  } else {
+    lines.push('· .mcp.json 은 이미 최신입니다.');
+  }
+
+  // 2) .gitignore
+  const giPath = join(root, '.gitignore');
+  const gi = mergeGitignore(existsSync(giPath) ? readFileSync(giPath, 'utf8') : '');
+  if (gi.changed) {
+    write(giPath, gi.content);
+    changes.push('.gitignore');
+    lines.push(`${dryRun ? '[dry-run] ' : ''}✓ .gitignore 에 ${GITIGNORE_ENTRY} 를 추가했습니다.`);
+  } else {
+    lines.push(`· .gitignore 에 ${GITIGNORE_ENTRY} 가 이미 있습니다.`);
+  }
+
+  // 3) docs/, tests/ 보장
+  for (const dir of ['docs', 'tests']) {
+    const p = join(root, dir);
+    if (!existsSync(p)) {
+      if (!dryRun) mkdirSync(p, { recursive: true });
+      changes.push(`${dir}/`);
+      lines.push(`${dryRun ? '[dry-run] ' : ''}✓ ${dir}/ 디렉터리를 만들었습니다.`);
+    } else {
+      lines.push(`· ${dir}/ 이미 존재합니다.`);
+    }
+  }
+
+  lines.push('', '이제 사용하세요:', '  hi-loop run --goal "요구사항" --test "npm test"', '  또는 에이전트에서 MCP 도구 hiloop_run 호출');
+  return { changes, lines, dryRun };
+}
+
+if (isMain(import.meta.url)) {
+  const args = parseArgs(process.argv.slice(2), { alias: { c: 'cwd' }, boolean: ['dry-run'] });
+  const report = runSetup({ cwd: args.cwd ?? process.cwd(), dryRun: Boolean(args['dry-run']) });
+  process.stdout.write(`${report.lines.join('\n')}\n`);
+}