@seanyao/roll 2026.519.2 → 2026.520.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.519.2"
+VERSION="2026.520.1"
 ROLL_HOME="${ROLL_HOME:-${HOME}/.roll}"
 ROLL_CONFIG="${ROLL_HOME}/config.yaml"
 ROLL_GLOBAL="${ROLL_HOME}/conventions/global"
@@ -986,10 +986,16 @@ cmd_init() {
 
 # 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.
+# Roll conventions. US-ONBOARD-012 widened the recogniser to cover non-canonical
+# layouts (WeChat mini-program, Python flat, Terraform, etc.) — any of:
+#   1. Classic layout: src/app/lib/pkg/cmd contains ≥10 non-empty files.
+#   2. A manifest of any common ecosystem at the project root.
+#   3. Git history exists (at least one commit on HEAD).
+# Either signal alone is enough; the AGENTS.md check happens earlier.
 _init_is_legacy_project() {
   local project_dir="$1"
+
+  # Signal 1 — classic source layout
   local dir count
   for dir in src app lib pkg cmd; do
     if [[ -d "$project_dir/$dir" ]]; then
@@ -999,6 +1005,29 @@ _init_is_legacy_project() {
       fi
     fi
   done
+
+  # Signal 2 — manifest file at project root
+  local manifest
+  for manifest in \
+      package.json pyproject.toml requirements.txt setup.py setup.cfg Pipfile \
+      go.mod Cargo.toml Gemfile pom.xml build.gradle build.gradle.kts \
+      Makefile Dockerfile docker-compose.yml docker-compose.yaml \
+      app.json project.config.json \
+      mix.exs composer.json deno.json deno.jsonc; do
+    [[ -f "$project_dir/$manifest" ]] && return 0
+  done
+  # Terraform: any *.tf at the root
+  if compgen -G "$project_dir/*.tf" >/dev/null 2>&1; then
+    return 0
+  fi
+
+  # Signal 3 — git history exists
+  if [[ -d "$project_dir/.git" ]] || [[ -f "$project_dir/.git" ]]; then
+    if ( cd "$project_dir" && git rev-parse --verify HEAD >/dev/null 2>&1 ); then
+      return 0
+    fi
+  fi
+
   return 1
 }
 
@@ -1085,9 +1114,96 @@ _init_legacy_file_summary() {
       fi
     fi
   done
+  # US-ONBOARD-012: surface non-canonical signals in the summary too.
+  local manifest
+  for manifest in \
+      package.json pyproject.toml requirements.txt setup.py setup.cfg Pipfile \
+      go.mod Cargo.toml Gemfile pom.xml build.gradle build.gradle.kts \
+      Makefile Dockerfile docker-compose.yml docker-compose.yaml \
+      app.json project.config.json \
+      mix.exs composer.json deno.json deno.jsonc; do
+    if [[ -f "$project_dir/$manifest" ]]; then
+      parts+=("manifest: $manifest")
+      break
+    fi
+  done
+  if compgen -G "$project_dir/*.tf" >/dev/null 2>&1; then
+    parts+=("Terraform .tf files")
+  fi
+  if [[ ${#parts[@]} -eq 0 ]] \
+      && { [[ -d "$project_dir/.git" ]] || [[ -f "$project_dir/.git" ]]; } \
+      && ( cd "$project_dir" && git rev-parse --verify HEAD >/dev/null 2>&1 ); then
+    parts+=("git history present")
+  fi
   echo "no AGENTS.md, ${parts[*]}"
 }
 
+# US-ONBOARD-013: changeset recording — onboard writes a manifest of every
+# side effect (files created, .gitignore entries, scope) into
+# .roll/onboard-changeset.yaml so `roll offboard` has a rollback record.
+# Without this, a user who wants to retire Roll from a project has to guess
+# which files came from onboard vs their own work.
+_onboard_changeset_path() {
+  echo "$1/.roll/onboard-changeset.yaml"
+}
+
+# Begin a fresh changeset record. Overwrites any prior file — every apply
+# starts from a clean slate; offboard reads the latest record.
+_onboard_changeset_begin() {
+  local project_dir="$1"
+  local path; path=$(_onboard_changeset_path "$project_dir")
+  mkdir -p "$(dirname "$path")"
+  cat > "$path" <<EOF
+# Generated by \`roll init --apply\`. Used by \`roll offboard\` to reverse
+# the changes onboard made. Do not edit by hand.
+onboarded_at: "$(date -u +%FT%TZ)"
+roll_version: "$(_pkg_version 2>/dev/null || echo unknown)"
+scope_approved: []
+files_created: []
+dirs_created: []
+gitignore_entries_added: []
+launchd_plists_installed: []
+EOF
+}
+
+# Append a YAML list entry to a section in the changeset.
+_onboard_changeset_record() {
+  local project_dir="$1" section="$2" value="$3"
+  local path; path=$(_onboard_changeset_path "$project_dir")
+  [ -f "$path" ] || return 0
+  # Each section line ends with `: []` — replace with the new value on first
+  # entry, otherwise append a `- <value>` line under the section.
+  if grep -qE "^${section}: \[\]$" "$path"; then
+    local tmp; tmp=$(mktemp)
+    awk -v sec="$section" -v val="$value" '
+      $0 ~ "^" sec ": \\[\\]$" {
+        print sec ":"
+        print "  - \"" val "\""
+        next
+      }
+      { print }
+    ' "$path" > "$tmp" && mv "$tmp" "$path"
+  else
+    # Find the section header and insert under it (after the last entry).
+    local tmp; tmp=$(mktemp)
+    awk -v sec="$section" -v val="$value" '
+      $0 ~ "^" sec ":$" {
+        print
+        in_sec=1; next
+      }
+      in_sec && /^[a-z_]+:/ {
+        print "  - \"" val "\""
+        in_sec=0
+        print; next
+      }
+      { print }
+      END {
+        if (in_sec) print "  - \"" val "\""
+      }
+    ' "$path" > "$tmp" && mv "$tmp" "$path"
+  fi
+}
+
 # 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
@@ -1124,6 +1240,9 @@ _init_apply() {
   info "Applying onboard plan...  正在应用 onboard 计划..."
   _ROLL_MERGE_SUMMARY=()
 
+  # US-ONBOARD-013: start a fresh changeset record so offboard can reverse.
+  _onboard_changeset_begin "$project_dir"
+
   # Read scope from plan (simple grep — validator confirmed structure)
   local approved
   approved=$(python3 -c "
@@ -1132,22 +1251,33 @@ p = yaml.safe_load(open('$plan'))
 print(' '.join(p.get('scope', {}).get('approved', [])))
 " 2>/dev/null || echo "")
 
+  # Record each approved scope entry for offboard's selective rollback.
+  local item
+  for item in $approved; do
+    _onboard_changeset_record "$project_dir" "scope_approved" "$item"
+  done
+
   _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"
+    _onboard_changeset_record "$project_dir" "files_created" ".roll/backlog.md"
   fi
   if [[ " $approved " == *" features "* ]]; then
     _ensure_features_dir "$project_dir/.roll/features"
     _write_features_md "$project_dir/.roll/features.md"
+    _onboard_changeset_record "$project_dir" "dirs_created" ".roll/features"
+    _onboard_changeset_record "$project_dir" "files_created" ".roll/features.md"
   fi
   if [[ " $approved " == *" domain "* ]]; then
     mkdir -p "$project_dir/.roll/domain"
+    _onboard_changeset_record "$project_dir" "dirs_created" ".roll/domain"
   fi
   if [[ " $approved " == *" briefs "* ]]; then
     mkdir -p "$project_dir/.roll/briefs"
+    _onboard_changeset_record "$project_dir" "dirs_created" ".roll/briefs"
   fi
 
   print_merge_summary
@@ -1164,6 +1294,7 @@ print('true' if p.get('privacy', {}).get('gitignore_dot_roll', False) else 'fals
     local gi="$project_dir/.gitignore"
     if ! grep -qFx ".roll/" "$gi" 2>/dev/null; then
       echo ".roll/" >> "$gi"
+      _onboard_changeset_record "$project_dir" "gitignore_entries_added" ".roll/"
       ok "Added .roll/ to .gitignore  已将 .roll/ 加入 .gitignore"
     fi
   fi
@@ -1176,6 +1307,178 @@ print('true' if p.get('privacy', {}).get('gitignore_dot_roll', False) else 'fals
   ok "Onboard apply complete.  Onboard 应用完成。"
 }
 
+# US-ONBOARD-014: roll offboard
+# Reverse what `roll init --apply` (US-ONBOARD-009/013) did, using the
+# changeset manifest at .roll/onboard-changeset.yaml as the rollback record.
+# Safety contract:
+#   1. Refuse when no changeset exists — print manual instructions instead.
+#   2. Default to dry-run; only `--confirm` (or `-y`) actually deletes.
+#   3. Only touch entries that are in the manifest. Anything else stays put.
+#   4. Refuse to delete a file/dir whose path does not resolve under the
+#      current project root, even if the changeset says so (cross-project
+#      guard). Print the safe manual command instead.
+cmd_offboard() {
+  local confirm=0
+  local arg
+  for arg in "$@"; do
+    case "$arg" in
+      --confirm|-y) confirm=1 ;;
+      --help|-h)
+        echo "Usage: roll offboard [--confirm]"
+        echo "  Preview (default) or apply (--confirm) the removal of every"
+        echo "  artefact recorded in .roll/onboard-changeset.yaml."
+        return 0
+        ;;
+      *)
+        err "Unknown flag: $arg  未知参数"
+        return 1
+        ;;
+    esac
+  done
+
+  local project_dir; project_dir="$(pwd -P)"
+  local changeset; changeset=$(_onboard_changeset_path "$project_dir")
+
+  if [[ ! -f "$changeset" ]]; then
+    err "No onboard changeset found at .roll/onboard-changeset.yaml"
+    err "未找到 onboard 变更清单 .roll/onboard-changeset.yaml"
+    echo "" >&2
+    echo "  Manual offboard — remove these by hand if they came from Roll:" >&2
+    echo "    rm -rf .roll/                  # all process artefacts" >&2
+    echo "    rm -f AGENTS.md CLAUDE.md      # only if they were generated by roll init" >&2
+    echo "    Edit .gitignore to remove any '.roll/' entry" >&2
+    return 1
+  fi
+
+  # Parse changeset (Python keeps YAML semantics consistent with apply).
+  local parser
+  parser=$(python3 - "$changeset" <<'PY'
+import sys, yaml
+try:
+    data = yaml.safe_load(open(sys.argv[1])) or {}
+except Exception as e:
+    print(f"PARSE_ERROR:{e}", file=sys.stderr)
+    sys.exit(2)
+def pr(section):
+    for v in (data.get(section) or []):
+        print(f"{section}\t{v}")
+pr("files_created")
+pr("dirs_created")
+pr("gitignore_entries_added")
+pr("launchd_plists_installed")
+PY
+  )
+  if [[ $? -ne 0 ]]; then
+    err "Failed to parse changeset  解析变更清单失败"
+    return 1
+  fi
+
+  local files=() dirs=() gi_entries=() plists=()
+  while IFS=$'\t' read -r section value; do
+    [[ -z "$section" ]] && continue
+    case "$section" in
+      files_created)           files+=("$value") ;;
+      dirs_created)            dirs+=("$value") ;;
+      gitignore_entries_added) gi_entries+=("$value") ;;
+      launchd_plists_installed) plists+=("$value") ;;
+    esac
+  done <<< "$parser"
+
+  # Cross-project guard — verify every recorded path resolves under
+  # project_dir. Catches the case where a user accidentally points roll
+  # offboard at a directory whose changeset names paths from elsewhere.
+  local item resolved
+  local _all=()
+  [ "${#files[@]}" -gt 0 ] && _all+=("${files[@]}")
+  [ "${#dirs[@]}" -gt 0 ]  && _all+=("${dirs[@]}")
+  for item in "${_all[@]:+${_all[@]}}"; do
+    case "$item" in
+      /*) resolved="$item" ;;        # absolute — must already start with project_dir
+      *)  resolved="$project_dir/$item" ;;
+    esac
+    case "$resolved" in
+      "$project_dir"|"$project_dir"/*) ;;
+      *)
+        err "Refusing to act on '$item' — it does not resolve under $project_dir"
+        err "拒绝处理 '$item' — 路径不在当前项目下，可能是误用"
+        echo "  This usually means the changeset was copied from another project." >&2
+        echo "  Remove .roll/onboard-changeset.yaml manually, or rerun in the right dir." >&2
+        return 1
+        ;;
+    esac
+  done
+
+  # Print the plan.
+  echo ""
+  echo -e "  ${BOLD}Offboard plan for ${project_dir}${NC}"
+  echo ""
+  if [[ ${#files[@]} -gt 0 ]]; then
+    echo -e "  ${RED}Files to remove:${NC}"
+    for item in "${files[@]}"; do echo "    rm   $item"; done
+    echo ""
+  fi
+  if [[ ${#dirs[@]} -gt 0 ]]; then
+    echo -e "  ${RED}Directories to remove:${NC}"
+    for item in "${dirs[@]}"; do echo "    rmdir/r $item"; done
+    echo ""
+  fi
+  if [[ ${#gi_entries[@]} -gt 0 ]]; then
+    echo -e "  ${YELLOW}.gitignore entries to remove:${NC}"
+    for item in "${gi_entries[@]}"; do echo "    -    $item"; done
+    echo ""
+  fi
+  if [[ ${#plists[@]} -gt 0 ]]; then
+    echo -e "  ${YELLOW}launchd plists to unload:${NC}"
+    for item in "${plists[@]}"; do echo "    unload $item"; done
+    echo ""
+  fi
+  if [[ ${#files[@]} -eq 0 && ${#dirs[@]} -eq 0 && ${#gi_entries[@]} -eq 0 && ${#plists[@]} -eq 0 ]]; then
+    info "Changeset is empty — nothing to offboard."
+    info "变更清单为空，无需 offboard。"
+    return 0
+  fi
+
+  if [[ "$confirm" -ne 1 ]]; then
+    echo "  This is a dry-run. Re-run with --confirm to apply."
+    echo "  以上为预演结果。加 --confirm 后才会真正执行。"
+    return 0
+  fi
+
+  # Apply. Guard every loop with a count check — `set -u` upstream makes
+  # naked `"${arr[@]}"` over an empty array a hard error on bash 5.0.
+  echo "  Applying offboard...  执行 offboard..."
+  if [ "${#files[@]}" -gt 0 ]; then
+    for item in "${files[@]}"; do
+      rm -f "$project_dir/$item" 2>/dev/null && echo "    removed file $item"
+    done
+  fi
+  if [ "${#dirs[@]}" -gt 0 ]; then
+    for item in "${dirs[@]}"; do
+      rm -rf "$project_dir/$item" 2>/dev/null && echo "    removed dir  $item"
+    done
+  fi
+  if [ "${#gi_entries[@]}" -gt 0 ]; then
+    for item in "${gi_entries[@]}"; do
+      local gi="$project_dir/.gitignore"
+      if [[ -f "$gi" ]] && grep -qFx "$item" "$gi"; then
+        local tmp; tmp=$(mktemp)
+        grep -vFx "$item" "$gi" > "$tmp" || true
+        mv "$tmp" "$gi"
+        echo "    .gitignore -   $item"
+      fi
+    done
+  fi
+  if [ "${#plists[@]}" -gt 0 ]; then
+    for item in "${plists[@]}"; do
+      launchctl unload -w "$HOME/Library/LaunchAgents/$item" 2>/dev/null && echo "    unloaded     $item"
+      rm -f "$HOME/Library/LaunchAgents/$item" 2>/dev/null
+    done
+  fi
+  # Finally, remove the changeset file itself.
+  rm -f "$changeset"
+  ok "Offboard complete.  Offboard 完成。"
+}
+
 # ═══════════════════════════════════════════════════════════════════════════════
 # cmd_migrate
 # US-ONBOARD-003: One-shot migration from old project layout to .roll/ structure.
@@ -1916,6 +2219,9 @@ cmd_peer() {
   local context_file=""
   local yolo=false
   local subcmd=""
+  # US-VIEW-009: parse --demo before any side effects so the v2 renderer can
+  # run standalone (no peer state, no tmux session, no agent call).
+  local demo=false
 
   while [[ $# -gt 0 ]]; do
     case "$1" in
@@ -1925,6 +2231,7 @@ cmd_peer() {
       --tag) tag="$2"; shift 2 ;;
       --context) context_file="$2"; shift 2 ;;
       --yes|--yolo) yolo=true; shift ;;
+      --demo) demo=true; shift ;;
       status) subcmd="status"; shift ;;
       reset) subcmd="reset"; shift; break ;;
       help|--help|-h) subcmd="help"; shift ;;
@@ -1932,6 +2239,13 @@ cmd_peer() {
     esac
   done
 
+  # US-VIEW-009: ROLL_UI=v2 (default) + --demo routes to the redesigned Python view.
+  # Set ROLL_UI=v1 to fall back to the legacy bash implementation.
+  if [[ "$demo" == "true" ]] && { [[ "${ROLL_UI:-v2}" == "v2" ]] || [[ "$demo" == "true" ]]; }; then
+    python3 "${ROLL_PKG_DIR}/lib/roll-peer.py" --demo
+    return
+  fi
+
   case "$subcmd" in
     status) cmd_peer_status; return ;;
     reset) cmd_peer_reset "$@"; return ;;
@@ -2192,8 +2506,22 @@ cmd_peer_help() {
 # AGENT — per-project agent configuration
 # ═══════════════════════════════════════════════════════════════════════════════
 
+# REFACTOR-040: project agent preference moved from the project root
+# (`.roll.yaml`) to `.roll/local.yaml`. The new location stays alongside other
+# per-machine runtime state inside `.roll/`, never reaches git (.roll/ is
+# gitignored), and keeps the project root clean. The old `.roll.yaml` location
+# is still read as a fallback so existing checkouts keep working until the next
+# `roll agent use` rewrites them in place.
+_project_agent_pref_file() {
+  echo ".roll/local.yaml"
+}
+
 _project_agent() {
-  if [[ -f ".roll.yaml" ]] && grep -q "^agent:" .roll.yaml 2>/dev/null; then
+  local pref new_pref
+  new_pref=$(_project_agent_pref_file)
+  if [[ -f "$new_pref" ]] && grep -q "^agent:" "$new_pref" 2>/dev/null; then
+    grep "^agent:" "$new_pref" | awk '{print $2}' | tr -d '"' | head -1
+  elif [[ -f ".roll.yaml" ]] && grep -q "^agent:" .roll.yaml 2>/dev/null; then
     grep "^agent:" .roll.yaml | awk '{print $2}' | tr -d '"' | head -1
   elif [[ -f "$ROLL_CONFIG" ]] && grep -q "primary_agent:" "$ROLL_CONFIG" 2>/dev/null; then
     grep "primary_agent:" "$ROLL_CONFIG" | awk '{print $2}' | tr -d '"' | head -1
@@ -2343,7 +2671,13 @@ cmd_review_pr() {
   local output
   info "Reviewing PR #${pr_number} with ${agent}..."
   _agent_argv "$agent" text "$prompt" || { err "Unknown agent '${agent}'"; return 1; }
-  output=$("${_AGENT_ARGV[@]}" 2>/dev/null)
+  local _stderr_log; _stderr_log=$(mktemp)
+  output=$("${_AGENT_ARGV[@]}" 2>"$_stderr_log")
+  if [[ -z "$output" && -s "$_stderr_log" ]]; then
+    err "agent ${agent} produced no output. stderr (first 5 lines):"
+    head -5 "$_stderr_log" | sed 's/^/    /' >&2
+  fi
+  rm -f "$_stderr_log"
 
   echo "$output"
 
@@ -2382,10 +2716,25 @@ cmd_agent() {
       local name="${1:-}"
       [[ -z "$name" ]] && { err "Usage: roll agent use <claude|kimi|deepseek|pi|codex|opencode>"; exit 1; }
       command -v "$name" &>/dev/null || warn "${name} not found in PATH — setting anyway  未找到，仍写入配置"
-      if [[ -f ".roll.yaml" ]] && grep -q "^agent:" .roll.yaml; then
-        local tmp; tmp=$(mktemp) && sed "s/^agent:.*/agent: ${name}/" .roll.yaml > "$tmp" && mv "$tmp" .roll.yaml
+      # REFACTOR-040: write to .roll/local.yaml (per-machine state). Migrate
+      # from legacy .roll.yaml in the project root on the spot — copy the
+      # value over once, then delete the old file so the root stays clean.
+      mkdir -p .roll
+      local pref; pref=$(_project_agent_pref_file)
+      if [[ -f "$pref" ]] && grep -q "^agent:" "$pref"; then
+        local tmp; tmp=$(mktemp) && sed "s/^agent:.*/agent: ${name}/" "$pref" > "$tmp" && mv "$tmp" "$pref"
       else
-        echo "agent: ${name}" >> .roll.yaml
+        echo "agent: ${name}" >> "$pref"
+      fi
+      if [[ -f ".roll.yaml" ]]; then
+        # Drop legacy agent line; remove the file if it's left empty (covers
+        # the common case where .roll.yaml only ever held the agent pref).
+        # grep -v returns 1 when nothing remains after filtering — that's a
+        # success here, so suppress the exit code so the mv still runs.
+        local tmp; tmp=$(mktemp)
+        grep -v "^agent:" .roll.yaml > "$tmp" 2>/dev/null || true
+        mv "$tmp" .roll.yaml
+        [[ -s ".roll.yaml" ]] || rm -f .roll.yaml
       fi
       ok "Agent set to ${name} for this project  当前项目 agent 已设为 ${name}"
       local project_path; project_path=$(pwd -P)
@@ -2410,7 +2759,13 @@ cmd_agent() {
       ;;
     "")
       local agent; agent=$(_project_agent)
-      local src="global"; [[ -f ".roll.yaml" ]] && grep -q "^agent:" .roll.yaml 2>/dev/null && src="project (.roll.yaml)"
+      local src="global"
+      local pref; pref=$(_project_agent_pref_file)
+      if [[ -f "$pref" ]] && grep -q "^agent:" "$pref" 2>/dev/null; then
+        src="project (.roll/local.yaml)"
+      elif [[ -f ".roll.yaml" ]] && grep -q "^agent:" .roll.yaml 2>/dev/null; then
+        src="project (.roll.yaml, legacy — run \`roll agent use\` to migrate)"
+      fi
       echo -e "\n  Agent  ${CYAN}${agent}${NC}  (${src})\n"
       echo "  roll agent use <name>   — switch agent for this project"
       echo "  roll agent list         — show installed agents"; echo ""
@@ -2545,6 +2900,35 @@ PYEOF
 }
 
 _LOOP_TAG="# roll-loop"
+# FIX-065: when sourced in a test context with no explicit override, route
+# shared state into a per-process /tmp path instead of falling back to
+# production ~/.shared/roll/. Without this safety net, tests that source
+# bin/roll (directly or via a generated inner runner under /var/folders/)
+# would write ALERT / state / events / runs.jsonl into the live loop
+# daemon's monitored directory and trigger false aborts.
+#
+# Test context is detected via three signals (any one is enough):
+#   1. BATS_TEST_FILENAME is set (works for direct test invocations)
+#   2. The caller's file path lives under /tmp or /var/folders (catches the
+#      generated runner-inner.sh path that bats subprocesses spawn —
+#      BATS_* env can be lost across `bash -l` + nested forks)
+#   3. PWD is under /tmp or /var/folders (catches helpers that cd'd in)
+if [ -z "${_SHARED_ROOT:-}" ]; then
+  _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
+    _SHARED_ROOT="${TMPDIR:-/tmp}/roll-test-shared.$$"
+    mkdir -p "${_SHARED_ROOT}/loop"
+    export _SHARED_ROOT
+  fi
+  unset _roll_in_test_ctx _roll_caller
+fi
 : "${_SHARED_ROOT:=${HOME}/.shared/roll}"
 # FIX-052: per-project loop state — ALERT/state/mute were globally shared,
 # causing one project's alerts to surface in another project's session and
@@ -2553,7 +2937,9 @@ _LOOP_TAG="# roll-loop"
 : "${_LOOP_PROJ_SLUG:=$(_project_slug 2>/dev/null || echo default)}"
 : "${_LOOP_STATE:=${_SHARED_ROOT}/loop/state-${_LOOP_PROJ_SLUG}.yaml}"
 : "${_LOOP_ALERT:=${_SHARED_ROOT}/loop/ALERT-${_LOOP_PROJ_SLUG}.md}"
-_LOOP_RUNS="${HOME}/.shared/roll/loop/runs.jsonl"
+# FIX-065: was hardcoded to ${HOME}/.shared/roll/loop/runs.jsonl which ignored
+# _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"
 
@@ -2564,6 +2950,13 @@ _config_read_int() {
   if [[ "$val" =~ ^[0-9]+$ ]]; then echo "$val"; else echo "$default"; fi
 }
 
+# REFACTOR-031: cross-platform file mtime in epoch seconds.
+# Replaces the `stat -c %Y ... || stat -f %m ... || echo 0` pattern that was
+# copy-pasted in four places (dashboard age widgets, briefs, dream, peer).
+_file_mtime() {
+  stat -c %Y "$1" 2>/dev/null || stat -f %m "$1" 2>/dev/null || echo 0
+}
+
 # Derive a minute in [1,55] from project path hash + offset so different projects
 # and different services within a project don't fire at the same time.
 # Offsets used: loop=0, dream=2, brief=4 → always three distinct values (2<55).
@@ -2589,25 +2982,39 @@ _loop_event() {
   ts=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
   slug=$(_project_slug 2>/dev/null || basename "$PWD")
   evfile="${_SHARED_ROOT:-$HOME/.shared/roll}/loop/events-${slug}.ndjson"
+  # FIX-065 tripwire: in a test context (BATS or temp cwd), refuse to write
+  # into production ~/.shared/roll/. Catching this in code is the last line
+  # of defense if some unusual path bypassed the auto-sandbox at source-time.
+  # Skipped when HOME itself has been redirected to a sandbox dir — then
+  # $HOME/.shared/roll IS the sandbox, not prod.
+  case "${HOME:-}" in
+    /tmp/*|/private/tmp/*|*/var/folders/*|*/tmp.*) ;;
+    *)
+      if [ -n "${HOME:-}" ] && [ "${evfile#${HOME}/.shared/roll/}" != "$evfile" ]; then
+        case "${BATS_TEST_FILENAME:-}${PWD}" in
+          */tmp.*|*/var/folders/*|/tmp/*|/private/tmp/*|*.bats)
+            echo "[FIX-065] refusing prod _loop_event write: $evfile (test context)" >&2
+            return 1
+            ;;
+        esac
+      fi
+      ;;
+  esac
   mkdir -p "$(dirname "$evfile")"
 
   # stdout: tab-separated for tmux display
   printf '%s\t%s\t%s\t%s\t%s\n' "$ts" "$stage" "$label" "$detail" "$outcome"
 
-  # JSON line appended to NDJSON file; serialized with flock (Linux) or
-  # lockf (macOS/BSD) — fall back to unguarded append when neither is available.
+  # JSON line appended to NDJSON file. FIX-067: drop the flock/lockf guard.
+  # POSIX requires write() ≤ PIPE_BUF (≥512 bytes, 4 KiB on Linux/macOS) to
+  # a file opened O_APPEND be atomic across concurrent writers, and a single
+  # JSONL event line is well under that limit. The old lockfile path could
+  # stall the EXIT trap added in FIX-066 when the lockfile state was
+  # inconsistent, leaving cycle_end unwritten when the outer SIGHUP fired —
+  # defeating FIX-066's whole purpose.
   json=$(printf '{"ts":"%s","stage":"%s","label":"%s","detail":"%s","outcome":"%s"}\n' \
     "$ts" "$stage" "$label" "$detail" "$outcome")
-  if command -v flock >/dev/null 2>&1; then
-    (
-      flock -x 9
-      printf '%s\n' "$json" >> "$evfile"
-    ) 9>>"${evfile}.lock"
-  elif command -v lockf >/dev/null 2>&1; then
-    lockf -s "${evfile}.lock" sh -c "printf '%s\n' $(printf '%q' "$json") >> $(printf '%q' "$evfile")"
-  else
-    printf '%s\n' "$json" >> "$evfile"
-  fi
+  printf '%s\n' "$json" >> "$evfile"
 
   # File rotation: if >10MB, rotate keeping last 5
   _loop_event_rotate "$evfile"
@@ -2779,7 +3186,7 @@ fi
 printf '%s:%s\n' "\$\$" "\$(date -u +%s)" > "\$INNER_LOCK"
 # FIX-038: background heartbeat writer — outer script uses this as primary liveness signal
 # to detect stale execution without relying on PID reuse heuristics.
-HEARTBEAT_FILE="${HOME}/.shared/roll/loop/.heartbeat-${slug}"
+HEARTBEAT_FILE="\${_SHARED_ROOT:-\${HOME}/.shared/roll}/loop/.heartbeat-${slug}"
 _heartbeat_writer() {
   while true; do echo "\$(date -u +%s)" > "\$HEARTBEAT_FILE"; sleep 60; done
 }
@@ -2791,6 +3198,11 @@ _HEARTBEAT_PID=\$!
 # next cron tick can proceed. Overridable via env for tests.
 LOOP_CYCLE_TIMEOUT_SEC="\${ROLL_LOOP_CYCLE_TIMEOUT_SEC:-2700}"
 _CYCLE_TIMED_OUT=0
+# IDEA-028 / FIX-066: track whether cycle_end has been emitted via any of the
+# explicit completion paths (publish/merge_back/orphan-push/claude-failed).
+# When zero, the EXIT trap emits a fallback so cycle_start never orphans the
+# dashboard into a phantom "still running" row.
+_CYCLE_END_WRITTEN=0
 _on_sigterm() { _CYCLE_TIMED_OUT=1; }
 trap '_on_sigterm' TERM
 # US-LOOP-005: idempotent runs.jsonl writer shared by normal exit, timeout
@@ -2798,7 +3210,7 @@ trap '_on_sigterm' TERM
 # 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"
+  local _runs_dst="\${_SHARED_ROOT:-\${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%-*}"
@@ -2834,12 +3246,21 @@ _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
+    _CYCLE_END_WRITTEN=1
     # 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
+  # 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
+  # "still running" until the next successful cycle rolls past it.
+  if [ "\${_CYCLE_END_WRITTEN:-0}" -eq 0 ] && [ -n "\${CYCLE_ID:-}" ]; then
+    _loop_event cycle_end "\${CYCLE_ID}" "\${BRANCH:-}" "aborted" 2>/dev/null || true
+    _runs_append "aborted" 0 "[]" 2>/dev/null || true
+  fi
   rm -f "\$INNER_LOCK" "\$HEARTBEAT_FILE"
   exit "\$_rc"
 }
@@ -2864,6 +3285,10 @@ _LOOP_MUTE_FILE="\${_SHARED_ROOT}/loop/mute-${slug}"
 # 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}"
+# FIX-070: helpers that need to update the main repo's backlog (e.g. when a
+# worktree cycle marks a story 🔨 In Progress) read ROLL_MAIN_PROJECT to
+# locate it — the cycle's own cwd is the worktree, not main.
+export ROLL_MAIN_PROJECT="${project_path}"
 
 # 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
@@ -2915,6 +3340,11 @@ if _worktree_fetch_origin main \\
    && _worktree_create "\$WT" "\$BRANCH" "origin/main"; then
   _USE_WORKTREE=1
   _worktree_submodule_init "\$WT" 2>/dev/null || true
+  # FIX-069: copy .roll/ meta (backlog, skills, conventions) into the
+  # worktree as a read-only reference. Without this the cycle no-ops
+  # because .roll/ is gitignored and the clean clone has no backlog
+  # for Claude to read or skill entry points to dispatch to.
+  _worktree_sync_meta "\$WT" 2>/dev/null || true
   echo "[loop] cycle \${CYCLE_ID}: worktree \$WT on \$BRANCH"
   _loop_event cycle_start "\${CYCLE_ID}" "" "" || true
 else
@@ -2939,11 +3369,25 @@ export LOOP_PROJECT_SLUG="${slug}"
 export LOOP_CYCLE_ID="\${CYCLE_ID}"
 export LOOP_SHARED_ROOT="\${_SHARED_ROOT:-\$HOME/.shared/roll}"
 for _attempt in 1 2 3; do
-  # FIX-057: watchdog — fires SIGTERM at the inner script (and its direct
-  # children) when the cycle exceeds LOOP_CYCLE_TIMEOUT_SEC. Signal the inner
-  # script first so _on_sigterm sets _CYCLE_TIMED_OUT before pkill takes out
-  # the watchdog subshell itself (pkill -P \$\$ matches this subshell too).
-  ( sleep "\$LOOP_CYCLE_TIMEOUT_SEC" && { kill -TERM \$\$ 2>/dev/null; pkill -TERM -P \$\$ 2>/dev/null; } ) &
+  # FIX-068: defensive reset before each attempt — _CYCLE_TIMED_OUT carries
+  # the SIGTERM result of the previous attempt and would otherwise force an
+  # immediate break on a clean retry.
+  _CYCLE_TIMED_OUT=0
+  # FIX-057 + FIX-068: watchdog — fires SIGTERM at the inner script (and its
+  # direct children) when the cycle exceeds LOOP_CYCLE_TIMEOUT_SEC, then
+  # escalates to SIGKILL after a 5s grace period for any claude process
+  # still alive. claude lives inside a pipeline subshell, so pkill -P \$\$
+  # alone only catches the subshell, not claude itself; matching by the
+  # worktree path (which appears in claude's --add-dir arg, FIX-048) targets
+  # the cycle's claude uniquely without touching other projects' processes.
+  ( sleep "\$LOOP_CYCLE_TIMEOUT_SEC" && {
+      kill -TERM \$\$ 2>/dev/null
+      pkill -TERM -P \$\$ 2>/dev/null
+      pkill -TERM -f "\$WT" 2>/dev/null
+      sleep 5
+      pkill -KILL -P \$\$ 2>/dev/null
+      pkill -KILL -f "\$WT" 2>/dev/null
+    } ) &
   _WATCHDOG_PID=\$!
   if [ -f "\$FMT" ]; then
     ( cd "\$WT" && ${claude_cmd} ) | python3 "\$FMT"
@@ -3023,13 +3467,13 @@ if [ "\$_USE_WORKTREE" = "1" ]; then
           fi
         fi
         _worktree_cleanup "\$WT" "\$BRANCH"
-        _loop_event cycle_end "\${CYCLE_ID}" "" "done" || true
+        _loop_event cycle_end "\${CYCLE_ID}" "" "done" || true; _CYCLE_END_WRITTEN=1
         echo "[loop] cycle \${CYCLE_ID}: published; worktree cleaned"
       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
+          _loop_event cycle_end "\${CYCLE_ID}" "" "done" || true; _CYCLE_END_WRITTEN=1
           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
@@ -3040,12 +3484,12 @@ if [ "\$_USE_WORKTREE" = "1" ]; then
                && 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
+            _loop_event cycle_end "\${CYCLE_ID}" "" "orphan" || true; _CYCLE_END_WRITTEN=1
             _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
+            _loop_event cycle_end "\${CYCLE_ID}" "" "failed" || true; _CYCLE_END_WRITTEN=1
             _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
@@ -3059,12 +3503,12 @@ if [ "\$_USE_WORKTREE" = "1" ]; then
              && 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
+          _loop_event cycle_end "\${CYCLE_ID}" "" "orphan" || true; _CYCLE_END_WRITTEN=1
           _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
+          _loop_event cycle_end "\${CYCLE_ID}" "" "failed" || true; _CYCLE_END_WRITTEN=1
           _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
@@ -3072,7 +3516,7 @@ if [ "\$_USE_WORKTREE" = "1" ]; then
     fi
   else
     # US-LOOP-005 T8: claude session failed after retry budget → cycle_end failed
-    _loop_event cycle_end "\${CYCLE_ID}" "" "failed" || true
+    _loop_event cycle_end "\${CYCLE_ID}" "" "failed" || true; _CYCLE_END_WRITTEN=1
     _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
@@ -3117,13 +3561,13 @@ if [ -z "\$ROLL_LOOP_FORCE" ] && [ -f "\$PAUSE" ]; then exit 0; fi
 HEARTBEAT_TIMEOUT="\${ROLL_HEARTBEAT_TIMEOUT:-1800}"
 # FIX-052: per-project STATE_FILE (was global state.yaml — caused two projects
 # to clobber each other's cycle state).
-STATE_FILE="${HOME}/.shared/roll/loop/state-${slug}.yaml"
+STATE_FILE="\${_SHARED_ROOT:-\${HOME}/.shared/roll}/loop/state-${slug}.yaml"
 if [ -f "\$STATE_FILE" ]; then
   _state=\$(grep '^status:' "\$STATE_FILE" | awk '{print \$2}' 2>/dev/null || echo "")
   if [ "\$_state" = "running" ]; then
     _still_active=false
     # FIX-038: heartbeat is primary signal
-    _heartbeat_file="${HOME}/.shared/roll/loop/.heartbeat-${slug}"
+    _heartbeat_file="\${_SHARED_ROOT:-\${HOME}/.shared/roll}/loop/.heartbeat-${slug}"
     if [ -f "\$_heartbeat_file" ]; then
       _hb_ts=\$(cat "\$_heartbeat_file" 2>/dev/null || echo "0")
       _now=\$(date -u +%s)
@@ -4102,50 +4546,10 @@ _loop_heal_dir() {
   printf '%s\n' "${ROLL_LOOP_DIR:-${HOME}/.shared/roll/loop}/heal"
 }
 
-# Bounded CI self-heal gate. Called by the loop SKILL when the
-# post-build CI check goes red. Counter is per-story, persisted under
-# $ROLL_LOOP_DIR/heal/<story-id>.count, so retries survive cycle boundaries.
-#
-# Exit 0: another heal attempt is allowed (counter incremented). Caller should
-#         invoke roll-fix with the failure summary, then re-run the CI gate.
-# Exit 1: heal disabled (ROLL_LOOP_NO_HEAL=1) or exhausted (>= ROLL_LOOP_HEAL_MAX).
-#         Caller should write ALERT and stop.
-_loop_self_heal_ci() {
-  local story_id="$1"
-  [[ -z "$story_id" ]] && return 1
-  [[ "${ROLL_LOOP_NO_HEAL:-0}" == "1" ]] && return 1
-  local max="${ROLL_LOOP_HEAL_MAX:-2}"
-  local state="$_LOOP_STATE"
-  local current=0
-  if [[ -f "$state" ]]; then
-    local raw; raw=$(grep '^heal_count:' "$state" 2>/dev/null | awk '{print $2}')
-    [[ "$raw" =~ ^[0-9]+$ ]] && current="$raw"
-  fi
-  [[ "$current" -ge "$max" ]] && return 1
-  local new=$((current + 1))
-  mkdir -p "$(dirname "$state")"
-  if grep -q '^heal_count:' "$state" 2>/dev/null; then
-    local tmp; tmp=$(mktemp)
-    sed "s/^heal_count:.*/heal_count: ${new}/" "$state" > "$tmp"
-    mv "$tmp" "$state"
-  else
-    echo "heal_count: ${new}" >> "$state"
-  fi
-  return 0
-}
-
-# Reset per-story heal counter. Called when CI eventually turns green or by
-# `roll loop reset`. Idempotent.
-_loop_clear_heal_state() {
-  local story_id="$1"
-  [[ -z "$story_id" ]] && return 0
-  local state="$_LOOP_STATE"
-  [[ ! -f "$state" ]] && return 0
-  local tmp; tmp=$(mktemp)
-  grep -v '^heal_count:' "$state" > "$tmp"
-  mv "$tmp" "$state"
-  return 0
-}
+# REFACTOR-030: removed `_loop_self_heal_ci` and `_loop_clear_heal_state`.
+# REFACTOR-023 merged the CI self-heal counter into the main state.yaml flow,
+# but the two helpers themselves were left behind as dead code. Their job
+# now lives in the state.yaml read/write paths called from the loop runner.
 
 # Verify TCR rhythm after a story completes. Returns 0 if ok, 1 if no TCR commits.
 # On failure: reverts story in .roll/backlog.md to 📋 Todo and writes ALERT.
@@ -4527,6 +4931,50 @@ _loop_pr_inbox() {
   return 0
 }
 
+# FIX-070: flip a story row in the main repo's .roll/backlog.md between
+# 📋 Todo and 🔨 In Progress. The cycle worktree is gitignored at .roll/,
+# so editing the worktree copy + committing leaves no trace in git — and
+# main's backlog (which roll-brief reads) stays stale. These helpers write
+# directly to ${ROLL_MAIN_PROJECT}/.roll/backlog.md instead.
+#
+# _loop_mark_in_progress <story-id> [backlog-path]
+#   Replace "📋 Todo" with "🔨 In Progress" on the row containing <story-id>.
+#   No-op when backlog or row is missing (idempotent retries don't error).
+_loop_mark_in_progress() {
+  local story_id="$1"
+  local backlog="${2:-${ROLL_MAIN_PROJECT:-$PWD}/.roll/backlog.md}"
+  [ -n "$story_id" ] || return 1
+  [ -f "$backlog" ] || return 0
+  local tmp; tmp=$(mktemp "${backlog}.XXXXXX") || return 1
+  awk -v sid="$story_id" '
+    {
+      if (index($0, sid) > 0 && index($0, "📋 Todo") > 0) {
+        sub(/📋 Todo/, "🔨 In Progress")
+      }
+      print
+    }
+  ' "$backlog" > "$tmp" && mv "$tmp" "$backlog"
+}
+
+# _loop_mark_todo <story-id> [backlog-path]
+#   Revert a row from "🔨 In Progress" back to "📋 Todo". Called when a
+#   cycle's executor fails so the next cycle can pick the story up again.
+_loop_mark_todo() {
+  local story_id="$1"
+  local backlog="${2:-${ROLL_MAIN_PROJECT:-$PWD}/.roll/backlog.md}"
+  [ -n "$story_id" ] || return 1
+  [ -f "$backlog" ] || return 0
+  local tmp; tmp=$(mktemp "${backlog}.XXXXXX") || return 1
+  awk -v sid="$story_id" '
+    {
+      if (index($0, sid) > 0 && index($0, "🔨 In Progress") > 0) {
+        sub(/🔨 In Progress/, "📋 Todo")
+      }
+      print
+    }
+  ' "$backlog" > "$tmp" && mv "$tmp" "$backlog"
+}
+
 # FIX-048: report story IDs already claimed by open loop/* PRs so a new cycle
 # can skip them before scanning BACKLOG. Without this gate, a cycle launched
 # before the previous cycle's PR merges would re-pick the same Todo story
@@ -4803,6 +5251,30 @@ _worktree_submodule_init() {
   ( cd "$path" && git submodule update --init --recursive --quiet )
 }
 
+# _worktree_sync_meta <path>
+#   FIX-069: Copy main repo's .roll/ meta (backlog, skills, conventions,
+#   features, decisions) into the cycle worktree as a read-only reference.
+#   Without this, the loop runs in a clean git clone with no .roll/ (it's
+#   gitignored), so Claude finds no backlog and no skill entry points —
+#   the whole cycle no-ops.
+#
+#   Excludes runtime state listed in .roll/.gitignore plus loop event/run
+#   logs, so the worktree never inherits main's live cycle state.
+#   Single-shot: never written back; the worktree copy is thrown away with
+#   the worktree itself.
+_worktree_sync_meta() {
+  local path="$1"
+  [ -d ".roll" ] || return 0
+  rsync -a \
+    --exclude='state/' \
+    --exclude='scratch/' \
+    --exclude='*.lock' \
+    --exclude='last-test-pass' \
+    --exclude='events.ndjson*' \
+    --exclude='runs.jsonl*' \
+    .roll/ "$path/.roll/" 2>/dev/null || true
+}
+
 # _worktree_merge_back <branch>
 #   Caller must be in the main worktree (cwd = main). Steps:
 #     1. git pull --ff-only origin main   (sync local main with remote)
@@ -5289,7 +5761,7 @@ cmd_brief() {
     latest=$(ls "${briefs_dir}"/*.md 2>/dev/null | sort | tail -1 || true)
   else
     local mod_time now age
-    mod_time=$(stat -c %Y "$latest" 2>/dev/null || stat -f %m "$latest" 2>/dev/null || echo 0)
+    mod_time=$(_file_mtime "$latest")
     now=$(date +%s); age=$(( now - mod_time ))
     if (( age > 86400 )); then
       info "Brief is $(( age / 3600 ))h old — regenerating...  简报已 $(( age / 3600 )) 小时未更新，重新生成..."
@@ -5311,34 +5783,11 @@ cmd_brief() {
   cat "$latest"
 }
 
-_promote_unreleased() {
-  local version="$1"
-  local changelog="$2"
-  [[ -f "$changelog" ]] || return 0
-  grep -q "^## Unreleased" "$changelog" || return 0
-  sed -i.bak "s/^## Unreleased$/## v${version}/" "$changelog" && rm "${changelog}.bak"
-}
-
-_ensure_unreleased() {
-  local changelog="$1"
-  [[ -f "$changelog" ]] || return 0
-  grep -q "^## Unreleased$" "$changelog" && return 0
-  python3 - "$changelog" <<'PYEOF'
-import sys, pathlib
-p = pathlib.Path(sys.argv[1])
-lines = p.read_text().splitlines(keepends=True)
-out = []
-inserted = False
-for line in lines:
-    out.append(line)
-    if not inserted and line.rstrip() == "# Changelog":
-        out.append("\n## Unreleased\n")
-        inserted = True
-if not inserted:
-    out.insert(0, "## Unreleased\n\n")
-p.write_text("".join(out))
-PYEOF
-}
+# REFACTOR-030: removed `_promote_unreleased` and `_ensure_unreleased`.
+# 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.
 
 # ═══════════════════════════════════════════════════════════════════════════════
 # BACKLOG — show pending tasks / manage status
@@ -5479,6 +5928,73 @@ cmd_ci() {
   echo "$runs" | jq -r '.[] | "\(.name): \(.status)/\(.conclusion)"'
 }
 
+# REFACTOR-041: backlog description linter. The global convention bans file
+# paths, function names, filenames, and "architecture jargon" in description
+# columns — see conventions/global/AGENTS.md §4. This helper scans each row's
+# description column for those patterns and prints any findings. Phase 1 is
+# warn-only (always exit 0) so a noisy ramp-up doesn't block work; Phase 2
+# will switch to hard-fail. Output format mirrors a linter ("file:line:
+# message") so editors can navigate from it.
+_backlog_lint() {
+  local backlog="${1:-.roll/backlog.md}"
+  [ -f "$backlog" ] || { err "backlog not found: $backlog"; return 1; }
+
+  local violations=0
+  local lineno=0
+  while IFS= read -r line; do
+    lineno=$((lineno+1))
+    # Only data rows (start with "|"), skip header/separator/non-table
+    case "$line" in
+      \|*) ;;
+      *) continue ;;
+    esac
+    case "$line" in
+      *Story*Description*Status*|*'---'*) continue ;;
+    esac
+    local desc
+    desc=$(echo "$line" | awk -F'|' '{print $3}' | sed 's/^ *//;s/ *$//')
+    [ -n "$desc" ] || continue
+    # Strip the leading `[US-XXX](path)` link / bare `US-XXX` id — those are
+    # structural, not description prose.
+    local body
+    body=$(echo "$desc" \
+      | sed -E 's|^\[[A-Z]+-[0-9]+\]\([^)]*\)[[:space:]]*||' \
+      | sed -E 's|^[A-Z]+-[0-9]+[[:space:]]*||')
+    local issues=""
+    # Filenames: bare `something.ext` for common code/config extensions
+    if echo "$body" | grep -qE '\b[A-Za-z_][A-Za-z0-9_.-]*\.(sh|bash|yaml|yml|json|js|ts|tsx|py|rb|go|rs|c|cpp|h)\b'; then
+      issues="${issues:+${issues}, }filename"
+    fi
+    # Paths: directory/anything pattern not preceded by `(` (links already
+    # stripped above). Hyphens / dots / underscores allowed in path segments.
+    if echo "$body" | grep -qE '[A-Za-z_][A-Za-z0-9_.-]*/[A-Za-z0-9_./-]+'; then
+      issues="${issues:+${issues}, }path"
+    fi
+    # Function names: underscore-prefixed identifier or trailing parens
+    if echo "$body" | grep -qE '\b_[a-zA-Z][a-zA-Z0-9_]+\b|\b[A-Za-z_][A-Za-z0-9_]+\(\)'; then
+      issues="${issues:+${issues}, }function"
+    fi
+    if [ -n "$issues" ]; then
+      violations=$((violations+1))
+      # Extract the story id from column 2 so reports name the offending row.
+      local sid; sid=$(echo "$line" | awk -F'|' '{print $2}' \
+        | sed -E 's/^[[:space:]]*\[?([A-Z]+-[0-9]+).*/\1/' \
+        | tr -d '[:space:]')
+      printf '%s:%d: %s — %s\n  %s\n' "$backlog" "$lineno" "$sid" "$issues" "$desc"
+    fi
+  done < "$backlog"
+
+  echo ""
+  if [ "$violations" -gt 0 ]; then
+    echo "  ${violations} violation(s) — see conventions/global/AGENTS.md §4"
+    echo "  ${violations} 条违规 — Phase 1: warn-only, not blocking"
+  else
+    echo "  No violations  无违规"
+  fi
+  # Phase 1: warn-only. Exit 0 regardless.
+  return 0
+}
+
 cmd_backlog() {
   local backlog=".roll/backlog.md"
   if [[ ! -f "$backlog" ]]; then
@@ -5490,6 +6006,10 @@ cmd_backlog() {
 
   # ── Status management subcommands ─────────────────────────────────────────
   case "$subcmd" in
+    lint)
+      _backlog_lint "$backlog"
+      return
+      ;;
     block|defer|unblock|promote)
       local pattern="${2:-}"
       local reason="${3:-}"
@@ -5666,7 +6186,7 @@ _dash_last_dream_hours() {
   local dream_log="${HOME}/.shared/roll/dream/log.md"
   [[ -f "$dream_log" ]] || return 0
   local mod_time now
-  mod_time=$(stat -c %Y "$dream_log" 2>/dev/null || stat -f %m "$dream_log" 2>/dev/null || echo 0)
+  mod_time=$(_file_mtime "$dream_log")
   now=$(date +%s)
   echo $(( (now - mod_time) / 3600 ))
 }
@@ -5686,7 +6206,7 @@ _dash_last_peer() {
   local result
   result=$(grep -oE '(AGREE|REFINE|OBJECT|ESCALATE)' "$latest" 2>/dev/null | tail -1 || true)
   local mod_time now days
-  mod_time=$(stat -c %Y "$latest" 2>/dev/null || stat -f %m "$latest" 2>/dev/null || echo 0)
+  mod_time=$(_file_mtime "$latest")
   now=$(date +%s)
   days=$(( (now - mod_time) / 86400 ))
   printf '%s|%s' "${result:-—}" "${days}"
@@ -5979,7 +6499,7 @@ _legacy_home() {
   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)
+    mod_time=$(_file_mtime "$latest_brief")
     now=$(date +%s); age=$(( (now - mod_time) / 3600 ))
     summary=$(_dash_brief_summary "$latest_brief")
     printf "    Brief ${CYAN}%sh${NC} ago — %s\n" "$age" "${summary:-—}"
@@ -6016,7 +6536,8 @@ _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 + .roll/backlog.md + docs/     初始化项目工作流文件"
+  echo "  init                   [Project] Create AGENTS.md + .roll/backlog.md + .roll/features/  初始化项目工作流文件"
+  echo "  offboard [--confirm]   [Project] Reverse a previous \`roll init --apply\` (dry-run by default)  卸载本项目的 Roll 痕迹"
   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  管理自主执行循环"
@@ -6025,6 +6546,7 @@ _legacy_help() {
   echo "  backlog block <pat> [reason]  Mark matching items as 🔒 Blocked  标记为已阻塞"
   echo "  backlog defer <pat> [reason]  Mark matching items as ⏸ Deferred  标记为已推迟"
   echo "  backlog unblock <pat>         Restore matching items to 📋 Todo   恢复为待处理"
+  echo "  backlog lint                  Check descriptions for path/function/filename violations  检查描述合规"
   echo "  agent [use <name>|list]   [Config] Per-project agent selection            切换项目 agent"
   echo "  ci [--wait]            [CI] Show or wait for current commit's CI status       查看/等待 CI 状态"
   echo "  review-pr <number>     [PR Review] AI-powered code review for a PR           AI 代码评审"
@@ -6075,6 +6597,7 @@ _check_structure() {
   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
+    offboard) return 0 ;;  # cmd_offboard does its own changeset check
   esac
 
   # Determine project root: git root if available, else pwd
@@ -6126,6 +6649,7 @@ main() {
     setup)         cmd_setup "$@" ;;
     update)        cmd_update "$@" ;;
     init)          cmd_init "$@" ;;
+    offboard)      cmd_offboard "$@" ;;
     migrate)       cmd_migrate "$@" ;;
     status)        cmd_status "$@" ;;
     peer)          cmd_peer "$@" ;;