@su-record/vibe 2.13.0 → 2.14.1

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)
 

package/skills/vibe.run/references/ultrawork-mode.md

@@ -1,24 +1,26 @@
-# ULTRAWORK Mode — Full Reference
+# ULTRAWORK Mode — Automation Level Reference
 
 > Loaded by vibe.run SKILL.md when user includes `ultrawork` or `ulw` keyword.
+>
+> **루프 시맨틱(ANCHOR/ACT/JUDGE/RECORD/stuck/max_iterations)의 SSOT는 `vibe/rules/loop-contract.md`다.** `ultrawork`/`ulw`는 `automationLevel: autonomous` + 병렬 ACT의 deprecated 별칭이다. 루프 자체는 모든 실행의 기본 동작이며, ultrawork는 그 루프를 자율(비대화형)·병렬 모드로 돌리는 축을 제어한다.
 
-## What ULTRAWORK Enables
+## What `automationLevel: autonomous` Enables
 
-When you include `ultrawork` (or `ulw`), ALL of these activate automatically:
+`ultrawork` (또는 `ulw`, `.vibe/config.json`의 `automationLevel: autonomous`) 설정 시 활성화:
 
 | Feature | Description |
 |---------|-------------|
-| **Parallel Exploration** | 3+ Task(haiku) agents run simultaneously |
-| **Boulder Loop** | Auto-continues until ALL phases complete |
+| **Parallel Exploration** | 3+ Task(haiku) agents run simultaneously (ACT 병렬화) |
+| **Loop (기본 동작)** | 모든 실행의 기본 — exit=게이트 통과 또는 stuck 또는 max_iterations |
 | **Context Compression** | Aggressive auto-save at 70%+ context |
-| **No Pause** | Doesn't wait for confirmation between phases |
+| **No Pause** | stuck·SPEC 게이트 외 확인 없음 (`automationLevel: autonomous`) |
 | **External LLMs** | Auto-consults GPT/Antigravity if enabled |
-| **Error Recovery** | Loops until 100% or stuck; on stuck auto-records TODO and proceeds (no user prompt) |
-| **Race Review (v2.6.9)** | Multi-LLM review (GPT+Antigravity) with cross-validation |
+| **Error Recovery** | stuck 시 TODO 기록 후 다음으로 (사용자 질문 없음) |
+| **Race Review** | Multi-LLM review (GPT+Antigravity) with cross-validation |
 
-## Boulder Loop (Inspired by Sisyphus)
+## Boulder Loop — Parallel ACT Visualization
 
-Like Sisyphus rolling the boulder, ULTRAWORK **keeps going until done**:
+루프 자체는 loop-contract의 기본 동작이다. Boulder Loop는 `automationLevel: autonomous`에서 **병렬 ACT**가 어떻게 실행되는지를 보여주는 다이어그램이다:
 
 ```
 ┌─────────────────────────────────────────────────────────────────┐
@@ -45,23 +47,24 @@ Like Sisyphus rolling the boulder, ULTRAWORK **keeps going until done**:
 │                       ↓         ↓                                │
 │                   [Continue]  [Complete!]                        │
 │                                                                  │
-│   NO STOPPING until acceptance criteria met or error limit hit   │
+│   loop-contract EXIT: 게이트 통과 │ stuck │ max_iterations       │
 └─────────────────────────────────────────────────────────────────┘
 ```
 
-## ULTRAWORK Example Session
+## Example Session (automationLevel: autonomous)
 
 ```
 User: /vibe.run "brick-game" ultrawork
 
 Claude:
-ULTRAWORK MODE ACTIVATED
+AUTONOMOUS MODE (automationLevel: autonomous)
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 SPEC: .vibe/specs/brick-game.md
 4 Phases detected
-Boulder Loop: ENABLED (will continue until all phases complete)
-Auto-retry: ON (loop until 100% or stuck → auto-TODO)
+Loop: ENABLED (exit = 게이트 통과 | stuck | max_iterations=10)
+Parallel ACT: ON
+automationLevel: autonomous (stuck → auto-TODO, no confirmation)
 Context compression: AGGRESSIVE
 
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
@@ -101,37 +104,37 @@ Retries: 2
 Context saved: 3 checkpoints
 ```
 
-## Normal vs ULTRAWORK Comparison
+## confirm vs autonomous Comparison
 
-| Aspect | Normal | ULTRAWORK |
-|--------|--------|-----------|
-| Phase transition | May pause | Auto-continues |
-| On error | Reports and stops | Auto-retries (3x) |
+| Aspect | `automationLevel: confirm` (default) | `automationLevel: autonomous` (ultrawork) |
+|--------|--------------------------------------|-------------------------------------------|
+| Loop | ANCHOR→ACT→JUDGE→RECORD (기본 동작) | 동일 |
+| Confirmation gates | stuck·SPEC에서 질문 | stuck 포함 전부 skip → TODO |
+| On error | Reports, asks before retry | Auto-retries, auto-TODO on stuck |
 | Context 70%+ | Warning only | Auto-compress + save |
 | Exploration | Sequential possible | FORCED parallel |
-| Completion | Phase-by-phase | Until ALL done |
 
 ## Automation Level System
 
-Magic keywords in the user input automatically set the **AutomationLevel**, which controls how much the AI self-advances vs. pausing for confirmation.
+**automationLevel**은 루프가 사람 개입 없이 얼마나 자율적으로 진행하는지를 제어한다. `.vibe/config.json`에서 설정하거나, deprecated 별칭 키워드로 런타임 오버라이드 가능.
 
 ### Level Definitions
 
-| Level | Name | Keyword(s) | Auto-advance | Auto-retry | Stuck Behavior | Parallel Agents | Checkpoints |
-|-------|------|------------|--------------|------------|----------------|-----------------|-------------|
+| Level | Name | 설정 방법 | Auto-advance | Auto-retry | Stuck Behavior | Parallel Agents | Checkpoints |
+|-------|------|-----------|--------------|------------|----------------|-----------------|-------------|
 | L0 | Manual | `manual` | No | No | Ask user every step | No | All |
-| L1 | Guided | `guided`, `verify` | No | No | Ask user on stuck | No | All |
-| L2 | Semi-auto | `quick` (default) | Yes | Yes (low cap: 2) | Ask user after 2 retries | No | Key points |
-| L3 | Auto | `ultrawork`, `ulw` | Yes | Yes (no cap) | Auto-TODO + proceed | Yes | Checkpoint-only |
-| L4 | Full-auto | `ralph`, `ralplan` | Yes | Yes (no cap) | Auto-TODO + proceed | Yes | None |
+| L1 | Guided | `guided`, `verify`(deprecated) | No | No | Ask user on stuck | No | All |
+| L2 | confirm | default | Yes | Yes (low cap: 2) | Ask user after 2 retries | No | Key points |
+| L3 | autonomous | `automationLevel: autonomous` / `ultrawork`(dep) / `ulw`(dep) | Yes | Yes (no cap) | Auto-TODO + proceed | Yes | Checkpoint-only |
+| L4 | Full-auto | `ralph`(deprecated) / `ralplan`(deprecated) | Yes | Yes (no cap) | Auto-TODO + proceed | Yes | None |
 
-### Detection Rule
+### Detection Rule (deprecated aliases)
 
 ```
-/vibe.run "login"              → L2 Semi-auto (default)
-/vibe.run "login" ultrawork    → L3 Auto
-/vibe.run "login" ralph        → L4 Full-auto
-/vibe.run "login" verify       → L1 Guided
+/vibe.run "login"              → L2 confirm (default)
+/vibe.run "login" ultrawork    → L3 autonomous (deprecated alias)
+/vibe.run "login" ralph        → L4 Full-auto (deprecated alias, exit=coverage-100)
+/vibe.run "login" verify       → L1 Guided (deprecated alias)
 ```
 
 ### Confirmation Matrix

package/vibe/rules/loop-contract.md

@@ -0,0 +1,54 @@
+# Loop Contract — vibe 실행의 기본 계약 (SSOT)
+
+> `/vibe`의 기본 동작은 **단계별 1회 실행이 아니라 완성까지의 루프**다.
+> 루프가 기본이 될 수 있는 이유: 폭주 방어가 모델의 양심이 아니라 결정론적 가드(코드)이기 때문.
+> 이 문서가 루프 시맨틱의 유일한 정의다 — ralph/Boulder/Convergence 등 과거 명칭은 전부 이 계약의 파라미터로 환원된다.
+
+## 적용 범위
+
+- **적용**: 검증 가능한 목표가 있는 실행 — `vibe.run`, `vibe.verify`, `vibe.review`, `vibe.loop` 및 이들을 체인하는 `/vibe` 파이프라인
+- **제외**: 단발 조회·생성 작업 (`vibe.docs`, `vibe.analyze`, `vibe.scaffold` 등) — 루프 의례를 강제하지 않는다
+
+## 계약
+
+```
+/vibe {요구사항}
+  → SPEC 확정  ← 유일한 의무적 사람 개입 지점 (DONE의 정의 = REQ-ID + 수용 기준 승인)
+  → 루프:
+      ANCHOR   디스크에서 재고정: SPEC + run-ledger + scope.json (+ 직전 인박스)
+      ACT      파이프라인 실행 (스킬 체인)
+      JUDGE    결정론 판정만 인정: run-ledger verifyPassed │ 테스트 exit code │ RTM status
+               — 모델의 "완료했습니다" 자기 보고는 종료 조건이 될 수 없다
+      RECORD   run-ledger(현재 회전) + loop-history.jsonl(회전 이력, 스케줄 루프)
+  → 종료(EXIT): 게이트 전부 통과 │ stuck │ max_iterations │ 예산 상한
+```
+
+### ANCHOR가 컨텍스트 오염 방어인 이유
+루프 상태는 컨텍스트가 아니라 디스크에 산다. 매 회전이 아티팩트에서 다시 시작하므로 컨텍스트가 오염되거나 compact로 소실돼도 루프는 깨지지 않으며, 회전마다 fresh 컨텍스트(서브에이전트)로 돌려도 된다.
+
+### stuck (결정론)
+연속 2회 회전의 발견(discover/findings) 해시가 동일 → 중단하고 사람에게 (`loop-ledger.js check-stuck`이 판정·기록). "다시 해보면 될 것 같다"는 모델 판단으로 무시 금지.
+
+## 파라미터 (기본값)
+
+| 파라미터 | 기본 | 의미 |
+|---|---|---|
+| `max_iterations` | 10 | 회전 상한. 도달 시 잔여를 인박스로 이월 |
+| `exit` | 게이트 통과 (P1=0 ∧ verifyPassed) | 종료 기준. coverage 100% 등으로 상향 가능 |
+| `--interactive` | off | 단계별 확인 모드 (회전마다 사람 승인 — 과거의 기본값) |
+| `--max-iter N` | — | 회전 상한 명시 (N=1이면 1회 시도) |
+| `automationLevel` | `confirm` | `confirm`(SPEC·stuck에서 질문) / `autonomous`(기록 후 계속, 비대화형) — `.vibe/config.json` |
+
+## 금지 (루프 권한 경계)
+
+루프는 push·release·배포·버전 범프를 수행하지 않는다. 커밋은 auto-commit verify 게이트 통과 시만. 결과는 인박스(사람 리뷰 큐)로.
+
+## Deprecated 별칭 (하위 호환 매핑 — 새 문서에서 가르치지 않는다)
+
+| 별칭 | 환원 |
+|---|---|
+| `ralph` | 기본 동작과 동일 (no-op). 굳이 구분하면 `exit: coverage-100` |
+| `verify` | 기본 동작과 동일 (no-op) — JUDGE는 항상 결정론 검증 |
+| `quick` | `--max-iter 1` + 최소 JUDGE |
+| `ralplan` | 같은 계약을 계획 단계에 적용 |
+| `ultrawork` / `ulw` | `automationLevel: autonomous` + 병렬 ACT — 루프 시맨틱이 아니라 자율성·병렬성 축 |