@seanyao/roll 0.5.0 → 2.602.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sean YAO
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -7,195 +7,95 @@
  ╚═╝  ╚═╝ ╚═════╝ ╚══════╝╚══════╝
 ```
 
-> Roll out features with AI agents — _Move fast, no sprints._
+**[中文版 README](README_CN.md)**
 
+[![Website](https://img.shields.io/badge/Website-seanyao.github.io%2Froll-blue)](https://seanyao.github.io/roll/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
-[![npm version](https://img.shields.io/npm/v/roll.svg)](https://www.npmjs.com/package/roll)
+[![npm version](https://img.shields.io/npm/v/@seanyao/roll.svg)](https://www.npmjs.com/package/@seanyao/roll)
+[![CI](https://github.com/seanyao/roll/actions/workflows/ci.yml/badge.svg)](https://github.com/seanyao/roll/actions/workflows/ci.yml)
 
----
+Roll — a CLI that lets AI agents pick up backlog items and ship them through your normal git + CI workflow. Works with Claude, Cursor, Codex, Kimi, and others.
 
-## What is Roll?
+## Install
 
-Roll solves a specific problem: when developers on the same team use different AI clients (Claude Code, Cursor, Gemini CLI, Codex), each agent operates under different engineering constraints. One developer's Claude runs tests another's Cursor never even considers.
-
-Roll fixes this through two mechanisms:
-
-1. **Convention CLI** — a single source of engineering conventions distributed to every AI client on the machine (`~/.claude/`, `~/.cursor/`, `~/.gemini/`, etc.)
-2. **Skill System** — proven engineering practices (TDD, TCR, SRE, INVEST) encoded as instructions that any AI agent can follow
-
-The result: any agent, any client, same constraints.
-
----
-
-## Start Here
-
-Before commands and skills, read the Engineering Methodology — it explains the three-loop architecture (Research → Build → Observe), why each skill exists, and how they connect into a complete delivery system.
-
-**[English](docs/methodology-en.md)** · **[中文](docs/methodology.md)**
-
----
-
-## Installation
+```bash
+curl -fsSL https://seanyao.github.io/roll/install | bash
+```
 
 ```bash
 npm install -g @seanyao/roll
-roll setup
 ```
 
-**Requirements:** bash 4+, Node.js 16+
+Requirements: bash 3.2+. npm/Node.js not required — curl install is self-contained.
 
-To update:
+## Use
 
 ```bash
-roll update
+cd your-project
+roll init           # set up Roll here
+roll loop on        # let AI work through the backlog (optional)
 ```
 
-> **For contributors** (working on roll itself): `git clone https://github.com/seanyao/roll.git && cd roll && ./install.sh`
-
----
+`roll init` detects legacy code and routes you to `$roll-onboard` when appropriate.
 
-## Convention Management
-
-Unified behavioral conventions for Claude Code / Gemini CLI / Cursor / Codex — all from one source.
-
-### Commands
+## Commands
 
 | Command | Description |
 |---------|-------------|
-| `roll setup` | First-time install: create `~/.roll/` + sync to all AI tools |
-| `roll update` | Update roll to latest version + re-sync |
-| `roll sync` | Re-sync conventions and skill symlinks to all AI tools |
-| `roll init` | New project: create `AGENTS.md` + `BACKLOG.md` + `docs/features/` |
-| `roll hook install` | Optional: global git hook for AI client auto-detection |
-| `roll reset` | Force-rebuild local cache from repo source, then re-sync |
-| `roll status` | Show sync state, skill links, and detected AI tools |
-| `roll clean` | Remove legacy `~/.wukong/` or `~/.cybernetix/` remnants |
-
-### Typical Flow
-
-```bash
-# 1. Install
-./install.sh
-
-# 2. Initialize a project (run from project root)
-cd my-app
-roll init
-
-# 3. Re-sync after editing ~/.roll/config.yaml
-roll sync
-
-# 4. Optional: tag commits with AI client name
-roll hook install
-```
-
-### How Convention Layering Works
-
-```
-Global  ~/.claude/CLAUDE.md         ← user-owned; roll setup appends @roll.md
-        ~/.claude/roll.md            ← Roll conventions (written by roll setup/sync)
-  ↓  auto-stacked
-Project <project>/AGENTS.md         ← generated by roll init
-        <project>/.claude/CLAUDE.md
-```
-
-Global conventions are additive and never overwrite existing files. Project conventions are injected per project via `roll init`.
-
-### Directory Layout
-
-```
-~/.roll/
-├── config.yaml                  # sync path configuration
-└── conventions/
-    ├── global/                  # single source of truth
-    │   ├── AGENTS.md
-    │   ├── CLAUDE.md / GEMINI.md / .cursor-rules
-    └── templates/               # project type templates
-        ├── fullstack/
-        ├── frontend-only/
-        ├── backend-service/
-        └── cli/
-```
-
----
-
-## Skill System
-
-Skills are instructions that encode proven engineering practices into a form AI agents can reliably follow. They live in `~/.roll/skills/` and are symlinked into each AI client's skill directory on `roll sync`.
-
-### Workflow
-
-```
-Research → Design → Build → Check → Fix → (loop)
-```
-
-### Quick Reference
-
-| Scenario | Skill |
-|----------|-------|
-| Uncertain approach, need to think it through | `$roll-design "topic"` |
-| Execute a planned Story | `$roll-build US-001` |
-| Free-form feature request | `$roll-build "add search to admin"` |
-| Bug fix | `$roll-fix FIX-001` |
-| Fast backlog capture (bug / idea) | `$roll-jot "description"` |
-| High-risk logic (payments, auth, state machines) | `$roll-spar "feature"` |
-| Deep research (product / company / tech) | `$roll-research "subject"` |
-| Patrol production for regressions | `$roll-sentinel patrol` |
-| Debug a broken page | `$roll-debug <URL>` |
-
-### Full Skill List
-
-| Skill | Phase | Description |
-|-------|-------|-------------|
-| `$roll-build` | DESIGN+BUILD | Universal entry: Story ID, fix ID, or free-text fly mode |
-| `$roll-design` | DESIGN | Explore approaches → design solution → write Stories to BACKLOG |
-| `$roll-fix` | FIX | Bug fix / hotfix from BACKLOG |
-| `$roll-jot` | Support | Fast capture a bug or idea into BACKLOG.md |
-| `$roll-spar` | BUILD | Adversarial TDD — Attacker writes tests, Defender writes code |
-| `$roll-sentinel` | CHECK | Scheduled production patrol |
-| `$roll-debug` | CHECK | Deep page diagnostics + root cause analysis |
-| `$roll-research` | RESEARCH | HV Analysis framework, outputs PDF report |
-| `$roll-.review` | Support | Pre-commit self code review |
-| `$roll-.qa` | Support | Test pyramid and coverage standards reference |
-| `$roll-.changelog` | Support | Auto-generate CHANGELOG from BACKLOG |
-| `$roll-.echo` | Support | Passive intent clarification |
-| `$roll-.clarify` | Support | Passive scope clarification for vague build requests |
-
----
-
-## Project Structure (`roll init`)
-
-```
-my-project/
-├── AGENTS.md            # Project constraints & skill routing
-├── BACKLOG.md           # Story and bug index
-├── docs/features/       # Story details and specs
-└── ... your project files
-```
-
----
+| **Autonomy · daily use** | |
+| `roll loop <on\|off\|now\|status\|eval\|signals\|runs\|story\|monitor\|…>` | Manage the autonomous BACKLOG executor (incl. per-cycle result scoring) |
+| `roll brief` | Show latest owner brief |
+| `roll backlog [sync\|block\|defer\|lint\|…]` | View, manage, and sync (from GitHub Issues) pending tasks |
+| `roll peer` | Cross-agent negotiation & review |
+| `roll alert` | View / clear loop alerts |
+| **Project · per repo** | |
+| `roll init` | Set up Roll in this project |
+| `roll status` | Show current state and drift |
+| `roll agent [use <name>]` | Per-project agent selection |
+| `roll ci [--wait]` | Show or wait for current commit's CI status |
+| `roll test [--where] [--reset]` | Run the test suite (routes through isolation adapter; Tart VM on Apple Silicon) |
+| `roll release` | Run the release script (human-only) |
+| `roll review-pr <number>` | AI-powered code review for a PR |
+| **Machine · global** | |
+| `roll setup [-f]` | First-time install or re-sync conventions to all AI clients |
+| `roll update` | Upgrade to latest + re-sync |
+| `roll version` | Print installed roll version |
+
+## Documentation
+
+| Topic | English | 中文 |
+|-------|---------|------|
+| Overview & architecture | [guide/en/overview.md](guide/en/overview.md) | [guide/zh/overview.md](guide/zh/overview.md) |
+| Engineering methodology | [guide/en/methodology.md](guide/en/methodology.md) | [guide/zh/methodology.md](guide/zh/methodology.md) |
+| Loop (autonomous executor) | [guide/en/loop.md](guide/en/loop.md) | [guide/zh/loop.md](guide/zh/loop.md) |
+| Loop data layout (Phase 2.0) | [guide/en/loop-data-layout.md](guide/en/loop-data-layout.md) | [guide/zh/loop-data-layout.md](guide/zh/loop-data-layout.md) |
+| Dream (nightly health scan) | [guide/en/dream.md](guide/en/dream.md) | [guide/zh/dream.md](guide/zh/dream.md) |
+| Peer (cross-agent review) | [guide/en/peer.md](guide/en/peer.md) | [guide/zh/peer.md](guide/zh/peer.md) |
+| AI agents & complexity routing | [guide/en/ai-agents.md](guide/en/ai-agents.md) | [guide/zh/ai-agents.md](guide/zh/ai-agents.md) |
+| Configuration (env vars) | [guide/en/configuration.md](guide/en/configuration.md) | [guide/zh/configuration.md](guide/zh/configuration.md) |
+| Skill selection guide | [guide/en/skills.md](guide/en/skills.md) | [guide/zh/skills.md](guide/zh/skills.md) |
+| roll-doc (legacy doc automation: four phases + Phase 3b deep read) | [guide/en/roll-doc.md](guide/en/roll-doc.md) | [guide/zh/roll-doc.md](guide/zh/roll-doc.md) |
+| Slides (deck generator) | [guide/en/slides.md](guide/en/slides.md) | [guide/zh/slides.md](guide/zh/slides.md) |
+| Slides — Layouts reference | [guide/en/slides.md#layouts](guide/en/slides.md#layouts) | [guide/zh/slides.md#layouts布局](guide/zh/slides.md#layouts%E5%B8%83%E5%B1%80) |
+| Feedback (`roll feedback`) | [guide/en/feedback.md](guide/en/feedback.md) | [guide/zh/feedback.md](guide/zh/feedback.md) |
+| Backlog GitHub sync (`roll backlog sync`) | [guide/en/backlog-github-sync.md](guide/en/backlog-github-sync.md) | [guide/zh/backlog-github-sync.md](guide/zh/backlog-github-sync.md) |
+| Test isolation (`roll test` + Tart VM) | [guide/en/test-isolation.md](guide/en/test-isolation.md) | [guide/zh/test-isolation.md](guide/zh/test-isolation.md) |
+| Cross-machine sync | [guide/en/loop.md#cross-machine-sync](guide/en/loop.md#cross-machine-sync) | [guide/zh/loop.md#跨机器同步](guide/zh/loop.md#%E8%B7%A8%E6%9C%BA%E5%99%A8%E5%90%8C%E6%AD%A5) |
+| Remote monitoring (watch loop from a phone via `remote-watch`) | [guide/en/loop.md#remote-monitoring](guide/en/loop.md#remote-monitoring) | [guide/zh/loop.md#远程监控remote-monitoring](guide/zh/loop.md#%E8%BF%9C%E7%A8%8B%E7%9B%91%E6%8E%A7remote-monitoring) |
+| Cycle result eval (`roll loop eval`) | [guide/en/loop.md#cycle-result-eval](guide/en/loop.md#cycle-result-eval) | [guide/zh/loop.md#cycle-结果评分result-eval](guide/zh/loop.md#cycle-%E7%BB%93%E6%9E%9C%E8%AF%84%E5%88%86result-eval) |
+| Cycle exit summary (`.command` window recap) | [guide/en/loop.md#cycle-exit-summary](guide/en/loop.md#cycle-exit-summary) | [guide/zh/loop.md#cycle-退出摘要cycle-exit-summary](guide/zh/loop.md#cycle-%E9%80%80%E5%87%BA%E6%91%98%E8%A6%81cycle-exit-summary) |
+| Pricing (cost visibility) | [guide/en/pricing.md](guide/en/pricing.md) | [guide/zh/pricing.md](guide/zh/pricing.md) |
+| FAQ (troubleshooting) | [guide/en/faq.md](guide/en/faq.md) | [guide/zh/faq.md](guide/zh/faq.md) |
+| Adoption patterns | [guide/en/patterns/](guide/en/patterns/) | [guide/zh/patterns/](guide/zh/patterns/) |
 
 ## Contributing
 
-Contributions are welcome. Roll is a small focused tool — keep PRs focused on one thing.
-
-1. Fork the repo and create a branch from `main`
-2. Make your changes with tests where applicable (`tests/`)
-3. Ensure `./bin/roll --help` output is correct
-4. Open a pull request with a clear description
-
-For larger changes, open an issue first to discuss the approach.
-
----
-
-## Acknowledgments
-
-Roll builds on ideas and inspiration from the open-source community:
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the development workflow, test setup, and PR conventions.
 
-- **[khazix-skills](https://github.com/KKKKhazix/khazix-skills)** by Digital Life Khazix — The HV Analysis (Horizontal-Vertical Analysis) deep research framework that powers `$roll-research` was adapted from this project.
-- **[superpowers](https://github.com/obra/superpowers)** by Jesse Vincent — A composable skills library for AI coding agents that informed several workflow patterns in Roll.
+## Security
 
----
+See [SECURITY.md](SECURITY.md). Please report vulnerabilities privately, not through public issues.
 
 ## License
 
-MIT
+[MIT](LICENSE)

package/bin/dream-test-quality-scan

@@ -0,0 +1,110 @@
+#!/usr/bin/env bash
+# dream-test-quality-scan — ad-hoc helper for roll-.dream Scan 7.
+#
+# Walks bats files and flags ❶-class anti-patterns (hardcoded business data
+# in assertion bodies). Emits structured REFACTOR-shaped lines so the
+# maintainer can sanity-check the rubric against the current suite without
+# waiting for the nightly dream cycle.
+#
+# Usage:
+#   dream-test-quality-scan [--category N] [--path PATH] [--max N]
+#   dream-test-quality-scan --help
+#
+# Only category 1 (❶ hardcoded business data) is implemented as a deterministic
+# heuristic; categories ❷..❻ stay with the dream skill (AI agent applies the
+# rubric). The helper exists so a smoke test and a maintainer dry-run can
+# confirm ❶ detection keeps working as the suite evolves.
+
+set -euo pipefail
+
+CATEGORY=1
+TARGET=""
+MAX=5
+
+usage() {
+  cat <<'EOF'
+dream-test-quality-scan — Scan 7 ❶ dry-run helper
+
+Usage:
+  dream-test-quality-scan [--category N] [--path PATH] [--max N]
+  dream-test-quality-scan --help
+
+Options:
+  --category N   Anti-pattern category (only 1 is implemented; default 1)
+  --path PATH    File or directory to scan (default: tests/)
+  --max N        Maximum entries to emit (default: 5; matches dream skill cap)
+  --help         Show this message
+
+Output:
+  One line per finding:
+    [test-quality:❶] <file>:<line> — <one-line description>
+  Exit code is 0 even when nothing is found (dry-run is informational).
+EOF
+}
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --category) CATEGORY="${2:-1}"; shift 2 ;;
+    --path)     TARGET="${2:-}"; shift 2 ;;
+    --max)      MAX="${2:-5}"; shift 2 ;;
+    --help|-h)  usage; exit 0 ;;
+    *)          echo "unknown flag: $1" >&2; usage >&2; exit 2 ;;
+  esac
+done
+
+if [[ "$CATEGORY" -ne 1 ]]; then
+  echo "category $CATEGORY not yet implemented — only ❶ is mechanical" >&2
+  exit 0
+fi
+
+# Default scan root.
+if [[ -z "$TARGET" ]]; then
+  repo_root=$(git rev-parse --show-toplevel 2>/dev/null || pwd)
+  TARGET="${repo_root}/tests"
+fi
+
+if [[ ! -e "$TARGET" ]]; then
+  echo "path not found: $TARGET" >&2
+  exit 2
+fi
+
+scan_file() {
+  local file="$1"
+  # ❶ heuristic — assertion lines whose RHS contains a numeric literal:
+  #   - lines containing `[[` or `[ ` (bats assertion syntax)
+  #   - AND containing `==` or `=` (equality)
+  #   - AND containing a decimal/integer literal of length ≥ 1 inside quotes
+  # Emits one entry per file (not per line) to stay under the rate cap.
+  local first_hit
+  first_hit=$(grep -nE '\[\[.*"[^"]*[0-9]+(\.[0-9]+)?[^"]*"' "$file" 2>/dev/null \
+              | head -1 || true)
+  [[ -z "$first_hit" ]] && return 1
+
+  local lineno
+  lineno=$(echo "$first_hit" | cut -d: -f1)
+  local rel
+  rel=$(python3 -c "import os,sys; print(os.path.relpath(sys.argv[1]))" "$file" 2>/dev/null || echo "$file")
+  printf '[test-quality:❶] %s:%s — assertion body hardcodes a numeric literal that likely owns its value elsewhere\n' \
+    "$rel" "$lineno"
+  return 0
+}
+
+emitted=0
+if [[ -d "$TARGET" ]]; then
+  # Iterate over .bats files under TARGET; stop after MAX hits.
+  # Exclude vendored bats-core helpers — those are framework tests, not ours.
+  while IFS= read -r f; do
+    case "$f" in
+      */tests/helpers/bats-*/*) continue ;;
+    esac
+    if scan_file "$f"; then
+      emitted=$((emitted + 1))
+      [[ "$emitted" -ge "$MAX" ]] && break
+    fi
+  done < <(find "$TARGET" -type f -name '*.bats' | sort)
+else
+  scan_file "$TARGET" && emitted=1 || true
+fi
+
+# Always succeed — dry-run is informational, the dream cycle decides what to do.
+exit 0