@seanyao/roll 4.630.1 → 4.702.2

package/guide/en/configuration.md

@@ -0,0 +1,112 @@
+# Roll — Configuration
+
+Roll resolves three environment variables at startup. Override any of them
+before running `roll` to change where it looks for state, skills, and
+shared conventions.
+
+## Environment Variables
+
+| Variable | Default | Purpose |
+|----------|---------|---------|
+| `ROLL_HOME` | `~/.roll` | Per-user state root. Holds `config.yaml`, installed `skills/`, synced `conventions/`. |
+| `ROLL_CONFIG` | `$ROLL_HOME/config.yaml` | Editor, loop/dream/brief schedule hours, and per-tool (`ai_*`) config. Agent routing is **not** here — it lives in per-project `.roll/agents.yaml` (see [ai-agents.md](ai-agents.md)). |
+| `ROLL_GLOBAL` | `$ROLL_HOME/conventions/global` | Global convention files (`AGENTS.md`, `CLAUDE.md`, etc.) synced into AI tool directories. |
+| `ROLL_LANG` | unset | Per-process language override for CLI/help/HTML user surfaces. Supported values are `en` and `zh`; when unset, Roll uses the saved config preference or locale detection. |
+| `ROLL_HEARTBEAT_TIMEOUT` | `1800` (seconds) | How long without a heartbeat write before the loop runner treats an inner cycle as orphan and heals state. Raise it if your cycles can legitimately stay quiet longer than 30 minutes. |
+| `ROLL_LOOP_FORCE` | unset | When set to any non-empty value, `roll loop` bypasses the active-window check and the pause file. `roll loop now` and `roll loop test` set this internally; export it manually only when you want a cron-scheduled run to ignore quiet hours. |
+| `ROLL_LOOP_NO_HEAL` | `0` | Set to `1` to disable post-build CI self-heal and restore fail-fast behaviour. Useful for debugging or when you want to cap autonomous spend per cycle. |
+| `ROLL_LOOP_HEAL_MAX` | `2` | Maximum number of CI self-heal attempts per story after the build commits land. Raise it for noisy CI environments; lower it to fail faster. |
+| `ROLL_PR_MERGE_TIMEOUT` | `600` (seconds) | **Deprecated (US-AUTO-044).** The main loop no longer waits for merge, so this is unused; PR merging is now handled asynchronously by the dedicated PR Loop. |
+| `ROLL_LOOP_NO_POPUP` | unset | When set to any non-empty value, the runner does **not** auto-spawn a macOS Terminal.app window running `tmux attach`. For tests and headless batch runs — the popup outlives the killed tmux session and clutters the desktop. |
+| `ROLL_LOOP_GC_RETENTION_DAYS` | `30` | Override the GC retention period for `roll loop gc`. Takes precedence over `loop_gc.retention_days` in `.roll/local.yaml`. |
+| `ROLL_FEED_BUDGET_BYTES` | `16384` | Byte budget for the context feed handed to the inner agent each cycle. Set it to a positive integer to dial the feed to the inner agent's capacity; non-numeric or non-positive values fall back to the default. |
+| `ROLL_AGENT_NUDGE` | `1` (on) | Compatibility agent preference switch. The scoped role binding is the primary selector; set this to `0` (or `off`/`false`/`no`) to disable legacy history preference. |
+| `ROLL_RUN_DIR` | unset | Canonical acceptance-evidence run directory. The loop runner sets it before agent spawn; `roll attest --run-dir` and standalone `roll attest` can also consume it. |
+| `ROLL_EVIDENCE_DIR` | derived from `ROLL_RUN_DIR` | Directory for raw command/test artifacts inside the open evidence frame. Normally set by the runner or `roll test`, not by hand. |
+| `ROLL_SCREENSHOTS_DIR` | derived from `ROLL_RUN_DIR` | Directory for visual proof inside the open evidence frame. Normally set by the runner or capture lane, not by hand. |
+
+`ROLL_CONFIG` and `ROLL_GLOBAL` derive from `ROLL_HOME`, so usually you only
+need to override `ROLL_HOME` to relocate everything together.
+
+## Common Overrides
+
+Pin roll's state to a project-local directory (useful for CI, tests, or
+isolated experimentation):
+
+```bash
+export ROLL_HOME="$PWD/.roll-sandbox"
+roll setup
+roll loop now
+```
+
+Run roll against an alternate convention set without touching `~/.roll`:
+
+```bash
+ROLL_GLOBAL=/path/to/team-conventions roll init
+```
+
+Point `ROLL_CONFIG` at a one-off config file to test changes:
+
+```bash
+ROLL_CONFIG=/tmp/test-config.yaml roll status
+```
+
+## Language Selection
+
+Language has two controls:
+
+- `ROLL_LANG=en|zh` overrides the language for the current process and wins over
+  saved config.
+- `roll config lang en|zh` saves the preference in Roll config;
+  `roll config lang --reset` clears it so locale detection applies again.
+
+`roll help --lang en|zh <topic>` is a one-command override for help and guide
+reads. `roll doctor language` audits active docs, conventions, skills, and
+generated surfaces for mixed-language drift. The expected CLI language snapshots
+are maintained in `packages/cli/test/cli-language-surface.test.ts` and
+`packages/cli/test/__snapshots__/cli-language-surface.test.ts.snap`; the audit
+surface is covered by `packages/cli/test/doctor-language.test.ts`.
+
+User-facing surfaces still render one visible language at a time. Agent
+contracts, code, git metadata, and stable schema keys remain English.
+Owner-facing conversation follows the language the owner uses in the current
+task.
+
+## Project Policy
+
+Project-local safety policy lives in `.roll/policy.yaml`. The acceptance
+evidence gate defaults to `hard`: a delivered story with ACs needs a fresh,
+contentful attest report before it can be marked `✅ Done`.
+
+```yaml
+loop_safety:
+  attest_gate: hard
+```
+
+Use `attest_gate: soft` only for an explicit migration window. Soft mode keeps
+the audit trail and alert, but it does not block the delivery cycle.
+
+## Verifying
+
+`roll status` prints the resolved paths so you can confirm overrides took
+effect. Invoke the `roll-doctor` skill (`$roll-doctor`) to diagnose
+directory structure issues under the resolved `ROLL_HOME`.
+
+## Agent Installation
+
+Install the agent CLI, then declare or bind it through the scoped agent files:
+`~/.roll/agents.yaml` for Machine Scope and `.roll/agents.yaml` for Project
+Scope. For example:
+
+- Codex CLI: `npm install -g @openai/codex`
+- Antigravity CLI: `npm install -g @antigravity/agy`
+
+Run `roll agent` to inspect the effective scopes, or `roll agent migrate
+--dry-run` to convert legacy agent config. See [ai-agents.md](ai-agents.md) for
+the full model and supported agent list.
+
+## See Also
+
+- [overview.md](overview.md) — three-layer model, BACKLOG priority
+- [loop.md](loop.md) — `roll loop` subcommands
+- [ai-agents.md](ai-agents.md) — supported AI agents

package/guide/en/consistency.md

@@ -0,0 +1,58 @@
+# Consistency — the release gate inside `roll release`
+
+Seven dimensions are continuously reconciled against truth anchors. A backlog
+`✅ Done` row is a claim; merge evidence on `main`, acceptance reports, terminal
+cycle events, and release-gate events are the facts. The dimensions are:
+① code ↔ backlog claims · ② cards (every live backlog row owns
+`features/<epic>/<ID>/spec.md`; evidence links never dangle; card-era delivered
+stories with ACs own a `latest/<ID>-report.html`; pre-card-era Done rows are
+counted, not failed) · ③ docs (changelog / features / guide / README / --help)
+· ④ tests · ⑤ locale parity (guide en↔zh + i18n keys) · ⑥ site ·
+⑦ truth-live (`ensureDeliveriesFresh` + `queryStoryDelivery` must prove each
+release-delta story is actually delivered, with PR refs matching the Done row
+when present).
+
+```bash
+roll release              # the ONE release flow — the gate runs inside it
+roll release --dry-run    # preview the plan; nothing mutates
+roll release --gate-check # machine entry (CI uses it); exit 0 = all pass
+```
+
+## The release gate
+
+`roll release` runs the **consistency gate twice in the same place: before
+anything irreversible.** Locally, the gate runs on the release branch — after
+the version bump and changelog fold are committed, but **before** the PR is
+opened or merged. A failing dimension aborts the release while it is still just
+a local branch: the bump+changelog never reach `main`, so there is no
+merged-but-untagged half-product. Remotely, every `v*` tag re-runs the same gate
+in `release.yml` before the GitHub Release is created. Shipping with a known
+drift requires fixing the drift — not skipping the gate.
+
+`main` stays PR-protected, so the release opens a PR even for itself. It then
+drives the merge through GitHub-native **auto-merge** (`gh pr merge --auto
+--squash`) rather than waiting on a background lane: the merge completes when CI
+goes green, even if you close the terminal. While it waits, the release prints a
+progress line per poll and nudges CI (an empty commit) if a fresh PR's checks
+never schedule. This needs **"Allow auto-merge"** enabled on the repo (Settings
+→ General → Pull Requests); without it the release stops with an honest error
+asking you to enable the setting or merge the PR manually — never a silent hang.
+
+The acceptance-evidence gate is `hard` by default. `loop_safety.attest_gate: soft`
+is an explicit project policy for migration windows; consistency still reports
+missing or dangling evidence so the gap cannot disappear silently.
+
+The truth-live dimension is the anti-false-Done guard. It first rebuilds the
+delivery projection from `runs.jsonl` plus first-parent `main` merge commits,
+then calls `queryStoryDelivery()` for every story id found in the release delta.
+Backlog markdown is only the human claim; `deliveries.jsonl` is a rebuildable
+cache; git merges and run events are the facts.
+
+## Doc alignment boundary
+
+Registry drift is already a hard red line: if the command registry, README,
+guide, or `--help` disagree, the FIX-242 guard fails consistency and release.
+The `doc-gap` signal in `roll attest` is shadow-only. It warns when a delivery
+diff changes user-visible command or output-copy files without a README/docs/guide/site
+touch in the same diff, but it does not change the report exit code or Gate
+verdict yet.

package/guide/en/conventions.md

@@ -0,0 +1,113 @@
+# Roll — Conventions & AGENTS.md
+
+Roll's convention system gives every AI agent the same shared understanding of
+your project — its domain, coding standards, and navigation pointers.
+
+## AGENTS.md
+
+`AGENTS.md` is the primary convention file. It defines:
+
+- **Domain model**: bounded contexts, aggregates, key entities
+- **Coding standards**: language idioms, naming, forbidden patterns
+- **Scope rules**: which files an agent is allowed to touch
+- **Where to Look**: named pointers to key docs and directories
+- **Goal-Driven Execution**: instructions for agents to define verifiable goals before acting
+
+Roll writes an `AGENTS.md` skeleton during `roll init`. You fill in the domain
+model and standards that are specific to your project.
+
+## Goal-Driven Execution Rule
+
+Every agent must define a verifiable goal before starting work:
+
+```
+Verifiable Goal: <one sentence that can be confirmed true or false>
+Success Criteria: <measurable outcomes>
+```
+
+This prevents vague execution ("refactor the auth module") and forces the agent
+to state what "done" looks like. Roll's skills enforce this at the start of each
+story.
+
+## Where to Look
+
+The `AGENTS.md` navigation section maps concept names to file paths. Roll 2.0
+consolidates everything Roll touches under `.roll/`, so navigation is anchored
+there:
+
+```markdown
+## Where to Look
+
+| Concept | Location |
+|---------|----------|
+| Backlog index | `.roll/backlog.md` |
+| Feature specs | `.roll/features/<name>.md` |
+| Domain model | `.roll/domain/context-map.md` |
+| Architecture decisions | `.roll/decisions/` |
+| Autonomous output (briefs, dream) | `.roll/briefs/`, `.roll/dream/` |
+| User guides | `guide/en/`, `guide/zh/` |
+| Test helpers | `tests/unit/helpers.bash` |
+```
+
+The contract: `AGENTS.md` lives at the project root (every AI client reads it
+first); everything it points into lives under `.roll/`. The root stays clean,
+and the navigation table is the single map agents need.
+
+`$roll-design` maintains this table as new docs and directories are added.
+Any agent entering the project can navigate to authoritative sources without
+scanning the whole tree.
+
+## Language Surface Policy
+
+Roll separates the contract language from rendered user language:
+
+- Agent contracts, TypeScript code, git metadata, schemas, and stable keys stay
+  in English.
+- Owner conversation follows the owner's language in the current task.
+- CLI output, help, docs, and HTML pages render one visible language at a time,
+  selected by `ROLL_LANG`, `roll config lang`, `roll help --lang`, or locale
+  detection.
+
+Write user documentation in the matching locale file under `guide/en/` or
+`guide/zh/`. For CLI and generated HTML, add or update i18n catalog entries
+instead of putting translation pairs into one output string. Run
+`roll doctor language` before release when conventions, help, docs, or generated
+surfaces changed. The policy is covered by
+`packages/cli/test/cli-language-surface.test.ts`,
+`packages/cli/test/__snapshots__/cli-language-surface.test.ts.snap`, and
+`packages/cli/test/doctor-language.test.ts`.
+
+## Existing Codebases: `$roll-onboard` and `$roll-doc-audit`
+
+For an existing codebase with no `.roll/` yet, the entry point is
+`$roll-onboard` (the **graft** adoption pattern). It scans the code, asks a
+focused set of cognition / scope / privacy questions, and writes
+`.roll/onboard-plan.yaml` as a reviewable contract. After review,
+`roll init --apply` prints the planned operation checkpoint and waits for
+confirmation before turning that plan into the on-disk structure; non-interactive
+automation must use `roll init --apply --auto` — see
+[legacy-onboarding.md](legacy-onboarding.md) and
+[patterns/](patterns/README.md).
+
+For projects that already have `AGENTS.md` but scattered or stale docs:
+
+```bash
+$roll-doc-audit
+```
+
+`roll-doc-audit` checks README, guides, site pages, CLI help, and docs against
+implemented behavior. When inventory is requested, it infers domain structure
+from existing code, refreshes the `Where to Look` navigation table, and flags
+documentation gaps (missing architecture docs, undocumented public APIs) for
+`$roll-build` to fill.
+
+## Global Conventions
+
+Files in `~/.roll/conventions/global/` are synced into every AI tool's config
+directory by `roll setup` and `roll sync`. Changes to global conventions
+propagate to all projects on your next sync.
+
+## See Also
+
+- [project-setup.md](project-setup.md) — `roll init` creates AGENTS.md
+- [overview.md](overview.md) — three-layer model (human / BACKLOG / autonomous)

package/guide/en/dream.md

@@ -0,0 +1,121 @@
+# roll-.dream — Nightly Code Health Scanner
+
+`roll-.dream` is a nightly skill that scans the codebase for architectural friction,
+dead code, and technical debt. It runs automatically at 3am (via launchd, installed by
+`roll loop on`) and deposits `REFACTOR-NNN` entries into `BACKLOG.md` for loop to execute.
+
+The schedule fires a self-contained v3 runner whose heart is `roll dream run-once`
+(the TS command that resolves the `roll-.dream` skill and spawns the agent in place) —
+the same shape as the loop runner, with no bash-engine dependency.
+
+## What Dream Does
+
+Dream runs one full scan per night and produces these outputs:
+
+1. **`.roll/dream/YYYY-MM-DD.md`** — detailed report in Chinese (one file per night)
+2. **BACKLOG.md entries** — actionable `REFACTOR-NNN` items appended to the `## ♻️ Refactor` table
+3. **`.roll/dream/structure-scan.json`** — deterministic TypeScript/AST evidence for code-structure findings
+
+The report covers:
+
+- Dead code and unused functions, seeded by TypeScript Language Service references
+- Duplicated logic across modules, seeded by normalized AST fingerprints
+- Module boundary violations (one concern leaking into another)
+- Missing tests for shipped behavior
+- Documentation coverage gaps (missing EN/ZH guides, stale references)
+
+Code-structure findings now come from the deterministic pre-scan first: dead exports,
+unreachable branches, duplicate AST shapes, single-implementation abstractions, and
+undocumented env variables are written to `structure-scan.json` before the agent runs.
+The agent consumes that artifact instead of re-running grep-style heuristics. Document
+coverage, freshness, and existence-drift checks stay in the existing Dream flow.
+
+## How to Read Dream Logs
+
+```bash
+# See last 3 nights
+ls -lt .roll/dream/ | head -4
+
+# Read latest report
+cat .roll/dream/$(ls -1t .roll/dream/ | head -1)
+```
+
+Each report section ends with a priority classification:
+
+- **P0** — blocks other work, should be addressed this sprint
+- **P1** — significant friction, address within 2 weeks
+- **P2** — low severity, address when convenient
+
+## REFACTOR Item Generation
+
+When dream finds a concrete, actionable issue it appends a row to BACKLOG.md:
+
+```markdown
+| REFACTOR-005 | Extract _for_each_ai_tool() — 4 duplicate iteration loops | 📋 Todo |
+```
+
+Loop picks these up at normal priority (after FIX-XXX, alongside US-XXX).
+
+Dream does **not** generate REFACTOR entries for:
+- Issues that would take >1 day to fix (escalates as IDEA instead)
+- Purely stylistic preferences
+- Issues already in BACKLOG as US or FIX items
+
+## Schedule Configuration
+
+Dream runs at 3am by default. The recommended way to change the time is the
+`roll config dream-time` facade — it writes both keys at once, no hand-editing yaml:
+推荐用 `roll config dream-time` 改时间 —— 一条命令同时写两个 key，免手工编辑 yaml：
+
+```bash
+roll config dream-time 03:20   # sets loop_dream_hour + loop_dream_minute
+```
+
+`roll config` writes to the project's `.roll/local.yaml` by default (`--project`);
+pass `--global` to write `~/.roll/config.yaml` instead:
+`roll config` 默认写项目的 `.roll/local.yaml`（`--project`）；加 `--global` 改写 `~/.roll/config.yaml`：
+
+```bash
+roll config loop_dream_hour 3            # set a single key, project scope
+roll config loop_dream_hour 3 --global   # set a single key, global scope
+roll config loop_dream_hour              # print current value + source
+roll config --list                       # list all loop/dream/brief schedule keys
+```
+
+The underlying keys (resolved here as `.roll/local.yaml`):
+底层 key（这里以 `.roll/local.yaml` 为例）：
+
+```yaml
+loop_dream_hour: 3     # 0-23, default 3
+loop_dream_minute: 12  # 0-59, omit to auto-derive
+```
+
+Changing the time writes config only; apply the new schedule by re-running
+`roll loop on` (a config write no longer remounts launchd — US-PORT-006).
+`roll loop on` installs the dream plist alongside the loop and pr plists.
+改完时间只写配置；用 `roll loop on` 重挂应用新调度（config 写入不再自动重挂
+launchd —— US-PORT-006）。`roll loop on` 会把 dream plist 和 loop、pr plist 一起安装。
+All three services are managed together:
+
+```bash
+roll loop on       # install loop + pr + dream
+roll loop off      # boot out loop + pr + dream
+roll loop status   # shows all three service states
+```
+
+## Manual Run
+
+To run a dream scan immediately (without waiting for the scheduled 3am run):
+
+```bash
+# v3-native — same heart the nightly runner uses
+roll dream run-once
+
+# Or drive the skill via Claude Code directly
+$roll-.dream
+```
+
+Dream always writes to today's date file and always appends to BACKLOG.md —
+running it twice in one day appends a second pass (safe but redundant).
+Each run also refreshes `.roll/dream/structure-scan.json`; inspect that file when you
+need machine-readable evidence behind code-structure REFACTOR rows.