@seanyao/roll 2026.518.4 → 2026.519.2

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.518.4"
+VERSION="2026.519.2"
 ROLL_HOME="${ROLL_HOME:-${HOME}/.roll}"
 ROLL_CONFIG="${ROLL_HOME}/config.yaml"
 ROLL_GLOBAL="${ROLL_HOME}/conventions/global"
@@ -913,15 +913,39 @@ _merge_claude_to_project() {
 # ═══════════════════════════════════════════════════════════════════════════════
 # COMMAND: init
 # Initialize or re-merge a project. Always operates on the current directory.
-# Fresh project: creates AGENTS.md + BACKLOG.md + docs/features/
+# Fresh project: creates AGENTS.md + .roll/backlog.md + .roll/features/
 # 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
   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
@@ -930,13 +954,20 @@ 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.
+    if _init_is_legacy_project "$project_dir"; then
+      _init_legacy_onboard_guide "$project_dir"
+      return 0
+    fi
   fi
 
   _merge_global_to_project "$project_dir"
   _merge_claude_to_project "$project_dir"
-  _write_backlog "$project_dir/BACKLOG.md"
-  _ensure_features_dir "$project_dir/docs/features"
-  _write_features_md "$project_dir/docs/features.md"
+  _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
 
   echo ""
@@ -953,6 +984,402 @@ cmd_init() {
   fi
 }
 
+# US-ONBOARD-006: Legacy detection
+# A project is "Legacy" if it has substantive code but no AGENTS.md to anchor
+# Roll conventions. Definition (per design doc §5.1): no AGENTS.md AND any of
+# src/ app/ lib/ pkg/ cmd/ contains ≥10 non-empty files.
+_init_is_legacy_project() {
+  local project_dir="$1"
+  local dir count
+  for dir in src app lib pkg cmd; do
+    if [[ -d "$project_dir/$dir" ]]; then
+      count=$(find "$project_dir/$dir" -type f -not -empty 2>/dev/null | wc -l | tr -d ' ')
+      if [[ "$count" -ge 10 ]]; then
+        return 0
+      fi
+    fi
+  done
+  return 1
+}
+
+# US-ONBOARD-006: Agent discovery + token consumption notice + onboard guidance.
+# Reuses _for_each_ai_tool to enumerate installed AI agents. Tells the user
+# which agent to open, why their tokens will be used, and what to do next.
+_init_legacy_onboard_guide() {
+  local project_dir="$1"
+  local count_summary
+  count_summary=$(_init_legacy_file_summary "$project_dir")
+
+  info "Detected: legacy project (${count_summary})  检测到遗留项目"
+  echo ""
+
+  # Enumerate installed agents by parsing ROLL_CONFIG inline.
+  # Output format in config: ai_<name>: <dir>|<config>|<src>
+  local installed=()
+  local missing=()
+  local _key _value _name _dir
+  while IFS=: read -r _key _value; do
+    [[ "$_key" =~ ^ai_ ]] || continue
+    _name="${_key#ai_}"
+    _dir="${_value%%|*}"
+    _dir="${_dir# }"            # trim leading space
+    _dir="${_dir/#\~/$HOME}"    # expand ~
+    if [[ -d "$_dir" ]]; then
+      installed+=("$_name")
+    else
+      missing+=("$_name")
+    fi
+  done < "$ROLL_CONFIG"
+
+  echo "  Onboarding 需要一个 AI agent 来读懂这个项目。检测到："
+  echo "  Onboarding requires an AI agent to read your code. Detected:"
+  echo ""
+  local n
+  if [[ ${#installed[@]} -gt 0 ]]; then
+    for n in "${installed[@]}"; do
+      printf "    %b✓%b %s   (installed)\n" "${GREEN}" "${NC}" "$n"
+    done
+  fi
+  if [[ ${#missing[@]} -gt 0 ]]; then
+    for n in "${missing[@]}"; do
+      printf "    %b✗%b %s   (not found)\n" "${RED}" "${NC}" "$n"
+    done
+  fi
+
+  if [[ ${#installed[@]} -eq 0 ]]; then
+    echo ""
+    err "No AI agent detected. Install one (e.g., 'claude', 'codex', 'kimi') and try again."
+    err "未检测到 AI agent。请先安装 (如 claude / codex / kimi) 后重试。"
+    return 1
+  fi
+
+  echo ""
+  echo "  后续过程会使用你的 agent 调用模型，token 消耗在你自己的账户上。"
+  echo "  Onboarding uses your agent to call models — tokens are billed to your account."
+  echo ""
+  echo "  代码与对话都留在你的 agent 工具里 —— Roll 本身不上传任何内容。"
+  echo "  Your code and conversation stay in your agent — Roll never uploads anything."
+  echo ""
+  echo "  下一步  Next step:"
+  echo ""
+  if [[ ${#installed[@]} -eq 1 ]]; then
+    echo "    Open ${installed[0]} and run:    $roll-onboard"
+  else
+    echo "    Open any installed agent and run:    \$roll-onboard"
+  fi
+  echo ""
+  echo "  完成对话后回到这里运行  After the conversation, return and run:"
+  echo "    roll init --apply"
+  echo ""
+}
+
+# Helper: human-readable summary of why this is detected as legacy.
+_init_legacy_file_summary() {
+  local project_dir="$1"
+  local dir count parts=()
+  for dir in src app lib pkg cmd; do
+    if [[ -d "$project_dir/$dir" ]]; then
+      count=$(find "$project_dir/$dir" -type f -not -empty 2>/dev/null | wc -l | tr -d ' ')
+      if [[ "$count" -ge 10 ]]; then
+        parts+=("${count} files in ${dir}/")
+      fi
+    fi
+  done
+  echo "no AGENTS.md, ${parts[*]}"
+}
+
+# US-ONBOARD-009: roll init --apply
+# Consume .roll/onboard-plan.yaml (produced by $roll-onboard skill) and execute
+# all side effects: create .roll/ structure per scope, sync AI tools, write
+# .gitignore based on user's Q7 choice.
+#
+# Plan validation is delegated to lib/roll-plan-validate.py to avoid bash YAML
+# parsing fragility.
+_init_apply() {
+  local project_dir; project_dir="$(pwd)"
+  local plan="${project_dir}/.roll/onboard-plan.yaml"
+  local validator="${ROLL_PKG_DIR}/lib/roll-plan-validate.py"
+
+  if [[ ! -f "$plan" ]]; then
+    err "No onboard plan found at .roll/onboard-plan.yaml  未找到 onboard 计划。"
+    echo "" >&2
+    echo "  Run \$roll-onboard in your AI agent first to generate the plan." >&2
+    echo "  请先在 AI agent 里运行 \$roll-onboard 生成 plan，再回来执行 apply。" >&2
+    return 1
+  fi
+
+  if [[ ! -f "$validator" ]]; then
+    err "Plan validator missing: $validator  校验器缺失。"
+    return 1
+  fi
+
+  # Validate plan (schema + generated_at freshness + version)
+  if ! python3 "$validator" "$plan"; then
+    err "Plan validation failed. See errors above.  Plan 校验失败。"
+    echo "" >&2
+    echo "  If the plan is stale (>24h), regenerate by running \$roll-onboard again." >&2
+    return 1
+  fi
+
+  info "Applying onboard plan...  正在应用 onboard 计划..."
+  _ROLL_MERGE_SUMMARY=()
+
+  # Read scope from plan (simple grep — validator confirmed structure)
+  local approved
+  approved=$(python3 -c "
+import yaml, sys
+p = yaml.safe_load(open('$plan'))
+print(' '.join(p.get('scope', {}).get('approved', [])))
+" 2>/dev/null || echo "")
+
+  _merge_global_to_project "$project_dir"
+  _merge_claude_to_project "$project_dir"
+
+  # Create .roll/ artifacts based on scope.approved
+  if [[ " $approved " == *" backlog "* ]]; then
+    _write_backlog "$project_dir/.roll/backlog.md"
+  fi
+  if [[ " $approved " == *" features "* ]]; then
+    _ensure_features_dir "$project_dir/.roll/features"
+    _write_features_md "$project_dir/.roll/features.md"
+  fi
+  if [[ " $approved " == *" domain "* ]]; then
+    mkdir -p "$project_dir/.roll/domain"
+  fi
+  if [[ " $approved " == *" briefs "* ]]; then
+    mkdir -p "$project_dir/.roll/briefs"
+  fi
+
+  print_merge_summary
+
+  # Q7: .gitignore preference
+  local gitignore_roll
+  gitignore_roll=$(python3 -c "
+import yaml
+p = yaml.safe_load(open('$plan'))
+print('true' if p.get('privacy', {}).get('gitignore_dot_roll', False) else 'false')
+" 2>/dev/null || echo "false")
+
+  if [[ "$gitignore_roll" == "true" ]]; then
+    local gi="$project_dir/.gitignore"
+    if ! grep -qFx ".roll/" "$gi" 2>/dev/null; then
+      echo ".roll/" >> "$gi"
+      ok "Added .roll/ to .gitignore  已将 .roll/ 加入 .gitignore"
+    fi
+  fi
+
+  echo ""
+  info "Syncing conventions to AI tools...  正在同步约定到 AI 工具..."
+  _sync_conventions
+  echo ""
+
+  ok "Onboard apply complete.  Onboard 应用完成。"
+}
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# cmd_migrate
+# US-ONBOARD-003: One-shot migration from old project layout to .roll/ structure.
+#
+# Moves process artifacts (.roll/backlog.md, .roll/proposals.md, .roll/features/, .roll/briefs/,
+# .roll/dream/, .roll/design/, .roll/domain/) into .roll/. Also relocates user docs
+# (guide/ → guide/, site/ → site/, site/slides/ → site/slides/).
+#
+# Three-state idempotency:
+#   - old-only:   execute migration via git mv (single atomic commit)
+#   - new-only:   no-op with "already migrated" message
+#   - both:       error with conflict list (manual resolution required)
+#   - neither:    no-op with "nothing to migrate"
+# ═══════════════════════════════════════════════════════════════════════════════
+cmd_migrate() {
+  local dry_run=false
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      --dry-run|-n) dry_run=true; shift ;;
+      -h|--help) _migrate_help; return 0 ;;
+      *) err "Unknown arg: $1  未知参数: $1"; return 1 ;;
+    esac
+  done
+
+  # Must be in a git repo (git mv preserves history)
+  if ! git rev-parse --git-dir >/dev/null 2>&1; then
+    err "Not a git repository. roll migrate requires git.  当前目录不是 git 仓库。"
+    return 1
+  fi
+
+  # Build canonical migration plan (read from stdout to avoid bash 4.3+ nameref)
+  local -a moves=()
+  while IFS= read -r _line; do moves+=("$_line"); done < <(_migrate_build_moves)
+
+  # Detect state: do old paths exist? does .roll/ exist?
+  local has_old=false has_new=false
+  [[ -e .roll ]] && has_new=true
+  local m src
+  for m in "${moves[@]}"; do
+    src="${m%%|*}"
+    if [[ -e "$src" ]]; then
+      has_old=true
+      break
+    fi
+  done
+
+  # Three-state dispatch
+  if [[ "$has_new" == "true" && "$has_old" == "true" ]]; then
+    err "Both old and new structures exist (partial migration detected).  老结构与新结构同时存在（部分迁移）。"
+    echo "" >&2
+    echo "Conflicting paths:  冲突路径：" >&2
+    for m in "${moves[@]}"; do
+      src="${m%%|*}"
+      local tgt="${m##*|}"
+      if [[ -e "$src" && -e "$tgt" ]]; then
+        echo "  - $src  AND  $tgt  both exist" >&2
+      fi
+    done
+    echo "" >&2
+    err "Resolve manually then re-run.  请手动解决冲突后重新运行。"
+    return 1
+  fi
+
+  if [[ "$has_new" == "true" && "$has_old" == "false" ]]; then
+    ok "Already migrated. .roll/ exists, no old paths found.  已迁移，无需重复操作。"
+    return 0
+  fi
+
+  if [[ "$has_old" == "false" ]]; then
+    info "No old structure detected. Nothing to migrate.  未发现老结构，无需迁移。"
+    return 0
+  fi
+
+  # State: old-only — proceed. Filter to actually existing paths.
+  local -a active_moves=()
+  for m in "${moves[@]}"; do
+    src="${m%%|*}"
+    [[ -e "$src" ]] && active_moves+=("$m")
+  done
+
+  if [[ ${#active_moves[@]} -eq 0 ]]; then
+    warn "Old structure markers found but no migratable files.  未找到可迁移文件。"
+    return 0
+  fi
+
+  if [[ "$dry_run" == "true" ]]; then
+    _migrate_preview "${active_moves[@]}"
+    return 0
+  fi
+
+  # Real execution requires clean working tree (we'll create a single commit)
+  if ! git diff --quiet --ignore-submodules HEAD 2>/dev/null; then
+    err "Working tree not clean. Commit or stash changes before running migrate.  工作区有未提交改动，请先 commit 或 stash。"
+    return 1
+  fi
+
+  _migrate_execute "${active_moves[@]}"
+}
+
+# Build canonical migration plan as "src|target" pairs (one per line).
+# Single source of truth for what migrates where.
+# Returns via stdout (bash 3.2-compatible — no nameref).
+_migrate_build_moves() {
+  # Order matters: directory-renames must precede moves whose target_dir is
+  # the same dir. Otherwise mkdir -p pre-creates the target, and git mv then
+  # places the source INSIDE rather than renaming. Specifically:
+  #   - docs/site → site   must precede docs/intro → site/slides
+  #   - docs/guide/en → guide/en  must precede docs/practices/engineering-common-sense.md
+  #
+  # IMPORTANT: the LEFT side of each mapping is a literal OLD path. These must
+  # NOT be sed'd during Story 5 code-ref migration — they drive the migration
+  # for OTHER projects (and self-migrate idempotency).
+  cat << 'EOF'
+BACKLOG.md|.roll/backlog.md
+PROPOSALS.md|.roll/proposals.md
+docs/features.md|.roll/features.md
+docs/features|.roll/features
+docs/briefs|.roll/briefs
+docs/dream|.roll/dream
+docs/design|.roll/design
+docs/domain|.roll/domain
+docs/practices/loop-autorun-verification.md|.roll/verification/loop-autorun-verification.md
+docs/site|site
+docs/intro|site/slides
+docs/guide/en|guide/en
+docs/guide/zh|guide/zh
+docs/practices/engineering-common-sense.md|guide/en/practices/engineering-common-sense.md
+EOF
+}
+
+_migrate_preview() {
+  info "Migration preview (dry-run):  迁移预览（dry-run）"
+  echo ""
+  printf "  %-60s → %s\n" "Old path  老路径" "New path  新路径"
+  local sep; sep=$(printf '─%.0s' {1..100})
+  printf "  %s\n" "$sep"
+  local m
+  for m in "$@"; do
+    local src="${m%%|*}" tgt="${m##*|}"
+    printf "  %-60s → %s\n" "$src" "$tgt"
+  done
+  echo ""
+  info "Run without --dry-run to execute.  去掉 --dry-run 即可真实执行。"
+}
+
+_migrate_execute() {
+  info "Migrating ${#@} paths via git mv...  正在通过 git mv 迁移 ${#@} 个路径..."
+  local moved=0 m
+  for m in "$@"; do
+    local src="${m%%|*}" tgt="${m##*|}"
+    local target_dir; target_dir=$(dirname "$tgt")
+    [[ -d "$target_dir" ]] || mkdir -p "$target_dir"
+    git mv "$src" "$tgt" || {
+      err "git mv failed: $src → $tgt"
+      err "Aborting; previous moves are staged but not committed. Run 'git reset --hard' to undo.  已 stage 但未 commit，运行 'git reset --hard' 回滚。"
+      return 1
+    }
+    moved=$((moved + 1))
+  done
+  # Clean up empty docs/ shells
+  if [[ -d "docs" ]]; then
+    find docs -type d -empty -delete 2>/dev/null || true
+  fi
+  # Single atomic commit
+  git commit --quiet -m "Migrate project layout to .roll/ structure
+
+Atomic migration via 'roll migrate' command. Process artifacts moved
+from root and docs/ into .roll/; user docs relocated to guide/ and site/.
+
+Paths migrated: ${moved}"
+  ok "Migrated ${moved} paths in a single commit.  已在单 commit 中迁移 ${moved} 个路径。"
+  echo ""
+  echo "  Next steps  下一步："
+  echo "    git log -1                    # Inspect the migration commit"
+  echo "    roll status                   # Verify new structure"
+}
+
+_migrate_help() {
+  cat << 'EOF'
+Usage: roll migrate [--dry-run]
+
+Migrate this project's process artifacts (.roll/backlog.md, .roll/proposals.md,
+.roll/features/, .roll/briefs/, .roll/dream/, .roll/design/, .roll/domain/)
+into a .roll/ directory. Also relocates guide/ → guide/,
+site/ → site/, site/slides/ → site/slides/.
+
+Options:
+  --dry-run, -n   Show what would be moved without modifying files
+  --help, -h      Show this help
+
+Three-state idempotency:
+  - Only old paths present  → migration executes (single atomic commit)
+  - Only .roll/ present     → no-op (already migrated)
+  - Both present            → error with conflict list (manual review)
+  - Neither                 → no-op (nothing to migrate)
+
+Preconditions:
+  - Current directory is a git repository
+  - Working tree is clean (commit or stash changes first)
+
+Uses git mv to preserve file history. On success, produces a single commit.
+EOF
+}
+
 # ─── Helper: print a tidy summary of merge actions ───────────────────────────
 print_merge_summary() {
   if [[ ${#_ROLL_MERGE_SUMMARY[@]} -eq 0 ]]; then
@@ -1019,12 +1446,13 @@ scan_project_type_from_files() {
   fi
 }
 
-# ─── Helper: write starter BACKLOG.md (no-op if exists) ──────────────────────
+# ─── Helper: write starter .roll/backlog.md (no-op if exists) ──────────────────────
 _write_backlog() {
   if [[ -f "$1" ]]; then
-    _ROLL_MERGE_SUMMARY+=("unchanged|BACKLOG.md")
+    _ROLL_MERGE_SUMMARY+=("unchanged|.roll/backlog.md")
     return
   fi
+  mkdir -p "$(dirname "$1")"
   cat > "$1" << 'EOF'
 # Project Backlog
 
@@ -1036,25 +1464,25 @@ _write_backlog() {
 | ID | Problem | Status |
 |----|---------|--------|
 EOF
-  ok "Created: BACKLOG.md"
-  _ROLL_MERGE_SUMMARY+=("created|BACKLOG.md")
+  ok "Created: .roll/backlog.md"
+  _ROLL_MERGE_SUMMARY+=("created|.roll/backlog.md")
 }
 
 _ensure_features_dir() {
   if [[ -d "$1" ]]; then
-    _ROLL_MERGE_SUMMARY+=("unchanged|docs/features/")
+    _ROLL_MERGE_SUMMARY+=("unchanged|.roll/features/")
     return
   fi
 
   mkdir -p "$1"
-  ok "Created: docs/features/"
-  _ROLL_MERGE_SUMMARY+=("created|docs/features/")
+  ok "Created: .roll/features/"
+  _ROLL_MERGE_SUMMARY+=("created|.roll/features/")
 }
 
-# ─── Helper: write starter docs/features.md (no-op if exists) ────────────────
+# ─── Helper: write starter .roll/features.md (no-op if exists) ────────────────
 _write_features_md() {
   if [[ -f "$1" ]]; then
-    _ROLL_MERGE_SUMMARY+=("unchanged|docs/features.md")
+    _ROLL_MERGE_SUMMARY+=("unchanged|.roll/features.md")
     return
   fi
   mkdir -p "$(dirname "$1")"
@@ -1069,8 +1497,8 @@ _write_features_md() {
 
 <!-- Add feature entries here as epics are completed -->
 EOF
-  ok "Created: docs/features.md"
-  _ROLL_MERGE_SUMMARY+=("created|docs/features.md")
+  ok "Created: .roll/features.md"
+  _ROLL_MERGE_SUMMARY+=("created|.roll/features.md")
 }
 
 # ═══════════════════════════════════════════════════════════════════════════════
@@ -1250,8 +1678,8 @@ _status_loop_overview() {
     fi
 
     local todo_count=0
-    if [[ -z "$path_note" && -f "${proj_path}/BACKLOG.md" ]]; then
-      todo_count=$(grep -c '📋 Todo' "${proj_path}/BACKLOG.md" 2>/dev/null; true)
+    if [[ -z "$path_note" && -f "${proj_path}/.roll/backlog.md" ]]; then
+      todo_count=$(grep -c '📋 Todo' "${proj_path}/.roll/backlog.md" 2>/dev/null; true)
     fi
 
     echo -e "  ${state_icon} ${proj_name}${path_note}   ${schedule}   ${todo_count} pending"
@@ -1998,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
@@ -2358,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
@@ -2367,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"
@@ -2389,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
@@ -2448,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
 
@@ -2501,7 +2980,7 @@ if [ "\$_USE_WORKTREE" = "1" ]; then
       _cycle_status="built"
       _cycle_tcr=\$(cd "\$WT" && git log --oneline origin/main..HEAD -- 2>/dev/null | grep -c ' tcr:' || echo 0)
       if command -v jq >/dev/null 2>&1; then
-        _cycle_built=\$(cd "\$WT" && git diff origin/main -- BACKLOG.md 2>/dev/null | grep '✅ Done' | grep -oE '\[[A-Z]+-[0-9]+\]' | sed 's/^.//;s/.\$//' | jq -R -s 'split("\n") | map(select(length>0))' 2>/dev/null || echo "[]")
+        _cycle_built=\$(cd "\$WT" && git diff origin/main -- .roll/backlog.md 2>/dev/null | grep '✅ Done' | grep -oE '\[[A-Z]+-[0-9]+\]' | sed 's/^.//;s/.\$//' | jq -R -s 'split("\n") | map(select(length>0))' 2>/dev/null || echo "[]")
       fi
     fi
   fi
@@ -2549,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
@@ -2558,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
@@ -2573,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
@@ -2592,29 +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" \\
-    --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,
-      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"
 
@@ -2851,7 +3322,7 @@ _agent_skill_cmd() {
     return 1
   }
   # Cron-installed skills (dream / brief / loop) run autonomously and need to
-  # Edit files (docs/dream/, docs/briefs/, BACKLOG, etc.). Claude Code 2.1.x's
+  # Edit files (.roll/dream/, .roll/briefs/, BACKLOG, etc.). Claude Code 2.1.x's
   # pre-write approval UX silently blocks `claude -p` from applying edits in
   # non-interactive pipe mode — bypass it for the cron context.
   _agent_bypass_claude_perms
@@ -3083,6 +3554,9 @@ _loop_test() {
 }
 
 _loop_status() {
+  # FIX-060: backfill merged PRs before rendering — independent of cycle ticks,
+  # so dashboard reflects merges that happened while loop was paused.
+  _loop_backfill_merged >/dev/null 2>&1 || true
   # ROLL_UI=v2 (default) routes to the redesigned Python view.
   # Set ROLL_UI=v1 to fall back to the legacy bash implementation.
   if [[ "${ROLL_UI:-v2}" == "v2" ]]; then
@@ -3332,6 +3806,9 @@ _loop_runs() {
     esac
   done
 
+  # FIX-060: refresh merged status before reading, so paused-window merges show up.
+  _loop_backfill_merged >/dev/null 2>&1 || true
+
   if [[ ! -f "$_LOOP_RUNS" ]] || [[ ! -s "$_LOOP_RUNS" ]]; then
     echo "No loop runs yet  尚无 loop 运行记录"
     return 0
@@ -3363,7 +3840,7 @@ _loop_runs() {
   [[ "$(uname)" == "Darwin" ]] && _is_darwin="1"
 
   _LOOP_RUNS_BACKLOG=""
-  [[ -f "$project_path/BACKLOG.md" ]] && _LOOP_RUNS_BACKLOG=$(cat "$project_path/BACKLOG.md")
+  [[ -f "$project_path/.roll/backlog.md" ]] && _LOOP_RUNS_BACKLOG=$(cat "$project_path/.roll/backlog.md")
 
   while IFS= read -r line; do
     [[ -z "$line" ]] && continue
@@ -3671,7 +4148,7 @@ _loop_clear_heal_state() {
 }
 
 # Verify TCR rhythm after a story completes. Returns 0 if ok, 1 if no TCR commits.
-# On failure: reverts story in BACKLOG.md to 📋 Todo and writes ALERT.
+# On failure: reverts story in .roll/backlog.md to 📋 Todo and writes ALERT.
 _loop_enforce_tcr() {
   local story_id="$1"
   local started_at="${2:-}"
@@ -3682,10 +4159,10 @@ _loop_enforce_tcr() {
 
   if [[ "$count" -eq 0 ]]; then
     # Revert story status
-    if [[ -f "BACKLOG.md" ]]; then
+    if [[ -f ".roll/backlog.md" ]]; then
       local tmp; tmp=$(mktemp)
-      sed "/\[${story_id}\]/s/ | ✅ Done |/ | 📋 Todo |/" BACKLOG.md > "$tmp" \
-        && mv "$tmp" BACKLOG.md
+      sed "/\[${story_id}\]/s/ | ✅ Done |/ | 📋 Todo |/" .roll/backlog.md > "$tmp" \
+        && mv "$tmp" .roll/backlog.md
     fi
 
     # Write ALERT
@@ -3725,7 +4202,7 @@ EOF
 #   Stdout (on exit 1 due to unsatisfied deps): space-separated unsatisfied IDs.
 _loop_check_depends_on() {
   local id="$1"
-  local backlog="${2:-BACKLOG.md}"
+  local backlog="${2:-.roll/backlog.md}"
   [ -n "$id" ] || return 1
   [ -f "$backlog" ] || return 1
 
@@ -3762,7 +4239,7 @@ _loop_check_depends_on() {
 #   Exit 1: tag absent, story-id not found, or backlog missing.
 _loop_is_manual_only() {
   local id="$1"
-  local backlog="${2:-BACKLOG.md}"
+  local backlog="${2:-.roll/backlog.md}"
   [ -n "$id" ] || return 1
   [ -f "$backlog" ] || return 1
 
@@ -4072,7 +4549,7 @@ _loop_pr_claimed_stories() {
     [ -n "$branch" ] || continue
     local content
     content=$(gh -R "$slug" api \
-      "repos/${slug}/contents/BACKLOG.md?ref=${branch}" \
+      "repos/${slug}/contents/.roll/backlog.md?ref=${branch}" \
       -H "Accept: application/vnd.github.raw" 2>/dev/null) || continue
     [ -n "$content" ] || continue
     local ids
@@ -4124,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
@@ -4181,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
 
@@ -4511,13 +4988,15 @@ _loop_wait_pr_merge() {
 
 # _loop_is_doc_only_change
 #   Returns 0 if every file changed since origin/main is doc-only
-#   (BACKLOG.md, CHANGELOG.md, PROPOSALS.md, docs/, .claude/).
+#   (.roll/backlog.md, CHANGELOG.md, .roll/proposals.md, docs/, .claude/).
 #   Returns 1 if any code file changed or there are no changes.
 _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
 }
 
@@ -4556,6 +5035,60 @@ _loop_publish_doc_pr() {
   return 0
 }
 
+# _loop_backfill_merged [runs_jsonl_path]
+#   FIX-060: independent PR-merge backfill. Walks runs.jsonl, finds entries
+#   with status:"built" and a cycle_id field, queries GitHub for the matching
+#   loop/cycle-<id> PR, and rewrites entries whose PR is MERGED to
+#   status:"merged" with merged_at + merge_commit fields.
+#
+#   Designed to run from the outer runner BEFORE the pause check, so the
+#   scan fires every scheduled tick even when the loop is paused — fixes
+#   the pre-FIX-060 behaviour where merge backfill only happened at next
+#   cycle startup and stalled forever during pause.
+#
+#   Lenient: returns 0 when gh is missing, slug is unresolvable, jq is
+#   missing, or runs.jsonl does not exist. Atomic rewrite via temp file.
+_loop_backfill_merged() {
+  local runs_path="${1:-${HOME}/.shared/roll/loop/runs.jsonl}"
+  [ -f "$runs_path" ] || return 0
+  command -v gh >/dev/null 2>&1 || return 0
+  command -v jq >/dev/null 2>&1 || return 0
+  local slug; _gh_resolve slug || return 0
+
+  local tmp="${runs_path}.tmp.$$"
+  : > "$tmp"
+  local line status cycle_id branch view_json state merged_at merge_commit
+  while IFS= read -r line; do
+    [ -z "$line" ] && continue
+    status=$(printf '%s' "$line" | jq -r '.status // ""' 2>/dev/null)
+    cycle_id=$(printf '%s' "$line" | jq -r '.cycle_id // ""' 2>/dev/null)
+    if [ "$status" != "built" ] || [ -z "$cycle_id" ]; then
+      printf '%s\n' "$line" >> "$tmp"
+      continue
+    fi
+    branch="loop/cycle-${cycle_id}"
+    view_json=$(gh -R "$slug" pr view "$branch" --json state,mergedAt,mergeCommit 2>/dev/null) || view_json=""
+    if [ -z "$view_json" ]; then
+      printf '%s\n' "$line" >> "$tmp"
+      continue
+    fi
+    state=$(printf '%s' "$view_json" | jq -r '.state // ""' 2>/dev/null)
+    if [ "$state" != "MERGED" ]; then
+      printf '%s\n' "$line" >> "$tmp"
+      continue
+    fi
+    merged_at=$(printf '%s' "$view_json" | jq -r '.mergedAt // ""' 2>/dev/null)
+    merge_commit=$(printf '%s' "$view_json" | jq -r '.mergeCommit.oid // ""' 2>/dev/null)
+    printf '%s' "$line" | jq -c \
+      --arg merged_at "$merged_at" \
+      --arg merge_commit "$merge_commit" \
+      '.status = "merged" | .merged_at = $merged_at | .merge_commit = $merge_commit' \
+      >> "$tmp" 2>/dev/null || printf '%s\n' "$line" >> "$tmp"
+  done < "$runs_path"
+  mv "$tmp" "$runs_path" 2>/dev/null || rm -f "$tmp"
+  return 0
+}
+
 _loop_monitor() {
   local interval="${1:-3}"
   local project_path; project_path=$(pwd -P)
@@ -4637,7 +5170,7 @@ _loop_monitor() {
     # Queue: pending items
     echo ""
     echo -e "  ${BOLD}Queue  待处理队列${NC}"
-    local backlog="BACKLOG.md"
+    local backlog=".roll/backlog.md"
     if [[ -f "$backlog" ]]; then
       local queue_count=0
       local fix_pending us_pending refactor_pending
@@ -4677,7 +5210,7 @@ _loop_monitor() {
 
       [[ $queue_count -eq 0 ]] && echo -e "    ${GREEN}✓ empty${NC}"
     else
-      echo "    BACKLOG.md not found"
+      echo "    .roll/backlog.md not found"
     fi
 
     # Log tail (launchd.log)
@@ -4747,7 +5280,7 @@ for line in sys.stdin:
 # ═══════════════════════════════════════════════════════════════════════════════
 
 cmd_brief() {
-  local briefs_dir="docs/briefs"
+  local briefs_dir=".roll/briefs"
   local latest; latest=$(ls "${briefs_dir}"/*.md 2>/dev/null | sort | tail -1 || true)
 
   if [[ -z "$latest" ]]; then
@@ -4816,7 +5349,7 @@ PYEOF
 _backlog_set_status() {
   local pattern="$1"
   local new_status="$2"
-  local backlog="BACKLOG.md"
+  local backlog=".roll/backlog.md"
   python3 -c "
 import sys, re
 pattern, new_status, filename = sys.argv[1], sys.argv[2], sys.argv[3]
@@ -4947,9 +5480,9 @@ cmd_ci() {
 }
 
 cmd_backlog() {
-  local backlog="BACKLOG.md"
+  local backlog=".roll/backlog.md"
   if [[ ! -f "$backlog" ]]; then
-    err "BACKLOG.md not found — run 'roll init' first  未找到 BACKLOG.md，请先运行 roll init"
+    err ".roll/backlog.md not found — run 'roll init' first  未找到 .roll/backlog.md，请先运行 roll init"
     return 1
   fi
 
@@ -5095,19 +5628,19 @@ _dash_git_status() {
   fi
 }
 
-# ② Loop layer: extract in-progress story id|title|feature-link from BACKLOG.md.
+# ② Loop layer: extract in-progress story id|title|feature-link from .roll/backlog.md.
 # Output empty if no row's *status column* is 🔨 In Progress (substring matches
 # anywhere on the row would catch description text that mentions the emoji).
 _dash_in_progress_story() {
-  [[ -f "BACKLOG.md" ]] || return 0
+  [[ -f ".roll/backlog.md" ]] || return 0
   local row
-  row=$(grep -F '| 🔨 In Progress |' BACKLOG.md | head -1) || return 0
+  row=$(grep -F '| 🔨 In Progress |' .roll/backlog.md | head -1) || return 0
   [[ -z "$row" ]] && return 0
   local id desc
   id=$(echo "$row" | grep -oE '(US|FIX|REFACTOR)-[A-Z]*-?[0-9]+' | head -1)
   desc=$(echo "$row" | awk -F'|' '{print $3}' | sed 's/^ *//;s/ *$//' | cut -c1-60)
   local link
-  link=$(echo "$row" | grep -oE 'docs/features/[^)]+' | head -1 || true)
+  link=$(echo "$row" | grep -oE '.roll/features/[^)]+' | head -1 || true)
   printf '%s|%s|%s' "$id" "$desc" "$link"
 }
 
@@ -5140,8 +5673,8 @@ _dash_last_dream_hours() {
 
 # ② Dream layer: count of REFACTOR-XXX rows currently 📋 Todo in BACKLOG.
 _dash_refactor_pending() {
-  [[ -f "BACKLOG.md" ]] || { echo 0; return; }
-  grep -E '^\| REFACTOR-' BACKLOG.md 2>/dev/null | grep -F '| 📋 Todo |' | wc -l | tr -d ' '
+  [[ -f ".roll/backlog.md" ]] || { echo 0; return; }
+  grep -E '^\| REFACTOR-' .roll/backlog.md 2>/dev/null | grep -F '| 📋 Todo |' | wc -l | tr -d ' '
 }
 
 # ② Peer layer: last result + days ago from peer log, empty if no log.
@@ -5161,11 +5694,11 @@ _dash_last_peer() {
 
 # ③ Pipeline counts → Idea Backlog Build (Verify/Release reserved).
 _dash_pipeline_counts() {
-  [[ -f "BACKLOG.md" ]] || { echo "0 0 0 0 0"; return; }
+  [[ -f ".roll/backlog.md" ]] || { echo "0 0 0 0 0"; return; }
   local idea backlog build
-  idea=$(grep -E '^\| IDEA-' BACKLOG.md 2>/dev/null | grep -F '| 📋 Todo |' | wc -l | tr -d ' ')
-  backlog=$(grep -E '^\| (\[?US-|FIX-|REFACTOR-)' BACKLOG.md 2>/dev/null | grep -F '| 📋 Todo |' | wc -l | tr -d ' ')
-  build=$(grep -F '| 🔨 In Progress |' BACKLOG.md 2>/dev/null | wc -l | tr -d ' ')
+  idea=$(grep -E '^\| IDEA-' .roll/backlog.md 2>/dev/null | grep -F '| 📋 Todo |' | wc -l | tr -d ' ')
+  backlog=$(grep -E '^\| (\[?US-|FIX-|REFACTOR-)' .roll/backlog.md 2>/dev/null | grep -F '| 📋 Todo |' | wc -l | tr -d ' ')
+  build=$(grep -F '| 🔨 In Progress |' .roll/backlog.md 2>/dev/null | wc -l | tr -d ' ')
   printf '%s %s %s 0 0' "$idea" "$backlog" "$build"
 }
 
@@ -5235,10 +5768,10 @@ _dash_alert_count() {
   grep '^# ALERT' "$_LOOP_ALERT" 2>/dev/null | wc -l | tr -d ' '
 }
 
-# ⑤ Pending proposal count — "## PROPOSAL:" entries in PROPOSALS.md.
+# ⑤ Pending proposal count — "## PROPOSAL:" entries in .roll/proposals.md.
 _dash_proposal_count() {
-  [[ -f "PROPOSALS.md" ]] || { echo 0; return; }
-  grep '^## PROPOSAL' PROPOSALS.md 2>/dev/null | wc -l | tr -d ' '
+  [[ -f ".roll/proposals.md" ]] || { echo 0; return; }
+  grep '^## PROPOSAL' .roll/proposals.md 2>/dev/null | wc -l | tr -d ' '
 }
 
 # ⑤ Release-ready signal — true iff there are releasable commits since the
@@ -5256,7 +5789,7 @@ _dash_release_ready() {
     | wc -l | tr -d ' ')
   [[ "${commits_with_code:-0}" -gt 0 ]] || return 1
   local latest
-  latest=$(ls docs/briefs/*.md 2>/dev/null | sort | tail -1 || true)
+  latest=$(ls .roll/briefs/*.md 2>/dev/null | sort | tail -1 || true)
   [[ -z "$latest" ]] && return 1
   grep -qE '✅ 可发版|Release ready' "$latest" 2>/dev/null
 }
@@ -5434,7 +5967,7 @@ _legacy_home() {
     printf "    ${GREEN}✓ AI 自驱中 — 无需介入${NC}\n"
   else
     (( alerts > 0 )) && printf "    ${RED}⚠ %s ALERT${NC}          run: roll alert\n" "$alerts"
-    (( proposals > 0 )) && printf "    ${YELLOW}📋 %s PROPOSAL${NC}      see: PROPOSALS.md\n" "$proposals"
+    (( proposals > 0 )) && printf "    ${YELLOW}📋 %s PROPOSAL${NC}      see: .roll/proposals.md\n" "$proposals"
     $release_ready && printf "    ${GREEN}✓ Release ready${NC}    run: roll release\n"
   fi
   echo ""
@@ -5443,7 +5976,7 @@ _legacy_home() {
   printf "  ${BOLD}⏰ Schedules & Last Brief${NC}\n"
   printf "    loop :%02d · dream %02d:%02d · brief %02d:%02d\n" \
     "$loop_minute" "$dream_hour" "$dream_minute" "$brief_hour" "$brief_minute"
-  local latest_brief; latest_brief=$(ls docs/briefs/*.md 2>/dev/null | sort | tail -1 || true)
+  local latest_brief; latest_brief=$(ls .roll/briefs/*.md 2>/dev/null | sort | tail -1 || true)
   if [[ -n "$latest_brief" ]]; then
     local mod_time now age summary
     mod_time=$(stat -c %Y "$latest_brief" 2>/dev/null || stat -f %m "$latest_brief" 2>/dev/null || echo 0)
@@ -5483,7 +6016,7 @@ _legacy_help() {
   echo "Commands:"
   echo "  setup [-f]             [Machine] First-time install or re-sync             首次安装或重新同步"
   echo "  update                 [Upgrade] npm install latest + re-sync             一键升级到最新版"
-  echo "  init                   [Project] Create AGENTS.md + BACKLOG.md + docs/     初始化项目工作流文件"
+  echo "  init                   [Project] Create AGENTS.md + .roll/backlog.md + docs/     初始化项目工作流文件"
   echo "  status                 [Diagnostic] Show current state                    显示当前状态"
   echo "  peer                   [Peer Review] Cross-agent negotiation               跨 Agent 协商对审"
   echo "  loop <on|off|now|status|monitor|resume|reset>  [Autonomous] Manage scheduled BACKLOG executor  管理自主执行循环"
@@ -5517,14 +6050,83 @@ _help() {
   fi
 }
 
+# ═══════════════════════════════════════════════════════════════════════════════
+# _check_structure — US-ONBOARD-004
+#
+# Refuse to run project commands on legacy directory structure. Pushes users
+# toward `roll migrate` rather than letting commands silently operate on old
+# paths and produce confusing results.
+#
+# Exempt commands (always allowed regardless of structure):
+#   setup, update, version/--version/-v, help/--help/-h, migrate, doctor
+#   "" (no command — shows home/help)
+#   init — has its own structure-aware logic inside cmd_init
+#
+# Detection walks from pwd up to git root (or stays at pwd if not in a git repo).
+# Decision: old structure markers present AND no .roll/ → refuse.
+#
+# Bypass: ROLL_SKIP_STRUCTURE_CHECK=1 (used by integration tests until Story 5
+# migrates the test fixtures to new structure).
+# ═══════════════════════════════════════════════════════════════════════════════
+_check_structure() {
+  [[ "${ROLL_SKIP_STRUCTURE_CHECK:-0}" == "1" ]] && return 0
+
+  local cmd="$1"
+  case "$cmd" in
+    setup|update|migrate|doctor|version|--version|-v|help|--help|-h|"") return 0 ;;
+    init) return 0 ;;  # cmd_init handles its own structure logic
+  esac
+
+  # Determine project root: git root if available, else pwd
+  local root
+  if root=$(git rev-parse --show-toplevel 2>/dev/null); then
+    :
+  else
+    root="$(pwd -P)"
+  fi
+
+  # If new structure exists, allow
+  [[ -d "$root/.roll" ]] && return 0
+
+  # Check for legacy structure markers (literal old-path strings — must NOT be
+  # rewritten during Story 5 code-ref migration; this is the detection logic
+  # for pre-2.0 user projects).
+  if [[ -f "$root/BACKLOG.md" ]] \
+     || [[ -f "$root/PROPOSALS.md" ]] \
+     || [[ -d "$root/docs/features" ]] \
+     || [[ -d "$root/docs/briefs" ]] \
+     || [[ -d "$root/docs/dream" ]]; then
+    err "Legacy structure detected at: $root  发现老结构目录"
+    echo "" >&2
+    echo "  This project uses the pre-2.0 layout (BACKLOG.md / docs/*). Roll 2.0 requires" >&2
+    echo "  process artifacts to live in .roll/. Run the migration to upgrade:" >&2
+    echo "" >&2
+    echo "    roll migrate --dry-run       # Preview changes" >&2
+    echo "    roll migrate                 # Execute (single atomic commit)" >&2
+    echo "" >&2
+    echo "  Migration guide: ${ROLL_PKG_DIR}/guide/en/migration-2.0.md" >&2
+    echo "" >&2
+    echo "  To roll back to Roll 1.x temporarily:" >&2
+    echo "    npm install -g @seanyao/roll@1" >&2
+    exit 1
+  fi
+
+  # No structure detected — empty project or non-Roll dir. Allow.
+  return 0
+}
+
 main() {
   local cmd="${1:-}"
   shift || true
 
+  # US-ONBOARD-004: refuse to run project commands on legacy structure
+  _check_structure "$cmd"
+
   case "$cmd" in
     setup)         cmd_setup "$@" ;;
     update)        cmd_update "$@" ;;
     init)          cmd_init "$@" ;;
+    migrate)       cmd_migrate "$@" ;;
     status)        cmd_status "$@" ;;
     peer)          cmd_peer "$@" ;;
     loop)          cmd_loop "$@" ;;
@@ -5537,7 +6139,7 @@ main() {
     review-pr)     cmd_review_pr "$@" ;;
     version|--version|-v) echo "roll v${VERSION}" ;;
     help|--help|-h) _help "$@" ;;
-    "") [[ -f "BACKLOG.md" ]] && _home || { _help; _show_changelog; } ;;
+    "") [[ -f ".roll/backlog.md" ]] && _home || { _help; _show_changelog; } ;;
     *)
       err "Unknown command: $cmd  未知命令: $cmd"
       echo ""