@seanyao/roll 3.628.1 → 4.629.2

package/CHANGELOG.md

@@ -2,6 +2,25 @@
 
 ## Unreleased
 
+## v4.629.2 — 2026-06-29
+
+### Agent 管理
+
+- **Agent 配置收敛成 Scope → Role → Binding → Agent → Model**：机器级和项目级 Agent 域现在只写 `~/.roll/agents.yaml` / `.roll/agents.yaml`，`roll agent` 展示 Machine Scope、Project Scope、继承来源、resolved role、Agent pool health 和 legacy compatibility；`roll agent migrate` 可以把旧的 primary/local/pairing/route 配置迁到新模型，迁移默认不删除旧文件。(US-V4-015, US-V4-016, US-V4-017, US-V4-019, US-V4-020, #1073) `[autonomous-evolution]`
+- **评审/打分回到公平候选池**：peer review 和 score 现在优先通过 evaluation Role binding 解析候选，历史上的 headless auth、VPN、账号状态不再变成静态排除；临时不可用只作为本次 runtime health skip 记录，异构评审和自评防线保持不变。(US-V4-018, #1073) `[autonomous-evolution]`
+
+### 自动化流水线
+
+- **Supervisor 成为 V4 操作入口**：`roll supervisor status/next/why/live` 会说明 guided/autonomous 模式、下一步 owner action、Planner/Builder/Evaluator 角色状态和不可用原因；旧 Dossier Web / daemon 产品面退场，story-scoped attest report 和 CLI-first observability 继续作为验收与观察入口。(US-V4-011, US-V4-013, US-V4-014, #1072, #1073) `[autonomous-evolution]`
+
+## v4.629.1 — 2026-06-29
+
+### 自动化流水线
+
+- **V4 Supervisor 执行架构上线**：Story 现在按 standard、verified、planned 剖面交付，Supervisor 负责项目级观察与建议，验收证据按 Story 收口，不再依赖全局档案刷新。(US-V4-001, US-V4-002, US-V4-003, US-V4-004, US-V4-005, US-V4-006, US-V4-007, US-V4-008, US-V4-009, US-V4-010, US-V4-012) `[autonomous-evolution]`
+  <!-- evidence: .roll/features/autonomous-evolution/US-V4-008/latest/US-V4-008-report.html -->
+  <!-- evidence: .roll/features/autonomous-evolution/US-V4-012/latest/US-V4-012-report.html -->
+
 ## v3.628.1 — 2026-06-28
 
 ### 上手引导

package/README.md

@@ -14,7 +14,7 @@
 [![npm version](https://img.shields.io/npm/v/@seanyao/roll.svg)](https://www.npmjs.com/package/@seanyao/roll)
 [![CI](https://github.com/seanyao/roll/actions/workflows/ci.yml/badge.svg)](https://github.com/seanyao/roll/actions/workflows/ci.yml)
 
-Roll — a CLI that lets AI agents pick up backlog items and ship them through your normal git + CI workflow. Works with Claude, Cursor, Codex, Kimi, and others.
+Roll — a Supervisor-led CLI harness that routes AI agents through story-scoped planning, building, evaluation, git, CI, and acceptance evidence. Works with Claude, Cursor, Codex, Kimi, Pi, Reasonix, and other local rigs when they are available.
 
 ## Install
 
@@ -55,6 +55,86 @@ 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).
 
+## 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`.
+- **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.
+
+### Operating modes
+
+Roll has two product modes over the same backlog, truth, route profile, execution
+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.
+- **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.
+
+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
+and bind Story roles:
+
+```yaml
+schema: roll-agents/v1
+scope: project
+inherits: machine
+defaults:
+  story:
+    roles:
+      execute:
+        kind: select
+        from: [kimi, codex, pi]
+        require: [execute]
+        strategy: first-available
+      evaluate:
+        kind: select
+        from: [claude, codex, kimi, pi, agy, reasonix]
+        require: [evaluate]
+        avoid: [execute]
+        strategy: least-recent
+```
+
+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.
+
+## Onboarding Samples
+
+**Zero-start project**
+
+```bash
+mkdir my-product && cd my-product
+roll init
+# In an interactive terminal, describe the requirement, point to a PRD,
+# or let Roll write .roll/brief.md from detected notes.
+roll next
+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.
+
+**Existing project**
+
+```bash
+cd existing-codebase
+roll init
+roll next
+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.
+
 ## Quick start for new projects
 
 A new project needs a remote before the loop can push branches and open PRs:
@@ -86,9 +166,9 @@ with `roll loop resume` when ready.
 | `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 daemon <start\|stop\|status>` | Opt-in read-only observability daemon for the live console; defaults to `127.0.0.1:7077`, records `.roll/loop/daemon.pid`, and is never auto-started by the loop |
 | `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 |
@@ -99,21 +179,19 @@ with `roll loop resume` when ready.
 | `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 daemon <start\|stop\|status>` | Manage the read-only observability daemon (OPT-IN only; never auto-started) |
 | `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) |
-| web `#loop` cycle rows | The same ledger expands to the shared ActivitySignal stream and writes `.roll/loop/cycle-<id>.signals.jsonl` for replay |
+| `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 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 [set <slot> <agent>\|use <name>\|list]` | Per-machine complexity-slot routing (easy/default/hard/fallback) |
-| `roll cast [--json]` | Print the complexity-ladder → role Casting table (same data the web console grid shows; `--json` for the machine view) |
+| `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) |
@@ -123,12 +201,14 @@ with `roll loop resume` when ready.
 | `roll update` | Upgrade to latest + re-sync |
 | `roll --version` / `roll -v` | Print installed roll version |
 
-## Truth Model In The UI
+## Observability Now
 
-The Delivery Dossier is a truth projection, not a backlog mirror. Persistent
-facts flow through one read path: anchors -> selectors -> adapter ->
-projections. `roll index` renders the front truth board from three aggregates:
-Story, Cycle, and Release.
+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
+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;
+it is not the active delivery truth surface.
 
 - A backlog row is a claim; merge evidence on `main` and recorded acceptance
   evidence are truth. A premature `✅ Done` claim is shown as drift.
@@ -136,6 +216,9 @@ Story, Cycle, and Release.
   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.
+
 ## Repository layout
 
 Dev side — a pnpm monorepo. Publish side — one npm package.