@su-record/vibe 3.2.23 → 3.2.24

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

@@ -36,7 +36,7 @@ export function hashDiscoverOutput(text) {
  * 루프 이벤트를 jsonl 파일에 append한다.
  *
  * @param {string} projectDir
- * @param {{ loop: string, event: 'start'|'discover'|'end', result?: 'ok'|'fail'|'stuck', summary?: string, discoverHash?: string }} opts
+ * @param {{ loop: string, event: 'start'|'discover'|'end'|'iteration', result?: 'ok'|'fail'|'stuck', summary?: string, discoverHash?: string, verified?: boolean }} opts
  * @returns {boolean} 성공 여부
  */
 export function appendLoopEvent(projectDir, opts) {
@@ -50,6 +50,7 @@ export function appendLoopEvent(projectDir, opts) {
       ...(opts.result !== undefined ? { result: opts.result } : {}),
       ...(opts.summary !== undefined ? { summary: opts.summary } : {}),
       ...(opts.discoverHash !== undefined ? { discoverHash: opts.discoverHash } : {}),
+      ...(opts.verified !== undefined ? { verified: opts.verified } : {}),
     };
     fs.appendFileSync(p, JSON.stringify(entry) + '\n', 'utf-8');
     return true;
@@ -116,3 +117,55 @@ export function isStuck(projectDir, loop, discoverHash) {
     return false;
   }
 }
+
+/**
+ * 회전 1회를 기록한다.
+ *
+ * @param {string} projectDir
+ * @param {string} loop
+ * @param {boolean} verified - 이 회전이 검증을 통과했는가 (JUDGE 결정론 게이트 기준)
+ * @returns {boolean}
+ */
+export function recordIteration(projectDir, loop, verified) {
+  return appendLoopEvent(projectDir, { loop, event: 'iteration', verified: Boolean(verified) });
+}
+
+/**
+ * 현재 루프 실행의 예산 상태.
+ *
+ * 두 축을 **따로** 센다:
+ *  - `iterations` — 모든 회전. `max_iterations` 와 비교하는 폭주 방어 축이다.
+ *  - `verified`   — 검증을 통과한 회전만. 실제로 전진한 양이다.
+ *
+ * 둘을 하나로 뭉치면 "10회를 썼다" 는 알아도 "그중 8회가 헛돌았다" 는 모른다 —
+ * 헛도는 루프와 원래 큰 작업을 구분할 수 없다. loop-contract 는 폭주 방어가
+ * 모델의 양심이 아니라 코드여야 한다고 선언하는데, 정작 max_iterations 에는
+ * 런타임 계수가 없어 모델이 스스로 세고 있었다 (감사 2026-08-10).
+ *
+ * 직전 `start` 이후만 센다 — 새 실행은 예산도 새로 시작한다.
+ *
+ * @param {string} projectDir
+ * @param {string} loop
+ * @param {number} [maxIterations=10]
+ * @returns {{ iterations: number, verified: number, remaining: number, exhausted: boolean }}
+ */
+export function readBudget(projectDir, loop, maxIterations = 10) {
+  const empty = { iterations: 0, verified: 0, remaining: maxIterations, exhausted: false };
+  try {
+    const raw = fs.readFileSync(historyPath(projectDir), 'utf-8');
+    const events = raw.split('\n')
+      .map(line => { try { return JSON.parse(line); } catch { return null; } })
+      .filter(e => e && e.loop === loop);
+
+    const lastStart = events.map(e => e.event).lastIndexOf('start');
+    const scoped = lastStart === -1 ? events : events.slice(lastStart);
+
+    const iters = scoped.filter(e => e.event === 'iteration');
+    const iterations = iters.length;
+    const verified = iters.filter(e => e.verified === true).length;
+    const remaining = Math.max(0, maxIterations - iterations);
+    return { iterations, verified, remaining, exhausted: remaining === 0 };
+  } catch {
+    return empty;
+  }
+}

package/hooks/scripts/loop-ledger.js

@@ -11,13 +11,15 @@
  *   node hooks/scripts/loop-ledger.js gate open <id> <question> [option...]
  *   node hooks/scripts/loop-ledger.js gate list
  *   node hooks/scripts/loop-ledger.js gate answer <id> <answer>
+ *   node hooks/scripts/loop-ledger.js iteration <name> <verified|unverified>
+ *   node hooks/scripts/loop-ledger.js budget <name> [maxIterations]
  *
  * check-stuck: 'stuck' 또는 'ok'를 stdout에 출력하고 항상 exit 0.
  * anchor: 재고정 번들 JSON을 stdout에 출력한다 (loop-contract ANCHOR 절).
  * 항상 exit 0 (fail-open).
  */
 
-import { appendLoopEvent, isStuck } from './lib/loop-ledger.js';
+import { appendLoopEvent, isStuck, recordIteration, readBudget } from './lib/loop-ledger.js';
 import { buildAnchor } from './lib/anchor.js';
 import { prependInboxBlock } from './lib/inbox.js';
 import { openGate, listOpenGates, answerGate, formatOpenGates } from './lib/gates.js';
@@ -73,6 +75,27 @@ if (subcommand === 'start') {
        : '[loop-ledger] WARNING: inbox write failed\n'
   );
 
+} else if (subcommand === 'iteration') {
+  // 회전 계수는 코드가 한다 — max_iterations 를 모델이 세면 폭주 방어가 양심이 된다
+  const [loop, verifiedArg] = args;
+  if (!loop || !['verified', 'unverified'].includes(verifiedArg || '')) {
+    process.stdout.write('[loop-ledger] error: iteration 에 루프 이름과 verified|unverified 가 필요합니다\n');
+    process.exit(0);
+  }
+  recordIteration(projectDir, loop, verifiedArg === 'verified');
+  const b = readBudget(projectDir, loop);
+  process.stdout.write(`[loop-ledger] iteration recorded: ${loop} ${verifiedArg} (${b.iterations} 회전 / 검증 ${b.verified})\n`);
+
+} else if (subcommand === 'budget') {
+  const [loop, maxRaw] = args;
+  if (!loop) {
+    process.stdout.write('[loop-ledger] error: budget 에 루프 이름이 필요합니다\n');
+    process.exit(0);
+  }
+  const max = Number.parseInt(maxRaw ?? '10', 10);
+  const b = readBudget(projectDir, loop, Number.isInteger(max) && max > 0 ? max : 10);
+  process.stdout.write(JSON.stringify(b) + '\n');
+
 } else if (subcommand === 'gate') {
   // 사람 판단 지점을 디스크에 남긴다 — 세션이 죽어도 무엇을 묻고 있었는지 남는다
   const [action, id, ...rest] = args;
@@ -105,7 +128,7 @@ if (subcommand === 'start') {
 } else {
   process.stdout.write(
     '[loop-ledger] 사용법: start <name> | end <name> <ok|fail|stuck> [summary] | '
-    + 'check-stuck <name> <hash> | anchor [feature] | inbox <name> <ok|fail|stuck> [line...] | gate <open|list|answer> …\n'
+    + 'check-stuck <name> <hash> | anchor [feature] | inbox <name> <ok|fail|stuck> [line...] | gate <open|list|answer> | iteration <name> <verified|unverified> | budget <name> [max]\n'
   );
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@su-record/vibe",
-  "version": "3.2.23",
+  "version": "3.2.24",
   "description": "AI Coding Framework for Claude Code — 7+ agents, 52 skills, multi-LLM orchestration",
   "type": "module",
   "main": "dist/cli/index.js",

package/skills/vibe.loop/SKILL.md

@@ -86,6 +86,11 @@ node -e "import('{{VIBE_PATH_URL}}/node_modules/@su-record/vibe/dist/tools/index
              · ledger: cat .vibe/metrics/run-ledger.json → verifyPassed === true 만 성공
              · tests:  정의의 test_command 실행 → exit 0 만 성공
              · none:   판정 생략(보고만). "코드를 보니 잘 된 것 같다"는 판정이 아니다.
+6-b. 회전 기록  node "$HOOKS_DIR/loop-ledger.js" iteration <name> <verified|unverified>
+             VERIFY 결과를 그대로 넣는다. 이어서 예산을 확인한다:
+             node "$HOOKS_DIR/loop-ledger.js" budget <name> <max_iterations>
+             → exhausted 면 잔여를 인박스로 이월하고 종료한다. 회전 수를 모델이
+               세지 않는다 — 폭주 방어는 코드가 판정한다 (loop-contract 예산 절).
 7. 종료 기록  node "$HOOKS_DIR/loop-ledger.js" end <name> <ok|fail|stuck> "<한 줄 요약>"
 8. 인박스    node "$HOOKS_DIR/loop-ledger.js" inbox <name> <ok|fail|stuck> \
                "발견: N건 / 처리: M건 / 검증: <기준과 결과>" \
@@ -111,6 +116,7 @@ node -e "import('{{VIBE_PATH_URL}}/node_modules/@su-record/vibe/dist/tools/index
 |------|------|
 | 완료는 게이트가 판정 | run-ledger `verifyPassed` / 테스트 exit code (REQ-005) |
 | stuck은 해시가 판정 | loop-ledger check-stuck, 동일 발견 2회 연속 (REQ-009) |
+| 회전 수도 코드가 판정 | loop-ledger iteration/budget — iterations(폭주 방어) 와 verified(전진량) 를 분리 |
 | 이해 부채 가드 | 인박스 리뷰 큐 + push/release 금지 (REQ-008) |
 | 기록 없는 실행 없음 | loop-history.jsonl start/end 의무 (REQ-006) |
 

package/vibe/rules/loop-contract.md

@@ -62,6 +62,27 @@ node "$HOOKS_DIR/loop-ledger.js" anchor [feature]
 
 > `autonomous` 의 "계속" 은 **stuck 난 루프를 더 돌린다는 뜻이 아니다** — 2회 연속 동일 발견은 정의상 재시도가 무의미하다. 같은 목표를 붙잡지 않고 다음 단위로 넘어간다는 뜻이며, 미달은 TODO/인박스에 남는다. 미달 상태를 **완료로 기록하지 않는다.**
 
+### 예산 — 회전은 코드가 세고, 전진과 헛돎을 구분한다
+
+이 문서는 서두에서 "폭주 방어가 모델의 양심이 아니라 결정론적 가드(코드)" 라고 선언한다. 그런데 정작 폭주 방어인 `max_iterations` 에는 런타임 계수가 없었다 — stuck 만 명령으로 판정되고 회전 수는 모델이 스스로 셌다. 선언과 구현이 어긋난 지점이었다 (감사 2026-08-10).
+
+```bash
+node "$HOOKS_DIR/loop-ledger.js" iteration <name> <verified|unverified>   # 회전 종료 시 1회
+node "$HOOKS_DIR/loop-ledger.js" budget <name> [max]                      # → {iterations, verified, remaining, exhausted}
+```
+
+**두 축을 따로 센다:**
+
+| 축 | 의미 | 쓰임 |
+|---|---|---|
+| `iterations` | 모든 회전 | `max_iterations` 와 비교하는 **폭주 방어** |
+| `verified` | JUDGE 결정론 게이트를 통과한 회전만 | 실제로 **전진한 양** |
+
+둘을 하나로 뭉치면 "10회를 썼다" 는 알아도 "그중 8회가 헛돌았다" 는 모른다 — 헛도는 루프와 원래 큰 작업을 구분할 수 없다. `exhausted: true` 면 잔여를 인박스로 이월하고 종료한다.
+
+- **실행 실패(error)는 회전을 소비하지 않는다** — 위 실행 실패 절대로 루프가 즉시 종료되므로 예산을 갉아먹지 않는다. 재시도가 예산을 태우는 형태를 만들지 않는다.
+- 계수는 직전 `start` 이후만 센다 — 새 실행은 예산도 새로 시작한다.
+
 ### 게이트 객체 — 사람을 기다리는 이유는 디스크에 산다
 
 사람 개입 지점의 질문이 컨텍스트에만 있으면, 세션이 죽거나 compact 로 소실될 때 **무엇을 묻고 있었는지가 사라진다.** 사람은 돌아왔는데 답할 대상이 없다. run-ledger·loop-history·인박스가 전부 디스크에 사는데 "지금 왜 멈춰 있는가"만 컨텍스트에 있었다.
@@ -131,7 +152,7 @@ stuck 은 **같은 발견이 반복되는** 상태다. 스킬이 로드되지
 
 | 파라미터 | 기본 | 의미 |
 |---|---|---|
-| `max_iterations` | 10 | 회전 상한. 도달 시 잔여를 인박스로 이월 |
+| `max_iterations` | 10 | 회전 상한. 도달 시 잔여를 인박스로 이월. **계수는 코드가 한다** — 아래 예산 절 |
 | `exit` | 게이트 통과 (**측정된** P1=0 ∧ verifyPassed) | 종료 기준. coverage 100% 등으로 상향 가능. 판정된 P1 은 위 Judge 권한 경계 표를 따른다 |
 | `--interactive` | off | 단계별 확인 모드 (회전마다 사람 승인 — 과거의 기본값) |
 | `--max-iter N` | — | 회전 상한 명시 (N=1이면 1회 시도) |