@su-record/vibe 3.2.60 → 3.2.62

package/hooks/scripts/session-start.js

@@ -96,19 +96,11 @@ async function main() {
       getLatestVersionCached(),
     ]);
 
-    console.log(time.content[0].text);
-
-    // Active feature 1줄 인덱스
-    try {
-      const LIB_BASE_P = (await import('./utils.js')).getLibBaseUrl();
-      const iterMod = await import(`${LIB_BASE_P}IterationTracker.js`);
-      const progressLine = iterMod.getProgressSummary(PROJECT_DIR);
-      if (progressLine) {
-        console.log(`\n📋 ${progressLine} — resume full context: /vibe.continue`);
-      }
-    } catch { /* progress index is best-effort */ }
-
-    console.log('\n[Memory Index — bodies on demand via recall_memory]');
+    // ─── 안정 블록 먼저 ────────────────────────────────────────────────
+    // 세션마다 값이 달라지는 것(현재 시각·진행 카운터·버전 체크)은 아래 휘발 블록으로
+    // 모아 뒤에 붙인다. 세션 컨텍스트의 앞부분을 가능한 한 세션 간 동일하게 유지하려는
+    // 배치다 — 휘발 데이터를 앞에 두면 어떤 합성 방식에서도 이득이 없다.
+    console.log('[Memory Index — bodies on demand via recall_memory]');
     console.log(memories.content[0].text);
 
     // Phase 3 — Recipes + anti-patterns 인덱스 (post-task curation)
@@ -130,15 +122,6 @@ async function main() {
       }
     } catch { /* curation is best-effort */ }
 
-    // Version check
-    if (latestVersion) {
-      const currentVersion = getCurrentVersion();
-      if (currentVersion && compareVersions(latestVersion, currentVersion) > 0) {
-        console.log(`\n⬆️ Harness update available: v${currentVersion} → v${latestVersion}`);
-        console.log('   Run: vibe upgrade');
-      }
-    }
-
     // Scope sync — 기본 OFF (opt-in: scopeGuard.enabled=true). SSOT: scope-from-spec.js.
     try {
       const { syncScopeFile, isScopeGuardEnabled } = await import('./lib/scope-from-spec.js');
@@ -214,8 +197,32 @@ async function main() {
 
     // Evolution 상태 요약은 제거 — evolution 은 동결(opt-in) 상태이며
     // 사용자는 `vibe evolution` CLI 로 명시적으로 조회한다 (P3-3).
+
+    // ─── 휘발 블록 마지막 ──────────────────────────────────────────────
+    // 현재 시각·진행 카운터·버전 체크는 세션마다 값이 달라진다. 위의 안정 블록을
+    // 앞에 두기 위해 여기로 모았다. 내용은 이전과 동일하고 순서만 바뀐다.
+    console.log(`\n${time.content[0].text}`);
+
+    try {
+      const LIB_BASE_P = (await import('./utils.js')).getLibBaseUrl();
+      const iterMod = await import(`${LIB_BASE_P}IterationTracker.js`);
+      const progressLine = iterMod.getProgressSummary(PROJECT_DIR);
+      if (progressLine) {
+        console.log(`📋 ${progressLine} — resume full context: /vibe.continue`);
+      }
+    } catch { /* progress index is best-effort */ }
+
+    if (latestVersion) {
+      const currentVersion = getCurrentVersion();
+      if (currentVersion && compareVersions(latestVersion, currentVersion) > 0) {
+        console.log(`\n⬆️ Harness update available: v${currentVersion} → v${latestVersion}`);
+        console.log('   Run: vibe upgrade');
+      }
+    }
   } catch (e) {
-    console.log('[Session] Error:', e.message);
+    // 훅 실패를 stdout 으로 보내면 "실패 신호" 가 아니라 모델에게 주입되는
+    // 컨텍스트 문자열이 된다 — 가드의 생사가 관측 불가능해진다.
+    console.error('[Session] Error:', e.message);
   }
 }
 

package/hooks/scripts/utils.js

@@ -372,12 +372,11 @@ const DEFAULT_COST = { input: 0.003, output: 0.010 };
  *
  * @param {string} provider - 프로바이더 (gpt, antigravity)
  * @param {string} model - 모델명
- * @param {number} inputLen - 입력 문자 수
- * @param {number} outputLen - 출력 문자 수
- * @param {number} durationMs - 호출 소요 시간
- * @param {boolean} cached - 캐시 히트 여부
+ * @param {{ inputLen: number, outputLen: number, durationMs: number, cached: boolean }} call
+ *   inputLen/outputLen 은 문자 수, durationMs 는 호출 소요 시간, cached 는 캐시 히트 여부
  */
-export function logLlmCost(provider, model, inputLen, outputLen, durationMs, cached) {
+export function logLlmCost(provider, model, call) {
+  const { inputLen, outputLen, durationMs, cached } = call;
   try {
     if (fs.existsSync(LLM_COST_PATH)) {
       const stat = fs.statSync(LLM_COST_PATH);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@su-record/vibe",
-  "version": "3.2.60",
+  "version": "3.2.62",
   "description": "AI Coding Framework for Claude Code — 7+ agents, 52 skills, multi-LLM orchestration",
   "type": "module",
   "main": "dist/cli/index.js",
@@ -23,12 +23,15 @@
   "scripts": {
     "build": "tsc -p tsconfig.build.json && chmod +x dist/cli/index.js",
     "dev": "tsc --watch",
-    "gen:skill-docs": "npx tsx scripts/gen-skill-docs.ts",
-    "gen:skill-docs:check": "npx tsx scripts/gen-skill-docs.ts --check",
-    "sync:agent-models": "npx tsx scripts/sync-agent-models.ts",
-    "sync:agent-models:check": "npx tsx scripts/sync-agent-models.ts --check",
-    "validate:skill-invocation": "npx tsx scripts/validate-skill-invocation.ts",
-    "validate:counts": "npx tsx scripts/validate-counts.ts",
+    "gen:skill-docs": "tsx scripts/gen-skill-docs.ts",
+    "gen:skill-docs:check": "tsx scripts/gen-skill-docs.ts --check",
+    "sync:agent-models": "tsx scripts/sync-agent-models.ts",
+    "sync:agent-models:check": "tsx scripts/sync-agent-models.ts --check",
+    "validate:skill-invocation": "tsx scripts/validate-skill-invocation.ts",
+    "validate:counts": "tsx scripts/validate-counts.ts",
+    "lint": "oxlint",
+    "lint:ratchet": "tsx scripts/lint-ratchet.ts",
+    "verify:all": "pnpm lint && pnpm lint:ratchet && pnpm gen:skill-docs:check && pnpm sync:agent-models:check && pnpm validate:skill-invocation && pnpm validate:counts && pnpm gen:agents-md:check && pnpm validate:spec-lifecycle && pnpm validate:cache-surface",
     "test": "vitest run",
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
@@ -41,7 +44,11 @@
     "gen:plugin-hooks": "npx tsx scripts/gen-plugin-hooks.ts",
     "gen:plugin-hooks:check": "npx tsx scripts/gen-plugin-hooks.ts --check",
     "validate:plugin-tree": "npx tsx scripts/build-plugin.ts && git diff --exit-code --stat HEAD -- plugins/",
-    "validate:mermaid": "npx tsx scripts/validate-mermaid.ts"
+    "validate:mermaid": "npx tsx scripts/validate-mermaid.ts",
+    "validate:spec-lifecycle": "npx tsx scripts/validate-spec-lifecycle.ts",
+    "validate:cache-surface": "npx tsx scripts/validate-cache-surface.ts",
+    "gen:agents-md": "npx tsx scripts/gen-agents-md.ts",
+    "gen:agents-md:check": "npx tsx scripts/gen-agents-md.ts --check"
   },
   "keywords": [
     "ai",
@@ -100,6 +107,8 @@
     "ajv": "^8.17.1",
     "jsdom": "^25.0.1",
     "mermaid": "^11.17.2",
+    "oxlint": "^1.76.0",
+    "tsx": "^4.23.5",
     "typescript": "^5.9.3",
     "vitest": "^4.1.10"
   },
@@ -121,7 +130,8 @@
   ],
   "pnpm": {
     "onlyBuiltDependencies": [
-      "better-sqlite3"
+      "better-sqlite3",
+      "esbuild"
     ]
   }
 }

package/skills/vibe.docs/references/agent.md

@@ -17,6 +17,10 @@ Cursor is not supported — do not generate or check Cursor-specific context fil
 **Source of truth:**
 - **`CLAUDE.md` is the content SSOT.** Always edit it first; `AGENTS.md` is a regenerated derivative.
 - Behavioral block: `skills/vibe.docs/templates/behavioral-principles.md` (4 Karpathy principles, wrapped in `<!-- VIBE-BEHAVIORAL:START/END -->` markers).
+- **번역 규칙이 파일로 존재하면 그 파일이 SSOT다.** 프로젝트 루트에 `scripts/agents-md-rules.json` 이 있으면
+  아래 4·5번 손 치환 목록을 쓰지 않고 `npm run gen:agents-md` 로 생성한다 — 규칙을 두 곳에 적으면
+  그 순간 두 벌이 되고, 어느 쪽이 맞는지 판정할 수단이 사라진다. 검증은 `npm run gen:agents-md:check`.
+  (vibe 저장소 자신이 이 경로다. 규칙 파일이 없는 프로젝트는 4·5번을 그대로 적용한다.)
 
 **Procedure (applies to both creation and modification):**
 

package/vibe/rules/prefix-cache-surface.md

@@ -0,0 +1,98 @@
+# 프리픽스 캐시 표면
+
+> 매 요청의 **앞부분에 항상 실리는 자산**이 무엇이고, 그것을 건드리면 무엇이 깨지는지.
+> 검증: `npm run validate:cache-surface` (CI `test` job).
+
+## 왜 이 문서가 있는가
+
+컨텍스트 정책(85% 룰, `/new` 가 KV 프리픽스 캐시를 전량 폐기한다)은 `CLAUDE.md` 에 한 줄로
+적혀 있었다. 그 한 줄은 **어떤 파일을 고치면 캐시가 깨지는지**를 말해주지 않는다 — 그래서
+"상시 로드 자산에 문단 하나 추가" 같은 변경이 리뷰에서 그냥 통과한다. 비용은 그 PR 이
+아니라 이후 모든 세션의 첫 토큰에서 나온다.
+
+여기서 고정하는 것은 두 가지다: **모델이 이 자산을 어떻게 경험하는가**(Model Experience)와
+**이 자산을 바꾸면 캐시가 어떻게 되는가**(KV Cache effect). 자산이 늘거나 사라지면 게이트가 막는다.
+
+## 무효화의 규칙 (모든 표면 공통)
+
+프리픽스 캐시는 **접두사 일치**로 재사용된다 — 앞에서 한 바이트가 달라지면 그 뒤는 전부
+다시 계산된다. 따라서 비용은 "얼마나 고쳤나" 가 아니라 **"얼마나 앞에서 고쳤나"** 로 정해진다.
+표면을 아래 순서대로 읽는다: 위쪽일수록 한 글자의 대가가 크다.
+
+<!-- surface: always-loaded-docs -->
+## 표면 1 — 루트 지침 문서 (`CLAUDE.md` · `AGENTS.md`)
+
+- **Model Experience**: 세션 시작 시 **전문이** 시스템 프롬프트에 들어간다. 모델은 이 문서를
+  "검색해서 찾는 문서" 가 아니라 **이미 알고 있는 규칙**으로 경험한다 — 그래서 여기 적힌 것은
+  탐색 없이 즉시 적용되고, 여기 없는 것은 존재를 모른다.
+- **KV Cache effect**: 프리픽스의 가장 앞쪽에 가깝다. **한 줄만 고쳐도 그 아래 전체가 무효화**되고,
+  이후 모든 세션이 첫 요청에서 전문을 다시 계산한다. 문단 추가는 상시 비용이므로, 상세는
+  `vibe/rules/**` 로 내리고 루트에는 **포인터만** 남긴다.
+
+| 자산 | 비고 |
+|---|---|
+| `CLAUDE.md` | content SSOT |
+| `AGENTS.md` | `CLAUDE.md` 에서 생성 (`npm run gen:agents-md`) |
+
+<!-- surface: prefix-hooks -->
+## 표면 2 — 프리픽스에 stdout 을 얹는 훅
+
+훅 전체가 아니라 **턴 앞단에서 도는 두 이벤트**만 해당한다. `PreToolUse`/`PostToolUse`/`Stop` 은
+턴 중간에 끼어들어 이미 만들어진 프리픽스를 바꾸지 않는다.
+
+- **Model Experience**: 이 훅의 stdout 은 모델에게 **사용자가 말하지 않은 지시문**으로 보인다.
+  출처 표시가 없으면 사용자 발화와 구분되지 않으므로, 출력은 짧고 라벨이 붙어야 한다.
+- **KV Cache effect**: `SessionStart` 출력은 세션 프리픽스에 **한 번** 박힌다 — 길이가 그대로
+  상시 비용이다. `UserPromptSubmit` 출력은 **매 턴** 프리픽스 끝에 붙는다. 출력이 턴마다
+  달라지면(시각·카운터·랜덤 순서) 그 지점부터 재사용이 끊기므로, **불변 텍스트를 앞에, 가변
+  텍스트를 뒤에** 둔다.
+
+| 이벤트 | 스크립트 |
+|---|---|
+| SessionStart | `hooks/scripts/session-start.js` |
+| UserPromptSubmit | `hooks/scripts/prompt-dispatcher.js` |
+
+<!-- surface: agents -->
+## 표면 3 — 에이전트 frontmatter `description`
+
+- **Model Experience**: 에이전트 **본문은 로드되지 않는다.** 모델이 항상 보는 것은 이름과
+  `description` 한 줄뿐이고, 위임 여부는 전적으로 그 한 줄로 결정된다. description 이 비면
+  에이전트는 설치돼 있어도 **없는 것과 같다** (실측: frontmatter 가 YAML 파싱에 실패해 통째로
+  버려진 설치본이 11개 중 4개였다 — `CLAUDE.md` Gotchas).
+- **KV Cache effect**: 에이전트 목록 전체가 프리픽스에 실린다. 에이전트를 **추가·삭제**하면
+  목록이 바뀌어 그 뒤가 무효화되고, description 을 한 글자 고쳐도 같다. 본문을 아무리 늘려도
+  프리픽스는 커지지 않는다 — **길이는 본문으로, 신호는 description 으로**.
+
+| 에이전트 |
+|---|
+| `agents/architect.md` |
+| `agents/build-error-resolver.md` |
+| `agents/code-reviewer.md` |
+| `agents/e2e-tester.md` |
+| `agents/implementer.md` |
+| `agents/security-reviewer.md` |
+| `agents/tester.md` |
+| `agents/event/event-ops.md` |
+| `agents/event/event-planner.md` |
+| `agents/ui/design-reviewer.md` |
+| `agents/ui/design-system-gen.md` |
+
+<!-- surface: skills -->
+## 표면 4 — 스킬 frontmatter `description` (집계)
+
+- **Model Experience**: 에이전트와 같다 — **본문은 호출될 때만** 로드되고, 상시 실리는 것은
+  `name` + `description` 이다. 따라서 스킬 본문의 길이는 라우팅 정확도에 기여하지 않는다.
+  라우팅은 description 이 한다.
+- **KV Cache effect**: 스킬 **개수**가 프리픽스 길이를 좌우한다. 스킬을 하나 추가하면 목록이
+  길어져 그 뒤가 무효화된다. 그래서 스택·capability 로 갈라 설치하는 것이다 — 아무 프로젝트에나
+  실릴 이유가 없는 스킬은 내려둔다 (`GLOBAL_SKILLS_*` / `STACK_TO_SKILLS` / `CAPABILITY_SKILLS`).
+- **개수 검증은 여기서 하지 않는다** — `npm run validate:counts` 가 이미 그 사실의 집이다.
+  같은 사실을 두 곳에서 세면 그 순간 두 벌이 된다.
+
+## 새 표면을 추가할 때
+
+1. 위 형식으로 절을 만든다 — `<!-- surface: {id} -->` 마커 + `Model Experience` + `KV Cache effect`.
+2. 자산을 나열한다면 표의 백틱 경로가 실물과 **정확히 일치**해야 한다. 게이트가 양방향으로 본다:
+   문서에 없는 실물도, 실물이 없는 문서 항목도 실패다.
+3. 집계로 충분하면 나열하지 않는다. 나열은 그 자체가 유지보수 비용이고, 다른 게이트가 이미
+   세고 있다면 여기서 또 세지 않는다.

package/vibe/templates/spec-template.md

@@ -1,7 +1,8 @@
 # SPEC: {Feature Name}
 
 - **Created**: {YYYY-MM-DD}
-- **Status**: DRAFT | APPROVED
+- **Status**: DRAFT | APPROVED | VERIFIED | SUPERSEDED | REJECTED (닫힌 집합 — `npm run validate:spec-lifecycle`)
+- **Class**: feature | bug-fix | simplification | architecture | process | testing
 - **Stakes**: demo | prototype | production — {판정 근거 1구} (SSOT: vibe/rules/loop-contract.md)
 - **Tech Stack**: {Project tech stack summary}
 
@@ -153,3 +154,17 @@ Response: 201 {...}
 - Verification writes `.vibe/runs/{run-id}/evidence.json`; only deterministic Judge results can complete the loop.
 - Model Judge findings are advisory-only. Human Taste is release-only.
 - Gate = all Done Criteria pass (exit codes / observed behavior) — loop continues until gates pass, stuck, or max iterations.
+
+---
+
+## Anchors
+
+> **Class 가 feature · bug-fix · architecture 이고 Status 를 VERIFIED 로 올릴 때 필수.**
+> 그 외에는 이 절을 통째로 지운다 — 고정할 코드 경로가 없는 SPEC 에 억지로 요구하면 통과 의식이 된다.
+
+이 SPEC 이 안착한 경로를 나열한다. 여기 적힌 경로가 사라지면 `npm run validate:spec-lifecycle`
+이 실패한다 — 그것이 "코드가 움직였는데 SPEC 이 따라오지 않았다" 를 잡는 유일한 신호다.
+lifecycle 표기만으로는 못 잡는다: 문서는 Status 를 바꾸지 않은 채 늙기 때문이다.
+
+- `{src/auth/session.ts}`
+- `{src/auth/session.test.ts}`