@seanyao/roll 2026.521.2 → 2026.522.1

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.521.2"
+VERSION="2026.522.1"
 ROLL_HOME="${ROLL_HOME:-${HOME}/.roll}"
 ROLL_CONFIG="${ROLL_HOME}/config.yaml"
 ROLL_GLOBAL="${ROLL_HOME}/conventions/global"
@@ -100,7 +100,7 @@ config_get() {
   local default="${2:-}"
   if [[ -f "$ROLL_CONFIG" ]]; then
     local val
-    val=$(grep -E "^${key}:" "$ROLL_CONFIG" 2>/dev/null | head -1 | sed 's/^[^:]*:[[:space:]]*//' | sed 's/[[:space:]]*$//')
+    val=$(grep -E "^${key}:" "$ROLL_CONFIG" 2>/dev/null | head -1 | sed 's/^[^:]*:[[:space:]]*//' | sed 's/[[:space:]]*#.*$//' | sed 's/[[:space:]]*$//')
     if [[ -n "$val" ]]; then
       echo "${val/#\~/$HOME}"
       return
@@ -1070,6 +1070,9 @@ cmd_init() {
     _write_backlog "$project_dir/.roll/backlog.md"
     _ensure_features_dir "$project_dir/.roll/features"
     _write_features_md "$project_dir/.roll/features.md"
+    # US-ONBOARD-019: stamp the project so legacy detection can recognise it
+    # as Roll-onboarded without depending on directory-name heuristics.
+    _write_version_stamp "$project_dir"
   } >/dev/null
 
   local sync_status="ok"
@@ -1196,8 +1199,9 @@ _init_is_legacy_project() {
 }
 
 # 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.
+# US-ONBOARD-018: also auto-launches the chosen agent in interactive mode with
+# the $roll-onboard skill content pre-loaded as the initial prompt, then chains
+# into `roll init --apply` when the conversation ends successfully.
 _init_legacy_onboard_guide() {
   local project_dir="$1"
   local count_summary
@@ -1206,40 +1210,25 @@ _init_legacy_onboard_guide() {
   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"
+  # Discover installed agents (writes to globals: _ONBOARD_INSTALLED, _ONBOARD_MISSING).
+  _onboard_discover_agents
 
   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
+  if [[ ${#_ONBOARD_INSTALLED[@]} -gt 0 ]]; then
+    for n in "${_ONBOARD_INSTALLED[@]}"; do
       printf "    %b✓%b %s   (installed)\n" "${GREEN}" "${NC}" "$n"
     done
   fi
-  if [[ ${#missing[@]} -gt 0 ]]; then
-    for n in "${missing[@]}"; do
+  if [[ ${#_ONBOARD_MISSING[@]} -gt 0 ]]; then
+    for n in "${_ONBOARD_MISSING[@]}"; do
       printf "    %b✗%b %s   (not found)\n" "${RED}" "${NC}" "$n"
     done
   fi
 
-  if [[ ${#installed[@]} -eq 0 ]]; then
+  if [[ ${#_ONBOARD_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) 后重试。"
@@ -1253,17 +1242,169 @@ _init_legacy_onboard_guide() {
   echo "  代码与对话都留在你的 agent 工具里 —— Roll 本身不上传任何内容。"
   echo "  Your code and conversation stay in your agent — Roll never uploads anything."
   echo ""
-  echo "  下一步  Next step:"
+
+  # US-ONBOARD-018: select an agent. Single installed → auto-pick. Multiple
+  # installed → ask the user (or honour ROLL_ONBOARD_AGENT for non-interactive
+  # callers and tests).
+  local chosen
+  chosen=$(_onboard_select_agent "${_ONBOARD_INSTALLED[@]}") || return 1
+  [[ -n "$chosen" ]] || return 1
+
+  echo ""
+  info "Launching ${chosen}…  正在启动 ${chosen}…"
+  echo "  Conversation ends with /exit (or Ctrl-C). On exit Roll will run apply for you."
+  echo "  在 agent 内用 /exit 结束（或 Ctrl-C）。退出后 Roll 会自动衔接 apply。"
   echo ""
-  if [[ ${#installed[@]} -eq 1 ]]; then
-    echo "    Open ${installed[0]} and run:    $roll-onboard"
+
+  # US-ONBOARD-018: actually run the agent with the onboard prompt pre-loaded.
+  _run_onboard_agent "$chosen" "$project_dir"
+}
+
+# US-ONBOARD-018: discover installed AI agents from ROLL_CONFIG.
+# Populates global arrays _ONBOARD_INSTALLED and _ONBOARD_MISSING.
+# Extracted from _init_legacy_onboard_guide so it can be unit-tested.
+_onboard_discover_agents() {
+  _ONBOARD_INSTALLED=()
+  _ONBOARD_MISSING=()
+  local _key _value _name _dir
+  while IFS=: read -r _key _value; do
+    [[ "$_key" =~ ^ai_ ]] || continue
+    _name="${_key#ai_}"
+    _dir="${_value%%|*}"
+    _dir="${_dir# }"
+    _dir="${_dir/#\~/$HOME}"
+    if [[ -d "$_dir" ]]; then
+      _ONBOARD_INSTALLED+=("$_name")
+    else
+      _ONBOARD_MISSING+=("$_name")
+    fi
+  done < "$ROLL_CONFIG"
+}
+
+# US-ONBOARD-018: pick an agent for the onboard flow.
+# - $ROLL_ONBOARD_AGENT (env) wins if set and present in the candidate list.
+# - Single candidate → auto-pick (printed to stdout).
+# - Multiple candidates → prompt user for a number. Stdin EOF / invalid input → return 1.
+# Echoes the chosen agent name on stdout, nothing else.
+_onboard_select_agent() {
+  local -a candidates=("$@")
+  [[ ${#candidates[@]} -gt 0 ]] || return 1
+
+  # Explicit override (tests, CI, dotfile aliases).
+  if [[ -n "${ROLL_ONBOARD_AGENT:-}" ]]; then
+    local c
+    for c in "${candidates[@]}"; do
+      if [[ "$c" == "$ROLL_ONBOARD_AGENT" ]]; then
+        printf '%s\n' "$c"
+        return 0
+      fi
+    done
+    err "ROLL_ONBOARD_AGENT='${ROLL_ONBOARD_AGENT}' is not in installed agents." >&2
+    return 1
+  fi
+
+  if [[ ${#candidates[@]} -eq 1 ]]; then
+    printf '%s\n' "${candidates[0]}"
+    return 0
+  fi
+
+  # Multi-agent: prompt the user. To stderr so stdout stays clean for the caller.
+  {
+    echo "  选一个 agent  Pick an agent:"
+    local i=1
+    for c in "${candidates[@]}"; do
+      printf "    %d) %s\n" "$i" "$c"
+      i=$((i + 1))
+    done
+    printf "  Enter number [1-%d]: " "${#candidates[@]}"
+  } >&2
+
+  local choice
+  if ! IFS= read -r choice; then
+    err "No input received. Aborting onboard.  未收到输入，已取消 onboard。" >&2
+    return 1
+  fi
+  if ! [[ "$choice" =~ ^[0-9]+$ ]] || (( choice < 1 || choice > ${#candidates[@]} )); then
+    err "Invalid choice: '${choice}'.  无效选择。" >&2
+    return 1
+  fi
+  printf '%s\n' "${candidates[$((choice - 1))]}"
+}
+
+# US-ONBOARD-018: compose the initial prompt for the onboard agent —
+# the $roll-onboard skill body (frontmatter stripped) plus a kickoff line.
+# Returns 1 if the skill file is missing.
+_onboard_initial_prompt() {
+  local skill_file="${ROLL_PKG_DIR}/skills/roll-onboard/SKILL.md"
+  [[ -f "$skill_file" ]] || {
+    err "Skill file missing: ${skill_file}" >&2
+    return 1
+  }
+  # Lead line orients the agent before the skill body. Keep it stable; tests
+  # match on this exact prefix.
+  printf '%s\n\n' "Run the \$roll-onboard skill below for this project. Follow it end-to-end and write .roll/onboard-plan.yaml when done."
+  _skill_content "$skill_file"
+}
+
+# US-ONBOARD-018: print retry / switch-agent guidance after a failed onboard run.
+# Extracted so we can unit-test the wording without spawning subprocesses.
+# $1 = chosen agent name, $2 = exit code from the agent.
+_onboard_failure_hint() {
+  local agent="$1" code="$2"
+  echo "" >&2
+  if [[ "$code" == "130" ]]; then
+    err "Onboard cancelled (Ctrl-C).  Onboard 已取消（Ctrl-C）。" >&2
   else
-    echo "    Open any installed agent and run:    \$roll-onboard"
+    err "Agent '${agent}' exited with code ${code}.  agent '${agent}' 异常退出 (code ${code})。" >&2
+  fi
+  echo "" >&2
+  echo "  下一步  Next step:" >&2
+  echo "    - 再试一次同一个 agent:  roll init" >&2
+  echo "    - retry the same agent:   roll init" >&2
+  echo "    - 换一个 agent:           ROLL_ONBOARD_AGENT=<name> roll init" >&2
+  echo "    - switch to another:      ROLL_ONBOARD_AGENT=<name> roll init" >&2
+  echo "" >&2
+}
+
+# US-ONBOARD-018: launch the chosen agent in interactive mode with the onboard
+# prompt pre-loaded, wait for it to exit, then branch:
+#   exit 0  + .roll/onboard-plan.yaml present → chain into roll init --apply
+#   exit 0  + plan missing                    → tell user to re-run if they want
+#   exit !0 (incl. 130 from SIGINT)           → print retry / switch-agent hint
+# $1 = chosen agent name, $2 = project dir
+_run_onboard_agent() {
+  local agent="$1" project_dir="$2"
+  local prompt
+  prompt=$(_onboard_initial_prompt) || return 1
+  _agent_argv "$agent" interactive "$prompt" || {
+    err "Agent '${agent}' has no interactive mode wired up.  agent '${agent}' 暂未接入 interactive 模式。" >&2
+    return 1
+  }
+
+  # Run attached to the user's tty so the agent's REPL gets stdin/stdout/stderr.
+  # `set -e` is active script-wide; suppress with `|| rc=$?` so the failure
+  # branch (SIGINT 130, agent error) can be handled instead of aborting init.
+  local rc=0
+  "${_AGENT_ARGV[@]}" || rc=$?
+
+  if [[ "$rc" -ne 0 ]]; then
+    _onboard_failure_hint "$agent" "$rc"
+    return "$rc"
   fi
-  echo ""
-  echo "  完成对话后回到这里运行  After the conversation, return and run:"
-  echo "    roll init --apply"
-  echo ""
+
+  if [[ ! -f "${project_dir}/.roll/onboard-plan.yaml" ]]; then
+    echo "" >&2
+    err "Agent exited cleanly but did not write .roll/onboard-plan.yaml." >&2
+    err "agent 正常退出但未生成 .roll/onboard-plan.yaml。" >&2
+    echo "  Re-run \`roll init\` once you've completed the conversation." >&2
+    echo "  对话完成后再次运行 \`roll init\` 即可。" >&2
+    return 1
+  fi
+
+  # Plan present → chain into apply automatically.
+  echo "" >&2
+  info "Plan written. Running apply…  已写入 plan，正在执行 apply…"
+  ( cd "$project_dir" && _init_apply )
 }
 
 # Helper: human-readable summary of why this is detected as legacy.
@@ -1424,6 +1565,15 @@ print(' '.join(p.get('scope', {}).get('approved', [])))
   _merge_global_to_project "$project_dir"
   _merge_claude_to_project "$project_dir"
 
+  # US-ONBOARD-019: stamp the project at onboard-apply time so subsequent
+  # invocations recognise it as Roll-onboarded (and offboard can sweep it).
+  local _stamp_existed=true
+  [[ -f "$project_dir/.roll/.version" ]] || _stamp_existed=false
+  _write_version_stamp "$project_dir"
+  if [[ "$_stamp_existed" == "false" ]] && [[ -f "$project_dir/.roll/.version" ]]; then
+    _onboard_changeset_record "$project_dir" "files_created" ".roll/.version"
+  fi
+
   # Create .roll/ artifacts based on scope.approved
   if [[ " $approved " == *" backlog "* ]]; then
     _write_backlog "$project_dir/.roll/backlog.md"
@@ -1946,6 +2096,88 @@ _ensure_features_dir() {
   _ROLL_MERGE_SUMMARY+=("created|.roll/features/")
 }
 
+# US-ONBOARD-019: write a Roll version stamp under .roll/.version when a project
+# is onboarded. Going forward, this stamp is the canonical "this project was
+# onboarded with Roll" signal — it lets `_check_structure` distinguish a
+# genuine pre-2.0 Roll project (needs migrate) from a non-Roll project that
+# coincidentally has BACKLOG.md / docs/features/ from another tool.
+#
+# Idempotent: an existing stamp is never overwritten, so the original install
+# timestamp is preserved across re-runs of `roll init`.
+_write_version_stamp() {
+  local project_dir="$1"
+  local stamp_path="$project_dir/.roll/.version"
+  if [[ -f "$stamp_path" ]]; then
+    _ROLL_MERGE_SUMMARY+=("unchanged|.roll/.version")
+    return 0
+  fi
+  mkdir -p "$project_dir/.roll"
+  local installed_at; installed_at=$(date -u +%FT%TZ)
+  cat > "$stamp_path" <<EOF
+# Roll project version stamp — written by \`roll init\` (US-ONBOARD-019).
+# Used by \`_check_structure\` to recognise a previously-onboarded Roll project
+# without depending on directory-name heuristics.
+roll_version: "${VERSION}"
+installed_at: "${installed_at}"
+EOF
+  _ROLL_MERGE_SUMMARY+=("created|.roll/.version")
+  return 0
+}
+
+# US-ONBOARD-019: is <root> a Roll-onboarded project (current or pre-2.0)?
+#
+# Returns 0 (true) when at least one Roll-specific signal is present:
+#   1. .roll/.version stamp (post-019 onboard)
+#   2. BACKLOG.md with a Roll-1.x Story table or "Bug Fixes" section
+#   3. PROPOSALS.md with a Roll-style "## Proposal" heading
+#   4. docs/features/ containing US-/FIX-/REFACTOR- named .md files
+#   5. docs/briefs/ or docs/dream/ directory non-empty
+#
+# A bare BACKLOG.md/PROPOSALS.md from another tool, or a generic
+# docs/features/ folder, does NOT count — that's the bug US-ONBOARD-019
+# fixes (false-positive migrate prompts on non-Roll projects).
+_has_roll_signature() {
+  local root="$1"
+
+  # Signal 1 — post-019 version stamp
+  [[ -f "$root/.roll/.version" ]] && return 0
+
+  # Signal 2 — Roll-1.x BACKLOG.md content
+  if [[ -f "$root/BACKLOG.md" ]]; then
+    if grep -qE '^\| Story \| Description \| Status \|' "$root/BACKLOG.md" 2>/dev/null \
+       || grep -qE '^## Epic:' "$root/BACKLOG.md" 2>/dev/null \
+       || grep -qE '^\| ID \| Problem \| Status \|' "$root/BACKLOG.md" 2>/dev/null; then
+      return 0
+    fi
+  fi
+
+  # Signal 3 — Roll-style PROPOSALS.md
+  if [[ -f "$root/PROPOSALS.md" ]]; then
+    if grep -qE '^## Proposal' "$root/PROPOSALS.md" 2>/dev/null; then
+      return 0
+    fi
+  fi
+
+  # Signal 4 — Roll-named files under docs/features/
+  if [[ -d "$root/docs/features" ]]; then
+    if find "$root/docs/features" -maxdepth 2 -type f -name '*.md' 2>/dev/null \
+         | grep -qE '/(US|FIX|REFACTOR)-[0-9]+'; then
+      return 0
+    fi
+  fi
+
+  # Signal 5 — Roll-1.x process artefacts (docs/briefs/ docs/dream/)
+  local dir
+  for dir in docs/briefs docs/dream; do
+    if [[ -d "$root/$dir" ]] \
+       && [[ -n "$(find "$root/$dir" -mindepth 1 -maxdepth 2 -type f 2>/dev/null | head -1)" ]]; then
+      return 0
+    fi
+  done
+
+  return 1
+}
+
 # ─── Helper: write starter .roll/features.md (no-op if exists) ────────────────
 _write_features_md() {
   if [[ -f "$1" ]]; then
@@ -2708,21 +2940,48 @@ _parse_review_verdict() {
 # Returns 1 on unknown agent. Adding a new agent only needs an entry here.
 _agent_argv() {
   local agent="$1" mode="$2" prompt="$3"
+  # US-ONBOARD-018: `interactive` mode launches the agent's REPL with the prompt
+  # pre-loaded as the first user message. The user can then converse normally,
+  # keep their tty, and exit with Ctrl-C or /exit. Used by `roll init` to auto-
+  # start the chosen agent for $roll-onboard without a copy-paste handoff.
+  # Convention: positional arg as initial prompt; no -p / exec / run / --quiet.
   case "$agent" in
     claude)
       case "$mode" in
-        text|peer) _AGENT_ARGV=(claude -p --output-format text "$prompt") ;;
-        *)         _AGENT_ARGV=(claude -p "$prompt") ;;
+        interactive) _AGENT_ARGV=(claude "$prompt") ;;
+        text|peer)   _AGENT_ARGV=(claude -p --output-format text "$prompt") ;;
+        *)           _AGENT_ARGV=(claude -p "$prompt") ;;
+      esac ;;
+    kimi)
+      case "$mode" in
+        interactive) _AGENT_ARGV=(kimi "$prompt") ;;
+        *)           _AGENT_ARGV=(kimi --quiet -p "$prompt") ;;
+      esac ;;
+    deepseek)
+      # deepseek has the same argv shape in both modes (positional prompt).
+      _AGENT_ARGV=(deepseek "$prompt") ;;
+    pi)
+      case "$mode" in
+        interactive) _AGENT_ARGV=(pi "$prompt") ;;
+        *)           _AGENT_ARGV=(pi -p "$prompt") ;;
       esac ;;
-    kimi)     _AGENT_ARGV=(kimi --quiet -p "$prompt") ;;
-    deepseek) _AGENT_ARGV=(deepseek "$prompt") ;;
-    pi)       _AGENT_ARGV=(pi -p "$prompt") ;;
     codex)
       case "$mode" in
-        peer) _AGENT_ARGV=(codex exec --json --output-last-message "$prompt") ;;
-        *)    _AGENT_ARGV=(codex exec "$prompt") ;;
+        interactive) _AGENT_ARGV=(codex "$prompt") ;;
+        peer)        _AGENT_ARGV=(codex exec --json --output-last-message "$prompt") ;;
+        *)           _AGENT_ARGV=(codex exec "$prompt") ;;
+      esac ;;
+    opencode)
+      case "$mode" in
+        interactive) _AGENT_ARGV=(opencode "$prompt") ;;
+        *)           _AGENT_ARGV=(opencode run "$prompt") ;;
+      esac ;;
+    gemini)
+      # gemini integration is interactive-only for now (used by onboard flow).
+      case "$mode" in
+        interactive) _AGENT_ARGV=(gemini "$prompt") ;;
+        *) return 1 ;;
       esac ;;
-    opencode) _AGENT_ARGV=(opencode run "$prompt") ;;
     *) return 1 ;;
   esac
 }
@@ -2766,6 +3025,463 @@ _agent_run_skill() {
   "${_AGENT_ARGV[@]}"
 }
 
+# ═══════════════════════════════════════════════════════════════════════════════
+# SLIDES — deck.md → HTML rendering pipeline (US-DECK-003 / 004 / 005)
+#
+#   roll slides build <slug>   render .roll/slides/<slug>/deck.md → .html, open
+#   roll slides new "<topic>"  invoke selected agent with roll-deck skill (US-DECK-004)
+#   roll slides list           list decks as a table (US-DECK-005)
+#   roll slides preview <slug> open .roll/slides/<slug>.html in browser (US-DECK-005)
+#
+# All four subcommands are implemented: `build` (DECK-003), `new` (DECK-004),
+# `list` / `preview` (DECK-005). The AI authoring step happens in `new`;
+# everything else is pure bash.
+# ═══════════════════════════════════════════════════════════════════════════════
+_slides_help() {
+  cat <<'EOF'
+roll slides — deck.md → HTML rendering
+roll slides — 幻灯片 deck.md 渲染管线
+
+USAGE  用法
+  roll slides build <slug> [--no-open]
+                          Render .roll/slides/<slug>/deck.md → .roll/slides/<slug>.html
+                          渲染 deck.md 为 HTML 并自动打开浏览器
+  roll slides new "<topic>" [--template <name>]
+                          Generate a new deck.md from a topic via the selected AI agent
+                          通过所选 AI agent 根据主题生成新的 deck.md
+  roll slides list        List all decks under .roll/slides/ as a table
+                          列出 .roll/slides/ 下所有幻灯片
+  roll slides preview <slug> [--no-open]
+                          Open .roll/slides/<slug>.html in the default browser
+                          在浏览器中打开已渲染的幻灯片
+
+OPTIONS  选项
+  --no-open               Skip auto-opening the rendered HTML in a browser
+                          渲染后不自动打开浏览器
+  --help, -h              Show this help
+                          显示本帮助
+EOF
+}
+
+# Resolve the renderer / validator paths (shipped with the roll package).
+_slides_lib() {
+  printf '%s' "${ROLL_PKG_DIR}/lib"
+}
+
+# Resolve the template path for a given template name.
+# Returns 0 + prints the path if the template exists, else returns 1.
+_slides_template_path() {
+  local name="$1"
+  local tpl="${ROLL_PKG_DIR}/site/slides/templates/${name}.html"
+  if [[ -f "$tpl" ]]; then
+    printf '%s' "$tpl"
+    return 0
+  fi
+  return 1
+}
+
+# Read the `template:` value from a deck.md frontmatter. Defaults to
+# `introduction-v3` if the field is absent (validator will catch missing field
+# separately).
+_slides_template_for_deck() {
+  local deck="$1"
+  local tpl
+  tpl=$(awk '
+    /^---[[:space:]]*$/ { d++; if (d==2) exit; next }
+    d==1 && /^template:[[:space:]]*/ {
+      sub(/^template:[[:space:]]*/, "")
+      gsub(/^["'\'']|["'\'']$/, "")
+      print
+      exit
+    }
+  ' "$deck" 2>/dev/null)
+  [[ -n "$tpl" ]] || tpl="introduction-v3"
+  printf '%s' "$tpl"
+}
+
+# Ensure .roll/.gitignore contains `slides/*.html` so the per-build HTML
+# artefact is ignored by default. deck.md remains committable. Idempotent.
+_slides_ensure_gitignore() {
+  local gi=".roll/.gitignore"
+  mkdir -p ".roll"
+  if [[ -f "$gi" ]] && grep -qE '^slides/\*\.html$' "$gi" 2>/dev/null; then
+    return 0
+  fi
+  # Preserve a trailing newline before appending.
+  if [[ -f "$gi" ]] && [[ -s "$gi" ]] && [[ "$(tail -c 1 "$gi" 2>/dev/null)" != $'\n' ]]; then
+    printf '\n' >>"$gi"
+  fi
+  printf 'slides/*.html\n' >>"$gi"
+}
+
+# Pick the browser-open command for the current OS. Echoes the command name;
+# returns 1 if no opener is available (tests + headless CI).
+_slides_open_cmd() {
+  case "$(uname -s 2>/dev/null)" in
+    Darwin) command -v open >/dev/null 2>&1 && { printf 'open'; return 0; } ;;
+    Linux)  command -v xdg-open >/dev/null 2>&1 && { printf 'xdg-open'; return 0; } ;;
+  esac
+  return 1
+}
+
+cmd_slides_build() {
+  local slug="" no_open=0
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      --no-open) no_open=1; shift ;;
+      --help|-h) _slides_help; return 0 ;;
+      --*) err "Unknown option: $1  未知选项: $1"; return 1 ;;
+      *)
+        if [[ -z "$slug" ]]; then
+          slug="$1"; shift
+        else
+          err "Unexpected argument: $1  多余参数: $1"; return 1
+        fi
+        ;;
+    esac
+  done
+
+  if [[ -z "$slug" ]]; then
+    err "Usage: roll slides build <slug> [--no-open]"
+    echo "用法: roll slides build <slug> [--no-open]" >&2
+    return 1
+  fi
+
+  local deck=".roll/slides/${slug}/deck.md"
+  if [[ ! -f "$deck" ]]; then
+    err "Deck not found: ${deck}"
+    echo "  未找到 deck 文件：${deck}" >&2
+    echo "  Hint: run 'roll slides new \"<topic>\"' to generate a new deck." >&2
+    echo "  提示：先运行 'roll slides new \"<主题>\"' 生成新的幻灯片。" >&2
+    return 1
+  fi
+
+  local lib_dir; lib_dir=$(_slides_lib)
+  local validator="${lib_dir}/slides-validate.py"
+  local renderer="${lib_dir}/slides-render.py"
+  if [[ ! -f "$validator" || ! -f "$renderer" ]]; then
+    err "Slides toolchain missing — re-run 'roll setup'  渲染工具缺失，请运行 roll setup"
+    return 1
+  fi
+
+  # 1. Validate first (fail-fast on AI-generated decks).
+  if ! python3 "$validator" "$deck"; then
+    err "deck.md validation failed — fix the issues above before building."
+    echo "  deck.md 校验失败，请先修复上方提示再重试。" >&2
+    return 1
+  fi
+
+  # 2. Resolve template + render.
+  local tpl_name; tpl_name=$(_slides_template_for_deck "$deck")
+  local tpl_path
+  if ! tpl_path=$(_slides_template_path "$tpl_name"); then
+    err "Template not found: ${tpl_name}  未找到模板：${tpl_name}"
+    return 1
+  fi
+
+  local out=".roll/slides/${slug}.html"
+  mkdir -p ".roll/slides"
+  if ! python3 "$renderer" "$deck" "$tpl_path" "$out"; then
+    err "Render failed for ${deck}  渲染失败：${deck}"
+    return 1
+  fi
+
+  # 3. Default-ignore the HTML artefact so it doesn't accidentally get committed.
+  _slides_ensure_gitignore
+
+  ok "Rendered → ${out}  渲染完成 → ${out}"
+
+  # 4. Auto-open browser unless suppressed (or running inside bats tests).
+  if [[ "$no_open" -eq 1 ]] || [[ -n "${BATS_TEST_NUMBER:-}" ]] || [[ -n "${ROLL_SLIDES_NO_OPEN:-}" ]]; then
+    return 0
+  fi
+  local opener
+  if opener=$(_slides_open_cmd); then
+    "$opener" "$out" >/dev/null 2>&1 || true
+  fi
+  return 0
+}
+
+# ─── US-DECK-005 ─────────────────────────────────────────────────────────────
+# Read a frontmatter field from deck.md. Returns empty string if absent.
+# Stops scanning at the closing `---` so YAML body keys can't leak through.
+_slides_frontmatter_field() {
+  local deck="$1" field="$2"
+  awk -v field="$field" '
+    /^---[[:space:]]*$/ { d++; if (d==2) exit; next }
+    d==1 {
+      pat = "^" field "[[:space:]]*:[[:space:]]*"
+      if ($0 ~ pat) {
+        sub(pat, "")
+        gsub(/^["'\'']|["'\'']$/, "")
+        print
+        exit
+      }
+    }
+  ' "$deck" 2>/dev/null
+}
+
+# Format a byte count for human-friendly display: 1234 → "1.2K", 2345678 → "2.2M".
+# Bash arithmetic only — no `bc`, no `numfmt` dependency.
+_slides_human_size() {
+  local bytes="${1:-0}"
+  if [[ "$bytes" -lt 1024 ]]; then
+    printf '%dB' "$bytes"
+  elif [[ "$bytes" -lt 1048576 ]]; then
+    local tenth=$(( (bytes * 10) / 1024 ))
+    printf '%d.%dK' "$((tenth / 10))" "$((tenth % 10))"
+  else
+    local tenth=$(( (bytes * 10) / 1048576 ))
+    printf '%d.%dM' "$((tenth / 10))" "$((tenth % 10))"
+  fi
+}
+
+cmd_slides_list() {
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      --help|-h) _slides_help; return 0 ;;
+      --*) err "Unknown option: $1  未知选项: $1"; return 1 ;;
+      *) err "Unexpected argument: $1  多余参数: $1"; return 1 ;;
+    esac
+  done
+
+  local slides_dir=".roll/slides"
+  if [[ ! -d "$slides_dir" ]]; then
+    info "No decks found under .roll/slides/  无幻灯片"
+    echo "  Hint: run 'roll slides new \"<topic>\"' to create one."
+    echo "  提示：运行 'roll slides new \"<主题>\"' 创建第一个幻灯片。"
+    return 0
+  fi
+
+  local -a slugs=()
+  local d slug
+  shopt -s nullglob
+  for d in "$slides_dir"/*/; do
+    slug="${d%/}"
+    slug="${slug##*/}"
+    if [[ -f "${d}deck.md" ]]; then
+      slugs+=("$slug")
+    fi
+  done
+  shopt -u nullglob
+
+  if [[ "${#slugs[@]}" -eq 0 ]]; then
+    info "No decks found under .roll/slides/  无幻灯片"
+    echo "  Hint: run 'roll slides new \"<topic>\"' to create one."
+    echo "  提示：运行 'roll slides new \"<主题>\"' 创建第一个幻灯片。"
+    return 0
+  fi
+
+  local -a sorted_slugs
+  IFS=$'\n' sorted_slugs=($(printf '%s\n' "${slugs[@]}" | sort))
+  unset IFS
+
+  printf '%-20s  %-20s  %-12s  %-12s  %-5s  %s\n' \
+    "slug" "template" "total_slides" "created" "built" "size"
+  printf '%-20s  %-20s  %-12s  %-12s  %-5s  %s\n' \
+    "----" "--------" "------------" "-------" "-----" "----"
+
+  local s deck html template total created built size bytes
+  for s in "${sorted_slugs[@]}"; do
+    deck="${slides_dir}/${s}/deck.md"
+    html="${slides_dir}/${s}.html"
+    template=$(_slides_frontmatter_field "$deck" "template")
+    [[ -z "$template" ]] && template="-"
+    total=$(_slides_frontmatter_field "$deck" "total_slides")
+    [[ -z "$total" ]] && total="-"
+    created=$(_slides_frontmatter_field "$deck" "created")
+    [[ -z "$created" ]] && created="-"
+    if [[ -f "$html" ]]; then
+      built="✓"
+      bytes=$(wc -c <"$html" 2>/dev/null | tr -d ' ')
+      [[ -z "$bytes" ]] && bytes=0
+      size=$(_slides_human_size "$bytes")
+    else
+      built="✗"
+      size="-"
+    fi
+    printf '%-20s  %-20s  %-12s  %-12s  %-5s  %s\n' \
+      "$s" "$template" "$total" "$created" "$built" "$size"
+  done
+  return 0
+}
+
+cmd_slides_preview() {
+  local slug="" no_open=0
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      --no-open) no_open=1; shift ;;
+      --help|-h) _slides_help; return 0 ;;
+      --*) err "Unknown option: $1  未知选项: $1"; return 1 ;;
+      *)
+        if [[ -z "$slug" ]]; then
+          slug="$1"; shift
+        else
+          err "Unexpected argument: $1  多余参数: $1"; return 1
+        fi
+        ;;
+    esac
+  done
+
+  if [[ -z "$slug" ]]; then
+    err "Usage: roll slides preview <slug> [--no-open]"
+    echo "用法: roll slides preview <slug> [--no-open]" >&2
+    return 1
+  fi
+
+  local html=".roll/slides/${slug}.html"
+  if [[ ! -f "$html" ]]; then
+    err "Rendered HTML not found: ${html}"
+    echo "  未找到已渲染的 HTML：${html}" >&2
+    echo "  Hint: run 'roll slides build ${slug}' first to render it." >&2
+    echo "  提示：先运行 'roll slides build ${slug}' 渲染幻灯片。" >&2
+    return 1
+  fi
+
+  ok "Preview → ${html}  打开预览 → ${html}"
+
+  if [[ "$no_open" -eq 1 ]] || [[ -n "${BATS_TEST_NUMBER:-}" ]] || [[ -n "${ROLL_SLIDES_NO_OPEN:-}" ]]; then
+    return 0
+  fi
+  local opener
+  if opener=$(_slides_open_cmd); then
+    "$opener" "$html" >/dev/null 2>&1 || true
+  fi
+  return 0
+}
+
+# ─── US-DECK-004 ─────────────────────────────────────────────────────────────
+# Turn a topic string into a kebab-case slug.
+# Lower-cases, replaces any run of non-alphanumerics with a single dash,
+# strips leading/trailing dashes. Matches the convention assumed by
+# `roll slides build <slug>` (lowercase kebab) and the schema.
+_slides_topic_slug() {
+  local topic="$1"
+  local slug
+  slug=$(printf '%s' "$topic" | tr '[:upper:]' '[:lower:]' | tr -cs 'a-z0-9' '-')
+  # Strip leading/trailing dashes.
+  slug="${slug#-}"
+  slug="${slug%-}"
+  printf '%s' "$slug"
+}
+
+# `roll slides new "<topic>" [--template <name>]`
+# AI authoring entry point. Loads the `roll-deck` skill, builds a single text
+# prompt containing the skill body + topic + slug + template, and hands it
+# to the selected project agent. The agent is responsible for writing
+# `.roll/slides/<slug>/deck.md` (and nothing else). After the agent exits,
+# we print a bilingual hint pointing at `roll slides build <slug>`.
+cmd_slides_new() {
+  local topic="" template="introduction-v3"
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      --template)
+        [[ -n "${2:-}" ]] || { err "--template requires a value  --template 需要一个值"; return 1; }
+        template="$2"; shift 2 ;;
+      --template=*) template="${1#--template=}"; shift ;;
+      --help|-h) _slides_help; return 0 ;;
+      --*) err "Unknown option: $1  未知选项: $1"; return 1 ;;
+      *)
+        if [[ -z "$topic" ]]; then
+          topic="$1"; shift
+        else
+          err "Unexpected argument: $1  多余参数: $1"; return 1
+        fi
+        ;;
+    esac
+  done
+
+  if [[ -z "$topic" ]]; then
+    err "Usage: roll slides new \"<topic>\" [--template <name>]"
+    echo "  用法：roll slides new \"<主题>\" [--template <模板名>]" >&2
+    return 1
+  fi
+
+  local slug; slug=$(_slides_topic_slug "$topic")
+  if [[ -z "$slug" ]]; then
+    err "Could not derive a slug from topic: $topic"
+    echo "  无法从主题派生 slug：$topic" >&2
+    return 1
+  fi
+
+  local skill_file="${ROLL_PKG_DIR}/skills/roll-deck/SKILL.md"
+  [[ -f "$skill_file" ]] || { err "Skill not found: ${skill_file}"; return 1; }
+  local skill_body; skill_body=$(_skill_content "$skill_file")
+
+  local agent; agent=$(_project_agent)
+
+  # Compose the full prompt: skill body + concrete task context. The agent
+  # reads the skill, then sees the topic / slug / template it must use.
+  local prompt
+  prompt="$(cat <<EOF
+${skill_body}
+
+---
+
+# Task
+
+topic: ${topic}
+slug: ${slug}
+template: ${template}
+target_file: .roll/slides/${slug}/deck.md
+
+Generate the 18-slide bilingual deck.md for the topic above, following the workflow and hard constraints in this skill. Write exactly one file: .roll/slides/${slug}/deck.md. Then print the bilingual "Next" hint.
+
+按本 skill 的工作流和硬约束生成 18 张双语 slide 的 deck.md。只写一个文件：.roll/slides/${slug}/deck.md，然后打印双语 "Next" 提示。
+EOF
+)"
+
+  _agent_argv "$agent" text "$prompt" || {
+    err "Unknown agent '${agent}'. Run: roll agent use <claude|kimi|deepseek|pi|codex|opencode>"
+    return 1
+  }
+
+  info "Launching ${agent} with roll-deck skill for topic: ${topic}"
+  info "启动 ${agent} 处理主题：${topic}"
+  "${_AGENT_ARGV[@]}"
+  local rc=$?
+
+  # Whether the agent succeeded or not, point the user at the next bash step.
+  # (Build will surface its own validation errors if deck.md is malformed.)
+  echo
+  echo "Next:  roll slides build ${slug}"
+  echo "下一步：roll slides build ${slug}"
+
+  return "$rc"
+}
+
+cmd_slides() {
+  local subcmd="${1:-}"
+  shift || true
+  case "$subcmd" in
+    build)
+      cmd_slides_build "$@"
+      ;;
+    new)
+      cmd_slides_new "$@"
+      ;;
+    list)
+      cmd_slides_list "$@"
+      ;;
+    preview)
+      cmd_slides_preview "$@"
+      ;;
+    --help|-h|help)
+      _slides_help
+      return 0
+      ;;
+    "")
+      _slides_help
+      return 1
+      ;;
+    *)
+      err "Unknown subcommand: ${subcmd}  未知子命令：${subcmd}"
+      _slides_help >&2
+      return 1
+      ;;
+  esac
+}
+
 cmd_review_pr() {
   local pr_number="${1:-}"
   [ -n "$pr_number" ] || { err "Usage: roll review-pr <number>"; return 1; }
@@ -3094,7 +3810,40 @@ fi
 # _SHARED_ROOT overrides and silently leaked test runs.jsonl writes into prod.
 _LOOP_RUNS="${_SHARED_ROOT}/loop/runs.jsonl"
 : "${_LOOP_MUTE_FILE:=${_SHARED_ROOT}/loop/mute-${_LOOP_PROJ_SLUG}}"
-_LAUNCHD_DIR="${HOME}/Library/LaunchAgents"
+# FIX-087: parallel to FIX-065's _SHARED_ROOT auto-sandbox above. Without this,
+# tests that source bin/roll (directly via BATS or indirectly via a runner-inner
+# fork under /tmp / /var/folders/) wrote plists into the developer's real
+# ~/Library/LaunchAgents/ while their runner paths lived in the sandbox. When
+# the sandbox got cleaned up, those plists outlived their runners and launchd
+# fired them every hour with EX_CONFIG, silently killing the autonomous loop.
+# Detection signals mirror the _SHARED_ROOT block; under a sandbox we route
+# _LAUNCHD_DIR into _SHARED_ROOT so a single teardown removes both.
+if [ -z "${_LAUNCHD_DIR:-}" ]; then
+  # When HOME itself is a sandbox dir (run_roll-style wrappers, roll_status
+  # setup, etc.) the default ${HOME}/Library/LaunchAgents is ALREADY in the
+  # sandbox — redirecting again would break tests that pre-seed plists under
+  # the sandboxed HOME. Only auto-sandbox when HOME points to a real user dir.
+  case "${HOME:-}" in
+    /tmp/*|/private/tmp/*|*/var/folders/*|*/tmp.*) ;;
+    *)
+      _roll_in_test_ctx=0
+      if [ -n "${BATS_TEST_FILENAME:-}" ]; then
+        _roll_in_test_ctx=1
+      else
+        _roll_caller="${BASH_SOURCE[1]:-}"
+        case "$_roll_caller" in /tmp/*|/private/tmp/*|/var/folders/*) _roll_in_test_ctx=1 ;; esac
+        case "$PWD" in /tmp/*|/private/tmp/*|/var/folders/*) _roll_in_test_ctx=1 ;; esac
+      fi
+      if [ "$_roll_in_test_ctx" = 1 ]; then
+        _LAUNCHD_DIR="${_SHARED_ROOT}/LaunchAgents"
+        mkdir -p "$_LAUNCHD_DIR"
+        export _LAUNCHD_DIR
+      fi
+      unset _roll_in_test_ctx _roll_caller
+      ;;
+  esac
+fi
+: "${_LAUNCHD_DIR:=${HOME}/Library/LaunchAgents}"
 
 _config_read_int() {
   local key="$1" default="$2"
@@ -3224,6 +3973,25 @@ _write_launchd_plist() {
   local plist_path="$1" label="$2" project_path="$3"
   local minute="$4" hour="$5" runner_script="$6"
 
+  # FIX-087 tripwire: last line of defense if some caller explicitly set
+  # _LAUNCHD_DIR back to the real path (or built plist_path manually) while
+  # in a test context. Refuse rather than pollute the user's launchd domain.
+  # Skipped when HOME itself has been redirected to a sandbox dir — then
+  # $HOME/Library/LaunchAgents IS the sandbox, not prod.
+  case "${HOME:-}" in
+    /tmp/*|/private/tmp/*|*/var/folders/*|*/tmp.*) ;;
+    *)
+      if [ -n "${HOME:-}" ] && [ "${plist_path#${HOME}/Library/LaunchAgents/}" != "$plist_path" ]; then
+        case "${BATS_TEST_FILENAME:-}${PWD}" in
+          */tmp.*|*/var/folders/*|/tmp/*|/private/tmp/*|*.bats)
+            echo "[FIX-087] refusing prod plist write: $plist_path (test context)" >&2
+            return 1
+            ;;
+        esac
+      fi
+      ;;
+  esac
+
   local hour_xml=""
   [[ -n "$hour" ]] && hour_xml="    <key>Hour</key>
     <integer>${hour}</integer>
@@ -3406,6 +4174,38 @@ _inner_cleanup() {
     _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
+  # FIX-086: aborted-path orphan safety net. When the inner script is killed
+  # (e.g. SIGUSR1, parent process death) after claude has committed TCR work
+  # but before publish runs, the existing aborted fallback below writes
+  # cycle_end aborted and the commits are local-only — if the worktree is
+  # later cleaned up, the work is lost. Before falling through to aborted,
+  # detect unpushed commits in the worktree and push them as an orphan
+  # branch + tag (mirroring FIX-039's PR-publish-failed safety net). On
+  # push success → cycle_end orphan; on failure → fall through to aborted
+  # path below (no regression).
+  # Skip when _CYCLE_TIMED_OUT=1: 45-min hard timeout SIGKILLs claude mid-flight,
+  # so commits may not be atomic — keep human-in-loop via blocked path.
+  # Guard uses inequality form so the FIX-066 audit anchors on the aborted
+  # fallback below, not this block.
+  if [ "\${_CYCLE_END_WRITTEN:-0}" != "1" ] \\
+     && [ "\${_CYCLE_TIMED_OUT:-0}" = "0" ] \\
+     && [ "\${_USE_WORKTREE:-0}" = "1" ] \\
+     && [ -n "\${WT:-}" ] \\
+     && [ -d "\$WT" ] \\
+     && [ -n "\${CYCLE_ID:-}" ]; then
+    _unpushed=\$(cd "\$WT" && git rev-list --count "origin/main..HEAD" 2>/dev/null || echo 0)
+    if [ "\${_unpushed:-0}" -gt 0 ]; then
+      _orphan_tag="loop-orphan-\${CYCLE_ID}"
+      if ( cd "\$WT" && git push origin "\$BRANCH" 2>/dev/null \\
+           && git tag "\$_orphan_tag" 2>/dev/null \\
+           && git push origin "\$_orphan_tag" 2>/dev/null ); then
+        _loop_event cycle_end "\${CYCLE_ID}" "\${BRANCH:-}" "orphan" 2>/dev/null || true
+        _CYCLE_END_WRITTEN=1
+        _runs_append "orphan" 0 "[]" 2>/dev/null || true
+        _worktree_alert "cycle \${CYCLE_ID}: aborted with \${_unpushed} commits; FIX-086 pushed orphan tag \${_orphan_tag}" 2>/dev/null || true
+      fi
+    fi
+  fi
   # IDEA-028 / FIX-066: catch every other abort (SIGKILL, set -e fire, ALERT
   # poisoning that bypasses the retry budget, etc.). Without this, cycle_start
   # is emitted but cycle_end never is, and dashboard renders the cycle as
@@ -3619,6 +4419,10 @@ if [ "\$_USE_WORKTREE" = "1" ]; then
             _worktree_alert "cycle \${CYCLE_ID}: FIX-047: PR not merged within timeout — code may not be in main (BRANCH=\${BRANCH})"
           fi
         fi
+        # US-VIEW-011: emit terminal PR state (merged/closed/open) before cycle_end
+        # so dashboard renders #NN ✓/↩/… correctly. Must run while branch ref
+        # is still resolvable on remote — gh pr view <branch> needs the head ref.
+        _loop_emit_pr_final "\$BRANCH" 2>/dev/null || true
         _worktree_cleanup "\$WT" "\$BRANCH"
         _loop_event cycle_end "\${CYCLE_ID}" "" "done" || true; _CYCLE_END_WRITTEN=1
         echo "[loop] cycle \${CYCLE_ID}: published; worktree cleaned"
@@ -4041,8 +4845,19 @@ _loop_off() {
       warn "Loop not enabled for this project  当前项目 loop 未启用"; return 0
     fi
     local slug; slug=$(_project_slug "$project_path")
+    local uid; uid=$(id -u)
     for svc in loop dream brief; do
       rm -f "${_SHARED_ROOT}/${svc}/run-${slug}.sh"
+      # FIX-081: reverse the FIX-059 auto-bootstrap guard. `_install_launchd_plists`
+      # writes `launchctl disable gui/<UID>/<label>` for every brand-new plist
+      # to block macOS FSEvents from auto-bootstrapping it. That write lands in
+      # the host's /private/var/db/com.apple.xpc.launchd/disabled.<UID>.plist —
+      # it ignores any HOME sandbox. Without a symmetric `enable` on teardown,
+      # every short-lived project leaves 3 permanent ghost labels in the host's
+      # disable list, polluting `launchctl print-disabled` forever even after
+      # the project dir, plists, and ~/.roll are gone.
+      local label; label=$(_launchd_label "$svc" "$project_path")
+      launchctl enable "gui/${uid}/${label}" 2>/dev/null || true
     done
     ok "Loop disabled  已停用"
     return 0
@@ -5426,6 +6241,14 @@ _worktree_sync_meta() {
     --exclude='events.ndjson*' \
     --exclude='runs.jsonl*' \
     .roll/ "$path/.roll/" 2>/dev/null || true
+  # FIX-085: hard-constrain the "skip 🔨 In Progress" rule from the runner
+  # side. SKILL.md tells the agent to skip 🔨 rows but agents don't always
+  # comply, so we strip those rows from the worktree's backlog copy — the
+  # agent literally can't pick a row it can't see. Main backlog untouched.
+  if [ -f "$path/.roll/backlog.md" ]; then
+    sed -i.bak '/| 🔨 In Progress |$/d' "$path/.roll/backlog.md" 2>/dev/null || true
+    rm -f "$path/.roll/backlog.md.bak"
+  fi
 }
 
 # _worktree_merge_back <branch>
@@ -5583,11 +6406,45 @@ _loop_publish_pr() {
   fi
   gh -R "$slug" pr merge "$branch" --auto --squash --delete-branch >/dev/null 2>&1 \
     || _worktree_alert "_loop_publish_pr: gh pr merge --auto failed for ${branch} (PR ${pr_url} left open)"
-  _loop_event pr "$branch" "$pr_url" "ok" 2>/dev/null || true
+  # US-VIEW-011: emit 'open' at PR creation; cycle_end path emits a follow-up
+  # event with the terminal outcome (merged / closed) via _loop_emit_pr_final.
+  _loop_event pr "$branch" "$pr_url" "open" 2>/dev/null || true
   echo "$pr_url"
   return 0
 }
 
+# _loop_emit_pr_final <branch>
+#   US-VIEW-011: after wait_pr_merge resolves, query gh for the PR's terminal
+#   state and emit a second `pr` event so the dashboard renders the correct
+#   landing marker (#NN ✓ merged / #NN ↩ closed / #NN … open).
+#
+#   gh state mapping:
+#     MERGED → merged   (auto-merge landed)
+#     CLOSED → closed   (PR closed without merging — wasted cycle)
+#     OPEN   → open     (still waiting; auto-merge or human reviewer pending)
+#     UNKNOWN/error → open (conservative — don't lie about merged)
+#
+#   Lenient: returns 0 on any failure (gh missing, slug unparseable, network
+#   error). The earlier 'open' event remains as the conservative default
+#   rendering.
+_loop_emit_pr_final() {
+  local branch="$1"
+  command -v gh >/dev/null 2>&1 || return 0
+  local slug; _gh_resolve slug || return 0
+  local pr_url state outcome
+  pr_url=$(gh -R "$slug" pr view "$branch" --json url -q .url 2>/dev/null) || pr_url=""
+  state=$(gh -R "$slug" pr view "$branch" --json state -q .state 2>/dev/null || echo "UNKNOWN")
+  case "$state" in
+    MERGED) outcome="merged" ;;
+    CLOSED) outcome="closed" ;;
+    OPEN)   outcome="open"   ;;
+    *)      outcome="open"   ;;
+  esac
+  [ -z "$pr_url" ] && return 0
+  _loop_event pr "$branch" "$pr_url" "$outcome" 2>/dev/null || true
+  return 0
+}
+
 # _loop_wait_pr_merge <branch>
 #   FIX-047: poll GitHub until PR for <branch> is merged (confirms delivery).
 #   Returns 0: merged. Returns 1: CLOSED or timeout.
@@ -5940,7 +6797,7 @@ cmd_brief() {
 # REFACTOR-021 collapsed the changelog double-pipeline so the release script
 # generates the version header directly from BACKLOG, leaving these two
 # helpers orphaned. Their behaviour is now part of the changelog renderer
-# called from scripts/release.sh.
+# called from the maintainer-private release script at roll-meta/ops/release.sh.
 
 # ═══════════════════════════════════════════════════════════════════════════════
 # BACKLOG — show pending tasks / manage status
@@ -6764,14 +7621,21 @@ _check_structure() {
   # 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).
+  # US-ONBOARD-019: only treat the directory as a legacy *Roll* project when an
+  # old-path marker is present AND a Roll-specific content signature confirms
+  # the project was actually onboarded with Roll. Otherwise we'd block any
+  # non-Roll repo that happens to ship a BACKLOG.md (Jira export, board dump,
+  # different tooling) or a generic docs/features/ folder.
+  local _has_old_path=false
   if [[ -f "$root/BACKLOG.md" ]] \
      || [[ -f "$root/PROPOSALS.md" ]] \
      || [[ -d "$root/docs/features" ]] \
      || [[ -d "$root/docs/briefs" ]] \
      || [[ -d "$root/docs/dream" ]]; then
+    _has_old_path=true
+  fi
+
+  if [[ "$_has_old_path" == "true" ]] && _has_roll_signature "$root"; 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
@@ -6814,6 +7678,7 @@ main() {
     ci)            cmd_ci "$@" ;;
     doctor)        cmd_doctor "$@" ;;
     review-pr)     cmd_review_pr "$@" ;;
+    slides)        cmd_slides "$@" ;;
     version|--version|-v) echo "roll v${VERSION}" ;;
     help|--help|-h) _help "$@" ;;
     "") [[ -f ".roll/backlog.md" ]] && _home || { _help; _show_changelog; } ;;