@seanyao/roll 4.630.2 → 4.702.2

package/guide/zh/feedback.md

@@ -0,0 +1,30 @@
+# 反馈与 issue 入口
+
+Roll 把两条反馈路径分开：
+
+- 输入应该进入本地 Roll backlog 时，用 `roll idea "<一句话>"`。
+- 输入属于公开仓库或跨项目 tracker 时，直接用 `gh issue create`。
+
+## 本地 Roll backlog
+
+```bash
+roll idea "Safari 登录在 session cookie 过期后失败"
+roll idea "给 Story 报告归档加暗色主题"
+```
+
+`roll idea` 会分类、分配下一个 ID、推断 epic、铸卡夹、追加 backlog 行并刷新索引。
+这是项目 owner 把零散反馈变成 Roll 工作项的常规入口。
+
+## GitHub Issues
+
+公开 bug 或外部协作直接走 GitHub：
+
+```bash
+gh issue create \
+  --repo owner/repo \
+  --title "Safari 登录失败" \
+  --body "复现步骤：1. ... 2. ..."
+```
+
+如果项目看板会把 issue 回流进 Roll backlog，可以按需加 `bug`、`idea`、
+`enhancement`、`FIX`、`US` 等 labels。

package/guide/zh/getting-started.md

@@ -0,0 +1,96 @@
+# Roll — 快速上手
+
+这条路径把一个 git 项目从安装带到验收报告，目标是 5 分钟内跑通第一条
+Roll 管理的故事。
+
+## 1. 安装
+
+```bash
+curl -fsSL https://seanyao.github.io/roll/install | bash
+# 或
+npm install -g @seanyao/roll
+```
+
+Roll 需要 Node.js 22 或更新版本，并且本机至少装好一个支持的 AI agent。
+
+## 2. 初始化项目
+
+```bash
+cd your-project
+roll setup
+roll init
+```
+
+`roll init` 会先诊断当前目录，再决定是否写文件。空项目走新项目骨架；已有
+代码库走 `$roll-onboard`；只有 PRD/文档的目录会被当成新项目并指向设计；
+部分 Roll 或旧 Roll 布局只打印修复/迁移建议，不直接改文件。
+
+## 3. 从需求到 Backlog
+
+如果你手头有需求文档（PRD、草图、笔记）但还没有源码，`roll init` 会把它识别
+为 PRD-only 新项目并指向设计。已有 Roll 骨架但 backlog 为空时，`roll status`
+和 `roll doctor` 仍会提示进入设计阶段。
+
+想立刻开始设计对话：
+
+```bash
+roll design --from-file docs/PRD.md
+```
+
+如果 `roll init` 检测到 PRD，就使用它打印出来的那条
+`roll design --from-file ...` 命令；没有文件时，`roll design` 仍会在你的 AI
+agent 里拉起同一个 `roll-design` 技能。你描述领域模型，agent 把 INVEST 故事写入
+`.roll/backlog.md`，详细设计会生成自包含的 `design-review.html` Design Review Page，
+然后 `roll loop` 接过去接着干。
+
+你也可以直接在 agent 里跑 `$roll-design`，效果一样。
+
+如果你心里已经有故事，只想快速加一条，跳到第 4 步。
+
+## 4. 写第一条 Backlog
+
+用一句话建一张小故事卡：
+
+```bash
+roll idea "Add a health check endpoint"
+```
+
+`roll idea` 自动分类、取号、推断史诗、建卡片文件夹 — 一步完成待办行和故事文件夹。
+
+然后编辑 `.roll/features/<史诗>/<ID>/spec.md`，把 AC 写清楚。
+
+第一条故事要小：一个可见行为，一条明确测试路径。
+
+## 5. 启动 Loop
+
+```bash
+roll loop on
+roll loop status
+```
+
+`roll loop status` 是常用快照视图。若当前有 cycle 在跑，并且你想看实时视图，
+先用只读 watch 命令：
+
+```bash
+roll loop watch
+```
+
+排查事件用 `roll loop watch --events`，只有需要原始审计 JSON 时才用
+`roll loop watch --raw-events`。所有 watch 模式都是只读；Ctrl-C 只停止视图。
+
+如果不想等调度触发，可以手动跑一轮：
+
+```bash
+roll loop now
+```
+
+## 6. 生成验收报告
+
+故事落地、backlog 行变成 `✅ Done` 后，生成离线验收报告：
+
+```bash
+roll attest US-DEMO-001
+```
+
+报告会写进该故事的 `.roll/features/` 文件夹。发布前，每条 AC 都应有 verdict
+和证据链接。

package/guide/zh/installation.md

@@ -0,0 +1,83 @@
+# Roll — 安装与更新
+
+## 安装
+
+### curl（推荐）
+
+```bash
+curl -fsSL https://seanyao.github.io/roll/install | bash
+```
+
+仅需 bash 3.2+、curl、tar —— macOS 和 Linux 预装即可，无需 Node.js。
+
+钉版本：
+
+```bash
+curl -fsSL https://seanyao.github.io/roll/install | ROLL_VERSION=v3.610.1 bash
+```
+
+### npm
+
+```bash
+npm install -g @seanyao/roll
+```
+
+需要 Node.js 16+。
+
+无论哪种方式安装，完成后运行 setup 将约定和技能同步到你的 AI 工具：
+
+```bash
+roll setup
+```
+
+## 验证
+
+```bash
+roll --version   # 显示已安装版本
+roll status      # 显示路径和约定状态
+```
+
+## 更新
+
+```bash
+roll update
+```
+
+Roll 自动检测安装方式并对应处理：
+
+| 安装方式 | `roll update` 的行为 |
+|---|---|
+| curl（默认） | 重新下载最新 tarball、原子替换，然后 `roll sync` |
+| npm | `npm update -g @seanyao/roll`，然后 `roll sync` |
+| git clone（贡献者） | 在包目录执行 `git pull`，然后 `roll sync` |
+
+## 自动版本提示
+
+每次 `roll` 命令结束后，后台静默查询 GitHub releases API（每 24 小时最多一次，缓存在 `~/.roll/.update-check`）。若有新版本，下一条命令结束时显示一行提示。检查完全异步，不影响命令速度。
+
+## 卸载
+
+### curl
+
+```bash
+rm -rf ~/.local/share/roll ~/.local/bin/roll
+```
+
+### npm
+
+```bash
+npm uninstall -g @seanyao/roll
+```
+
+不再需要时删除状态文件：
+
+```bash
+rm -rf ~/.roll ~/.shared/roll
+```
+
+## 另见
+
+- [overview.md](overview.md) — roll 是什么
+- [project-setup.md](project-setup.md) — 新项目的 `roll init`
+- [configuration.md](configuration.md) — 环境变量
+- [SECURITY.md](../../SECURITY.md) — curl|bash 信任边界与版本钉住

package/guide/zh/legacy-onboarding.md

@@ -0,0 +1,192 @@
+# 已有代码库接入 Roll
+
+> 在现有代码库上接入 Roll，不破坏你团队现有的工作流。
+
+本页继续保留 `legacy-onboarding.md` 路径以保证旧链接稳定；可见流程名称统一为
+**已有代码库接入 Roll**。
+
+如果你有一个已经运行了一段时间的真实项目——有代码、有测试、有历史、有约定——想开始用 Roll 管理它，这是你要走的路径。
+
+## 三种接入模式
+
+| 模式 | 适用场景 | 取舍 |
+|------|---------|------|
+| **Seed**（播种） | 新项目从零开始 | 摩擦最低，day 1 就有 specs/backlog |
+| **Graft**（嫁接，本页） | 活跃的已有代码库，还在演化 | 零侵入原代码，Roll 在上层叠加 |
+| **Replant**（翻种） | 想清债、重写一次 | 工作量大，需要先反推规格 |
+
+本页讲 **graft**。关于 seed / replant，见 [接入模式文档](https://github.com/seanyao/roll-meta)（维护者私有仓，README 有公开摘要）。
+
+## Graft 做了什么
+
+- **读**你的项目，理解类型、领域、关键模块
+- **问**你 9 个问题，3 分钟内完成
+- **生成** `.roll/` 目录，与原代码并列（不动你的源文件）
+- **同步**Roll 约定到你用的 AI 工具
+- 你得到的项目同时拥有：原来的工作流 + Roll 的项目管理能力
+
+Graft 是**完全可逆**的：跑 `roll setup offboard` 让 Roll 自己撤销它加进来的全部痕迹（见下文"怎么退出"）。
+
+## 分步操作
+
+### 1. 安装 Roll
+
+```bash
+curl -fsSL https://seanyao.github.io/roll/install | bash
+```
+
+或通过 npm：
+
+```bash
+npm install -g @seanyao/roll@latest
+```
+
+然后：
+
+```bash
+roll setup
+```
+
+### 2. 在项目里跑 `roll init`
+
+```bash
+cd your-project
+roll init
+```
+
+Roll 会检测到这是已有代码库且尚未接入 Roll（有源码/清单文件，但没有当前 Roll 标记），打印类似：
+
+```
+Detected: existing codebase without Roll
+Recommended path: agentic-onboard
+Facts:
+  - manifests: package.json
+  - source dirs: src
+  - test dirs: tests
+  - source files: 47
+  - Roll markers: none
+  - facts hash: sha256:...
+Next: $roll-onboard
+Agent status: available: claude, codex
+Run `$roll-onboard` with an available agent, review the artifacts, then run `roll init --apply`.
+No files changed.
+```
+
+### 3. 在 AI agent 里跑 `$roll-onboard`
+
+打开你想用的 agent（Claude Code、Codex CLI、Cursor 等），运行：
+
+```
+$roll-onboard
+```
+
+技能会：
+1. 浏览你的仓库，告诉你它看到的项目结构
+2. 第一组 3 问：确认推断的项目类型 / 领域 / 关键模块
+3. 第二组 3 问：要生成哪些 `.roll/` 产物，哪些现有文档要 include 而非重新生成
+4. 第三组 3 问：`.gitignore`、AI 工具同步、loop 启用与否
+5. 只写两个结构化产物：`.roll/init-diagnosis.yaml` 和 `.roll/onboard-plan.yaml`
+
+总耗时：3 分钟以内。
+
+### 4. 应用 plan
+
+回到终端，先审阅 `.roll/init-diagnosis.yaml` 和 `.roll/onboard-plan.yaml`，然后执行：
+
+```bash
+roll init --apply
+```
+
+这一步会先校验成对的 diagnosis / plan 产物，任何写文件之前先拒绝不支持的 schema 版本、过期或 stale 的 facts hash、非幂等 file operation、路径穿越和 shell-command key。
+
+校验通过后，Roll 会打印 apply 审阅检查点：表格列出每个计划操作的动作、目标路径、
+合并/创建模式，以及是否保留用户内容。在交互终端里，确认前不会写入任何已审阅的变更。
+
+如果是在非交互自动化里执行，审阅后要显式确认：
+
+```bash
+roll init --apply --auto
+```
+
+校验通过后，Roll 会：
+- 按你选的 scope 创建 `.roll/` 子目录
+- 如果选了"生成 backlog"，写入初始 `.roll/backlog.md`
+- 你标记 include 的现有文档不会被覆盖
+- 如果 Q7 说 yes，把 `.roll/` 加入 `.gitignore`
+- 把 Roll 约定同步到你选的 AI 工具
+
+完事。执行 `roll next` 接续下一步。
+
+### 5.（可选）启动自治 loop
+
+如果 Q9 选了 yes，`roll loop on` 会按定时表激活 loop，自动从 `BACKLOG.md` 拉 `📋 Todo` 任务，跑 `$roll-build` / `$roll-fix`。
+
+## Graft 的边界
+
+Roll 只动它**自己的**文件：
+
+| Roll 会动 | Roll 不会动 |
+|----------|------------|
+| `.roll/`（全部） | `src/`、`lib/`、`tests/` 等你的代码 |
+| `AGENTS.md`（不存在则创建，存在则 section 级合并） | `README.md` |
+| `.gitignore`（仅当 Q7 说 yes） | `package.json`、`pyproject.toml` 等 |
+
+如果你已有 `CONTRIBUTING.md` 或 `.github/` workflow，Roll 不会碰它们。如果想把 Roll 工作流接到现有 CI，需要你后续手动配置。
+
+`$roll-onboard` 自己的边界比 `roll init --apply` 更窄：agent 只能写 `.roll/init-diagnosis.yaml` 和 `.roll/onboard-plan.yaml`。`AGENTS.md`、`.gitignore`、backlog、features、docs、offboard changeset 都由 apply 命令负责。
+
+## 怎么退出
+
+`roll init --apply` 会把 Roll 管理的文件、目录、合并 marker 区块、`.gitignore` 行都记到 `.roll/onboard-changeset.yaml`。重复执行同一个 plan 会保留并去重这份 metadata，不会丢掉第一次 apply 的 offboard 记录。如果 apply 中途失败，先检查 changeset，再在确认后运行 `roll setup offboard --confirm` 回滚 Roll 管理的产物。
+
+已有 `AGENTS.md` 会被保留。Roll 只会在稳定的 `<!-- roll:onboard:start -->` / `<!-- roll:onboard:end -->` marker 中追加自己管理的区块，之后 offboard 只剥离这些区块。
+
+**先预演（默认）：**
+
+```bash
+cd your-project
+roll setup offboard
+```
+
+这是 dry-run，不会真的删除。输出会列出清单中记录的所有产物，以及将要从 `.gitignore` 撤销的行。
+
+**确认后执行：**
+
+```bash
+roll setup offboard --confirm
+```
+
+Roll 不创建的文件 / 目录原封不动；已有用户文件里的 Roll marker 区块会被剥离，但文件本身不会被删除；你自己加到 `.gitignore` 的内容也保留。执行成功后，清单文件本身也会被删除。
+
+安全保障：
+
+- 找不到 `.roll/onboard-changeset.yaml`（比如较早版本的 Roll 没记录、或者这个项目从没跑过 `roll init --apply`），`roll setup offboard` 拒绝执行，并打印手动 `rm` 命令，不会自己猜。
+- 如果清单里的路径不在当前项目根目录下（跨项目串路径），`roll setup offboard` 也拒绝执行，并提示你切到正确目录再跑。
+
+**完全卸载（全机器）：**
+
+```bash
+roll setup offboard --confirm
+npm uninstall -g @seanyao/roll
+```
+
+项目回到接入前的状态。
+
+## FAQ
+
+**Q: 没装 AI agent 怎么办？**
+至少装一个。Claude Code、Codex CLI、Cursor 都可以——安装免费，AI 调用走你的账户消耗 token。
+
+**Q: 已经有从别的工具来的 `BACKLOG.md` 怎么办？**
+Roll 会检测为 pre-2.0 Roll 项目（不是已有代码库接入目标），让你跑 `npx @seanyao/roll@2 migrate`。如果文件来自完全不同的工具，先重命名（`mv BACKLOG.md old-backlog.md`）再跑 `roll init`。
+
+**Q: roll-onboard 推断的项目类型不对，怎么改？**
+在对话里告诉它。第一组 3 问就是为了让你纠正。Skill 把纠正后的理解写进 plan，bash 信任 plan。
+
+**Q: 能手动编辑 `.roll/onboard-plan.yaml` 吗？**
+可以，但要和 `.roll/init-diagnosis.yaml` 配套。`roll init --apply` 要求两边的 `factsHash` 一致，并会重新计算当前项目 facts hash；同时不允许 shell-command key，`file_operations` 只能声明那两个位于项目内且幂等的允许文件。超过 24 小时、相对当前项目已 stale，或由旧版 `$roll-onboard` 生成的 plan，都应该重新生成。
+
+手动改过的 plan 仍然会进入同一个审阅检查点；没有交互确认或显式 `--auto` 时，不会修改文件。
+
+**Q: 我们团队用 GitHub Issues / Jira / Linear，Roll 会替代它们吗？**
+不会。Roll 的 `BACKLOG.md` 是给 AI loop 自治执行用的。你团队的外部 tracker 继续用。有的团队只把"AI-loop 能执行的 story"放 Roll，纯人工任务留在原 tracker。

package/guide/zh/loop-data-layout.md

@@ -0,0 +1,236 @@
+# Loop 数据布局（Phase 2.0）
+
+From Phase 2.0 onward, a project's loop runtime data lives inside the project at
+`<project>/.roll/loop/`.
+
+从 Phase 2.0 起，项目自己的 loop 运行时数据搬进了**项目目录** `<project>/.roll/loop/`，
+不再放在家目录下。只有机器级的绑定文件（launchd runner、attach 脚本）留在
+`~/.shared/roll/loop/`。
+
+Move the project, the state moves with it; delete it, the state goes too.
+
+项目挪走，状态跟着走；项目删掉，状态也一起没了。`git status` 和你的 IDE 能在代码
+旁边看到 loop 的控制与数据文件。
+
+---
+
+## `<project>/.roll/loop/` 里有什么
+
+What lives in `<project>/.roll/loop/`:
+
+`<project>/.roll/loop/` 里放什么：
+
+| 文件 | 平面 | 内容 |
+|------|------|------|
+| `state-<slug>.yaml` | 控制 | 当前/最近一次运行：状态、故事 ID、Agent、run_id |
+| `ALERT-<slug>.md` | 控制 | 累积的告警（失败、TCR 违规） |
+| `PAUSE-<slug>` | 控制 | 暂停标记（由 `roll loop pause` 创建） |
+| `mute-<slug>` | 控制 | 项目级 auto-attach 静音标记 |
+| `.LOCK-<slug>` | 控制 | 本项目的单实例锁 |
+| `heartbeat` | 控制 | 当前 cycle 的存活时间戳 |
+| `runs.jsonl` | 数据 | 只追加的运行历史（每次 cycle 一行 JSON） |
+| `events.ndjson` | 数据 | 逐 cycle 事件流（phase_start/phase_end…） |
+| `cron.log` | 数据 | 旧的聚合 cycle 日志（见下方弃用说明） |
+
+The control plane and the data plane ship independently but both resolve to this
+project-local directory.
+
+控制平面（outer runner 在 spawn tmux 之前接触的）和数据平面（inner cycle 脚本写
+入的）各自独立演进，但现在都解析到同一个项目本地目录。
+
+---
+
+## Dream 的 cron 日志
+
+`roll-.dream`（每晚代码健康扫描）的 cron stdout 捕获日志也改为项目本地：
+
+| 服务 | 路径 |
+|------|------|
+| dream | `<project>/.roll/dream/cron.log` |
+
+以前放在 `~/.shared/roll/dream/cron-<slug>.log`。项目本地后，删项目即
+清日志，并发项目也不会互相穿插。
+
+`roll-.dream` (the nightly code-health scan) also writes its cron stdout capture
+project-local:
+
+| Service | Path |
+|---------|------|
+| dream | `<project>/.roll/dream/cron.log` |
+
+Previously this lived in `~/.shared/roll/dream/cron-<slug>.log`.
+Moving it project-local means it is naturally garbage-collected when
+the project is deleted, and concurrent projects never interleave.
+
+---
+
+## `~/.shared/roll/loop/` 还剩什么
+
+What is left in `~/.shared/roll/loop/`:
+
+`~/.shared/roll/loop/` 现在只剩：
+
+| 文件 | 为什么留着 |
+|------|-----------|
+| `run-<slug>.sh` / `run-<slug>-inner.sh` | launchd `WorkingDirectory` / `ProgramArguments` 绑定绝对家目录路径 |
+| `attach-<slug>.command` | LaunchServices 双击目标，必须是稳定家目录路径 |
+| `worktrees/` | 机器级临时区，非项目本征 |
+| `changelog-audit*` | 机器级审计日志 |
+| `archived/` | `roll loop gc` 退役 slug 的停车场 |
+
+The global mute switch `~/.shared/roll/mute` also stays in home — it is
+machine-wide on purpose.
+
+全局静音开关 `~/.shared/roll/mute`（所有项目、所有自动化活动共享）也留在家目录 ——
+它本来就是机器级的。
+
+---
+
+## 跨项目 dashboard
+
+`roll loop runs --all` aggregates per-project files live instead of reading one
+machine-wide file.
+
+`roll loop runs --all` 不再读单个机器级的 `runs.jsonl`，而是：
+
+1. Enumerate slugs from launchd plists.
+2. Resolve each slug to its project, read its `.roll/loop/runs.jsonl`.
+3. Merge with `jq`, sort by timestamp.
+
+1. 从 launchd plist 枚举已安装的 slug。
+2. 把每个 slug 解析到它的项目路径，读该项目的 `.roll/loop/runs.jsonl`。
+3. 用 `jq` 把所有项目的行归并，按时间排序。
+
+You still get a machine-wide overview, computed live — no central file to drift.
+
+所以你照样能看到机器级总览，只是改为从各项目文件实时聚合 —— 没有会失同步的中心文件。
+
+The cache hook `ROLL_LOOP_RUNS_CACHE_TTL` (default `0`) is reserved for future
+use.
+
+可选缓存钩子 `ROLL_LOOP_RUNS_CACHE_TTL`（默认 `0` = 不缓存）为未来预留；目前是实时
+聚合。
+
+---
+
+## 自动迁移（7 天双路窗口）
+
+If you upgrade an existing project you do not need to do anything.
+
+如果你升级一个既有项目，**无需任何手动操作**。outer runner 会在下一个 cycle 自动
+迁移老文件。
+
+**How it works:**
+
+**工作原理：**
+
+1. Before reading control state, `旧路径迁移 helper <slug>` copies
+   `state` / `ALERT` / `PAUSE` / `mute` from home into the project, then renames
+   each legacy file `<name>.migrated-<timestamp>`.
+2. `旧运行记录迁移 helper` splits the machine-wide `runs.jsonl` by each
+   row's `project` slug into each project's file, then renames the legacy file.
+   Unresolvable rows are left behind so no history is lost.
+3. Migration is idempotent and never overwrites a newer target.
+
+1. 读控制状态之前，`旧路径迁移 helper <slug>` 把 `state` / `ALERT` /
+   `PAUSE` / `mute` 从家目录复制进项目，再把每个老文件改名为
+   `<name>.migrated-<时间戳>`。
+2. `旧运行记录迁移 helper` 把机器级 `runs.jsonl` 按每行的 `project` slug 拆
+   分进各项目文件，再把老文件改名。无法解析的行留在原处，不丢历史。
+3. 迁移幂等，已存在的更新目标永不被覆盖。
+
+**During the 7-day window**, control-plane reads use dual-path lookup
+(`控制状态路径解析器`): project-local first, legacy home as fallback. A
+separate FIX removes the fallback afterward.
+
+**在 7 天窗口期内**，控制平面文件的读取走双路查找（`控制状态路径解析器`）：
+优先项目本地路径，回退到家目录老路径。窗口结束后由单独的 FIX 移除回退。
+
+The `.migrated-*` artifacts are reaped by `roll loop gc` after they age out.
+
+`.migrated-*` 和 `runs.jsonl.migrated-*` 残骸到期后由 `roll loop gc` 回收，家目录不
+会堆积。
+
+---
+
+## `roll loop gc` — 垃圾回收
+
+`roll loop gc` retires slugs whose project directory no longer exists and sweeps
+debris.
+
+`roll loop gc` 退役那些项目目录已不存在的 slug，并清扫迁移/备份残骸。
+
+```bash
+roll loop gc                  # 回收孤儿 slug + 残骸（默认保留 30 天）
+roll loop gc --dry-run        # 预览将清理什么 —— 不动任何文件
+roll loop gc --keep-days 14   # 本次覆盖保留期
+```
+
+**What it cleans:**
+
+**它清什么：**
+
+- Orphan slugs → moved to `~/.shared/roll/loop/archived/<slug>-<timestamp>/`,
+  launchd plist booted out first.
+- `runs.jsonl.tmp.*` write-interrupted leftovers.
+- `backup-before-merge-*.tgz` older than 5 days.
+- `*.migrated-<ts>` markers older than 7 days.
+
+- 孤儿 slug —— `run-<slug>.sh` / `-inner.sh` / `attach-*.command` 移到
+  `~/.shared/roll/loop/archived/<slug>-<时间戳>/`，先 bootout launchd plist。
+- `runs.jsonl.tmp.*` 写中断残留。
+- 5 天前的 `backup-before-merge-*.tgz`。
+- 7 天前的 `*.migrated-<时间戳>` 标记。
+
+**Retention precedence** (highest first): `ROLL_LOOP_GC_RETENTION_DAYS` env >
+`loop_gc.retention_days` in `.roll/local.yaml` > default 30 days.
+
+**保留期优先级**（从高到低）：
+
+1. 环境变量 `ROLL_LOOP_GC_RETENTION_DAYS`。
+2. `.roll/local.yaml` 里的 `loop_gc.retention_days`。
+3. 默认 30 天。
+
+`--dry-run` lists the plan without executing — safe anytime.
+
+`--dry-run` 列出完整计划但不执行 —— 随时可放心运行。
+
+---
+
+## 排查
+
+**Where did my ALERT go?**
+
+**我的 ALERT 跑到哪去了？**
+
+It is now at `<project>/.roll/loop/ALERT-<slug>.md`. Run `roll loop alert` inside
+the project.
+
+现在在 `<project>/.roll/loop/ALERT-<slug>.md`。在项目里跑 `roll loop alert`，或直
+接打开文件。
+
+**How do I migrate manually?**
+
+**怎么手动迁移？**
+
+You never need to — the next cycle does it. To force it, run `roll loop now`
+once.
+
+正常你永远不需要 —— 下一个 cycle 会做。要不等就触发，跑一次 `roll loop now`（或
+`roll loop test`）；runner 在读状态前会先迁移。
+
+**How do I roll back?**
+
+**怎么回滚？**
+
+Legacy files are kept as `<name>.migrated-<timestamp>` for 7 days. Rename one
+back (drop the suffix) and remove the project-local copy. Roll back within the
+window before `roll loop gc` reaps the markers.
+
+老文件以 `<name>.migrated-<时间戳>` 形式保留 7 天。要回退某个文件，把它改名回去
+（去掉 `.migrated-<时间戳>` 后缀）并删掉项目本地副本。7 天后 `roll loop gc` 会回
+收这些标记，所以请在窗口期内回滚。
+
+See also: [roll loop](loop.md) · [Migration 2.0](migration-2.0.md) · [FAQ](faq.md)
+
+另见：[roll loop](loop.md) · [Migration 2.0](migration-2.0.md) · [FAQ](faq.md)