@su-record/vibe 3.2.61 → 3.2.64

package/hooks/scripts/lib/iteration-cost.js

@@ -0,0 +1,178 @@
+/**
+ * 회전 비용 계측 — "그 전진이 얼마짜리였나" 를 코드가 센다.
+ *
+ * 원장은 `iterations`(폭주 방어)와 `verified`(전진량) 두 축만 세고 있었다. 둘로는
+ * "10회를 썼고 2회 전진했다" 까지만 알 수 있고, 그 2회가 싼 전진이었는지 비싼
+ * 전진이었는지는 모른다. vibe 가 효율에 대해 아무 주장도 할 수 없는 이유가 그것이다
+ * (constitution §3.5 — 측정하지 않은 수치는 쓰지 않는다).
+ *
+ * **수치의 출처는 코드여야 한다.** 모델이 "도구를 12번 썼다" 고 보고하는 형태면 그건
+ * vibe 가 완료 판정에서 배제하는 바로 그 자기보고이고, 그 위에 쌓인 데이터로는
+ * 아무것도 주장할 수 없다. 그래서 인자로 받지 않고 이미 코드가 세고 있는 것을 읽는다 —
+ * `step-counter.js`(PostToolUse)가 액션 툴콜을 `current-run.jsonl` 에 스로틀 없이 append 한다.
+ *
+ * 두 가지를 0 과 구분해서 남긴다. 이게 이 모듈의 존재 이유의 절반이다:
+ *  - `measured: false` — 훅 미설치·첫 실행이라 **재지 못했다**. 0 이 아니다
+ *  - `truncated: true` — 로그가 회전해 창의 앞부분이 사라졌다. 그 값은 **하한**이다
+ * 재지 못한 것을 0 으로 채우면 훅 미설치 환경에서 "회전당 도구 0회" 라는 거짓 데이터가
+ * 쌓이고, 훅은 프로젝트 로컬이라 미설치가 흔하다.
+ */
+
+import fs from 'fs';
+import path from 'path';
+
+/** 서브에이전트 스폰 툴 — 하네스가 이름을 바꾼다. 옛 이름을 지우지 않는다 (step-counter 와 같은 규칙) */
+const SUBAGENT_TOOLS = new Set(['Agent', 'Task']);
+
+function toolLogPath(projectDir) {
+  return path.join(projectDir, '.vibe', 'metrics', 'current-run.jsonl');
+}
+
+function historyPath(projectDir) {
+  return path.join(projectDir, '.vibe', 'metrics', 'loop-history.jsonl');
+}
+
+/** 회전 마커 — `step-counter.js` 가 jsonl 앞부분을 잘라낼 때 남긴다 */
+function rotationMarkerPath(projectDir) {
+  return path.join(projectDir, '.vibe', 'metrics', 'current-run-rotation.json');
+}
+
+/**
+ * 창의 앞부분이 회전으로 사라졌는가.
+ *
+ * **추측하지 않고 마커를 읽는다.** "로그의 첫 줄이 창 시작보다 뒤" 라는 추측은 회전이
+ * 없어도 항상 참이다 — 창 시작 직후에 툴콜이 없었을 뿐일 수 있다. 그 추측으로 두면
+ * 멀쩡한 회전이 전부 `truncated` 로 찍혀 합계에서 조용히 빠진다. 재지 못한 것을 0 으로
+ * 적지 않으려다 잰 것까지 버리는 셈이다.
+ *
+ * @param {string} projectDir
+ * @param {string} startTs 창 시작 ISO-8601
+ * @returns {boolean}
+ */
+function windowTruncated(projectDir, startTs) {
+  try {
+    const marker = JSON.parse(fs.readFileSync(rotationMarkerPath(projectDir), 'utf-8'));
+    return Boolean(marker && marker.keptFrom && marker.keptFrom > startTs);
+  } catch {
+    return false; // 마커 없음 = 회전 없음
+  }
+}
+
+function readJsonLines(filePath) {
+  const raw = fs.readFileSync(filePath, 'utf-8');
+  const out = [];
+  for (const line of raw.split('\n')) {
+    if (!line) continue;
+    try { out.push(JSON.parse(line)); } catch { /* 손상된 줄 무시 */ }
+  }
+  return out;
+}
+
+/**
+ * 회전 창의 시작 시각 — 직전 `iteration`, 없으면 직전 `start`.
+ *
+ * 별도 신호를 만들지 않는 이유: 원장이 이미 두 시각을 갖고 있다. 새 신호를 만들면
+ * 그것이 기록되지 않는 경로가 생기고, 그 경로에서 계측이 조용히 죽는다.
+ *
+ * @param {string} projectDir
+ * @param {string} loop
+ * @returns {string|null} ISO-8601, 판단 불가면 null
+ */
+export function windowStart(projectDir, loop) {
+  try {
+    const events = readJsonLines(historyPath(projectDir)).filter((e) => e && e.loop === loop);
+    for (let i = events.length - 1; i >= 0; i -= 1) {
+      if (events[i].event === 'iteration' || events[i].event === 'start') {
+        return events[i].ts || null;
+      }
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * 창은 `(startTs, endTs]` **반열림**이다.
+ *
+ * 경계에 정확히 걸친 호출을 앞 회전 몫으로 두어야 이중 계수가 나지 않는다 — 직전
+ * 회전의 창은 그 시각을 끝으로 포함해 이미 세었다. 같은 밀리초 충돌은 실제로 일어난다.
+ */
+function countInWindow(entries, startTs, endTs) {
+  let toolCalls = 0;
+  let subagents = 0;
+  for (const entry of entries) {
+    const ts = entry && entry.ts;
+    if (!ts || !entry.tool || ts <= startTs || ts > endTs) continue;
+    toolCalls += 1;
+    if (SUBAGENT_TOOLS.has(entry.tool)) subagents += 1;
+  }
+  return { toolCalls, subagents };
+}
+
+/** 재지 못한 회전 — 0 이 아니라 null 로 남긴다 */
+function unmeasured(elapsedMs, reason) {
+  return { measured: false, reason, elapsedMs, toolCalls: null, subagents: null, truncated: false };
+}
+
+/**
+ * 이번 회전의 비용을 잰다.
+ *
+ * `elapsedMs` 는 툴 로그와 무관하게 원장 `ts` 만으로 나오므로 로그가 없어도 계산한다.
+ *
+ * @param {string} projectDir
+ * @param {string} loop
+ * @param {string} [endTs] 회전 종료 시각 ISO-8601 (기본: 지금)
+ * @returns {{ measured: boolean, reason?: string, elapsedMs: number|null,
+ *            toolCalls: number|null, subagents: number|null, truncated: boolean }}
+ */
+export function measureIterationCost(projectDir, loop, endTs) {
+  const end = endTs || new Date().toISOString();
+  let elapsedMs = null;
+  try {
+    const start = windowStart(projectDir, loop);
+    if (start) elapsedMs = Math.max(0, Date.parse(end) - Date.parse(start));
+
+    if (!start) return unmeasured(elapsedMs, 'no-window-start');
+    const logPath = toolLogPath(projectDir);
+    if (!fs.existsSync(logPath)) return unmeasured(elapsedMs, 'no-tool-log');
+
+    const entries = readJsonLines(logPath);
+    if (entries.length === 0) return unmeasured(elapsedMs, 'empty-tool-log');
+
+    // 로그가 회전해 창의 앞부분이 사라졌으면 이 회전의 수치는 하한이다
+    const truncated = windowTruncated(projectDir, start);
+    const { toolCalls, subagents } = countInWindow(entries, start, end);
+    return { measured: true, elapsedMs, toolCalls, subagents, truncated };
+  } catch {
+    return unmeasured(elapsedMs, 'measure-failed');
+  }
+}
+
+/**
+ * 회전별 비용을 합산한다.
+ *
+ * 미측정·절단 회전은 **합계에서 뺀다.** 대신 `measuredIterations` 로 분모를 함께 낸다 —
+ * 분모를 모르면 합계는 거짓말이 된다 ("5회전에 도구 20회" 인지 "그중 2회전만 잰 20회" 인지).
+ *
+ * @param {Array<{cost?: object}>} iterationEvents
+ * @returns {{ measuredIterations: number, unmeasuredIterations: number,
+ *            elapsedMs: number, toolCalls: number, subagents: number }}
+ */
+export function sumIterationCosts(iterationEvents) {
+  const total = {
+    measuredIterations: 0, unmeasuredIterations: 0, elapsedMs: 0, toolCalls: 0, subagents: 0,
+  };
+  for (const event of iterationEvents) {
+    const cost = event && event.cost;
+    if (!cost || cost.measured !== true || cost.truncated === true) {
+      total.unmeasuredIterations += 1;
+      continue;
+    }
+    total.measuredIterations += 1;
+    total.elapsedMs += Number(cost.elapsedMs) || 0;
+    total.toolCalls += Number(cost.toolCalls) || 0;
+    total.subagents += Number(cost.subagents) || 0;
+  }
+  return total;
+}

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

@@ -14,6 +14,7 @@
 import fs from 'fs';
 import path from 'path';
 import crypto from 'crypto';
+import { measureIterationCost, sumIterationCosts } from './iteration-cost.js';
 
 /** 루프 이력 파일 경로 */
 function historyPath(projectDir) {
@@ -36,7 +37,7 @@ export function hashDiscoverOutput(text) {
  * 루프 이벤트를 jsonl 파일에 append한다.
  *
  * @param {string} projectDir
- * @param {{ loop: string, event: 'start'|'discover'|'end'|'iteration'|'trial-approved', result?: 'ok'|'fail'|'stuck', summary?: string, discoverHash?: string, verified?: boolean }} opts
+ * @param {{ loop: string, event: 'start'|'discover'|'end'|'iteration'|'trial-approved', result?: 'ok'|'fail'|'stuck', summary?: string, discoverHash?: string, verified?: boolean, cost?: object }} opts
  * @returns {boolean} 성공 여부
  */
 export function appendLoopEvent(projectDir, opts) {
@@ -51,6 +52,7 @@ export function appendLoopEvent(projectDir, opts) {
       ...(opts.summary !== undefined ? { summary: opts.summary } : {}),
       ...(opts.discoverHash !== undefined ? { discoverHash: opts.discoverHash } : {}),
       ...(opts.verified !== undefined ? { verified: opts.verified } : {}),
+      ...(opts.cost !== undefined ? { cost: opts.cost } : {}),
     };
     fs.appendFileSync(p, JSON.stringify(entry) + '\n', 'utf-8');
     return true;
@@ -121,13 +123,28 @@ export function isStuck(projectDir, loop, discoverHash) {
 /**
  * 회전 1회를 기록한다.
  *
+ * 비용은 **기록 시점에 재서 원장에 박는다.** 나중에 파생하지 않는 이유: 툴 로그
+ * (`current-run.jsonl`)는 2MB/5000줄에서 회전하므로 과거 창은 이미 사라졌을 수 있고,
+ * 그러면 조용히 낮은 값이 나온다. 계측은 재지 못한 것을 0 으로 채우지 않는 것이 절반이다.
+ *
+ * 계측은 append 보다 **먼저** 한다 — 창의 끝이 이번 회전이므로, 이 이벤트가 이력에
+ * 들어간 뒤에 재면 창이 자기 자신에서 시작한다.
+ *
  * @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) });
+  let cost;
+  try {
+    cost = measureIterationCost(projectDir, loop);
+  } catch {
+    cost = undefined; // fail-open — 계측 실패가 회전 기록을 막지 않는다
+  }
+  return appendLoopEvent(projectDir, {
+    loop, event: 'iteration', verified: Boolean(verified), ...(cost ? { cost } : {}),
+  });
 }
 
 /**
@@ -146,11 +163,25 @@ export function recordIteration(projectDir, loop, verified) {
  *
  * @param {string} projectDir
  * @param {string} loop
+ * 세 번째 축(`cost`)은 **계측이지 판정이 아니다** — 예산 소진이나 stuck 을 좌우하지
+ * 않는다. 재지 못하거나 창이 잘린 회전은 합계에서 빠지고 `cost.measuredIterations` 가
+ * 분모를 알려준다. 분모를 모르면 합계는 거짓말이 된다.
+ *
+ * ⚠️ 이 수치로 "N% 절감" 같은 문구를 쓰지 않는다 — 비교 데이터가 쌓이기 전의
+ * 배수·퍼센트는 constitution §3.5 가 금지하는 바로 그것이다. 쌓기만 한다.
+ *
  * @param {number} [maxIterations=10]
- * @returns {{ iterations: number, verified: number, remaining: number, exhausted: boolean }}
+ * @returns {{ iterations: number, verified: number, remaining: number, exhausted: boolean,
+ *             cost: { measuredIterations: number, unmeasuredIterations: number,
+ *                     elapsedMs: number, toolCalls: number, subagents: number } }}
  */
 export function readBudget(projectDir, loop, maxIterations = 10) {
-  const empty = { iterations: 0, verified: 0, remaining: maxIterations, exhausted: false };
+  const emptyCost = {
+    measuredIterations: 0, unmeasuredIterations: 0, elapsedMs: 0, toolCalls: 0, subagents: 0,
+  };
+  const empty = {
+    iterations: 0, verified: 0, remaining: maxIterations, exhausted: false, cost: emptyCost,
+  };
   try {
     const raw = fs.readFileSync(historyPath(projectDir), 'utf-8');
     const events = raw.split('\n')
@@ -164,7 +195,9 @@ export function readBudget(projectDir, loop, maxIterations = 10) {
     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 };
+    return {
+      iterations, verified, remaining, exhausted: remaining === 0, cost: sumIterationCosts(iters),
+    };
   } catch {
     return empty;
   }

package/hooks/scripts/loop-ledger.js

@@ -13,6 +13,9 @@
  *   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]
+ *
+ * iteration: 회전을 기록하면서 비용(경과 시간·도구 호출 수·서브에이전트 수)을 함께 잰다.
+ *   수치의 출처는 코드다 — 모델이 보고한 값을 받는 인자는 두지 않는다.
  *   node hooks/scripts/loop-ledger.js trial <name> [trialIterations]
  *   node hooks/scripts/loop-ledger.js trial-approve <name>
  *
@@ -88,7 +91,12 @@ if (subcommand === 'start') {
   }
   recordIteration(projectDir, loop, verifiedArg === 'verified');
   const b = readBudget(projectDir, loop);
-  process.stdout.write(`[loop-ledger] iteration recorded: ${loop} ${verifiedArg} (${b.iterations} 회전 / 검증 ${b.verified})\n`);
+  // 비용은 계측이지 판정이 아니다 — 재지 못한 회전은 0 이 아니라 '미측정' 으로 보인다
+  const c = b.cost;
+  const costNote = c.measuredIterations > 0
+    ? `도구 ${c.toolCalls} / 서브에이전트 ${c.subagents} / ${Math.round(c.elapsedMs / 1000)}s (측정 ${c.measuredIterations}회전)`
+    : '비용 미측정';
+  process.stdout.write(`[loop-ledger] iteration recorded: ${loop} ${verifiedArg} (${b.iterations} 회전 / 검증 ${b.verified}) — ${costNote}\n`);
 
 } else if (subcommand === 'budget') {
   const [loop, maxRaw] = args;

package/hooks/scripts/pre-tool-guard.js

@@ -198,6 +198,7 @@ function formatOutput(toolName, validation) {
 import { logHookDecision, PROJECT_DIR } from './utils.js';
 import { buildCliCtx, isDirectRun } from './lib/hook-context.js';
 import { runPrTestGate } from './lib/pr-gate-runner.js';
+import { ephemeralPathsInGitCommand, formatEphemeralBlock } from './lib/ephemeral-lane.js';
 
 /** gh pr create 감지 정규식 (단어 경계 기준, 플래그 허용). */
 const GH_PR_CREATE_RE = /\bgh\s+pr\s+create\b/;
@@ -237,6 +238,21 @@ export async function run(ctx) {
     }
   }
 
+  // 2-b단계: 일회성 경로를 커밋하려는 시도 차단 (심층 방어)
+  //
+  // 1차 방어는 gitignore 다 — `git add` 는 무시된 경로를 그냥 거부한다. 실제로 뚫리는
+  // 경로는 `git add -f` 하나뿐이고 여기서 그것을 막는다. 훅은 프로젝트 로컬이라
+  // 미설치가 흔하므로 이것을 1차라고 부르지 않는다.
+  if (toolName === 'Bash' || toolName === 'bash') {
+    const command = extractTarget(toolInput, 'command') || toolInput;
+    const ephemeral = ephemeralPathsInGitCommand(command);
+    if (ephemeral.length > 0) {
+      console.error(formatEphemeralBlock(ephemeral));
+      logHookDecision('pre-tool-guard', 'Bash', 'block', `ephemeral commit: ${ephemeral.join(', ')}`);
+      return 2;
+    }
+  }
+
   // 3단계: 위험 패턴 검증 (보안 탐지)
   const validation = validateCommand(toolName, toolInput);
   const output = formatOutput(toolName, validation);

package/hooks/scripts/step-counter.js

@@ -41,6 +41,8 @@ const METRICS_DIR = projectVibePath(PROJECT_DIR, 'metrics');
 const ANTI_PATTERNS_DIR = projectVibePath(PROJECT_DIR, 'anti-patterns');
 const CURRENT_RUN_JSON = path.join(METRICS_DIR, 'current-run.json');
 const CURRENT_RUN_JSONL = path.join(METRICS_DIR, 'current-run.jsonl');
+// 회전 마커 — jsonl 앞부분이 잘린 사실을 소비자가 추측하지 않게 남긴다 (iteration-cost.js 가 읽는다)
+const CURRENT_RUN_ROTATION = path.join(METRICS_DIR, 'current-run-rotation.json');
 const MAX_JSONL_LINES = 5000;
 const FAIL_WINDOW = 10;
 const FAIL_THRESHOLD = 3;
@@ -169,6 +171,32 @@ function bumpCounter(toolName, currentLineCount) {
 // 책임 2: current-run.jsonl append + error_category 채움
 // 항상 즉시 append — 스로틀 없음 (3-fail detector, recipe-extractor 가 소비)
 // ─────────────────────────────────────────────────────
+
+/**
+ * 회전 사실을 **기록한다** — 소비자가 추측하지 않게.
+ *
+ * 회전은 로그의 앞부분을 지우므로, 그 뒤로 계산되는 구간 집계는 전부 하한이 된다.
+ * 그런데 "로그의 첫 줄이 구간 시작보다 뒤" 라는 추측으로는 회전을 알아낼 수 없다 —
+ * 그건 회전이 없어도 항상 참이다(구간 시작 직후에 툴콜이 없었을 뿐일 수 있다).
+ * 추측으로 두면 소비자가 멀쩡한 구간을 조용히 버린다.
+ *
+ * 별도 파일에 쓰는 이유: jsonl 에 마커 줄을 끼우면 이 파일을 툴콜 기록으로 읽는
+ * 기존 소비자(recipe-extractor · 3-fail detector)가 그것을 툴콜로 센다.
+ *
+ * @param {string[]} keptLines 회전 후 남긴 줄들
+ */
+function writeRotationMarker(keptLines) {
+  try {
+    let keptFrom = null;
+    for (const line of keptLines) {
+      try { keptFrom = JSON.parse(line).ts || null; break; } catch { /* 손상된 줄 건너뜀 */ }
+    }
+    fs.writeFileSync(
+      CURRENT_RUN_ROTATION,
+      JSON.stringify({ rotatedAt: new Date().toISOString(), keptFrom }, null, 2),
+    );
+  } catch { /* 마커 실패는 무시 — 회전 자체를 막지 않는다 */ }
+}
 function appendJsonl(ctx) {
   const toolName = ctx.toolName;
   if (!toolName) return null;
@@ -194,6 +222,7 @@ function appendJsonl(ctx) {
       if (lines.length > MAX_JSONL_LINES) {
         const keep = lines.slice(-Math.floor(MAX_JSONL_LINES / 2));
         fs.writeFileSync(CURRENT_RUN_JSONL, keep.join('\n') + '\n');
+        writeRotationMarker(keep);
       }
     }
   } catch { /* 회전 실패는 무시 */ }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@su-record/vibe",
-  "version": "3.2.61",
+  "version": "3.2.64",
   "description": "AI Coding Framework for Claude Code — 7+ agents, 52 skills, multi-LLM orchestration",
   "type": "module",
   "main": "dist/cli/index.js",
@@ -31,7 +31,7 @@
     "validate:counts": "tsx scripts/validate-counts.ts",
     "lint": "oxlint",
     "lint:ratchet": "tsx scripts/lint-ratchet.ts",
-    "verify:all": "pnpm lint && pnpm lint:ratchet && pnpm gen:skill-docs:check && pnpm sync:agent-models:check && pnpm validate:skill-invocation && pnpm validate:counts",
+    "verify:all": "pnpm lint && pnpm lint:ratchet && pnpm gen:skill-docs:check && pnpm sync:agent-models:check && pnpm validate:skill-invocation && pnpm validate:counts && pnpm gen:agents-md:check && pnpm validate:spec-lifecycle && pnpm validate:cache-surface",
     "test": "vitest run",
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
@@ -44,7 +44,11 @@
     "gen:plugin-hooks": "npx tsx scripts/gen-plugin-hooks.ts",
     "gen:plugin-hooks:check": "npx tsx scripts/gen-plugin-hooks.ts --check",
     "validate:plugin-tree": "npx tsx scripts/build-plugin.ts && git diff --exit-code --stat HEAD -- plugins/",
-    "validate:mermaid": "npx tsx scripts/validate-mermaid.ts"
+    "validate:mermaid": "npx tsx scripts/validate-mermaid.ts",
+    "validate:spec-lifecycle": "npx tsx scripts/validate-spec-lifecycle.ts",
+    "validate:cache-surface": "npx tsx scripts/validate-cache-surface.ts",
+    "gen:agents-md": "npx tsx scripts/gen-agents-md.ts",
+    "gen:agents-md:check": "npx tsx scripts/gen-agents-md.ts --check"
   },
   "keywords": [
     "ai",

package/skills/vibe.contract/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: vibe.contract
 description: Use when a SPEC API contract may differ from implementation or endpoint and schema drift must be detected.
-argument-hint: "extract | check | diff [feature-name]"
+argument-hint: "extract | check | reverse | agent | diff [feature-name]"
 user-invocable: true
 ---
 
@@ -17,6 +17,8 @@ user-invocable: true
 /vibe.contract extract <feature>       # SPEC → contract record at .vibe/contracts/<feature>.md
 /vibe.contract check <feature>         # contract vs implementation, drift report
 /vibe.contract diff <feature>          # changed fields since last check
+/vibe.contract reverse <feature>       # implementation → SPEC, SPEC 결손을 인박스로
+/vibe.contract agent <feature>         # 에이전트 계약 vs 도구 호출 로그
 ```
 
 ## What counts as an "API contract"
@@ -91,6 +93,7 @@ Hidden vibe-coding weakness: as the implementation grows, response shapes drift
 .vibe/contracts/
   <feature>.md             # contract SSOT (extracted from SPEC)
   <feature>.snapshot.md    # implementation snapshot (last check)
+  <feature>.reverse.md     # 역방향 대조 결과 (구현에만 있는 표면)
 ```
 
 ### Contract frontmatter schema
@@ -176,6 +179,101 @@ endpoints:
    ```
 4. On any drift, auto-call `/vibe.regress register --from-contract`
 
+### 4. `reverse` — implementation → SPEC (역방향)
+
+`check` 가 "SPEC 이 약속한 것을 구현이 지키는가" 를 본다면, `reverse` 는 **"구현이 가진 표면을 SPEC 이
+알고 있는가"** 를 본다. 둘을 합치지 않는 이유는 방향이 아니라 **귀결이 반대**이기 때문이다.
+
+> SPEC 은 승인 시점에 얼어붙는다. 구현이 알아낸 사실이 돌아오는 경로가 없으면
+> "의도 설계자" 의 산출물은 시간이 지날수록 실제 시스템과 멀어진다.
+
+**대상**: `구현 ⊃ SPEC` 인 경우만. 구현이 SPEC 보다 **좁은** 것(약속한 필드가 없다 등)은
+`check` 의 관할이다 — 여기서 다시 보지 않는다.
+
+**Steps**:
+1. `.vibe/contracts/<feature>.md` 로드. 없으면 → `extract` 를 먼저 제안하고 종료
+2. 구현 표면을 수집한다 — **탐지기를 새로 만들지 않고** 아래 Framework Detection Rules 를 그대로 쓴다
+3. 계약에 없는 표면을 4종으로 분류한다 (아래 등급표)
+4. `.vibe/contracts/<feature>.reverse.md` 로 기록 — **발견 0건이어도 파일을 낸다**
+   ("아직 안 돌렸다" 와 "돌렸는데 깨끗하다" 는 구분되어야 한다)
+5. 발견이 있으면 인박스에 올린다 (아래 명령)
+
+**등급 매핑은 정방향과 반대다** — 구현에만 있는 표면은 코드 실패가 아니라 **SPEC 결손**이다:
+
+| 종류 | 등급 | 예 |
+|---|---|---|
+| `unspecified-endpoint` | P2 | 구현에 `GET /users/:id/avatar` 가 있는데 SPEC 에 없다 |
+| `unspecified-field` | P3 | 응답에 `phoneNumber` 가 있는데 계약에 없다 |
+| `unspecified-status-code` | P3 | 구현이 `429` 를 내는데 SPEC 에 없다 |
+| `unspecified-parameter` | P3 | 문서화되지 않은 쿼리 파라미터 |
+
+⛔ **역방향은 차단하지 않는다. P1 을 만들지 않는다.** 판정 주체가 LLM 추출이므로
+loop-contract 의 Judge 권한 경계상 "판정된 P1" 이고, 그것은 단독으로 차단 근거가 아니다.
+verify 를 강등하지 않고, `vibe.regress` 에 등록하지 않으며, SPEC 을 자동으로 고쳐 쓰지 않는다
+(SPEC 확정은 유일한 의무적 사람 개입 지점이다 — 자동 갱신은 그 게이트를 우회한다).
+
+등급·목적지와 출력 형식은 산문이 아니라 코드가 고정한다 (`src/tools/contract/reverseDrift.ts`) —
+`blocking: false` 와 `destination: 'inbox'` 가 리터럴 타입이라 차단하는 분류를 만들 수 없다:
+
+```bash
+node -e "import('{{VIBE_PATH_URL}}/node_modules/@su-record/vibe/dist/tools/index.js').then(t => {
+  const findings = [{ kind: 'unspecified-endpoint', surface: '<GET /path>', location: '<file:line>' }];
+  console.log(t.formatReverseReport({ feature: '<feature>', specPath: '<.vibe/specs/x.md>', comparedAt: new Date().toISOString(), findings }));
+  console.log(JSON.stringify(t.formatReverseInboxLines('<feature>', findings)));
+})"
+```
+
+인박스 기록 (발견 0건이면 줄이 빈 배열로 나오므로 **호출하지 않는다**):
+
+```bash
+node "$HOOKS_DIR/loop-ledger.js" inbox <feature> ok "<line 1>" "<line 2>" …
+```
+
+### 5. `agent` — 에이전트 계약 vs 도구 호출 로그 (런타임 축)
+
+vibe 는 빌드타임만 다룬다. 그런데 사용자가 만드는 것이 **에이전트 제품**일 때, 그 에이전트가
+사용자 앞에서 내리는 판단은 vibe 의 어떤 게이트도 보지 않는다. 그렇다고 vibe 를 런타임에 넣으면
+`loop-contract` 의 push·release·배포 금지를 정면으로 깬다.
+
+그래서 vibe 가 런타임에 들어가는 대신 **런타임 게이트를 빌드타임에 생성한다.** SPEC 의
+`## Agent Contract` 섹션이 스위치다 (`## API Contract` 와 같은 관례).
+
+⛔ **LLM 이 에이전트 응답을 채점하지 않는다.** 그건 Model Judge 이고 완료 권한이 없다.
+단언 대상은 **도구 호출 로그**이고, "금지된 도구를 불렀는가" 는 관측된 사실이라 **차단한다** —
+`reverse` 가 절대 차단하지 않는 것과 반대 방향의 결정이며, 그 차이가 곧 Judge 권한 경계다.
+
+**Steps**:
+1. SPEC 에서 `## Agent Contract` 를 파싱한다. 없으면 → 조용히 종료 (모든 기능에 에이전트가 있지 않다)
+2. `validateAgentContract` 로 정의를 검사한다. P1 이면 실행하지 않는다
+3. 에이전트 실행 로그를 `{ tool, approved?, ts? }[]` 로 모은다 — **vibe 자신의 로그 형식**이다
+   (`step-counter.js` 의 `current-run.jsonl`). 새 형식을 발명하지 않는다
+4. `checkAgentToolLog` → 위반과 advisory
+5. 위반이 있으면 `blocking: true` — verify 를 실패로 내린다. **로그가 없으면 `checked: false` 이고,
+   그것은 위반 0건이 아니다** (안 본 것과 봤는데 깨끗한 것은 다르다)
+
+| 위반 | 뜻 |
+|---|---|
+| `forbidden-tool` | 계약이 금지한 도구를 호출했다 |
+| `unlisted-tool` | allowlist 가 선언됐는데 목록 밖 도구를 호출했다 (미선언이면 검사하지 않는다) |
+| `unapproved-irreversible` | 되돌릴 수 없는 작업을 승인 기록 없이 호출했다 |
+
+**`Escalate` 는 게이트가 아니다.** 조건 충족 여부가 도구 로그에 없어 판정할 수 없다. 선언은 받되
+`advisory` 로 사람에게 넘긴다 — 판정할 수 없는 것을 게이트에 넣으면 통과 의식이 되고,
+그건 없는 게이트보다 나쁘다.
+
+도구 이름은 **정확히 일치**만 인정한다. 글롭을 허용하면 `send_*` 가 `send_log` 까지 잡는지
+아무도 확신하지 못한다.
+
+```bash
+node -e "import('{{VIBE_PATH_URL}}/node_modules/@su-record/vibe/dist/tools/index.js').then(t => {
+  const spec = require('fs').readFileSync('<.vibe/specs/x.md>', 'utf-8');
+  const contract = t.parseAgentContract(spec);
+  if (!contract) { console.log('no-agent-contract'); return; }
+  console.log(JSON.stringify(t.validateAgentContract(contract)));
+  console.log(JSON.stringify(t.checkAgentToolLog(contract, JSON.parse(process.env.AGENT_LOG || 'null'))));
+})"
+```
+
 ## Integration Points
 
 ### From /vibe.spec
@@ -196,6 +294,15 @@ Load skill `vibe.contract` with: check <feature>
 - P1 drift → demote verify to fail; auto-register
 - P2 / P3 drift → warning only; verify still passes
 
+이어서 역방향도 한 번 돌린다:
+```
+Load skill `vibe.contract` with: reverse <feature>
+```
+SPEC 에 `## Agent Contract` 가 있으면 `agent <feature>` 도 돌린다 — 위반은 **차단한다**
+(판정 대상이 도구 로그이므로 관측된 사실이다).
+- 결과와 **무관하게 verify 판정은 바뀌지 않는다** — 발견은 인박스로만 간다
+- 인박스에 올린 뒤 파이프라인을 계속 진행한다 (사람을 세우지 않는다)
+
 ### To /vibe.regress
 
 On P1 drift:
@@ -230,3 +337,9 @@ After detection, grep for each framework's **route definition pattern** to map e
 - [ ] `check` reports each drift with severity + location (file:line)
 - [ ] P1 drift always invokes `/vibe.regress`
 - [ ] On framework detection failure, ask the user — do not silently skip
+- [ ] `reverse` 는 어떤 발견에도 verify 판정을 바꾸지 않는다
+- [ ] `reverse` 는 발견 0건이어도 `.reverse.md` 를 남긴다
+- [ ] `reverse` 는 발견 0건이면 인박스를 호출하지 않는다
+- [ ] `agent` 는 섹션이 없는 SPEC 에서 조용히 종료한다
+- [ ] `agent` 는 로그가 없으면 `checked:false` 로 남긴다 — 위반 0건으로 적지 않는다
+- [ ] `agent` 의 `Escalate` 는 advisory 로만 나가고 차단하지 않는다

package/skills/vibe.docs/references/agent.md

@@ -17,6 +17,10 @@ Cursor is not supported — do not generate or check Cursor-specific context fil
 **Source of truth:**
 - **`CLAUDE.md` is the content SSOT.** Always edit it first; `AGENTS.md` is a regenerated derivative.
 - Behavioral block: `skills/vibe.docs/templates/behavioral-principles.md` (4 Karpathy principles, wrapped in `<!-- VIBE-BEHAVIORAL:START/END -->` markers).
+- **번역 규칙이 파일로 존재하면 그 파일이 SSOT다.** 프로젝트 루트에 `scripts/agents-md-rules.json` 이 있으면
+  아래 4·5번 손 치환 목록을 쓰지 않고 `npm run gen:agents-md` 로 생성한다 — 규칙을 두 곳에 적으면
+  그 순간 두 벌이 되고, 어느 쪽이 맞는지 판정할 수단이 사라진다. 검증은 `npm run gen:agents-md:check`.
+  (vibe 저장소 자신이 이 경로다. 규칙 파일이 없는 프로젝트는 4·5번을 그대로 적용한다.)
 
 **Procedure (applies to both creation and modification):**
 

package/skills/vibe.loop/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: vibe.loop
 description: 반복 작업을 자율 goal loop로 설계·설치·실행하고 결정론적 gate로 완료를 판정해야 할 때 사용한다.
-argument-hint: "design | install | run | status | list [loop-name]"
+argument-hint: "design | install | run | status | list | bench [loop-name]"
 user-invocable: true
 ---
 
@@ -27,6 +27,7 @@ user-invocable: true
 /vibe.loop run <name>           # 1회 반복 실행 (스케줄러가 호출하는 진입점)
 /vibe.loop status [name]        # 실행 이력 + 인박스 요약
 /vibe.loop list                 # 정의된 루프 목록과 상태
+/vibe.loop bench <name>         # 루프 설정 자기 대조 — 조건만 바꿔 돌린 실행을 비교
 ```
 
 ## 경로 상수 (모든 서브커맨드 공통)
@@ -129,6 +130,50 @@ node -e "import('{{VIBE_PATH_URL}}/node_modules/@su-record/vibe/dist/tools/loop/
 - `list`: `$LOOPS_DIR/*.md`의 frontmatter(name, trigger, status, goal) 테이블.
 - `status [name]`: `$HISTORY`에서 해당 루프(생략 시 전체)의 최근 10개 이벤트 + 인박스의 미처리 블록 수.
 
+## bench — 자기 대조 벤치마크
+
+`loop-contract.md` 는 `per-iteration` vs `continuous` 를 두고 **"어느 쪽이 결과가 나은지는 vibe 가
+측정한 바 없다"** 고 적어두었다. 축만 열고 기본값을 바꾸지 않은 이유가 그것이다. `bench` 는 그
+문장을 지울 수 있게 하는 도구다 — 외부 벤치마크(SWE-bench 등)와 겨루는 것이 아니라 **같은 루프를
+조건만 바꿔 돌린 결과끼리** 비교한다.
+
+**핵심은 비교가 아니라 판정 불가다.** 벤치 산출물은 곧 문서의 수치가 되므로, 판정을 절제에
+맡기면 constitution §3.5 가 금지하는 배수·퍼센트가 그 자리에서 만들어진다. 그래서 코드가 낸다.
+
+**Steps**:
+1. 벤치 정의를 만든다 — `name` · `taskSet`(모든 arm 이 동일하게 수행할 과제 id) ·
+   `arms`(비교할 조건 2개 이상, **이 축만 다르고 나머지는 같아야 한다**) · `minRunsPerArm`(기본 5)
+2. `validateBenchDefinition` 으로 검사한다. P1 이 있으면 실행하지 않는다
+3. arm 마다 `taskSet` 을 `minRunsPerArm` 회 이상 돌린다. 각 실행은 `loop-ledger.js budget` 산출물에서
+   `{armId, taskSetHash, gatesPassed, iterations, cost}` 를 남긴다
+4. `summarizeArm` → `compareArms` → `formatBenchReport`
+5. 리포트를 `~/.vibe/test-reports/<YYYYMMDD-HHmm>-bench-<name>.md` 에 쓴다 (**프로젝트 로컬 금지**)
+
+**판정 어휘 4종 — `winner` 는 없다**:
+
+| verdict | 뜻 |
+|---|---|
+| `insufficient-runs` | arm 당 사용 가능 실행이 `minRunsPerArm` 미만 — 어떤 차이든 우연과 구분되지 않는다 |
+| `mixed-task-sets` | 두 arm 이 같은 과제 셋을 돌지 않았다 — 다른 일을 시킨 결과는 비교가 아니다 |
+| `inconclusive` | 관측 범위(min~max)가 겹친다 — 이 표본으로는 차이를 말할 수 없다 |
+| `difference-observed` | 범위가 겹치지 않는다. **"차이가 관측됐다" 이지 "A 가 낫다" 가 아니다** |
+
+⛔ **비율·퍼센트·배수를 만들지 않는다.** 차이는 절대 단위 `delta` 로만 나오고, 게이트 통과도
+"3/5 회" 로 적지 "60%" 로 적지 않는다. 판정 규칙은 범위 겹침이며 **유의성 검정이 아니다** —
+표본이 한 자릿수인데 t-검정을 붙이면 정밀해 *보이는* 숫자가 나온다.
+
+⛔ **bench 는 아무것도 차단하지 않고, 기본값을 자동으로 바꾸지 않는다.** 리포트다.
+어느 조건을 고를지는 지표의 방향을 아는 사람이 정한다.
+
+```bash
+node -e "import('{{VIBE_PATH_URL}}/node_modules/@su-record/vibe/dist/tools/index.js').then(t => {
+  const runs = JSON.parse(process.env.BENCH_RUNS);   // 위 3단계에서 모은 실행 기록
+  const a = t.summarizeArm('<arm-a>', runs), b = t.summarizeArm('<arm-b>', runs);
+  const cmp = t.compareArms(a, b, 'iterations');
+  console.log(t.formatBenchReport({ name: '<bench-name>', ranAt: new Date().toISOString(), comparison: cmp }));
+})"
+```
+
 ## Auto-integration
 
 - `/vibe.regress`의 open 항목, `/vibe.contract`의 drift는 nightly-triage discover의 1차 입력이다.
@@ -141,6 +186,7 @@ node -e "import('{{VIBE_PATH_URL}}/node_modules/@su-record/vibe/dist/tools/loop/
 | 완료는 게이트가 판정 | run-ledger `verifyPassed` / 테스트 exit code (REQ-005) |
 | stuck은 해시가 판정 | loop-ledger check-stuck, 동일 발견 2회 연속 (REQ-009) |
 | 회전 수도 코드가 판정 | loop-ledger iteration/budget — iterations(폭주 방어) 와 verified(전진량) 를 분리 |
+| 판정 불가도 코드가 판정 | bench — 표본 부족·과제 셋 불일치·범위 겹침이면 차이를 말하지 않는다 (§3.5) |
 | 이해 부채 가드 | 인박스 리뷰 큐 + push/release 금지 (REQ-008) |
 | 기록 없는 실행 없음 | loop-history.jsonl start/end 의무 (REQ-006) |