@seanyao/roll 2026.519.3 → 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.3"
+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
@@ -2388,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)
@@ -2416,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 ""
@@ -2656,20 +3005,16 @@ _loop_event() {
   # 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"
@@ -2940,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
@@ -2991,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
@@ -3015,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"
@@ -4178,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.
@@ -4603,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
@@ -4879,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)
@@ -5387,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
@@ -5555,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
@@ -5566,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:-}"
@@ -6093,6 +6537,7 @@ _legacy_help() {
   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 + .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  管理自主执行循环"
@@ -6101,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 代码评审"
@@ -6151,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
@@ -6202,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 "$@" ;;