@seanyao/roll 4.630.2 → 4.702.2

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

@@ -0,0 +1,112 @@
+# Replant Pattern — Legacy 项目的"翻种"路径
+
+> Roll 三种接入模式之一。另见 [graft-pattern.md](./graft-pattern.md)、[seed-pattern.md](./seed-pattern.md)。
+>
+> **核心精神：以现有产品为靶子，反推规格、有意识精炼、连根拔起栽新苗。**
+
+## 何时选这个 pattern
+
+适合：
+- 现有项目累积包袱太重，重构成本 > 重建成本
+- 想借机做一次有意识的架构跃迁（去掉冗余、调整边界、统一约定）
+- 团队有能力维持"新旧并行"一段时间
+- 现有项目的**测试套件足够完整**（这是反推规格的契约层）
+
+不适合：
+- 现有项目还在快速演化（重建期间会持续漂移）
+- 测试覆盖率低（反推的规格会丢掉隐性约束）
+- 团队不能停下新功能开发
+
+## 目录结构
+
+```
+project-builder/                       构建 v2.0 的工程项目
+│
+├── project-v1.0/                     ⓪ 原料：v1.x 完整 snapshot（只读参照物）
+│   └── (按某个 tag 冻结，不随主线演化)
+│
+├── project-rev/                      ① 粗料：从 v1.0 反推的草稿
+│   ├── prd-draft.md
+│   ├── architecture-draft.md
+│   ├── ddd-draft.md
+│   └── us-list-draft.md
+│
+├── .roll/                            ② 工坊 meta（管理"构建 v2.0"这个项目）
+│   ├── backlog.md
+│   ├── specs/                         ← 精炼后的 v2.0 权威规格
+│   │   ├── prd.md
+│   │   ├── architecture.md
+│   │   └── ddd.md
+│   ├── features/                      每条 Story 详情
+│   └── decisions/                     构建过程中的 ADR
+│
+└── project-v2.0/                     ③ 产物：v2.0 真身（loop 增量构建出来）
+    └── (bin/ lib/ ...)
+```
+
+## 数据流
+
+```
+v1.0 源码 ──反推──→ project-rev/（粗料）
+                       │
+                       ▼ 精炼（保留 / 丢弃 / 新增 / 重塑）
+                   .roll/specs/（设计权威）
+                       │
+                       ▼ Loop 按 .roll/backlog 增量构建
+                   project-v2.0/（产物）
+                       │
+                       ▼ 发布
+                   覆盖 origin 仓库 @ 2.0.0
+```
+
+## 三层数据各自的角色
+
+| 层 | 数据性质 | 写一次还是反复改 |
+|----|---------|----------------|
+| `project-v1.0/` | 不可变 snapshot | 只读 |
+| `project-rev/` | AI 反推产物，反映"v1.0 实际行为" | 写一次，后续可补丁但不大改 |
+| `.roll/specs/` | 人工精炼后的 v2.0 蓝图 | **反复迭代**，是设计权威 |
+| `project-v2.0/` | Loop 按 specs 增量构建的代码 | Story 推进时增长 |
+
+**关键洞察：`project-rev/` → `.roll/specs/` 不是简单 copy，是一次有意识的设计跃迁。**
+
+这是真正去掉 v1.0 累积包袱的窗口。粗料保留下来作为对照组（v2.0 发布时随产物归档到 `project-v2.0/.roll/specs/origins/`，作为历史档案）。
+
+## 执行步骤
+
+1. **冻结 v1.0**：选定 tag/commit，复制源码到 `project-v1.0/`，标注版本号
+2. **反推粗料**：AI 读 v1.0 源码 + 测试，产出 `project-rev/` 下的草稿
+3. **精炼规格**：人工 review 粗料，做出"保留 / 丢弃 / 新增 / 重塑"的决策，产出 `.roll/specs/`
+4. **拆解 Story**：基于 specs 写 `.roll/backlog.md`，按依赖顺序
+5. **Loop 构建**：在 `project-v2.0/` 下增量造，Story 实现时引用 `.roll/specs/` 作为权威
+6. **对照校验**：每条 Story 完成后用 v1.0 测试套验证 v2.0（如果测试可移植）
+7. **发布**：v2.0 满足验收后覆盖 origin 仓库，发布主版本号
+
+## 早停门
+
+| 检查点 | 通过判据 | 不通过怎么办 |
+|-------|---------|------------|
+| Day 1 后 | PRD 对 v1.0 artifact 覆盖率 ≥ 90% | < 70% 停下来：项目行为已超出"可声明为产品"的范畴 |
+| 第一批 Story 后 | v2.0 行为与 v1.0 一致率 ≥ 80% | < 80% 停下来：分析 gap 来自反推漏项还是 v1.0 偶然行为 |
+
+任一门没过 → 切换到 [graft-pattern](./graft-pattern.md)，承认这个项目不适合重建。
+
+## 与其他 pattern 的对比
+
+| 维度 | replant-pattern | graft-pattern | seed-pattern |
+|------|----------------|---------------|--------------|
+| 对原架构的态度 | 推翻重建 | 保留并嫁接 | 无原架构（从零） |
+| 风险 | 高（隐性知识丢失） | 低（不动原码） | 低 |
+| 上限 | 高（彻底清债） | 中（仍受历史约束） | 高（无包袱起步） |
+| 适用 | 累积包袱重、可冷藏老版本 | 仍在演化、不可停下来 | 新项目、从 idea 阶段 |
+| 工作量 | 大（造一个新的） | 小（接入工具链） | 中（先写 spec 再 loop） |
+
+## 实例：Roll 自身
+
+Roll 项目自己用这个 pattern 从 v1.x 重建到 v2.0：
+- `roll-builder/roll-v1.0/` ← v2026.518.4 snapshot
+- `roll-builder/roll-rev/` ← Claude 反推的 PRD/Arch/DDD/US 草稿
+- `roll-builder/.roll/specs/` ← 精炼后的 v2.0 设计权威
+- `roll-builder/roll-v2.0/` ← Loop 增量构建的 v2.0 产物，发布到 `seanyao/roll`
+
+这是 Roll 的"自我重塑"工程，也是 replant-pattern 的 reference implementation。

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

@@ -0,0 +1,130 @@
+# Seed Pattern — 新项目的"播种"路径
+
+> Roll 三种接入模式之一。另见 [graft-pattern.md](./graft-pattern.md)、[replant-pattern.md](./replant-pattern.md)。
+>
+> **核心精神：项目从第一天就携带 Roll 基因，像一粒种子在新土里发芽，所有约定、目录、工作流原生匹配。**
+
+## 何时选这个 pattern
+
+适合：
+- 从零开始的新项目
+- 有明确的产品愿景，实现细节灵活
+- 想从 day 1 用 Roll loop 的自治能力
+- 团队愿意先写 PRD / Architecture 再动代码（即使只写最薄一层）
+
+不适合：
+- 完全探索性项目，PRD 都写不出来 → 先用别的工具做原型，定型后再 seed 适配
+- 极小项目（一个 100 行的 script），上 Roll 是过度工程
+
+## 目录结构
+
+```
+my-new-project/                       ← Roll 原生项目，从 day 1 就是 .roll/ 形态
+│
+├── README.md                          产品门面
+├── LICENSE
+├── AGENTS.md                          AI 约定（roll init 生成）
+├── CHANGELOG.md                       随发版生长
+├── package.json                       或其他语言对应的 manifest
+│
+├── src/  lib/  tests/                 产品代码（最初为空，Loop 增量构建）
+│
+├── guide/                             用户文档（最初为空，发布前生长）
+│   ├── en/  zh/
+│
+└── .roll/                            ← 项目管理 + 设计过程（从 day 1 存在）
+    ├── backlog.md                     创始人写下的初始 Story 清单
+    ├── specs/                         初始 PRD / Architecture / DDD
+    │   ├── prd.md
+    │   ├── architecture.md
+    │   └── domain/
+    ├── features/                      Story 详情
+    ├── briefs/  dream/                Roll 自动产出
+    └── decisions/                     ADR
+```
+
+## 数据流
+
+```
+创始人愿景 ──写入──→ .roll/specs/（初始 PRD / Architecture）
+                       │
+                       ▼ 拆解 Story
+                   .roll/backlog.md
+                       │
+                       ▼ Loop 增量构建
+                   src/  lib/  tests/（产品产物）
+                       │
+                       ▼ 发布
+                   v1.0.0
+```
+
+与 replant-pattern 的本质差异：**起点不同**。
+- replant：从已有 v1.x 反推规格
+- seed：由人直接写规格（创始人愿景作为唯一输入）
+
+## 三层数据角色
+
+| 层 | 数据性质 | 何时写 |
+|----|---------|------|
+| `.roll/specs/` | 设计权威 | 项目启动时写第一版，演化中持续迭代 |
+| `.roll/backlog.md` | 工作流入口 | specs 写完后拆解，loop 推进时增减 |
+| `src/`  `lib/`  `tests/` | 产品产物 | Loop 按 backlog 增量构建 |
+
+## 执行步骤
+
+1. `mkdir my-new-project && cd my-new-project`
+2. `roll init` 生成 `.roll/` 骨架 + `AGENTS.md`
+3. **写第一版 specs**：用 `$roll-design` 或手写，在 `.roll/specs/` 完成 PRD / Architecture / DDD
+4. **拆解 Story**：用 `$roll-design` 把 specs 拆成 INVEST-compliant Story 写入 `.roll/backlog.md`
+5. **启动 loop**：`roll loop on`，进入自治构建
+6. 创始人持续校对、调整 specs，loop 跟着新 backlog 跑
+
+## 创始人的两种姿态
+
+**姿态 A — specs-driven（重型）**
+先把 PRD / Architecture 写得相对完整再启动 loop。
+- 适合：愿景清晰、有 senior 工程师、关键决策需要前置敲定
+- 风险：可能过度设计、与现实脱节
+
+**姿态 B — seed-driven（轻型）**
+specs 只写最核心的 1-2 章，backlog 只列前 3 条 Story，启动 loop 边跑边写。
+- 适合：愿景模糊、迭代快、容错高、Hackathon 节奏
+- 风险：早期决策反复，loop 可能跑出不符合最终愿景的代码
+
+两种姿态对应**同一个目录结构**，差别只在 `.roll/specs/` 的初始完整度。
+
+## 与其他 pattern 的对比
+
+| 维度 | seed-pattern | replant-pattern | graft-pattern |
+|------|--------------------|----------------|---------------|
+| 起点 | 空目录 + 愿景 | 现有 v1.x | 现有项目 |
+| 规格来源 | 人写 | 反推 v1.x + 精炼 | 不需要（用现有） |
+| 历史包袱 | 无 | 反推时丢弃 | 保留 |
+| 上限 | 高 | 高 | 中 |
+| 启动门槛 | 中（要先写 PRD） | 高（反推 + 精炼） | 低（直接加 .roll/） |
+| 适用 | 新项目、从 idea 阶段 | 包袱重、可冷藏老版本 | 仍在演化、不可停下来 |
+
+## 实例
+
+- 新创立的 SaaS 产品，第一天就用 Roll 管开发
+- 学习型项目，"如何用 Roll 协作" 本身就是学习目标
+- Hackathon 项目，48 小时内从 idea 到 demo，全程 Roll 驱动
+- 个人侧项目，单人开发但想要 AI loop 的"24h 续航"能力
+
+## 演化路径
+
+seed 项目的自然演化：
+
+```
+seed 启动
+    │
+    ▼ 跑 3-6 个月，积累 specs + backlog
+项目进入"成熟"期
+    │
+    ├── 一切顺畅 → 继续 seed 节奏
+    │
+    ├── 发现累积了不该有的债 → 切换 replant-pattern
+    │                          （把当前版本当 v1.x snapshot，反推清债）
+    │
+    └── 想拉新人/团队加入 → 文档或网站与实现不齐时，用 $roll-doc-audit 对账并补齐
+```

package/guide/zh/peer.md

@@ -0,0 +1,63 @@
+# $roll-peer — 结构化外部评审
+
+`$roll-peer` 通过与 goal-mode 终审相同的结构化 adapter 运行外部 provider
+reviewer。旧的顶层 peer CLI 已退役；需要这个能力时，在 agent 工作流里调用 skill。
+
+需要多轮协商协议，或需要从 Claude、Codex、Kimi、Pi 等已安装外部 CLI 记录 durable
+reviewer fact 时，使用 `$roll-peer`。
+
+## Prompt 形状
+
+```text
+$roll-peer
+Review this plan and return VERDICT / REASON / FINDING lines.
+```
+
+Reviewer 输出必须包含且只包含一行 verdict：
+
+```text
+VERDICT: APPROVE|REQUEST_CHANGES
+REASON: <short reason>
+FINDING: <concrete issue>
+```
+
+verdict 行缺失或出现多行时，adapter 保守判为 `REQUEST_CHANGES`。
+
+## 记录的事实
+
+每次采信的 review 都会向这里追加一行 JSON：
+
+```text
+.roll/peer/runs.jsonl
+```
+
+如果 reviewer 进程产生了输出，transcript 也会写到：
+
+```text
+.roll/peer/transcripts/
+```
+
+记录字段包括 reviewer agent、provider、command family、verdict、reason、
+findings、timeout/error 状态、耗时、transcript 路径和 evidence 路径。goal-mode
+终审会在 `goal:final_review` 事件上写入同一组事实字段。
+
+## 解析失败
+
+当 reviewer 或 scorer 在 autonomous cycle 里跑了，但输出**无法解析**时，这次尝试
+不会被悄悄丢弃。原始尝试会被捕获到 `.roll/loop/peer/` 下，该 agent 在 cycle
+角色阵容里显示 `failed`，带 `cause` 和 `raw artifact:` 指针。
+
+读法见 [Cycle 角色可观测](./loop.md#cycle-角色可观测)，排障步骤见
+[排障：无法解析的 score/review](../../docs/live-console.md#故障排查)。
+
+## 外部 reviewer 与辅助 subagent
+
+`$roll-peer` 面向外部 provider reviewer CLI。Codex 内部 subagent 可以辅助并行分析，
+但不等同于外部 peer review。adapter 会把 `codex-subagent:*` / `subagent:*` 身份视为
+auxiliary，排除在异构 reviewer 选择之外。
+
+## 与 pairing 的关系
+
+Loop pairing 是构建期 gate：自主 cycle 中风险较高的交付 diff 会被异构 peer 复查，
+并写入 cycle 证据。`$roll-peer` 是 agent 调用的结构化外部评审 skill。两者共享
+provider 多样性原则，但服务不同工作流。

package/guide/zh/pr-review.md

@@ -0,0 +1,54 @@
+# Roll — PR 评审
+
+Roll 处理完整的 PR 生命周期——从开 PR 到合入——大多数情况无需人工干预。
+
+## 手动评审
+
+```bash
+roll review-pr <number>   # AI 评审指定 PR
+```
+
+通过 `gh cli` 获取 PR 标题、描述和 diff，路由到项目配置的 AI Agent，输出结构化决议：
+
+| 决议 | 操作 |
+|------|------|
+| `APPROVE` | `gh pr review --approve` |
+| `REQUEST_CHANGES` | `gh pr review --request-changes` 并附理由 |
+| `UNCERTAIN` | 写入 ALERT——由人决定 |
+
+## Loop PR Inbox
+
+每轮 loop cycle 在认领新故事前先处理开放 PR：
+
+| PR 分类 | Loop 操作 |
+|---|---|
+| Loop 自己开的（`loop/*` 分支） | 跳过——不自我评审 |
+| Bot 已 Approve | 跳过——等 auto-merge |
+| Bot 要求修改 | 写 ALERT——等作者推修复 |
+| Stale（CI 红 / 落后 main） | 自动 rebase 到 `main` |
+| 外部 PR / 干净状态 | 调用 `roll review-pr` |
+
+**Stale PR 熔断器**：若 rebase 在 24 小时内失败 3 次，loop 停止重试并写 ALERT，由人接手。
+
+## Auto-merge
+
+Loop 自己开的 PR（`loop/*`）以 `--auto --squash --delete-branch` 创建。GitHub 在所有必需检查通过后自动合入，无需手动 `git merge`。
+
+## 可选：事件驱动评审（GitHub Actions）
+
+如需秒级反馈（而非等待 loop 下一轮调度，最多约 1 小时）：
+
+```bash
+cp templates/workflows/pr-review-event.yml .github/workflows/
+```
+
+此工作流在每次 PR 打开或更新时触发 `roll review-pr`。Fork PR 和正文含 `[skip-ai-review]` 的 PR 自动跳过。两种模式共存——GHA 提供即时反馈，loop 作为兜底。
+
+## 跳过 AI 评审
+
+在 PR 正文任意位置加 `[skip-ai-review]` 即可不调用 Agent，直接 Auto-approve。适用于机械性 PR（依赖升级、生成内容）。
+
+## 另见
+
+- [loop.md](loop.md) — loop PR inbox 详情和 stale rebase 处理
+- [ai-agents.md](ai-agents.md) — 哪个 Agent 负责评审