@seanyao/roll 3.610.1 → 3.610.2

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

@@ -3,372 +3,45 @@ 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.
+description: "Load when a scheduled or manual nightly architecture health scan should inspect code structure, dead code, doc staleness, and refactor candidates."
 ---
+# Roll Dream
 
-# Roll Dream (Nightly Code Health Scan)
+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.
 
-> Follows the Architecture Constraints, Development Discipline, and Engineering
-> Common Sense defined in the project AGENTS.md.
+## Load
 
-**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.
+Load when a scheduled or manual nightly architecture health scan should inspect code structure, dead code, doc staleness, and refactor candidates.
 
-## Distinction from roll-sentinel
+## When Not to Use
 
-| | 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?" |
+- Runtime patrols; load roll-sentinel.
+- Local web debugging; load roll-debug.
 
-## Scan Logic
+## Read On Demand
 
-Run all scans every night. Each scan is independent.
+- 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.
 
-### Scan 1 — Dead Code
+## Workflow Skeleton
 
-Find code that is defined but never referenced:
+1. Scan structure, dead code, drift, and docs.
+2. Classify findings as refactor/doc candidates.
+3. Write daily dream log and backlog candidates.
+4. Keep recommendations human-reviewed.
 
-```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
+## Hard Gates
 
-# 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
-```
+- Do not auto-activate scored findings.
+- Fail loud if the dream skill or project context is missing.
 
-Flag: files or exports with zero references outside their own file.
+## Gotchas
 
-### Scan 2 — Architectural Drift
+- Dream reviews code and architecture health, not live production behavior; use roll-sentinel for runtime patrols.
+- Findings become human-reviewed backlog candidates; do not auto-activate refactors from scoring signals.
 
-Compare current code structure against the domain model in `.roll/domain/`:
+## Maintenance
 
-```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.
+- 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.