@seanyao/roll 2026.514.2 → 2026.514.5

package/CHANGELOG.md

@@ -1,12 +1,26 @@
 # Changelog
 
-## v2026.514.2
+## v2026.514.5
 
-- Changelog 历史版本全部重新整理：按主题分组、合并同类项、用词更贴近用户视角，附 `[loop]` / `[dream]` 归因标记
-- Changelog Skill 新增 Release Notes 生成规范：分组规则、条目合并、归因标签、措辞原则
-- README 新增 Evolution 章节，梳理 Roll 从工具到自主交付系统的演进脉络
+- **Fixed**: 上版 `claude/*` 临时分支清理意外失效 — 现已恢复 `[loop]`
+- **Fixed**: loop session 结束后本地 worktree 不再积累，`git worktree list` 保持干净 `[loop]`
+- **Fixed**: 发版脚本不再维护独立的 agent 检测逻辑，配置变更时两处不再悄悄漂移
+
+## v2026.514.3
+
+### 约定与导航
+
+- `$roll-design` 澄清需求前先自己定位产品端和业务域，问你的问题少了
+- `$roll-doc` 为已有项目生成 AGENTS.md 导航骨架 — 新接入 Roll 不再从空白出发
 
-## v2026.514.1
+### 自动化流水线
+
+- loop 每轮先消化开放 PR 再领新 backlog — 把队列里的 PR 当成首类工作，不是绕开的障碍 `[loop]`
+- 自己开的 `loop/*` 分支不会被自己评审，避免同源 bias `[loop]`
+- 24 小时内 rebase 同一个 PR 超过 3 次自动熔断，workflow 文件出错时不再无限循环 `[loop]`
+- 每次 session 收尾自动删掉自己推上去的 `claude/*` 临时分支，远端不再积压"看起来要发 PR 实际不会发"的孤儿分支 `[loop]`
+
+## v2026.514.2
 
 ### 自动化流水线
 
@@ -18,6 +32,8 @@
 
 - 生成时自动过滤技术黑话，并对照历史风格保持表达一致 `[loop]`
 - 写入前有一道自审：行文不达标就退回重写，不进 changelog `[loop]`
+- 历史版本全部重新整理：按主题分组、合并同类项、附 `[loop]` / `[dream]` 归因标记
+- Release Notes 生成规范写入 Skill：分组规则、条目合并、归因标签、措辞原则
 
 ### 可见性
 
@@ -28,6 +44,7 @@
 ### 其他
 
 - 纯文档改动直接合 main，不等 CI，合并更快
+- README 新增 Evolution 章节，梳理 Roll 从工具到自主交付系统的演进脉络
 
 ## v2026.513.1
 

package/README.md

@@ -7,7 +7,7 @@
  ╚═╝  ╚═╝ ╚═════╝ ╚══════╝╚══════╝
 ```
 
-> Roll out features with AI agents — _Move fast, no sprints._
+> _Agents, roll out._
 
 **[中文版 README](README_CN.md)**
 
@@ -27,6 +27,16 @@ Roll is an autonomous delivery system for software teams — AI agents pick stor
 
 _Works with Claude, Cursor, Codex, or your own agent._
 
+## Evolution
+
+Roll didn't start as a framework. It started as a question: *what if the AI didn't just write code, but actually shipped it?*
+
+Early versions just pushed engineering conventions to whichever AI tool you were running. Then came multi-agent support — Kimi, DeepSeek, Codex, Trae — and `roll-peer`, which let one AI challenge another's decisions before anything landed on `main`.
+
+The real shift was `roll loop`: stories running back-to-back without human prompting, `roll-.dream` filing its own refactor tickets after nightly scans, the system generating its own work queue. What followed was building enough trust to leave it running overnight — worktree isolation, CI + AI review double gates, real-time visibility into what the agent was actually doing.
+
+The goal from here: full delivery, end to end — with humans on the loop, not in it.
+
 ---
 
 ## Quick Start (30 seconds)
@@ -52,6 +62,7 @@ roll loop on        # optional: let the agent work unattended
 | Loop (autonomous executor) | [guide/en/loop.md](docs/guide/en/loop.md) | [guide/zh/loop.md](docs/guide/zh/loop.md) |
 | Dream (nightly health scan) | [guide/en/dream.md](docs/guide/en/dream.md) | [guide/zh/dream.md](docs/guide/zh/dream.md) |
 | 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) |
 | 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) | — |
@@ -74,22 +85,6 @@ roll loop on        # optional: let the agent work unattended
 
 ---
 
-## Evolution
-
-Roll didn't start as a framework. It started as a question: *what if the AI didn't just write code, but actually shipped it?*
-
-The first version was almost embarrassingly small — a way to push engineering conventions to whatever AI tool you happened to be running. But it needed to be trustworthy before it could be useful, so the early weeks went into making Roll self-maintaining: one-command releases, self-updating installs, a clean npm presence.
-
-The next step was making Roll genuinely multi-agent. Kimi, DeepSeek, Codex, Trae — each integrated with its own skill preferences and model bindings. `roll-peer` came from a simple insight: agents shouldn't just review their own work. Have one AI challenge another's design decisions before anything lands on `main`. That turned out to be the first glimpse of what Roll was actually becoming.
-
-The real shift happened when `roll loop` went live. Stories started running back-to-back without any human prompt. `roll-.dream` began filing its own refactor tickets after nightly scans. The system had started generating its own work queue — not just executing tasks, but surfacing the next ones.
-
-What followed was learning to trust that autonomy: real-time terminal windows, worktree isolation so loop runs never touch your in-progress work, a CI + AI review double gate so nothing merges until it's actually ready. The kind of loop you can leave running overnight and wake up to something mergeable.
-
-The goal from here: full delivery, end to end — with humans on the loop, not in it.
-
----
-
 ## Contributing
 
 PRs welcome. Keep them focused on one thing. For larger changes, open an issue first.

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.2"
+VERSION="2026.514.5"
 ROLL_HOME="${ROLL_HOME:-${HOME}/.roll}"
 ROLL_CONFIG="${ROLL_HOME}/config.yaml"
 ROLL_GLOBAL="${ROLL_HOME}/conventions/global"
@@ -465,7 +465,9 @@ _link_skills() {
         local current_target
         current_target="$(readlink "$skill_link")"
         if [[ "$current_target" != "$skill_dir" ]]; then
-          ln -sf "$skill_dir" "$skill_link"
+          # macOS ln -sf follows symlinks-to-dirs and creates inside instead of
+          # replacing — explicitly remove first to guarantee replacement.
+          rm -f "$skill_link" && ln -s "$skill_dir" "$skill_link"
           repaired=$((repaired + 1))
         fi
         # correct symlink: skip silently
@@ -1903,7 +1905,7 @@ _agent_run_skill() {
   [[ -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 stream-json "$content" ;;
+    claude)   claude -p --output-format text "$content" ;;
     kimi)     kimi --quiet -p "$content" ;;
     deepseek) deepseek "$content" ;;
     pi)       pi -p "$content" ;;
@@ -2123,6 +2125,9 @@ WT="\$(_worktree_path "${slug}" "cycle-\${CYCLE_ID}")"
 BRANCH="loop/cycle-\${CYCLE_ID}"
 _USE_WORKTREE=0
 cd "${project_path}" 2>/dev/null || true
+# 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}")"
 if _worktree_fetch_origin main \\
    && _worktree_create "\$WT" "\$BRANCH" "origin/main"; then
   _USE_WORKTREE=1
@@ -2148,6 +2153,14 @@ for _attempt in 1 2 3; do
   fi
 done
 
+# US-AUTO-038: diff snapshot vs current and delete any claude/* branches this
+# session pushed to origin. Runs regardless of claude's exit code (cleanup is
+# orthogonal to success/failure) and is silent on non-GitHub / unreachable.
+_claude_cleanup_new_branches "\$CLAUDE_BRANCH_SNAPSHOT" "${project_path}" || true
+# REFACTOR-011: also prune local .claude/worktrees/ entries whose branch has
+# been merged to main (remote-branch cleanup above doesn't touch local worktrees).
+_claude_cleanup_stale_worktrees "${project_path}" || true
+
 # Post-claude: publish cycle branch. Doc-only changes (BACKLOG/docs) merge
 # immediately via --admin; code changes use auto-merge (CI gate required).
 # When \`gh\` is unavailable, fall back to the legacy ff-merge path.
@@ -2963,15 +2976,73 @@ _loop_precheck_ci() {
 **Reason**: HEAD CI is red — loop refused to build on a broken base  HEAD CI 红，loop 拒绝在破损的基础上构建
 
 **Action required**:
-- Investigate and fix CI: \`gh -R $(_gh_repo_slug) run list --commit ${commit}\`
+- Investigate and fix CI: \`gh -R ${slug} run list --commit ${commit}\`
 - After fixing and pushing green commit: \`roll loop now\`
 EOF
+    _loop_diagnose_open_prs "$slug" >> "$_LOOP_ALERT"
     _notify "roll ⚠ CI red" "loop refused to build on broken base (${short})"
     return 1
   fi
   return 0
 }
 
+# _loop_diagnose_open_prs <slug>
+#   Appended to ALERT when CI is red on HEAD.
+#   For each open PR targeting main: lists CI failing tests + changed files,
+#   flags whether failures look unrelated to the PR's own changes.
+_loop_diagnose_open_prs() {
+  local slug="$1"
+  local prs
+  prs=$(gh -R "$slug" pr list --base main --state open --json number,title,headRefName \
+    --jq '.[] | [.number|tostring, .headRefName, .title] | @tsv' 2>/dev/null) || return 0
+  [[ -z "$prs" ]] && return 0
+
+  printf '\n## Open PRs (potential fixes)\n'
+  while IFS=$'\t' read -r pr_num branch pr_title; do
+    printf '\nPR #%s: %s\n' "$pr_num" "$pr_title"
+
+    # Files changed in this PR
+    local changed_files
+    changed_files=$(gh -R "$slug" pr diff "$pr_num" --name-only 2>/dev/null | head -10) || changed_files="(unable to fetch)"
+    printf '  Changed: %s\n' "$(echo "$changed_files" | tr '\n' ' ')"
+
+    # Latest CI run on the PR branch
+    local run_id conclusion
+    run_id=$(gh -R "$slug" run list --branch "$branch" --json databaseId,conclusion \
+      --jq '[.[] | select(.conclusion != null)] | first | .databaseId' 2>/dev/null) || run_id=""
+    conclusion=$(gh -R "$slug" run list --branch "$branch" --json databaseId,conclusion \
+      --jq '[.[] | select(.conclusion != null)] | first | .conclusion' 2>/dev/null) || conclusion="unknown"
+
+    if [[ "$conclusion" == "success" ]]; then
+      printf '  CI: green — blocked only by branch protection (safe to merge)\n'
+      printf '  Suggest: gh pr merge %s --admin\n' "$pr_num"
+    elif [[ -n "$run_id" ]]; then
+      local failing_tests
+      failing_tests=$(gh -R "$slug" run view "$run_id" --log-failed 2>/dev/null \
+        | grep -oP '(?<=not ok \d{1,4} ).*' | head -8) || failing_tests="(unable to fetch)"
+
+      printf '  CI: %s\n' "$conclusion"
+      printf '  Failing tests:\n'
+      while IFS= read -r t; do
+        [[ -n "$t" ]] && printf '    - %s\n' "$t"
+      done <<< "$failing_tests"
+
+      # Heuristic: if no failing test mentions a changed file, flag as likely unrelated
+      local related=0
+      while IFS= read -r f; do
+        local base; base=$(basename "$f")
+        echo "$failing_tests" | grep -qi "$base" && { related=1; break; }
+      done <<< "$changed_files"
+      if [[ "$related" -eq 0 ]]; then
+        printf '  Note: failing tests appear UNRELATED to changed files — consider manual merge\n'
+        printf '  Suggest: gh pr merge %s --admin  (verify tests manually first)\n' "$pr_num"
+      else
+        printf '  Note: failing tests may relate to PR changes — investigate before merging\n'
+      fi
+    fi
+  done <<< "$prs"
+}
+
 # CI gate before marking a story Done.
 # On CI failure: writes ALERT, returns 1 (caller keeps story 🔨 In Progress).
 # When gh unavailable: returns 0 (graceful skip).
@@ -3101,6 +3172,219 @@ _loop_is_manual_only() {
   echo "$row" | grep -qE 'manual-only:true'
 }
 
+# US-AUTO-034: PR-first inbox — loop processes open PRs before scanning BACKLOG.
+#
+# Three building blocks, kept as pure / mockable functions:
+#   _loop_pr_classify        pure routing decision (no side effects)
+#   _loop_pr_rebase_circuit  24h sliding-window circuit breaker on rebase retries
+#   _loop_pr_inbox           orchestrator that walks `gh pr list` and routes
+#                            each open PR to skip / review / rebase
+#
+# Design notes:
+#   - gh missing or any gh failure → return 0 (lenient, like FIX-026's pre-check)
+#   - self-authored loop/* PRs are skipped to avoid same-source AI review
+#   - latest human review of CHANGES_REQUESTED or APPROVED blocks AI review
+#     (Human-review-activity guard from US-AUTO-034 AC)
+#   - rebase attempts ≥3 within 24h trip the circuit breaker (writes ALERT)
+
+# _loop_pr_classify <head_ref> <human_review_state> <ci_state> <mergeable_state>
+#   Prints one of:
+#     loop_self
+#     blocked_human_request_changes
+#     blocked_human_approved
+#     stale
+#     eligible
+#   Exit 0 always — callers parse the printed token.
+_loop_pr_classify() {
+  local head_ref="${1:-}"
+  local human_review="${2:-}"
+  local ci_state="${3:-}"
+  local mergeable="${4:-}"
+
+  case "$head_ref" in
+    loop/*) echo "loop_self"; return 0 ;;
+  esac
+
+  case "$human_review" in
+    CHANGES_REQUESTED) echo "blocked_human_request_changes"; return 0 ;;
+    APPROVED)          echo "blocked_human_approved";         return 0 ;;
+  esac
+
+  if [ "$ci_state" = "failure" ] || [ "$mergeable" = "CONFLICTING" ] || [ "$mergeable" = "BEHIND" ]; then
+    echo "stale"
+    return 0
+  fi
+
+  echo "eligible"
+}
+
+# _loop_pr_rebase_circuit <pr_number>
+#   Side effect: appends current timestamp to $_LOOP_STATE under
+#   pr_state.<PR>.attempts_at, pruning entries older than 24h.
+#   Exit 0: attempt allowed and recorded.
+#   Exit 1: ≥3 attempts within 24h → blocked; ALERT written.
+_loop_pr_rebase_circuit() {
+  local pr="$1"
+  [ -n "$pr" ] || return 1
+
+  local state="${_LOOP_STATE:-${HOME}/.shared/roll/loop/state.yaml}"
+  local now; now=$(date -u +%s)
+  local cutoff=$((now - 86400))
+
+  # Extract existing timestamps for this PR (empty if absent).
+  local existing=""
+  if [ -f "$state" ]; then
+    existing=$(awk -v pr="\"$pr\":" '
+      $0 ~ "pr_state:" {in_pr=1; next}
+      in_pr && $0 ~ pr {in_target=1; next}
+      in_target && $0 ~ /attempts_at:/ {
+        sub(/^[^"]*"/, ""); sub(/".*$/, ""); print; exit
+      }
+      in_target && /^[^[:space:]]/ {in_target=0}
+    ' "$state" 2>/dev/null)
+  fi
+
+  # Prune stale timestamps (>24h ago).
+  local fresh=""
+  local ts
+  for ts in $existing; do
+    case "$ts" in
+      ''|*[!0-9]*) continue ;;
+    esac
+    if [ "$ts" -ge "$cutoff" ]; then
+      fresh="${fresh:+$fresh }$ts"
+    fi
+  done
+
+  # Count attempts within window; ≥3 means this would be the 4th retry blocked.
+  local count=0
+  for ts in $fresh; do count=$((count + 1)); done
+
+  if [ "$count" -ge 3 ]; then
+    mkdir -p "$(dirname "${_LOOP_ALERT:-/dev/null}")" 2>/dev/null || true
+    cat > "${_LOOP_ALERT}" <<EOF
+# ALERT — PR rebase circuit breaker tripped
+
+**Time**: $(date '+%Y-%m-%d %H:%M')
+**PR**: #${pr}
+**Reason**: PR #${pr} rebased ${count}× within 24h without CI resolution — possible workflow file error  PR rebase 多次未解决，可能是 workflow 文件错误
+
+**Action required**:
+- Check PR CI logs and workflow files for breakage
+- Resolve manually, then: \`roll loop now\`
+EOF
+    return 1
+  fi
+
+  # Record this attempt and persist.
+  fresh="${fresh:+$fresh }$now"
+  _loop_pr_state_write "$pr" "$fresh" "$state"
+  return 0
+}
+
+# Internal: rewrite $state with pr_state.<pr>.attempts_at = "<fresh-ts-list>".
+# Minimal YAML writer — we own the schema and only need this one field family.
+_loop_pr_state_write() {
+  local pr="$1"
+  local attempts="$2"
+  local state="$3"
+
+  mkdir -p "$(dirname "$state")" 2>/dev/null || true
+  [ -f "$state" ] || : > "$state"
+
+  local tmp; tmp=$(mktemp)
+  awk -v pr="\"$pr\":" -v attempts="$attempts" '
+    BEGIN { in_pr=0; in_target=0; written=0 }
+    /^pr_state:/ { in_pr=1; print; next }
+    in_pr && $0 ~ pr {
+      in_target=1
+      print "  " pr
+      print "    attempts_at: \"" attempts "\""
+      written=1
+      next
+    }
+    in_target && /attempts_at:/ { next }   # skip old value, already written
+    in_target && /^[^[:space:]]/ { in_target=0 }
+    { print }
+    END {
+      if (!in_pr) {
+        print "pr_state:"
+        print "  " pr
+        print "    attempts_at: \"" attempts "\""
+      } else if (!written) {
+        print "  " pr
+        print "    attempts_at: \"" attempts "\""
+      }
+    }
+  ' "$state" > "$tmp" && mv "$tmp" "$state"
+}
+
+# _loop_pr_inbox
+#   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 prs_json
+  prs_json=$(gh -R "$slug" pr list --state open \
+    --json number,headRefName,author,title \
+    2>/dev/null) || return 0
+  [ -n "$prs_json" ] || return 0
+  [ "$prs_json" = "[]" ] && return 0
+
+  local count; count=$(echo "$prs_json" | jq 'length' 2>/dev/null || echo 0)
+  [ "${count:-0}" -gt 0 ] || return 0
+
+  local i=0
+  while [ "$i" -lt "$count" ]; do
+    local num head_ref
+    num=$(echo "$prs_json" | jq -r ".[$i].number")
+    head_ref=$(echo "$prs_json" | jq -r ".[$i].headRefName")
+
+    # Fetch CI + review state for this PR.
+    local view_json
+    view_json=$(gh -R "$slug" pr view "$num" \
+      --json reviews,mergeStateStatus,statusCheckRollup \
+      2>/dev/null) || { i=$((i + 1)); continue; }
+
+    local human_review ci_state mergeable
+    human_review=$(echo "$view_json" | jq -r '
+      [.reviews[]? | select(.authorAssociation != "BOT" and .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 ""
+      elif any(.statusCheckRollup[]?; .conclusion == "FAILURE") then "failure"
+      elif all(.statusCheckRollup[]?; .conclusion == "SUCCESS" or .conclusion == "SKIPPED") then "success"
+      else "pending" end' 2>/dev/null)
+
+    local verdict
+    verdict=$(_loop_pr_classify "$head_ref" "$human_review" "$ci_state" "$mergeable")
+
+    case "$verdict" in
+      loop_self|blocked_human_request_changes|blocked_human_approved)
+        : # skip — explained by verdict; nothing to do this cycle
+        ;;
+      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
+        ;;
+      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
+        ;;
+    esac
+
+    i=$((i + 1))
+  done
+  return 0
+}
+
 # US-CL-004: changelog 风格守门 Phase 1 — mechanical linter.
 #
 # _changelog_lint_bullet <bullet-text>
@@ -3156,7 +3440,7 @@ _changelog_style_anchors() {
     /^## v/ { ver++; if (ver > 3) exit; printing = 1; next }
     /^## /  { printing = 0 }
     printing && /^- / { print }
-  ' "$changelog" | head -c 1500
+  ' "$changelog" | head -c 1500 || true
 }
 
 # US-CL-005: changelog 风格守门 Phase 2 — self-audit gate.
@@ -3362,6 +3646,75 @@ _worktree_merge_back() {
   return 0
 }
 
+# _claude_remote_snapshot [repo]
+#   Echo the current set of remote `claude/*` branch names (sans
+#   refs/heads/), one per line, sorted. Silent on remote unreachable / no
+#   remote / no matches — empty stdout, exit 0.
+_claude_remote_snapshot() {
+  local repo="${1:-.}"
+  git -C "$repo" ls-remote --heads origin 'refs/heads/claude/*' 2>/dev/null \
+    | awk '{print $2}' \
+    | sed 's|^refs/heads/||' \
+    | sort
+}
+
+# _claude_cleanup_new_branches <prior> [repo]
+#   Delete remote `claude/*` branches present now but absent from <prior>
+#   (newline-separated list, as emitted by _claude_remote_snapshot). Skips
+#   silently when origin is not a GitHub remote. Each successful delete logs
+#   one INFO line; failures are silently ignored so the loop's main flow is
+#   never derailed.
+_claude_cleanup_new_branches() {
+  local prior="$1"
+  local repo="${2:-.}"
+  local url; url=$(git -C "$repo" remote get-url origin 2>/dev/null)
+  [[ "$url" == *github.com* ]] || return 0
+  local current; current=$(_claude_remote_snapshot "$repo")
+  [ -z "$current" ] && return 0
+  local prior_sorted; prior_sorted=$(printf '%s\n' "$prior" | sort -u)
+  local new_branches
+  new_branches=$(comm -13 <(printf '%s\n' "$prior_sorted") <(printf '%s\n' "$current"))
+  [ -z "$new_branches" ] && return 0
+  while IFS= read -r branch; do
+    [ -z "$branch" ] && continue
+    if git -C "$repo" push origin --delete "$branch" 2>/dev/null; then
+      echo "[loop] deleted stale claude branch: $branch"
+    fi
+  done <<< "$new_branches"
+  return 0
+}
+
+# _claude_cleanup_stale_worktrees [project_path]
+#   Remove local worktrees under <project_path>/.claude/worktrees/ whose
+#   branch has been fully merged into main (merge-base --is-ancestor). Active
+#   worktrees (branch ahead of main) are preserved. Runs `git worktree prune`
+#   afterwards to clear stale metadata. Silent on missing directory or any
+#   individual failure so the loop's main flow is never derailed.
+_claude_cleanup_stale_worktrees() {
+  local project_path="${1:-.}"
+  local wt_dir="${project_path}/.claude/worktrees"
+  [ -d "$wt_dir" ] || return 0
+  local entry branch
+  for entry in "$wt_dir"/*/; do
+    [ -d "$entry" ] || continue
+    branch=$(git -C "$project_path" worktree list --porcelain 2>/dev/null \
+      | awk -v p="${entry%/}" '
+          /^worktree / { cur=$2; flag=(cur==p) }
+          /^branch /   && flag { sub(/^refs\/heads\//, "", $2); print $2; flag=0 }
+        ')
+    [ -z "$branch" ] && branch=$(git -C "$entry" symbolic-ref --short HEAD 2>/dev/null)
+    [ -z "$branch" ] && continue
+    if git -C "$project_path" merge-base --is-ancestor "$branch" main 2>/dev/null; then
+      git -C "$project_path" worktree remove --force "$entry" 2>/dev/null || true
+      rm -rf "$entry" 2>/dev/null || true
+      git -C "$project_path" branch -D "$branch" 2>/dev/null || true
+      echo "[loop] removed stale worktree: $branch"
+    fi
+  done
+  git -C "$project_path" worktree prune 2>/dev/null || true
+  return 0
+}
+
 # US-AUTO-033: publish a loop cycle branch as a GitHub PR with auto-merge.
 #
 # _loop_publish_pr <branch> [title]

package/conventions/global/AGENTS.md

@@ -34,6 +34,10 @@
   - Requests made in conversation are NOT AC — capture with `roll-idea` first.
   - Any new Story/Fix requires design doc + user confirmation before TCR starts.
   - Do not commit without user approval unless explicitly told to auto-commit.
+- **Goal First**: Before any implementation, state verifiable success criteria.
+  Transform vague tasks: "add validation" → "write test for invalid input, then make it pass".
+  Multi-step work: list steps with verify checkpoints (step → verify: how to check).
+  Weak criteria ("make it work") require human clarification before starting.
 - **TCR**: Test -> Green = Commit / Red = Revert. No WIP commits.
   - Before implementing: confirm exact files, test strategy, and commit message
     draft with user. Do not write code until approved.
@@ -83,3 +87,9 @@ Confirm each phase clean before proceeding to the next.
 - `components/ui/` is shadcn-generated — never edit manually.
 - Tailwind utility classes only. No inline styles, no CSS modules.
 - Icons: Lucide React.
+
+## 8. Where to Look
+- **Domain model**: `docs/domain/context-map.md` — Bounded Contexts and relationships
+- **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.

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

@@ -25,3 +25,8 @@ src/
 - **TCR**: Mandatory.
 - **Security**: Input validation (zod), Rate limiting, Secrets rotation.
 - **Workspace**: `BACKLOG.md` + `docs/features/`.
+
+## 5. Where to Look
+- **Domain model**: `docs/domain/context-map.md` — Bounded Contexts and relationships
+- **Story details**: `docs/features/` — AC, implementation specs, dependencies
+- **Design decisions**: `docs/domain/` — DDD models, architecture records

package/conventions/templates/cli/AGENTS.md

@@ -27,3 +27,8 @@ tests/
 - **TCR**: Mandatory.
 - **Distribution**: `bin` in `package.json`, test `npm i -g`.
 - **Workspace**: `BACKLOG.md` + `docs/features/`.
+
+## 5. Where to Look
+- **Domain model**: `docs/domain/context-map.md` — Bounded Contexts and relationships
+- **Story details**: `docs/features/` — AC, implementation specs, dependencies
+- **Design decisions**: `docs/domain/` — DDD models, architecture records

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

@@ -24,3 +24,8 @@ src/
 - **TCR**: Mandatory.
 - **Testing**: Unit (hooks/logic) >80%, E2E (Playwright).
 - **Workspace**: `BACKLOG.md` + `docs/features/`.
+
+## 5. Where to Look
+- **Domain model**: `docs/domain/context-map.md` — Bounded Contexts and relationships
+- **Story details**: `docs/features/` — AC, implementation specs, dependencies
+- **Design decisions**: `docs/domain/` — DDD models, architecture records

package/conventions/templates/fullstack/AGENTS.md

@@ -27,3 +27,8 @@ api/
 - **TCR**: Mandatory.
 - **Testing**: Unit >80%, E2E for critical flows.
 - **Workspace**: `BACKLOG.md` + `docs/features/`.
+
+## 5. Where to Look
+- **Domain model**: `docs/domain/context-map.md` — Bounded Contexts and relationships
+- **Story details**: `docs/features/` — AC, implementation specs, dependencies
+- **Design decisions**: `docs/domain/` — DDD models, architecture records

package/package.json

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

package/skills/roll-design/SKILL.md

@@ -491,6 +491,19 @@ OrderPricingService:
 Domain: Order Context > Order Aggregate > OrderItem Entity
 ```
 
+### AGENTS.md Where to Look — 指针维护
+
+After completing any Domain Slice (User Story level), check if the project's `AGENTS.md` has a `## Where to Look` section with a `docs/domain/` pointer. If missing, append one line:
+
+```markdown
+- **Domain model**: `docs/domain/context-map.md` — Bounded Contexts and relationships
+```
+
+Rules:
+- Idempotent: only append if the pointer line is not already present
+- Do not modify any other content in AGENTS.md
+- Skip silently if `docs/domain/` does not yet exist for this project
+
 ---
 
 ## Clarify Phase
@@ -505,10 +518,20 @@ Domain: Order Context > Order Aggregate > OrderItem Entity
 - Contains ambiguous terms like "优化一下", "改一下", "加个东西", "做个设计"
 - Could be interpreted in multiple ways
 
+**Pre-Clarify: three-step product localization (always run first, silently)**
+
+Before listing questions, internally determine:
+1. **产品端 (product end)**: web / mobile / API / CLI / other — which surface does this touch?
+2. **角色 (role)**: who initiates this action? (end user / admin / system / external)
+3. **业务域 (domain)**: which business domain does this belong to?
+
+Already-localized dimensions become context prefix in the output, not open questions.
+
 **Output format:**
 
 ```
 🎯 Clarified Intent: {1-2 sentences}
+🗺  Context: {product end} · {role} · {domain}   ← omit if all three are unknown
 
 📏 Complexity: {small|medium|large}
 

package/skills/roll-doc/SKILL.md

@@ -124,6 +124,29 @@ For each gap:
 | Module with no README | `<dir>/README.md` |
 | No `docs/domain/` entries | `docs/domain/context-map.md` |
 | No conventions doc | `docs/CONVENTIONS.md` |
+| Missing `AGENTS.md` `## Where to Look` section | `AGENTS.md` (append or create) |
+
+**AGENTS.md Where to Look bootstrap:**
+
+When `AGENTS.md` has no `## Where to Look` section, generate and append one:
+
+1. Scan which doc directories actually exist: `docs/domain/`, `docs/features/`, `docs/practices/`, etc.
+2. Generate pointer lines **only for directories that actually exist** — never fabricate pointers to missing paths
+3. If `docs/domain/context-map.md` exists, read it to extract Bounded Context names for a one-line summary
+4. Append the section to the end of `AGENTS.md` with the standard draft header
+5. **Idempotency**: if `## Where to Look` already present, do not overwrite or duplicate — skip this gap
+
+Draft output format:
+
+```markdown
+> **Draft** — auto-generated by roll-doc on YYYY-MM-DD. Review before treating as authoritative.
+
+## Where to Look
+- **Domain model**: `docs/domain/context-map.md` — Contexts: {list from context-map, or "see file"}
+- **Story details**: `docs/features/` — AC, implementation specs, dependencies
+```
+
+Only include lines for directories that already exist in the project.
 
 **Every generated file starts with this exact header line:**
 

package/skills/roll-loop/SKILL.md

@@ -84,6 +84,33 @@ exact stuck-red state FIX-026 traces to).
 - `gh` missing or repo unparseable → graceful skip (`_loop_precheck_ci`
   returns 0); the post-build `_loop_enforce_ci` remains the strict gate.
 
+### Step 1.6 — PR Inbox (US-AUTO-034)
+
+Before scanning BACKLOG, process open PRs first. PRs are also units of work:
+external contributors and human teammates expect their PRs to be reviewed and
+moved forward, not starved while loop opens new fronts.
+
+Call `_loop_pr_inbox` after the pre-run CI check passes. It walks
+`gh pr list --state open` and routes each PR by classification:
+
+| Classification | Action |
+|---|---|
+| `loop_self` (head ref starts with `loop/`) | Skip — let GitHub auto-merge handle it; never AI-review your own commit |
+| `blocked_human_request_changes` | Skip — last human review requested changes; wait for the author to push fixes |
+| `blocked_human_approved` | Skip — let GitHub auto-merge after CI is green |
+| `stale` (CI failed or branch behind/conflicting) | Try `_loop_pr_rebase_stale` after the circuit breaker allows it |
+| `eligible` (clean external PR, no blocking review) | Invoke `_loop_pr_review_external` — the actual decision is provided by US-AUTO-035's GitHub Action |
+
+**Rebase circuit breaker** — `_loop_pr_rebase_circuit <pr>` records each rebase
+attempt under `pr_state.<PR>.attempts_at` in `state.yaml`, pruning entries older
+than 24 h. Once ≥3 attempts land within 24 h, further rebases are blocked and an
+ALERT is written (typical cause: a broken workflow file makes CI never run,
+which would otherwise drive infinite rebase loops).
+
+**Lenient on infrastructure** — `gh` missing, repo unparseable, or any
+`gh` API failure → `_loop_pr_inbox` returns 0 and the loop falls through to
+Step 2 (BACKLOG scan). Same posture as the pre-run CI check.
+
 ### Step 2 — Scan BACKLOG
 
 Read `BACKLOG.md`. Collect all rows where Status = `📋 Todo`, in order: