@seanyao/roll 4.630.2 → 4.702.2

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

@@ -0,0 +1,114 @@
+> Mirror of the original Chinese source — English translation pending. See IDEA-NNN for translation status.
+
+# 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/en/patterns/seed-pattern.md

@@ -0,0 +1,132 @@
+> Mirror of the original Chinese source — English translation pending. See IDEA-NNN for translation status.
+
+# 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/en/peer.md

@@ -0,0 +1,71 @@
+# $roll-peer — Structured External Review
+
+`$roll-peer` runs external-provider review through the same structured adapter
+used by goal-mode final review. The old top-level peer CLI is retired; invoke
+the skill from an agent workflow when you need this capability.
+
+Use `$roll-peer` when you need the full multi-round negotiation protocol, or
+when a durable reviewer fact from Claude, Codex, Kimi, Pi, or another installed
+external CLI should be recorded.
+
+## Prompt Shape
+
+```text
+$roll-peer
+Review this plan and return VERDICT / REASON / FINDING lines.
+```
+
+Reviewer output must contain exactly one verdict line:
+
+```text
+VERDICT: APPROVE|REQUEST_CHANGES
+REASON: <short reason>
+FINDING: <concrete issue>
+```
+
+Malformed or multiple verdict lines fail closed as `REQUEST_CHANGES`.
+
+## Recorded Facts
+
+Every accepted review appends one JSON line to:
+
+```text
+.roll/peer/runs.jsonl
+```
+
+When a reviewer process produced output, the transcript is also written under:
+
+```text
+.roll/peer/transcripts/
+```
+
+The recorded fact includes reviewer agent, provider, command family, verdict,
+reason, findings, timeout/error state, duration, transcript path, and evidence
+path. Goal-mode final review emits the same fact fields on `goal:final_review`.
+
+## Parse Failures
+
+When a reviewer or scorer runs inside an autonomous cycle but its output is
+**unparseable** (for example, control characters before the `SCORE` line, or a
+missing `VERDICT` line), the attempt is not silently dropped. The raw attempt is
+captured under `.roll/loop/peer/`, and the agent's row in the cycle role cast
+shows `failed` with a `cause` and a `raw artifact:` pointer.
+
+See [Cycle Role Visibility](./loop.md#cycle-role-visibility) for how to read
+that cast, and
+[Troubleshooting unparseable score/review](../../docs/live-console.md#troubleshooting)
+for recovery steps.
+
+## External Reviewers vs Auxiliary Subagents
+
+`$roll-peer` is for external-provider reviewer CLIs. Codex-internal subagents are
+useful auxiliary analysis workers, but they are not a substitute for external
+peer review. The adapter treats `codex-subagent:*` / `subagent:*` identities as
+auxiliary and excludes them from heterogeneous reviewer selection.
+
+## Relationship To Pairing
+
+Loop pairing is a build-time gate: a heterogeneous peer re-checks risky delivery
+diffs during autonomous cycles and writes cycle evidence. `$roll-peer` is the
+agent-invoked negotiation skill for structured external review. They share the
+same explicit-diversity principle but serve different workflows.

package/guide/en/pr-review.md

@@ -0,0 +1,62 @@
+# Roll — PR Review
+
+Roll handles the full PR lifecycle — from opening to merging — without requiring
+manual intervention for most cases.
+
+## Manual Review
+
+```bash
+roll review-pr <number>   # AI review of a specific PR
+```
+
+Fetches the PR title, body, and diff via `gh cli`, routes to the project's
+configured AI agent, and outputs a structured verdict:
+
+| Verdict | Action |
+|---------|--------|
+| `APPROVE` | `gh pr review --approve` |
+| `REQUEST_CHANGES` | `gh pr review --request-changes` with reason |
+| `UNCERTAIN` | Writes ALERT — human decides |
+
+## Loop PR Inbox
+
+Each loop cycle processes open PRs before picking new stories:
+
+| PR classification | Loop action |
+|---|---|
+| Loop's own (`loop/*` branch) | Skip — no self-review |
+| Bot already approved | Skip — let auto-merge proceed |
+| Bot requested changes | Write ALERT — wait for author |
+| Stale (CI failed, branch behind) | Auto-rebase onto `main` |
+| External / clean | Invoke `roll review-pr` |
+
+**Stale PR circuit breaker**: If rebasing fails 3× within 24 hours, loop stops
+retrying and writes an ALERT for human attention.
+
+## Auto-merge
+
+Loop's own PRs (`loop/*`) are opened with `--auto --squash --delete-branch`.
+GitHub merges them automatically once all required checks pass. No manual
+`git merge` needed.
+
+## Optional: Event-Driven Review (GitHub Actions)
+
+For instant feedback (seconds vs. up to 1 hour with loop scheduling):
+
+```bash
+cp templates/workflows/pr-review-event.yml .github/workflows/
+```
+
+This workflow triggers `roll review-pr` on every PR open or update.
+Fork PRs and PRs with `[skip-ai-review]` in the body are skipped automatically.
+The two modes coexist — GHA provides instant feedback, loop acts as safety net.
+
+## Skip AI Review
+
+Add `[skip-ai-review]` anywhere in the PR body to auto-approve without invoking
+the agent. Useful for mechanical PRs (dependency bumps, generated content).
+
+## See Also
+
+- [loop.md](loop.md) — full loop PR inbox details and stale rebase handling
+- [ai-agents.md](ai-agents.md) — which agent handles reviews