@seanyao/roll 4.630.2 → 4.702.2

package/guide/en/roll-doc-audit.md

@@ -0,0 +1,98 @@
+# roll-doc-audit — Documentation/Product Consistency Audit
+
+`roll-doc-audit` checks user-facing documentation surfaces against implemented
+behavior: README, guides, site pages, CLI help, tests, and source. When a
+documentation inventory is requested, it also produces draft documentation: a
+doc index, module READMEs for undocumented directories, and — in Phase 3b —
+deep cross-directory topic docs (data flows, state machines, integrations, and
+more). It never invents behavior without source evidence.
+
+```
+$roll-doc-audit              # full run (all phases)
+$roll-doc-audit --dry-run    # Phases 1–2 only; print the Phase 3 / 3b plan, write nothing
+$roll-doc-audit --force      # regenerate drafts even when target files already exist
+```
+
+## The Four-Phase Pipeline
+
+roll-doc-audit runs four phases in order, plus a deep-read Phase 3b that fires when
+the project has cross-directory structure worth documenting.
+
+| Phase | Name | What it does |
+|-------|------|--------------|
+| 1 | Scan & Index | Walk the tree, classify every `*.md` and convention file, (over)write `docs/INDEX.md` with a coverage summary and gap report. |
+| 2 | Gap Analysis | Find module directories with ≥ 3 source files (or imported by ≥ 5 files) and no `README.md`, plus special gaps (domain map, conventions doc). |
+| 3 | Fill | For each directory-level gap, read up to 20 files from that directory and generate a draft `README.md` / context map / conventions doc. Skip existing files unless `--force`. |
+| 3b | Deep Read | Build a full project symbol table (no truncation) and detect six cross-directory topics that Phase 3 alone cannot find. |
+| 4 | Report | Print a per-phase summary: docs indexed, gaps found, drafts generated, Phase 3b symbol-table counts and topic docs. |
+
+Phase 3b is the difference between "directory-by-directory" docs and docs that
+follow logic across the whole codebase. Phase 3 reads each gap directory in
+isolation (and only a capped number of files per directory); Phase 3b reads
+every source file in full and reasons across files.
+
+## Phase 3b — The Six Topics
+
+Phase 3b runs when **either** Phase 2 found a gap **or** the project shows
+code characteristics Phase 3 cannot capture (import chains spanning ≥ 3
+directories, shared state enums, external endpoint calls, or CI config). A
+pure docs-only project with no source gaps skips Phase 3b entirely.
+
+After building the symbol table (`exports`, `imports`, `enums`,
+`external_urls`, `configs`), Phase 3b detects six topic types. Each is skipped
+when its detection rule finds nothing, and skipped when its target file already
+exists (unless `--force`).
+
+| # | Topic | Trigger condition | Output |
+|---|-------|-------------------|--------|
+| 1 | Data flow / call chain | An import chain from an entry file (`bin/`, `main.*`, `index.*`) spans ≥ 3 distinct source directories | `docs/data-flows.md` |
+| 2 | State machine | An enum named `*State` / `*Status` referenced by ≥ 2 source files | `docs/state-machines.md` |
+| 3 | External integrations | `fetch` / `axios` / `http.*` calls or `*_URL` / `*_HOST` constants (outside comments and test fixtures) | `docs/integrations.md` |
+| 4 | Deployment pipeline | A CI config file (`.github/workflows/*.yml`, `.gitlab-ci.yml`, `circle.yml`, `Jenkinsfile`) plus a deploy URL pattern | `docs/deployment.md` |
+| 5 | Agent entrypoint | No `AGENTS.md` at root AND the source root has ≥ 3 subdirectories | `AGENTS.md` |
+| 6 | High fan-in directory | A directory imported by ≥ 5 other source files, even with < 3 source files | `<dir>/README.md` |
+
+Every topic doc cites `file:line` for each claim, sourced from real symbol-table
+records — roll-doc-audit never fabricates a line number.
+
+## dry-run / force Behavior
+
+**`--dry-run`** runs Phases 1–2, then prints the Phase 3 fill plan and the
+Phase 3b plan (symbol-table summary counts plus the topic docs it *would*
+generate, each tagged `(plan)`). Nothing is written to disk. Use it to preview
+before committing to a full run.
+
+**`--force`** regenerates drafts even when the target file already exists. It
+affects only draft generation (Phase 3 and Phase 3b output files); the symbol
+table is rebuilt from scratch on every run regardless of flags. `--force` never
+touches `docs/INDEX.md` behavior (always rebuilt) and never overwrites human
+content outside the draft targets.
+
+**Default (no flag)** is idempotent: re-running when no new gaps exist is a
+no-op — no files written, no existing drafts modified.
+
+## Typical Output Files
+
+A full run on a code-bearing project may produce:
+
+```
+docs/INDEX.md            # Phase 1 — always (over)written
+src/<module>/README.md   # Phase 3 — one per module gap
+docs/CONVENTIONS.md      # Phase 3 — when no conventions doc exists
+.roll/domain/context-map.md  # Phase 3 — when no domain entries exist
+docs/data-flows.md       # Phase 3b — cross-directory call chains
+docs/state-machines.md   # Phase 3b — shared state enums
+docs/integrations.md     # Phase 3b — external endpoints
+docs/deployment.md       # Phase 3b — CI pipeline
+AGENTS.md                # Phase 3b — only when none exists
+<dir>/README.md          # Phase 3b — high fan-in directories
+```
+
+Only `docs/INDEX.md` is ever overwritten — it is a derived artifact. Every
+other file is a draft headed with:
+
+```
+> **Draft** — auto-generated by roll-doc-audit on YYYY-MM-DD. Review before treating as authoritative.
+```
+
+Review each draft, edit as needed, and commit the ones you want to keep.

package/guide/en/skills.md

@@ -0,0 +1,206 @@
+# Roll Skill Selection Guide
+
+Quickly select the right skill or tool.
+
+## Core Skills
+
+| User Intent | Skill | Description |
+|---------|-----------|------|
+| **"Not sure how to do it"** / **"There are several options"** | `roll-design` | Explore solutions, compare options, human decision-making |
+| **"Help me build a..."** / **"Implement US-001"** / **"Fix FIX-001"** | `roll-build` | Universal entry: US-XXX story mode, FIX-XXX fix mode, or free-text fly mode — all in one skill |
+| **"This logic is critical"** / **"Involves payment"** | `roll-spar` | Adversarial TDD, activate for high-risk scenarios |
+| **"Fix a bug"** / **"Change some copy"** | `roll-fix` | Quick fix, no full workflow |
+| **"Plan requirements"** / **"Split into stories"** | `roll-design` | Plan only, no implementation, outputs BACKLOG.md |
+| **"Run several Actions in parallel"** | `roll-build` | Auto-determines parallelism after splitting Actions |
+| **"What shipped / what's queued?"** | `roll status` / `roll loop cycle` / story reports | CLI-first delivery state, cycle trace, and story-scoped evidence |
+| **"Debug this page"** | `roll-debug` | Deep diagnosis, collect logs/network/DOM |
+
+## Support Skills
+
+| Scenario | Skill | Trigger Timing |
+|------|-------|---------|
+| Code self-review | `roll-.review` | Before Commit, or manually triggered |
+| Generate Changelog | `roll-.changelog` | Auto-triggered after successful Deploy |
+| QA test reference | `roll-.qa` | Referenced when writing tests |
+| Intent clarification | `roll-.echo` | Auto-activates when user input is vague or unclear |
+| Documentation/product audit | `roll-doc-audit` | Check README, guides, site pages, CLI help and docs against implemented behavior; optionally index docs and fill gaps |
+
+## roll-doc-audit — Documentation/Product Consistency Audit
+
+`roll-doc-audit` first checks user-facing documentation surfaces against real
+behavior: README, guides, site pages, CLI help, tests, and source. For inventory
+work it still runs the four-phase docs pipeline — scan/index → gap analysis →
+fill → report — plus a deep-read **Phase 3b**. Phase 3 fills directory-level
+gaps; Phase 3b builds a full project symbol table and detects **6
+cross-directory topics** that directory-level filling alone cannot find:
+
+| Topic | Triggers when | Output |
+|-------|---------------|--------|
+| Data flow / call chain | An import chain spans ≥ 3 source directories | `docs/data-flows.md` |
+| State machine | A `*State` / `*Status` enum is referenced by ≥ 2 files | `docs/state-machines.md` |
+| External integrations | `fetch` / `axios` / `*_URL` constants are present | `docs/integrations.md` |
+| Deployment pipeline | A CI config file plus a deploy URL pattern exists | `docs/deployment.md` |
+| Agent entrypoint | No `AGENTS.md` and the source root has ≥ 3 subdirs | `AGENTS.md` |
+| High fan-in directory | A directory is imported by ≥ 5 source files | `<dir>/README.md` |
+
+`$roll-doc-audit --dry-run` runs Phases 1–2 and prints the Phase 3 / 3b plan without
+writing; `$roll-doc-audit --force` regenerates drafts even when targets already exist.
+Full guide: [roll-doc-audit.md](roll-doc-audit.md).
+
+## Quick Decision Tree
+
+```
+User Input
+    |
++----------------------+
+| "Unsure about        |
+|  the approach?"      |--> roll-design
++----------------------+
+    | No
++----------------------+
+| "One-sentence        |
+|  request?"           |--> roll-build (fly mode)
++----------------------+
+    | No
++----------------------+
+| "Has a US-XXX ID?"   |--> roll-build (story mode)
++----------------------+
+    | No
++----------------------+
+| "Has a FIX-XXX ID?"  |--> roll-fix
++----------------------+
+    | No
++----------------------+
+| "Fix a bug?"         |--> roll-fix
++----------------------+
+    | No
++----------------------+
+| "Plan/split?"        |--> roll-design
++----------------------+
+    | No
++----------------------+
+| "High-risk logic?"   |--> roll-spar
++----------------------+
+    | No
+  Manual judgment
+```
+
+## Review Score (US-SKILL-010..014, FIX-343)
+
+Skills do **not** self-score. The working agent never grades its own story;
+the **Review Score** is a runner-side peer outcome, produced by a Reviewer in
+a fresh, separate session (never a sub-agent of the builder). After a
+`roll-build` or `roll-fix` cycle delivers, the runner casts a fresh-session
+Reviewer and writes one structured Review Score note into the story's card
+folder (US-META-008 — the card folder is the story's single home; the flat
+`.roll/notes/` keeps the project diary and pre-migration history, and both
+the dashboard trend and the story archive merge the two sources):
+
+```
+.roll/features/<epic>/US-AUTH-001/notes/2026-05-29-roll-build-US-AUTH-001-1717000000.md
+.roll/features/<epic>/FIX-072/notes/2026-05-29-roll-fix-FIX-072-1717000123.md
+```
+
+Each note is YAML frontmatter + rationale:
+
+```markdown
+---
+skill: roll-build
+story: US-AUTH-001
+score: 8
+verdict: good
+ts: 2026-05-29T03:14:15Z
+---
+
+Story shipped cleanly; AC fully met. One TCR retry on the auth-cookie test
+(missing setup). Peer review surfaced one nit, addressed inline.
+```
+
+`roll loop status` rolls up the trend at the bottom of the ROLLUP block:
+
+```
+review-score: mean 7.8 / min 4 / redo 2 (last 14)
+```
+
+`redo` counts entries whose `verdict` is `regression`, or whose `verdict`
+is `ok` with `score < 6` — both signal that a follow-up look is
+warranted. Mean and min cover the whole window so a single bad cycle
+doesn't get hidden by the average.
+
+The notes are part of `.roll/` and therefore commit-tracked, so the
+quality trail is reproducible across machines and visible to anyone
+reading the project history.
+
+`roll loop status` 状态盘底部会汇总评审分趋势:`review-score: mean 7.8 /
+min 4 / redo 2 (last 14)`,`redo` 包含 `regression` 判定和 `ok` 但分
+数 < 6 的低置信交付,共同标记需要回看的 cycle 数量。评审分由全新独立会话
+的同行 Reviewer 产出,工作 agent 绝不自评。
+
+## Adding a New Skill
+
+A skill is a directory under `skills/<name>/` with a `SKILL.md` whose YAML
+frontmatter declares at least `name` and `description`. To register a new
+skill, follow these steps — you never hand-maintain a catalog list:
+
+1. Create `skills/<name>/SKILL.md` with frontmatter (`name`, `description`,
+   `license`, and `allowed-tools` — see below).
+2. Regenerate the capability catalog:
+
+   ```bash
+   roll setup skills
+   ```
+
+   This rescans every `skills/*/SKILL.md` and rewrites `guide/skills.md` from
+   the frontmatter. `guide/skills.md` is a **generated artifact** — its header
+   says `GENERATED by roll setup skills — do not edit by hand`. Adding or
+   removing a skill is reflected automatically on the next regenerate; never
+   edit `guide/skills.md` by hand.
+3. Commit both the new `SKILL.md` and the regenerated `guide/skills.md`.
+
+### Drift guard
+
+The committed catalog cannot silently drift from the actual skills:
+
+- `roll doctor skills` rescans and fails (non-zero exit, prints a diff) if
+  `guide/skills.md` no longer matches `skills/*/SKILL.md`. CI runs this gate,
+  so a hand-edit or a forgotten regenerate is caught before merge.
+- `roll doctor` prints a non-failing nudge in its skills section when the
+  catalog is stale, as a local reminder to run `roll setup skills`.
+
+The scan is bash 3.2 compatible (awk-based parser; no `declare -A`, `mapfile`,
+or `${var^^}`), so it runs on the macOS system bash.
+
+## Declaring Tool Scope (`allowed-tools`)
+
+Every `SKILL.md` frontmatter should declare an `allowed-tools` line listing the
+tools the skill is permitted to use:
+
+```yaml
+---
+name: roll-design
+license: MIT
+allowed-tools: "Read, Edit, Write, Glob, Grep, Bash(git:*), WebSearch, WebFetch, Skill"
+description: ...
+---
+```
+
+- **What to write**: the comma-separated set of tools the skill actually needs
+  (e.g. `Read, Edit, Write, Glob, Grep`), narrowing Bash where possible with
+  the `Bash(git:*)` glob form rather than granting unscoped `Bash`.
+- **Why declare it**: the declaration documents each skill's intended tool
+  surface so the scope is auditable and reviewable per skill, consistent across
+  the catalog.
+- **What this is for Roll**: a **declaration + lint** only. Roll surfaces the
+  declaration and lints for its presence; the actual tool **enforcement**
+  happens in the inner agent harness, not in Roll. Writing `allowed-tools` does
+  not by itself sandbox the skill.
+
+## Auto-Trigger Keywords
+
+| Skill | Trigger Keywords |
+|-------|-----------|
+| `roll-design` | "discuss", "compare options", "how to choose", "trade-offs", "not sure what to use", "design", "plan", "split", "write stories", "requirements analysis" |
+| `roll-build` | "help me build", "add a feature", "change this", "refactor", "implement US-", "do this story", "complete Action", "parallel", "develop simultaneously" |
+| `roll-fix` | "fix bug", "change copy", "adjust color", "error", "FIX-", "BUG-" |
+| `roll-spar` | "adversarial", "attack-defense", "high-risk", "critical logic", "payment", "permissions", "security" |
+| `roll-debug` | "debug", "diagnose", "page has issues", "black-box analysis" |

package/guide/en/test-isolation.md

@@ -0,0 +1,51 @@
+# Roll — Test Isolation (`roll test`)
+
+`roll test` runs your project's test suite through an **isolation adapter**
+selected in `.roll/local.yaml`:
+
+```yaml
+test_isolation:
+  type: none   # default
+```
+
+## `type: none` (the only built-in adapter)
+
+Direct host execution — the same shell `npm test` would use. `roll test`
+forwards to `npm test -- <args>` with `--affected` as the default argument:
+
+```bash
+roll test                  # npm test -- --affected
+roll test -- tests/        # full suite, explicit
+roll test -- --tier=fast   # forward anything to npm test
+```
+
+The v3 test suites are hermetic by construction — fabricated `$HOME`s,
+PATH-shimmed binaries, `file://` remotes, blackholed network — so host
+execution does not touch your launchd jobs, shared roll state, or the network.
+
+## Routing: `--where`
+
+Prints where tests would run, without running them:
+
+| Configured type | `--where` prints |
+|---|---|
+| `none` (or no config) | `host` |
+| anything else | `unknown:<type>` |
+
+The `<type>:<detail>` token format is the **extension point**: a future
+adapter (say, a container lane) would print `docker:running`-style tokens in
+the same shape.
+
+## Unknown types fail loud
+
+Any `test_isolation.type` other than `none` makes `roll test` exit non-zero
+with an explicit error listing the supported types. It never silently falls
+back to host execution — a misconfigured isolation lane should stop you, not
+quietly change where your tests run.
+
+## `--reset`
+
+Resets the isolation environment. For `type: none` there is nothing to reset
+(host execution is stateless): it prints a note and exits 0. A reset holds a
+lockfile at `.roll/.iso-reset.lock`; concurrent `roll test` invocations
+fast-fail with a clear message while it is held.