@seanyao/roll 4.630.1 → 4.702.2

package/guide/zh/tools.md

@@ -0,0 +1,173 @@
+# Roll — 工具与策略
+
+Roll 的 tools layer 是交付周期里执行副作用的受治理路径：shell 命令、浏览器检查、文件系统访问、git、GitHub、网络请求和 MCP 调用。
+
+tools layer 不是 AI 客户端自己的工具白名单替代品。客户端的 `allowed-tools` 决定内层 agent 能请求什么。Roll 的 tools layer 决定外层 harness 注册哪些工具、怎样解析项目策略、记录哪些事件，以及成本怎样进入 cycle 证据。
+
+工具层设计方案见 [../../.roll/features/tools-layer/plan.md](../../.roll/features/tools-layer/plan.md)。
+
+## 核心概念
+
+| 概念 | 含义 |
+|------|------|
+| 工具声明 | 工具的共享契约：id、kind、标题、默认值、依赖、输入输出 schema。 |
+| 注册表 | core 里的统一路径：注册工具、解析 policy、调用 adapter、发事件、重试、记录成本快照。 |
+| 适配器 | infra 里的具体实现，例如 `bash`、`browser.screenshot`、`git.push`、`network.fetch`。 |
+| 策略 | 工具声明默认值与 `.roll/policy.yaml` 覆盖合成后的有效配置。 |
+| 证据 | `tool:invoke`、`tool:result`、cycle 成本行、CLI 输出、attest report、dashboard 时间线。 |
+
+当前注册的工具族：
+
+| 工具族 | 工具 id |
+|--------|---------|
+| Bash | `bash` |
+| Browser | `browser.screenshot`、`browser.console`、`browser.dom-query` |
+| Filesystem | `filesystem.stat`、`filesystem.read`、`filesystem.write` |
+| Git | `git.status`、`git.commit`、`git.push`、`git.merge` |
+| GitHub | `github.pr`、`github.ci` |
+| MCP | `mcp.call` |
+| Network | `network.fetch` |
+
+完整的内置工具清单——每个工具的能力、输入/输出契约、默认护栏与依赖——可在机器全局 **Tools** 页（`tools.html`）浏览，它是 `MACHINE › …` 面包屑里与 Agents、Skills 同级的页面之一。
+
+## 项目策略
+
+工具策略写在 `.roll/policy.yaml` 的 `tools:` 段里。
+
+```yaml
+tools:
+  bash:
+    enabled: true
+    timeoutMs: 30000
+    maxInvocationsPerCycle: 20
+    sandbox:
+      allowedPaths: [.]
+      blockedCommands: [sudo]
+      maxOutputBytes: 65536
+
+  browser.screenshot:
+    timeoutMs: 60000
+    sandbox:
+      headlessOnly: true
+      allowedOrigins: [http://localhost:4173]
+
+  network.fetch:
+    retry:
+      attempts: 2
+      backoffMs: 250
+    sandbox:
+      network: restricted
+      allowedOrigins: [https://api.example.com]
+```
+
+支持字段：
+
+| 字段 | 范围 | 含义 |
+|------|------|------|
+| `enabled` | 工具 | `false` 会通过 policy 阻断调用。 |
+| `timeoutMs` | 工具 | adapter 使用的软超时；输入里更窄的限制可覆盖它。 |
+| `retry.attempts` | 工具 | 支持重试的 adapter 的最大尝试次数。 |
+| `retry.backoffMs` | 工具 | 两次重试之间的等待时间。 |
+| `maxInvocationsPerCycle` | 工具 | registry 执行的单 cycle 调用预算。 |
+| `sandbox.allowedPaths` | sandbox | 文件系统类 adapter 的路径白名单。 |
+| `sandbox.blockedCommands` | sandbox | bash 的 advisory 命令阻断列表。 |
+| `sandbox.hardTimeoutSec` | sandbox | 支持该字段的 adapter 的硬超时。 |
+| `sandbox.maxOutputBytes` | sandbox | 输出截断上限。 |
+| `sandbox.allowedOrigins` | sandbox | 网络或浏览器 origin 白名单。 |
+| `sandbox.headlessOnly` | sandbox | 浏览器 lane 必须保持 headless。 |
+| `sandbox.network` | sandbox | `inherit`、`restricted` 或 `blocked`。 |
+
+未知字段会告警但不会拒绝整个 policy 文件，方便新旧版本之间前向兼容。
+
+## CLI
+
+用 `roll doctor tools status` 查看当前项目已注册工具、输入契约、依赖就绪度和合成后的有效 policy 状态。
+
+```bash
+roll doctor tools status
+```
+
+示例输出：
+
+```text
+tool              kind        enabled  readiness    timeout  limit  contract                                       sandbox
+bash               bash        yes      available    30000    -      args?, command, cwd?, env?                     maxOutputBytes=65536
+browser.screenshot browser     yes      available    60000    -      screenshotPath?, url, viewport?, waitFor?      headlessOnly=true,maxOutputBytes=2097152
+network.fetch      network     yes      available    30000    -      body?, headers?, method?, timeoutMs?, url      network=restricted
+```
+
+修改 `.roll/policy.yaml` 后，可以用它确认 Roll 读到的状态符合预期。
+
+## 完整示例
+
+这个示例把浏览器截图限制在本地 dev server，先确认有效 policy，再说明一次交付完成后应该去哪里看工具证据。
+
+1. 为项目配置 browser 和 network policy：
+
+```yaml
+tools:
+  browser.screenshot:
+    timeoutMs: 60000
+    sandbox:
+      headlessOnly: true
+      allowedOrigins: [http://localhost:4173]
+
+  network.fetch:
+    timeoutMs: 10000
+    retry:
+      attempts: 2
+      backoffMs: 250
+    sandbox:
+      network: restricted
+      allowedOrigins: [http://localhost:4173]
+```
+
+2. 确认 Roll 解析到的 policy：
+
+```bash
+roll doctor tools status
+```
+
+预期能看到这些行：
+
+```text
+browser.screenshot browser     yes      60000    -      allowedOrigins=http://localhost:4173,headlessOnly=true,maxOutputBytes=2097152
+network.fetch      network     yes      10000    -      allowedOrigins=http://localhost:4173,network=restricted
+```
+
+3. 跑一个有可视网页面的交付。故事 spec 应声明要截图的页面：
+
+```yaml
+---
+deliverable_url: http://localhost:4173
+---
+```
+
+attest 阶段会通过 `browser.screenshot` 捕获这个页面。对 Roll 暴露的工具 id 是 `browser.screenshot`；底层可能使用 Playwright 或 Chrome，但 `playwright` 不是 policy key，也不是工具 id。
+
+4. 检查证据：
+
+```bash
+roll loop cycle <cycle-id>
+```
+
+寻找类似这样的行：
+
+```text
+tools browser.screenshot×1(2.0s) network.fetch×1(0.4s)
+```
+
+Story attest report 和 cycle 视图会从同一条事件流展示：
+
+| 证据 | 检查点 |
+|------|--------|
+| `tool:invoke` | 工具 id、调用 cycle、合成后的 policy。 |
+| `tool:result` | 成功或 errorCode、耗时、输出路径。 |
+| 截图链接 | `.roll/tool-dumps/...png` 或卡片目录里附加的截图路径。 |
+| 成本行 | 保留 USD、CNY/RMB 或 `¥`；混合币种不会被折成一个假的总额。 |
+
+## 证据与成本
+
+`roll loop status`、`roll loop cycle` 和 attest report 都会从事件流展示工具摘要。失败的工具调用保留 errorCode，截图工具可以直接链接到图片证据。
+
+工具成本保留原生币种。美元行仍是 USD。人民币行仍是 CNY/RMB 或 `¥`。Roll 不会把人民币计价的工具或模型成本标成美元，也不会把混合币种盲目加成一个数字。

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@seanyao/roll",
-  "version": "4.630.1",
+  "version": "4.702.2",
   "description": "Roll — Roll out features with AI agents",
   "packageManager": "pnpm@11.1.3",
   "scripts": {
     "test": "bash scripts/test-ts.sh",
     "lint:story-ids": "node scripts/lint-story-ids.mjs",
+    "lint:role-taxonomy": "node scripts/audit-role-taxonomy.mjs",
     "test:e2e": "pnpm -r build && pnpm --filter @roll/cli exec vitest run test/critical-flows.e2e.test.ts",
     "test:cov": "pnpm -r exec vitest run --coverage.enabled --coverage.provider=v8 --coverage.include='src/**' --coverage.reporter=text-summary --coverage.reporter=text",
     "bundle": "node scripts/bundle.mjs",
@@ -31,6 +32,8 @@
   "files": [
     "dist/",
     "conventions/",
+    "docs/",
+    "guide/",
     "lib/",
     "skills/",
     "template/",

package/skills/README.md

@@ -19,6 +19,7 @@ roll 的**技能契约**仓——AI agent 在 roll 项目里工作时加载并
 - `roll-fix` — 缺陷修复轻量链路（FIX 卡专用）
 - `roll-idea` — 一句话快速捕获 → 自动分类编号落 backlog
 - `roll-loop` — 无人值守 BACKLOG 执行器的工作流契约
+- `roll-prime` — Supervisor（supervise 角色）协同领袖：对账、派卡、只读盯场、失败归因、meta reconcile
 
 **Quality · 质量与评审**
 - `roll-peer` — 跨 agent 协商评审（三态协议 + 时间盒）

package/skills/roll-.qa/SKILL.md

@@ -48,4 +48,4 @@ Load when a build, fix, review, or story needs Roll QA coverage standards: test
 
 ## Role in v4 execution profiles
 
-These QA standards are an **Evaluator capability** in the `verified`/`planned` execution profiles: the independent Evaluator applies them to judge story satisfaction and produces an `eval-report.md` (blocking findings, advisory findings, score, attest/evidence status, recommendation) — distinct from CI feedback and from the Builder's self-report. (Roles: Supervisor Agent / Planner / Builder / Evaluator; never Prime/Watchman/Dispatcher/Governor.)
+These QA standards are an **Evaluator capability** in the `verified`/`designed` execution profiles: the independent Evaluator applies them to judge story satisfaction and produces an `eval-report.md` (blocking findings, advisory findings, score, attest/evidence status, recommendation) — distinct from CI feedback and from the Builder's self-report. Roles: Supervisor / Designer / Builder / Evaluator.

package/skills/roll-.review/SKILL.md

@@ -149,4 +149,4 @@ In each micro-step of `$roll-build`:
 
 ## Role in v4 execution profiles
 
-Self-review is a TCR-step quality gate **within the Builder role** — it is NOT story acceptance. In the `verified`/`planned` execution profiles the independent **Evaluator** (a fresh session, never the Builder's) judges whether the delivery satisfies the contract; blocking review, score, and attest stay three SEPARATE dimensions (never one pass/fail). This skill is one Evaluator capability among review/qa/scoring. (Roles: Supervisor Agent / Planner / Builder / Evaluator; never Prime/Watchman/Dispatcher/Governor.)
+Self-review is a TCR-step quality gate **within the Builder role** — it is NOT story acceptance. In the `verified`/`designed` execution profiles the independent **Evaluator** (a fresh session, never the Builder's) judges whether the delivery satisfies the contract; blocking review, score, and attest stay three SEPARATE dimensions (never one pass/fail). This skill is one Evaluator capability among review/qa/scoring. Roles: Supervisor / Designer / Builder / Evaluator.

package/skills/roll-build/SKILL.md

@@ -57,4 +57,4 @@ same TCR, evidence, Evaluator, and release gates apply in both modes.
 
 ## Role in v4 execution profiles
 
-**roll-build is the Builder capability in every execution profile** (`standard` / `verified` / `planned`). Under `planned` it receives the Planner's `planner-contract.md` via artifact refs (no shared raw session). Under `verified`/`planned` an independent **Evaluator** (a fresh session) judges the delivery and may open a BOUNDED repair round — you address the blocking findings and write a repair note mapping findings → changes. `standard` is Builder-only. (Roles: Supervisor Agent / Planner / Builder / Evaluator; never Prime/Watchman/Dispatcher/Governor.)
+**roll-build is the Builder capability in every execution profile** (`standard` / `verified` / `designed`). Under `designed` it receives the Designer's `design-contract.md` via artifact refs (no shared raw session). Under `verified`/`designed` an independent **Evaluator** (a fresh session) judges the delivery and may open a BOUNDED repair round — you address the blocking findings and write a repair note mapping findings → changes. `standard` is Builder-only. Roles: Supervisor / Designer / Builder / Evaluator.

package/skills/roll-build/references/full-contract.md

@@ -117,7 +117,7 @@ the command decides. The cap exists purely to stop infinite split chains.
 1. Open `.roll/backlog.md`, find the US row, follow the link to `.roll/features/<epic>/<story>/spec.md`
 2. Read the full AC / Files / Dependencies section
 3. If a plan doc (`<feature>-plan.md`) exists, read it for context
-4. **Read the Evaluation contract (US-SKILL-030)**: if the spec contains an `**Evaluation contract:**` block, read `expected_evidence` and `scorer_focus` before writing any code. This is the planner's artifact contract — use it to inform test design and evidence planning. Map each `expected_evidence` item to a planned Action or test; if an item is impossible given the actual scope, note the deviation in your report/ac-map. `builder_notes` carry planner hints — treat them as bounded guidance, not hidden requirements.
+4. **Read the Evaluation contract (US-SKILL-030)**: if the spec contains an `**Evaluation contract:**` block, read `expected_evidence` and `scorer_focus` before writing any code. This is the Designer's artifact contract — use it to inform test design and evidence planning. Map each `expected_evidence` item to a candidate Action or test; if an item is impossible given the actual scope, note the deviation in your report/ac-map. `builder_notes` carry Designer hints — treat them as bounded guidance, not hidden requirements.
 
 ### Step A3: Split into Actions
 
@@ -190,11 +190,11 @@ Before defining the verification, classify **each Action** on one axis:
 ```
 Action acceptance
   ├── YES (deterministic) → objective 4-stage loop  ← DEFAULT
-  │      Planner (AC/contract) → Tester (Phase 2 + write RED)
+  │      Designer/AC contract → Tester (Phase 2 + write RED)
   │      → Builder (Phase 3 TCR) → Evaluator (Phase 6, incl. Agent 4 test audit)
   │
   └── NO (judgment-dependent) → subjective 3-stage loop
-         Planner emits EXPLICIT evaluation criteria up front
+         Designer emits EXPLICIT evaluation criteria up front
          → Builder produces the output
          → an ISOLATED Evaluator scores the output against those criteria
 ```
@@ -542,7 +542,7 @@ Agent 3: Efficiency Review            (receives: full diff)
 Agent 4: Test Adequacy Review         (receives: AC/contract + test files ONLY)
   → Audit the TESTS, not the implementation. This agent does NOT receive
      the implementation diff or any builder reasoning — only (a) the Story's
-     AC / interface contract (the Planner artifact) and (b) the test files.
+     AC / interface contract (the Designer artifact) and (b) the test files.
   → AC ↔ assertion coverage: every AC has at least one test that would fail
      if that AC regressed. Flag any AC with no corresponding assertion.
   → Tautological / vacuous assertions: tests that only assert "did not throw",
@@ -720,7 +720,7 @@ story (loop or manual Phase 10.6) and earn the report at delivery time.
    ] }]
 ```
 
-   **Cross-reference with the Evaluation contract** (when present): each `expected_evidence` item in the contract maps to an AC via its `proves` field. When writing ac-map entries, ensure every `expected_evidence` item is addressed — the attest gate later surfaces a planned-vs-delivered delta from this mapping (US-SKILL-030).
+   **Cross-reference with the Evaluation contract** (when present): each `expected_evidence` item in the contract maps to an AC via its `proves` field. When writing ac-map entries, ensure every `expected_evidence` item is addressed — the attest gate later surfaces a design-contract-vs-delivered delta from this mapping (US-SKILL-030).
    No evidence for an AC → say `claimed` yourself; the renderer enforces that downgrade anyway (red line) and lists it under Discrepancies.
 3. **Run** `roll attest {ID}` (add `--deploy-url <url>` when one exists). The report lands at `.roll/features/<epic>/{ID}/latest/{ID}-report.html` (archive-per-card layout, US-META-001). The report is now layered (US-ATTEST-013): card context + conclusion/business badges + key screenshots up front, technical ANSI/command output folded into collapsed `<details>`, and a closing block (quality gate + evidence index + Review Score).
 4. **Design QA checklist (US-ATTEST-013) — READABILITY ONLY**. After the report
@@ -931,9 +931,10 @@ Reviewer that mints the Review Score (1..10 + verdict + rationale), recorded
 with `scoredBy` and the fresh-session id so independence is verifiable.
 
 Independence is about session/context, not vendor: a fresh same-vendor session
-is the minimum acceptable; a different agent+model+session (non-sub-agent) is
-encouraged (absolute heterogeneity). A score sharing the builder's session
-(including any sub-agent of it) is rejected as a self-score.
+is the minimum acceptable; a different agent+model+session (non-sub-agent) is a
+ranking preference unless the owner explicitly requested strict diversity. A
+score sharing the builder's session (including any sub-agent of it) is rejected
+as a self-score.
 
 Score guidance the Reviewer applies (integer 1..10):
 - **9..10** — story shipped cleanly: AC fully met, TCR rhythm tight, no
@@ -963,11 +964,13 @@ GAPS: <gap one; gap two; gap three>
 ```
 
 On a RESIZE signal (low score), the loop runs `roll loop review-resize <story>`:
-`$roll-design` mints sub-stories from the gaps, ≥2 **heterogeneous** reviewers
-gate the split by consensus (all agree → auto-land via `roll loop self-downgrade`,
-which parks the parent at 🚫 Hold + appends the sub-stories; any objection →
-pause + ALERT, backlog unchanged), and the chain-depth cap (US-AGENT-009) stops
-runaway splits. The human is **on** the loop (alerted only on consensus failure
+`$roll-design` mints sub-stories from the gaps, and ≥2 fresh-session reviewers
+gate the split by consensus. Prefer diverse agents/models when available, but do
+not block solely on matching brand/provider unless the owner requested strict
+diversity. When all agree, auto-land via `roll loop self-downgrade`, which parks
+the parent at 🚫 Hold + appends the sub-stories; any objection → pause + ALERT,
+backlog unchanged. The chain-depth cap (US-AGENT-009) stops runaway splits. The
+human is **on** the loop (alerted only on consensus failure
 or the cap), not in it. A RESIZE is never emitted for a pure quality problem.
 
 ---

package/skills/roll-design/SKILL.md

@@ -15,7 +15,7 @@ Load when the user wants to discuss approaches, design a solution, model domains
 ## Operating Modes
 
 Used in **guided** mode when the owner explicitly designs or splits work, and in
-**autonomous** mode only as the Planner capability selected by a `planned`
+**autonomous** mode only as the Designer capability selected by a `designed`
 execution profile. It must never silently start Builder work.
 
 ## When Not to Use
@@ -43,7 +43,7 @@ execution profile. It must never silently start Builder work.
 - Backlog rows and spec files must stay consistent.
 - Peer review gates apply only when explicitly available/requested.
 - No story decomposition until a detailed design exists and the owner has signed off (proportional to risk). Decomposition slices an agreed design — it is NOT a substitute for designing. If you cannot show at least one complete worked sample of the intended output/behavior, the design is NOT done.
-- **Evaluation contract (US-SKILL-030 — planner-builder-evaluator artifact contract)**: every newly split story spec MUST include an `**Evaluation contract:**` block with `expected_evidence` (each item: `kind`, `target`, `proves`) and `scorer_focus`. This artifact is authored by the planner and consumed by builder (roll-build/roll-fix reads before coding) and evaluator (peer score prompt reads the contract; attest surfaces planned-vs-delivered mapping) — not a fixed three-agent collaboration model. Genuinely trivial/internal stories may carry a one-item minimal block, but never omit it. See `references/full-contract.md` for the full template and rules.
+- **Evaluation contract (US-SKILL-030 — designer-builder-evaluator artifact contract)**: every newly split story spec MUST include an `**Evaluation contract:**` block with `expected_evidence` (each item: `kind`, `target`, `proves`) and `scorer_focus`. This artifact is authored by the Designer and consumed by Builder (roll-build/roll-fix reads before coding) and Evaluator (peer score prompt reads the contract; attest surfaces design-contract-vs-delivered mapping) — not a fixed three-agent collaboration model. Genuinely trivial/internal stories may carry a one-item minimal block, but never omit it. See `references/full-contract.md` for the full template and rules.
 - **Visual-evidence contract (FIX-311 — design-phase gate)**: every story spec is born honest. By default each story MUST carry one AC that captures its user-visible surface (web/CLI/TUI), and a web/visual card MUST declare the real product surface in its spec frontmatter — `deliverable_url:` (alias `screenshot_url:`) pointing at the actual deliverable page (e.g. `https://app.example.test/casting#board`), NEVER the card's own dossier/report/archive page. A card with genuinely no visual surface writes `screenshot_exempt: <reason>` (a naked `true`/`yes` is NOT a valid exemption — it must carry a reason). This is enforced, not advisory: `validateStoryVisualEvidence(specText)` in `packages/cli/src/lib/design-visual-evidence.ts` returns `ok:false` for a non-exempt spec with no visual-evidence AC, or one that declares a visual surface but no `deliverable_url`. Keyword matching may only RECOGNISE an exemption / an existing visual-evidence AC — it may NEVER be used to decide a card needs a screenshot (it always does, by default). This is the same contract the runtime enforce gate (FIX-309) and archive gate (FIX-334) hold; the three must agree.
 
 ## Gotchas
@@ -60,4 +60,4 @@ execution profile. It must never silently start Builder work.
 
 ## Role in v4 execution profiles
 
-In the `planned` execution profile, **roll-design is the Planner capability**: in a FRESH session before the Builder it writes a `planner-contract.md` (scope boundary, acceptance/evaluation contract, expected evidence, risks, out-of-scope items, resize/split guidance) that the Builder consumes via artifact refs. roll-design stays a skill — the TS engine owns orchestration and validates the contract fail-closed before the Builder starts. For pure design/backlog planning the user loads roll-design directly; it does not auto-trigger. (Roles: Supervisor Agent / Planner / Builder / Evaluator; never Prime/Watchman/Dispatcher/Governor.)
+In the `designed` execution profile, **roll-design is the Designer capability**: in a FRESH session before the Builder it writes a `design-contract.md` (scope boundary, acceptance/evaluation contract, expected evidence, risks, out-of-scope items, resize/split guidance) that the Builder consumes via artifact refs. roll-design stays a skill — the TS engine owns orchestration and validates the contract fail-closed before the Builder starts. For pure design/backlog planning the user loads roll-design directly; it does not auto-trigger. Roles: Supervisor / Designer / Builder / Evaluator.

package/skills/roll-design/references/full-contract.md

@@ -731,9 +731,9 @@ Note: `{DOMAIN}` maps to the Bounded Context name identified in DDD analysis.
 - builder_notes:
   - {bounded implementation/evidence hints; no hidden requirements}
 
-> **强制规则 — Evaluation contract 必须填**：每张新 story 必须带 `**Evaluation contract:**` 块（expected_evidence + scorer_focus）。这是 planner 写给 builder 和 evaluator 的验收契约——builder 编码前读 contract、交付后把 ac-map 项映射回 contract 的 expected_evidence；evaluator（peer score / attest gate）读 contract 对账。不是固定三 agent 协同模型，是 artifact-based 契约。真正 trivial/internal 故事可放一项 minimal block，但不许省略。
+> **强制规则 — Evaluation contract 必须填**：每张新 story 必须带 `**Evaluation contract:**` 块（expected_evidence + scorer_focus）。这是 Designer 写给 Builder 和 Evaluator 的验收契约——Builder 编码前读 contract、交付后把 ac-map 项映射回 contract 的 expected_evidence；Evaluator（peer score / attest gate）读 contract 对账。不是固定三 agent 协同模型，是 artifact-based 契约。真正 trivial/internal 故事可放一项 minimal block，但不许省略。
 >
-> **MUST fill** the `**Evaluation contract:**` block on every newly split story. This is an artifact contract authored by roll-design, consumed by builder (read before coding, map delivered evidence back) and evaluator (peer score prompt includes it, attest surfaces planned-vs-delivered). Genuinely trivial/internal stories may use a one-item minimal block, never omit it.
+> **MUST fill** the `**Evaluation contract:**` block on every newly split story. This is an artifact contract authored by roll-design as the Designer, consumed by Builder (read before coding, map delivered evidence back) and Evaluator (peer score prompt includes it, attest surfaces design-contract-vs-delivered). Genuinely trivial/internal stories may use a one-item minimal block, never omit it.
 
 **Spec frontmatter (visual-evidence contract — FIX-311):**
 - A web/visual card MUST declare the real product surface it delivers:
@@ -771,9 +771,9 @@ Note: `{DOMAIN}` maps to the Bounded Context name identified in DDD analysis.
 >
 > **MUST fill** the `**Agent profile:**` block on every newly split US. `est_min` is the **sole loop-routing input** — `lib/loop_pick_agent.py` maps it onto a four-slot complexity tier (easy/default/hard/fallback) on the est_min axis alone (missing/illegal → default). Fill `risk_zone` too, but note it does NOT feed routing; it only informs the roll-build / roll-fix pre-flight self-eval (US-AGENT-007).
 
-> **强制规则 — Evaluation contract 必须填（US-SKILL-030）**：每张新 story spec 都必须包含 `**Evaluation contract:**` 块，明确列出 `expected_evidence`（每项 kind/target/proves 三字段）和 `scorer_focus`（peer scorer 评分口径）。纯内部/无可见面的 trivial story 可使用 one-item 最小块，但不可省略。该块由 planner（`roll-design`）撰写，供 builder 和 evaluator 作为共享证据契约消费，不触发三 agent 协同会话。
+> **强制规则 — Evaluation contract 必须填（US-SKILL-030）**：每张新 story spec 都必须包含 `**Evaluation contract:**` 块，明确列出 `expected_evidence`（每项 kind/target/proves 三字段）和 `scorer_focus`（peer scorer 评分口径）。纯内部/无可见面的 trivial story 可使用 one-item 最小块，但不可省略。该块由 Designer（`roll-design`）撰写，供 Builder 和 Evaluator 作为共享证据契约消费，不触发三 agent 协同会话。
 
-> **Evaluation contract is required (US-SKILL-030)**: every newly split story spec MUST carry an `**Evaluation contract:**` block with `expected_evidence` (each item: `kind`, `target`, `proves`) and `scorer_focus` (scorer rubric). Genuinely trivial/internal stories may use a one-item minimal block but must not omit the section entirely. This block is authored by the planner (`roll-design`) and consumed as a shared artifact contract by builder (`roll-build`/`roll-fix`) and evaluator (peer scorer, attest gate) — no three-agent chat pipeline is introduced.
+> **Evaluation contract is required (US-SKILL-030)**: every newly split story spec MUST carry an `**Evaluation contract:**` block with `expected_evidence` (each item: `kind`, `target`, `proves`) and `scorer_focus` (scorer rubric). Genuinely trivial/internal stories may use a one-item minimal block but must not omit the section entirely. This block is authored by the Designer (`roll-design`) and consumed as a shared artifact contract by Builder (`roll-build`/`roll-fix`) and Evaluator (peer scorer, attest gate) — no three-agent chat pipeline is introduced.
 >
 > **Block template:**
 > ```markdown
@@ -790,13 +790,13 @@ Note: `{DOMAIN}` maps to the Bounded Context name identified in DDD analysis.
 >
 > **Rules**: (1) `expected_evidence` items are **binding for evidence expectations** — if an item becomes impossible, the builder updates the spec or explains the deviation in the report/ac-map. (2) `scorer_focus` items extend, not replace, the generic scoring rubric. (3) This block complements the visual-evidence contract; `deliverable_url`/`screenshot_exempt` rules are unchanged. (4) Legacy specs without the block degrade gracefully — builder and scorer fall back to the generic rubric with no behavior change.
 
-### Closing Doc-Refresh Story Template — Phase N.M 收尾文档
+### Closing Doc-Refresh Story Template — Phase N.M Documentation Refresh
 
 When any preceding US in the batch changes user-visible behavior, append this template story at the end of the batch. Wire it as `depends-on:` against every preceding user-facing US so it runs last.
 
 ```markdown
 <a id="us-{domain}-{n}"></a>
-## US-{DOMAIN}-{N} Phase {N.M} 用户文档刷新（中英双轨） 📋
+## US-{DOMAIN}-{N} Phase {N.M} documentation refresh 📋
 
 **Created**: {YYYY-MM-DD}
 
@@ -805,11 +805,12 @@ When any preceding US in the batch changes user-visible behavior, append this te
 - So that the next person reading the guide / README / `--help` does not hit a stale version
 
 **AC:**
-- [ ] Update each affected doc file listed below; **English line and Chinese line on separate lines**, never inline
+- [ ] Update each affected doc file listed below; each rendered page is single-language for its locale
 - [ ] `roll <cmd> --help` output reflects new flags / commands / status semantics (paste verified output)
 - [ ] README index links to any new guide pages
 - [ ] Error-message changes are mirrored in troubleshooting / FAQ sections
 - [ ] Verified: no doc page still describes the pre-Phase behavior
+- [ ] Locale resources/catalog entries stay consistent across affected `en` and `zh` surfaces
 
 **Files:**
 - `guide/en/{topic}.md`
@@ -875,7 +876,7 @@ emits no quality score; the agent just delivers the split + specs and stops.
 A design has **no executable pass/fail test** — correctness is judgment. So it is
 the canonical **3-stage loop**, and naming the stages keeps the roles honest:
 
-- **Planner / Builder = this design session.** Besides the split + specs, it must
+- **Designer = this design session.** Besides the split + specs, it must
   emit **explicit evaluation criteria for the design itself** — the prose
   equivalent of a test contract: what would make this design wrong or incomplete
   (e.g. "every Bounded Context boundary is justified", "the worked sample covers
@@ -886,7 +887,8 @@ the canonical **3-stage loop**, and naming the stages keeps the roles honest:
   criteria, and **must not be seeded with the designer's reasoning** (roll-peer's
   Independent Judgment Rule already enforces exactly this — see the two
   `[peer]` checkpoints in the Workflow: Direction Review and Plan Review). A
-  fresh same-vendor session is the minimum; a different agent+model is encouraged.
+  fresh same-vendor session is the minimum; a different agent+model is a ranking
+  preference unless the owner explicitly requested strict diversity.
 
 Until the runner's FIX-344 stage lands, the isolated Evaluator is the
 `$roll-peer` Plan Review checkpoint, not an automated score — but the criteria
@@ -975,19 +977,21 @@ guide notices.
 - 安全 / 隔离基础设施（沙箱配置、权限矩阵内部调整）
 - 测试基础设施 / fixture 数据更新
 
-**Checklist for the doc-refresh story (中英双语必需)：**
+**Checklist for the doc-refresh story (locale consistency required):**
 - [ ] `guide/en/<topic>.md` — English guide updated
 - [ ] `guide/zh/<topic>.md` — Chinese guide updated
 - [ ] `README.md` index links to any new doc page
 - [ ] `--help` output snapshot matches new flags / commands / status semantics
 - [ ] Error-message strings reflected in troubleshooting / FAQ
-- [ ] **Bilingual rule**: English and Chinese on **separate lines**, never inline
-      （遵循 project CLAUDE.md 中 Bilingual Output Convention）
+- [ ] **Language surface rule**: each rendered page/output uses exactly one
+      locale; multilingual source resources stay behind `guide/en`, `guide/zh`,
+      or catalog boundaries
 
 **How to wire the doc-refresh story:**
 1. Place it **last** in the batch
 2. `depends-on:` lists **every** preceding user-facing US in the batch
-3. Title 用 "Phase N.M 用户文档刷新（中英双轨）" 模板（见 [Story Format](#story-format) 中的模板）
+3. Use the "Phase N.M documentation refresh" title template from
+   [Story Format](#story-format)
 4. Cite a worked example in its Dependencies note — current best reference is
    `features/authoring/slide-deck-generator.md` US-DECK-015 (roll slides Phase 1.5)
 

package/skills/roll-fix/SKILL.md

@@ -57,4 +57,4 @@ modes.
 
 ## Role in v4 execution profiles
 
-**roll-fix is the Builder capability for hot-fix scope** (a single issue), normally under the `standard` execution profile — the same TCR/test/attest flow as roll-build, with no Planner or Evaluator. A fix that turns out user-visible or evidence-risky is selected into `verified`; one that turns out cross-module or ambiguous into `planned`. (Roles: Supervisor Agent / Planner / Builder / Evaluator; never Prime/Watchman/Dispatcher/Governor.)
+**roll-fix is the Builder capability for hot-fix scope** (a single issue), normally under the `standard` execution profile — the same TCR/test/attest flow as roll-build, with no Designer or Evaluator. A fix that turns out user-visible or evidence-risky is selected into `verified`; one that turns out cross-module or ambiguous into `designed`. Roles: Supervisor / Designer / Builder / Evaluator.

package/skills/roll-fix/references/full-contract.md

@@ -20,7 +20,7 @@ Use when:
 
 **Workflow:**
 1. Read .roll/backlog.md index → Find FIX/BUG row → Follow link to `.roll/features/<epic>/<story>/spec.md`
-2. **Read the Evaluation contract (US-SKILL-030)** if the spec contains an `**Evaluation contract:**` block. Read `expected_evidence` and `scorer_focus` before writing code; use them to guide test design and evidence collection. Map each evidence item to a planned change and map delivered evidence back to the contract in the ac-map; note any deviation if an item turns out to be N/A for a fix.
+2. **Read the Evaluation contract (US-SKILL-030)** if the spec contains an `**Evaluation contract:**` block. Read `expected_evidence` and `scorer_focus` before writing code; use them to guide test design and evidence collection. Map each evidence item to a candidate change and map delivered evidence back to the contract in the ac-map; note any deviation if an item turns out to be N/A for a fix.
 3. Single Action (no splitting)
 4. Execute via TCR workflow
 5. Write back: update .roll/backlog.md status column + update FIX section in Feature file
@@ -526,9 +526,10 @@ Review Score (1..10 + verdict + rationale), recorded with `scoredBy` and the
 fresh-session id so independence is verifiable.
 
 Independence is about session/context, not vendor: a fresh same-vendor session
-is the minimum acceptable; a different agent+model+session (non-sub-agent) is
-encouraged (absolute heterogeneity). A score sharing the builder's session
-(including any sub-agent of it) is rejected as a self-score.
+is the minimum acceptable; a different agent+model+session (non-sub-agent) is a
+ranking preference unless the owner explicitly requested strict diversity. A
+score sharing the builder's session (including any sub-agent of it) is rejected
+as a self-score.
 
 Score guidance the Reviewer applies (integer 1..10):
 - **9..10** — clean root-cause fix; regression test added; TCR cycle smooth.
@@ -556,12 +557,14 @@ GAPS: <gap one; gap two; ...>
 ```
 
 On a RESIZE signal (low score) the loop runs `roll loop review-resize FIX-XXX`:
-`$roll-design` mints sub-stories from the gaps, ≥2 **heterogeneous** reviewers
-gate the split by consensus (all agree → auto-land via `roll loop self-downgrade`,
-parking the FIX at 🚫 Hold + appending sub-stories; any objection → pause +
-ALERT, backlog unchanged), with the chain-depth cap (US-AGENT-009) stopping
-runaway splits. The human is on the loop (alerted only on consensus failure or
-the cap), not in it. Never emit RESIZE for a pure quality problem.
+`$roll-design` mints sub-stories from the gaps, and ≥2 fresh-session reviewers
+gate the split by consensus. Prefer diverse agents/models when available, but do
+not block solely on matching brand/provider unless the owner requested strict
+diversity. When all agree, auto-land via `roll loop self-downgrade`, parking the
+FIX at 🚫 Hold + appending sub-stories; any objection → pause + ALERT, backlog
+unchanged. The chain-depth cap (US-AGENT-009) stops runaway splits. The human is
+on the loop (alerted only on consensus failure or the cap), not in it. Never emit
+RESIZE for a pure quality problem.
 
 ## Rubric
 

package/skills/roll-peer/SKILL.md

@@ -48,4 +48,4 @@ Load when the user explicitly asks for peer review, cross-agent negotiation, /pe
 
 ## Role in v4 execution profiles
 
-Cross-agent peer review is an **Evaluator capability**: an independent fresh-session reviewer (never the Builder's session) scores the delivery. The Evaluator's judgment is binding for story satisfaction; peer negotiation is the mechanism. In `verified`/`planned` profiles this feeds the `eval-report.md`. (Roles: Supervisor Agent / Planner / Builder / Evaluator; never Prime/Watchman/Dispatcher/Governor.)
+Cross-agent peer review is an **Evaluator capability**: an independent fresh-session reviewer (never the Builder's session) scores the delivery. The Evaluator's judgment is binding for story satisfaction; peer negotiation is the mechanism. In `verified`/`designed` profiles this feeds the `eval-report.md`. Fresh-session independence is required; agent/model diversity is a preference or explicit owner-requested mode, not a default brand rejection. Roles: Supervisor / Designer / Builder / Evaluator.

package/skills/roll-prime/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: roll-prime
+license: MIT
+allowed-tools: "Read, Glob, Grep, Bash(git:*), Bash(roll:*), Bash(node:*), Bash(tmux:*), Bash(tail:*), Bash(rg:*), Skill, Agent"
+description: "Load when coordinating a Roll project as Supervisor (supervise role): reconcile backlog truth, advise the owner, dispatch the Delta Team, watch cycles read-only, diagnose structural failures, and reconcile .roll meta — not when implementing a Story as Builder."
+---
+# Roll Supervisor
+
+Supervisor is the project-level leader of the Roll harness: set direction, keep the
+team aligned, watch the field, and say **"Agents, roll out"** — dispatch the Delta
+Team (Designer / Builder / Evaluator) and Peers to execute Stories. You
+coordinate with the owner; you are not the default Builder.
+
+This hub keeps the role boundary, hard gates, and runbook skeleton in context.
+Load the full supervisor contract only when you are actively coordinating.
+
+## Load
+
+Load when coordinating a Roll project as **Supervisor** (`supervise` role) in guided
+mode: clearing backlog scope, watching loop cycles, diagnosing failures,
+salvaging gates, or reconciling `.roll` meta — **not** when implementing a
+Story as Builder (`roll-build` / `roll-fix`).
+
+## Operating Modes
+
+- **Guided (default for Supervisor)**: owner + Supervisor collaborate. Read
+  `roll supervisor next/why --json`, reconcile truth, then dispatch with
+  `roll loop go`. Watch read-only; confirm before mutating project state.
+- **Autonomous**: `roll loop on` runs the scheduler. Supervisor still advises and
+  escalates; do not fight the scheduler without `roll loop pause` and owner
+  alignment.
+- Pair with **`roll-loop`** for scheduler/loop mechanics; Supervisor owns
+  coordination discipline, not runner internals.
+
+## When Not to Use
+
+- Implementing a US/FIX/REFACTOR card as Builder → `roll-build` / `roll-fix`.
+- One-shot code review on a diff → `roll-peer` / `roll-review-pr`.
+- Designing or splitting new stories from vague input → `roll-design`.
+
+## Read On Demand
+
+- [Supervisor prompt](references/supervisor-prompt.md) — full Supervisor operating
+  contract (US-V4-021 aligned).
+- [Explorer annex](references/explorer-annex.md) — read-only sub-session for
+  deep failure diagnosis.
+- Project overlay: `.roll/prime.local.md` when present (roll-meta).
+
+## Workflow Skeleton
+
+1. Lock explicit backlog scope (US + FIX + REFACTOR unless owner narrows).
+2. Reconcile truth (`supervisor next/why`, git main + `.roll`, events, PRs).
+3. Select next card; explain cast (Designer / Builder / Evaluator / Peers).
+4. Clean gate → `roll loop go --cards <id> --max-cycles 1`.
+5. Watch cycles read-only (events + worktree; 0 TCR ≠ auto-fail if still moving).
+6. Stop on structural failure; diagnose before blind retry.
+7. Salvage deliberately (`repair-evidence`, recover, independent evaluator).
+8. Reconcile `.roll` meta after product truth (PR/CI/main).
+
+## Hard Gates
+
+- Facts from `roll supervisor --json` and events — not Builder self-report.
+- Never bypass TCR, peer, evaluator, attest, PR, CI, merge, or release gates.
+- Never `git push` / `gh pr create` as Supervisor during a Builder cycle.
+- Persistent policy changes need owner confirmation.
+- Pause live workers before hand-editing `.roll/backlog.md` or specs.
+
+## Gotchas
+
+- Do not load this skill for Builder implementation; mixing Supervisor coordination and
+  Builder TCR on the same card blurs gates and pollutes worktrees.
+- `roll supervisor live` is a snapshot board, not Supervisor itself; prefer
+  `supervisor next/why --json` plus `roll loop watch` for ongoing cycles.
+- When CLI JSON and narrative disagree, trust structured supervisor output and
+  `events.ndjson`, then explain the delta to the owner.
+- Spawn explorer sub-sessions for deep diagnosis; do not turn Supervisor into a
+  200-command polling loop without decisions.

package/skills/roll-prime/references/explorer-annex.md

@@ -0,0 +1,39 @@
+# Supervisor Explorer Annex — Read-Only Deep Diagnosis
+
+Use when Supervisor needs evidence-heavy investigation without polluting the main
+coordination session.
+
+## When to spawn
+
+- Repeated or structural cycle failure (3+ angles: events, worktree, agent log).
+- Gate floor mismatches (attest produced but gate says missing structured content).
+- `handoff_without_tcr`, leaked commits, rescue branches, outcome vs terminal drift.
+
+## Explorer rules
+
+- **Read-only.** No edits to product repo, Builder worktrees, or `.roll` meta.
+- **No dispatch.** Do not `loop go`, `recover`, or `repair-evidence`.
+- **Evidence only.** Output: conclusion + file:line + event refs + recommended
+  Supervisor action (recover / salvage / FIX card / owner).
+
+## Suggested commands
+
+```bash
+rg -n "<cycle-id>" .roll/loop/events.ndjson | tail -200
+git -C .roll/loop/worktrees/cycle-<id> status --short
+git -C .roll/loop/worktrees/cycle-<id> diff --stat
+tail -n 80 .roll/loop/cycle-logs/<cycle-id>.agent.log
+nl -ba packages/... | sed -n '...'   # only when classifying harness bugs
+```
+
+## Handback to Supervisor
+
+Return a short brief:
+
+1. **Verdict** (one line)
+2. **Root cause class** (runner / agent / toolchain / card scope / gate contract)
+3. **Artifacts** (paths + line refs)
+4. **Recommended next move** (exact `roll` command or backlog card)
+
+Supervisor synthesizes for the owner; explorer does not speak to the owner directly
+unless Supervisor delegates.