@seanyao/roll 2026.512.6 → 2026.512.8

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.512.6"
+VERSION="2026.512.8"
 ROLL_HOME="${ROLL_HOME:-${HOME}/.roll}"
 ROLL_CONFIG="${ROLL_HOME}/config.yaml"
 ROLL_GLOBAL="${ROLL_HOME}/conventions/global"
@@ -117,6 +117,18 @@ _get_ai_tools() {
   done
 }
 
+# Iterate all configured AI tools, calling: callback entry ai_dir ai_config ai_src [extra_args...]
+_for_each_ai_tool() {
+  local _feach_cb="$1"; shift
+  while IFS= read -r _feach_entry; do
+    "$_feach_cb" "$_feach_entry" \
+      "$(_ai_dir "$_feach_entry")" \
+      "$(_ai_config "$_feach_entry")" \
+      "$(_ai_src "$_feach_entry")" \
+      "$@"
+  done < <(_get_ai_tools)
+}
+
 # Add any ai_* keys from the default set that are missing from the user's config.
 # Non-destructive: never removes or modifies existing entries.
 _ensure_config_entries() {
@@ -505,16 +517,14 @@ _sync_convention_for_tool() {
   fi
 }
 
+_sync_one_tool() {
+  local _entry="$1" _ai_dir="$2" _cfg="$3" _src="$4" force="$5"
+  _sync_convention_for_tool "$ROLL_GLOBAL/$_src" "$_ai_dir/$_cfg" "$force"
+}
+
 _sync_conventions() {
   local force="${1:-false}"
-
-  while IFS= read -r entry; do
-    local ai_dir config_file src_file
-    ai_dir="$(_ai_dir "$entry")"
-    config_file="$(_ai_config "$entry")"
-    src_file="$(_ai_src "$entry")"
-    _sync_convention_for_tool "$ROLL_GLOBAL/$src_file" "$ai_dir/$config_file" "$force"
-  done < <(_get_ai_tools)
+  _for_each_ai_tool _sync_one_tool "$force"
 }
 
 # ─── Internal: sync skills (pull + link) ──────────────────────────────────────
@@ -1038,22 +1048,10 @@ scan_project_type_from_files() {
   fi
 }
 
-# ─── Helper: true when cwd has no existing source code ───────────────────────
-is_fresh_project() {
-  local dir="${1:-.}"
-  ! ( [[ -f "$dir/package.json" ]] || [[ -f "$dir/go.mod" ]] || \
-      [[ -f "$dir/Cargo.toml" ]] || [[ -f "$dir/requirements.txt" ]] || \
-      [[ -f "$dir/pyproject.toml" ]] || \
-      [[ -d "$dir/src" ]] || [[ -d "$dir/api" ]] || [[ -d "$dir/app" ]] )
-}
-
-# ─── Helper: make a scaffold dir + .gitkeep ───────────────────────────────────
-_mkscaffold() { mkdir -p "$1"; touch "$1/.gitkeep"; }
-
 # ─── Helper: write starter BACKLOG.md (no-op if exists) ──────────────────────
 _write_backlog() {
   if [[ -f "$1" ]]; then
-    _WK_MERGE_SUMMARY+=("unchanged|BACKLOG.md")
+    _ROLL_MERGE_SUMMARY+=("unchanged|BACKLOG.md")
     return
   fi
   cat > "$1" << 'EOF'
@@ -1068,18 +1066,18 @@ _write_backlog() {
 |----|---------|--------|
 EOF
   ok "Created: BACKLOG.md"
-  _WK_MERGE_SUMMARY+=("created|BACKLOG.md")
+  _ROLL_MERGE_SUMMARY+=("created|BACKLOG.md")
 }
 
 _ensure_features_dir() {
   if [[ -d "$1" ]]; then
-    _WK_MERGE_SUMMARY+=("unchanged|docs/features/")
+    _ROLL_MERGE_SUMMARY+=("unchanged|docs/features/")
     return
   fi
 
   mkdir -p "$1"
   ok "Created: docs/features/"
-  _WK_MERGE_SUMMARY+=("created|docs/features/")
+  _ROLL_MERGE_SUMMARY+=("created|docs/features/")
 }
 
 # ─── Helper: write starter .gitignore (no-op if exists) ──────────────────────
@@ -2266,7 +2264,8 @@ cmd_loop() {
     pause)   _loop_pause ;;
     resume)  _loop_resume ;;
     reset)   _loop_reset ;;
-    *) err "Usage: roll loop <on|off|now|test|status|monitor|runs|attach|mute|unmute|pause|resume|reset>"; exit 1 ;;
+    notify)  _notify "${1:-roll}" "${2:-}" ;;
+    *) err "Usage: roll loop <on|off|now|test|status|monitor|runs|attach|mute|unmute|pause|resume|reset|notify>"; exit 1 ;;
   esac
 }
 
@@ -2484,7 +2483,7 @@ _loop_status() {
   else
     echo -e "  Auto-attach  ${GREEN}live${NC}    run: roll loop mute"
   fi
-  [[ -f "$_LOOP_ALERT" ]] && { echo ""; echo -e "  ${RED}⚠ ALERT:${NC}"; sed 's/^/    /' "$_LOOP_ALERT"; }
+  [[ -f "$_LOOP_ALERT" ]] && { echo ""; echo -e "  ${RED}⚠ ALERT${NC}  (${CYAN}roll alert${NC} to manage)"; sed 's/^/    /' "$_LOOP_ALERT"; }
   [[ -f "$_LOOP_STATE" ]] && { echo ""; echo "  State:"; sed 's/^/    /' "$_LOOP_STATE"; }
   echo ""
 }
@@ -2596,11 +2595,12 @@ _loop_runs_dur() {
 }
 
 # Format a single JSONL run record for display.
+# Reads _LOOP_RUNS_BACKLOG global for ID→description lookup (set by _loop_runs).
 _loop_runs_format_line() {
-  local line="$1" show_project="$2"
+  local line="$1" show_project="$2" is_darwin="$3"
   command -v jq >/dev/null 2>&1 || { echo "  (jq required)"; return 0; }
 
-  local ts status project tcr duration alerts run_id reason built_count built_csv skipped_count
+  local ts status project tcr duration alerts run_id reason built_count skipped_count
   ts=$(jq -r '.ts // ""' <<<"$line")
   status=$(jq -r '.status // ""' <<<"$line")
   project=$(jq -r '.project // ""' <<<"$line")
@@ -2610,10 +2610,16 @@ _loop_runs_format_line() {
   run_id=$(jq -r '.run_id // ""' <<<"$line")
   reason=$(jq -r '.reason // ""' <<<"$line")
   built_count=$(jq -r '(.built // []) | length' <<<"$line")
-  built_csv=$(jq -r '(.built // []) | join(", ")' <<<"$line")
   skipped_count=$(jq -r '(.skipped // []) | length' <<<"$line")
 
-  local hhmm; hhmm=$(printf "%s" "$ts" | sed -E 's/.*T([0-9]{2}):([0-9]{2}).*/\1:\2/')
+  local hhmm epoch=""
+  if [[ "$is_darwin" == "1" ]]; then
+    epoch=$(date -j -u -f "%Y-%m-%dT%H:%M:%SZ" "$ts" "+%s" 2>/dev/null) || epoch=""
+    [[ -n "$epoch" ]] && hhmm=$(date -j -f "%s" "$epoch" "+%H:%M" 2>/dev/null) || hhmm=""
+  else
+    hhmm=$(date -d "$ts" "+%H:%M" 2>/dev/null) || hhmm=""
+  fi
+  [[ -z "$hhmm" ]] && hhmm=$(printf "%s" "$ts" | sed -E 's/.*T([0-9]{2}):([0-9]{2}).*/\1:\2/')
   local prefix=""
   if [[ "$show_project" == "true" ]]; then
     prefix="[$(basename "$project")] "
@@ -2623,8 +2629,29 @@ _loop_runs_format_line() {
     built)
       local skipped_note=""
       [[ "$skipped_count" -gt 0 ]] && skipped_note=", ${skipped_count} skipped"
-      printf "  %s  %s✅ built %s  (%d items, %d tcr%s, %s)\n" \
-        "$hhmm" "$prefix" "$built_csv" "$built_count" "$tcr" "$skipped_note" "$(_loop_runs_dur "$duration")"
+      local items_word; [[ "$built_count" -eq 1 ]] && items_word="item" || items_word="items"
+      printf "  %s  %s✅ built %d %s (%d tcr%s, %s)\n" \
+        "$hhmm" "$prefix" "$built_count" "$items_word" "$tcr" "$skipped_note" "$(_loop_runs_dur "$duration")"
+      local id desc
+      while IFS= read -r id; do
+        [[ -z "$id" ]] && continue
+        desc=""
+        if [[ -n "$_LOOP_RUNS_BACKLOG" ]]; then
+          desc=$(printf "%s\n" "$_LOOP_RUNS_BACKLOG" | awk -F'|' -v id="$id" '
+            NF >= 3 {
+              cell = $2; gsub(/^[[:space:]]+|[[:space:]]+$/, "", cell)
+              if (cell == id || cell ~ "^\\[" id "\\]") {
+                gsub(/^[[:space:]]+|[[:space:]]+$/, "", $3); print $3; exit
+              }
+            }')
+        fi
+        if [[ -n "$desc" ]]; then
+          [[ ${#desc} -gt 72 ]] && desc="${desc:0:69}..."
+          printf "    • %-14s %s\n" "$id" "$desc"
+        else
+          printf "    • %s\n" "$id"
+        fi
+      done < <(jq -r '(.built // []) | .[]' <<<"$line")
       ;;
     idle)
       printf "  %s  %s○ idle — no Todo items\n" "$hhmm" "$prefix"
@@ -2677,10 +2704,27 @@ _loop_runs() {
   local reversed; reversed=$(printf "%s\n" "$filtered" | awk '{a[NR]=$0} END{for(i=NR; i>=1; i--) print a[i]}')
   local recent; recent=$(printf "%s\n" "$reversed" | head -n "$n")
 
+  local _is_darwin=""
+  [[ "$(uname)" == "Darwin" ]] && _is_darwin="1"
+
+  _LOOP_RUNS_BACKLOG=""
+  [[ -f "$project_path/BACKLOG.md" ]] && _LOOP_RUNS_BACKLOG=$(cat "$project_path/BACKLOG.md")
+
   while IFS= read -r line; do
     [[ -z "$line" ]] && continue
-    _loop_runs_format_line "$line" "$all_flag"
+    _loop_runs_format_line "$line" "$all_flag" "$_is_darwin"
   done <<<"$recent"
+  unset _LOOP_RUNS_BACKLOG
+}
+
+# Send a macOS system notification. No-op when muted, non-macOS, or osascript unavailable.
+_notify() {
+  local title="${1:-roll}"
+  local body="${2:-}"
+  [ "$(uname)" = "Darwin" ] || return 0
+  [ -f "$_LOOP_MUTE_FILE" ] && return 0
+  command -v osascript >/dev/null 2>&1 || return 0
+  osascript -e "display notification \"${body}\" with title \"${title}\"" >/dev/null 2>&1 || true
 }
 
 # Count `tcr:` prefixed commits in the current git repo since started_at timestamp.
@@ -2690,6 +2734,152 @@ _loop_tcr_count() {
     | awk '/^[a-f0-9]+ tcr:/{n++} END{print n+0}'
 }
 
+# Parse origin remote URL → "owner/repo" for GitHub repos.
+# Returns non-zero if no origin, or origin is not github.com.
+# Decoupled from `gh` auto-detection so SSH config host rewrites don't break it.
+_gh_repo_slug() {
+  local url
+  url=$(git config --get remote.origin.url 2>/dev/null) || return 1
+  case "$url" in
+    git@github.com:*)          url="${url#git@github.com:}" ;;
+    ssh://git@github.com/*)    url="${url#ssh://git@github.com/}" ;;
+    https://github.com/*)      url="${url#https://github.com/}" ;;
+    http://github.com/*)       url="${url#http://github.com/}" ;;
+    *)                         return 1 ;;
+  esac
+  url="${url%.git}"
+  [[ -z "$url" ]] && return 1
+  printf "%s\n" "$url"
+}
+
+# Poll gh run list until current commit's CI completes.
+# Returns 0 on success (or when gh binary missing — graceful skip).
+# Returns 1 on CI failure, timeout, or any gh call failure.
+_ci_wait() {
+  local timeout="${1:-300}"
+  local interval=15
+  local elapsed=0
+
+  command -v gh &>/dev/null || { warn "gh not installed — skipping CI gate  gh 未安装，跳过 CI 检查"; return 0; }
+
+  local commit; commit=$(git rev-parse HEAD 2>/dev/null) || { err "Not a git repo  非 git 仓库"; return 1; }
+  local short; short=$(git rev-parse --short HEAD 2>/dev/null)
+
+  # Resolve owner/repo from git remote so we don't depend on gh's auto-detection,
+  # which breaks when ~/.ssh/config rewrites `Host github.com` → IP address.
+  local repo_slug; repo_slug=$(_gh_repo_slug) || {
+    err "Cannot determine GitHub repo from origin remote  无法从 origin 推导 GitHub 仓库"
+    return 1
+  }
+
+  ok "Waiting for CI on ${short} (${repo_slug})  等待 CI: ${short}"
+
+  while (( elapsed < timeout )); do
+    local runs
+    runs=$(gh -R "$repo_slug" run list --commit "$commit" --json status,conclusion 2>&1) || {
+      err "gh run list failed for ${repo_slug}@${short}: ${runs}  gh 调用失败"
+      return 1
+    }
+
+    if [[ -z "$runs" || "$runs" == "[]" ]]; then
+      (( elapsed == 0 )) && echo "  No CI runs found yet, waiting...  尚无 CI 记录，等待触发..."
+      sleep "$interval"
+      elapsed=$(( elapsed + interval ))
+      continue
+    fi
+
+    local pending
+    pending=$(echo "$runs" | jq -r '[.[] | select(.status != "completed")] | length' 2>/dev/null || echo "0")
+
+    if [[ "$pending" -gt 0 ]]; then
+      printf "  ⏳ CI running (%ds)...  CI 运行中（%ds）...\n" "$elapsed" "$elapsed"
+      sleep "$interval"
+      elapsed=$(( elapsed + interval ))
+      continue
+    fi
+
+    local failed
+    failed=$(echo "$runs" | jq -r '[.[] | select(.conclusion != "success" and .conclusion != "skipped" and .conclusion != null)] | length' 2>/dev/null || echo "0")
+
+    if [[ "$failed" -gt 0 ]]; then
+      err "CI failed for ${short}  CI 失败: ${short}"
+      return 1
+    fi
+
+    ok "CI passed  CI 通过"
+    return 0
+  done
+
+  warn "CI timed out after ${timeout}s  CI 等待超时（${timeout}s）"
+  return 1
+}
+
+# Pre-run CI health check — call before picking up new stories.
+# Refuses to build on a red base (HEAD CI failed). Lenient on unknown states
+# (gh missing, repo unparseable, no runs yet) — the post-build _loop_enforce_ci
+# is the strict gate.
+# Returns 0: ok to proceed (green / pending / unknown / no gh).
+# Returns 1: HEAD CI is definitively red → ALERT written, do not build.
+_loop_precheck_ci() {
+  command -v gh &>/dev/null || return 0
+
+  local commit; commit=$(git rev-parse HEAD 2>/dev/null) || return 0
+  local slug; slug=$(_gh_repo_slug) || return 0
+
+  local runs
+  runs=$(gh -R "$slug" run list --commit "$commit" --json conclusion 2>/dev/null) || return 0
+  [[ -z "$runs" || "$runs" == "[]" ]] && return 0
+
+  local failed
+  failed=$(echo "$runs" | jq -r '[.[] | select(.conclusion != null and .conclusion != "success" and .conclusion != "skipped")] | length' 2>/dev/null || echo "0")
+
+  if [[ "$failed" -gt 0 ]]; then
+    local short; short=$(git rev-parse --short HEAD 2>/dev/null || echo unknown)
+    err "Pre-run CI check: HEAD CI is red — refuse to build on broken base (${short})  HEAD CI 红，拒绝在破损的基础上构建"
+    mkdir -p "$(dirname "$_LOOP_ALERT")"
+    cat > "$_LOOP_ALERT" << EOF
+# ALERT — Pre-run CI check failed (red base)
+
+**Time**: $(date '+%Y-%m-%d %H:%M')
+**Commit**: ${short}
+**Reason**: HEAD CI is red — loop refused to build on a broken base  HEAD CI 红，loop 拒绝在破损的基础上构建
+
+**Action required**:
+- Investigate and fix CI: \`gh -R $(_gh_repo_slug) run list --commit ${commit}\`
+- After fixing and pushing green commit: \`roll loop now\`
+EOF
+    _notify "roll ⚠ CI red" "loop refused to build on broken base (${short})"
+    return 1
+  fi
+  return 0
+}
+
+# CI gate before marking a story Done.
+# On CI failure: writes ALERT, returns 1 (caller keeps story 🔨 In Progress).
+# When gh unavailable: returns 0 (graceful skip).
+_loop_enforce_ci() {
+  local story_id="$1"
+
+  _ci_wait 300 && return 0
+
+  mkdir -p "$(dirname "$_LOOP_ALERT")"
+  cat > "$_LOOP_ALERT" << EOF
+# ALERT — CI gate failed
+
+**Time**: $(date '+%Y-%m-%d %H:%M')
+**Story**: ${story_id}
+**Commit**: $(git rev-parse --short HEAD 2>/dev/null || echo unknown)
+**Reason**: CI did not pass — story kept as 🔨 In Progress  CI 未通过，故事保持进行中
+
+**Action required** (choose one):
+- Fix CI and re-run: \`roll loop now\`
+- Take over manually: \`\$roll-build ${story_id}\`
+- Reset and retry: \`roll loop reset\` then \`roll loop now\`
+EOF
+  _notify "roll ⚠ CI Failed" "${story_id}: CI did not pass"
+  return 1
+}
+
 # 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() {
@@ -2722,6 +2912,7 @@ _loop_enforce_tcr() {
 - Take over manually: \`\$roll-build ${story_id}\`
 - Reset and retry: \`roll loop reset\` then \`roll loop now\`
 EOF
+    _notify "roll ⚠ TCR Failed" "${story_id}: no tcr: commits found"
     return 1
   fi
 
@@ -2802,7 +2993,7 @@ _loop_monitor() {
     # Alert
     if [[ -f "$_LOOP_ALERT" ]]; then
       echo ""
-      echo -e "  ${RED}⚠ ALERT:${NC}"
+      echo -e "  ${RED}⚠ ALERT${NC}  (${CYAN}roll alert${NC} to manage)"
       sed 's/^/    /' "$_LOOP_ALERT"
     fi
 
@@ -2973,6 +3164,88 @@ _backlog_extract_id() {
   fi
 }
 
+# ═══════════════════════════════════════════════════════════════════════════════
+# CI — check or wait for current commit's CI status
+# ═══════════════════════════════════════════════════════════════════════════════
+# ALERT — view / ack / resolve loop alert lifecycle
+# ═══════════════════════════════════════════════════════════════════════════════
+
+cmd_alert() {
+  local subcmd="${1:-list}"
+  shift || true
+
+  case "$subcmd" in
+    list|"")
+      if [[ ! -f "$_LOOP_ALERT" ]]; then
+        ok "No active alerts  暂无告警"
+        return 0
+      fi
+      echo -e "${BOLD}Active Alert  当前告警${NC}"
+      echo ""
+      cat "$_LOOP_ALERT"
+      echo ""
+      echo -e "  Run '${CYAN}roll alert ack${NC}' to acknowledge, '${CYAN}roll alert resolve${NC}' to clear."
+      echo -e "  运行 'roll alert ack' 确认告警，'roll alert resolve' 清除告警。"
+      ;;
+    ack)
+      if [[ ! -f "$_LOOP_ALERT" ]]; then
+        warn "No active alerts to acknowledge  暂无待确认告警"
+        return 0
+      fi
+      local ts; ts=$(date '+%Y-%m-%d %H:%M:%S')
+      {
+        echo ""
+        echo "**Acknowledged**: ${ts}"
+      } >> "$_LOOP_ALERT"
+      ok "Alert acknowledged at ${ts}  告警已确认"
+      ;;
+    resolve|clear)
+      if [[ ! -f "$_LOOP_ALERT" ]]; then
+        ok "No active alerts  暂无告警"
+        return 0
+      fi
+      rm -f "$_LOOP_ALERT"
+      ok "Alert resolved and cleared  告警已解决并清除"
+      ;;
+    *)
+      err "Unknown subcommand: $subcmd  未知子命令: $subcmd"
+      echo "  Usage: roll alert [list|ack|resolve]"
+      echo "  用法: roll alert [list|ack|resolve]"
+      return 1
+      ;;
+  esac
+}
+
+# ═══════════════════════════════════════════════════════════════════════════════
+
+cmd_ci() {
+  local wait_mode=false
+  local timeout=300
+
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      --wait) wait_mode=true; shift ;;
+      --timeout=*) timeout="${1#*=}"; shift ;;
+      *) err "Usage: roll ci [--wait] [--timeout=N]  用法: roll ci [--wait] [--timeout=N]"; exit 1 ;;
+    esac
+  done
+
+  if $wait_mode; then
+    _ci_wait "$timeout"
+    return
+  fi
+
+  command -v gh &>/dev/null || { warn "gh not installed  gh 未安装"; return 0; }
+  local commit; commit=$(git rev-parse HEAD 2>/dev/null) || { err "Not a git repo  非 git 仓库"; return 1; }
+  local runs
+  runs=$(gh run list --commit "$commit" --json status,conclusion,name 2>/dev/null) || { warn "gh run list failed"; return 0; }
+  if [[ -z "$runs" || "$runs" == "[]" ]]; then
+    echo "No CI runs for $(git rev-parse --short HEAD)  当前提交无 CI 记录"
+    return 0
+  fi
+  echo "$runs" | jq -r '.[] | "\(.name): \(.status)/\(.conclusion)"'
+}
+
 cmd_backlog() {
   local backlog="BACKLOG.md"
   if [[ ! -f "$backlog" ]]; then
@@ -3193,7 +3466,7 @@ _dashboard() {
   else
     echo -e "  Loop  ${YELLOW}○ off${NC}   run: roll loop on"
   fi
-  [[ -f "$_LOOP_ALERT" ]] && echo -e "  ${RED}⚠ ALERT — run: roll loop status${NC}"
+  [[ -f "$_LOOP_ALERT" ]] && echo -e "  ${RED}⚠ ALERT — run: roll alert${NC}"
 
   # Backlog summary
   if [[ -f "BACKLOG.md" ]]; then
@@ -3253,6 +3526,7 @@ usage() {
   echo "  backlog unblock <pat>         Restore matching items to 📋 Todo   恢复为待处理"
   echo "  agent [use <name>|list]   [Config] Per-project agent selection            切换项目 agent"
   echo "  release                [Publish] Sync changelog + version bump + npm publish  同步日志并发版"
+  echo "  ci [--wait]            [CI] Show or wait for current commit's CI status       查看/等待 CI 状态"
   echo ""
   echo "Examples / 示例:"
   echo "  roll setup                    # New machine: first-time install            新机器首次安装"
@@ -3280,8 +3554,10 @@ main() {
     loop)          cmd_loop "$@" ;;
     brief)         cmd_brief "$@" ;;
     backlog)       cmd_backlog "$@" ;;
+    alert)         cmd_alert "$@" ;;
     agent)         cmd_agent "$@" ;;
     release)       cmd_release "$@" ;;
+    ci)            cmd_ci "$@" ;;
     version|--version|-v) echo "roll v${VERSION}" ;;
     help|--help|-h) usage ;;
     "") [[ -f "BACKLOG.md" ]] && _dashboard || { usage; _show_changelog; } ;;

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@seanyao/roll",
-  "version": "2026.512.6",
+  "version": "2026.512.8",
   "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"
+    "test": "bash tests/run.sh"
   },
   "keywords": [
     "ai",

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

@@ -101,6 +101,19 @@ CHANGELOG 是给**使用者**看的，不是给维护者看的。一句话讲清
 - **Fixed**: 多个 loop 实例不会再互相打架（重复触发自动跳过）
 ```
 
+❌ 说机制不说现象（Fix 类最常犯）：
+```
+- **Fixed**: `roll loop runs` 过滤条件从完整路径改为 slug，历史记录不再因路径不匹配而消失
+- **Fixed**: `roll-loop` skill 写入 `runs.jsonl` 时 project slug 计算方式明确，避免写成 bare basename
+```
+
+✅ 直接说用户看到了什么：
+```
+- **Fixed**: `roll loop runs` 不再报"当前项目尚无运行记录"，历史记录正常显示
+```
+
+Fix 类句式参考：`<命令/功能> 不再 <之前的坏现象>`，或 `<命令/功能> 现在 <正常表现>`。内部有几个 bug 导致这一个现象，合并成一条。
+
 ### 4. Section Header — Always `## Unreleased`
 
 **⚠️ do NOT guess version numbers.** Only `scripts/release.sh` assigns concrete
@@ -152,11 +165,20 @@ version numbers like `v2026.511.8`. Just write to `## Unreleased`.
 
 **Ordering**: Unreleased always at top. Below it, released versions in reverse chronological order.
 
-### 6. Commit Update
+### 6. Stage Update
+
+**Normal path (called from `$roll-build` or `$roll-fix`)**: stage only — the
+caller's completion commit will pick up CHANGELOG.md.
+
+```bash
+git add CHANGELOG.md
+```
+
+**Standalone / manual path** (called outside a roll-build session): stage and commit.
 
 ```bash
 git add CHANGELOG.md
-git commit -m "docs: update changelog for release $(date +%Y.%m.%d)"
+git commit -m "chore: sync changelog"
 git push
 ```