@seanyao/roll 3.610.1 → 3.611.2

package/skills/roll-.qa/references/full-contract.md

@@ -0,0 +1,256 @@
+# Full Contract Reference
+
+This file preserves the detailed contract extracted from SKILL.md. Read it when the hub points here for exact workflow steps, templates, rubrics, or recovery branches.
+
+---
+
+# QA Cover
+
+This is a **reference skill** used by `roll-build` and `roll-fix` for quality assurance and test coverage.
+
+## When to Apply
+
+Any product with a user interface (Web, Desktop, Mobile) must follow these testing standards.
+
+## When Not to Use
+
+- Non-UI backends (APIs, CLI tools, data pipelines) — use project-specific test frameworks
+- Spike code or throwaway prototypes that won't ship
+- Per-commit self-review of diffs (use `$roll-.review`)
+
+## Required Testing Levels
+
+### 1. Unit Tests (Logic)
+- **Tool**: Vitest / Jest
+- **Coverage**: Business logic, utilities, hooks
+- **Run**: `npm run test`
+
+### 2. E2E Tests (User Flows)
+- **Tool**: **Playwright** (default)
+- **Coverage**: Critical user paths, interactions
+- **Run**: `npm run test:e2e`
+
+### 3. Visual Regression (UI Stability)
+- **Tool**: Playwright screenshot testing
+- **Coverage**: Key UI states
+- **Run**: Part of E2E tests
+- **Baseline**: Stored in `e2e/__snapshots__/`
+
+### 4. Smoke Tests (Post-deploy)
+- **Tool**: Playwright
+- **Coverage**: Core functionality on production
+- **Run**: `npm run test:e2e:smoke`
+
+## Playwright Setup
+
+### Installation
+```bash
+npm install -D @playwright/test
+npx playwright install chromium
+```
+
+### Configuration (playwright.config.ts)
+```typescript
+import { defineConfig, devices } from '@playwright/test';
+
+export default defineConfig({
+  testDir: './e2e',
+  fullyParallel: true,
+  retries: process.env.CI ? 2 : 0,
+  reporter: 'html',
+  use: {
+    baseURL: process.env.PLAYWRIGHT_BASE_URL || 'http://localhost:5173',
+    trace: 'on-first-retry',
+    screenshot: 'only-on-failure',
+  },
+  projects: [
+    { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
+  ],
+});
+```
+
+### Required Test Files
+
+**e2e/smoke.spec.ts** (Deployment verification)
+```typescript
+import { test, expect } from '@playwright/test';
+
+test('app loads', async ({ page }) => {
+  await page.goto('/');
+  await expect(page.locator('#app')).toBeVisible();
+});
+```
+
+**e2e/interaction.spec.ts** (User flows)
+```typescript
+test('user can complete core flow', async ({ page }) => {
+  await page.goto('/');
+  // Test critical user journey
+});
+```
+
+**e2e/visual.spec.ts** (Visual regression)
+```typescript
+test('homepage visual', async ({ page }) => {
+  await page.goto('/');
+  await expect(page).toHaveScreenshot('homepage.png');
+});
+```
+
+### Package.json Scripts
+```json
+{
+  "scripts": {
+    "test:e2e": "playwright test",
+    "test:e2e:ui": "playwright test --ui",
+    "test:e2e:smoke": "playwright test smoke.spec.ts",
+    "test:all": "npm run test && npm run test:e2e"
+  }
+}
+```
+
+## Visual Regression Workflow
+
+### 1. Create Baseline (First Time)
+```bash
+npx playwright test --update-snapshots
+```
+
+### 2. Commit Baseline
+```bash
+git add e2e/__snapshots__/
+git commit -m "chore: add visual regression baselines"
+```
+
+### 3. Subsequent Runs (Compare)
+```bash
+npm run test:e2e
+# Fails if screenshots differ beyond threshold
+```
+
+### 4. Update Baseline (Intentional UI Change)
+```bash
+npx playwright test --update-snapshots
+git add e2e/__snapshots__/
+git commit -m "chore: update visual baseline for new design"
+```
+
+## CI/CD Integration
+
+### Local Pre-push Checklist
+- [ ] `npm run test` passes
+- [ ] `npm run test:e2e` passes
+- [ ] No unexpected visual regressions
+
+### Post-deploy Smoke Test
+```bash
+# Against production URL
+PLAYWRIGHT_BASE_URL=https://your-app.com npm run test:e2e:smoke
+```
+
+## Common Patterns
+
+### Testing Canvas/Game Rendering
+```typescript
+test('game renders', async ({ page }) => {
+  await page.goto('/');
+  const canvas = page.locator('#gameCanvas');
+  await expect(canvas).toBeVisible();
+  
+  // Visual regression for canvas
+  await expect(page).toHaveScreenshot('game-initial.png', {
+    maxDiffPixels: 100,
+  });
+});
+```
+
+### Testing Responsive Layouts
+```typescript
+test('responsive design', async ({ page }) => {
+  await page.setViewportSize({ width: 375, height: 667 });
+  await page.goto('/');
+  await expect(page.locator('.mobile-menu')).toBeVisible();
+});
+```
+
+### Testing Voice/Audio Features
+```typescript
+test('voice button toggles', async ({ page }) => {
+  await page.goto('/');
+  const btn = page.locator('#voiceBtn');
+  await btn.click();
+  await expect(btn).toHaveClass(/active/);
+});
+```
+
+## Failure Handling
+
+### Flaky Tests
+- Add `test.fixme()` to skip temporarily
+- Increase `timeout` for slow operations
+- Use `retries` in config for network-dependent tests
+
+### Visual Regression Failures
+1. Check if change is intentional
+2. If yes: `npx playwright test --update-snapshots`
+3. If no: fix the code
+
+### Missing Test Infrastructure
+If project lacks Playwright setup:
+1. Install dependencies
+2. Create config
+3. Add basic smoke test
+4. Run to create baseline
+5. Commit as separate "test infrastructure" change
+
+## CI Failure Triage
+
+When CI goes red, triage the failure into an actionable item instead of ignoring it.
+
+### Step 1: Read the CI Log
+
+```
+CI failure
+    │
+    ├── Which step failed? (lint / build / test / e2e)
+    ├── What is the error message?
+    ├── Is it reproducible locally?
+    └── Is it flaky (passes on retry)?
+```
+
+### Step 2: Classify Severity
+
+| Severity | Signal | Action |
+|----------|--------|--------|
+| Critical | Build or core tests fail, blocks all merges | Fix immediately via `$roll-fix` |
+| High | E2E test fails on a key user flow | Create FIX-XXX, fix within current sprint |
+| Medium | Visual regression, non-critical test failure | Create FIX-XXX, prioritize in backlog |
+| Low | Lint warning, flaky test (passes on retry) | Create FIX-XXX or IDEA-XXX, fix when convenient |
+
+### Step 3: Create Backlog Entry
+
+```bash
+# For fixable bugs — create FIX entry
+$roll-idea fix "CI: {step} fails — {root cause summary}"
+
+# For flaky/environmental issues — create IDEA entry
+$roll-idea idea "CI: investigate flaky {test name}"
+```
+
+### Step 4: Execute Fix
+
+```
+FIX-XXX created
+    │
+    ├── Critical / High → $roll-fix FIX-XXX (immediate)
+    ├── Medium → schedule in backlog, $roll-fix when ready
+    └── Low → backlog, fix opportunistically
+```
+
+All fixes go through `$roll-fix` TCR workflow — test, fix, review, commit, push, CI green.
+
+## References
+
+- [Playwright Docs](https://playwright.dev/)
+- [Visual Regression Guide](https://playwright.dev/docs/test-snapshots)
+- Example implementation: `<owner>/<repo>/e2e/`

package/skills/roll-.review/SKILL.md

@@ -3,11 +3,15 @@ hidden: true
 name: roll-.review
 license: MIT
 allowed-tools: "Read, Bash(git:*)"
-description: Self code review step in the TCR workflow. Runs after each micro-step is completed and before commit, checking code quality, security, and design issues.
+description: "Load when a TCR micro-step needs self code review before commit, focused on bugs, regressions, security, and design issues."
 ---
-
 # WK Self Code Review
 
+## Gotchas
+
+- Review findings lead with bugs and regressions, not style preferences or summaries.
+- This is local self-review; use roll-review-pr for PR diffs and roll-peer for cross-agent negotiation.
+
 **Quality gate for the TCR loop** - Self-review after each micro-step is completed and before commit.
 
 ## Position in WK Workflow

package/skills/roll-brief/SKILL.md

@@ -2,17 +2,15 @@
 name: roll-brief
 license: MIT
 allowed-tools: "Read, Glob, Grep, Write, Bash(git:*)"
-description: |
-  Owner-facing briefing generator. Summarizes what the agent has done since
-  the last brief: completed US/FIX/REFACTOR, in-progress items, BACKLOG queue
-  status, escalations requiring human attention, and a release-readiness verdict.
-  Three trigger modes: auto on Feature completion, daily morning schedule,
-  or manual $roll-brief invocation. Distinct from roll-.changelog (user-facing
-  changelog) — this is an internal digest for the product owner.
+description: "Load when the owner asks for an internal Roll briefing summarizing completed work, in-progress items, backlog queue, escalations, and release readiness."
 ---
-
 # Roll Brief
 
+## Gotchas
+
+- Brief is owner-facing internal context, not public changelog copy.
+- Call out escalations and release readiness explicitly; do not flatten them into a generic progress summary.
+
 > Follows the Architecture Constraints, Development Discipline, and Engineering
 > Common Sense defined in the project AGENTS.md.