@seanyao/roll 2026.514.1 → 2026.514.2

package/CHANGELOG.md

@@ -1,136 +1,128 @@
 # 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.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 里，结束自动合回 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

@@ -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.514.1"
+VERSION="2026.514.2"
 ROLL_HOME="${ROLL_HOME:-${HOME}/.roll}"
 ROLL_CONFIG="${ROLL_HOME}/config.yaml"
 ROLL_GLOBAL="${ROLL_HOME}/conventions/global"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seanyao/roll",
-  "version": "2026.514.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

@@ -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**` 前缀，分组标题已经承担了语义分类的职责。