@seanyao/roll 4.630.2 → 4.702.2

package/guide/zh/migration-2.0.md

@@ -0,0 +1,154 @@
+# 迁移到 Roll 2.0
+
+> **TL;DR:** 跑 `npx @seanyao/roll@2 migrate --dry-run` 预览，确认后 `npx @seanyao/roll@2 migrate`。单个原子 commit。完事。
+
+Roll 2.0 把所有"过程"产物（BACKLOG、PROPOSALS、feature 规格、briefs、dream 日志、设计文档）从项目根级和 `docs/` 搬进统一的 `.roll/` 目录。用户可见文档（`docs/guide/`、`docs/site/`）上移到项目根级。
+
+这是一次性破坏性变更。文件的 git 历史会保留——Roll 用 `git mv`。
+
+## 开工前
+
+- **想留后路就 pin 老版本**：`npm install -g @seanyao/roll@1`。npm 历史版本永远在，随时可以回滚。
+- **工作区必须干净**：`npx @seanyao/roll@2 migrate` 不接受未提交改动，先 commit 或 stash。
+- **建议把整页读完再开始。**
+
+## 迁移内容
+
+| 老路径 | 新路径 | 说明 |
+|--------|--------|------|
+| `BACKLOG.md`（根级） | `.roll/backlog.md` | 主项目工作流文件 |
+| `PROPOSALS.md`（根级） | `.roll/proposals.md` | 待审批提案 |
+| `docs/features.md` | `.roll/features.md` | 功能索引 |
+| `docs/features/` | `.roll/features/` | 各 feature 详细规格 |
+| `docs/briefs/` | `.roll/briefs/` | `roll-brief` 自动产出 |
+| `docs/dream/` | `.roll/dream/` | `roll-.dream` 自动产出 |
+| `docs/design/` | `.roll/design/` | 设计探索文档 |
+| `docs/domain/` | `.roll/domain/` | DDD 模型 |
+| `docs/practices/loop-autorun-verification.md` | `.roll/features/loop-engine/loop-autorun-verification.md` | 执行验证记录 |
+| `docs/practices/engineering-common-sense.md` | `guide/en/practices/engineering-common-sense.md` | 工程规范（对外） |
+| `docs/intro/` | `site/slides/` | 宣传 HTML 页面 |
+| `docs/guide/en/` | `guide/en/` | 用户文档（英文） |
+| `docs/guide/zh/` | `guide/zh/` | 用户文档（中文） |
+| `docs/site/` | `site/` | 网站源码 |
+
+迁移完成后 `docs/` 目录消失。如果你的 `docs/` 里有自己的文件不在上述列表中，`npx @seanyao/roll@2 migrate` 不会动它们。
+
+## 为什么是两个目的地
+
+Roll 2.0 强制做了架构分离：
+
+- **`.roll/`** = 过程产物，给*我们自己*（维护者）。backlog、dream 日志、设计笔记。
+- **根级** = 产品产物，给*别人*。README、guide、site、源码。
+
+`.roll/` 要不要 gitignore 是你的选择（见下方[隐私](#隐私)）。是否 track 跟方向性分类是正交的。
+
+## 三态幂等
+
+`npx @seanyao/roll@2 migrate` 是幂等的，遇到危险就拒绝执行：
+
+| 状态 | 行为 |
+|------|------|
+| 仅老路径 | 执行迁移（单 commit） |
+| 仅 `.roll/`，无老路径 | no-op，输出"已迁移" |
+| 两者并存 | **拒绝** —— 列冲突，要求手动解决 |
+| 都没有 | no-op |
+
+如果中途停了，部分状态会落入"两者并存"，下次运行会给清晰的冲突报告。
+
+## 分步操作
+
+### 1. 升级到 2.0
+
+```bash
+npm install -g @seanyao/roll@2
+npx @seanyao/roll@2 version    # 应该显示 2.x
+```
+
+### 2. 预览迁移
+
+```bash
+cd your-project
+npx @seanyao/roll@2 migrate --dry-run
+```
+
+打印每条迁移的对照表，文件不会动。
+
+### 3. 执行
+
+```bash
+npx @seanyao/roll@2 migrate
+```
+
+会在当前分支看到一个 commit：
+
+```
+Migrate project layout to .roll/ structure
+
+Paths migrated: 14
+```
+
+`git log --follow .roll/backlog.md` 应该还能看到从 `BACKLOG.md` 一路下来的完整历史。
+
+### 4. 验证
+
+```bash
+roll status          # 应该正常跑
+ls -la .roll/        # 看新结构
+git log -1           # 迁移 commit
+```
+
+发现异常 → `git revert HEAD` 撤回。
+
+## 隐私
+
+默认情况下 `.roll/` 是**被 track 的**（仓库可见者都能看）。如果想把过程产物私有：
+
+```bash
+echo ".roll/" >> .gitignore
+git add .gitignore && git commit -m "chore: gitignore .roll/"
+```
+
+如果已经被 commit 进 git，再取消 tracking：
+
+```bash
+git rm -r --cached .roll/
+git commit -m "chore: stop tracking .roll/"
+```
+
+Roll 自己用的是另一种方式——**独立 private repo**（`seanyao/roll-meta`），不靠 gitignore 隔离。只有需要彻底分开访问权限时才需要这种模式。
+
+## 回滚
+
+需要撤销时：
+
+```bash
+git revert HEAD                          # 撤回迁移 commit
+npm install -g @seanyao/roll@1           # 重装老版本
+```
+
+文件历史在两种情况下都保留（`git mv` 不丢 blame）。
+
+## 其他工具的影响
+
+迁移后：
+
+- `roll status`、`roll backlog`、`roll loop`、`roll brief` —— 自动用新路径
+- `$roll-build`、`$roll-fix`、`$roll-design` 等 skill —— 已更新，重跑 `roll setup` 刷新
+- 外部脚本引用了 `BACKLOG.md` 等 —— **需要你手动改**
+
+## FAQ
+
+**Q: 能不能分次迁移？**
+不能。迁移是原子的——单 commit。"并存"状态会刻意报错，所以不会陷入半迁移状态。
+
+**Q: CI / GitHub Actions 里还引用老路径怎么办？**
+跟迁移在同一时间窗口内更新。迁移后 CI 红，99% 是 workflow 文件里的老路径引用没改。
+
+**Q: 我们团队多个项目都用 Roll，要不要全部迁移？**
+独立处理。Roll 2.0 遇到老结构会拒绝运行，提示 `npx @seanyao/roll@2 migrate`，不会静默出错。
+
+**Q: 能不能不迁移，一直用 Roll 1.x？**
+可以。npm 历史版本永远在。但新特性（已有代码库接入、agent 发现、plan 驱动 init）就用不到。
+
+**Q: 迁移后 `npm test` 大量失败，是预期吗？**
+不是。迁移不应该改变测试结果。如果失败，跑 `git diff HEAD~1` 看哪些文件移动了，找 workflow / test fixture 里漏改的路径。提 issue 附 diff。

package/guide/zh/overview.md

@@ -0,0 +1,186 @@
+# Roll — 概述
+
+Roll 是 Supervisor-led 的交付 harness。把目标写下来，让 Roll 拆成 Story，并把每张 Story 路由进 scoped `supervise`、`execute`、`evaluate` 角色。
+
+## 快速开始
+
+```bash
+curl -fsSL https://seanyao.github.io/roll/install | bash
+
+cd my-project
+roll setup && roll init
+
+roll next           # 接续 design/apply/repair/migrate/loop/status
+roll loop on        # AI 按可配置频次执行 BACKLOG
+roll loop status    # 查看调度状态和最近 cycle
+roll loop watch     # 可选：CLI-first 实时旁观当前 cycle
+```
+
+## 工作原理
+
+Roll 以 V4 Supervisor 执行系统运行：
+
+- **Supervisor** —— 项目级 observe/advise 角色。它读取 backlog、merge truth、open PR、scoped role bindings、重复失败、发布就绪和 owner 问题。它协调跨 Story 工作；不实现具体 Story，也不覆盖证据闸。
+- **Delta Unit** —— 一张 Story 在需要时先由 `design` 产出 Designer contract，再通过 `execute` 交付，并在配置后由 `evaluate` 评审。
+- **角色与绑定** —— `supervise`、`design`、`execute`、`evaluate` 是稳定角色；具体 agent 和可选 model 由 `Scope -> Role -> Binding -> Agent -> Model` 解析。请求的绑定不可用时，Roll 记录并 fail loud，不冒充成另一个 agent。
+- **Loop** —— 按可配置频次从 BACKLOG 摘取最高优先级故事，在隔离 worktree 里执行。CI 通过后才会落到 `main`。
+- **Dream** — 凌晨 3 点扫描代码库，发现死代码、文档缺口和架构漂移，将 `REFACTOR-NNN` 条目排队交给 loop 领取。
+- **Skills** —— 仍然是能力层。角色调用 `$roll-design`、`$roll-build`、`$roll-fix`、`$roll-peer`、`$roll-.qa` 等技能。
+
+你负责提需求、审 PR、执行发布。中间的一切交给 Roll。
+
+## 运行模式
+
+Roll 有两个模式，它们共用同一套 backlog、路由剖面、证据、Evaluator 和发布闸。
+`guided` 表示 owner 通过 `roll supervisor status/next/why` 理解状态，并显式启动工作，通常是
+`roll loop go --cards <id>`。`autonomous` 表示 `roll loop on` 已安装 scheduler，合格 Todo
+可以在既有闸内被调度。`roll loop pause` / `roll loop off` 回到 guided；`roll loop resume` /
+`roll loop on` 显式切回 autonomous。
+
+### 接入样例
+
+**从零开始的新项目**
+
+```bash
+mkdir my-product && cd my-product
+roll init
+roll next
+roll design --from-file .roll/brief.md
+roll loop on
+```
+
+从一句需求、PRD 或几条笔记开始。Roll 说明下一步设计动作，而不是静默创建假工作；Designer 创建 backlog，Supervisor 为每张 Story 选择 `standard`、`verified` 或 `designed` 执行剖面，owner 查看按 Story 收口的 attest 证据。
+
+**已有项目接入**
+
+```bash
+cd existing-codebase
+roll init
+roll next
+roll init --apply
+roll loop on
+```
+
+Roll 无破坏地诊断现有代码，审阅后才创建或更新 Roll metadata，然后基于已有 backlog/docs/context 推理。当前状态通过 CLI-first 可观测入口查看：`roll status`、`roll loop watch`、`roll loop runs`、`roll loop cycle <id>`、告警和 Story 报告。
+
+**按 Scope 路由角色**
+
+```yaml
+schema: roll-agents/v1
+defaults:
+  story:
+    roles:
+      execute:
+        candidates: [kimi, codex]
+      evaluate:
+        candidates: [pi, reasonix]
+```
+
+运行时可用性必须显式记录：不可用 agent 记录为 unavailable；角色解析必须 fail-loud，不能静默替换。
+
+## 功能一览
+
+### 自主执行
+
+- `roll loop on` — AI 从 BACKLOG 领取故事，按可配置频次在隔离 worktree 里执行 `[core]`
+- `roll loop status` — 查看调度、最近 cycle、队列、告警和成本 `[core]`
+- `roll loop watch` — 默认只读实时状态；排查事件用 `--events`，审计/底层排障才用 `--raw-events` `[highlight]`
+- `roll loop pause / resume` — 手动编码时暂停，完成后让 AI 继续
+
+### 质量门禁
+
+- Peer 评审 — 第二个 AI agent 在高风险构建前挑战方案或 diff `[core]` `[highlight]`
+- 自检 — 每次微提交后自动做 post-commit 检查
+- 验收检查 — 每次构建后对照故事定义逐条核实 AC
+- CI 门禁 — loop 等待 CI 绿；CI 红则停止循环并写入告警 `[core]`
+- TCR 纪律 — 测试不过不提交；空 diff 提交自动回滚 `[core]`
+
+### 夜间巡检
+
+- 代码健康扫描 — 检测死代码、架构漂移、过度工程候选项 `[highlight]`
+- 文档覆盖率 — 标记缺失指南、过时文档、未记录的 ENV 变量
+- REFACTOR 队列 — 将 REFACTOR-NNN 条目写入 BACKLOG，次日早晨由 loop 领取
+
+### 故事生命周期
+
+- `$roll-idea` — 一行捕获：即时生成 FIX 或 IDEA 条目 `[core]`
+- `roll design` / `$roll-design` — DDD 驱动规划：澄清 → 设计 → 拆分为 INVEST 故事。`roll design` 从命令行在你的 AI agent 里拉起设计技能，并把详细设计渲染成自包含 Design Review Page。`[core]`
+- `$roll-build` — Builder 角色执行：TCR 故事执行 → worktree → PR → 证据 `[core]`
+- `$roll-fix` — 快速路径 Bug 修复，同样的 CI 门禁，更轻的流程
+- Evaluator 角色 —— 执行剖面需要时，做独立评审、可视证据检查、score/attest 契约
+
+### 可观测性
+
+- `roll status` — 判定优先的真相摘要（LOOP · CYCLE · RELEASE · STORY，含 attest 验收覆盖率），其后是约定/AI 客户端同步健康 `[core]`
+- `roll loop watch` — 当前 cycle 的 CLI-first 实时 activity 流
+- `roll loop cycle <id>` — 单个 cycle 的轨迹与证据指针
+- `roll loop runs` — 每轮 TerminalOutcome 历史，含 TCR 次数和耗时
+- `roll loop alert` — 查看、确认、清除 loop 告警
+- 验收 Review Page —— Story 自己的 `latest/<id>-review.html` 是人类验收入口 `[highlight]`
+
+### 当前可观测性
+
+当前产品是 CLI-first。`roll status`、`roll loop watch`、`roll loop runs`、`roll loop cycle <id>`、`roll status pulse`、告警和按 Story 收口的 attest 报告，是当前活体真相入口。归档重建 是按需静态归档/修复渲染器，适合 CI artifact 和迁移对账；它不是当前真相入口。
+
+三态交付阶梯仍然成立：**claimed -> merged -> attested**。backlog 行写了 Done 只是 `claimed`；PR 合入 `main` 后变 `merged`；Story 证据齐备后变 `attested`。使用 `roll supervisor live` 查看一帧 CLI-first 多角色看板，或用 `roll supervisor live --watch` 让同一看板在终端原地刷新；浏览器/TUI 版 Supervisor Live Console 仍是未来工作。
+
+### 按需技能
+
+- `$roll-debug` — 挂载诊断探针，追踪根因，如果可溯源则自动修复
+- `$roll-doc-audit` — 核对文档/网站/help 与实现；索引缺口并起草缺失文档
+- `$roll-doctor` — 诊断开发工具链：node、npm、git、AI 工具
+- `$roll-notes` — 以叙述形式记录一个开发时刻
+
+### 多 Agent 协作
+
+- Fail-loud 路由 — 请求的 agent/model/rig 不可用 → 记录限制并暂停，或仅按显式 fallback 策略路由 `[highlight]`
+- `$roll-peer` — 多轮协商；结构化 adapter 记录一次性 reviewer facts `[core]`
+- PR 收件箱 — 外部 PR 先经 AI 评审再合入；过时 PR 自动 rebase `[new]`
+- `roll review-pr` — 对任意 PR 按需发起 AI 评审，可指定 agent `[new]`
+
+## 项目结构
+
+Roll 2.0 让项目根目录保持干净，所有 Roll 管理的产物都收进 `.roll/`：
+
+```
+my-project/
+├── AGENTS.md            # 工程约束（根目录 — Agent 第一读它）
+├── README.md            # 产品门面
+├── src/  tests/         # 业务代码
+└── .roll/               # Roll 接触的一切
+    ├── backlog.md       # Story / Fix / Refactor 索引
+    ├── features/        # 每个 Story 的 AC + plan 文档
+    ├── domain/          # DDD 模型、context map
+    ├── briefs/  dream/  # 自主层产出
+    └── decisions/       # ADR
+```
+
+从 2.0 之前的版本升级？看 [migration-2.0.md](migration-2.0.md) ——
+`npx @seanyao/roll@2 migrate` 一次性把旧版 `BACKLOG.md`、`docs/features/`、
+`docs/domain/` 迁到新布局。
+
+## 选择接入模式
+
+Roll 支持三种接入模式，按项目起点选择 —— 决策树见
+[patterns/](patterns/README.md)：
+
+- **Seed（播种）** —— 空目录 + 产品愿景。从 day 1 就是 Roll 原生形态。
+- **Graft（嫁接）** —— 已有代码、零侵入。`$roll-onboard` 从现有项目反推
+  生成 `.roll/`。参见 [legacy-onboarding.md](legacy-onboarding.md)。
+- **Replant（翻种）** —— 历史包袱重。先反推规格，再按新规格重建。
+
+## 指南目录
+
+| 主题 | 文档 |
+|------|------|
+| 第一次跑通项目 | [getting-started.md](getting-started.md) |
+| 调度、子命令、tmux 可见性 | [loop.md](loop.md) |
+| 受治理的工具注册表与策略 | [tools.md](tools.md) |
+| 夜间代码健康巡检与 REFACTOR 生成 | [dream.md](dream.md) |
+| 跨 Agent 评审协议 | [peer.md](peer.md) |
+| 完整技能目录 | [skills.md](skills.md) |
+| 接入模式（seed / graft / replant） | [patterns/](patterns/README.md) |
+| 给已有项目接入 Roll | [legacy-onboarding.md](legacy-onboarding.md) |
+| 从 2.0 之前版本升级 | [migration-2.0.md](migration-2.0.md) |
+| 常见场景与故障排查 | [faq.md](faq.md) |
+| 环境变量配置 | [configuration.md](configuration.md) |

package/guide/zh/pairing.md

@@ -0,0 +1,117 @@
+# 跨 Agent 结对 —— 在 loop 里自动获得异构的第二双眼睛
+
+结对让一个**不同**的 agent（不同厂商）自动复检你的工作。它的 primitive 是
+**结对（pair）**而非评审：一个 agent 干完活，一个异构搭档复检，换来视角多样性。
+一个模型盲区里藏着的 bug，另一个模型往往一眼看到。
+
+Roll 把评审指派看成 scoped Agent 模型里的 `evaluate` 角色：
+`Scope -> Role -> Binding -> Agent -> optional Model`。agent 是有限的七个身份
+（`claude`、`kimi`、`codex`、`pi`、`agy`、`reasonix`、`cursor`）；model 是挂在该 agent 上的可选数据。
+
+结对与 [`$roll-peer`](peer.md) 不同：peer 是你（或 loop 风险闸）按需发起的多轮协商；
+结对是常驻的单向第二遍，接在 cycle 里，由 Project Scope 的 `evaluate` binding 管控。
+
+## 开启 —— 显式，绝不静默
+
+```bash
+roll agent                         # 查看 story.evaluate
+roll agent migrate --dry-run       # 如有旧 pairing.yaml，预览迁移
+```
+
+新项目应在 `.roll/agents.yaml` 里声明 evaluator pool：
+
+```yaml
+# .roll/agents.yaml
+schema: roll-agents/v1
+scope: project
+defaults:
+  story:
+    roles:
+      evaluate:
+        kind: select
+        from: [claude, codex, kimi, pi, agy, reasonix]
+        require: [evaluate]
+        strategy: health-aware
+```
+
+`.roll/pairing.yaml` 仍是 legacy compatibility 输入；两者同时存在时优先使用 scoped
+`evaluate` role。静态配置列公平候选，auth/network/VPN/account 等运行时失败只在本次
+resolution 中跳过候选。
+
+## 看它做了什么 —— 可观测性
+
+Loop cycle evidence 和角色视图会显示结对池（谁能结对、其厂商、被声明的能力，
+以及某个 agent**因何被排除**），外加**结对花了多少钱**：
+
+```
+  Cross-Agent Pairing — pool status / 结对池状态
+
+  enabled: true · stages: [code]
+
+    ✓ claude  vendor=anthropic · [code]
+    ✓ codex   vendor=openai · [code]
+    · pi      vendor=pi · [code] · excluded: no heterogeneous partner
+
+  pairings to date: 7 (codex×4, kimi×3) · total cost $0.94 · 11 findings
+```
+
+成本从第一天起每次结对都记账——即使还没做预算自适应，你也始终知道这第二双眼睛
+花了多少。
+
+## 选择逻辑
+
+某阶段触发时，选择器**只**保留：已安装、可用、被声明能做该阶段、能作为 headless
+reviewer 运行，且与干活 agent **不同厂商**的——然后在其中轮换（以 cycle id 为种子，
+可复现）。有战绩的搭档会被温和偏好（ε-greedy，ε≈0.2），但始终保留探索，任何一对都
+不会垄断。若没有合格的异构搭档，这个"没有"本身也会被记录（`pair:none-available`）——
+绝不静默跳过。
+
+## 安全 —— 结对绝不阻塞 cycle
+
+- 对复检设 **30 秒硬超时**（executor 里双保险），慢搭档绝不拖死 cycle。
+- **不阻塞**：超时、出错或无搭档都只记录，cycle 照常推进。结对是增强，不是闸。
+- **绝不自行动主干**：结对只产证据和事件，不做合并。
+
+## 事件与证据
+
+每次结对先发 `pair:selected`，再发 `pair:verdict`（含裁定、发现数、成本、阶段）
+或 `pair:none-available`。裁定同时作为证据写入本轮的 `peer/cycle-<id>.pair.json`。
+评分结对发 `pair:score`（分数、裁定、成本），证据写入
+`peer/cycle-<id>.score.pair.json`。
+
+## 阶段
+
+`code` 和 `score` 是默认——异构搭档复检交付的改动，另一位给完成的 cycle 打分。
+`design`、`test`、`cycle` 把同一套机制扩到其它检查点；想要更早或更广的第二双
+眼睛时在 `stages` 里开启。
+
+## Review Score —— 同行打分，绝不让作者给自己打分
+
+agent 给自己的交付打分是利益冲突，所以质量评分（**Review Score**）一律由
+**全新独立会话**里的 Reviewer 产出，绝不由工作 agent 自评：
+
+- **loop 内**：验收闸通过后，runner 拉起一个全新会话的 Reviewer 给交付打分。
+  note 落在卡片 `notes/` 目录，带溯源——`scoring: pair`、`scored-by: <agent>`
+  以及全新会话 id（独立性可核验）。
+- **Loop 交付**：验收闸通过后，runner 在全新会话里触发同一适配器。
+- **设计产出**（`roll-design`，无 loop cycle）：设计工作流可以触发全新会话的 Reviewer
+  评**设计**质量（INVEST 拆分、可视 AC 完整、`deliverable_url` 正确、领域/spec 一致），
+  而非代码；记为 `stage=design`。设计 agent 只触发、绝不给自己打分；无可用评审则诚实
+  标记未评审（fail-loud），绝不合成自评。
+- **只要装了别的 agent，builder 的本体 agent 绝不给自己的 cycle 打分**：此时 builder 被
+  整个排除出打分池——要么由独立 Evaluator 评分，要么 fail-loud（即便同厂全新会话也不回落成自评）。
+  只有真正的单 agent 安装里，builder 的本体 agent 才是评分者，此时同厂全新会话是最低可接受档。
+  独立性仍按 session id 核验（更鼓励不同 `agent × model × session` rig），所以单 agent 场景不会死锁。
+  任何与 builder 共享会话的打分——包括其子 agent——都被判为自评而拒收。
+  无独立候选、超时或协议不符时**不会**回落成自评；缺席通过 `pair:none-available`
+  事件留痕，该 story 仍欠一份全新会话的 Review Score 才能 attest（`review_score_missing`）。
+- **真实 agent 输出会先归一化再评分**：Evaluator 回复中夹带终端控制字节、ANSI 启动横幅、
+  JSONL stream-json 外壳或 bullet/markdown 前缀都能被接受——解析器先归一化，再严格要求一段完整、
+  有序的 `SCORE`/`VERDICT`/`RATIONALE` 块（分数 1..10、合法 verdict）。仅在散文里提到这些标记的仍会被拒。
+- **重复出现的最终块若一致也会被容忍**：有的 Evaluator 会重绘终端（最终块出现两次），或先打印
+  回复模板和分析、再给出真正的块。解析器只取**最终可用块**，并在所有合法 `SCORE` 行一致、所有合法
+  `VERDICT` 行一致时采信——重绘属于已确定的同一答案。真正冲突的重复块（分数或 verdict 不同）、
+  模板 `<占位符>` 回声、越界分数、不支持的 verdict 仍会被拒。
+- **拒收有可观测的具体原因，而非笼统报错**：回复未被采信时，cycle 记录的是具体原因而非一句
+  “unparseable”。`roll loop cycle <id> --roles` 会区分 Evaluator 是**返回了类分数文本但未被采信**
+  （如重复块冲突、缺字段）还是**完全没返回任何分数内容**，并在角色行上标出确切原因。

package/guide/zh/patterns/README.md

@@ -0,0 +1,74 @@
+# Roll 接入模式（Patterns）
+
+> 三种把 Roll 引入项目的标准姿势。基于项目所处的生命周期阶段与团队风险偏好选择。
+
+## 三种 pattern 速览
+
+| Pattern | 中文 | 起点 | 比喻 |
+|---------|------|------|------|
+| [seed-pattern](./seed-pattern.md) | 播种 | 空目录 + 愿景 | 处女地播种 |
+| [graft-pattern](./graft-pattern.md) | 嫁接 | 仍在演化的现有项目 | 砧木上嫁接接穗 |
+| [replant-pattern](./replant-pattern.md) | 翻种 | 累积过多债的现有项目 | 连根拔起栽新苗 |
+
+## 决策树
+
+```
+你的项目处于哪个状态？
+    │
+    ├── 还没开始 / 只有一个 idea
+    │       └──→ seed-pattern
+    │
+    └── 已有代码
+            │
+            ├── 项目仍在快速演化、不能停 → graft-pattern
+            ├── 团队想小步试水 Roll      → graft-pattern
+            ├── 代码量 < 1000 行         → graft-pattern（先嫁接，需要时再 replant）
+            │
+            ├── 累积包袱重、想清债       → replant-pattern
+            ├── 想借机做架构跃迁         → replant-pattern
+            └── 现有版本可冷藏           → replant-pattern（必要前提）
+```
+
+## 三种 pattern 的核心精神对比
+
+| 维度 | seed | graft | replant |
+|------|-----------|-------|---------|
+| 对原架构 | 不存在 | 零侵入保留 | 推翻 |
+| 可逆性 | — | 高（`rm -rf .roll/`） | 低（发布后） |
+| 风险 | 低 | 低 | 高 |
+| 上限 | 高 | 中 | 高 |
+| 启动门槛 | 中（要写 spec） | 低 | 高 |
+| 典型周期 | 持续演化 | 持续演化 | 一次性工程 |
+
+## 共通要素
+
+无论选哪个 pattern，三者都共享同一个 `.roll/` 目录约定：
+
+```
+.roll/
+├── backlog.md       项目管理入口
+├── specs/           设计权威（PRD / Architecture / DDD）
+├── features/        Story 详情
+├── briefs/  dream/  Roll 自动产出
+├── decisions/       ADR
+└── state/           运行时中间产物
+```
+
+差别在于 **`.roll/` 是怎么诞生的**：
+- seed：人手写 specs + backlog
+- graft：`$roll-onboard` 从现有项目反推后落盘
+- replant：先反推到 `roll-rev/`，精炼后写入 `.roll/specs/`
+
+## 选错了怎么办
+
+三种 pattern 之间存在迁移路径：
+
+| 从 | 到 | 可行？ |
+|----|----|-------|
+| graft | replant | ✓ 任何时候都可以"升级"为重建 |
+| graft | seed | ✗ 项目已存在，不能假装没有 |
+| replant | graft | ✓ 反推后发现不必重建，退回嫁接 |
+| seed | graft | 不适用（seed 已经是从零起步） |
+| seed | replant | ✓ 项目跑一段时间后决定重建 |
+
+最常见的真实路径：**graft 起步 → 跑半年 → 决定 replant 清债**。这是最稳健的演进路线。

package/guide/zh/patterns/graft-pattern.md

@@ -0,0 +1,108 @@
+# Graft Pattern — Legacy 项目的"续写"路径
+
+> Roll 三种接入模式之一。另见 [replant-pattern.md](./replant-pattern.md)、[seed-pattern.md](./seed-pattern.md)。
+>
+> **核心精神：原架构零侵入，Roll 作为接穗嫁接进来，与项目共生演化。**
+
+## 何时选这个 pattern
+
+适合：
+- 项目仍在快速演化，不能停下来重建
+- 团队风险偏好低，想小步增量验证
+- 想先试用 Roll 一段时间再决定是否深入采用
+- 原项目代码质量尚可，只是缺少 AI 辅助的项目管理与自治执行
+
+不适合：
+- 项目本身架构腐烂，"续写" 等于继续累积债 → 选 replant
+- 团队希望借机做架构跃迁 → 选 replant
+- 项目尚未开始 → 选 seed
+
+## 目录结构
+
+```
+my-legacy-project/                    ← 砧木：现有项目，零侵入
+│
+├── src/  lib/  tests/  docs/           原有结构，全部不动
+├── package.json                        不动
+├── README.md                           不动
+│
+├── AGENTS.md                         ← 嫁接接口：新增或 section-merge（非破坏）
+│
+└── .roll/                            ← 接穗：Roll 工具栖息地
+    ├── backlog.md                      项目管理增量（新故事走这里）
+    ├── features/                       Story 详情
+    ├── dream/                          Roll 自动产出（代码健康扫描）
+    ├── specs/                          可选：增量沉淀的规格文档
+    └── (可选 .gitignore)               团队决定是否公开
+```
+
+## 数据流
+
+```
+现有项目（砧木） ──持续演化──→ 项目继续生长，原有工作流不变
+                                  ↓
+                              .roll/（接穗）嫁接进来
+                                  ↓
+                              Roll 工具链接管新故事的管理与自治执行
+                              （loop / dream / peer review / status·cycle 可观测）
+```
+
+## 砧木与接穗的边界
+
+| 内容 | 砧木的职责 | 接穗的职责 |
+|------|----------|----------|
+| 现有源码 | ✓ 团队手动维护 | — |
+| 现有测试 / CI | ✓ 不动 | — |
+| 现有 issue tracker | ✓ 继续用 | — |
+| 新功能的设计 / 拆解 | — | ✓ Roll 接管（`$roll-design` → backlog） |
+| 新故事的实现 | — | ✓ Loop 增量执行 |
+| 文档新鲜度巡检 | — | ✓ `$roll-.dream` 自动巡 |
+| 跨 agent 评审 | — | ✓ Peer review 入循环 |
+| 交付可观测 | — | ✓ `roll status` / `roll loop cycle` / Story 报告 |
+
+**`.roll/` 完全可以被 `rm -rf` 整体移除，项目回到嫁接前的状态。**
+这是 graft-pattern 与 replant-pattern 的根本区别——嫁接是**可逆**的。
+
+## 执行步骤
+
+1. `cd my-legacy-project && roll init`
+2. Roll 检测到 Legacy 结构（有源码、无 `AGENTS.md`），进入 onboarding 引导
+3. 用户在 AI agent 里运行 `$roll-onboard`
+4. Skill 读代码、理解项目、走三组九问、产出 `.roll/onboard-plan.yaml`
+5. `roll init --apply` 先打印计划操作检查点并等待确认，再按 plan 落盘 `.roll/` 结构
+6. 团队 review 生成的 backlog，调整后开始用 `$roll-build` 推新故事
+7. 可选：`roll loop on` 进入自治模式
+
+## 渐进式深入（L1 → L5）
+
+graft 不是一次性事件，可以分阶段加深采用：
+
+| 阶段 | 做了什么 | 砧木受影响程度 |
+|------|---------|-------------|
+| L1: 工具链 | 装 Roll CLI，`AGENTS.md` 同步 AI 工具约定 | 零（仅追加文件） |
+| L2: 项目管理 | `.roll/backlog.md` 接管新故事 | 零（新故事走新流，老故事不动） |
+| L3: 自动巡检 | 启用 `roll-.dream` 代码健康扫描 | 零（仅读、产出独立文件） |
+| L4: Loop 自治 | 启用 `roll loop` 自动执行 Todo | 低（loop 会改源码，但走 PR 流程） |
+| L5: Peer review | 跨 agent 评审入流 | 低（评审是 gating，非自动 merge） |
+
+团队可以停在任一层。**L1+L2 已经能拿到 70% 的 Roll 价值。**
+
+## 与其他 pattern 的对比
+
+| 维度 | graft-pattern | replant-pattern | seed-pattern |
+|------|--------------|----------------|---------------------|
+| 对原架构的态度 | 保留并嫁接 | 推翻重建 | 无原架构（从零） |
+| 风险 | 低 | 高 | 低 |
+| 上限 | 中（受历史约束） | 高（彻底清债） | 高（无包袱起步） |
+| 可逆性 | 高（`rm -rf .roll/` 即可） | 低（覆盖发布后） | 不适用 |
+| 启动门槛 | 低 | 高 | 中 |
+| 适用 | 仍在演化、不可停下来 | 包袱重、可冷藏老版本 | 新项目、从 idea 阶段 |
+
+## 实例
+
+任何使用 Roll 的已有代码库都是 graft 的实例。典型场景：
+
+- 5 年的 Django 项目，团队装 Roll 只为给新功能做自治管理
+- Spring Boot 微服务集群，装 Roll 给跨服务的 PR 评审做 peer
+- 长期演进的 bash 工具链，装 Roll 给文档新鲜度做 dream 巡检
+- 任何已有 `git log` 但缺方法论的项目