@seanyao/roll 2026.519.1 → 2026.519.3

package/CHANGELOG.md

@@ -1,10 +1,55 @@
 # Changelog
 
+## v2026.519.3
+
+### Major
+
+- **`.roll/` 拆为独立私有仓库** — 过程文件（backlog / brief / features / dream / domain / briefs）整体迁入嵌套私有 repo `roll-meta`，主仓只留产品文档。AGENTS.md 新增 §9 说明双 repo 协作约定 `[meta]`
+
+### Improved
+
+- **`.roll/features/` 按 Epic 分组** — features 目录由扁平改为 Epic 子目录，附带 loop 架构经验文档 `[docs]`
+- **站点登陆页对齐 v2.0 架构** — `docs/site/` 文案与 2.0 实际产物对齐，去掉过期描述 `[docs]`
+
+### Fixed
+
+- **loop 异常退出** — dashboard 不再卡在"运行中"，崩溃 / 被 kill / 超时退出都会写下结束标记 `[loop]`
+- **`FIX-065` loop 共享状态隔离** — 测试运行的 loop 不再污染生产 backlog/brief，sandbox 化共享路径 `[loop]`
+
+## v2026.519.2
+
+### Improved
+
+- **`roll init`** — 初始化流程现在显示 6 步编号进度，新建文件用绿色 `+`、合并已有用琥珀 `~`，结尾给三步上手指南 `[loop]`
+
+### Fixed
+
+- **`roll --help` 中 `init` 描述** — 文案从 `+ docs/` 改为 `+ .roll/features/`，对齐 2.0 实际产物和 README；v2 (`lib/roll-help.py`) 与 legacy (`bin/roll`) 两份 help 同步修正 `[FIX-064]`
+
 ## v2026.519.1
 
+### Major（大版本重构）
+
+- **项目结构重组 — 过程文件迁入 `.roll/`** — Phase 1 of Legacy Onboard Epic。`BACKLOG.md`、`PROPOSALS.md`、`docs/{features,briefs,dream,design,domain}/` 全部搬入 `.roll/`；`docs/guide/`、`docs/site/`、`docs/intro/` 上移到根级。一次性 breaking change，迁移指南见 `guide/{en,zh}/migration-2.0.md` `[legacy-onboard]`
+- **新命令 `roll migrate`** — 老项目一键迁到新结构：dry-run 预览 + `git mv` 保留历史 + 单原子 commit + 三态幂等（仅老 / 仅新 / 并存） `[legacy-onboard]`
+- **新版 `roll init` 识别 Legacy 项目** — 检测到现有源码无 `AGENTS.md` 时引导用户进入 onboard 流程：列出本机 AI agent、显式告知 token 消耗、引导运行 `$roll-onboard` `[legacy-onboard]`
+- **新技能 `$roll-onboard`** — 三组九问 ≤ 3 分钟，AI 读懂项目后生成 `.roll/onboard-plan.yaml`，bash 侧 `roll init --apply` 执行 `[legacy-onboard]`
+- **新命令 `roll init --apply`** — 消费 onboard plan 创建 `.roll/` 结构，按用户选择写 `.gitignore`、同步 AI 工具约定 `[legacy-onboard]`
+- **结构强制检测** — 新版 Roll 在老结构项目上拒绝运行 + 引导 `roll migrate`（`setup` / `update` / `version` / `help` / `init` 豁免；`ROLL_SKIP_STRUCTURE_CHECK=1` 旁路） `[legacy-onboard]`
+
+### Improved
+
+- `AGENTS.md` §8 Documentation Conventions 重写匹配新目录结构，明确"过程默认对内、产品默认对外"原则 `[docs]`
+- `guide/{en,zh}/practices/` 收入工程规范文档（原 `docs/practices/engineering-common-sense.md`） `[docs]`
+- 新增 Python 校验器 `lib/roll-plan-validate.py`，验证 onboard plan 完整性、`generated_at` 24h 时效、版本兼容 `[legacy-onboard]`
+
 ### Fixed
 
 - **`roll setup` 后从未开启 loop 的项目** — 不再被 macOS 自动激活、每小时弹出终端窗口 `[loop]`
+- **`_write_backlog` 缺 `mkdir -p` 导致 `cmd_init` 在 `.roll/` 不存在时崩** `[legacy-onboard]`
+- **`release.sh` 多 feature 时 awk `newline in string` 错误** — macOS BSD awk 不容忍 `-v var=多行`；改用 `ENVIRON` 读取 `[release]`
+- **GitHub 仓库改名 Roll → roll** — 内部代码、测试 fixture、文档引用全部同步小写命名 `[chore]`
+- **`.roll/backlog.md` 和 `guide/*` 中残留 `docs/features` 等老路径引用** — Story 5 sed 漏覆盖 `.roll/` 和 `guide/` 文件，dream 巡检发现后补齐 `[legacy-onboard]`
 
 ## v2026.518.4
 

package/README.md

@@ -11,7 +11,7 @@
 
 **[中文版 README](README_CN.md)**
 
-[![Website](https://img.shields.io/badge/Website-seanyao.github.io%2FRoll-blue)](https://seanyao.github.io/Roll/)
+[![Website](https://img.shields.io/badge/Website-seanyao.github.io%2Froll-blue)](https://seanyao.github.io/roll/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 [![npm version](https://img.shields.io/npm/v/@seanyao/roll.svg)](https://www.npmjs.com/package/@seanyao/roll)
 [![CI](https://github.com/seanyao/roll/actions/workflows/ci.yml/badge.svg)](https://github.com/seanyao/roll/actions/workflows/ci.yml)
@@ -28,6 +28,15 @@ Roll is an autonomous delivery system for software teams — AI agents pick stor
 
 _Works with Claude, Cursor, Codex, or your own agent._
 
+## What's New in 2.0 (May 2026)
+
+Roll 2.0 introduces a **process/product split** to keep open-source projects clean:
+
+- **`.roll/` directory convention** — all process artifacts (backlog, features, briefs, dream logs) move out of root into `.roll/`. User-facing `guide/` and `site/` move up to root. Old `docs/` directory disappears.
+- **`roll migrate`** — one-command migration for projects on pre-2.0 layout. `git mv` preserves history, single atomic commit, three-state idempotent.
+- **`$roll-onboard`** — interactive skill for adopting Roll on legacy codebases without rewrites. AI reads your code, asks 9 questions in ≤ 3 minutes, produces a plan; `roll init --apply` executes it.
+- **Three adoption patterns** — `seed` (new project), `graft` (legacy, non-invasive), `replant` (legacy, clean rebuild). See [guide/en/patterns/](guide/en/patterns/).
+
 ## Evolution
 
 Roll didn't start as a framework. It started as a question: *what if the AI didn't just write code, but actually shipped it?*
@@ -54,6 +63,20 @@ roll loop on        # optional: let the agent work unattended
 
 ---
 
+## Adoption Paths
+
+Three ways to bring Roll into a project. Not sure which fits? Just run `roll init` — it detects legacy code and routes you to `$roll-onboard` automatically.
+
+| Path | When to use | How to start |
+|------|-------------|--------------|
+| **Seed** | Brand-new project, starting from zero | `roll init` (the Quick Start path above) |
+| **Graft** | Existing codebase, keep current workflow intact | `roll init` → AI prompts `$roll-onboard` → 9 questions in ≤ 3 min → `roll init --apply` |
+| **Replant** | Existing codebase, ready to realign on Roll conventions | Same as Graft, choose "clean rebuild" during onboarding |
+
+Details: [seed](guide/en/patterns/seed-pattern.md) · [graft](guide/en/patterns/graft-pattern.md) · [replant](guide/en/patterns/replant-pattern.md)
+
+---
+
 ## Documentation Index
 
 | Topic | English | 中文 |
@@ -66,7 +89,7 @@ roll loop on        # optional: let the agent work unattended
 | Configuration (env vars) | [guide/en/configuration.md](guide/en/configuration.md) | [guide/zh/configuration.md](guide/zh/configuration.md) |
 | Skill selection guide | [guide/en/skills.md](guide/en/skills.md) | [guide/zh/skills.md](guide/zh/skills.md) |
 | FAQ (troubleshooting) | [guide/en/faq.md](guide/en/faq.md) | [guide/zh/faq.md](guide/zh/faq.md) |
-| Domain model (DDD) | [domain/context-map.md](.roll/domain/context-map.md) | — |
+| Adoption patterns | [guide/en/patterns/](guide/en/patterns/) | [guide/zh/patterns/](guide/zh/patterns/) |
 | Engineering common sense | [practices/engineering-common-sense.md](guide/en/practices/engineering-common-sense.md) | — |
 
 ---
@@ -75,15 +98,23 @@ roll loop on        # optional: let the agent work unattended
 
 | Command | Description |
 |---------|-------------|
+| **Autonomy · daily use** | |
+| `roll loop <on\|off\|now\|status\|monitor>` | 🤖 Manage the autonomous BACKLOG executor |
+| `roll brief` | 🤖 Show latest owner brief |
+| `roll backlog [block\|defer\|…]` | View and manage pending tasks |
+| `roll peer` | 🤖 Cross-agent negotiation & review |
+| `roll alert` | View / clear loop alerts |
+| **Project · per repo** | |
+| `roll init` | Create AGENTS.md + .roll/backlog.md + .roll/features/ |
+| `roll status` | Show current state and drift |
+| `roll agent [use <name>]` | Per-project agent selection (Claude / Cursor / Codex / Kimi / …) |
+| `roll ci [--wait]` | Show or wait for current commit's CI status |
+| `roll release` | 🤖 Run the release script (human-only) |
+| `roll review-pr <number>` | 🤖 AI-powered code review for a PR |
+| **Machine · global** | |
 | `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 + .roll/backlog.md + .roll/features/ |
-| `roll status` | Show sync state, skill links, detected AI tools |
-| `roll backlog` | Show pending tasks from .roll/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 |
+| `roll update` | Upgrade to latest + re-sync |
+| `roll version` | Print installed roll version |
 
 ---
 

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.519.1"
+VERSION="2026.519.3"
 ROLL_HOME="${ROLL_HOME:-${HOME}/.roll}"
 ROLL_CONFIG="${ROLL_HOME}/config.yaml"
 ROLL_GLOBAL="${ROLL_HOME}/conventions/global"
@@ -917,6 +917,23 @@ _merge_claude_to_project() {
 # Existing AGENTS.md: re-merges global conventions (section-level, non-destructive)
 # ═══════════════════════════════════════════════════════════════════════════════
 cmd_init() {
+  # US-VIEW-008: parse --demo before any side effects so the v2 renderer can
+  # run standalone (no templates, no project mutation).
+  local demo=false
+  local args=()
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      --demo) demo=true; shift ;;
+      *)      args+=("$1"); shift ;;
+    esac
+  done
+  set -- "${args[@]:-}"
+
+  if [[ "${ROLL_UI:-v2}" == "v2" ]] || [[ "$demo" == "true" ]]; then
+    python3 "${ROLL_PKG_DIR}/lib/roll-init.py" --demo
+    if [[ "$demo" == "true" ]]; then return; fi
+  fi
+
   if [[ ! -d "$ROLL_TEMPLATES" ]]; then
     err "No templates found. Run 'roll setup' first.  未找到模板，请先运行 'roll setup'。"
     exit 1
@@ -2326,7 +2343,13 @@ cmd_review_pr() {
   local output
   info "Reviewing PR #${pr_number} with ${agent}..."
   _agent_argv "$agent" text "$prompt" || { err "Unknown agent '${agent}'"; return 1; }
-  output=$("${_AGENT_ARGV[@]}" 2>/dev/null)
+  local _stderr_log; _stderr_log=$(mktemp)
+  output=$("${_AGENT_ARGV[@]}" 2>"$_stderr_log")
+  if [[ -z "$output" && -s "$_stderr_log" ]]; then
+    err "agent ${agent} produced no output. stderr (first 5 lines):"
+    head -5 "$_stderr_log" | sed 's/^/    /' >&2
+  fi
+  rm -f "$_stderr_log"
 
   echo "$output"
 
@@ -2409,6 +2432,13 @@ cmd_agent() {
 # Returns a filesystem-safe slug combining the project basename and a 6-char
 # hash of the full path, ensuring uniqueness across sibling dirs with same name.
 _project_slug() {
+  # US-LOOP-006: cycle wrapper exports ROLL_MAIN_SLUG so any subshell — worktree,
+  # tmp cwd, or unrelated path — writes events / runs.jsonl under the main project
+  # identity instead of fragmenting into tmp-* / cycle-* phantom slugs.
+  if [[ -n "${ROLL_MAIN_SLUG:-}" ]]; then
+    printf '%s' "$ROLL_MAIN_SLUG"
+    return 0
+  fi
   local path="${1:-$(pwd -P 2>/dev/null || pwd)}"
   # FIX-056: normalize path to canonical case on macOS case-insensitive filesystem.
   # Two paths differing only in case point to the same directory; realpath
@@ -2521,6 +2551,35 @@ PYEOF
 }
 
 _LOOP_TAG="# roll-loop"
+# FIX-065: when sourced in a test context with no explicit override, route
+# shared state into a per-process /tmp path instead of falling back to
+# production ~/.shared/roll/. Without this safety net, tests that source
+# bin/roll (directly or via a generated inner runner under /var/folders/)
+# would write ALERT / state / events / runs.jsonl into the live loop
+# daemon's monitored directory and trigger false aborts.
+#
+# Test context is detected via three signals (any one is enough):
+#   1. BATS_TEST_FILENAME is set (works for direct test invocations)
+#   2. The caller's file path lives under /tmp or /var/folders (catches the
+#      generated runner-inner.sh path that bats subprocesses spawn —
+#      BATS_* env can be lost across `bash -l` + nested forks)
+#   3. PWD is under /tmp or /var/folders (catches helpers that cd'd in)
+if [ -z "${_SHARED_ROOT:-}" ]; then
+  _roll_in_test_ctx=0
+  if [ -n "${BATS_TEST_FILENAME:-}" ]; then
+    _roll_in_test_ctx=1
+  else
+    _roll_caller="${BASH_SOURCE[1]:-}"
+    case "$_roll_caller" in /tmp/*|/private/tmp/*|/var/folders/*) _roll_in_test_ctx=1 ;; esac
+    case "$PWD" in /tmp/*|/private/tmp/*|/var/folders/*) _roll_in_test_ctx=1 ;; esac
+  fi
+  if [ "$_roll_in_test_ctx" = 1 ]; then
+    _SHARED_ROOT="${TMPDIR:-/tmp}/roll-test-shared.$$"
+    mkdir -p "${_SHARED_ROOT}/loop"
+    export _SHARED_ROOT
+  fi
+  unset _roll_in_test_ctx _roll_caller
+fi
 : "${_SHARED_ROOT:=${HOME}/.shared/roll}"
 # FIX-052: per-project loop state — ALERT/state/mute were globally shared,
 # causing one project's alerts to surface in another project's session and
@@ -2529,7 +2588,9 @@ _LOOP_TAG="# roll-loop"
 : "${_LOOP_PROJ_SLUG:=$(_project_slug 2>/dev/null || echo default)}"
 : "${_LOOP_STATE:=${_SHARED_ROOT}/loop/state-${_LOOP_PROJ_SLUG}.yaml}"
 : "${_LOOP_ALERT:=${_SHARED_ROOT}/loop/ALERT-${_LOOP_PROJ_SLUG}.md}"
-_LOOP_RUNS="${HOME}/.shared/roll/loop/runs.jsonl"
+# FIX-065: was hardcoded to ${HOME}/.shared/roll/loop/runs.jsonl which ignored
+# _SHARED_ROOT overrides and silently leaked test runs.jsonl writes into prod.
+_LOOP_RUNS="${_SHARED_ROOT}/loop/runs.jsonl"
 : "${_LOOP_MUTE_FILE:=${_SHARED_ROOT}/loop/mute-${_LOOP_PROJ_SLUG}}"
 _LAUNCHD_DIR="${HOME}/Library/LaunchAgents"
 
@@ -2540,6 +2601,13 @@ _config_read_int() {
   if [[ "$val" =~ ^[0-9]+$ ]]; then echo "$val"; else echo "$default"; fi
 }
 
+# REFACTOR-031: cross-platform file mtime in epoch seconds.
+# Replaces the `stat -c %Y ... || stat -f %m ... || echo 0` pattern that was
+# copy-pasted in four places (dashboard age widgets, briefs, dream, peer).
+_file_mtime() {
+  stat -c %Y "$1" 2>/dev/null || stat -f %m "$1" 2>/dev/null || echo 0
+}
+
 # Derive a minute in [1,55] from project path hash + offset so different projects
 # and different services within a project don't fire at the same time.
 # Offsets used: loop=0, dream=2, brief=4 → always three distinct values (2<55).
@@ -2565,6 +2633,24 @@ _loop_event() {
   ts=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
   slug=$(_project_slug 2>/dev/null || basename "$PWD")
   evfile="${_SHARED_ROOT:-$HOME/.shared/roll}/loop/events-${slug}.ndjson"
+  # FIX-065 tripwire: in a test context (BATS or temp cwd), refuse to write
+  # into production ~/.shared/roll/. Catching this in code is the last line
+  # of defense if some unusual path bypassed the auto-sandbox at source-time.
+  # Skipped when HOME itself has been redirected to a sandbox dir — then
+  # $HOME/.shared/roll IS the sandbox, not prod.
+  case "${HOME:-}" in
+    /tmp/*|/private/tmp/*|*/var/folders/*|*/tmp.*) ;;
+    *)
+      if [ -n "${HOME:-}" ] && [ "${evfile#${HOME}/.shared/roll/}" != "$evfile" ]; then
+        case "${BATS_TEST_FILENAME:-}${PWD}" in
+          */tmp.*|*/var/folders/*|/tmp/*|/private/tmp/*|*.bats)
+            echo "[FIX-065] refusing prod _loop_event write: $evfile (test context)" >&2
+            return 1
+            ;;
+        esac
+      fi
+      ;;
+  esac
   mkdir -p "$(dirname "$evfile")"
 
   # stdout: tab-separated for tmux display
@@ -2755,7 +2841,7 @@ fi
 printf '%s:%s\n' "\$\$" "\$(date -u +%s)" > "\$INNER_LOCK"
 # FIX-038: background heartbeat writer — outer script uses this as primary liveness signal
 # to detect stale execution without relying on PID reuse heuristics.
-HEARTBEAT_FILE="${HOME}/.shared/roll/loop/.heartbeat-${slug}"
+HEARTBEAT_FILE="\${_SHARED_ROOT:-\${HOME}/.shared/roll}/loop/.heartbeat-${slug}"
 _heartbeat_writer() {
   while true; do echo "\$(date -u +%s)" > "\$HEARTBEAT_FILE"; sleep 60; done
 }
@@ -2767,8 +2853,45 @@ _HEARTBEAT_PID=\$!
 # next cron tick can proceed. Overridable via env for tests.
 LOOP_CYCLE_TIMEOUT_SEC="\${ROLL_LOOP_CYCLE_TIMEOUT_SEC:-2700}"
 _CYCLE_TIMED_OUT=0
+# IDEA-028 / FIX-066: track whether cycle_end has been emitted via any of the
+# explicit completion paths (publish/merge_back/orphan-push/claude-failed).
+# When zero, the EXIT trap emits a fallback so cycle_start never orphans the
+# dashboard into a phantom "still running" row.
+_CYCLE_END_WRITTEN=0
 _on_sigterm() { _CYCLE_TIMED_OUT=1; }
 trap '_on_sigterm' TERM
+# US-LOOP-005: idempotent runs.jsonl writer shared by normal exit, timeout
+# trap, and worktree-setup-failure early exit. Guards on jq + run_id dedupe so
+# multiple callers in the same cycle are safe.
+_runs_append() {
+  local _status="\$1"; local _tcr="\${2:-0}"; local _built="\${3:-[]}"
+  local _runs_dst="\${_SHARED_ROOT:-\${HOME}/.shared/roll}/loop/runs.jsonl"
+  command -v jq >/dev/null 2>&1 || return 0
+  local _cid="\${CYCLE_ID:-pre-cycle-\$\$}"
+  local _rid="loop-\${_cid%-*}"
+  grep -qF "\"run_id\":\"\$_rid\"" "\$_runs_dst" 2>/dev/null && return 0
+  mkdir -p "\$(dirname "\$_runs_dst")"
+  local _ts_now; _ts_now=\$(date -u +%Y-%m-%dT%H:%M:%SZ)
+  local _start="\${CYCLE_START:-\$(date -u +%s)}"
+  local _dur=\$(( \$(date -u +%s) - _start ))
+  [ "\$_dur" -lt 0 ] && _dur=0
+  jq -nc \\
+    --arg ts "\$_ts_now" \\
+    --arg project "${slug}" \\
+    --arg run_id "\$_rid" \\
+    --arg status "\$_status" \\
+    --arg cycle_id "\$_cid" \\
+    --argjson built "\$_built" \\
+    --argjson skipped '[]' \\
+    --argjson alerts '[]' \\
+    --argjson tcr_count "\$_tcr" \\
+    --argjson duration_sec "\$_dur" \\
+    '{ts:\$ts, project:\$project, run_id:\$run_id, status:\$status,
+      cycle_id:\$cycle_id,
+      built:\$built, skipped:\$skipped, alerts:\$alerts,
+      tcr_count:\$tcr_count, duration_sec:\$duration_sec}' \\
+    >> "\$_runs_dst" 2>/dev/null || true
+}
 _inner_cleanup() {
   local _rc=\$?
   # Kill heartbeat + every remaining background job (watchdog, orphan
@@ -2778,8 +2901,21 @@ _inner_cleanup() {
   for _pid in \$(jobs -p); do kill "\$_pid" 2>/dev/null; done
   if [ "\${_CYCLE_TIMED_OUT:-0}" -eq 1 ]; then
     _loop_event cycle_end "\${CYCLE_ID:-unknown}" "\${BRANCH:-}" "blocked" 2>/dev/null || true
+    _CYCLE_END_WRITTEN=1
+    # US-LOOP-005 T9: timeout path must also write runs.jsonl row so dashboard
+    # has a terminal record (cycle_end alone is insufficient — runs.jsonl is
+    # the canonical history feed for 'roll loop runs').
+    _runs_append "failed" 0 "[]" 2>/dev/null || true
     _worktree_alert "cycle \${CYCLE_ID:-unknown}: \${LOOP_CYCLE_TIMEOUT_SEC}s timeout — claude/python killed; in-progress story marked Blocked" 2>/dev/null || true
   fi
+  # IDEA-028 / FIX-066: catch every other abort (SIGKILL, set -e fire, ALERT
+  # poisoning that bypasses the retry budget, etc.). Without this, cycle_start
+  # is emitted but cycle_end never is, and dashboard renders the cycle as
+  # "still running" until the next successful cycle rolls past it.
+  if [ "\${_CYCLE_END_WRITTEN:-0}" -eq 0 ] && [ -n "\${CYCLE_ID:-}" ]; then
+    _loop_event cycle_end "\${CYCLE_ID}" "\${BRANCH:-}" "aborted" 2>/dev/null || true
+    _runs_append "aborted" 0 "[]" 2>/dev/null || true
+  fi
   rm -f "\$INNER_LOCK" "\$HEARTBEAT_FILE"
   exit "\$_rc"
 }
@@ -2800,12 +2936,16 @@ _LOOP_PROJ_SLUG="${slug}"
 _LOOP_ALERT="\${_SHARED_ROOT}/loop/ALERT-${slug}.md"
 _LOOP_STATE="\${_SHARED_ROOT}/loop/state-${slug}.yaml"
 _LOOP_MUTE_FILE="\${_SHARED_ROOT}/loop/mute-${slug}"
+# US-LOOP-006: ROLL_MAIN_SLUG is the canonical identity for any subprocess —
+# claude, loop-fmt.py, _loop_event in arbitrary cwd. _project_slug honors this
+# env var first, so writes never fragment into tmp-* / cycle-* phantom slugs.
+export ROLL_MAIN_SLUG="${slug}"
 
 # Pre-claude: try to create a per-cycle isolated worktree on origin/main.
 # On any failure (no remote, no main, etc.) fall back to running in the
 # project's main tree (degraded — no isolation, like pre-037 behavior).
-CYCLE_ID="\$(date -u +%Y%m%d-%H%M%S)-\$\$"
-CYCLE_START=\$(date -u +%s)
+CYCLE_ID="\$(date +%Y%m%d-%H%M%S)-\$\$"
+CYCLE_START=\$(date +%s)
 WT="\$(_worktree_path "${slug}" "cycle-\${CYCLE_ID}")"
 BRANCH="loop/cycle-\${CYCLE_ID}"
 _USE_WORKTREE=0
@@ -2859,6 +2999,10 @@ else
   # falling back to the main tree without isolation is unacceptable.
   _worktree_alert "cycle \${CYCLE_ID}: worktree setup failed — skipping cycle to avoid running without isolation"
   echo "[loop] cycle \${CYCLE_ID}: worktree setup failed; skipping cycle (no isolation)"
+  # US-LOOP-005 T10: worktree-setup-failed path leaves no commits and never
+  # emits cycle_start, but dashboard still needs a runs.jsonl row marking the
+  # cycle as failed (otherwise the scheduled tick appears to have vanished).
+  _runs_append "failed" 0 "[]" 2>/dev/null || true
   exit 0
 fi
 
@@ -2955,11 +3099,13 @@ if [ "\$_USE_WORKTREE" = "1" ]; then
           fi
         fi
         _worktree_cleanup "\$WT" "\$BRANCH"
-        _loop_event cycle_end "\${CYCLE_ID}" "" "done" || true
+        _loop_event cycle_end "\${CYCLE_ID}" "" "done" || true; _CYCLE_END_WRITTEN=1
         echo "[loop] cycle \${CYCLE_ID}: published; worktree cleaned"
       elif [ "\$_publish_status" -eq 2 ]; then
         if ( cd "${project_path}" && _worktree_merge_back "\$BRANCH" ); then
           _worktree_cleanup "\$WT" "\$BRANCH"
+          # US-LOOP-005 T3: gh unavailable + ff merge_back OK → cycle_end done
+          _loop_event cycle_end "\${CYCLE_ID}" "" "done" || true; _CYCLE_END_WRITTEN=1
           echo "[loop] cycle \${CYCLE_ID}: gh unavailable; merged via ff and cleaned up"
         else
           # FIX-039: gh unavailable + merge_back failed — push orphan branch+tag to origin
@@ -2969,9 +3115,13 @@ if [ "\$_USE_WORKTREE" = "1" ]; then
                && git tag "\$_orphan_tag" 2>/dev/null \
                && git push origin "\$_orphan_tag" 2>/dev/null ); then
             _worktree_cleanup "\$WT" "\$BRANCH"
+            # US-LOOP-005 T4: gh unavailable + orphan push OK → cycle_end orphan
+            _loop_event cycle_end "\${CYCLE_ID}" "" "orphan" || true; _CYCLE_END_WRITTEN=1
             _worktree_alert "cycle \${CYCLE_ID}: gh+merge_back failed; FIX-039 pushed orphan+tag \${_orphan_tag}; worktree cleaned"
             echo "[loop] cycle \${CYCLE_ID}: FIX-039: orphan branch+tag \${_orphan_tag} pushed; worktree cleaned"
           else
+            # US-LOOP-005 T5: gh unavailable + all failed → cycle_end failed
+            _loop_event cycle_end "\${CYCLE_ID}" "" "failed" || true; _CYCLE_END_WRITTEN=1
             _worktree_alert "cycle \${CYCLE_ID}: gh+merge_back+push all failed; worktree preserved at \$WT"
             echo "[loop] cycle \${CYCLE_ID}: all publish paths failed; worktree preserved at \$WT"
           fi
@@ -2984,15 +3134,21 @@ if [ "\$_USE_WORKTREE" = "1" ]; then
              && git tag "\$_orphan_tag" 2>/dev/null \
              && git push origin "\$_orphan_tag" 2>/dev/null ); then
           _worktree_cleanup "\$WT" "\$BRANCH"
+          # US-LOOP-005 T6: PR publish failed + orphan push OK → cycle_end orphan
+          _loop_event cycle_end "\${CYCLE_ID}" "" "orphan" || true; _CYCLE_END_WRITTEN=1
           _worktree_alert "cycle \${CYCLE_ID}: PR publish failed; FIX-039 pushed orphan+tag \${_orphan_tag}; worktree cleaned"
           echo "[loop] cycle \${CYCLE_ID}: FIX-039: orphan branch+tag \${_orphan_tag} pushed; worktree cleaned"
         else
+          # US-LOOP-005 T7: PR publish failed + orphan push failed → cycle_end failed
+          _loop_event cycle_end "\${CYCLE_ID}" "" "failed" || true; _CYCLE_END_WRITTEN=1
           _worktree_alert "cycle \${CYCLE_ID}: PR publish failed; worktree preserved at \$WT (branch \$BRANCH)"
           echo "[loop] cycle \${CYCLE_ID}: PR publish failed; worktree preserved at \$WT"
         fi
       fi
     fi
   else
+    # US-LOOP-005 T8: claude session failed after retry budget → cycle_end failed
+    _loop_event cycle_end "\${CYCLE_ID}" "" "failed" || true; _CYCLE_END_WRITTEN=1
     _worktree_alert "cycle \${CYCLE_ID}: claude exited \$_exit; worktree preserved at \$WT (branch \$BRANCH)"
     echo "[loop] cycle \${CYCLE_ID}: claude failed (exit \$_exit); worktree preserved at \$WT"
   fi
@@ -3003,31 +3159,9 @@ _loop_cleanup_stale_cycle_branches "${project_path}" || true
 
 # FIX-044 / Step 5: Write loop cycle run summary to runs.jsonl
 # Deterministic — runs in shell regardless of whether agent executes SKILL.md Step 5.
-# Idempotent: skips if a record for this run_id already exists (agent may also write).
-_runs_dst="${HOME}/.shared/roll/loop/runs.jsonl"
-mkdir -p "\$(dirname "\$_runs_dst")"
-_cycle_end=\$(date -u +%s)
-_cycle_dur=\$(( _cycle_end - CYCLE_START ))
-_ts=\$(date -u +%Y-%m-%dT%H:%M:%SZ)
-_run_id="loop-\${CYCLE_ID%-*}"
-if command -v jq >/dev/null 2>&1 && ! grep -qF "\"run_id\":\"\$_run_id\"" "\$_runs_dst" 2>/dev/null; then
-  jq -nc \\
-    --arg ts "\$_ts" \\
-    --arg project "${slug}" \\
-    --arg run_id "\$_run_id" \\
-    --arg status "\$_cycle_status" \\
-    --arg cycle_id "\$CYCLE_ID" \\
-    --argjson built "\$_cycle_built" \\
-    --argjson skipped '[]' \\
-    --argjson alerts '[]' \\
-    --argjson tcr_count "\$_cycle_tcr" \\
-    --argjson duration_sec "\$_cycle_dur" \\
-    '{ts:\$ts, project:\$project, run_id:\$run_id, status:\$status,
-      cycle_id:\$cycle_id,
-      built:\$built, skipped:\$skipped, alerts:\$alerts,
-      tcr_count:\$tcr_count, duration_sec:\$duration_sec}' \\
-    >> "\$_runs_dst" 2>/dev/null || true
-fi
+# US-LOOP-005: now routed through _runs_append so timeout/worktree-setup-fail
+# share the same write logic. _runs_append is idempotent on run_id.
+_runs_append "\$_cycle_status" "\$_cycle_tcr" "\$_cycle_built" 2>/dev/null || true
 INNER
   chmod +x "$inner_path"
 
@@ -3059,13 +3193,13 @@ if [ -z "\$ROLL_LOOP_FORCE" ] && [ -f "\$PAUSE" ]; then exit 0; fi
 HEARTBEAT_TIMEOUT="\${ROLL_HEARTBEAT_TIMEOUT:-1800}"
 # FIX-052: per-project STATE_FILE (was global state.yaml — caused two projects
 # to clobber each other's cycle state).
-STATE_FILE="${HOME}/.shared/roll/loop/state-${slug}.yaml"
+STATE_FILE="\${_SHARED_ROOT:-\${HOME}/.shared/roll}/loop/state-${slug}.yaml"
 if [ -f "\$STATE_FILE" ]; then
   _state=\$(grep '^status:' "\$STATE_FILE" | awk '{print \$2}' 2>/dev/null || echo "")
   if [ "\$_state" = "running" ]; then
     _still_active=false
     # FIX-038: heartbeat is primary signal
-    _heartbeat_file="${HOME}/.shared/roll/loop/.heartbeat-${slug}"
+    _heartbeat_file="\${_SHARED_ROOT:-\${HOME}/.shared/roll}/loop/.heartbeat-${slug}"
     if [ -f "\$_heartbeat_file" ]; then
       _hb_ts=\$(cat "\$_heartbeat_file" 2>/dev/null || echo "0")
       _now=\$(date -u +%s)
@@ -4543,7 +4677,7 @@ _changelog_lint_bullet() {
   if [ "${len:-0}" -gt 50 ]; then
     echo "over-length"
   fi
-  if printf '%s' "$stripped" | grep -qE '(^|[^A-Za-z0-9_])(docs|bin|tests|scripts)/'; then
+  if printf '%s' "$stripped" | grep -qE '(^|[^A-Za-z0-9_])(\.roll|docs|bin|tests|scripts)/'; then
     echo "path-fragment"
   fi
   return 0
@@ -4600,7 +4734,7 @@ _changelog_audit_bullet() {
 
   # Rule 3: file suffix / path fragment outside backticks.
   if printf '%s' "$stripped" | grep -qE '\.(md|sh|yml|ts|bats)([^A-Za-z0-9]|$)' \
-    || printf '%s' "$stripped" | grep -qE '(^|[^A-Za-z0-9_])(docs|bin|tests|scripts)/'; then
+    || printf '%s' "$stripped" | grep -qE '(^|[^A-Za-z0-9_])(\.roll|docs|bin|tests|scripts)/'; then
     echo "path-or-suffix"
   fi
 
@@ -4936,7 +5070,9 @@ _loop_is_doc_only_change() {
   local changed
   changed=$(git diff --name-only origin/main HEAD 2>/dev/null) || return 1
   [ -z "$changed" ] && return 1
-  echo "$changed" | grep -qvE '^(BACKLOG\.md|CHANGELOG\.md|PROPOSALS\.md|docs/|\.claude/)' && return 1
+  # Post-Phase-1: process artifacts moved into .roll/; user-facing docs at guide/ + site/.
+  # Legacy paths (BACKLOG.md, PROPOSALS.md, docs/) kept as fallback for pre-2.0 projects.
+  echo "$changed" | grep -qvE '^(\.roll/|CHANGELOG\.md|guide/|site/|\.claude/|BACKLOG\.md|PROPOSALS\.md|docs/)' && return 1
   return 0
 }
 
@@ -5229,7 +5365,7 @@ cmd_brief() {
     latest=$(ls "${briefs_dir}"/*.md 2>/dev/null | sort | tail -1 || true)
   else
     local mod_time now age
-    mod_time=$(stat -c %Y "$latest" 2>/dev/null || stat -f %m "$latest" 2>/dev/null || echo 0)
+    mod_time=$(_file_mtime "$latest")
     now=$(date +%s); age=$(( now - mod_time ))
     if (( age > 86400 )); then
       info "Brief is $(( age / 3600 ))h old — regenerating...  简报已 $(( age / 3600 )) 小时未更新，重新生成..."
@@ -5606,7 +5742,7 @@ _dash_last_dream_hours() {
   local dream_log="${HOME}/.shared/roll/dream/log.md"
   [[ -f "$dream_log" ]] || return 0
   local mod_time now
-  mod_time=$(stat -c %Y "$dream_log" 2>/dev/null || stat -f %m "$dream_log" 2>/dev/null || echo 0)
+  mod_time=$(_file_mtime "$dream_log")
   now=$(date +%s)
   echo $(( (now - mod_time) / 3600 ))
 }
@@ -5626,7 +5762,7 @@ _dash_last_peer() {
   local result
   result=$(grep -oE '(AGREE|REFINE|OBJECT|ESCALATE)' "$latest" 2>/dev/null | tail -1 || true)
   local mod_time now days
-  mod_time=$(stat -c %Y "$latest" 2>/dev/null || stat -f %m "$latest" 2>/dev/null || echo 0)
+  mod_time=$(_file_mtime "$latest")
   now=$(date +%s)
   days=$(( (now - mod_time) / 86400 ))
   printf '%s|%s' "${result:-—}" "${days}"
@@ -5919,7 +6055,7 @@ _legacy_home() {
   local latest_brief; latest_brief=$(ls .roll/briefs/*.md 2>/dev/null | sort | tail -1 || true)
   if [[ -n "$latest_brief" ]]; then
     local mod_time now age summary
-    mod_time=$(stat -c %Y "$latest_brief" 2>/dev/null || stat -f %m "$latest_brief" 2>/dev/null || echo 0)
+    mod_time=$(_file_mtime "$latest_brief")
     now=$(date +%s); age=$(( (now - mod_time) / 3600 ))
     summary=$(_dash_brief_summary "$latest_brief")
     printf "    Brief ${CYAN}%sh${NC} ago — %s\n" "$age" "${summary:-—}"
@@ -5956,7 +6092,7 @@ _legacy_help() {
   echo "Commands:"
   echo "  setup [-f]             [Machine] First-time install or re-sync             首次安装或重新同步"
   echo "  update                 [Upgrade] npm install latest + re-sync             一键升级到最新版"
-  echo "  init                   [Project] Create AGENTS.md + .roll/backlog.md + docs/     初始化项目工作流文件"
+  echo "  init                   [Project] Create AGENTS.md + .roll/backlog.md + .roll/features/  初始化项目工作流文件"
   echo "  status                 [Diagnostic] Show current state                    显示当前状态"
   echo "  peer                   [Peer Review] Cross-agent negotiation               跨 Agent 协商对审"
   echo "  loop <on|off|now|status|monitor|resume|reset>  [Autonomous] Manage scheduled BACKLOG executor  管理自主执行循环"

package/lib/roll-backlog.py

@@ -244,7 +244,7 @@ def _write_demo(path: str) -> None:
 ### Feature: autonomous-evolution
 | Story | Description | Status |
 |-------|-------------|--------|
-| [US-AUTO-042](.roll/features/autonomous-evolution.md) | Loop cost telemetry — write model and token data per cycle | 📋 Todo |
+| [US-AUTO-042](.roll/features/autonomous-evolution/autonomous-evolution.md) | Loop cost telemetry — write model and token data per cycle | 📋 Todo |
 
 ## ♻️ Refactor
 | ID | Description | Status |

package/lib/roll-help.py

@@ -45,7 +45,7 @@ AUTONOMY = [
 ]
 
 PROJECT = [
-    ("init",      "",              "create AGENTS.md + .roll/backlog.md + docs/",              "初始化项目工作流文件",         False),
+    ("init",      "",              "create AGENTS.md + .roll/backlog.md + .roll/features/",    "初始化项目工作流文件",         False),
     ("status",    "",              "show current state and drift",                        "显示当前状态和漂移项",         False),
     ("agent",     "[use <name>]",  "per-project agent selection",                        "切换项目 agent",             False),
     ("ci",        "[--wait]",      "show or wait for current commit's CI status",         "查看 / 等待 CI 状态",        False),

package/lib/roll-home.py

@@ -116,6 +116,26 @@ def _launchd_svc_state(service: str, slug: str) -> str:
     except Exception:
         return "installed-off"
 
+def _read_plist_schedule(service: str, slug: str) -> Optional[Dict[str, int]]:
+    """FIX-063: read actual Minute/Hour from launchd plist (truth source).
+    Returns {'minute': N, 'hour': N|None} or None if plist missing.
+    Dashboard must reflect what launchd actually fires, not a hardcoded default.
+    """
+    label = f"com.roll.{service}.{slug}"
+    plist = Path(os.path.expanduser("~/Library/LaunchAgents")) / f"{label}.plist"
+    if not plist.exists():
+        return None
+    try:
+        text = plist.read_text(errors="ignore")
+    except Exception:
+        return None
+    # Parse <key>Minute</key><integer>N</integer> (and Hour)
+    m = re.search(r"<key>Minute</key>\s*<integer>(\d+)</integer>", text)
+    h = re.search(r"<key>Hour</key>\s*<integer>(\d+)</integer>", text)
+    if not m:
+        return None
+    return {"minute": int(m.group(1)), "hour": int(h.group(1)) if h else None}
+
 def _dream_last_hours() -> Optional[int]:
     log = _shared_root() / "dream" / "log.md"
     if not log.exists():
@@ -469,12 +489,12 @@ def main() -> None:
             timestamp      = datetime.now().strftime("%H:%M"),
             state          = state,
             loop_state     = _launchd_svc_state("loop", slug),
-            loop_minute    = _ci("loop_minute", 38),
+            loop_minute    = (_read_plist_schedule("loop", slug) or {}).get("minute") or _ci("loop_minute", 38),
             loop_active_start = _ci("loop_active_start", 10),
             loop_active_end   = _ci("loop_active_end", 18),
             dream_state    = _launchd_svc_state("dream", slug),
-            dream_hour     = _ci("loop_dream_hour", 3),
-            dream_minute   = _ci("loop_dream_minute", 12),
+            dream_hour     = (_read_plist_schedule("dream", slug) or {}).get("hour") or _ci("loop_dream_hour", 3),
+            dream_minute   = (_read_plist_schedule("dream", slug) or {}).get("minute") or _ci("loop_dream_minute", 12),
             dream_last_hours = _dream_last_hours(),
             refactor_pending = refactor_pending,
             peer_last      = _peer_last(),

package/lib/roll-init.py

@@ -0,0 +1,101 @@
+#!/usr/bin/env python3
+"""roll-init — v2 terminal view for `roll init` (US-VIEW-008)."""
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+
+_LIB_DIR = os.path.dirname(os.path.realpath(__file__))
+if _LIB_DIR not in sys.path:
+    sys.path.insert(0, _LIB_DIR)
+import roll_render
+from roll_render import c, row, COLS
+
+# ════════════════════════════════════════════════════════════════════════════
+# Demo data — 6 steps mirror cmd_init's actual phases.
+# AC text: detect → AGENTS.md → BACKLOG.md → docs/features/ → merge CLAUDE.md → link skills
+# Each entry: (label, [(op, filename)]) where op ∈ {"+", "~"}.
+# ════════════════════════════════════════════════════════════════════════════
+
+_DEMO_STEPS = [
+    ("Detect project type",          []),
+    ("Create AGENTS.md",             [("+", "AGENTS.md")]),
+    ("Create .roll/backlog.md",      [("+", ".roll/backlog.md")]),
+    ("Create .roll/features/",       [("+", ".roll/features/")]),
+    ("Merge existing CLAUDE.md",     [("~", "CLAUDE.md")]),
+    ("Link skills to AI clients",    [("+", "~/.claude/skills/roll-build"),
+                                      ("+", "~/.claude/skills/roll-fix")]),
+]
+
+_NEXT_STEPS = [
+    ("Edit .roll/backlog.md",     "open the backlog and add your first US"),
+    ("Run roll loop now",         "execute one cycle manually to test the flow"),
+    ("Enable loop scheduling",    "roll loop on  — let it run hourly"),
+]
+
+
+# ════════════════════════════════════════════════════════════════════════════
+# Render
+# ════════════════════════════════════════════════════════════════════════════
+
+def _divider(char: str = "─") -> None:
+    print(c("dim", char * min(COLS, 80)))
+
+
+def _op_marker(op: str) -> str:
+    if op == "+":
+        return c("green", "+", bold=True)
+    if op == "~":
+        return c("amber", "~", bold=True)
+    return c("dim", op)
+
+
+def render_demo(project_path: str = "~/myproject") -> None:
+    left  = "  " + c("blue", "INIT", bold=True) + c("dim", "  ·  ") + c("dim", "项目初始化")
+    right = c("dim", project_path) + "  "
+    print(row(left, right))
+    _divider()
+    print()
+
+    for i, (label, files) in enumerate(_DEMO_STEPS, start=1):
+        num  = c("dim", f"  {i}.")
+        icon = c("green", "✓")
+        print(f"{num} {icon}  {label}")
+        for op, fname in files:
+            mark = _op_marker(op)
+            color = "green" if op == "+" else "amber"
+            print("       " + mark + "  " + c(color, fname))
+
+    print()
+    _divider()
+    print("  " + c("green", "✓") + " " + c("green", "Project ready", bold=True))
+    print()
+    print("  " + c("pink", "NEXT", bold=True) + c("dim", "  ·  下一步"))
+    for i, (label, hint) in enumerate(_NEXT_STEPS, start=1):
+        num = c("dim", f"  {i}.")
+        print(f"{num} {c('fg', label, bold=True)}")
+        print("     " + c("dim", hint))
+    _divider("═")
+
+
+# ════════════════════════════════════════════════════════════════════════════
+# Entry point
+# ════════════════════════════════════════════════════════════════════════════
+
+def main() -> None:
+    ap = argparse.ArgumentParser(add_help=False)
+    ap.add_argument("--demo",     action="store_true")
+    ap.add_argument("--no-color", dest="no_color", action="store_true")
+    ap.add_argument("--en",       action="store_true")
+    ap.add_argument("--zh",       action="store_true")
+    args, _ = ap.parse_known_args()
+
+    if args.no_color or os.environ.get("NO_COLOR") or not sys.stdout.isatty():
+        roll_render.USE_COLOR = False
+
+    render_demo(project_path=os.getcwd())
+
+
+if __name__ == "__main__":
+    main()

package/lib/roll-loop-status.py

@@ -701,11 +701,27 @@ def render(events, cron, state, backlog, *, days=3, lang="both", now=None,
           c("muted", "       ") +
           c("dim", "more   ") + c("blue", "roll loop --days 7"))
 
+def _read_plist_loop_minute() -> int:
+    """FIX-063: read actual loop Minute from launchd plist (truth source).
+    Falls back to 48 only when plist missing/unparseable.
+    """
+    import re as _re
+    slug = project_slug()
+    plist = Path(os.path.expanduser("~/Library/LaunchAgents")) / f"com.roll.loop.{slug}.plist"
+    if not plist.exists():
+        return 48
+    try:
+        text = plist.read_text(errors="ignore")
+    except Exception:
+        return 48
+    m = _re.search(r"<key>Minute</key>\s*<integer>(\d+)</integer>", text)
+    return int(m.group(1)) if m else 48
+
+
 def _next_cron_hint(state: Dict[str, str], zh: bool = False) -> str:
-    """Best-effort next-cron string. The real schedule lives in launchd/cron;
-    we only have access to last_run here, so we approximate to the next :48."""
+    """Compute next cron fire time from the actual launchd plist Minute (FIX-063)."""
     now = datetime.now().astimezone()
-    minute_target = 48  # bin/roll default; per-project may differ
+    minute_target = _read_plist_loop_minute()
     nxt = now.replace(minute=minute_target, second=0, microsecond=0)
     if nxt <= now:
         nxt += timedelta(hours=1)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seanyao/roll",
-  "version": "2026.519.1",
+  "version": "2026.519.3",
   "description": "Roll — Roll out features with AI agents",
   "scripts": {
     "test": "bash tests/run.sh"

package/skills/roll-build/SKILL.md

@@ -278,7 +278,7 @@ When any signal appears, **do not stop — flag it**:
 # 1. Append to .roll/backlog.md under ## ♻️ Refactor
 # REFACTOR-XXX | <one-line description> | 📋 Todo
 
-# 2. Append a brief entry to .roll/features/refactor-log.md
+# 2. Append a brief entry to .roll/features/autonomous-evolution/refactor-log.md
 ```
 
 **REFACTOR entry format in .roll/backlog.md:**
@@ -287,7 +287,7 @@ When any signal appears, **do not stop — flag it**:
 | REFACTOR-001 | {one-line plain-language description} | 📋 Todo |
 ```
 
-描述写法：参见 AGENTS.md "Backlog descriptions" 规则。说清楚"什么需要改"以及"不改会怎样"，技术细节写在 `.roll/features/refactor-log.md`。
+描述写法：参见 AGENTS.md "Backlog descriptions" 规则。说清楚"什么需要改"以及"不改会怎样"，技术细节写在 `.roll/features/autonomous-evolution/refactor-log.md`。
 
 **refactor-log.md entry format:**
 

package/skills/roll-loop/SKILL.md

@@ -208,11 +208,14 @@ For each item, **before invoking the executor skill**, mark the story 🔨 In Pr
 
 This commit is what makes the work visible — without it, tcr micro-commits during execution are invisible to `roll-brief`.
 
-选定故事后，调用 `_loop_event` 发出 story 事件，让 monitor 和 attach 能渲染当前进度：
+选定故事后，调用 `_loop_event` 发出 pick_todo 事件，让 dashboard / monitor / attach 都能把"这个 cycle 选了哪个 story"正确归类：
 
 ```bash
 # 选定故事后立即 emit（在调用 executor skill 之前）
-_loop_event story "$US_ID" "$story_title" ""
+# label 必须是 cycle_id（来自 bin/roll 注入的 LOOP_CYCLE_ID 环境变量），
+# 不是 US_ID — dashboard 按 label 聚类，US_ID 当 label 会让事件分到错的桶
+# 里，cycle 看起来"有 token 没 ID"。
+_loop_event pick_todo "$LOOP_CYCLE_ID" "$US_ID" ""
 ```
 
 Then invoke the executor: