@seanyao/roll 2026.519.2 → 2026.519.3

package/CHANGELOG.md

@@ -1,11 +1,31 @@
 # 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（大版本重构）

package/README.md

@@ -37,9 +37,6 @@ Roll 2.0 introduces a **process/product split** to keep open-source projects cle
 - **`$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/).
 
-📖 Upgrading from 1.x? Read [guide/en/migration-2.0.md](guide/en/migration-2.0.md).
-📖 New legacy project? Read [guide/en/legacy-onboarding.md](guide/en/legacy-onboarding.md).
-
 ## 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?*
@@ -66,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 | 中文 |
@@ -78,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) | — |
 
 ---
@@ -87,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.2"
+VERSION="2026.519.3"
 ROLL_HOME="${ROLL_HOME:-${HOME}/.roll}"
 ROLL_CONFIG="${ROLL_HOME}/config.yaml"
 ROLL_GLOBAL="${ROLL_HOME}/conventions/global"
@@ -2343,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"
 
@@ -2545,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
@@ -2553,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"
 
@@ -2564,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).
@@ -2589,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
@@ -2779,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
 }
@@ -2791,6 +2853,11 @@ _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
@@ -2798,7 +2865,7 @@ trap '_on_sigterm' TERM
 # multiple callers in the same cycle are safe.
 _runs_append() {
   local _status="\$1"; local _tcr="\${2:-0}"; local _built="\${3:-[]}"
-  local _runs_dst="${HOME}/.shared/roll/loop/runs.jsonl"
+  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%-*}"
@@ -2834,12 +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"
 }
@@ -3023,13 +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
+          _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
@@ -3040,12 +3116,12 @@ if [ "\$_USE_WORKTREE" = "1" ]; then
                && 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
+            _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
+            _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
@@ -3059,12 +3135,12 @@ if [ "\$_USE_WORKTREE" = "1" ]; then
              && 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
+          _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
+          _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
@@ -3072,7 +3148,7 @@ if [ "\$_USE_WORKTREE" = "1" ]; then
     fi
   else
     # US-LOOP-005 T8: claude session failed after retry budget → cycle_end failed
-    _loop_event cycle_end "\${CYCLE_ID}" "" "failed" || true
+    _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
@@ -3117,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)
@@ -5289,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 )) 小时未更新，重新生成..."
@@ -5666,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 ))
 }
@@ -5686,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}"
@@ -5979,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:-—}"
@@ -6016,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seanyao/roll",
-  "version": "2026.519.2",
+  "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: