@seanyao/roll 4.630.2 → 4.702.2

package/docs/live-console.md

@@ -0,0 +1,203 @@
+# CLI 实时观察指南 / CLI Live Observation Guide
+
+> roll 的 CLI-first 实时可观测：跟着一个正在跑的 cycle，看它的标准 activity 流，不依赖 web/daemon。
+
+## 这是什么
+
+`roll loop cycle watch` 是 roll 的**一线实时窗口**。它给出一个进行中 cycle 的**归一化 activity 流**——跨 agent（pi/kimi/codex/cursor/claude）一致、同一个词表、同一个渲染。不需要 daemon 或浏览器；终端里直接看。
+
+这是 roll "抹平 agent 差异"灵魂在实时流维度的落地：每种 agent 的 raw stdout 都经 `normalizerFor(agent)` 映射到标准 `ActivitySignal`，下游渲染统一消费。
+
+## 怎么用
+
+### 看当前 running cycle
+
+```bash
+roll loop cycle watch
+```
+
+自动找到当前正在跑的 cycle（最近一条 `cycle:start` 且还没收到 `cycle:end`/`cycle:terminal` 的），用 `tail -F` 跟随 `events.ndjson` 或 `cycle-<id>.signals.jsonl`，实时逐行输出归一化信号。cycle 结束自动退出。
+
+### 看指定 cycle
+
+```bash
+roll loop cycle watch <id>
+```
+
+`<id>` 可以是完整 cycle id（如 `c-abc123`），也可以是截短形式（如 `abc123`），或是 ledger 行号（如 `#123`）。
+
+### 只看一帧
+
+```bash
+roll loop cycle watch --once
+```
+
+回放当前 cycle 的全部已记录信号一帧后退出，不跟随。适合快速扫一眼状态。
+
+```bash
+roll loop cycle watch <id> --once
+```
+
+回放一个已完成（或进行中）cycle 的信号。
+
+### 回放最近 N 行
+
+```bash
+roll loop cycle watch --since 0       # 从头回放 + 跟随（"--since 0" = "all"）
+roll loop cycle watch --since 500     # 回放最近 500 行 + 跟随
+roll loop cycle watch --since 50 --once  # 只回放最近 50 行，退出
+```
+
+### 机器可读输出
+
+```bash
+roll loop cycle watch --json          # JSON 输出：cycleId + storyId + agent + outcome + signals[]
+roll loop cycle watch <id> --once --json  # 单帧 JSON
+```
+
+## 看到什么
+
+### 顶部概要
+
+```
+cycle c-abc12345
+story US-OBS-025
+agent codex
+outcome running
+```
+
+每条信号行格式：`●` 彩色圆点 + tier（层级）+ seg（阶段）+ summary（摘要）。
+
+### 信号类别
+
+| 信号 | tier | 含义 |
+|------|------|------|
+| `lifecycle` | `info` | cycle 生命周期：start / phase change / timeout-reclaim / end / terminal |
+| `tcr` | `info` / `warn` / `error` | TCR 微步：test pass / test fail / commit / revert |
+| `gate` | `info` / `error` | 闸状态：peer gate / attest gate 通过或失败 |
+| `stdout` | `trace` | agent 输出摘要（行数、大小） |
+| `tool_use` | `info` | 工具调用开始（tool id + input 摘要） |
+| `tool_result` | `info` / `error` | 工具调用结果（ok / error + duration） |
+
+### 信号示例
+
+```
+● info     lifecycle  cycle started (pick US-OBS-025)
+  │
+● info     lifecycle  build phase
+● trace    stdout     agent output 42 lines (+2.1KiB)
+● info     tcr        test passed (vitest --changed, 7 suites, 142ms)
+● info     tcr        commit e3a7f2b (tcr: update architecture.md BC7)
+  │
+● info     gate       peer gate passed
+● info     lifecycle  attest phase
+● info     gate       attest gate passed
+  │
+● info     lifecycle  cycle ended (delivered)
+```
+
+### 结局
+
+cycle 结束（或 `--once` 回放完）时输出证据指针：
+
+```
+evidence  PR https://github.com/seanyao/roll/pull/999 · diff https://github.com/seanyao/roll/pull/999/files · story .roll/features/*/US-OBS-025/index.html
+```
+
+## 三流权威边界
+
+`roll loop cycle watch` 的每一条信号来自以下三条流中的**投影流（ActivitySignal）**——这是 keystone 契约：
+
+| 流 | 角色 | watch 怎么看 |
+|---|------|------------|
+| `events.ndjson` | **唯一持久真相** | `cycleActivitySignalsFromEvents()` 将 `RollEvent` 折成 `ActivitySignal`；`tail -F` 跟随新行 |
+| `cycle-<id>.signals.jsonl` | **持久化投影** | 如果文件存在且非空，直接读它（runner 侧 `executor.ts` 已把全量信号写进这个文件） |
+| `live.log` | **debug 附件** | **不显示**——从不参与 watch 窗口渲染 |
+
+**外挂不变量**：watch 窗口只消费 `ActivitySignal`；永不做 per-agent raw stream 解析。添加新 agent = 加一个 `normalizerFor(agent).normalize()`，watch 窗口零改动。
+
+## 静态导出 vs CLI watch
+
+当前产品面是 CLI-first：共享 `collectDossierState` / `cycleActivitySignalsFromEvents` 选择器，不同 CLI 入口读取同一批事实：
+
+| 入口 | 触发 | 更新 | 依赖 |
+|--------|------|------|------|
+| 归档重建（静态） | 手动 | 不更新 | 无 |
+| `roll loop cycle watch`（CLI） | 手动 | `tail -F` 实时跟随 | 无（纯文件跟随） |
+| `roll status` / `roll status pulse` / `roll loop runs` | 手动 | 命令时刻快照 | 无 |
+
+CLI watch 是最低层实时路径——终端开着就能看。`roll supervisor live` 在它之上提供只读多角色 board：默认输出一帧快照，`roll supervisor live --watch` 则在同一终端区域原地刷新；浏览器/TUI 版 Supervisor Live Console 是后续工作，必须复用同一 view model。
+
+## TCR 节奏与动态拆分
+
+`roll loop cycle <id> --activity` 是给 Supervisor 读单个 cycle 节奏的解释面。它把
+US-OBS-042 的 activity 信号重建成几类状态：active vs silent、当前 micro-step、
+`test:red` / `test:green`、`green-uncommitted`、`action oversized`。
+
+当一个 action 超出声明的文件区域、契约区域、持续时间或测试面时，US-OBS-043 会在
+同一输出中给出 advisory split suggestion。建议只在安全边界生效：测试已绿且未提交时，
+输出会提示先 commit current green work，再继续或把发现的范围拆成 follow-up。它不会杀
+掉正在编辑的 Builder，不会自动 revert，也不会把 deferred scope 计入当前卡的交付。
+
+若 Builder 或 Supervisor 接受拆分，后续卡/action 会通过现有 story/backlog 机制生成，
+并在事件流里留下 `followup:queued` 引用。Evaluator/Scorer 可以看到 split history：
+如果 Builder 忽略建议并落了一个很大的 TCR，评分可以按节奏判断，但 cycle 不会只因为慢
+而失败。
+
+## TCR Rhythm And Dynamic Splits
+
+`roll loop cycle <id> --activity` is the single-cycle explanation surface for the
+Supervisor. It rebuilds US-OBS-042 activity signals into active vs silent,
+micro-step plan, `test:red` / `test:green`, `green-uncommitted`, and
+`action oversized` states.
+
+When an action expands beyond its declared file area, contract area, duration
+band, or test surface, US-OBS-043 adds an advisory split suggestion to the same
+output. The checkpoint is safe-boundary oriented: when tests are green and work
+is uncommitted, the output suggests committing the current green work first,
+then continuing or splitting discovered follow-up scope. It does not kill the
+active Builder, auto-revert, or count deferred scope as delivered by the current
+card.
+
+When the Builder or Supervisor accepts a split, the follow-up card/action is
+materialized through the existing story/backlog mechanisms and the event stream
+keeps a `followup:queued` reference. Evaluator/Scorer can read the split
+history: if the Builder ignores repeated suggestions and lands one large TCR,
+the rhythm is reviewable without failing the cycle merely for being slow.
+
+## 证据按构造（方向）
+
+证据的素材源——activity stream + diff——已经在 BC7 的标准流中。US-OBS-031 的方向是：ac-map / report / 截图引用从 activity 流 + git diff **自动起草**（不再是 builder 手动步骤 `Phase 10.6`）。实际落地范围以 US-OBS-031 的 spec 为准。
+
+## 故障排查
+
+**"no running cycle"**：当前没有 `cycle:start` 未结束的 cycle。传一个 cycle id 看特定的：`roll loop cycles --since all` 列出所有 cycle，挑一个。
+
+**"no activity signals recorded"**：这个 cycle 的 events.ndjson 里没有归一化信号。可能发生在 US-OBS-026 落地之前的老 cycle——用 `--since all` 重试看原始事件。
+
+**"no event stream"**：项目还没初始化 loop runtime dir（`.roll/loop/`）。跑一次 `roll setup`。
+
+**unparseable score/review（无法解析的评分/评审）**：当某个 evaluator/scorer 或
+peer reviewer 的输出无法解析（如 `SCORE` 行前有控制字符、缺 `VERDICT` 行）时，
+它不会让整个 cycle 静默假绿。在 `roll loop cycle <id> --roles` 的执行阵容里，该 agent
+那一行显示 `failed`，带 `cause`（如 `unparseable`）和一个 `raw artifact:` 指针。
+原始尝试被捕获在 `.roll/loop/peer/` 下——直接打开那个文件看 agent 到底吐了什么。
+关键：**即便有 agent 解析失败，也只有一个被采纳（`accepted`）的 score 决定 gate**；
+读 `accepted` 那一行（及 `accepted evaluator` 产物链接）拿真正算数的判定。完整读法见
+[Cycle Role Visibility](../guide/en/loop.md#cycle-role-visibility) /
+[Cycle 角色可观测](../guide/zh/loop.md#cycle-角色可观测)。
+
+**unparseable score/review (English)**: when an evaluator/scorer or peer
+reviewer emits output that cannot be parsed, the cycle does not silently turn
+green. The agent's row in `roll loop cycle <id> --roles` shows `failed` with a
+`cause` and a `raw artifact:` pointer under `.roll/loop/peer/`. Only the one
+`accepted` score gates the delivery — read that row, not the failed attempts.
+
+## 相关
+
+- `docs/architecture.md` §BC7 — 三流契约与 CLI-first 架构
+- `packages/cli/src/commands/cycle.ts` — 实现
+- `packages/core/src/loop/activity-signal.ts` — ActivitySignal 模型 + normalizer
+- `packages/spec/src/types/cycle-activity.ts` — CycleActivityEvent 类型
+- `.roll/features/loop-observability/live-console-design.md` — 历史完整设计（旧 web/daemon 第二发射器已退役，远程就绪缝仍是未来设计约束）
+- `.roll/features/loop-observability/observability-retro.md` — 为什么是 CLI-first（复盘 + 三 agent 收敛）

package/docs/manifesto.md

@@ -0,0 +1,65 @@
+# 理念
+
+roll 的根本立场。当设计决策争执不下时，回到这里。
+
+## 控制
+
+**1. 可靠性在 harness，不在模型。**
+模型是黑盒。让产出可靠的是外面那层反馈闭环——设定目标、调度执行、感知结果、修正方向。这是 roll 存在的全部理由。
+
+**2. roll 是一个按反馈闭环设计的 agent harness，不是一堆功能。**
+它的形态是闭环：作动（编排）→ 传感（可观测）→ 评分（Evals = 误差信号）→ 反哺（修正下一轮）。功能要长在这个回路上，不是并列堆叠。
+
+**3. 不打开黑盒。**
+Token 级压缩、工具 schema 强制、单次推理——全部委派给下游 agent。不必建模被控对象内部，靠反馈就能控制。越界去管内层，是 roll 的范围错误。
+
+## 真相
+
+**4. 主干即真相。**
+完成 ≡ 已合并进主干。退出码、自我声明都不算数——事后对账才算。愿望（Backlog）和真相（main）要分开，由对账协调。
+
+**5. 上下文是持久的结构化文档，不是对话历史。**
+每条工作开工前先把设计/领域/验收写成持久文档——这就是控制器对系统的模型与记忆。fresh context 之所以能成立，正因为上下文被预先补齐、落盘。
+
+**6. 持久优先于便利。**
+写在前——原子追加——退出必写终态——事件流是源不是缓存。宁可多写一笔，不可丢一次状态。
+
+## 失败
+
+**7. 失败要响，不偷偷自愈。**
+ALERT + 通知，人决策。agent 连败不自动换人重试。一个坏 Story 不冻结其他工作，但永久中毒的 Story 不要再捞起来。
+
+**8. 进程随时可能死，防御要覆盖每条路径。**
+不假设优雅退出——SIGKILL 后重入必须能检测孤儿并安全接管；开始信号一发出，任何退出路径都必须补结束信号，兜底本身不能再依赖可能失败的操作。防御不只覆盖写入，还要覆盖删除和枚举路径——最深一课：可以拦住「写 tmp」，拦不住「按真目录枚举后删除」。
+
+**9. 反馈必有 Goodhart 护栏。**
+度量一旦被当目标就会被钻空子。所以 Evals 信号只生成「待人确认」的候选，绝不自动改动真实 backlog。自我改进的飞轮要转，但不能脱手。
+
+## 结构
+
+**10. 有界且可逆。**
+一 Cycle 一个 Story、全新上下文、TCR 绿则提交红则回退、Feature 可整体回退、迁移可一键切回。不对大颗粒 Story 让步——拆小再跑。任何一步都要能干净撤销。
+
+**11. 路径即身份。**
+不同项目共享存储 = 污染。每个项目的运行态数据放在自己的 `.roll/loop/` 下，互不可见。
+
+**12. 一个能力域，一个家。**
+按能力域（编排/执行/工具/上下文/可观测/Evals/治理）各归其位，用类型化契约连接。能力散落在多种载体、靠文本缝合，就是不稳定与低效的根源——这是重写要根除的。
+
+**13. 可观察契约是真相，实现怪癖不是。**
+一段行为的契约是它的可观察面——入参、stdout、副作用、退出码、写的文件与事件——由冻结快照守护。踩过的每个坑固化成不变量，不在新代码里重新发现。
+
+**14. 决策者是人——人在环上，不在环中。**
+人是监督控制器与限幅器（human-on-the-loop），不是每步审批的瓶颈（human-in-the-loop）。自动化执行，但策略（merge 规则、安全阈值、路由偏好）由人设定。发布永远人点头。Loop 在人的环上跑，不是替代人。
+
+---
+
+## 一句话信仰
+
+> **把 AI 当黑盒，用反馈闭环把它的产出逼向可靠；让这台 harness 自己可观测、可信赖、能自评、还拦得住自己。** 语言、框架、端都会变，这条不变。
+
+## 反信仰（我们明确不信的）
+
+- 不信"模型够强就够了"——再强的黑盒也需要外层闭环。
+- 不信"全自动无人化"——发版与高风险决策永远留人。
+- 不信"LLM 是能被经典控制器稳定的对象"——反馈闭环是设计镜头，不是字面控制数学（理论沿革见 [specs/theory-foundation](specs/theory-foundation.md)）。

package/docs/migration/role-taxonomy-v4.md

@@ -0,0 +1,60 @@
+# Role Taxonomy v4 Migration
+
+This is a breaking cleanup. Roll no longer accepts or aliases the retired role/profile names in active runtime config.
+
+## Manual Config Update
+
+Old config patterns to remove:
+
+```yaml
+execution_profiles:
+  planned:
+    roles:
+      planner: { rig: kimi-strong }
+      builder: { routing: default }
+execution_policy:
+  mode: planned
+  default_profile: planned
+defaults:
+  story:
+    roles:
+      execute:
+        avoid: [supervise]
+      evaluate:
+        avoid: [execute]
+```
+
+Use the canonical taxonomy and open pools instead:
+
+```yaml
+execution_profiles:
+  designed:
+    roles:
+      designer: { rig: kimi-strong }
+      builder: { routing: default }
+      evaluator: { rig: reasonix-eval }
+execution_policy:
+  mode: designed
+  default_profile: standard
+defaults:
+  story:
+    roles:
+      execute:
+        kind: select
+        require: [execute]
+        strategy: health-aware
+      evaluate:
+        kind: select
+        require: [evaluate]
+        strategy: health-aware
+```
+
+## No Compatibility Fallback
+
+There is no runtime alias, fallback, or dual-write path for the retired names. Invalid legacy keys fail loudly so stale configs are visible during setup, test, or loop routing.
+
+## Review Isolation
+
+Fresh-session independence is the required isolation boundary. The same agent brand may serve different roles when each role runs in a separate fresh session and the selector ranks candidates by capability, health, risk, cost, and recent outcomes.
+
+Agent/model diversity remains useful as a ranking preference or an explicit owner-requested strict mode. It is not a default reason to remove a capable agent from the pool.

package/docs/verification.md

@@ -0,0 +1,83 @@
+# 质量体系
+
+roll 的可靠性不靠「线上没出事」来证明，靠可执行、可证伪的测试来证明。分三层。
+
+## L1 · 混沌测试
+
+对 12 条不变量（[01-system](01-system.md) I1–I12）的每一条，主动注入故障，验证系统正确响应。这些测试进 CI，红即阻塞发布。
+
+| # | 注入的故障 | 期望行为 |
+|---|-----------|---------|
+| I1 | Cycle 跑到一半 kill agent 进程 | ≤watchdog 阈值内落 failed，无僵尸 running |
+| I2 | spawn 后立即 SIGKILL 整个进程组 | 重入检测孤儿（锁龄/心跳/PID）→ 安全接管，无脏锁，无丢提交 |
+| I3 | 并发两个 Cycle 选同一 Story | 只产生 1 个 PR；已有 open PR 的 Story 不再新建 |
+| I4 | 标 Done 但 PR 不 merge | Cycle 末对账 → 自动退回 |
+| I5 | 注入一个永远失败的 Story | 其他 Story 照常交付；毒 Story 连败 N 次 → 进暂缓，不再被选取 |
+| I6 | primary agent 连败 3 次 | PAUSE + ALERT + 通知均发生；不自动换 agent 重试 |
+| I7 | 两个名字重叠的项目并行跑 | 状态互不污染（路径即身份） |
+| I8 | 写 cycle_end 前杀进程 | 仅凭事件流重建出正确终态；trap 补写 |
+| I9 | 两个 loop 同时写 Backlog | 乐观锁重试，不丢更新；精确匹配不误伤 depends-on 行 |
+| I10 | 角色候选 agent 不可用 | 当前 resolution 记录 skipped runtime health；无可用候选则 PAUSE + ALERT，不静默改写静态池 |
+| I11 | 模拟成本逼近日上限 | 自动降级到便宜槽 或 暂停 + ALERT |
+| I12 | 制造 0 个 TCR 提交的 Cycle | 判定失败 + ALERT；Feature 可 revert 到 Cycle 1 且仓库干净 |
+
+## L2 · Evals（结果评估）
+
+每个 Cycle 收尾按六维打分，0–1 加权汇总为 1–10。
+
+| 维度 | 权重 | 评估内容 |
+|------|------|---------|
+| outcome | 3 | 是否真的 merge 进 main（对齐 I4） |
+| correctness | 2 | 产出 PR 的 CI 是否绿 |
+| scope_fidelity | 2 | 是否完成了被路由的那个 Story（无漂移、无空转） |
+| quality | 1 | 是否加了测试、是否立刻返工 |
+| efficiency | 1 | 实际耗时 vs 预估 |
+| cleanliness | 1 | 无孤儿 worktree/分支、无 ALERT |
+
+缺失维度记 unknown，从加权中剔除并重新归一——缺数据 ≠ 0 分。连续多 Cycle 同一维度低分 → 生成改进候选（落 signals 候选文件，标「待人确认」，不自动改代码——Goodhart 护栏）。
+
+## L3 · 成熟度评级
+
+12 条能力逐条评 S/A/B。每个 release 更新 scorecard。目标 = 消灭所有 B。
+
+| 能力 | 起点 | 目标 | 度量 |
+|------|------|------|------|
+| I1–I4, I7, I8, I12 | S | 保持 S | 对应 L1 混沌测试常绿 + L2 outcome/cleanliness 趋势 |
+| I5 | A | S | L1-I5 通过 + 毒 Story 不拖累吞吐 |
+| I9 | A | S | L1-I9 通过 + 无 Backlog 写冲突丢更新 |
+| I10 | A | S | L1-I10 通过 + 角色解析可预测性 |
+| I11 | B | S | L1-I11 通过 + 成本不破上限 |
+
+任何能力从 S 降级 = 回归，触发 ALERT。
+
+## diff-test
+
+port 期间，每个从 v2.0 迁移的函数和命令，输出必须与 bash 版对齐：
+
+```bash
+diff <(v2.0-bash <cmd>) <(v3-ts <cmd>)
+```
+
+分层验收：每完成一层，该层 difftest 全绿才进下一层。允许白名单例外——TS 版刻意改进的输出差异须显式声明并记录原因。
+
+## 验收档案布局
+
+一张卡的交付物收口在卡夹 `.roll/features/<epic>/<ID>/`：
+
+- **生命周期**：loop 周期开始时先创建 `<ID>/<run-id>/` 证据框，并通过 `ROLL_RUN_DIR` 交给内层 agent；`ROLL_EVIDENCE_DIR` 与 `ROLL_SCREENSHOTS_DIR` 指向本次 run 的 `evidence/` 与 `screenshots/`。
+- **过程采集**：`roll test`、截图通道和手工证据都写入本次 run；`ac-map.json` 放在卡片根目录，声明每条 AC 由哪些证据支撑。
+- **收尾硬闸**：runner 在交付末尾调用 `roll attest <ID> --run-dir "$ROLL_RUN_DIR"`；默认 `loop_safety.attest_gate: hard`，带 AC 的交付若没有新鲜且内容充足的报告会被拦住。`attest_gate: soft` 只用于显式迁移窗口。
+- **证据模式**：`evidence_mode` 决定 QA/Evaluator 应看的证据矩阵，不是空口截图豁免。`visual_ui` 保持截图硬闸；`refactor_contract` / `data_state` / `docs_content` 用测试、build/typecheck、grep、fixture、事件、链接等证明，只有视觉表面变化、AC 明确要求或 layout 风险出现时升级截图。
+- **落位**：一次验收写进 `<ID>/<run-id>/`（run-id 为时间戳，永不覆盖），`latest` 软链指向最新；主入口是 `<ID>-review.html` 验收 Review Page，`<ID>-report.html` 在一个发版周期内保留为旧报告兼容别名。
+- **索引**：归档重建 从 `backlog.md` 生成 `.roll/index.json`（ID→epic，确定性、幂等）。attest 先查索引定位 epic，查不到回落 `features/uncategorized/<ID>/`；验收收尾会尽力刷新 story 交付段与 `.roll/index.json`。
+- **回收**：`roll loop gc` 按阈值清理陈旧 run（保最近 N 次 + M 天内，二者满足其一即留；只删「又旧又超额」的尾部）。阈值 `--keep-latest`（默认 10）/`--keep-days`（默认 30），`--dry-run` 预演。
+- **读取兼容**：迁移窗口内旧布局 `.roll/verification/<ID>/` 仍可读（attest gate、ac-map、报告解析都先查卡夹再回落旧树）；存量迁移与兼容代码移除由 US-META-002 收尾。
+
+## 门
+
+| 门 | 条件 | 频率 |
+|----|------|------|
+| 持续门 | L1 混沌 12 项全绿 + TCR 硬校验 + CI 绿 + 关键路径 difftest 全绿 | 每次合并 |
+| 层级门 | 每层全部卡 difftest 对齐 v2.0 + 向 owner 汇报、点头后进下一层 | 每层收尾 |
+| 切换门（P4） | v3 loop 连跑 20 Cycle ≥90%、unstick <10% + L1 全绿 + difftest 达标 | 一次 |
+| 发布门 | 成熟度 scorecard 无 B + 稳定性基线 ≥ v2.0 + release 永远人点头 | 每次发布 |

package/guide/INDEX.md

@@ -0,0 +1,86 @@
+# Documentation Index
+
+> Auto-generated by roll-doc-audit on 2026-06-13. Edit individual docs, not this file.
+
+## Index
+
+| Path | Title | Category | Last Modified |
+|------|-------|----------|---------------|
+| AGENTS.md | Roll Project — Internal Conventions | convention | 2026-05-28 |
+| CONTRIBUTING.md | Contributing to Roll | convention | 2026-05-23 |
+| guide/en/ai-agents.md | Roll — AI Agent Support | guide | 2026-06-30 |
+| guide/en/acceptance-evidence.md | Acceptance Evidence — roll attest / Evidence lifecycle | guide | 2026-07-02 |
+| guide/en/changelog.md | Roll — Changelog | guide | 2026-05-21 |
+| guide/en/configuration.md | Roll — Configuration | guide | 2026-07-02 |
+| guide/en/conventions.md | Roll — Conventions & AGENTS.md | guide | 2026-07-02 |
+| guide/en/dream.md | roll-.dream — Nightly Code Health Scanner | guide | 2026-05-19 |
+| guide/en/faq.md | Roll FAQ | guide | 2026-07-02 |
+| guide/en/getting-started.md | Roll — Getting Started | guide | 2026-06-08 |
+| guide/en/installation.md | Roll — Installation & Updates | guide | 2026-05-19 |
+| guide/en/legacy-onboarding.md | Existing Codebase Onboarding | guide | 2026-05-20 |
+| guide/en/loop-driven-architecture.md | Loop-Driven Agent Architecture | guide | 2026-05-27 |
+| guide/en/loop.md | roll loop — Autonomous BACKLOG Executor | guide | 2026-07-02 |
+| guide/en/methodology.md | Roll Engineering Methodology | guide | 2026-05-25 |
+| guide/en/migration-2.0.md | Migrating to Roll 2.0 | guide | 2026-05-19 |
+| guide/en/overview.md | Roll — Overview | guide | 2026-06-13 |
+| guide/en/patterns/README.md | Roll Onboarding Patterns | guide | 2026-05-19 |
+| guide/en/patterns/graft-pattern.md | Graft Pattern | guide | 2026-05-19 |
+| guide/en/patterns/replant-pattern.md | Replant Pattern | guide | 2026-05-19 |
+| guide/en/patterns/seed-pattern.md | Seed Pattern | guide | 2026-05-19 |
+| guide/en/pairing.md | Cross-Agent Pairing — heterogeneous second eyes | guide | 2026-06-08 |
+| guide/en/peer.md | roll peer — Cross-Agent Code Review | guide | 2026-06-30 |
+| guide/en/pr-review.md | Roll — PR Review | guide | 2026-05-19 |
+| guide/en/practices/engineering-common-sense.md | Roll Engineering Common Sense Checklist | guide | 2026-05-27 |
+| guide/en/pricing.md | Pricing — Cost Visibility & Price Snapshots | guide | 2026-05-24 |
+| guide/en/project-setup.md | Roll — Project Setup | guide | 2026-05-28 |
+| guide/en/skills.md | Roll Skill Selection Guide | guide | 2026-05-19 |
+| guide/en/test-isolation.md | Roll — Test Isolation (roll test) | guide | 2026-05-28 |
+| guide/en/tools.md | Roll — Tools & Policy | guide | 2026-06-19 |
+| guide/en/testing.md | Roll — Testing Workflow | guide | 2026-05-23 |
+| guide/en/testing/quality-rubric.md | Test Quality Rubric | guide | 2026-05-23 |
+| guide/zh/ai-agents.md | Roll — AI Agent 支持 | guide | 2026-06-30 |
+| guide/zh/changelog.md | Roll — Changelog (中文) | guide | 2026-05-21 |
+| guide/zh/configuration.md | Roll — 配置 | guide | 2026-07-02 |
+| guide/zh/conventions.md | Roll — 约定与 AGENTS.md | guide | 2026-07-02 |
+| guide/zh/dream.md | roll-.dream — 夜间代码健康巡检 | guide | 2026-05-19 |
+| guide/zh/faq.md | Roll 常见问题 | guide | 2026-07-02 |
+| guide/zh/getting-started.md | Roll — 快速上手 | guide | 2026-06-08 |
+| guide/zh/installation.md | Roll — 安装与更新 | guide | 2026-05-19 |
+| guide/zh/legacy-onboarding.md | 已有代码库接入 Roll | guide | 2026-05-20 |
+| guide/zh/loop-driven-architecture.md | Loop 驱动的 Agent 架构 | guide | 2026-05-27 |
+| guide/zh/acceptance-evidence.md | 验收证据 — roll attest / 证据生命周期 | guide | 2026-07-02 |
+| guide/zh/loop.md | roll loop — 自主 BACKLOG 执行器 | guide | 2026-07-02 |
+| guide/zh/methodology.md | Roll 工程方法论 | guide | 2026-05-25 |
+| guide/zh/migration-2.0.md | 迁移到 Roll 2.0 | guide | 2026-05-19 |
+| guide/zh/overview.md | Roll — 概述 | guide | 2026-06-13 |
+| guide/zh/patterns/README.md | Roll 接入模式（Patterns）| guide | 2026-05-19 |
+| guide/zh/practices/engineering-common-sense.md | Roll 工程常识清单 | guide | 2026-05-30 |
+| guide/zh/patterns/graft-pattern.md | Graft Pattern（续写路径）| guide | 2026-05-19 |
+| guide/zh/patterns/replant-pattern.md | Replant Pattern（翻种路径）| guide | 2026-05-19 |
+| guide/zh/patterns/seed-pattern.md | Seed Pattern（播种路径）| guide | 2026-05-19 |
+| guide/zh/pairing.md | 跨 Agent 结对 — 异构的第二双眼睛 | guide | 2026-06-08 |
+| guide/zh/peer.md | roll peer — 跨 Agent 代码评审 | guide | 2026-06-30 |
+| guide/zh/pr-review.md | Roll — PR 评审 | guide | 2026-05-19 |
+| guide/zh/pricing.md | Pricing — 成本可见性与价格快照 | guide | 2026-05-24 |
+| guide/zh/project-setup.md | Roll — 项目初始化 | guide | 2026-05-28 |
+| guide/zh/skills.md | Roll 技能选择指南 | guide | 2026-05-19 |
+| guide/zh/test-isolation.md | Roll — 测试隔离（roll test）| guide | 2026-05-28 |
+| guide/zh/tools.md | Roll — 工具与策略 | guide | 2026-06-19 |
+| guide/zh/testing.md | Roll — 测试工作流 | guide | 2026-05-23 |
+| guide/zh/testing/quality-rubric.md | 测试质量评分卷 | guide | 2026-05-23 |
+| lib/agent_usage/README.md | Agent Usage Tracking | module | — |
+
+## Coverage Summary
+
+- Total docs indexed: 60
+- By category: guide (56) / convention (2) / module (2)
+
+## Gap Report
+
+### Undocumented module directories (≥ 3 source files, no README)
+
+| Directory | Source Files | Note |
+|-----------|-------------|------|
+| lib/ | 21 | draft: lib/README.md |
+| lib/i18n/ | 39 | draft: lib/i18n/README.md |
+| lib/prices/ | 3 | draft: lib/prices/README.md |