@seanyao/roll 2026.519.2 → 2026.520.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (14) hide show
  1. package/CHANGELOG.md +39 -0
  2. package/README.md +40 -70
  3. package/bin/roll +639 -115
  4. package/conventions/global/AGENTS.md +3 -2
  5. package/lib/roll-backlog.py +1 -1
  6. package/lib/roll-help.py +1 -1
  7. package/lib/roll-peer.py +242 -0
  8. package/lib/roll_render.py +21 -0
  9. package/package.json +1 -1
  10. package/skills/roll-build/SKILL.md +2 -2
  11. package/skills/roll-loop/SKILL.md +21 -10
  12. package/lib/__pycache__/model_prices.cpython-314.pyc +0 -0
  13. package/lib/__pycache__/roll-loop-status.cpython-314.pyc +0 -0
  14. package/lib/__pycache__/roll_render.cpython-314.pyc +0 -0
package/CHANGELOG.md CHANGED
@@ -1,11 +1,50 @@
1
1
  # Changelog
2
2
 
3
+ ## v2026.520.1
4
+
5
+ ### Added
6
+
7
+ - **`roll offboard`** — 一键清掉项目里的 Roll 痕迹，先 dry-run 预览、二次确认才动手；命名空间对不上直接拒绝，绝不跨项目误删 `[legacy-onboard]`
8
+ - **`roll init` 现在认得出非典型布局的老项目** — 微信小程序、Python 平铺、Terraform 仓不再被当成空项目静默跳过引导 `[legacy-onboard]`
9
+ - **onboard / offboard 用户指南** — 完整接入与退出流程文档上线，遗留项目页"怎么退出"段从手动 rm 改为指向新命令 `[docs]`
10
+
11
+ ### Improved
12
+
13
+ - **公开 README 重写为给使用者看的** — 中英文 README 去掉自我推销语言，围绕安装 + 使用展开，新增贡献指南与漏洞报告说明 `[docs]`
14
+ - **markdown 改动不再绕过 CI** — 文档量减下来之后，关键文档改动现在和代码一样要过 CI `[ci]`
15
+ - **onboard 留下回退清单** — onboard 完事会记下动过哪些文件、在 AGENTS.md 哪段合并、加了哪些 launchd 调度，作为 offboard 的精准回退依据 `[legacy-onboard]`
16
+
17
+ ### Fixed
18
+
19
+ - **loop 跑过 45 分钟预算时不再卡死** — watchdog 现在能稳定收掉超时的 claude，下一轮按时启动 `[loop]`
20
+ - **loop worktree 里能看到主仓最新 backlog** — 每轮启动会先把主仓 `.roll/` 同步进 worktree，不再因为 meta 滞后让 loop 拿到旧待办 `[loop]`
21
+
22
+ ## v2026.519.3
23
+
24
+ ### Major
25
+
26
+ - **`.roll/` 拆为独立私有仓库** — 过程文件（backlog / brief / features / dream / domain / briefs）整体迁入嵌套私有 repo `roll-meta`，主仓只留产品文档。AGENTS.md 新增 §9 说明双 repo 协作约定 `[meta]`
27
+
28
+ ### Improved
29
+
30
+ - **`.roll/features/` 按 Epic 分组** — features 目录由扁平改为 Epic 子目录，附带 loop 架构经验文档 `[docs]`
31
+ - **站点登陆页对齐 v2.0 架构** — `docs/site/` 文案与 2.0 实际产物对齐，去掉过期描述 `[docs]`
32
+
33
+ ### Fixed
34
+
35
+ - **loop 异常退出** — dashboard 不再卡在"运行中"，崩溃 / 被 kill / 超时退出都会写下结束标记 `[loop]`
36
+ - **`FIX-065` loop 共享状态隔离** — 测试运行的 loop 不再污染生产 backlog/brief，sandbox 化共享路径 `[loop]`
37
+
3
38
  ## v2026.519.2
4
39
 
5
40
  ### Improved
6
41
 
7
42
  - **`roll init`** — 初始化流程现在显示 6 步编号进度，新建文件用绿色 `+`、合并已有用琥珀 `~`，结尾给三步上手指南 `[loop]`
8
43
 
44
+ ### Fixed
45
+
46
+ - **`roll --help` 中 `init` 描述** — 文案从 `+ docs/` 改为 `+ .roll/features/`，对齐 2.0 实际产物和 README；v2 (`lib/roll-help.py`) 与 legacy (`bin/roll`) 两份 help 同步修正 `[FIX-064]`
47
+
9
48
  ## v2026.519.1
10
49
 
11
50
  ### Major（大版本重构）
package/README.md CHANGED
@@ -7,8 +7,6 @@
7
7
  ╚═╝ ╚═╝ ╚═════╝ ╚══════╝╚══════╝
8
8
  ```
9
9
 
10
- > _Agents, roll out._
11
-
12
10
  **[中文版 README](README_CN.md)**
13
11
 
14
12
  [![Website](https://img.shields.io/badge/Website-seanyao.github.io%2Froll-blue)](https://seanyao.github.io/roll/)
@@ -16,57 +14,50 @@
16
14
  [![npm version](https://img.shields.io/npm/v/@seanyao/roll.svg)](https://www.npmjs.com/package/@seanyao/roll)
17
15
  [![CI](https://github.com/seanyao/roll/actions/workflows/ci.yml/badge.svg)](https://github.com/seanyao/roll/actions/workflows/ci.yml)
18
16
 
19
- ---
20
-
21
- ## What is Roll?
22
-
23
- Roll is an autonomous delivery system for software teams — AI agents pick stories from your BACKLOG, execute them with encoded engineering discipline, and ship continuously while you stay focused on what to build next.
24
-
25
- **Two core values:**
26
- 1. **Autonomous delivery** — `roll loop on` runs BACKLOG items hourly; Dream (nightly code-health scan) surfaces maintenance tasks; humans retain sole release authority
27
- 2. **Skill-driven execution** — 20+ skills encode TDD, TCR, and INVEST practices as reliable, repeatable workflows any agent can follow
28
-
29
- _Works with Claude, Cursor, Codex, or your own agent._
30
-
31
- ## What's New in 2.0 (May 2026)
32
-
33
- Roll 2.0 introduces a **process/product split** to keep open-source projects clean:
34
-
35
- - **`.roll/` directory convention** — all process artifacts (backlog, features, briefs, dream logs) move out of root into `.roll/`. User-facing `guide/` and `site/` move up to root. Old `docs/` directory disappears.
36
- - **`roll migrate`** — one-command migration for projects on pre-2.0 layout. `git mv` preserves history, single atomic commit, three-state idempotent.
37
- - **`$roll-onboard`** — interactive skill for adopting Roll on legacy codebases without rewrites. AI reads your code, asks 9 questions in ≤ 3 minutes, produces a plan; `roll init --apply` executes it.
38
- - **Three adoption patterns** — `seed` (new project), `graft` (legacy, non-invasive), `replant` (legacy, clean rebuild). See [guide/en/patterns/](guide/en/patterns/).
17
+ Roll — a CLI that lets AI agents pick up backlog items and ship them through your normal git + CI workflow. Works with Claude, Cursor, Codex, Kimi, and others.
39
18
 
40
- 📖 Upgrading from 1.x? Read [guide/en/migration-2.0.md](guide/en/migration-2.0.md).
41
- 📖 New legacy project? Read [guide/en/legacy-onboarding.md](guide/en/legacy-onboarding.md).
19
+ ## Install
42
20
 
43
- ## Evolution
44
-
45
- 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?*
46
-
47
- 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`.
48
-
49
- 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.
50
-
51
- The goal from here: full delivery, end to end — with humans on the loop, not in it.
21
+ ```bash
22
+ npm install -g @seanyao/roll
23
+ roll setup
24
+ ```
52
25
 
53
- ---
26
+ Requirements: bash 4+, Node.js 16+.
54
27
 
55
- ## Quick Start (30 seconds)
28
+ ## Use
56
29
 
57
30
  ```bash
58
- npm install -g @seanyao/roll
59
- roll setup # distribute conventions to all AI clients
60
- cd my-project
61
- roll init # create AGENTS.md + .roll/backlog.md + .roll/features/
62
- roll loop on # optional: let the agent work unattended
31
+ cd your-project
32
+ roll init # set up Roll here
33
+ roll loop on # let AI work through the backlog (optional)
63
34
  ```
64
35
 
65
- **Requirements:** bash 4+, Node.js 16+
36
+ `roll init` detects legacy code and routes you to `$roll-onboard` when appropriate.
66
37
 
67
- ---
38
+ ## Commands
68
39
 
69
- ## Documentation Index
40
+ | Command | Description |
41
+ |---------|-------------|
42
+ | **Autonomy · daily use** | |
43
+ | `roll loop <on\|off\|now\|status\|monitor>` | Manage the autonomous BACKLOG executor |
44
+ | `roll brief` | Show latest owner brief |
45
+ | `roll backlog [block\|defer\|lint\|…]` | View and manage pending tasks |
46
+ | `roll peer` | Cross-agent negotiation & review |
47
+ | `roll alert` | View / clear loop alerts |
48
+ | **Project · per repo** | |
49
+ | `roll init` | Set up Roll in this project |
50
+ | `roll status` | Show current state and drift |
51
+ | `roll agent [use <name>]` | Per-project agent selection |
52
+ | `roll ci [--wait]` | Show or wait for current commit's CI status |
53
+ | `roll release` | Run the release script (human-only) |
54
+ | `roll review-pr <number>` | AI-powered code review for a PR |
55
+ | **Machine · global** | |
56
+ | `roll setup [-f]` | First-time install or re-sync conventions to all AI clients |
57
+ | `roll update` | Upgrade to latest + re-sync |
58
+ | `roll version` | Print installed roll version |
59
+
60
+ ## Documentation
70
61
 
71
62
  | Topic | English | 中文 |
72
63
  |-------|---------|------|
@@ -78,42 +69,21 @@ roll loop on # optional: let the agent work unattended
78
69
  | Configuration (env vars) | [guide/en/configuration.md](guide/en/configuration.md) | [guide/zh/configuration.md](guide/zh/configuration.md) |
79
70
  | Skill selection guide | [guide/en/skills.md](guide/en/skills.md) | [guide/zh/skills.md](guide/zh/skills.md) |
80
71
  | FAQ (troubleshooting) | [guide/en/faq.md](guide/en/faq.md) | [guide/zh/faq.md](guide/zh/faq.md) |
81
- | Domain model (DDD) | [domain/context-map.md](.roll/domain/context-map.md) | — |
82
- | Engineering common sense | [practices/engineering-common-sense.md](guide/en/practices/engineering-common-sense.md) | — |
83
-
84
- ---
85
-
86
- ## Commands
87
-
88
- | Command | Description |
89
- |---------|-------------|
90
- | `roll setup [-f]` | First-time install or re-sync conventions to all AI clients |
91
- | `roll update` | Upgrade to latest version |
92
- | `roll init` | Initialize project: AGENTS.md + .roll/backlog.md + .roll/features/ |
93
- | `roll status` | Show sync state, skill links, detected AI tools |
94
- | `roll backlog` | Show pending tasks from .roll/backlog.md |
95
- | `roll loop <on\|off\|now\|status\|monitor>` | 🤖 Manage autonomous executor |
96
- | `roll brief` | 🤖 Show latest owner digest |
97
- | `roll peer` | 🤖 Cross-agent code review |
98
- | `roll release` | 🤖 Version + tag + npm publish + GitHub Release |
99
-
100
- ---
72
+ | Adoption patterns | [guide/en/patterns/](guide/en/patterns/) | [guide/zh/patterns/](guide/zh/patterns/) |
101
73
 
102
74
  ## Contributing
103
75
 
104
- PRs welcome. Keep them focused on one thing. For larger changes, open an issue first.
76
+ See [CONTRIBUTING.md](CONTRIBUTING.md) for the development workflow, test setup, and PR conventions.
105
77
 
106
- 1. `git clone https://github.com/seanyao/roll.git && cd roll && ./install.sh`
107
- 2. Make changes with bats tests (`tests/`)
108
- 3. Run `npm test` before pushing
78
+ ## Security
109
79
 
110
- ---
80
+ See [SECURITY.md](SECURITY.md). Please report vulnerabilities privately, not through public issues.
111
81
 
112
82
  ## Acknowledgments
113
83
 
114
84
  - **[khazix-skills](https://github.com/KKKKhazix/khazix-skills)** by Digital Life Khazix — HV Analysis framework used by `$roll-research`, MIT License.
115
85
  - **[superpowers](https://github.com/obra/superpowers)** by Jesse Vincent — composable skills library that inspired several Roll workflow patterns.
116
86
 
117
- ---
87
+ ## License
118
88
 
119
- MIT License
89
+ [MIT](LICENSE)