@seanyao/roll 4.714.2 → 4.717.2

package/docs/architecture.md

@@ -221,6 +221,8 @@ building ──attest earned──► publishable ──push+PR──► awaitin
   - 完全跳过预检：`loop_safety.skip_network_check: true`（FIX-1025）——当你确认所配置的服务可直连、不希望被任何固定主机探测拦住时使用。
   - English: the precheck defaults to `github.com:443`. For a domestic-only workflow, point it at a host you actually need via `loop_safety.probe_url`, or opt out entirely with `loop_safety.skip_network_check: true` — so a dropped VPN never halts loop/release when every configured provider is directly reachable.
 - Warm session 复用：`loop_safety.session_reuse: true` 只表达复用意图；必须同时设置 `loop_safety.resume_scope: same-story` 才会在同一 story 重试时复用 codex session。缺省、非法值或未设置 `resume_scope` 都按 `off` 处理，跨卡复用保持禁用。
+- Builder 硬轮换：`loop_safety.builder_no_consecutive_repeat`（默认开）保证任意连续两个 cycle 的 builder agent 不相同——上一个 cycle 的 builder 被从本次 execute 池中硬排除。池缩到只剩上一个 builder 时**失败即声（ALERT + pending）**，绝不静默重复、绝不空转；轮换真正发生时记 `builder:rotation` 事件可审计。设 `builder_no_consecutive_repeat: false` 关闭；仅约束 builder（Evaluator 独立性靠 fresh session，不靠排除品牌）。
+  - English: `loop_safety.builder_no_consecutive_repeat` (default on) forbids two consecutive cycles from sharing a Builder — the previous cycle's builder is hard-excluded from the execute pool. If that empties the pool it fails loud (ALERT + pending), never repeating silently; a real rotation records a `builder:rotation` audit event. Set `false` to disable. Builder-only (Evaluator independence comes from fresh sessions, not brand exclusion).
 
 策略是规则源——它不直接执行动作，而是被其他上下文读取并遵循。
 

package/guide/INDEX.md

@@ -9,6 +9,7 @@
 | 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/browser-operations.md | Roll — Browser Operations (managed + interactive lanes) | guide | 2026-07-15 |
 | 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 |
@@ -39,6 +40,7 @@
 | 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/browser-operations.md | Roll — 浏览器操作（受管通道 + 交互通道） | guide | 2026-07-15 |
 | 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 |

package/guide/en/acceptance-evidence.md

@@ -53,6 +53,12 @@ the archive rebuild; they are a convenience/archive view, not the delivery-truth
 `roll attest` also runs standalone — without an intent map every AC renders as
 🟧 Claimed, honestly.
 
+Captured artifacts render by their actual media type, not the capture lane that
+produced them. Image files (`png`, `jpg`, `jpeg`, `webp`, or `gif`, including a
+recognised image signature without an extension) render as images; text output
+such as `.txt` or `.log` is escaped and shown inline in a readable `<pre>`
+block. A terminal capture may therefore appear in either form.
+
 ## Gate policy
 
 The attest gate is **hard by default**. A delivered story with ACs but no fresh,
@@ -108,6 +114,66 @@ renderer forces it down to 🟧 Claimed and lists it under **Discrepancies**.
 evidence; it is explicitly not the same as an agent-confirmed `pass`. Verbal
 completion ("I confirmed it works") is exactly what this rules out.
 
+## Outward behavior verification
+
+Some ACs describe behavior Roll cannot prove locally — a real
+`npm i -g github:owner/repo`, a published CLI's first run, a live OAuth
+callback. A build or `npm pack` succeeding does **not** prove any of these; a
+simulation is not the outward promise. Marking such an AC "manual-only" and
+letting it render green is the same as substituting *not run* for *passed*.
+
+When a story or fix documents an external install / publish / login channel, the
+relevant AC must declare **one** explicit verification path in its Evaluation
+contract — Roll never infers "outward" from prose:
+
+```yaml
+expected_evidence:
+  - kind: external-smoke                     # real command in an isolated env
+    target: npm i -g github:owner/repo#<commit> && repo --version
+    proves: the documented git-install channel installs and starts clean
+    outward:
+      mode: external-smoke
+      command: npm i -g github:owner/repo#<commit> && repo --version
+      environment: release                   # ci | nightly | release
+      timeout_sec: 180
+  - kind: owner-attested                     # human sign-off when no smoke can cover it
+    proves: the production OAuth callback round-trips
+    outward:
+      mode: owner-attested
+      reason: needs a real third-party account; no safe automated path exists
+      approvalRef: https://github.com/owner/repo/issues/1343
+```
+
+The attest report renders an **Outward verification** banner and table near the
+top. Only a real smoke pass (or a valid, unexpired owner attestation) is green:
+
+| Resolved state | Report line | Green? |
+|----------------|-------------|--------|
+| `verified` | `VERIFIED (external smoke)` / `VERIFIED (owner-attested)` | yes |
+| `verified-in-simulation` | `verified-in-simulation — simulation only, NOT accepted` | **no** |
+| `unverified-external` | `UNVERIFIED — external smoke not run` (or `owner attestation pending`) | **no** |
+| `failed-external` | `FAILED — external smoke` | **no** |
+
+A single non-`verified` outward AC turns the banner red — the delivery cannot
+overstate its outward behavior. `npm pack`–style simulation evidence is kept and
+labeled `verified-in-simulation`, but it never substitutes for a real smoke.
+
+### Release / nightly smoke setup
+
+External smoke runs in an **isolated** environment — a fresh temporary
+`HOME`/`PREFIX`/working directory — and executes only the exact command template
+declared in the spec, with controlled variables. Its artifact records exit code,
+version, and a redacted stdout/stderr summary; credentials are never written.
+
+Point the runner at an environment with `ROLL_SMOKE_ENV=release` (or `ci` /
+`nightly`); a declaration whose `environment` does not match the current one is
+reported `unverified`, never silently skipped. **No real publish or account
+action is ever automatic**: nothing that pushes a package, mutates a remote
+account, or spends money runs without a declared authority (an `external-smoke`
+command you wrote into the spec, or an `owner-attested` approval reference). If no
+matching smoke environment exists, the AC stays `unverified` and the report stays
+non-green — it is never auto-promoted to a manual pass.
+
 ## Declaring visual evidence at design time
 
 `roll story validate` checks, at design time, that a spec is *born* with a

package/guide/en/ai-agents.md

@@ -23,7 +23,7 @@ migration input, but it is no longer the primary authoring surface for agent
 semantics. Use:
 
 ```bash
-roll agent                      # show Machine Scope, Project Scope, roles, pool, and legacy inputs
+roll agent                      # show Machine Scope, effective Project Scope, and installed pool
 roll agent migrate --dry-run    # preview conversion from legacy files
 roll agent migrate              # write roll-agents/v1 files
 roll agent list                 # show installed agents
@@ -170,13 +170,13 @@ roll supervisor health --json      # machine-readable classifications
 roll supervisor next               # next card + agent health summary
 ```
 
-## Legacy Compatibility
+## Migration from Older Agent Config
 
-Older projects may still contain `.roll/local.yaml agent`, `.roll/pairing.yaml`,
-or v3 route slots in `.roll/agents.yaml`. `roll agent` shows them under
-`Legacy compatibility`, and `roll agent migrate` converts their useful data into
-the scoped model. They remain readable compatibility inputs, not the primary
-agent-management model.
+Older projects may contain `.roll/local.yaml agent`, `.roll/pairing.yaml`, or v3
+route slots in `.roll/agents.yaml`. These are not runtime inputs. Run
+`roll agent migrate --dry-run` to preview their one-time conversion, then
+`roll agent migrate` to write scoped bindings. A loop that encounters v3 route
+slots fails loudly instead of silently using a second configuration model.
 
 ## See Also