@seanyao/roll 4.630.2 → 4.702.2

package/guide/zh/acceptance-evidence.md

@@ -0,0 +1,194 @@
+# 验收 Review Page — `roll attest`
+
+每个交付完成的 story 都可以带一份**单文件验收 Review Page**：逐条 AC 的判定与支撑证据，
+离线可开、可打印 PDF、非工程角色也能读。
+
+## Review Page 位置
+
+每个 story 只有一个家——史诗下的卡片文件夹：
+
+```
+.roll/features/<epic>/<id>/<run-id>/<id>-review.html  ← 验收 Review Page（自包含）
+.roll/features/<epic>/<id>/<run-id>/<id>-report.html  ← 旧报告兼容别名（一个发版周期）
+.roll/features/<epic>/<id>/<run-id>/evidence.json     ← 采集的硬事实
+.roll/features/<epic>/<id>/<run-id>/evidence/         ← 原始命令/测试产物
+.roll/features/<epic>/<id>/<run-id>/screenshots/      ← 需要视觉验收时的截图
+.roll/features/<epic>/<id>/ac-map.json                ← AC → 证据的意图映射
+.roll/features/<epic>/<id>/latest                     ← 指向最新一次的软链
+```
+
+每次运行按时间戳落盘、永不覆盖。backlog 的 `✅ Done` 行链接到
+`latest/<id>-review.html`；CHANGELOG 条目旁可带不可见的
+`<!-- evidence: ... -->` 注释 marker 供追溯。
+
+**故事自己的 `latest/<id>-review.html` 就是人类验收入口。** 验收一张故事看的是
+它自己的验收 Review Page，不是全局 archive/index 页面。`roll attest` 只对当前故事负责：
+它只写本故事的 Review Page、旧报告兼容别名和 `latest` 指针，不刷新任何全局 archive / 史诗 / 首页
+HTML。那些归档页想看时用 归档重建 按需渲染，它们是便捷/归档视图，不是交付真相面。
+
+## 三段式生命周期
+
+1. 立框。loop 周期一开始，runner 先创建带时间戳的 run 目录，并把它通过
+   `ROLL_RUN_DIR` 交给内层 agent。派生目录 `ROLL_EVIDENCE_DIR` 与
+   `ROLL_SCREENSHOTS_DIR` 分别指向 `<run-id>/evidence/` 和
+   `<run-id>/screenshots/`。
+2. 过程采集。`roll test` 把命令输出和摘要写入 `ROLL_EVIDENCE_DIR`；需要视觉
+   验收的端面把截图写入 `ROLL_SCREENSHOTS_DIR`。agent 在故事卡根目录维护
+   `ac-map.json`，把每条 AC 映射到支撑证据，并标注状态：`pass` ·
+   `readonly` · `partial` · `claimed` · `missing`。
+3. 收尾硬闸。交付结束时 runner 调用
+   `roll attest <story-id> --run-dir "$ROLL_RUN_DIR"`。`roll attest` 清扫硬事实
+   （TCR commits、最新 CI、可选部署探针、test-pass 凭证），渲染验收 Review Page，把
+   `latest` 指向本次 run。仅此而已——它只对当前故事负责：不挂载故事页交付段、
+   不重建 `.roll/index.json`、不刷新任何全局 archive/史诗/首页（那些归档页用
+   归档重建 按需渲染）。
+
+`roll attest` 也可独立运行——没有意图映射时，每条 AC 诚实渲染为 🟧 仅声明。
+
+## 闸口策略
+
+验收闸**默认是 hard**。带 AC 的 story 若交付完成却没有新鲜且内容充足的报告，
+不会被标成 `✅ Done`，而是直接拦住。显式迁移窗口可在 `.roll/policy.yaml`
+里改成 soft：
+
+```yaml
+loop_safety:
+  attest_gate: soft
+```
+
+soft 模式会记录缺口并发出同一类审计信号，但不阻塞本轮交付。它是临时兼容口，
+不是默认行为。
+
+## 红线
+
+**零证据**的 AC 永远不能是 `pass`：渲染层强制降级为 🟧 仅声明，并列入
+**Discrepancies（证据缺口）**附录。"我确认它能跑"这类口头完成，正是被这条
+红线挡住的东西。
+
+## 设计期声明可视证据
+
+`roll story validate` 在设计期就检查一张卡是否**生而诚实**——带可视证据 AC，
+且 web 面要声明可截的产品页。校验器靠两条规则识别：
+
+- **`[visual-evidence]` 标记即定论。** 以字面 `[visual-evidence]` 标记开头的 AC
+  条目**本身**就是可视证据 AC，无论后面写什么词——不必再额外写"截图 / screenshot"：
+  标记就是你的显式声明。（没标记时，校验器仍认 `screenshot` / `截图` / `录屏`
+  这类无歧义名词。）
+
+  ```markdown
+  - [ ] [visual-evidence] headless 截 Now 落地页及各 tab 真实渲染
+  ```
+
+- **声明的交付面优先于 AC 文本。** 一旦卡有了可视证据 AC，其 surface 先看 frontmatter：
+  - 声明了 `deliverable_url:`（别名 `screenshot_url:`）⇒ **web**——卡已承诺一个真实
+    产品页,就该截 web 图；
+  - 声明了 `physical_terminal:` ⇒ **terminal**，但合同更严格——报告必须包含从 macOS
+    `Terminal.app` 真实屏幕像素截下来的图。headless stdout、transcript 渲染图、
+    HTML replay 图都不能满足这个合同；
+  - 否则声明了 `deliverable_cmd:` ⇒ **terminal**——走终端截屏通道的 CLI 交付；
+  - 否则由 AC 文本判定（web / terminal / 含糊）。
+
+  所以声明了 `deliverable_url: .roll/features/agents.html` 的卡判为 **web** 面，
+  即便其 AC 文案里提到 `roll` 命令。
+
+## 证据模式
+
+Story 可以在 frontmatter 声明 `evidence_mode:`，也可以在 Evaluation contract
+里声明 `- evidence_mode: ...`。Roll 也会为 Evaluator prompt 推导模式，但只有显式
+声明的非视觉模式会改变截图门。
+这个显式模式不是空白覆盖：已经声明 URL、终端命令、physical terminal 或
+visual-evidence AC 时，仍会升级到对应截图/采集门。
+
+| 模式 | 必需证明 | 截图策略 |
+|------|----------|----------|
+| `visual_ui` | 真实渲染截图、功能/冒烟检查、CI | 必需 |
+| `cli_output` | stdout/stderr 快照、退出码、命令 fixture 或聚焦测试、CI | 条件必需；终端/TUI 视觉变化仍要截图 |
+| `refactor_contract` | 聚焦测试、typecheck/build、grep/no-old-symbol 检查、CI | 默认不需要；有视觉风险时升级 |
+| `data_state` | fixture replay、事件断言、幂等/并发覆盖、CI | 默认不需要；有视觉风险时升级 |
+| `docs_content` | rendered text 检查、链接检查、diff review、CI | 条件必需；布局变化要截图 |
+
+`screenshot_exempt:` 应命名或明确指向替代矩阵，最好配套
+`evidence_mode: refactor_contract`、`data_state` 或 `docs_content`。QA/Evaluator
+可以在三种情况下把非视觉模式升级回截图门：改了视觉表面、AC 明确要求 visual
+evidence、已有证据暴露 rendering/layout 风险；升级原因必须记录。
+
+## 外部工具就绪度
+
+可视证据依赖机器级工具；这些工具会被显式声明，并在启动时探测：
+
+- `macOS screencapture` —— 物理 Terminal.app / 浏览器窗口截图工具。它是 macOS
+  内置工具，但作为稳定截图宿主的 Terminal.app 需要 Screen Recording 权限。
+  缺权限时 attest 记录明确的截图 skip；headless、transcript 渲染图和 HTML
+  复现图都不算截图证据。交互式 `Terminal.app` 授权探针一旦成功，会缓存在
+  `ROLL_HOME` 下，后续 `roll doctor` / setup 检查不会反复触发 macOS 权限弹窗；
+  如果刚刚授权，先重启 Terminal.app 再信任缓存。
+- `Playwright Chromium` —— 可选的 headless web 截图工具，用于 `roll attest`
+  和归档截图。安装命令是 `npx playwright install chromium`。
+
+`roll doctor` 总是打印这些工具的可用性、权限状态、影响和修复命令。只想看工具与
+Terminal.app Screen Recording 就绪度时，用 `roll doctor --tools`。`roll init`
+与 `roll loop go` 在启动时跑同一套探测；交互式终端会询问是否安装/打开缺失的
+设置步骤，自动化环境默认静默，除非设置 `ROLL_EXTERNAL_TOOLS=yes` 或
+`ROLL_EXTERNAL_TOOLS=no`。选择 `no` 时会说明证据影响，然后继续，不改机器状态。
+
+机器级 Agents 页面（`.roll/features/agents.html`）也显示同一块工具状态，方便
+审阅者区分证据采集问题来自机器配置，而不是 story 代码。
+
+## Review Score 折叠区
+
+`.roll/notes/` 里存在该 story 的评审分条目时，报告底部出现折叠的
+*Review Score · 评审分* 区；没有则整块不出现。评审分由全新独立会话的
+同行 Reviewer 产出，绝不由工作 agent 自评。
+
+## 卡片从哪来 —— `roll idea`
+
+用一句自然语言加卡：
+
+```bash
+roll idea "退款流程在部分支付时会崩溃"
+```
+
+`roll idea` 自动分类（bug→FIX / 功能→IDEA）、取下一号、lint 校验、推断归属史诗，
+并创建完整卡片文件夹（spec.md + 故事页 + 刷新索引）。一个命令全搞定。
+
+如需显式指定 ID 与史诗，内部命令 `roll story new` 仍在：
+
+```bash
+roll story new US-PAY-001 --title "退款流程" --epic payments
+```
+
+两条通道都写出带 frontmatter 的 `spec.md`、故事页骨架，并刷新 `.roll/index.json`。
+已存在的卡拒绝覆盖——卡只出生一次，之后由人补充。技能从不手写卡片文件；
+任何没有卡的活卡行会被一致性 `cards` 维度在发版闸拦下。
+
+## 静态归档 —— 归档重建
+
+归档重建 是按需的修复/归档渲染器。它把归档重建为可浏览的三层静态
+HTML（每页自包含、按当前语言单语显示、明暗主题、可打印）：
+
+```
+.roll/features/index.html              ← 归档首页（Story / Cycle / Release）、
+                                         真相条、可搜索的史诗卡片
+.roll/features/<epic>/index.html       ← 史诗页：史诗账本 + 故事三分组
+                                         （已合主干 / 周期中 / 待办）
+.roll/features/<epic>/<id>/index.html  ← 故事归档：五站——立项、设计、执行、
+                                         交付（验收横幅 + 逐 AC 证据块）、复盘
+```
+
+页面上每个数字都来自真相模型——anchors -> selectors -> adapter ->
+projections——绝不手填。Story 聚合对比 backlog 声明与 merge/证据真相；
+Cycle 聚合只读 TerminalOutcome 终态记录；Release 聚合读取最新发版闸 verdict
+和有效 waiver。一句话：**待办是愿望，主干是事实，done ≡ merged。**
+
+归档首页会显式保留未知。`?` 表示事实缺失或不在已知 schema 内；`0` 表示
+已知为零。过早写下的 backlog `✅ Done` 只是和真相冲突的声明，会显示为漂移，
+不会被当成已交付。
+
+故事归档页里，截图证据仍是缩略图并可点开看大图。Vitest 输出等文本证据会从
+引用的 evidence 文件读取，并以内联、折叠、可滚动的正文块显示在 AC 下；
+文件缺失或不可读时，页面显示明确的不可用空态。
+
+当前交付真相仍以按 Story 收口的 attest 加 CLI-first 可观测为准：
+`roll status`、`roll loop watch`、`roll loop runs`、`roll loop cycle <id>`。手动
+运行 归档重建 只用于对账、归档导出、CI artifact 或迁移修复；rebuild mode
+会在手工合并或历史迁移后从源重渲每张故事页。

package/guide/zh/ai-agents.md

@@ -0,0 +1,170 @@
+# Roll — AI Agent 支持
+
+Roll 把 AI agent 当作一个按 scope 管理的执行身份池。当前模型是：
+
+```text
+Scope -> Role -> Binding -> Agent -> optional Model
+```
+
+这个形状在每一层递归复用：Machine 声明本机有哪些 agent，Project 绑定项目和
+Story 的角色，Story 或 Skill 可以在需要时进一步收窄绑定。
+
+## Agent 领域文件
+
+- `~/.roll/agents.yaml` 是 Machine Scope，用来声明本机 agent pool，以及
+  `supervise` 这类机器级角色。
+- `.roll/agents.yaml` 是 Project Scope，用来绑定项目/Story 角色，例如
+  `supervise`、`execute`、`evaluate`。
+
+`~/.roll/config.yaml` 仍可作为通用偏好和 legacy migration 输入存在，但它不再是
+agent 语义的主配置面。常用命令：
+
+```bash
+roll agent                      # 查看 Machine Scope、Project Scope、角色、pool、legacy 输入
+roll agent migrate --dry-run    # 预览 legacy 文件迁移
+roll agent migrate              # 写入 roll-agents/v1 文件
+roll agent list                 # 查看本机已安装 agent
+```
+
+## 角色
+
+Roll 的 Agent 领域有三个核心角色：
+
+- `supervise` — 项目级协调。guided mode 下可以是你当前对话的 agent；autonomous
+  mode 下由 Roll 解析角色并驱动 loop。
+- `execute` — 通过选中的 skill 工作流构建或修复 Story。
+- `evaluate` — 用 fresh session 评审、打分或检查交付。
+
+**一个跑完的 cycle 里，谁演了哪个角色？** cycle 跑完后，解析出的角色不是要你
+从日志里重建的谜题。跑 `roll loop cycle <id> --roles` 就能看清谁是 Builder、谁是
+Evaluator，咨询了哪些 peer，以及 gate 采纳了哪一个 score。同一份阵容也写进
+`summary.md` / `summary.json`，并内嵌到故事的 Execution Cast 报告块。完整的面见
+[Cycle 角色可观测](./loop.md#cycle-角色可观测)。
+
+Project 通常给 Story 设置默认角色绑定：
+
+```yaml
+schema: roll-agents/v1
+scope: project
+inherits: machine
+defaults:
+  story:
+    roles:
+      execute:
+        kind: select
+        from: [kimi, codex, pi]
+        require: [execute]
+        strategy: first-available
+      evaluate:
+        kind: select
+        from: [claude, codex, kimi, pi, agy, reasonix, cursor]
+        require: [evaluate]
+        strategy: health-aware
+```
+
+Machine Scope 可以声明 supervisor 和本机 agent pool：
+
+```yaml
+schema: roll-agents/v1
+scope: machine
+agents:
+  codex:
+    capabilities: [supervise, execute, evaluate]
+  kimi:
+    capabilities: [execute, evaluate]
+roles:
+  supervise:
+    use: codex
+```
+
+## 公平候选池
+
+静态配置只列出公平候选，不应该因为某次历史 auth、VPN、账号或网络问题永久排除
+某个支持的 agent。运行时健康在角色解析或 spawn 时检查：
+
+- 当前不可用的候选只在本次 resolution 中被跳过；
+- 跳过原因作为运行时事实记录；
+- 静态 pool 保持公平，除非你显式收窄它。
+
+未知或未注册的 agent 名会在配置解析时 fail loud。
+
+`health-aware` 是开放角色 casting 的选择策略。除非 owner policy 显式收窄 pool，
+Designer、Builder、Evaluator、Peer Reviewer 都从同一个已安装候选池里可见地选择，
+再按近期健康信号、角色能力标签、成功交付、近期使用和成本档位排序。降级候选仍会显示
+并带 warning，但不会因为 least-recent 早于健康候选被选中。便宜但较弱的 agent 可以继续
+适合聚焦任务，同时在 broad 或高风险 Builder 工作中排到更低。
+
+需要看清本次 casting 时，用 route trace：
+
+```bash
+roll supervisor route --role builder --story US-123
+roll supervisor route --role evaluator --story US-123 --json
+```
+
+trace 会列出每个候选、eligibility、score reasons、warnings、skipped runtime facts、
+最终选中 agent、策略和来源 binding。
+
+## Guided Mode 与 Autonomous Mode
+
+Guided mode 下，你可以继续留在当前 agent 窗口里工作。这个会话就是 supervisor
+front door：它可以查看 `roll agent`、执行 migration，并通过 CLI 让 Roll 继续。
+
+Autonomous mode 下，你不需要手动打开多个 agent 窗口。loop 会解析 `supervise`、
+`story.execute`、`story.evaluate`，再按绑定为各角色 spawn fresh agent session。
+
+## 支持的 Agent
+
+| Agent | CLI 命令 | 备注 |
+|-------|----------|------|
+| Claude Code | `claude` | Anthropic coding agent。 |
+| Kimi CLI | `kimi-code`（旧版：`kimi-cli` / `kimi`） | Moonshot coding agent。 |
+| Codex CLI | `codex` | OpenAI coding agent；`openai` 别名解析到 `codex`。 |
+| Antigravity | `agy` | Google Antigravity agent；旧 `gemini` 别名解析到 `agy`。 |
+| Pi | `pi` | `deepseek` 别名解析到 `pi`。 |
+| Reasonix | `reasonix` | DeepSeek 原生 coding agent；需要 `DEEPSEEK_API_KEY`。 |
+| Cursor | `cursor-agent` | Cursor headless agent；首日 usage 记录为 `?`，直到其 stdout 提供可解析的 token/cost 输出。 |
+
+Agent 差异只放在一份 profile 里，不散落到下游 runner/gate：
+
+1. 在 `packages/core/src/agent/specs.ts` 增加公开 registry 项。
+2. 在 `packages/cli/src/runner/agent-spawn.ts` 增加或更新 runner profile。
+3. executor、attest、pairing、scoring 保持 agent-agnostic。
+4. 为 profile 与 registry 项补单测。
+
+## Agent 工具链健康（US-V4-022）
+
+Supervisor 把 agent 工具链健康当作协调工作的一部分，而不是留给 owner 的谜团。
+它会扫描警告、auth/network 状态、被污染的技能根目录、陈旧的 setup 同步以及
+worktree 权限失败，并把它们归类为以下四类之一：
+
+- **auth_block** — "403"、"please run /login"、"Unauthorized" → `pause_for_owner`
+- **network_block** — `ECONNREFUSED`、`ETIMEDOUT`、DNS 失败 → `continue`
+  （瞬态；loop 会重试或呼吸）
+- **setup_skill_root_pollution** — Reasonix 辅助目录警告、skill 缺少 description
+  → `create_fix` → 作为 FIX 路由给 delta team
+- **worktree_permission_failure** — worktree 路径上的 `EACCES` / "permission denied"
+  → `pause_for_owner`
+
+当信号是 setup/skill-root 污染时，Supervisor **不会**把它标成 auth-blocked，
+而是把修复路由到 backlog/delta team 作为 FIX，而不是让 owner 临时救火。
+Supervisor 负责协调和诊断这些问题，但它不会变成 Builder 或 Evaluator，
+也不会自动删除全局文件。
+
+```bash
+roll supervisor health             # 人类可读的健康面板
+roll supervisor health --json      # 机器可读的分类结果
+roll supervisor next               # 下一张卡 + agent health 摘要
+```
+
+## Legacy 兼容
+
+旧项目可能还会有 `.roll/local.yaml agent`、`.roll/pairing.yaml`，或者
+`.roll/agents.yaml` 里的 v3 route slots。`roll agent` 会把它们显示在
+`Legacy compatibility` 区块，`roll agent migrate` 会把仍有用的数据迁进 scoped
+模型。它们仍可读取，但不再是主要 agent 管理模型。
+
+## 另见
+
+- [configuration.md](configuration.md) — 配置与策略文件
+- [pairing.md](pairing.md) — evaluate role 评审与打分
+- [loop.md](loop.md) — 自主模式下的角色解析

package/guide/zh/backlog-github-sync.md

@@ -0,0 +1,105 @@
+# roll backlog sync —— 把 GitHub Issues 同步进 backlog
+
+`roll backlog sync` 从 GitHub 仓库拉取 issues,写进本地
+`.roll/backlog.md`。v1 是单向的(issues → backlog),不回写 GitHub。
+
+`roll backlog sync` pulls GitHub issues into your local backlog
+(one-direction in v1).
+
+## 鉴权
+
+sync 按以下顺序解析 GitHub token:
+
+1. `$GITHUB_TOKEN` —— 在环境变量或 CI secret 里设置。
+2. `gh auth token` —— 跑过 `gh auth login` 后回退到 GitHub CLI。
+
+两者都没有时命令会停下来,并提示怎么设置。
+
+```bash
+export GITHUB_TOKEN=ghp_xxx
+# 或者用 GitHub CLI:
+gh auth login
+```
+
+## 快速上手
+
+```bash
+# 首次 sync 必须显式指定仓库:
+roll backlog sync --repo seanyao/roll-meta
+
+# 只预览,不写文件:
+roll backlog sync --repo seanyao/roll-meta --dry-run
+
+# 只拉带指定标签的 issue(命中任一即可,OR 语义):
+roll backlog sync --repo seanyao/roll-meta --label P1,bug
+
+# 首次成功后会记住仓库,之后可以省略 --repo:
+roll backlog sync
+```
+
+## 参数
+
+| 参数         | 说明 |
+|--------------|------|
+| `--repo`     | `owner/repo`。首次 sync 必填,之后从配置读取。 |
+| `--dry-run`  | 计算并打印差异,但不改动 `.roll/backlog.md`。 |
+| `--label`    | 逗号分隔的标签过滤,可重复;命中任一即匹配(OR)。 |
+
+## label → type 映射
+
+issue 的标签决定 backlog 类型前缀。第一个命中的标签生效;都不命中
+时默认 `US`。
+
+| GitHub 标签                  | Backlog 类型 |
+|-----------------------------|--------------|
+| `bug`                       | `FIX`        |
+| `enhancement` / `feature` / `US` | `US`    |
+| `refactor`                  | `REFACTOR`   |
+| (无匹配标签)                | `US`         |
+
+issue 状态映射到状态列:`open` → `📋 Todo`,`closed` → `✅ Done`。
+issue 标题作为行描述。
+
+## ID 与幂等
+
+每个 issue 得到稳定的 backlog id `GH-<编号>`(例如 issue #13 →
+`GH-13`),再与类型前缀组合(`US-GH-13`、`FIX-GH-13`)。
+
+sync 是幂等的:二次运行会跳过 backlog 里已存在 id 的 issue —— 不覆盖
+已有行的状态或描述,并打印 `skipped (already exists): GH-13`。每次运行
+结尾给出汇总:
+
+```
+added: 2, skipped: 5, total issues: 7
+```
+
+`--dry-run` 用 `+`(将新增)和 `=`(将跳过)标记打印同样的差异,且
+永不改动文件。
+
+## 配置:`.roll/local.yaml`
+
+一次真正成功的 sync 之后,解析出的仓库、标签和时间戳会被持久化,后续
+运行可省略 `--repo`:
+
+```yaml
+backlog_sync:
+  repo: seanyao/roll-meta
+  direction: issues-to-backlog
+  labels: []
+  last_sync_at: 2026-05-28T10:00:00Z
+```
+
+| 字段            | 含义 |
+|-----------------|------|
+| `repo`          | 无 flag 时的默认 `owner/repo`。 |
+| `direction`     | v1 始终是 `issues-to-backlog`。 |
+| `labels`        | 默认标签过滤;显式 `--label` 会覆盖它。 |
+| `last_sync_at`  | 上一次成功 sync 的时间戳。 |
+
+显式 flag 始终覆盖配置。若 `.roll/local.yaml` 没有 `backlog_sync:` 块,
+首次 sync 必须传 `--repo`。
+
+## v1 不做
+
+双向回写、Projects/Milestones 映射、PR 关联、非 GitHub 平台、自定义
+映射规则,均不在 v1 范围内。

package/guide/zh/changelog.md

@@ -0,0 +1,57 @@
+# Roll — Changelog
+
+Roll 自动保持 `CHANGELOG.md` 同步，无需手动编写或更新。
+
+## 工作原理
+
+1. `$roll-build`（或 `$roll-fix`）交付故事并暂存 `CHANGELOG.md`。
+2. 故事完成提交中包含 `CHANGELOG.md`——不产生单独的 changelog commit。
+3. 发版时，Roll 的发布流程将 `## Unreleased` 重命名为版本标签。
+
+## 写什么内容
+
+`$roll-.changelog` 技能读取 `BACKLOG.md`，为每个完成的故事或修复写一条 bullet，只保留用户可见的变化：
+
+**写入：**
+- 用户可直接调用的新命令
+- 用户能感知到的 bug 修复
+- 可见的体验变化（布局、输出、速度）
+- 安装、升级、配置相关的改动
+
+**跳过：**
+- 内部重构
+- 测试基础设施
+- 只有开发者会遇到的 bug 修复
+- 实现细节
+
+技能内置风格守门——bullet 必须简洁、白话、面向用户。技术黑话会触发重写循环。
+
+## 可发版的两种形态
+
+`roll release` 认两种"changelog 就绪"形态：顶部 `## Unreleased` 段且有条目，**或**预写好的下一版本段（`## v3.608.1 — 2026-06-08`，版本号比 package.json 当前新）——后者正是发布流程自己的惯例。首段版本等于当前版本意味着全部已发完。
+
+```markdown
+## Unreleased
+- **Added**: `roll loop runs` — 随时查看 loop 最近都跑了什么
+- **Fixed**: `roll update` 不再在升级后误报旧版本
+
+## v2026.05.07
+- ...
+```
+
+## 首次创建与历史回填
+
+若项目尚无 `CHANGELOG.md`，`$roll-.changelog` 会创建文件并将所有历史完成故事按日期倒序回填。
+
+## 手动触发
+
+```bash
+$roll-.changelog   # 暂存 CHANGELOG.md（在 build 会话中调用）
+```
+
+在 build 会话外单独调用时，会暂存并以 `chore: sync changelog` 提交。
+
+## 另见
+
+- [loop.md](loop.md) — loop 在每个故事结束后自动触发 changelog
+- [skills.md](skills.md) — 支持技能表中的 `roll-.changelog`

package/guide/zh/configuration.md

@@ -0,0 +1,99 @@
+# Roll — 配置
+
+Roll 在启动时解析三个环境变量。在运行 `roll` 之前覆盖任意一个，
+就能改变它查找状态、技能和共享约定的位置。
+
+## 环境变量
+
+| 变量 | 默认值 | 用途 |
+|------|--------|------|
+| `ROLL_HOME` | `~/.roll` | 单用户状态根目录。存放 `config.yaml`、已安装的 `skills/`、同步的 `conventions/`。 |
+| `ROLL_CONFIG` | `$ROLL_HOME/config.yaml` | 编辑器、loop/dream/brief 调度时间、单工具（`ai_*`）配置。Agent 路由不在这里，而在项目内 `.roll/agents.yaml`（见 [ai-agents.md](ai-agents.md)）。 |
+| `ROLL_GLOBAL` | `$ROLL_HOME/conventions/global` | 全局约定文件（`AGENTS.md`、`CLAUDE.md` 等），同步到各 AI 工具目录。 |
+| `ROLL_LANG` | 未设置 | 当前进程的用户表面语言覆盖。支持 `en` 与 `zh`；未设置时使用已保存配置或系统语言探测。 |
+| `ROLL_HEARTBEAT_TIMEOUT` | `1800`（秒） | loop runner 认定 inner cycle 已成孤儿、需要 heal state 的心跳静默阈值。如果你的 cycle 合理静默时间超过 30 分钟，可调大此值。 |
+| `ROLL_LOOP_FORCE` | 未设置 | 设为任意非空值时，`roll loop` 会跳过活跃窗口和 pause 文件检查。`roll loop now` 和 `roll loop test` 内部已自动设置；只有当你希望 cron 定时调度也忽略静默时段时，才需要手动 export。 |
+| `ROLL_LOOP_NO_HEAL` | `0` | 设为 `1` 关闭构建完成后的 CI 自愈，恢复 fail-fast。调试或想给自主循环按周期省钱时使用。 |
+| `ROLL_LOOP_HEAL_MAX` | `2` | 故事提交落地后，CI 自愈的最大尝试次数。CI 抖动较多时可调大；想更快失败则调小。 |
+| `ROLL_PR_MERGE_TIMEOUT` | `600`（秒） | **已弃用（US-AUTO-044）。** 主 loop 不再等合并,此项已无用;PR 合并改由专职 PR Loop 异步处理。 |
+| `ROLL_LOOP_NO_POPUP` | 未设置 | 设为任意非空值时，runner 在 macOS 下不再自动弹出 Terminal.app 窗口运行 `tmux attach`。供测试和后台跑批使用——窗口在 tmux session 结束后会留下空 attach 提示，污染桌面。 |
+| `ROLL_LOOP_GC_RETENTION_DAYS` | `30` | 覆盖 `roll loop gc` 的保留天数。优先级高于 `.roll/local.yaml` 中的 `loop_gc.retention_days`。 |
+| `ROLL_FEED_BUDGET_BYTES` | `16384` | 每个周期交给内层 agent 的上下文 feed 字节预算。设为正整数即可调节容量；非数字或非正数回落默认值。 |
+| `ROLL_AGENT_NUDGE` | `1`（开启） | 兼容期的 agent 偏好开关。新模型优先通过 scoped role binding 选择候选；设为 `0`（或 `off`/`false`/`no`）关闭历史偏好。 |
+| `ROLL_RUN_DIR` | 未设置 | 验收证据 run 目录的标准入口。loop runner 在 agent 启动前设置；`roll attest --run-dir` 与独立 `roll attest` 也会读取它。 |
+| `ROLL_EVIDENCE_DIR` | 从 `ROLL_RUN_DIR` 派生 | 已打开证据框中的原始命令/测试产物目录。通常由 runner 或 `roll test` 设置，不需要手写。 |
+| `ROLL_SCREENSHOTS_DIR` | 从 `ROLL_RUN_DIR` 派生 | 已打开证据框中的视觉证据目录。通常由 runner 或截图通道设置，不需要手写。 |
+
+`ROLL_CONFIG` 和 `ROLL_GLOBAL` 都派生自 `ROLL_HOME`，所以通常只需覆盖
+`ROLL_HOME` 即可一并搬迁。
+
+## 常见覆盖场景
+
+把 roll 状态钉到项目本地目录（适合 CI、测试、隔离实验）：
+
+```bash
+export ROLL_HOME="$PWD/.roll-sandbox"
+roll setup
+roll loop now
+```
+
+不动 `~/.roll`，用另一套约定运行 roll：
+
+```bash
+ROLL_GLOBAL=/path/to/team-conventions roll init
+```
+
+用一次性配置文件验证通用配置改动时，可以设置 `ROLL_CONFIG`；Agent 语义请通过
+`~/.roll/agents.yaml` 与 `.roll/agents.yaml` 管理，并用 `roll agent` 查看解析结果。
+
+## 语言选择
+
+语言有两层控制：
+
+- `ROLL_LANG=en|zh` 只覆盖当前进程，并且优先于已保存配置。
+- `roll config lang en|zh` 把偏好写入 Roll 配置；`roll config lang --reset`
+  清除偏好，重新使用系统语言探测。
+
+`roll help --lang en|zh <topic>` 可临时切换帮助和指南语言。
+`roll doctor language` 会审计活跃文档、约定、skills 与生成表面的语言漂移。
+CLI 语言快照维护在 `packages/cli/test/cli-language-surface.test.ts` 和
+`packages/cli/test/__snapshots__/cli-language-surface.test.ts.snap`；审计表面由
+`packages/cli/test/doctor-language.test.ts` 覆盖。
+
+用户可见表面仍一次只显示一种语言。Agent 契约、代码、git 元数据和稳定 schema key 保持英文；
+面向 owner 的对话跟随当前任务里 owner 使用的语言。
+
+## 项目策略
+
+项目内安全策略放在 `.roll/policy.yaml`。验收证据闸默认是 `hard`：带 AC 的
+story 要有新鲜且内容充足的 attest 报告，才允许标成 `✅ Done`。
+
+```yaml
+loop_safety:
+  attest_gate: hard
+```
+
+只有显式迁移窗口才应使用 `attest_gate: soft`。soft 模式保留审计记录和告警，
+但不阻塞本轮交付。
+
+## 验证
+
+`roll status` 会打印解析后的路径，便于确认覆盖是否生效；
+通过 `$roll-doctor` 技能可以诊断解析后的 `ROLL_HOME` 下的目录结构问题。
+
+## Agent 安装
+
+先安装 agent CLI，再通过 scoped agent 文件声明或绑定：`~/.roll/agents.yaml` 是
+Machine Scope，`.roll/agents.yaml` 是 Project Scope。例如：
+
+- Codex CLI：`npm install -g @openai/codex`
+- Antigravity CLI：`npm install -g @antigravity/agy`
+
+运行 `roll agent` 查看有效 scope；运行 `roll agent migrate --dry-run` 预览旧 agent
+配置迁移。完整模型和支持列表见 [ai-agents.md](ai-agents.md)。
+
+## 相关文档
+
+- [overview.md](overview.md) — 三层模型、BACKLOG 优先级
+- [loop.md](loop.md) — `roll loop` 子命令
+- [ai-agents.md](ai-agents.md) — 支持的 AI Agent

package/guide/zh/consistency.md

@@ -0,0 +1,48 @@
+# 一致性 — `roll release` 内置的发版闸
+
+以真相锚点持续核对七个维度。backlog 的 `✅ Done` 行是声明；`main` 上的
+merge 证据、验收报告、cycle 终态事件、发版闸事件才是事实。七个维度为：
+① 代码 ↔ backlog 声明 · ② 卡片（每条活卡必须拥有
+`features/<epic>/<ID>/spec.md`，证据链接不许悬空；卡片制之后已交付且带 AC
+的故事必须拥有 `latest/<ID>-report.html`；卡片制之前的历史 Done 行只计数不拦截）·
+③ 文档（changelog / features / guide / README / --help）· ④ 测试 ·
+⑤ locale 对等（guide en↔zh + i18n key）· ⑥ 网站 · ⑦ 真相活体
+（`ensureDeliveriesFresh` + `queryStoryDelivery` 必须证明发布增量里的每张卡
+确实已交付；Done 行有 PR ref 时还要与结构化真相一致）。
+
+```bash
+roll release              # 唯一发版流——闸在流程内运行
+roll release --dry-run    # 预览计划；不改任何东西
+roll release --gate-check # 机器入口（CI 用）；exit 0 = 全部通过
+```
+
+## 发版闸
+
+`roll release` 把**一致性闸放在任何不可逆操作之前**，且本地、远端同口径。本地这
+一遍跑在发布分支上——版本号 bump 与 changelog 折叠提交之后、**开 PR / 合并之前**。
+任一维度失败就在它还只是本地分支时中止发版：bump+changelog 永远不会进 `main`，
+所以不会出现“已合并但没打 tag”的半成品。远端则在每个 `v*` tag 上由 `release.yml`
+再跑同一道闸，之后才创建 GitHub Release。带着已知漂移发版的唯一方式是把漂移修掉——
+不是绕过闸。
+
+`main` 始终受 PR 保护，所以发版即便给自己也要开 PR。随后它用 GitHub 原生**自动合并**
+（`gh pr merge --auto --squash`）自驱合并，而不是干等后台看护 lane：CI 转绿即合并，
+哪怕你关掉终端也会完成。等待期间每轮轮询打印一行进度；若新 PR 的检查迟迟没调度，
+会推一个空提交把 CI“顶”一下。这需要仓库开启 **“Allow auto-merge”**（Settings →
+General → Pull Requests）；没开则发版会带着诚实的错误停下，提示你开启该设置或手动
+合并 PR——绝不静默挂死。
+
+验收证据闸默认是 `hard`。`loop_safety.attest_gate: soft` 是显式项目策略，
+只用于迁移窗口；一致性检查仍会报告缺失或悬空的证据，避免缺口静默消失。
+
+真相活体维度是防“假 Done”闸。它先从 `runs.jsonl` 和 first-parent `main`
+merge commit 重建交付投影，再对发布增量里的每个 story id 调
+`queryStoryDelivery()`。backlog markdown 只是人的声明；`deliveries.jsonl`
+是可重建缓存；git merge 与 run 事件才是事实。
+
+## 文档对齐边界
+
+registry 漂移已经是硬红线：命令注册表、README、guide 或 `--help` 彼此不一致时，
+FIX-242 守卫会让一致性检查和发版闸失败。`roll attest` 里的 `doc-gap` 信号仍是
+shadow-only：当交付 diff 改了用户可见命令面或输出文案文件，却没有在同一 diff
+触及 README/docs/guide/site 时，它只在报告里给出警示，暂不改变退出码或 Gate 结论。