@su-record/vibe 2.7.6 → 2.7.9

package/hooks/gemini-hooks.json

@@ -0,0 +1,73 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "command": "VIBE_CLI=gemini node {{VIBE_PATH}}/hooks/scripts/session-start.js"
+      }
+    ],
+    "BeforeTool": [
+      {
+        "tool_name": "shell",
+        "command": "VIBE_CLI=gemini node {{VIBE_PATH}}/hooks/scripts/sentinel-guard.js Bash"
+      },
+      {
+        "tool_name": "shell",
+        "command": "VIBE_CLI=gemini node {{VIBE_PATH}}/hooks/scripts/pre-tool-guard.js Bash"
+      },
+      {
+        "tool_name": "edit",
+        "command": "VIBE_CLI=gemini node {{VIBE_PATH}}/hooks/scripts/sentinel-guard.js Edit"
+      },
+      {
+        "tool_name": "edit",
+        "command": "VIBE_CLI=gemini node {{VIBE_PATH}}/hooks/scripts/pre-tool-guard.js Edit"
+      },
+      {
+        "tool_name": "write_file",
+        "command": "VIBE_CLI=gemini node {{VIBE_PATH}}/hooks/scripts/sentinel-guard.js Write"
+      },
+      {
+        "tool_name": "write_file",
+        "command": "VIBE_CLI=gemini node {{VIBE_PATH}}/hooks/scripts/pre-tool-guard.js Write"
+      }
+    ],
+    "AfterTool": [
+      {
+        "tool_name": "edit",
+        "command": "VIBE_CLI=gemini node {{VIBE_PATH}}/hooks/scripts/code-check.js"
+      },
+      {
+        "tool_name": "write_file",
+        "command": "VIBE_CLI=gemini node {{VIBE_PATH}}/hooks/scripts/code-check.js"
+      },
+      {
+        "tool_name": "edit",
+        "command": "VIBE_CLI=gemini node {{VIBE_PATH}}/hooks/scripts/post-edit.js"
+      }
+    ],
+    "BeforeAgent": [
+      {
+        "command": "VIBE_CLI=gemini node {{VIBE_PATH}}/hooks/scripts/prompt-dispatcher.js"
+      }
+    ],
+    "Notification": [
+      {
+        "matcher": "context_window_80",
+        "command": "VIBE_CLI=gemini node {{VIBE_PATH}}/hooks/scripts/context-save.js medium"
+      },
+      {
+        "matcher": "context_window_90",
+        "command": "VIBE_CLI=gemini node {{VIBE_PATH}}/hooks/scripts/context-save.js high"
+      },
+      {
+        "matcher": "context_window_95",
+        "command": "VIBE_CLI=gemini node {{VIBE_PATH}}/hooks/scripts/context-save.js critical"
+      }
+    ],
+    "SessionEnd": [
+      {
+        "command": "VIBE_CLI=gemini node {{VIBE_PATH}}/hooks/scripts/stop-notify.js"
+      }
+    ]
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@su-record/vibe",
-  "version": "2.7.6",
+  "version": "2.7.9",
   "description": "AI Coding Framework for Claude Code — 49 agents, 41+ tools, multi-LLM orchestration",
   "type": "module",
   "main": "dist/cli/index.js",

package/skills/agents-md/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: agents-md
+description: "Optimize AGENTS.md / CLAUDE.md by removing discoverable info and keeping only gotchas. Based on Addy Osmani's AGENTS.md principles. Activates on agents.md, claude.md, context file optimization."
+triggers: [agents.md, claude.md, context file, optimize agents, optimize claude]
+priority: 50
+---
+
+# agents-md — Context File Optimizer
+
+AGENTS.md / CLAUDE.md를 최적화한다.
+근거: https://addyosmani.com/blog/agents-md/
+
+## 핵심 원칙
+
+**한 줄 테스트**: "에이전트가 코드를 읽어서 스스로 알 수 있는가?" → Yes면 삭제.
+
+## Step 1: 대상 파일 찾기
+
+프로젝트 루트에서 다음 파일을 탐색한다:
+
+```
+Glob: pattern="AGENTS.md"
+Glob: pattern="CLAUDE.md"
+Glob: pattern=".cursorrules"
+Glob: pattern=".github/copilot-instructions.md"
+Glob: pattern=".windsurfrules"
+```
+
+대상 파일이 없으면 새로 생성할지 사용자에게 확인한다.
+
+## Step 2: 현재 내용 분류
+
+파일의 각 항목을 다음 기준으로 분류한다:
+
+### 삭제 (Discoverable)
+
+에이전트가 코드 탐색으로 발견 가능한 정보:
+
+| 유형 | 예시 | 발견 경로 |
+|------|------|----------|
+| 디렉토리 구조 | "src/에 컴포넌트가 있다" | `ls`, `Glob` |
+| 기술 스택 | "React + TypeScript 사용" | `package.json`, 파일 확장자 |
+| Phase/진행 테이블 | "Phase 1 ✅, Phase 2 ✅..." | 이력일 뿐, 행동 지침 아님 |
+| 빌드/테스트 커맨드 | "npm test로 테스트 실행" | `package.json` scripts |
+| API 엔드포인트 목록 | "POST /api/users" | 라우터 코드 |
+| 기능별 상세 설명 | "Phase 3에서 서킷브레이커 구현" | 해당 코드 읽으면 파악 가능 |
+| 아키텍처 다이어그램 | ASCII 박스 다이어그램 | 개념적 설명, 실수 방지 효과 없음 |
+
+### 유지 (Non-discoverable)
+
+에이전트가 코드만으로 알 수 없는 함정과 규칙:
+
+| 유형 | 예시 |
+|------|------|
+| 런타임 함정 | "Bun이다, Node가 아니다" (package.json에 명시 안 됨) |
+| 금지 패턴 | "require() 쓰지 말 것", "React 패턴 금지" |
+| SSOT 위치 | "model-registry.ts만 수정할 것, 하드코딩 금지" |
+| 불변 순서/규칙 | "우선순위: A → B → C, 이 순서 변경 금지" |
+| 재시도/폴백 제한 | "최대 2회, 3회 이상 금지" |
+| 도구 선택 | "Zod만 사용, joi/yup 금지" |
+| 네이밍 컨벤션 | 비표준 패턴 (표준이면 삭제) |
+| 프로젝트 한 줄 소개 | 코드만으로 목적 파악 어려운 경우 |
+| 언어/응답 지시 | "한글로 답변" 같은 선호 |
+
+### 앵커링 주의
+
+기술 이름을 언급하면 에이전트가 해당 기술로 편향된다. "무엇을 쓰지 말라"는 유용하지만, "우리는 X를 쓴다"는 코드에서 이미 보인다면 불필요.
+
+## Step 3: 재구성
+
+다음 구조로 재작성한다:
+
+```markdown
+# {프로젝트명} — {한 줄 소개}
+
+{프로젝트가 무엇을 하는지 1-2문장. 코드만으로 목적 파악이 어려운 경우에만.}
+
+# Gotchas
+
+- **{함정 제목}.** {구체적 금지/규칙 설명}.
+- ...
+
+# Naming
+
+{비표준 네이밍 패턴이 있을 때만. 표준(camelCase 등)이면 생략.}
+```
+
+규칙:
+- 섹션은 최대 3개 (소개, Gotchas, Naming)
+- Gotchas 항목은 각각 **볼드 제목 + 구체적 do/don't**
+- "~를 사용한다" 보다 "~를 쓰지 말 것"이 더 유용
+- 전체 50줄 이내 목표
+
+## Step 4: CLAUDE.md 분리 (해당 시)
+
+CLAUDE.md가 존재하면 Claude 전용 지시만 남긴다:
+
+```markdown
+{Claude 전용 지시. 예: "답변은 반드시 한글로 답변할 것."}
+```
+
+공통 규칙은 AGENTS.md에 둔다. Claude Code는 둘 다 읽는다.
+
+## Step 5: 결과 보고
+
+```markdown
+## AGENTS.md 최적화 결과
+
+| 지표 | Before | After |
+|------|--------|-------|
+| 줄 수 | N | N |
+| 삭제 항목 | - | N개 (discoverable) |
+| 유지 항목 | - | N개 (gotchas) |
+
+### 삭제된 항목
+- {항목}: {삭제 이유}
+
+### 유지/추가된 항목
+- {항목}: {유지 이유}
+```

package/skills/brand-assets/SKILL.md

@@ -136,3 +136,11 @@ public/
   android-chrome-512x512.png
   site.webmanifest
 ```
+
+## Done Criteria (K4)
+
+- [ ] All required sizes generated (16x16 through 512x512)
+- [ ] Icons work at small sizes (recognizable at 16x16)
+- [ ] No text/letters in icon (illegible at small sizes)
+- [ ] `site.webmanifest` updated with icon paths
+- [ ] Fallback generated if Gemini API unavailable

package/skills/characterization-test/SKILL.md

@@ -11,6 +11,10 @@ priority: 65
 
 Lock existing behavior with snapshot/characterization tests before modifying code. This prevents regressions in legacy, complex, or unfamiliar codebases.
 
+## Pre-check (K1)
+
+> Are you modifying existing code with uncertain behavior? If the code is new (you just wrote it), well-tested, or trivially simple, skip characterization tests and write regular unit tests instead.
+
 ## When to Use
 
 | Scenario | Signal |

package/skills/commerce-patterns/SKILL.md

@@ -4,358 +4,56 @@ description: "E-commerce domain patterns - cart, payment, inventory with transac
 triggers: [commerce, ecommerce, cart, payment, checkout, inventory, stock, order, pg, toss, stripe]
 priority: 70
 ---
-# Commerce Patterns Skill
 
-E-commerce domain patterns for reliable transactions.
+# Commerce Patterns
 
-## When to Use
+## Pre-check (K1)
 
-- Shopping cart implementation
-- Payment integration (PG, Stripe, Toss)
-- Inventory/stock management
-- Order processing systems
+> Is this an e-commerce transaction flow? If building simple CRUD without payment/stock management, this skill is not needed.
 
-## Core Patterns
+## Gotchas & Traps
 
-### 1. Cart (Shopping Cart)
+These are the non-obvious failure modes LLMs typically miss:
 
-#### State Model
-```typescript
-interface CartItem {
-  productId: string;
-  variantId?: string;
-  quantity: number;
-  price: number;           // Snapshot at add time
-  originalPrice: number;   // For comparison
-  addedAt: Date;
-}
-
-interface Cart {
-  id: string;
-  userId?: string;         // null for guest
-  sessionId: string;       // For guest merge
-  items: CartItem[];
-  couponCode?: string;
-  updatedAt: Date;
-  expiresAt: Date;         // Cart expiration
-}
-```
-
-#### Key Patterns
-
-| Pattern | Description |
-|---------|-------------|
-| **Guest → User Merge** | Merge localStorage cart on login |
-| **Price Snapshot** | Store price at add time, revalidate at checkout |
-| **Expiration** | Clear abandoned carts after N days |
-| **Validation** | Check stock/price at checkout entry |
-
-#### Implementation
-```typescript
-class CartService {
-  async addItem(cartId: string, item: AddItemRequest): Promise<Cart> {
-    // 1. Validate product exists and in stock
-    const product = await this.productService.get(item.productId);
-    if (!product || product.stock < item.quantity) {
-      throw new OutOfStockError();
-    }
-
-    // 2. Snapshot current price
-    const cartItem: CartItem = {
-      ...item,
-      price: product.currentPrice,
-      originalPrice: product.originalPrice,
-      addedAt: new Date(),
-    };
-
-    // 3. Add or update quantity
-    return this.cartRepository.upsertItem(cartId, cartItem);
-  }
-
-  async mergeGuestCart(userId: string, sessionId: string): Promise<Cart> {
-    const guestCart = await this.cartRepository.findBySession(sessionId);
-    const userCart = await this.cartRepository.findByUser(userId);
-
-    if (!guestCart) return userCart;
-
-    // Merge: user cart takes priority for duplicates
-    const merged = this.mergeItems(userCart.items, guestCart.items);
-    await this.cartRepository.delete(guestCart.id);
-
-    return this.cartRepository.update(userCart.id, { items: merged });
-  }
-}
-```
-
-### 2. Payment
-
-#### State Machine
-```
-PENDING → PROCESSING → AUTHORIZED → CAPTURED → COMPLETED
-                    ↘ FAILED
-                    ↘ CANCELED
-COMPLETED → REFUND_REQUESTED → REFUNDED (partial/full)
-```
-
-#### Idempotency Pattern (Critical)
-```typescript
-interface PaymentRequest {
-  orderId: string;
-  amount: number;
-  currency: string;
-  idempotencyKey: string;  // REQUIRED: `order_${orderId}_${timestamp}`
-  paymentMethod: PaymentMethod;
-}
-
-class PaymentService {
-  async processPayment(request: PaymentRequest): Promise<PaymentResult> {
-    // 1. Check idempotency - prevent duplicate charges
-    const existing = await this.paymentRepository.findByIdempotencyKey(
-      request.idempotencyKey
-    );
-    if (existing) {
-      return existing.result;  // Return cached result
-    }
-
-    // 2. Create payment record (PENDING)
-    const payment = await this.paymentRepository.create({
-      ...request,
-      status: 'PENDING',
-    });
-
-    try {
-      // 3. Call PG adapter
-      const pgResult = await this.pgAdapter.authorize(request);
-
-      // 4. Update status
-      return this.paymentRepository.update(payment.id, {
-        status: pgResult.success ? 'AUTHORIZED' : 'FAILED',
-        pgTransactionId: pgResult.transactionId,
-        result: pgResult,
-      });
-    } catch (error) {
-      await this.paymentRepository.update(payment.id, {
-        status: 'FAILED',
-        error: error.message,
-      });
-      throw error;
-    }
-  }
-}
-```
-
-#### PG Adapter Pattern
-```typescript
-interface PGAdapter {
-  authorize(request: PaymentRequest): Promise<PGResult>;
-  capture(transactionId: string): Promise<PGResult>;
-  cancel(transactionId: string): Promise<PGResult>;
-  refund(transactionId: string, amount?: number): Promise<PGResult>;
-}
-
-// Implementations
-class TossPaymentsAdapter implements PGAdapter { /* ... */ }
-class StripeAdapter implements PGAdapter { /* ... */ }
-class PortOneAdapter implements PGAdapter { /* ... */ }
-```
-
-#### Webhook Handling
-```typescript
-class PaymentWebhookHandler {
-  async handle(event: WebhookEvent): Promise<void> {
-    // 1. Verify signature
-    if (!this.verifySignature(event)) {
-      throw new UnauthorizedError();
-    }
-
-    // 2. Idempotency check - process each event only once
-    const processed = await this.eventStore.find(event.id);
-    if (processed) {
-      return;  // Already processed
-    }
-
-    // 3. Process event
-    await this.processEvent(event);
-
-    // 4. Mark as processed
-    await this.eventStore.save({
-      eventId: event.id,
-      processedAt: new Date(),
-    });
-  }
-}
-```
-
-### 3. Inventory (Stock Management)
-
-#### Reservation Pattern (Two-Phase)
-```typescript
-interface StockReservation {
-  id: string;
-  productId: string;
-  quantity: number;
-  orderId: string;
-  status: 'RESERVED' | 'COMMITTED' | 'RELEASED';
-  expiresAt: Date;         // Auto-release if not committed
-  createdAt: Date;
-}
-
-class InventoryService {
-  // Phase 1: Reserve stock (at checkout start)
-  async reserve(orderId: string, items: OrderItem[]): Promise<void> {
-    for (const item of items) {
-      // Atomic decrement with check
-      const result = await this.db.query(`
-        UPDATE products
-        SET reserved_stock = reserved_stock + $1
-        WHERE id = $2
-          AND (available_stock - reserved_stock) >= $1
-        RETURNING *
-      `, [item.quantity, item.productId]);
-
-      if (result.rowCount === 0) {
-        // Rollback previous reservations
-        await this.releaseAll(orderId);
-        throw new InsufficientStockError(item.productId);
-      }
-
-      await this.reservationRepository.create({
-        orderId,
-        productId: item.productId,
-        quantity: item.quantity,
-        status: 'RESERVED',
-        expiresAt: addMinutes(new Date(), 15),  // 15min hold
-      });
-    }
-  }
-
-  // Phase 2: Commit stock (after payment success)
-  async commit(orderId: string): Promise<void> {
-    const reservations = await this.reservationRepository.findByOrder(orderId);
-
-    for (const reservation of reservations) {
-      await this.db.query(`
-        UPDATE products
-        SET
-          available_stock = available_stock - $1,
-          reserved_stock = reserved_stock - $1
-        WHERE id = $2
-      `, [reservation.quantity, reservation.productId]);
-
-      await this.reservationRepository.update(reservation.id, {
-        status: 'COMMITTED',
-      });
-    }
-  }
-
-  // Rollback: Release stock (payment failed or timeout)
-  async release(orderId: string): Promise<void> {
-    const reservations = await this.reservationRepository.findByOrder(orderId);
+### Payment
 
-    for (const reservation of reservations) {
-      if (reservation.status === 'RESERVED') {
-        await this.db.query(`
-          UPDATE products
-          SET reserved_stock = reserved_stock - $1
-          WHERE id = $2
-        `, [reservation.quantity, reservation.productId]);
+| Trap | Consequence | Prevention |
+|------|-------------|------------|
+| No idempotency key | User double-clicks → charged twice | `idempotencyKey: order_${orderId}_${timestamp}` on every payment request |
+| Webhook not idempotent | Retry delivers duplicate events | Check `eventId` before processing, store processed events |
+| Missing webhook signature verification | Attacker forges payment confirmation | Always verify HMAC signature before processing |
+| No payment state machine | Order stuck in limbo | `PENDING → PROCESSING → AUTHORIZED → CAPTURED → COMPLETED` (+ FAILED, CANCELED, REFUNDED) |
 
-        await this.reservationRepository.update(reservation.id, {
-          status: 'RELEASED',
-        });
-      }
-    }
-  }
-}
-```
+### Inventory
 
-#### Concurrency Control
-```typescript
-// Option 1: Optimistic Locking
-await db.query(`
-  UPDATE products
-  SET stock = stock - $1, version = version + 1
-  WHERE id = $2 AND version = $3 AND stock >= $1
-`, [quantity, productId, expectedVersion]);
+| Trap | Consequence | Prevention |
+|------|-------------|------------|
+| Non-atomic stock decrement | Race condition → negative stock | `UPDATE SET stock = stock - $1 WHERE stock >= $1` (atomic with check) |
+| No reservation TTL | Stock locked forever on abandoned checkout | 15-min reservation + scheduled cleanup job |
+| Commit without reservation | Stock sold twice | Two-phase: RESERVE (checkout start) → COMMIT (payment success) / RELEASE (failure) |
+| Optimistic lock without retry | Fails silently under contention | Use `version` column or `FOR UPDATE` for high-contention products |
 
-// Option 2: Pessimistic Locking (for high contention)
-await db.query(`
-  SELECT * FROM products WHERE id = $1 FOR UPDATE
-`, [productId]);
+### Cart & Pricing
 
-// Option 3: Redis Distributed Lock
-const lock = await redlock.lock(`stock:${productId}`, 5000);
-try {
-  // Update stock
-} finally {
-  await lock.unlock();
-}
-```
+| Trap | Consequence | Prevention |
+|------|-------------|------------|
+| No price snapshot | Price changes between add and checkout | Store `price` at add time, revalidate at checkout entry |
+| No guest→user cart merge | Guest loses cart on login | Merge by `sessionId` on login, user cart takes priority for duplicates |
+| No cart expiration | Abandoned carts accumulate forever | TTL-based cleanup (e.g., 7 days) |
 
-## Order Flow (Complete)
+## Checkout Flow (Reference)
 
 ```
-┌─────────────────────────────────────────────────────────────┐
-│  CHECKOUT FLOW                                              │
-├─────────────────────────────────────────────────────────────┤
-│                                                             │
-│  1. Cart Validation                                         │
-│     └─ Revalidate prices, check stock availability          │
-│                                                             │
-│  2. Order Creation (PENDING)                                │
-│     └─ Generate orderId, snapshot cart                      │
-│                                                             │
-│  3. Stock Reservation                                       │
-│     └─ Reserve inventory (15min hold)                       │
-│                                                             │
-│  4. Payment Processing                                      │
-│     ├─ Success → Order PAID, Stock COMMIT                   │
-│     └─ Failure → Order FAILED, Stock RELEASE                │
-│                                                             │
-│  5. Order Confirmation                                      │
-│     └─ Send notification, trigger fulfillment               │
-│                                                             │
-└─────────────────────────────────────────────────────────────┘
+Cart Validation → Order Creation (PENDING) → Stock Reservation (15min) → Payment
+  ├─ Success → Order PAID, Stock COMMIT, Send Confirmation
+  └─ Failure → Order FAILED, Stock RELEASE
 ```
 
-## Common Bugs & Prevention
-
-| Bug | Cause | Prevention |
-|-----|-------|------------|
-| **Duplicate payment** | User double-click, webhook retry | Idempotency key |
-| **Negative stock** | Race condition | Atomic update with check |
-| **Price mismatch** | Price changed during checkout | Snapshot + revalidation |
-| **Orphan reservation** | Payment timeout without release | TTL + scheduled cleanup |
-| **Lost webhook** | Network failure | Retry + idempotent handler |
-| **Order state corruption** | Concurrent updates | State machine + versioning |
-
-## Integration with /vibe.run
-
-During commerce feature implementation:
+## Done Criteria (K4)
 
-1. **Phase 1**: Define domain models (Cart, Order, Payment, Inventory)
-2. **Phase 2**: Implement core services with patterns above
-3. **Phase 3**: Add PG adapter and webhook handlers
-4. **Phase 4**: Implement compensating transactions (Saga)
-5. **Phase 5**: E2E test critical flows
-
-## Checklist
-
-### Cart
-- [ ] Guest/user cart merge on login
-- [ ] Price snapshot at add time
-- [ ] Stock validation at checkout
-- [ ] Cart expiration cleanup
-
-### Payment
-- [ ] Idempotency key on all requests
-- [ ] Webhook signature verification
-- [ ] Duplicate event handling
-- [ ] Timeout/retry strategy
-- [ ] Refund flow tested
-
-### Inventory
-- [ ] Two-phase reservation (reserve → commit/release)
-- [ ] Atomic stock updates
-- [ ] Reservation TTL and cleanup job
-- [ ] Concurrency control tested
+- [ ] Idempotency key on all payment requests
+- [ ] Webhook handler is idempotent (dedup by eventId)
+- [ ] Stock updates are atomic (SQL-level check)
+- [ ] Two-phase reservation implemented with TTL
+- [ ] Prices snapshot at cart add, revalidated at checkout
+- [ ] Payment state machine covers all transitions