@seanyao/roll 2026.513.1 → 2026.514.2

package/CHANGELOG.md

@@ -1,127 +1,128 @@
 # Changelog
 
+## v2026.514.2
+
+- Changelog 历史版本全部重新整理：按主题分组、合并同类项、用词更贴近用户视角，附 `[loop]` / `[dream]` 归因标记
+- Changelog Skill 新增 Release Notes 生成规范：分组规则、条目合并、归因标签、措辞原则
+- README 新增 Evolution 章节，梳理 Roll 从工具到自主交付系统的演进脉络
+
+## v2026.514.1
+
+### 自动化流水线
+
+- 故事跑完自动开 PR，CI 过了就合入主分支 — 你不需要盯着，审计记录也完整保留 `[loop]`
+- AI 评审现在有实权：可以批准或打回 PR，配合 CI 形成双重把关；真的很急可以在 PR 描述里加 `[skip-ai-review]` 临时绕过 `[loop]`
+- 散落的 session 分支自动清理，远端仓库不再越来越乱 `[loop]`
+
+### Changelog 开始管自己
+
+- 生成时自动过滤技术黑话，并对照历史风格保持表达一致 `[loop]`
+- 写入前有一道自审：行文不达标就退回重写，不进 changelog `[loop]`
+
+### 可见性
+
+- Peer review 协商现在对所有 agent 实时可见，不再只是 claude 专属
+- "Release ready" 只有真的有东西可发时才会亮，纯文档改动不再误报 `[loop]`
+- PROPOSAL 的提示指向了实际有内容的地方 `[loop]`
+
+### 其他
+
+- 纯文档改动直接合 main，不等 CI，合并更快
+
 ## v2026.513.1
-- **Added**: loop worktree 隔离 Phase 2 — `_write_loop_runner_script` 现在让每轮 cron 在独立的 `loop/cycle-<ts>-<pid>` worktree 里跑 claude，结束后 ff-merge 回 main + 自动清理；失败保留 worktree + 写 ALERT。loop 不再吞 main 的 WIP，多轮之间也完全隔离。claude 仍保留 story selection 权（SKILL.md 不变）
-- **Added**: loop worktree 隔离 Phase 1 — `bin/roll` 新增 7 个 `_worktree_*` helpers（path / create 幂等 / cleanup / fetch lenient / submodule init / merge_back ff-only / alert），覆盖 loop 在独立 worktree 跑 story 的完整生命周期；零行 runner.sh 改动，loop 自己也能跑；US-AUTO-037 (manual-only) 之后把这些 helpers 接入 `_write_loop_runner_script`
-- **Added**: loop 依赖闸门 — BACKLOG 行末尾的 `` `depends-on:US-X,US-Y` `` 和 `` `manual-only:true` `` 标签从此具有强制力；loop 选 story 前先用 `_loop_check_depends_on` / `_loop_is_manual_only` 两个 helper 过一遍，未满足依赖或带 manual-only 标的 story 直接跳过并写 `skipped` runs.jsonl 记录，不再需要靠人盯标签
-- **Fixed**: loop 并发保护补丁 — 2026-05-13 14:37 实测同 runner 下出现并发 claude 会话同时改 state.yaml / BACKLOG / git；inner script 现新增二级 LOCK（PID + start-ts 4h 双校验），守住 claude 调用现场，外层 LOCK 即使被旁路也兜底
-- **Changed**: CI 拆 unit / integration 双 job 并行 — `tests/run.sh` 接受可选目录参数；`.github/workflows/ci.yml` 用 `strategy.matrix` 把 509 unit + 70 integration 用例分到两个 runner 并行跑（REFACTOR-009 Phase 1B）；Phase 2 测试瘦身拆到 REFACTOR-010
-- **Changed**: `roll`（无参）dashboard 重设计 — 自治优先六块布局：① Identity（项目名 + 版本 + agent + git 状态）② AI 自治主视觉（Loop / Dream / Peer 三层 + 四道防线，框线高亮）③ Pipeline 全景（Idea/Backlog/Build/Verify/Release 五段计数）④ Current Focus · DoD（in-progress story 的 [AC] [CI] 信号，其余 4 项标注待接入）⑤ Human × AI 介入区（ALERT/PROPOSAL/Release ready，空时显示"AI 自驱中"）⑥ Schedules & Last Brief。把"AI 自动跑什么"放第一眼，不再埋在 `roll loop status` 子命令里
-- **Changed**: CI 测试运行器 (`tests/run.sh`) 动态检测核数（`nproc`/`sysctl`）替换硬编码 `--jobs 4`，可用 `ROLL_TEST_JOBS` 覆盖；bats-core submodule 缺失时给出清晰报错
-- **Changed**: GitHub Actions CI 跳过 docs-only PR（`paths-ignore: **.md, docs/**`），文档改动不再触发全套 bats
-- **Fixed**: `roll peer` 在 REFINE/OBJECT 退出路径上的 "resolution: unbound variable" 风险 — cmd_peer 显式初始化 `local resolution=""`，并补齐 AGREE/REFINE/OBJECT/ESCALATE/UNKNOWN 五条退出路径的回归测试
-- **Fixed**: `roll update` 后 `roll loop status` 误报 off — `_install_launchd_plists` reload 路径改用 `launchctl bootout` + `bootstrap`（不动 overrides db），消除 macOS Sonoma+ 上 no-`-w` unload/load 把 label `enabled` 标记吞掉的副作用；不再需要手动 `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` — legacy 项目文档自动化技能：四阶段扫描（索引 + 缺口分析 + 草稿补全 + 报告），支持 `--dry-run` / `--force`，适用任何项目
-- **Added**: `roll-.dream` Scan 6 — 文档新鲜度检测（滞后文档 / 未记录 ENV 变量 / 架构文档缺失），依赖 roll-doc，发现写入 REFACTOR 条目
-- **Fixed**: loop CI gate 在 SSH config 改写 github.com 为 IP 的环境下失灵 — `gh` 自动识别失败被静默吞掉，loop 把 "gh 出错" 误判为 "gh 未装"，在 CI 红的情况下继续把 story 标 ✅ Done；现从 git remote 推导 `owner/repo` 强制传 `-R`，gh 调用失败 = ALERT，loop 起跑前先验 HEAD CI 红绿，红则拒绝 build
-
-## 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 架构的 DDD 领域模型文档（5 个 Bounded Context + 自治操作 Aggregate 设计）
-- **Fixed**: `roll loop runs` 不再报"当前项目尚无运行记录"，历史记录正常显示
-- **Added**: 文档目录重组 — methodology、skill 选择指南、loop 验证记录迁移至 `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 自洽 — 内联 agent 检测和 changelog 同步，发版流程不依赖外部调用
-- **Fixed**: roll release 命令重构 — 改为独立调用 roll-release skill，与 scripts/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

@@ -74,6 +74,22 @@ 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.513.1"
+VERSION="2026.514.2"
 ROLL_HOME="${ROLL_HOME:-${HOME}/.roll}"
 ROLL_CONFIG="${ROLL_HOME}/config.yaml"
 ROLL_GLOBAL="${ROLL_HOME}/conventions/global"
@@ -609,6 +609,36 @@ cmd_setup() {
 
   echo ""
   info "Next: run ${BOLD}roll init${NC} inside a project to initialize it.  下一步：在项目目录运行 roll init"
+
+  echo ""
+  _print_pr_pipeline_hint
+}
+
+# ─── PR pipeline hint ────────────────────────────────────────────────────────
+# US-AUTO-035: print the one-time branch-protection command that flips repo
+# from path A (CI gate only) to path C (CI + AI review double gate). Reading
+# this hint is opt-in; the command is destructive (changes branch protection)
+# so it is never run automatically.
+_print_pr_pipeline_hint() {
+  cat <<'HINT'
+
+  Optional — enable AI review as a hard merge gate (path C).
+  可选 —— 启用 AI 评审作为合并双门（路径 C）。
+
+  Run once per repo (requires admin token), then claude-code-review.yml
+  approvals become a required merge gate alongside CI:
+  每个仓库执行一次（需要管理员 token），之后 claude-code-review.yml 的
+  approve 将与 CI 一起成为合并必经的双门：
+
+      gh api -X PATCH repos/<owner>/<repo>/branches/main/protection \
+        -f required_pull_request_reviews.required_approving_review_count=1
+
+  Escape hatch: add [skip-ai-review] to a PR body, or include
+  SKIP_AI_REVIEW in any commit message, to bypass AI review for that PR.
+  紧急通道：在 PR body 加 [skip-ai-review]，或在任一 commit message
+  里包含 SKIP_AI_REVIEW，可对该 PR 绕过 AI 评审。
+
+HINT
 }
 
 # ═══════════════════════════════════════════════════════════════════════════════
@@ -2118,15 +2148,31 @@ for _attempt in 1 2 3; do
   fi
 done
 
-# Post-claude: merge back if we used an isolated worktree.
+# 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.
 if [ "\$_USE_WORKTREE" = "1" ]; then
   if [ "\$_exit" -eq 0 ]; then
-    if ( cd "${project_path}" && _worktree_merge_back "\$BRANCH" ); then
+    if ( cd "\$WT" && _loop_is_doc_only_change ); then
+      ( cd "\$WT" && _loop_publish_doc_pr "\$BRANCH" "doc: loop cycle \${CYCLE_ID}" )
+    else
+      ( cd "\$WT" && _loop_publish_pr "\$BRANCH" "loop cycle \${CYCLE_ID}" )
+    fi
+    _publish_status=\$?
+    if [ "\$_publish_status" -eq 0 ]; then
       _worktree_cleanup "\$WT" "\$BRANCH"
-      echo "[loop] cycle \${CYCLE_ID}: merged and cleaned up"
+      echo "[loop] cycle \${CYCLE_ID}: published; worktree cleaned"
+    elif [ "\$_publish_status" -eq 2 ]; then
+      if ( cd "${project_path}" && _worktree_merge_back "\$BRANCH" ); 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"
+      fi
     else
-      _worktree_alert "cycle \${CYCLE_ID}: merge_back failed; worktree preserved at \$WT (branch \$BRANCH)"
-      echo "[loop] cycle \${CYCLE_ID}: merge_back failed; worktree preserved at \$WT"
+      _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
   else
     _worktree_alert "cycle \${CYCLE_ID}: claude exited \$_exit; worktree preserved at \$WT (branch \$BRANCH)"
@@ -3055,6 +3101,172 @@ _loop_is_manual_only() {
   echo "$row" | grep -qE 'manual-only:true'
 }
 
+# US-CL-004: changelog 风格守门 Phase 1 — mechanical linter.
+#
+# _changelog_lint_bullet <bullet-text>
+#   Stdout: one violation tag per line; empty = bullet passes.
+#   Exit:   0 always (callers read the output stream, not the exit code).
+#
+# Violation tags:
+#   backtick-identifier  `…` contains `_` or `()`  (e.g. `_foo`, `bar()`)
+#   file-suffix          `.md`/`.sh`/`.yml`/`.ts`/`.bats` outside backticks
+#   internal-word        Phase N / Step N / Helper / Schema / Fixture / Refactor
+#   over-length          > 50 visible chars (UTF-8 codepoints; 中文按字符计)
+#   path-fragment        docs/ / bin/ / tests/ / scripts/ outside backticks
+#
+# Backticks are treated as the "user-quoted" zone — content there is assumed
+# to be a real user command (e.g. `roll edit notes.md`) and is excluded from
+# the file-suffix / path-fragment checks.
+_changelog_lint_bullet() {
+  local bullet="$1"
+  local stripped
+  stripped=$(printf '%s' "$bullet" | sed -E 's/`[^`]*`//g')
+
+  if printf '%s' "$bullet" | grep -qE '`[^`]*(_|\(\))[^`]*`'; then
+    echo "backtick-identifier"
+  fi
+  if printf '%s' "$stripped" | grep -qE '\.(md|sh|yml|ts|bats)([^A-Za-z0-9]|$)'; then
+    echo "file-suffix"
+  fi
+  if printf '%s' "$bullet" | grep -qE '(Phase|Step)[[:space:]]+[0-9]+|Helper|Schema|Fixture|Refactor'; then
+    echo "internal-word"
+  fi
+  local len
+  len=$(printf '%s' "$bullet" | LC_ALL=C.UTF-8 wc -m | tr -d ' ')
+  if [ "${len:-0}" -gt 50 ]; then
+    echo "over-length"
+  fi
+  if printf '%s' "$stripped" | grep -qE '(^|[^A-Za-z0-9_])(docs|bin|tests|scripts)/'; then
+    echo "path-fragment"
+  fi
+  return 0
+}
+
+# US-CL-004: changelog few-shot style anchors — extract bullets from the
+# most recent 3 published `## v...` sections of CHANGELOG.md (skipping
+# `## Unreleased`). Cap at ~1500 chars so the agent's context stays lean.
+#
+# _changelog_style_anchors [changelog-path]
+#   Stdout: concatenated bullet lines from the last 3 released versions.
+#   Exit:   0 (empty output when no CHANGELOG.md or no released sections).
+_changelog_style_anchors() {
+  local changelog="${1:-CHANGELOG.md}"
+  [ -f "$changelog" ] || return 0
+  awk '
+    /^## v/ { ver++; if (ver > 3) exit; printing = 1; next }
+    /^## /  { printing = 0 }
+    printing && /^- / { print }
+  ' "$changelog" | head -c 1500
+}
+
+# US-CL-005: changelog 风格守门 Phase 2 — self-audit gate.
+#
+# _changelog_audit_bullet <bullet>
+#   Stricter than _changelog_lint_bullet: 5 boolean rules, 30-char cap.
+#   Stdout: one failed-rule tag per line; empty = bullet passes.
+#   Exit:   0 always.
+#
+# Rules:
+#   over-length-30   visible chars > 30 AND no backtick (user-cmd escape hatch)
+#   internal-id      backtick content contains `_` or `()`
+#   path-or-suffix   .md/.sh/.yml/.ts/.bats or docs/bin/tests/scripts/ outside backticks
+#   phase-step       `Phase N` / `Step N` workflow vocabulary
+#   bad-shape        no `—` (em dash) AND no `不再` AND no `现在` keyword
+_changelog_audit_bullet() {
+  local bullet="$1"
+  local stripped
+  stripped=$(printf '%s' "$bullet" | sed -E 's/`[^`]*`//g')
+
+  # Rule 1: length cap 30 (user-command in backticks bypasses this rule).
+  if ! printf '%s' "$bullet" | grep -q '`'; then
+    local len
+    len=$(LC_ALL=en_US.UTF-8 printf '%s' "$bullet" | LC_ALL=en_US.UTF-8 wc -m | tr -d ' ')
+    if [ "${len:-0}" -gt 30 ]; then
+      echo "over-length-30"
+    fi
+  fi
+
+  # Rule 2: internal identifier inside backticks.
+  if printf '%s' "$bullet" | grep -qE '`[^`]*(_|\(\))[^`]*`'; then
+    echo "internal-id"
+  fi
+
+  # Rule 3: file suffix / path fragment outside backticks.
+  if printf '%s' "$stripped" | grep -qE '\.(md|sh|yml|ts|bats)([^A-Za-z0-9]|$)' \
+    || printf '%s' "$stripped" | grep -qE '(^|[^A-Za-z0-9_])(docs|bin|tests|scripts)/'; then
+    echo "path-or-suffix"
+  fi
+
+  # Rule 4: workflow vocabulary.
+  if printf '%s' "$bullet" | grep -qE '(Phase|Step)[[:space:]]+[0-9]+'; then
+    echo "phase-step"
+  fi
+
+  # Rule 5: required shape — em dash, 不再, or 现在.
+  if ! printf '%s' "$bullet" | grep -qE '—|不再|现在'; then
+    echo "bad-shape"
+  fi
+
+  return 0
+}
+
+# _changelog_audit_log <verdict> <round> <bullet> [<reason>...]
+#   Append a JSONL record to the audit log. Path overridable via
+#   ROLL_CHANGELOG_AUDIT_LOG (tests use this to stay out of $HOME).
+_changelog_audit_log() {
+  local verdict="$1" round="$2" bullet="$3"
+  shift 3
+  local log="${ROLL_CHANGELOG_AUDIT_LOG:-${_SHARED_ROOT}/loop/changelog-audit.jsonl}"
+  mkdir -p "$(dirname "$log")"
+  local ts; ts=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+  local reasons_json='[]'
+  if [ "$#" -gt 0 ]; then
+    reasons_json=$(printf '%s\n' "$@" | jq -R . | jq -sc .)
+  fi
+  jq -nc \
+    --arg ts "$ts" \
+    --arg verdict "$verdict" \
+    --argjson round "$round" \
+    --arg bullet "$bullet" \
+    --argjson reasons "$reasons_json" \
+    '{ts:$ts, verdict:$verdict, round:$round, bullet:$bullet, reasons:$reasons}' \
+    >> "$log"
+}
+
+# _changelog_audit_gate <round1> [<round2> <round3>]
+#   Run up to 3 candidate bullets through _changelog_audit_bullet.
+#   First clean candidate wins: print bullet to stdout, exit 0.
+#   All 3 failed: print ⚠️-prefixed last candidate, append ALERT, exit 1.
+#   Each round writes a _changelog_audit_log record.
+_changelog_audit_gate() {
+  local i=0 last=""
+  for candidate in "$@"; do
+    i=$((i + 1))
+    last="$candidate"
+    local viols
+    # shellcheck disable=SC2207
+    viols=( $(_changelog_audit_bullet "$candidate") )
+    if [ "${#viols[@]}" -eq 0 ]; then
+      _changelog_audit_log pass "$i" "$candidate"
+      printf '%s\n' "$candidate"
+      return 0
+    fi
+    _changelog_audit_log fail "$i" "$candidate" "${viols[@]}"
+    [ "$i" -ge 3 ] && break
+  done
+  # All 3 rounds failed (or fewer if caller passed < 3).
+  mkdir -p "$(dirname "$_LOOP_ALERT")" 2>/dev/null
+  {
+    echo ""
+    echo "# ALERT — changelog audit failed after $i rounds"
+    echo "**Time**: $(date -u +%Y-%m-%dT%H:%M:%SZ)"
+    echo "**Bullet**: $last"
+    echo "**Action**: kept under \`## Unreleased\` with ⚠️ prefix; human review recommended."
+  } >> "$_LOOP_ALERT"
+  printf '⚠️ %s\n' "$last"
+  return 1
+}
+
 # US-AUTO-036: worktree helpers (loop-safe pure additions).
 #
 # Phase 1 of worktree isolation — these helpers are NOT yet called by
@@ -3150,6 +3362,107 @@ _worktree_merge_back() {
   return 0
 }
 
+# US-AUTO-033: publish a loop cycle branch as a GitHub PR with auto-merge.
+#
+# _loop_publish_pr <branch> [title]
+#   Caller's cwd: a tree where <branch> exists locally.
+#   Steps:
+#     1. git push origin <branch>
+#     2. gh pr view <branch>  → reuse if a PR is already open
+#     3. gh pr create --base main --head <branch> ...
+#     4. gh pr merge <branch> --auto --squash --delete-branch
+#   Stdout: PR URL (always, even on idempotent reuse).
+#   Exit 0 on success / idempotent reuse; non-zero on push or create failure.
+#   On auto-merge failure: still returns 0 (PR exists; human can take over).
+#   When `gh` is not installed: returns 2 — runner script's fallback path.
+_loop_publish_pr() {
+  local branch="$1"
+  local title="${2:-loop cycle ${branch#loop/}}"
+  if ! command -v gh >/dev/null 2>&1; then
+    _worktree_alert "_loop_publish_pr: gh not installed; cannot publish PR for ${branch}"
+    return 2
+  fi
+  local slug; slug=$(_gh_repo_slug 2>/dev/null) || slug=""
+  if [ -z "$slug" ]; then
+    _worktree_alert "_loop_publish_pr: origin remote is not a github repo; cannot publish PR for ${branch}"
+    return 2
+  fi
+  local _push_err
+  _push_err=$(git push origin "$branch" 2>&1) || {
+    _worktree_alert "_loop_publish_pr: push origin ${branch} failed: ${_push_err}"
+    return 1
+  }
+  local pr_url
+  pr_url=$(gh -R "$slug" pr view "$branch" --json url -q .url 2>/dev/null) || pr_url=""
+  if [ -z "$pr_url" ]; then
+    local body
+    body=$(printf 'Auto-opened by roll-loop cycle.\n\n- Branch: %s\n- TCR micro-commits: %s\n\nThis PR will auto-merge once required checks pass.' \
+      "$branch" "$(git rev-list --count origin/main.."$branch" 2>/dev/null || echo '?')")
+    pr_url=$(gh -R "$slug" pr create --base main --head "$branch" \
+      --title "$title" --body "$body" 2>/dev/null) || pr_url=""
+    if [ -z "$pr_url" ]; then
+      _worktree_alert "_loop_publish_pr: gh pr create failed for ${branch}"
+      return 1
+    fi
+  fi
+  gh -R "$slug" pr merge "$branch" --auto --squash --delete-branch >/dev/null 2>&1 \
+    || _worktree_alert "_loop_publish_pr: gh pr merge --auto failed for ${branch} (PR ${pr_url} left open)"
+  echo "$pr_url"
+  return 0
+}
+
+# _loop_is_doc_only_change
+#   Returns 0 if every file changed since origin/main is doc-only
+#   (BACKLOG.md, CHANGELOG.md, PROPOSALS.md, docs/, .claude/).
+#   Returns 1 if any code file changed or there are no changes.
+_loop_is_doc_only_change() {
+  local changed
+  changed=$(git diff --name-only origin/main HEAD 2>/dev/null) || return 1
+  [ -z "$changed" ] && return 1
+  echo "$changed" | grep -qvE '^(BACKLOG\.md|CHANGELOG\.md|PROPOSALS\.md|docs/|\.claude/)' && return 1
+  return 0
+}
+
+# _loop_publish_doc_pr <branch> [title]
+#   Like _loop_publish_pr but merges immediately with --admin (no CI wait).
+#   For doc-only changes where CI is not meaningful.
+_loop_publish_doc_pr() {
+  local branch="$1"
+  local title="${2:-doc update ${branch#loop/}}"
+  if ! command -v gh >/dev/null 2>&1; then
+    _worktree_alert "_loop_publish_doc_pr: gh not installed; cannot publish PR for ${branch}"
+    return 2
+  fi
+  local slug; slug=$(_gh_repo_slug 2>/dev/null) || slug=""
+  if [ -z "$slug" ]; then
+    _worktree_alert "_loop_publish_doc_pr: origin remote is not a github repo; cannot publish PR for ${branch}"
+    return 2
+  fi
+  if ! git push origin "$branch" --quiet 2>/dev/null; then
+    _worktree_alert "_loop_publish_doc_pr: push origin ${branch} failed"
+    return 1
+  fi
+  local pr_url
+  pr_url=$(gh -R "$slug" pr view "$branch" --json url -q .url 2>/dev/null) || pr_url=""
+  if [ -z "$pr_url" ]; then
+    local body
+    body=$(printf 'Doc-only update by roll-loop cycle.\n\n- Branch: %s\n- Files: BACKLOG / docs only\n\nMerging immediately — no CI gate needed for doc-only changes.' "$branch")
+    pr_url=$(gh -R "$slug" pr create --base main --head "$branch" \
+      --title "$title" --body "$body" 2>/dev/null) || pr_url=""
+    if [ -z "$pr_url" ]; then
+      _worktree_alert "_loop_publish_doc_pr: gh pr create failed for ${branch}"
+      return 1
+    fi
+  fi
+  if ! gh -R "$slug" pr merge "$branch" --admin --squash --delete-branch >/dev/null 2>&1; then
+    _worktree_alert "_loop_publish_doc_pr: gh pr merge --admin failed for ${branch} (PR ${pr_url} left open)"
+    echo "$pr_url"
+    return 1
+  fi
+  echo "$pr_url"
+  return 0
+}
+
 _loop_monitor() {
   local interval="${1:-3}"
   local project_path; project_path=$(pwd -P)
@@ -3807,8 +4120,20 @@ _dash_proposal_count() {
   grep '^## PROPOSAL' PROPOSALS.md 2>/dev/null | wc -l | tr -d ' '
 }
 
-# ⑤ Release-ready signal — true if latest brief contains 可发版 or "Release ready".
+# ⑤ Release-ready signal — true iff there are releasable commits since the
+# latest tag AND the latest brief signals 可发版/Release ready. Releasable =
+# any commit since the latest tag whose subject does NOT start with the
+# release-irrelevant prefixes `docs:` or `chore:`. Prevents the flag from
+# sticking on after a release when only docs rewrites land on top of the tag
+# (FIX-033 symptom 2).
 _dash_release_ready() {
+  local latest_tag
+  latest_tag=$(git describe --tags --abbrev=0 2>/dev/null) || return 1
+  local commits_with_code
+  commits_with_code=$(git log "${latest_tag}..HEAD" --pretty=format:%s 2>/dev/null \
+    | grep -cvE '^(docs|chore)(\([^)]*\))?:[[:space:]]' 2>/dev/null \
+    || echo 0)
+  [[ "${commits_with_code:-0}" -gt 0 ]] || return 1
   local latest
   latest=$(ls docs/briefs/*.md 2>/dev/null | sort | tail -1 || true)
   [[ -z "$latest" ]] && return 1
@@ -3988,7 +4313,7 @@ _dashboard() {
     printf "    ${GREEN}✓ AI 自驱中 — 无需介入${NC}\n"
   else
     (( alerts > 0 )) && printf "    ${RED}⚠ %s ALERT${NC}          run: roll alert\n" "$alerts"
-    (( proposals > 0 )) && printf "    ${YELLOW}📋 %s PROPOSAL${NC}      run: roll backlog\n" "$proposals"
+    (( proposals > 0 )) && printf "    ${YELLOW}📋 %s PROPOSAL${NC}      see: PROPOSALS.md\n" "$proposals"
     $release_ready && printf "    ${GREEN}✓ Release ready${NC}    run: roll release\n"
   fi
   echo ""

package/conventions/global/AGENTS.md

@@ -40,6 +40,12 @@
   - Before claiming completion: verify in the target environment mentioned by
     user (e.g., specific CLI tool, remote server, hardware platform).
 - **Workspace**: `BACKLOG.md` index. `docs/features/` for details.
+- **Backlog descriptions** (US, FIX, REFACTOR, IDEA, PROPOSAL): one sentence in plain language.
+  Say what changed and why it matters — not how it works internally.
+  No file paths, function names, parameter lists, or architecture jargon.
+  `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.
 - **Done**: Push + CI passes + deployed. Local-only is not done.
 - **Commit message format**:
   - Format: `<type>: <description>` (Git Hook may auto-prepend type prefix)

package/package.json

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

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

@@ -47,6 +47,14 @@ Create mode:
 
 CHANGELOG 是给**使用者**看的，不是给维护者看的。一句话讲清"用户能做什么 / 不再被什么坑"，能不写就不写。
 
+**BACKLOG 描述写好了，CHANGELOG 就是复制 + 过滤，不是重写。**
+如果 BACKLOG 描述已经是人话、一句话、说用户价值，直接用它（去掉 `depends-on:` / `manual-only:` 等功能性标签）。
+只有 BACKLOG 描述包含实现细节或技术黑话时，才需要改写。
+
+**FIX 条目的 filter 规则**：BACKLOG 的 FIX 描述通常是 `<用户症状> — <修复手段>` 结构。
+CHANGELOG 只取破折号前的用户症状，丢弃破折号后的修复手段。
+例：`roll update 后 loop 状态误报 off — reload 改用 bootout+bootstrap` → CHANGELOG 只写 `roll update 后 loop 状态不再误报 off`。
+
 **完全跳过（不写入 CHANGELOG）：**
 - 测试基建（teardown 清理、test isolation、bats helper、CI 时序）
 - prompt / SKILL.md 内部契约（schema 锁定、enum 强制、contract test）
@@ -62,9 +70,9 @@ CHANGELOG 是给**使用者**看的，不是给维护者看的。一句话讲清
 - 看得见的体验变化（布局、文案、速度、可见性）
 - 影响安装、升级、配置的改动
 
-**写法约束：**
+**写法约束（BACKLOG 描述不符合时才介入改写）：**
 
-1. **一行，30 字以内**。超了就是太啰嗦。
+1. **一行**。超了就是太啰嗦。
 2. **不写实现细节**：禁止文件路径、函数名、字段列表、命令参数、配置键名。
 3. **不写数字细节**："3 个服务"、"60+ ghost" 这种内部状态不写。
 4. **说人话**：避免 "幂等"、"trap"、"epoch" 等技术黑话；说"做两次效果一样"、"异常退出也会清理"、"启动时间"。
@@ -133,6 +141,94 @@ assigned.
 Do NOT read `package.json` version, do NOT call `git describe`, do NOT invent
 version numbers like `v2026.511.8`. Just write to `## Unreleased`.
 
+### 5.3 Style Anchors — In-Context Few-Shot
+
+Before drafting bullets, pull the most recent 3 published versions' bullets as
+in-context examples so the agent doesn't write from a blank slate (the blank
+slate is where the technical-jargon habit comes from — the agent is fresh
+from writing function names and just copies them over).
+
+```bash
+_changelog_style_anchors CHANGELOG.md
+```
+
+Output is the concatenated bullet lines from the last 3 `## v...` sections,
+capped at 1500 characters. Use them as a style reference when drafting — pay
+attention to length, voice ("不再被…坑" / "现在 …"), and absence of internal
+names.
+
+### 5.4 Mechanical Lint — Hard Gate
+
+After drafting bullets, run each through the mechanical linter. Any non-empty
+output means the bullet violates at least one blacklist rule and must be
+rewritten.
+
+```bash
+for bullet in "${draft_bullets[@]}"; do
+  violations=$(_changelog_lint_bullet "$bullet")
+  [ -n "$violations" ] && needs_rewrite+=("$bullet :: $violations")
+done
+```
+
+Violation tags emitted by `_changelog_lint_bullet`:
+
+| Tag | Trigger | Why it's noise to users |
+|---|---|---|
+| `backtick-identifier` | `…` contains `_` or `()` | Internal symbol names mean nothing to users |
+| `file-suffix` | `.md/.sh/.yml/.ts/.bats` outside backticks | File paths are maintainer concern |
+| `internal-word` | Phase N / Step N / Helper / Schema / Fixture / Refactor | Workflow/design vocabulary, not user-facing |
+| `over-length` | > 50 visible chars | Too long = probably explaining implementation |
+| `path-fragment` | `docs/` / `bin/` / `tests/` / `scripts/` outside backticks | Source-tree layout is maintainer concern |
+
+**Rewrite loop (max 2 rounds)**:
+1. Show the agent the violation list + original bullet → request rewrite
+2. Re-lint the rewrite
+3. If still violating after 2 rewrites → **keep the bullet but prefix `⚠️ `** so
+   the human reviewer can spot it, AND append a line to
+   `~/.shared/roll/loop/ALERT.md` describing what couldn't be fixed.
+   Never block the whole release on style — let the human take the wheel.
+
+### 5.5 Self-Audit — Stage Gate
+
+The mechanical linter in Step 5.4 catches **blacklist** patterns; the audit
+gate in this step is a **whitelist** of 5 boolean checks that the bullet must
+satisfy before it can be staged. Stricter (30-char cap vs 50) and shape-aware
+(requires the user-facing `—` or `不再`/`现在` sentence pattern).
+
+```bash
+accepted=$(_changelog_audit_gate "$draft1" "$rewrite1" "$rewrite2")
+# Exit 0: stdout = first clean candidate
+# Exit 1: stdout = ⚠️-prefixed last candidate; ALERT was written
+```
+
+5 boolean checks evaluated by `_changelog_audit_bullet`:
+
+| Tag | Trigger |
+|---|---|
+| `over-length-30` | visible chars > 30 (bypassed if bullet has a backticked user command) |
+| `internal-id` | backtick content contains `_` or `()` |
+| `path-or-suffix` | `.md/.sh/.yml/.ts/.bats` or `docs/bin/tests/scripts/` outside backticks |
+| `phase-step` | `Phase N` or `Step N` |
+| `bad-shape` | none of `—`, `不再`, `现在` present |
+
+**3-round retry envelope**:
+1. Round 1 = original draft; if pass → stage immediately
+2. Round 2 = rewrite based on violations from round 1
+3. Round 3 = second rewrite if round 2 also failed
+4. All 3 failed → keep last candidate prefixed with `⚠️ `, append ALERT to
+   `~/.shared/roll/loop/ALERT.md`. **Never block the stage** — let the human
+   reviewer take the wheel. The loop must keep moving.
+
+**Audit log**: every round (pass or fail) appends one JSONL line to
+`~/.shared/roll/loop/changelog-audit.jsonl`:
+
+```json
+{"ts":"2026-05-13T13:50:00Z","verdict":"fail","round":1,"bullet":"...","reasons":["over-length-30","bad-shape"]}
+```
+
+Useful when reviewing whether the agent actually iterated or just rubber-stamped
+its own first draft. Set `ROLL_CHANGELOG_AUDIT_LOG` to redirect (tests only).
+
 ### 5. Generate CHANGELOG.md
 
 **Create mode** (first time, no CHANGELOG.md yet):
@@ -190,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-.dream/SKILL.md

@@ -222,6 +222,8 @@ section of BACKLOG.md:
 | REFACTOR-XXX | {one-line description} — flagged by dream {YYYY-MM-DD} | 📋 Todo |
 ```
 
+`{one-line description}` 写法：一句人话说清楚"什么地方需要改"以及"不改会怎样"。不写函数名、文件路径、技术方案。例：`loop 状态读取逻辑分散在多处，修一处容易遗漏另一处`。
+
 **Threshold**: only flag items where the fix would meaningfully reduce
 complexity or prevent future bugs. Ignore cosmetic issues.
 

package/skills/roll-build/SKILL.md

@@ -284,9 +284,11 @@ When any signal appears, **do not stop — flag it**:
 **REFACTOR entry format in BACKLOG.md:**
 
 ```markdown
-| REFACTOR-001 | Extract payment boundary — leaking into Order module during US-AUTH-003 | 📋 Todo |
+| REFACTOR-001 | {one-line plain-language description} | 📋 Todo |
 ```
 
+描述写法：参见 AGENTS.md "Backlog descriptions" 规则。说清楚"什么需要改"以及"不改会怎样"，技术细节写在 `docs/features/refactor-log.md`。
+
 **refactor-log.md entry format:**
 
 ```markdown

package/skills/roll-design/SKILL.md

@@ -625,6 +625,8 @@ DOMAIN_DIR="docs/domain/"
 | [US-{DOMAIN}-{N}](docs/features/<feature>.md#us-{domain}-{n}) | {one-line description} | 📋 Todo |
 ```
 
+`{one-line description}` 写法：用户能读懂的一句话，说清楚"能做什么"或"解决了什么麻烦"。不写实现细节、文件路径、函数名。细节和 AC 写在 `docs/features/` 里。写好了可以直接当 CHANGELOG 条目用。
+
 Note: `{DOMAIN}` maps to the Bounded Context name identified in DDD analysis.
 
 **US section in docs/features/\<feature\>.md (full details):**

package/skills/roll-peer/SKILL.md

@@ -180,6 +180,33 @@ If serve mode is available, prefer HTTP transport over direct CLI invocation.
 
 **CLI vs. API Key**: `claude`, `deepseek`, `kimi`, `codex` CLIs authenticate via existing subscription accounts — no separate API key required. This is the primary advantage of CLI transport over the MCP/HTTP approach.
 
+## Inline Display Mode (Manual Triggers)
+
+When peer review is manually triggered by a human (via `/peer`, "叫上 peer", etc.), the executing agent **must display each round inline in the current conversation**. This applies regardless of which agent is executing — Claude, DeepSeek, Kimi, PI, or any other.
+
+**Per-round display format:**
+
+```
+─── Peer Review · Round N ───────────────────────────────
+→ Sending to [peer]:
+{full message sent to peer}
+
+← [peer] responds:
+{peer's full response, verbatim}
+
+◆ My analysis: {Claude/executing agent's reaction and position for this round}
+─────────────────────────────────────────────────────────
+```
+
+**Rules:**
+- Peer CLI calls must be **synchronous** (do NOT use background/async execution).
+- Show the outgoing message **before** calling the peer, so the user sees what's being asked.
+- Relay the peer's response **verbatim** before adding your own analysis.
+- If a peer call fails or times out, report it immediately inline and either retry or ESCALATE.
+- Negotiation log is still written to `~/.shared/roll/peer/logs/` as usual.
+
+**Why inline, not tmux:** When a human manually triggers peer review inside an agent's interactive session, the conversation IS the visible interface. tmux auto-attach is only relevant for CLI-launched background sessions (`bin/roll peer`), not for skill invocations.
+
 ## Workflow Integration
 
 ### `roll-build` Plan Mode

package/skills/roll-propose/SKILL.md

@@ -74,7 +74,11 @@ Generate between 1 and 3 proposals. For each:
 
 ```
 ## PROPOSAL: {Short title}
+```
+
+`{Short title}` 写法：用户看得懂的一句话，说清楚"加什么"或"解决什么问题"。不用技术术语，不提内部实现。这句话批准后会直接成为 BACKLOG 里的描述。
 
+```
 **Motivation (why):**
 One to two sentences from the user's perspective explaining the pain or opportunity.