@seanyao/roll 3.610.1 → 3.611.2

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

@@ -0,0 +1,365 @@
+# 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.
+
+---
+
+# Roll Dream (Nightly Code Health Scan)
+
+> Follows the Architecture Constraints, Development Discipline, and Engineering
+> Common Sense defined in the project AGENTS.md.
+
+**Passively triggered — do not invoke manually.** Runs nightly via scheduler.
+Consolidates structural signals accumulated during the day, surfaces technical
+debt, and writes REFACTOR entries to BACKLOG. The human reviews the dream log
+in the morning brief.
+
+## Distinction from roll-sentinel
+
+| | roll-sentinel | roll-.dream |
+|--|--------------|------------|
+| **Trigger** | Post-deploy, scheduled patrol | Nightly, fixed schedule |
+| **Target** | Runtime behavior (production) | Code structure (codebase) |
+| **Output** | FIX entries | REFACTOR entries + dream log |
+| **Question** | "Is the product working?" | "Is the code healthy?" |
+
+## Scan Logic
+
+Run all scans every night. Each scan is independent.
+
+### Scan 1 — Dead Code
+
+Find code that is defined but never referenced:
+
+```bash
+# Unused exports (TypeScript/JS)
+grep -r "^export " src/ --include="*.ts" -l | while read f; do
+  symbol=$(grep -o "export \(function\|const\|class\|type\|interface\) [A-Za-z]*" "$f" | awk '{print $NF}')
+  # check if symbol appears anywhere else in the codebase
+done
+
+# Unused files (no imports pointing to them)
+# Git: files not touched in 90+ days and not imported anywhere
+git log --since="90 days ago" --name-only --format="" | sort -u > /tmp/recently_touched
+```
+
+Flag: files or exports with zero references outside their own file.
+
+### Scan 2 — Architectural Drift
+
+Compare current code structure against the domain model in `.roll/domain/`:
+
+```bash
+# Read context-map.md and ubiquitous-language.md if they exist
+# Check: do module/directory names match Bounded Context names?
+# Check: do cross-module imports respect Context boundaries?
+# Check: do any modules import directly across Context lines without ACL?
+```
+
+Flag: modules that import directly from a different Bounded Context without
+an Anti-Corruption Layer, or module names that have diverged from the
+Ubiquitous Language.
+
+**Distinction from Scan 6C**: Scan 2 flags *import boundary violations* (cross-context coupling). Scan 6C flags *missing documentation entries* (module exists but has no entry in `.roll/domain/*.md`). Never double-flag — Scan 2 and Scan 6C are orthogonal checks.
+
+### Scan 3 — Pruning Candidates
+
+Find over-engineering that can be simplified:
+
+```bash
+# Abstractions with only one implementation
+grep -r "interface \|abstract class " src/ --include="*.ts" -l
+
+# Wrapper functions that do nothing but delegate
+# Config flags that are never toggled (always true or always false)
+# Error handling for paths that cannot occur
+```
+
+Flag: interfaces with exactly one implementor, feature flags frozen to one
+value, wrapper layers with no logic.
+
+### Scan 4 — Emerging Patterns
+
+Find repeated structures that warrant extraction:
+
+```bash
+# Duplicated code blocks (>10 lines, similar structure)
+# Similar file structures across multiple modules
+# Repeated try/catch patterns with identical handling
+```
+
+Flag: any pattern appearing 3+ times that could be extracted into a shared
+utility or convention.
+
+### Scan 5 — Doc Coverage Check
+
+Check documentation structure against the conventions in `AGENTS.md § Documentation Conventions`.
+
+**Check A — BACKLOG Done stories missing guide/en/ docs:**
+
+Scan .roll/backlog.md for features with multiple ✅ Done stories. For each feature epic, check whether a corresponding `guide/en/<topic>.md` exists. If a feature has ≥3 Done stories and no guide doc, flag it.
+
+**Check B — guide/en/ files missing guide/zh/ translations:**
+
+```bash
+for f in guide/en/*.md; do
+  base=$(basename "$f")
+  [ ! -f "guide/zh/$base" ] && echo "missing ZH: $base"
+done
+```
+
+Flag any `guide/en/<topic>.md` that has no matching `guide/zh/<topic>.md`, provided the EN file has existed since before the most recent git tag (i.e., at least one release cycle old).
+
+**Check C — stray files in docs/ root (根目录散落文件):**
+
+```bash
+find docs/ -maxdepth 1 -name '*.md' 2>/dev/null
+```
+
+Flag any `.md` file directly in `docs/` root (allowed subdirs: `guide/`, `domain/`, `features/`, `practices/`, `briefs/`, `dream/`).
+
+**Check D — features.md Feature Coverage (US-DOC-009):**
+
+Dependency gate: skip when `.roll/features.md` does not exist.
+
+Parse .roll/backlog.md for all `### Feature: <name>` groups that contain ≥1 ✅ Done story. Parse `.roll/features.md` for Feature names. If any Feature group with Done stories is absent from `.roll/features.md`, the catalog is stale — flag as REFACTOR:
+
+```markdown
+| REFACTOR-XXX | features.md 功能目录落后于 BACKLOG，N 个已完成功能区未收录，用户无法通过产品目录发现这些功能 — flagged by dream YYYY-MM-DD | 📋 Todo |
+```
+
+The catalog is auto-updated by the release script (maintainer-private at `roll-meta/ops/release.sh`) at release time (Section 8 of roll-.changelog). Between releases, this check surfaces the coverage gap so it isn't silently skipped.
+
+**REFACTOR entry format for doc findings:**
+
+```markdown
+| REFACTOR-XXX | docs: {具体缺口描述} — flagged by dream {YYYY-MM-DD} | 📋 Todo |
+```
+
+**Dream log section** — add after existing sections:
+
+```markdown
+## 文档覆盖度
+- features.md 功能区覆盖：{N}/{M} 个已完成功能区已收录（缺失：{列表 或 "无"}）
+{其他发现内容 或 "文档结构符合规范，无缺口。"}
+```
+
+### Scan 6 — 文档新鲜度 (Doc Freshness)
+
+**Dependency gate**: Skip Scan 6 entirely when `$roll-doc` (US-SKILL-008) is not yet deployed.
+Check: `[ -f "$ROLL_HOME/skills/roll-doc/SKILL.md" ]`. If absent, log "Scan 6 skipped — roll-doc not deployed" in the dream log and stop. No fallback.
+
+When deployed, each finding produces a REFACTOR entry with `$roll-doc` as execution hint:
+```markdown
+| REFACTOR-XXX | docs: <description> — flagged by dream <date> (hint: $roll-doc) | 📋 Todo |
+```
+
+#### Check A — Stale Docs
+
+Flag source files whose owning doc is >30 days stale:
+
+```bash
+# For each file listed in .roll/features/*.md or README.md "## Files:" sections:
+#   owner_doc_commit = git log -1 --format="%ci" -- <doc_file>
+#   source_commit    = git log -1 --format="%ci" -- <source_file>
+#   lag_days = (source_commit - owner_doc_commit) in days
+#   if lag_days > 30 AND doc contains at least one specific file path reference → flag
+```
+
+The "owner doc" for a source file is the nearest `README.md` or `.roll/features/*.md` that lists the file path in a `## Files:` section. Skip docs that contain only conceptual descriptions (no specific file path references) — they cannot be objectively stale.
+
+#### Check B — Undocumented ENV Vars
+
+Flag environment variables that appear frequently in source but have no documentation:
+
+```bash
+# Detect ENV var patterns in non-test source files:
+patterns=(
+  'process\.env\.[A-Z_]+'        # Node.js
+  'os\.getenv\("[A-Z_]+"\)'      # Python
+  'ENV\["[A-Z_]+"\]'             # Ruby
+)
+# For each matched variable name:
+#   count occurrences across all source files
+#   if count >= 5 AND zero mentions in any .md file → flag
+```
+
+Flag variables appearing ≥5× in source with zero mentions in any `.md`.
+"Other convention signals" (comment clusters, module structure templates) are explicitly deferred — too vague for deterministic detection.
+
+#### Check C — Existence Drift
+
+Find module directories that exist in code but are absent from architecture docs.
+This is distinct from Scan 2 (which checks *import violations*) — Scan 6C checks *documentation existence*:
+
+```bash
+# Walk all non-excluded directories
+# For each dir with >= 3 non-hidden, non-.md source files:
+#   check if any .roll/domain/*.md contains the directory name
+#   if not found → flag as "existence drift"
+```
+
+Exclusions: `node_modules/`, `.git/`, `dist/`, `build/`, `.shared/`, `docs/`, `tests/`.
+
+Flag directories with ≥3 source files and zero name-match in `.roll/domain/*.md`.
+
+#### Dream Log Section
+
+Add after `## 文档覆盖度` section:
+
+```markdown
+## 文档新鲜度
+- 滞后文档：{N} 个（超过 30 天未更新但绑定了代码文件）
+- 未记录 ENV 变量：{N} 个（出现 ≥5 次但无文档）
+- 架构文档缺失模块：{N} 个（≥3 个源文件的目录未出现在 .roll/domain/）
+{发现内容列表 或 "文档新鲜度良好，无滞后或缺失项。"}
+```
+
+### Scan 7 — Test Quality (rubric-driven)
+
+Apply the test-quality rubric at [guide/en/testing/quality-rubric.md](../../guide/en/testing/quality-rubric.md)
+(Chinese: [quality-rubric.zh.md](../../guide/zh/testing/quality-rubric.md)) against every file under
+`tests/`. The rubric publishes six anti-pattern categories (❶..❻); each has a
+**Signals** subsection that lists the matching heuristics. Scan 7 is purely a
+mechanical apply-the-rubric step — no new logic.
+
+**Per-category signals** — read from the rubric, summarized here:
+
+| Marker | Anti-pattern | Cheapest signal |
+|--------|--------------|-----------------|
+| ❶ | Hardcoded business data | Bare numeric / version / pricing literal inside `[[ "$output" == *"..."*` that matches a value also defined in `lib/` |
+| ❷ | Over-mocking real boundaries | `function git() {` / `function gh() {` overrides at the top of a unit test |
+| ❸ | Asserting implementation details | `grep '_internal_helper'` against output; assertions on `.roll/internal/*` paths |
+| ❹ | Fixture order coupling | `setup_file` writes shared mutable state without per-test reset |
+| ❺ | Testing private functions | Test sources a `lib/` file and calls a `_underscore_prefixed` helper directly |
+| ❻ | Asserting framework behavior | References to `$BATS_TEST_NUMBER`, `$BATS_SUITE_NAME` in assertions |
+
+**Rate cap — 每轮 ≤ 5 条 test-quality REFACTOR entries**. Same dream cycle may
+emit more than 5 findings; the dream scan must rank by severity (❶ > ❷ > ❸ > ❹ > ❺ > ❻
+and within a class, by occurrence count) and only persist the top 5 to BACKLOG.
+Remaining findings go into the dream log under `## 测试质量` but are not made
+into REFACTOR rows — this prevents the backlog from being drowned in test-debt
+on the first scan after rubric publication.
+
+**REFACTOR entry format** — same as other scans, but tagged with category:
+
+```markdown
+| REFACTOR-XXX | docs: <one-line description> [test-quality:❶] — flagged by dream YYYY-MM-DD | 📋 Todo |
+```
+
+The `[test-quality:❶]` (through `❻`) tag is **required** so downstream filtering
+(e.g. "show me all ❶ items still open") is mechanical. The marker character must
+match the rubric exactly.
+
+**Optional helper** — `bin/dream-test-quality-scan` is a thin shell script
+maintainers can invoke ad-hoc to dry-run the ❶ detector against a single file
+or directory (see `bin/dream-test-quality-scan --help`). The dream skill itself
+does **not** depend on the helper — Scan 7 is the AI agent applying the rubric.
+The helper just exists so a maintainer (or this skill's smoke test) can confirm
+the ❶ heuristic still finds known instances.
+
+#### Dream Log Section (Scan 7)
+
+Add after `## 文档新鲜度` section:
+
+```markdown
+## 测试质量
+- 本轮发现 {N} 项（写入 BACKLOG 的前 5 项见下；剩余 {M} 项仅记录于本日志）
+- ❶ 硬编码业务数据：{count}
+- ❷ 过度 mock：{count}
+- ❸ 断言实现细节：{count}
+- ❹ Fixture 顺序耦合：{count}
+- ❺ 测私有函数：{count}
+- ❻ 断言框架行为：{count}
+{命中文件列表 或 "未发现可治理的测试反模式。"}
+```
+
+## Output
+
+### REFACTOR Entry (.roll/backlog.md)
+
+For each finding that warrants action, append one row to the `## ♻️ Refactor`
+section of .roll/backlog.md:
+
+```markdown
+| REFACTOR-XXX | {one-line description} — flagged by dream {YYYY-MM-DD} | 📋 Todo |
+```
+
+`{one-line description}` 写法：一句人话说清楚"什么地方需要改"以及"不改会怎样"。不写函数名、文件路径、技术方案。例：`loop 状态读取逻辑分散在多处，修一处容易遗漏另一处`。
+
+**Threshold**: only flag items where the fix would meaningfully reduce
+complexity or prevent future bugs. Ignore cosmetic issues.
+
+### Dream Log (.roll/dream/YYYY-MM-DD.md)
+
+Always write a log, even when no REFACTOR entries are created. Output uses
+Chinese to align with roll-brief style — easier for the morning reader to scan
+without context switching:
+
+```markdown
+# Dream Log {YYYY-MM-DD}
+
+## 概要
+- 扫描项：死代码 / 架构漂移 / 裁剪候选 / 新兴模式 / 文档覆盖度 / 文档新鲜度
+- 发现：{N} 项标记，{M} 个 REFACTOR 条目已创建
+
+## 死代码
+{发现内容 或 "未发现死代码。"}
+
+## 架构漂移
+{发现内容 或 "未发现架构漂移。"}
+
+## 裁剪候选
+{发现内容 或 "未发现可裁剪项。"}
+
+## 新兴模式
+{发现内容 或 "未发现可提取的重复模式。"}
+
+## 文档覆盖度
+{发现内容 或 "文档结构符合规范，无缺口。"}
+
+## 文档新鲜度
+- 滞后文档：{N} 个
+- 未记录 ENV 变量：{N} 个
+- 架构文档缺失模块：{N} 个
+{发现内容 或 "文档新鲜度良好，无滞后或缺失项。"}
+
+## 创建的 REFACTOR 条目
+{列表 或 "无。"}
+```
+
+### Commit
+
+扫描完成后立即提交，把 dream 发现纳入 git 历史，便于晨报追溯：
+
+```bash
+git add .roll/backlog.md .roll/dream/YYYY-MM-DD.md
+# 有 REFACTOR 条目时：
+git commit -m "chore: dream scan YYYY-MM-DD — {N} REFACTOR entries"
+# 无发现时：
+git commit -m "chore: dream scan YYYY-MM-DD — no findings"
+git push origin main
+```
+
+- .roll/backlog.md 和 dream 日志必须在**同一个 commit** 里入库，避免出现"REFACTOR 已加但日志找不到"或反过来的撕裂状态
+- 写文件失败时不要执行 commit；保持工作区干净，由调度器负责重试
+- 仅 `.roll/backlog.md` 和 `.roll/dream/YYYY-MM-DD.md` 入 commit，不要顺带带入其他无关变更
+
+## Scheduler Configuration
+
+roll-.dream runs **locally** — it reads the local codebase directly.
+
+### Local cron (default)
+
+Installed automatically via `roll loop on` alongside roll-loop and roll-brief.
+The cron entry is generated using the configured agent — no manual cron editing needed.
+
+## Failure Handling
+
+If the scan fails partway through:
+
+1. Write partial results to `.roll/dream/YYYY-MM-DD.md` with a `## 状态：部分完成` header
+2. Do not write incomplete REFACTOR entries to BACKLOG
+3. Log the error to `~/.shared/roll/dream/error.log`
+
+The scheduler (not this skill) is responsible for retry and human notification.

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

@@ -2,13 +2,15 @@
 hidden: true
 name: roll-.echo
 license: MIT
-description: |
-  Passive intent clarification skill. Automatically activates when user input is vague, rambling, contradictory, or unclear. Restates the user's intent in structured, concise form and confirms before proceeding. Does NOT activate when intent is already clear — in that case, just execute directly.
-  This is a passive skill. Never announce "I'm using roll-.echo." Just do it naturally: restate, confirm, proceed.
+description: "Load when user intent is vague, contradictory, rambling, or unclear and should be restated for confirmation before action."
 ---
-
 # Echo
 
+## Gotchas
+
+- Echo confirms unclear intent; it must not add scope, design decisions, or backlog artifacts on its own.
+- Do not load for clear actionable requests, even if the task is large.
+
 > Passive intent clarification — restate messy thoughts as clear intent, confirm, then act.
 
 ## When to Activate

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

@@ -3,256 +3,45 @@ hidden: true
 name: roll-.qa
 license: MIT
 allowed-tools: "Read"
-description: QA coverage reference for build skills. Defines test pyramid (unit/E2E/visual/smoke), coverage requirements, and CI gates. Ensures quality assurance across all testing layers.
+description: "Load when a build, fix, review, or story needs Roll QA coverage standards: test pyramid, evidence expectations, visual/E2E boundaries, or CI gates."
 ---
+# Roll QA
 
-# QA Cover
+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.
 
-This is a **reference skill** used by `roll-build` and `roll-fix` for quality assurance and test coverage.
+## Load
 
-## When to Apply
-
-Any product with a user interface (Web, Desktop, Mobile) must follow these testing standards.
+Load when a build, fix, review, or story needs Roll QA coverage standards: test pyramid, evidence expectations, visual/E2E boundaries, or CI gates.
 
 ## 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)?
-```
+- Post-TCR code review; load roll-.review.
+- PR review verdicts; load roll-review-pr.
 
-### Step 2: Classify Severity
+## Read On Demand
 
-| 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 |
+- 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.
 
-### Step 3: Create Backlog Entry
+## Workflow Skeleton
 
-```bash
-# For fixable bugs — create FIX entry
-$roll-idea fix "CI: {step} fails — {root cause summary}"
+1. Map risk to unit, integration, E2E, visual, and smoke layers.
+2. Define acceptance evidence per story.
+3. Use the lightest layer that proves the risk.
+4. Escalate coverage when behavior crosses boundaries.
 
-# For flaky/environmental issues — create IDEA entry
-$roll-idea idea "CI: investigate flaky {test name}"
-```
+## Hard Gates
 
-### Step 4: Execute Fix
+- Tests must exercise product code or public entry points.
+- Visual checks require rendered evidence when UI is touched.
 
-```
-FIX-XXX created
-    │
-    ├── Critical / High → $roll-fix FIX-XXX (immediate)
-    ├── Medium → schedule in backlog, $roll-fix when ready
-    └── Low → backlog, fix opportunistically
-```
+## Gotchas
 
-All fixes go through `$roll-fix` TCR workflow — test, fix, review, commit, push, CI green.
+- QA chooses evidence depth; it does not replace story-specific acceptance criteria or TCR test design.
+- Do not use visual/E2E layers as a substitute for focused unit coverage when the risk is pure logic.
 
-## References
+## Maintenance
 
-- [Playwright Docs](https://playwright.dev/)
-- [Visual Regression Guide](https://playwright.dev/docs/test-snapshots)
-- Example implementation: `<owner>/<repo>/e2e/`
+- 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.