@seanyao/roll 2026.517.3 → 2026.517.4

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # 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]`

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.3"
+VERSION="2026.517.4"
 ROLL_HOME="${ROLL_HOME:-${HOME}/.roll}"
 ROLL_CONFIG="${ROLL_HOME}/config.yaml"
 ROLL_GLOBAL="${ROLL_HOME}/conventions/global"
@@ -872,167 +872,6 @@ cmd_init() {
   fi
 }
 
-
-# ─── Helper: merge global preamble + template into output ────────────────────
-merge_convention() {
-  local filename="$1"
-  local tpl_dir="$2"
-  local out_dir="$3"
-  local display="${4:-$filename}"
-  local global_file="$ROLL_GLOBAL/$filename"
-  local tpl_file="$tpl_dir/$filename"
-  local out_file="$out_dir/$filename"
-
-  if [[ ! -f "$tpl_file" ]]; then
-    return
-  fi
-
-  local merged
-  merged="$(cat "$global_file" 2>/dev/null || true)"
-  merged+=$'\n\n'
-  merged+="---"
-  merged+=$'\n\n'
-  merged+="$(cat "$tpl_file")"
-
-  if [[ -f "$out_file" ]]; then
-    if diff -q <(echo "$merged") "$out_file" &>/dev/null; then
-      _ROLL_MERGE_SUMMARY+=("unchanged|$display")
-      return  # identical, nothing to do
-    fi
-    warn "File exists: $display  文件已存在: $display"
-    echo -n "  [o] Overwrite  [k] Keep  [M] Merge (default): "
-    read -r answer
-    answer="${answer:-M}"
-    case "$answer" in
-      o|O)
-        echo "$merged" > "$out_file"
-        ok "Overwritten: $display  已覆盖: $display"
-        _ROLL_MERGE_SUMMARY+=("overwritten|$display")
-        return
-        ;;
-      k|K)
-        info "Kept: $display  已保留: $display"
-        _ROLL_MERGE_SUMMARY+=("kept|$display")
-        return
-        ;;
-      m|M|"")
-        # Merge: for each ## section in template:
-        #   - if missing in output → append
-        #   - if present but content differs → show diff, prompt [u/k]
-        #   - if present and identical → skip
-
-        # Helper: extract a section's body (lines after heading until next ## or EOF)
-        # Usage: _extract_section "$file" "$heading"
-        _extract_section() {
-          local file="$1"
-          local heading="$2"
-          local in_section=false
-          local body=""
-          while IFS= read -r ln; do
-            if [[ "$ln" == "$heading" ]]; then
-              in_section=true
-              continue
-            fi
-            if [[ "$in_section" == "true" ]]; then
-              if [[ "$ln" =~ ^##\  ]]; then
-                break
-              fi
-              body+="$ln"$'\n'
-            fi
-          done < "$file"
-          printf '%s' "$body"
-        }
-
-        local current_heading=""
-        local current_body=""
-
-        # _process_section: check/append/update a completed section
-        _process_section() {
-          local heading="$1"
-          local body="$2"
-          local out="$3"
-          if ! grep -qF "$heading" "$out" 2>/dev/null; then
-            # Section missing → append
-            printf '\n%s\n%s' "$heading" "$body" >> "$out"
-          else
-            # Section exists → compare content
-            local existing
-            existing="$(_extract_section "$out" "$heading")"
-            if [[ "$body" != "$existing" ]]; then
-              echo ""
-              warn "Section \"$heading\" exists but content differs:"
-              diff <(printf '%s' "$existing") <(printf '%s' "$body") || true
-              echo -n "  [u] update with template  [k] keep mine (default): "
-              local sec_ans
-              read -r sec_ans
-              sec_ans="${sec_ans:-k}"
-              if [[ "$sec_ans" == "u" || "$sec_ans" == "U" ]]; then
-                # Replace existing section with template section
-                local tmp_out
-                tmp_out="$(mktemp)"
-                local skip=false
-                while IFS= read -r fline; do
-                  if [[ "$fline" == "$heading" ]]; then
-                    skip=true
-                    printf '%s\n%s' "$heading" "$body" >> "$tmp_out"
-                    continue
-                  fi
-                  if [[ "$skip" == "true" ]]; then
-                    if [[ "$fline" =~ ^##\  ]]; then
-                      skip=false
-                      printf '%s\n' "$fline" >> "$tmp_out"
-                    fi
-                    continue
-                  fi
-                  printf '%s\n' "$fline" >> "$tmp_out"
-                done < "$out"
-                mv "$tmp_out" "$out"
-              fi
-            fi
-          fi
-        }
-
-        # Parse template sections, reading from file (not herestring) to keep stdin free
-        # for interactive user prompts inside _process_section
-        local tpl_sections=()
-        local tpl_bodies=()
-        local cur_h="" cur_b=""
-        while IFS= read -r line; do
-          if [[ "$line" =~ ^##\  ]]; then
-            if [[ -n "$cur_h" ]]; then
-              tpl_sections+=("$cur_h")
-              tpl_bodies+=("$cur_b")
-            fi
-            cur_h="$line"
-            cur_b=""
-          elif [[ -n "$cur_h" ]]; then
-            cur_b+="$line"$'\n'
-          fi
-        done < "$tpl_file"
-        # Capture last section
-        if [[ -n "$cur_h" ]]; then
-          tpl_sections+=("$cur_h")
-          tpl_bodies+=("$cur_b")
-        fi
-
-        # Now process sections (stdin is free for user input)
-        local i
-        for (( i=0; i<${#tpl_sections[@]}; i++ )); do
-          _process_section "${tpl_sections[$i]}" "${tpl_bodies[$i]}" "$out_file"
-        done
-
-        ok "Merged: $display  已合并: $display"
-        _ROLL_MERGE_SUMMARY+=("merged|$display")
-        return
-        ;;
-    esac
-  fi
-
-  echo "$merged" > "$out_file"
-  ok "Created: $display  已创建: $display"
-  _ROLL_MERGE_SUMMARY+=("created|$display")
-}
-
 # ─── Helper: print a tidy summary of merge actions ───────────────────────────
 print_merge_summary() {
   if [[ ${#_ROLL_MERGE_SUMMARY[@]} -eq 0 ]]; then
@@ -2243,6 +2082,13 @@ _write_loop_runner_script() {
   # _install_launchd_plists prepend it). The runner now manages cwd itself
   # — pointing at the worktree when isolation succeeds, project_path otherwise.
   local claude_cmd; claude_cmd="${cmd_verbose#cd \"*\" && }"
+  # FIX-048: Claude Code resolves project root from the worktree's .git file to
+  # the main repo, placing worktree absolute paths outside its sandbox. Inject
+  # --add-dir "$WT" so the worktree directory is explicitly allowed. Only applies
+  # to claude (the --output-format stream-json flag is exclusive to claude runs).
+  if [[ "$claude_cmd" == *"--output-format stream-json"* ]]; then
+    claude_cmd="${claude_cmd/--output-format stream-json/--output-format stream-json --add-dir \"\$WT\"}"
+  fi
   local slug; slug=$(_project_slug "$project_path")
   cat > "$inner_path" << INNER
 #!/bin/bash -l
@@ -2303,6 +2149,11 @@ for _orphan_wt in "\${_SHARED_ROOT}/worktrees/${slug}-cycle-"*; do
   _orphan_commits=\$(cd "\$_orphan_wt" && git rev-list --count origin/main..HEAD 2>/dev/null || echo 0)
   if [ "\$_orphan_commits" -gt 0 ]; then
     echo "[loop] FIX-040: recovering orphan worktree \$_orphan_wt (branch \$_orphan_branch, \${_orphan_commits} commits)"
+    # FIX-045: rebase onto origin/main before publishing — avoids BEHIND state on GitHub
+    if ! ( cd "\$_orphan_wt" && git fetch origin main 2>/dev/null && git rebase origin/main 2>/dev/null ); then
+      echo "[loop] FIX-045: orphan \$_orphan_branch rebase failed — skipping recovery (conflict or network error)"
+      continue
+    fi
     _orphan_ok=0
     if ( cd "\$_orphan_wt" && _loop_is_doc_only_change ); then
       ( cd "\$_orphan_wt" && _loop_publish_doc_pr "\$_orphan_branch" "doc: recover orphan \${_orphan_branch}" ) && _orphan_ok=1
@@ -2393,13 +2244,21 @@ if [ "\$_USE_WORKTREE" = "1" ]; then
       _loop_event idle "\${CYCLE_ID}" "" "" || true
       echo "[loop] cycle \${CYCLE_ID}: idle (no new commits); worktree cleaned"
     else
-      if ( cd "\$WT" && _loop_is_doc_only_change ); then
+      _is_doc_only=0
+      ( cd "\$WT" && _loop_is_doc_only_change ) && _is_doc_only=1
+      if [ "\$_is_doc_only" -eq 1 ]; then
         ( cd "\$WT" && _loop_publish_doc_pr "\$BRANCH" "doc: loop cycle \${CYCLE_ID}" )
       else
         ( cd "\$WT" && _loop_publish_pr "\$BRANCH" "loop cycle \${CYCLE_ID}" )
       fi
       _publish_status=\$?
       if [ "\$_publish_status" -eq 0 ]; then
+        # FIX-047: CI green ≠ delivered — wait for actual PR merge before cycle complete
+        if [ "\$_is_doc_only" -eq 0 ]; then
+          if ! ( cd "\$WT" && _loop_wait_pr_merge "\$BRANCH" ); then
+            _worktree_alert "cycle \${CYCLE_ID}: FIX-047: PR not merged within timeout — code may not be in main (BRANCH=\${BRANCH})"
+          fi
+        fi
         _worktree_cleanup "\$WT" "\$BRANCH"
         _loop_event cycle_end "\${CYCLE_ID}" "" "done" || true
         echo "[loop] cycle \${CYCLE_ID}: published; worktree cleaned"
@@ -2731,8 +2590,10 @@ cmd_loop() {
     pause)   _loop_pause ;;
     resume)  _loop_resume ;;
     reset)   _loop_reset ;;
-    notify)  _notify "${1:-roll}" "${2:-}" ;;
-    *) err "Usage: roll loop <on|off|now|test|status|monitor|runs|events|attach|mute|unmute|pause|resume|reset|notify>"; exit 1 ;;
+    notify)       _notify "${1:-roll}" "${2:-}" ;;
+    enforce-tcr)  _loop_enforce_tcr "${1:-}" "${2:-}" ;;
+    precheck-ci)  _loop_precheck_ci ;;
+    *) err "Usage: roll loop <on|off|now|test|status|monitor|runs|events|attach|mute|unmute|pause|resume|reset|notify|enforce-tcr|precheck-ci>"; exit 1 ;;
   esac
 }
 
@@ -3251,6 +3112,20 @@ _gh_repo_slug() {
   printf "%s\n" "$url"
 }
 
+# Returns 0 if gh CLI is installed and executable, 1 otherwise.
+_gh_available() { command -v gh >/dev/null 2>&1; }
+
+# Resolve the GitHub owner/repo slug and set <outvar> to it.
+# Returns 0 on success. Returns 1 (no output) if gh is unavailable or the
+# remote is not a GitHub URL — caller decides how to handle failure.
+_gh_resolve() {
+  local _outvar="$1"
+  _gh_available || return 1
+  local _slug
+  _slug=$(_gh_repo_slug 2>/dev/null) || return 1
+  printf -v "$_outvar" '%s' "$_slug"
+}
+
 # Poll gh run list until current commit's CI completes.
 # Returns 0 on success (or when gh binary missing — graceful skip).
 # Returns 1 on CI failure, timeout, or any gh call failure.
@@ -3259,7 +3134,7 @@ _ci_wait() {
   local interval=15
   local elapsed=0
 
-  command -v gh &>/dev/null || { warn "gh not installed — skipping CI gate  gh 未安装，跳过 CI 检查"; return 0; }
+  _gh_available || { 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)
@@ -3281,6 +3156,17 @@ _ci_wait() {
     }
 
     if [[ -z "$runs" || "$runs" == "[]" ]]; then
+      # FIX-046: CI only fires on pull_request events — without a PR, runs will never appear.
+      # Check if an open PR exists; if not, skip the gate gracefully.
+      local _branch; _branch=$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo "")
+      if [[ -n "$_branch" ]]; then
+        local _pr_json; _pr_json=$(gh -R "$repo_slug" pr list --head "$_branch" --state open --json number 2>/dev/null || echo "1")
+        local _pr_count; _pr_count=$(echo "$_pr_json" | jq 'length' 2>/dev/null || echo "1")
+        if [[ "$_pr_count" == "0" ]]; then
+          warn "No open PR for ${_branch} — CI not triggered; skipping CI gate  当前分支无 PR，CI 未触发，跳过"
+          return 0
+        fi
+      fi
       (( elapsed == 0 )) && echo "  No CI runs found yet, waiting...  尚无 CI 记录，等待触发..."
       sleep "$interval"
       elapsed=$(( elapsed + interval ))
@@ -3320,10 +3206,9 @@ _ci_wait() {
 # Returns 0: ok to proceed (green / pending / unknown / no gh).
 # Returns 1: HEAD CI is definitively red → ALERT written, do not build.
 _loop_precheck_ci() {
-  command -v gh &>/dev/null || return 0
+  local slug; _gh_resolve slug || return 0
 
   local commit; commit=$(git rev-parse HEAD 2>/dev/null) || return 0
-  local slug; slug=$(_gh_repo_slug) || return 0
 
   local runs
   runs=$(gh -R "$slug" run list --commit "$commit" --json conclusion 2>/dev/null) || return 0
@@ -3458,13 +3343,22 @@ _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 dir; dir=$(_loop_heal_dir)
-  local counter="${dir}/${story_id}.count"
-  mkdir -p "$dir"
-  local current; current=$(<"$counter") 2>/dev/null || current=0
-  [[ "$current" =~ ^[0-9]+$ ]] || current=0
+  local state="${_LOOP_STATE:-${HOME}/.shared/roll/loop/state.yaml}"
+  local current=0
+  if [[ -f "$state" ]]; then
+    local raw; raw=$(grep '^heal_count:' "$state" 2>/dev/null | awk '{print $2}')
+    [[ "$raw" =~ ^[0-9]+$ ]] && current="$raw"
+  fi
   [[ "$current" -ge "$max" ]] && return 1
-  echo $((current + 1)) > "$counter"
+  local new=$((current + 1))
+  mkdir -p "$(dirname "$state")"
+  if grep -q '^heal_count:' "$state" 2>/dev/null; then
+    local tmp; tmp=$(mktemp)
+    sed "s/^heal_count:.*/heal_count: ${new}/" "$state" > "$tmp"
+    mv "$tmp" "$state"
+  else
+    echo "heal_count: ${new}" >> "$state"
+  fi
   return 0
 }
 
@@ -3473,7 +3367,11 @@ _loop_self_heal_ci() {
 _loop_clear_heal_state() {
   local story_id="$1"
   [[ -z "$story_id" ]] && return 0
-  rm -f "$(_loop_heal_dir)/${story_id}.count" 2>/dev/null
+  local state="${_LOOP_STATE:-${HOME}/.shared/roll/loop/state.yaml}"
+  [[ ! -f "$state" ]] && return 0
+  local tmp; tmp=$(mktemp)
+  grep -v '^heal_count:' "$state" > "$tmp"
+  mv "$tmp" "$state"
   return 0
 }
 
@@ -3746,7 +3644,7 @@ _loop_pr_rebase_stale() {
   local pr="$1" head_ref="$2"
   [ -n "$pr" ] && [ -n "$head_ref" ] || return 0
 
-  local slug; slug=$(_gh_repo_slug 2>/dev/null) || return 0
+  local slug; _gh_resolve slug || return 0
 
   local pr_json
   pr_json=$(gh -R "$slug" pr view "$pr" --json headRepository,headRepositoryOwner,isCrossRepository 2>/dev/null) || return 0
@@ -3780,9 +3678,7 @@ _loop_pr_rebase_stale() {
 #   Walks open PRs and routes each by classification.
 #   Lenient on gh unavailability — returns 0 so the loop continues to BACKLOG.
 _loop_pr_inbox() {
-  command -v gh >/dev/null 2>&1 || return 0
-
-  local slug; slug=$(_gh_repo_slug 2>/dev/null) || return 0
+  local slug; _gh_resolve slug || return 0
   local prs_json
   prs_json=$(gh -R "$slug" pr list --state open \
     --json number,headRefName,author,title \
@@ -4219,15 +4115,10 @@ _loop_cleanup_stale_cycle_branches() {
 _loop_publish_pr() {
   local branch="$1"
   local title="${2:-loop cycle ${branch#loop/}}"
-  if ! command -v gh >/dev/null 2>&1; then
-    _worktree_alert "_loop_publish_pr: gh not installed; cannot publish PR for ${branch}"
+  local slug; _gh_resolve slug || {
+    _worktree_alert "_loop_publish_pr: gh not installed or origin is not a github repo; cannot publish PR for ${branch}"
     return 2
-  fi
-  local slug; slug=$(_gh_repo_slug 2>/dev/null) || slug=""
-  if [ -z "$slug" ]; then
-    _worktree_alert "_loop_publish_pr: origin remote is not a github repo; cannot publish PR for ${branch}"
-    return 2
-  fi
+  }
   local _push_err
   _push_err=$(git push origin "$branch" 2>&1) || {
     _worktree_alert "_loop_publish_pr: push origin ${branch} failed: ${_push_err}"
@@ -4253,6 +4144,29 @@ _loop_publish_pr() {
   return 0
 }
 
+# _loop_wait_pr_merge <branch>
+#   FIX-047: poll GitHub until PR for <branch> is merged (confirms delivery).
+#   Returns 0: merged. Returns 1: CLOSED or timeout.
+#   Gracefully skips (returns 0) when gh is unavailable or slug unparseable.
+#   Timeout: ROLL_PR_MERGE_TIMEOUT (default 600s).
+_loop_wait_pr_merge() {
+  local branch="$1"
+  local timeout="${ROLL_PR_MERGE_TIMEOUT:-600}"
+  local interval=30
+  local elapsed=0
+  local slug; _gh_resolve slug || return 0
+  while (( elapsed < timeout )); do
+    local state; state=$(gh -R "$slug" pr view "$branch" --json state -q .state 2>/dev/null || echo "UNKNOWN")
+    case "$state" in
+      MERGED) return 0 ;;
+      CLOSED) return 1 ;;
+    esac
+    sleep "$interval"
+    elapsed=$(( elapsed + interval ))
+  done
+  return 1
+}
+
 # _loop_is_doc_only_change
 #   Returns 0 if every file changed since origin/main is doc-only
 #   (BACKLOG.md, CHANGELOG.md, PROPOSALS.md, docs/, .claude/).
@@ -4271,15 +4185,10 @@ _loop_is_doc_only_change() {
 _loop_publish_doc_pr() {
   local branch="$1"
   local title="${2:-doc update ${branch#loop/}}"
-  if ! command -v gh >/dev/null 2>&1; then
-    _worktree_alert "_loop_publish_doc_pr: gh not installed; cannot publish PR for ${branch}"
+  local slug; _gh_resolve slug || {
+    _worktree_alert "_loop_publish_doc_pr: gh not installed or origin is not a github repo; cannot publish PR for ${branch}"
     return 2
-  fi
-  local slug; slug=$(_gh_repo_slug 2>/dev/null) || slug=""
-  if [ -z "$slug" ]; then
-    _worktree_alert "_loop_publish_doc_pr: origin remote is not a github repo; cannot publish PR for ${branch}"
-    return 2
-  fi
+  }
   if ! git push origin "$branch" --quiet 2>/dev/null; then
     _worktree_alert "_loop_publish_doc_pr: push origin ${branch} failed"
     return 1
@@ -4657,7 +4566,7 @@ cmd_ci() {
     return
   fi
 
-  command -v gh &>/dev/null || { warn "gh not installed  gh 未安装"; return 0; }
+  _gh_available || { 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; }
@@ -4962,7 +4871,7 @@ _dash_ac_completion() {
 # ④ DoD CI signal — query gh for HEAD's most-recent run conclusion.
 # Returns: success | pending | failure | none
 _dash_ci_status() {
-  command -v gh &>/dev/null || { echo "none"; return; }
+  _gh_available || { echo "none"; return; }
   local commit; commit=$(git rev-parse HEAD 2>/dev/null) || { echo "none"; return; }
   local slug; slug=$(_gh_repo_slug 2>/dev/null) || true
   local out

package/lib/loop-fmt.py

@@ -9,15 +9,77 @@ Tier 1 (signal):     tcr commit, story skill, peer verdict, ci gate, pr merge, e
 import sys
 import json
 import re
+import os
+import threading
+import time
 from datetime import datetime, timezone
 
+_SPIN_ENABLED = os.environ.get("LOOP_FMT_NO_SPIN", "0") != "1"
+SPIN_FRAMES   = "⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏"
+
 DARK_GRAY = "\033[90m"
 CYAN      = "\033[36m"
 WHITE     = "\033[97m"
 GREEN     = "\033[32m"
 RED       = "\033[31m"
+YELLOW    = "\033[33m"
 RESET     = "\033[0m"
 
+
+class Spinner:
+    """Animated wait indicator for long-running operations.
+
+    In production (LOOP_FMT_NO_SPIN=0): background thread writes frames using \\r.
+    In test mode  (LOOP_FMT_NO_SPIN=1): writes a static ⏳ line to stdout instead.
+    """
+    def __init__(self):
+        self._thread  = None
+        self._running = False
+        self._label   = ""
+        self._lock    = threading.Lock()
+
+    @property
+    def active(self):
+        return self._running
+
+    def start(self, label):
+        with self._lock:
+            if self._running:
+                self._label = label  # update without restart
+                return
+            self._label   = label
+            self._running = True
+        if _SPIN_ENABLED:
+            self._thread = threading.Thread(target=self._run, daemon=True)
+            self._thread.start()
+        else:
+            sys.stdout.write(f"  {YELLOW}⏳ {label}...{RESET}\n")
+            sys.stdout.flush()
+
+    def stop(self):
+        with self._lock:
+            was_running   = self._running
+            self._running = False
+        if self._thread:
+            self._thread.join(timeout=0.3)
+            self._thread = None
+        if _SPIN_ENABLED and was_running:
+            sys.stdout.write(f"\r{' ' * 60}\r")
+            sys.stdout.flush()
+
+    def _run(self):
+        i = 0
+        while self._running:
+            with self._lock:
+                label = self._label
+            frame = SPIN_FRAMES[i % len(SPIN_FRAMES)]
+            sys.stdout.write(f"\r  {YELLOW}{frame} {label}...{RESET}")
+            sys.stdout.flush()
+            time.sleep(0.12)
+            i += 1
+        sys.stdout.write(f"\r{' ' * 60}\r")
+        sys.stdout.flush()
+
 SUPPRESS_TOOLS = {"Read", "Glob", "Grep", "ReadMcpResourceTool", "ListMcpResourcesTool",
                   "WebFetch", "WebSearch", "TaskCreate", "TaskGet", "TaskList",
                   "TaskUpdate", "TaskOutput", "TaskStop"}
@@ -45,13 +107,15 @@ def stamp(text, muted=False):
 
 class LoopFmt:
     def __init__(self):
-        self.last_bash_cmd = ""
-        self.tcr_count = 0
+        self.last_bash_cmd   = ""
+        self.tcr_count       = 0
         self.last_test_count = None
-        self.cycle_num = None
-        self.pending_commit = False
-        self.pending_pr = False
-        self.pending_ci = False
+        self.cycle_num       = None
+        self.pending_commit  = False
+        self.pending_pr      = False
+        self.pending_ci      = False
+        self.pending_story   = False
+        self.spinner         = Spinner()
 
     def _extract_cycle_num(self, text):
         m = re.search(r'cycle[#\s]+(\d+)', text, re.IGNORECASE)
@@ -139,8 +203,10 @@ class LoopFmt:
                 self.pending_commit = True
             elif re.search(r'gh pr (create|merge)', cmd):
                 self.pending_pr = True
-            elif re.search(r'(roll ci|npm run ci|ci:local)', cmd):
+                self.spinner.start("merging PR")
+            elif re.search(r'(roll ci|npm run ci|_ci_wait|ci:local)', cmd):
                 self.pending_ci = True
+                self.spinner.start("waiting for CI")
             return  # Wait for result
 
         if name == "Skill":
@@ -151,6 +217,8 @@ class LoopFmt:
                 print()
                 print(stamp(f"cycle #{self.cycle_num or '?'} — picking story"))
                 print(step("story", us_id, trunc(args, 60)))
+                self.pending_story = True
+                self.spinner.start("executing story")
             return
 
         # All other tools (Agent, ToolSearch, etc.): suppress
@@ -189,7 +257,13 @@ class LoopFmt:
                     print(step("tcr", commit_hash, f"{commit_msg}{test_part}"))
                 return
 
+            if self.pending_story:
+                self.pending_story = False
+                self.spinner.stop()
+                return  # story result content suppressed; TCR events showed the work
+
             if self.pending_pr:
+                self.spinner.stop()
                 self.pending_pr = False
                 m = re.search(r'#(\d+)', text)
                 if m:
@@ -201,6 +275,7 @@ class LoopFmt:
                 return
 
             if self.pending_ci:
+                self.spinner.stop()
                 self.pending_ci = False
                 has_green = re.search(r'(green|pass|success|all tests)', text, re.IGNORECASE)
                 has_red   = re.search(r'(red|fail|error)', text, re.IGNORECASE)

package/package.json

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

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

@@ -416,6 +416,10 @@ prompt 会包含：
   （即使没有 deep doc 也要列）
 - Feature 名跟 `docs/features/<file>.md` 文件名一致时，加链接到该 md
 - 没有对应 deep doc 的 Feature，**只写 plain text 不加链接**
+- **Planning distinction（US-DOC-011）**：
+  - 该 Feature 下**所有** Story 均为 `📋 Todo` → 在描述末尾追加 `*(规划中)*`
+  - 只要有 **≥1 个** `✅ Done` Story → 正常展示，**不加**任何标记
+  - 一眼可见：规划中的 Feature 在每个 Epic 分组的末尾列出
 - 描述写 1 句话 **产品视角**：用户能用它做什么，避免实现细节
 - 分组用 BACKLOG 的 Epic 名，原序，不重排
 - Core Highlights 从所有 Features 里挑 3-5 个最能代表产品定位的，

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

@@ -45,7 +45,9 @@ $roll-.review unstaged
 $roll-.review files src/utils.ts
 ```
 
-## Review Dimensions (6 Core Dimensions)
+## Review Dimensions (7 Core Dimensions)
+
+Original 6 dimensions plus Reuse (added in REFACTOR-022, simplify three-axis integration):
 
 ```
 ┌─────────────────────────────────────────────────────────┐
@@ -54,13 +56,42 @@ $roll-.review files src/utils.ts
 │  ✅ Correctness     - Logic is correct, no bugs         │
 │  ✅ Security        - No vulnerabilities, input valid.  │
 │  ✅ Maintainability - Clear naming, sound structure     │
+│     Quality anti-patterns (check each):                 │
+│       □ Redundant state / cached values that could be   │
+│         derived directly                                │
+│       □ Parameter sprawl — new param vs. restructure    │
+│       □ Copy-paste with slight variation (near-dup)     │
+│       □ Leaky abstraction — exposes internal details    │
+│       □ Stringly-typed — raw string where constant      │
+│         / enum exists                                   │
+│       □ Unnecessary JSX nesting (no layout value)       │
+│       □ Nested conditionals ≥3 deep (ternary chains,    │
+│         nested if/else) — flatten with early return     │
+│       □ Unnecessary comments explaining WHAT            │
 │  ✅ Performance     - No performance pitfalls           │
+│     Efficiency anti-patterns (check each):              │
+│       □ Redundant computation / repeated file read /    │
+│         duplicate API call / N+1 pattern                │
+│       □ Missed concurrency — independent ops sequential │
+│       □ Hot-path bloat — blocking work in startup or    │
+│         per-request path                                │
+│       □ Loop no-op updates — missing change-detection   │
+│         guard                                           │
+│       □ TOCTOU existence pre-check — operate directly + │
+│         handle error instead                            │
+│       □ Memory — unbounded structures / missing cleanup │
+│       □ Overly broad op — reading full file for a slice │
 │  ✅ Testability     - Easy to test, edge cases covered  │
 │  ✅ Scope           - Focused on current task, no       │
 │                       unrelated changes                 │
+│  ✅ Reuse           - No new code duplicating existing  │
+│     □ New function duplicates existing utility/helper   │
+│     □ Inline logic replaceable by existing tool         │
 └─────────────────────────────────────────────────────────┘
 ```
 
+**Usage in TCR**: Each micro-step review is a lightweight self-check against this checklist — no sub-agents, zero extra token cost. The three-axis deep review with parallel agents runs once per Story in `$roll-build` Phase 7.
+
 ## Severity Levels and Decisions
 
 | Level | Definition | Decision |

package/skills/roll-build/SKILL.md

@@ -378,33 +378,51 @@ EOF
 chmod +x .git/hooks/pre-push
 ```
 
-### Phase 7: Pre-Push Code Review
+### Phase 7: Pre-Push Code Review (Three-Axis Deep Review)
+
+This phase runs **once per Story** (not per micro-step) on the full accumulated diff.
+Per-micro-step review uses `$roll-.review staged` inline checklist (zero extra cost).
+
+**Phase 3.5 vs Phase 7 split**: Phase 3.5 (Peer Review) focuses on architectural direction
+and approach before coding begins. Phase 7 focuses on implementation quality after all
+micro-steps are done — catching issues that only appear at diff scale (parameter sprawl
+across files, copy-paste patterns, cross-file N+1, etc.).
 
 ```bash
-$roll-.review staged
+# Capture full Story diff
+git diff main...HEAD
 ```
 
-**Review output:**
+**Launch three review agents in parallel** (each receives the full diff):
+
 ```
-🔍 Self Review Report
-├── Scope: X files (+Y/-Z lines)
-├── 🔴 Critical: N issues (must fix)
-├── 🟡 Warnings: N issues (should fix)
-├── 🟢 Suggestions: N items (optional)
-└── ✅ Passed dimensions: [Quality, Design, Scope, ...]
+Agent 1: Reuse Review
+  → Search for existing utilities / helpers the new code could use instead
+  → Flag any new function that duplicates existing functionality
+  → Flag inline logic replaceable by existing tools
+
+Agent 2: Quality Review
+  → Redundant state, Parameter sprawl, Copy-paste near-duplicate,
+     Leaky abstraction, Stringly-typed, JSX nesting,
+     Nested conditionals ≥3 deep, Unnecessary comments
+
+Agent 3: Efficiency Review
+  → Redundant computation / N+1, Missed concurrency,
+     Hot-path bloat, Loop no-op updates, TOCTOU existence pre-check,
+     Memory leaks, Overly broad operations
 ```
 
-**Review dimensions** (correctness guaranteed by TCR):
-- 🎯 **Quality**: Naming clarity, DRY, function size, readability
-- 📐 **Design**: Architecture, abstraction level, separation of concerns
-- ⚠️ **Scope**: No opportunistic changes
-- 📝 **Documentation**: Comments where needed
+Wait for all three agents to complete. Aggregate findings → fix each issue
+(false positives: note and skip, no debate) → summarize what was fixed.
+
+**Fallback**: If parallel agent invocation fails, run `$roll-.review staged` on
+the full diff as a single-pass fallback — do not skip review entirely.
 
 **Decision:**
 ```
 🔴 Critical > 0 → Fix via new TCR cycle → Re-review
 🟡 Warnings > 0 → Fix if quick (< 5 min) or document
-🟢 Suggestions / ✅ All clear → Proceed to push
+🟢 Suggestions / ✅ All clear → Proceed to Phase 8
 ```
 
 ### Phase 8: Commit & Push

package/skills/roll-loop/SKILL.md

@@ -96,7 +96,7 @@ fi
 
 ### Step 1.5 — Pre-run CI Health Check
 
-Call `_loop_precheck_ci` before scanning BACKLOG. This is a **defensive gate**
+Call `roll loop precheck-ci` before scanning BACKLOG. This is a **defensive gate**
 against building on a broken base — if the most recent commit on the branch
 has red CI, the loop must not stack new commits on top (which would create the
 exact stuck-red state FIX-026 traces to).
@@ -105,7 +105,7 @@ exact stuck-red state FIX-026 traces to).
 - HEAD CI red → write ALERT, **do not pick up any stories this cycle**,
   exit cleanly. The next cycle will retry; the human must fix CI manually
   (typically by reverting or pushing a green commit) before the loop resumes.
-- `gh` missing or repo unparseable → graceful skip (`_loop_precheck_ci`
+- `gh` missing or repo unparseable → graceful skip (`roll loop precheck-ci`
   returns 0); the post-build `_loop_enforce_ci` remains the strict gate.
 
 ### Step 1.6 — PR Inbox (US-AUTO-034)
@@ -229,7 +229,7 @@ run_id: loop-20260510-0200
 
 After each item completes:
 
-1. **TCR 硬校验** — call `_loop_enforce_tcr <story_id> <started_at>`:
+1. **TCR 硬校验** — call `roll loop enforce-tcr <story_id> <started_at>`:
    - 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
@@ -246,34 +246,36 @@ After each item completes:
      (return 0). Any other `gh` error is **not** "gh unavailable" — it is a
      hard failure and must block the gate.
 
-   **CI self-heal (US-AUTO-041)** — bounded auto-fix before ALERT:
-
-   ```
-   shell: _loop_self_heal_ci <story_id>
-     ├── exit 0 → heal attempt allowed (counter incremented)
-     │   1. Capture failure summary:
-     │      gh run view --log-failed --repo <slug> $(gh run list --commit HEAD \
-     │        --json databaseId,conclusion -L 5 | jq -r '.[] | select(.conclusion=="failure") | .databaseId' | head -1) \
-     │        2>/dev/null | head -200 > /tmp/roll-heal-<story_id>.log
-     │   2. Invoke Skill("roll-fix") with brief:
-     │      "CI red after <story_id>. Failing run logs at /tmp/roll-heal-<story_id>.log.
-     │       Diagnose root cause, fix via TCR, commit, push. Do NOT change <story_id>'s
-     │       BACKLOG status — it stays ✅ Done. The fix is a follow-up."
-     │   3. After roll-fix completes, return to step 2 (CI Gate) — re-run
-     │      `roll ci --wait`. The counter prevents infinite loops.
-     │
-     └── exit 1 → heal exhausted (>=ROLL_LOOP_HEAL_MAX, default 2) or disabled
-                  (ROLL_LOOP_NO_HEAL=1):
-         1. Keep story as ✅ Done (commits are already on main — CI red is a
-            follow-up problem, not a story-failure)
-         2. Write ALERT to `~/.shared/roll/loop/ALERT.md` with:
-            - story ID, time, commit SHA
-            - heal attempts made (read counter from
-              `${ROLL_LOOP_DIR:-~/.shared/roll/loop}/heal/<story_id>.count`)
-            - last failure summary (head of /tmp/roll-heal-<story_id>.log)
-            - suggested actions: `$roll-fix` manually / inspect CI / `roll loop reset`
-         3. Skip to next story.
-   ```
+   **CI self-heal (US-AUTO-041)** — bounded auto-fix before ALERT.
+
+   Call `_loop_self_heal_ci <story_id>` to check if another attempt is permitted.
+
+   **Path A — attempt allowed (exit 0, counter incremented in `state.yaml`):**
+
+   1. Capture failure summary:
+      ```
+      gh run view --log-failed --repo <slug> \
+        $(gh run list --commit HEAD --json databaseId,conclusion -L 5 \
+          | jq -r '.[] | select(.conclusion=="failure") | .databaseId' | head -1) \
+        2>/dev/null | head -200 > /tmp/roll-heal-<story_id>.log
+      ```
+   2. Invoke `Skill("roll-fix")` with brief:
+      `"CI red after <story_id>. Failing run logs at /tmp/roll-heal-<story_id>.log.
+      Diagnose root cause, fix via TCR, commit, push. Do NOT change <story_id>'s
+      BACKLOG status — it stays ✅ Done. The fix is a follow-up."`
+   3. After `roll-fix` completes, return to step 2 (CI Gate) — re-run `roll ci --wait`.
+      The counter in `state.yaml` prevents infinite loops.
+
+   **Path B — heal exhausted (≥`ROLL_LOOP_HEAL_MAX`, default 2) or disabled (`ROLL_LOOP_NO_HEAL=1`) (exit 1):**
+
+   1. Keep story as ✅ Done — commits are already on main; CI red is a follow-up
+      problem, not a story failure.
+   2. Write ALERT to `~/.shared/roll/loop/ALERT.md` with:
+      - story ID, time, commit SHA
+      - heal attempts made (read `heal_count:` from `state.yaml`)
+      - last failure summary (head of `/tmp/roll-heal-<story_id>.log`)
+      - suggested actions: `$roll-fix` manually / inspect CI / `roll loop reset`
+   3. Skip to next story.
 
    **Bypass for debugging / cost control:** set `ROLL_LOOP_NO_HEAL=1` to restore
    pre-US-AUTO-041 fail-fast behaviour.