@su-record/vibe 3.2.62 → 3.2.64

package/vibe/rules/loop-contract.md

@@ -71,14 +71,32 @@ node "$HOOKS_DIR/loop-ledger.js" iteration <name> <verified|unverified>   # 회
 node "$HOOKS_DIR/loop-ledger.js" budget <name> [max]                      # → {iterations, verified, remaining, exhausted}
 ```
 
-**두 축을 따로 센다:**
+**세 축을 따로 센다:**
 
-| 축 | 의미 | 쓰임 |
+| 축 | 의미 | 쓰임 | 성격 |
+|---|---|---|---|
+| `iterations` | 모든 회전 | `max_iterations` 와 비교하는 **폭주 방어** | 판정 |
+| `verified` | JUDGE 결정론 게이트를 통과한 회전만 | 실제로 **전진한 양** | 판정 |
+| `cost` | 회전당 경과 시간 · 도구 호출 수 · 서브에이전트 수 | 그 전진이 **얼마짜리였나** | **계측** |
+
+앞의 둘을 하나로 뭉치면 "10회를 썼다" 는 알아도 "그중 8회가 헛돌았다" 는 모른다 — 헛도는 루프와 원래 큰 작업을 구분할 수 없다. `exhausted: true` 면 잔여를 인박스로 이월하고 종료한다.
+
+#### `cost` 는 계측이지 판정이 아니다
+
+예산 소진·stuck·시운전 어디에도 영향을 주지 않는다. 축을 늘리는 것이 목적이 아니라, **지금 vibe 가 효율에 대해 아무 말도 할 수 없다**는 상태를 푸는 것이 목적이다 (constitution §3.5 — 측정하지 않은 수치는 쓰지 않는다).
+
+**수치의 출처는 코드다.** 모델이 "도구를 12번 썼다" 고 보고하는 형태였다면 그건 이 문서가 처음부터 배제하는 자기보고이고, 그 위에 쌓인 데이터로는 아무것도 주장할 수 없다. `step-counter.js`(PostToolUse)가 이미 액션 툴콜을 `current-run.jsonl` 에 적고 있으므로, 회전 창(직전 회전 ~ 이번 회전)에 드는 줄을 세는 것으로 끝난다 — 모델은 아무것도 넘기지 않는다.
+
+**재지 못한 것을 0 으로 적지 않는다.** 두 상태를 값과 구분해 남긴다:
+
+| 상태 | 뜻 | 합계 |
 |---|---|---|
-| `iterations` | 모든 회전 | `max_iterations` 와 비교하는 **폭주 방어** |
-| `verified` | JUDGE 결정론 게이트를 통과한 회전만 | 실제로 **전진한 양** |
+| `measured: false` | 훅 미설치·첫 실행이라 **재지 못했다** | 제외 |
+| `truncated: true` | 툴 로그가 회전해 창 앞부분이 사라졌다 — 그 값은 **하한** | 제외 |
 
-둘을 하나로 뭉치면 "10회를 썼다" 는 알아도 "그중 8회가 헛돌았다" 는 모른다 — 헛도는 루프와 원래 큰 작업을 구분할 수 없다. `exhausted: true` 면 잔여를 인박스로 이월하고 종료한다.
+`readBudget` 은 합계와 함께 `cost.measuredIterations`(분모)를 낸다. 분모를 모르면 합계는 거짓말이 된다 — "5회전에 도구 20회" 인지 "그중 2회전만 잰 20회" 인지 구분되지 않는다. 훅은 프로젝트 로컬이라 미설치가 흔하고, 그 환경에서 0 을 채우면 "회전당 도구 0회" 라는 거짓 데이터가 쌓인다.
+
+> ⛔ **이 수치로 "N% 절감"·"몇 배 빠름" 을 쓰지 않는다.** 비교 데이터가 쌓이기 전의 배수·퍼센트는 §3.5 가 금지하는 바로 그것이다. 지금 하는 일은 **쌓는 것**이고, 비교는 `/vibe.test bench` 가 자기 대조로 할 일이다.
 
 - **실행 실패(error)는 회전을 소비하지 않는다** — 위 실행 실패 절대로 루프가 즉시 종료되므로 예산을 갉아먹지 않는다. 재시도가 예산을 태우는 형태를 만들지 않는다.
 - 계수는 직전 `start` 이후만 센다 — 새 실행은 예산도 새로 시작한다.
@@ -221,6 +239,8 @@ JUDGE는 이번 feature의 **신규 생성 파일** 기준으로 검증 코드
 
 **어느 쪽이 결과가 나은지는 vibe 가 측정한 바 없다.** 컨텍스트 누적이 품질을 떨어뜨린다는 주장은 널리 퍼져 있지만 이 저장소에는 비교 데이터가 없다(수치 출처 규율 §3.5). 그래서 기본값을 바꾸지 않고 **축만 열어둔다** — 긴 무인 운전에서 컨텍스트 상한이 걱정되면 `per-iteration`, 회전 간 연속성이 중요하면 `continuous`.
 
+재려면 `/vibe.loop bench` 로 조건만 바꿔 돌린 실행을 대조한다 — 표본이 부족하거나 관측 범위가 겹치면 그 도구가 `inconclusive` 를 내고 차이를 지어내지 않는다. 이 문장이 지워지는 시점은 벤치가 `difference-observed` 를 낸 뒤다.
+
 전제 하나는 반드시 지킨다: `per-iteration` 에서 **넘길 것을 파일에 적기 전에 끝내지 않는다.** 맥락이 파일로만 넘어가는 구조이므로, 안 적으면 이월이 아니라 유실이다.
 
 ### 시운전 (처음 거는 루프)

package/vibe/templates/spec-template.md

@@ -147,7 +147,21 @@ Response: 201 {...}
 
 ---
 
-## 7. Verification
+## 7. Agent Contract (only if the feature ships an agent)
+
+> Presence of this section enables `/vibe.contract agent` — 에이전트 실행이 남긴 **도구 호출
+> 로그**에 대해 계약을 단언한다. LLM 이 에이전트 응답을 채점하는 것이 아니다: 그건 Model Judge 라
+> 완료 권한이 없다 (`vibe/rules/loop-contract.md`). 판정 대상이 로그이므로 위반은 차단한다.
+
+- **Allowed tools**: `{tool_a}`, `{tool_b}` — 비워 두면 allowlist 미선언(미등재 호출을 검사하지 않는다)
+- **Forbidden tools**: `{tool_x}`
+- **Irreversible**: `{tool_y}` — 호출에 승인 기록(`approved: true`)이 있어야 한다
+- **Escalate**: {조건 1문장} — **선언만 받는다.** 조건 충족 여부가 도구 로그에 없어 게이트가 되지 못하고,
+  advisory 로 사람에게 넘어간다. 판정할 수 없는 것을 게이트에 넣으면 통과 의식이 된다
+
+---
+
+## 8. Verification
 
 - `/vibe.run "{feature}"` implements scenario-by-scenario, verifying each immediately.
 - `/vibe.verify "{feature}"` judges the Done Criteria and sets `verifyPassed` in the run-ledger.