@su-record/vibe 2.8.23 → 2.8.25

package/skills/arch-guard/agents/violation-checker.md

@@ -0,0 +1,51 @@
+---
+name: arch-violation-checker
+role: Scans all import statements across the codebase and flags boundary violations against the rule set
+tools: [Glob, Grep, Read]
+---
+
+# Arch Violation Checker
+
+## Role
+Performs the mechanical import-graph scan against the generated rule set. For every file in a `from` layer, it extracts all import paths and checks whether any resolve into a `cannotImport` layer. Reports each violation with full context.
+
+## Responsibilities
+- Enumerate all files matching each rule's `from` glob pattern
+- Extract import and require statements from each file
+- Resolve relative imports to their canonical layer classification
+- Check resolved imports against the `cannotImport` glob patterns
+- Collect violations with file path, line number, importing path, and violated rule
+
+## Input
+Normalized rule set JSON from `arch-rule-generator` and project root path.
+
+## Output
+Violation list JSON:
+```json
+{
+  "violations": [
+    {
+      "rule": "domain-no-infra",
+      "file": "src/domain/user.ts",
+      "line": 3,
+      "import": "../infra/db/userRepository",
+      "resolved": "src/infra/db/userRepository.ts",
+      "severity": "error"
+    }
+  ],
+  "scannedFiles": 142,
+  "cleanFiles": 139
+}
+```
+
+## Communication
+- Reports violation list to: `arch-reporter`
+- Receives instructions from: arch-guard orchestrator (SKILL.md)
+
+## Domain Knowledge
+Import resolution rules:
+- Relative imports (`./`, `../`) must be resolved relative to the importing file's location
+- Path aliases (`@/`, `~/`) must be resolved using the project's `tsconfig.json` `paths` config
+- External package imports (no leading `.` or `/`) are always allowed — skip them
+- Re-export barrel files (`index.ts`) count as the directory they represent
+- Type-only imports (`import type`) still count as dependencies for boundary purposes

package/skills/arch-guard/frameworks/clean-architecture.md

@@ -0,0 +1,108 @@
+---
+name: clean-architecture
+type: framework
+applies-to: [arch-guard]
+---
+
+# Clean Architecture — Reference Card
+
+## Layer Model
+
+```
+┌─────────────────────────────────┐
+│  Frameworks & Drivers           │  ← UI, DB, HTTP, CLI, external APIs
+├─────────────────────────────────┤
+│  Interface Adapters             │  ← Controllers, Presenters, Gateways
+├─────────────────────────────────┤
+│  Application Use Cases          │  ← Business rules orchestration
+├─────────────────────────────────┤
+│  Entities (Domain)              │  ← Core business objects & rules
+└─────────────────────────────────┘
+```
+
+**Dependency Rule**: Dependencies point inward only. Inner layers know nothing about outer layers.
+
+## Layer Responsibilities
+
+| Layer | Contains | Must NOT contain |
+|-------|----------|-----------------|
+| Entities | Domain models, value objects, domain rules | Framework imports, DB calls |
+| Use Cases | Application workflows, business logic | HTTP, DB drivers, UI logic |
+| Adapters | Controllers, mappers, repository impls | Business rules, domain logic |
+| Frameworks | Express routes, Prisma, React, CLI | Business or application logic |
+
+## Dependency Rule in Code
+
+```ts
+// Good — Use Case depends on abstraction (repository interface)
+// src/use-cases/CreateUser.ts
+interface UserRepository { save(user: User): Promise<void> }
+
+export class CreateUserUseCase {
+  constructor(private users: UserRepository) {}
+  execute(data: CreateUserInput): Promise<User> { /* business logic only */ }
+}
+
+// Good — Adapter implements the interface
+// src/adapters/PrismaUserRepository.ts
+import { PrismaClient } from '@prisma/client'; // framework import OK here
+class PrismaUserRepository implements UserRepository {
+  save(user: User): Promise<void> { /* prisma call */ }
+}
+
+// Bad — Use Case imports Prisma directly (crosses boundary)
+// src/use-cases/CreateUser.ts
+import { PrismaClient } from '@prisma/client'; // VIOLATION
+```
+
+## Boundary Crossing Patterns
+
+### Data Transfer Objects (DTOs)
+Cross boundaries using plain data structures, not domain entities.
+
+```ts
+// Input DTO — from outer layer into use case
+type CreateUserInput = { email: string; name: string }
+
+// Output DTO — from use case out to adapter
+type CreateUserOutput = { id: string; email: string; createdAt: Date }
+```
+
+### Repository Pattern
+Isolates data access behind an interface defined in the domain layer.
+
+```ts
+// Defined in domain layer
+interface UserRepository {
+  findById(id: string): Promise<User | null>
+  save(user: User): Promise<void>
+  delete(id: string): Promise<void>
+}
+```
+
+## Common Violations
+
+| Violation | Example | Fix |
+|-----------|---------|-----|
+| Framework import in entity | `import express from 'express'` in `User.ts` | Move to adapter layer |
+| DB call in use case | `prisma.user.findMany()` in use case | Use repository interface |
+| Business logic in controller | `if (price > 100) applyDiscount()` in route handler | Move to use case |
+| Entity exposed via HTTP | Return `User` domain object as JSON directly | Map to response DTO |
+| Use case depends on use case | `CreateOrder` imports `CreateUser` | Extract shared logic to domain service |
+
+## Directory Structure Convention
+
+```
+src/
+  domain/          ← Entities, value objects, domain interfaces
+  use-cases/       ← Application business rules
+  adapters/        ← Controllers, repository implementations, mappers
+  infrastructure/  ← DB, HTTP, external services (framework layer)
+```
+
+## Arch-Guard Checks
+
+- No `import` crossing inward (outer → inner only)
+- No framework imports (`express`, `prisma`, `mongoose`) in `domain/` or `use-cases/`
+- No `fetch`/`axios` in entities or use cases
+- All use case dependencies are interfaces, not concrete classes

package/skills/arch-guard/frameworks/solid.md

@@ -0,0 +1,102 @@
+---
+name: solid-principles
+type: framework
+applies-to: [arch-guard]
+---
+
+# SOLID Principles — Reference Card
+
+## S — Single Responsibility Principle
+> A class/module should have only one reason to change.
+
+**Violation signal**: A function does fetching + parsing + formatting + writing.
+
+```ts
+// Bad — UserService handles auth AND email AND db writes
+class UserService {
+  login(email: string, password: string): void { /* auth logic */ }
+  sendWelcomeEmail(user: User): void { /* email logic */ }
+  saveToDb(user: User): void { /* db logic */ }
+}
+
+// Good — each class owns one concern
+class AuthService { login(email: string, password: string): void {} }
+class EmailService { sendWelcome(user: User): void {} }
+class UserRepository { save(user: User): void {} }
+```
+
+## O — Open/Closed Principle
+> Open for extension, closed for modification.
+
+**Violation signal**: Adding a new type requires editing existing switch/if chains.
+
+```ts
+// Bad — adding payment type requires editing processPayment
+function processPayment(type: string, amount: number): void {
+  if (type === 'card') { /* ... */ }
+  if (type === 'paypal') { /* ... */ }
+}
+
+// Good — extend via new class, no existing code changes
+interface PaymentProcessor { process(amount: number): void }
+class CardProcessor implements PaymentProcessor { process(amount: number): void {} }
+class PayPalProcessor implements PaymentProcessor { process(amount: number): void {} }
+```
+
+## L — Liskov Substitution Principle
+> Subtypes must be substitutable for their base types.
+
+**Violation signal**: Overriding a method to throw `NotImplementedError` or changing preconditions.
+
+```ts
+// Bad — Square breaks Rectangle's invariant (width/height independence)
+class Rectangle { setWidth(w: number): void {} setHeight(h: number): void {} }
+class Square extends Rectangle {
+  setWidth(w: number): void { this.width = w; this.height = w; } // breaks contract
+}
+
+// Good — separate types, shared interface
+interface Shape { area(): number }
+class Rectangle implements Shape { area(): number { return this.w * this.h; } }
+class Square implements Shape { area(): number { return this.side ** 2; } }
+```
+
+## I — Interface Segregation Principle
+> Clients should not depend on interfaces they do not use.
+
+**Violation signal**: Implementing an interface and leaving methods as `() => { throw new Error() }`.
+
+```ts
+// Bad — Printer forced to implement fax() it doesn't support
+interface Machine { print(): void; scan(): void; fax(): void; }
+
+// Good — split into focused interfaces
+interface Printer { print(): void }
+interface Scanner { scan(): void }
+interface FaxMachine { fax(): void }
+```
+
+## D — Dependency Inversion Principle
+> Depend on abstractions, not concretions.
+
+**Violation signal**: High-level module imports a specific low-level class directly.
+
+```ts
+// Bad — OrderService tightly coupled to MySQLDatabase
+import { MySQLDatabase } from './MySQLDatabase';
+class OrderService { db = new MySQLDatabase(); }
+
+// Good — depend on interface, inject implementation
+interface Database { query(sql: string): unknown[] }
+class OrderService { constructor(private db: Database) {} }
+```
+
+## Quick Checklist
+
+| Principle | Red Flag |
+|-----------|----------|
+| SRP | Function/class name contains "And" or "Manager" |
+| OCP | Adding feature requires editing existing if/switch |
+| LSP | Subclass throws `NotImplemented` or removes behavior |
+| ISP | Interface has methods unused by most implementors |
+| DIP | `new ConcreteClass()` inside a high-level module |

package/skills/arch-guard/scripts/check-boundaries.js

@@ -0,0 +1,90 @@
+#!/usr/bin/env node
+/**
+ * arch-guard/scripts/check-boundaries.js
+ * Read arch-rules.json and scan imports for violations.
+ * Usage: node check-boundaries.js [arch-rules.json] [src-dir]
+ * Output: JSON array of violations to stdout.
+ */
+
+import fs from 'fs';
+import path from 'path';
+
+const IMPORT_RE = /(?:import|from|require)\s*\(?['"]([^'"]+)['"]\)?/g;
+const CODE_EXTS = new Set(['.ts', '.tsx', '.js', '.jsx']);
+
+/** @returns {string[]} */
+function collectFiles(dir) {
+  if (!fs.existsSync(dir)) return [];
+  const results = [];
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    if (entry.name.startsWith('.') || entry.name === 'node_modules' || entry.name === 'dist') continue;
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) results.push(...collectFiles(full));
+    else if (CODE_EXTS.has(path.extname(entry.name))) results.push(full);
+  }
+  return results;
+}
+
+/** @param {string} pattern @param {string} filePath @returns {boolean} */
+function matchesGlob(pattern, filePath) {
+  const normalized = filePath.replace(/\\/g, '/');
+  const regexStr = pattern
+    .replace(/\\/g, '/')
+    .replace(/\./g, '\\.')
+    .replace(/\*\*/g, '__DOUBLE__')
+    .replace(/\*/g, '[^/]+')
+    .replace(/__DOUBLE__/g, '.+');
+  return new RegExp(`^${regexStr}$`).test(normalized);
+}
+
+/** @param {string} file @returns {string[]} */
+function extractImports(file) {
+  const content = fs.readFileSync(file, 'utf-8');
+  const imports = [];
+  let m;
+  IMPORT_RE.lastIndex = 0;
+  while ((m = IMPORT_RE.exec(content)) !== null) imports.push(m[1]);
+  return imports;
+}
+
+/** @param {string} fromFile @param {string} imp @param {string} baseDir @returns {string} */
+function resolveImport(fromFile, imp, baseDir) {
+  if (!imp.startsWith('.')) return imp;
+  return path.resolve(path.dirname(fromFile), imp).replace(baseDir + path.sep, '').replace(/\\/g, '/');
+}
+
+const rulesPath = process.argv[2] || '.claude/vibe/arch-rules.json';
+const srcDir = path.resolve(process.argv[3] || 'src');
+const baseDir = path.resolve('.');
+
+if (!fs.existsSync(rulesPath)) {
+  process.stderr.write(`arch-rules.json not found: ${rulesPath}\n`);
+  process.exit(1);
+}
+
+const { rules } = JSON.parse(fs.readFileSync(rulesPath, 'utf-8'));
+const files = collectFiles(srcDir);
+const violations = [];
+
+for (const rule of rules) {
+  const fromFiles = files.filter(f => matchesGlob(rule.from, f.replace(baseDir + path.sep, '').replace(/\\/g, '/')));
+  for (const file of fromFiles) {
+    const imports = extractImports(file);
+    for (const imp of imports) {
+      const resolved = resolveImport(file, imp, baseDir);
+      const forbidden = (rule.cannotImport || []).some(pat => matchesGlob(pat, resolved) || resolved.includes(pat.replace('/**', '').replace('**/', '')));
+      if (forbidden) {
+        violations.push({
+          rule: rule.name,
+          file: file.replace(baseDir + path.sep, '').replace(/\\/g, '/'),
+          import: imp,
+          resolved,
+          reason: rule.reason || `Violates rule: ${rule.name}`,
+        });
+      }
+    }
+  }
+}
+
+process.stdout.write(JSON.stringify(violations, null, 2) + '\n');
+if (violations.length > 0) process.exit(1);

package/skills/arch-guard/templates/arch-rules.json

@@ -0,0 +1,47 @@
+{
+  "_comment": "Architecture boundary rules for arch-guard. Copy to .claude/vibe/arch-rules.json and customize.",
+  "rules": [
+    {
+      "name": "services-no-ui",
+      "from": "src/services/**",
+      "cannotImport": ["src/components/**", "src/pages/**", "src/app/**"],
+      "canImport": ["src/models/**", "src/utils/**", "src/types/**"],
+      "reason": "Services must be UI-agnostic for testability and reuse"
+    },
+    {
+      "name": "domain-no-infra",
+      "from": "src/domain/**",
+      "cannotImport": ["src/infra/**", "src/db/**", "src/adapters/**"],
+      "canImport": ["src/domain/**", "src/types/**"],
+      "reason": "Domain layer must not depend on infrastructure (Clean Architecture)"
+    },
+    {
+      "name": "components-no-pages",
+      "from": "src/components/**",
+      "cannotImport": ["src/pages/**", "src/app/**"],
+      "canImport": ["src/components/**", "src/hooks/**", "src/utils/**", "src/types/**"],
+      "reason": "Shared components must not import from page-level modules"
+    },
+    {
+      "name": "lib-no-components",
+      "from": "src/lib/**",
+      "cannotImport": ["src/components/**", "src/pages/**"],
+      "canImport": ["src/lib/**", "src/types/**"],
+      "reason": "Library utilities must be framework-agnostic"
+    },
+    {
+      "name": "models-no-controllers",
+      "from": "src/models/**",
+      "cannotImport": ["src/controllers/**", "src/handlers/**", "src/routes/**"],
+      "canImport": ["src/models/**", "src/types/**"],
+      "reason": "Models must not depend on request/response layer (MVC)"
+    },
+    {
+      "name": "no-direct-db-in-handlers",
+      "from": "src/handlers/**",
+      "cannotImport": ["src/db/**", "src/repositories/**"],
+      "canImport": ["src/services/**", "src/types/**"],
+      "reason": "Handlers must use services, not access the database directly"
+    }
+  ]
+}

package/skills/arch-guard/templates/violation-report.md

@@ -0,0 +1,53 @@
+# Architecture Violation Report
+
+**Project**: {{PROJECT_NAME}}
+**Date**: {{DATE}}
+**Rules File**: {{RULES_FILE}}
+**Total Violations**: {{VIOLATION_COUNT}}
+
+---
+
+## Summary
+
+| Rule | Violations |
+|------|-----------|
+{{RULE_SUMMARY_TABLE}}
+
+---
+
+## Violations by Rule
+
+{{VIOLATIONS_BY_RULE}}
+
+<!-- Example entry:
+### services-no-ui (3 violations)
+
+**Rule**: Services must be UI-agnostic for testability and reuse
+
+| File | Forbidden Import |
+|------|-----------------|
+| src/services/auth.ts | src/components/Button.tsx |
+| src/services/user.ts | src/pages/dashboard/index.ts |
+-->
+
+---
+
+## How to Fix
+
+For each violation, choose one:
+
+1. **Move the dependency** — relocate shared logic to a layer both sides can import
+2. **Invert the dependency** — use an interface/callback instead of a direct import
+3. **Promote the import** — move the imported file to a shared/common layer
+4. **Update the rule** — if the violation is intentional, document why and update arch-rules.json
+
+> Do NOT suppress violations without documenting the reason in arch-rules.json.
+
+---
+
+## Next Steps
+
+1. Fix all violations in the table above
+2. Re-run: `node skills/arch-guard/scripts/check-boundaries.js {{RULES_FILE}} {{SRC_DIR}}`
+3. Commit clean state: `git commit -m "fix: resolve arch-guard boundary violations"`
+4. Add to CI: run check-boundaries.js in pre-commit or CI pipeline

package/skills/brand-assets/rubrics/asset-checklist.md

@@ -0,0 +1,98 @@
+# Required Brand Assets Checklist
+
+Complete this checklist before shipping. Each missing item is a gap in brand completeness.
+
+---
+
+## Tier 1 — Blocking (must exist before launch)
+
+### Favicon & App Icons
+
+- [ ] `favicon.ico` — 16×16, 32×32, 48×48 combined
+- [ ] `favicon-16x16.png`
+- [ ] `favicon-32x32.png`
+- [ ] `apple-touch-icon.png` — 180×180
+- [ ] `android-chrome-192x192.png`
+- [ ] `android-chrome-512x512.png`
+- [ ] `site.webmanifest` — references all icon paths, correct `name` and `theme_color`
+
+### Logo
+
+- [ ] Primary logo (SVG) — color version
+- [ ] Primary logo (SVG) — white/reversed version for dark backgrounds
+- [ ] Icon-only version (SVG) — usable at 32px minimum
+
+---
+
+## Tier 2 — Important (should exist before public launch)
+
+### Open Graph / Social Sharing
+
+- [ ] `og-image.png` — 1200×630px, includes logo and product name
+- [ ] `twitter-image.png` — 1200×600px or reuse OG image
+- [ ] OG meta tags in `<head>`: `og:title`, `og:description`, `og:image`, `og:url`
+- [ ] Twitter card meta tags: `twitter:card`, `twitter:image`
+
+### iOS / PWA
+
+- [ ] `apple-touch-icon.png` correctly linked in `<head>`
+- [ ] `maskable_icon.png` — 512×512, safe zone within inner 80% (for Android adaptive icons)
+- [ ] PWA manifest includes `purpose: "any maskable"` entry
+- [ ] `theme-color` meta tag set to brand primary color
+
+---
+
+## Tier 3 — Complete (production-quality brand presence)
+
+### Email Assets
+
+- [ ] Email header logo — 300×80px max, hosted URL (not local path)
+- [ ] Email footer logo — monochrome version
+
+### Documentation / Marketing
+
+- [ ] Logo usage guidelines documented
+- [ ] Color codes documented (HEX, RGB, HSL)
+- [ ] Font names and weights documented
+- [ ] Do/don't logo usage examples
+
+---
+
+## Quality Checks
+
+### Icon Quality
+
+- [ ] Icon is recognizable at 16×16 (no fine details lost)
+- [ ] No text or letters in icon (illegible at small sizes)
+- [ ] Single focal element (not a scene or complex composition)
+- [ ] Works on both white and dark backgrounds
+- [ ] Consistent visual weight with similar products in the app's ecosystem
+
+### File Formats
+
+- [ ] SVG files are clean (no Figma/Illustrator junk metadata)
+- [ ] PNG files are optimized (use `pngcrush` or equivalent)
+- [ ] ICO file contains all three sizes (16, 32, 48)
+- [ ] All files referenced in manifest actually exist
+
+### Colors in Assets
+
+- [ ] Icon colors match brand color palette exactly (no approximations)
+- [ ] OG image background uses brand color, not generic gray
+- [ ] Logo SVG uses `currentColor` or hardcoded brand values (never browser defaults)
+
+---
+
+## Asset Inventory
+
+| Asset | File Path | Size | Format | Status |
+|-------|-----------|------|--------|--------|
+| Primary logo | {{LOGO_PATH}} | — | SVG | {{STATUS}} |
+| Logo white | {{LOGO_WHITE_PATH}} | — | SVG | {{STATUS}} |
+| App icon | {{ICON_PATH}} | 512×512 | PNG | {{STATUS}} |
+| Favicon bundle | `public/favicon.ico` | 16/32/48 | ICO | {{STATUS}} |
+| Apple touch | `public/apple-touch-icon.png` | 180×180 | PNG | {{STATUS}} |
+| Android 192 | `public/android-chrome-192x192.png` | 192×192 | PNG | {{STATUS}} |
+| Android 512 | `public/android-chrome-512x512.png` | 512×512 | PNG | {{STATUS}} |
+| OG image | `public/og-image.png` | 1200×630 | PNG | {{STATUS}} |
+| Maskable icon | `public/maskable-icon.png` | 512×512 | PNG | {{STATUS}} |