@seanyao/roll 2026.516.1 → 2026.517.2

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## v2026.517.2
+- **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.515.1
 
 - **New**: `roll brief` / `roll dream` 生成文档后自动提交推送 — 每次晨报和夜检不再需要手动 commit `[loop]`
@@ -170,7 +187,6 @@ Roll 从「技能编排工具」变成了「自主执行系统」——三个新
 
 ## 2026.05.06
 - **Added**: OpenCode 集成 — 检测 opencode 环境，自动同步全局 AGENTS.md 规则文件
-- **Added**: roll-bipo-onboard 技能 — 新员工入职引导流程技能，含 bats 测试
 - **Improved**: Git 提交归属 — 用 Co-Authored-By trailer 替代 [client] 前缀，更标准的多 AI 工具归属方式
 - **Improved**: AGENTS.md 加入 Scope Gate — 防止技能执行时越界修改不相关文件
 

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.516.1"
+VERSION="2026.517.2"
 ROLL_HOME="${ROLL_HOME:-${HOME}/.roll}"
 ROLL_CONFIG="${ROLL_HOME}/config.yaml"
 ROLL_GLOBAL="${ROLL_HOME}/conventions/global"
@@ -1493,45 +1493,19 @@ _peer_call() {
     local out_file
     out_file=$(mktemp)
     local cmd_str
-    case "$to" in
-      claude)   cmd_str="claude -p --output-format text $(printf %q "$prompt")" ;;
-      kimi)     cmd_str="kimi --quiet -p $(printf %q "$prompt")" ;;
-      pi)       cmd_str="pi -p $(printf %q "$prompt")" ;;
-      deepseek) cmd_str="deepseek $(printf %q "$prompt")" ;;
-      codex)    cmd_str="codex exec --json --output-last-message $(printf %q "$prompt")" ;;
-      opencode) cmd_str="opencode run $(printf %q "$prompt")" ;;
-      *)
-        err "Unsupported peer: $to  不支持的 peer: $to"
-        return 1 ;;
-    esac
+    cmd_str=$(_agent_cmd_str "$to" peer "$prompt") || {
+      err "Unsupported peer: $to  不支持的 peer: $to"
+      return 1
+    }
     _peer_dispatch_in_tmux "$session" "$cmd_str" "$out_file" "$stderr_log" "$call_timeout"
     output="$(cat "$out_file" 2>/dev/null || true)"
     rm -f "$out_file"
   else
-    case "$to" in
-      claude)
-        output="$(claude -p --output-format text "$prompt" 2>"$stderr_log" || true)"
-        ;;
-      kimi)
-        output="$(kimi --quiet -p "$prompt" 2>"$stderr_log" || true)"
-        ;;
-      pi)
-        output="$(pi -p "$prompt" 2>"$stderr_log" || true)"
-        ;;
-      deepseek)
-        output="$(deepseek "$prompt" 2>"$stderr_log" || true)"
-        ;;
-      codex)
-        output="$(codex exec --json --output-last-message "$prompt" 2>"$stderr_log" || true)"
-        ;;
-      opencode)
-        output="$(opencode run "$prompt" 2>"$stderr_log" || true)"
-        ;;
-      *)
-        err "Unsupported peer: $to  不支持的 peer: $to"
-        return 1
-        ;;
-    esac
+    _agent_argv "$to" peer "$prompt" || {
+      err "Unsupported peer: $to  不支持的 peer: $to"
+      return 1
+    }
+    output="$("${_AGENT_ARGV[@]}" 2>"$stderr_log" || true)"
   fi
 
   printf '%s\n' "$output"
@@ -1884,21 +1858,71 @@ _parse_review_verdict() {
   echo "${type}${reason:+:${reason}}"
 }
 
+# REFACTOR-017: single source of truth for agent invocation argv.
+# Sets the global _AGENT_ARGV array to the command + args for (agent, mode, prompt).
+# Modes:
+#   text  — structured text (claude --output-format text; codex exec)
+#   plain — default output (claude -p; codex exec)
+#   peer  — peer protocol (claude --output-format text; codex --json --output-last-message)
+# Returns 1 on unknown agent. Adding a new agent only needs an entry here.
+_agent_argv() {
+  local agent="$1" mode="$2" prompt="$3"
+  case "$agent" in
+    claude)
+      case "$mode" in
+        text|peer) _AGENT_ARGV=(claude -p --output-format text "$prompt") ;;
+        *)         _AGENT_ARGV=(claude -p "$prompt") ;;
+      esac ;;
+    kimi)     _AGENT_ARGV=(kimi --quiet -p "$prompt") ;;
+    deepseek) _AGENT_ARGV=(deepseek "$prompt") ;;
+    pi)       _AGENT_ARGV=(pi -p "$prompt") ;;
+    codex)
+      case "$mode" in
+        peer) _AGENT_ARGV=(codex exec --json --output-last-message "$prompt") ;;
+        *)    _AGENT_ARGV=(codex exec "$prompt") ;;
+      esac ;;
+    opencode) _AGENT_ARGV=(opencode run "$prompt") ;;
+    *) return 1 ;;
+  esac
+}
+
+# Build a printf %q-escaped command string for (agent, mode, prompt).
+# Used where the command must be passed as a string (e.g. tmux send-keys).
+_agent_cmd_str() {
+  _agent_argv "$@" || return 1
+  local i out
+  printf -v out '%q' "${_AGENT_ARGV[0]}"
+  for ((i = 1; i < ${#_AGENT_ARGV[@]}; i++)); do
+    printf -v out '%s %q' "$out" "${_AGENT_ARGV[i]}"
+  done
+  printf '%s' "$out"
+}
+
+# Splice --dangerously-skip-permissions into _AGENT_ARGV for claude. Used by
+# trusted, human-triggered, or autonomous flows that should not be blocked by
+# Claude Code's pre-write "approve diff" UX (which silently never gets
+# approved in `claude -p` pipe mode). No-op for non-claude agents and for
+# already-bypassed argvs.
+_agent_bypass_claude_perms() {
+  [[ "${_AGENT_ARGV[0]}" == "claude" ]] || return 0
+  local arg
+  for arg in "${_AGENT_ARGV[@]}"; do
+    [[ "$arg" == "--dangerously-skip-permissions" ]] && return 0
+  done
+  _AGENT_ARGV=("${_AGENT_ARGV[@]:0:2}" --dangerously-skip-permissions "${_AGENT_ARGV[@]:2}")
+}
+
 _agent_run_skill() {
   local skill="$1"
   local agent; agent=$(_project_agent)
   local skill_file="${ROLL_HOME}/skills/${skill}/SKILL.md"
   [[ -f "$skill_file" ]] || { err "Skill not found: ${skill}"; return 1; }
   local content; content=$(_skill_content "$skill_file")
-  case "$agent" in
-    claude)   claude -p --output-format text "$content" ;;
-    kimi)     kimi --quiet -p "$content" ;;
-    deepseek) deepseek "$content" ;;
-    pi)       pi -p "$content" ;;
-    codex)    codex exec "$content" ;;
-    opencode) opencode run "$content" ;;
-    *)        err "Unknown agent '${agent}'. Run: roll agent use <claude|kimi|deepseek|pi|codex|opencode>"; return 1 ;;
-  esac
+  _agent_argv "$agent" text "$content" || {
+    err "Unknown agent '${agent}'. Run: roll agent use <claude|kimi|deepseek|pi|codex|opencode>"
+    return 1
+  }
+  "${_AGENT_ARGV[@]}"
 }
 
 cmd_review_pr() {
@@ -1958,15 +1982,8 @@ cmd_review_pr() {
   local agent; agent=$(_project_agent)
   local output
   info "Reviewing PR #${pr_number} with ${agent}..."
-  case "$agent" in
-    claude)   output=$(claude -p --output-format text "$prompt" 2>/dev/null) ;;
-    kimi)     output=$(kimi --quiet -p "$prompt" 2>/dev/null) ;;
-    deepseek) output=$(deepseek "$prompt" 2>/dev/null) ;;
-    pi)       output=$(pi -p "$prompt" 2>/dev/null) ;;
-    codex)    output=$(codex exec "$prompt" 2>/dev/null) ;;
-    opencode) output=$(opencode run "$prompt" 2>/dev/null) ;;
-    *)        err "Unknown agent '${agent}'"; return 1 ;;
-  esac
+  _agent_argv "$agent" text "$prompt" || { err "Unknown agent '${agent}'"; return 1; }
+  output=$("${_AGENT_ARGV[@]}" 2>/dev/null)
 
   echo "$output"
 
@@ -2046,9 +2063,9 @@ cmd_agent() {
 # ═══════════════════════════════════════════════════════════════════════════════
 
 _LOOP_TAG="# roll-loop"
-_SHARED_ROOT="${HOME}/.shared/roll"
-_LOOP_STATE="${HOME}/.shared/roll/loop/state.yaml"
-_LOOP_ALERT="${HOME}/.shared/roll/loop/ALERT.md"
+: "${_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"
@@ -2168,7 +2185,11 @@ _write_loop_runner_script() {
   # stream-json enables realtime streaming; loop-fmt.py humanizes the events.
   local fmt_script="${ROLL_PKG_DIR}/lib/loop-fmt.py"
   local roll_bin="${ROLL_PKG_DIR}/bin/roll"
-  local cmd_verbose="${cmd/claude -p/claude -p --verbose --output-format stream-json}"
+  # FIX-041: loop cycle is autonomous — permission prompts and sandbox path
+  # restrictions only cause the cycle to burn turns asking for approvals
+  # it cannot receive. Bypass all permission checks for the inner claude
+  # invocation. Worktree isolation contains the blast radius.
+  local cmd_verbose="${cmd/claude -p/claude -p --verbose --dangerously-skip-permissions --output-format stream-json}"
   # US-AUTO-037: strip leading `cd "<path>" && ` (callers like
   # _install_launchd_plists prepend it). The runner now manages cwd itself
   # — pointing at the worktree when isolation succeeds, project_path otherwise.
@@ -2220,6 +2241,35 @@ WT="\$(_worktree_path "${slug}" "cycle-\${CYCLE_ID}")"
 BRANCH="loop/cycle-\${CYCLE_ID}"
 _USE_WORKTREE=0
 cd "${project_path}" 2>/dev/null || true
+# FIX-040: orphan worktree recovery — scan for worktrees left by previous failed
+# cycles (publish failed or inner script was SIGKILL'd). Attempt to publish each
+# before starting the new cycle. Glob is chronological via timestamp in name.
+for _orphan_wt in "\${_SHARED_ROOT}/worktrees/${slug}-cycle-"*; do
+  [ -d "\$_orphan_wt" ] || continue
+  # Confirm it's a real worktree directory (not glob literal when no matches)
+  [ -d "\${_orphan_wt}/.git" ] || [ -f "\${_orphan_wt}/.git" ] || continue
+  _orphan_branch=\$(cd "\$_orphan_wt" && git rev-parse --abbrev-ref HEAD 2>/dev/null || echo "")
+  [ -z "\$_orphan_branch" ] && continue
+  _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)"
+    _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
+    else
+      ( cd "\$_orphan_wt" && _loop_publish_pr "\$_orphan_branch" "recover orphan \${_orphan_branch}" ) && _orphan_ok=1
+    fi
+    if [ "\$_orphan_ok" -eq 1 ]; then
+      _worktree_cleanup "\$_orphan_wt" "\$_orphan_branch"
+      echo "[loop] FIX-040: orphan recovered and cleaned: \$_orphan_branch"
+    else
+      echo "[loop] FIX-040: orphan recovery publish failed for \$_orphan_branch — leaving preserved"
+    fi
+  else
+    echo "[loop] FIX-040: orphan worktree \$_orphan_wt has no commits; cleaning up"
+    _worktree_cleanup "\$_orphan_wt" "\$_orphan_branch"
+  fi
+done
 # US-AUTO-038: snapshot orphan claude/* branches before claude runs so the
 # post-claude cleanup can diff and delete only this session's additions.
 CLAUDE_BRANCH_SNAPSHOT="\$(_claude_remote_snapshot "${project_path}")"
@@ -2229,8 +2279,12 @@ if _worktree_fetch_origin main \\
   _worktree_submodule_init "\$WT" 2>/dev/null || true
   echo "[loop] cycle \${CYCLE_ID}: worktree \$WT on \$BRANCH"
 else
-  echo "[loop] cycle \${CYCLE_ID}: worktree setup failed; running in main tree (no isolation)"
-  WT="${project_path}"
+  # P3 fix: skip the cycle entirely when worktree isolation fails.
+  # --dangerously-skip-permissions is only safe paired with worktree isolation;
+  # 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)"
+  exit 0
 fi
 
 FMT="${fmt_script}"
@@ -2282,12 +2336,34 @@ if [ "\$_USE_WORKTREE" = "1" ]; then
           _worktree_cleanup "\$WT" "\$BRANCH"
           echo "[loop] cycle \${CYCLE_ID}: gh unavailable; merged via ff and cleaned up"
         else
-          _worktree_alert "cycle \${CYCLE_ID}: gh unavailable AND merge_back failed; worktree preserved at \$WT"
-          echo "[loop] cycle \${CYCLE_ID}: gh+merge_back both failed; worktree preserved at \$WT"
+          # FIX-039: gh unavailable + merge_back failed — push orphan branch+tag to origin
+          # as final safety net so code is never local-only before worktree cleanup.
+          _orphan_tag="loop-orphan-\${CYCLE_ID}"
+          if ( cd "\$WT" && git push origin "\$BRANCH" 2>/dev/null \
+               && git tag "\$_orphan_tag" 2>/dev/null \
+               && git push origin "\$_orphan_tag" 2>/dev/null ); then
+            _worktree_cleanup "\$WT" "\$BRANCH"
+            _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
+            _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
         fi
       else
-        _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"
+        # FIX-039: PR publish failed — push orphan branch+tag to origin as safety net.
+        # (_loop_publish_pr may have already pushed the branch; git push is idempotent.)
+        _orphan_tag="loop-orphan-\${CYCLE_ID}"
+        if ( cd "\$WT" && git push origin "\$BRANCH" 2>/dev/null \
+             && git tag "\$_orphan_tag" 2>/dev/null \
+             && git push origin "\$_orphan_tag" 2>/dev/null ); then
+          _worktree_cleanup "\$WT" "\$BRANCH"
+          _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
+          _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
@@ -2379,7 +2455,7 @@ fi
 echo "\$\$" > "\$LOCK"
 trap 'rm -f "\$LOCK"' EXIT
 if command -v tmux >/dev/null 2>&1; then
-  tmux list-sessions -F "#{session_name}" 2>/dev/null | grep "^roll-loop-" | while read _s; do
+  tmux list-sessions -F "#{session_name}" 2>/dev/null | grep "^roll-loop-${slug}\$" | while read _s; do
     tmux kill-session -t "\$_s" 2>/dev/null || true
   done
   tmux new-session -d -s "\$SESSION" -x 200 -y 50 "bash \"\$INNER_SCRIPT\""
@@ -2520,17 +2596,24 @@ _install_launchd_plists() {
 _agent_skill_cmd() {
   local skill_path="$1"
   local agent; agent=$(_project_agent)
-  # Strip YAML frontmatter inline for cron commands
   local strip="awk 'NR==1 && /^---$/{skip=1;next} skip && /^---$/{skip=0;next} !skip{print}' '${skill_path}'"
-  case "$agent" in
-    claude)   local _bin; _bin=$(command -v claude 2>/dev/null || echo "claude"); echo "${_bin} -p \"\$(${strip})\"" ;;
-    kimi)     echo "kimi --quiet -p \"\$(${strip})\"" ;;
-    deepseek) echo "deepseek \"\$(${strip})\"" ;;
-    pi)       echo "pi -p \"\$(${strip})\"" ;;
-    codex)    echo "codex exec \"\$(${strip})\"" ;;
-    opencode) echo "opencode run \"\$(${strip})\"" ;;
-    *)        err "Unknown agent '${agent}'. Run: roll agent use <claude|kimi|deepseek|pi|codex|opencode>"; return 1 ;;
-  esac
+  _agent_argv "$agent" plain "__PROMPT__" || {
+    err "Unknown agent '${agent}'. Run: roll agent use <claude|kimi|deepseek|pi|codex|opencode>"
+    return 1
+  }
+  # Cron-installed skills (dream / brief / loop) run autonomously and need to
+  # Edit files (docs/dream/, docs/briefs/, BACKLOG, etc.). Claude Code 2.1.x's
+  # pre-write approval UX silently blocks `claude -p` from applying edits in
+  # non-interactive pipe mode — bypass it for the cron context.
+  _agent_bypass_claude_perms
+  # In cron context, use absolute claude path so a fresh shell can find it.
+  [[ "$agent" == "claude" ]] && _AGENT_ARGV[0]="$(command -v claude 2>/dev/null || echo claude)"
+  # Drop the prompt sentinel (always last), re-emit head args + quoted $(strip).
+  local out="${_AGENT_ARGV[0]}" i prompt_idx=$((${#_AGENT_ARGV[@]} - 1))
+  for ((i = 1; i < prompt_idx; i++)); do
+    out+=" ${_AGENT_ARGV[i]}"
+  done
+  echo "${out} \"\$(${strip})\""
 }
 
 cmd_loop() {
@@ -2651,15 +2734,46 @@ _loop_off() {
   ok "Loop disabled  已停用"
 }
 
+_loop_is_active() {
+  # Three-level liveness probe used by FIX-037 heal and `roll loop now`.
+  # Returns 0 if any signal says the cycle is alive, 1 if all signals are dead.
+  # Heartbeat is primary (FIX-038); LOCK PID and tmux session are fallbacks.
+  # ROLL_HEARTBEAT_TIMEOUT (default 1800s) matches the outer heredoc's threshold.
+  local slug="${1:?slug required}"
+  local timeout="${ROLL_HEARTBEAT_TIMEOUT:-1800}"
+  local hb_file="${_SHARED_ROOT}/loop/.heartbeat-${slug}"
+  if [[ -f "$hb_file" ]]; then
+    local ts; ts=$(cat "$hb_file" 2>/dev/null || echo "")
+    if [[ "$ts" =~ ^[0-9]+$ ]]; then
+      local age=$(( $(date -u +%s) - ts ))
+      [[ $age -lt $timeout ]] && return 0
+    fi
+  fi
+  local lock="${_SHARED_ROOT}/loop/.LOCK-${slug}"
+  if [[ -f "$lock" ]]; then
+    local pid; pid=$(head -1 "$lock" 2>/dev/null || echo "")
+    [[ -n "$pid" ]] && kill -0 "$pid" 2>/dev/null && return 0
+  fi
+  command -v tmux >/dev/null 2>&1 && tmux has-session -t "roll-loop-${slug}" 2>/dev/null && return 0
+  return 1
+}
+
 _loop_now() {
+  local project_path; project_path=$(pwd -P)
+  local slug; slug=$(_project_slug "$project_path")
+  # Manual `roll loop now` must not bypass FIX-037 heal: if state says running
+  # but no live signal exists, this trigger is the canonical recovery point.
   if [[ -f "$_LOOP_STATE" ]] && grep -q "status: running" "$_LOOP_STATE" 2>/dev/null; then
-    warn "Loop already running  loop 正在运行中"; return 0
+    if _loop_is_active "$slug"; then
+      warn "Loop already running  loop 正在运行中"; return 0
+    fi
+    info "Stale running state detected — healing before new cycle  检测到孤儿状态，正在修复..."
+    printf "status: idle\n" > "$_LOOP_STATE"
+    rm -f "${_SHARED_ROOT}/loop/.LOCK-${slug}" 2>/dev/null || true
   fi
   # Invoke the SAME runner script that launchd would invoke — same tmux,
   # same --verbose, same LOCK, same auto-attach popup. ROLL_LOOP_FORCE
   # bypasses only the active-window check (manual triggers aren't time-gated).
-  local project_path; project_path=$(pwd -P)
-  local slug; slug=$(_project_slug "$project_path")
   local runner="${_SHARED_ROOT}/loop/run-${slug}.sh"
   if [[ ! -f "$runner" ]]; then
     err "Runner script not found: ${runner}"
@@ -2832,6 +2946,7 @@ _loop_reset() {
   else
     info "No loop state to clear  无 loop 状态可清除"
   fi
+  rm -rf "$(_loop_heal_dir)"
 }
 
 # Suppress the auto-attach popup. When the marker file exists, runner scripts
@@ -3223,6 +3338,42 @@ EOF
   return 1
 }
 
+_loop_heal_dir() {
+  printf '%s\n' "${ROLL_LOOP_DIR:-${HOME}/.shared/roll/loop}/heal"
+}
+
+# Bounded CI self-heal gate. Called by the loop SKILL when the
+# post-build CI check goes red. Counter is per-story, persisted under
+# $ROLL_LOOP_DIR/heal/<story-id>.count, so retries survive cycle boundaries.
+#
+# Exit 0: another heal attempt is allowed (counter incremented). Caller should
+#         invoke roll-fix with the failure summary, then re-run the CI gate.
+# Exit 1: heal disabled (ROLL_LOOP_NO_HEAL=1) or exhausted (>= ROLL_LOOP_HEAL_MAX).
+#         Caller should write ALERT and stop.
+_loop_self_heal_ci() {
+  local story_id="$1"
+  [[ -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
+  [[ "$current" -ge "$max" ]] && return 1
+  echo $((current + 1)) > "$counter"
+  return 0
+}
+
+# Reset per-story heal counter. Called when CI eventually turns green or by
+# `roll loop reset`. Idempotent.
+_loop_clear_heal_state() {
+  local story_id="$1"
+  [[ -z "$story_id" ]] && return 0
+  rm -f "$(_loop_heal_dir)/${story_id}.count" 2>/dev/null
+  return 0
+}
+
 # Verify TCR rhythm after a story completes. Returns 0 if ok, 1 if no TCR commits.
 # On failure: reverts story in BACKLOG.md to 📋 Todo and writes ALERT.
 _loop_enforce_tcr() {
@@ -4245,16 +4396,6 @@ p.write_text("".join(out))
 PYEOF
 }
 
-cmd_release() {
-  local pkg; pkg=$(node -p "require('./package.json').name" 2>/dev/null || true)
-  if [[ "$pkg" == "@seanyao/roll" ]]; then
-    err "roll 自身发版请用 scripts/release.sh（npm publish 需要人工 2FA）"
-    echo "  Run: scripts/release.sh"
-    exit 1
-  fi
-  _agent_run_skill "roll-release"
-}
-
 # ═══════════════════════════════════════════════════════════════════════════════
 # BACKLOG — show pending tasks / manage status
 # ═══════════════════════════════════════════════════════════════════════════════
@@ -4951,7 +5092,6 @@ usage() {
   echo "  backlog defer <pat> [reason]  Mark matching items as ⏸ Deferred  标记为已推迟"
   echo "  backlog unblock <pat>         Restore matching items to 📋 Todo   恢复为待处理"
   echo "  agent [use <name>|list]   [Config] Per-project agent selection            切换项目 agent"
-  echo "  release                [Publish] Sync changelog + version bump + npm publish  同步日志并发版"
   echo "  ci [--wait]            [CI] Show or wait for current commit's CI status       查看/等待 CI 状态"
   echo "  review-pr <number>     [PR Review] AI-powered code review for a PR           AI 代码评审"
   echo ""
@@ -4983,7 +5123,6 @@ main() {
     backlog)       cmd_backlog "$@" ;;
     alert)         cmd_alert "$@" ;;
     agent)         cmd_agent "$@" ;;
-    release)       cmd_release "$@" ;;
     ci)            cmd_ci "$@" ;;
     review-pr)     cmd_review_pr "$@" ;;
     version|--version|-v) echo "roll v${VERSION}" ;;

package/conventions/global/AGENTS.md

@@ -50,7 +50,18 @@
   `depends-on:` and `manual-only:` functional tags are allowed; `Domain:` annotation tags are not.
   Technical details and AC go in `docs/features/`.
   A well-written BACKLOG description can be used directly as a CHANGELOG entry.
+- **Convention layering**: project-level convention files extend the global SOT — see §9 below.
 - **Done**: Push + CI passes + deployed. Local-only is not done.
+- **Post-push verification** (universal — applies to any push to main, regardless of which
+  skill drove the work):
+  - After every push, wait for the triggered CI run and verify status (`gh run watch`
+    or equivalent). Do not move on, switch tasks, or claim completion until CI is green.
+  - Before pushing any new code commit, verify the **previous** code-changing push's CI
+    is green. Never stack new code commits on top of a red CI (this is the failure
+    mode FIX-026 / `_loop_precheck_ci` exists to prevent for the loop — humans need
+    the same discipline). docs-only commits (matching CI `paths-ignore`) don't reset
+    the gate either way.
+  - If CI is red, the next action is **fix or revert**, not "queue something else".
 - **Commit message format**:
   - Format: `<type>: <description>` (Git Hook may auto-prepend type prefix)
   - Types: `Story N`, `Fix`, `Refactor`, `Docs`, `Chore`
@@ -93,3 +104,41 @@ Confirm each phase clean before proceeding to the next.
 - **Story details**: `docs/features/` — AC, implementation specs, dependencies
 - **Design decisions**: `docs/domain/` — DDD models, architecture records
 - When `docs/domain/` or `docs/features/` don't exist yet, run `$roll-doc` to bootstrap.
+
+## 9. Convention Architecture
+
+Roll conventions form a two-layer hierarchy. The **global** layer is the single
+source of truth for **cross-project rules** — rules that apply regardless of
+stack, language, or domain (e.g., BACKLOG row format, identity, TCR rhythm,
+commit message format, scope discipline). The **project** layer carries only
+**project-specific** rules — stack, structure, build commands, domain
+conventions, deploy targets.
+
+**The contract:**
+
+1. Every project-level convention file **must declare it extends the global
+   counterpart** via a one-line foundation note at the top (e.g., "Extends
+   `~/.<agent>/AGENTS.md`" or "Extends AGENTS.md in this directory").
+2. Project-level files **never duplicate or re-state** cross-project rules.
+   When you find yourself wanting to copy a rule down, add a pointer instead.
+3. Cross-project rules go in `conventions/global/`. Project-specific rules go
+   in `conventions/templates/<type>/`. Anything that applies regardless of
+   stack belongs upstairs.
+
+**Layered file pairs** — each global ↔ project pair must follow the contract:
+
+| Global SOT | Project layer | Audience |
+|---|---|---|
+| `conventions/global/AGENTS.md` | `conventions/templates/<type>/AGENTS.md` | All agents |
+| `conventions/global/CLAUDE.md` | `conventions/templates/<type>/CLAUDE.md` | Claude Code |
+| `conventions/global/GEMINI.md` | `conventions/templates/<type>/GEMINI.md` | Gemini CLI |
+| `conventions/global/project_rules.md` | `conventions/templates/<type>/project_rules.md` | Trae IDE |
+
+The CLAUDE / GEMINI / project_rules global files themselves declare they
+extend this AGENTS.md, so this section's rules apply transitively to all
+four file families.
+
+**Why it matters**: copies drift, pointers don't. When a rule must change, it
+changes in one place and propagates; if it's duplicated, half the copies get
+updated and the others silently lag — which is the failure mode that produced
+this section in the first place.

package/conventions/templates/backend-service/AGENTS.md

@@ -1,6 +1,11 @@
 # Project Conventions — Backend Service
 
 > Reference for skills to infer backend project conventions.
+>
+> **Foundation**: extends the shared rules in `~/.<agent>/AGENTS.md`
+> (installed by `roll setup`). For BACKLOG row format, identity, TCR
+> rhythm, and other cross-project rules, see that file's §4. Only
+> project-specific stack / structure / domain rules live below.
 
 ## 1. Design
 - **API**: RESTful `/api/{res}/{id}`. Structured JSON errors.

package/conventions/templates/cli/AGENTS.md

@@ -1,6 +1,11 @@
 # Project Conventions — CLI Tool
 
 > Reference for skills to infer CLI project conventions.
+>
+> **Foundation**: extends the shared rules in `~/.<agent>/AGENTS.md`
+> (installed by `roll setup`). For BACKLOG row format, identity, TCR
+> rhythm, and other cross-project rules, see that file's §4. Only
+> project-specific stack / structure / domain rules live below.
 
 ## 1. Principles
 - **Lightweight**: No server/frontend.

package/conventions/templates/frontend-only/AGENTS.md

@@ -1,6 +1,11 @@
 # Project Conventions — Frontend Only
 
 > Reference for skills to infer frontend project conventions.
+>
+> **Foundation**: extends the shared rules in `~/.<agent>/AGENTS.md`
+> (installed by `roll setup`). For BACKLOG row format, identity, TCR
+> rhythm, and other cross-project rules, see that file's §4. Only
+> project-specific stack / structure / domain rules live below.
 
 ## 1. Stack
 - **Core**: React 18+ / TS / Vite / Tailwind / shadcn/ui.

package/conventions/templates/fullstack/AGENTS.md

@@ -1,6 +1,11 @@
 # Project Conventions — Fullstack Web
 
 > Reference for skills to infer fullstack project conventions.
+>
+> **Foundation**: extends the shared rules in `~/.<agent>/AGENTS.md`
+> (installed by `roll setup`). For BACKLOG row format, identity, TCR
+> rhythm, and other cross-project rules, see that file's §4. Only
+> project-specific stack / structure / domain rules live below.
 
 ## 1. Stack
 - **Frontend**: React 18+ / TS / Vite / Tailwind / shadcn/ui.

package/package.json

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

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

@@ -19,7 +19,7 @@ After successful Build & Deploy, extracts completed Stories from BACKLOG.md to g
 
 - Generating commit messages or PR descriptions — this skill only runs post-deploy
 - Recording dev diary / moments (use `$roll-notes`)
-- Bumping package version (use `$roll-release`)
+- Bumping package version (use the project's release script, e.g. `scripts/release.sh`)
 
 ## Workflow
 
@@ -357,3 +357,75 @@ After successful deploy in `$roll-build` / `$roll-fix`:
 ```
 
 不需要 `**Added**` / `**Fixed**` 前缀，分组标题已经承担了语义分类的职责。
+
+## 8. features.md 重写模式（产品 SOT）
+
+US-DOC-008 — `scripts/release.sh` 在 changelog/release-notes 生成完后会再
+调一次本 skill，请求"整体重写 `docs/features.md`"。这次调用的语义和上面
+两种完全不同：**不是基于本版 Story 增量**，而是基于**项目整体当前状态**。
+
+### 8.1 何时触发
+
+release.sh 完成 changelog/release-notes 写盘后，喂一段以
+`## 当前任务：重写 docs/features.md（Section 8）` 开头的 prompt。
+
+### 8.2 输入
+
+prompt 会包含：
+- 当前 `docs/features.md`（可能为空，可能上一版本的）
+- 当前 `BACKLOG.md` 全文（Epic / Feature 分组结构）
+- 当前 `docs/features/` 目录清单
+- 当前版本号
+
+### 8.3 输出契约
+
+把整个 `docs/features.md` 写出来。结构固定为三段：
+
+```
+# Roll — Features
+
+> 说明段（保留原文）
+
+---
+
+## ✨ Core Highlights
+
+- **<Feature 名>** — 1 句话产品级描述
+- **<Feature 名>** — 1 句话产品级描述
+- ...（3-5 条）
+
+---
+
+## Features by Epic
+
+### <Epic 名>
+- [<Feature 名>](docs/features/<file>.md) — 1 句话描述
+- <Feature 名> — 1 句话描述（缺 deep doc 时不加链接）
+
+### <Epic 名>
+- ...
+
+---
+
+## 维护说明（保留原文）
+```
+
+### 8.4 规则
+
+- **Catalog 必须列出 BACKLOG 中所有 `### Feature:` 出现的 Feature 名**
+  （即使没有 deep doc 也要列）
+- Feature 名跟 `docs/features/<file>.md` 文件名一致时，加链接到该 md
+- 没有对应 deep doc 的 Feature，**只写 plain text 不加链接**
+- 描述写 1 句话 **产品视角**：用户能用它做什么，避免实现细节
+- 分组用 BACKLOG 的 Epic 名，原序，不重排
+- Core Highlights 从所有 Features 里挑 3-5 个最能代表产品定位的，
+  描述用 bold 标 Feature 名后接说明；不照搬 catalog 文案
+- **不**写 "Recent Activity" 类区块——features.md 是 SOT，全量当下状态
+- **不**写版本号、不引用 changelog 条目
+- 说明段（顶部 quote）和维护说明（尾部）原文保留，不要重新生成措辞
+
+### 8.5 失败安全
+
+如果 prompt 信息不足（BACKLOG 解析失败等），**不要部分写入** —— 输出原
+文件内容即可。release.sh 会捕获 stdout 后比较：内容未变就不 stage。
+

package/skills/roll-brief/SKILL.md

@@ -17,7 +17,7 @@ description: |
 > Common Sense defined in the project AGENTS.md.
 
 Owner-facing digest of autonomous agent activity. Gives the human everything
-needed to decide whether to run `roll-release` — without having to read every
+needed to decide whether to cut a new release — without having to read every
 commit or diff.
 
 ## Distinct from roll-.changelog

package/skills/roll-loop/SKILL.md

@@ -7,7 +7,7 @@ description: |
   Actions), scans BACKLOG.md for 📋 Todo items, and routes each to the
   appropriate skill: US-XXX → $roll-build, FIX-XXX → $roll-fix,
   REFACTOR-XXX → $roll-build. Handles agent fallback on token/network failure.
-  Never executes roll-release autonomously — release is always a human decision.
+  Never cuts a release autonomously — release is always a human decision.
   Triggers roll-brief when a Feature completes.
 ---
 
@@ -18,7 +18,7 @@ description: |
 
 Runs on a schedule. Picks up pending BACKLOG items and executes them without
 human intervention. The human stays informed via `roll-brief` and retains
-sole authority over `roll-release`.
+sole authority over releases.
 
 ## Execution Boundary
 
@@ -28,7 +28,7 @@ sole authority over `roll-release`.
 - REFACTOR-XXX (Refactors) → `$roll-build`
 
 **What roll-loop never executes:**
-- `roll-release` — production deployment is always a human decision
+- Releases — production deployment is always a human decision (requires 2FA in real terminal)
 - Any Story marked 🚫 Hold or flagged for human review
 - Destructive operations outside normal skill scope
 
@@ -37,6 +37,30 @@ sole authority over `roll-release`.
 故事评审等场景）。loop 通过 LOCK 和 `🔨 In Progress` 状态识别并跳过人正在做的故事，
 人机并行不会撞车（见 Concurrency Safety）。
 
+## Environment Constraints (autonomous loop)
+
+You are running inside an autonomous cycle. No human is watching this turn.
+Adapt commands to the constraints below — otherwise you will burn turns on
+denied operations and the cycle will idle-exit.
+
+- **No `AskUserQuestion`**: no human can answer. If you genuinely cannot
+  proceed without a decision, write an entry to `${HOME}/.shared/roll/loop/ALERT.md`
+  describing what's needed and exit cleanly.
+- **Avoid compound bash**: each `Bash` call must run a single command.
+  No `cmd1 && cmd2`, no `cmd1 ; cmd2`, no pipes (`|`), no `$(...)` /
+  backtick subshells, no `bash -c '...'` with nested quoting. These are
+  rejected by static analysis before they run. Chain operations as
+  separate Bash calls and read intermediate output yourself.
+- **Prefer Read/Edit over cat/sed**: use the `Read` tool for any file
+  lookup, `Edit` for modifications. They cross sandbox boundaries that
+  `cat` / `ls` / `sed` cannot.
+- **CWD-relative paths first**: the cycle's CWD is the per-cycle worktree.
+  Files inside it (BACKLOG.md, bin/roll, tests/, docs/) are always
+  accessible. Files at `~/.shared/roll/...` are reachable via the `Read`
+  tool but not via shell commands.
+- **Skill invocation is the work**: route US/REFACTOR via `$roll-build`,
+  FIX via `$roll-fix`. Do not try to re-implement those flows inline.
+
 ## Configuration
 
 ```yaml
@@ -208,12 +232,44 @@ After each item completes:
    it derives `owner/repo` from the git remote and uses `gh -R <slug>`, which
    is required to work through `~/.ssh/config` host rewrites that break gh's
    auto-detection.
-   - CI passes → continue normally
-   - CI fails / times out / `gh` call fails → keep story as `🔨 In Progress`
-     (do NOT mark ✅ Done); write ALERT; skip to next story
+   - CI passes → call `_loop_clear_heal_state <story_id>` (idempotent) and
+     continue normally
+   - CI fails / times out / `gh` call fails → enter **CI self-heal** (US-AUTO-041)
    - `gh` binary not installed (`command -v gh` fails) → skip gracefully
      (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.
+   ```
+
+   **Bypass for debugging / cost control:** set `ROLL_LOOP_NO_HEAL=1` to restore
+   pre-US-AUTO-041 fail-fast behaviour.
 3. Update state file: `status: idle`
 4. Check if a Feature is now fully complete (all its Stories ✅)
 5. If yes and `brief_on_feature_complete: true` → invoke `Skill("roll-brief")`

package/skills/roll-release/SKILL.md

@@ -1,146 +0,0 @@
----
-name: roll-release
-license: MIT
-allowed-tools: "Read, Edit, Bash(git:*), Bash(npm:*), Bash(sed:*), Bash(date:*), Bash(gh:*)"
-description: "Release skill for roll maintainers. Calculates next version (YYYY.MMDD.N format, auto-increments N from today's git tags), updates VERSION in bin/roll and package.json, commits, tags, and pushes to trigger npm auto-publish via GitHub Actions. Trigger: release, publish, 发版, 发布新版本."
----
-
-# Release (roll-release)
-
-One-command publish flow for roll maintainers.
-
-## When Not to Use
-
-- Non-maintainer users (this skill publishes the package defined in `package.json` — confirm scope before running)
-- Internal project releases — only for the `roll` CLI package itself
-- Hotfixing code without a version bump (use `$roll-fix`)
-- Generating user-facing release notes (use `$roll-.changelog`)
-
-## Version Format
-
-`YYYY.MMDD.N` — e.g. `2026.419.1`
-
-- `YYYY.MMDD` = today's date, month has **no leading zero** (e.g. `420` not `0420`)
-- `N` = auto-incremented from existing git tags for today (starts at 1)
-
-## Execution Steps
-
-### Step 1: Calculate Version
-
-First, inspect recent tags to confirm the actual format in use:
-
-```bash
-git tag | sort -V | tail -5
-```
-
-Then calculate:
-
-```bash
-today=$(date +%Y.%-m%d)
-last_n=$(git tag | grep "^v${today}\." | sed "s/^v${today}\.//" | sort -n | tail -1)
-
-# Reuse tag if latest today's tag already points to HEAD (e.g. npm publish failed, retrying)
-if [[ -n "$last_n" ]]; then
-  last_tag="v${today}.${last_n}"
-  if [[ "$(git rev-list -n1 "$last_tag")" == "$(git rev-parse HEAD)" ]]; then
-    version="${today}.${last_n}"
-    echo "♻️  Reusing ${last_tag} — same commit, skipping version bump"
-    # Skip Steps 2-4, jump directly to Step 5 (GitHub Release) or Step 6 (npm publish)
-  else
-    n=$(( last_n + 1 ))
-    version="${today}.${n}"
-  fi
-else
-  version="${today}.1"
-fi
-```
-
-Show the proposed version to the user:
-```
-Recent tags: v2026.419.1  v2026.419.2  v2026.420.3
-Proposed version: 2026.420.4        ← new version (code changed since last tag)
-  — or —
-♻️  Reusing v2026.420.3             ← same commit, retry after npm failure
-Proceed? [y/N]
-```
-
-Wait for confirmation before continuing.
-
-### Step 2: Update Version Fields
-
-**`bin/roll`** — update the VERSION line:
-```bash
-sed -i '' "s/^VERSION=.*/VERSION=\"${version}\"/" bin/roll
-```
-
-**`package.json`** — update the version field:
-```bash
-npm version "${version}" --no-git-tag-version
-```
-
-Verify both files show the new version before continuing.
-
-### Step 3: Commit
-
-```bash
-git add bin/roll package.json
-git commit -m "[release] v${version}"
-```
-
-### Step 4: Tag and Push
-
-```bash
-git tag "v${version}"
-git push && git push --tags
-```
-
-### Step 5: Create GitHub Release
-
-**This step is mandatory.** Without it, `roll` update notifications will not work.
-
-Convert version to changelog date, extract notes, then create the release:
-
-```bash
-# Convert version (2026.510.3) to changelog date (2026.05.10)
-_year=$(echo "${version}" | cut -d. -f1)
-_mmdd=$(echo "${version}" | cut -d. -f2)
-if [ ${#_mmdd} -eq 3 ]; then
-  _cl_date="${_year}.0${_mmdd:0:1}.${_mmdd:1:2}"
-else
-  _cl_date="${_year}.${_mmdd:0:2}.${_mmdd:2:2}"
-fi
-
-# Extract release notes from CHANGELOG.md
-notes=$(sed -n "/^## ${_cl_date}$/,/^## /{ /^## ${_cl_date}$/d; /^## /d; p; }" CHANGELOG.md | sed '/^[[:space:]]*$/d')
-
-gh release create "v${version}" \
-  --title "v${version}" \
-  --notes "${notes:-Release v${version}}"
-```
-
-This enables the background update check in `bin/roll` (`_check_update_async`), which queries the GitHub Releases API.
-
-### Step 6: Publish to npm
-
-```bash
-npm publish --access public
-```
-
-This will open a browser for 2FA verification. Wait for it to complete before continuing.
-
-### Step 7: Confirm
-
-After publish, show:
-```
-✅ Released v{version}
-🏷  Tag: v{version} pushed to origin
-📦 npm published: {package_name}@{version}   # package name read from package.json
-🐙 GitHub Release: https://github.com/{owner}/{repo}/releases/tag/v{version}
-🔗 https://www.npmjs.com/package/{package_name}
-```
-
-## Abort Conditions
-
-- Uncommitted changes in `bin/roll` or `package.json` → warn and abort
-- Tag already exists for today's N → increment N and re-propose
-- `git push` fails → show error, do not leave a dangling local tag (run `git tag -d v{version}`)