@seanyao/roll 2026.520.1 → 2026.521.1

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## v2026.521.1
+
+### Added
+
+- **dashboard cycle 行现在标出模型和按公开单价算的成本** — 跨账号 / 跨项目可以横向对比和加总，不再被订阅折扣藏掉真实开销 `[loop]`
+
+### Improved
+
+- **`roll setup` 重跑能看出"已是最新"还是"刷新了 X 项"** — 每步上报 changed / unchanged / failed，强制覆盖用 `~` 标出 `[loop]`
+- **`roll-peer` 评审第一轮要先独立判断** — 不再被评审方预设结论带跑，跨 agent 才真的是二次判断 `[loop]`
+
+### Fixed
+
+- **`roll init` 默认不再打"Project ready"假提示** — 老项目进引导分支时不再骗你说已就绪 `[legacy-onboard]`
+
 ## v2026.520.1
 
 ### Added

package/bin/roll

@@ -4,7 +4,7 @@ set -euo pipefail
 # Roll — AI Agent Convention Manager
 # Single source of truth for how all AI coding agents behave.
 
-VERSION="2026.520.1"
+VERSION="2026.521.1"
 ROLL_HOME="${ROLL_HOME:-${HOME}/.roll}"
 ROLL_CONFIG="${ROLL_HOME}/config.yaml"
 ROLL_GLOBAL="${ROLL_HOME}/conventions/global"
@@ -572,53 +572,154 @@ _ensure_tmux() {
   return 0
 }
 
+# FIX-075: snapshot the content of watched directories so cmd_setup can detect
+# whether a step actually changed any file. Uses `cksum` (mtime-independent) so
+# a re-copy with identical content is recognised as a no-op even when the inner
+# helper rewrites the file. Watch is a colon-separated list of directories;
+# missing dirs are skipped silently.
+_setup_snapshot() {
+  local watch="$1"
+  local -a dirs
+  IFS=':' read -r -a dirs <<<"$watch"
+  local d
+  {
+    for d in "${dirs[@]}"; do
+      [[ -d "$d" ]] || continue
+      find "$d" -type f -print0 2>/dev/null | xargs -0 cksum 2>/dev/null
+    done
+  } | sort
+}
+
+# FIX-075: run a setup step and report changed/unchanged/failed via the global
+# _ROLL_SETUP_STATE. Caller passes the watch dir(s) plus the command + args.
+# stdout/stderr of the inner command are suppressed (same as the previous
+# pattern in cmd_setup) to keep the v2 UI render the only user-visible output.
+_run_setup_step() {
+  local watch="$1"; shift
+  local before after
+  before=$(_setup_snapshot "$watch")
+  if "$@" >/dev/null 2>&1; then
+    after=$(_setup_snapshot "$watch")
+    if [[ "$before" == "$after" ]]; then
+      _ROLL_SETUP_STATE="unchanged"
+    else
+      _ROLL_SETUP_STATE="changed"
+    fi
+  else
+    _ROLL_SETUP_STATE="failed"
+  fi
+}
+
 cmd_setup() {
   local force=false
-  local demo=false
   while [[ $# -gt 0 ]]; do
     case "$1" in
       --force|-f) force=true; shift ;;
-      --demo)     demo=true;  shift ;;
       *) err "Unknown argument: $1  未知参数: $1"; exit 1 ;;
     esac
   done
 
-  if [[ "${ROLL_UI:-v2}" == "v2" ]] || [[ "$demo" == "true" ]]; then
-    python3 "${ROLL_PKG_DIR}/lib/roll-setup.py" --demo
-    if [[ "$demo" == "true" ]]; then return; fi
-  fi
+  # Capture per-step outcomes for the v2 UI render at the end.
+  local steps_buf=()
+  _record() { steps_buf+=("$1|$2"); }
+
+  # Map snapshot-detected state to v2 UI marker. -f rewrites "changed" to
+  # "forced" so the user can tell a forced reinstall apart from a fresh
+  # install — both produce diff'd files, only -f was explicitly requested.
+  _state_to_marker() {
+    local s="$1"
+    case "$s" in
+      changed)   [[ "$force" == "true" ]] && echo forced || echo ok ;;
+      unchanged) echo skip ;;
+      failed)    echo fail ;;
+      *)         echo fail ;;
+    esac
+  }
 
-  info "Setting up Roll on this machine...  正在初始化 Roll..."
-  echo ""
+  local _ai_dirs="$HOME/.claude:$HOME/.gemini:$HOME/.kimi:$HOME/.codex:$HOME/.cursor:$HOME/.trae:$HOME/.config/opencode:$HOME/.openclaw:$HOME/.pi:$HOME/.deepseek"
 
-  _install_local "$force"
-  echo ""
-  info "Syncing to AI tools...  正在同步到 AI 工具..."
-  _sync_conventions "$force"
-  echo ""
-  _sync_skills "$force"
+  _run_setup_step "$ROLL_HOME" _install_local "$force"
+  _record "$(_state_to_marker "$_ROLL_SETUP_STATE")" "Install templates & conventions to ~/.roll"
 
-  echo ""
-  info "Setting up peer review state...  正在初始化 peer review 状态..."
-  _peer_ensure_state_dir
-  ok "Peer state directory ready.  Peer 状态目录已就绪。"
+  _run_setup_step "$_ai_dirs" _sync_conventions "$force"
+  _record "$(_state_to_marker "$_ROLL_SETUP_STATE")" "Sync conventions to AI tools"
 
-  echo ""
-  info "Ensuring tmux is installed (required for visible loop runs)...  正在确认 tmux 已安装..."
-  _ensure_tmux
+  _run_setup_step "$_ai_dirs" _sync_skills "$force"
+  _record "$(_state_to_marker "$_ROLL_SETUP_STATE")" "Install skills to ~/.claude"
+
+  _run_setup_step "$ROLL_HOME/.peer-state" _peer_ensure_state_dir
+  _record "$(_state_to_marker "$_ROLL_SETUP_STATE")" "Initialize peer-review state directory"
+
+  if command -v tmux >/dev/null 2>&1; then
+    _record skip "Ensure tmux is installed (already present)"
+  else
+    if _ensure_tmux >/dev/null 2>&1 && command -v tmux >/dev/null 2>&1; then
+      _record ok "Ensure tmux is installed"
+    else
+      _record fail "Ensure tmux is installed"
+    fi
+  fi
 
   if [[ "$(uname)" == "Darwin" ]]; then
-    echo ""
-    info "Installing launchd plists...  正在安装 LaunchAgents..."
-    _install_launchd_plists "$(pwd -P)"
+    _run_setup_step "$HOME/Library/LaunchAgents" _install_launchd_plists "$(pwd -P)"
+    _record "$(_state_to_marker "$_ROLL_SETUP_STATE")" "Install launchd plists (macOS)"
   fi
 
-  echo ""
-  ok "Setup complete.  初始化完成。"
+  _emit_setup_v2_ui "${steps_buf[@]}"
+}
 
-  echo ""
-  info "Next: run ${BOLD}roll init${NC} inside a project to initialize it.  下一步：在项目目录运行 roll init"
-  info "Optional gates: run ${BOLD}roll doctor${NC} inside a repo to see which PR review extras are still off.  可选闸门：在仓库内运行 roll doctor 查看 PR 评审两档开关状态"
+# FIX-073: Render the cmd_setup v2 UI from per-step outcomes captured above.
+# FIX-075: footer composition depends on how many steps actually changed —
+#   all unchanged → "no changes"; some forced (~) → "re-installed (forced)";
+#   any failed → "Setup incomplete"; otherwise → "X items refreshed".
+_emit_setup_v2_ui() {
+  local color_flag=""
+  if [[ -n "${NO_COLOR:-}" ]] || ! [ -t 1 ]; then
+    color_flag="--no-color"
+  fi
+
+  python3 - "$@" <<'PY' \
+    | python3 "${ROLL_PKG_DIR}/lib/roll-setup.py" $color_flag
+import json, sys
+entries = sys.argv[1:]
+steps = []
+for i, entry in enumerate(entries, start=1):
+    status, _sep, label = entry.partition("|")
+    steps.append({"num": i, "label": label, "status": status})
+
+n_failed   = sum(1 for s in steps if s["status"] == "fail")
+n_forced   = sum(1 for s in steps if s["status"] == "forced")
+n_changed  = sum(1 for s in steps if s["status"] == "ok")
+
+if n_failed:
+    footer_status = "fail"
+    label = "Setup incomplete"
+    hint = None
+elif n_forced:
+    footer_status = "ok"
+    label = f"Setup re-installed (forced — {n_forced} item{'s' if n_forced != 1 else ''})"
+    hint = "run roll init inside a project"
+elif n_changed == 0:
+    footer_status = "ok"
+    label = "Setup complete (no changes)"
+    hint = "everything already up to date"
+else:
+    footer_status = "ok"
+    label = f"Setup complete ({n_changed} item{'s' if n_changed != 1 else ''} refreshed)"
+    hint = "run roll init inside a project"
+
+payload = {
+    "header_label": "SETUP",
+    "subtitle":     "初始化",
+    "steps":        steps,
+    "footer": {
+        "status": footer_status,
+        "label":  label,
+        "hint":   hint,
+    },
+}
+print(json.dumps(payload))
+PY
 }
 
 # ─── PR pipeline hint ────────────────────────────────────────────────────────
@@ -917,21 +1018,20 @@ _merge_claude_to_project() {
 # Existing AGENTS.md: re-merges global conventions (section-level, non-destructive)
 # ═══════════════════════════════════════════════════════════════════════════════
 cmd_init() {
-  # US-VIEW-008: parse --demo before any side effects so the v2 renderer can
-  # run standalone (no templates, no project mutation).
-  local demo=false
-  local args=()
-  while [[ $# -gt 0 ]]; do
-    case "$1" in
-      --demo) demo=true; shift ;;
-      *)      args+=("$1"); shift ;;
-    esac
-  done
-  set -- "${args[@]:-}"
+  # US-ONBOARD-009: --apply consumes onboard-plan.yaml produced by $roll-onboard
+  if [[ "${1:-}" == "--apply" ]]; then
+    if [[ ! -d "$ROLL_TEMPLATES" ]]; then
+      err "No templates found. Run 'roll setup' first.  未找到模板，请先运行 'roll setup'。"
+      exit 1
+    fi
+    shift
+    _init_apply "$@"
+    return $?
+  fi
 
-  if [[ "${ROLL_UI:-v2}" == "v2" ]] || [[ "$demo" == "true" ]]; then
-    python3 "${ROLL_PKG_DIR}/lib/roll-init.py" --demo
-    if [[ "$demo" == "true" ]]; then return; fi
+  if [[ "${1:-}" == -* ]]; then
+    err "Unknown flag: $1  未知参数: $1"
+    exit 1
   fi
 
   if [[ ! -d "$ROLL_TEMPLATES" ]]; then
@@ -939,13 +1039,6 @@ cmd_init() {
     exit 1
   fi
 
-  # US-ONBOARD-009: --apply consumes onboard-plan.yaml produced by $roll-onboard
-  if [[ "${1:-}" == "--apply" ]]; then
-    shift
-    _init_apply "$@"
-    return $?
-  fi
-
   local project_dir
   project_dir="$(pwd)"
   local has_agents=false
@@ -953,7 +1046,6 @@ cmd_init() {
 
   if [[ -f "$project_dir/AGENTS.md" ]]; then
     has_agents=true
-    info "Re-merging global conventions...  正在重新合并全局约定..."
   else
     # US-ONBOARD-006: legacy project detection — guide user through $roll-onboard
     # instead of blindly scaffolding files into an existing codebase.
@@ -963,25 +1055,90 @@ cmd_init() {
     fi
   fi
 
-  _merge_global_to_project "$project_dir"
-  _merge_claude_to_project "$project_dir"
-  _write_backlog "$project_dir/.roll/backlog.md"
-  _ensure_features_dir "$project_dir/.roll/features"
-  _write_features_md "$project_dir/.roll/features.md"
-  print_merge_summary
+  # FIX-073: Suppress per-step echoes — outcomes are captured into
+  # _ROLL_MERGE_SUMMARY and rendered through the v2 UI below.
+  {
+    _merge_global_to_project "$project_dir"
+    _merge_claude_to_project "$project_dir"
+    _write_backlog "$project_dir/.roll/backlog.md"
+    _ensure_features_dir "$project_dir/.roll/features"
+    _write_features_md "$project_dir/.roll/features.md"
+  } >/dev/null
 
-  echo ""
-  info "Syncing conventions to AI tools...  正在同步约定到 AI 工具..."
-  _sync_conventions
-  echo ""
+  local sync_status="ok"
+  if ! _sync_conventions >/dev/null 2>&1; then
+    sync_status="fail"
+  fi
 
-  _install_launchd_plists "$project_dir"
+  _install_launchd_plists "$project_dir" >/dev/null 2>&1 || true
 
+  _emit_init_v2_ui "$project_dir" "$has_agents" "$sync_status"
+}
+
+# FIX-073: Build a real-data JSON payload from _ROLL_MERGE_SUMMARY and pipe it
+# to lib/roll-init.py for v2 UI rendering. Replaces the previous demo-only
+# render path.
+_emit_init_v2_ui() {
+  local project_dir="$1"
+  local has_agents="$2"
+  local sync_status="${3:-ok}"
+
+  local header_label="INIT" subtitle="项目初始化" footer_label="Initialized"
   if [[ "$has_agents" == "true" ]]; then
-    ok "Done.  完成。"
-  else
-    ok "Initialized.  已初始化。"
+    header_label="REINIT"
+    subtitle="重新合并约定"
+    footer_label="Re-merged"
   fi
+
+  local color_flag=""
+  if [[ -n "${NO_COLOR:-}" ]] || ! [ -t 1 ]; then
+    color_flag="--no-color"
+  fi
+
+  python3 - "$project_dir" "$header_label" "$subtitle" "$footer_label" "$sync_status" "${_ROLL_MERGE_SUMMARY[@]}" <<'PY' \
+    | python3 "${ROLL_PKG_DIR}/lib/roll-init.py" $color_flag
+import json, sys
+project_dir, header_label, subtitle, footer_label, sync_status, *summary = sys.argv[1:]
+STATUS = {"created":"ok","merged":"ok","unchanged":"skip","overwritten":"ok","kept":"skip"}
+OP = {"created":"+","merged":"~","unchanged":"·","overwritten":"~","kept":"·"}
+by_file = {}
+for entry in summary:
+    action, _sep, fname = entry.partition("|")
+    if fname:
+        by_file[fname] = action
+
+def step(num, label, fname):
+    act = by_file.get(fname)
+    if not act:
+        return {"num": num, "label": label, "status": "skip",
+                "note": "not modified"}
+    return {"num": num, "label": label, "status": STATUS.get(act, "ok"),
+            "files": [[OP.get(act, "·"), fname]]}
+
+steps = [
+    {"num": 1, "label": "Detect project type", "status": "ok"},
+    step(2, "Create AGENTS.md",           "AGENTS.md"),
+    step(3, "Create .roll/backlog.md",    ".roll/backlog.md"),
+    step(4, "Create .roll/features/",     ".roll/features/"),
+    step(5, "Merge existing CLAUDE.md",   ".claude/CLAUDE.md"),
+    {"num": 6, "label": "Link skills to AI clients", "status": sync_status},
+]
+footer_status = "fail" if any(s["status"] == "fail" for s in steps) else "ok"
+payload = {
+    "header_label": header_label,
+    "subtitle":     subtitle,
+    "project_path": project_dir,
+    "steps":        steps,
+    "footer":       {"status": footer_status,
+                     "label": footer_label if footer_status == "ok" else "Init incomplete"},
+    "next": [
+        ["Edit .roll/backlog.md",   "open the backlog and add your first US"],
+        ["Run roll loop now",       "execute one cycle manually to test the flow"],
+        ["Enable loop scheduling",  "roll loop on  — let it run hourly"],
+    ],
+}
+print(json.dumps(payload))
+PY
 }
 
 # US-ONBOARD-006: Legacy detection
@@ -2219,9 +2376,6 @@ cmd_peer() {
   local context_file=""
   local yolo=false
   local subcmd=""
-  # US-VIEW-009: parse --demo before any side effects so the v2 renderer can
-  # run standalone (no peer state, no tmux session, no agent call).
-  local demo=false
 
   while [[ $# -gt 0 ]]; do
     case "$1" in
@@ -2231,7 +2385,6 @@ cmd_peer() {
       --tag) tag="$2"; shift 2 ;;
       --context) context_file="$2"; shift 2 ;;
       --yes|--yolo) yolo=true; shift ;;
-      --demo) demo=true; shift ;;
       status) subcmd="status"; shift ;;
       reset) subcmd="reset"; shift; break ;;
       help|--help|-h) subcmd="help"; shift ;;
@@ -2239,13 +2392,6 @@ cmd_peer() {
     esac
   done
 
-  # US-VIEW-009: ROLL_UI=v2 (default) + --demo routes to the redesigned Python view.
-  # Set ROLL_UI=v1 to fall back to the legacy bash implementation.
-  if [[ "$demo" == "true" ]] && { [[ "${ROLL_UI:-v2}" == "v2" ]] || [[ "$demo" == "true" ]]; }; then
-    python3 "${ROLL_PKG_DIR}/lib/roll-peer.py" --demo
-    return
-  fi
-
   case "$subcmd" in
     status) cmd_peer_status; return ;;
     reset) cmd_peer_reset "$@"; return ;;

package/lib/loop-fmt.py

@@ -116,10 +116,15 @@ class LoopFmt:
         self.pending_ci      = False
         self.pending_story   = False
         self.spinner         = Spinner()
-        # Track the most recent usage / model seen on assistant turns so
-        # the result event handler can emit a 'usage' event even when
-        # result.usage is missing.
-        self._last_usage     = None
+        # Accumulate token usage across all assistant turns in the cycle so
+        # the trailing result event can emit a 'usage' event carrying the
+        # cumulative totals (result.usage only carries the last turn's).
+        self._usage_totals   = {
+            "input_tokens":          0,
+            "output_tokens":         0,
+            "cache_creation_tokens": 0,
+            "cache_read_tokens":     0,
+        }
         self._last_model     = None
 
     def _extract_cycle_num(self, text):
@@ -161,10 +166,14 @@ class LoopFmt:
 
     def _handle_assistant(self, ev):
         msg = ev.get("message", {})
-        # Remember the latest usage / model so the trailing result event
-        # can emit a 'usage' event even if result.usage is empty.
-        if msg.get("usage"):
-            self._last_usage = msg["usage"]
+        # Sum token usage across turns; result.usage only carries the last
+        # turn so accumulating here is the only way to get cumulative totals.
+        u = msg.get("usage") or {}
+        if u:
+            self._usage_totals["input_tokens"]          += int(u.get("input_tokens") or 0)
+            self._usage_totals["output_tokens"]         += int(u.get("output_tokens") or 0)
+            self._usage_totals["cache_creation_tokens"] += int(u.get("cache_creation_input_tokens") or 0)
+            self._usage_totals["cache_read_tokens"]     += int(u.get("cache_read_input_tokens") or 0)
         if msg.get("model"):
             self._last_model = msg["model"]
         for blk in msg.get("content", []):
@@ -341,18 +350,17 @@ class LoopFmt:
         shared  = os.environ.get("LOOP_SHARED_ROOT") or os.path.expanduser("~/.shared/roll")
         if not (slug and cycle):
             return
-        # Pull usage off the result event itself if present, otherwise off
-        # the most recent assistant turn we observed.
-        usage = (result_ev.get("usage") or self._last_usage or {})
+        # Use the cumulative totals accumulated across all assistant turns;
+        # result.usage is per-turn (last only) so it would under-count badly.
         model = result_ev.get("model") or self._last_model or ""
         payload = {
-            "model": model,
-            "input_tokens":            int(usage.get("input_tokens") or 0),
-            "output_tokens":           int(usage.get("output_tokens") or 0),
-            "cache_creation_tokens":   int(usage.get("cache_creation_input_tokens") or 0),
-            "cache_read_tokens":       int(usage.get("cache_read_input_tokens") or 0),
-            "cost_reported_usd":       float(cost_usd or 0),
-            "duration_ms":             int(dur_ms or 0),
+            "model":                 model,
+            "input_tokens":          self._usage_totals["input_tokens"],
+            "output_tokens":         self._usage_totals["output_tokens"],
+            "cache_creation_tokens": self._usage_totals["cache_creation_tokens"],
+            "cache_read_tokens":     self._usage_totals["cache_read_tokens"],
+            "cost_reported_usd":     float(cost_usd or 0),
+            "duration_ms":           int(dur_ms or 0),
         }
         evfile = os.path.join(shared, "loop", f"events-{slug}.ndjson")
         line = json.dumps({

package/lib/roll-backlog.py

@@ -211,51 +211,14 @@ def render(path: str) -> None:
 
 def main() -> None:
     args = sys.argv[1:]
-    demo = "--demo" in args
     no_color = "--no-color" in args or not sys.stdout.isatty() or os.getenv("NO_COLOR")
     rr.USE_COLOR = not no_color
 
     backlog = ".roll/backlog.md"
-    if not demo and not os.path.isfile(backlog):
+    if not os.path.isfile(backlog):
         print(f"Error: {backlog} not found — run 'roll init' first", file=sys.stderr)
         sys.exit(1)
-
-    if demo:
-        _write_demo(backlog)
-        try:
-            render(backlog)
-        finally:
-            os.unlink(backlog)
-    else:
-        render(backlog)
-
-
-def _write_demo(path: str) -> None:
-    with open(path, "w") as f:
-        f.write("""# Project Backlog
-
-## 🐛 Bug Fixes
-| ID | Description | Status |
-|----|-------------|--------|
-| FIX-042 | Fix outer runner tmux kill matching wrong session | 🔨 In Progress |
-| FIX-043 | Handle stale state in loop now command | 📋 Todo |
-
-## Epic: Autonomous Evolution
-### Feature: autonomous-evolution
-| Story | Description | Status |
-|-------|-------------|--------|
-| [US-AUTO-042](.roll/features/autonomous-evolution/autonomous-evolution.md) | Loop cost telemetry — write model and token data per cycle | 📋 Todo |
-
-## ♻️ Refactor
-| ID | Description | Status |
-|----|-------------|--------|
-| REFACTOR-010 | Simplify CI test parallelism strategy | 🔒 Blocked [waiting on CI infra] |
-
-## 💡 Ideas
-| ID | Description | Status |
-|----|-------------|--------|
-| IDEA-025 | Dashboard cost from list-price tokens | ⏸ Deferred [design pending] |
-""")
+    render(backlog)
 
 
 if __name__ == "__main__":

package/lib/roll-help.py

@@ -7,7 +7,7 @@ Compact wordmark + grouped commands (AUTONOMY / PROJECT / MACHINE) + examples.
 Usage:
   python3 lib/roll-help.py              # live
   python3 lib/roll-help.py --no-color
-  python3 lib/roll-help.py --demo       # same as live, no fixture needed
+  python3 lib/roll-help.py              # static layout, no fixture needed
 """
 
 from __future__ import annotations
@@ -142,7 +142,6 @@ def render(version: str) -> None:
 # ════════════════════════════════════════════════════════════════════════════
 def main() -> None:
     ap = argparse.ArgumentParser(add_help=False)
-    ap.add_argument("--demo",     action="store_true")
     ap.add_argument("--no-color", dest="no_color", action="store_true")
     ap.add_argument("--en",       action="store_true")
     ap.add_argument("--zh",       action="store_true")

package/lib/roll-home.py

@@ -10,7 +10,7 @@ Usage:
   python3 lib/roll-home.py              # live data
   python3 lib/roll-home.py --no-color
   python3 lib/roll-home.py --en | --zh  # collapse bilingual rows
-  python3 lib/roll-home.py --demo       # render with fixture data
+  ROLL_RENDER_FIXTURE=1 python3 lib/roll-home.py   # render with fixture data (test only)
 """
 
 from __future__ import annotations
@@ -262,9 +262,9 @@ def _ac_completion(feature_link: str) -> Tuple[int, int]:
     return (done, total)
 
 # ════════════════════════════════════════════════════════════════════════════
-# Demo fixture
+# Fixture data (test-only; opt in via ROLL_RENDER_FIXTURE=1)
 # ════════════════════════════════════════════════════════════════════════════
-def _demo_data() -> Dict[str, Any]:
+def _fixture_data() -> Dict[str, Any]:
     return dict(
         project_name="myapp", version="2026.518.3",
         agent="claude", git_branch="main", git_status="✓",
@@ -455,7 +455,6 @@ def render(d: Dict[str, Any]) -> None:
 # ════════════════════════════════════════════════════════════════════════════
 def main() -> None:
     ap = argparse.ArgumentParser(add_help=False)
-    ap.add_argument("--demo",     action="store_true")
     ap.add_argument("--no-color", dest="no_color", action="store_true")
     ap.add_argument("--en",       action="store_true")
     ap.add_argument("--zh",       action="store_true")
@@ -464,8 +463,8 @@ def main() -> None:
     if args.no_color or os.environ.get("NO_COLOR") or not sys.stdout.isatty():
         roll_render.USE_COLOR = False
 
-    if args.demo:
-        d = _demo_data()
+    if os.environ.get("ROLL_RENDER_FIXTURE"):
+        d = _fixture_data()
     else:
         slug    = _project_slug()
         config  = _load_config()

package/lib/roll-init.py

@@ -1,8 +1,38 @@
 #!/usr/bin/env python3
-"""roll-init — v2 terminal view for `roll init` (US-VIEW-008)."""
+"""roll-init — v2 terminal view for `roll init`.
+
+Reads a single JSON document from stdin describing real step outcomes
+captured by the bash flow in `bin/roll cmd_init`. Renders the v2 UI
+(banner + horizontal rule + numbered steps + NEXT block) preserving the
+visual style of US-VIEW-008 but reflecting what actually happened.
+
+Input schema (single JSON object on stdin):
+  {
+    "kind": "init",                     # informational; UI label uses header_label
+    "header_label": "INIT",             # banner label (e.g. "INIT" / "REINIT")
+    "subtitle": "项目初始化",            # banner subtitle
+    "project_path": "/path/to/project", # right-aligned banner text
+    "steps": [
+      {"num": 1, "label": "Detect project type", "status": "ok"},
+      {"num": 2, "label": "Create AGENTS.md", "status": "ok",
+       "files": [["+", "AGENTS.md"]]},
+      {"num": 3, "label": "...", "status": "skip", "note": "already exists"},
+      {"num": 4, "label": "...", "status": "fail", "error": "permission denied"}
+    ],
+    "footer": {"status": "ok", "label": "Project ready"},
+    "next": [["Edit .roll/backlog.md", "open the backlog and add your first US"]]
+  }
+
+`status` values: ok | skip | fail.
+`files` ops:     "+" created  "~" merged  "·" unchanged  "✗" failed.
+
+If stdin is empty or invalid JSON, exit 1 with a short message — the
+renderer is no longer runnable standalone, it always renders real data.
+"""
 from __future__ import annotations
 
 import argparse
+import json
 import os
 import sys
 
@@ -12,32 +42,6 @@ if _LIB_DIR not in sys.path:
 import roll_render
 from roll_render import c, row, COLS
 
-# ════════════════════════════════════════════════════════════════════════════
-# Demo data — 6 steps mirror cmd_init's actual phases.
-# AC text: detect → AGENTS.md → BACKLOG.md → docs/features/ → merge CLAUDE.md → link skills
-# Each entry: (label, [(op, filename)]) where op ∈ {"+", "~"}.
-# ════════════════════════════════════════════════════════════════════════════
-
-_DEMO_STEPS = [
-    ("Detect project type",          []),
-    ("Create AGENTS.md",             [("+", "AGENTS.md")]),
-    ("Create .roll/backlog.md",      [("+", ".roll/backlog.md")]),
-    ("Create .roll/features/",       [("+", ".roll/features/")]),
-    ("Merge existing CLAUDE.md",     [("~", "CLAUDE.md")]),
-    ("Link skills to AI clients",    [("+", "~/.claude/skills/roll-build"),
-                                      ("+", "~/.claude/skills/roll-fix")]),
-]
-
-_NEXT_STEPS = [
-    ("Edit .roll/backlog.md",     "open the backlog and add your first US"),
-    ("Run roll loop now",         "execute one cycle manually to test the flow"),
-    ("Enable loop scheduling",    "roll loop on  — let it run hourly"),
-]
-
-
-# ════════════════════════════════════════════════════════════════════════════
-# Render
-# ════════════════════════════════════════════════════════════════════════════
 
 def _divider(char: str = "─") -> None:
     print(c("dim", char * min(COLS, 80)))
@@ -48,53 +52,104 @@ def _op_marker(op: str) -> str:
         return c("green", "+", bold=True)
     if op == "~":
         return c("amber", "~", bold=True)
+    if op == "·":
+        return c("dim", "·")
+    if op == "✗":
+        return c("red", "✗", bold=True)
     return c("dim", op)
 
 
-def render_demo(project_path: str = "~/myproject") -> None:
-    left  = "  " + c("blue", "INIT", bold=True) + c("dim", "  ·  ") + c("dim", "项目初始化")
+def _step_icon(status: str) -> str:
+    if status == "ok":
+        return c("green", "✓")
+    if status == "skip":
+        return c("amber", "↷")
+    if status == "fail":
+        return c("red", "✗", bold=True)
+    return c("dim", "·")
+
+
+def _file_color(op: str) -> str:
+    if op == "+":
+        return "green"
+    if op == "~":
+        return "amber"
+    if op == "✗":
+        return "red"
+    return "dim"
+
+
+def render(payload: dict) -> None:
+    header_label = payload.get("header_label", "INIT")
+    subtitle = payload.get("subtitle", "项目初始化")
+    project_path = payload.get("project_path", "")
+
+    left = "  " + c("blue", header_label, bold=True) + c("dim", "  ·  ") + c("dim", subtitle)
     right = c("dim", project_path) + "  "
     print(row(left, right))
     _divider()
     print()
 
-    for i, (label, files) in enumerate(_DEMO_STEPS, start=1):
-        num  = c("dim", f"  {i}.")
-        icon = c("green", "✓")
+    for step in payload.get("steps", []):
+        num = c("dim", f"  {step.get('num', 0)}.")
+        icon = _step_icon(step.get("status", "ok"))
+        label = step.get("label", "")
         print(f"{num} {icon}  {label}")
-        for op, fname in files:
+        for entry in step.get("files", []) or []:
+            op, fname = entry[0], entry[1]
             mark = _op_marker(op)
-            color = "green" if op == "+" else "amber"
+            color = _file_color(op)
             print("       " + mark + "  " + c(color, fname))
+        note = step.get("note") or step.get("error")
+        if note:
+            tone = "red" if step.get("status") == "fail" else "dim"
+            print("       " + c(tone, str(note)))
 
     print()
     _divider()
-    print("  " + c("green", "✓") + " " + c("green", "Project ready", bold=True))
-    print()
-    print("  " + c("pink", "NEXT", bold=True) + c("dim", "  ·  下一步"))
-    for i, (label, hint) in enumerate(_NEXT_STEPS, start=1):
-        num = c("dim", f"  {i}.")
-        print(f"{num} {c('fg', label, bold=True)}")
-        print("     " + c("dim", hint))
+
+    footer = payload.get("footer") or {}
+    f_status = footer.get("status", "ok")
+    f_label = footer.get("label", "Done")
+    icon_color = "green" if f_status == "ok" else "red"
+    icon = "✓" if f_status == "ok" else "✗"
+    print("  " + c(icon_color, icon) + " " + c(icon_color, f_label, bold=True))
+
+    next_items = payload.get("next") or []
+    if next_items:
+        print()
+        print("  " + c("pink", "NEXT", bold=True) + c("dim", "  ·  下一步"))
+        for i, entry in enumerate(next_items, start=1):
+            label = entry[0]
+            hint = entry[1] if len(entry) > 1 else ""
+            num = c("dim", f"  {i}.")
+            print(f"{num} {c('fg', label, bold=True)}")
+            if hint:
+                print("     " + c("dim", hint))
     _divider("═")
 
 
-# ════════════════════════════════════════════════════════════════════════════
-# Entry point
-# ════════════════════════════════════════════════════════════════════════════
+def _read_payload() -> dict:
+    raw = sys.stdin.read()
+    if not raw.strip():
+        sys.stderr.write("roll-init.py: expected JSON on stdin\n")
+        sys.exit(1)
+    try:
+        return json.loads(raw)
+    except json.JSONDecodeError as exc:
+        sys.stderr.write(f"roll-init.py: invalid JSON on stdin: {exc}\n")
+        sys.exit(1)
+
 
 def main() -> None:
     ap = argparse.ArgumentParser(add_help=False)
-    ap.add_argument("--demo",     action="store_true")
     ap.add_argument("--no-color", dest="no_color", action="store_true")
-    ap.add_argument("--en",       action="store_true")
-    ap.add_argument("--zh",       action="store_true")
     args, _ = ap.parse_known_args()
 
     if args.no_color or os.environ.get("NO_COLOR") or not sys.stdout.isatty():
         roll_render.USE_COLOR = False
 
-    render_demo(project_path=os.getcwd())
+    render(_read_payload())
 
 
 if __name__ == "__main__":

package/lib/roll-loop-status.py

@@ -17,7 +17,7 @@ Usage:
   python3 lib/roll-loop-status.py --days 7
   python3 lib/roll-loop-status.py --no-color
   python3 lib/roll-loop-status.py --en | --zh  # collapse bilingual rows
-  python3 lib/roll-loop-status.py --demo       # render with fixture data
+  ROLL_RENDER_FIXTURE=1 python3 lib/roll-loop-status.py   # render with fixture data (test only)
 
   Wire it in bin/roll under `loop status` (replace _loop_status with a call to
   this script).
@@ -206,9 +206,19 @@ def aggregate(events: List[Dict[str, Any]], cron: List[Dict[str, Any]]) -> List[
         elif stage == "usage":
             # US-LOOP-004: loop-fmt emits this with full token / cost data.
             # Detail is a dict (not the legacy string form).
+            # US-VIEW-010: token counts are per-turn deltas — sum across events
+            # so list-price cost computed from totals matches actual API usage.
+            # Non-additive fields (model, cost_reported_usd, duration_ms) take
+            # the last value seen.
             d = e.get("detail") or {}
             if isinstance(d, dict):
-                cy["usage_event"] = d
+                prev = cy.get("usage_event") or {}
+                merged = dict(prev)
+                merged.update(d)
+                for k in ("input_tokens", "output_tokens",
+                          "cache_creation_tokens", "cache_read_tokens"):
+                    merged[k] = int(prev.get(k) or 0) + int(d.get(k) or 0)
+                cy["usage_event"] = merged
         elif stage in ("test", "build") and e.get("outcome") == "fail":
             cy["fail_detail"] = detail or stage
 
@@ -315,8 +325,7 @@ def backfill_usage_from_claude_sessions(cycles: List[Dict[str, Any]], slug: str)
     for cy in cycles:
         # Path 1: usage event written by loop-fmt at result time.
         ue = cy.get("usage_event")
-        if isinstance(ue, dict) and (ue.get("input_tokens") or ue.get("output_tokens")
-                                     or ue.get("cost_reported_usd")):
+        if isinstance(ue, dict) and (ue.get("input_tokens") or ue.get("output_tokens")):
             cy["tokens"] = mp.total_tokens(
                 input_tokens=ue.get("input_tokens", 0),
                 output_tokens=ue.get("output_tokens", 0),
@@ -324,20 +333,18 @@ def backfill_usage_from_claude_sessions(cycles: List[Dict[str, Any]], slug: str)
                 cache_read_tokens=ue.get("cache_read_tokens", 0),
             )
             cy["model"] = ue.get("model")
-            # FIX-060: cost_reported_usd is the authoritative cumulative session
-            # cost written by loop-fmt; use it directly instead of recomputing
-            # from the last individual API-call token counts (which would only
-            # reflect one small call and badly undercount the true cycle cost).
-            if ue.get("cost_reported_usd"):
-                cy["cost_list"] = float(ue["cost_reported_usd"])
-            else:
-                cy["cost_list"] = mp.compute_list_cost(
-                    ue.get("model"),
-                    input_tokens=ue.get("input_tokens", 0),
-                    output_tokens=ue.get("output_tokens", 0),
-                    cache_creation_tokens=ue.get("cache_creation_tokens", 0),
-                    cache_read_tokens=ue.get("cache_read_tokens", 0),
-                )
+            # US-VIEW-010: aggregate now sums per-turn usage tokens, so the
+            # totals in `ue` reflect the whole cycle. Always compute cost at
+            # list price for cross-account comparability — supersedes FIX-060
+            # which preferred cost_reported_usd as a workaround for
+            # last-event-only token counts (that root cause is now gone).
+            cy["cost_list"] = mp.compute_list_cost(
+                ue.get("model"),
+                input_tokens=ue.get("input_tokens", 0),
+                output_tokens=ue.get("output_tokens", 0),
+                cache_creation_tokens=ue.get("cache_creation_tokens", 0),
+                cache_read_tokens=ue.get("cache_read_tokens", 0),
+            )
             if ue.get("duration_ms") and not cy.get("duration_s"):
                 cy["duration_s"] = int(ue["duration_ms"] / 1000)
             continue
@@ -733,9 +740,9 @@ def _next_cron_hint(state: Dict[str, str], zh: bool = False) -> str:
     return nxt.strftime("%H:%M") + f" · in {mins}m {secs:02d}s"
 
 # ════════════════════════════════════════════════════════════════════════════
-# Demo fixture — lets you preview the output without real data
+# Fixture data (test-only; opt in via ROLL_RENDER_FIXTURE=1)
 # ════════════════════════════════════════════════════════════════════════════
-def _demo_data():
+def _fixture_data():
     now = datetime.now(timezone.utc)
     events, cron = [], []
     cycle_id = 0
@@ -788,7 +795,6 @@ def main(argv=None):
     p.add_argument("--no-color", action="store_true", help="strip ANSI (also honors NO_COLOR=1)")
     p.add_argument("--en", action="store_true", help="EN rows only")
     p.add_argument("--zh", action="store_true", help="ZH rows only")
-    p.add_argument("--demo", action="store_true", help="render with fixture data")
     args = p.parse_args(argv)
 
     roll_render.USE_COLOR = (not args.no_color
@@ -797,10 +803,12 @@ def main(argv=None):
 
     lang = "en" if args.en else ("zh" if args.zh else "both")
 
-    if args.demo:
-        events, cron, state, backlog = _demo_data()
+    use_fixture = bool(os.environ.get("ROLL_RENDER_FIXTURE"))
+    if use_fixture:
+        events, cron, state, backlog = _fixture_data()
         runs = {}
         git_merges = {}
+        slug = None
     else:
         slug = project_slug()
         events     = load_events(slug, args.days)
@@ -812,7 +820,7 @@ def main(argv=None):
 
     render(events, cron, state, backlog, days=args.days, lang=lang,
            runs=runs, git_merges=git_merges,
-           claude_slug=None if args.demo else slug)
+           claude_slug=slug)
 
 if __name__ == "__main__":
     try:

package/lib/roll-peer.py

@@ -50,10 +50,11 @@ def _agent_c(name: str) -> str:
 
 
 # ════════════════════════════════════════════════════════════════════════════
-# Demo data — illustrative cross-agent review: claude proposes, codex reviews
+# Fixture data (test-only; opt in via ROLL_RENDER_FIXTURE=1)
+# Illustrative cross-agent review: claude proposes, codex reviews
 # ════════════════════════════════════════════════════════════════════════════
 
-_DEMO_SUBJECT = {
+_FIXTURE_SUBJECT = {
     "story":     "US-AUTH-014",
     "title":     "Session refresh fallback when refresh-token API 5xx",
     "pr":        "#412",
@@ -63,7 +64,7 @@ _DEMO_SUBJECT = {
     "reviewer":  "codex",
 }
 
-_DEMO_ROUNDS = [
+_FIXTURE_ROUNDS = [
     {
         "n": 1,
         "hint": "first pass — proposer ships, reviewer probes",
@@ -93,13 +94,13 @@ _DEMO_ROUNDS = [
     },
 ]
 
-_DEMO_VERDICT = {
+_FIXTURE_VERDICT = {
     "outcome": "approved",
     "reason":  "2 rounds · 5 turns · all blocks resolved",
 }
 
-_DEMO_ARTIFACT = "~/.roll/.peer-state/logs/20260519_213700_claude_codex.md"
-_DEMO_NEXT = [
+_FIXTURE_ARTIFACT = "~/.roll/.peer-state/logs/20260519_213700_claude_codex.md"
+_FIXTURE_NEXT = [
     ("Continue execution",   "claude resumes work on US-AUTH-014"),
     ("Inspect log",          "open the artifact above to replay the transcript"),
 ]
@@ -205,19 +206,19 @@ def _footer(artifact: str, next_steps: list) -> None:
 # Top-level render
 # ════════════════════════════════════════════════════════════════════════════
 
-def render_demo() -> None:
-    _eyebrow(_DEMO_SUBJECT["trigger"])
+def render_fixture() -> None:
+    _eyebrow(_FIXTURE_SUBJECT["trigger"])
     _divider()
     print()
-    _subject(_DEMO_SUBJECT)
+    _subject(_FIXTURE_SUBJECT)
     print()
-    _pair_overview(_DEMO_SUBJECT)
-    for rd in _DEMO_ROUNDS:
+    _pair_overview(_FIXTURE_SUBJECT)
+    for rd in _FIXTURE_ROUNDS:
         _round_header(rd["n"], rd["hint"])
         for agent, weight, body in rd["turns"]:
             _turn(agent, weight, body)
-    _verdict(_DEMO_VERDICT)
-    _footer(_DEMO_ARTIFACT, _DEMO_NEXT)
+    _verdict(_FIXTURE_VERDICT)
+    _footer(_FIXTURE_ARTIFACT, _FIXTURE_NEXT)
 
 
 # ════════════════════════════════════════════════════════════════════════════
@@ -226,7 +227,6 @@ def render_demo() -> None:
 
 def main() -> None:
     ap = argparse.ArgumentParser(add_help=False)
-    ap.add_argument("--demo",     action="store_true")
     ap.add_argument("--no-color", dest="no_color", action="store_true")
     ap.add_argument("--en",       action="store_true")
     ap.add_argument("--zh",       action="store_true")
@@ -235,7 +235,17 @@ def main() -> None:
     if args.no_color or os.environ.get("NO_COLOR") or not sys.stdout.isatty():
         roll_render.USE_COLOR = False
 
-    render_demo()
+    # FIX-076: this standalone entrypoint only knows how to render the fixture
+    # transcript (for UI tests). Real peer review is orchestrated by bin/roll
+    # and never invokes this main(). Require an explicit opt-in so a stray
+    # `python3 lib/roll-peer.py` invocation can't masquerade as live output.
+    if not os.environ.get("ROLL_RENDER_FIXTURE"):
+        print("Error: lib/roll-peer.py only renders fixture data; "
+              "set ROLL_RENDER_FIXTURE=1 to use it (test-only).",
+              file=sys.stderr)
+        sys.exit(2)
+
+    render_fixture()
 
 
 if __name__ == "__main__":

package/lib/roll-setup.py

@@ -1,61 +1,101 @@
 #!/usr/bin/env python3
-"""roll-setup — v2 terminal view for `roll setup`."""
+"""roll-setup — v2 terminal view for `roll setup`.
+
+Reads a single JSON document from stdin describing the real outcomes of
+`bin/roll cmd_setup`'s step sequence (detect platform / install skills /
+sync conventions / etc). Renders the v2 UI preserving the visual style
+of US-VIEW-007 while reflecting actual results.
+
+Input schema matches `lib/roll-init.py` (see that file for details).
+"""
 from __future__ import annotations
 
+import argparse
+import json
 import os
 import sys
 
 _LIB_DIR = os.path.dirname(os.path.realpath(__file__))
 if _LIB_DIR not in sys.path:
     sys.path.insert(0, _LIB_DIR)
+import roll_render
 from roll_render import c, row, COLS
 
-# ════════════════════════════════════════════════════════════════════════════
-# Demo data
-# ════════════════════════════════════════════════════════════════════════════
-
-_DEMO_STEPS = [
-    "Detect platform & shell",
-    "Fetch latest roll version",
-    "Install skills to ~/.claude",
-    "Symlink bin/roll to PATH",
-    "Check for config drift",
-    "Apply convention templates",
-]
-
-# ════════════════════════════════════════════════════════════════════════════
-# Rendering
-# ════════════════════════════════════════════════════════════════════════════
 
 def _divider(char: str = "─") -> None:
     print(c("dim", char * min(COLS, 80)))
 
 
-def render_demo() -> None:
-    left  = "  " + c("blue", "SETUP", bold=True) + c("dim", "  ·  ") + c("dim", "初始化")
-    right = c("dim", "--demo")
-    print(row(left, "  " + right))
+def _step_icon(status: str) -> str:
+    if status == "ok":
+        return c("green", "✓")
+    if status == "skip":
+        return c("amber", "↷")
+    if status == "forced":
+        return c("blue", "~")
+    if status == "fail":
+        return c("red", "✗", bold=True)
+    return c("dim", "·")
+
+
+def render(payload: dict) -> None:
+    header_label = payload.get("header_label", "SETUP")
+    subtitle = payload.get("subtitle", "初始化")
+    right_text = payload.get("project_path") or payload.get("right", "")
+
+    left = "  " + c("blue", header_label, bold=True) + c("dim", "  ·  ") + c("dim", subtitle)
+    right = c("dim", right_text) + "  " if right_text else ""
+    print(row(left, right))
     _divider()
     print()
 
-    for i, label in enumerate(_DEMO_STEPS, start=1):
-        num  = c("dim", f"  {i}.")
-        icon = c("green", "✓")
+    for step in payload.get("steps", []):
+        num = c("dim", f"  {step.get('num', 0)}.")
+        icon = _step_icon(step.get("status", "ok"))
+        label = step.get("label", "")
         print(f"{num} {icon}  {label}")
+        note = step.get("note") or step.get("error")
+        if note:
+            tone = "red" if step.get("status") == "fail" else "dim"
+            print("       " + c(tone, str(note)))
 
     print()
     _divider()
-    msg = c("green", "Setup complete")
-    print(f"  {msg}  —  run {c('fg', 'roll init', bold=True)} inside a project to begin")
+
+    footer = payload.get("footer") or {}
+    f_status = footer.get("status", "ok")
+    f_label = footer.get("label", "Setup complete")
+    icon_color = "green" if f_status == "ok" else "red"
+    msg = c(icon_color, f_label)
+    next_hint = footer.get("hint")
+    if next_hint:
+        print(f"  {msg}  —  {next_hint}")
+    else:
+        print(f"  {msg}")
     _divider("═")
 
 
-# ════════════════════════════════════════════════════════════════════════════
-# Entry point
-# ════════════════════════════════════════════════════════════════════════════
+def _read_payload() -> dict:
+    raw = sys.stdin.read()
+    if not raw.strip():
+        sys.stderr.write("roll-setup.py: expected JSON on stdin\n")
+        sys.exit(1)
+    try:
+        return json.loads(raw)
+    except json.JSONDecodeError as exc:
+        sys.stderr.write(f"roll-setup.py: invalid JSON on stdin: {exc}\n")
+        sys.exit(1)
+
 
 def main() -> None:
-    render_demo()
+    ap = argparse.ArgumentParser(add_help=False)
+    ap.add_argument("--no-color", dest="no_color", action="store_true")
+    args, _ = ap.parse_known_args()
+
+    if args.no_color or os.environ.get("NO_COLOR") or not sys.stdout.isatty():
+        roll_render.USE_COLOR = False
+
+    render(_read_payload())
 
 
 if __name__ == "__main__":

package/lib/roll-status.py

@@ -8,7 +8,7 @@ project templates, and this-project metrics.
 Usage:
   python3 lib/roll-status.py              # live data
   python3 lib/roll-status.py --no-color
-  python3 lib/roll-status.py --demo       # render with fixture data
+  ROLL_RENDER_FIXTURE=1 python3 lib/roll-status.py   # render with fixture data (test only)
 """
 
 from __future__ import annotations
@@ -149,9 +149,9 @@ def _launchd_state(service: str, slug: str) -> str:
         return "installed-off"
 
 # ════════════════════════════════════════════════════════════════════════════
-# Demo fixture
+# Fixture data (test-only; opt in via ROLL_RENDER_FIXTURE=1)
 # ════════════════════════════════════════════════════════════════════════════
-def _demo_data() -> Dict[str, Any]:
+def _fixture_data() -> Dict[str, Any]:
     return dict(
         conventions=[
             ("AGENTS.md", True), ("CLAUDE.md", True), ("GEMINI.md", False),
@@ -347,7 +347,6 @@ def _live_data() -> Dict[str, Any]:
 # ════════════════════════════════════════════════════════════════════════════
 def main() -> None:
     ap = argparse.ArgumentParser(add_help=False)
-    ap.add_argument("--demo",     action="store_true")
     ap.add_argument("--no-color", dest="no_color", action="store_true")
     ap.add_argument("--en",       action="store_true")
     ap.add_argument("--zh",       action="store_true")
@@ -356,7 +355,7 @@ def main() -> None:
     if args.no_color or os.environ.get("NO_COLOR") or not sys.stdout.isatty():
         roll_render.USE_COLOR = False
 
-    d = _demo_data() if args.demo else _live_data()
+    d = _fixture_data() if os.environ.get("ROLL_RENDER_FIXTURE") else _live_data()
 
     _render_health(d)
     _render_global_conventions(d["conventions"])

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seanyao/roll",
-  "version": "2026.520.1",
+  "version": "2026.521.1",
   "description": "Roll — Roll out features with AI agents",
   "scripts": {
     "test": "bash tests/run.sh"

package/skills/roll-peer/SKILL.md

@@ -105,11 +105,67 @@ Rules:
 - Do not copy README text. List file pointers only.
 - Never include secrets, tokens, credentials, or `.env` content.
 - Even if logically a continuation, treat as round=1 if the peer has **no prior context**.
+- **Do NOT** prefill the peer with your own root-cause analysis, proposed fix, or leading questions — see the *Independent Judgment Rule* below. The handoff card is for context, not conclusions.
 
 ### Anti-Hallucination Rule
 
 When mentioning specific paths, function names, commands, line numbers, or tool results, **must cite the source** ("I read X at line Y"). If unverified, state "unverified" explicitly.
 
+### Independent Judgment Rule (round=1)
+
+The whole point of peer review is to surface a **second, independent** read. If
+the reviewer's own root-cause analysis, fix diff, and leading questions are sent
+to the peer up front, the peer can only AGREE inside the reviewer's frame — and
+that AGREE carries no signal. The reviewer **must complete their own analysis
+before opening round=1**; skipping that step turns peer review into a search for
+endorsement.
+
+Round=1 message **must NOT include**:
+
+- The reviewer's own root-cause analysis ("the bug is in function X at line Y because…").
+- The reviewer's own proposed fix, patch, or diff.
+- Leading questions of the form "do you agree with my conclusion on X?" / "is the change I made on Y safe?" — these lock the peer into the reviewer's framing.
+- Specific line numbers, function names, or branch points the reviewer has already identified as relevant — let the peer locate them.
+
+Round=1 message **should include**:
+
+- The Project Handoff Card (above).
+- Symptoms exactly as observed: the user's reported error, terminal output verbatim, the precise commands that triggered it.
+- Necessary external context: the goal of the work, the date / version under test, anything the peer cannot infer from the repo alone.
+- Key file pointers as **entry points** (paths only — let the peer choose what to read and how deep).
+- An open invitation: "independently identify the root cause, propose a fix, and call out any test gaps."
+
+After receiving the peer's round=1 reply, the reviewer **compares** their own
+conclusion to the peer's and routes the next action:
+
+| Reviewer's own conclusion vs. peer's conclusion | Next action |
+|---|---|
+| Same root cause + same fix direction | High confidence — AGREE and proceed to execution |
+| Same root cause, different fix direction | REFINE — open round=2 to reconcile the fix |
+| Different root cause | OBJECT — open round=2; at least one of the two analyses is wrong |
+| Peer asks for more context | REFINE — supply the missing context, then re-evaluate |
+
+#### Example (bad — endorsement-seeking)
+
+```
+Bug is in `cmd_init` at line 932 — the v2 demo renderer fires unconditionally.
+My fix: gate it behind `--demo`. Q1: is this over-killed? Q2: should I
+refactor the renderer instead? Q3: are the tests strong enough?
+```
+
+The peer can only AGREE or quibble inside the reviewer's framing.
+
+#### Example (good — independent analysis)
+
+```
+Symptoms: user ran `roll init` on /path/X and saw [verbatim terminal output A];
+then ran `roll backlog` and saw [verbatim terminal output B]. Project background:
+[project shape]. Entry points: `bin/roll`, `lib/roll-init.py`, `tests/`.
+Independently identify the root cause and propose a fix.
+```
+
+The peer reads, locates, and proposes on its own. The reviewer then compares.
+
 ## State Machine
 
 ### Per Negotiation (Single Task)
@@ -208,8 +264,10 @@ When peer review is manually triggered by a human (via `/peer`, "叫上 peer", e
 
 **Rules:**
 - Peer CLI calls must be **synchronous** (do NOT use background/async execution).
+- The outgoing round=1 message must follow the *Independent Judgment Rule* above — no root-cause analysis, no fix diff, no leading questions.
 - Show the outgoing message **before** calling the peer, so the user sees what's being asked.
 - Relay the peer's response **verbatim** before adding your own analysis.
+- After the peer's reply, the reviewer's own analysis block must explicitly state whether the peer's root cause and fix direction match the reviewer's own (independent) conclusion — that comparison is what determines the next round's action.
 - If a peer call fails or times out, report it immediately inline and either retry or ESCALATE.
 - Negotiation log is still written to `~/.shared/roll/peer/logs/` as usual.