@seanyao/roll 2026.510.9 → 2026.511.1

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## v2026.511.1
+- **Changed**: roll loop 调度器切换到 launchd（macOS）— `roll setup` 自动安装 loop/dream/brief 三个 launchd 服务（默认关闭），`roll loop on/off/status` 统一走 launchctl 管理，幂等安装，Linux 保留 crontab 回退路径
+- **Added**: roll-loop TCR 硬校验 — 故事完成后自动统计 `tcr:` 微提交数量，为 0 时将故事状态回退为 📋 Todo 并写 ALERT，防止 agent 跳过 TCR 节奏
+- **Fixed**: CI 测试环境兼容 — 移除依赖本地 state.yaml 的 hello_world.bats，修复 GitHub Actions 持续失败
+
+## v2026.510.10
+- **Fixed**: release.sh changelog 同步时序修复 — 修正条件逻辑和执行顺序，确保每次发版时 changelog 正确更新
+- **Added**: roll-loop 22:00 自动执行验证 — 新增 hello_world.bats 作为 loop 定时执行的端到端存档，可回放确认调度器正常工作
+
+## v2026.510.9
+- **Fixed**: CHANGELOG 改版本号分组 — 每个 release 独立 section，GitHub Release 增量内容提取正确
+- **Fixed**: release.yml 加 fetch-depth: 0，确保历史 tag 在 workflow 中可见
+
 ## v2026.510.8
 - **Fixed**: release.sh 自洽 — 内联 agent 检测和 changelog 同步，发版流程不依赖外部调用
 - **Fixed**: roll release 命令重构 — 改为独立调用 roll-release skill，与 scripts/release.sh 解耦

package/README.md

@@ -134,7 +134,7 @@ Research → Design → Build → Check → Fix → (loop)
 | Execute a planned Story | `$roll-build US-001` |
 | Free-form feature request | `$roll-build "add search to admin"` |
 | Bug fix | `$roll-fix FIX-001` |
-| Fast backlog capture (bug / idea) | `$roll-jot "description"` |
+| Fast backlog capture (bug / idea) | `$roll-idea "description"` |
 | High-risk logic (payments, auth, state machines) | `$roll-spar "feature"` |
 | Deep research (product / company / tech) | `$roll-research "subject"` |
 | Patrol production for regressions | `$roll-sentinel patrol` |
@@ -148,7 +148,7 @@ Research → Design → Build → Check → Fix → (loop)
 | `$roll-build` | DESIGN+BUILD | Universal entry: Story ID, fix ID, or free-text fly mode |
 | `$roll-design` | DESIGN | Multi-turn discuss → [peer review] → DDD model → solution design → [peer review] → write Stories to BACKLOG |
 | `$roll-fix` | FIX | Bug fix / hotfix from BACKLOG |
-| `$roll-jot` | Support | Fast capture a bug or idea into BACKLOG.md |
+| `$roll-idea` | Support | Fast capture a bug or idea into BACKLOG.md |
 | `$roll-spar` | BUILD | Adversarial TDD — Attacker writes tests, Defender writes code |
 | `$roll-sentinel` | CHECK | Scheduled production patrol |
 | `$roll-debug` | CHECK | Deep page diagnostics + root cause analysis |

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.510.9"
+VERSION="2026.511.1"
 ROLL_HOME="${ROLL_HOME:-${HOME}/.roll}"
 ROLL_CONFIG="${ROLL_HOME}/config.yaml"
 ROLL_GLOBAL="${ROLL_HOME}/conventions/global"
@@ -544,6 +544,12 @@ cmd_setup() {
   _peer_ensure_state_dir
   ok "Peer state directory ready.  Peer 状态目录已就绪。"
 
+  if [[ "$(uname)" == "Darwin" ]]; then
+    echo ""
+    info "Installing launchd plists...  正在安装 LaunchAgents..."
+    _install_launchd_plists "$(pwd -P)"
+  fi
+
   echo ""
   ok "Setup complete.  初始化完成。"
 
@@ -1729,8 +1735,128 @@ cmd_agent() {
 # ═══════════════════════════════════════════════════════════════════════════════
 
 _LOOP_TAG="# roll-loop"
+_SHARED_ROOT="${HOME}/.shared/roll"
 _LOOP_STATE="${HOME}/.shared/roll/loop/state.yaml"
 _LOOP_ALERT="${HOME}/.shared/roll/loop/ALERT.md"
+_LAUNCHD_DIR="${HOME}/Library/LaunchAgents"
+
+# Returns a filesystem-safe slug combining the project basename and a 6-char
+# hash of the full path, ensuring uniqueness across sibling dirs with same name.
+_project_slug() {
+  local path="$1"
+  local base; base=$(basename "$path")
+  local hash
+  if command -v md5 &>/dev/null; then
+    hash=$(printf '%s' "$path" | md5 | cut -c1-6)
+  else
+    hash=$(printf '%s' "$path" | md5sum | cut -c1-6)
+  fi
+  base=$(printf '%s' "$base" | tr -cs '[:alnum:]' '-' | sed 's/-*$//')
+  printf '%s' "${base}-${hash}"
+}
+
+_launchd_label() {
+  local service="$1" project_path="$2"
+  printf 'com.roll.%s.%s' "$service" "$(_project_slug "$project_path")"
+}
+
+_launchd_plist_path() {
+  local service="$1" project_path="$2"
+  printf '%s/%s.plist' "$_LAUNCHD_DIR" "$(_launchd_label "$service" "$project_path")"
+}
+
+_write_launchd_plist() {
+  local plist_path="$1" label="$2" project_path="$3"
+  local minute="$4" hour="$5" runner_script="$6"
+
+  local hour_xml=""
+  [[ -n "$hour" ]] && hour_xml="    <key>Hour</key>
+    <integer>${hour}</integer>
+"
+
+  local content
+  content="<?xml version=\"1.0\" encoding=\"UTF-8\"?>
+<!DOCTYPE plist PUBLIC \"-//Apple//DTD PLIST 1.0//EN\" \"http://www.apple.com/DTDs/PropertyList-1.0.dtd\">
+<plist version=\"1.0\">
+<dict>
+  <key>Label</key>
+  <string>${label}</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>/bin/bash</string>
+    <string>-l</string>
+    <string>${runner_script}</string>
+  </array>
+  <key>StartCalendarInterval</key>
+  <dict>
+    <key>Minute</key>
+    <integer>${minute}</integer>
+${hour_xml}  </dict>
+  <key>WorkingDirectory</key>
+  <string>${project_path}</string>
+</dict>
+</plist>"
+
+  if [[ -f "$plist_path" ]] && [[ "$(cat "$plist_path")" == "$content" ]]; then
+    return 0
+  fi
+  printf '%s\n' "$content" > "$plist_path"
+}
+
+_write_runner_script() {
+  local script_path="$1" project_path="$2" cmd="$3" log_path="$4"
+  mkdir -p "$(dirname "$script_path")"
+  printf '#!/bin/bash -l\ncd "%s" && %s >> "%s" 2>&1\n' "$project_path" "$cmd" "$log_path" > "$script_path"
+  chmod +x "$script_path"
+}
+
+_launchd_is_loaded() {
+  launchctl list "$1" &>/dev/null 2>&1
+}
+
+# Install launchd plist files (disabled by default) and runner scripts for
+# a given project path. Idempotent — skips unchanged files. Does NOT load.
+_install_launchd_plists() {
+  local project_path="$1"
+  local sd="${ROLL_HOME}/skills"
+  local shared="${_SHARED_ROOT}"
+
+  mkdir -p "$_LAUNCHD_DIR"
+  mkdir -p "${shared}/loop" "${shared}/dream" "${shared}/brief"
+
+  local services=("loop" "dream" "brief")
+  local skill_names=("roll-loop" "roll-.dream" "roll-brief")
+  local minutes=("0" "0" "0")
+  local hours=("" "1" "8")
+
+  local updated=0
+  for i in "${!services[@]}"; do
+    local svc="${services[$i]}"
+    local skill="${skill_names[$i]}"
+    local minute="${minutes[$i]}"
+    local hour="${hours[$i]}"
+    local label; label=$(_launchd_label "$svc" "$project_path")
+    local plist; plist=$(_launchd_plist_path "$svc" "$project_path")
+    local runner="${shared}/${svc}/run.sh"
+    local log="${shared}/${svc}/cron.log"
+    local cmd; cmd=$(_agent_skill_cmd "${sd}/${skill}/SKILL.md" 2>/dev/null || echo "roll loop now")
+
+    _write_runner_script "$runner" "$project_path" "cd \"${project_path}\" && ${cmd}" "$log"
+
+    local before=""
+    [[ -f "$plist" ]] && before=$(cat "$plist")
+    _write_launchd_plist "$plist" "$label" "$project_path" "$minute" "$hour" "$runner"
+    local after; after=$(cat "$plist")
+    [[ "$before" != "$after" ]] && updated=$((updated + 1))
+  done
+
+  if [[ $updated -gt 0 ]]; then
+    ok "Launchd plists installed (${updated} updated)  LaunchAgents 已安装"
+    echo "  Run: roll loop on  to activate  运行 roll loop on 激活"
+  else
+    ok "Launchd plists up to date  LaunchAgents 无需更新"
+  fi
+}
 
 _agent_skill_cmd() {
   local skill_path="$1"
@@ -1738,7 +1864,7 @@ _agent_skill_cmd() {
   # Strip YAML frontmatter inline for cron commands
   local strip="awk 'NR==1 && /^---$/{skip=1;next} skip && /^---$/{skip=0;next} !skip{print}' '${skill_path}'"
   case "$agent" in
-    claude)   echo "claude -p \"\$(${strip})\"" ;;
+    claude)   local _bin; _bin=$(command -v claude 2>/dev/null || echo "claude"); echo "${_bin} -p \"\$(${strip})\"" ;;
     kimi)     echo "kimi --quiet -p \"\$(${strip})\"" ;;
     deepseek) echo "deepseek \"\$(${strip})\"" ;;
     pi)       echo "pi -p \"\$(${strip})\"" ;;
@@ -1751,31 +1877,57 @@ _agent_skill_cmd() {
 cmd_loop() {
   local subcmd="${1:-status}"; shift || true
   case "$subcmd" in
-    on)     _loop_on ;;
-    off)    _loop_off ;;
-    now)    _loop_now ;;
-    status) _loop_status ;;
-    resume) _loop_resume ;;
-    reset)  _loop_reset ;;
-    *) err "Usage: roll loop <on|off|now|status|resume|reset>"; exit 1 ;;
+    on)      _loop_on ;;
+    off)     _loop_off ;;
+    now)     _loop_now ;;
+    status)  _loop_status ;;
+    monitor) _loop_monitor "${1:-3}" ;;
+    resume)  _loop_resume ;;
+    reset)   _loop_reset ;;
+    *) err "Usage: roll loop <on|off|now|status|monitor|resume|reset>"; exit 1 ;;
   esac
 }
 
 _loop_on() {
   local project_path; project_path=$(pwd -P)
   local agent; agent=$(_project_agent)
-  local sd="${ROLL_HOME}/skills"
 
+  if [[ "$(uname)" == "Darwin" ]]; then
+    _install_launchd_plists "$project_path" >/dev/null
+
+    local all_loaded=true
+    for svc in loop dream brief; do
+      local label; label=$(_launchd_label "$svc" "$project_path")
+      if ! _launchd_is_loaded "$label"; then
+        all_loaded=false
+        launchctl load "$(_launchd_plist_path "$svc" "$project_path")" 2>/dev/null || true
+      fi
+    done
+
+    if $all_loaded; then
+      warn "Loop already enabled for this project  当前项目 loop 已启用"; return 0
+    fi
+
+    ok "Loop enabled  已启用"
+    echo "  • roll-loop   every hour :00    每小时整点"
+    echo "  • roll-.dream nightly at 01:00  每晚 01:00"
+    echo "  • roll-brief  daily at 08:00    每天 08:00"
+    echo "  • Agent: ${agent}  (change: roll agent use <name>)"
+    return 0
+  fi
+
+  # Linux: crontab
+  local sd="${ROLL_HOME}/skills"
   if crontab -l 2>/dev/null | grep -q "${_LOOP_TAG}:${project_path}"; then
     warn "Loop already enabled for this project  当前项目 loop 已启用"; return 0
   fi
 
-  mkdir -p ~/.shared/roll/{loop,dream,brief}
+  mkdir -p "${_SHARED_ROOT}/loop" "${_SHARED_ROOT}/dream" "${_SHARED_ROOT}/brief"
 
   local loop_cmd dream_cmd brief_cmd
-  loop_cmd="cd \"${project_path}\" && $(_agent_skill_cmd "${sd}/roll-loop/SKILL.md") >> ~/.shared/roll/loop/cron.log 2>&1"
-  dream_cmd="cd \"${project_path}\" && $(_agent_skill_cmd "${sd}/roll-.dream/SKILL.md") >> ~/.shared/roll/dream/cron.log 2>&1"
-  brief_cmd="cd \"${project_path}\" && $(_agent_skill_cmd "${sd}/roll-brief/SKILL.md") >> ~/.shared/roll/brief/cron.log 2>&1"
+  loop_cmd="cd \"${project_path}\" && $(_agent_skill_cmd "${sd}/roll-loop/SKILL.md") >> ${_SHARED_ROOT}/loop/cron.log 2>&1"
+  dream_cmd="cd \"${project_path}\" && $(_agent_skill_cmd "${sd}/roll-.dream/SKILL.md") >> ${_SHARED_ROOT}/dream/cron.log 2>&1"
+  brief_cmd="cd \"${project_path}\" && $(_agent_skill_cmd "${sd}/roll-brief/SKILL.md") >> ${_SHARED_ROOT}/brief/cron.log 2>&1"
 
   (
     crontab -l 2>/dev/null
@@ -1793,6 +1945,24 @@ _loop_on() {
 
 _loop_off() {
   local project_path; project_path=$(pwd -P)
+
+  if [[ "$(uname)" == "Darwin" ]]; then
+    local any_loaded=false
+    for svc in loop dream brief; do
+      local label; label=$(_launchd_label "$svc" "$project_path")
+      if _launchd_is_loaded "$label"; then
+        any_loaded=true
+        launchctl unload "$(_launchd_plist_path "$svc" "$project_path")" 2>/dev/null || true
+      fi
+    done
+    if ! $any_loaded; then
+      warn "Loop not enabled for this project  当前项目 loop 未启用"; return 0
+    fi
+    ok "Loop disabled  已停用"
+    return 0
+  fi
+
+  # Linux: crontab
   if ! crontab -l 2>/dev/null | grep -q "${_LOOP_TAG}:${project_path}"; then
     warn "Loop not enabled for this project  当前项目 loop 未启用"; return 0
   fi
@@ -1805,14 +1975,22 @@ _loop_now() {
     warn "Loop already running  loop 正在运行中"; return 0
   fi
   info "Triggering loop cycle...  正在触发一个周期..."
-  _agent_run_skill "roll-loop"
+  local log_file="${_SHARED_ROOT}/loop/launchd.log"
+  mkdir -p "$(dirname "$log_file")"
+  _agent_run_skill "roll-loop" | tee -a "$log_file"
 }
 
 _loop_status() {
   local project_path; project_path=$(pwd -P)
   local agent; agent=$(_project_agent)
   echo ""
-  if crontab -l 2>/dev/null | grep -q "${_LOOP_TAG}:${project_path}"; then
+  local loop_enabled=false
+  if [[ "$(uname)" == "Darwin" ]]; then
+    _launchd_is_loaded "$(_launchd_label "loop" "$project_path")" && loop_enabled=true
+  else
+    crontab -l 2>/dev/null | grep -q "${_LOOP_TAG}:${project_path}" && loop_enabled=true
+  fi
+  if $loop_enabled; then
     echo -e "  Scheduler  ${GREEN}● enabled${NC}   Agent: ${CYAN}${agent}${NC}"
   else
     echo -e "  Scheduler  ${YELLOW}○ disabled${NC}   run: roll loop on"
@@ -1842,6 +2020,176 @@ _loop_reset() {
   fi
 }
 
+# Count `tcr:` prefixed commits in the current git repo since started_at timestamp.
+_loop_tcr_count() {
+  local started_at="$1"
+  git log --oneline --since="${started_at}" 2>/dev/null \
+    | awk '/^[a-f0-9]+ tcr:/{n++} END{print n+0}'
+}
+
+# Verify TCR rhythm after a story completes. Returns 0 if ok, 1 if no TCR commits.
+# On failure: reverts story in BACKLOG.md to 📋 Todo and writes ALERT.
+_loop_enforce_tcr() {
+  local story_id="$1"
+  local started_at="${2:-}"
+
+  [[ -z "$started_at" ]] && return 0
+
+  local count; count=$(_loop_tcr_count "$started_at")
+
+  if [[ "$count" -eq 0 ]]; then
+    # Revert story status
+    if [[ -f "BACKLOG.md" ]]; then
+      local tmp; tmp=$(mktemp)
+      sed "/\[${story_id}\]/s/ | ✅ Done |/ | 📋 Todo |/" BACKLOG.md > "$tmp" \
+        && mv "$tmp" BACKLOG.md
+    fi
+
+    # Write ALERT
+    mkdir -p "$(dirname "$_LOOP_ALERT")"
+    cat > "$_LOOP_ALERT" << EOF
+# ALERT — TCR check failed
+
+**Time**: $(date '+%Y-%m-%d %H:%M')
+**Story**: ${story_id}
+**Reason**: zero tcr: commits since story start (${started_at})
+
+**Action required** (choose one):
+- Add TCR commits and re-run: \`roll loop now\`
+- Take over manually: \`\$roll-build ${story_id}\`
+- Reset and retry: \`roll loop reset\` then \`roll loop now\`
+EOF
+    return 1
+  fi
+
+  return 0
+}
+
+_loop_monitor() {
+  local interval="${1:-3}"
+  local project_path; project_path=$(pwd -P)
+  local project_name; project_name=$(basename "$project_path")
+
+  # Determine terminal clear capability
+  local clear_cmd="clear"
+  command -v clear &>/dev/null || clear_cmd="echo ''"
+
+  while true; do
+    $clear_cmd
+    local agent; agent=$(_project_agent)
+    local now; now=$(date '+%Y-%m-%d %H:%M:%S')
+
+    echo -e "\n  ${BOLD}${CYAN}roll loop monitor${NC}  ${YELLOW}${project_name}${NC}  ${now}  (Ctrl-C to exit)\n"
+
+    # Services status (three services on macOS, single on Linux)
+    echo -e "  ${BOLD}Services  服务状态${NC}   Agent: ${CYAN}${agent}${NC}"
+    if [[ "$(uname)" == "Darwin" ]]; then
+      local svc_info svc schedule
+      for svc_info in "loop:hourly" "dream:01:00" "brief:08:00"; do
+        svc="${svc_info%%:*}"
+        schedule="${svc_info#*:}"
+        if _launchd_is_loaded "$(_launchd_label "$svc" "$project_path")"; then
+          printf "    ${GREEN}%-8s ● enabled${NC}   (%s)\n" "$svc" "$schedule"
+        else
+          printf "    ${YELLOW}%-8s ○ disabled${NC}  (%s)\n" "$svc" "$schedule"
+        fi
+      done
+    else
+      if crontab -l 2>/dev/null | grep -q "${_LOOP_TAG}:${project_path}"; then
+        echo -e "    ${GREEN}loop     ● enabled${NC}"
+      else
+        echo -e "    ${YELLOW}loop     ○ disabled${NC}   run: roll loop on"
+      fi
+    fi
+
+    # Current state
+    if [[ -f "$_LOOP_STATE" ]]; then
+      local status current_item started_at run_id
+      status=$(grep '^status:' "$_LOOP_STATE" | awk '{print $2}')
+      current_item=$(grep '^current_item:' "$_LOOP_STATE" | awk '{print $2}')
+      started_at=$(grep '^started_at:' "$_LOOP_STATE" | cut -d' ' -f2- | tr -d '"')
+      run_id=$(grep '^run_id:' "$_LOOP_STATE" | awk '{print $2}')
+      echo ""
+      case "$status" in
+        running) echo -e "  State      ${GREEN}▶ running${NC}   ${CYAN}${current_item}${NC}   started: ${started_at}   run: ${run_id}" ;;
+        paused)  echo -e "  State      ${RED}‖ paused${NC}    on: ${current_item}" ;;
+        idle)    echo -e "  State      ${YELLOW}○ idle${NC}" ;;
+        *)       echo -e "  State      ${status}" ;;
+      esac
+    else
+      echo ""
+      echo -e "  State      ${YELLOW}○ no state file${NC}"
+    fi
+
+    # Alert
+    if [[ -f "$_LOOP_ALERT" ]]; then
+      echo ""
+      echo -e "  ${RED}⚠ ALERT:${NC}"
+      sed 's/^/    /' "$_LOOP_ALERT"
+    fi
+
+    # Queue: pending items
+    echo ""
+    echo -e "  ${BOLD}Queue  待处理队列${NC}"
+    local backlog="BACKLOG.md"
+    if [[ -f "$backlog" ]]; then
+      local queue_count=0
+      local fix_pending us_pending refactor_pending
+      fix_pending=$(grep -E '^\| FIX-' "$backlog" | grep '📋 Todo' || true)
+      us_pending=$(grep -E '^\| \[US-' "$backlog" | grep '📋 Todo' || true)
+      refactor_pending=$(grep -E '^\| REFACTOR-' "$backlog" | grep '📋 Todo' || true)
+
+      # FIX first (priority)
+      while IFS= read -r line; do
+        [[ -z "$line" ]] && continue
+        local id desc
+        id=$(echo "$line" | awk -F'|' '{print $2}' | tr -d ' ')
+        desc=$(echo "$line" | awk -F'|' '{print $3}' | sed 's/^ *//;s/ *$//' | cut -c1-60)
+        printf "    ${RED}%-14s${NC}  %s\n" "$id" "$desc"
+        (( queue_count++ )) || true
+      done <<< "$fix_pending"
+
+      # US stories
+      while IFS= read -r line; do
+        [[ -z "$line" ]] && continue
+        local id desc
+        id=$(echo "$line" | sed 's/.*\[\(US-[^]]*\)\].*/\1/')
+        desc=$(echo "$line" | awk -F'|' '{print $3}' | sed 's/^ *//;s/ *$//' | cut -c1-60)
+        printf "    ${CYAN}%-14s${NC}  %s\n" "$id" "$desc"
+        (( queue_count++ )) || true
+      done <<< "$us_pending"
+
+      # Refactors
+      while IFS= read -r line; do
+        [[ -z "$line" ]] && continue
+        local id desc
+        id=$(echo "$line" | awk -F'|' '{print $2}' | tr -d ' ')
+        desc=$(echo "$line" | awk -F'|' '{print $3}' | sed 's/^ *//;s/ *$//' | cut -c1-60)
+        printf "    ${YELLOW}%-14s${NC}  %s\n" "$id" "$desc"
+        (( queue_count++ )) || true
+      done <<< "$refactor_pending"
+
+      [[ $queue_count -eq 0 ]] && echo -e "    ${GREEN}✓ empty${NC}"
+    else
+      echo "    BACKLOG.md not found"
+    fi
+
+    # Log tail (launchd.log)
+    local log_file="${_SHARED_ROOT}/loop/launchd.log"
+    echo ""
+    echo -e "  ─────────────────────────────────────────────────────"
+    echo -e "  ${BOLD}Log Tail  实时日志${NC}  (~/.shared/roll/loop/launchd.log, last 10 lines)"
+    if [[ -f "$log_file" && -s "$log_file" ]]; then
+      tail -10 "$log_file" | sed 's/^/    /'
+    else
+      echo -e "    ${YELLOW}(no log yet)${NC}"
+    fi
+
+    echo ""
+    sleep "$interval"
+  done
+}
+
 # ═══════════════════════════════════════════════════════════════════════════════
 # BRIEF — owner-facing project digest
 # ═══════════════════════════════════════════════════════════════════════════════
@@ -1872,6 +2220,75 @@ cmd_release() {
   _agent_run_skill "roll-release"
 }
 
+# ═══════════════════════════════════════════════════════════════════════════════
+# BACKLOG — show pending tasks
+# ═══════════════════════════════════════════════════════════════════════════════
+
+cmd_backlog() {
+  local backlog="BACKLOG.md"
+  if [[ ! -f "$backlog" ]]; then
+    err "BACKLOG.md not found — run 'roll init' first  未找到 BACKLOG.md，请先运行 roll init"
+    return 1
+  fi
+
+  local us_items fix_items refactor_items total=0
+
+  us_items=$(grep -E '^\| \[US-' "$backlog" | grep '📋 Todo' || true)
+  fix_items=$(grep -E '^\| FIX-' "$backlog" | grep '📋 Todo' || true)
+  refactor_items=$(grep -E '^\| REFACTOR-' "$backlog" | grep '📋 Todo' || true)
+
+  local us_count fix_count refactor_count
+  us_count=$(echo "$us_items" | grep -c . || true)
+  fix_count=$(echo "$fix_items" | grep -c . || true)
+  refactor_count=$(echo "$refactor_items" | grep -c . || true)
+  [[ -z "$us_items" ]] && us_count=0
+  [[ -z "$fix_items" ]] && fix_count=0
+  [[ -z "$refactor_items" ]] && refactor_count=0
+  total=$(( us_count + fix_count + refactor_count ))
+
+  echo ""
+  echo -e "  ${BOLD}Pending Backlog  待处理任务${NC}  (${total} items)"
+  echo ""
+
+  if [[ $fix_count -gt 0 ]]; then
+    echo -e "  ${RED}Bug Fixes  缺陷修复  (${fix_count})${NC}"
+    while IFS= read -r line; do
+      local id desc
+      id=$(echo "$line" | awk -F'|' '{print $2}' | tr -d ' ')
+      desc=$(echo "$line" | awk -F'|' '{print $3}' | sed 's/^ *//;s/ *$//')
+      printf "    %-12s  %s\n" "$id" "$desc"
+    done <<< "$fix_items"
+    echo ""
+  fi
+
+  if [[ $us_count -gt 0 ]]; then
+    echo -e "  ${CYAN}User Stories  用户故事  (${us_count})${NC}"
+    while IFS= read -r line; do
+      local id desc
+      id=$(echo "$line" | sed 's/.*\[\(US-[^]]*\)\].*/\1/')
+      desc=$(echo "$line" | awk -F'|' '{print $3}' | sed 's/^ *//;s/ *$//')
+      printf "    %-14s  %s\n" "$id" "$desc"
+    done <<< "$us_items"
+    echo ""
+  fi
+
+  if [[ $refactor_count -gt 0 ]]; then
+    echo -e "  ${YELLOW}Refactors  重构  (${refactor_count})${NC}"
+    while IFS= read -r line; do
+      local id desc
+      id=$(echo "$line" | awk -F'|' '{print $2}' | tr -d ' ')
+      desc=$(echo "$line" | awk -F'|' '{print $3}' | sed 's/^ *//;s/ *$//')
+      printf "    %-16s  %s\n" "$id" "$desc"
+    done <<< "$refactor_items"
+    echo ""
+  fi
+
+  if [[ $total -eq 0 ]]; then
+    echo -e "  ${GREEN}✓ Nothing pending — backlog is clear  暂无待处理任务${NC}"
+    echo ""
+  fi
+}
+
 # ─────────────────────────────────────────────────────────────────────────────
 
 _dashboard() {
@@ -1888,6 +2305,17 @@ _dashboard() {
   fi
   [[ -f "$_LOOP_ALERT" ]] && echo -e "  ${RED}⚠ ALERT — run: roll loop status${NC}"
 
+  # Backlog summary
+  if [[ -f "BACKLOG.md" ]]; then
+    local pending_count
+    pending_count=$(grep -c '📋 Todo' "BACKLOG.md" 2>/dev/null || echo 0)
+    if (( pending_count > 0 )); then
+      echo -e "  Backlog  ${YELLOW}${pending_count} pending${NC}   run: roll backlog"
+    else
+      echo -e "  Backlog  ${GREEN}✓ clear${NC}"
+    fi
+  fi
+
   local briefs_dir="docs/briefs"
   local latest; latest=$(ls "${briefs_dir}"/*.md 2>/dev/null | sort | tail -1 || true)
   if [[ -n "$latest" ]]; then
@@ -1903,7 +2331,7 @@ _dashboard() {
   fi
 
   echo ""
-  echo "  loop <on|off|now|status|resume|reset>  ·  brief  ·  agent use <name>  ·  release"
+  echo "  loop <on|off|now|status|monitor|resume|reset>  ·  brief  ·  backlog  ·  agent use <name>  ·  release"
   echo "  setup  ·  update  ·  init  ·  status  ·  peer  ·  help"
   echo ""
 }
@@ -1930,8 +2358,9 @@ usage() {
   echo "  init                   [Project] Create AGENTS.md + BACKLOG.md + docs/     初始化项目工作流文件"
   echo "  status                 [Diagnostic] Show current state                    显示当前状态"
   echo "  peer                   [Peer Review] Cross-agent negotiation               跨 Agent 协商对审"
-  echo "  loop <on|off|now|status|resume|reset>  [Autonomous] Manage scheduled BACKLOG executor  管理自主执行循环"
+  echo "  loop <on|off|now|status|monitor|resume|reset>  [Autonomous] Manage scheduled BACKLOG executor  管理自主执行循环"
   echo "  brief                  [Digest] Show latest owner brief (regenerate if stale)  展示最新简报"
+  echo "  backlog                [View] Show all pending tasks from BACKLOG.md           显示待处理任务清单"
   echo "  agent [use <name>|list]   [Config] Per-project agent selection            切换项目 agent"
   echo "  release                [Publish] Sync changelog + version bump + npm publish  同步日志并发版"
   echo ""
@@ -1941,6 +2370,7 @@ usage() {
   echo "  roll init                     # New or re-merge project (run in project)   新建或重新合并（项目目录）"
   echo "  roll loop on                  # Enable autonomous loop (cron)              启用自主执行循环"
   echo "  roll brief                    # Show latest brief                          查看最新简报"
+  echo "  roll backlog                  # Show pending BACKLOG items                 查看待处理任务"
   echo "  roll agent use kimi           # Switch this project to kimi               切换当前项目到 kimi"
 
 }
@@ -1957,6 +2387,7 @@ main() {
     peer)          cmd_peer "$@" ;;
     loop)          cmd_loop "$@" ;;
     brief)         cmd_brief "$@" ;;
+    backlog)       cmd_backlog "$@" ;;
     agent)         cmd_agent "$@" ;;
     release)       cmd_release "$@" ;;
     version|--version|-v) echo "roll v${VERSION}" ;;

package/conventions/global/AGENTS.md

@@ -31,7 +31,7 @@
 
 ## 4. Workflow
 - **Scope Gate**: Only implement what is explicitly listed in the AC. Nothing more.
-  - Requests made in conversation are NOT AC — capture with `roll-jot` first.
+  - Requests made in conversation are NOT AC — capture with `roll-idea` first.
   - Any new Story/Fix requires design doc + user confirmation before TCR starts.
   - Do not commit without user approval unless explicitly told to auto-commit.
 - **TCR**: Test -> Green = Commit / Red = Revert. No WIP commits.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seanyao/roll",
-  "version": "2026.510.9",
+  "version": "2026.511.1",
   "description": "Roll — Roll out features with AI agents",
   "scripts": {
     "test": "find tests/unit tests/integration -name '*.bats' | sort | xargs ./tests/helpers/bats-core/bin/bats"

package/skills/roll-.changelog/SKILL.md

@@ -76,12 +76,23 @@ Bad:
 
 ### 4. Version Number Format
 
+Determine the current version being released:
+
+```bash
+VERSION=$(node -e "process.stdout.write(require('./package.json').version)" 2>/dev/null \
+  || git describe --tags --abbrev=0 2>/dev/null | sed 's/^v//')
 ```
-YYYY.MM.DD
-YYYY.MM.DD-1  (multiple releases on the same day)
-YYYY.MM.DD-2
+
+`package.json` is the authoritative source — it is updated before this skill runs. Fall back to git tags only if `package.json` is unavailable.
+
+The CHANGELOG section header uses the full version string with a `v` prefix:
+
+```
+## v${VERSION}
 ```
 
+For the human-readable date display within entries, use `YYYY.MM.DD` format.
+
 ### 5. Generate CHANGELOG.md
 
 **Create mode** (first time):

package/skills/roll-.clarify/SKILL.md

@@ -22,7 +22,7 @@ Auto-invoked by `roll-build` (Fly mode) when the user input is:
 ## When Not to Use
 
 - Intent is already clear and actionable
-- User gives a specific command with a skill trigger (e.g. `$roll-jot ...`)
+- User gives a specific command with a skill trigger (e.g. `$roll-idea ...`)
 - User is answering a clarification question you just asked
 - The task is simple enough that misinterpretation risk is negligible
 - User messy thoughts need restatement rather than questioning (use `$roll-.echo`)

package/skills/roll-.qa/SKILL.md

@@ -233,10 +233,10 @@ CI failure
 
 ```bash
 # For fixable bugs — create FIX entry
-$roll-jot fix "CI: {step} fails — {root cause summary}"
+$roll-idea fix "CI: {step} fails — {root cause summary}"
 
 # For flaky/environmental issues — create IDEA entry
-$roll-jot idea "CI: investigate flaky {test name}"
+$roll-idea idea "CI: investigate flaky {test name}"
 ```
 
 ### Step 4: Execute Fix

package/skills/roll-brief/SKILL.md

@@ -95,52 +95,51 @@ A simple heuristic — not a gate, just a signal for the human:
 
 ### Step 4 — Write Brief
 
-Output to `docs/briefs/YYYY-MM-DD-HH.md`:
+Output to `docs/briefs/YYYY-MM-DD-HH.md`，全部用中文输出：
 
 ```markdown
-# Brief {YYYY-MM-DD HH:mm}
+# 简报 {YYYY-MM-DD HH:mm}
 
-## What's Done
-| ID | Description | Type |
+## 已完成
+| 编号 | 描述 | 类型 |
 |----|-------------|------|
-| US-XXX | {title} | Story |
-| FIX-XXX | {title} | Fix |
-| REFACTOR-XXX | {title} | Refactor |
+| US-XXX | {标题} | 用户故事 |
+| FIX-XXX | {标题} | 缺陷修复 |
+| REFACTOR-XXX | {标题} | 重构 |
 
-## In Progress
-| ID | Description |
+## 进行中
+| 编号 | 描述 |
 |----|-------------|
-| US-XXX | {title} — started {date} |
+| US-XXX | {标题} — 开始于 {date} |
 
-## Queue ({N} items)
-| ID | Description | Priority |
+## 待处理队列（{N} 项）
+| 编号 | 描述 | 优先级 |
 |----|-------------|----------|
-| US-XXX | {title} | high |
+| US-XXX | {标题} | 高 |
 
-## Overnight Dream Findings
-{summary from docs/dream/ since last brief, or "No new findings."}
+## 夜间巡检发现
+{来自 docs/dream/ 的摘要，无则写"暂无新发现。"}
 
-## Escalations Requiring Human Input
-{any alerts, or "None — agent operating normally."}
+## 需要人工介入的升级事项
+{任何告警，无则写"无 — agent 运行正常。"}
 
-## Release Readiness
-{✅ Release candidate / ⚠️ Hold — reason}
+## 发布就绪状态
+{✅ 可发布 / ⚠️ 暂缓 — 原因}
 
 ---
-*Next scheduled brief: {datetime}*
+*下次定时简报：{datetime}*
 ```
 
 ### Step 5 — Notify
 
-After writing the file, print the brief path so it's visible in the terminal
-or CI log:
+写完文件后在终端或 CI 日志中打印简报路径：
 
 ```
-📋 Brief written: docs/briefs/2026-05-10-08.md
-   Release readiness: ✅ Release candidate
+📋 简报已生成：docs/briefs/2026-05-10-08.md
+   发布就绪：✅ 可发布
 ```
 
-If there are escalations, print them prominently so they're impossible to miss.
+有升级事项时须显著打印，不得遗漏。
 
 ## Scheduler Configuration
 

package/skills/roll-build/SKILL.md

@@ -18,7 +18,7 @@ One entry point. Any input. Full delivery.
 Input received
   ├── matches "US-[A-Z]+-[0-9]+"  → Story mode: read BACKLOG → TCR workflow
   ├── matches "FIX-[A-Z]+-[0-9]+" → redirect to $roll-fix
-  ├── matches "IDEA-[0-9]+"       → redirect to $roll-jot (lookup and expand)
+  ├── matches "IDEA-[0-9]+"       → redirect to $roll-idea (lookup and expand)
   └── anything else               → Fly mode: clarify → design → execute
 ```
 
@@ -654,7 +654,7 @@ When complex state management is error-prone → consider full reset + re-initia
 roll-build   → ship anything (new idea, US-ID, free-text request)
 roll-fix     → fix a specific known bug (FIX-XXX / BUG-XXX)
 roll-design  → plan and design before building (no code output)
-roll-jot     → fast capture a bug or idea into BACKLOG.md
+roll-idea    → fast capture a bug or idea into BACKLOG.md
 roll-.clarify → passive scope clarification for vague build requests
 ```
 

package/skills/roll-design/SKILL.md

@@ -29,7 +29,7 @@ Discuss approaches, design architecture, plan requirements, and write to `BACKLO
 
 ## When Not to Use
 
-- One-liner capture of ideas or bugs (use `$roll-jot`)
+- One-liner capture of ideas or bugs (use `$roll-idea`)
 - Executing an already-split US-XXX (use `$roll-build`)
 - Fixing a well-defined FIX-XXX (use `$roll-fix`)
 

package/skills/{roll-jot → roll-idea}/SKILL.md

@@ -1,22 +1,22 @@
 ---
-name: roll-jot
+name: roll-idea
 license: MIT
 allowed-tools: "Read, Edit"
 description: "Fast backlog capture. Analyzes a short description, classifies it as bug or idea, and appends it to BACKLOG.md with an auto-incremented ID."
 ---
 
-# roll-jot
+# roll-idea
 
 > One-liner in, backlog entry out. No questions asked.
 
 ## Trigger
 
-User explicitly invokes `roll-jot` with a free-text description.
+User explicitly invokes `roll-idea` with a free-text description.
 
 ```
-$roll-jot 评价页面的星星也要纳入到 draft 的 scope 里
-$roll-jot 手机端星星指标一行一个从上往下排
-$roll-jot 给 HOD 加一个批量导出 PDF 的功能
+$roll-idea 评价页面的星星也要纳入到 draft 的 scope 里
+$roll-idea 手机端星星指标一行一个从上往下排
+$roll-idea 给 HOD 加一个批量导出 PDF 的功能
 ```
 
 ## When Not to Use

package/skills/roll-loop/SKILL.md

@@ -92,9 +92,13 @@ run_id: loop-20260510-0200
 
 After each item completes:
 
-1. Update state file: `status: idle`
-2. Check if a Feature is now fully complete (all its Stories ✅)
-3. If yes and `brief_on_feature_complete: true` → invoke `Skill("roll-brief")`
+1. **TCR 硬校验** — call `_loop_enforce_tcr <story_id> <started_at>`:
+   - Count `tcr:` prefix commits since `started_at` via `git log --oneline --since=<started_at>`
+   - Count == 0 → revert story status in BACKLOG.md from ✅ Done → 📋 Todo; write ALERT to `~/.shared/roll/loop/ALERT.md` with story ID, time, reason "zero tcr: commits since story start", and suggested actions (`roll loop now` / `$roll-build <id>` / `roll loop reset`)
+   - Count > 0 → continue normally
+2. Update state file: `status: idle`
+3. Check if a Feature is now fully complete (all its Stories ✅)
+4. If yes and `brief_on_feature_complete: true` → invoke `Skill("roll-brief")`
 
 ### Step 5 — Write Run Summary
 

package/skills/roll-notes/SKILL.md

@@ -23,7 +23,7 @@ $roll-notes 今天的 code review 给了很好的反馈
 
 ## When Not to Use
 
-- Capturing a bug or feature idea into BACKLOG (use `$roll-jot`)
+- Capturing a bug or feature idea into BACKLOG (use `$roll-idea`)
 - Generating user-facing release notes (use `$roll-.changelog`)
 - Writing design documents or AC (use `$roll-design`)