@seanyao/roll 2026.517.5 → 2026.517.9

package/CHANGELOG.md

@@ -1,37 +1,47 @@
 # Changelog
 
-## v2026.517.4
-- **Improved**: `roll-build` story 收尾三角度并行深审（重用/质量/效率），自检清单新增参数膨胀、N+1 等具体反模式
-- **New**: 七个功能区补上中英双语用户指南 — 现在都能从文档里找到了 `[dream]`
-- **Improved**: 官网首屏动画 — 6 秒内演示装好到自动交付的完整流程 `[loop]`
-- **Added**: `features.md` 现在区分已上线和规划中的功能 — 一眼看出哪些能用
-- **Improved**: loop attach 输出不再像卡住 — 执行 story、等 CI、合 PR 三个等待点都有动态反馈 `[loop]`
-- **Fixed**: 恢复孤儿 worktree 时 PR 不再被 BEHIND 状态卡住 `[loop]`
-- **Fixed**: 无 PR 时 `roll ci --wait` 不再一直等到超时 `[loop]`
-- **Fixed**: loop 现在等 PR 合入 main 才算交付，不再 CI 绿就认为代码进了主干 `[loop]`
-
-## v2026.517.3
-- **New**: dream 现在察觉功能目录过期 — 落后时不再悄悄无人知晓 `[dream]`
-- **New**: `roll loop events` — 查看 loop 每轮的详细事件流，任务选择、评审结果、CI 状态、合并全都有迹可查 `[loop]`
-- **Improved**: loop 实时输出不再一眼看不出重点 — TCR 纪律、评审决议、CI gate 突出显示，工具日志不再喧宾夺主 `[loop]`
-
-## v2026.517.2
-- **Fixed**: `roll loop runs` 现在能看到刚跑完的循环记录（不再无历史） `[loop]`
-- **Fixed**: `roll dream`、`roll brief`、`roll loop` 的定时任务不再被 Claude 升级后的弹窗拦住，悄悄失效
-
-## v2026.517.1
-
-- **New**: loop 自动修复 story 引入的 CI 红 — 不再每次 CI 红都停下等人，修不好才写 ALERT `[loop]`
-- **New**: Roll 官网上线 — 装、用、原理一站讲清楚
-- **Fixed**: mac 休眠不再打断 loop cycle — 全程保持唤醒 `[loop]`
-- **Fixed**: agent 假死时 loop 自动接管，不再无限挂起 `[loop]`
-- **Fixed**: PR / 合并失败时 — loop 仍能把代码备份到独立分支不丢失 `[loop]`
-- **Fixed**: loop 启动时自动恢复上一轮中断的工作，意外中断的代码不再失踪 `[loop]`
-- **Fixed**: `roll loop now` 现在卡住状态也会先自愈再启动 `[loop]`
-- **Fixed**: 自治 loop 不再被权限弹窗卡住 `[loop]`
-- **Fixed**: `roll peer` 多轮 review 不再中途断线 `[peer]`
-- **Fixed**: `roll loop runs` 现在跨子目录都能显示历史 `[loop]`
-- **Fixed**: loop 空跑也会清理 worktree，不再随时间堆积 `[loop]`
+## v2026.517.6
+
+### Fixed
+
+- **`features.md` 规划中标记不再依赖 AI 自觉** — 发版脚本 AI 重写后跑机械校验自动补齐 `*(规划中)*`，规则落到 shell 里不再可能被 prompt 漂移悄悄抹掉
+
+## v2026.517.5
+
+合并 v2026.517.1 – v2026.517.5 全部更新。
+
+### New
+
+- **`loop` CI 自愈** — story 引入的 CI 红自动修，修不好才写 ALERT，不再每次都停下等人 `[loop]`
+- **`roll loop events`** — 查看每轮详细事件流：任务选择、评审、CI、合并全都有迹可查 `[loop]`
+- **`features.md` 区分已上线和规划中** — 一眼看出哪些能用
+- **七个功能区补上中英双语用户指南** `[dream]`
+- **dream 检测功能目录过期** — 文档落后时不再悄悄无人知晓 `[dream]`
+- **Roll 官网上线** — 装、用、原理一站讲清楚
+
+### Improved
+
+- **`roll-build` 收尾三角度并行深审**（重用 / 质量 / 效率），自检清单新增参数膨胀、N+1 等反模式
+- **loop 实时输出突出重点** — TCR、评审、CI gate 高亮，工具日志不再喧宾夺主 `[loop]`
+- **loop attach 三个等待点动态反馈** — story 执行、CI、PR 合入不再像卡住 `[loop]`
+- **官网首屏动画** — 6 秒内演示装好到自动交付的完整流程
+
+### Fixed
+
+- **多 cycle 并行不再双取同一 Todo** — 新 cycle 启动前扫 OPEN 的 loop PR 跳过已认领故事 `[loop]`
+- **loop 等 PR 合入 main 才算交付** — 不再 CI 绿就以为代码进了主干 `[loop]`
+- **孤儿 worktree 恢复的 PR 不再被 BEHIND 状态卡住** `[loop]`
+- **无 PR 时 `roll ci --wait` 不再死等超时** `[loop]`
+- **`roll loop runs` 看得到刚跑完的记录**，且跨子目录可见 `[loop]`
+- **`roll dream` / `roll brief` / `roll loop` 定时任务不再被 Claude 升级弹窗拦住悄悄失效**
+- **mac 休眠不再打断 loop cycle** — 全程保持唤醒 `[loop]`
+- **agent 假死时 loop 自动接管**，不再无限挂起 `[loop]`
+- **PR 合并失败时 loop 仍把代码备份到独立分支不丢失** `[loop]`
+- **loop 启动时自动恢复上一轮中断工作**，意外中断的代码不再失踪 `[loop]`
+- **`roll loop now` 卡住状态会先自愈再启动** `[loop]`
+- **自治 loop 不再被权限弹窗卡住** `[loop]`
+- **`roll peer` 多轮 review 不再中途断线** `[peer]`
+- **loop 空跑也清理 worktree**，不再随时间堆积 `[loop]`
 
 ## v2026.515.1
 

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.517.5"
+VERSION="2026.517.9"
 ROLL_HOME="${ROLL_HOME:-${HOME}/.roll}"
 ROLL_CONFIG="${ROLL_HOME}/config.yaml"
 ROLL_GLOBAL="${ROLL_HOME}/conventions/global"
@@ -856,6 +856,7 @@ cmd_init() {
   _merge_claude_to_project "$project_dir"
   _write_backlog "$project_dir/BACKLOG.md"
   _ensure_features_dir "$project_dir/docs/features"
+  _write_features_md "$project_dir/docs/features.md"
   print_merge_summary
 
   echo ""
@@ -970,6 +971,29 @@ _ensure_features_dir() {
   _ROLL_MERGE_SUMMARY+=("created|docs/features/")
 }
 
+# ─── Helper: write starter docs/features.md (no-op if exists) ────────────────
+_write_features_md() {
+  if [[ -f "$1" ]]; then
+    _ROLL_MERGE_SUMMARY+=("unchanged|docs/features.md")
+    return
+  fi
+  mkdir -p "$(dirname "$1")"
+  cat > "$1" << 'EOF'
+# Features
+
+> 产品视角的功能索引。每次发版时更新，使之与 BACKLOG 保持一致。
+> Product-level feature index. Updated at release to stay in sync with BACKLOG.
+
+---
+
+## Features by Epic
+
+<!-- Add feature entries here as epics are completed -->
+EOF
+  ok "Created: docs/features.md"
+  _ROLL_MERGE_SUMMARY+=("created|docs/features.md")
+}
+
 # ═══════════════════════════════════════════════════════════════════════════════
 # COMMAND: status
 # Show current state of conventions
@@ -1302,7 +1326,10 @@ _peer_dispatch_in_tmux() {
   inner=$(mktemp /tmp/roll-peer-inner-XXXXXX.sh)
   {
     printf '#!/bin/bash -l\n'
-    printf 'export PATH="/opt/homebrew/bin:$PATH"\n'
+    # FIX-050: portable PATH assembly (was hardcoded /opt/homebrew/bin)
+    printf 'for _d in /opt/homebrew/bin /usr/local/bin /opt/local/bin "$HOME/.local/bin"; do\n'
+    printf '  case ":$PATH:" in *":$_d:"*) ;; *) [ -d "$_d" ] && PATH="$_d:$PATH" ;; esac\n'
+    printf 'done; export PATH\n'
     printf '%s > %q 2> %q || true\n' "$cmd_str" "$out_file" "$err_file"
     printf 'touch %q\n' "$done_file"
   } > "$inner"
@@ -1842,7 +1869,8 @@ cmd_review_pr() {
       ;;
     UNCERTAIN)
       warn "PR #${pr_number}: UNCERTAIN — ${vreason}"
-      local alert_file="${ROLL_LOOP_DIR:-${HOME}/.shared/roll/loop}/ALERT.md"
+      # FIX-052: write to per-project ALERT (was global ALERT.md).
+      local alert_file="$_LOOP_ALERT"
       mkdir -p "$(dirname "$alert_file")"
       printf '[%s] PR #%s: AI review UNCERTAIN — %s\n' \
         "$(date -u +%Y-%m-%dT%H:%M:%SZ)" "$pr_number" "$vreason" >> "$alert_file"
@@ -1901,14 +1929,6 @@ cmd_agent() {
 # LOOP — autonomous BACKLOG executor management
 # ═══════════════════════════════════════════════════════════════════════════════
 
-_LOOP_TAG="# roll-loop"
-: "${_SHARED_ROOT:=${HOME}/.shared/roll}"
-: "${_LOOP_STATE:=${_SHARED_ROOT}/loop/state.yaml}"
-: "${_LOOP_ALERT:=${_SHARED_ROOT}/loop/ALERT.md}"
-_LOOP_RUNS="${HOME}/.shared/roll/loop/runs.jsonl"
-_LOOP_MUTE_FILE="${HOME}/.shared/roll/mute"
-_LAUNCHD_DIR="${HOME}/Library/LaunchAgents"
-
 # 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() {
@@ -1932,6 +1952,19 @@ _project_slug() {
   printf '%s' "${base}-${hash}"
 }
 
+_LOOP_TAG="# roll-loop"
+: "${_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
+# letting concurrent cycles overwrite each other's state. Align with the
+# existing events-/run-/LOCK-/heartbeat-<slug> namespacing.
+: "${_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"
+: "${_LOOP_MUTE_FILE:=${_SHARED_ROOT}/loop/mute-${_LOOP_PROJ_SLUG}}"
+_LAUNCHD_DIR="${HOME}/Library/LaunchAgents"
+
 _config_read_int() {
   local key="$1" default="$2"
   local val
@@ -2003,6 +2036,28 @@ _loop_event_rotate() {
   fi
 }
 
+# FIX-050: probe brew prefix + common tool dirs to build a PATH that survives
+# launchd/cron's bare-env launch. Setup-time companion to the runtime
+# assembly snippet embedded in runner scripts.
+_detect_path_prepend() {
+  local dirs=() seen="" d out=""
+  if command -v brew >/dev/null 2>&1; then
+    local bp; bp=$(brew --prefix 2>/dev/null || true)
+    [[ -n "$bp" && -d "$bp/bin" ]] && dirs+=("$bp/bin")
+  fi
+  [[ -d /opt/homebrew/bin ]] && dirs+=("/opt/homebrew/bin")
+  [[ -d /usr/local/bin ]] && dirs+=("/usr/local/bin")
+  [[ -d /opt/local/bin ]] && dirs+=("/opt/local/bin")
+  [[ -d "$HOME/.local/bin" ]] && dirs+=("$HOME/.local/bin")
+  dirs+=("/usr/bin" "/bin" "/usr/sbin" "/sbin")
+  for d in "${dirs[@]}"; do
+    case ":$seen:" in *":$d:"*) continue ;; esac
+    seen="$seen:$d"
+    [[ -z "$out" ]] && out="$d" || out="$out:$d"
+  done
+  printf '%s' "$out"
+}
+
 _launchd_label() {
   local service="$1" project_path="$2"
   printf 'com.roll.%s.%s' "$service" "$(_project_slug "$project_path")"
@@ -2022,6 +2077,11 @@ _write_launchd_plist() {
     <integer>${hour}</integer>
 "
 
+  # FIX-050: bake PATH into the plist so launchd-spawned bash can find tmux,
+  # claude, node, etc. The runner script also re-asserts PATH at runtime as
+  # a second layer (covers stale plists where brew was installed after setup).
+  local path_value; path_value=$(_detect_path_prepend)
+
   local content
   content="<?xml version=\"1.0\" encoding=\"UTF-8\"?>
 <!DOCTYPE plist PUBLIC \"-//Apple//DTD PLIST 1.0//EN\" \"http://www.apple.com/DTDs/PropertyList-1.0.dtd\">
@@ -2035,6 +2095,11 @@ _write_launchd_plist() {
     <string>-l</string>
     <string>${runner_script}</string>
   </array>
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>PATH</key>
+    <string>${path_value}</string>
+  </dict>
   <key>StartCalendarInterval</key>
   <dict>
     <key>Minute</key>
@@ -2093,7 +2158,13 @@ _write_loop_runner_script() {
   cat > "$inner_path" << INNER
 #!/bin/bash -l
 set -o pipefail
-export PATH="/opt/homebrew/bin:\$PATH"
+# FIX-050: portable PATH assembly — launchd/cron deliver a bare PATH that
+# misses brew-installed tools (tmux, claude, node, …). Iterate candidate
+# dirs; only prepend when present and not already in PATH. Idempotent.
+for _d in /opt/homebrew/bin /usr/local/bin /opt/local/bin "\$HOME/.local/bin"; do
+  case ":\$PATH:" in *":\$_d:"*) ;; *) [ -d "\$_d" ] && PATH="\$_d:\$PATH" ;; esac
+done
+export PATH
 # FIX-031: inner-level LOCK (PID + start-ts) — outer runner.sh LOCK can be
 # bypassed (recovery / retry / direct invocation); this guards the actual
 # claude invocation so a second session can't run under the same project.
@@ -2128,6 +2199,15 @@ trap 'kill "\${_HEARTBEAT_PID}" 2>/dev/null; rm -f "\$INNER_LOCK" "\$HEARTBEAT_F
 source "${roll_bin}"
 set +e
 
+# FIX-052: bin/roll initializes loop state paths from cwd at source time, but
+# the inner script may be launched from anywhere. Override to this project's
+# slug (baked at template generation) so helpers like _worktree_alert write
+# to the correct project's ALERT-<slug>.md / state-<slug>.yaml / mute-<slug>.
+_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}"
+
 # 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).
@@ -2336,6 +2416,13 @@ INNER
 
   cat > "$script_path" << SCRIPT
 #!/bin/bash -l
+# FIX-050: portable PATH assembly before any brew-tool lookup (tmux, caffeinate
+# on some systems, claude). Mirrors the inner script's bootstrap so even when
+# launchd's plist EnvironmentVariables is stale, the runner self-repairs.
+for _d in /opt/homebrew/bin /usr/local/bin /opt/local/bin "\$HOME/.local/bin"; do
+  case ":\$PATH:" in *":\$_d:"*) ;; *) [ -d "\$_d" ] && PATH="\$_d:\$PATH" ;; esac
+done
+export PATH
 # caffeinate: prevent idle sleep from killing claude during cycles
 caffeinate -i -w \$\$ &
 # Active-window check — skipped when ROLL_LOOP_FORCE is set (manual 'roll loop now')
@@ -2353,7 +2440,9 @@ if [ -z "\$ROLL_LOOP_FORCE" ] && [ -f "\$PAUSE" ]; then exit 0; fi
 # FIX-038: heartbeat is the primary liveness signal (avoids PID reuse race);
 # LOCK pid check is secondary fallback for backward compatibility.
 HEARTBEAT_TIMEOUT="\${ROLL_HEARTBEAT_TIMEOUT:-1800}"
-STATE_FILE="${HOME}/.shared/roll/loop/state.yaml"
+# 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"
 if [ -f "\$STATE_FILE" ]; then
   _state=\$(grep '^status:' "\$STATE_FILE" | awk '{print \$2}' 2>/dev/null || echo "")
   if [ "\$_state" = "running" ]; then
@@ -2384,7 +2473,9 @@ if [ -f "\$STATE_FILE" ]; then
       echo "[\$(date '+%Y-%m-%dT%H:%M:%S%z')] FIX-037: orphan state detected (status=running, heartbeat stale or missing) — healing to idle" >> "\$LOG"
       echo "status: idle" > "\${STATE_FILE}.tmp" && mv "\${STATE_FILE}.tmp" "\$STATE_FILE"
       rm -f "\$_lock_file" 2>/dev/null || true
-      _alert_file="\$(dirname "\$0")/ALERT.md"
+      # FIX-052: per-project ALERT file (was shared ALERT.md — caused R0
+      # auto-heal entries to surface in Roll's alert view).
+      _alert_file="\$(dirname "\$0")/ALERT-${slug}.md"
       echo "\$(date '+%Y-%m-%dT%H:%M:%S%z') | FIX-037 auto-heal | Orphan state detected and cleared (status=running → idle)" >> "\$_alert_file" 2>/dev/null || true
       echo "[\$(date '+%Y-%m-%dT%H:%M:%S%z')] FIX-037: healed to idle, ALERT written" >> "\$LOG"
     fi
@@ -2420,7 +2511,7 @@ if command -v tmux >/dev/null 2>&1; then
   # Auto-attach popup: when not muted, spawn a Terminal window attached to the
   # tmux session so the user can watch the loop work in real time. Best-effort
   # focus retention: capture the current frontmost app and re-activate after.
-  if [ ! -f "\$HOME/.shared/roll/mute" ] && [ "\$(uname)" = "Darwin" ]; then
+  if [ ! -f "\$HOME/.shared/roll/loop/mute-${slug}" ] && [ "\$(uname)" = "Darwin" ]; then
     # Runtime terminal detection: try preferred first, fallback through installed apps.
     # open -na returns non-zero when app not found, so || chain works as fallback.
     _launched=0
@@ -2515,7 +2606,8 @@ _install_launchd_plists() {
     local label; label=$(_launchd_label "$svc" "$project_path")
     local plist; plist=$(_launchd_plist_path "$svc" "$project_path")
     local runner="${shared}/${svc}/run-${slug}.sh"
-    local log="${shared}/${svc}/cron.log"
+    # FIX-052: per-project cron log so concurrent projects don't interleave.
+    local log="${shared}/${svc}/cron-${slug}.log"
     local cmd; cmd=$(_agent_skill_cmd "${sd}/${skill}/SKILL.md" 2>/dev/null || echo "roll loop now")
 
     if [[ "$svc" == "loop" ]]; then
@@ -2643,10 +2735,12 @@ _loop_on() {
 
   mkdir -p "${_SHARED_ROOT}/loop" "${_SHARED_ROOT}/dream" "${_SHARED_ROOT}/brief"
 
+  # FIX-052: per-project cron logs so concurrent projects don't interleave.
+  local slug; slug=$(_project_slug "$project_path")
   local loop_cmd dream_cmd brief_cmd
-  loop_cmd="cd \"${project_path}\" && $(_agent_skill_cmd "${sd}/roll-loop/SKILL.md") >> ${_SHARED_ROOT}/loop/cron.log 2>&1"
-  dream_cmd="cd \"${project_path}\" && $(_agent_skill_cmd "${sd}/roll-.dream/SKILL.md") >> ${_SHARED_ROOT}/dream/cron.log 2>&1"
-  brief_cmd="cd \"${project_path}\" && $(_agent_skill_cmd "${sd}/roll-brief/SKILL.md") >> ${_SHARED_ROOT}/brief/cron.log 2>&1"
+  loop_cmd="cd \"${project_path}\" && $(_agent_skill_cmd "${sd}/roll-loop/SKILL.md") >> ${_SHARED_ROOT}/loop/cron-${slug}.log 2>&1"
+  dream_cmd="cd \"${project_path}\" && $(_agent_skill_cmd "${sd}/roll-.dream/SKILL.md") >> ${_SHARED_ROOT}/dream/cron-${slug}.log 2>&1"
+  brief_cmd="cd \"${project_path}\" && $(_agent_skill_cmd "${sd}/roll-brief/SKILL.md") >> ${_SHARED_ROOT}/brief/cron-${slug}.log 2>&1"
 
   (
     crontab -l 2>/dev/null
@@ -2757,7 +2851,8 @@ _loop_test() {
     err "Run 'roll loop on' first to generate it."
     return 1
   fi
-  local log="${_SHARED_ROOT}/loop/cron.log"
+  # FIX-052: per-project log so test cycle output doesn't mix with other projects'.
+  local log="${_SHARED_ROOT}/loop/cron-${slug}.log"
   local test_runner="${_SHARED_ROOT}/loop/run-${slug}-test.sh"
 
   # Detect terminal pref same way _install_launchd_plists does
@@ -3343,7 +3438,7 @@ _loop_self_heal_ci() {
   [[ -z "$story_id" ]] && return 1
   [[ "${ROLL_LOOP_NO_HEAL:-0}" == "1" ]] && return 1
   local max="${ROLL_LOOP_HEAL_MAX:-2}"
-  local state="${_LOOP_STATE:-${HOME}/.shared/roll/loop/state.yaml}"
+  local state="$_LOOP_STATE"
   local current=0
   if [[ -f "$state" ]]; then
     local raw; raw=$(grep '^heal_count:' "$state" 2>/dev/null | awk '{print $2}')
@@ -3367,7 +3462,7 @@ _loop_self_heal_ci() {
 _loop_clear_heal_state() {
   local story_id="$1"
   [[ -z "$story_id" ]] && return 0
-  local state="${_LOOP_STATE:-${HOME}/.shared/roll/loop/state.yaml}"
+  local state="$_LOOP_STATE"
   [[ ! -f "$state" ]] && return 0
   local tmp; tmp=$(mktemp)
   grep -v '^heal_count:' "$state" > "$tmp"
@@ -3533,7 +3628,7 @@ _loop_pr_rebase_circuit() {
   local pr="$1"
   [ -n "$pr" ] || return 1
 
-  local state="${_LOOP_STATE:-${HOME}/.shared/roll/loop/state.yaml}"
+  local state="$_LOOP_STATE"
   local now; now=$(date -u +%s)
   local cutoff=$((now - 86400))
 
@@ -3651,7 +3746,7 @@ _loop_pr_rebase_stale() {
   local is_fork
   is_fork=$(echo "$pr_json" | jq -r '.isCrossRepository // false' 2>/dev/null)
   if [ "$is_fork" = "true" ]; then
-    local alert="${_LOOP_ALERT:-${HOME}/.shared/roll/loop/ALERT.md}"
+    local alert="$_LOOP_ALERT"
     mkdir -p "$(dirname "$alert")" 2>/dev/null || true
     printf '[%s] PR #%s: fork PR — cannot rebase (no write access)\n' \
       "$(date -u +%Y-%m-%dT%H:%M:%SZ)" "$pr" >> "$alert"
@@ -3666,7 +3761,7 @@ _loop_pr_rebase_stale() {
   else
     git rebase --abort 2>/dev/null || true
     git checkout - 2>/dev/null || true
-    local alert="${_LOOP_ALERT:-${HOME}/.shared/roll/loop/ALERT.md}"
+    local alert="$_LOOP_ALERT"
     mkdir -p "$(dirname "$alert")" 2>/dev/null || true
     printf '[%s] PR #%s: rebase conflict on %s — please rebase manually\n' \
       "$(date -u +%Y-%m-%dT%H:%M:%SZ)" "$pr" "$head_ref" >> "$alert"
@@ -3717,9 +3812,17 @@ _loop_pr_inbox() {
 
     # Bot review gate: if a GHA workflow already handled this PR, defer to it.
     if [ "$bot_review" = "APPROVED" ]; then
+      # All gates cleared (bot-approved + CI green + no conflicts) → merge directly.
+      # Relying on repo-level auto-merge being configured is not reliable; loop
+      # owns the decision here since it already ran the review.
+      if [ "$ci_state" = "success" ] && [ "$mergeable" = "MERGEABLE" ]; then
+        gh -R "$slug" pr merge "$num" --squash --delete-branch >/dev/null 2>&1 \
+          && info "PR #${num}: bot-approved + CI green — merged" \
+          || warn "PR #${num}: merge failed (bot-approved + CI green) — left open"
+      fi
       i=$((i + 1)); continue
     elif [ "$bot_review" = "CHANGES_REQUESTED" ]; then
-      local alert="${_LOOP_ALERT:-${HOME}/.shared/roll/loop/ALERT.md}"
+      local alert="$_LOOP_ALERT"
       mkdir -p "$(dirname "$alert")" 2>/dev/null || true
       printf '[%s] PR #%s: bot review CHANGES_REQUESTED — loop PR rejected by GHA reviewer\n' \
         "$(date -u +%Y-%m-%dT%H:%M:%SZ)" "$num" >> "$alert"
@@ -3747,6 +3850,45 @@ _loop_pr_inbox() {
   return 0
 }
 
+# FIX-048: report story IDs already claimed by open loop/* PRs so a new cycle
+# can skip them before scanning BACKLOG. Without this gate, a cycle launched
+# before the previous cycle's PR merges would re-pick the same Todo story
+# (its worktree branches from main, where the 🔨 mark is not yet visible).
+#
+# _loop_pr_claimed_stories
+#   Stdout: one story ID per line, deduped. Empty when nothing claimed.
+#   Exit:   0 always (lenient: gh missing / API failure → empty output).
+_loop_pr_claimed_stories() {
+  local slug; _gh_resolve slug || return 0
+  local branches
+  branches=$(gh -R "$slug" pr list --state open \
+    --json headRefName \
+    --jq '.[] | select(.headRefName | startswith("loop/")) | .headRefName' \
+    2>/dev/null) || return 0
+  [ -n "$branches" ] || return 0
+
+  local branch claimed=""
+  while IFS= read -r branch; do
+    [ -n "$branch" ] || continue
+    local content
+    content=$(gh -R "$slug" api \
+      "repos/${slug}/contents/BACKLOG.md?ref=${branch}" \
+      -H "Accept: application/vnd.github.raw" 2>/dev/null) || continue
+    [ -n "$content" ] || continue
+    local ids
+    ids=$(printf '%s\n' "$content" \
+      | awk -F'|' '/🔨 In Progress/ {
+          gsub(/^[[:space:]]+|[[:space:]]+$/, "", $2)
+          sub(/^\[/, "", $2)
+          sub(/\].*$/, "", $2)
+          if ($2 != "") print $2
+        }')
+    [ -n "$ids" ] && claimed="${claimed}${ids}"$'\n'
+  done <<< "$branches"
+
+  printf '%s' "$claimed" | awk 'NF' | sort -u
+}
+
 # US-CL-004: changelog 风格守门 Phase 1 — mechanical linter.
 #
 # _changelog_lint_bullet <bullet-text>
@@ -4495,6 +4637,23 @@ _backlog_extract_id() {
   fi
 }
 
+# Render one pending-group section (FIX / US / REFACTOR / IDEA) — all four
+# types share identical row structure, so they share one render path. Format
+# changes only need to happen here.
+#   $1 title (EN + ZH)   $2 ANSI color   $3 count   $4 id column width   $5 items text
+_backlog_render_group() {
+  local title="$1" color="$2" count="$3" width="$4" items="$5"
+  echo -e "  ${color}${title}  (${count})${NC}"
+  while IFS= read -r line; do
+    [[ -z "$line" ]] && continue
+    local id desc
+    id=$(_backlog_extract_id "$line")
+    desc=$(echo "$line" | awk -F'|' '{print $3}' | sed 's/^ *//;s/ *$//')
+    printf "    %-${width}s  %s\n" "$id" "$desc"
+  done <<< "$items"
+  echo ""
+}
+
 # ═══════════════════════════════════════════════════════════════════════════════
 # CI — check or wait for current commit's CI status
 # ═══════════════════════════════════════════════════════════════════════════════
@@ -4650,49 +4809,10 @@ cmd_backlog() {
   echo -e "  ${BOLD}Pending Backlog  待处理任务${NC}  (${total} items)"
   echo ""
 
-  if [[ $fix_count -gt 0 ]]; then
-    echo -e "  ${RED}Bug Fixes  缺陷修复  (${fix_count})${NC}"
-    while IFS= read -r line; do
-      local id desc
-      id=$(echo "$line" | awk -F'|' '{print $2}' | tr -d ' ')
-      desc=$(echo "$line" | awk -F'|' '{print $3}' | sed 's/^ *//;s/ *$//')
-      printf "    %-12s  %s\n" "$id" "$desc"
-    done <<< "$fix_items"
-    echo ""
-  fi
-
-  if [[ $us_count -gt 0 ]]; then
-    echo -e "  ${CYAN}User Stories  用户故事  (${us_count})${NC}"
-    while IFS= read -r line; do
-      local id desc
-      id=$(echo "$line" | sed 's/.*\[\(US-[^]]*\)\].*/\1/')
-      desc=$(echo "$line" | awk -F'|' '{print $3}' | sed 's/^ *//;s/ *$//')
-      printf "    %-14s  %s\n" "$id" "$desc"
-    done <<< "$us_items"
-    echo ""
-  fi
-
-  if [[ $refactor_count -gt 0 ]]; then
-    echo -e "  ${YELLOW}Refactors  重构  (${refactor_count})${NC}"
-    while IFS= read -r line; do
-      local id desc
-      id=$(echo "$line" | awk -F'|' '{print $2}' | tr -d ' ')
-      desc=$(echo "$line" | awk -F'|' '{print $3}' | sed 's/^ *//;s/ *$//')
-      printf "    %-16s  %s\n" "$id" "$desc"
-    done <<< "$refactor_items"
-    echo ""
-  fi
-
-  if [[ $idea_count -gt 0 ]]; then
-    echo -e "  ${NC}Ideas  创意  (${idea_count})"
-    while IFS= read -r line; do
-      local id desc
-      id=$(echo "$line" | awk -F'|' '{print $2}' | tr -d ' ')
-      desc=$(echo "$line" | awk -F'|' '{print $3}' | sed 's/^ *//;s/ *$//')
-      printf "    %-14s  %s\n" "$id" "$desc"
-    done <<< "$idea_items"
-    echo ""
-  fi
+  [[ $fix_count -gt 0 ]]      && _backlog_render_group "Bug Fixes  缺陷修复"   "$RED"    "$fix_count"      12 "$fix_items"
+  [[ $us_count -gt 0 ]]       && _backlog_render_group "User Stories  用户故事" "$CYAN"   "$us_count"       14 "$us_items"
+  [[ $refactor_count -gt 0 ]] && _backlog_render_group "Refactors  重构"        "$YELLOW" "$refactor_count" 16 "$refactor_items"
+  [[ $idea_count -gt 0 ]]     && _backlog_render_group "Ideas  创意"            "$NC"     "$idea_count"     14 "$idea_items"
 
   if [[ $total -eq 0 ]]; then
     echo -e "  ${GREEN}✓ Nothing pending — backlog is clear  暂无待处理任务${NC}"

package/package.json

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

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

@@ -420,6 +420,9 @@ prompt 会包含：
   - 该 Feature 下**所有** Story 均为 `📋 Todo` → 在描述末尾追加 `*(规划中)*`
   - 只要有 **≥1 个** `✅ Done` Story → 正常展示，**不加**任何标记
   - 一眼可见：规划中的 Feature 在每个 Epic 分组的末尾列出
+  - **FIX-051 兜底**：`scripts/release.sh` 在 AI 重写后会跑机械校验
+    `_enforce_planning_markers`，即使本规则被 AI 漏掉也会自动补 `*(规划中)*`；
+    规则的权威实现是 release.sh 里的纯 shell 函数，prompt 这条只是软提示
 - 描述写 1 句话 **产品视角**：用户能用它做什么，避免实现细节
 - 分组用 BACKLOG 的 Epic 名，原序，不重排
 - Core Highlights 从所有 Features 里挑 3-5 个最能代表产品定位的，

package/skills/roll-loop/SKILL.md

@@ -146,6 +146,19 @@ Priority: FIX-XXX first (bugs block progress), then US-XXX, then REFACTOR-XXX.
 - An earlier loop iteration that hasn't finished yet (rare; should be guarded by LOCK)
 - A previous interrupted run (the resume logic in Step 1 will pick these up)
 
+**In-flight PR gate** (FIX-048). Before picking, also exclude stories already
+claimed by an **open `loop/*` PR**. Each cycle's worktree is branched from
+`origin/main`, so a story another cycle has marked 🔨 In Progress is invisible
+locally until that cycle's PR merges. Without this gate, two cycles started
+back-to-back will both pick the same Todo row and produce duplicate PRs.
+
+```bash
+bash -c 'source "$(command -v roll)"; _loop_pr_claimed_stories'
+#   stdout: one story ID per line (deduped) — these are claimed by open
+#           loop/* PRs on the remote. SKIP any candidate whose ID appears.
+#   exit 0 always (lenient: gh missing / API error → empty output).
+```
+
 **Dependency gate** (FIX-032). For each `📋 Todo` candidate, before picking:
 
 ```bash