@seanyao/roll 4.630.2 → 4.702.2

package/guide/en/acceptance-evidence.md

@@ -0,0 +1,231 @@
+# Acceptance Review Page — `roll attest`
+
+Every delivered story can carry a **single-file Acceptance Review Page**: per-AC
+verdicts with the artifacts that back them, openable offline, printable to PDF,
+readable by non-engineers.
+
+## Where Review Pages live
+
+Every story has ONE home — its card folder under the epic:
+
+```
+.roll/features/<epic>/<id>/<run-id>/<id>-review.html  ← Acceptance Review Page (self-contained)
+.roll/features/<epic>/<id>/<run-id>/<id>-report.html  ← legacy report alias (one release cycle)
+.roll/features/<epic>/<id>/<run-id>/evidence.json     ← collected hard facts
+.roll/features/<epic>/<id>/<run-id>/evidence/         ← raw command/test artifacts
+.roll/features/<epic>/<id>/<run-id>/screenshots/      ← visual proof, when relevant
+.roll/features/<epic>/<id>/ac-map.json                ← AC → evidence intent map
+.roll/features/<epic>/<id>/latest                     ← symlink to the newest run
+```
+
+Runs are timestamped and never overwritten. The backlog `✅ Done` row links to
+`latest/<id>-review.html`; CHANGELOG bullets may carry an invisible
+`<!-- evidence: ... -->` marker for traceability.
+
+**The story's `latest/<id>-review.html` is the human acceptance entry.** A
+story is accepted by opening its own Acceptance Review Page — not a global archive/index page.
+`roll attest` is story-scoped: it writes only this story's Review Page, the legacy report alias, and the
+`latest` pointer. It does not refresh any global archive, epic, or front-page
+HTML. Those board pages, when you want them, are rendered on demand with
+the archive rebuild; they are a convenience/archive view, not the delivery-truth surface.
+
+## Lifecycle in three stages
+
+1. Open the evidence frame. At the beginning of a loop cycle the runner creates
+   the timestamped run directory and exports it to the inner agent as
+   `ROLL_RUN_DIR`. The derived directories `ROLL_EVIDENCE_DIR` and
+   `ROLL_SCREENSHOTS_DIR` point at `<run-id>/evidence/` and
+   `<run-id>/screenshots/`.
+2. Collect during execution. `roll test` writes command output and summaries
+   into `ROLL_EVIDENCE_DIR`; visual lanes write screenshots into
+   `ROLL_SCREENSHOTS_DIR` when the surface requires inspection. The agent keeps
+   `ac-map.json` in the story card root, mapping each AC to the evidence files
+   that support it, with a status per AC: `pass` · `readonly` · `partial` ·
+   `claimed` · `missing`.
+3. Close with the hard attest gate. The runner calls
+   `roll attest <story-id> --run-dir "$ROLL_RUN_DIR"` at the end of delivery.
+   `roll attest` sweeps the hard facts (TCR commits, latest CI run, optional
+   deploy probe, test-pass proof), renders the Acceptance Review Page, and moves `latest` to the
+   run. That is all it writes — it is story-scoped. It does not mount a story
+   archive delivery section, regenerate `.roll/index.json`, or refresh any global
+   archive/epic/front page (run the archive rebuild on demand for those board pages).
+
+`roll attest` also runs standalone — without an intent map every AC renders as
+🟧 Claimed, honestly.
+
+## Gate policy
+
+The attest gate is **hard by default**. A delivered story with ACs but no fresh,
+contentful report is blocked rather than marked `✅ Done`. During an explicit
+migration window a project may set `.roll/policy.yaml` to soft mode:
+
+```yaml
+loop_safety:
+  attest_gate: soft
+```
+
+Soft mode records the gap and raises the same audit signal, but it does not
+block the delivery cycle. Treat it as temporary compatibility, not the default.
+
+## The red line
+
+An AC with **zero evidence** can never claim `pass`: the renderer forces it
+down to 🟧 Claimed and lists it under **Discrepancies**. Verbal completion
+("I confirmed it works") is exactly what this rules out.
+
+## Declaring visual evidence at design time
+
+`roll story validate` checks, at design time, that a spec is *born* with a
+visual-evidence AC (and, for a web surface, a declared product page to capture).
+Two rules decide what the validator recognises:
+
+- **The `[visual-evidence]` marker is authoritative.** An AC item that opens with
+  a literal `[visual-evidence]` marker *is* a visual-evidence AC — on its own, no
+  matter what words follow. You do not need to also write "screenshot" / "截图":
+  the marker is your explicit declaration. (Without the marker, the validator
+  still recognises unambiguous nouns like `screenshot` / `截图` / `录屏`.)
+
+  ```markdown
+  - [ ] [visual-evidence] headless capture of the Now landing and each tab
+  ```
+
+- **The declared surface wins over AC text.** Once a spec has a visual-evidence
+  AC, its surface is read from the frontmatter first:
+  - a declared `deliverable_url:` (alias `screenshot_url:`) ⇒ **web** — the card
+    has committed to a real product page, so it owes a web screenshot;
+  - a declared `physical_terminal:` ⇒ **terminal** with a stricter contract — the
+    report must contain a real macOS `Terminal.app` screenshot captured from
+    screen pixels. Headless stdout, transcript-rendered images, and HTML replays
+    are rejected for this contract;
+  - else a declared `deliverable_cmd:` ⇒ **terminal** — a CLI deliverable that
+    rides the terminal-capture lane;
+  - else the AC text decides (web / terminal / ambiguous).
+
+  So a card that declares `deliverable_url: .roll/features/agents.html` is judged
+  a **web** surface even when its AC prose mentions a `roll` command.
+
+## Evidence Modes
+
+Stories may declare `evidence_mode:` in frontmatter, or an Evaluation contract
+may declare `- evidence_mode: ...`. Roll also derives a mode for Evaluator
+prompts, but only an explicit non-visual mode changes the screenshot gate.
+That explicit mode is not a blank override: a declared URL, terminal command,
+physical terminal, or visual-evidence AC still escalates to the relevant capture
+gate.
+
+| Mode | Required proof | Screenshot policy |
+|------|----------------|-------------------|
+| `visual_ui` | rendered visual capture, functional/smoke check, CI | required |
+| `cli_output` | stdout/stderr snapshot, exit code, command fixture or focused test, CI | conditional; required for terminal/TUI visual changes |
+| `refactor_contract` | focused tests, typecheck/build, grep/no-old-symbol checks, CI | not required unless visual risk is present |
+| `data_state` | fixture replay, event assertions, idempotency/concurrency coverage, CI | not required unless visual risk is present |
+| `docs_content` | rendered text checks, link checks, diff review, CI | conditional; required for layout changes |
+
+`screenshot_exempt:` should name or imply the alternate matrix, preferably by
+pairing it with `evidence_mode: refactor_contract`, `data_state`, or
+`docs_content`. QA/Evaluator may escalate any non-visual mode back to a screenshot
+gate when a visual surface changed, an AC explicitly asks for visual evidence, or
+prior evidence exposes rendering/layout risk; the escalation reason must be
+recorded.
+
+## External tool readiness
+
+Visual evidence uses machine-level tools that are declared explicitly and probed
+at startup:
+
+- `macOS screencapture` — physical Terminal.app / browser-window screenshot
+  capture. It is built into macOS, but Terminal.app, the stable roll capture
+  host, must have Screen Recording permission. Missing permission means attest
+  records an honest screenshot skip; headless, transcript-rendered, and HTML
+  reproduction images do not count as screenshot evidence. A successful
+  interactive `Terminal.app` permission probe is cached under `ROLL_HOME` so
+  repeated `roll doctor` / setup checks do not keep re-triggering the macOS
+  prompt; if permission was just granted, restart Terminal.app before trusting
+  the cache.
+- `Playwright Chromium` — optional headless web capture for `roll attest` and
+  archive screenshots. Install with `npx playwright install chromium`.
+
+`roll doctor` always prints the current availability, permission state, impact,
+and repair command for these tools. Use `roll doctor --tools` when you only want
+the focused tool and Terminal.app Screen Recording readiness view. `roll init`
+and `roll loop go` run the same probe at startup; in an interactive terminal they ask whether to install/open
+the missing setup steps, and in automation they stay silent unless
+`ROLL_EXTERNAL_TOOLS=yes` or `ROLL_EXTERNAL_TOOLS=no` is set. Choosing `no`
+prints the evidence impact and continues without changing the machine.
+
+The machine Agents page (`.roll/features/agents.html`) includes the same tool
+status block so a reviewer can see whether evidence capture depends on
+machine setup rather than story code.
+
+## Review Score fold
+
+When `.roll/notes/` carries the story's Review Score entry, the report ends
+with a collapsed *Review Score · 评审分* section. No entry → no section. The
+Review Score is produced by a fresh-session peer Reviewer, never by the
+building agent.
+
+## Where cards come from — `roll idea`
+
+Add a card with one natural-language sentence:
+
+```bash
+roll idea "Refund flow is broken for partial payments"
+```
+
+`roll idea` auto-classifies it (bug → FIX / feature → IDEA), assigns the
+next id in that family, lint-checks the description, infers the right epic
+folder, and mints the full card folder (spec.md + story page + index
+refresh). All in one command.
+
+For explicit control over id and epic, the internal `roll story new` is
+available:
+
+```bash
+roll story new US-PAY-001 --title "Refund flow" --epic payments
+# the ONE minting entry: card folder + backlog row + index refresh in one step.
+# Batch minting: add --no-index per card, finish with a single the archive rebuild.
+```
+
+Both channels write the frontmatter'd `spec.md`, the story page skeleton,
+and refresh `.roll/index.json`. They refuse to overwrite an existing card —
+cards are born once, then evolved by hand. Skills never hand-create card
+files; the `cards` consistency dimension fails the release gate on any
+live backlog row without a card.
+
+## Static Archive — the archive rebuild
+
+the archive rebuild is an on-demand repair/archive renderer. It regenerates browsable,
+three-layer static HTML pages (every page is self-contained, localized with one
+visible language at a time, theme-aware, printable):
+
+```
+.roll/features/index.html              ← archive front page (Story / Cycle /
+                                         Release), truth strip, searchable epic cards
+.roll/features/<epic>/index.html       ← epic page: epic ledger + stories in three
+                                         groups (merged / in a cycle / in backlog)
+.roll/features/<epic>/<id>/index.html  ← story archive: five stations — Definition,
+                                         Design, Execution, Delivery (attest banner
+                                         + per-AC evidence blocks), Retrospective
+```
+
+Every figure is computed from the truth model — anchors -> selectors -> adapter
+-> projections — never typed in. Story facts compare backlog claims with merge
+and evidence truth; Cycle facts use TerminalOutcome records; Release facts use
+the latest gate verdict and active waiver. The guiding line: **backlog is wish,
+main is truth, done ≡ merged.**
+
+The archive front page keeps unknown visible. `?` means the fact is absent
+or outside the known schema; `0` means a known zero. A premature backlog
+`✅ Done` row is treated as a claim that conflicts with truth and is rendered as
+drift, not as delivered work.
+
+On story archive pages, screenshot evidence remains a thumbnail linked to the
+full image. Text evidence such as Vitest output is read from the referenced
+evidence file and shown inline under the AC in a folded, scrollable block; if
+the file is missing or unreadable, the page shows an explicit unavailable state.
+
+The current delivery truth remains story-scoped attest plus CLI-first
+observability (`roll status`, `roll loop watch`, `roll loop runs`,
+`roll loop cycle <id>`). Use the archive rebuild by hand for reconciliation, archive
+export, CI artifacts, or migration repair; rebuild mode re-renders every story
+page from source after hand-merges or history migrations.

package/guide/en/ai-agents.md

@@ -0,0 +1,185 @@
+# Roll — AI Agent Support
+
+Roll treats AI agents as a scoped pool of execution identities. The current
+model is:
+
+```text
+Scope -> Role -> Binding -> Agent -> optional Model
+```
+
+The same shape repeats at every level. A machine can declare the agents it has,
+a project can bind roles for its work, and a story or skill can narrow those
+bindings when needed.
+
+## Agent-Domain Files
+
+- `~/.roll/agents.yaml` is Machine Scope. It declares the local agent pool and
+  machine-level roles such as `supervise`.
+- `.roll/agents.yaml` is Project Scope. It binds project/story roles such as
+  `supervise`, `execute`, and `evaluate`.
+
+`~/.roll/config.yaml` may still exist for generic preferences and legacy
+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 migrate --dry-run    # preview conversion from legacy files
+roll agent migrate              # write roll-agents/v1 files
+roll agent list                 # show installed agents
+```
+
+## Roles
+
+Roll uses three core Agent-domain roles:
+
+- `supervise` — coordinates at project level. In guided mode this may be the
+  current agent session you are talking to; in autonomous mode Roll resolves the
+  role and drives the loop.
+- `execute` — builds or fixes a story through the selected skill workflow.
+- `evaluate` — reviews, scores, or checks the delivery in a fresh session.
+
+**Who played each role in a finished cycle?** After a cycle runs, the resolved
+roles are not a mystery you have to reconstruct from logs. Run
+`roll loop cycle <id> --roles` to see exactly who was Builder and who was Evaluator,
+which peers were consulted, and which single score the gate accepted. The same
+cast is written to `summary.md` / `summary.json` and embedded in the story's
+Execution Cast report block. See
+[Cycle Role Visibility](./loop.md#cycle-role-visibility) for the full surface.
+
+Project defaults normally 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, cursor]
+        require: [evaluate]
+        strategy: health-aware
+```
+
+Machine scope can declare a supervisor and the local pool:
+
+```yaml
+schema: roll-agents/v1
+scope: machine
+agents:
+  codex:
+    capabilities: [supervise, execute, evaluate]
+  kimi:
+    capabilities: [execute, evaluate]
+roles:
+  supervise:
+    use: codex
+```
+
+## Fair Eligibility
+
+Static config lists fair candidates. It should not permanently exclude a
+supported agent because of an old auth, VPN, account, or network incident.
+Runtime health is checked when Roll resolves or spawns the role:
+
+- unavailable candidates are skipped for the current resolution;
+- the skip is recorded as a runtime fact;
+- the static pool remains fair until you intentionally narrow it.
+
+Unknown or unregistered agent names fail loud during config parsing.
+
+`health-aware` is the selection strategy for open role casting. It keeps the
+same installed pool visible for Designer, Builder, Evaluator, and Peer Reviewer
+unless an owner policy narrows the pool, then ranks candidates with recent
+health signals, role capability tags, successful deliveries, recent use, and
+cost band. A degraded candidate stays visible with warnings, but a healthy
+candidate with the right capability wins. A cheap weaker agent can remain
+eligible for focused work while ranking lower for broad or high-risk Builder
+work.
+
+Use the route trace when you need to see the cast instead of guessing:
+
+```bash
+roll supervisor route --role builder --story US-123
+roll supervisor route --role evaluator --story US-123 --json
+```
+
+The trace lists every candidate, eligibility, score reasons, warnings, skipped
+runtime facts, selected agent, strategy, and source binding.
+
+## Guided vs Autonomous Mode
+
+In guided mode, you can keep working in the current agent window. That session
+acts as the supervisor front door: it can inspect `roll agent`, run migrations,
+and ask Roll to continue through the CLI.
+
+In autonomous mode, you do not open multiple agent windows manually. The loop
+resolves `supervise`, `story.execute`, and `story.evaluate`, then spawns fresh
+agent sessions for the roles through the configured bindings.
+
+## Supported Agents
+
+| Agent | CLI command | Notes |
+|-------|-------------|-------|
+| Claude Code | `claude` | Anthropic coding agent. |
+| Kimi CLI | `kimi-code` (legacy: `kimi-cli` / `kimi`) | Moonshot coding agent. |
+| Codex CLI | `codex` | OpenAI coding agent; `openai` aliases to `codex`. |
+| Antigravity | `agy` | Google Antigravity agent; legacy `gemini` aliases to `agy`. |
+| Pi | `pi` | The `deepseek` alias resolves to `pi`. |
+| Reasonix | `reasonix` | DeepSeek-native coding agent; requires `DEEPSEEK_API_KEY`. |
+| Cursor | `cursor-agent` | Cursor headless agent; day-one usage is recorded as `?` until parseable token/cost output is available. |
+
+Agent-specific behavior belongs in one profile, not in downstream runner gates:
+
+1. Add the public registry entry in `packages/core/src/agent/specs.ts`.
+2. Add or update the runner profile in `packages/cli/src/runner/agent-spawn.ts`.
+3. Keep executor, attest, pairing, and scoring code agent-agnostic.
+4. Add unit coverage for the profile and registry entry.
+
+## Agent Toolchain Health (US-V4-022)
+
+Supervisor treats agent toolchain health as part of coordination, not as an
+owner-side mystery. It scans warnings, auth/network status, polluted skill
+roots, stale setup sync, and worktree permission failures, then classifies them
+into one of four operational categories:
+
+- **auth_block** — "403", "please run /login", "Unauthorized" → `pause_for_owner`
+- **network_block** — `ECONNREFUSED`, `ETIMEDOUT`, DNS failure → `continue`
+  (transient; loop retries or breathes)
+- **setup_skill_root_pollution** — Reasonix auxiliary-dir warnings, skills with no
+  description → `create_fix` → routed to the delta team as a FIX
+- **worktree_permission_failure** — `EACCES` / "permission denied" on a worktree
+  path → `pause_for_owner`
+
+When the signal is setup/skill-root pollution, Supervisor must **not** label it
+as auth-blocked. It routes the repair to the backlog/delta team as a FIX,
+instead of asking the owner to debug ad hoc. Supervisor coordinates and
+diagnoses these issues but does not become the Builder or Evaluator, and it does
+not auto-delete global files.
+
+```bash
+roll supervisor health             # human-readable health board
+roll supervisor health --json      # machine-readable classifications
+roll supervisor next               # next card + agent health summary
+```
+
+## Legacy Compatibility
+
+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.
+
+## See Also
+
+- [configuration.md](configuration.md) — config and policy files
+- [pairing.md](pairing.md) — evaluate-role review and scoring
+- [loop.md](loop.md) — autonomous role resolution

package/guide/en/backlog-github-sync.md

@@ -0,0 +1,108 @@
+# roll backlog sync — pull GitHub Issues into your backlog
+
+`roll backlog sync` pulls issues from a GitHub repository and writes them
+into your local `.roll/backlog.md`. It is single-direction
+(issues → backlog) in v1: nothing is written back to GitHub.
+
+`roll backlog sync` 把 GitHub Issues 拉进本地 `.roll/backlog.md`。
+
+## Authentication
+
+The sync resolves a GitHub token in this order:
+
+1. `$GITHUB_TOKEN` — set it in your environment or CI secrets.
+2. `gh auth token` — falls back to the GitHub CLI if you have run
+   `gh auth login`.
+
+If neither is available the command stops and tells you how to set one.
+
+```bash
+export GITHUB_TOKEN=ghp_xxx
+# or, if you use the GitHub CLI:
+gh auth login
+```
+
+## Quick start
+
+```bash
+# First sync must name the repo explicitly:
+roll backlog sync --repo seanyao/roll-meta
+
+# Preview without writing anything:
+roll backlog sync --repo seanyao/roll-meta --dry-run
+
+# Only pull issues carrying specific labels (OR semantics):
+roll backlog sync --repo seanyao/roll-meta --label P1,bug
+
+# After the first run the repo is remembered, so you can omit --repo:
+roll backlog sync
+```
+
+## Flags
+
+| Flag         | Notes |
+|--------------|-------|
+| `--repo`     | `owner/repo`. Required on the first sync; afterwards read from config. |
+| `--dry-run`  | Compute the diff and print it, but leave `.roll/backlog.md` unchanged. |
+| `--label`    | Comma-separated label filter. May repeat. Matches any (OR). |
+
+## label → type mapping
+
+The issue's labels decide the backlog type prefix. The first matching
+label wins; with no match the default is `US`.
+
+| GitHub label                | Backlog type |
+|-----------------------------|--------------|
+| `bug`                       | `FIX`        |
+| `enhancement` / `feature` / `US` | `US`    |
+| `refactor`                  | `REFACTOR`   |
+| (no matching label)         | `US`         |
+
+Issue state maps to the status column: `open` → `📋 Todo`,
+`closed` → `✅ Done`. The issue title becomes the row description.
+
+## IDs and idempotency
+
+Each issue gets a stable backlog id `GH-<number>` (e.g. issue #13 →
+`GH-13`), combined with the type prefix (`US-GH-13`, `FIX-GH-13`).
+
+Sync is idempotent: a second run skips any issue whose id already exists
+in `.roll/backlog.md` — it never overwrites the status or description of
+an existing row, and prints `skipped (already exists): GH-13`. Each run
+ends with a summary:
+
+```
+added: 2, skipped: 5, total issues: 7
+```
+
+`--dry-run` prints the same diff with `+` (would add) and `=` (would
+skip) markers and never touches the file.
+
+## Configuration: `.roll/local.yaml`
+
+After a successful real sync the resolved repo, labels and timestamp are
+persisted so later runs can omit `--repo`:
+
+```yaml
+backlog_sync:
+  repo: seanyao/roll-meta
+  direction: issues-to-backlog
+  labels: []
+  last_sync_at: 2026-05-28T10:00:00Z
+```
+
+| Field           | Meaning |
+|-----------------|---------|
+| `repo`          | Default `owner/repo` for flagless syncs. |
+| `direction`     | Always `issues-to-backlog` in v1. |
+| `labels`        | Default label filter; an explicit `--label` flag overrides it. |
+| `last_sync_at`  | Timestamp of the last successful sync. |
+
+An explicit flag always overrides the persisted config. If
+`.roll/local.yaml` has no `backlog_sync:` block, the first sync must pass
+`--repo`.
+
+## Not in v1
+
+Two-way write-back, Projects/Milestones mapping, PR linking, non-GitHub
+platforms, and custom mapping rules are out of scope for v1.

package/guide/en/changelog.md

@@ -0,0 +1,66 @@
+# Roll — Changelog
+
+Roll keeps `CHANGELOG.md` in sync automatically. You never have to write or
+update it manually.
+
+## How It Works
+
+1. `$roll-build` (or `$roll-fix`) delivers a story and stages `CHANGELOG.md`.
+2. The story completion commit includes `CHANGELOG.md` — no separate commit.
+3. On release, Roll's release process renames `## Unreleased` to the version tag.
+
+## What Gets Written
+
+The `$roll-.changelog` skill reads `BACKLOG.md` and writes a bullet for each
+completed story or fix. It filters for user-visible changes only:
+
+**Written:**
+- New commands users can invoke
+- Bug fixes users would notice
+- Visible behavior changes (layout, output, speed)
+- Install / upgrade changes
+
+**Skipped:**
+- Internal refactors
+- Test infrastructure changes
+- Developer-only bug fixes
+- Implementation details
+
+The skill enforces a style gate — bullets are short, plain-language,
+user-facing. Technical jargon triggers a rewrite loop.
+
+## Release-ready sections
+
+`roll release` treats the changelog as ready in either shape: an
+`## Unreleased` section with bullets, **or** a pre-written next-version
+section at the top (`## v3.608.1 — 2026-06-08`) naming a version newer than
+package.json's current — the release flow's own convention. A first section
+matching the current version means everything is already shipped.
+
+```markdown
+## Unreleased
+- **Added**: `roll loop runs` — instantly see what loop ran and when
+- **Fixed**: `roll update` no longer reports the wrong version after upgrading
+
+## v2026.05.07
+- ...
+```
+
+## First-Time Backfill
+
+If your project has no `CHANGELOG.md` yet, `$roll-.changelog` creates one
+and backfills all historical completed stories, grouped by date.
+
+## Manual Trigger
+
+```bash
+$roll-.changelog   # stage CHANGELOG.md (call from within a build session)
+```
+
+When called outside a build session (standalone), it stages and commits
+with `chore: sync changelog`.
+
+## See Also
+
+- [loop.md](loop.md) — loop triggers changelog automatically after each story
+- [skills.md](skills.md) — `roll-.changelog` in the support skills table