@su-record/vibe 2.13.0 → 2.14.0

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,6 +1,6 @@
 {
   "name": "@su-record/vibe",
-  "version": "2.13.0",
+  "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",

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
 

package/skills/vibe.loop/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: vibe.loop
+description: Loop engineering — design, install, and run autonomous goal loops whose completion is judged by deterministic gates, not self-report
+argument-hint: "design | install | run | status | list [loop-name]"
+user-invocable: true
+---
+
+# /vibe.loop
+
+**Loop Engineering** — 사람이 프롬프트하는 대신, 에이전트에게 프롬프트하는 루프를 설계한다.
+
+> 루프의 완료 판정은 모델의 자기 보고가 아니라 **결정론적 게이트**(run-ledger `verifyPassed`, 테스트 exit code)가 내린다.
+> 루프는 push·release·배포를 절대 수행하지 않는다 — 결과는 항상 사람 리뷰 큐(인박스)로 간다.
+
+## Usage
+
+```
+/vibe.loop design [name]        # 인터뷰 → .vibe/loops/<name>.md 정의 생성
+/vibe.loop install <name>       # 실행 환경(CC/Codex/cron)에 스케줄 연결
+/vibe.loop run <name>           # 1회 반복 실행 (스케줄러가 호출하는 진입점)
+/vibe.loop status [name]        # 실행 이력 + 인박스 요약
+/vibe.loop list                 # 정의된 루프 목록과 상태
+```
+
+## 경로 상수 (모든 서브커맨드 공통)
+
+```bash
+HOOKS_DIR="${VIBE_PATH:-$(npm root -g 2>/dev/null)/@su-record/vibe}/hooks/scripts"
+LOOPS_DIR=".vibe/loops"
+INBOX="$LOOPS_DIR/inbox.md"
+HISTORY=".vibe/metrics/loop-history.jsonl"
+```
+
+---
+
+## design — 루프 정의 생성
+
+1. 다음 5가지를 사용자에게 묻는다 (이미 인자로 답이 있으면 생략):
+   - **목표(goal)**: 루프가 0으로 만들려는 것 (예: "open 회귀 0건", "P1 lint 0건")
+   - **트리거**: `scheduled`(cron) / `manual` / `on-event`
+   - **발견(discover)**: 일거리를 어떻게 찾는가 — 명령 또는 지시
+   - **검증(verify)**: `ledger`(vibe.verify 경유, 기본) / `tests`(테스트 명령 exit code) / `none`(보고만)
+   - **격리(isolation)**: 병렬 항목이 파일을 수정하면 `worktree`, 아니면 `none`
+2. `{{VIBE_PATH}}/vibe/templates/loop-template.md`를 읽어 `.vibe/loops/<name>.md`를 생성한다.
+3. **생성 직후 반드시 검증한다** — 실패 시 정의를 고치고 재검증, 통과 전에는 install/run 금지:
+
+```bash
+node -e "import('{{VIBE_PATH_URL}}/node_modules/@su-record/vibe/dist/tools/index.js').then(t => { const fs = require('fs'); const r = t.validateLoopDefinition(fs.readFileSync('.vibe/loops/<name>.md', 'utf-8')); console.log(JSON.stringify(r.errors.length ? r.errors : 'valid')); })"
+```
+
+**기본 제안 레시피 — nightly-triage** (사용자가 목표를 정하지 못하면 이것을 제안):
+- discover: ① `.vibe/regressions/`에서 `status: open` 항목 ② `npx vitest run` 실패 ③ `.vibe/contracts/` drift 의심 항목 → 우선순위 목록(P1 먼저)
+- pipeline: `[vibe.run, vibe.verify]` — 항목별로 SPEC 범위 내 수정 → 검증
+- verify: `ledger` / trigger: `scheduled` / schedule: `0 6 * * *` / isolation: `worktree`
+
+## install — 스케줄 연결
+
+루프 정의는 하네스 중립이다. 현재 환경을 감지해 정확한 설치 명령을 **사용자에게 제시**한다 (직접 등록하지 않는다 — 스케줄 등록은 사용자 결정):
+
+| 환경 | 명령 |
+|------|------|
+| Claude Code (세션 루프) | `/loop <interval> "/vibe.loop run <name>"` |
+| Claude Code (클라우드 루틴) | `/schedule` 로 cron `<schedule>` + 프롬프트 `/vibe.loop run <name>` 등록 |
+| OS cron 폴백 | `<schedule> cd <project> && claude -p "/vibe.loop run <name>" --permission-mode acceptEdits` |
+| Codex | Automations 탭에 `<schedule>` + `$vibe.loop run <name>` 등록 |
+
+`trigger: manual` 루프는 install 불필요 — run만 안내한다.
+
+## run — 1회 반복 실행 (핵심)
+
+`status: paused` 루프는 즉시 종료. 실행 순서는 **전부 의무**이며 생략 불가:
+
+```
+1. 검증     validateLoopDefinition 통과 확인 (위 design 3의 명령) — 실패 시 인박스에 기록 후 종료
+2. 시작 기록  node "$HOOKS_DIR/loop-ledger.js" start <name>
+3. DISCOVER  정의의 discover 지시 실행 → 일거리 목록 산출
+4. STUCK 검사 DISCOVER_HASH=$(node -e "...hashDiscoverOutput...")   # 발견 목록 텍스트의 해시
+             node "$HOOKS_DIR/loop-ledger.js" check-stuck <name> "$DISCOVER_HASH"
+             → 'stuck'이면: end <name> stuck 기록 + 인박스에 "동일 발견 2회 연속 — 사람 개입 필요" 후 종료.
+               stuck 판단은 이 명령의 출력만 따른다. 모델이 "다시 해보면 될 것 같다"고 무시하는 것 금지.
+5. ACT       발견 항목을 우선순위순으로, max_iterations 한도 내에서 pipeline 체인 실행.
+             isolation: worktree면 항목별 worktree에서 (git-worktree 스킬 패턴).
+             scope-guard·verifyGate 등 기존 게이트는 그대로 적용된다 — 루프라고 우회하지 않는다.
+6. VERIFY    완료 판정 — verify 모드별 결정론 기준:
+             · ledger: cat .vibe/metrics/run-ledger.json → verifyPassed === true 만 성공
+             · tests:  정의의 test_command 실행 → exit 0 만 성공
+             · none:   판정 생략(보고만). "코드를 보니 잘 된 것 같다"는 판정이 아니다.
+7. 종료 기록  node "$HOOKS_DIR/loop-ledger.js" end <name> <ok|fail|stuck> "<한 줄 요약>"
+8. 인박스    $INBOX 상단에 결과 블록 prepend:
+             ## <name> — <ISO 시각> — <ok|fail|stuck>
+             - 발견: N건 / 처리: M건 / 검증: <기준과 결과>
+             - 리뷰 필요: <항목들 — 없으면 "없음">
+```
+
+**금지**: `git push`, `gh pr merge`, `npm publish`, 버전 범프, 릴리즈 — 루프는 커밋까지만 가며(auto-commit verify 게이트 통과 시), 그 이상은 인박스를 본 사람이 한다.
+
+## status / list
+
+- `list`: `$LOOPS_DIR/*.md`의 frontmatter(name, trigger, status, goal) 테이블.
+- `status [name]`: `$HISTORY`에서 해당 루프(생략 시 전체)의 최근 10개 이벤트 + 인박스의 미처리 블록 수.
+
+## Auto-integration
+
+- `/vibe.regress`의 open 항목, `/vibe.contract`의 drift는 nightly-triage discover의 1차 입력이다.
+- 루프 안에서 verify 실패 시 기존 규칙대로 회귀 자동 등록(vibe.verify 경유)이 그대로 동작한다.
+
+## 설계 원칙 (요약)
+
+| 원칙 | 구현 |
+|------|------|
+| 완료는 게이트가 판정 | run-ledger `verifyPassed` / 테스트 exit code (REQ-005) |
+| stuck은 해시가 판정 | loop-ledger check-stuck, 동일 발견 2회 연속 (REQ-009) |
+| 이해 부채 가드 | 인박스 리뷰 큐 + push/release 금지 (REQ-008) |
+| 기록 없는 실행 없음 | loop-history.jsonl start/end 의무 (REQ-006) |
+
+SPEC: `.vibe/specs/loop-engineering.md`

package/skills/vibe.run/SKILL.md

@@ -14,10 +14,12 @@ Execute **Scenario-Driven Implementation** with automatic quality verification.
 ## Usage
 
 ```
-/vibe.run "feature-name"              # Full implementation
+/vibe.run "feature-name"              # Full implementation (loops to convergence)
 /vibe.run "feature-name" --phase 1    # Specific Phase only
-/vibe.run "feature-name" ultrawork    # ULTRAWORK mode (recommended)
-/vibe.run "feature-name" ulw          # Short alias for ultrawork
+/vibe.run "feature-name" --interactive  # Step-by-step confirmation per iteration
+/vibe.run "feature-name" --max-iter 1   # Single-pass (no loop)
+/vibe.run "feature-name" ultrawork    # deprecated alias: automationLevel autonomous + parallel
+/vibe.run "feature-name" ulw          # deprecated alias: same as ultrawork
 ```
 
 ---
@@ -47,7 +49,7 @@ Execute **Scenario-Driven Implementation** with automatic quality verification.
 Load skill `regress` with: list --feature "{feature-name}"
 ```
 
-- Open regressions exist → interactive: ask user; ultrawork: auto-invoke `/vibe.regress generate <slug>`
+- Open regressions exist → automationLevel confirm: ask user; autonomous: auto-invoke `/vibe.regress generate <slug>`
 - No open regressions → silently continue
 
 Also load `.vibe/contracts/{feature-name}.md` if present — use it as the contract reference during implementation.
@@ -60,8 +62,8 @@ test -f DESIGN.md
 
 - **DESIGN.md present OR no UI stack** → silently continue
 - **DESIGN.md absent AND UI stack present**:
-  - interactive: 한 줄 안내 — "UI 작업에 `DESIGN.md` 시각 SSOT 가 없습니다. `/vibe.design init` 으로 생성하면 시각 드리프트가 자동 검출됩니다. (생략 가능 — 1 회만 안내)"
-  - ultrawork: 무음 스킵
+  - automationLevel confirm: 한 줄 안내 — "UI 작업에 `DESIGN.md` 시각 SSOT 가 없습니다. `/vibe.design init` 으로 생성하면 시각 드리프트가 자동 검출됩니다. (생략 가능 — 1 회만 안내)"
+  - automationLevel autonomous: 무음 스킵
 
 > **권유 > 강제**. DESIGN.md 부재는 절대 vibe.run 을 블록하지 않는다.
 
@@ -89,7 +91,7 @@ test -f DESIGN.md
 └─────────────────────────────────────────────────────────────────┘
 ```
 
-> **하네스-안전 증분 (Dual-Harness Doctrine)**: 시나리오는 **가장 작은 검증 단위**다. 한 시나리오 구현 → 즉시 검증 → 다음. `ultrawork` 모드라도 이 단위는 무너뜨리지 않는다 (병렬은 시나리오 간, 검증은 시나리오별). 전문: `vibe/rules/principles/dual-harness-doctrine.md`.
+> **하네스-안전 증분 (Dual-Harness Doctrine)**: 시나리오는 **가장 작은 검증 단위**다. 한 시나리오 구현 → 즉시 검증 → 다음. `automationLevel: autonomous`이라도 이 단위는 무너뜨리지 않는다 (병렬은 시나리오 간, 검증은 시나리오별). 전문: `vibe/rules/principles/dual-harness-doctrine.md`.
 
 ### Automated Verification (Closed Loop)
 
@@ -129,20 +131,22 @@ Scenario verification failed
       Repeat until pass (stuck 감지로 종료)
 ```
 
-**Termination conditions:**
+**Termination conditions (loop-contract JUDGE):**
 - PASS → 다음 scenario
-- Stuck (같은 failure가 이전 라운드와 동일) → ask user or ultrawork: TODO + next scenario
+- stuck (같은 failure가 이전 라운드와 동일, `loop-ledger.js check-stuck`) → automationLevel confirm: 사용자 질문; autonomous: TODO + next scenario
 
 ---
 
-## **ULTRAWORK Mode** (ulw)
+## **ULTRAWORK Mode** (ulw) — deprecated alias
 
-> Read `references/ultrawork-mode.md` for the full Boulder Loop diagram, automation level definitions, and confirmation matrix.
+> 루프 시맨틱은 `vibe/rules/loop-contract.md`를 따른다. `ultrawork`/`ulw`는 `automationLevel: autonomous` + 병렬 ACT의 deprecated 별칭이다.
+> 전체 Boulder Loop 다이어그램, automation level 정의, confirmation matrix: `references/ultrawork-mode.md`
 
-When `ultrawork` or `ulw` is included:
-- Parallel Exploration + Boulder Loop + No Pause + Error Recovery (auto-TODO on stuck)
-- Race Review (GPT+Antigravity) enabled by default
-- Ralph Loop runs after all phases
+`ultrawork` 또는 `ulw` 포함 시 vibe.run-specific 동작:
+- 병렬 탐색 (3+ Task agents 동시)
+- 비대화형 (중단점 없음)
+- Race Review (GPT+Antigravity) 기본 활성화
+- stuck 시 TODO 기록 후 다음 시나리오로 (사용자 질문 없음)
 
 ---
 
@@ -316,9 +320,9 @@ After all scenarios: GPT + Antigravity review in parallel. ULTRAWORK enables thi
 
 Auto-update scenario status with `Last verified` timestamp and quality score.
 
-### 8. Ralph Loop (Coverage Verification)
+### 8. Coverage Verification Loop (RTM)
 
-> Read `references/ralph-loop.md` for the full RTM loop diagram, output format, and iteration rules.
+> 루프 시맨틱은 `vibe/rules/loop-contract.md`를 따른다. 여기서의 exit 기준은 `coveragePercent === 100`. RTM 다이어그램, 출력 형식, 반복 규칙: `references/ralph-loop.md`
 
 After ALL phases complete:
 
@@ -329,7 +333,7 @@ node -e "import('{{VIBE_PATH_URL}}/node_modules/@su-record/vibe/dist/tools/index
 
 > Default SPEC path is `.vibe/specs/<feature>.md`. `status === 'empty'` must be treated as failed/not-applicable — never as 100% pass.
 
-Loop until `coveragePercent === 100` or stuck. Stuck → interactive: ask user; ultrawork → TODO + done.
+JUDGE: `coveragePercent === 100` → 루프 종료. stuck(연속 2회 동일 커버리지) → automationLevel confirm이면 사용자 질문; autonomous이면 TODO + done.
 
 ---
 

package/skills/vibe.run/references/ralph-loop.md

@@ -1,18 +1,20 @@
-# Ralph Loop — Full Reference
+# Ralph Loop — Coverage Verification Reference
 
-> Loaded by vibe.run SKILL.md when Ralph Loop or ULTRAWORK is active (coverage verification).
+> Loaded by vibe.run SKILL.md for RTM/coverage verification. **루프 시맨틱(ANCHOR/ACT/JUDGE/RECORD/stuck/max_iterations)의 SSOT는 `vibe/rules/loop-contract.md`다.** 이 파일은 vibe.run-specific한 RTM 기반 커버리지 검증 메커니즘을 문서화한다.
+>
+> `ralph`는 loop-contract의 deprecated 별칭으로, "exit: coverage-100"이 설정된 기본 루프와 동일하다. 더 이상 별도 모드가 아니다.
 
-## Ralph Loop (Completion Verification)
+## Coverage Verification Loop
 
 > **Inspired by [ghuntley.com/ralph](https://ghuntley.com/ralph)**: "Deterministically bad in an undeterministic world" — Keep iterating until TRULY complete.
 
 **Problem**: AI often claims "complete" when implementation is partial.
 
-**Solution**: RTM-based automated coverage verification with iteration tracking.
+**Solution**: RTM-based automated coverage verification — loop-contract의 JUDGE 기준은 `coveragePercent === 100`.
 
 ```
 ┌─────────────────────────────────────────────────────────────────┐
-│                    RALPH LOOP (Mandatory)                        │
+│           COVERAGE VERIFICATION LOOP (loop-contract + RTM)      │
 │                                                                  │
 │   After ALL phases complete:                                     │
 │                                                                  │
@@ -50,15 +52,15 @@
 │                                                                  │
 │                      │                                          │
 │                      ↓                                          │
-│              Stuck? (coverage unchanged from prev iteration)    │
+│       stuck? (loop-ledger.js check-stuck: 연속 2회 동일 커버리지) │
 │                      │                                          │
-│                      ├─ Interactive: Ask user                   │
+│                      ├─ automationLevel confirm: Ask user       │
 │                      │     1. Provide resolution → retry        │
 │                      │     2. "proceed" → TODO + done           │
 │                      │     3. "abort" → stop                    │
-│                      └─ ultrawork: TODO + done                  │
+│                      └─ automationLevel autonomous: TODO + done │
 │                                                                  │
-│   NO iteration cap — loop until 100% OR stuck                   │
+│   max_iterations 기본 10 — 도달 시 잔여 인박스 이월             │
 │   ZERO TOLERANCE for silent scope reduction                     │
 └─────────────────────────────────────────────────────────────────┘
 ```
@@ -84,16 +86,15 @@ node -e "import('{{VIBE_PATH_URL}}/node_modules/@su-record/vibe/dist/tools/index
 | `coveragePercent` | Overall coverage percentage |
 | `uncoveredRequirements` | List of missing REQ-* IDs |
 
-## Ralph Loop Rules
+## Coverage Loop Rules
 
 | Rule | Description |
 |------|-------------|
 | **No Scope Reduction** | Never say "simplified" or "basic version" — implement FULL request |
-| **Iteration Tracking** | Display `[{{ITER}}]` to show progress (no max — loop until done) |
+| **Iteration Tracking** | Display `[{{ITER}}]` to show progress; max_iterations 기본 10 |
 | **RTM-Based Gap List** | Use `uncoveredRequirements` array — no manual comparison |
-| **Coverage Threshold** | Must reach 100% coverage to complete |
-| **No Iteration Cap** | Loop until 100% coverage OR stuck (convergence detected) |
-| **Stuck Handling** | If coverage % unchanged between iterations → ask user (proceed/abort/fix), or ultrawork → TODO + done |
+| **Coverage Threshold** | JUDGE: `coveragePercent === 100` → exit (loop-contract exit=coverage-100) |
+| **Stuck Handling** | `loop-ledger.js check-stuck`: 연속 2회 동일 커버리지 → confirm이면 질문; autonomous이면 TODO + done |
 | **Diminishing Returns** | Iteration 3+ → focus on core requirements (REQ-*-001~003) first; P2/P3 continue but lower priority |
 
 ## Ralph Loop Output Format
@@ -155,11 +156,11 @@ RTM saved: .vibe/rtm/login-rtm.md
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ```
 
-## When to Trigger Ralph Loop
+## When to Trigger Coverage Loop
 
-1. After all phases complete
+1. After all phases complete (기본 동작 — 별도 키워드 불필요)
 2. Before final quality report
-3. Whenever user says "ultrawork" or "ralph"
+3. `ralph` 별칭 감지 시 — 기본 동작과 동일, exit=coverage-100으로 해석
 
 ## Forbidden Responses (VIOLATIONS)