@seanyao/roll 2026.514.5 → 2026.515.1

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## v2026.515.1
+
+- **New**: `roll brief` / `roll dream` 生成文档后自动提交推送 — 每次晨报和夜检不再需要手动 commit `[loop]`
+- **New**: 双语 FAQ 指南 — 10 个自治交付常见场景（loop 卡住、PR 冲突、agent 切换、权限问题等），每条含原因和原理，EN + ZH 对照 `[docs]`
+- **New**: 可选的事件驱动 PR 评审模板 — `cp templates/workflows/pr-review-event.yml .github/workflows/`，PR 开即触发 AI 评审，不装也行（loop 每轮兜底） `[pr]`
+- **New**: loop PR inbox 从"分类但空转"升级到"分类+执行" — eligible PR 自动调 AI 评审，stale PR 自动 rebase，fork 和冲突写 ALERT；bot 已评审的 PR 自动让步 `[loop]`
+- **New**: `roll review-pr <number>` — agent-agnostic AI 代码评审，任意 agent（Claude/Kimi/DeepSeek 等）均可评审任意 git 平台的 PR；PR body 加 `[skip-ai-review]` 可跳过 `[pr]`
+- **Fixed**: `roll peer` 终态后 tmux session 不再残留 — AGREE/ESCALATE/UNKNOWN/round≥3 自动 kill，round<3 保留复用 `[peer]`
+- **New**: `loop/cycle-*` 远程僵尸分支兜底 GC — 每轮 cycle 结尾扫描已合入 main 的 `loop/cycle-*` 分支并删除，弥补 PR auto-merge 失败时的清理盲区 `[loop]`
+
 ## v2026.514.5
 
 - **Fixed**: 上版 `claude/*` 临时分支清理意外失效 — 现已恢复 `[loop]`

package/README.md

@@ -64,6 +64,7 @@ roll loop on        # optional: let the agent work unattended
 | Peer (cross-agent review) | [guide/en/peer.md](docs/guide/en/peer.md) | [guide/zh/peer.md](docs/guide/zh/peer.md) |
 | Configuration (env vars) | [guide/en/configuration.md](docs/guide/en/configuration.md) | [guide/zh/configuration.md](docs/guide/zh/configuration.md) |
 | Skill selection guide | [guide/en/skills.md](docs/guide/en/skills.md) | [guide/zh/skills.md](docs/guide/zh/skills.md) |
+| FAQ (troubleshooting) | [guide/en/faq.md](docs/guide/en/faq.md) | [guide/zh/faq.md](docs/guide/zh/faq.md) |
 | Domain model (DDD) | [domain/context-map.md](docs/domain/context-map.md) | — |
 | Engineering common sense | [practices/engineering-common-sense.md](docs/practices/engineering-common-sense.md) | — |
 

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.514.5"
+VERSION="2026.515.1"
 ROLL_HOME="${ROLL_HOME:-${HOME}/.roll}"
 ROLL_CONFIG="${ROLL_HOME}/config.yaml"
 ROLL_GLOBAL="${ROLL_HOME}/conventions/global"
@@ -614,6 +614,7 @@ cmd_setup() {
 
   echo ""
   _print_pr_pipeline_hint
+  _print_pr_event_hint
 }
 
 # ─── PR pipeline hint ────────────────────────────────────────────────────────
@@ -643,6 +644,24 @@ _print_pr_pipeline_hint() {
 HINT
 }
 
+_print_pr_event_hint() {
+  cat <<'HINT'
+
+  Optional — enable event-driven PR review (seconds-fast, GitHub only).
+  可选 —— 启用事件驱动 PR 评审（秒级响应，仅限 GitHub）。
+
+  Without this, Roll reviews PRs each loop cycle (~1h). With it,
+  contributors get AI feedback on PR open/update immediately.
+  不安装也行 — loop 每轮会兜底评审。安装后 PR 一开即触发 AI 评审。
+
+      cp templates/workflows/pr-review-event.yml .github/workflows/
+
+  Then set the API key secret for your configured agent in GitHub repo settings.
+  然后在 GitHub 仓库设置中添加你配置的 agent 对应的 API key secret。
+
+HINT
+}
+
 # ═══════════════════════════════════════════════════════════════════════════════
 # COMMAND: update
 # Thin wrapper: upgrade the npm-installed package, then re-sync via setup.
@@ -1777,6 +1796,16 @@ cmd_peer() {
   echo ""
   info "Log: $log_file"
 
+  local _should_kill=true
+  case "$resolution" in
+    REFINE|OBJECT) [[ "$round" -lt 3 ]] && _should_kill=false ;;
+  esac
+  if [[ "$_should_kill" == "true" ]] && [[ -n "$peer_session" ]] \
+     && command -v tmux >/dev/null 2>&1 \
+     && tmux has-session -t "$peer_session" 2>/dev/null; then
+    tmux kill-session -t "$peer_session" 2>/dev/null || true
+  fi
+
   case "$resolution" in
     AGREE) exit 0 ;;
     REFINE|OBJECT) exit 2 ;;
@@ -1898,6 +1927,17 @@ _skill_content() {
   awk 'NR==1 && /^---$/{skip=1;next} skip && /^---$/{skip=0;next} !skip{print}' "$1"
 }
 
+_parse_review_verdict() {
+  local output="$1"
+  local line
+  line=$(echo "$output" | grep -o '<!--VERDICT:[^>]*-->' | tail -1)
+  [ -n "$line" ] || return 0
+  local type reason
+  type=$(echo "$line" | sed -E 's/<!--VERDICT:([A-Z_]+)(:.*)?-->/\1/')
+  reason=$(echo "$line" | sed -E 's/<!--VERDICT:[A-Z_]+:?//; s/-->//' | sed 's/^ *//')
+  echo "${type}${reason:+:${reason}}"
+}
+
 _agent_run_skill() {
   local skill="$1"
   local agent; agent=$(_project_agent)
@@ -1915,6 +1955,102 @@ _agent_run_skill() {
   esac
 }
 
+cmd_review_pr() {
+  local pr_number="${1:-}"
+  [ -n "$pr_number" ] || { err "Usage: roll review-pr <number>"; return 1; }
+
+  local slug; slug=$(_gh_repo_slug) || { err "Not a GitHub repo — review-pr requires GitHub remote"; return 1; }
+
+  local pr_json
+  pr_json=$(gh -R "$slug" pr view "$pr_number" --json title,body,diff 2>&1) \
+    || { err "gh pr view failed: ${pr_json}"; return 1; }
+
+  local title body diff
+  title=$(echo "$pr_json" | jq -r '.title // ""')
+  body=$(echo "$pr_json" | jq -r '.body // ""')
+  diff=$(echo "$pr_json" | jq -r '.diff // ""')
+
+  if echo "$body" | grep -qF '[skip-ai-review]'; then
+    gh -R "$slug" pr review "$pr_number" --approve -b "Auto-approved: [skip-ai-review] detected" 2>/dev/null || true
+    info "PR #${pr_number}: [skip-ai-review] — auto-approved"
+    return 0
+  fi
+
+  local template="${ROLL_PKG_DIR}/skills/roll-review-pr/SKILL.md"
+  [ -f "$template" ] || { err "Skill template not found: ${template}"; return 1; }
+
+  local content; content=$(_skill_content "$template")
+
+  local tmp; tmp=$(mktemp)
+  # shellcheck disable=SC2064
+  trap "rm -f '$tmp'" EXIT
+
+  echo "$content" > "$tmp"
+  sed -i '' "s|{{PR_TITLE}}|${title}|g" "$tmp" 2>/dev/null \
+    || sed -i "s|{{PR_TITLE}}|${title}|g" "$tmp"
+
+  local body_escaped; body_escaped=$(printf '%s' "$body" | sed 's/[&/\]/\\&/g; s/$/\\/' | sed '$ s/\\$//')
+  sed -i '' "s|{{PR_BODY}}|${body_escaped}|g" "$tmp" 2>/dev/null \
+    || sed -i "s|{{PR_BODY}}|${body_escaped}|g" "$tmp"
+
+  local diff_truncated
+  diff_truncated=$(echo "$diff" | head -500)
+  local diff_file; diff_file=$(mktemp)
+  echo "$diff_truncated" > "$diff_file"
+  awk -v f="$diff_file" '{
+    if (index($0, "{{PR_DIFF}}")) {
+      while ((getline line < f) > 0) print line
+      close(f)
+    } else print
+  }' "$tmp" > "${tmp}.out" && mv "${tmp}.out" "$tmp"
+  rm -f "$diff_file"
+
+  local prompt; prompt=$(cat "$tmp")
+  rm -f "$tmp"
+  trap - EXIT
+
+  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
+
+  echo "$output"
+
+  local verdict; verdict=$(_parse_review_verdict "$output")
+  local vtype; vtype="${verdict%%:*}"
+  local vreason; vreason="${verdict#*:}"
+  [ "$vreason" = "$vtype" ] && vreason=""
+
+  case "$vtype" in
+    APPROVE)
+      gh -R "$slug" pr review "$pr_number" --approve -b "AI review: approved" 2>/dev/null || true
+      info "PR #${pr_number}: APPROVED"
+      ;;
+    REQUEST_CHANGES)
+      gh -R "$slug" pr review "$pr_number" --request-changes -b "${vreason:-AI review requested changes}" 2>/dev/null || true
+      info "PR #${pr_number}: REQUEST_CHANGES — ${vreason}"
+      ;;
+    UNCERTAIN)
+      warn "PR #${pr_number}: UNCERTAIN — ${vreason}"
+      local alert_file="${ROLL_LOOP_DIR:-${HOME}/.shared/roll/loop}/ALERT.md"
+      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"
+      ;;
+    *)
+      warn "PR #${pr_number}: no verdict parsed from agent output"
+      ;;
+  esac
+}
+
 cmd_agent() {
   local subcmd="${1:-}"; shift || true
   case "$subcmd" in
@@ -1929,8 +2065,12 @@ cmd_agent() {
       fi
       ok "Agent set to ${name} for this project  当前项目 agent 已设为 ${name}"
       local project_path; project_path=$(pwd -P)
-      crontab -l 2>/dev/null | grep -q "roll-loop:${project_path}" && \
-        info "Takes effect on next scheduled run — or: roll loop now"
+      local slug; slug=$(_project_slug "$project_path")
+      local runner="${_SHARED_ROOT}/loop/run-${slug}.sh"
+      if [[ -f "$runner" ]]; then
+        _install_launchd_plists "$project_path" >/dev/null
+        ok "Loop runner scripts regenerated for new agent  已为新 agent 重新生成 loop 脚本"
+      fi
       ;;
     list)
       echo ""; echo "  Available agents  可用 agent:"; echo ""
@@ -2192,6 +2332,9 @@ if [ "\$_USE_WORKTREE" = "1" ]; then
     echo "[loop] cycle \${CYCLE_ID}: claude failed (exit \$_exit); worktree preserved at \$WT"
   fi
 fi
+
+# US-AUTO-040: fallback GC — delete remote loop/cycle-* branches already merged to main.
+_loop_cleanup_stale_cycle_branches "${project_path}" || true
 INNER
   chmod +x "$inner_path"
 
@@ -2227,7 +2370,9 @@ fi
 echo "\$\$" > "\$LOCK"
 trap 'rm -f "\$LOCK"' EXIT
 if command -v tmux >/dev/null 2>&1; then
-  tmux kill-session -t "\$SESSION" 2>/dev/null || true
+  tmux list-sessions -F "#{session_name}" 2>/dev/null | grep "^roll-loop-" | 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\""
   tmux pipe-pane -t "\$SESSION" "cat >> \"\$LOG\""
   # Auto-attach popup: when not muted, spawn a Terminal window attached to the
@@ -3319,6 +3464,55 @@ _loop_pr_state_write() {
   ' "$state" > "$tmp" && mv "$tmp" "$state"
 }
 
+# _loop_pr_review_external <pr_number>
+#   Calls cmd_review_pr (US-PR-001) to run AI review on an eligible external PR.
+#   Lenient: errors are logged but do not fail the loop.
+_loop_pr_review_external() {
+  local pr="$1"
+  [ -n "$pr" ] || return 0
+  cmd_review_pr "$pr" 2>&1 || {
+    warn "review-pr failed for PR #${pr} (non-fatal)"
+    return 0
+  }
+}
+
+# _loop_pr_rebase_stale <pr_number> <head_ref>
+#   Attempts to rebase a stale PR onto origin/main and push.
+#   Fork PRs are skipped (no write access). Conflicts write ALERT.
+_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 pr_json
+  pr_json=$(gh -R "$slug" pr view "$pr" --json headRepository,headRepositoryOwner,isCrossRepository 2>/dev/null) || return 0
+  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}"
+    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"
+    return 0
+  fi
+
+  git fetch origin "$head_ref" 2>/dev/null || return 0
+  if git checkout "$head_ref" 2>/dev/null \
+     && git rebase origin/main 2>/dev/null \
+     && git push origin "$head_ref" 2>/dev/null; then
+    info "PR #${pr}: rebased ${head_ref} onto origin/main"
+  else
+    git rebase --abort 2>/dev/null || true
+    git checkout - 2>/dev/null || true
+    local alert="${_LOOP_ALERT:-${HOME}/.shared/roll/loop/ALERT.md}"
+    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"
+  fi
+  return 0
+}
+
 # _loop_pr_inbox
 #   Walks open PRs and routes each by classification.
 #   Lenient on gh unavailability — returns 0 so the loop continues to BACKLOG.
@@ -3348,10 +3542,13 @@ _loop_pr_inbox() {
       --json reviews,mergeStateStatus,statusCheckRollup \
       2>/dev/null) || { i=$((i + 1)); continue; }
 
-    local human_review ci_state mergeable
+    local human_review ci_state mergeable bot_review
     human_review=$(echo "$view_json" | jq -r '
       [.reviews[]? | select(.authorAssociation != "BOT" and .authorAssociation != "APP")]
       | last // {} | .state // ""' 2>/dev/null)
+    bot_review=$(echo "$view_json" | jq -r '
+      [.reviews[]? | select(.authorAssociation == "BOT" or .authorAssociation == "APP")]
+      | last // {} | .state // ""' 2>/dev/null)
     mergeable=$(echo "$view_json" | jq -r '.mergeStateStatus // ""' 2>/dev/null)
     ci_state=$(echo "$view_json" | jq -r '
       if (.statusCheckRollup | length) == 0 then ""
@@ -3359,6 +3556,17 @@ _loop_pr_inbox() {
       elif all(.statusCheckRollup[]?; .conclusion == "SUCCESS" or .conclusion == "SKIPPED") then "success"
       else "pending" end' 2>/dev/null)
 
+    # Bot review gate: if a GHA workflow already handled this PR, defer to it.
+    if [ "$bot_review" = "APPROVED" ]; then
+      i=$((i + 1)); continue
+    elif [ "$bot_review" = "CHANGES_REQUESTED" ]; then
+      local alert="${_LOOP_ALERT:-${HOME}/.shared/roll/loop/ALERT.md}"
+      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"
+      i=$((i + 1)); continue
+    fi
+
     local verdict
     verdict=$(_loop_pr_classify "$head_ref" "$human_review" "$ci_state" "$mergeable")
 
@@ -3368,15 +3576,10 @@ _loop_pr_inbox() {
         ;;
       stale)
         _loop_pr_rebase_circuit "$num" || true
-        # Actual rebase work delegated to _loop_pr_rebase_stale when present
-        # (kept out of this cycle to avoid touching git remote in tests).
-        command -v _loop_pr_rebase_stale >/dev/null 2>&1 \
-          && _loop_pr_rebase_stale "$num" "$head_ref" || true
+        _loop_pr_rebase_stale "$num" "$head_ref" || true
         ;;
       eligible)
-        # Hand off to review (US-AUTO-035 supplies the actual decision).
-        command -v _loop_pr_review_external >/dev/null 2>&1 \
-          && _loop_pr_review_external "$num" || true
+        _loop_pr_review_external "$num" || true
         ;;
     esac
 
@@ -3715,6 +3918,28 @@ _claude_cleanup_stale_worktrees() {
   return 0
 }
 
+_loop_cleanup_stale_cycle_branches() {
+  local project_path="${1:-.}"
+  local url; url=$(git -C "$project_path" remote get-url origin 2>/dev/null) || return 0
+  [[ "$url" == *github.com* ]] || return 0
+
+  local branches
+  branches=$(git -C "$project_path" ls-remote --heads origin 'refs/heads/loop/cycle-*' 2>/dev/null \
+    | awk '{print $2}' | sed 's|^refs/heads/||')
+  [ -z "$branches" ] && return 0
+
+  while IFS= read -r branch; do
+    [ -z "$branch" ] && continue
+    if ! git -C "$project_path" merge-base --is-ancestor "$branch" origin/main 2>/dev/null; then
+      continue
+    fi
+    if git -C "$project_path" push origin --delete "$branch" 2>/dev/null; then
+      echo "[loop] deleted stale cycle branch: $branch"
+    fi
+  done <<< "$branches"
+  return 0
+}
+
 # US-AUTO-033: publish a loop cycle branch as a GitHub PR with auto-merge.
 #
 # _loop_publish_pr <branch> [title]
@@ -4719,6 +4944,7 @@ usage() {
   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 ""
   echo "Examples / 示例:"
   echo "  roll setup                    # New machine: first-time install            新机器首次安装"
@@ -4750,6 +4976,7 @@ main() {
     agent)         cmd_agent "$@" ;;
     release)       cmd_release "$@" ;;
     ci)            cmd_ci "$@" ;;
+    review-pr)     cmd_review_pr "$@" ;;
     version|--version|-v) echo "roll v${VERSION}" ;;
     help|--help|-h) usage ;;
     "") [[ -f "BACKLOG.md" ]] && _dashboard || { usage; _show_changelog; } ;;

package/package.json

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

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

@@ -275,6 +275,7 @@ git add BACKLOG.md docs/dream/YYYY-MM-DD.md
 git commit -m "chore: dream scan YYYY-MM-DD — {N} REFACTOR entries"
 # 无发现时：
 git commit -m "chore: dream scan YYYY-MM-DD — no findings"
+git push origin main
 ```
 
 - BACKLOG.md 和 dream 日志必须在**同一个 commit** 里入库，避免出现"REFACTOR 已加但日志找不到"或反过来的撕裂状态

package/skills/roll-brief/SKILL.md

@@ -167,6 +167,7 @@ A simple heuristic — not a gate, just a signal for the human:
 ```bash
 git add docs/briefs/YYYY-MM-DD-NN.md
 git commit -m "docs: roll-brief YYYY-MM-DD-NN — {触发原因}"
+git push origin main
 ```
 
 - 触发原因来自调用上下文（Feature 完成 / 每日 / 手动 / `--feature` / `--since`），用一句话填入

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

@@ -0,0 +1,58 @@
+---
+name: roll-review-pr
+license: MIT
+allowed-tools: "Read"
+description: "Agent-agnostic PR review skill. Reviews a pull request diff and emits a structured 3-state verdict (APPROVE / REQUEST_CHANGES / UNCERTAIN). Used by `roll review-pr` and `_loop_pr_review_external`."
+---
+
+# PR Review
+
+> Follows the Architecture Constraints, Development Discipline, and Engineering
+> Common Sense defined in the project AGENTS.md.
+
+You are reviewing a pull request. Your job is to assess code quality,
+correctness, and adherence to project conventions.
+
+## Context
+
+**PR Title:** {{PR_TITLE}}
+
+**PR Body:**
+{{PR_BODY}}
+
+## Diff
+
+```diff
+{{PR_DIFF}}
+```
+
+## Review Instructions
+
+1. Read the diff carefully. Focus on:
+   - Correctness: logic errors, off-by-one, unhandled edge cases
+   - Security: injection, secrets exposure, unsafe operations
+   - Conventions: naming, structure, test coverage (as described in AGENTS.md)
+   - Scope: changes should match what the PR title/body claims
+
+2. Write your analysis in free text (2-10 sentences). Be specific — cite file
+   names and line numbers when pointing out issues.
+
+3. End your response with exactly ONE verdict footer on its own line:
+
+   - If the code is acceptable:
+     `<!--VERDICT:APPROVE-->`
+
+   - If changes are needed (cite the most important issue):
+     `<!--VERDICT:REQUEST_CHANGES:one-line reason-->`
+
+   - If you cannot confidently judge (e.g., missing context, domain-specific logic):
+     `<!--VERDICT:UNCERTAIN:one-line reason-->`
+
+## Rules
+
+- The verdict footer MUST appear on the last non-empty line of your response.
+- Choose exactly one verdict. Do not combine them.
+- REQUEST_CHANGES is for real issues — not style nitpicks or personal preferences.
+- When in doubt between APPROVE and UNCERTAIN, prefer UNCERTAIN.
+- If the PR body contains `[skip-ai-review]`, immediately output
+  `<!--VERDICT:APPROVE-->` with no analysis.