@tuzi-ince/hi-loop 0.1.2 → 0.2.0

package/src/state.js

@@ -7,18 +7,34 @@ import { readFileSync, writeFileSync, renameSync, existsSync, rmSync } from 'nod
 import { join, dirname } from 'node:path';
 import { createHash } from 'node:crypto';
 
-export const STATE_VERSION = 1;
+// 사람이 읽는 보고(Gaps 공개·상태 요약)는 report.js 로 뺐다. 기존 import 경로를
+// 깨지 않도록 여기서 다시 내보낸다 — 호출부가 어느 파일에서 오는지 알 필요는 없다.
+export { reportGaps, summarizeState } from './report.js';
+
+export const STATE_VERSION = 2;
 export const STATE_FILENAME = '.agent-state.json';
 
 export const DEFAULT_SPEC_PATH = 'docs/spec.md';
 export const DEFAULT_TEST_PATH = 'tests/app.test.js';
 
+/**
+ * 라이프사이클 위치 (FR-10~14). `phase` 와 다르다:
+ * - `phase` 는 **안쪽 루프**의 회차별 위치 (PLAN/DO/CHECK/ACT/DONE) — 의미 불변.
+ * - `stage` 는 **바깥 껍질**의 위치. BUILD 가 안쪽 루프 전체를 감싼다.
+ */
+export const STAGES = ['DISCOVER', 'BUILD', 'CODE_REVIEW', 'SHIP', 'WATCH', 'DONE'];
+
 export const LIMITS = {
   specSummary: 1200,
   lastError: 2000,
   historyKeep: 5,
   historySummary: 300,
   checkpointKeep: 10, // 최근 10개 체크포인트만 유지 (L3)
+  assumptionsKeep: 20,
+  assumptionText: 300,
+  findingsKeep: 10,
+  findingText: 300,
+  answersKeep: 10,
 };
 
 export function truncate(text, max) {
@@ -75,6 +91,14 @@ export function planPathsFor({ cwd, goal }) {
   };
 }
 
+/**
+ * DISCOVER 산출물 경로 (FR-10.1). 항상 goal 해시를 붙인다 — 기본 경로를 쓰면
+ * 남의 파일을 덮어쓸 수 있고, 같은 프로젝트에서 goal 만 바꿔 두 번 돌릴 때 서로를 파괴한다.
+ */
+export function discoveryPathFor(goal) {
+  return `docs/discovery-${createHash('sha1').update(String(goal)).digest('hex').slice(0, 8)}.md`;
+}
+
 export function createState({
   goal,
   testCommand,
@@ -90,6 +114,7 @@ export function createState({
     goal,
     testCommand,
     status: 'running',
+    stage: 'DISCOVER',   // 라이프사이클 시작점 (FR-10). --no-discover 면 엔진이 BUILD 로 건너뛴다.
     phase: 'PLAN',
     iteration: 0,
     maxLoops,
@@ -105,12 +130,58 @@ export function createState({
     stagnantRuns: 0,     // L2: errorSig 가 연속 동일한 횟수.
     checkpoints: [],     // L3: [{iteration, sha}] git stash create 스냅샷.
     deletedFiles: [],    // L8: 에이전트가 지운 baseline 파일(관측용, 누적).
+    assumptions: [],     // FR-10.2: DISCOVER/ask 가 확정한 가정. 기록 안 된 가정은 없어야 한다.
+    ask: null,           // FR-10.3/13.4: 대기 중인 질문. 있으면 status 는 'awaiting'.
+    answers: [],         // 사람이 고른 이력 [{id, choice, note, at}].
+    designRounds: 0,     // FR-11.3 상한 카운터.
+    reviewRounds: 0,     // FR-12.4 상한 카운터.
+    reviewFindings: [],  // FR-12.4: 미해결 findings. Gaps 에 공개된다.
+    discovery: null,     // FR-10: {doc, at} — 있으면 발굴이 끝났다는 표시(재개 시 재실행 방지).
+    ship: null,          // FR-13: {command, code, at}
+    watch: null,         // FR-14: {command, checks, failures, at}
     history: [],
     startedAt: now,
     updatedAt: now,
   };
 }
 
+/** v1 상태의 신규 필드 기본값. 한 곳에만 두어 createState/migrate/resume 이 갈라지지 않게 한다. */
+const V2_DEFAULTS = {
+  stage: 'BUILD',
+  assumptions: [],
+  ask: null,
+  answers: [],
+  designRounds: 0,
+  reviewRounds: 0,
+  reviewFindings: [],
+  discovery: null,
+  ship: null,
+  watch: null,
+};
+
+/**
+ * v1 → v2 승격 (제안서 §5).
+ *
+ * 그냥 STATE_VERSION 만 올리면 `loadState` 가 버전 불일치로 **null 을 반환**해서
+ * 진행 중이던 v1 루프가 조용히 버려진다. 사용자에겐 "업데이트했더니 작업이 사라졌다"다.
+ * 그래서 버리지 않고 신규 필드만 채워 올린다.
+ *
+ * stage 를 BUILD 로 두는 이유: v1 상태는 이미 PLAN(1회차)을 지났다. DISCOVER 로 되돌리면
+ * 이미 만든 스펙을 두고 발굴을 다시 하는 낭비가 된다. 통과한 상태는 DONE 이다.
+ * 미래 버전(>2)은 읽지 않는다 — 구버전이 신버전 상태를 해석하면 조용히 망가뜨린다.
+ */
+export function migrateState(prev) {
+  if (!prev || typeof prev !== 'object') return null;
+  if (prev.version === STATE_VERSION) return prev;
+  if (prev.version !== 1) return null;
+  return {
+    ...V2_DEFAULTS,
+    ...prev,
+    version: STATE_VERSION,
+    stage: prev.status === 'passed' ? 'DONE' : 'BUILD',
+  };
+}
+
 /**
  * 동일 goal 이면 auto-resume, 아니면 새 상태 (FR-3.5).
  * resume 은 상태 로직이므로 state.js 가 제자리다 — loadState/createState/planPathsFor 를 여기서 쓴다.
@@ -134,9 +205,21 @@ export function resumeOrCreate({ statePath, goal, testCommand, maxLoops, cwd })
       stagnantRuns: Number.isFinite(prev.stagnantRuns) ? prev.stagnantRuns : 0,
       checkpoints: Array.isArray(prev.checkpoints) ? prev.checkpoints : [],
       deletedFiles: Array.isArray(prev.deletedFiles) ? prev.deletedFiles : [],
+      stage: STAGES.includes(prev.stage) ? prev.stage : V2_DEFAULTS.stage,
+      assumptions: Array.isArray(prev.assumptions) ? prev.assumptions : [],
+      ask: prev.ask ?? null,
+      answers: Array.isArray(prev.answers) ? prev.answers : [],
+      designRounds: Number.isFinite(prev.designRounds) ? prev.designRounds : 0,
+      reviewRounds: Number.isFinite(prev.reviewRounds) ? prev.reviewRounds : 0,
+      reviewFindings: Array.isArray(prev.reviewFindings) ? prev.reviewFindings : [],
+      discovery: prev.discovery ?? null,
+      ship: prev.ship ?? null,
+      watch: prev.watch ?? null,
       testCommand,
       maxLoops,
-      status: 'running',
+      // 답을 안 받은 질문이 남아 있으면 재개해선 안 된다. 그냥 running 으로 덮으면
+      // 사람이 고르라던 분기를 엔진이 조용히 스스로 골라 지나간다 — ask 의 존재 이유가 사라진다.
+      status: prev.ask ? 'awaiting' : 'running',
     };
   }
   return createState({ goal, testCommand, maxLoops, cwd });
@@ -146,8 +229,9 @@ export function loadState(path) {
   if (!existsSync(path)) return null;
   try {
     const parsed = JSON.parse(readFileSync(path, 'utf8'));
-    if (!parsed || parsed.version !== STATE_VERSION) return null;
-    return parsed;
+    if (!parsed) return null;
+    // 구버전은 버리지 않고 승격한다. 못 읽는 버전만 null 이다.
+    return parsed.version === STATE_VERSION ? parsed : migrateState(parsed);
   } catch {
     return null; // 손상된 상태 파일은 무시하고 새로 시작한다.
   }
@@ -163,6 +247,16 @@ export function saveState(path, state, { now = new Date().toISOString() } = {})
       ...h,
       summary: truncate(h.summary ?? '', LIMITS.historySummary),
     })),
+    // 가정·findings 도 컨텍스트 다이어트 대상이다. 이것들은 프롬프트에 실려 나가므로
+    // 자르지 않으면 핸드오프가 압축한 만큼을 그대로 되돌려놓는다.
+    assumptions: (state.assumptions ?? []).slice(-LIMITS.assumptionsKeep).map((a) => ({
+      ...a,
+      text: truncate(a.text ?? '', LIMITS.assumptionText),
+    })),
+    reviewFindings: (state.reviewFindings ?? []).slice(-LIMITS.findingsKeep).map((f) =>
+      typeof f === 'string' ? truncate(f, LIMITS.findingText) : { ...f, text: truncate(f.text ?? '', LIMITS.findingText) },
+    ),
+    answers: (state.answers ?? []).slice(-LIMITS.answersKeep),
     updatedAt: now,
   };
   const tmp = join(dirname(path), `.${STATE_FILENAME}.${process.pid}.tmp`);
@@ -178,53 +272,3 @@ export function resetState(path) {
   }
   return false;
 }
-
-/**
- * 완료 보고: 무엇을 관측했고 무엇을 안 했는가 (L10, moai 의 5-섹션 규약 중 Evidence+Gaps).
- *
- * 이 엔진의 `passed` 는 조용한 거짓말이 될 수 있다 — 테스트를 PLAN 단계에서 에이전트
- * 자신이 썼기 때문이다. exit 0 의 실제 의미는 "에이전트가 자기가 쓴 테스트를 자기가
- * 통과시켰다"이고, 스펙의 수용 기준 중 무엇이 테스트로 커버 안 됐는지는 아무도 안 본다.
- *
- * moai: "빈 Gaps 섹션은 '관측하지 않은 것이 없다'는 강한 주장이며, 그 주장 자체가
- * 참이어야 한다." 그래서 숨기는 대신 매 완료에 공개한다. false green 을 disclosed green 으로.
- */
-export function reportGaps(state) {
-  const lines = ['', '## 검증 현황 (hi-loop 는 자기 판정의 한계를 숨기지 않는다)'];
-
-  const deleted = state.deletedFiles ?? [];
-
-  lines.push('관측한 것(Evidence):');
-  lines.push(`- ${state.testCommand} 종료 코드로 판정 (iteration ${state.iteration})`);
-  lines.push('- 테스트 파일 무결성 위반 없음 (직전 회차 대비 지문 비교)');
-  lines.push(`- 누적 비용 $${(state.costUsd ?? 0).toFixed(2)}`);
-  if (state.specVerified) lines.push('- 스펙 대비 구현을 별도 검증자가 심판(2단 판정 통과)');
-
-  lines.push('관측하지 않은 것(Gaps):');
-  lines.push(`- 이 테스트는 PLAN 단계에서 에이전트 자신이 \`${state.testPath || 'tests/app.test.js'}\`에 작성했다. 외부 오라클이 아니다.`);
-  if (!state.specVerified) {
-    lines.push(`- \`${state.specPath || 'docs/spec.md'}\`의 수용 기준 중 무엇이 테스트로 커버되지 않았는지는 검증하지 않았다(--verify-spec 로 켤 수 있다).`);
-  }
-  lines.push('- 런타임 동작·성능·보안은 관측 범위 밖이다.');
-  if (deleted.length) {
-    lines.push(`- ⚠️ 에이전트가 baseline 파일 ${deleted.length}개를 삭제했다(차단 안 함): ${deleted.slice(0, 5).join(', ')}${deleted.length > 5 ? ' …' : ''}. hi-loop rollback 으로 복원 가능.`);
-  }
-
-  return lines.join('\n');
-}
-
-export function summarizeState(state) {
-  if (!state) return '진행 중인 hi-loop 루프 상태가 없습니다.';
-  const lines = [
-    `goal: ${state.goal}`,
-    `status: ${state.status}${state.stopReason ? ` (${state.stopReason})` : ''} / phase: ${state.phase}`,
-    `iteration: ${state.iteration}/${state.maxLoops} (session #${state.sessionSerial})`,
-    `cost: $${(state.costUsd ?? 0).toFixed(2)}`,
-    ...(state.stagnantRuns > 1 ? [`stagnant: 같은 실패 ${state.stagnantRuns}회 연속`] : []),
-    `testCommand: ${state.testCommand}`,
-    `updatedAt: ${state.updatedAt}`,
-  ];
-  if (state.specSummary) lines.push(`spec: ${truncate(state.specSummary, 200)}`);
-  if (state.lastError) lines.push(`lastError: ${truncate(state.lastError, 400)}`);
-  return lines.join('\n');
-}

package/src/telegram.js

@@ -40,7 +40,7 @@ export function truncateForTelegram(text) {
   return `${s.slice(0, TELEGRAM_MAX - 1)}…`;
 }
 
-const ICON = { start: '🚀', handoff: '♻️', passed: '✅', failed: '❌', check: '🔍' };
+const ICON = { start: '🚀', handoff: '♻️', passed: '✅', failed: '❌', check: '🔍', ship: '📦', watch: '🩺' };
 
 /** 루프 이벤트를 사람이 읽을 문장으로 바꿔 전송한다 (FR-5.5) */
 export function makeNotifier(options = {}) {

package/src/verify.js

@@ -24,7 +24,8 @@ import { join } from 'node:path';
 import { buildAgentArgs, parseAgentOutput } from './runners.js';
 import { verifyPrompt } from './prompts.js';
 
-function gitDiff(cwd) {
+/** 워킹트리 전체 diff. 검증자·리뷰어가 공유하는 "이번에 무엇을 했는가"의 원본. */
+export function gitDiff(cwd) {
   return new Promise((resolve) => {
     // 워킹트리 전체 diff (추적 파일). 스펙·테스트 대비 구현이 무엇을 했는지.
     execFile('git', ['diff', 'HEAD'], { cwd, maxBuffer: 4 * 1024 * 1024 }, (err, stdout) => {