@seanyao/roll 2026.514.1 → 2026.514.3

package/CHANGELOG.md

@@ -1,136 +1,139 @@
 # Changelog
 
-## Unreleased
-- **Fixed**: dashboard 不再在已发版后还显示 "✓ Release ready"——只有 tag 之后存在非 docs/chore 的可发版提交时才亮，光是文档改写不会再让它误报
-- **Fixed**: dashboard 上 "📋 N PROPOSAL" 的动作提示改成 `see: PROPOSALS.md`，原先指向的 `roll backlog` 只看 BACKLOG.md，点过去看不到 PROPOSAL，逻辑断头
-- **Added**: changelog 生成时自动挡掉技术黑话
-- **Added**: 写 changelog 时会先参考最近几次发布的风格
-- **Added**: 故事跑完自动开 PR + auto-merge，CI 绿就合
-- **Added**: 完成的故事不再直接 push main，留下 PR 作为审计入口
-- **Added**: AI 代码评审可以批准 / 打回 PR — 配合 CI 形成合并双门；紧急 hotfix 在 PR body 加 `[skip-ai-review]` 即可绕开
-- **Added**: changelog 现在自审挡黑话
+## v2026.514.3
+
+### 约定与导航
+
+- `$roll-design` 澄清需求前先自己定位产品端和业务域，问你的问题少了
+- `$roll-doc` 为已有项目生成 AGENTS.md 导航骨架 — 新接入 Roll 不再从空白出发
+
+### 自动化流水线
+
+- loop 每轮先消化开放 PR 再领新 backlog — 把队列里的 PR 当成首类工作，不是绕开的障碍 `[loop]`
+- 自己开的 `loop/*` 分支不会被自己评审，避免同源 bias `[loop]`
+- 24 小时内 rebase 同一个 PR 超过 3 次自动熔断，workflow 文件出错时不再无限循环 `[loop]`
+- 每次 session 收尾自动删掉自己推上去的 `claude/*` 临时分支，远端不再积压"看起来要发 PR 实际不会发"的孤儿分支 `[loop]`
+
+## v2026.514.2
+
+### 自动化流水线
+
+- 故事跑完自动开 PR，CI 过了就合入主分支 — 你不需要盯着，审计记录也完整保留 `[loop]`
+- AI 评审现在有实权：可以批准或打回 PR，配合 CI 形成双重把关；真的很急可以在 PR 描述里加 `[skip-ai-review]` 临时绕过 `[loop]`
+- 散落的 session 分支自动清理，远端仓库不再越来越乱 `[loop]`
+
+### Changelog 开始管自己
+
+- 生成时自动过滤技术黑话，并对照历史风格保持表达一致 `[loop]`
+- 写入前有一道自审：行文不达标就退回重写，不进 changelog `[loop]`
+- 历史版本全部重新整理：按主题分组、合并同类项、附 `[loop]` / `[dream]` 归因标记
+- Release Notes 生成规范写入 Skill：分组规则、条目合并、归因标签、措辞原则
+
+### 可见性
+
+- Peer review 协商现在对所有 agent 实时可见，不再只是 claude 专属
+- "Release ready" 只有真的有东西可发时才会亮，纯文档改动不再误报 `[loop]`
+- PROPOSAL 的提示指向了实际有内容的地方 `[loop]`
+
+### 其他
+
+- 纯文档改动直接合 main，不等 CI，合并更快
+- README 新增 Evolution 章节，梳理 Roll 从工具到自主交付系统的演进脉络
 
 ## v2026.513.1
-- **Added**: loop 现在每轮跑在独立的 worktree 里，结束自动合回 main 并清理；跑挂时保留现场目录方便排查 — 再也不会吞掉 main 上你正在改的代码
-- **Added**: BACKLOG 上的 `depends-on:` 和 `manual-only:true` 标签从此有强制力，loop 选 story 前会过一遍，依赖没满足或标 manual-only 的直接跳过，不用人盯
-- **Fixed**: loop 多了一道并发保护 — 偶发的同一个 runner 下两个 claude 同时改状态的情况彻底堵住
-- **Changed**: CI 把 unit 和 integration 测试拆到两个 runner 并行跑，墙钟时间显著下降
-- **Changed**: `roll`（不带参数）的 dashboard 重新设计 — AI 在自动跑什么放第一眼，自治三层 + 四道防线 + Pipeline 全景 + 当前焦点 + 介入区一屏看完，不用再去 `roll loop status` 子命令翻
-- **Changed**: 测试运行器自动按机器核数并行，不再写死 4 个 job
-- **Changed**: 纯文档改动不再触发 CI 跑全套测试，文档 PR 合并节奏更快
-- **Fixed**: `roll peer` 在 REFINE / OBJECT 收尾时偶发的 "unbound variable" 崩溃
-- **Fixed**: `roll update` 后 `roll loop status` 不再误报 off，不用手动 `roll loop on` 恢复
+
+### Loop 更可靠了
+
+- 每轮 story 在独立工作区里跑，完了自动合回来清理；跑挂时现场保留，不会碰主分支上你正在改的东西 `[loop]`
+- `depends-on:` 和 `manual-only:` 标签现在真的有用 — Loop 自己会跳过条件没满足的任务，不用再盯着 `[loop]`
+- 同时只有一个 Loop 在跑，并发写入的问题修掉了 `[loop]`
+- `roll update` 之后 loop 状态不再误报 off `[loop]`
+
+### 测试和 CI
+
+- Unit 和集成测试并行执行，机器有多少核就用多少，等待时间降下来了 `[dream]`
+- 纯文档改动不触发 CI 全套测试，合并更快 `[dream]`
+
+### Dashboard
+
+- 重新设计：三层自治状态 + 四道防线 + Pipeline 全景 + 当前焦点 + 介入区，一屏看完 AI 正在做什么 `[loop]`
+
+### 修复
+
+- `roll peer` 协商退出时偶发的崩溃修掉了 `[loop]`
 
 ## v2026.512.8
-- **Added**: `$roll-doc` — 扫描任意项目的文档现状，找出缺口并生成草稿，支持 `--dry-run`
-- **Added**: `roll-.dream` Scan 6 — 每晚检测文档是否跟代码脱节，发现问题自动写进重构待办
-- **Fixed**: 某些 SSH 配置下 loop 把"CI 查询失败"误判为"CI 工具未安装"，导致测试没过就标任务完成
-
-## v2026.512.7
-- **Added**: `roll alert` — 查看、确认、清除 loop 告警，不用再去翻 loop status
-- **Added**: macOS 系统通知 — story 完成或告警写入时自动弹通知，静音模式下不打扰
-- **Added**: `roll ci [--wait]` — 查看当前提交的 CI 状态，或等待 CI 跑完再继续
-- **Fixed**: loop 现在会等 CI 通过后才标记故事完成，CI 失败则保持进行中并发出提醒
-- **Fixed**: changelog 更新不再产生独立 commit，并入故事完成提交，git log 更干净
-- **Added**: `docs/domain/` — Roll 架构领域模型文档
-- **Fixed**: `roll loop runs` 不再报"当前项目尚无运行记录"，历史记录正常显示
-- **Added**: 文档目录重组 — 散落文档统一迁移至 `docs/guide/` 和 `docs/practices/`
-- **Added**: README 精简，新增文档导航索引
-- **Added**: dream 每晚自动检测文档缺口，brief 新增文档覆盖率数字
-
-## v2026.512.6
-- **Added**: peer review 现在也会自动弹出终端窗口，实时观察跨 AI 协商过程（mute 关闭同一开关）
-- **Added**: `docs/guide/en/` — loop/dream/peer 英文用户指南上线，覆盖所有子命令和使用场景
-- **Added**: `docs/guide/zh/` — loop/dream/peer 中文用户指南上线，内容与英文版语义一致
-
-## v2026.512.5
-- **Fixed**: loop 遇到 API 错误时自动重试，不再直接中断
-
-## v2026.512.3
-- **Added**: BACKLOG 支持 block / defer / unblock 状态管理 — 标记卡住的任务不再占队列
-- **Fixed**: 自动弹窗现在能识别 Ghostty 和 iTerm2，不再强制弹出 Terminal.app
-- **Fixed**: loop 检测到上一轮还在跑时自动跳过，不重复启动
-
-## v2026.512.1
-- **Added**: `roll loop pause` / `roll loop resume` — 想自己上手时一键暂停 loop，做完再恢复
-- **Added**: `roll status` 新增所有项目的 loop 状态一览 — 调度时间、待办数、是否在跑
-- **Fixed**: `roll loop attach` 不再黑屏，AI 干活过程实时可见
-
-## v2026.511.7
-- **Added**: loop 跑起来时自动弹出一个终端窗口，看 AI 实时干活
-- **Added**: `roll loop mute` 关掉自动弹窗，`roll loop unmute` 恢复
-- **Added**: `roll loop runs` — 查看 loop 最近几次都跑了什么
-- **Added**: `roll loop attach` — 随时接入正在跑的 loop 现场围观
-- **Added**: BACKLOG 任务执行中会实时显示 🔨 进度，不用等做完才知道
-- **Added**: `roll setup` 自动安装 tmux（macOS 通过 brew）
-- **Improved**: 代码巡检（dream）报告改为中文输出
-- **Fixed**: loop 在某些情况下完成后不正常退出
-- **Fixed**: loop 中途崩溃后下次启动会自动清理残留状态
-
-## v2026.511.6
-- **Fixed**: 多个 loop 实例不会再因为定时重复触发而互相打架
-
-## v2026.511.5
-- **Fixed**: 升级 roll 后 loop 服务自动生效，无需手动重启
-- **Improved**: `roll loop status` 三态显示，看得清是真没装、装了没启、还是在跑
-
-## v2026.511.4
-- **Fixed**: 升级 roll 后 `roll init` 自动迁移 loop 配置，少一步手动操作
-
-## v2026.511.3
-- **Fixed**: 多个项目同时跑 loop，互不干扰
-- **Fixed**: 在 roll 项目里运行 `roll release` 会提示改用 `scripts/release.sh`
-
-## v2026.511.2
-- **Added**: `roll loop monitor` — 一屏看 loop/dream/brief 三个调度服务状态
-- **Fixed**: dashboard 待办数、release 状态显示问题
-- **Fixed**: loop 异常退出后队列卡住不再继续执行
-- **Improved**: 简报输出更精简，去掉空白段落和冗余信息
-
-## v2026.511.1
-- **Changed**: macOS 上 loop 调度切换到 launchd，比 crontab 更稳定
-- **Added**: agent 跳过 TCR 节奏时自动拦回 Todo，强制重做
+
+### 掌控感更强了
+
+Loop 已经能跑、能看了——这一批让你对它有更多控制权：
+
+- `roll loop pause` / `roll loop resume` — 想自己上手时一键暂停，做完再让 AI 接着跑 `[loop]`
+- `roll alert` — 集中查看、确认、清除 loop 产生的告警，不用翻 loop status `[loop]`
+- macOS 系统通知 — story 完成或有新告警时自动弹通知，静音模式下不打扰 `[loop]`
+- `roll ci [--wait]` — 查看当前 CI 状态，或等 CI 跑完再继续手头的事
+
+### Loop 更聪明了
+
+- Loop 现在等 CI 通过后才标 story 完成，CI 红了会保持进行中并发出提醒 `[loop]`
+- API 出错时自动重试，不再直接中断 `[loop]`
+- 弹窗认识 Ghostty 和 iTerm2 了，不再强制弹 Terminal.app `[loop]`
+- BACKLOG 支持 `block` / `defer` — 卡住的任务标一下就不占队列了
+
+### 文档体系上线
+
+- loop / dream / peer 中英文用户指南全部上线，覆盖所有子命令和使用场景 `[dream]`
+- `$roll-doc` — 扫描任意项目的文档现状，找出缺口并生成草稿 `[dream]`
+- Dream 每晚检测文档是否跟代码脱节，发现问题写进重构待办 `[dream]`
+- `roll status` 新增跨项目 loop 状态一览
+
+## v2026.511.8
+
+### 终于能看到 Loop 在做什么了
+
+Loop 上线后最大的感受是「不知道它在干啥」——这一批更新专门解决这个问题：
+
+- Loop 开跑时自动弹出终端窗口，AI 干活的过程实时可见 `[loop]`
+- `roll loop attach` — 随时接入正在跑的 loop 现场 `[loop]`
+- `roll loop runs` — 查看 loop 最近几次跑了什么、完成了哪些 `[loop]`
+- BACKLOG 任务执行中实时显示进度标记，不用等做完才知道 `[loop]`
+- 不想被打扰时，`roll loop mute` 关掉弹窗，`roll loop unmute` 恢复
+
+### Loop 更稳了
+
+- macOS 上调度从 crontab 换成 launchd，重启后不丢 `[loop]`
+- 升级 roll 后 loop 服务自动生效，不用手动重启 `[loop]`
+- 多个项目同时跑 loop，互不干扰 `[loop]`
+- 崩溃或异常退出后，下次启动自动清理残留状态 `[loop]`
+- 并发触发时自动跳过，不重复执行 `[loop]`
+
+### 其他改进
+
+- `roll loop monitor` — 一屏查看 loop / dream / brief 三个服务状态
+- `roll loop status` 三态显示：没装 / 装了没启 / 正在跑，一眼看清
+- `roll init` 升级后自动迁移 loop 配置，少一步手动操作
 
 ## v2026.510.10
-- **Fixed**: release.sh changelog 同步时序修复 — 修正条件逻辑和执行顺序，确保每次发版时 changelog 正确更新
-- **Added**: roll-loop 22:00 自动执行验证 — 新增 hello_world.bats 作为 loop 定时执行的端到端存档，可回放确认调度器正常工作
-
-## v2026.510.9
-- **Fixed**: CHANGELOG 改版本号分组 — 每个 release 独立 section，GitHub Release 增量内容提取正确
-- **Fixed**: release.yml 加 fetch-depth: 0，确保历史 tag 在 workflow 中可见
-
-## v2026.510.8
-- **Fixed**: release.sh 自洽 — 发版流程不依赖外部调用
-- **Fixed**: `roll release` 改为独立调用 roll-release skill，与 release.sh 解耦
-- **Fixed**: GitHub Release workflow 加 fetch-depth: 0，确保历史 tag 可见
-
-## v2026.510.7
-- **Fixed**: 版本比较改用 sort -V，防止旧版本号被误判为最新
-- **Fixed**: 版本更新后主动清缓存 — 检测到运行版本更新时自动清缓存，避免旧版本幽灵提示
-- **Fixed**: Kimi CLI 解析修复 — 剥离 YAML frontmatter 中的 `---` 分隔符，避免调用时解析崩溃
-- **Fixed**: dashboard 命令列表补全，`roll --help` 现在展示全部可用命令
-- **Added**: `roll release` 命令补全到 usage() 帮助中
-
-## v2026.510.6
-- **Fixed**: Agent 调用层统一 — 移除所有 claude -p 硬编码，统一 agent 抽象层，支持 Claude/Kimi/Pi/Codex/OpenCode
-- **Fixed**: pi/codex/opencode 支持补全 — _agent_run_skill/_peer_call 穷举所有 agent，未知 agent 给明确错误
-- **Fixed**: kimi 非交互调用语法修正为 kimi --quiet -p，经实测验证
-- **Fixed**: roll-build / roll-fix Phase 12 强制触发 roll-.changelog，确保 CHANGELOG 与 BACKLOG 同步
-- **Added**: roll release 命令 — 在 roll CLI 内直接调用 roll-release skill
-- **Added**: GitHub Release 自动创建 — tag push 后由 workflow 从 CHANGELOG diff 提取内容
-
-## v2026.510.5
-- **Added**: roll-loop — BACKLOG 自主执行器，支持调度、跨 Agent 路由和失败处理，让 AI 自主推进项目任务
-- **Added**: roll-brief — Feature完成汇报、每日晨报、按需简报，一句话掌握项目状态和发布就绪情况
-- **Added**: roll-.dream — 每晚代码架构健康巡检，自动产出 REFACTOR 条目，架构问题持续浮出水面
-- **Added**: roll-build 架构摩擦信号 — 实现遇阻时自动向 BACKLOG 写入 REFACTOR 标记，技术债持续可见
-- **Added**: E2E 自动沉淀 — 每个 Story 交付时自动写一个端到端测试，项目逐步积累可回放的 E2E 套件
-- **Added**: CI E2E 门禁 — 模板 CI 每次推送自动跑 E2E 测试，没有 E2E 时静默跳过不阻塞
-- **Added**: CI 红灯分诊 — 按严重程度分类 CI 失败，自动路由到 backlog 变成可执行的修复项
-- **Added**: roll-debug 自动修复 — 诊断后若根因在项目源码内，自动进入 TCR 修复流程并回验
-- **Added**: Changelog 自动生成 — 每次部署后自动更新，首次运行时回填全部历史记录
-- **Added**: roll status/update 显示最近更新 — 运行 `roll status` 或 `roll update` 时展示最近 3 个版本的 changelog
-- **Fixed**: roll-release 补齐 GitHub Release 创建步骤 — 修复版本更新提醒从不生效的问题
+
+### Loop、Dream、Brief 首次亮相
+
+Roll 从「技能编排工具」变成了「自主执行系统」——三个新组件同步上线：
+
+- `roll loop` — 让 AI 自动调度 BACKLOG，Story 一个接一个跑，不用你盯着
+- `roll brief` — 每天早上自动整理昨天做了什么，帮你快速恢复上下文
+- `roll-.dream` — 每晚自动巡检代码和架构，把发现的问题写成可执行的待办
+
+### 自动化能力
+
+- 每个 Story 交付时自动沉淀一个 E2E 测试，项目逐步积累可回放的验收套件 `[loop]`
+- CI 失败会自动分诊，按严重程度路由成 backlog 里可执行的修复项 `[loop]`
+- `roll debug` 诊断出根因在源码内时，自动进入修复流程并回验 `[loop]`
+- Changelog 每次部署后自动更新，不再需要手动整理 `[loop]`
+
+### 可见性
+
+- `roll status` / `roll update` 运行后展示最近几个版本的更新内容
+- `roll release` 命令 — 在 CLI 里直接触发发布，不用记路径
 
 ## 2026.05.09
 - **Added**: roll-peer 跨 Agent 代码评审 — 支持 Claude Code、Kimi CLI、DeepSeek TUI、Codex CLI 多工具协同评审 (by @seanyao)

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)

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.1"
+VERSION="2026.514.3"
 ROLL_HOME="${ROLL_HOME:-${HOME}/.roll}"
 ROLL_CONFIG="${ROLL_HOME}/config.yaml"
 ROLL_GLOBAL="${ROLL_HOME}/conventions/global"
@@ -1903,7 +1903,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" ;;
@@ -2963,15 +2963,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 +3159,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 +3427,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.

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.1",
+  "version": "2026.514.3",
   "description": "Roll — Roll out features with AI agents",
   "scripts": {
     "test": "bash tests/run.sh"

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

@@ -286,3 +286,74 @@ After successful deploy in `$roll-build` / `$roll-fix`:
 **Post-Deploy:**
 - `$roll-.changelog` - Sync external changelog
 ```
+
+---
+
+## 7. Release Notes 生成模式（GitHub Release 正文）
+
+`CHANGELOG.md` 里的 `## Unreleased` 条目是**原始数据**，每条对应一个故事或修复。
+发版时（`release.sh` 打 tag 前，或手动 `roll release notes`），把这些散装 bullet 整理成**给人读的 Release 正文**。
+
+这是两个不同的产物：
+- `CHANGELOG.md` — 机器写、给 `roll update` 之后展示用，条目可以多
+- GitHub Release 正文 — 给用户 / 关注者读，要分组、要有温度、要简洁
+
+### 7.1 何时触发
+
+- `release.sh` 在 commit 之前调用本 skill 并传入 `--release-notes` flag
+- 或用户手动说"帮我整理 Release Notes"
+
+### 7.2 分组规则
+
+把当前版本的 bullet 按**用户感知**归入以下分组，每组最多 5 条，超出的合并：
+
+| 分组标题 | 归入条件 |
+|---|---|
+| 自动化流水线 | PR 自动化、Auto-merge、CI 触发、分支管理 |
+| 可见性 | Dashboard、弹窗、实时输出、状态显示 |
+| 稳定性 | 崩溃修复、并发问题、状态误报 |
+| 工程和测试 | CI 速度、测试并行、文档工作流 |
+| 新功能 | 全新命令或用户可感知的新能力 |
+
+分组顺序：**影响日常使用的放前面**，纯工程改进放后面。
+分组少于 2 条时可以合并到相邻组，不强制保留空组。
+
+### 7.3 合并相似条目
+
+同一功能点的多个 bullet（如"开 PR"和"Auto-merge"都在描述同一条流水线）合并为一条，用一句话说清楚整体效果，不要列两条。
+
+判断标准：**用户感知到的是同一件事，就合并。**
+
+### 7.4 归因标签
+
+在每条末尾加标签，说明是谁做的：
+
+| 标签 | 归因依据 |
+|---|---|
+| `[loop]` | 对应 `US-AUTO-*` / `FIX-*` / `US-CL-*` 故事，由 Loop 自动执行 |
+| `[dream]` | 对应 `REFACTOR-*` 故事，由 Dream 夜间扫描发现并推入 Backlog |
+| （无标签） | 人工提交，或无法确定来源 |
+
+### 7.5 措辞原则
+
+- 用**第二人称**（"你不需要盯着"、"你可以随时查看"）
+- **主语是用户的感受**，不是系统的行为（"不再误报" > "修复了误报逻辑"）
+- **故意模糊实现细节**：不写函数名、文件名、Phase 编号
+- **有温度**：可以用"真的很急"、"不再越来越乱"这样口语化的表达
+- 每条一行，简洁优先
+
+### 7.6 输出格式
+
+```markdown
+## <分组标题>
+
+- <条目> `[loop]`
+- <条目> `[dream]`
+- <条目>
+
+## <分组标题>
+
+- ...
+```
+
+不需要 `**Added**` / `**Fixed**` 前缀，分组标题已经承担了语义分类的职责。

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: