@seanyao/roll 4.630.2 → 4.702.2

package/guide/en/testing/quality-rubric.md

@@ -0,0 +1,340 @@
+# Test Quality Rubric
+
+> Scope: Vitest tests in `packages/*/test/`, used by `roll-.dream` Scan 7 to
+> surface anti-patterns as structured REFACTOR entries.
+> Chinese version: [quality-rubric.zh.md](./quality-rubric.zh.md)
+
+This rubric publishes eight anti-patterns that make tests give wrong signal —
+either false-positive (red on unrelated change) or false-negative (green
+while production is broken). Each category has the same four parts:
+
+- **Definition** — what the anti-pattern is
+- **Signals** — how to spot it from the test file alone
+- **Fix template** — minimal repair pattern (not a full rewrite)
+- **Real example** — an actual occurrence inside this repo
+
+Categories are numbered ❶ through ❽. Categories ❶–❻ are advisory (dream
+flags them; the maintainer triages). Categories ❼ and ❽ are **blocking**:
+the loop cycle's test-quality merge gate (US-QA-012) rejects a PR that
+introduces a new ❼ or ❽ violation, even if CI is green.
+
+---
+
+## ❶ Hardcoded business data in assertions
+
+### Definition
+
+The test asserts a literal business value (price, version string, product
+copy, model name) instead of importing the value from the module under
+test or from a versioned fixture. When the business value changes, every
+unrelated test that hardcoded the old value turns red even though the
+logic under test still works.
+
+### Signals
+
+- Bare numeric or string literals inside `[[ "$output" == *"..."*` /
+  `[ "$output" = "..." ]` that match values living in the source module.
+- The same literal appears in ≥2 test files (price tables, version
+  numbers, model identifiers).
+- The test file is not the canonical owner of the value (e.g. a runner
+  test asserts a price, but pricing lives in `packages/core/src/cost/prices.ts`).
+
+### Fix template
+
+```ts
+// BEFORE
+it("opus rate is 5/25", () => {
+  expect(computeListCost("claude-opus-4-7", usage)).toBe("5.0 25.0");
+});
+
+// AFTER — feed a fixed fixture rate table; assert the FORMULA, not the live rates
+it("computeListCost multiplies tokens × the injected rate", () => {
+  const rates = { "m": { in: 2, out: 4 } };
+  expect(computeListCost("m", { input_tokens: 1000, output_tokens: 500 }, rates)).toBe(/* 0.002 + 0.002 */ 0.004);
+});
+```
+
+Or assert only structural invariants on the production rates (e.g.
+`cache_read < input`, `out ≥ in`) so a rate-card move can't redden the suite.
+
+### Real example
+
+`packages/core/test/prices.difftest.test.ts` used to read the live opus/sonnet/haiku
+rates directly in the assertions — every rate-card move turned it red without
+revealing any regression in the rate-resolution logic. It now feeds a fixed
+fixture table for the arithmetic and asserts only structural invariants on the
+production rates.
+
+---
+
+## ❷ Over-mocking
+
+### Definition
+
+The test mocks a boundary it should be hitting for real — database,
+filesystem, child-process spawn, git command — so the test passes against
+a mock that doesn't behave like the real thing. The test ships green; the
+first integration run breaks.
+
+### Signals
+
+- `function git() { … }` / `function gh() { … }` overrides at the top of
+  a unit test that exercises real git or gh behavior.
+- A SQL or filesystem call replaced with an inline stub returning a
+  hand-rolled string.
+- Mocks live in the test file itself rather than in a shared test helper
+  module, signaling they were added ad-hoc rather than shared.
+
+### Fix template
+
+```ts
+// Use a real ephemeral substrate (tmp git repo, tmpdir). Clean it up in
+// afterEach/afterAll. The mock disappears entirely.
+let dir: string;
+beforeEach(() => { dir = realpathSync(mkdtempSync(join(tmpdir(), "t-"))); execSync("git init -q", { cwd: dir }); });
+afterEach(() => { rmSync(dir, { recursive: true, force: true }); });
+```
+
+If a true boundary cannot be exercised cheaply (network, gh, launchctl),
+inject it as a port/dependency and pass a fake in the test — the same pattern
+`runner-executor.test.ts` uses with `fakePorts()`.
+
+### Real example
+
+Watch for ad-hoc `const gh = () => ({...})` overrides scattered across tests
+that exercise loop-PR routing. The fix is an injected `GithubPort` (as in
+`packages/cli/test/runner-executor.test.ts`) so the same fake is shared,
+deliberate, and discoverable.
+
+---
+
+## ❸ Asserting on implementation details
+
+### Definition
+
+The test asserts on the *shape* of internal state (private function
+names, intermediate variable contents, file path of an internal cache)
+rather than the observable behavior. A refactor that preserves behavior
+breaks the test, blocking the refactor for no good reason.
+
+### Signals
+
+- `grep -q '_internal_helper' "$output"` — asserting a private symbol
+  name is leaked to output.
+- `[[ "$(cat .roll/internal/_cache.tmp)" == ... ]]` — asserting on an
+  internal cache file path that the public API never promised.
+- The assertion would still pass after a meaningful behavioral
+  regression because it checks the wrong layer.
+
+### Fix template
+
+Re-anchor the assertion to the **public effect**: exit code, observable
+output, state visible to a caller. If the internal detail is the only
+thing visible, the production code probably needs a thin public API to
+expose the behavior intentionally.
+
+### Real example
+
+Tests asserting `grep -q 'some_internal_helper' <output>` would break
+the moment the helper is renamed, even though the gating logic is
+unchanged. The right assertion is "story X is skipped because dep Y
+is unsatisfied," verified through the public side effect (story stays
+📋 Todo, log line emitted).
+
+---
+
+## ❹ Fixture order coupling
+
+### Definition
+
+Tests share mutable state (a file, an env var, a temp dir) and rely on
+running in a specific order. Parallel runs, `--filter`, or reshuffling
+cause sporadic failures that look like flakes.
+
+### Signals
+
+- A test reads state another test in the same file wrote.
+- A module-level (or `beforeAll`) fixture mutates shared state that nothing
+  resets, and a later test depends on it.
+- The test passes alone but fails inside the suite (or vice versa).
+
+### Fix template
+
+Create per-test state in `beforeEach` (its own tmpdir / env / fixture), assert,
+and clean up in `afterEach`. Cross-test dependencies become explicit only when
+truly necessary, and even then they go through a named helper, not implicit
+ordering or a shared mutable.
+
+### Real example
+
+Any test file where a `beforeAll` mutates `$HOME` or writes a shared
+state-`<slug>.yaml` and a later test in the same file reads it without
+re-initializing is a candidate. The fix is per-test isolation through a
+fresh `mkdtempSync` + an injected home/root.
+
+---
+
+## ❺ Testing private functions / bypassing the public API
+
+### Definition
+
+The test reaches inside a module to call a private helper directly,
+asserting its return value. The helper can be renamed, inlined, or
+removed without changing behavior — but the test claims regression.
+
+### Signals
+
+- A test deep-imports an unexported helper from a module's internals and
+  calls it by name.
+- The function name starts with `_` (project convention for private),
+  yet a test depends on its signature.
+- The public API isn't exercised at all in the file; the test is
+  effectively testing the internal decomposition.
+
+### Fix template
+
+Route the call through the public entry point (`roll <cmd>` /
+`my-tool foo`). If the public API doesn't cover the case being tested,
+that's a feature gap — either the case is unreachable (delete the
+test) or the public API needs a new flag (add it intentionally).
+
+### Real example
+
+A test that reaches into a private helper (importing an unexported
+`_loopCheckDependsOn` via a back door) instead of running the command and
+observing the skip decision in the run log. The first form locks the helper
+name; the second tests the behavior the user cares about.
+
+---
+
+## ❻ Asserting on framework behavior
+
+### Definition
+
+The test exercises Vitest itself (or any framework) rather than the
+project code: asserting that `beforeEach` runs before tests, that a mock
+records calls, that `expect` exists. These assertions pass because the
+framework works; they tell us nothing about the project.
+
+### Signals
+
+- Assertions on framework internals / the test runner's own behavior.
+- A test whose body is only setup/teardown verification with no call to
+  project code.
+- Tests added after a framework upgrade to "make sure Vitest still works."
+
+### Fix template
+
+Delete the test. Framework verification belongs upstream. If the project
+relies on a specific framework guarantee, document that contract in a shared
+test helper and run one smoke test, not a category of them.
+
+### Real example
+
+A test that asserts the test runner's own bookkeeping (e.g. that a mock was
+constructed, or that `beforeEach` ran) adds noise to every CI run without ever
+surfacing a project regression. Trust the framework; delete the test.
+
+---
+
+## ❼ Test inlines external tool behaviour
+
+### Definition
+
+The test body re-implements the behaviour of external tools (`sed`, `grep`,
+`find`, `awk`, `tr`) via inline shell pipelines, instead of calling a
+project function that encapsulates that logic. When the project replaces
+the external tool or changes the internal parsing, every test that copied
+the pipeline breaks — even though the public-API output didn't change.
+
+### Signals
+
+- `foo=$(echo "$output" | grep ... | sed ... | awk ...)` chains inside
+the test body.
+- The same pipeline appears in ≥2 test files (duplicated parsing logic).
+- A project function exists (or should exist) that encapsulates this
+parsing, but the test bypasses it and rolls its own inline version.
+
+### Fix template
+
+```ts
+// BEFORE — inline regex replicates what a project function already does
+const label = /<key>Label<\/key>\s*<string>([^<]*)<\/string>/.exec(plist)?.[1];
+
+// AFTER — call the project function that owns the parsing
+import { plistString } from "../src/lib/plist.js";
+const label = plistString(plist, "Label");
+```
+
+If no project function exists, extract the parsing into a named test helper
+module so the logic is shared and deliberate.
+
+### Real example
+
+An integration test that hand-rolls a regex chain to parse a plist XML file
+for a `<string>` value, instead of importing the project's own plist parser.
+Any schema change then forces the test author to fix the inline pattern in
+multiple test files — the parser is the single owner that should change.
+
+---
+
+## ❽ Test asserts on a file outside this repo
+
+### Definition
+
+The test assertion reads or asserts on a file path outside the repository
+root (e.g. `~/.roll/`, `~/.codex/`, `/etc/`, `/tmp/other-project/`). When
+the repo is cloned on a different machine, or the user's home directory
+has different state, the test either fails spuriously or — worse — passes
+by coincidence while testing the wrong thing.
+
+### Signals
+
+- `[[ -f ~/.xxx/... ]]`, `[[ -d ~/.xxx/... ]]`, `cat ~/.xxx/...` inside
+an assertion.
+- A tmp path that the test file did not create itself.
+- Paths starting with `~`, `${HOME}`, `/Users/`, or `/home/` that the test
+file did not create itself.
+
+### Fix template
+
+```ts
+// BEFORE — asserts on a file that lives outside the repo
+it("skill file is synced", () => {
+  expect(readFileSync(`${homedir()}/.roll/skills/roll-.dream/SKILL.md`, "utf8")).toMatch(/Scan 6/);
+});
+
+// AFTER — recreate the fixture inside a tmpdir owned by the test
+it("skill file includes Scan 6", () => {
+  const home = mkdtempSync(join(tmpdir(), "h-"));
+  mkdirSync(join(home, ".roll/skills/roll-.dream"), { recursive: true });
+  writeFileSync(join(home, ".roll/skills/roll-.dream/SKILL.md"), "### Scan 6 — Doc Freshness\n");
+  expect(checkSkillHasScan6({ home })).toBe(true);
+});
+```
+
+If the test's purpose is truly to verify interaction with an external file,
+inject the home/root path (a tmpdir) so the test stays deterministic across
+machines.
+
+### Real example
+
+A dream-scan test that asserts on `${HOME}/.roll/skills/roll-.dream/SKILL.md`,
+a file outside the repo whose content depends on whether the user ran
+`roll setup`. On a machine without Roll installed, or with an older version,
+the test fails even though the project code under test is correct. Sandbox the
+fixture under a temp `HOME` instead.
+
+---
+
+## How `roll-.dream` consumes this rubric
+
+`roll-.dream` Scan 7 scans the test suite for each category's signals,
+emits at most 5 REFACTOR entries per cycle (rate cap to avoid drowning
+the backlog), and tags each entry with the matching marker:
+
+```markdown
+| REFACTOR-XXX | docs: <one-line description> [test-quality:❶] — flagged by dream YYYY-MM-DD | 📋 Todo |
+```
+
+The maintainer triages the REFACTOR queue in the morning brief.

package/guide/en/testing.md

@@ -0,0 +1,123 @@
+# Roll — Testing Workflow
+
+Roll enforces a test-first discipline throughout delivery:
+
+- **TCR** (Test && Commit || Revert) — every micro-step passes tests before committing.
+- **E2E Deposit** — each completed Story leaves an E2E test covering its golden path.
+- **CI E2E Gate** — the deposited E2E runs on every push, blocking merges on failure.
+- **proof-of-pass** — pre-commit hook physically blocks commits that haven't passed tests.
+
+## E2E Deposit
+
+After TCR micro-steps pass, `$roll-build` Phase 5.5 deposits an E2E test:
+
+1. Detects your project's existing E2E infrastructure (framework, directory, naming).
+2. Writes one E2E test covering the Story's critical user path.
+3. Runs it — fixes via TCR if red.
+4. Commits: `tcr: e2e deposit for <story-id>`.
+
+The deposited test becomes a durable regression guard that CI replays on every
+push, blocking merges on failure.
+
+## Pre-commit Hook (proof-of-pass)
+
+Roll's pre-commit hook blocks commits unless tests passed within the last 60 seconds
+**on the exact tree being committed**:
+
+```bash
+# Proof written by test runner:
+# .roll/last-test-pass  ← timestamp + tree hash
+
+# Hook checks at commit time:
+# - elapsed < 60 s
+# - tree hash matches current staged tree
+```
+
+To satisfy the hook, run your tests immediately before committing. If you use TCR
+(which roll-build does), this is automatic.
+
+## CI E2E Gate
+
+The template CI workflow (`.github/workflows/ci.yml`) runs E2E tests as a
+separate job that must pass before merge. If E2E fails:
+
+1. Check the failing test name — it corresponds to a Story ID.
+2. Run the test locally to reproduce.
+3. Open a `FIX-XXX` entry in `BACKLOG.md`, or use `$roll-fix` to fix immediately.
+
+## Failure Triage
+
+`$roll-.qa` provides structured guidance for diagnosing test failures at each
+layer of the test pyramid:
+
+| Layer | Run command | Triage starting point |
+|-------|-------------|-----------------------|
+| Unit | `pnpm --filter @roll/<pkg> test` | Failing test file → function name |
+| Integration | `pnpm --filter @roll/cli test` | Captured stdout/exit, fixture cwd |
+| E2E | `<project E2E command>` | User path, environment |
+| Smoke | `roll doctor` | Toolchain health |
+
+## TCR Test Strategy (Phase 3.0)
+
+Each TCR micro-step needs second-level feedback. The suite is **Vitest** across
+the pnpm workspace; the gate runs only what the diff touched.
+
+### `roll test` — run only the tests touched by the diff
+
+```bash
+roll test               # affected-only (the TCR micro-step gate); writes the test-pass proof
+pnpm --filter @roll/cli exec vitest run test/<file>.test.ts   # one file
+pnpm -r test            # the full suite (pre-push / CI / release)
+pnpm test:cov           # full suite with v8 coverage
+```
+
+`roll test` maps the diff to affected Vitest files, runs them, and writes the
+proof the commit gate checks (see below). A doc-only change has no affected
+tests and exits 0. Pre-push / CI / release always run the full `pnpm -r test`.
+
+## Test Quality Rubric
+
+`guide/en/testing/quality-rubric.md` (referenced from `$roll-.dream` Scan 7)
+catalogs eight recurring antipatterns the dream nightly scan flags as
+`REFACTOR-XXX [test-quality:❶|❷|...|❽]`:
+
+| # | Antipattern | Fix |
+|---|-------------|-----|
+| ❶ | Hard-coded business data (prices, version strings, product copy) | Inject fixture data via monkey-patch or constructor; assert behaviour, not the data table itself |
+| ❷ | Over-mocking (database, filesystem, real boundary) | Use real subsystems behind small adapter mocks; prefer in-memory test doubles |
+| ❸ | Asserting implementation details (private symbol names, internal data shape) | Assert observable behaviour through the public API |
+| ❹ | Fixture order coupling (shared mutable state between tests) | Setup/teardown each test independently; use immutable fixtures |
+| ❺ | Testing private functions / bypassing the public API | Re-route through the public entry point; if it's hard to reach, the API is wrong |
+| ❻ | Asserting framework behaviour (testing Vitest itself) | Delete the test; trust the framework |
+| ❼ | Inlining external-tool behaviour (`sed`/`grep`/`awk` pipelines duplicated in test bodies) | Call the project helper that owns the parsing, or extract into a test helper module |
+| ❽ | Asserting on a file outside this repo (`~/.codex`, `~/.kimi`, `~/.roll`, system paths) | Sandbox in a temp dir (`mkdtempSync`), redirect env vars there, never touch live config |
+
+The dream skill emits at most 5 REFACTOR entries per scan, so the backlog
+doesn't drown in noise. Refactor them in priority order.
+
+### Test-quality merge gate (US-QA-012 / 013)
+
+Categories ❼ and ❽ are **blocking**: loop runs
+`roll loop test-quality-check <changed-test-files>` between CI green and
+auto-merge. Violations write `ALERT-<slug>.md` and hold the PR until either
+the test is reshaped or the PR description carries `[skip-test-quality]`
+(case-insensitive). Use the bypass sparingly — the violation still gets
+reported through dream as a REFACTOR row, so it doesn't quietly accumulate.
+
+Categories ❶..❻ remain advisory: dream flags them as REFACTOR entries but
+the gate doesn't block on them. Triage them in your usual queue.
+
+Lines with `# test-quality:allow` are skipped by the scanner — reserved for
+doc-validation tests that legitimately inline `awk` to parse markdown
+without ever touching production code.
+
+`packages/core/test/prices.difftest.test.ts` is the canonical ❶ exemplar —
+assertions that read live production rates broke every time the rate card moved,
+even when the arithmetic was unchanged. It now feeds a fixed fixture price table
+for the arithmetic and asserts only structural invariants (cache_read < input,
+etc.) on the production rates.
+
+## See Also
+
+- [loop.md](loop.md) — how loop enforces TCR discipline per story
+- [skills.md](skills.md) — `$roll-build` (delivers + deposits E2E)

package/guide/en/tools.md

@@ -0,0 +1,173 @@
+# Roll — Tools & Policy
+
+Roll's tools layer is the governed path for side effects that a delivery cycle performs: shell commands, browser inspection, filesystem access, git, GitHub, network fetches, and MCP calls.
+
+Tools are not a replacement for an AI client's own tool allowlist. Client-level `allowed-tools` controls what the inner agent may ask for. Roll's tool layer controls what the outer harness registers, how project policy is resolved, what events are recorded, and how costs appear in cycle evidence.
+
+See the tools-layer design plan in [../../.roll/features/tools-layer/plan.md](../../.roll/features/tools-layer/plan.md).
+
+## Concepts
+
+| Concept | Meaning |
+|---------|---------|
+| Tool declaration | The shared contract for a tool: id, kind, title, defaults, requirements, and input/output schema. |
+| Registry | The core path that registers tools, resolves policy, invokes adapters, emits events, retries, and snapshots costs. |
+| Adapter | The infra implementation for one tool family, such as `bash`, `browser.screenshot`, `git.push`, or `network.fetch`. |
+| Policy | The effective settings from declaration defaults plus `.roll/policy.yaml` overrides. |
+| Evidence | `tool:invoke`, `tool:result`, cycle cost rows, CLI output, attest reports, and dashboard timeline rows. |
+
+Registered tool families today:
+
+| Family | Tool ids |
+|--------|----------|
+| 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` |
+
+Browse the full built-in tool catalog — every tool with its capability, input/output contract, default guardrails, and requirements — on the machine-global **Tools** page (`tools.html`), one of the `MACHINE › …` breadcrumb pages alongside Agents and Skills.
+
+## Project Policy
+
+Tool policy lives under the `tools:` section of `.roll/policy.yaml`.
+
+```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]
+```
+
+Supported fields:
+
+| Field | Scope | Meaning |
+|-------|-------|---------|
+| `enabled` | tool | `false` blocks invocation through policy. |
+| `timeoutMs` | tool | Soft timeout used by the adapter unless the input has a narrower limit. |
+| `retry.attempts` | tool | Maximum attempts for adapters that support retry. |
+| `retry.backoffMs` | tool | Delay between retry attempts. |
+| `maxInvocationsPerCycle` | tool | Per-cycle budget limit enforced by the registry. |
+| `sandbox.allowedPaths` | sandbox | Path allowlist for filesystem-like adapters. |
+| `sandbox.blockedCommands` | sandbox | Advisory command blocklist for bash. |
+| `sandbox.hardTimeoutSec` | sandbox | Hard execution limit for adapters that support it. |
+| `sandbox.maxOutputBytes` | sandbox | Output truncation limit. |
+| `sandbox.allowedOrigins` | sandbox | Network or browser origin allowlist. |
+| `sandbox.headlessOnly` | sandbox | Browser lane must stay headless. |
+| `sandbox.network` | sandbox | `inherit`, `restricted`, or `blocked`. |
+
+Unknown fields warn but do not reject the policy file, so newer Roll versions can add fields without breaking older project configs.
+
+## CLI
+
+Use `roll doctor tools status` to inspect the registered tools, input contracts, requirement readiness, and the effective policy state for the current project.
+
+```bash
+roll doctor tools status
+```
+
+Example output:
+
+```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
+```
+
+Use it after editing `.roll/policy.yaml` to confirm Roll sees the intended state.
+
+## Complete Example
+
+This example locks browser screenshots to a local dev server, confirms the effective policy, and then verifies where the tool evidence appears after a delivery.
+
+1. Configure browser and network policy for the project:
+
+```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. Confirm Roll resolved the policy:
+
+```bash
+roll doctor tools status
+```
+
+Expected rows:
+
+```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. Run a delivery that has a visible web surface. The story spec should declare the page it wants captured:
+
+```yaml
+---
+deliverable_url: http://localhost:4173
+---
+```
+
+During attest, Roll captures the page through `browser.screenshot`. The exposed Roll tool id is `browser.screenshot`; Playwright or Chrome may be used underneath, but `playwright` is not a policy key or tool id.
+
+4. Inspect the evidence:
+
+```bash
+roll loop cycle <cycle-id>
+```
+
+Look for rows like:
+
+```text
+tools browser.screenshot×1(2.0s) network.fetch×1(0.4s)
+```
+
+In the story attest report and cycle views, the same event stream appears as:
+
+| Evidence | What to check |
+|----------|---------------|
+| `tool:invoke` | Tool id, caller cycle, resolved policy. |
+| `tool:result` | Success or error code, duration, output path. |
+| Screenshot link | A `.roll/tool-dumps/...png` or attached card screenshot path. |
+| Cost row | Currency is preserved as USD, CNY/RMB, or `¥`; mixed currencies are not collapsed into one fake total. |
+
+## Evidence And Cost
+
+`roll loop status`, `roll loop cycle`, and attest reports show tool summaries from the event stream. Failed tool calls keep their error codes, and screenshot tools can link directly to captured images.
+
+Tool costs preserve their native currency. USD rows stay USD. CNY/RMB rows stay CNY/RMB or `¥`. Roll does not relabel RMB-denominated tool or model costs as dollars and does not blindly add mixed currencies into one number.

package/guide/skills.md

@@ -0,0 +1,30 @@
+# Roll Skill Catalog
+
+> GENERATED by `roll setup skills` — do not edit by hand.
+> 由 `roll setup skills` 生成 — 请勿手工编辑。
+>
+> Source of truth: each skill's `skills/<name>/SKILL.md` frontmatter.
+> 事实源：各 skill 的 `skills/<name>/SKILL.md` frontmatter。
+
+| Skill | Description |
+|-------|-------------|
+| `roll-.changelog` | After build completion, extracts completed Stories from .roll/backlog.md to generate CHANGELOG.md. Auto-triggered after successful deploy, keeping the external changelog in sync with the internal backlog. |
+| `roll-.clarify` | Passive scope-clarification skill. Auto-triggers when roll-build receives vague or under-specified input in Fly mode. Summarizes intent and asks 3–5 targeted questions to establish boundaries before planning or coding. This is a passive skill. Never announce "I'm using roll-.clarify." Just do it naturally: summarize, ask, wait. |
+| `roll-.dream` | Nightly code and architecture health scan. Passively triggered by scheduler (cron or GitHub Actions), not invoked by users directly. Detects dead code, architectural drift from domain model, pruning candidates, emerging patterns, doc coverage gaps, and doc staleness (文档新鲜度). Outputs REFACTOR entries to .roll/backlog.md and a daily log to .roll/dream/. A Loop C observability/maintenance surface: it reviews code structure and architectural health and feeds corrections back into the backlog. |
+| `roll-.echo` | Passive intent clarification skill. Automatically activates when user input is vague, rambling, contradictory, or unclear. Restates the user's intent in structured, concise form and confirms before proceeding. Does NOT activate when intent is already clear — in that case, just execute directly. This is a passive skill. Never announce "I'm using roll-.echo." Just do it naturally: restate, confirm, proceed. |
+| `roll-.qa` | QA coverage reference for build skills. Defines test pyramid (unit/E2E/visual/smoke), coverage requirements, and CI gates. Ensures quality assurance across all testing layers. |
+| `roll-.review` | Self code review step in the TCR workflow. Runs after each micro-step is completed and before commit, checking code quality, security, and design issues. |
+| `roll-build` | Universal delivery skill. Handles any input: a US-XXX ID executes from BACKLOG via TCR; a FIX-XXX redirects to roll-fix; any other text auto-clarifies, designs, and ships as a new Story. |
+| `roll-debug` | Universal web debugger. Mounts a Black Box (BB) diagnostic probe on any page, collects rich diagnostics, analyzes root causes, and auto-fixes when the root cause is in project source. Cleans up after itself. |
+| `roll-design` | Unified entry for discussion, design and planning. Explores options when uncertain, designs solutions with DDD modeling, splits into INVEST-compliant user stories, and writes to .roll/backlog.md. Use when user wants to discuss approaches, design solutions, plan features, or create stories. |
+| `roll-doc-audit` | Documentation/product consistency audit. Checks README, guides, site pages, CLI help and docs against implemented behavior; can also index docs and draft fills from code evidence. |
+| `roll-doctor` | Diagnose Roll toolchain health. Checks skill files, YAML frontmatter, symlinks, conventions sync, template integrity, and config validity. |
+| `roll-fix` | Execute bugfix/hotfix from backlog. Reads FIX/BUG from .roll/backlog.md, delivers via TCR workflow. Lighter than roll-build, focused on single-issue fixes. |
+| `roll-idea` | Fast backlog capture. Analyzes a short description, classifies it as bug or idea, and appends it to .roll/backlog.md with an auto-incremented ID. |
+| `roll-loop` | Autonomous BACKLOG executor. Runs on a schedule (hourly via cron or GitHub Actions), scans .roll/backlog.md for 📋 Todo items, and routes each to the appropriate skill: US-XXX → $roll-build, FIX-XXX → $roll-fix, REFACTOR-XXX → $roll-build. Retries the primary agent up to 3 times on transient failure; pauses with ALERT on persistent failure. Never cuts a release autonomously — release is always a human decision. The human reads delivery state from CLI-first surfaces such as roll status, roll cycle, loop watch, alerts, and story reports. |
+| `roll-notes` | Project diary skill. Records development moments — successes, failures, discoveries — appended chronologically to a daily notes file. |
+| `roll-onboard` | Interactive onboarding for legacy projects. Reads existing code, understands the project, asks 9 questions in 3 groups (cognition / scope / privacy), and writes .roll/onboard-plan.yaml as the contract for `roll init --apply` to execute. |
+| `roll-peer` | Cross-agent peer review skill. When a task enters a decision phase (planning, high-risk, ambiguous, destructive), triggers a bidirectional negotiation with another AI agent via a unified protocol. Up to 3 rounds. If consensus is not reached, escalates to the human user. Includes adaptive peer routing based on task type and historical success rate. Trigger: /peer, "叫上 peer", "peer review", or auto-triggered at workflow gates. |
+| `roll-propose` | Human-triggered product proposal generator. Reads project context (BACKLOG, recent commits, existing skills) and generates 1–3 structured US drafts from a user-facing perspective. Writes to .roll/proposals.md for human review — never directly to BACKLOG. Distinct from roll-.dream (which surfaces technical debt from execution experience); roll-propose thinks in user scenarios and feature gaps. |
+| `roll-review-pr` | Agent-agnostic PR review skill. Reviews a pull request diff and emits a structured 3-state verdict (APPROVE / REQUEST_CHANGES / UNCERTAIN). Dispatched by `roll loop pr-inbox` for eligible external PRs. |
+| `roll-spar` | Adversarial TDD mode with Attacker/Defender agents. Attacker writes tests to break the system, Defender writes minimal code to pass. Use for high-risk logic like auth, payments, data integrity, or complex state machines. |