@seanyao/roll 2026.512.6 → 2026.512.7

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## v2026.512.7
+- **Added**: `roll alert` — 查看、确认、清除 loop 告警，不用再去翻 loop status
+- **Added**: macOS 系统通知 — story 完成或告警写入时自动弹通知，静音模式下不打扰
+- **Added**: `roll ci [--wait]` — 查看当前提交的 CI 状态，或等待 CI 跑完再继续
+- **Fixed**: loop 现在会等 CI 通过后才标记故事完成，CI 失败则保持进行中并发出提醒
+- **Fixed**: changelog 更新不再产生独立 commit，并入故事完成提交，git log 更干净
+- **Added**: `docs/domain/` — Roll 架构的 DDD 领域模型文档（5 个 Bounded Context + 自治操作 Aggregate 设计）
+- **Fixed**: `roll loop runs` 不再报"当前项目尚无运行记录"，历史记录正常显示
+- **Added**: 文档目录重组 — methodology、skill 选择指南、loop 验证记录迁移至 `docs/guide/` 和 `docs/practices/`，根目录不再有散落文件
+- **Added**: README 大幅精简并新增文档导航索引 — 首页更清晰，所有指南一表可查
+- **Added**: dream 每晚自动检测文档缺口，brief 新增文档覆盖率数字
+
 ## v2026.512.6
 - **Added**: peer review 现在也会自动弹出终端窗口，实时观察跨 AI 协商过程（mute 关闭同一开关）
 - **Added**: `docs/guide/en/` — loop/dream/peer 英文用户指南上线，覆盖所有子命令和使用场景

package/README.md

@@ -19,262 +19,75 @@
 
 ## What is Roll?
 
-Roll solves a specific problem: when developers on the same team use different AI clients (Claude Code, Cursor, Gemini CLI, Kimi, Codex, DeepSeek, Pi, OpenCode, Trae), each agent operates under different engineering constraints. One developer's Claude runs tests another's Cursor never even considers.
+Roll is an instruction and workflow framework for AI agents — it encodes proven engineering practices (TDD, TCR, SRE, INVEST) as skills any agent can follow, distributes unified conventions to every AI client on your machine, and optionally lets the agent work unattended via an autonomous evolution layer.
 
-Roll fixes this through three mechanisms:
-
-1. **Convention CLI** — a single source of engineering conventions distributed to every AI client on the machine (`~/.claude/`, `~/.cursor/`, `~/.gemini/`, `~/.kimi/`, `~/.codex/`, `~/.deepseek/`, etc.)
-2. **Skill System** — 20 proven engineering practices (TDD, TCR, SRE, INVEST, DDD) encoded as instructions that any AI agent can follow
-3. **Autonomous Evolution** — an optional layer that lets the agent work unattended: `roll-loop` executes BACKLOG items hourly, `roll-.dream` scans code health nightly, and `roll-brief` briefs the human each morning. The human retains sole authority over releases.
-
-The result: any agent, any client, same constraints — and optionally, continuous autonomous delivery.
-
----
-
-## Start Here
-
-Before commands and skills, read the Engineering Methodology — it explains the three-loop architecture (Research → Build → Observe), the autonomous evolution layer, why each skill exists, and how they connect into a complete delivery system.
-
-**[English](docs/methodology-en.md)** · **[中文](docs/methodology.md)**
+**Three core values:**
+1. **Any agent, same constraints** — Claude, Cursor, Kimi, DeepSeek, Codex all receive identical engineering guardrails
+2. **Skill system** — 20 skills encode research → design → build → check → fix as reliable, repeatable workflows
+3. **Autonomous evolution** — `roll loop on` runs BACKLOG items hourly; humans retain sole release authority
 
 ---
 
-## Installation
+## Quick Start (30 seconds)
 
 ```bash
 npm install -g @seanyao/roll
-roll setup
+roll setup          # distribute conventions to all AI clients
+cd my-project
+roll init           # create AGENTS.md + BACKLOG.md + docs/features/
+roll loop on        # optional: let the agent work unattended
 ```
 
 **Requirements:** bash 4+, Node.js 16+
 
-To update:
-
-```bash
-roll update
-```
-
-> **For contributors** (working on roll itself): `git clone https://github.com/seanyao/roll.git && cd roll && ./install.sh`
-
 ---
 
-## Convention Management
+## Documentation Index
 
-Unified behavioral conventions for Claude Code / Gemini CLI / Cursor / Kimi / Codex / DeepSeek / Pi / OpenCode / Trae — all from one source.
+| Topic | English | 中文 |
+|-------|---------|------|
+| Overview & architecture | [guide/en/overview.md](docs/guide/en/overview.md) | [guide/zh/overview.md](docs/guide/zh/overview.md) |
+| Engineering methodology | [guide/en/methodology.md](docs/guide/en/methodology.md) | [guide/zh/methodology.md](docs/guide/zh/methodology.md) |
+| Loop (autonomous executor) | [guide/en/loop.md](docs/guide/en/loop.md) | [guide/zh/loop.md](docs/guide/zh/loop.md) |
+| Dream (nightly health scan) | [guide/en/dream.md](docs/guide/en/dream.md) | [guide/zh/dream.md](docs/guide/zh/dream.md) |
+| Peer (cross-agent review) | [guide/en/peer.md](docs/guide/en/peer.md) | [guide/zh/peer.md](docs/guide/zh/peer.md) |
+| Skill selection guide | [guide/en/skills.md](docs/guide/en/skills.md) | [guide/zh/skills.md](docs/guide/zh/skills.md) |
+| Domain model (DDD) | [domain/context-map.md](docs/domain/context-map.md) | — |
+| Engineering common sense | [practices/engineering-common-sense.md](docs/practices/engineering-common-sense.md) | — |
 
-### Commands
+---
 
-Commands fall into two categories: **bash commands** run pure shell logic; **agent commands** (marked with 🤖) launch a full AI agent session to execute a SKILL.md.
+## Commands
 
 | Command | Description |
 |---------|-------------|
-| `roll setup [-f]` | First-time install on this machine, or re-sync (use `--force` to overwrite local cache) |
-| `roll update` | One-step upgrade: `npm install -g @seanyao/roll@latest` + re-sync via setup |
-| `roll init` | New project: create `AGENTS.md` + `BACKLOG.md` + `docs/features/` |
-| `roll status` | Show sync state, skill links, and detected AI tools |
-| `roll backlog` | Show all pending tasks from BACKLOG.md |
-| `roll agent [use <name>\|list]` | Per-project agent selection — affects all 🤖 commands |
-| `roll loop <on\|off\|now\|status\|monitor\|resume\|reset>` | 🤖 Manage the autonomous BACKLOG executor (three-service: loop/dream/brief) |
-| `roll brief` | 🤖 Show latest owner brief (regenerate if stale >24h) |
-| `roll peer` | 🤖 Cross-agent code review and negotiation |
-| `roll release` | 🤖 Sync changelog + version bump + tag + npm publish + GitHub Release |
-| `roll` _(no args, in project dir)_ | Dashboard: loop status, pending count, latest brief summary |
-
-### Typical Flow
-
-```bash
-# 1. Install on this machine
-npm install -g @seanyao/roll
-roll setup
-
-# 2. Initialize a project (run from project root)
-cd my-app
-roll init
-
-# 3. Upgrade to a new release
-roll update
-
-# 4. Enable autonomous evolution (optional)
-roll loop on                  # three services: loop (hourly) + dream (nightly) + brief (daily)
-roll loop monitor             # real-time top-like dashboard
-roll brief                    # read the latest digest
-
-# 5. Switch agent per project
-roll agent use kimi           # all 🤖 commands now use kimi for this project
-```
-
-### How Convention Layering Works
-
-```
-Global  ~/.claude/CLAUDE.md         ← user-owned; roll setup appends @roll.md
-        ~/.claude/roll.md            ← Roll conventions (written by roll setup/sync)
-  ↓  auto-stacked
-Project <project>/AGENTS.md         ← generated by roll init
-        <project>/.claude/CLAUDE.md
-```
-
-Global conventions are additive and never overwrite existing files. Project conventions are injected per project via `roll init`.
-
-### Directory Layout
-
-```
-~/.roll/
-├── config.yaml                  # sync path configuration
-└── conventions/
-    ├── global/                  # single source of truth
-    │   ├── AGENTS.md
-    │   ├── CLAUDE.md / GEMINI.md / .cursor-rules
-    └── templates/               # project type templates
-        ├── fullstack/
-        ├── frontend-only/
-        ├── backend-service/
-        └── cli/
-```
-
----
-
-## Skill System
-
-Skills are instructions that encode proven engineering practices into a form AI agents can reliably follow. They live in `~/.roll/skills/` and are symlinked into each AI client's skill directory on `roll setup`.
-
-### Workflow
-
-```
-Research → Design → Build → Check → Fix → (loop)
-```
-
-### Quick Reference
-
-| Scenario | Skill |
-|----------|-------|
-| Uncertain approach, need to think it through | `$roll-design "topic"` |
-| Execute a planned Story | `$roll-build US-001` |
-| Free-form feature request | `$roll-build "add search to admin"` |
-| Bug fix | `$roll-fix FIX-001` |
-| Fast backlog capture (bug / idea) | `$roll-idea "description"` |
-| High-risk logic (payments, auth, state machines) | `$roll-spar "feature"` |
-| Deep research (product / company / tech) | `$roll-research "subject"` |
-| Cross-agent code review | `$roll-peer` |
-| Patrol production for regressions | `$roll-sentinel patrol` |
-| Debug a broken page | `$roll-debug <URL>` |
-| Record a dev moment / diary entry | `$roll-notes "just fixed that nasty bug"` |
-| Let the agent work overnight | `roll loop on` |
-
-### Full Skill List
-
-**Loop A — Research & Design**
-
-| Skill | Description |
-|-------|-------------|
-| `$roll-research` | HV Analysis (Horizontal-Vertical) deep research framework, outputs PDF report |
-| `$roll-design` | Multi-turn discuss → [peer review] → DDD model → solution design → [peer review] → write Stories to BACKLOG |
-
-**Loop B — Implementation & Iteration**
-
-| Skill | Description |
-|-------|-------------|
-| `$roll-build` | Universal entry: Story ID, fix ID, or free-text fly mode. TCR-driven micro-commits |
-| `$roll-spar` | Adversarial TDD — Attacker writes tests, Defender writes code |
-| `$roll-fix` | Bug fix / hotfix from BACKLOG |
-| `$roll-release` | One-command publish: auto version (YYYY.MMDD.N) → tag → npm publish → GitHub Release |
-| `$roll-peer` | Cross-agent code review — Claude / Kimi / DeepSeek / Codex bilateral negotiation |
-
-**Loop C — Observability & Maintenance**
-
-| Skill | Description |
-|-------|-------------|
-| `$roll-sentinel` | Randomized production patrol with adaptive hot-spot weighting |
-| `$roll-debug` | Deep page diagnostics + root cause analysis (Black Box probe) |
-
-**Autonomous Evolution (optional, via `roll loop on`)**
-
-| Skill | Description |
-|-------|-------------|
-| `$roll-loop` | Hourly BACKLOG executor — routes US/FIX/REFACTOR to the right skill, enforces TCR |
-| `$roll-.dream` | Nightly code health scan — dead code, architectural drift → REFACTOR entries |
-| `$roll-brief` | Owner-facing digest — what's done, what's pending, release readiness verdict |
-
-**Passive Support**
-
-| Skill | Description |
-|-------|-------------|
-| `$roll-.review` | Pre-commit multi-dimensional self code review |
-| `$roll-.qa` | Test pyramid and coverage standards reference |
-| `$roll-.changelog` | Auto-generate CHANGELOG from BACKLOG |
-| `$roll-.echo` | Passive intent clarification |
-| `$roll-.clarify` | Passive scope clarification for vague build requests |
-| `$roll-idea` | Fast capture a bug or idea into BACKLOG.md |
-| `$roll-notes` | Project diary — append dev moments to `notes/YYYY-MM-DD.md` |
-| `$roll-doctor` | One-command dev toolchain health check |
-
----
-
-## Autonomous Evolution
-
-Off by default. Enable with `roll loop on` to let the agent work unattended on your project.
-
-```
-┌─────────────────────────────────────────────────────────┐
-│  Base layer (always active)                             │
-│  $roll-design → $roll-build → $roll-fix → $roll-spar   │
-│  Human drives every action                              │
-├─────────────────────────────────────────────────────────┤
-│  Autonomous layer (opt-in: roll loop on)                │
-│  roll-loop   — hourly BACKLOG executor                  │
-│  roll-.dream — nightly code health scan                 │
-│  roll-brief  — daily morning digest + release readiness │
-│  Human reviews briefs; retains sole release authority   │
-└─────────────────────────────────────────────────────────┘
-```
-
-Three services are scheduled via macOS launchd (Linux: crontab) and managed as a unit:
-
-- **roll-loop** runs hourly, picks up `📋 Todo` items from BACKLOG, routes them (`US-XXX → $roll-build`, `FIX-XXX → $roll-fix`, `REFACTOR-XXX → $roll-build`), and enforces TCR discipline — if a story completes with zero `tcr:` micro-commits, it reverts to Todo with an ALERT.
-- **roll-.dream** runs nightly, scanning for dead code, architectural drift, and refactoring opportunities. Outputs `REFACTOR-XXX` entries to BACKLOG.
-- **roll-brief** runs each morning (or on-demand via `roll brief`), producing an owner-facing digest with a release-readiness verdict.
-
-The autonomous layer **never** invokes `roll-release`. Production deployment is always a human decision.
-
-Use `roll loop monitor` for a real-time `top`-like view of all three services: launchd status, current execution state, pending queue, alerts, and live log tail.
-
-Per-project agent configuration: `roll agent use <name>` writes `.roll.yaml` so each project can use a different AI client (claude / kimi / deepseek / pi / codex / opencode). Lookup order: `.roll.yaml` → `~/.roll/config.yaml` → `claude` (default).
-
----
-
-## Project Structure (`roll init`)
-
-```
-my-project/
-├── AGENTS.md            # Project constraints & skill routing
-├── BACKLOG.md           # Story and bug index
-├── docs/features/       # Story details and specs
-└── ... your project files
-```
+| `roll setup [-f]` | First-time install or re-sync conventions to all AI clients |
+| `roll update` | Upgrade to latest version |
+| `roll init` | Initialize project: AGENTS.md + BACKLOG.md + docs/features/ |
+| `roll status` | Show sync state, skill links, detected AI tools |
+| `roll backlog` | Show pending tasks from BACKLOG.md |
+| `roll loop <on\|off\|now\|status\|monitor>` | 🤖 Manage autonomous executor |
+| `roll brief` | 🤖 Show latest owner digest |
+| `roll peer` | 🤖 Cross-agent code review |
+| `roll release` | 🤖 Version + tag + npm publish + GitHub Release |
 
 ---
 
 ## Contributing
 
-Contributions are welcome. Roll is a small focused tool — keep PRs focused on one thing.
-
-1. Fork the repo and create a branch from `main`
-2. Make your changes with tests where applicable (`tests/`)
-3. Ensure `./bin/roll --help` output is correct
-4. Open a pull request with a clear description
+PRs welcome. Keep them focused on one thing. For larger changes, open an issue first.
 
-For larger changes, open an issue first to discuss the approach.
+1. `git clone https://github.com/seanyao/roll.git && cd roll && ./install.sh`
+2. Make changes with bats tests (`tests/`)
+3. Run `npm test` before pushing
 
 ---
 
 ## Acknowledgments
 
-Roll builds on ideas and inspiration from the open-source community:
-
-- **[khazix-skills](https://github.com/KKKKhazix/khazix-skills)** by Digital Life Khazix — The HV Analysis (Horizontal-Vertical Analysis) deep research framework and schema used by `$roll-research` are derived from this project, used under the MIT License. Copyright (c) 2026 数字生命卡兹克.
-- **[superpowers](https://github.com/obra/superpowers)** by Jesse Vincent — A composable skills library for AI coding agents that informed several workflow patterns in Roll.
+- **[khazix-skills](https://github.com/KKKKhazix/khazix-skills)** by Digital Life Khazix — HV Analysis framework used by `$roll-research`, MIT License.
+- **[superpowers](https://github.com/obra/superpowers)** by Jesse Vincent — composable skills library that inspired several Roll workflow patterns.
 
 ---
 
-## License
-
-MIT
+MIT License

package/bin/roll

@@ -4,7 +4,7 @@ set -euo pipefail
 # Roll — AI Agent Convention Manager
 # Single source of truth for how all AI coding agents behave.
 
-VERSION="2026.512.6"
+VERSION="2026.512.7"
 ROLL_HOME="${ROLL_HOME:-${HOME}/.roll}"
 ROLL_CONFIG="${ROLL_HOME}/config.yaml"
 ROLL_GLOBAL="${ROLL_HOME}/conventions/global"
@@ -117,6 +117,18 @@ _get_ai_tools() {
   done
 }
 
+# Iterate all configured AI tools, calling: callback entry ai_dir ai_config ai_src [extra_args...]
+_for_each_ai_tool() {
+  local _feach_cb="$1"; shift
+  while IFS= read -r _feach_entry; do
+    "$_feach_cb" "$_feach_entry" \
+      "$(_ai_dir "$_feach_entry")" \
+      "$(_ai_config "$_feach_entry")" \
+      "$(_ai_src "$_feach_entry")" \
+      "$@"
+  done < <(_get_ai_tools)
+}
+
 # Add any ai_* keys from the default set that are missing from the user's config.
 # Non-destructive: never removes or modifies existing entries.
 _ensure_config_entries() {
@@ -505,16 +517,14 @@ _sync_convention_for_tool() {
   fi
 }
 
+_sync_one_tool() {
+  local _entry="$1" _ai_dir="$2" _cfg="$3" _src="$4" force="$5"
+  _sync_convention_for_tool "$ROLL_GLOBAL/$_src" "$_ai_dir/$_cfg" "$force"
+}
+
 _sync_conventions() {
   local force="${1:-false}"
-
-  while IFS= read -r entry; do
-    local ai_dir config_file src_file
-    ai_dir="$(_ai_dir "$entry")"
-    config_file="$(_ai_config "$entry")"
-    src_file="$(_ai_src "$entry")"
-    _sync_convention_for_tool "$ROLL_GLOBAL/$src_file" "$ai_dir/$config_file" "$force"
-  done < <(_get_ai_tools)
+  _for_each_ai_tool _sync_one_tool "$force"
 }
 
 # ─── Internal: sync skills (pull + link) ──────────────────────────────────────
@@ -1038,22 +1048,10 @@ scan_project_type_from_files() {
   fi
 }
 
-# ─── Helper: true when cwd has no existing source code ───────────────────────
-is_fresh_project() {
-  local dir="${1:-.}"
-  ! ( [[ -f "$dir/package.json" ]] || [[ -f "$dir/go.mod" ]] || \
-      [[ -f "$dir/Cargo.toml" ]] || [[ -f "$dir/requirements.txt" ]] || \
-      [[ -f "$dir/pyproject.toml" ]] || \
-      [[ -d "$dir/src" ]] || [[ -d "$dir/api" ]] || [[ -d "$dir/app" ]] )
-}
-
-# ─── Helper: make a scaffold dir + .gitkeep ───────────────────────────────────
-_mkscaffold() { mkdir -p "$1"; touch "$1/.gitkeep"; }
-
 # ─── Helper: write starter BACKLOG.md (no-op if exists) ──────────────────────
 _write_backlog() {
   if [[ -f "$1" ]]; then
-    _WK_MERGE_SUMMARY+=("unchanged|BACKLOG.md")
+    _ROLL_MERGE_SUMMARY+=("unchanged|BACKLOG.md")
     return
   fi
   cat > "$1" << 'EOF'
@@ -1068,18 +1066,18 @@ _write_backlog() {
 |----|---------|--------|
 EOF
   ok "Created: BACKLOG.md"
-  _WK_MERGE_SUMMARY+=("created|BACKLOG.md")
+  _ROLL_MERGE_SUMMARY+=("created|BACKLOG.md")
 }
 
 _ensure_features_dir() {
   if [[ -d "$1" ]]; then
-    _WK_MERGE_SUMMARY+=("unchanged|docs/features/")
+    _ROLL_MERGE_SUMMARY+=("unchanged|docs/features/")
     return
   fi
 
   mkdir -p "$1"
   ok "Created: docs/features/"
-  _WK_MERGE_SUMMARY+=("created|docs/features/")
+  _ROLL_MERGE_SUMMARY+=("created|docs/features/")
 }
 
 # ─── Helper: write starter .gitignore (no-op if exists) ──────────────────────
@@ -2266,7 +2264,8 @@ cmd_loop() {
     pause)   _loop_pause ;;
     resume)  _loop_resume ;;
     reset)   _loop_reset ;;
-    *) err "Usage: roll loop <on|off|now|test|status|monitor|runs|attach|mute|unmute|pause|resume|reset>"; exit 1 ;;
+    notify)  _notify "${1:-roll}" "${2:-}" ;;
+    *) err "Usage: roll loop <on|off|now|test|status|monitor|runs|attach|mute|unmute|pause|resume|reset|notify>"; exit 1 ;;
   esac
 }
 
@@ -2484,7 +2483,7 @@ _loop_status() {
   else
     echo -e "  Auto-attach  ${GREEN}live${NC}    run: roll loop mute"
   fi
-  [[ -f "$_LOOP_ALERT" ]] && { echo ""; echo -e "  ${RED}⚠ ALERT:${NC}"; sed 's/^/    /' "$_LOOP_ALERT"; }
+  [[ -f "$_LOOP_ALERT" ]] && { echo ""; echo -e "  ${RED}⚠ ALERT${NC}  (${CYAN}roll alert${NC} to manage)"; sed 's/^/    /' "$_LOOP_ALERT"; }
   [[ -f "$_LOOP_STATE" ]] && { echo ""; echo "  State:"; sed 's/^/    /' "$_LOOP_STATE"; }
   echo ""
 }
@@ -2683,6 +2682,16 @@ _loop_runs() {
   done <<<"$recent"
 }
 
+# Send a macOS system notification. No-op when muted, non-macOS, or osascript unavailable.
+_notify() {
+  local title="${1:-roll}"
+  local body="${2:-}"
+  [ "$(uname)" = "Darwin" ] || return 0
+  [ -f "$_LOOP_MUTE_FILE" ] && return 0
+  command -v osascript >/dev/null 2>&1 || return 0
+  osascript -e "display notification \"${body}\" with title \"${title}\"" >/dev/null 2>&1 || true
+}
+
 # Count `tcr:` prefixed commits in the current git repo since started_at timestamp.
 _loop_tcr_count() {
   local started_at="$1"
@@ -2690,6 +2699,87 @@ _loop_tcr_count() {
     | awk '/^[a-f0-9]+ tcr:/{n++} END{print n+0}'
 }
 
+# Poll gh run list until current commit's CI completes.
+# Returns 0 on success or when gh is unavailable (graceful skip).
+# Returns 1 on CI failure or timeout.
+_ci_wait() {
+  local timeout="${1:-300}"
+  local interval=15
+  local elapsed=0
+
+  command -v gh &>/dev/null || { warn "gh not installed — skipping CI gate  gh 未安装，跳过 CI 检查"; return 0; }
+
+  local commit; commit=$(git rev-parse HEAD 2>/dev/null) || { err "Not a git repo  非 git 仓库"; return 1; }
+  local short; short=$(git rev-parse --short HEAD 2>/dev/null)
+
+  ok "Waiting for CI on ${short}  等待 CI: ${short}"
+
+  while (( elapsed < timeout )); do
+    local runs
+    runs=$(gh run list --commit "$commit" --json status,conclusion 2>/dev/null) || {
+      warn "gh run list failed — skipping CI gate"
+      return 0
+    }
+
+    if [[ -z "$runs" || "$runs" == "[]" ]]; then
+      (( elapsed == 0 )) && echo "  No CI runs found yet, waiting...  尚无 CI 记录，等待触发..."
+      sleep "$interval"
+      elapsed=$(( elapsed + interval ))
+      continue
+    fi
+
+    local pending
+    pending=$(echo "$runs" | jq -r '[.[] | select(.status != "completed")] | length' 2>/dev/null || echo "0")
+
+    if [[ "$pending" -gt 0 ]]; then
+      printf "  ⏳ CI running (%ds)...  CI 运行中（%ds）...\n" "$elapsed" "$elapsed"
+      sleep "$interval"
+      elapsed=$(( elapsed + interval ))
+      continue
+    fi
+
+    local failed
+    failed=$(echo "$runs" | jq -r '[.[] | select(.conclusion != "success" and .conclusion != "skipped" and .conclusion != null)] | length' 2>/dev/null || echo "0")
+
+    if [[ "$failed" -gt 0 ]]; then
+      err "CI failed for ${short}  CI 失败: ${short}"
+      return 1
+    fi
+
+    ok "CI passed  CI 通过"
+    return 0
+  done
+
+  warn "CI timed out after ${timeout}s  CI 等待超时（${timeout}s）"
+  return 1
+}
+
+# CI gate before marking a story Done.
+# On CI failure: writes ALERT, returns 1 (caller keeps story 🔨 In Progress).
+# When gh unavailable: returns 0 (graceful skip).
+_loop_enforce_ci() {
+  local story_id="$1"
+
+  _ci_wait 300 && return 0
+
+  mkdir -p "$(dirname "$_LOOP_ALERT")"
+  cat > "$_LOOP_ALERT" << EOF
+# ALERT — CI gate failed
+
+**Time**: $(date '+%Y-%m-%d %H:%M')
+**Story**: ${story_id}
+**Commit**: $(git rev-parse --short HEAD 2>/dev/null || echo unknown)
+**Reason**: CI did not pass — story kept as 🔨 In Progress  CI 未通过，故事保持进行中
+
+**Action required** (choose one):
+- Fix CI and re-run: \`roll loop now\`
+- Take over manually: \`\$roll-build ${story_id}\`
+- Reset and retry: \`roll loop reset\` then \`roll loop now\`
+EOF
+  _notify "roll ⚠ CI Failed" "${story_id}: CI did not pass"
+  return 1
+}
+
 # Verify TCR rhythm after a story completes. Returns 0 if ok, 1 if no TCR commits.
 # On failure: reverts story in BACKLOG.md to 📋 Todo and writes ALERT.
 _loop_enforce_tcr() {
@@ -2722,6 +2812,7 @@ _loop_enforce_tcr() {
 - Take over manually: \`\$roll-build ${story_id}\`
 - Reset and retry: \`roll loop reset\` then \`roll loop now\`
 EOF
+    _notify "roll ⚠ TCR Failed" "${story_id}: no tcr: commits found"
     return 1
   fi
 
@@ -2802,7 +2893,7 @@ _loop_monitor() {
     # Alert
     if [[ -f "$_LOOP_ALERT" ]]; then
       echo ""
-      echo -e "  ${RED}⚠ ALERT:${NC}"
+      echo -e "  ${RED}⚠ ALERT${NC}  (${CYAN}roll alert${NC} to manage)"
       sed 's/^/    /' "$_LOOP_ALERT"
     fi
 
@@ -2973,6 +3064,88 @@ _backlog_extract_id() {
   fi
 }
 
+# ═══════════════════════════════════════════════════════════════════════════════
+# CI — check or wait for current commit's CI status
+# ═══════════════════════════════════════════════════════════════════════════════
+# ALERT — view / ack / resolve loop alert lifecycle
+# ═══════════════════════════════════════════════════════════════════════════════
+
+cmd_alert() {
+  local subcmd="${1:-list}"
+  shift || true
+
+  case "$subcmd" in
+    list|"")
+      if [[ ! -f "$_LOOP_ALERT" ]]; then
+        ok "No active alerts  暂无告警"
+        return 0
+      fi
+      echo -e "${BOLD}Active Alert  当前告警${NC}"
+      echo ""
+      cat "$_LOOP_ALERT"
+      echo ""
+      echo -e "  Run '${CYAN}roll alert ack${NC}' to acknowledge, '${CYAN}roll alert resolve${NC}' to clear."
+      echo -e "  运行 'roll alert ack' 确认告警，'roll alert resolve' 清除告警。"
+      ;;
+    ack)
+      if [[ ! -f "$_LOOP_ALERT" ]]; then
+        warn "No active alerts to acknowledge  暂无待确认告警"
+        return 0
+      fi
+      local ts; ts=$(date '+%Y-%m-%d %H:%M:%S')
+      {
+        echo ""
+        echo "**Acknowledged**: ${ts}"
+      } >> "$_LOOP_ALERT"
+      ok "Alert acknowledged at ${ts}  告警已确认"
+      ;;
+    resolve|clear)
+      if [[ ! -f "$_LOOP_ALERT" ]]; then
+        ok "No active alerts  暂无告警"
+        return 0
+      fi
+      rm -f "$_LOOP_ALERT"
+      ok "Alert resolved and cleared  告警已解决并清除"
+      ;;
+    *)
+      err "Unknown subcommand: $subcmd  未知子命令: $subcmd"
+      echo "  Usage: roll alert [list|ack|resolve]"
+      echo "  用法: roll alert [list|ack|resolve]"
+      return 1
+      ;;
+  esac
+}
+
+# ═══════════════════════════════════════════════════════════════════════════════
+
+cmd_ci() {
+  local wait_mode=false
+  local timeout=300
+
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      --wait) wait_mode=true; shift ;;
+      --timeout=*) timeout="${1#*=}"; shift ;;
+      *) err "Usage: roll ci [--wait] [--timeout=N]  用法: roll ci [--wait] [--timeout=N]"; exit 1 ;;
+    esac
+  done
+
+  if $wait_mode; then
+    _ci_wait "$timeout"
+    return
+  fi
+
+  command -v gh &>/dev/null || { warn "gh not installed  gh 未安装"; return 0; }
+  local commit; commit=$(git rev-parse HEAD 2>/dev/null) || { err "Not a git repo  非 git 仓库"; return 1; }
+  local runs
+  runs=$(gh run list --commit "$commit" --json status,conclusion,name 2>/dev/null) || { warn "gh run list failed"; return 0; }
+  if [[ -z "$runs" || "$runs" == "[]" ]]; then
+    echo "No CI runs for $(git rev-parse --short HEAD)  当前提交无 CI 记录"
+    return 0
+  fi
+  echo "$runs" | jq -r '.[] | "\(.name): \(.status)/\(.conclusion)"'
+}
+
 cmd_backlog() {
   local backlog="BACKLOG.md"
   if [[ ! -f "$backlog" ]]; then
@@ -3193,7 +3366,7 @@ _dashboard() {
   else
     echo -e "  Loop  ${YELLOW}○ off${NC}   run: roll loop on"
   fi
-  [[ -f "$_LOOP_ALERT" ]] && echo -e "  ${RED}⚠ ALERT — run: roll loop status${NC}"
+  [[ -f "$_LOOP_ALERT" ]] && echo -e "  ${RED}⚠ ALERT — run: roll alert${NC}"
 
   # Backlog summary
   if [[ -f "BACKLOG.md" ]]; then
@@ -3253,6 +3426,7 @@ usage() {
   echo "  backlog unblock <pat>         Restore matching items to 📋 Todo   恢复为待处理"
   echo "  agent [use <name>|list]   [Config] Per-project agent selection            切换项目 agent"
   echo "  release                [Publish] Sync changelog + version bump + npm publish  同步日志并发版"
+  echo "  ci [--wait]            [CI] Show or wait for current commit's CI status       查看/等待 CI 状态"
   echo ""
   echo "Examples / 示例:"
   echo "  roll setup                    # New machine: first-time install            新机器首次安装"
@@ -3280,8 +3454,10 @@ main() {
     loop)          cmd_loop "$@" ;;
     brief)         cmd_brief "$@" ;;
     backlog)       cmd_backlog "$@" ;;
+    alert)         cmd_alert "$@" ;;
     agent)         cmd_agent "$@" ;;
     release)       cmd_release "$@" ;;
+    ci)            cmd_ci "$@" ;;
     version|--version|-v) echo "roll v${VERSION}" ;;
     help|--help|-h) usage ;;
     "") [[ -f "BACKLOG.md" ]] && _dashboard || { usage; _show_changelog; } ;;

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@seanyao/roll",
-  "version": "2026.512.6",
+  "version": "2026.512.7",
   "description": "Roll — Roll out features with AI agents",
   "scripts": {
-    "test": "find tests/unit tests/integration -name '*.bats' | sort | xargs ./tests/helpers/bats-core/bin/bats"
+    "test": "bash tests/run.sh"
   },
   "keywords": [
     "ai",

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

@@ -101,6 +101,19 @@ CHANGELOG 是给**使用者**看的，不是给维护者看的。一句话讲清
 - **Fixed**: 多个 loop 实例不会再互相打架（重复触发自动跳过）
 ```
 
+❌ 说机制不说现象（Fix 类最常犯）：
+```
+- **Fixed**: `roll loop runs` 过滤条件从完整路径改为 slug，历史记录不再因路径不匹配而消失
+- **Fixed**: `roll-loop` skill 写入 `runs.jsonl` 时 project slug 计算方式明确，避免写成 bare basename
+```
+
+✅ 直接说用户看到了什么：
+```
+- **Fixed**: `roll loop runs` 不再报"当前项目尚无运行记录"，历史记录正常显示
+```
+
+Fix 类句式参考：`<命令/功能> 不再 <之前的坏现象>`，或 `<命令/功能> 现在 <正常表现>`。内部有几个 bug 导致这一个现象，合并成一条。
+
 ### 4. Section Header — Always `## Unreleased`
 
 **⚠️ do NOT guess version numbers.** Only `scripts/release.sh` assigns concrete
@@ -152,11 +165,20 @@ version numbers like `v2026.511.8`. Just write to `## Unreleased`.
 
 **Ordering**: Unreleased always at top. Below it, released versions in reverse chronological order.
 
-### 6. Commit Update
+### 6. Stage Update
+
+**Normal path (called from `$roll-build` or `$roll-fix`)**: stage only — the
+caller's completion commit will pick up CHANGELOG.md.
+
+```bash
+git add CHANGELOG.md
+```
+
+**Standalone / manual path** (called outside a roll-build session): stage and commit.
 
 ```bash
 git add CHANGELOG.md
-git commit -m "docs: update changelog for release $(date +%Y.%m.%d)"
+git commit -m "chore: sync changelog"
 git push
 ```
 

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

@@ -97,6 +97,46 @@ Find repeated structures that warrant extraction:
 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 BACKLOG.md for features with multiple ✅ Done stories. For each feature epic, check whether a corresponding `docs/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 docs/guide/en/*.md; do
+  base=$(basename "$f")
+  [ ! -f "docs/guide/zh/$base" ] && echo "missing ZH: $base"
+done
+```
+
+Flag any `docs/guide/en/<topic>.md` that has no matching `docs/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/`).
+
+**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
+## 文档覆盖度
+{发现内容 或 "文档结构符合规范，无缺口。"}
+```
+
 ## Output
 
 ### REFACTOR Entry (BACKLOG.md)
@@ -121,7 +161,7 @@ without context switching:
 # Dream Log {YYYY-MM-DD}
 
 ## 概要
-- 扫描项：死代码 / 架构漂移 / 裁剪候选 / 新兴模式
+- 扫描项：死代码 / 架构漂移 / 裁剪候选 / 新兴模式 / 文档覆盖度
 - 发现：{N} 项标记，{M} 个 REFACTOR 条目已创建
 
 ## 死代码

package/skills/roll-brief/SKILL.md

@@ -78,6 +78,9 @@ From BACKLOG.md and git log, classify all items since last brief:
 - **Queue**: items still 📋 Todo (ordered by priority)
 - **Dream findings**: any REFACTOR entries added by roll-.dream since last brief
 - **Escalations**: any ALERT files in `~/.shared/roll/loop/` or `~/.shared/roll/dream/`
+- **Doc coverage**: compute from `docs/guide/en/` and `docs/guide/zh/`:
+  - EN coverage = number of files in `docs/guide/en/`
+  - ZH translation rate = files in `docs/guide/zh/` ÷ files in `docs/guide/en/` × 100%
 
 ### Step 3 — Assess Release Readiness
 
@@ -132,6 +135,12 @@ A simple heuristic — not a gate, just a signal for the human:
 ## 需人工介入
 {告警内容}
 
+<!-- 始终输出 doc coverage 数字；若无缺口写"覆盖完整" -->
+## 文档覆盖度
+- guide/en: {N} 个文档
+- ZH 翻译率：{M}/{N}（{%}）
+- {缺口列表 或 "覆盖完整，无缺口。"}
+
 ## 发版就绪
 {✅ 可发版 / ⚠️ 暂缓 — 原因}
 

package/skills/roll-build/SKILL.md

@@ -509,17 +509,21 @@ For Fly mode: first append an index row under the appropriate Epic > Feature gro
 
 If the US section does not yet exist, create the full section (AC / Files / Dependencies).
 
+**Before committing, run `$roll-.changelog`** to stage CHANGELOG.md — then include
+it in the completion commit so no separate changelog commit is created.
+
 ```bash
-git add BACKLOG.md docs/features/
+# 1. Stage changelog (roll-.changelog stages CHANGELOG.md only, does not commit)
+$roll-.changelog
+
+# 2. Commit BACKLOG + feature doc + CHANGELOG.md together
+git add BACKLOG.md docs/features/ CHANGELOG.md
 git commit -m "docs: mark {US-ID} as completed"
 git push
 ```
 
 ### Phase 12: Report & Celebrate
 
-**Before reporting, run `$roll-.changelog`** to sync completed Story to CHANGELOG.md.
-This is mandatory — release notes depend on it.
-
 ```
 ✅ Pushed to GitHub: origin/main
 🚀 Deployed: <url>
@@ -530,7 +534,7 @@ This is mandatory — release notes depend on it.
 📊 TCR Stats: <success rate, revert count if any>
 📋 Review Gate: <self-review findings summary>
 📝 BACKLOG: <US-ID> marked ✅ Done
-📄 CHANGELOG: $roll-.changelog → updated
+📄 CHANGELOG: bundled into completion commit (Phase 11)
 
 🎉 Shipped.
 
@@ -604,7 +608,7 @@ Before creating any file or directory:
 - [ ] **Verification Gate passed** (fresh evidence for tests, build, deploy, no regression)
 - [ ] **BACKLOG.md index status updated** (📋 → ✅, REQUIRED)
 - [ ] **`docs/features/<feature>.md` US section updated** (Completed date + [x] ACs, REQUIRED)
-- [ ] **CHANGELOG.md updated** via `$roll-.changelog` (REQUIRED)
+- [ ] **CHANGELOG.md staged and bundled** into completion commit via `$roll-.changelog` in Phase 11 (REQUIRED)
 - [ ] Summary reported to user
 
 ---

package/skills/roll-loop/SKILL.md

@@ -142,9 +142,14 @@ After each item completes:
    - Count `tcr:` prefix commits since `started_at` via `git log --oneline --since=<started_at>`
    - Count == 0 → revert story status in BACKLOG.md from ✅ Done → 📋 Todo; write ALERT to `~/.shared/roll/loop/ALERT.md` with story ID, time, reason "zero tcr: commits since story start", and suggested actions (`roll loop now` / `$roll-build <id>` / `roll loop reset`)
    - Count > 0 → continue normally
-2. Update state file: `status: idle`
-3. Check if a Feature is now fully complete (all its Stories ✅)
-4. If yes and `brief_on_feature_complete: true` → invoke `Skill("roll-brief")`
+2. **CI Gate** — call `roll ci --wait` (or `_loop_enforce_ci <story_id>`):
+   - Polls `gh run list --commit <HEAD>` until all CI runs complete
+   - CI passes → continue normally
+   - CI fails or times out → keep story as `🔨 In Progress` (do NOT mark ✅ Done); write ALERT; skip to next story
+   - `gh` not installed → skip gracefully (return 0)
+3. Update state file: `status: idle`
+4. Check if a Feature is now fully complete (all its Stories ✅)
+5. If yes and `brief_on_feature_complete: true` → invoke `Skill("roll-brief")`
 
 ### Step 5 — Write Run Summary
 
@@ -180,7 +185,7 @@ final report in `cron.log` instead.
 | Field | Type | Format / Enum |
 |---|---|---|
 | `ts` | string | ISO 8601 **UTC** with `Z` suffix. Get via `date -u +%Y-%m-%dT%H:%M:%SZ`. Never use `+08:00` or other offsets. |
-| `project` | string | Project **slug** only (e.g. `roll-d9dfa0`), NOT the absolute path. Derive from `basename` of plist label or `_project_slug` output. |
+| `project` | string | Project **slug** only (e.g. `roll-d9dfa0`), NOT the absolute path and NOT plain `basename`. Compute via: `p=$(pwd -P); base=$(basename "$p" | tr -cs '[:alnum:]' '-' | sed 's/-*$//'); hash=$(printf '%s' "$p" | md5 | cut -c1-6 2>/dev/null || printf '%s' "$p" | md5sum | cut -c1-6); echo "${base}-${hash}"` |
 | `run_id` | string | Matches `state.yaml` `run_id` exactly. Format: `loop-YYYYMMDD-HHMM`. |
 | `status` | enum | Exactly one of: `built` (≥1 story shipped), `idle` (no Todo items found), `failed` (paused/error). **No synonyms.** |
 | `built` | array&lt;string&gt; | Story ids completed this cycle. `[]` when none. **Always array, never null/number.** |
@@ -196,7 +201,13 @@ Optional field, only when `status == "failed"`:
 
 ```bash
 ts=$(date -u +%Y-%m-%dT%H:%M:%SZ)
-project=$(_project_slug "$(pwd -P)")  # must match roll loop runs filter
+# Compute project slug — inlined equivalent of bin/roll's _project_slug
+# (Claude sessions can't call roll's internal functions, so we inline).
+# Must produce identical output to _project_slug to match `roll loop runs` filter.
+_p=$(pwd -P)
+_base=$(basename "$_p" | tr -cs '[:alnum:]' '-' | sed 's/-*$//')
+_hash=$(printf '%s' "$_p" | md5 | cut -c1-6 2>/dev/null || printf '%s' "$_p" | md5sum | cut -c1-6)
+project="${_base}-${_hash}"  # e.g. roll-d9dfa0 — must match roll loop runs filter
 # duration_sec = cycle_end_epoch - cycle_start_epoch (track at Step 1)
 # tcr_count = git log --oneline --since="<cycle_start>" | grep -c '^[a-f0-9]* tcr:'