@seanyao/roll 4.630.2 → 4.702.2

package/CHANGELOG.md

@@ -2,6 +2,69 @@
 
 ## Unreleased
 
+## v4.702.2 — 2026-07-02
+
+### Breaking changes
+- Role taxonomy is now cut over to Supervisor / Designer / Builder / Evaluator. Designed cycles use `execution_profiles.designed`, `roles.designer`, and `role-artifacts/designer/design-contract.md`; retired keys now fail loudly instead of aliasing. See `docs/migration/role-taxonomy-v4.md` for the manual config update. (REFACTOR-ROLE-001..008)
+
+### Automation pipeline
+- Default project agent routing now uses open execute/evaluate pools with capability and health-aware ranking. Fresh sessions are the review isolation boundary; agent/model diversity is a preference or explicit strict mode, not a default hard exclusion. (REFACTOR-ROLE-008, US-AGENT-049)
+
+### Acceptance evidence
+- `roll design` now writes a Design Review Page so you can inspect the plan, flow, and prototype before build starts. (US-REVIEW-001, US-REVIEW-002)
+  <!-- evidence: .roll/features/review-pages/US-REVIEW-001/latest/US-REVIEW-001-report.html -->
+  <!-- evidence: .roll/features/review-pages/US-REVIEW-002/latest/US-REVIEW-002-report.html -->
+- Acceptance gates now follow the work type: UI still needs real visual proof, while contract-heavy work can pass with tests, build, grep, and CI. (US-QA-015)
+  <!-- evidence: .roll/features/qa-testing/US-QA-015/latest/US-QA-015-report.html -->
+
+### Observability
+- `roll supervisor live --watch` keeps the Supervisor Live role board open and redraws it in-place from the same event-backed view model. Snapshot and JSON modes remain unchanged; watch mode is interactive-only and supports `--interval <sec>`. (FIX-1035)
+
+## v4.702.1 — 2026-07-02
+
+### 可见性
+- `roll cycles` 现在能看清 Builder 和模型身份，不再把内部模型名当成 agent（FIX-1066, FIX-1067）`[loop-observability]`
+- 协同视图补齐协议图例，TCR 节奏能区分活跃大步和真实停滞（US-OBS-037, US-OBS-042）`[loop-observability]`
+- CLI、HTML 和文档现在按单一语言显示，并说明如何切换和审计语言表面（US-LANG-001, US-LANG-003, US-LANG-004, US-LANG-005）`[i18n]`
+
+### 自动化流水线
+- Cursor 进入正式 agent roster，角色选角也会结合能力和健康状态排序（US-AGENT-048, US-AGENT-049）`[agents]`
+- Builder 路由会避开 Prime 角色，并解释候选池、排除原因和最终选择（FIX-1047）`[loop-engine]`
+- 公开命令面有了真相源，辅助命令收入口径和帮助文档保持一致（REFACTOR-056, REFACTOR-057, REFACTOR-058, REFACTOR-059）`[cli]`
+
+### 稳定性
+- Builder 不再能绕出 cycle worktree 留下泄漏提交，收尾前也会先过硬闸（FIX-1068, FIX-1069）`[loop-engine]`
+- PR 合并对账和补证恢复更可靠，绿 PR 不再因为缺验收页或分数识别卡住（FIX-1057, FIX-1058, FIX-1061）`[loop-engine]`
+- loop worktree 里的链接式卡片 spec 能被 attest 正常识别（FIX-1059）`[loop-engine]`
+- Reasonix setup 不再把 docs/reports 等辅助目录挂成 agent skill（FIX-1042）`[skill-ecosystem]`
+- Builder cycle 现在会把 `cd` 回主 checkout 后产生的本地 main 提交判为 sandbox boundary violation，记录泄漏提交数和 cwd 线索，并阻止它被当成 TCR 交付证据 `[loop-engine]`
+- `roll supervisor repair-evidence` 现在能救回卡在证据门的绿 PR，不用手动合并或重跑整张卡 `[loop]`
+- `roll supervisor repair-evidence` 已修复的 PR 重跑不再误报无法修复 `[loop]`
+  <!-- evidence: .roll/features/loop-engine/FIX-1062/latest/FIX-1062-report.html -->
+- `roll cycles` 不再把旧失败轮误标为 delivered `[loop]`
+- 等待 PR 合并的 cycle 证据不再被归档为失败诊断 `[loop]`
+- **`aborted_no_delivery` 周期不再丢失 story/agent 归属**：外部信号终止的 cycle 会从已写入的 events.ndjson 回填已知的 `story_id` 与 `agent`；如果在路由完成前被终止，`agent` 字段会保留空值并附带 `agent_unknown_reason`，避免失败匿名化，`roll cycles` 也能正确显示对应卡片与 agent。(FIX-1060) `[loop-engine]`
+
+### 文档与命名
+- **持续刷新的 loop 摘要不再叫 "Morning Report"**：这个从 events/runs 持续重建、窗口为最近 12 小时的 digest 不管白天还是夜里都在刷新，叫 "Morning Report" 会误导白天查看的运营者。现在改叫 Loop Digest（循环摘要），主路径换成 `.roll/reports/loop/latest.html`，Truth Console 上直接露出链接。旧的 `reports/morning/latest.html` 作为兼容别名继续写一版，已有链接不会断开。(FIX-1048) `[loop-observability]`
+
+
+- **两个核心概念改回更好记的名字**：项目级协调者从“Supervisor Agent”改名“Prime Agent”，交付一张 Story 的角色组合（规划/构建/评估）从“Story Execution Unit”改名“Delta Unit”。CLI 输出、文档、指南、宣传站、技能说明三端统一用新名。命令 `roll supervisor` 与内部代码标识符暂时保留原名作兼容，用户面一律读作 Prime Agent，下次大版本再评估是否连命令一起改。这是对 2026-06-27 一次改名的回退，回到 owner 更喜欢的原始命名。(REFACTOR-054)
+
+### 自动化流水线
+
+- **评分更能读懂 Reasonix/Kimi 的回复了**：有的评审会重绘终端、把同一段最终分数打印两遍，或先回显模板和分析再给真正答案；现在 Roll 会取最后一段可用的分数块，只要重复的分数和结论一致就采信，模板占位、真正冲突的两个不同分数、越界分数、不支持的结论仍会被拒。被拒时，`roll cycle <id> --roles` 会写出具体原因，并区分“给了类分数文本但没被采信”和“根本没返回分数内容”，不再是笼统的 unparseable。(FIX-1045) `[loop-engine]`
+- **卡死在“无进展”的目标有了可审计的换人恢复路径**：当 loop 因连续无进展自动停下一张卡时，不再是个看不出原因、也走不出去的死角。`roll supervisor why` 会显示卡住的卡、连续无进展次数、上一个失败的 Builder、下一个可换的 Builder，以及如何查看上一次失败 cycle 留下的现场。新命令 `roll loop recover <卡号>` 先预览这些信息；加 `--apply` 后，在有“另一个”可用 Builder 时清掉这张卡的熔断计数、让它能被下一个 Builder 再试一次（不用手删 `goal.yaml` 或改内部状态）；没有可换的 Builder 时会明确拒绝并说明原因。每次恢复都会记一条事件，写明是谁恢复的、跳过/选了哪个 Builder、为什么允许重试——熔断器不会被悄悄绕过；没人来手动恢复时，无进展熔断照常拦住盲目重试。(FIX-1049) `[loop-engine]`
+- **Reasonix / agy cycle 用量也能被 ledger 记录了**：Reasonix 跑完后会在 stdout 留下 `tok · in X · out Y · ¥Z` 用量页脚，Roll 现在会解析这个页脚并把 token、cost 写进 cycle ledger；agy / gemini 的 `-p` 输出本身不含用量，runner 会显式记录 `agy_stdout_no_usage` 原因，不再笼统地标成 `usage_unknown`。`roll cycles --json` 会带出具体原因，方便区分"解析失败"和"agent 确实没输出用量"。(FIX-1050) `[loop-engine]`
+- **agy 内部工具失败不再被当成普通 gave-up**：当 agy 退出码为 0 但 stdout 只剩控制字符、且 native antigravity CLI 日志里出现 `GREP_SEARCH` 超时或 `trajectory converted to zero chat messages` 等内部错误时，Roll 会把 cycle 终态记为 `agent_internal_failure`，在 ledger、`roll cycles --detail` 和 ALERT 里带上原生错误类别、摘要和日志路径，而不是隐藏成无输出的 gave-up。(FIX-1051) `[loop-engine]`
+- **agy 登录一次后就能参与无人值守的评审/打分了**：以前即便你已经在终端里登录过 agy，loop 在后台拉起它做评审或打分时还是会反复报"登录失败"，因为后台进程看不到你登录留下的凭据。现在 agy 会带着和你手动使用时相同的登录环境启动，登录过一次就能安静地参与循环，不再打断你去重新确认。新命令 `roll agent readiness agy` 可以先检查 agy 在后台能不能正常登录：能就直接说 ok，不能就明确告诉你缺什么、怎么恢复（只报路径和变量名，绝不打印任何密钥）。万一登录真的失效了，agy 会被临时挂起并留下一条可见记录，等你重新登录后自动恢复；纯网络波动不会被误判成登录问题。(FIX-1056) `[loop-engine]`
+- **已交付的故事不再在 cycle 账本里显示"未发布"**：当一个 story 已经合并到 main 并出现在交付记录里，但较早的 cycle 行因为当时 publish 没完成、`runs.jsonl` 里还是 `unpublished`，`roll cycles` 现在会检查交付真相、把该行标记为 `delivered`，不再让已上线的成果看起来像"没发出去"。同时，`roll truth query` 能在交付记录缺少 PR 编号时，从合并提交的正文里找回 PR 编号，不再报 `pr_number_no_publish_attempted`。(FIX-1046) `[loop-engine]`
+  <!-- evidence: .roll/features/loop-engine/FIX-1046/latest/FIX-1046-report.html -->
+
+### 新功能
+
+- **`roll design` 现在会给出一个可读的运行摘要和产物交付块**：运行前显示目标、模式、agent 和原始记录路径；运行中默认只渲染关键进度行，原始 agent 输出保存到 `.roll/runs/design/<timestamp>-<target>/transcript.log`；结束后交付块列出设计产物（`spec.md#detailed-design`）、生成的 HTML、新建卡片数、当前状态和下一步动作。`--verbose` 可查看 assistant 详细文本，`--raw` 可输出完整记录。(FIX-1055) `[legacy-onboard]`
+
 ## v4.630.2 — 2026-06-30
 
 ### 自动化流水线
@@ -11,6 +74,7 @@
 ### 可见性
 
 - **v4 角色日志入口补齐**：文档说明 Builder、Peer Reviewer、Evaluator、采信分数和解析失败原始产物分别该去哪里看，方便 supervisor 诊断多 agent 协作链路。(US-OBS-036) `[loop-observability]`
+- **协同视图数据底座就位**：新增 `collab-view.v1` 投影，从事件流和 CycleRoleSummary 派生换手、升级与 supervisor 姿态，为 `roll cycle --collab` 和 `roll supervisor live --collab` 提供类型稳定的数据契约。(US-OBS-038) `[loop-observability]`
 
 ## v4.630.1 — 2026-06-30
 

package/README.md

@@ -55,13 +55,31 @@ brief, onboard plan, backlog, and Roll markers, then prints one best next
 command instead of a menu.
 First time through? Start with [Getting started](guide/en/getting-started.md).
 
+## Language Surfaces
+
+Roll renders one visible language per user surface. `ROLL_LANG=en|zh` pins the
+current process, `roll config lang en|zh` persists a preference, and
+`roll config lang --reset` returns to locale detection. `roll help --lang en|zh`
+is available for one-off guide/help reads, and `roll doctor language` audits
+docs, conventions, skills, and generated surfaces for mixed-language drift.
+
+Agent contracts, code comments, git metadata, and TypeScript identifiers stay in
+English as the harness contract layer. Owner conversation follows the owner's
+language. User docs live in separate locale files under `guide/en/` and
+`guide/zh/`; contributors should update the matching locale file or i18n catalog
+instead of placing translation pairs in the same rendered surface. Snapshot
+coverage for the current language controls lives in
+`packages/cli/test/cli-language-surface.test.ts`,
+`packages/cli/test/__snapshots__/cli-language-surface.test.ts.snap`, and
+`packages/cli/test/doctor-language.test.ts`.
+
 ## V4 Supervisor Execution
 
 Roll V4 separates project coordination from story delivery:
 
-- **Supervisor Agent** coordinates at project level: backlog order, cross-Story context, route advice, repeated failures, release readiness, budget, and owner escalation. It observes and advises; it does not implement a Story or override evidence gates.
-- **Story Execution Unit** delivers one Story through scoped roles: `execute` performs the Story work, `evaluate` reviews/scores evidence, and `supervise` coordinates above the Story boundary.
-- **supervise / execute / evaluate roles** are stable contracts. The concrete `agent` and optional `model` are resolved through the Agent Scope model: `Scope -> Role -> Binding -> Agent -> Model`.
+- **Supervisor** coordinates at project level: backlog order, cross-Story context, route advice, repeated failures, release readiness, budget, and owner escalation. It observes and advises; it does not implement a Story or override evidence gates.
+- **Delta Unit** delivers one Story through scoped roles: `design` produces the Designer contract when the profile needs it, `execute` performs the Builder work, `evaluate` reviews/scores evidence, and `supervise` coordinates above the Story boundary.
+- **supervise / design / execute / evaluate roles** are stable contracts. The concrete `agent` and optional `model` are resolved through the Agent Scope model: `Scope -> Role -> Binding -> Agent -> Model`.
 - **Skills remain** the capability layer. Roles invoke `$roll-design`, `$roll-build`, `$roll-fix`, `$roll-peer`, `$roll-.qa`, and related skills instead of rewriting those contracts into TypeScript.
 - **Fallback is fail-loud**. If a requested agent or rig is unavailable, Roll records that unavailability and pauses or asks for owner action; it does not silently pretend another agent was used.
 
@@ -84,12 +102,14 @@ profiles, evidence, Evaluator, and release gates:
 
 - **guided** — the owner drives through `roll supervisor status/next/why` and
   starts work explicitly with commands such as `roll loop go --cards <id>`.
-  Guided mode never silently starts long-running Story execution.
+  Guided mode never silently starts long-running Story execution. When the
+  scheduler is off, `roll loop go` runs a manual goal; when the loop is paused,
+  use `roll loop resume` before scheduled work can continue.
 - **autonomous** — `roll loop on` installs the scheduler; eligible Stories may
   be picked within the existing pause, budget, route, evidence, Evaluator, and
   release gates. `roll loop pause` / `roll loop off` return control to guided
   operation; `roll loop resume` / `roll loop on` switch back explicitly.
-- **Attest and evidence are story-scoped**. A Story is accepted through its own `latest/<id>-report.html`, AC map, and screenshots/test artifacts.
+- **Attest and evidence are story-scoped**. A Story is accepted through its own Acceptance Review Page (`latest/<id>-review.html`), AC map, and screenshots/test artifacts. `latest/<id>-report.html` remains a legacy alias for one release cycle.
 
 Agent bindings are declared in two files: `~/.roll/agents.yaml` for Machine Scope
 and `.roll/agents.yaml` for Project Scope. A Project can inherit the machine pool
@@ -109,15 +129,19 @@ defaults:
         strategy: first-available
       evaluate:
         kind: select
-        from: [claude, codex, kimi, pi, agy, reasonix]
+        from: [claude, codex, kimi, pi, agy, reasonix, cursor]
         require: [evaluate]
-        avoid: [execute]
-        strategy: least-recent
+        strategy: health-aware
 ```
 
 Runtime availability is explicit: if a candidate is not callable on the current
 machine because of auth, network, VPN, or account state, the current resolution
 records that limitation instead of rewriting the static pool.
+For open role casting, `strategy: health-aware` keeps the installed pool visible
+and ranks candidates by capability, recent health, successful deliveries, recent
+use, and cost band. Inspect a cast with
+`roll supervisor route --role builder --story <id> [--json]`; the trace lists
+every candidate, warnings, skipped facts, reasons, and the selected agent.
 
 ## Onboarding Samples
 
@@ -133,7 +157,7 @@ roll design --from-file .roll/brief.md
 roll loop on
 ```
 
-Roll explains the next design step instead of inventing fake work. The Supervisor turns the requirement into Stories, resolves `execute` and optional `evaluate` roles per Story, and the owner reviews story-scoped attest evidence.
+Roll explains the next design step instead of inventing fake work. The Designer turns the requirement into Stories, the Supervisor chooses `standard`, `verified`, or `designed` execution, and the owner reviews story-scoped attest evidence.
 
 **Existing project**
 
@@ -145,7 +169,7 @@ roll init --apply        # after reviewing the generated onboard plan
 roll loop on
 ```
 
-Roll diagnoses the repository without destructive migration, writes or updates Roll metadata only after review, and then lets the Supervisor reason over existing backlog, docs, context, open PRs, and scoped role bindings. Current state is visible through CLI-first observability: `roll status`, `roll loop watch`, `roll loop runs`, `roll cycle <id>`, `roll loop alert`, and story reports.
+Roll diagnoses the repository without destructive migration, writes or updates Roll metadata only after review, and then lets the Supervisor reason over existing backlog, docs, context, open PRs, and scoped role bindings. Current state is visible through CLI-first observability: `roll status`, `roll loop watch`, `roll loop runs`, `roll loop cycle <id>`, `roll loop alert`, and story reports.
 
 ## Quick start for new projects
 
@@ -170,57 +194,39 @@ with `roll loop resume` when ready.
 
 | Command | Description |
 |---------|-------------|
-| **Autonomy · daily use** | |
-| `roll loop <on\|off\|now\|status\|watch\|runs\|log\|story\|events\|eval\|signals\|alert\|fmt\|pr-inbox\|mute\|unmute\|pause\|resume\|reset\|gc>` | Manage the autonomous BACKLOG executor (incl. per-cycle result scoring) |
-| `roll loop watch [-n <lines>] [--events\|--raw-events] [--verbose\|--raw] [--attach]` | Read-only live observation. Use default first for owner-facing status (phase / quiet / TCR / last signal), `--events` for compact event debugging, and `--raw-events` only for audit/debug JSON. Ctrl-C ends the view, not the loop; `--attach` joins the tmux observe window read-only |
-| `roll loop go [--epic <e>\|--cards <ids>] [--budget <usd>] [--for <duration>] [--review <auto\|hetero\|self\|off>]` | Run goal mode manually until the scoped work completes, pauses, or hits a budget/usage/timebox guardrail; it can run while the scheduler is off, and a paused loop should be resumed first; final review defaults to `auto` |
-| `roll loop goal` | Show persisted goal scope, review mode, usage, limits, safety gate, and last decision |
-| `roll backlog [sync\|block\|defer\|lint\|…]` | View, manage, and sync (from GitHub Issues) pending tasks |
-| `roll loop alert [list\|ack\|resolve\|log]` | View / clear loop alerts |
-| `roll status` | Verdict-first truth summary read from the ONE snapshot — LOOP · CYCLE · RELEASE · STORY, with the STORY line's attest-coverage % (`done ≡ merged ∧ attested`) — then convention/AI-client sync health |
-| `roll supervisor [status\|observe\|advise\|next\|why\|live] [--json]` | Project-level Supervisor Agent: observes project truth, explains guided/autonomous mode and next owner action, advises next steps, and renders a read-only live role board with Planner / Builder / Evaluator panes. Cross-Story coordination only — never implements a Story; persistent policy changes need owner confirmation |
-| `roll pulse [--json]` | Today's delivery pulse: cycles in window, merged count, attested count, plus an ASCII sparkline from the story spectrum. Bilingual EN/中. `--json` for machine-readable output |
-| `roll doctor [skills\|--tools]` | Environment + install diagnosis; `roll doctor --tools` shows focused tool and screenshot readiness, including Terminal.app Screen Recording |
-| `roll tune [reset]` | Suggest-only self-tuning from loop trends — read-only, never auto-applies |
-| **Cards & evidence** | |
-| `roll idea "<one-sentence description>"` | Capture a card: auto-classify, number, lint, infer epic, mint the full story folder — the one user entry for adding cards |
-| `roll story new <ID> --title <t> [--epic <e>] [--no-index]` | The one minting entry agents/skills use: card folder + backlog row + index refresh (`--no-index` for batches) |
-| **Project · per repo** | |
-| `roll init` | Diagnose this directory and route to fresh scaffold, PRD/design handoff, existing-codebase onboard, repair, migration, or `roll status` |
-| `roll next` | Continue the init/onboard journey with one best next command: design, apply, repair, migrate, loop, or status |
-| `roll design [--from-file <path>] [--agent <name>]` | Launch `$roll-design` interactively; `--from-file` binds a PRD/brief as the design input |
-| `roll offboard` | Remove Roll from this project |
-| `roll test [--where] [--reset]` | Run the test suite (routes through the isolation adapter; unknown types fail loud) |
-| `roll ci [--wait]` | Show or wait for current commit's CI status |
-| `roll release [--dry-run]` | The ONE release flow: bump → changelog fold → package gate → commit-push → consistency gate → PR → auto-merge → tag push (gate runs before merge; drives the merge via GitHub auto-merge) |
-| `roll showcase [--card <ID>]` | The golden-path standard E2E in an isolated sandbox: reset the card, cast a heterogeneous real-agent trio (kimi/claude/pi), deliver via the loop, capture CLI+web screenshots, assemble the evidence chain, emit a pass/fail verdict |
-| `roll dream run-once` | Run the nightly Dream scan now; code-structure findings are seeded by a deterministic TS/AST pre-scan artifact before the agent writes the report |
-| `roll pair [init\|status\|score]` | Cross-agent pairing: heterogeneous peer re-checks and scores deliveries |
-| `roll cycles [--since 1d\|3d\|7d\|all]` | The cycle ledger — one line per cycle, failures never swallowed |
-| `roll cycle <id>` | One cycle's full trace tape (cycle→story→build→peer→ci→pr→end); the same trace is persisted as `.roll/loop/cycle-<id>.signals.jsonl` for replay |
-| `roll cycle <id> --roles [--json]` | The execution cast — who was Builder and who was Evaluator, which peers were consulted, and the single accepted score; also written to `summary.md`/`summary.json` and the Execution Cast report block ([guide](guide/en/loop.md#cycle-role-visibility)) |
-| `roll peer [--reviewer <agent>] (--prompt <text>\|--file <path>)` | One-shot structured external-provider review; records `.roll/peer/runs.jsonl` |
-| **Config & machine** | |
-| `roll ls [--json] [--stale-days <n>]` | List the cross-project registry (`~/.roll/projects.json`): name · tag · verdict · path; missing/stale rows flagged, never dropped |
-| `roll config [lang <zh\|en\|--reset>\|…]` | Read/write roll config (language, loop window, dream time) |
-| `roll agent [migrate --dry-run\|migrate\|list]` | Agent Scope view: Machine Scope, Project Scope, resolved roles, pool health, and legacy compatibility |
-| `roll cast [--json]` | Print the current role casting view (`--json` for the machine view) |
-| `roll doctor skills [--strict] [--json]` | Strict skills audit (skills · violations · hub lines + the four invocation groups — the SAME yardstick the web Skills page reads) |
-| `roll setup skills` | Sync the `guide/skills.md` skill catalog |
-| `roll doc [--lang en\|zh] [name]` | View the Charter / language guide markdown in the terminal (`--lang` falls back to the configured language) |
-| `roll tool status` | Show registered tools, effective `.roll/policy.yaml` state, input contracts, and requirement readiness |
-| `roll prices [refresh]` | Model price table (cost accounting source) |
-| `roll setup [skills\|-f]` | First-time install, skill catalog generation, or re-sync conventions to all AI clients |
-| `roll update` | Upgrade to latest + re-sync |
+| `roll agent [migrate\|list\|cast]` | Agent Scope, installed-agent inventory, and role casting |
+| `roll backlog [sync\|block\|defer\|lint\|…]` | View, manage, lint, and sync pending tasks |
+| `roll config [lang\|prices\|tune\|…]` | Read/write configuration, model prices, and suggest-only tuning |
+| `roll design [--from-file <path>] [--agent <name>]` | Launch `$roll-design` interactively; detailed designs get a self-contained Design Review Page |
+| `roll doctor [skills\|tools\|language]` | Diagnose install health, skills, tools, permissions, and language drift |
+| `roll help [--lang en\|zh] [name]` | View built-in Charter / guide docs; `roll --help` prints CLI usage |
+| `roll idea "<one-sentence description>"` | Capture and classify a new backlog card |
+| `roll init` | Diagnose this directory and route setup/onboarding |
+| `roll loop <on\|off\|go\|watch\|runs\|cycles\|cycle\|alert\|…>` | Run, observe, and maintain the autonomous executor |
+| `roll next` | Continue init/onboard with one best next command |
+| `roll release [--dry-run\|--showcase]` | Release planning/flow plus golden-path showcase support |
+| `roll setup [skills\|offboard\|-f]` | Install/sync conventions or remove Roll-owned project artifacts |
+| `roll status [ci\|pulse] [--json]` | Project health, CI state, and delivery pulse |
+| `roll test [--where] [--reset]` | Run tests through the isolation adapter |
+| `roll update` | Upgrade the global Roll install and re-sync conventions |
 | `roll --version` / `roll -v` | Print installed roll version |
 
+Retained support surfaces live under their owners: `roll config prices`, `roll config tune`,
+`roll agent cast`, `roll doctor tools`, `roll status ci`, `roll status pulse`,
+`roll loop cycles`, `roll loop cycle`, `roll release showcase`, and `roll setup offboard`.
+Historical top-level aliases for those capabilities now return the standard
+unknown-command response.
+
 ## Observability Now
 
 Roll's current observability is CLI-first. Persistent facts flow through one
 read path: anchors -> selectors -> adapter -> projections. `roll status`,
-`roll loop watch`, `roll loop runs`, `roll cycle <id>`, `roll pulse`, and
+`roll loop watch`, `roll loop runs`, `roll loop cycle <id>`, `roll status pulse`, and
 story-scoped attest reports are the current user-facing truth surfaces.
-`roll index` is an on-demand archive and repair renderer for static HTML pages;
+Role and collaboration visibility are part of that same surface: `roll loop cycle <id> --roles`,
+`roll loop cycle <id> --collab`, `roll loop cycle --legend`, `roll supervisor live --collab`,
+and the Execution Cast report block expose selected/returned/accepted role outcomes.
+The archive rebuild is an on-demand archive and repair renderer for static HTML pages;
 it is not the active delivery truth surface.
 
 - A backlog row is a claim; merge evidence on `main` and recorded acceptance
@@ -229,8 +235,11 @@ it is not the active delivery truth surface.
   free-form summary text.
 - Missing facts render as `?`. A visible `0` means a known zero, not unknown.
 
-`roll supervisor live` is the shipped CLI-first multi-role board. A browser/TUI
-Supervisor Live Console remains future work and must reuse the same view model.
+`roll supervisor live` is the shipped CLI-first multi-role board. It prints a
+one-frame snapshot for scripts and quick inspection; `roll supervisor live --watch`
+keeps the same board open and redraws it in-place from the same event-backed view
+model. A browser/TUI Supervisor Live Console remains future work and must reuse
+that view model.
 
 ## Repository layout
 

package/conventions/global/AGENTS.md

@@ -3,19 +3,20 @@
 > Baseline for AI-agent-friendly projects. Extend with project-specific rules.
 
 ## 1. Communication
-- User's language. Code/Git/Comments: English. UI: Chinese.
+- User conversation follows the user's language. Code/Git/Comments: English.
+- Rendered UI/CLI/docs use one resolved language per surface; keep multilingual
+  resources behind locale files or catalogs.
 - Concise. No summaries/code-walking. Implementation invisible.
 - Strategy (Why) OK; Tactics (How) NO. Outcomes only.
 - **Ambiguity resolution**: When user says "explicit" in automation contexts,
   interpret as "logged/observable with clear output", NOT "requiring manual
   intervention". Confirm with one question if uncertain.
 - **Voice**: Natural, colleague-like tone — neither robotic ("Executing…") nor over-enthusiastic ("Great!"). "Done — here's what changed." instead of "Task completed successfully." Consistent warmth for success and failure alike.
-- **Bilingual output**: EN + ZH on separate lines, never inline.
-  ```
-  Processing...
-  处理中...
-  ```
-  Not: `Processing... 处理中...`
+- **Language surfaces**: never append automatic translations. Agent contracts are
+  English; owner conversation follows the user; CLI output follows the resolved
+  locale; docs live in `guide/en` or `guide/zh`; backlog/spec/release notes use
+  the project primary language; code comments stay English except quoted
+  user-facing copy and fixtures.
 
 ## 2. Code
 - **TS**: Strict, no `any`. Functional hooks. Early returns.