@seanyao/roll 2026.519.1 → 2026.519.2

package/CHANGELOG.md

@@ -1,10 +1,35 @@
 # Changelog
 
+## v2026.519.2
+
+### Improved
+
+- **`roll init`** — 初始化流程现在显示 6 步编号进度，新建文件用绿色 `+`、合并已有用琥珀 `~`，结尾给三步上手指南 `[loop]`
+
 ## v2026.519.1
 
+### Major（大版本重构）
+
+- **项目结构重组 — 过程文件迁入 `.roll/`** — Phase 1 of Legacy Onboard Epic。`BACKLOG.md`、`PROPOSALS.md`、`docs/{features,briefs,dream,design,domain}/` 全部搬入 `.roll/`；`docs/guide/`、`docs/site/`、`docs/intro/` 上移到根级。一次性 breaking change，迁移指南见 `guide/{en,zh}/migration-2.0.md` `[legacy-onboard]`
+- **新命令 `roll migrate`** — 老项目一键迁到新结构：dry-run 预览 + `git mv` 保留历史 + 单原子 commit + 三态幂等（仅老 / 仅新 / 并存） `[legacy-onboard]`
+- **新版 `roll init` 识别 Legacy 项目** — 检测到现有源码无 `AGENTS.md` 时引导用户进入 onboard 流程：列出本机 AI agent、显式告知 token 消耗、引导运行 `$roll-onboard` `[legacy-onboard]`
+- **新技能 `$roll-onboard`** — 三组九问 ≤ 3 分钟，AI 读懂项目后生成 `.roll/onboard-plan.yaml`，bash 侧 `roll init --apply` 执行 `[legacy-onboard]`
+- **新命令 `roll init --apply`** — 消费 onboard plan 创建 `.roll/` 结构，按用户选择写 `.gitignore`、同步 AI 工具约定 `[legacy-onboard]`
+- **结构强制检测** — 新版 Roll 在老结构项目上拒绝运行 + 引导 `roll migrate`（`setup` / `update` / `version` / `help` / `init` 豁免；`ROLL_SKIP_STRUCTURE_CHECK=1` 旁路） `[legacy-onboard]`
+
+### Improved
+
+- `AGENTS.md` §8 Documentation Conventions 重写匹配新目录结构，明确"过程默认对内、产品默认对外"原则 `[docs]`
+- `guide/{en,zh}/practices/` 收入工程规范文档（原 `docs/practices/engineering-common-sense.md`） `[docs]`
+- 新增 Python 校验器 `lib/roll-plan-validate.py`，验证 onboard plan 完整性、`generated_at` 24h 时效、版本兼容 `[legacy-onboard]`
+
 ### Fixed
 
 - **`roll setup` 后从未开启 loop 的项目** — 不再被 macOS 自动激活、每小时弹出终端窗口 `[loop]`
+- **`_write_backlog` 缺 `mkdir -p` 导致 `cmd_init` 在 `.roll/` 不存在时崩** `[legacy-onboard]`
+- **`release.sh` 多 feature 时 awk `newline in string` 错误** — macOS BSD awk 不容忍 `-v var=多行`；改用 `ENVIRON` 读取 `[release]`
+- **GitHub 仓库改名 Roll → roll** — 内部代码、测试 fixture、文档引用全部同步小写命名 `[chore]`
+- **`.roll/backlog.md` 和 `guide/*` 中残留 `docs/features` 等老路径引用** — Story 5 sed 漏覆盖 `.roll/` 和 `guide/` 文件，dream 巡检发现后补齐 `[legacy-onboard]`
 
 ## v2026.518.4
 

package/README.md

@@ -11,7 +11,7 @@
 
 **[中文版 README](README_CN.md)**
 
-[![Website](https://img.shields.io/badge/Website-seanyao.github.io%2FRoll-blue)](https://seanyao.github.io/Roll/)
+[![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/@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)
@@ -28,6 +28,18 @@ Roll is an autonomous delivery system for software teams — AI agents pick stor
 
 _Works with Claude, Cursor, Codex, or your own agent._
 
+## What's New in 2.0 (May 2026)
+
+Roll 2.0 introduces a **process/product split** to keep open-source projects clean:
+
+- **`.roll/` directory convention** — all process artifacts (backlog, features, briefs, dream logs) move out of root into `.roll/`. User-facing `guide/` and `site/` move up to root. Old `docs/` directory disappears.
+- **`roll migrate`** — one-command migration for projects on pre-2.0 layout. `git mv` preserves history, single atomic commit, three-state idempotent.
+- **`$roll-onboard`** — interactive skill for adopting Roll on legacy codebases without rewrites. AI reads your code, asks 9 questions in ≤ 3 minutes, produces a plan; `roll init --apply` executes it.
+- **Three adoption patterns** — `seed` (new project), `graft` (legacy, non-invasive), `replant` (legacy, clean rebuild). See [guide/en/patterns/](guide/en/patterns/).
+
+📖 Upgrading from 1.x? Read [guide/en/migration-2.0.md](guide/en/migration-2.0.md).
+📖 New legacy project? Read [guide/en/legacy-onboarding.md](guide/en/legacy-onboarding.md).
+
 ## Evolution
 
 Roll didn't start as a framework. It started as a question: *what if the AI didn't just write code, but actually shipped it?*

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.519.1"
+VERSION="2026.519.2"
 ROLL_HOME="${ROLL_HOME:-${HOME}/.roll}"
 ROLL_CONFIG="${ROLL_HOME}/config.yaml"
 ROLL_GLOBAL="${ROLL_HOME}/conventions/global"
@@ -917,6 +917,23 @@ _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[@]:-}"
+
+  if [[ "${ROLL_UI:-v2}" == "v2" ]] || [[ "$demo" == "true" ]]; then
+    python3 "${ROLL_PKG_DIR}/lib/roll-init.py" --demo
+    if [[ "$demo" == "true" ]]; then return; fi
+  fi
+
   if [[ ! -d "$ROLL_TEMPLATES" ]]; then
     err "No templates found. Run 'roll setup' first.  未找到模板，请先运行 'roll setup'。"
     exit 1
@@ -2409,6 +2426,13 @@ cmd_agent() {
 # Returns a filesystem-safe slug combining the project basename and a 6-char
 # hash of the full path, ensuring uniqueness across sibling dirs with same name.
 _project_slug() {
+  # US-LOOP-006: cycle wrapper exports ROLL_MAIN_SLUG so any subshell — worktree,
+  # tmp cwd, or unrelated path — writes events / runs.jsonl under the main project
+  # identity instead of fragmenting into tmp-* / cycle-* phantom slugs.
+  if [[ -n "${ROLL_MAIN_SLUG:-}" ]]; then
+    printf '%s' "$ROLL_MAIN_SLUG"
+    return 0
+  fi
   local path="${1:-$(pwd -P 2>/dev/null || pwd)}"
   # FIX-056: normalize path to canonical case on macOS case-insensitive filesystem.
   # Two paths differing only in case point to the same directory; realpath
@@ -2769,6 +2793,38 @@ LOOP_CYCLE_TIMEOUT_SEC="\${ROLL_LOOP_CYCLE_TIMEOUT_SEC:-2700}"
 _CYCLE_TIMED_OUT=0
 _on_sigterm() { _CYCLE_TIMED_OUT=1; }
 trap '_on_sigterm' TERM
+# US-LOOP-005: idempotent runs.jsonl writer shared by normal exit, timeout
+# trap, and worktree-setup-failure early exit. Guards on jq + run_id dedupe so
+# multiple callers in the same cycle are safe.
+_runs_append() {
+  local _status="\$1"; local _tcr="\${2:-0}"; local _built="\${3:-[]}"
+  local _runs_dst="${HOME}/.shared/roll/loop/runs.jsonl"
+  command -v jq >/dev/null 2>&1 || return 0
+  local _cid="\${CYCLE_ID:-pre-cycle-\$\$}"
+  local _rid="loop-\${_cid%-*}"
+  grep -qF "\"run_id\":\"\$_rid\"" "\$_runs_dst" 2>/dev/null && return 0
+  mkdir -p "\$(dirname "\$_runs_dst")"
+  local _ts_now; _ts_now=\$(date -u +%Y-%m-%dT%H:%M:%SZ)
+  local _start="\${CYCLE_START:-\$(date -u +%s)}"
+  local _dur=\$(( \$(date -u +%s) - _start ))
+  [ "\$_dur" -lt 0 ] && _dur=0
+  jq -nc \\
+    --arg ts "\$_ts_now" \\
+    --arg project "${slug}" \\
+    --arg run_id "\$_rid" \\
+    --arg status "\$_status" \\
+    --arg cycle_id "\$_cid" \\
+    --argjson built "\$_built" \\
+    --argjson skipped '[]' \\
+    --argjson alerts '[]' \\
+    --argjson tcr_count "\$_tcr" \\
+    --argjson duration_sec "\$_dur" \\
+    '{ts:\$ts, project:\$project, run_id:\$run_id, status:\$status,
+      cycle_id:\$cycle_id,
+      built:\$built, skipped:\$skipped, alerts:\$alerts,
+      tcr_count:\$tcr_count, duration_sec:\$duration_sec}' \\
+    >> "\$_runs_dst" 2>/dev/null || true
+}
 _inner_cleanup() {
   local _rc=\$?
   # Kill heartbeat + every remaining background job (watchdog, orphan
@@ -2778,6 +2834,10 @@ _inner_cleanup() {
   for _pid in \$(jobs -p); do kill "\$_pid" 2>/dev/null; done
   if [ "\${_CYCLE_TIMED_OUT:-0}" -eq 1 ]; then
     _loop_event cycle_end "\${CYCLE_ID:-unknown}" "\${BRANCH:-}" "blocked" 2>/dev/null || true
+    # US-LOOP-005 T9: timeout path must also write runs.jsonl row so dashboard
+    # has a terminal record (cycle_end alone is insufficient — runs.jsonl is
+    # the canonical history feed for 'roll loop runs').
+    _runs_append "failed" 0 "[]" 2>/dev/null || true
     _worktree_alert "cycle \${CYCLE_ID:-unknown}: \${LOOP_CYCLE_TIMEOUT_SEC}s timeout — claude/python killed; in-progress story marked Blocked" 2>/dev/null || true
   fi
   rm -f "\$INNER_LOCK" "\$HEARTBEAT_FILE"
@@ -2800,12 +2860,16 @@ _LOOP_PROJ_SLUG="${slug}"
 _LOOP_ALERT="\${_SHARED_ROOT}/loop/ALERT-${slug}.md"
 _LOOP_STATE="\${_SHARED_ROOT}/loop/state-${slug}.yaml"
 _LOOP_MUTE_FILE="\${_SHARED_ROOT}/loop/mute-${slug}"
+# US-LOOP-006: ROLL_MAIN_SLUG is the canonical identity for any subprocess —
+# claude, loop-fmt.py, _loop_event in arbitrary cwd. _project_slug honors this
+# env var first, so writes never fragment into tmp-* / cycle-* phantom slugs.
+export ROLL_MAIN_SLUG="${slug}"
 
 # Pre-claude: try to create a per-cycle isolated worktree on origin/main.
 # On any failure (no remote, no main, etc.) fall back to running in the
 # project's main tree (degraded — no isolation, like pre-037 behavior).
-CYCLE_ID="\$(date -u +%Y%m%d-%H%M%S)-\$\$"
-CYCLE_START=\$(date -u +%s)
+CYCLE_ID="\$(date +%Y%m%d-%H%M%S)-\$\$"
+CYCLE_START=\$(date +%s)
 WT="\$(_worktree_path "${slug}" "cycle-\${CYCLE_ID}")"
 BRANCH="loop/cycle-\${CYCLE_ID}"
 _USE_WORKTREE=0
@@ -2859,6 +2923,10 @@ else
   # falling back to the main tree without isolation is unacceptable.
   _worktree_alert "cycle \${CYCLE_ID}: worktree setup failed — skipping cycle to avoid running without isolation"
   echo "[loop] cycle \${CYCLE_ID}: worktree setup failed; skipping cycle (no isolation)"
+  # US-LOOP-005 T10: worktree-setup-failed path leaves no commits and never
+  # emits cycle_start, but dashboard still needs a runs.jsonl row marking the
+  # cycle as failed (otherwise the scheduled tick appears to have vanished).
+  _runs_append "failed" 0 "[]" 2>/dev/null || true
   exit 0
 fi
 
@@ -2960,6 +3028,8 @@ if [ "\$_USE_WORKTREE" = "1" ]; then
       elif [ "\$_publish_status" -eq 2 ]; then
         if ( cd "${project_path}" && _worktree_merge_back "\$BRANCH" ); then
           _worktree_cleanup "\$WT" "\$BRANCH"
+          # US-LOOP-005 T3: gh unavailable + ff merge_back OK → cycle_end done
+          _loop_event cycle_end "\${CYCLE_ID}" "" "done" || true
           echo "[loop] cycle \${CYCLE_ID}: gh unavailable; merged via ff and cleaned up"
         else
           # FIX-039: gh unavailable + merge_back failed — push orphan branch+tag to origin
@@ -2969,9 +3039,13 @@ if [ "\$_USE_WORKTREE" = "1" ]; then
                && git tag "\$_orphan_tag" 2>/dev/null \
                && git push origin "\$_orphan_tag" 2>/dev/null ); then
             _worktree_cleanup "\$WT" "\$BRANCH"
+            # US-LOOP-005 T4: gh unavailable + orphan push OK → cycle_end orphan
+            _loop_event cycle_end "\${CYCLE_ID}" "" "orphan" || true
             _worktree_alert "cycle \${CYCLE_ID}: gh+merge_back failed; FIX-039 pushed orphan+tag \${_orphan_tag}; worktree cleaned"
             echo "[loop] cycle \${CYCLE_ID}: FIX-039: orphan branch+tag \${_orphan_tag} pushed; worktree cleaned"
           else
+            # US-LOOP-005 T5: gh unavailable + all failed → cycle_end failed
+            _loop_event cycle_end "\${CYCLE_ID}" "" "failed" || true
             _worktree_alert "cycle \${CYCLE_ID}: gh+merge_back+push all failed; worktree preserved at \$WT"
             echo "[loop] cycle \${CYCLE_ID}: all publish paths failed; worktree preserved at \$WT"
           fi
@@ -2984,15 +3058,21 @@ if [ "\$_USE_WORKTREE" = "1" ]; then
              && git tag "\$_orphan_tag" 2>/dev/null \
              && git push origin "\$_orphan_tag" 2>/dev/null ); then
           _worktree_cleanup "\$WT" "\$BRANCH"
+          # US-LOOP-005 T6: PR publish failed + orphan push OK → cycle_end orphan
+          _loop_event cycle_end "\${CYCLE_ID}" "" "orphan" || true
           _worktree_alert "cycle \${CYCLE_ID}: PR publish failed; FIX-039 pushed orphan+tag \${_orphan_tag}; worktree cleaned"
           echo "[loop] cycle \${CYCLE_ID}: FIX-039: orphan branch+tag \${_orphan_tag} pushed; worktree cleaned"
         else
+          # US-LOOP-005 T7: PR publish failed + orphan push failed → cycle_end failed
+          _loop_event cycle_end "\${CYCLE_ID}" "" "failed" || true
           _worktree_alert "cycle \${CYCLE_ID}: PR publish failed; worktree preserved at \$WT (branch \$BRANCH)"
           echo "[loop] cycle \${CYCLE_ID}: PR publish failed; worktree preserved at \$WT"
         fi
       fi
     fi
   else
+    # US-LOOP-005 T8: claude session failed after retry budget → cycle_end failed
+    _loop_event cycle_end "\${CYCLE_ID}" "" "failed" || true
     _worktree_alert "cycle \${CYCLE_ID}: claude exited \$_exit; worktree preserved at \$WT (branch \$BRANCH)"
     echo "[loop] cycle \${CYCLE_ID}: claude failed (exit \$_exit); worktree preserved at \$WT"
   fi
@@ -3003,31 +3083,9 @@ _loop_cleanup_stale_cycle_branches "${project_path}" || true
 
 # FIX-044 / Step 5: Write loop cycle run summary to runs.jsonl
 # Deterministic — runs in shell regardless of whether agent executes SKILL.md Step 5.
-# Idempotent: skips if a record for this run_id already exists (agent may also write).
-_runs_dst="${HOME}/.shared/roll/loop/runs.jsonl"
-mkdir -p "\$(dirname "\$_runs_dst")"
-_cycle_end=\$(date -u +%s)
-_cycle_dur=\$(( _cycle_end - CYCLE_START ))
-_ts=\$(date -u +%Y-%m-%dT%H:%M:%SZ)
-_run_id="loop-\${CYCLE_ID%-*}"
-if command -v jq >/dev/null 2>&1 && ! grep -qF "\"run_id\":\"\$_run_id\"" "\$_runs_dst" 2>/dev/null; then
-  jq -nc \\
-    --arg ts "\$_ts" \\
-    --arg project "${slug}" \\
-    --arg run_id "\$_run_id" \\
-    --arg status "\$_cycle_status" \\
-    --arg cycle_id "\$CYCLE_ID" \\
-    --argjson built "\$_cycle_built" \\
-    --argjson skipped '[]' \\
-    --argjson alerts '[]' \\
-    --argjson tcr_count "\$_cycle_tcr" \\
-    --argjson duration_sec "\$_cycle_dur" \\
-    '{ts:\$ts, project:\$project, run_id:\$run_id, status:\$status,
-      cycle_id:\$cycle_id,
-      built:\$built, skipped:\$skipped, alerts:\$alerts,
-      tcr_count:\$tcr_count, duration_sec:\$duration_sec}' \\
-    >> "\$_runs_dst" 2>/dev/null || true
-fi
+# US-LOOP-005: now routed through _runs_append so timeout/worktree-setup-fail
+# share the same write logic. _runs_append is idempotent on run_id.
+_runs_append "\$_cycle_status" "\$_cycle_tcr" "\$_cycle_built" 2>/dev/null || true
 INNER
   chmod +x "$inner_path"
 
@@ -4543,7 +4601,7 @@ _changelog_lint_bullet() {
   if [ "${len:-0}" -gt 50 ]; then
     echo "over-length"
   fi
-  if printf '%s' "$stripped" | grep -qE '(^|[^A-Za-z0-9_])(docs|bin|tests|scripts)/'; then
+  if printf '%s' "$stripped" | grep -qE '(^|[^A-Za-z0-9_])(\.roll|docs|bin|tests|scripts)/'; then
     echo "path-fragment"
   fi
   return 0
@@ -4600,7 +4658,7 @@ _changelog_audit_bullet() {
 
   # Rule 3: file suffix / path fragment outside backticks.
   if printf '%s' "$stripped" | grep -qE '\.(md|sh|yml|ts|bats)([^A-Za-z0-9]|$)' \
-    || printf '%s' "$stripped" | grep -qE '(^|[^A-Za-z0-9_])(docs|bin|tests|scripts)/'; then
+    || printf '%s' "$stripped" | grep -qE '(^|[^A-Za-z0-9_])(\.roll|docs|bin|tests|scripts)/'; then
     echo "path-or-suffix"
   fi
 
@@ -4936,7 +4994,9 @@ _loop_is_doc_only_change() {
   local changed
   changed=$(git diff --name-only origin/main HEAD 2>/dev/null) || return 1
   [ -z "$changed" ] && return 1
-  echo "$changed" | grep -qvE '^(BACKLOG\.md|CHANGELOG\.md|PROPOSALS\.md|docs/|\.claude/)' && return 1
+  # Post-Phase-1: process artifacts moved into .roll/; user-facing docs at guide/ + site/.
+  # Legacy paths (BACKLOG.md, PROPOSALS.md, docs/) kept as fallback for pre-2.0 projects.
+  echo "$changed" | grep -qvE '^(\.roll/|CHANGELOG\.md|guide/|site/|\.claude/|BACKLOG\.md|PROPOSALS\.md|docs/)' && return 1
   return 0
 }
 

package/lib/roll-home.py

@@ -116,6 +116,26 @@ def _launchd_svc_state(service: str, slug: str) -> str:
     except Exception:
         return "installed-off"
 
+def _read_plist_schedule(service: str, slug: str) -> Optional[Dict[str, int]]:
+    """FIX-063: read actual Minute/Hour from launchd plist (truth source).
+    Returns {'minute': N, 'hour': N|None} or None if plist missing.
+    Dashboard must reflect what launchd actually fires, not a hardcoded default.
+    """
+    label = f"com.roll.{service}.{slug}"
+    plist = Path(os.path.expanduser("~/Library/LaunchAgents")) / f"{label}.plist"
+    if not plist.exists():
+        return None
+    try:
+        text = plist.read_text(errors="ignore")
+    except Exception:
+        return None
+    # Parse <key>Minute</key><integer>N</integer> (and Hour)
+    m = re.search(r"<key>Minute</key>\s*<integer>(\d+)</integer>", text)
+    h = re.search(r"<key>Hour</key>\s*<integer>(\d+)</integer>", text)
+    if not m:
+        return None
+    return {"minute": int(m.group(1)), "hour": int(h.group(1)) if h else None}
+
 def _dream_last_hours() -> Optional[int]:
     log = _shared_root() / "dream" / "log.md"
     if not log.exists():
@@ -469,12 +489,12 @@ def main() -> None:
             timestamp      = datetime.now().strftime("%H:%M"),
             state          = state,
             loop_state     = _launchd_svc_state("loop", slug),
-            loop_minute    = _ci("loop_minute", 38),
+            loop_minute    = (_read_plist_schedule("loop", slug) or {}).get("minute") or _ci("loop_minute", 38),
             loop_active_start = _ci("loop_active_start", 10),
             loop_active_end   = _ci("loop_active_end", 18),
             dream_state    = _launchd_svc_state("dream", slug),
-            dream_hour     = _ci("loop_dream_hour", 3),
-            dream_minute   = _ci("loop_dream_minute", 12),
+            dream_hour     = (_read_plist_schedule("dream", slug) or {}).get("hour") or _ci("loop_dream_hour", 3),
+            dream_minute   = (_read_plist_schedule("dream", slug) or {}).get("minute") or _ci("loop_dream_minute", 12),
             dream_last_hours = _dream_last_hours(),
             refactor_pending = refactor_pending,
             peer_last      = _peer_last(),

package/lib/roll-init.py

@@ -0,0 +1,101 @@
+#!/usr/bin/env python3
+"""roll-init — v2 terminal view for `roll init` (US-VIEW-008)."""
+from __future__ import annotations
+
+import argparse
+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 — 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)))
+
+
+def _op_marker(op: str) -> str:
+    if op == "+":
+        return c("green", "+", bold=True)
+    if op == "~":
+        return c("amber", "~", bold=True)
+    return c("dim", op)
+
+
+def render_demo(project_path: str = "~/myproject") -> None:
+    left  = "  " + c("blue", "INIT", bold=True) + c("dim", "  ·  ") + c("dim", "项目初始化")
+    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", "✓")
+        print(f"{num} {icon}  {label}")
+        for op, fname in files:
+            mark = _op_marker(op)
+            color = "green" if op == "+" else "amber"
+            print("       " + mark + "  " + c(color, fname))
+
+    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))
+    _divider("═")
+
+
+# ════════════════════════════════════════════════════════════════════════════
+# Entry point
+# ════════════════════════════════════════════════════════════════════════════
+
+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())
+
+
+if __name__ == "__main__":
+    main()

package/lib/roll-loop-status.py

@@ -701,11 +701,27 @@ def render(events, cron, state, backlog, *, days=3, lang="both", now=None,
           c("muted", "       ") +
           c("dim", "more   ") + c("blue", "roll loop --days 7"))
 
+def _read_plist_loop_minute() -> int:
+    """FIX-063: read actual loop Minute from launchd plist (truth source).
+    Falls back to 48 only when plist missing/unparseable.
+    """
+    import re as _re
+    slug = project_slug()
+    plist = Path(os.path.expanduser("~/Library/LaunchAgents")) / f"com.roll.loop.{slug}.plist"
+    if not plist.exists():
+        return 48
+    try:
+        text = plist.read_text(errors="ignore")
+    except Exception:
+        return 48
+    m = _re.search(r"<key>Minute</key>\s*<integer>(\d+)</integer>", text)
+    return int(m.group(1)) if m else 48
+
+
 def _next_cron_hint(state: Dict[str, str], zh: bool = False) -> str:
-    """Best-effort next-cron string. The real schedule lives in launchd/cron;
-    we only have access to last_run here, so we approximate to the next :48."""
+    """Compute next cron fire time from the actual launchd plist Minute (FIX-063)."""
     now = datetime.now().astimezone()
-    minute_target = 48  # bin/roll default; per-project may differ
+    minute_target = _read_plist_loop_minute()
     nxt = now.replace(minute=minute_target, second=0, microsecond=0)
     if nxt <= now:
         nxt += timedelta(hours=1)

package/package.json

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