@su-record/vibe 2.13.0 → 2.14.1

package/hooks/scripts/__tests__/loop-ledger.test.js

@@ -0,0 +1,321 @@
+/**
+ * loop-ledger 라이브러리 + CLI 테스트
+ *
+ * 커버리지:
+ * - appendLoopEvent round-trip
+ * - isStuck: 2회 연속 동일 hash → true
+ * - isStuck: 다른 hash → false
+ * - isStuck: 이력 없음 → false
+ * - fail-open: 손상된 jsonl 줄 무시
+ * - hashDiscoverOutput: 공백 정규화
+ * - CLI: start / end / check-stuck 서브커맨드
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+import { spawnSync } from 'child_process';
+import { fileURLToPath } from 'url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+let tmpDir;
+beforeEach(() => {
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'vibe-loop-ledger-test-'));
+});
+afterEach(() => {
+  try { fs.rmSync(tmpDir, { recursive: true, force: true }); } catch { /* ignore */ }
+});
+
+async function importLedger() {
+  const p = path.resolve(__dirname, '..', 'lib', 'loop-ledger.js');
+  return import(p);
+}
+
+const CLI = path.resolve(__dirname, '..', 'loop-ledger.js');
+
+function historyPath(dir) {
+  return path.join(dir, '.vibe', 'metrics', 'loop-history.jsonl');
+}
+
+// ─── appendLoopEvent round-trip ───────────────────────────────────────
+
+describe('loop-ledger: appendLoopEvent round-trip', () => {
+  it('start 이벤트를 append 하면 jsonl 파일에 기록된다', async () => {
+    const { appendLoopEvent } = await importLedger();
+    appendLoopEvent(tmpDir, { loop: 'nightly', event: 'start' });
+
+    const p = historyPath(tmpDir);
+    expect(fs.existsSync(p)).toBe(true);
+    const line = fs.readFileSync(p, 'utf-8').trim();
+    const obj = JSON.parse(line);
+    expect(obj.loop).toBe('nightly');
+    expect(obj.event).toBe('start');
+    expect(obj.ts).toBeDefined();
+  });
+
+  it('end 이벤트에 result, summary, discoverHash가 포함된다', async () => {
+    const { appendLoopEvent } = await importLedger();
+    appendLoopEvent(tmpDir, {
+      loop: 'nightly',
+      event: 'end',
+      result: 'ok',
+      summary: '3 items processed',
+      discoverHash: 'abc123',
+    });
+
+    const p = historyPath(tmpDir);
+    const line = fs.readFileSync(p, 'utf-8').trim();
+    const obj = JSON.parse(line);
+    expect(obj.event).toBe('end');
+    expect(obj.result).toBe('ok');
+    expect(obj.summary).toBe('3 items processed');
+    expect(obj.discoverHash).toBe('abc123');
+  });
+
+  it('여러 이벤트가 순서대로 append 된다', async () => {
+    const { appendLoopEvent } = await importLedger();
+    appendLoopEvent(tmpDir, { loop: 'loop-a', event: 'start' });
+    appendLoopEvent(tmpDir, { loop: 'loop-a', event: 'end', result: 'ok' });
+    appendLoopEvent(tmpDir, { loop: 'loop-b', event: 'start' });
+
+    const p = historyPath(tmpDir);
+    const lines = fs.readFileSync(p, 'utf-8').trim().split('\n');
+    expect(lines).toHaveLength(3);
+    expect(JSON.parse(lines[0]).loop).toBe('loop-a');
+    expect(JSON.parse(lines[1]).event).toBe('end');
+    expect(JSON.parse(lines[2]).loop).toBe('loop-b');
+  });
+
+  it('appendLoopEvent는 true를 반환한다', async () => {
+    const { appendLoopEvent } = await importLedger();
+    const result = appendLoopEvent(tmpDir, { loop: 'x', event: 'start' });
+    expect(result).toBe(true);
+  });
+});
+
+// ─── isStuck ──────────────────────────────────────────────────────────
+
+describe('loop-ledger: isStuck', () => {
+  it('이력 없으면 false', async () => {
+    const { isStuck } = await importLedger();
+    expect(isStuck(tmpDir, 'nightly', 'hash-abc')).toBe(false);
+  });
+
+  it('직전 discover 이벤트와 동일 hash → true (2회 연속 성립)', async () => {
+    const { appendLoopEvent, isStuck } = await importLedger();
+    // 이전 반복의 discover 이벤트 (같은 hash)
+    appendLoopEvent(tmpDir, {
+      loop: 'nightly',
+      event: 'discover',
+      discoverHash: 'hash-same',
+    });
+    // 신규 반복이 같은 hash를 갖고 오면 stuck
+    expect(isStuck(tmpDir, 'nightly', 'hash-same')).toBe(true);
+  });
+
+  it('직전 discover 이벤트와 다른 hash → false', async () => {
+    const { appendLoopEvent, isStuck } = await importLedger();
+    appendLoopEvent(tmpDir, {
+      loop: 'nightly',
+      event: 'discover',
+      discoverHash: 'hash-old',
+    });
+    expect(isStuck(tmpDir, 'nightly', 'hash-new')).toBe(false);
+  });
+
+  it('end 이벤트의 hash는 비교 대상이 아님 (discover만 본다)', async () => {
+    const { appendLoopEvent, isStuck } = await importLedger();
+    appendLoopEvent(tmpDir, {
+      loop: 'nightly',
+      event: 'end',
+      result: 'ok',
+      discoverHash: 'hash-same',
+    });
+    expect(isStuck(tmpDir, 'nightly', 'hash-same')).toBe(false);
+  });
+
+  it('다른 루프 이름의 이벤트는 영향 안 줌', async () => {
+    const { appendLoopEvent, isStuck } = await importLedger();
+    appendLoopEvent(tmpDir, {
+      loop: 'other-loop',
+      event: 'discover',
+      discoverHash: 'hash-same',
+    });
+    // 'nightly' 에 대한 이력 없음 → false
+    expect(isStuck(tmpDir, 'nightly', 'hash-same')).toBe(false);
+  });
+
+  it('start 이벤트만 있고 discover 없으면 false', async () => {
+    const { appendLoopEvent, isStuck } = await importLedger();
+    appendLoopEvent(tmpDir, { loop: 'nightly', event: 'start' });
+    expect(isStuck(tmpDir, 'nightly', 'hash-abc')).toBe(false);
+  });
+
+  it('discoverHash 가 빈 문자열이면 false', async () => {
+    const { appendLoopEvent, isStuck } = await importLedger();
+    appendLoopEvent(tmpDir, {
+      loop: 'nightly',
+      event: 'discover',
+      discoverHash: '',
+    });
+    expect(isStuck(tmpDir, 'nightly', '')).toBe(false);
+  });
+});
+
+// ─── fail-open: 손상된 jsonl 줄 ──────────────────────────────────────
+
+describe('loop-ledger: fail-open on corrupt jsonl', () => {
+  it('손상된 줄이 있어도 isStuck이 충돌하지 않고 false 반환', async () => {
+    const { appendLoopEvent, isStuck } = await importLedger();
+
+    // 정상 줄 + 손상 줄 + 정상 줄 혼합
+    const p = historyPath(tmpDir);
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    fs.writeFileSync(
+      p,
+      [
+        JSON.stringify({ ts: '2026-01-01T00:00:00.000Z', loop: 'nightly', event: 'discover', discoverHash: 'abc' }),
+        'CORRUPTED LINE {{{',
+        JSON.stringify({ ts: '2026-01-01T01:00:00.000Z', loop: 'nightly', event: 'discover', discoverHash: 'xyz' }),
+      ].join('\n') + '\n',
+      'utf-8'
+    );
+
+    // 손상 줄은 건너뛰고, 가장 최근 discover 이벤트(최신)의 hash는 'xyz'
+    expect(isStuck(tmpDir, 'nightly', 'xyz')).toBe(true);
+    expect(isStuck(tmpDir, 'nightly', 'abc')).toBe(false);
+  });
+
+  it('appendLoopEvent: 전체 파일이 corrupt 여도 추가 후 정상 동작', async () => {
+    const { appendLoopEvent } = await importLedger();
+    const p = historyPath(tmpDir);
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    fs.writeFileSync(p, 'NOT JSON\n', 'utf-8');
+
+    const ok = appendLoopEvent(tmpDir, { loop: 'x', event: 'start' });
+    expect(ok).toBe(true);
+    const lines = fs.readFileSync(p, 'utf-8').split('\n').filter(Boolean);
+    // 손상 줄 + 새로 추가된 정상 줄
+    expect(lines.length).toBeGreaterThanOrEqual(2);
+    const last = JSON.parse(lines[lines.length - 1]);
+    expect(last.event).toBe('start');
+  });
+});
+
+// ─── hashDiscoverOutput ───────────────────────────────────────────────
+
+describe('loop-ledger: hashDiscoverOutput', () => {
+  it('동일 텍스트는 동일 해시를 반환한다', async () => {
+    const { hashDiscoverOutput } = await importLedger();
+    const h1 = hashDiscoverOutput('hello world');
+    const h2 = hashDiscoverOutput('hello world');
+    expect(h1).toBe(h2);
+  });
+
+  it('공백 정규화: 여분 공백/줄바꿈이 달라도 동일 해시', async () => {
+    const { hashDiscoverOutput } = await importLedger();
+    const h1 = hashDiscoverOutput('item a\nitem b');
+    const h2 = hashDiscoverOutput('item a  item b');
+    const h3 = hashDiscoverOutput('  item a item b  ');
+    expect(h1).toBe(h2);
+    expect(h2).toBe(h3);
+  });
+
+  it('다른 텍스트는 다른 해시', async () => {
+    const { hashDiscoverOutput } = await importLedger();
+    expect(hashDiscoverOutput('abc')).not.toBe(hashDiscoverOutput('xyz'));
+  });
+
+  it('sha256 hex 64자 반환', async () => {
+    const { hashDiscoverOutput } = await importLedger();
+    expect(hashDiscoverOutput('test')).toMatch(/^[0-9a-f]{64}$/);
+  });
+});
+
+// ─── CLI: start / end / check-stuck ─────────────────────────────────
+
+describe('loop-ledger CLI', () => {
+  it('start → exit 0, 확인 메시지 출력, jsonl 생성', () => {
+    const result = spawnSync('node', [CLI, 'start', 'nightly'], {
+      encoding: 'utf-8',
+      timeout: 5000,
+      env: { ...process.env, CLAUDE_PROJECT_DIR: tmpDir },
+    });
+    expect(result.status).toBe(0);
+    expect(result.stdout).toContain('start recorded');
+    expect(result.stdout).toContain('nightly');
+    expect(fs.existsSync(historyPath(tmpDir))).toBe(true);
+  });
+
+  it('end → exit 0, jsonl에 end 이벤트 기록', () => {
+    const result = spawnSync('node', [CLI, 'end', 'nightly', 'ok', 'summary text'], {
+      encoding: 'utf-8',
+      timeout: 5000,
+      env: { ...process.env, CLAUDE_PROJECT_DIR: tmpDir },
+    });
+    expect(result.status).toBe(0);
+    expect(result.stdout).toContain('end recorded');
+
+    const line = fs.readFileSync(historyPath(tmpDir), 'utf-8').trim();
+    const obj = JSON.parse(line);
+    expect(obj.event).toBe('end');
+    expect(obj.result).toBe('ok');
+    expect(obj.summary).toBe('summary text');
+  });
+
+  it('check-stuck: 직전 discover hash와 동일 → stdout "stuck"', async () => {
+    const { appendLoopEvent } = await importLedger();
+    appendLoopEvent(tmpDir, {
+      loop: 'nightly',
+      event: 'discover',
+      discoverHash: 'deadbeef',
+    });
+
+    const result = spawnSync('node', [CLI, 'check-stuck', 'nightly', 'deadbeef'], {
+      encoding: 'utf-8',
+      timeout: 5000,
+      env: { ...process.env, CLAUDE_PROJECT_DIR: tmpDir },
+    });
+    expect(result.status).toBe(0);
+    expect(result.stdout.trim()).toBe('stuck');
+  });
+
+  it('check-stuck: 새 hash → stdout "ok"', async () => {
+    const { appendLoopEvent } = await importLedger();
+    appendLoopEvent(tmpDir, {
+      loop: 'nightly',
+      event: 'end',
+      result: 'ok',
+      discoverHash: 'old-hash',
+    });
+
+    const result = spawnSync('node', [CLI, 'check-stuck', 'nightly', 'new-hash'], {
+      encoding: 'utf-8',
+      timeout: 5000,
+      env: { ...process.env, CLAUDE_PROJECT_DIR: tmpDir },
+    });
+    expect(result.status).toBe(0);
+    expect(result.stdout.trim()).toBe('ok');
+  });
+
+  it('check-stuck: 이력 없으면 "ok"', () => {
+    const result = spawnSync('node', [CLI, 'check-stuck', 'nightly', 'anyhash'], {
+      encoding: 'utf-8',
+      timeout: 5000,
+      env: { ...process.env, CLAUDE_PROJECT_DIR: tmpDir },
+    });
+    expect(result.status).toBe(0);
+    expect(result.stdout.trim()).toBe('ok');
+  });
+
+  it('인수 없이 실행해도 exit 0 (fail-open)', () => {
+    const result = spawnSync('node', [CLI], {
+      encoding: 'utf-8',
+      timeout: 5000,
+      env: { ...process.env, CLAUDE_PROJECT_DIR: tmpDir },
+    });
+    expect(result.status).toBe(0);
+  });
+});

package/hooks/scripts/keyword-detector.js

@@ -8,20 +8,20 @@ import { VIBE_PATH, PROJECT_DIR } from './utils.js';
 
 // 매직 키워드 정의
 const MAGIC_KEYWORDS = {
-  // 지속성 모드 (완료까지 계속)
+  // Deprecated: 기본 루프 동작과 동일 (no-op). exit=coverage-100으로 해석.
   ralph: {
-    name: 'Ralph Loop',
-    description: 'Continue until task is verified complete',
+    name: 'Ralph (deprecated alias)',
+    description: '[deprecated] Looping to convergence is the default; alias mapped',
     flags: ['persistence', 'verification'],
-    output: '[RALPH MODE] Self-referential completion loop activated. Will continue until ALL tasks verified complete. NO early stopping.',
+    output: '[vibe] \'ralph\' is deprecated — looping to convergence is the default; alias mapped.',
   },
 
-  // 울트라워크 모드 (병렬 + 자동 계속)
+  // 울트라워크 모드 (automationLevel: autonomous + 병렬 ACT)
   ultrawork: {
     name: 'Ultrawork',
-    description: 'Maximum parallel execution, no pause',
+    description: 'automationLevel: autonomous + parallel ACT (deprecated alias)',
     flags: ['parallel', 'auto_continue', 'no_confirmation'],
-    output: '[ULTRAWORK MODE] Use PARALLEL Task calls. Auto-continue through ALL phases. Auto-retry on errors up to 3 times. Do NOT ask for confirmation between phases.',
+    output: '[ULTRAWORK] automationLevel: autonomous + parallel ACT. Loop runs to convergence; stuck → auto-TODO (no confirmation).',
   },
   ulw: {
     alias: 'ultrawork',
@@ -47,12 +47,12 @@ const MAGIC_KEYWORDS = {
     output: '[RALPLAN MODE] Iterative planning with consensus. Will refine plan until approved, then execute with Ralph persistence.',
   },
 
-  // 검증 모드
+  // Deprecated: 기본 JUDGE는 항상 결정론 검증 (no-op)
   verify: {
-    name: 'Verify Mode',
-    description: 'Strict verification after each step',
+    name: 'Verify (deprecated alias)',
+    description: '[deprecated] Deterministic verification is the default; alias mapped',
     flags: ['verification', 'strict'],
-    output: '[VERIFY MODE] Strict verification enabled. Every change must be verified before proceeding.',
+    output: '[vibe] \'verify\' is deprecated — deterministic JUDGE is the default; alias mapped.',
     strict: true, // 일상어 ("please verify the fix" 오탐 방지)
   },
 
@@ -65,29 +65,29 @@ const MAGIC_KEYWORDS = {
     strict: true, // 일상어 ("let me explore the options" 오탐 방지)
   },
 
-  // 빠른 모드
+  // Deprecated: --max-iter 1 매핑
   quick: {
-    name: 'Quick Mode',
-    description: 'Fast execution, minimal verification',
+    name: 'Quick (deprecated alias)',
+    description: '[deprecated] Maps to --max-iter 1; use --max-iter 1 explicitly',
     flags: ['fast', 'minimal_verification'],
-    output: '[QUICK MODE] Fast execution mode. Minimal verification, single round reviews.',
+    output: '[vibe] \'quick\' maps to --max-iter 1 (single-pass, minimal JUDGE).',
     strict: true, // 일상어 ("quick question on auth" 오탐 방지)
   },
 };
 
-// 키워드 조합 시너지
+// 키워드 조합 시너지 (deprecated alias 조합도 매핑 유지)
 const KEYWORD_SYNERGIES = {
   'ralph+ultrawork': {
-    name: 'Ralph Ultrawork',
-    output: '[RALPH+ULTRAWORK] Maximum persistence AND parallel execution. Will NOT stop until ALL phases complete with verification.',
+    name: 'Ralph+Ultrawork (deprecated)',
+    output: '[vibe] \'ralph\'+\'ultrawork\' deprecated: automationLevel: autonomous + parallel ACT, exit=coverage-100.',
   },
   'ralph+verify': {
-    name: 'Ralph Verify',
-    output: '[RALPH+VERIFY] Persistent completion with strict verification at each step.',
+    name: 'Ralph+Verify (deprecated)',
+    output: '[vibe] \'ralph\'+\'verify\' deprecated: both are default behavior; alias mapped.',
   },
   'ultrawork+explore': {
-    name: 'Ultrawork Explore',
-    output: '[ULTRAWORK+EXPLORE] Parallel exploration agents for maximum coverage.',
+    name: 'Ultrawork+Explore',
+    output: '[ULTRAWORK+EXPLORE] automationLevel: autonomous + parallel exploration agents.',
   },
 };
 

package/hooks/scripts/lib/hook-context.js

@@ -19,6 +19,26 @@ import { pathToFileURL } from 'url';
 /** stdin을 EOF까지 읽을 때 허용하는 최대 바이트 수 (10MB). */
 const STDIN_MAX_BYTES = 10 * 1024 * 1024;
 
+/** EAGAIN 재시도 간격/데드라인 — non-blocking pipe에서 writer가 아직 flush 전일 수 있다. */
+const STDIN_EAGAIN_RETRY_MS = 5;
+const STDIN_EAGAIN_DEADLINE_MS = 500;
+
+/** 동기 sleep (Atomics.wait — 이벤트 루프 없이 대기). */
+const sleepBuf = new Int32Array(new SharedArrayBuffer(4));
+function sleepSync(ms) {
+  Atomics.wait(sleepBuf, 0, 0, ms);
+}
+
+/** 누적 청크가 완전한 JSON인지 검사 — EAGAIN 시 조기 종료 판단용. */
+function isCompleteJson(chunks) {
+  try {
+    JSON.parse(Buffer.concat(chunks).toString('utf-8'));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 /**
  * stdin에서 JSON 페이로드 동기 읽기 (Claude Code 하네스 호환).
  * fd 0 직접 사용 — Windows는 '/dev/stdin'이 없음.
@@ -37,16 +57,25 @@ export function readStdinSync() {
     const chunkSize = 65536;
     const chunkBuf = Buffer.alloc(chunkSize);
 
+    let lastProgress = Date.now();
     while (true) {
       let bytesRead;
       try {
         bytesRead = fs.readSync(0, chunkBuf, 0, chunkSize, null);
       } catch (err) {
-        // EAGAIN: non-blocking stdin에 데이터 없음 → 루프 종료
-        if (err.code === 'EAGAIN') break;
+        // EAGAIN: 파이프가 *지금* 비었을 뿐 EOF가 아닐 수 있다 (writer가 flush 전).
+        // EOF로 취급하면 대용량 페이로드가 중간에 끊겨 가드가 fail-open된다 —
+        // 완전한 JSON이 모였거나 데드라인이 지나기 전까지 재시도한다.
+        if (err.code === 'EAGAIN') {
+          if (chunks.length > 0 && isCompleteJson(chunks)) break;
+          if (Date.now() - lastProgress > STDIN_EAGAIN_DEADLINE_MS) break;
+          sleepSync(STDIN_EAGAIN_RETRY_MS);
+          continue;
+        }
         throw err;
       }
       if (bytesRead === 0) break;
+      lastProgress = Date.now();
       totalBytes += bytesRead;
       if (totalBytes > STDIN_MAX_BYTES) {
         truncated = true;

package/hooks/scripts/lib/loop-ledger.js

@@ -0,0 +1,118 @@
+/**
+ * Loop Ledger 라이브러리 — 루프 실행 이력 추적 및 stuck 감지.
+ *
+ * 파일 위치: <projectDir>/.vibe/metrics/loop-history.jsonl
+ * 형식: JSON Lines — 각 줄이 독립적인 루프 이벤트 JSON 객체
+ *
+ * 모든 함수는 fail-open (try/catch, 오류 시 무시하거나 안전한 기본값 반환).
+ * isStuck: 같은 루프의 가장 최근 discover 이벤트의 discoverHash가
+ *   신규 hash와 같으면 stuck으로 판정한다 (2회 연속 동일 발견).
+ *   discover 이벤트는 CLI check-stuck이 판정 직후 스스로 기록한다 —
+ *   기록 없는 판정은 다음 실행의 비교 기준을 잃는다.
+ */
+
+import fs from 'fs';
+import path from 'path';
+import crypto from 'crypto';
+
+/** 루프 이력 파일 경로 */
+function historyPath(projectDir) {
+  return path.join(projectDir, '.vibe', 'metrics', 'loop-history.jsonl');
+}
+
+/**
+ * discover 산출물 텍스트를 sha256 hex 해시로 변환한다.
+ * 공백/줄바꿈을 정규화해 동등한 출력이 동일 해시를 갖도록 한다.
+ *
+ * @param {string} text
+ * @returns {string} sha256 hex
+ */
+export function hashDiscoverOutput(text) {
+  const normalized = text.replace(/\s+/g, ' ').trim();
+  return crypto.createHash('sha256').update(normalized, 'utf-8').digest('hex');
+}
+
+/**
+ * 루프 이벤트를 jsonl 파일에 append한다.
+ *
+ * @param {string} projectDir
+ * @param {{ loop: string, event: 'start'|'discover'|'end', result?: 'ok'|'fail'|'stuck', summary?: string, discoverHash?: string }} opts
+ * @returns {boolean} 성공 여부
+ */
+export function appendLoopEvent(projectDir, opts) {
+  try {
+    const p = historyPath(projectDir);
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    const entry = {
+      ts: new Date().toISOString(),
+      loop: opts.loop,
+      event: opts.event,
+      ...(opts.result !== undefined ? { result: opts.result } : {}),
+      ...(opts.summary !== undefined ? { summary: opts.summary } : {}),
+      ...(opts.discoverHash !== undefined ? { discoverHash: opts.discoverHash } : {}),
+    };
+    fs.appendFileSync(p, JSON.stringify(entry) + '\n', 'utf-8');
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * 지정 루프의 특정 이벤트 목록을 최신순으로 읽는다.
+ * 손상된 줄은 건너뛴다 (fail-open).
+ *
+ * @param {string} projectDir
+ * @param {string} loop
+ * @param {string} eventType
+ * @returns {{ ts: string, discoverHash?: string }[]}
+ */
+function readEventsOfType(projectDir, loop, eventType) {
+  try {
+    const p = historyPath(projectDir);
+    if (!fs.existsSync(p)) return [];
+    const lines = fs.readFileSync(p, 'utf-8').split('\n').filter(Boolean);
+    const events = [];
+    for (const line of lines) {
+      try {
+        const obj = JSON.parse(line);
+        if (obj.loop === loop && obj.event === eventType) {
+          events.push(obj);
+        }
+      } catch {
+        // 손상된 줄 무시
+      }
+    }
+    // 최신순 정렬 (ts 기준)
+    return events.sort((a, b) => (a.ts < b.ts ? 1 : a.ts > b.ts ? -1 : 0));
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * 신규 discoverHash가 stuck 조건을 충족하는지 판정한다.
+ *
+ * stuck 조건: 신규 hash가 non-empty이고, 해당 루프의 가장 최근
+ * discover 이벤트에 동일한 discoverHash가 있을 때.
+ * (직전 실행의 발견 + 이번 발견 = 2회 연속 동일이 되는 시점)
+ *
+ * 주의: 판정만 하고 기록하지 않으면 다음 실행이 비교할 기준이 없다 —
+ * 호출자는 판정 직후 event:'discover'로 해시를 기록해야 한다 (CLI check-stuck이 수행).
+ *
+ * @param {string} projectDir
+ * @param {string} loop
+ * @param {string} discoverHash
+ * @returns {boolean}
+ */
+export function isStuck(projectDir, loop, discoverHash) {
+  try {
+    if (!discoverHash) return false;
+    const discoverEvents = readEventsOfType(projectDir, loop, 'discover');
+    if (discoverEvents.length === 0) return false;
+    const lastHash = discoverEvents[0].discoverHash;
+    return Boolean(lastHash && lastHash === discoverHash);
+  } catch {
+    return false;
+  }
+}

package/hooks/scripts/loop-ledger.js

@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+/**
+ * loop-ledger CLI — 루프 실행 이력 기록 및 stuck 감지.
+ *
+ * 사용법:
+ *   node hooks/scripts/loop-ledger.js start <name>
+ *   node hooks/scripts/loop-ledger.js end <name> <ok|fail|stuck> [summary]
+ *   node hooks/scripts/loop-ledger.js check-stuck <name> <discoverHash>
+ *
+ * check-stuck: 'stuck' 또는 'ok'를 stdout에 출력하고 항상 exit 0.
+ * 항상 exit 0 (fail-open).
+ */
+
+import { appendLoopEvent, isStuck } from './lib/loop-ledger.js';
+
+const [, , subcommand, ...args] = process.argv;
+const projectDir = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+
+if (subcommand === 'start') {
+  const loop = args[0];
+  if (!loop) {
+    process.stdout.write('[loop-ledger] error: start 에 루프 이름이 필요합니다\n');
+    process.exit(0);
+  }
+  appendLoopEvent(projectDir, { loop, event: 'start' });
+  process.stdout.write(`[loop-ledger] start recorded: loop=${loop}\n`);
+
+} else if (subcommand === 'end') {
+  const [loop, result, ...summaryParts] = args;
+  if (!loop || !result) {
+    process.stdout.write('[loop-ledger] error: end 에 루프 이름과 결과(ok|fail|stuck)가 필요합니다\n');
+    process.exit(0);
+  }
+  const summary = summaryParts.length > 0 ? summaryParts.join(' ') : undefined;
+  appendLoopEvent(projectDir, { loop, event: 'end', result, summary });
+  process.stdout.write(`[loop-ledger] end recorded: loop=${loop} result=${result}\n`);
+
+} else if (subcommand === 'check-stuck') {
+  const [loop, discoverHash] = args;
+  if (!loop || !discoverHash) {
+    process.stdout.write('[loop-ledger] error: check-stuck 에 루프 이름과 discoverHash가 필요합니다\n');
+    process.stdout.write('ok\n');
+    process.exit(0);
+  }
+  const stuck = isStuck(projectDir, loop, discoverHash);
+  // 판정 직후 이번 발견 해시를 기록 — 다음 실행의 비교 기준이 된다
+  appendLoopEvent(projectDir, { loop, event: 'discover', discoverHash });
+  process.stdout.write(stuck ? 'stuck\n' : 'ok\n');
+
+} else {
+  process.stdout.write(
+    '[loop-ledger] 사용법: start <name> | end <name> <ok|fail|stuck> [summary] | check-stuck <name> <hash>\n'
+  );
+}
+
+process.exit(0);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@su-record/vibe",
-  "version": "2.13.0",
-  "description": "AI Coding Framework for Claude Code — 60+ agents, 69 skills, multi-LLM orchestration",
+  "version": "2.14.1",
+  "description": "AI Coding Framework for Claude Code — 42+ agents, 70 skills, multi-LLM orchestration",
   "type": "module",
   "main": "dist/cli/index.js",
   "exports": {
@@ -28,6 +28,7 @@
     "gen:skill-docs": "npx tsx scripts/gen-skill-docs.ts",
     "gen:skill-docs:check": "npx tsx scripts/gen-skill-docs.ts --check",
     "validate:skill-invocation": "npx tsx scripts/validate-skill-invocation.ts",
+    "validate:counts": "npx tsx scripts/validate-counts.ts",
     "test": "vitest run",
     "test:watch": "vitest",
     "prepublishOnly": "pnpm build",