@seanyao/roll 3.620.1 → 3.624.1

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

@@ -1,256 +0,0 @@
-# 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

@@ -1,148 +0,0 @@
----
-hidden: true
-name: roll-.review
-license: MIT
-allowed-tools: "Read, Bash(git:*)"
-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
-
-```
-TCR Loop:
-  Write Test → Run Test → ✅ Green → Self Review → Commit
-                                          ↓
-                                     Critical?
-                                   Yes → Fix → Redo
-                                    No → Proceed
-```
-
-## When Triggered
-
-- **Auto-triggered**: After each TCR micro-step in `$roll-build` / `$roll-fix`
-- **Manual trigger**: When the user wants to review current changes
-
-## When Not to Use
-
-- Docs-only changes (README, CHANGELOG) with no code diff
-- Test pyramid / coverage standards check (use `$roll-.qa`)
-- Post-deploy production sampling (use `$roll-sentinel`)
-
-## Review Scope
-
-```bash
-# Default: review staged changes (recommended for TCR)
-$roll-.review staged
-
-# Review all uncommitted changes
-$roll-.review unstaged
-
-# Review specific files
-$roll-.review files src/utils.ts
-```
-
-## Review Dimensions (7 Core Dimensions)
-
-Original 6 dimensions plus Reuse (added in REFACTOR-022, simplify three-axis integration):
-
-```
-┌─────────────────────────────────────────────────────────┐
-│  WK Quality Checklist                                   │
-├─────────────────────────────────────────────────────────┤
-│  ✅ Correctness     - Logic is correct, no bugs         │
-│  ✅ Security        - No vulnerabilities, input valid.  │
-│  ✅ Maintainability - Clear naming, sound structure     │
-│     Quality anti-patterns (check each):                 │
-│       □ Redundant state / cached values that could be   │
-│         derived directly                                │
-│       □ Parameter sprawl — new param vs. restructure    │
-│       □ Copy-paste with slight variation (near-dup)     │
-│       □ Leaky abstraction — exposes internal details    │
-│       □ Stringly-typed — raw string where constant      │
-│         / enum exists                                   │
-│       □ Unnecessary JSX nesting (no layout value)       │
-│       □ Nested conditionals ≥3 deep (ternary chains,    │
-│         nested if/else) — flatten with early return     │
-│       □ Unnecessary comments explaining WHAT            │
-│  ✅ Performance     - No performance pitfalls           │
-│     Efficiency anti-patterns (check each):              │
-│       □ Redundant computation / repeated file read /    │
-│         duplicate API call / N+1 pattern                │
-│       □ Missed concurrency — independent ops sequential │
-│       □ Hot-path bloat — blocking work in startup or    │
-│         per-request path                                │
-│       □ Loop no-op updates — missing change-detection   │
-│         guard                                           │
-│       □ TOCTOU existence pre-check — operate directly + │
-│         handle error instead                            │
-│       □ Memory — unbounded structures / missing cleanup │
-│       □ Overly broad op — reading full file for a slice │
-│  ✅ Testability     - Easy to test, edge cases covered  │
-│  ✅ Scope           - Focused on current task, no       │
-│                       unrelated changes                 │
-│  ✅ Reuse           - No new code duplicating existing  │
-│     □ New function duplicates existing utility/helper   │
-│     □ Inline logic replaceable by existing tool         │
-└─────────────────────────────────────────────────────────┘
-```
-
-**Usage in TCR**: Each micro-step review is a lightweight self-check against this checklist — no sub-agents, zero extra token cost. The three-axis deep review with parallel agents runs once per Story in `$roll-build` Phase 7.
-
-## Severity Levels and Decisions
-
-| Level | Definition | Decision |
-|-------|-----------|----------|
-| 🔴 **Critical** | Bug, security vulnerability | **Must fix**, redo TCR |
-| 🟡 **Warning** | Maintainability issue | **Recommend fix** or document |
-| 🟢 **Suggestion** | Minor optimization | Optional, proceed with commit |
-| ✅ **Pass** | No issues | Proceed with commit |
-
-## Output Format
-
-```markdown
-## Self Review Report
-**Scope**: staged (2 files, +45/-12 lines)
-
-### 🔴 Critical (Must Fix)
-| File | Line | Issue | Action |
-|------|------|-------|--------|
-| auth.ts | 23 | SQL injection | Use parameterized query |
-
-### 🟡 Warnings
-- utils.ts:45 - Magic number, consider: `const MAX_RETRY = 3`
-
-### ✅ Passed
-- Naming conventions
-- Error handling
-```
-
-## TCR Integration
-
-In each micro-step of `$roll-build`:
-
-```markdown
-**Micro-Step X: [Description]**
-
-1. Write/Update Test
-2. Run Test → ✅ Green
-3. **$roll-.review staged**
-   - 🔴 Critical? → Fix → Redo step
-   - 🟡 Warning? → Quick fix or document
-   - ✅ Pass? → Proceed
-4. git commit -m "tcr: description"
-```
-
-## WK Principle Alignment
-
-- **Agent-First**: Structured review checklist, executable by AI
-- **Check Phase**: Local quality control
-- **Micro-steps**: Small fast steps, each review < 100 lines
-- **TCR**: Can only commit after passing self-check, ensuring repo quality

package/skills/roll-build/SKILL.md

@@ -1,49 +0,0 @@
----
-name: roll-build
-license: MIT
-allowed-tools: "Read, Edit, Write, Glob, Grep, Bash, Skill, Agent"
-description: "Load when a user gives a US-XXX story or asks to ship a feature through Roll TCR delivery, from clarification through verification and backlog write-back."
----
-# Roll Build
-
-This hub keeps the routing boundary, hard gates, and execution skeleton in the initial context. Load the heavier runbook only when the task actually needs the detailed contract.
-
-## Load
-
-Load when a user gives a US-XXX story or asks to ship a feature through Roll TCR delivery, from clarification through verification and backlog write-back.
-
-## When Not to Use
-
-- Pure design or backlog splitting without code; load roll-design.
-- Narrow FIX/BUG repair; load roll-fix.
-
-## Read On Demand
-
-- Read [the full contract](references/full-contract.md) before executing the workflow end to end, recovering from failures, or checking exact output templates.
-- Keep this hub in context for trigger boundaries and hard gates.
-
-## Workflow Skeleton
-
-1. Classify input as Story mode or Fly mode.
-2. Read backlog/spec and decide if the story fits one cycle.
-3. Split into small TCR actions and define verification.
-4. Run test-first implementation, self-review, evidence, and write-back.
-5. Commit on green, open PR, and leave remote evidence.
-
-## Hard Gates
-
-- TCR for every micro-step.
-- No WIP commits or bypassed verification.
-- Self-review, attest, and E2E evidence remain required. The Review Score is produced by the runner's fresh-session peer Reviewer — the agent does NOT self-score.
-- Docs/code/product alignment is a DoD gate: user-visible behavior, command, output-copy, site, or delivery-view changes update the touched README/docs/guide/site/help in the same delivery.
-
-## Gotchas
-
-- Do not use for pure design/backlog splitting; route that to roll-design until implementation starts.
-- TCR and evidence gates remain mandatory even when the code change looks small.
-
-## Maintenance
-
-- Description changes require updates in `route-cases/skills.json`.
-- New observed failures should add a gotcha and the matching positive or negative route case.
-- Heavy examples, templates, recovery paths, and deterministic snippets belong in `references/`, `assets/`, or `scripts/`, not in this hub.