@su-record/vibe 2.12.5 → 2.14.0

package/hooks/scripts/sentinel-guard.js

@@ -1,13 +1,31 @@
 #!/usr/bin/env node
 /**
  * Sentinel Guard — PreToolUse hook
- * Protects sentinel files and blocks dangerous operations.
- * Runs before pre-tool-guard.js.
+ * 핵심 자율 기계 경로를 Write/Edit/Bash 로부터 보호한다.
+ * pre-tool-guard.js 이전에 실행된다.
+ *
+ * 보호 경로 결정 근거:
+ *   src/infra/lib/autonomy/ 는 레포에 존재하지 않는 팬텀 경로였다.
+ *   git log 와 src/ 전수 조사 결과, 자율 기계(evolution machinery)의 실제
+ *   위치는 src/infra/lib/evolution/ 이다. GuardAnalyzer·HookTraceReader 등이
+ *   hook-traces.jsonl을 분석해 하네스 자기 개선 인사이트를 생성한다.
+ *   따라서 sentinel 대상을 이 실존 경로로 교체한다.
+ *
+ *   추가로 hooks/scripts/lib/ (디스패처 인프라)도 보호 — 이 디렉토리의
+ *   hook-context.js / dispatcher.js 가 손상되면 모든 pre-tool 게이트가
+ *   무력화된다.
+ *
+ * exit 2 = deny 규약 (PreToolUse 차단).
  */
 
-const SENTINEL_PATH_PREFIX = 'src/infra/lib/autonomy/';
+const SENTINEL_PREFIXES = [
+  'src/infra/lib/evolution/',
+  'hooks/scripts/lib/',
+];
 
-const SENTINEL_PATH_RE = /^(\.\/|\.\\)?src[\\/]infra[\\/]lib[\\/]autonomy[\\/]/;
+// 빠른 prefix 검사용 정규식 (backslash 포함)
+const SENTINEL_PATH_RE =
+  /^(?:\.[\\/])?(?:src[\\/]infra[\\/]lib[\\/]evolution|hooks[\\/]scripts[\\/]lib)[\\/]/;
 
 const DANGEROUS_BASH_RE =
   /\b(rm\s+-rf|kill\s+-9|drop\s+table|truncate|shutdown|reboot|mkfs|dd\s+if=)\b/i;
@@ -23,7 +41,6 @@ function extractFilePath(toolName, input) {
       return parsed.file_path || parsed.filePath || null;
     }
   } catch {
-    // Not JSON, try as plain string
     return typeof input === 'string' ? input : null;
   }
   return null;
@@ -48,7 +65,8 @@ function extractBashCommand(input) {
 function isSentinelPath(filePath) {
   if (!filePath) return false;
   const normalized = filePath.replace(/\\/g, '/').replace(/^\.\//, '');
-  return normalized.startsWith(SENTINEL_PATH_PREFIX) || SENTINEL_PATH_RE.test(filePath);
+  return SENTINEL_PREFIXES.some(p => normalized.startsWith(p)) ||
+    SENTINEL_PATH_RE.test(filePath);
 }
 
 /**
@@ -76,8 +94,7 @@ function guard(toolName, toolInput) {
       };
     }
     if (command && DANGEROUS_BASH_RE.test(command)) {
-      // Check if command targets sentinel files
-      if (command.includes(SENTINEL_PATH_PREFIX) || command.includes('src/infra/lib/autonomy')) {
+      if (SENTINEL_PREFIXES.some(p => command.includes(p))) {
         return {
           decision: 'block',
           reason: `Dangerous command targeting sentinel path: ${command}`,
@@ -86,45 +103,28 @@ function guard(toolName, toolInput) {
     }
   }
 
-  // Allow — return undefined for normal flow
   return undefined;
 }
 
-import fs from 'fs';
+import { logHookDecision } from './utils.js';
+import { buildCliCtx, isDirectRun } from './lib/hook-context.js';
 
 /**
- * stdin에서 JSON 페이로드 읽기 (Claude Code 하네스 호환)
+ * in-process 진입점 — 디스패처가 ctx를 전달해 직접 호출.
+ * @param {{ toolName: string, toolInput: string }} ctx
+ * @returns {Promise<number>} exit code (2 = deny 규약, 0 = allow)
  */
-function readStdinSync() {
-  try {
-    if (process.stdin.isTTY) return null;
-    // fd 0을 직접 사용 (Windows는 '/dev/stdin'이 없음)
-    const buf = Buffer.alloc(65536);
-    const bytesRead = fs.readSync(0, buf, 0, buf.length, null);
-    if (bytesRead > 0) {
-      return JSON.parse(buf.toString('utf-8', 0, bytesRead));
-    }
-  } catch { /* 폴백 */ }
-  return null;
+export async function run(ctx) {
+  const result = guard(ctx.toolName, ctx.toolInput);
+  if (result) {
+    logHookDecision('sentinel-guard', ctx.toolName, 'block', result.reason);
+    console.log(JSON.stringify(result));
+    return 2;
+  }
+  return 0;
 }
 
-// Main execution: stdin JSON 우선, argv 폴백
-const stdinPayload = readStdinSync();
-const toolName = stdinPayload?.tool_name || process.argv[2] || '';
-const toolInput = stdinPayload?.tool_input
-  ? (typeof stdinPayload.tool_input === 'string'
-    ? stdinPayload.tool_input
-    : JSON.stringify(stdinPayload.tool_input))
-  : (process.argv[3] || process.env.TOOL_INPUT || '');
-
-import { logHookDecision } from './utils.js';
-
-const result = guard(toolName, toolInput);
-
-if (result) {
-  logHookDecision('sentinel-guard', toolName, 'block', result.reason);
-  console.log(JSON.stringify(result));
-  process.exit(2); // deny 규약
+// standalone CLI 모드 (antigravity-hooks.json / 기존 테스트): stdin JSON 우선, argv 폴백
+if (isDirectRun(import.meta.url)) {
+  process.exit(await run(buildCliCtx()));
 }
-
-process.exit(0);

package/hooks/scripts/session-start.js

@@ -126,7 +126,7 @@ async function main() {
       }
     }
 
-    // Scope sync — 사용자가 .vibe/config.json scopeGuard.enabled=true 로 켰을 때만 동작.
+    // Scope sync — 기본 ON. scopeGuard.enabled=false 로 명시적 opt-out 가능.
     try {
       const { syncScopeFile, isScopeGuardEnabled } = await import('./lib/scope-from-spec.js');
       if (isScopeGuardEnabled(PROJECT_DIR)) {
@@ -135,6 +135,18 @@ async function main() {
           console.log(`\n🚧 Scope ${result.action} from active SPECs (${path.relative(PROJECT_DIR, path.join(projectVibeRoot(PROJECT_DIR), 'scope.json'))})`);
         }
       }
+      // scope 상태 1줄 알림 — 컨텍스트에 주입되어 모델이 현재 scope 범위를 인지한다
+      const scopeJsonPath = path.join(projectVibeRoot(PROJECT_DIR), 'scope.json');
+      if (fs.existsSync(scopeJsonPath)) {
+        try {
+          const scopeData = JSON.parse(fs.readFileSync(scopeJsonPath, 'utf-8'));
+          const featureLabel = scopeData.reason || path.basename(scopeJsonPath);
+          const modeLabel = scopeData.mode || 'warn';
+          console.log(`\nscope-guard: ${featureLabel} (${modeLabel})`);
+        } catch { /* ignore */ }
+      } else {
+        console.log('\nscope-guard: no active scope (no active SPEC or no derivable paths) — out-of-scope edits are not monitored');
+      }
     } catch { /* scope sync is best-effort */ }
 
     // Autonomy status summary

package/hooks/scripts/step-counter.js

@@ -2,9 +2,19 @@
 /**
  * PostToolUse Hook — 툴콜 스텝 카운터 + 패턴 로거 + 3-fail 감지기
  *
- * 책임 1) 모든 성공 툴콜을 1 스텝으로 집계 → `current-run.json`
+ * hooks.json matcher: "Edit|Write|Bash|Task|SlashCommand|NotebookEdit"
+ * → Read/Grep/Glob/WebFetch/WebSearch/TodoWrite/ToolSearch/ListMcpResourcesTool
+ *   는 matcher 단에서 제외되어 이 프로세스 자체가 spawn 되지 않는다.
+ *   아래 READ_ONLY_TOOLS 는 defense-in-depth 용 추가 가드이다.
+ *
+ * 책임 1) 액션 툴콜을 1 스텝으로 집계 → `current-run.json`
  *        ↳ /vibe.verify 가 history.jsonl에 append 후 출력
- * 책임 2) 각 툴콜 한 줄을 `current-run.jsonl` 에 append (post-task-curation SPEC)
+ *        ↳ recipe-extractor 가 meta(startedAt, steps) 소비
+ *        [쓰기 스로틀] current-run.json 전체 재작성은 (a) 마지막 재작성 후
+ *        ≥2초 경과, 또는 (b) 10이벤트마다 1회로 제한.
+ *        액션 툴(Edit/Write/Bash) 호출 + ≥2초 조건을 동시 충족할 때도 재작성.
+ *        Stop 경로 등 최종 상태가 필요한 소비자는 staleness ≤10 이벤트를 허용.
+ * 책임 2) 각 툴콜 한 줄을 `current-run.jsonl` 에 append (항상 즉시 — 스로틀 없음)
  *        ↳ Phase 3 의 recipe extractor 가 소비
  * 책임 3) (Phase 2) 실패 메시지 분류 + 같은 (file, category) 3회 반복 감지 →
  *        `.vibe/anti-patterns/<slug>.md` 로 자동 저장.
@@ -24,6 +34,16 @@ const MAX_JSONL_LINES = 5000;
 const FAIL_WINDOW = 10;
 const FAIL_THRESHOLD = 3;
 
+// 스로틀 파라미터
+const REWRITE_INTERVAL_MS = 2000; // 최소 재작성 간격
+const REWRITE_EVERY_N = 10;       // N이벤트마다 강제 재작성
+
+// 읽기 전용 툴 — defense-in-depth (matcher 단에서 이미 제거됨)
+const READ_ONLY_TOOLS = new Set([
+  'Read', 'Grep', 'Glob', 'WebFetch', 'WebSearch',
+  'TodoWrite', 'ToolSearch', 'ListMcpResourcesTool',
+]);
+
 // ─────────────────────────────────────────────────────
 // stdin / env 에서 PostToolUse payload 추출
 // ─────────────────────────────────────────────────────
@@ -97,9 +117,43 @@ function classifyError(toolResponse) {
 }
 
 // ─────────────────────────────────────────────────────
-// 책임 1: current-run.json 카운터
+// 스로틀: current-run.json 재작성 여부 결정
+// ─────────────────────────────────────────────────────
+/**
+ * 재작성해야 하는지 판단.
+ * - jsonlLineCount: jsonl 에 추가한 후의 총 라인 수 (이벤트 카운터 대리)
+ * - toolName: Edit/Write/Bash 인 경우 mtime 조건 충족 시 강제 재작성
+ * @param {string} toolName
+ * @param {number} jsonlLineCount
+ * @returns {boolean}
+ */
+function shouldRewriteJson(toolName, jsonlLineCount) {
+  // N이벤트마다 강제 재작성 (race-tolerant — jsonl 줄 수가 카운터 역할)
+  if (jsonlLineCount % REWRITE_EVERY_N === 0) return true;
+
+  // 마지막 재작성 후 ≥2초 경과 여부 (mtime 기반)
+  try {
+    const stat = fs.statSync(CURRENT_RUN_JSON);
+    const elapsed = Date.now() - stat.mtimeMs;
+    if (elapsed >= REWRITE_INTERVAL_MS) return true;
+  } catch {
+    // 파일 없음 → 첫 쓰기, 허용
+    return true;
+  }
+
+  return false;
+}
+
+// ─────────────────────────────────────────────────────
+// 책임 1: current-run.json 카운터 (스로틀 적용)
+//
+// steps 는 current-run.jsonl 의 라인 수에서 파생한다.
+// 이렇게 하면 스로틀로 재작성을 건너뛰어도 재작성 시점에
+// 정확한 steps 가 보장되며, 프로세스간 누적도 자연스럽게 처리된다.
 // ─────────────────────────────────────────────────────
-function bumpCounter() {
+function bumpCounter(toolName, currentLineCount) {
+  if (!shouldRewriteJson(toolName, currentLineCount)) return; // 스로틀 — 재작성 생략
+
   let data = { feature: null, startedAt: null, steps: 0 };
   if (fs.existsSync(CURRENT_RUN_JSON)) {
     try {
@@ -107,12 +161,24 @@ function bumpCounter() {
     } catch { /* 손상 → 새로 시작 */ }
   }
   if (!data.startedAt) data.startedAt = new Date().toISOString();
-  data.steps = (data.steps || 0) + 1;
-  fs.writeFileSync(CURRENT_RUN_JSON, JSON.stringify(data, null, 2));
+  // steps = jsonl 라인 수에서 파생 (매 재작성 시 최신값 보장)
+  data.steps = currentLineCount;
+
+  // 원자적 쓰기 (tmp → rename) — 동시 에이전트 파일 손상 방지
+  const tmp = CURRENT_RUN_JSON + '.tmp';
+  try {
+    fs.writeFileSync(tmp, JSON.stringify(data, null, 2));
+    fs.renameSync(tmp, CURRENT_RUN_JSON);
+  } catch {
+    // rename 실패 시 직접 쓰기 (fail-open)
+    try { fs.writeFileSync(CURRENT_RUN_JSON, JSON.stringify(data, null, 2)); } catch { /* ignore */ }
+    try { fs.unlinkSync(tmp); } catch { /* ignore */ }
+  }
 }
 
 // ─────────────────────────────────────────────────────
 // 책임 2: current-run.jsonl append + error_category 채움
+// 항상 즉시 append — 스로틀 없음 (3-fail detector, recipe-extractor 가 소비)
 // ─────────────────────────────────────────────────────
 function appendJsonl(stdinPayload) {
   const toolName = stdinPayload?.tool_name || process.argv[2] || '';
@@ -147,6 +213,21 @@ function appendJsonl(stdinPayload) {
   return record;
 }
 
+/**
+ * jsonl 의 현재 라인 수를 반환 (stat 으로만 — 전체 파일 읽기 없음).
+ * 경합 안전 — 정확한 값이 아니어도 스로틀 판단에 충분하다.
+ */
+function jsonlLineCount() {
+  try {
+    // 라인 수 근사: 파일 크기 / 평균 라인 길이(100바이트) — 정확도 불필요
+    // 실제 라인 수는 appendJsonl 직후 여기서 읽으면 +1 반영됨
+    const content = fs.readFileSync(CURRENT_RUN_JSONL, 'utf-8');
+    return content.split('\n').filter(Boolean).length;
+  } catch {
+    return 1; // 파일 없음 → 첫 이벤트로 간주
+  }
+}
+
 // ─────────────────────────────────────────────────────
 // 책임 3b: 3-fail detector → anti-pattern md
 // ─────────────────────────────────────────────────────
@@ -238,10 +319,22 @@ try {
   }
 
   const stdinPayload = readStdinSync();
+  const toolName = stdinPayload?.tool_name || process.argv[2] || '';
 
-  try { bumpCounter(); } catch { /* 카운터 실패 무시 */ }
+  // defense-in-depth: 읽기 전용 툴은 조기 종료 (matcher 단에서 이미 제거됨)
+  if (toolName && READ_ONLY_TOOLS.has(toolName)) {
+    process.exit(0);
+  }
+
+  // 책임 2를 먼저 실행 — jsonl 라인 수가 bumpCounter 스로틀 판단에 쓰임
   let lastRecord = null;
   try { lastRecord = appendJsonl(stdinPayload); } catch { /* 로깅 실패 무시 */ }
+
+  // 책임 1: jsonl append 후 라인 수로 스로틀 판단
+  const lineCount = jsonlLineCount();
+  try { bumpCounter(toolName, lineCount); } catch { /* 카운터 실패 무시 */ }
+
+  // 책임 3
   try {
     if (lastRecord && !lastRecord.ok && lastRecord.error_category) {
       const trip = detectThreeFail();

package/hooks/scripts/stop-dispatcher.js

@@ -7,6 +7,7 @@
  * 현재: 단일 디스패처에서 순차 실행.
  *
  * 실행 순서:
+ *   0. verify-skip 경고/차단 (in-process)
  *   1. codex-review-gate — 리뷰 필요 여부 판단 (stdout → Claude 지시 주입)
  *   2. stop-notify       — 완료 알림
  *   3. auto-commit       — 변경 자동 커밋 (git hook cascade 주의)
@@ -16,9 +17,34 @@
  * 이 Stop dispatcher도 건너뛴다 (자식 세션에서 auto-commit 등이 돌 이유 없음).
  */
 import { dispatch } from './lib/dispatcher.js';
+import { readLedger, markStopWarned } from './lib/run-ledger.js';
+import { PROJECT_DIR, readProjectConfig } from './utils.js';
 
 if (process.env.VIBE_HOOK_DEPTH) process.exit(0);
 
+// verify-skip 게이트 — runStarted가 있고 verifyPassed가 false이면 경고 또는 차단.
+// stopWarned가 이미 true이면 루프 방지를 위해 스킵.
+try {
+  const ledger = readLedger(PROJECT_DIR);
+  if (ledger && ledger.runStarted && !ledger.verifyPassed && !ledger.stopWarned) {
+    const config = readProjectConfig();
+    const gateMode = config?.verifyGate?.mode;
+
+    if (gateMode === 'block') {
+      // 1회에 한해 Stop 차단 — 루프 방지 플래그 먼저 세팅
+      markStopWarned(PROJECT_DIR);
+      const reason = '/vibe.verify not run after /vibe.run — stop blocked (verifyGate.mode=block)';
+      process.stdout.write(JSON.stringify({ decision: 'block', reason }) + '\n');
+      process.exit(0);
+    } else {
+      // 기본: warn 모드 — stderr에 경고, 루프 방지 플래그 세팅
+      markStopWarned(PROJECT_DIR);
+      const feature = ledger.runFeature ? ` (feature: ${ledger.runFeature})` : '';
+      process.stderr.write(`[vibe] WARNING: /vibe.run${feature} completed but /vibe.verify was not run.\n`);
+    }
+  }
+} catch { /* verify-skip 게이트 실패는 이후 실행을 막지 않음 */ }
+
 try {
   await dispatch([
     { name: 'codex-review-gate', script: 'codex-review-gate.js' },

package/hooks/scripts/utils.js

@@ -163,29 +163,71 @@ function toFileUrl(fsPath) {
   return url.endsWith('/') ? url : url + '/';
 }
 
-// 전역 npm 경로 캐시
+// 전역 npm 경로 캐시 — L1: 인-프로세스, L2: 파일 캐시 (TTL 24h)
+// VIBE_NPM_ROOT_CACHE_FILE 환경 변수로 테스트 시 격리된 경로 주입 가능
+const NPM_ROOT_CACHE_FILE = process.env.VIBE_NPM_ROOT_CACHE_FILE ||
+  path.join(os.homedir(), '.vibe', 'cache', 'npm-root.json');
+const NPM_ROOT_CACHE_TTL_MS = 24 * 60 * 60 * 1000; // 24시간
+
+/** npm root -g 결과를 파일로 캐시 (원자적 쓰기). 실패는 조용히 무시. */
+function saveNpmRootCache(npmRoot) {
+  try {
+    const dir = path.dirname(NPM_ROOT_CACHE_FILE);
+    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+    const payload = JSON.stringify({ npmRoot, savedAt: Date.now() });
+    const tmp = NPM_ROOT_CACHE_FILE + '.tmp';
+    fs.writeFileSync(tmp, payload, { mode: 0o600 });
+    fs.renameSync(tmp, NPM_ROOT_CACHE_FILE);
+  } catch { /* 캐시 저장 실패는 무시 */ }
+}
+
+/** 파일 캐시에서 npm root 읽기. TTL 초과 또는 손상 시 null 반환. */
+function loadNpmRootCache() {
+  try {
+    const raw = fs.readFileSync(NPM_ROOT_CACHE_FILE, 'utf-8');
+    const { npmRoot, savedAt } = JSON.parse(raw);
+    if (typeof npmRoot === 'string' && typeof savedAt === 'number') {
+      if (Date.now() - savedAt < NPM_ROOT_CACHE_TTL_MS) return npmRoot;
+    }
+  } catch { /* 파일 없음 / 손상 / 권한 → null */ }
+  return null;
+}
+
+/** npm root -g 플랫폼 폴백 (execSync 실패 시 사용). */
+function npmRootFallback() {
+  if (IS_WINDOWS) {
+    const appData = process.env.APPDATA || process.env.LOCALAPPDATA || '';
+    return path.join(appData, 'npm', 'node_modules');
+  }
+  const homeDir = os.homedir();
+  const candidates = [
+    '/usr/local/lib/node_modules',
+    path.join(homeDir, '.npm-global', 'lib', 'node_modules'),
+    path.join(homeDir, '.nvm', 'versions', 'node', process.version, 'lib', 'node_modules'),
+  ];
+  return candidates.find(p => fs.existsSync(p)) || candidates[0];
+}
+
+// L1 인-프로세스 캐시
 let _globalNpmPath = null;
 export function getGlobalNpmPath() {
-  if (_globalNpmPath === null) {
-    try {
-      _globalNpmPath = execSync('npm root -g', { encoding: 'utf8' }).trim();
-    } catch {
-      // 폴백: 플랫폼별 기본 경로
-      if (IS_WINDOWS) {
-        // Windows: %APPDATA%\npm\node_modules 또는 %LOCALAPPDATA%\npm\node_modules
-        const appData = process.env.APPDATA || process.env.LOCALAPPDATA || '';
-        _globalNpmPath = path.join(appData, 'npm', 'node_modules');
-      } else {
-        // macOS/Linux: /usr/local/lib/node_modules 또는 ~/.npm-global/lib/node_modules
-        const homeDir = os.homedir();
-        const defaultPaths = [
-          '/usr/local/lib/node_modules',
-          path.join(homeDir, '.npm-global', 'lib', 'node_modules'),
-          path.join(homeDir, '.nvm', 'versions', 'node', process.version, 'lib', 'node_modules'),
-        ];
-        _globalNpmPath = defaultPaths.find(p => fs.existsSync(p)) || defaultPaths[0];
-      }
-    }
+  // L1: 인-프로세스 캐시 히트
+  if (_globalNpmPath !== null) return _globalNpmPath;
+
+  // L2: 파일 캐시 히트
+  const cached = loadNpmRootCache();
+  if (cached !== null) {
+    _globalNpmPath = cached;
+    return _globalNpmPath;
+  }
+
+  // L3: execSync 실행 후 파일 캐시에 저장
+  try {
+    _globalNpmPath = execSync('npm root -g', { encoding: 'utf8' }).trim();
+    saveNpmRootCache(_globalNpmPath);
+  } catch {
+    _globalNpmPath = npmRootFallback();
+    // 폴백은 캐시에 저장하지 않음 — 다음 프로세스에서 재시도
   }
   return _globalNpmPath;
 }

package/hooks/scripts/verify-ledger.js

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+/**
+ * verify-ledger CLI — vibe.verify 결과를 run-ledger에 기록.
+ *
+ * 사용법: node hooks/scripts/verify-ledger.js pass|fail
+ *
+ * vibe.verify/SKILL.md 에서 검증 완료 시 호출.
+ * stdout 출력은 에이전트가 Bash로 실행하는 컨텍스트이므로 허용.
+ * 항상 exit 0.
+ */
+
+import { recordVerify } from './lib/run-ledger.js';
+
+const arg = process.argv[2];
+const passed = arg === 'pass';
+const projectDir = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+
+recordVerify(projectDir, passed);
+
+const status = passed ? 'pass' : 'fail';
+process.stdout.write(`[verify-ledger] recorded: verifyPassed=${passed} (${status})\n`);
+process.exit(0);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@su-record/vibe",
-  "version": "2.12.5",
-  "description": "AI Coding Framework for Claude Code — 56 agents, 45 skills, multi-LLM orchestration",
+  "version": "2.14.0",
+  "description": "AI Coding Framework for Claude Code — 60+ agents, 69 skills, multi-LLM orchestration",
   "type": "module",
   "main": "dist/cli/index.js",
   "exports": {

package/skills/spec/references/templates.md

@@ -86,19 +86,24 @@ Define AI role and expertise for implementation
 
 ## Task
 <task>
+<!-- ⚠️ MANDATORY: Every functional requirement item MUST carry a REQ-ID so the RTM can extract it.
+     Format: REQ-{feature-name}-NNN  (feature = SPEC file basename, NNN = 3-digit zero-padded number)
+     Example: REQ-auth-login-001
+     Regex the RTM uses: /\b(REQ-[a-z0-9-]+-\d{3})[:\s]/gi  — use uppercase REQ-, lowercase feature segment, exactly 3 digits.
+     status === 'empty' means the RTM gate MUST be treated as failed/not-applicable, never as 100% pass. -->
 ### Phase 1: {phase-name}
-1. [ ] {specific task}
+1. [ ] REQ-{feature-name}-001: {specific task}
    - File: `path/to/file`
    - Verify: `command`
-2. [ ] {specific task}
+2. [ ] REQ-{feature-name}-002: {specific task}
 
 ### Phase 2: {phase-name}
-1. [ ] {specific task}
-2. [ ] {specific task}
+1. [ ] REQ-{feature-name}-003: {specific task}
+2. [ ] REQ-{feature-name}-004: {specific task}
 
 ### Phase 3: Testing and Verification
-1. [ ] Unit Tests
-2. [ ] Integration Tests
+1. [ ] REQ-{feature-name}-005: Unit Tests
+2. [ ] REQ-{feature-name}-006: Integration Tests
 </task>
 
 ## Constraints

package/skills/vibe/SKILL.md

@@ -7,7 +7,9 @@ user-invocable: true
 
 # /vibe
 
-**vibe의 메인 진입점.** 사용자는 "무엇을 만들지 / 무엇을 할지"만 자연어로 말한다. vibe가 의도를 분석해 어떤 `/vibe.*` 스킬을 어떤 순서로 호출할지 파이프라인을 동적으로 설계하고, **1회 승인 후 실행**한다.
+**vibe의 메인 진입점.** 사용자는 "무엇을 만들지 / 무엇을 할지"만 자연어로 말한다. vibe가 의도를 분석해 어떤 `/vibe.*` 스킬을 어떤 순서로 호출할지 파이프라인을 동적으로 설계하고, **SPEC 확정 1회 승인 후 게이트 통과까지 루프 실행**한다.
+
+> **루프 시맨틱 SSOT**: `vibe/rules/loop-contract.md` — 이 문서가 ANCHOR→ACT→JUDGE→RECORD 계약과 모든 파라미터(exit, stuck, max_iterations, automationLevel)를 정의한다.
 
 ## Usage
 
@@ -17,7 +19,8 @@ user-invocable: true
 /vibe "로그인 회귀 테스트 다시 돌려서 통과시켜줘"
 /vibe "이 SPEC 리뷰만 한번 봐줘" + 📎 .vibe/specs/login.md
 /vibe "PRD 문서 기반으로 진행" + 📎 docs/prd.pdf
-/vibe "..." ultrawork    # 승인 게이트 없이 자동 전 흐름 실행
+/vibe "..." --interactive     # 단계별 확인 모드 (회전마다 승인)
+/vibe "..." --max-iter 1      # 1회 시도만
 ```
 
 ## Philosophy
@@ -29,7 +32,7 @@ user-invocable: true
 - **무제한 라우팅**: 라우팅 표는 빠른 경로일 뿐 닫힌 화이트리스트가 아니다. 설치된 모든 `vibe.*` 스킬이 라우팅 후보이며, 표에 없는 요구사항도 description 기반 의미 매칭으로 처리한다 (Catch-all).
 - **하네스 정규화 (추론 앞단)**: vibe는 CC(추론)·Codex(직역) 어느 하네스의 암묵적 동작에도 의존하지 않는다. `/vibe`가 모호한 NL을 **명시적·직역 가능한 지시로 먼저 전개**하고, 하위 skill은 모호한 입력을 받지 않는다. 이로써 모든 하네스에서 동일 결과 + CC급 편의를 제공한다. 전문: `vibe/rules/principles/dual-harness-doctrine.md`.
 - **Smart Resume**: `.vibe/{interviews,plans,specs,features}/` 감지하여 "이어서 진행?" 자동 제안.
-- **1회 승인 게이트**: 파이프라인을 설계해서 사용자에게 보여주고 OK 받은 뒤 실행. `ultrawork` 키워드 있으면 skip.
+- **SPEC 확정 1회 승인 → 루프**: SPEC(Done의 정의 + 수용 기준)을 사용자와 확정하는 것이 유일한 의무적 사람 개입. 승인 후에는 `vibe/rules/loop-contract.md`의 ANCHOR→ACT→JUDGE→RECORD 루프를 게이트 전부 통과할 때까지 자동 반복한다. 루프 종료 = 게이트 통과 또는 stuck 또는 max_iterations 도달.
 - **위임자 역할**: `/vibe` 본인은 코드를 직접 쓰지 않는다. 라우팅·설계·실행 위임만 한다.
 
 ## Process
@@ -45,7 +48,7 @@ user-invocable: true
 | 자연어 텍스트 | 의도 추출 (요구 종류, 도메인, 키워드) |
 | 첨부 파일 (`📎 path`) | 확장자로 분류 (md/feature/pdf/png/jpg/...) |
 | URL | 도메인으로 분류 (figma.com / github.com / 기타) |
-| 키워드 | `ultrawork`, `ralph`, `quick`, `verify` 등 magic keyword 추출 |
+| 옵션 플래그 | `--interactive`, `--max-iter N` 등 루프 파라미터 추출; `ultrawork`/`ralph`/`quick` 등 deprecated 별칭은 loop-contract 매핑표로 변환 |
 
 ### Phase 1: Intent 분류
 
@@ -113,7 +116,7 @@ user-invocable: true
 - **research 명시**: 조사가 필요하면 파이프라인에 명시적 탐색 단계를 넣는다. planning mode 같은 하네스 스위치에 의존하지 않는다.
 - **도메인 지식 흡수**: 사용자가 준 라이브러리·함수·파일 위치를 SPEC 입력으로 전달한다.
 
-이어서 분류된 의도 + resume 상태 + magic keyword 를 종합해 실행 계획 작성:
+이어서 분류된 의도 + resume 상태 + 루프 파라미터(automationLevel, --max-iter 등)를 종합해 실행 계획 작성:
 
 ```
 📋 Pipeline Plan
@@ -143,9 +146,10 @@ Phase 6: /vibe.trace → RTM 출력
 ```
 
 **Skip 조건:**
-- 입력에 `ultrawork` 또는 `ulw` 키워드 → 자동 진행
-- `ralph` 키워드 → 자동 진행 + 100% 수렴까지 반복
-- `quick` 키워드 → 최소 phase 만 자동 진행 (review/verify/contract/trace skip)
+- `automationLevel: autonomous` 설정 (`.vibe/config.json`) 또는 `ultrawork`/`ulw` 별칭 → SPEC 승인 게이트만 skip, 루프는 정상 동작
+- `--max-iter 1` 또는 `quick` 별칭 → 1회 시도 후 종료
+
+> 참고: Phase 4의 승인 게이트는 **파이프라인 설계 승인**이다. SPEC 확정 시점의 승인(loop-contract의 "유일한 의무 개입")과 구별된다.
 
 ### Phase 5: 체인 실행
 
@@ -161,10 +165,11 @@ Phase 6: /vibe.trace → RTM 출력
 ...
 ```
 
-각 phase 종료 시:
-- 성공 → 다음 phase
-- 실패 → 중단하고 사용자에게 보고 (재시도 / skip / abort 선택)
-- `ultrawork` 모드 → 실패도 TODO로 기록하고 계속 진행 (non-interactive)
+각 phase 종료 후 JUDGE 단계:
+- 게이트 통과 (P1=0 ∧ verifyPassed) → 루프 종료, Phase 6 보고
+- 게이트 미통과 → RECORD(run-ledger + loop-history.jsonl) 후 다음 ANCHOR로
+- stuck(연속 2회 동일 findings 해시) → `automationLevel: confirm`이면 사용자 질문; `autonomous`이면 TODO 기록 후 루프 종료
+- max_iterations(기본 10) 도달 → 잔여를 인박스로 이월
 
 ### Phase 6: 종료 보고
 
@@ -228,31 +233,43 @@ Phase 6: /vibe.trace → RTM 출력
    1. /vibe.review (단일 phase)
 ```
 
-### 예시 4: ultrawork
+### 예시 4: automationLevel autonomous (ultrawork 별칭)
 
 ```
 입력: /vibe "결제 API 만들어줘" ultrawork
 
-→ Approval gate SKIP
-→ 자동 전 phase 실행
-→ 실패는 TODO 기록만 하고 계속
+→ automationLevel: autonomous 설정 → SPEC 승인 게이트 skip
+→ 병렬 ACT 활성화
+→ ANCHOR→ACT→JUDGE→RECORD 루프 (게이트 통과까지 자동 반복)
+→ stuck 시 TODO 기록 후 루프 종료 (사용자 질문 없음)
 ```
 
 ## ⛔ 하지 않는 것
 
 - 직접 코드 작성 / 파일 수정 (위임만)
-- 파이프라인 미리보기 없이 즉시 실행 (`ultrawork` 외)
+- SPEC 확정 없이 루프 진입 (SPEC = Done의 정의, 유일한 의무 승인 지점)
 - 사용자가 명시한 phase 를 임의로 추가/제거
 - Resume 상태를 무시하고 처음부터 다시 시작
 
-## Magic Keywords (재정의)
+## 루프 옵션
+
+| 옵션 | 효과 |
+|---|---|
+| `--interactive` | 매 회전마다 사람 승인 (과거 기본값) |
+| `--max-iter N` | 회전 상한 N 으로 설정 (N=1이면 1회 시도) |
+| `automationLevel: autonomous` (`.vibe/config.json`) | stuck/SPEC 게이트 외 모든 확인 skip |
+
+## Deprecated 별칭 (하위 호환 — 새 코드에서 사용하지 말 것)
+
+> 아래 키워드는 계속 동작하지만 loop-contract 파라미터로 환원된다. 새 문서나 예시에서 가르치지 않는다. 전문: `vibe/rules/loop-contract.md` Deprecated 별칭 매핑표.
 
-| Keyword | Effect |
+| 별칭 | 환원 |
 |---|---|
-| `ultrawork` / `ulw` | 승인 게이트 skip + non-interactive |
-| `ralph` | 100% 수렴까지 자동 반복 |
-| `quick` | 최소 phase 만 (review/verify/contract/trace skip) |
-| `verify` | 강한 검증 (verify + contract + trace 강제 포함) |
+| `ultrawork` / `ulw` | `automationLevel: autonomous` + 병렬 ACT |
+| `ralph` | 기본 동작과 동일 (no-op); exit=coverage-100으로 해석 가능 |
+| `quick` | `--max-iter 1` + 최소 JUDGE |
+| `verify` | 기본 동작과 동일 (no-op) — JUDGE는 항상 결정론 검증 |
+| `ralplan` | 동일 loop-contract를 계획 단계에 적용 |
 
 ## Output