@su-record/vibe 2.12.5 → 2.14.0

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

@@ -0,0 +1,173 @@
+# Ralph Loop — Coverage Verification Reference
+
+> 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"이 설정된 기본 루프와 동일하다. 더 이상 별도 모드가 아니다.
+
+## 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 — loop-contract의 JUDGE 기준은 `coveragePercent === 100`.
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│           COVERAGE VERIFICATION LOOP (loop-contract + RTM)      │
+│                                                                  │
+│   After ALL phases complete:                                     │
+│                                                                  │
+│   ┌──────────────────────────────────────────────────────────┐  │
+│   │  RTM COVERAGE VERIFICATION [Iteration {{ITER}}/{{MAX}}]   │  │
+│   │                                                           │  │
+│   │  Generate RTM via core tools:                             │  │
+│   │  → generateTraceabilityMatrix("{feature-name}")           │  │
+│   │                                                           │  │
+│   │  Coverage Metrics (automated):                            │  │
+│   │  □ Requirements coverage: {coveragePercent}%              │  │
+│   │  □ SPEC → Feature mapping: {featureCovered}/{total}       │  │
+│   │  □ Feature → Test mapping: {testCovered}/{total}          │  │
+│   │  □ Build successful?                                      │  │
+│   │  □ Tests passing?                                         │  │
+│   │                                                           │  │
+│   │  UNCOVERED: {uncoveredRequirements[]}                     │  │
+│   └──────────────────────────────────────────────────────────┘  │
+│                              │                                   │
+│                   ┌──────────┴──────────┐                       │
+│                   │  Coverage == 100%?  │                       │
+│                   └──────────┬──────────┘                       │
+│                       │              │                          │
+│                      NO            YES                          │
+│                       │              │                          │
+│                       ↓              ↓                          │
+│              ┌────────────────┐  ┌────────────────┐             │
+│              │ IMPLEMENT      │  │ TRULY DONE     │             │
+│              │ UNCOVERED      │  │                │             │
+│              │ REQUIREMENTS   │  │ Report final   │             │
+│              │ (auto-extract) │  │ RTM coverage   │             │
+│              └───────┬────────┘  └────────────────┘             │
+│                      │                                          │
+│                      └──────────→ [Re-generate RTM]             │
+│                                                                  │
+│                      │                                          │
+│                      ↓                                          │
+│       stuck? (loop-ledger.js check-stuck: 연속 2회 동일 커버리지) │
+│                      │                                          │
+│                      ├─ automationLevel confirm: Ask user       │
+│                      │     1. Provide resolution → retry        │
+│                      │     2. "proceed" → TODO + done           │
+│                      │     3. "abort" → stop                    │
+│                      └─ automationLevel autonomous: TODO + done │
+│                                                                  │
+│   max_iterations 기본 10 — 도달 시 잔여 인박스 이월             │
+│   ZERO TOLERANCE for silent scope reduction                     │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+## RTM Invocation
+
+```bash
+# Generate RTM for coverage verification (generateTraceabilityMatrix is synchronous — no .then())
+node -e "import('{{VIBE_PATH_URL}}/node_modules/@su-record/vibe/dist/tools/index.js').then(t => { const r = t.generateTraceabilityMatrix('{feature-name}', {projectPath: process.cwd()}); console.log(JSON.stringify(r, null, 2)); })"
+```
+
+> **Note:** Default SPEC path is `.vibe/specs/<feature>.md` (falls back to `.claude/vibe/specs/` then `.claude/specs/` for legacy projects).
+> `status === 'empty'` means the gate MUST be treated as failed/not-applicable, never as 100% pass.
+
+## RTM Metrics
+
+| Metric | Description |
+|--------|-------------|
+| `totalRequirements` | Total REQ-* items in SPEC |
+| `specCovered` | Requirements with SPEC mapping |
+| `featureCovered` | Requirements with Feature scenarios |
+| `testCovered` | Requirements with test files |
+| `coveragePercent` | Overall coverage percentage |
+| `uncoveredRequirements` | List of missing REQ-* IDs |
+
+## Coverage Loop Rules
+
+| Rule | Description |
+|------|-------------|
+| **No Scope Reduction** | Never say "simplified" or "basic version" — implement FULL request |
+| **Iteration Tracking** | Display `[{{ITER}}]` to show progress; max_iterations 기본 10 |
+| **RTM-Based Gap List** | Use `uncoveredRequirements` array — no manual comparison |
+| **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
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+RALPH VERIFICATION [Iteration 1]
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+RTM Coverage Report: login
+
+Requirements Traceability:
+  Total Requirements: 9
+  SPEC Covered: 9/9 (100%)
+  Feature Covered: 5/9 (55%)
+  Test Covered: 4/9 (44%)
+
+  REQ-login-001: Login form UI → Scenario 1 → login.test.ts
+  REQ-login-002: Email validation → Scenario 2 → validation.test.ts
+  REQ-login-003: Password validation → Scenario 2 → validation.test.ts
+  REQ-login-004: Remember me checkbox → NOT IMPLEMENTED
+  REQ-login-005: Forgot password link → NOT IMPLEMENTED
+  REQ-login-006: API integration → Scenario 3 → api.test.ts
+  REQ-login-007: Loading state → NOT IMPLEMENTED
+  REQ-login-008: Error toast → NOT IMPLEMENTED
+  REQ-login-009: Session storage → Scenario 4 → (no test)
+
+Overall Coverage: 55% BELOW 100% TARGET
+
+UNCOVERED REQUIREMENTS (auto-extracted from RTM):
+  1. REQ-login-004: Remember me checkbox
+  2. REQ-login-005: Forgot password link
+  3. REQ-login-007: Loading state
+  4. REQ-login-008: Error toast notifications
+
+NOT COMPLETE — Implementing uncovered requirements...
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+RALPH VERIFICATION [Iteration 2]
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+RTM Coverage Report: login
+
+Requirements Traceability:
+  Total Requirements: 9
+  SPEC Covered: 9/9 (100%)
+  Feature Covered: 9/9 (100%)
+  Test Covered: 9/9 (100%)
+
+Overall Coverage: 100% TARGET REACHED
+
+Build: Passed
+Tests: 12/12 Passed
+Type Check: No errors
+
+RALPH VERIFIED COMPLETE!
+
+RTM saved: .vibe/rtm/login-rtm.md
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+## When to Trigger Coverage Loop
+
+1. After all phases complete (기본 동작 — 별도 키워드 불필요)
+2. Before final quality report
+3. `ralph` 별칭 감지 시 — 기본 동작과 동일, exit=coverage-100으로 해석
+
+## Forbidden Responses (VIOLATIONS)
+
+| NEVER Say | Instead |
+|-----------|---------|
+| "I've implemented a basic version" | Implement the FULL version |
+| "This is a simplified approach" | Implement as specified |
+| "You can add X later" | Add X now |
+| "For demonstration purposes" | Implement production-ready |
+| "The core functionality is done" | ALL functionality must be done |

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

@@ -0,0 +1,151 @@
+# 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 `automationLevel: autonomous` Enables
+
+`ultrawork` (또는 `ulw`, `.vibe/config.json`의 `automationLevel: autonomous`) 설정 시 활성화:
+
+| Feature | Description |
+|---------|-------------|
+| **Parallel Exploration** | 3+ Task(haiku) agents run simultaneously (ACT 병렬화) |
+| **Loop (기본 동작)** | 모든 실행의 기본 — exit=게이트 통과 또는 stuck 또는 max_iterations |
+| **Context Compression** | Aggressive auto-save at 70%+ context |
+| **No Pause** | stuck·SPEC 게이트 외 확인 없음 (`automationLevel: autonomous`) |
+| **External LLMs** | Auto-consults GPT/Antigravity if enabled |
+| **Error Recovery** | stuck 시 TODO 기록 후 다음으로 (사용자 질문 없음) |
+| **Race Review** | Multi-LLM review (GPT+Antigravity) with cross-validation |
+
+## Boulder Loop — Parallel ACT Visualization
+
+루프 자체는 loop-contract의 기본 동작이다. Boulder Loop는 `automationLevel: autonomous`에서 **병렬 ACT**가 어떻게 실행되는지를 보여주는 다이어그램이다:
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                    BOULDER LOOP (ultrawork)                      │
+│                                                                  │
+│   ┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐  │
+│   │ Phase 1  │───→│ Phase 2  │───→│ Phase 3  │───→│ Phase N  │  │
+│   └──────────┘    └──────────┘    └──────────┘    └──────────┘  │
+│        │               │               │               │         │
+│        ↓               ↓               ↓               ↓         │
+│   [Parallel]      [Parallel]      [Parallel]      [Parallel]    │
+│   [Implement]     [Implement]     [Implement]     [Implement]   │
+│   [Test]          [Test]          [Test]          [Test]        │
+│        │               │               │               │         │
+│        └───────────────┴───────────────┴───────────────┘         │
+│                              │                                   │
+│                              ↓                                   │
+│                     ┌──────────────┐                             │
+│                     │  ALL DONE?   │                             │
+│                     └──────────────┘                             │
+│                       │         │                                │
+│                      NO        YES                               │
+│                       │         │                                │
+│                       ↓         ↓                                │
+│                   [Continue]  [Complete!]                        │
+│                                                                  │
+│   loop-contract EXIT: 게이트 통과 │ stuck │ max_iterations       │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+## Example Session (automationLevel: autonomous)
+
+```
+User: /vibe.run "brick-game" ultrawork
+
+Claude:
+AUTONOMOUS MODE (automationLevel: autonomous)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+SPEC: .vibe/specs/brick-game.md
+4 Phases detected
+Loop: ENABLED (exit = 게이트 통과 | stuck | max_iterations=10)
+Parallel ACT: ON
+automationLevel: autonomous (stuck → auto-TODO, no confirmation)
+Context compression: AGGRESSIVE
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+BOULDER ROLLING... Phase 1/4
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+[PARALLEL] Launching 3 exploration agents...
+Exploration complete (7.2s)
+Implementing...
+Phase 1 complete
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+BOULDER ROLLING... Phase 2/4
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+[PARALLEL] Launching 3 exploration agents...
+Exploration complete (6.8s)
+Implementing...
+Test failed: collision detection
+Auto-retry [iteration 1]...
+Fixing...
+Phase 2 complete
+
+[...continues automatically...]
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+BOULDER REACHED THE TOP!
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+All 4 phases complete
+All acceptance criteria passed
+Build succeeded
+Tests passed
+
+Total: 8m 24s
+Retries: 2
+Context saved: 3 checkpoints
+```
+
+## confirm vs autonomous Comparison
+
+| 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 |
+
+## Automation Level System
+
+**automationLevel**은 루프가 사람 개입 없이 얼마나 자율적으로 진행하는지를 제어한다. `.vibe/config.json`에서 설정하거나, deprecated 별칭 키워드로 런타임 오버라이드 가능.
+
+### Level Definitions
+
+| 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`(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 (deprecated aliases)
+
+```
+/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
+
+| Action | L0 | L1 | L2 | L3 | L4 |
+|--------|----|----|----|----|-----|
+| `destructive` | confirm | confirm | confirm | confirm | auto |
+| `architecture_choice` | confirm | confirm | confirm | auto | auto |
+| `implementation_scope` | confirm | confirm | confirm | auto | auto |
+| `phase_advance` | confirm | confirm | auto | auto | auto |
+| `fix_strategy` | confirm | confirm | auto | auto | auto |
+| `retry` | confirm | auto | auto | auto | auto |
+
+**Rule**: When confirmation is required, pause and display a checkpoint before proceeding.

package/skills/vibe.trace/SKILL.md

@@ -187,63 +187,50 @@ Loading files:
 The RTM generation uses core tools:
 
 ```bash
-# Generate RTM
-node -e "import('{{VIBE_PATH_URL}}/node_modules/@su-record/vibe/dist/tools/index.js').then(t => t.generateTraceabilityMatrix('login').then(m => console.log(t.formatMatrixAsMarkdown(m))))"
+# Generate RTM (generateTraceabilityMatrix is synchronous — no .then())
+node -e "import('{{VIBE_PATH_URL}}/node_modules/@su-record/vibe/dist/tools/index.js').then(t => { const m = t.generateTraceabilityMatrix('login', {projectPath: process.cwd()}); console.log(t.formatMatrixAsMarkdown(m)); })"
 
 # Generate HTML
-node -e "import('{{VIBE_PATH_URL}}/node_modules/@su-record/vibe/dist/tools/index.js').then(t => t.generateTraceabilityMatrix('login').then(m => console.log(t.formatMatrixAsHtml(m))))"
+node -e "import('{{VIBE_PATH_URL}}/node_modules/@su-record/vibe/dist/tools/index.js').then(t => { const m = t.generateTraceabilityMatrix('login', {projectPath: process.cwd()}); console.log(t.formatMatrixAsHtml(m)); })"
 ```
 
-## VerificationLoop Integration
+> **Note:** Default SPEC path is `.vibe/specs/<feature>.md` (falls back to `.claude/vibe/specs/` then `.claude/specs/` for legacy projects).
+> `status === 'empty'` means the gate MUST be treated as failed/not-applicable, never as 100% pass.
 
-`/vibe.trace` results feed directly into the **VerificationLoop** module, which quantifies achievement rate and drives automatic re-iteration.
+## Post-Trace Gates
 
-### Key Functions
+After `/vibe.trace` completes and the RTM is displayed, two downstream mechanisms consume the result.
 
-| Function | Purpose |
-|----------|---------|
-| `createLoop(feature, config?)` | Initialize a new verification loop for a feature |
-| `recordVerification(state, requirements)` | Record RTM results and determine next action |
-| `formatVerificationResult(result, config)` | Format a single iteration result for display |
-| `formatLoopSummary(state)` | Format the full loop history as readable text |
-| `getUnmetRequirements(result)` | Extract failed/partial requirements for targeted fixing |
-| `isImproving(state)` | Detect whether achievement rate is increasing across iterations |
+### Empty-result gate
 
-### Loop Configuration
+`generateTraceabilityMatrix` returns `status: 'empty'` when no `REQ-<feature>-NNN` IDs are found in the SPEC. This state **must be treated as a gate failure**, not as 100% coverage. When the matrix status is `empty`, report it explicitly and do not proceed as if the feature is verified.
 
 ```
-threshold:      90    — Minimum achievement rate (%) to pass (default)
-maxIterations:  3     — Max re-verification attempts before stopping
-autoRetry:      false — Whether to auto-trigger re-implementation
+RTM status === 'empty'
+  → Coverage gate: FAILED (no requirements to trace)
+  → Action: run /vibe.spec to add REQ-IDs before re-running /vibe.trace
 ```
 
-### Action Types
+### Run-ledger flow
 
-After each `recordVerification` call, the loop returns one of:
+`/vibe.verify` records its outcome via `hooks/scripts/verify-ledger.js pass|fail`. This writes `verifyPassed` and `verifyAt` into `.vibe/metrics/run-ledger.json`. Downstream gates consume this record:
 
-| Action | Condition | Meaning |
-|--------|-----------|---------|
-| `passed` | rate >= threshold | All requirements met — done |
-| `retry` | rate < threshold AND iterations remaining | Fix unmet requirements and re-run |
-| `max_iterations` | rate < threshold AND no iterations left | Report remaining gaps as TODO |
+| Gate | Behavior |
+|------|----------|
+| `auto-commit` | Commits only when `verifyPassed === true` AND `verifyAt > runStarted` |
+| Stop hook | Warns when `runStarted && !verifyPassed`; blocks once if `verifyGate.mode === 'block'` |
 
-### Convergence Detection
-
-If the achievement rate does not improve between iterations (`isImproving` returns false), the loop stops early to avoid wasted cycles.
-
-### Example Flow
+**To register a passing trace as verified**, run `/vibe.verify` after `/vibe.trace` reports acceptable coverage. The verify skill calls `verify-ledger.js pass` internally — you do not invoke it manually.
 
 ```
-/vibe.trace "login"
-  → RTM generated: 7/9 requirements covered (78%)
-  → createLoop("login", { threshold: 90, maxIterations: 3 })
-  → recordVerification(...) → action: retry (iteration 1, 3 unmet)
-  → [fix unmet requirements]
-  → /vibe.trace "login"
-  → recordVerification(...) → action: passed (rate: 100%)
-  → formatVerificationResult → display final report
+/vibe.trace "login"         → RTM: 9/9 (100%)
+/vibe.verify "login"        → runs checks → calls verify-ledger.js pass
+                            → .vibe/metrics/run-ledger.json updated
+auto-commit / Stop gate     → verifyPassed=true, gate clears
 ```
 
+If `/vibe.verify` is skipped, `auto-commit` will log the skip reason and abort the commit.
+
 ## Options
 
 | Option | Description |

package/skills/vibe.verify/SKILL.md

@@ -465,6 +465,21 @@ Load skill `contract` with: check "{feature-name}"
 - **P1 drift** → demote verify to fail; auto-call `/vibe.regress register --from-contract`
 - P2 / P3 drift → warning only; verify still passes
 
+## Ledger Update (MANDATORY final step)
+
+After producing the verification report, record the result to the run ledger:
+
+```bash
+# pass 또는 fail — 시나리오 전체 통과 여부에 따라 선택
+HOOKS_DIR="${VIBE_PATH:-$(npm root -g 2>/dev/null)/@su-record/vibe}/hooks/scripts"
+if [ -f "$HOOKS_DIR/verify-ledger.js" ]; then
+  node "$HOOKS_DIR/verify-ledger.js" pass   # 전체 통과 시
+  # node "$HOOKS_DIR/verify-ledger.js" fail  # 실패 시
+fi
+```
+
+Replace `pass` with `fail` when any scenario fails. This step enables the Stop-hook verify-skip gate and auto-commit verify gate.
+
 ## Next Step
 
 On verification pass:

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 — 루프 시맨틱이 아니라 자율성·병렬성 축 |

package/vibe/templates/loop-template.md

@@ -0,0 +1,69 @@
+---
+name: {loop-name}
+trigger: scheduled
+schedule: "0 2 * * *"
+goal: "{사람이 읽는 루프 목표 — 한 문장}"
+discover: |
+  {일거리를 발견하는 지시문.
+  여러 줄 사용 가능.
+  예: .vibe/regressions/open/*.md 를 스캔해 우선순위 높은 항목을 반환한다.}
+pipeline:
+  - vibe.spec
+  - vibe.run
+  - vibe.verify
+verify: ledger
+max_iterations: 10
+isolation: none
+status: active
+---
+
+# 루프: {loop-name}
+
+## 목적
+
+{이 루프가 자동화하는 작업과 그 이유를 1–3문장으로 설명한다.}
+
+## Discover 상세
+
+{`discover` frontmatter 필드의 상세 설명.
+루프 런타임이 어떤 소스를 보는지, 어떤 형식으로 항목이 반환되는지 기술한다.
+
+예시:
+- 스캔 대상: `.vibe/regressions/open/`
+- 반환 형식: `- REQ-XXX-NNN: 설명` 불릿 목록
+- 빈 결과 처리: 항목 없을 시 루프 즉시 종료}
+
+## 항목별 파이프라인
+
+{`pipeline` frontmatter에 나열된 각 스킬이 단일 항목에 대해 수행하는 작업을 설명한다.
+
+| 단계 | 스킬 | 입력 | 출력 |
+|------|------|------|------|
+| 1 | vibe.spec | 항목 설명 | SPEC 파일 |
+| 2 | vibe.run | SPEC | 구현 |
+| 3 | vibe.verify | 구현 | 검증 결과 |
+}
+
+## 종료 조건
+
+{루프가 단일 항목 처리를 완료로 판정하는 조건을 명시한다.}
+
+- `verify: ledger` — `.vibe/metrics/run-ledger.json`의 `verifyPassed === true` (모델 자기 보고 불가)
+- `verify: tests` — `test_command` exit code 0
+- `verify: none` — 파이프라인 마지막 스킬 완료 시
+- 연속 2회 `discoverHash` 동일 → stuck으로 중단, 인박스 기록
+
+## 인박스 보고 형식
+
+{각 반복 완료 후 `.vibe/loops/inbox.md`에 추가되는 항목 형식.}
+
+```
+## [{loop-name}] {YYYY-MM-DD HH:mm}
+
+- **결과**: ok | fail | stuck
+- **처리한 항목**: {항목 설명}
+- **검증 상태**: verifyPassed=true | false
+- **리뷰 필요**: {사람이 확인해야 할 사항. 없으면 "없음"}
+```
+
+> 루프는 push·release·배포를 수행하지 않는다. auto-commit verify 게이트 통과 시 커밋까지만.