@su-record/vibe 2.7.8 → 2.7.9

package/skills/commerce-patterns/SKILL.md

@@ -1,361 +1,59 @@
----
-name: commerce-patterns
-description: "E-commerce domain patterns - cart, payment, inventory with transaction safety"
-triggers: [commerce, ecommerce, cart, payment, checkout, inventory, stock, order, pg, toss, stripe]
-priority: 70
----
-# Commerce Patterns Skill
-
-E-commerce domain patterns for reliable transactions.
-
-## When to Use
-
-- Shopping cart implementation
-- Payment integration (PG, Stripe, Toss)
-- Inventory/stock management
-- Order processing systems
-
-## Core Patterns
-
-### 1. Cart (Shopping Cart)
-
-#### 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);
-
-    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]);
-
-        await this.reservationRepository.update(reservation.id, {
-          status: 'RELEASED',
-        });
-      }
-    }
-  }
-}
-```
-
-#### 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]);
-
-// Option 2: Pessimistic Locking (for high contention)
-await db.query(`
-  SELECT * FROM products WHERE id = $1 FOR UPDATE
-`, [productId]);
-
-// Option 3: Redis Distributed Lock
-const lock = await redlock.lock(`stock:${productId}`, 5000);
-try {
-  // Update stock
-} finally {
-  await lock.unlock();
-}
-```
-
-## Order Flow (Complete)
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│  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               │
-│                                                             │
-└─────────────────────────────────────────────────────────────┘
-```
-
-## 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:
-
-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
+---
+name: commerce-patterns
+description: "E-commerce domain patterns - cart, payment, inventory with transaction safety"
+triggers: [commerce, ecommerce, cart, payment, checkout, inventory, stock, order, pg, toss, stripe]
+priority: 70
+---
+
+# Commerce Patterns
+
+## Pre-check (K1)
+
+> Is this an e-commerce transaction flow? If building simple CRUD without payment/stock management, this skill is not needed.
+
+## Gotchas & Traps
+
+These are the non-obvious failure modes LLMs typically miss:
+
+### Payment
+
+| 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) |
+
+### Inventory
+
+| 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 |
+
+### Cart & Pricing
+
+| 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) |
+
+## Checkout Flow (Reference)
+
+```
+Cart Validation → Order Creation (PENDING) → Stock Reservation (15min) → Payment
+  ├─ Success → Order PAID, Stock COMMIT, Send Confirmation
+  └─ Failure → Order FAILED, Stock RELEASE
+```
+
+## Done Criteria (K4)
+
+- [ ] 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

package/skills/commit-push-pr/SKILL.md

@@ -1,118 +1,75 @@
----
-name: commit-push-pr
-description: "Commit, push, and create PR in one go. Auto-activates on commit, PR, push keywords."
-triggers: [commit, push, PR, pull request, merge]
-priority: 70
----
-
-# Commit-Push-PR — From Commit to PR in One Step
-
-Commit current changes, push to the remote branch, and create a GitHub PR.
-
-## Pre-checks
-
-```bash
-# Check current state
-git status
-git diff --stat
-git log --oneline -5
-```
-
-## Workflow
-
-1. Review and stage changed files
-2. Write commit message (Conventional Commits format)
-3. Push to remote branch
-4. Create PR with `gh pr create`
-5. Write PR title/body
-
-## Commit Message Format
-
-```
-[type] title (under 50 chars)
-
-body (optional, 72 char line wrap)
-- What was changed
-- Why it was changed
-
-Co-Authored-By: Claude <noreply@anthropic.com>
-```
-
-### Type List
-
-| Type | Description |
-|------|-------------|
-| `feat` | New feature |
-| `fix` | Bug fix |
-| `docs` | Documentation changes |
-| `style` | Formatting (no code changes) |
-| `refactor` | Refactoring |
-| `test` | Add/modify tests |
-| `chore` | Build, config changes |
-| `perf` | Performance improvement |
-
-## Co-Authored-By Rule
-
-Always add for AI-generated/modified code:
-
-```
-Co-Authored-By: Claude <noreply@anthropic.com>
-```
-
-## Security File Check
-
-Always verify before committing:
-
-```bash
-# Detect sensitive files
-git diff --cached --name-only | grep -E '\.(env|pem|key)$|credentials|secret'
-```
-
-### Never Commit These Files
-
-| File Pattern | Reason |
-|-------------|--------|
-| `.env`, `.env.local` | Environment variables (contains secrets) |
-| `*.pem`, `*.key` | Certificates/keys |
-| `credentials.json` | Authentication info |
-| `service-account.json` | Service account |
-
-> If any of these files are staged, immediately warn and abort the commit.
-
-## Branch Protection Rules
-
-### main/master Branch Protection
-
-```bash
-# Check current branch
-git branch --show-current
-```
-
-- **No direct commits/pushes to main/master**
-- If on main/master: recommend creating a new branch and abort
-- **Never** `--force` push (main/master)
-
-## PR Creation Format
-
-```bash
-gh pr create \
-  --title "[type] title" \
-  --body "## Changes
-- Key changes
-
-## Related Issues
-- Closes #issue-number
-
-## Testing
-- Test methods and results"
-```
-
-## git-workflow Rule Integration
-
-This skill follows rules from `.claude/vibe/rules/standards/git-workflow.md`:
-
-- Conventional Commits format
-- PR checklist compliance
-- Prohibited actions (force push, .env commits, etc.)
-
-> **VIBE tool integration**: `/vibe.review`'s git-history agent automatically validates commit quality
+---
+name: commit-push-pr
+description: "Commit, push, and create PR in one go. Auto-activates on commit, PR, push keywords."
+triggers: [commit, push, PR, pull request, merge]
+priority: 70
+---
+
+# Commit-Push-PR
+
+## Pre-checks
+
+```bash
+git status            # What's changed
+git diff --stat       # Review changes
+git log --oneline -5  # Recent commits for style
+```
+
+## Workflow
+
+1. Review and stage changed files
+2. Write commit message (Conventional Commits)
+3. Push to remote branch
+4. Create PR with `gh pr create`
+
+## Commit Message Format
+
+```
+[type] title (under 50 chars)
+
+body (optional, 72 char wrap)
+
+Co-Authored-By: Claude <noreply@anthropic.com>
+```
+
+Types: `feat` | `fix` | `docs` | `style` | `refactor` | `test` | `chore` | `perf`
+
+## Security Checks (CRITICAL)
+
+```bash
+# Before committing — detect sensitive files
+git diff --cached --name-only | grep -E '\.(env|pem|key)$|credentials|secret'
+```
+
+**Never commit:** `.env`, `.env.local`, `*.pem`, `*.key`, `credentials.json`, `service-account.json`
+
+> If sensitive files are staged, **immediately warn and abort**.
+
+## Branch Protection
+
+- **No direct commits/pushes to main/master**
+- If on main: create a new branch first
+- **Never** `--force` push to main/master
+
+## PR Format
+
+```bash
+gh pr create \
+  --title "[type] title" \
+  --body "## Changes
+- Key changes
+
+## Related Issues
+- Closes #issue-number
+
+## Testing
+- Test methods and results"
+```
+
+## Done Criteria (K4)
+
+- [ ] No sensitive files in commit
+- [ ] Commit message follows Conventional Commits
+- [ ] Co-Authored-By line included
+- [ ] Not pushing directly to main/master
+- [ ] PR created with clear description