@seanyao/roll 3.627.1 → 4.629.1

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 ## Unreleased
 
+## 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
+
+### 上手引导
+
+- **`roll init` 给出的 PRD 下一步现在能直接运行**：`roll design --from-file <path>` 会校验输入文件并把 PRD/brief 绑定到 `$roll-design`，不再落到 usage。(#1065) `[legacy-onboard]`
+
 ## v3.627.1 — 2026-06-27
 
 ### 上手引导

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
 
@@ -41,7 +41,8 @@ roll loop on        # let AI work through the backlog (optional)
 `Already initialized` and `Next: roll status`; partial Roll projects get
 `roll init --repair`, while pre-2.0 layouts get migration guidance without writing files. Existing codebases route to
 `$roll-onboard`. PRD/docs-only workspaces are treated as new projects: Roll writes
-`.roll/brief.md` from the detected document and points to `roll design --from-file`.
+`.roll/brief.md` from the detected document and points to
+`roll design --from-file <detected-doc>`.
 Empty directories ask what you are building in an interactive terminal; in scripts
 and CI, plain `roll init` is read-only and `roll init --auto` writes a placeholder
 brief before pointing to `roll design`.
@@ -54,6 +55,61 @@ 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 an execution profile: `standard` = Builder, `verified` = Builder -> Evaluator, `planned` = Planner -> Builder -> Evaluator.
+- **Planner / Builder / Evaluator roles** are stable contracts. The concrete `agent`, `model`, and `rig` can vary per Story through route profiles.
+- **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.
+- **Attest and evidence are story-scoped**. A Story is accepted through its own `latest/<id>-report.html`, AC map, and screenshots/test artifacts.
+
+Role routing can be declared per Story:
+
+```yaml
+story: US-V4-012
+execution_profile: verified
+roles:
+  builder:
+    agent: kimi
+    responsibility: update README, docs, guides, website, and samples
+  evaluator:
+    agent: pi
+    responsibility: evaluate new-user clarity and product narrative
+```
+
+Runtime availability is explicit: if `kimi` or `pi` is not callable on the current machine, the delivery records that limitation instead of hiding it behind a silent fallback.
+
+## 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 Planner turns the requirement into Stories, the Supervisor selects `standard`, `verified`, or `planned` per Story, Builder/Evaluator roles execute, 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 route profiles. 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:
@@ -85,9 +141,10 @@ 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 [observe\|advise\|next\|why] [--json]` | Project-level Supervisor Agent (v0 observe/advise): reads backlog, merge truth, open PRs, route config, repeated failures, and release readiness, then emits advisory decisions. 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 daemon <start\|stop\|status>` | Experimental read-only event broadcaster for future browser observability; 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 |
@@ -95,24 +152,23 @@ with `roll loop resume` when ready.
 | **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 [--agent <name>]` | Launch `$roll-design` interactively to turn requirements into a domain model + INVEST backlog |
+| `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 daemon <start\|stop\|status>` | Manage the experimental 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 cast [--json]` | Print the complexity-ladder -> role Casting table (`--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) |
@@ -122,12 +178,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.
@@ -135,6 +193,9 @@ Story, Cycle, and Release.
   free-form summary text.
 - Missing facts render as `?`. A visible `0` means a known zero, not unknown.
 
+The full Supervisor Live Console and multi-role board are next work, not
+something this README claims as shipped.
+
 ## Repository layout
 
 Dev side — a pnpm monorepo. Publish side — one npm package.