@seanyao/roll 0.5.0 → 2.602.1

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

@@ -0,0 +1,374 @@
+---
+hidden: true
+name: roll-.dream
+license: MIT
+allowed-tools: "Read, Glob, Grep, Bash(git:*, curl:*, claude:*), Write, Edit"
+description: |
+  Nightly code and architecture health scan. Passively triggered by scheduler
+  (cron or GitHub Actions), not invoked by users directly. Detects dead code,
+  architectural drift from domain model, pruning candidates, emerging patterns,
+  doc coverage gaps, and doc staleness (文档新鲜度).
+  Outputs REFACTOR entries to .roll/backlog.md and a daily log to .roll/dream/.
+  Distinct from roll-sentinel: sentinel monitors runtime behavior; dream reviews
+  code structure and architectural health.
+---
+
+# 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

@@ -1,6 +1,7 @@
 ---
 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.
@@ -22,11 +23,13 @@ This skill fires **automatically** when the AI detects unclear intent. It should
 - Vague scope: "make it better", "fix this area", "do something about"
 - The intent could reasonably be interpreted in 2+ very different ways
 
-**Do NOT activate when**:
+## When Not to Use
+
 - Intent is already clear and actionable ("add a login button to the header")
-- User gives a specific command with a skill trigger ("$roll-story US-001")
+- User gives a specific command with a skill trigger ("$roll-build US-001")
 - User is answering a question you asked (they're clarifying, not initiating)
 - The task is simple enough that misinterpretation risk is negligible
+- User needs targeted Q&A to fill specific gaps (use `$roll-.clarify`)
 
 **When in doubt**: If you're 80%+ confident you understand correctly, just execute. Echo is for the 50/50 situations where getting it wrong would waste real effort.
 

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

@@ -1,17 +1,25 @@
 ---
 hidden: true
-name: roll-.qa-cover
+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.
 ---
 
 # QA Cover
 
-This is a **reference skill** used by `roll-story`, `roll-fix`, and `roll-fly` for quality assurance and test coverage.
+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)
@@ -197,8 +205,54 @@ If project lacks Playwright setup:
 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: `seanyao/kids-game/e2e/`
+- Example implementation: `<owner>/<repo>/e2e/`

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

@@ -1,6 +1,8 @@
 ---
 hidden: true
-name: roll-.code-review
+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.
 ---
 
@@ -21,9 +23,15 @@ TCR Loop:
 
 ## When Triggered
 
-- **Auto-triggered**: After each TCR micro-step in `$roll-story` / `$roll-fix` / `$roll-fly`
+- **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
@@ -37,7 +45,9 @@ $roll-.review unstaged
 $roll-.review files src/utils.ts
 ```
 
-## Review Dimensions (6 Core Dimensions)
+## Review Dimensions (7 Core Dimensions)
+
+Original 6 dimensions plus Reuse (added in REFACTOR-022, simplify three-axis integration):
 
 ```
 ┌─────────────────────────────────────────────────────────┐
@@ -46,13 +56,42 @@ $roll-.review files src/utils.ts
 │  ✅ 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 |