@seanyao/roll 4.702.4 → 4.703.2

package/guide/en/acceptance-evidence.md

@@ -67,6 +67,36 @@ loop_safety:
 Soft mode records the gap and raises the same audit signal, but it does not
 block the delivery cycle. Treat it as temporary compatibility, not the default.
 
+The merge gate reads structured evidence, not prose. A delivery can be refused
+when any of these facts are true:
+
+- `attest render` exits non-zero;
+- `ac-map.json` references a path that does not resolve under the story run or
+  card archive, except allowed GitHub PR/commit/check URLs for this repository;
+- an AC remains `claimed`, which means the Builder asserted completion without
+  pass/fail evidence;
+- a positive AC has no real evidence reference;
+- a non-exempt visual card has no captured screenshot or recorded machine
+  capture skip;
+- a declared `deliverable_url`, `deliverable_cmd`, or `physical_terminal`
+  surface was not really captured;
+- an AC is `fail`, which means a check ran and went red.
+
+The PR body carries a `Roll-Evidence` trailer that points reviewers to the
+story-scoped evidence. Treat that trailer as the entry point for human review:
+open the Acceptance Review Page, then follow the AC map and referenced files.
+
+Use the audit command before release or when a Done row looks suspicious:
+
+```bash
+roll attest audit
+roll attest audit --json
+```
+
+It scans Done stories for missing reports, missing or empty `ac-map.json`,
+dangling evidence references, and `evidence_debt` rows. A clean audit exits 0;
+any issue exits 1 and lists the story IDs and missing references.
+
 ## The red line
 
 An AC with **zero evidence** can never claim `pass`: the renderer forces it
@@ -96,7 +126,10 @@ Two rules decide what the validator recognises:
   - a declared `physical_terminal:` ⇒ **terminal** with a stricter contract — the
     report must contain a real macOS `Terminal.app` screenshot captured from
     screen pixels. Headless stdout, transcript-rendered images, and HTML replays
-    are rejected for this contract;
+    are rejected for this contract. `roll attest` also asks the
+    `physical.screenshot` provider for this evidence when available, copies the
+    returned PNG into the story run, and shows the status chain
+    `requested -> taken/skipped/failed/timeout -> attached/not-attached`;
   - else a declared `deliverable_cmd:` ⇒ **terminal** — a CLI deliverable that
     rides the terminal-capture lane;
   - else the AC text decides (web / terminal / ambiguous).
@@ -142,6 +175,10 @@ at startup:
   repeated `roll doctor` / setup checks do not keep re-triggering the macOS
   prompt; if permission was just granted, restart Terminal.app before trusting
   the cache.
+- `Roll Capture.app` / `physical.screenshot` — the provider path for physical
+  screenshot requests. If readiness is unavailable, `roll attest` records an
+  honest skip with the setup reason instead of blocking report generation; if
+  the provider times out, the report surfaces timeout as its own failure reason.
 - `Playwright Chromium` — optional headless web capture for `roll attest` and
   archive screenshots. Install with `npx playwright install chromium`.
 

package/guide/en/configuration.md

@@ -86,6 +86,20 @@ loop_safety:
 Use `attest_gate: soft` only for an explicit migration window. Soft mode keeps
 the audit trail and alert, but it does not block the delivery cycle.
 
+Automatic card picking also has an advisory semantic ranking layer. It is on by
+default and can be disabled explicitly:
+
+```yaml
+pick:
+  semantic_ranking: off
+```
+
+When enabled, Roll asks the default agent to rank the current candidate backlog
+only when the backlog/candidate hash changes, caches the result in
+`.roll/loop/pick-ranking.json`, and then still applies the normal picker gates.
+If the agent times out or returns bad JSON, Roll records `harness_failure` and
+falls back to the deterministic order.
+
 ## Verifying
 
 `roll status` prints the resolved paths so you can confirm overrides took

package/guide/en/loop.md

@@ -22,6 +22,76 @@ agent bindings.
 Loop runs inside a **tmux session** named `roll-loop-<project-slug>`.
 When not muted, a terminal window pops up automatically so you can watch in real time.
 
+## North Star Readings
+
+`roll status` starts with a one-line North Star summary so the owner can see the
+system trend before reading the rest of the health panel. The row is the compact
+form of `roll north`: autonomy, delivery rate, fix tax, and attribution errors.
+Each value is followed by a status dot; run `roll north` when you need the
+target, trend, and reason text.
+
+`roll north [--json]` reads the last 14 days of runs, events, backlog, card
+metadata, and delivery truth. The four targets are:
+
+| Metric | Target | Anti-gaming rule | `null` means |
+|--------|--------|------------------|--------------|
+| Autonomy | >=72h autonomous runtime | An effective autonomous day needs at least 6 non-idle attempts; backlog-empty days pause the clock and do not count as missed time. | There is not enough qualifying run history yet, or the backlog was empty for the window. |
+| Delivery rate | >=60% | Delivery is counted from merge truth, not self-reported cycle exits. | No eligible delivery denominator exists yet. |
+| Fix tax | <1x | The denominator is US cards only; FIX work is not allowed to improve its own ratio. | There is no US-card denominator in the window. |
+| Attribution errors | =0 | `unknown` is not guessed into env, harness, or card; missing envelopes stay visible. | No attribution sample exists yet. |
+
+Machine consumers should use `roll north --json`, which emits
+`roll.north.v1` with the same current values, targets, reasons, and daily
+series used by the terminal panel.
+
+## Failure Attribution and Pauses
+
+Every failed cycle is assigned one of four classes:
+
+| Class | Meaning | Owner action |
+|-------|---------|--------------|
+| `env` | Machine, checkout, auth, network, sandbox, or worktree condition. | Repair the named environment problem, then resume dispatch. |
+| `harness` | A Roll component failed, such as score parsing, attest render, publish, or rescue. | Inspect the component and open a focused FIX when needed. |
+| `card` | The Builder reached the story and failed during actual card work. | Investigate the story, split it, or change routing after reading evidence. |
+| `unknown` | There is not enough envelope evidence to charge a card honestly. | Add a deterministic failure envelope before blaming the card. |
+
+Root-cause counting is by `root_cause_key`, not by card. Repeated `env`,
+`harness`, or `unknown` causes pause dispatch and write a diagnostic snapshot
+under `.roll/loop/diagnostics/`. When the terminal says dispatch is paused,
+open that snapshot first: it includes the class, root cause, recent events, and
+playbook. Fix the named machine or Roll component, then run `roll loop resume`.
+
+If earlier env/harness failures pushed a card into the skip list, rebuild that
+state from the durable evidence:
+
+```bash
+roll loop pardon-skip-list --dry-run
+roll loop pardon-skip-list
+roll loop pardon-skip-list --include-unknown  # also pardons unknown/no-evidence rows
+```
+
+Use `--include-unknown` only after reading the rows; older zero-usage `gave_up`
+entries may be real card failures.
+
+## Builder Isolation and Rescue
+
+During Builder execution the main checkout is physically write-protected. The
+Builder works in its cycle worktree; the shared checkout is treated as a sensor,
+not a scratchpad. Roll releases the write protection when the cycle exits.
+
+If dirty or ahead changes appear in the main checkout anyway, Roll quarantines
+them before continuing:
+
+- dirty files become a `rescue/leaked-*` ref that can be restored with the
+  manifest's `git stash apply <ref>` command;
+- ahead commits become a `rescue/leaked-*` branch that can be restored with the
+  manifest's `git cherry-pick <ref>` command;
+- the manifest is written under `.roll/loop/quarantine/` and records the cycle,
+  story, phase, files, ref, and exact restore command.
+
+Claim the rescued work from the manifest, then reset or resume the loop from a
+clean main checkout.
+
 ## Scheduling
 
 Loop is scheduled via **launchd** (macOS). By default, every hour at a
@@ -193,6 +263,13 @@ roll agent                           # Show scopes, roles, agent pool, and legac
 roll agent list                      # Show agents installed on this machine
 ```
 
+When semantic pick ranking is enabled, `roll loop watch --events` includes a
+`pick:ranked` line such as `picked US-123 (rank 1/5: unblocks the release lane)`.
+`roll supervisor next` and `roll supervisor next --json` show the latest top
+three ranking suggestions and reasons. The ranking is advisory only; Hold, Cut,
+unsatisfied dependencies, skip-list, open PR, merged-delivery, and pending-publish
+gates still decide eligibility.
+
 ### Goal Mode vs Scheduled Mode
 
 `roll loop go` is a manual goal session, not a launchd scheduler tick. While it
@@ -1013,6 +1090,60 @@ This keeps `git worktree list` clean and prevents `.claude/worktrees/` from
 accumulating old entries over time. Active worktrees (branches ahead of `main`)
 are left untouched.
 
+## Main Checkout Guard
+
+During the Builder process, Roll makes the shared main checkout read-only at the
+filesystem boundary while leaving the cycle worktree writable. If a previous
+cycle left product files dirty or local commits ahead of `origin/main`, Roll
+moves that pollution to a `rescue/leaked-*` ref plus a
+`.roll/loop/quarantine/*.json` manifest, restores main to the trusted state, and
+continues the cycle.
+
+The event stream records `sandbox:write_protected` and `sandbox:quarantined`.
+`roll loop watch --events`, `roll loop cycle <id> --activity`, and supervisor output
+surface those facts. Each quarantine manifest includes the ref, file list, and a
+one-line restore command for owner/supervisor recovery.
+
+## Post-cycle Environment Cleanup
+
+Before the cycle worktree is removed, loop runs a declarative environment
+cleanup step. It targets only transient toolchain/scratch artifacts produced
+inside the worktree — e.g. `.scratch`, `tmp`, `node_modules/.cache`, `.vite`,
+`__pycache__`, `.build` — and leaves source files and uncommitted work alone.
+
+Each rule emits a `cycle:cleanup` event to `events.ndjson`, so the cleanup is
+observable and auditable. Cleanup failures are downgraded to warning events,
+also summarized in `ALERT.md` under the independent `harness:env_cleanup` root
+cause, and never block the next cycle.
+
+You can override or extend the default rules by creating
+`.roll/loop/cleanup-manifest.yaml`:
+
+```yaml
+rules:
+  - name: my-scratch
+    kind: rm
+    paths:
+      - .my-tmp
+      - "**/roll-cleanup.log"
+  - name: my-cache
+    kind: isolate
+    paths:
+      - .my-cache
+```
+
+`kind: rm` deletes the path; `kind: isolate` moves it into a cycle-local
+`.roll-cleanup/<cycle-id>/<rule>/` directory inside the worktree (so it is
+removed along with the worktree).
+
+Supported path forms are deliberately small: literal relative paths such as
+`.my-tmp` and recursive suffix matches of the form `prefix/**/literal-suffix`,
+including `**/roll-cleanup.log` or `src/**/__pycache__`. Shell globs are not
+expanded; a `*` inside the recursive suffix, such as `**/*.log`, makes that rule
+invalid, emits a warning, and skips the rule. Use `rules: []` or
+`enabled: false` to disable cleanup explicitly. The default manifest is used
+only when no override file is present.
+
 ## Cycle phases
 
 Every cycle is sliced into seven named phases. Each phase emits a `phase_start`
@@ -1027,7 +1158,7 @@ so the tmux viewer never looks frozen.
 | 3 | `worktree_setup` | fetch origin + worktree create + meta sync | 2 – 10 s |
 | 4 | `agent_invoke` | Agent executes with up to 3 retries | 5 – 45 min |
 | 5 | `publish_push` | push branch + open PR (or doc-only merge) | 5 – 30 s |
-| 6 | `cleanup` | emit PR final state + worktree teardown | < 1 s |
+| 6 | `cleanup` | env cleanup + emit PR final state + worktree teardown | < 1 s |
 
 > **US-AUTO-044**: the main loop exits after opening the PR and **no longer waits for merge**. Merge / rebase / close is handled asynchronously by the dedicated PR Loop (`com.roll.pr.<slug>`, every 5 min); a story with an open PR is skipped by the eligibility gate, so it is neither re-opened nor falsely marked Done.
 

package/guide/en/methodology.md

@@ -590,7 +590,7 @@ It is off by default. Enabling it requires an explicit `roll loop on`.
 
 ### 9.2 Components
 
-**`roll-loop`** — Runs on a configurable schedule via macOS launchd (Linux: crontab). Scans BACKLOG for `📋 Todo` items and routes them: `US-XXX → $roll-build`, `FIX-XXX → $roll-fix`, `REFACTOR-XXX → $roll-build`. Caps items per run to limit blast radius. Rebuilds the generated morning report page from events/runs as it goes. Built-in TCR enforcement: after a story completes, checks for `tcr:` micro-commits — if zero are found, reverts the story to Todo with an ALERT, preventing agents from skipping the TCR rhythm.
+**`roll-loop`** — Runs on a configurable schedule via macOS launchd (Linux: crontab). Scans BACKLOG for `📋 Todo` items and routes them: `US-XXX → $roll-build`, `FIX-XXX → $roll-fix`, `REFACTOR-XXX → $roll-build`. Caps items per run to limit blast radius. Rebuilds the Loop Digest from windowed `events.ndjson` / `runs.jsonl` facts as it goes; contradictory digest data is marked degraded and emits an ALERT instead of being reported as normal. Built-in TCR enforcement: after a story completes, checks for `tcr:` micro-commits — if zero are found, reverts the story to Todo with an ALERT, preventing agents from skipping the TCR rhythm.
 
 **`roll-.dream`** — Runs nightly (03:00 local) via macOS launchd (Linux: crontab). Scans the codebase for dead code, architectural drift against `.roll/domain/`, pruning candidates, and emerging patterns. Outputs `REFACTOR-XXX` entries to BACKLOG and a log to `.roll/dream/YYYY-MM-DD.md`.
 

package/guide/zh/acceptance-evidence.md

@@ -59,6 +59,31 @@ loop_safety:
 soft 模式会记录缺口并发出同一类审计信号，但不阻塞本轮交付。它是临时兼容口，
 不是默认行为。
 
+合并闸读取结构化证据，不读口头说明。出现以下事实时，交付可能被拒合：
+
+- `attest render` 退出码非零；
+- `ac-map.json` 引用的路径无法在本次 story run 或卡片归档下解析，除非是本仓允许的
+  GitHub PR/commit/check URL；
+- AC 仍是 `claimed`，表示 Builder 只有完成声明，没有 pass/fail 证据；
+- positive AC 没有真实证据引用；
+- 无豁免的可视卡没有截图，也没有记录化的机器采集 skip；
+- 声明了 `deliverable_url`、`deliverable_cmd` 或 `physical_terminal`，但对应
+  surface 没有真实采集；
+- AC 是 `fail`，表示检查执行过并变红。
+
+PR body 会带 `Roll-Evidence` trailer，指向这张 Story 的证据入口。人工评审从这里开始：
+打开验收 Review Page，再沿 AC map 和引用文件检查。
+
+发版前或发现 Done 行可疑时，运行审计命令：
+
+```bash
+roll attest audit
+roll attest audit --json
+```
+
+它会扫描 Done stories，查缺失报告、缺失或空的 `ac-map.json`、悬空证据引用和
+`evidence_debt` 行。无问题退出 0；发现问题退出 1，并列出 story ID 与缺失引用。
+
 ## 红线
 
 **零证据**的 AC 永远不能是 `pass`：渲染层强制降级为 🟧 仅声明，并列入
@@ -84,7 +109,10 @@ soft 模式会记录缺口并发出同一类审计信号，但不阻塞本轮交
     产品页,就该截 web 图；
   - 声明了 `physical_terminal:` ⇒ **terminal**，但合同更严格——报告必须包含从 macOS
     `Terminal.app` 真实屏幕像素截下来的图。headless stdout、transcript 渲染图、
-    HTML replay 图都不能满足这个合同；
+    HTML replay 图都不能满足这个合同。`roll attest` 会在可用时请求
+    `physical.screenshot` provider，把返回的 PNG 复制进本 story 的 run 目录，
+    并在报告里展示 `requested -> taken/skipped/failed/timeout -> attached/not-attached`
+    状态链；
   - 否则声明了 `deliverable_cmd:` ⇒ **terminal**——走终端截屏通道的 CLI 交付；
   - 否则由 AC 文本判定（web / terminal / 含糊）。
 
@@ -122,6 +150,9 @@ evidence、已有证据暴露 rendering/layout 风险；升级原因必须记录
   复现图都不算截图证据。交互式 `Terminal.app` 授权探针一旦成功，会缓存在
   `ROLL_HOME` 下，后续 `roll doctor` / setup 检查不会反复触发 macOS 权限弹窗；
   如果刚刚授权，先重启 Terminal.app 再信任缓存。
+- `Roll Capture.app` / `physical.screenshot` —— 物理截图请求的 provider 通道。
+  就绪度不可用时，`roll attest` 记录带设置原因的 honest skip，不阻断报告生成；
+  provider 超时时，报告把 timeout 作为独立失败原因展示。
 - `Playwright Chromium` —— 可选的 headless web 截图工具，用于 `roll attest`
   和归档截图。安装命令是 `npx playwright install chromium`。
 

package/guide/zh/configuration.md

@@ -76,6 +76,17 @@ loop_safety:
 只有显式迁移窗口才应使用 `attest_gate: soft`。soft 模式保留审计记录和告警，
 但不阻塞本轮交付。
 
+自动选卡还有一层 advisory 语义排序。它默认开启，也可以显式关闭：
+
+```yaml
+pick:
+  semantic_ranking: off
+```
+
+开启后，Roll 只在 backlog / candidate hash 变化时让默认 agent 排序一次，并把结果
+缓存到 `.roll/loop/pick-ranking.json`；最终仍由既有 picker gates 决定能不能选。
+如果 agent 超时或返回坏 JSON，Roll 记录 `harness_failure` 并回落到确定性顺序。
+
 ## 验证
 
 `roll status` 会打印解析后的路径，便于确认覆盖是否生效；

package/guide/zh/loop.md

@@ -20,6 +20,67 @@ autonomous，不改变 agent binding。
 Loop 在名为 **`roll-loop-<project-slug>`** 的 **tmux session** 里运行。
 未静音时，终端窗口会自动弹出，你可以实时旁观 AI 干活。
 
+## 北极星读数
+
+`roll status` 顶部先显示一行北极星摘要，让 owner 在读完整健康面板前先看到系统趋势。
+这行是 `roll north` 的压缩版：自主运行时长、交付率、修复税、归因错误。每个值后面
+有状态点；需要目标、趋势和原因时运行 `roll north`。
+
+`roll north [--json]` 读取最近 14 天的 runs、events、backlog、卡片元数据与交付真相。
+四项目标如下：
+
+| 指标 | 目标 | 防应试口径 | `null` 含义 |
+|------|------|------------|-------------|
+| 自主运行时长 | ≥72 小时 | 有效自主日需要至少 6 次非 idle 尝试；backlog 空的日期只停表，不计为未达标时间。 | 暂无足够合格运行历史，或窗口内 backlog 为空。 |
+| 交付率 | ≥60% | 交付按 merge truth 统计，不按 cycle 自报退出码。 | 暂无可作为分母的交付样本。 |
+| 修复税 | <1x | 分母仅统计 US 卡；FIX 工作不能改善自己的比值。 | 窗口内没有 US 卡分母。 |
+| 归因错误 | =0 | `unknown` 不猜成 env、harness 或 card；缺失 envelope 保持可见。 | 暂无归因样本。 |
+
+脚本消费用 `roll north --json`，它输出 `roll.north.v1`，字段与终端面板使用的当前值、
+目标、原因和每日序列一致。
+
+## 失败归因与暂停
+
+每个失败 cycle 都归到四类之一：
+
+| 类别 | 含义 | owner 动作 |
+|------|------|------------|
+| `env` | 机器、checkout、auth、network、sandbox 或 worktree 条件。 | 修复点名的环境问题，再恢复派工。 |
+| `harness` | Roll 组件失败，例如 score 解析、attest render、publish 或 rescue。 | 检查对应组件，必要时开聚焦 FIX。 |
+| `card` | Builder 已进入 story，并在真实卡片工作中失败。 | 读证据后调查 story、拆卡或调整路由。 |
+| `unknown` | 没有足够 envelope 证据诚实归因给卡片。 | 先补确定性失败 envelope，再考虑归因。 |
+
+根因计数按 `root_cause_key`，不是按卡片。同一个 `env`、`harness` 或 `unknown`
+根因反复出现时，Roll 会暂停派工，并在 `.roll/loop/diagnostics/` 写诊断快照。
+终端提示派工暂停时，先打开快照：里面有归因类别、根因、最近事件和 playbook。
+修复点名的机器或 Roll 组件后，再运行 `roll loop resume`。
+
+如果早先的 env/harness 失败把卡片错误推入 skip list，可以从持久证据重建：
+
+```bash
+roll loop pardon-skip-list --dry-run
+roll loop pardon-skip-list
+roll loop pardon-skip-list --include-unknown  # 同时平反 unknown/no-evidence 行
+```
+
+`--include-unknown` 只应在读过记录后使用；较早的零用量 `gave_up` 行可能是真实 card 失败。
+
+## Builder 隔离与救援区
+
+Builder 执行期间，主 checkout 会被物理写保护。Builder 在自己的 cycle worktree 中工作；
+共享 checkout 是传感器，不是草稿区。cycle 退出时 Roll 会释放写保护。
+
+如果 dirty 或 ahead 改动仍然出现在主 checkout，Roll 会先隔离再继续：
+
+- dirty 文件写成 `rescue/leaked-*` ref，可按 manifest 里的
+  `git stash apply <ref>` 还原；
+- ahead commits 写成 `rescue/leaked-*` 分支，可按 manifest 里的
+  `git cherry-pick <ref>` 还原；
+- manifest 写在 `.roll/loop/quarantine/`，记录 cycle、story、phase、文件列表、
+  ref 和精确还原命令。
+
+按 manifest 认领隔离内容，然后把主 checkout 恢复干净，再恢复 loop。
+
 ## 调度配置
 
 Loop 通过 **launchd**（macOS）调度。默认每小时在一个根据项目路径推导出的分钟触发
@@ -172,6 +233,12 @@ roll agent                           # 查看 scope、role、agent pool 与 lega
 roll agent list                      # 查看本机已装的 agent
 ```
 
+开启语义选卡排序时，`roll loop watch --events` 会显示 `pick:ranked` 行，例如
+`picked US-123 (rank 1/5: unblocks the release lane)`。`roll supervisor next` 和
+`roll supervisor next --json` 会展示最近一次 top3 排序建议与理由。该排序只作建议；
+Hold、Cut、未满足依赖、skip-list、open PR、已合并交付和 pending-publish gate 仍决定
+卡片是否可选。
+
 ### Goal Mode 与定时模式
 
 `roll loop go` 是手动 goal session，不是 launchd 定时 tick。运行期间 Roll 会持有
@@ -897,6 +964,54 @@ API key secret — 你配置的 agent 对应的那个。
 这样可以保持 `git worktree list` 干净，防止 `.claude/worktrees/` 随时间积累。
 分支仍领先于 `main` 的活跃 worktree 不受影响。
 
+## 主 checkout 保护
+
+Builder 进程运行期间，Roll 会在文件系统边界把共享主 checkout 设为只读，
+同时保持 cycle worktree 可写。如果上一轮 cycle 把产品文件留脏，或让本地
+`main` 领先 `origin/main`，Roll 会把污染物移入 `rescue/leaked-*` ref 和
+`.roll/loop/quarantine/*.json` 清单，随后把主 checkout 恢复到可信状态并继续
+本轮 cycle。
+
+事件流会记录 `sandbox:write_protected` 和 `sandbox:quarantined`。
+`roll loop watch --events`、`roll loop cycle <id> --activity` 和 supervisor 输出都会
+展示这些事实。每个 quarantine 清单都包含 ref、文件列表，以及供 owner /
+supervisor 认领恢复的一行命令。
+
+## Cycle 结束后环境清理
+
+在拆除 cycle worktree 之前，loop 会先执行一次声明式的环境清理。它只清理
+worktree 内部产生的临时/工具链缓存产物——例如 `.scratch`、`tmp`、
+`node_modules/.cache`、`.vite`、`__pycache__`、`.build`——不会触碰源码和
+未提交的改动。
+
+每条规则都会向 `events.ndjson` 写入一条 `cycle:cleanup` 事件，因此清理过程
+可观测、可审计。清理失败会降级为 warning 事件，同时汇总写入 `ALERT.md`，
+并按独立的 `harness:env_cleanup` 根因计数；它不会阻塞下一轮 cycle。
+
+你可以通过 `.roll/loop/cleanup-manifest.yaml` 覆盖或扩展默认规则：
+
+```yaml
+rules:
+  - name: my-scratch
+    kind: rm
+    paths:
+      - .my-tmp
+      - "**/roll-cleanup.log"
+  - name: my-cache
+    kind: isolate
+    paths:
+      - .my-cache
+```
+
+`kind: rm` 删除目标；`kind: isolate` 把目标移进 worktree 内的
+`.roll-cleanup/<cycle-id>/<rule>/`（随 worktree 一起被删除）。
+
+支持的路径形态刻意很小：字面相对路径，例如 `.my-tmp`；以及
+`prefix/**/literal-suffix` 形式的递归后缀匹配，例如 `**/roll-cleanup.log`
+或 `src/**/__pycache__`。不会展开 shell glob；递归后缀里包含 `*`（例如
+`**/*.log`）会让该规则无效，记录 warning，并跳过该规则。用 `rules: []`
+或 `enabled: false` 可以显式关闭 cleanup。只有没有覆盖文件时才使用默认清单。
+
 ## 阶段计时（Cycle phases）
 
 每轮 cycle 在内部切成七个命名阶段。每个阶段进入时 emit `phase_start`，
@@ -910,7 +1025,7 @@ PR 等合并）每 30–60s 还会 emit 一次 `phase_tick` 心跳，tmux 不再
 | 3 | `worktree_setup` | fetch origin + 建 worktree + 同步 meta | 2 – 10 秒 |
 | 4 | `agent_invoke` | 调起 agent（最多三次重试） | 5 – 45 分钟 |
 | 5 | `publish_push` | push 分支 + 建 PR（doc-only 直接合） | 5 – 30 秒 |
-| 6 | `cleanup` | 落 PR 终态 + 拆 worktree | < 1 秒 |
+| 6 | `cleanup` | 环境清理 + 落 PR 终态 + 拆 worktree | < 1 秒 |
 
 > **US-AUTO-044**:主 loop 开完 PR 即退,**不再等合并**。合并 / rebase / 关 PR 交给专职 PR Loop（`com.roll.pr.<slug>`,每 5 分钟）异步处理;有 open PR 的 story 由资格闸跳过,不会重复开,也不会假 Done。
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seanyao/roll",
-  "version": "4.702.4",
+  "version": "4.703.2",
   "description": "Roll — Roll out features with AI agents",
   "packageManager": "pnpm@11.1.3",
   "scripts": {