@su-record/vibe 2.12.5 → 2.14.0

package/hooks/scripts/lib/dispatcher.js

@@ -20,6 +20,7 @@ import { spawn } from 'child_process';
 import path from 'path';
 import fs from 'fs';
 import { fileURLToPath } from 'url';
+import { readStdinSync, buildCtx } from './hook-context.js';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const SCRIPTS_DIR = path.resolve(__dirname, '..');
@@ -112,3 +113,40 @@ export async function dispatch(steps) {
     process.exit(2);
   }
 }
+
+/**
+ * in-process 디스패처 — 자식 spawn 없이 import된 run(ctx)들을 병렬 실행.
+ *
+ * spawn 대비:
+ *   - 자식 node VM 기동(~20ms × N)과 stdin 재읽기/재파싱 제거
+ *   - 크래시 격리는 step별 try/catch로 대체 (throw → exit 1 취급, fail-open)
+ *   - step별 강제 timeout은 없음 — 무거운 작업(포매터/테스트러너)은 모두
+ *     자체 timeout을 가진 비동기 자식 프로세스라 디스패처가 행 걸리지 않는다
+ *
+ * deny 시맨틱 보존: denyOnExit2 step이 2를 반환하면 process.exit(2)로 상위 전파.
+ *
+ * @param {Array<{name: string, run: (ctx: object) => Promise<number>, denyOnExit2?: boolean}>} steps
+ * @param {{ argvToolName?: string }} [options]
+ */
+export async function dispatchInProcess(steps, { argvToolName = '' } = {}) {
+  const { raw, parsed } = readStdinSync();
+  const ctx = buildCtx({ rawInput: raw, payload: parsed, argvToolName });
+  const hookConfig = loadHookConfig();
+
+  const enabledSteps = steps.filter(s => isEnabled(hookConfig, s.name));
+  const results = await Promise.all(
+    enabledSteps.map(async (step) => {
+      try {
+        return { step, code: await step.run(ctx) };
+      } catch {
+        // 크래시 격리 — 실패 step은 exit 1 취급, 나머지 step과 디스패처는 계속
+        return { step, code: 1 };
+      }
+    })
+  );
+
+  // 하나라도 deny(exit 2) 반환 → 상위에 전파
+  if (results.some(({ step, code }) => step.denyOnExit2 && code === 2)) {
+    process.exit(2);
+  }
+}

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

@@ -0,0 +1,130 @@
+/**
+ * Hook 실행 컨텍스트 공용 헬퍼 — in-process 평탄화의 기반.
+ *
+ * 훅 스크립트는 두 모드로 실행된다:
+ *   1. in-process: 디스패처가 stdin을 1회 읽고 buildCtx()로 만든 ctx를
+ *      각 스크립트의 run(ctx)에 직접 전달 (자식 spawn 없음)
+ *   2. standalone CLI: antigravity-hooks.json / 기존 테스트가 스크립트를
+ *      직접 실행 — isDirectRun()으로 감지해 stdin/argv/env에서 ctx를 구성
+ *
+ * ctx 형태: { toolName, toolInput, payload, hookInput }
+ *   - toolName: payload.tool_name 우선, argv 폴백 (현행 각 스크립트와 동일 우선순위)
+ *   - toolInput: 문자열 정규화된 tool_input (payload → argv[3] → env.TOOL_INPUT)
+ *   - payload: 파싱된 stdin JSON 또는 null
+ *   - hookInput: stdin 원문 문자열 (code-check의 HOOK_INPUT 사용처 대체)
+ */
+import fs from 'fs';
+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'이 없음.
+ * 64KB 단일 버퍼 대신 EOF까지 청크 반복 읽기 (STDIN_MAX_BYTES 상한).
+ *
+ * @returns {{ raw: string|null, parsed: object|null, truncated: boolean }}
+ *   truncated=true: 페이로드가 STDIN_MAX_BYTES를 초과해 잘림
+ */
+export function readStdinSync() {
+  try {
+    if (process.stdin.isTTY) return { raw: null, parsed: null, truncated: false };
+
+    const chunks = [];
+    let totalBytes = 0;
+    let truncated = false;
+    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: 파이프가 *지금* 비었을 뿐 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;
+        break;
+      }
+      chunks.push(Buffer.from(chunkBuf.subarray(0, bytesRead)));
+    }
+
+    if (chunks.length === 0) return { raw: null, parsed: null, truncated: false };
+
+    const raw = Buffer.concat(chunks).toString('utf-8');
+    try {
+      return { raw, parsed: JSON.parse(raw), truncated };
+    } catch {
+      return { raw, parsed: null, truncated };
+    }
+  } catch { /* stdin 없음 → 폴백 */ }
+  return { raw: null, parsed: null, truncated: false };
+}
+
+/**
+ * 실행 컨텍스트 구성. 우선순위는 현행 스크립트들과 동일:
+ *   toolName: payload.tool_name → argvToolName
+ *   toolInput: payload.tool_input(문자열화) → argv[3] → env.TOOL_INPUT
+ */
+export function buildCtx({ rawInput = null, payload = null, argvToolName = '', argvToolInput = '' } = {}) {
+  const toolName = payload?.tool_name || argvToolName || '';
+  const toolInput = payload?.tool_input !== undefined && payload?.tool_input !== null
+    ? (typeof payload.tool_input === 'string' ? payload.tool_input : JSON.stringify(payload.tool_input))
+    : (argvToolInput || process.env.TOOL_INPUT || '');
+  return { toolName, toolInput, payload, hookInput: rawInput };
+}
+
+/** standalone CLI 모드용 ctx — stdin/argv/env에서 구성 */
+export function buildCliCtx() {
+  const { raw, parsed } = readStdinSync();
+  return buildCtx({
+    rawInput: raw ?? process.env.HOOK_INPUT ?? null,
+    payload: parsed,
+    argvToolName: process.argv[2] || '',
+    argvToolInput: process.argv[3] || '',
+  });
+}
+
+/** 모듈이 `node <file>`로 직접 실행됐는지 감지 (import 시 false) */
+export function isDirectRun(importMetaUrl) {
+  try {
+    return Boolean(process.argv[1]) && importMetaUrl === pathToFileURL(process.argv[1]).href;
+  } catch {
+    return false;
+  }
+}

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/lib/pr-gate-runner.js

@@ -0,0 +1,62 @@
+/**
+ * PR 테스트 게이트 공유 헬퍼 — pr-test-gate.js와 pre-tool-guard.js가 공용.
+ *
+ * 테스트 커맨드 감지 → 실행 → 결과 반환.
+ * exit code를 직접 호출하지 않고 결과 객체를 반환한다 (호출자가 판단).
+ */
+import { execSync } from 'child_process';
+import { existsSync, readFileSync } from 'fs';
+import path from 'path';
+
+/**
+ * 프로젝트에서 실행할 테스트 커맨드를 감지한다.
+ *
+ * @param {string} projectDir
+ * @returns {string|null}
+ */
+export function detectTestCommand(projectDir) {
+  const pkgPath = path.join(projectDir, 'package.json');
+  if (existsSync(pkgPath)) {
+    try {
+      const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+      if (pkg.scripts?.test && pkg.scripts.test !== 'echo "Error: no test specified" && exit 1') {
+        return 'npm test';
+      }
+    } catch { /* ignore */ }
+  }
+  // Python
+  if (existsSync(path.join(projectDir, 'pytest.ini')) || existsSync(path.join(projectDir, 'pyproject.toml'))) {
+    return 'python -m pytest --tb=short -q';
+  }
+  // Go
+  if (existsSync(path.join(projectDir, 'go.mod'))) {
+    return 'go test ./...';
+  }
+  return null;
+}
+
+/**
+ * 테스트 게이트를 실행한다.
+ *
+ * @param {string} projectDir
+ * @returns {{ passed: boolean, testCmd: string|null, output: string }}
+ *   testCmd=null 이면 테스트 없음 → passed=true (통과)
+ */
+export function runPrTestGate(projectDir) {
+  const testCmd = detectTestCommand(projectDir);
+  if (!testCmd) {
+    return { passed: true, testCmd: null, output: '' };
+  }
+
+  try {
+    execSync(testCmd, {
+      cwd: projectDir,
+      stdio: ['ignore', 'pipe', 'pipe'],
+      timeout: 120000,
+    });
+    return { passed: true, testCmd, output: '' };
+  } catch (err) {
+    const output = err.stdout ? err.stdout.toString().split('\n').slice(-5).join('\n') : '';
+    return { passed: false, testCmd, output };
+  }
+}

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

@@ -0,0 +1,169 @@
+/**
+ * Run Ledger — vibe.run 실행 및 vibe.verify 결과 추적.
+ *
+ * 파일 위치: <projectDir>/.vibe/metrics/run-ledger.json
+ * 형식: { runStarted, runFeature, verifyPassed, verifyAt, stopWarned,
+ *         verifyRequired, verifyRequiredReason }
+ *
+ * 모든 함수는 fail-open (try/catch, 오류 시 null/false 반환).
+ * 원자적 쓰기: 임시 파일 → rename 방식 사용.
+ */
+
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+
+/** 레저 파일 경로 */
+function ledgerPath(projectDir) {
+  return path.join(projectDir, '.vibe', 'metrics', 'run-ledger.json');
+}
+
+/**
+ * 레저 파일 읽기.
+ * @param {string} projectDir
+ * @returns {{ runStarted: string|null, runFeature: string|null, verifyPassed: boolean, verifyAt: string|null, stopWarned: boolean, verifyRequired: boolean, verifyRequiredReason: string|null }|null}
+ */
+export function readLedger(projectDir) {
+  try {
+    const p = ledgerPath(projectDir);
+    if (!fs.existsSync(p)) return null;
+    return JSON.parse(fs.readFileSync(p, 'utf-8'));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * 레저 파일 원자적 쓰기 (임시 파일 write → rename).
+ * @param {string} projectDir
+ * @param {object} data
+ * @returns {boolean} 성공 여부
+ */
+function writeLedger(projectDir, data) {
+  try {
+    const p = ledgerPath(projectDir);
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    const tmp = path.join(os.tmpdir(), `run-ledger-${process.pid}-${Date.now()}.tmp`);
+    fs.writeFileSync(tmp, JSON.stringify(data, null, 2), 'utf-8');
+    fs.renameSync(tmp, p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * vibe.run 시작 기록 — runStarted를 현재 시각으로 세팅하고 verifyPassed를 리셋.
+ * @param {string} projectDir
+ * @param {string|null} feature - 프롬프트에서 추출된 기능명 (없으면 null)
+ * @returns {boolean} 성공 여부
+ */
+export function recordRunStart(projectDir, feature) {
+  try {
+    const existing = readLedger(projectDir) || {};
+    const next = {
+      ...existing,
+      runStarted: new Date().toISOString(),
+      runFeature: feature || null,
+      verifyPassed: false,
+      verifyAt: null,
+      stopWarned: false,
+    };
+    return writeLedger(projectDir, next);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * vibe.verify 결과 기록.
+ * pass 시 verifyRequired 상태를 클리어한다.
+ * @param {string} projectDir
+ * @param {boolean} passed - 검증 통과 여부
+ * @returns {boolean} 성공 여부
+ */
+export function recordVerify(projectDir, passed) {
+  try {
+    const existing = readLedger(projectDir) || {};
+    const next = {
+      ...existing,
+      verifyPassed: Boolean(passed),
+      verifyAt: new Date().toISOString(),
+    };
+    // pass 시 verifyRequired 클리어
+    if (passed) {
+      next.verifyRequired = false;
+      next.verifyRequiredReason = null;
+    }
+    return writeLedger(projectDir, next);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * P1 이슈 발견 시 verify-required 상태 기록.
+ * @param {string} projectDir
+ * @param {string} reason - 이슈 사유
+ * @returns {boolean} 성공 여부
+ */
+export function recordVerifyRequired(projectDir, reason) {
+  try {
+    const existing = readLedger(projectDir) || {};
+    const next = {
+      ...existing,
+      verifyRequired: true,
+      verifyRequiredReason: reason || 'P1 issue detected',
+    };
+    return writeLedger(projectDir, next);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * stop 경고 플래그 세팅 (루프 방지).
+ * @param {string} projectDir
+ * @returns {boolean} 성공 여부
+ */
+export function markStopWarned(projectDir) {
+  try {
+    const existing = readLedger(projectDir) || {};
+    const next = { ...existing, stopWarned: true };
+    return writeLedger(projectDir, next);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * 프롬프트에서 vibe.run 기능명 추출.
+ * "/vibe.run some-feature ..." 또는 "$vibe.run some-feature ..." 형태에서 첫 토큰 추출.
+ * @param {string} prompt
+ * @returns {string|null}
+ */
+export function extractRunFeature(prompt) {
+  try {
+    const m = prompt.match(/(?:\/|\$)vibe\.run\s+([^\s]+)/i);
+    if (!m) return null;
+    const token = m[1];
+    // 플래그(-- 시작)나 키워드는 기능명이 아님
+    if (token.startsWith('-')) return null;
+    return token;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * 프롬프트에 vibe.run 호출이 포함되는지 확인 (단어 경계 매칭, 대소문자 무관).
+ * @param {string} prompt
+ * @returns {boolean}
+ */
+export function isVibeRunPrompt(prompt) {
+  try {
+    return /(?:^|[\s,;|&(])[$\/]vibe\.run(?:\b|$)/i.test(prompt);
+  } catch {
+    return false;
+  }
+}

package/hooks/scripts/lib/scope-from-spec.js

@@ -12,12 +12,26 @@ import path from 'path';
 
 const ACTIVE_STATUSES = new Set(['pending', 'in-progress', 'in_progress', 'active', 'running']);
 
+// status frontmatter 없는 SPEC을 활성으로 간주하는 최대 나이.
+// 오래된 status-없는 SPEC이 영구 활성으로 남아 stale scope를 만드는 것을 방지한다.
+const NO_STATUS_ACTIVE_MAX_AGE_DAYS = 14;
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+function isRecentlyModified(file) {
+  try {
+    return Date.now() - fs.statSync(file).mtimeMs <= NO_STATUS_ACTIVE_MAX_AGE_DAYS * DAY_MS;
+  } catch {
+    return false;
+  }
+}
+
 /**
  * scope-guard auto-derive 활성 여부.
  *
- * 기본값은 **off**. 사용자가 `.vibe/config.json` 의 `scopeGuard.enabled = true` 로
- * 명시적으로 켤 때만 SPEC → scope.json 자동 합성을 수행한다. 이전 동작(자동 ON)은
- * SPEC 외부 파일 편집에 매번 경고를 띄워 다수 사용자에게 노이즈가 됐기 때문.
+ * 기본값은 **on**. `.vibe/config.json` 의 `scopeGuard.enabled = false` 로
+ * 명시적으로 끌 때만 SPEC → scope.json 자동 합성을 건너뛴다.
+ * 노이즈 가드: SPEC 파일이 존재할 때만 scope.json 을 생성하며,
+ * SPEC 없이 scope.json 생성이 필요한 경우 수동 작성(auto:false)을 사용한다.
  *
  * 이미 `auto: false` scope.json 을 직접 만들어 둔 사용자는 영향 없음 — scope-guard.js
  * 자체는 scope.json 존재 여부만 본다.
@@ -31,10 +45,10 @@ export function isScopeGuardEnabled(projectDir) {
     for (const p of candidates) {
       if (!fs.existsSync(p)) continue;
       const cfg = JSON.parse(fs.readFileSync(p, 'utf-8'));
-      if (cfg && cfg.scopeGuard && cfg.scopeGuard.enabled === true) return true;
+      if (cfg && cfg.scopeGuard && cfg.scopeGuard.enabled === false) return false;
     }
   } catch { /* ignore */ }
-  return false;
+  return true;
 }
 
 /**
@@ -181,7 +195,7 @@ export function findActiveSpecs(projectDir) {
       const content = fs.readFileSync(f, 'utf-8');
       const fm = readFrontmatter(content);
       const status = (fm.status || '').toLowerCase();
-      if (!fm.status) return true; // status 없으면 활성 간주
+      if (!fm.status) return isRecentlyModified(f); // status 없으면 최근 수정분만 활성 간주
       return ACTIVE_STATUSES.has(status);
     } catch { return false; }
   });
@@ -215,6 +229,7 @@ export function synthesizeScope(specFiles, { projectDir } = {}) {
   return {
     auto: true,
     mode: 'warn',
+    derivedCount: verified.length,
     allow,
     deny: [],
     reason: sourceNames.length > 0
@@ -262,6 +277,23 @@ export function syncScopeFile(projectDir) {
   }
 
   const next = synthesizeScope(specs, { projectDir });
+
+  // SPEC은 있으나 경로를 산출하지 못함 → defaultAllow만 남은 scope는
+  // 모든 소스 편집에 경고를 띄우는 노이즈가 된다. 생성하지 않고, 기존
+  // 자동 생성 파일이 있으면 제거한다.
+  if (next.derivedCount === 0) {
+    if (fs.existsSync(scopePath)) {
+      try {
+        const existing = JSON.parse(fs.readFileSync(scopePath, 'utf-8'));
+        if (existing.auto === true) {
+          fs.unlinkSync(scopePath);
+          return { action: 'removed', path: scopePath };
+        }
+      } catch { /* ignore */ }
+    }
+    return { action: 'skipped-no-paths', path: scopePath };
+  }
+
   const nextStr = JSON.stringify(next, null, 2);
 
   // 변경 없음 체크 (generatedAt 제외)
@@ -288,7 +320,7 @@ import { fileURLToPath } from 'url';
 if (process.argv[1] && fileURLToPath(import.meta.url) === path.resolve(process.argv[1])) {
   const dir = process.argv[2] || process.env.CLAUDE_PROJECT_DIR || process.cwd();
   if (!isScopeGuardEnabled(dir)) {
-    console.log('[scope-sync] · scopeGuard.enabled !== true — skipping (set in .vibe/config.json to opt in)');
+    console.log('[scope-sync] · scopeGuard.enabled=false — skipping (explicitly opted out in .vibe/config.json)');
     process.exit(0);
   }
   const result = syncScopeFile(dir);
@@ -299,6 +331,7 @@ if (process.argv[1] && fileURLToPath(import.meta.url) === path.resolve(process.a
     removed: '✓ scope.json removed (no active SPECs)',
     'skipped-manual': '· scope.json is manually managed (auto=false)',
     'skipped-no-specs': '· no active SPECs — scope.json not generated',
+    'skipped-no-paths': '· active SPECs contain no derivable paths — scope.json not generated',
   }[result.action] || result.action;
   console.log(`[scope-sync] ${label}`);
 }

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);