start-vibing 4.3.3 → 4.4.0

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "start-vibing",
-	"version": "4.3.3",
-	"description": "Setup Claude Code with 9 plugins, 6 community skills, and 8 MCP servers. Parallel install, auto-accept, superpowers + ralph-loop. super-design 0.6.3: DSC-choice active selection — score-typeui.mjs ranks 12 typeui-* skills by 7-axis fingerprint (density/contrast/geometry/color/typography/motion/audience) from findings+DIS, top-3 written to typeui-proposal.json with copy-paste CLI; harvest-typeui.sh pulls typeui.sh catalog + vercel-labs/anthropic fallbacks; sd-fix --typeui <name> rebrands V1-V8 fixes to snap spacing/color/radius to chosen direction's tokens.",
+	"version": "4.4.0",
+	"description": "Setup Claude Code with 9 plugins, 6 community skills, and 8 MCP servers. Parallel install, auto-accept, superpowers + ralph-loop. super-design 0.7.0 (BREAKING): source-first surface & project-rule discovery. New scripts/discover-surfaces.sh statically maps modals, forms, triggers, internal nav, Next.js layout/error/loading/not-found/parallel/intercepting routes BEFORE Playwright runs. New scripts/extract-project-rules.sh parses FORBIDDEN tables from CLAUDE.md / AGENTS.md / .cursorrules into an authoritative rule source. sd-audit gains Step 1.5 (surface + rule extraction), viewport-coverage quota (emits audit-coverage-skewed meta finding if mobile < 30%), mandatory design-intelligence-craft-summary finding per page × viewport (one holistic verdict per combo, not just discrete C1-C17), Step 3i project-rule enforcement (project FORBIDDEN rules fire as primary findings keyed to the project's own wording), and modal-coverage-gap / form-coverage-gap findings for source-declared components never exercised at runtime. verify-audit.sh enforces design-intelligence/<slug>_<vp>.json existence per MATRIX combination and mobile quota gate. Baymard 88-rule catalog + DSC-choice typeui selection carry over from 0.6.4.",
 	"type": "module",
 	"bin": {
 		"start-vibing": "./dist/cli.js"

package/template/.claude/agents/sd-audit.md

@@ -67,6 +67,20 @@ Read in order:
 
 Run `.claude/skills/super-design/scripts/discover-routes.sh`. If incremental mode, filter to scope (read `.super-design/sessions/<id>/scope.json`).
 
+## Step 1.5 — Source-first surface & project-rule discovery (MANDATORY, 0.7.0+)
+
+Playwright deduction misses internal state (modals never triggered in the tested flow, forms gated behind other forms, parallel/intercepting routes). Source-first discovery reads the repo FIRST and emits two authoritative artifacts that Step 2.5 and Step 3i consume as ground truth.
+
+```bash
+bash .claude/skills/super-design/scripts/discover-surfaces.sh     > "$SESSION_DIR/surfaces.json"
+bash .claude/skills/super-design/scripts/extract-project-rules.sh > "$SESSION_DIR/project-rules.json"
+```
+
+- `surfaces.json` — authoritative inventory of modals, forms, triggers, internal nav, Next.js layout/error/loading/not-found/parallel/intercepting routes. Step 2.5 Phase B cross-checks runtime discovery against this list and emits `modal-coverage-gap` / `form-coverage-gap` findings for anything the source declares but Playwright never exercised.
+- `project-rules.json` — parsed FORBIDDEN tables from `CLAUDE.md`/`AGENTS.md`/`.cursorrules`. Applicable rules (audit-scope, not code-level) are consumed by Step 3i.
+
+Both files MUST exist before Step 2 starts. `verify-audit.sh` warns when either is missing.
+
 ## Step 2 — Launch audit loop
 
 For each viewport ∈ [mobile 375×812, tablet 768×1024, desktop 1440×900], for each page in scope:
@@ -385,6 +399,24 @@ Cross-reference the competitor component vocabulary from
 tabs on mobile and the product uses hamburger-only, density score drops AND
 the M1 finding cites the category norm.
 
+## Step 3i — Project-rule enforcement (MANDATORY, 0.7.0+)
+
+Iterate the `audit_applicable: true` rules from `project-rules.json` (Step 1.5). These rules are authoritative — the project owner has already codified them as the right answer for this codebase. Each violation fires as a PRIMARY finding with `rule: project-forbidden-<slug>` keyed to the project's own wording.
+
+```jsonc
+{
+  "id": "F-NNNN",
+  "rule": "project-forbidden-use-cards-on-mobile",
+  "source_rule": { "raw": "Use Cards on mobile", "reason": "Waste space in flex-col", "source_file": "CLAUDE.md" },
+  "template_id": "M2",
+  "viewport": "mobile",
+  "severity": 3,
+  ...
+}
+```
+
+Do NOT downgrade or tag — project-forbidden rules ARE the rule source, not a bump on another finding. `verify-audit.sh` skips snapshot_quote verification for this rule family (evidence is aggregate, not a single DOM quote).
+
 ## Step 4 — Write findings
 
 Append to `docs/super-design/findings/F-NNNN.md` (one file per finding) AND `.super-design/sessions/<id>/findings.json`.

package/template/.claude/skills/e2e-audit/DESIGN.md

@@ -0,0 +1,294 @@
+# E2E Audit Infrastructure - Design Specification
+
+## Objective
+
+Build a comprehensive E2E testing system for the Hakutaku Dashboard that:
+
+1. **Discovers every interactive element** on every page (links, buttons, inputs, modals, dropdowns, tabs, tooltips, toasts)
+2. **Auto-generates page specs** documenting all elements found per page
+3. **Produces fixed `.spec.ts` Playwright test files** that run standalone (`bun run test:e2e`) without AI
+4. **Validates UX/UI** — inputs, sanitization, notifications, tooltips, styles, toasts
+5. **Tests security** — XSS, RBAC across 4 roles, console leaks, security headers
+6. **Detects dead code** — unused/unreachable elements via static + dynamic analysis
+7. **Supports agent-driven updates** — agent re-audits and updates test files when app changes
+
+## Scope
+
+- **Desktop only** (1280px+) — no mobile/tablet for now
+- **All pages** — 25 pages across dashboard, auth, and public routes
+- **All roles** — OWNER, ADMIN, MANAGER, MEMBER + unauthenticated
+- **Public** — committed to git, no .gitignore
+
+---
+
+## 1. Playwright Infrastructure
+
+### Config
+
+- `playwright.config.ts` at project root
+- Desktop viewport: `1280x720`
+- Base URL: `http://localhost:3000`
+- `fullyParallel: true` for speed
+- `trace: 'on-first-retry'` for CI debugging
+- `screenshot: 'only-on-failure'`
+- Test directory: `tests/e2e/`
+- Output: `test-results/`
+
+### Auth Fixtures
+
+Reusable `storageState` per role:
+
+```
+tests/e2e/
+├── fixtures/
+│   ├── auth.ts          # Auth setup — generates storageState per role
+│   ├── base.ts          # Extended test fixture with page helpers
+│   └── storage/         # Generated auth state files (gitignored)
+│       ├── owner.json
+│       ├── admin.json
+│       ├── manager.json
+│       └── member.json
+├── pages/               # Page Object Models
+├── specs/               # Test spec files
+└── utils/               # Shared test utilities
+```
+
+### Test Tags
+
+| Tag | Purpose |
+|-----|---------|
+| `@smoke` | Critical path — must pass on every PR |
+| `@regression` | Full suite — runs on main merges |
+| `@security` | Security-specific tests |
+| `@a11y` | Accessibility checks |
+| `@ux` | UX/UI validation (toasts, tooltips, styles) |
+
+---
+
+## 2. Page Spec Template
+
+Each page gets a structured spec document in `docs/e2e-audit/page-specs/`:
+
+```markdown
+# Page: [Name]
+Route: /dashboard/[route]
+Auth Required: yes/no
+Minimum Role: MEMBER/MANAGER/ADMIN/OWNER
+
+## Interactive Elements
+
+### Navigation
+- [ ] Link: "Home" → /dashboard/home
+- [ ] Link: "Knowledge" → /dashboard/knowledge
+
+### Buttons
+- [ ] Button: "Create New" → opens modal
+- [ ] Button: "Delete" → confirmation dialog
+
+### Inputs
+- [ ] Input: "Search" (text, placeholder: "Search...")
+- [ ] Select: "Filter by" (options: All, Active, Archived)
+
+### Modals/Dialogs
+- [ ] Modal: "Create Item" (trigger: "Create New" button)
+  - Input: "Name" (required)
+  - Input: "Description" (optional)
+  - Button: "Save" → POST + toast
+  - Button: "Cancel" → closes modal
+
+### Toasts/Notifications
+- [ ] Success: "Item created successfully"
+- [ ] Error: "Failed to create item"
+
+### Tooltips
+- [ ] Tooltip: "Info icon" → "This is a tooltip"
+
+### States
+- [ ] Empty state: "No items found"
+- [ ] Loading state: skeleton/spinner
+- [ ] Error state: error message display
+```
+
+---
+
+## 3. E2E Audit Skill Architecture
+
+The skill (`/.claude/skills/e2e-audit/SKILL.md`) instructs agents to:
+
+1. **Crawl** — Navigate to each page, capture all interactive elements
+2. **Generate page spec** — Write structured spec to `docs/e2e-audit/page-specs/`
+3. **Generate test file** — Write `.spec.ts` to `tests/e2e/specs/`
+4. **Generate page object** — Write POM to `tests/e2e/pages/`
+5. **Validate** — Run tests via Playwright, fix failures
+6. **Report** — Write results to `docs/e2e-audit/reports/`
+
+### Agent Workflow
+
+```
+DISCOVER → SPEC → IMPLEMENT → VALIDATE → REPORT
+```
+
+- **DISCOVER**: Use Playwright MCP to navigate page, snapshot DOM, list all actionable elements
+- **SPEC**: Write page spec markdown documenting every element found
+- **IMPLEMENT**: Generate POM + test spec from the page spec
+- **VALIDATE**: Run `bunx playwright test <file>` and fix any failures
+- **REPORT**: Record pass/fail counts, coverage gaps, findings
+
+---
+
+## 4. Research-Oriented Testing Agent
+
+Each page audit follows a 4-phase approach:
+
+### Phase 1: RESEARCH
+- Check OWASP Top 10 for relevant vulnerabilities
+- Research common issues with the page's tech (e.g., file upload XSS, chat injection)
+- Look up library-specific CVEs and edge cases
+
+### Phase 2: DISCOVER
+- Navigate to page via Playwright MCP
+- Snapshot DOM to enumerate all elements
+- Identify: links, buttons, inputs, selects, modals, dropdowns, tabs, tooltips
+- Capture initial state, loading states, empty states, error states
+
+### Phase 3: GENERATE
+- Write page spec markdown
+- Write Page Object Model class
+- Write test spec with assertions for:
+  - Navigation (all links resolve correctly)
+  - Interactions (buttons, modals, forms work)
+  - Validation (required fields, error messages)
+  - UX (toasts appear, tooltips show, styles correct)
+  - Security (XSS in inputs, RBAC enforcement)
+
+### Phase 4: DOCUMENT
+- Record all findings
+- Flag missing test-ids
+- Flag accessibility issues
+- Flag security concerns
+
+---
+
+## 5. Security Testing
+
+### Layer 1: Passive (Every Page)
+- `page.on('console')` — capture and assert no sensitive data leaks
+- Response header checks: `X-Frame-Options`, `X-Content-Type-Options`, `Strict-Transport-Security`
+- No stack traces in error responses
+
+### Layer 2: RBAC Matrix
+- Test each page with all 4 roles + unauthenticated
+- Verify unauthorized access redirects to `/unauthorized` or `/auth`
+- Verify UI elements show/hide based on permissions
+
+### Layer 3: Active (Targeted)
+- XSS payloads in text inputs (`<script>`, `<img onerror>`, `javascript:`)
+- Verify dialog listeners don't fire (no XSS execution)
+- IDOR checks on ID-based routes (`/knowledge/[id]`, `/chat/[id]`)
+- CSRF token presence on mutations
+
+---
+
+## 6. Dead Code Detection
+
+### Static Analysis
+- `knip` for unused exports, files, dependencies
+- Run: `bunx knip --reporter json > docs/e2e-audit/reports/dead-code-static.json`
+
+### Dynamic Analysis
+- Playwright coverage API to track which code executes during tests
+- Compare covered vs total to identify unreachable code paths
+- Output: `docs/e2e-audit/reports/dead-code-dynamic.json`
+
+---
+
+## 7. Documentation Output
+
+```
+docs/e2e-audit/
+├── DESIGN.md              # This file
+├── page-specs/            # Per-page element inventories
+│   ├── dashboard-home.md
+│   ├── dashboard-knowledge.md
+│   ├── dashboard-chat.md
+│   └── ...
+├── reports/               # Audit results
+│   ├── master-audit.md    # Summary of all findings
+│   ├── security-report.md # Security-specific findings
+│   ├── coverage-gaps.md   # Missing test coverage
+│   └── dead-code.md       # Unused code findings
+└── runbook.md             # How to run, update, and maintain tests
+```
+
+---
+
+## 8. All Pages to Audit
+
+### Dashboard (Authenticated)
+| # | Page | Route | Min Role |
+|---|------|-------|----------|
+| 1 | Home | `/dashboard/home` | MEMBER |
+| 2 | Knowledge List | `/dashboard/knowledge` | MEMBER |
+| 3 | Knowledge Detail | `/dashboard/knowledge/[id]` | MEMBER |
+| 4 | Chat | `/dashboard/chat` | MEMBER |
+| 5 | Integrations List | `/dashboard/integrations` | MEMBER |
+| 6 | Integration Detail | `/dashboard/integrations/[id]` | MEMBER |
+| 7 | New Integration | `/dashboard/integrations/new` | MANAGER |
+| 8 | Integration Success | `/dashboard/integrations/success` | MEMBER |
+| 9 | Teams | `/dashboard/teams` | MEMBER |
+| 10 | Profile | `/dashboard/profile` | MEMBER |
+| 11 | Admin | `/dashboard/admin` | ADMIN |
+| 12 | Billing | `/dashboard/billing` | OWNER |
+| 13 | Ontology | `/dashboard/ontology` | MEMBER |
+| 14 | Transcripts List | `/dashboard/transcripts` | MEMBER |
+| 15 | Transcript Detail | `/dashboard/transcripts/[id]` | MEMBER |
+| 16 | Transcript Document | `/dashboard/transcripts/documents/[id]` | MEMBER |
+
+### Auth
+| # | Page | Route |
+|---|------|-------|
+| 17 | Login/Landing | `/` |
+| 18 | Desktop Auth | `/auth/desktop` |
+| 19 | Auth Error | `/auth/error` |
+| 20 | Logout | `/auth/logout` |
+| 21 | OAuth Popup Callback | `/auth/popup-callback` |
+| 22 | Integration Callback Success | `/auth/integration/callback/success` |
+| 23 | Integration Callback Error | `/auth/integration/callback/error` |
+
+### Other
+| # | Page | Route |
+|---|------|-------|
+| 24 | Unauthorized | `/unauthorized` |
+| 25 | Free Trial | `/freetrial` |
+
+---
+
+## 9. Running Tests
+
+```bash
+# Run all E2E tests
+bun run test:e2e
+
+# Run specific tag
+bunx playwright test --grep @smoke
+
+# Run specific page
+bunx playwright test tests/e2e/specs/dashboard-home.spec.ts
+
+# Run with UI mode
+bunx playwright test --ui
+
+# Run with trace viewer
+bunx playwright show-trace test-results/trace.zip
+```
+
+---
+
+## 10. Maintenance
+
+When the app changes:
+1. Agent re-runs discovery on affected pages
+2. Compares new elements with existing page spec
+3. Updates page spec, POM, and test file
+4. Runs tests to validate
+5. Updates reports with new findings