@seanyao/roll 4.630.2 → 4.702.2

package/guide/en/migration-2.0.md

@@ -0,0 +1,154 @@
+# Migrating to Roll 2.0
+
+> **TL;DR:** Run `npx @seanyao/roll@2 migrate --dry-run`, review, then `npx @seanyao/roll@2 migrate`. One atomic commit. Done.
+
+Roll 2.0 moves all "process" artifacts (BACKLOG, PROPOSALS, feature specs, briefs, dream logs, design docs) from your project root + `docs/` into a single `.roll/` directory. User-facing docs (`docs/guide/`, `docs/site/`) move up to the project root.
+
+This is a one-time, breaking change. Your existing files keep their git history — Roll uses `git mv`.
+
+## Before you start
+
+- **Pin your old version** if you want a safety net: `npm install -g @seanyao/roll@1`. Old npm versions never go away, so you can always go back.
+- **Make sure your working tree is clean.** `npx @seanyao/roll@2 migrate` refuses to run with uncommitted changes. Commit or stash first.
+- **Optional but recommended**: read this whole page before running.
+
+## What will move
+
+| Old path | New path | Notes |
+|----------|----------|-------|
+| `BACKLOG.md` (root) | `.roll/backlog.md` | The main project workflow file |
+| `PROPOSALS.md` (root) | `.roll/proposals.md` | Pending proposals |
+| `docs/features.md` | `.roll/features.md` | Feature index |
+| `docs/features/` | `.roll/features/` | Per-feature specs |
+| `docs/briefs/` | `.roll/briefs/` | `roll-brief` output (auto-generated) |
+| `docs/dream/` | `.roll/dream/` | `roll-.dream` output (auto-generated) |
+| `docs/design/` | `.roll/design/` | Design exploration docs |
+| `docs/domain/` | `.roll/domain/` | DDD models |
+| `docs/practices/loop-autorun-verification.md` | `.roll/features/loop-engine/loop-autorun-verification.md` | Execution records |
+| `docs/practices/engineering-common-sense.md` | `guide/en/practices/engineering-common-sense.md` | Engineering norm (user-facing) |
+| `docs/intro/` | `site/slides/` | Promotional HTML pages |
+| `docs/guide/en/` | `guide/en/` | User docs (English) |
+| `docs/guide/zh/` | `guide/zh/` | User docs (Chinese) |
+| `docs/site/` | `site/` | Marketing site source |
+
+After migration, your `docs/` directory is gone. If you had your own files in `docs/` outside this list, `npx @seanyao/roll@2 migrate` won't touch them.
+
+## Why two destinations
+
+Roll 2.0 enforces an architectural split:
+
+- **`.roll/`** = process artifacts, for *us* (the maintainers). Backlog, dream logs, design notes.
+- **Root** = product artifacts, for *others*. README, guide, site, source code.
+
+Whether `.roll/` is gitignored is your choice (see [Privacy](#privacy) below). Whether it's tracked is orthogonal to the directional split.
+
+## Three-state safety
+
+`npx @seanyao/roll@2 migrate` is idempotent and refuses to do anything dangerous:
+
+| State | Action |
+|-------|--------|
+| Old paths only | Migrate (single atomic commit) |
+| `.roll/` only, no old paths | No-op with "already migrated" message |
+| Both present | **Refuse** — list conflicts, require manual resolution |
+| Neither present | No-op |
+
+If you stop midway, the partial state goes into the "both" bucket and you'll get a clear conflict report on the next run.
+
+## Step by step
+
+### 1. Update Roll to 2.0
+
+```bash
+npm install -g @seanyao/roll@2
+npx @seanyao/roll@2 version    # Should show 2.x
+```
+
+### 2. Preview the migration
+
+```bash
+cd your-project
+npx @seanyao/roll@2 migrate --dry-run
+```
+
+This prints a table of every move. Nothing happens to your files.
+
+### 3. Execute
+
+```bash
+npx @seanyao/roll@2 migrate
+```
+
+You'll see a single commit on your current branch:
+
+```
+Migrate project layout to .roll/ structure
+
+Paths migrated: 14
+```
+
+`git log --follow .roll/backlog.md` should still show the full history from `BACKLOG.md`.
+
+### 4. Verify
+
+```bash
+roll status          # Should run cleanly
+ls -la .roll/        # New structure
+git log -1           # The migration commit
+```
+
+If anything looks wrong, revert with `git revert HEAD`.
+
+## Privacy
+
+By default, `.roll/` is **tracked** (visible to everyone with repo access). If you want process artifacts private:
+
+```bash
+echo ".roll/" >> .gitignore
+git add .gitignore && git commit -m "chore: gitignore .roll/"
+```
+
+Then untrack what's already been committed:
+
+```bash
+git rm -r --cached .roll/
+git commit -m "chore: stop tracking .roll/"
+```
+
+Roll itself uses a separate **private repo** (`seanyao/roll-meta`) instead of gitignoring — that's a valid pattern too, but only makes sense if you want totally separate access controls.
+
+## Rolling back
+
+If you need to undo:
+
+```bash
+git revert HEAD                          # Undo the migration commit
+npm install -g @seanyao/roll@1           # Reinstall old Roll
+```
+
+Your file history is preserved either way (`git mv` doesn't lose blame).
+
+## Updates to other tools
+
+After migration:
+
+- `roll status`, `roll backlog`, `roll loop`, `roll brief` — all automatically use the new paths
+- `$roll-build`, `$roll-fix`, `$roll-design` skills — all updated; just re-run `roll setup` to refresh
+- Any external scripts referencing `BACKLOG.md` etc. — **you need to update those manually**
+
+## FAQ
+
+**Q: Can I migrate one piece at a time?**
+No. Migration is atomic — single commit. The "both" state intentionally errors out so you never end up in a half-migrated mess.
+
+**Q: What about CI / GitHub Actions referencing old paths?**
+Update them in the same commit window. If CI breaks after migration, that's almost always a stale path reference in a workflow file.
+
+**Q: My team uses Roll on multiple projects. Do I need to migrate all of them?**
+Each project independently. Roll 2.0 refuses to run on old structure with a clear hint pointing to `npx @seanyao/roll@2 migrate`, so nothing silently breaks.
+
+**Q: Can I skip migration and stay on Roll 1.x forever?**
+Yes. Old npm versions are permanent. But you'll miss new features (existing-codebase onboarding, agent discovery, plan-driven init).
+
+**Q: Roll runs `npm test` and many tests fail after migration — is that expected?**
+No. The migration should not change test outcomes. If tests break, run `git diff HEAD~1` to see what moved and look for paths in test files or fixtures that didn't get migrated. File an issue with the diff.

package/guide/en/overview.md

@@ -0,0 +1,190 @@
+# Roll — Overview
+
+Roll is a Supervisor-led delivery harness. Write a goal, let Roll turn it into Stories, and route each Story through scoped `supervise`, `execute`, and `evaluate` roles.
+
+## Quick Start
+
+```bash
+curl -fsSL https://seanyao.github.io/roll/install | bash
+
+cd my-project
+roll setup && roll init
+
+roll next           # continue with design/apply/repair/migrate/loop/status
+roll loop on        # AI starts executing BACKLOG on a configurable schedule
+roll loop status    # check scheduler state and recent cycles
+roll loop watch     # optional: CLI-first live view of the current cycle
+```
+
+## How It Works
+
+Roll runs as a V4 Supervisor execution system:
+
+- **Supervisor** — project-level observe/advise role. It reads backlog, merge truth, open PRs, scoped role bindings, repeated failures, release readiness, and owner questions. It coordinates across Stories; it never implements a Story or overrides evidence gates.
+- **Delta Unit** — one Story delivered through `design` when needed, then `execute`, and, when configured, `evaluate`.
+- **Roles and bindings** — `supervise`, `design`, `execute`, and `evaluate` are stable roles. The concrete agent and optional model are resolved from `Scope -> Role -> Binding -> Agent -> Model`. If a requested binding is unavailable, Roll records that and fails loud instead of pretending another agent was used.
+- **Loop** — on a configurable schedule, picks the top story from BACKLOG and executes it in an isolated worktree. CI must pass before anything lands on `main`.
+- **Dream** — at 3am, scans the codebase for dead code, doc gaps, and architectural drift. Queues `REFACTOR-NNN` entries for loop to pick up.
+- **Skills** — remain the capability layer. Roles invoke `$roll-design`, `$roll-build`, `$roll-fix`, `$roll-peer`, `$roll-.qa`, and other skills.
+
+You set goals, review PRs, and run releases. Everything in between is Roll.
+
+## Operating Modes
+
+Roll has two modes over the same backlog, route profile, evidence, Evaluator,
+and release gates. `guided` means the owner asks `roll supervisor status/next/why`
+and explicitly starts work, usually with `roll loop go --cards <id>`.
+`autonomous` means `roll loop on` has installed the scheduler, so eligible Todo
+work may run within the existing gates. `roll loop pause` / `roll loop off`
+return control to guided operation; `roll loop resume` / `roll loop on` switch
+back explicitly.
+
+### Onboarding Samples
+
+**New project from zero**
+
+```bash
+mkdir my-product && cd my-product
+roll init
+roll next
+roll design --from-file .roll/brief.md
+roll loop on
+```
+
+Start with a short requirement, PRD, or notes. Roll explains the next design step instead of silently creating fake work; Designer creates the backlog, Supervisor picks `standard`, `verified`, or `designed` execution per Story, and the owner reviews story-scoped attest evidence.
+
+**Existing project**
+
+```bash
+cd existing-codebase
+roll init
+roll next
+roll init --apply
+roll loop on
+```
+
+Roll diagnoses current code without destructive migration, creates or updates Roll metadata after review, and then reasons over the existing backlog/docs/context. Inspect state through CLI-first observability: `roll status`, `roll loop watch`, `roll loop runs`, `roll loop cycle <id>`, alerts, and story reports.
+
+**Scoped role routing**
+
+```yaml
+schema: roll-agents/v1
+defaults:
+  story:
+    roles:
+      execute:
+        candidates: [kimi, codex]
+      evaluate:
+        candidates: [pi, reasonix]
+```
+
+Runtime availability is explicit. Unavailable agents are recorded as unavailable; role resolution is fail-loud, not silent substitution.
+
+## Features
+
+### Autonomous Execution
+
+- `roll loop on` — AI picks stories from BACKLOG and executes on a configurable schedule in an isolated worktree `[core]`
+- `roll loop status` — scheduler snapshot, recent cycles, queue, alerts, and cost `[core]`
+- `roll loop watch` — default read-only live status; use `--events` for compact events and `--raw-events` only for audit/debug `[highlight]`
+- `roll loop pause / resume` — hand-code yourself; let AI resume when you're done
+
+### Quality Gates
+
+- Peer Review — a second AI agent challenges the plan or diff before any risky build `[core]` `[highlight]`
+- Self-Review — post-commit self-check on each micro-commit
+- Acceptance Check — ACs verified against story definition after every build
+- CI Gate — loop waits for green CI; red CI halts the loop and writes an alert `[core]`
+- TCR Discipline — no commit without passing tests; zero-diff commits revert automatically `[core]`
+
+### Nightly Dream
+
+- Code Health Scan — detects dead code, architectural drift, over-engineering candidates `[highlight]`
+- Doc Coverage — flags missing guides, stale docs, undocumented ENV vars
+- REFACTOR Queue — writes REFACTOR-NNN entries to BACKLOG for loop to pick up next morning
+
+### Story Lifecycle
+
+- `$roll-idea` — one-liner capture: instant FIX or IDEA backlog entry `[core]`
+- `roll design` / `$roll-design` — DDD-backed planning: clarify → design → split into INVEST stories. `roll design` launches the skill in your AI agent from the command line and renders detailed designs as a self-contained Design Review Page. `[core]`
+- `$roll-build` — Builder role execution: TCR story execution → worktree → PR → evidence `[core]`
+- `$roll-fix` — fast-path bug fix, same CI gate, lighter ceremony
+- Evaluator role — independent review, visual evidence checks, score/attest contracts where the execution profile requires it
+
+### Observability
+
+- `roll status` — verdict-first truth summary (LOOP · CYCLE · RELEASE · STORY with attest coverage), then convention/AI-client sync health `[core]`
+- `roll loop watch` — CLI-first live activity stream for the current cycle
+- `roll loop cycle <id>` — one cycle's trace and evidence pointers
+- `roll loop runs` — per-cycle TerminalOutcome history with TCR count and duration
+- `roll loop alert` — view, acknowledge, and clear loop alerts
+- Acceptance Review Page — the Story's own `latest/<id>-review.html` is the human acceptance entry `[highlight]`
+
+### Current Observability
+
+The current product is CLI-first. `roll status`, `roll loop watch`, `roll loop runs`, `roll loop cycle <id>`, `roll status pulse`, alerts, and story-scoped attest reports are the active truth surfaces. the archive rebuild is an on-demand static archive/repair renderer, useful for CI artifacts and migration reconciliation; it is not the current truth surface.
+
+The three-state delivery ladder still matters: **claimed -> merged -> attested**. A backlog row that says done is only `claimed`; it becomes `merged` when the PR lands on `main`, and `attested` when story-scoped evidence is on file. Use `roll supervisor live` for a one-frame CLI-first multi-role board, or `roll supervisor live --watch` to keep that board refreshing in-place; browser/TUI Supervisor Live Console remains future work.
+
+### On-Demand Skills
+
+- `$roll-debug` — mount a diagnostic probe, trace root cause, auto-fix if source-traceable
+- `$roll-doc-audit` — check docs/site/help against implementation; index gaps and draft missing docs
+- `$roll-doctor` — diagnose the dev toolchain: node, npm, git, AI tools
+- `$roll-notes` — capture a development moment in narrative form
+
+### Multi-Agent
+
+- Fail-loud Routing — requested agent/model/rig unavailable → record the limit and pause or route only through an explicit fallback policy `[highlight]`
+- `$roll-peer` — multi-round negotiation; the structured adapter records one-shot reviewer facts `[core]`
+- PR Inbox — external PRs get AI review before merge; stale PRs auto-rebase `[new]`
+- `roll review-pr` — on-demand AI review for any PR, any agent `[new]`
+
+## Project Structure
+
+Roll 2.0 keeps the project root clean. All Roll-managed artifacts live under
+`.roll/`:
+
+```
+my-project/
+├── AGENTS.md            # engineering constraints (root-level — agents read this first)
+├── README.md            # product front door
+├── src/  tests/         # your code
+└── .roll/               # everything Roll touches
+    ├── backlog.md       # Story / Fix / Refactor index
+    ├── features/        # per-Story AC + plan docs
+    ├── domain/          # DDD models, context map
+    ├── briefs/  dream/  # autonomous-layer output
+    └── decisions/       # ADRs
+```
+
+Upgrading a pre-2.0 project? See [migration-2.0.md](migration-2.0.md) —
+`npx @seanyao/roll@2 migrate` moves `BACKLOG.md`, `docs/features/`, and
+`docs/domain/` into the new layout in one pass.
+
+## Choosing an Adoption Mode
+
+Roll supports three adoption patterns. Pick the one that fits your starting
+point — see [patterns/](patterns/README.md) for the decision tree:
+
+- **Seed** — empty directory + a product vision. Roll is native from day one.
+- **Graft** — existing project, zero-invasion. `$roll-onboard` reverse-engineers
+  `.roll/` from what's already there. See [legacy-onboarding.md](legacy-onboarding.md).
+- **Replant** — heavy legacy debt. Reverse-engineer the spec, then rebuild on
+  the new spec.
+
+## Guide Index
+
+| Topic | Document |
+|-------|----------|
+| First working project | [getting-started.md](getting-started.md) |
+| Scheduling, subcommands, tmux visibility | [loop.md](loop.md) |
+| Governed tool registry and policy | [tools.md](tools.md) |
+| Nightly code health and REFACTOR generation | [dream.md](dream.md) |
+| Cross-agent review protocol | [peer.md](peer.md) |
+| Complete skill catalog | [skills.md](skills.md) |
+| Adoption patterns (seed / graft / replant) | [patterns/](patterns/README.md) |
+| Onboarding an existing codebase | [legacy-onboarding.md](legacy-onboarding.md) |
+| Upgrading from pre-2.0 layout | [migration-2.0.md](migration-2.0.md) |
+| Common scenarios and troubleshooting | [faq.md](faq.md) |
+| Environment variable configuration | [configuration.md](configuration.md) |

package/guide/en/pairing.md

@@ -0,0 +1,151 @@
+# Cross-Agent Pairing — heterogeneous second eyes, in the loop
+
+Pairing makes a **different** agent (a different vendor) cross-check your work
+automatically. The primitive is the **pair**, not the review: a working agent
+delivers, and a heterogeneous peer reviews it for perspective diversity. A code
+bug that one model's blind spot hides, another model's catches.
+
+Roll treats reviewer assignment as the `evaluate` role in the scoped Agent
+model: `Scope -> Role -> Binding -> Agent -> optional Model`. The agent is the
+finite seven-name identity (`claude`, `kimi`, `codex`, `pi`, `agy`, `reasonix`, `cursor`);
+the model is optional data carried by that agent.
+
+Pairing is distinct from [`$roll-peer`](peer.md): peer is an on-demand,
+multi-round negotiation you (or the loop's risk gate) trigger; pairing is an
+always-available, one-way second pass wired into the cycle and governed by the
+Project Scope `evaluate` binding.
+
+## Turning it on — explicit, never silent
+
+```bash
+roll agent                         # inspect story.evaluate
+roll agent migrate --dry-run       # convert legacy pairing.yaml if present
+```
+
+New projects should author the evaluator pool in `.roll/agents.yaml`:
+
+```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` remains a legacy compatibility input. When both files are
+present, the scoped `evaluate` role is preferred. Static config lists fair
+candidates; runtime auth/network/VPN/account failures skip candidates only for
+the current resolution.
+
+## Seeing what it does — observability
+
+Loop cycle evidence and role views show the pool (who can pair, their vendor,
+declared capability, and **why** an agent is excluded), plus **how much pairing
+has cost**:
+
+```
+  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
+```
+
+Cost is recorded on every pairing from day one — you always know what the
+second pair of eyes is spending, even without budget-adaptive throttling.
+
+## How selection works
+
+When a stage fires, the selector keeps **only** agents that are installed,
+available, declared capable for that stage, able to run as a headless reviewer,
+and a **different vendor** from the working agent — then rotates among them
+(seeded by the cycle id, so it is replayable). Agents with a track record are
+gently preferred (ε-greedy, ε≈0.2), but exploration is always preserved so no
+single pair monopolizes. If no qualified heterogeneous peer exists, that absence
+is itself recorded (`pair:none-available`) — never a silent skip.
+
+## Safety — pairing never blocks a cycle
+
+- **30s hard timeout** on the peer review (belt-and-braces in the executor), so
+  a slow peer never stalls the cycle.
+- **Non-blocking**: a timeout, error, or missing peer is recorded and the cycle
+  proceeds. Pairing is an enhancement, never a gate.
+- **Never touches main on its own**: pairing produces evidence and events, not
+  merges.
+
+## Events & evidence
+
+Each pairing emits `pair:selected`, then `pair:verdict` (with the verdict,
+findings count, cost, and stage) or `pair:none-available`. The verdict is also
+written as evidence under the run's `peer/cycle-<id>.pair.json`. A score
+pairing emits `pair:score` (score, verdict, cost) and writes
+`peer/cycle-<id>.score.pair.json`.
+
+## Stages
+
+`code` and `score` are the defaults — a heterogeneous peer reviews the
+delivered diff, and another scores the finished cycle. `design`, `test`, and
+`cycle` extend the same mechanism to other checkpoints; enable them in
+`stages` when you want earlier or broader second eyes.
+
+## Review Score — a peer grades the cycle, never the author
+
+An agent grading its own delivery is a conflict of interest, so the cycle's
+quality score — the **Review Score** — is always produced by a Reviewer in a
+**fresh, separate session**, never by the building agent (the agent does NOT
+self-score):
+
+- **In the loop**: after the acceptance gate passes, the runner casts a
+  fresh-session Reviewer to score the delivery. The note lands in the card's
+  `notes/` with provenance — `scoring: pair`, `scored-by: <agent>`, and the
+  fresh-session id (so independence is verifiable).
+- **Loop delivery**: after the acceptance gate passes, the runner triggers the
+  same adapter from a fresh session.
+- **Design output** (`roll-design`, no loop cycle): the design workflow can
+  trigger a fresh-session Reviewer to grade the **design** (INVEST split,
+  visual-AC completeness, `deliverable_url` correctness, domain/spec
+  consistency) — not code. It stamps the score `stage=design`. The designing
+  agent triggers but never grades its own work; no peer available → honest
+  unscored (fail-loud), never a self-grade.
+- **The builder's own agent never scores its own cycle when an independent peer
+  exists**: whenever any other agent is installed, the builder is excluded from
+  the score pool entirely — an independent Evaluator grades the delivery or the
+  cycle fails loud (no self-score fallback, even from a fresh same-vendor
+  session). The builder's own agent is the scorer **only** in a true
+  single-agent install, where a fresh same-vendor session is the minimum
+  acceptable independence. Independence is still verified by session id (a
+  different `agent × model × session` rig is encouraged), so the single-agent
+  case never deadlocks.
+  A score sharing the builder's session — including any sub-agent of it — is
+  rejected as a self-score. No independent candidate, a timeout, or a
+  protocol miss does **not** fall back to a self-score; the absence is audited
+  via a `pair:none-available` event and the story owes a fresh-session Review
+  Score before it can attest (`review_score_missing`).
+- **Real agent output is normalized before scoring**: an Evaluator's reply is
+  accepted even when its stdout carries terminal control bytes, ANSI startup
+  banners, a JSONL stream-json wrapper, or a bullet/markdown prefix — the parser
+  normalizes these away, then still requires one complete, in-order
+  `SCORE`/`VERDICT`/`RATIONALE` block (score 1..10, supported verdict). Prose
+  that merely mentions the markers is still rejected.
+- **Repeated final blocks are tolerated when they agree**: some Evaluators repaint
+  their terminal (so the final block appears twice) or print the reply template and
+  their analysis before the real block. The parser isolates the **final usable
+  block** and accepts it when every valid `SCORE` line agrees and every valid
+  `VERDICT` line agrees — a redraw is a resolved answer. Genuinely conflicting
+  duplicate blocks (different scores or verdicts), template `<placeholder>` echoes,
+  out-of-range scores, and unsupported verdicts are still rejected.
+- **Rejections are observable, not generic**: when a reply is not accepted, the
+  cycle records a specific reason instead of a bare "unparseable". `roll loop cycle
+  <id> --roles` distinguishes an Evaluator that **returned score-like text but was
+  not accepted** (e.g. conflicting duplicate blocks, a missing field) from one that
+  **returned no score content** at all, with the precise reason on the role line.

package/guide/en/patterns/README.md

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

@@ -0,0 +1,110 @@
+> Mirror of the original Chinese source — English translation pending. See IDEA-NNN for translation status.
+
+# 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 reports |
+
+**`.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
+- Long-lived bash 工具链，装 Roll 给文档新鲜度做 dream 巡检
+- 任何已有 `git log` 但缺方法论的项目