@seanyao/roll 2026.511.7 → 2026.511.8

package/CHANGELOG.md

@@ -1,52 +1,42 @@
 # Changelog
 
-## v2026.511.11
-- **Added**: loop 默认 auto-attach 弹窗 — 每次 loop 触发时，runner script 自动通过 osascript 开一个背景 Terminal 窗口 `tmux attach -t roll-loop-<slug>`，看 claude 实时打字干活；弹窗用 `delay 0.3` + 还原前一个 frontmost app 做到不抢焦点，tmux session 结束窗口保留供回看，关掉窗口 loop 仍在 tmux 里继续跑。
-- **Added**: `roll loop mute` / `roll loop unmute` 一键开关 — 不想看弹窗时 `roll loop mute` 创建 `~/.shared/roll/mute` 标记文件即刻静音，`unmute` 删掉它恢复；mute 状态对所有项目生效（一个开关治整机），`roll loop status` 新增 `Auto-attach  live | muted` 一行实时显示。
-- **Added**: tmux 升级为 `roll setup` 必装依赖 — 新增 `_ensure_tmux` helper：macOS 自动 `brew install tmux`（无 brew 给手动命令），Linux/其他系统打印对应包管理器安装指引；任何失败路径都返回 0，不阻塞 setup 主流程。
-- **Fixed**: launchd runner 缺 brew PATH 导致 hook 子进程报 `node: command not found` — launchd 默认 PATH 不含 `/opt/homebrew/bin`，claude 通过 `sh -c` 调 SessionEnd hook 时找不到 node；inner runner 模板显式 `export PATH="/opt/homebrew/bin:$PATH"` 让整条 fork 链都能拿到 brew 工具。
-- **Fixed**: runs.jsonl schema 漂移 — 早期 claude 在 status/ts/alerts/project 字段自由发挥（`built` vs `success` vs `noop`、UTC vs `+08:00`、number vs array、全路径 vs slug）。SKILL Step 5 改为"严格契约"：ts 强制 UTC Z 后缀、project 用 slug、alerts/built/skipped 永远是数组、status 限定 `built/idle/failed` 三个 enum 无同义词；contract test 锁死关键不变量留在 prompt 里。
-
-## v2026.511.9
-- **Added**: `roll loop runs` 每次 loop 运行的快速可见性 — 单次 loop 结束追加一行 JSON 到 `~/.shared/roll/loop/runs.jsonl`（含 ts/project/run_id/status/built/skipped/alerts/tcr_count/duration_sec），新命令 `roll loop runs [N] [--all]` 倒序显示最近 N 次（默认 10），不必等次日早报就能查到中间 13 次 loop 各干了啥。
-- **Added**: loop 跑在 tmux session + `roll loop attach` 实时观看 — runner script 自动把 claude 包进 detached tmux session `roll-loop-<slug>`，输出同时 pipe 到 `cron.log`；执行 `roll loop attach` 可随时 attach 上去看它打字、写文件、commit，Ctrl-B D 分离后 loop 继续跑；未装 tmux 时自动 fallback 到原 headless 模式，零依赖回退。
-- **Improved**: roll-.dream 日志改为中文输出 — Dream Log 输出模板（概要 / 死代码 / 架构漂移 / 裁剪候选 / 新兴模式 / 创建的 REFACTOR 条目）和"未发现 / 部分完成"等固定文案全部中文化，与 roll-brief 风格对齐，晨间扫一眼不再需要在中英文之间切换语境。
-
-## v2026.511.8
-- **Fixed**: 集成测试 launchd ghost 泄漏 — `integration_teardown` 在删除 TEST_TMP 之前，先 `launchctl bootout` 该沙箱里被 `roll loop on` 注册到 user gui domain 的所有 `com.roll.*` 服务，避免删 plist 后 launchd 仍保留指向不存在路径的 ghost 注册。
+## Unreleased
+- **Fixed**: `roll loop attach` 不再黑屏，AI 干活过程实时可见
 
 ## v2026.511.7
-- **Added**: loop 执行 story 前显式标记 🔨 In Progress — roll-loop SKILL 在调用 executor 之前先把 BACKLOG 中的故事状态从 📋 Todo 改为 🔨 In Progress 并提交 `chore: mark US-XXX in progress`，brief 简报和 peer agent 都能即时感知正在进行的工作，tcr 微提交不再"对 brief 不可见"。
-- **Added**: loop 启动时孤儿 🔨 自愈 — 扫描 BACKLOG 中无对应 state.yaml running item 的 🔨 条目，视为上次崩溃残留，自动 revert 回 📋 Todo 并写 ALERT，避免被"卡"在错误的中间状态里。
-- **Improved**: roll-build / roll-fix SKILL 状态转换段更新 — 显式接受 📋 Todo 或 🔨 In Progress 作为 ✅ Done 前置状态，loop 触发链路状态过渡更稳健。
+- **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
-- **Added**: Loop 并发安全 — runner script 启动时写入 per-project LOCK 文件并检测重入；活跃 PID 已存在则跳过本次，残留死 LOCK 自动清理；正常/异常退出均通过 trap 清掉 LOCK。彻底防止两个 loop 实例同时启动造成的 BACKLOG/git 冲突。
-- **Added**: roll-loop SKILL 显式声明 skip-🔨 In Progress 语义 — claude 扫 BACKLOG 时跳过已被人工或 peer agent 标记的执行中条目，为人机协同和多 agent 协作奠定基础。
-- **Fixed**: 5 个 pre-existing 测试失败 — `run_roll` helper 切换到 TEST_TMP 作为 cwd 避免 slug 冲突；loop status 测试匹配三态显示新文案；dashboard 测试匹配 `_launchd_svc_state` + array 派生 schedule 的新结构。
+- **Fixed**: 多个 loop 实例不会再因为定时重复触发而互相打架
 
 ## v2026.511.5
-- **Fixed**: launchd plist 自动 reload — plist 内容变更且服务已加载时自动 unload + reload，升级 roll 后 loop 服务立即生效，无需手动重启
-- **Improved**: roll loop status/monitor 三态展示 — 区分 ● 运行中 / ⚠ 已安装未加载 / ○ 未安装，并给出对应的自愈操作提示
+- **Fixed**: 升级 roll 后 loop 服务自动生效，无需手动重启
+- **Improved**: `roll loop status` 三态显示，看得清是真没装、装了没启、还是在跑
 
 ## v2026.511.4
-- **Fixed**: roll init 自动重建 launchd runner scripts — 升级 roll 后直接跑 `roll init` 即可迁移到独立 runner，无需手动执行 roll setup 或 roll loop on
+- **Fixed**: 升级 roll 后 `roll init` 自动迁移 loop 配置，少一步手动操作
 
 ## v2026.511.3
-- **Fixed**: loop/dream/brief 多项目运行隔离 — 共享 run.sh 导致所有项目的 loop 在同一目录执行，改为每个项目独立 runner 脚本（run-{slug}.sh），彻底隔离多项目并发执行环境
-- **Fixed**: roll release 自发版拦截 — 在 roll 自身项目执行 `roll release` 时自动拦截并提示改用 scripts/release.sh，防止误操作绕过 2FA
+- **Fixed**: 多个项目同时跑 loop，互不干扰
+- **Fixed**: 在 roll 项目里运行 `roll release` 会提示改用 `scripts/release.sh`
 
 ## v2026.511.2
-- **Added**: roll loop monitor 三服务状态 — 监控台新增 loop/dream/brief 三个 launchd 服务的运行状态、调度时间和实时 log tail，一屏掌握全局执行情况
-- **Fixed**: dashboard 多处展示问题 — 修复 pending_count 算术错误、brief 内联显示 release readiness、移除底部冗余命令列表
-- **Fixed**: loop 异常退出后 state 未重置 — 防止 queue 卡住导致后续任务无法执行
-- **Fixed**: CI 稳定性 — 修复 _notify_update 裸返回和时间断言，消除环境差异引起的随机失败
-- **Improved**: roll-brief 输出格式 — 序号命名、省略空 section、元信息格式精简，减少无效噪音
+- **Added**: `roll loop monitor` — 一屏看 loop/dream/brief 三个调度服务状态
+- **Fixed**: dashboard 待办数、release 状态显示问题
+- **Fixed**: loop 异常退出后队列卡住不再继续执行
+- **Improved**: 简报输出更精简，去掉空白段落和冗余信息
 
 ## v2026.511.1
-- **Changed**: roll loop 调度器切换到 launchd（macOS）— `roll setup` 自动安装 loop/dream/brief 三个 launchd 服务（默认关闭），`roll loop on/off/status` 统一走 launchctl 管理，幂等安装，Linux 保留 crontab 回退路径
-- **Added**: roll-loop TCR 硬校验 — 故事完成后自动统计 `tcr:` 微提交数量，为 0 时将故事状态回退为 📋 Todo 并写 ALERT，防止 agent 跳过 TCR 节奏
-- **Fixed**: CI 测试环境兼容 — 移除依赖本地 state.yaml 的 hello_world.bats，修复 GitHub Actions 持续失败
+- **Changed**: macOS 上 loop 调度切换到 launchd，比 crontab 更稳定
+- **Added**: agent 跳过 TCR 节奏时自动拦回 Todo，强制重做
 
 ## v2026.510.10
 - **Fixed**: release.sh changelog 同步时序修复 — 修正条件逻辑和执行顺序，确保每次发版时 changelog 正确更新

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.511.7"
+VERSION="2026.511.8"
 ROLL_HOME="${ROLL_HOME:-${HOME}/.roll}"
 ROLL_CONFIG="${ROLL_HOME}/config.yaml"
 ROLL_GLOBAL="${ROLL_HOME}/conventions/global"
@@ -1891,10 +1891,14 @@ _write_loop_runner_script() {
   mkdir -p "$(dirname "$script_path")"
 
   local inner_path="${script_path%.sh}-inner.sh"
+  # Inject --verbose into `claude -p` so the tmux-attach view shows live
+  # tool-use and reasoning events (loop is launchd-triggered, the user is
+  # not driving it — visibility is required, not optional).
+  local cmd_verbose="${cmd/claude -p/claude --verbose -p}"
   cat > "$inner_path" << INNER
 #!/bin/bash -l
 export PATH="/opt/homebrew/bin:\$PATH"
-cd "${project_path}" && ${cmd}
+cd "${project_path}" && ${cmd_verbose}
 INNER
   chmod +x "$inner_path"
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seanyao/roll",
-  "version": "2026.511.7",
+  "version": "2026.511.8",
   "description": "Roll — Roll out features with AI agents",
   "scripts": {
     "test": "find tests/unit tests/integration -name '*.bats' | sort | xargs ./tests/helpers/bats-core/bin/bats"

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

@@ -45,83 +45,112 @@ Create mode:
 
 ### 3. Filter for External Content
 
-**Remove internal information:**
-- Progress tables, completion percentages
-- "As a / I can / So that" format
-- Detailed AC checklists
-- Technical debt, internal file paths
-- Test case counts, architecture diagrams
+CHANGELOG 是给**使用者**看的，不是给维护者看的。一句话讲清"用户能做什么 / 不再被什么坑"，能不写就不写。
 
-**Keep user-facing value:**
-- New features (one-sentence description)
-- Bug fixes (user-visible impact)
-- UX improvements (layout, interaction enhancements)
-- Performance/reliability improvements
+**完全跳过（不写入 CHANGELOG）：**
+- 测试基建（teardown 清理、test isolation、bats helper、CI 时序）
+- prompt / SKILL.md 内部契约（schema 锁定、enum 强制、contract test）
+- 内部重构（提取函数、变量改名、目录调整）
+- 只有开发者会遇到的 bug（release.sh 自身逻辑、TCR 节奏调整）
+- 任何"用户体验不变"的改动
 
-**语言：中文。** 所有 changelog 条目必须用中文撰写。
+判断准则：**如果用户读了这条记录，他不会改变使用方式，就别写。**
 
-**Description format:** `功能名 — 做了什么 + 用在什么场景`，一句话，精简。
+**保留：**
+- 用户能直接调用的新功能 / 新命令
+- 用户实际遇到过的 bug 修复
+- 看得见的体验变化（布局、文案、速度、可见性）
+- 影响安装、升级、配置的改动
 
-Good:
+**写法约束：**
+
+1. **一行，30 字以内**。超了就是太啰嗦。
+2. **不写实现细节**：禁止文件路径、函数名、字段列表、命令参数、配置键名。
+3. **不写数字细节**："3 个服务"、"60+ ghost" 这种内部状态不写。
+4. **说人话**：避免 "幂等"、"trap"、"epoch" 等技术黑话；说"做两次效果一样"、"异常退出也会清理"、"启动时间"。
+5. **句式**：`功能名 — 用户能做什么 / 解决了什么麻烦`。
+
+**语言：中文。**
+
+具体对比（都是真实的 roll 改动）：
+
+❌ 全是实现细节：
 ```
-- **Added**: roll-jot — 一句话快速记录 bug 或想法到 backlog，不打断当前工作
-- **Fixed**: 同步时清理已删除文件，防止用户机器残留幽灵文件
+- **Added**: `roll loop runs` 每次 loop 运行的快速可见性 — 单次 loop 结束追加一行 JSON 到 `~/.shared/roll/loop/runs.jsonl`（含 ts/project/run_id/status/built/skipped/alerts/tcr_count/duration_sec），新命令 `roll loop runs [N] [--all]` 倒序显示最近 N 次（默认 10）。
 ```
 
-Bad:
+✅ 讲价值：
 ```
-- **Added**: Add roll-jot skill for fast backlog capture
-- **Fixed**: Sync prunes stale files to prevent ghost files
+- **Added**: `roll loop runs` — 随时查看 loop 最近几次都跑了什么
 ```
 
-### 4. Version Number Format
+❌ 内部信息扎堆：
+```
+- **Fixed**: 集成测试 launchd ghost 泄漏 — `integration_teardown` 在删除 TEST_TMP 之前，先 `launchctl bootout` 该沙箱里被 `roll loop on` 注册到 user gui domain 的所有 `com.roll.*` 服务。
+```
 
-Determine the current version being released:
+✅ **直接跳过**：测试基建修复，用户感知不到。
 
-```bash
-VERSION=$(node -e "process.stdout.write(require('./package.json').version)" 2>/dev/null \
-  || git describe --tags --abbrev=0 2>/dev/null | sed 's/^v//')
+❌ 参数列表+黑话：
+```
+- **Added**: Loop 并发安全 — runner script 启动时写入 per-project LOCK 文件并检测重入；活跃 PID 已存在则跳过本次，残留死 LOCK 自动清理；正常/异常退出均通过 trap 清掉 LOCK。
 ```
 
-`package.json` is the authoritative source — it is updated before this skill runs. Fall back to git tags only if `package.json` is unavailable.
+✅ 用户视角：
+```
+- **Fixed**: 多个 loop 实例不会再互相打架（重复触发自动跳过）
+```
 
-The CHANGELOG section header uses the full version string with a `v` prefix:
+### 4. Section Header — Always `## Unreleased`
+
+**⚠️ do NOT guess version numbers.** Only `scripts/release.sh` assigns concrete
+versions, and it only does so at the moment of a real release. Until then,
+every new bullet goes under `## Unreleased` at the top of CHANGELOG.md.
 
 ```
-## v${VERSION}
+## Unreleased
+- **Added**: ...new entries here...
+- **Fixed**: ...
 ```
 
-For the human-readable date display within entries, use `YYYY.MM.DD` format.
+When `release.sh` runs, it renames `## Unreleased` to `## v{N}` (where N is
+computed from git tags) — that's the single moment a version label gets
+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. Generate CHANGELOG.md
 
-**Create mode** (first time):
+**Create mode** (first time, no CHANGELOG.md yet):
 ```markdown
 # Changelog
 
+## Unreleased
+- **Added**: ...current deploy's entries...
+
 ## 2026.05.10
-- **Added**: E2E 自动沉淀 — 每个 Story 交付时自动写一个端到端测试，项目逐步积累可回放的 E2E 套件
-- **Fixed**: 同步时清理已删除文件，防止用户机器残留幽灵文件
+- **Added**: ...historical entries from completed Stories before today...
+```
 
-## 2026.05.04
-- **Added**: BB 注入模式 — 对未集成 Black Box 的页面自动注入诊断探针，统一数据采集接口
+**Append mode** (most common — CHANGELOG.md exists):
 
-## 2026.04.28
-- ...
-```
+1. Find `## Unreleased` heading at the top of CHANGELOG.md.
+2. If it exists → append new bullets under it (do NOT create a new section).
+3. If it doesn't exist → insert a fresh `## Unreleased` at the very top (right after the `# Changelog` title) with the new bullets.
 
-**Append mode** (subsequent):
 ```markdown
 # Changelog
 
-## 2026.05.10    ← 新条目插入顶部
-- **Added**: Changelog 自动生成 — 每次部署后自动更新，首次运行时回填全部历史记录
+## Unreleased
+- **Added**: ...just-deployed entry appended here...
+- **Fixed**: ...another just-deployed entry...
 
-## 2026.05.04    ← 已有条目不动
+## v2026.05.07      ← previous releases left untouched
 - ...
 ```
 
-**Ordering**: Most recent version first (reverse chronological)
+**Ordering**: Unreleased always at top. Below it, released versions in reverse chronological order.
 
 ### 6. Commit Update