@seanyao/roll 3.620.1 → 3.624.1

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

@@ -1,365 +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.
-
----
-
-# 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-audit` (US-SKILL-008) is not yet deployed.
-Check: `[ -f "$ROLL_HOME/skills/roll-doc-audit/SKILL.md" ]`. If absent, log "Scan 6 skipped — roll-doc-audit not deployed" in the dream log and stop. No fallback.
-
-When deployed, each finding produces a REFACTOR entry with `$roll-doc-audit` as execution hint:
-```markdown
-| REFACTOR-XXX | docs: <description> — flagged by dream <date> (hint: $roll-doc-audit) | 📋 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,118 +0,0 @@
----
-hidden: true
-name: roll-.echo
-license: MIT
-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
-
-This skill fires **automatically** when the AI detects unclear intent. It should feel natural — not like a skill invocation, but like a thoughtful colleague saying "let me make sure I got that right."
-
-**Activation signals** (any of these):
-- Input is long and rambling (>3 sentences without a clear ask)
-- Multiple ideas tangled together with no clear priority
-- Contradictory statements ("I want X but also not-X")
-- Hedging language: "maybe", "sort of", "I think", "not sure but", "something like"
-- Vague scope: "make it better", "fix this area", "do something about"
-- The intent could reasonably be interpreted in 2+ very different ways
-
-## 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-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.
-
-## How to Echo
-
-### Step 1: Listen completely
-
-Let the user finish. Don't interrupt a stream of consciousness — the clearest signal often comes at the end.
-
-### Step 2: Distill
-
-Extract the core intent from the noise. Structure it as:
-
-```
-What I'm hearing:
-- **Goal**: {what they want to achieve — one sentence}
-- **Scope**: {what's in / what's out}
-- **Priority**: {if multiple things mentioned, which comes first}
-- **Constraints**: {any specific requirements or limitations mentioned}
-```
-
-Only include fields that are relevant. A simple clarification might just be:
-
-```
-So you want: {one clear sentence restating the intent}
-```
-
-### Step 3: Surface ambiguity (if any)
-
-If there are genuine decision points the user needs to resolve:
-
-```
-One thing I want to confirm: {the specific ambiguity, with 2-3 concrete options}
-```
-
-Don't manufacture ambiguity. If you understood fine, skip this.
-
-### Step 4: Confirm and proceed
-
-End with a natural confirmation prompt, then act on the response:
-- If confirmed → route to the appropriate skill or start working
-- If corrected → update understanding, optionally echo again if the correction introduces new ambiguity
-
-## Style
-
-- **Be brief.** The echo should be shorter than the original input, not longer.
-- **Be concrete.** Replace vague language with specific interpretations. "Make it better" → "Improve the search response time" or "Redesign the search UI."
-- **Be natural.** This is a conversation, not a form. Don't use the template rigidly.
-- **No jargon.** Mirror the user's vocabulary, not technical framework terms.
-- **No patronizing.** Don't echo things that are already obvious. The user will feel like you're not listening.
-
-## Anti-Patterns
-
-- Echoing when intent is already clear (wastes the user's time)
-- Echoing every single message (becomes annoying fast)
-- Adding your own ideas to the echo (scope creep — echo is for understanding, not suggesting)
-- Using the echo as a stall tactic when you should just do the work
-- Turning a simple ask into a complex questionnaire
-
-## Examples
-
-### Good Echo (vague input)
-
-**User**: "I've been thinking about the search, it's kind of slow and the results aren't great, maybe we need elasticsearch or something, and also the UI is weird on mobile, the filters don't work right, I don't know, just... it needs work"
-
-**Echo**: "Got it — sounds like two separate issues: (1) search quality and performance (results aren't relevant + slow), and (2) mobile UI broken filters. Want me to tackle them as two separate stories, or is one more urgent?"
-
-### Good Echo (contradictory input)
-
-**User**: "Make the dashboard simpler, but also add the analytics charts we discussed, and the export feature, oh and notifications"
-
-**Echo**: "Those pull in opposite directions — simpler dashboard vs. adding 3 new features. Which do you mean: strip the current dashboard down and then selectively add these features? Or keep what's there and add the new stuff on top?"
-
-### No Echo Needed (clear input)
-
-**User**: "Add a dark mode toggle to the settings page"
-
-*→ Just do it. No echo needed.*
-
-### No Echo Needed (skill trigger)
-
-**User**: "$roll-design search improvements"
-
-*→ Route to roll-design. No echo needed.*

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

@@ -1,47 +0,0 @@
----
-hidden: true
-name: roll-.qa
-license: MIT
-allowed-tools: "Read"
-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
-
-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 build, fix, review, or story needs Roll QA coverage standards: test pyramid, evidence expectations, visual/E2E boundaries, or CI gates.
-
-## When Not to Use
-
-- Post-TCR code review; load roll-.review.
-- PR review verdicts; load roll-review-pr.
-
-## 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. 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.
-
-## Hard Gates
-
-- Tests must exercise product code or public entry points.
-- Visual checks require rendered evidence when UI is touched.
-
-## Gotchas
-
-- 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.
-
-## 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.