@seanyao/roll 2026.529.3 → 2026.529.5

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## v2026.529.5
+
+### Fixed
+
+- loop dashboard 恢复显示当天跑完的 cycle（读取端对齐项目本地事件）`[loop]`
+- 非 Claude agent 执行阶段恢复存活心跳（修复心跳子进程 fork 早于 source）`[loop]`
+
+## v2026.529.4
+
+### Fixed
+
+- 非 Claude agent 跑 loop 不再黑屏 `[loop]`
+
+### Added
+
+- `roll-doc` 现在追踪数据流和调用链 `[loop]`
+
 ## v2026.529.3
 
 ### Fixed

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.529.3"
+VERSION="2026.529.5"
 ROLL_HOME="${ROLL_HOME:-${HOME}/.roll}"
 ROLL_CONFIG="${ROLL_HOME}/config.yaml"
 ROLL_GLOBAL="${ROLL_HOME}/conventions/global"
@@ -6031,6 +6031,10 @@ printf '%s:%s\n' "\$\$" "\$(date -u +%s)" > "\$INNER_LOCK"
 # readers see "still alive in <phase>" during long-running silences (e.g.
 # agent_invoke 5-45 min). CURRENT_PHASE is maintained by _phase_begin/_phase_end.
 HEARTBEAT_FILE="\${_SHARED_ROOT:-\${HOME}/.shared/roll}/loop/.heartbeat-${slug}"
+# FIX-136: file-based phase tracking so forked heartbeat child can see phase changes.
+# CURRENT_PHASE is inherited at fork time — changes after fork are invisible to child.
+# Writing phase state to a file decouples the heartbeat from fork-time snapshot.
+HEARTBEAT_PHASE_FILE="\${_SHARED_ROOT:-\${HOME}/.shared/roll}/loop/.phase-${slug}"
 CURRENT_PHASE=""
 # bash 3.2 (macOS /bin/bash) lacks associative arrays — use namespaced
 # variables via 'printf -v' + indirect '\${!VAR}' expansion instead.
@@ -6042,6 +6046,8 @@ _phase_begin() {
   local _name="\$1"
   printf -v "_PHASE_START_\${_name}" '%s' "\$(date +%s)"
   CURRENT_PHASE="\$_name"
+  # FIX-136: write phase+start_ts to file so forked heartbeat child can read it
+  printf '%s %s' "\$_name" "\$(date +%s)" > "\$HEARTBEAT_PHASE_FILE"
   _loop_event phase_start "\$_name" "" "" || true
 }
 _phase_end() {
@@ -6053,24 +6059,32 @@ _phase_end() {
   printf -v "_PHASE_DUR_\${_name}" '%s' "\$_dur"
   case " \$_PHASE_NAMES_DONE " in *" \$_name "*) ;; *) _PHASE_NAMES_DONE="\${_PHASE_NAMES_DONE} \$_name" ;; esac
   CURRENT_PHASE=""
+  # FIX-136: clear phase file so heartbeat knows no active phase
+  echo -n > "\$HEARTBEAT_PHASE_FILE" 2>/dev/null || true
   _loop_event phase_end "\$_name" "\${_dur}s" "\$_outcome" || true
 }
 _heartbeat_writer() {
   while true; do
     echo "\$(date -u +%s)" > "\$HEARTBEAT_FILE"
-    if [ -n "\$CURRENT_PHASE" ]; then
-      local _start_var="_PHASE_START_\${CURRENT_PHASE}"
-      local _phase_start="\${!_start_var:-}"
-      if [ -n "\$_phase_start" ]; then
-        local _el=\$(( \$(date +%s) - _phase_start ))
-        _loop_event phase_tick "\$CURRENT_PHASE" "\${_el}s elapsed" "" 2>/dev/null || true
+    # FIX-136: read phase from file — CURRENT_PHASE is inherited at fork and
+    # never updated. The parent writes phase+start_ts on _phase_begin, clears
+    # on _phase_end. No phase file = no active phase = skip tick.
+    if [ -f "\$HEARTBEAT_PHASE_FILE" ]; then
+      read -r _hb_phase _hb_start_ts < "\$HEARTBEAT_PHASE_FILE" 2>/dev/null || true
+      if [ -n "\$_hb_phase" ] && [ -n "\$_hb_start_ts" ]; then
+        local _el=\$(( \$(date +%s) - _hb_start_ts ))
+        _loop_event phase_tick "\$_hb_phase" "\${_el}s elapsed" "" 2>/dev/null || true
       fi
     fi
     sleep 60
   done
 }
-_heartbeat_writer &
-_HEARTBEAT_PID=\$!
+# FIX-138: _heartbeat_writer is started AFTER sourcing bin/roll below, NOT here.
+# Backgrounding a function forks a subshell snapshot of the current shell;
+# _loop_event (defined in bin/roll, sourced ~240 lines later) is undefined in
+# that snapshot, so every phase_tick call silently failed (2>/dev/null || true)
+# -> zero heartbeat across the whole cycle. The publish_wait_merge ticks seen
+# were its own 30s poll loop, not this writer. Starting post-source fixes it.
 # FIX-057: cycle hard timeout — 45 minute SLA per loop cycle. If a cycle runs
 # longer, kill claude / loop-fmt.py / all backgrounded children, mark the
 # in-progress backlog item Blocked (caller decides), and exit cleanly so the
@@ -6300,11 +6314,10 @@ _runs_append "failed" 0 "[]" "\$_phases_t" 2>/dev/null || true
     sed -E 's/\x1b\[[0-9;]*[A-Za-z]//g; s/\r$//' "\$ROLL_CYCLE_LOG_RAW" \
       > "\${_log_dir}/\${CYCLE_ID}.log" 2>/dev/null || true
     rm -f "\$ROLL_CYCLE_LOG_RAW"
-    # Rotate: keep newest ROLL_CYCLE_LOG_KEEP (default 50) .log files
-    _keep="\${ROLL_CYCLE_LOG_KEEP:-50}"
-    ( cd "\$_log_dir" && ls -t *.log 2>/dev/null | tail -n +\$((_keep + 1)) | xargs -r rm -f ) 2>/dev/null || true
+    # FIX-139: keep ALL per-cycle logs — no rotation cap. Each log is ~2KB,
+    # full-year retention is a few MB. Owner: "不做 50 的限制,所有的都要留下来".
   fi
-  rm -f "\$INNER_LOCK" "\$HEARTBEAT_FILE"
+  rm -f "\$INNER_LOCK" "\$HEARTBEAT_FILE" "\$HEARTBEAT_PHASE_FILE"
   exit "\$_rc"
 }
 trap '_inner_cleanup' EXIT
@@ -6316,6 +6329,11 @@ trap '_inner_cleanup' EXIT
 source "${roll_bin}"
 set +e
 
+# FIX-138: start heartbeat now that _loop_event is defined (see note at its
+# definition above). Forking earlier loses _loop_event in the subshell snapshot.
+_heartbeat_writer &
+_HEARTBEAT_PID=\$!
+
 # FIX-052: bin/roll initializes loop state paths from cwd at source time, but
 # the inner script may be launched from anywhere. Override to this project's
 # slug (baked at template generation) so helpers like _worktree_alert write
@@ -6468,6 +6486,11 @@ export LOOP_SHARED_ROOT="\${_SHARED_ROOT:-\$HOME/.shared/roll}"
 export ROLL_LOOP_AGENT="\${CYCLE_AGENT:-\$(_project_agent)}"
 export ROLL_LOOP_ROUTED_STORY ROLL_LOOP_ROUTED_AGENT ROLL_LOOP_ROUTED_RULE
 _phase_begin agent_invoke
+# FIX-136: non-claude agents (pi/deepseek/kimi) buffer stdout when piped.
+# Force a pseudo-TTY via script(1) so loop-fmt.py's passthrough receives
+# output in real time — without this, tmux is black for the entire phase.
+_AGENT_PTY_PREFIX=""
+[ "\$ROLL_LOOP_AGENT" != "claude" ] && _AGENT_PTY_PREFIX="script -q /dev/null"
 for _attempt in 1 2 3; do
   # FIX-068: defensive reset before each attempt — _CYCLE_TIMED_OUT carries
   # the SIGTERM result of the previous attempt and would otherwise force an
@@ -6493,11 +6516,11 @@ for _attempt in 1 2 3; do
   # FIX-134: prefer the runtime-rebuilt command (routing-aware); fall back to
   # the baked command (project agent at \`roll loop on\` time) when empty.
   if [ -f "\$FMT" ]; then
-    if [ -n "\$_CYCLE_CMD" ]; then ( cd "\$WT" && eval "\$_CYCLE_CMD" ) | python3 "\$FMT"
-    else ( cd "\$WT" && ${agent_cmd} ) | python3 "\$FMT"; fi
+    if [ -n "\$_CYCLE_CMD" ]; then ( cd "\$WT" && eval \$_AGENT_PTY_PREFIX "\$_CYCLE_CMD" ) | python3 "\$FMT"
+    else ( cd "\$WT" && \$_AGENT_PTY_PREFIX ${agent_cmd} ) | python3 "\$FMT"; fi
   else
-    if [ -n "\$_CYCLE_CMD" ]; then ( cd "\$WT" && eval "\$_CYCLE_CMD" )
-    else ( cd "\$WT" && ${agent_cmd} ); fi
+    if [ -n "\$_CYCLE_CMD" ]; then ( cd "\$WT" && eval \$_AGENT_PTY_PREFIX "\$_CYCLE_CMD" )
+    else ( cd "\$WT" && \$_AGENT_PTY_PREFIX ${agent_cmd} ); fi
   fi
   _exit=\$?
   kill "\$_WATCHDOG_PID" 2>/dev/null
@@ -6605,6 +6628,11 @@ if [ "\$_USE_WORKTREE" = "1" ]; then
           _phase_begin publish_wait_merge
           if ! ( cd "\$WT" && _loop_wait_pr_merge "\$BRANCH" ); then
             _worktree_alert "cycle \${CYCLE_ID}: FIX-047: PR not merged within timeout — code may not be in main (BRANCH=\${BRANCH})"
+            # FIX-140: PR not merged => commits are NOT on main => story is NOT
+            # done. Revert the routed story ✅ Done -> 📋 Todo so backlog reflects
+            # reality instead of a false Done. (FIX-141's open-PR gate keeps the
+            # next cycle from opening a duplicate PR while this one is still open.)
+            [ -n "\${ROLL_LOOP_ROUTED_STORY:-}" ] && _loop_mark_todo "\$ROLL_LOOP_ROUTED_STORY" 2>/dev/null || true
             _phase_end publish_wait_merge fail
           else
             _phase_end publish_wait_merge ok
@@ -6754,7 +6782,11 @@ fi
 LOCK="\$(dirname "\$0")/.LOCK-\$(basename "\$0" .sh | sed 's/^run-//')"
 SESSION="roll-loop-\$(basename "\$0" .sh | sed 's/^run-//')"
 INNER_SCRIPT="${inner_path}"
+# FIX-139: machine/ops log path is supplied by the caller (now project-local
+# .roll/loop/cron.log — see the _write_loop_runner_script call site). Ensure its
+# directory exists before the early LOCK-skip echoes append to it.
 LOG="${log_path}"
+mkdir -p "\$(dirname "\$LOG")" 2>/dev/null || true
 if [ -f "\$LOCK" ]; then
   prev_pid=\$(head -1 "\$LOCK" 2>/dev/null || echo "")
   if [ -n "\$prev_pid" ] && kill -0 "\$prev_pid" 2>/dev/null; then
@@ -6794,7 +6826,10 @@ if command -v tmux >/dev/null 2>&1; then
   CYCLE_LOG_RAW="${project_path}/.roll/cycle-logs/.pipe-\$\$.raw"
   export ROLL_CYCLE_LOG_RAW="\$CYCLE_LOG_RAW"
   tmux new-session -d -s "\$SESSION" -x 200 -y 50 "bash \"\$INNER_SCRIPT\""
-  tmux pipe-pane -t "\$SESSION" "tee -a \"\$LOG\" >> \"\$ROLL_CYCLE_LOG_RAW\""
+  # FIX-139: pane output goes ONLY to the per-cycle raw (-> <CYCLE_ID>.log),
+  # no cumulative tee into LOG — per-cycle logs are the single source, all kept
+  # (no cap). Machine/ops events still append to LOG directly.
+  tmux pipe-pane -t "\$SESSION" "cat >> \"\$ROLL_CYCLE_LOG_RAW\""
   # Auto-attach popup: when not muted, spawn a Terminal.app window attached
   # to the tmux session so the user can watch the loop work in real time.
   # FIX-054: terminal selection removed — fixed to macOS Terminal.app for
@@ -6814,8 +6849,10 @@ if command -v tmux >/dev/null 2>&1; then
     # cron-<slug>.log file still has the full transcript as a fallback.
     # FIX-131: after tmux session ends, open the cron log with less so the
     # user can scroll through the full cycle output instead of seeing nothing.
-    printf '#!/bin/bash\\ntmux attach -t %s 2>/dev/null\\nLOGFILE=~/.shared/roll/loop/cron-%s.log\\necho\\nif [ -f "\$LOGFILE" ]; then\\n  echo "================================================================"\\n  echo "  Cycle ended  —  showing log (arrows to scroll, q to close)"\\n  echo "================================================================"\\n  less -R +G "\$LOGFILE"\\nelse\\n  echo "================================================================"\\n  echo "  Cycle ended. Log not found: \$LOGFILE"\\n  echo "  press enter to close."\\n  echo "================================================================"\\n  read _\\nfi\\n' \\
-      "\$SESSION" "${slug}" > "\$_attach_cmd" 2>/dev/null || true
+    # FIX-139: after the session ends, show ONLY this cycle's per-cycle log
+    # (newest in .roll/cycle-logs/), not the global cumulative transcript.
+    printf '#!/bin/bash\\ntmux attach -t %s 2>/dev/null\\nLOGFILE=\$(ls -t "%s"/.roll/cycle-logs/*.log 2>/dev/null | head -1)\\necho\\nif [ -n "\$LOGFILE" ] && [ -f "\$LOGFILE" ]; then\\n  echo "================================================================"\\n  echo "  Cycle ended  —  showing this cycle log (arrows to scroll, q to close)"\\n  echo "================================================================"\\n  less -R +G "\$LOGFILE"\\nelse\\n  echo "================================================================"\\n  echo "  Cycle ended. No per-cycle log yet."\\n  echo "  press enter to close."\\n  echo "================================================================"\\n  read _\\nfi\\n' \\
+      "\$SESSION" "${project_path}" > "\$_attach_cmd" 2>/dev/null || true
     chmod +x "\$_attach_cmd" 2>/dev/null || true
     open -g -a Terminal "\$_attach_cmd" >/dev/null 2>&1 || true
   fi
@@ -6957,7 +6994,11 @@ _install_launchd_plists() {
     local cmd; cmd=$(_agent_skill_cmd "${sd}/${skill}/SKILL.md" 2>/dev/null || echo "roll loop now")
 
     if [[ "$svc" == "loop" ]]; then
-      _write_loop_runner_script "$runner" "$project_path" "cd \"${project_path}\" && ${cmd}" "$log" "$active_start" "$active_end" "${sd}/${skill}/SKILL.md"
+      # FIX-139: loop machine/ops log is project-local (.roll/loop/cron.log),
+      # not the global cron-<slug>.log. Reader (FIX-137) reads it project-local;
+      # per-cycle transcripts live in .roll/cycle-logs/ (single source, no dup).
+      local loop_log="${project_path}/.roll/loop/cron.log"
+      _write_loop_runner_script "$runner" "$project_path" "cd \"${project_path}\" && ${cmd}" "$loop_log" "$active_start" "$active_end" "${sd}/${skill}/SKILL.md"
     else
       _write_runner_script "$runner" "$project_path" "cd \"${project_path}\" && ${cmd}" "$log"
     fi
@@ -9635,6 +9676,15 @@ _loop_pick_next_story() {
   local backlog="${1:-.roll/backlog.md}"
   [ -f "$backlog" ] || return 1
 
+  # FIX-141: fetch open PR titles ONCE so we can skip any story that already
+  # has an open PR (it's in review / awaiting merge — re-picking it produces a
+  # duplicate PR, as happened with FIX-137 #257 -> #258). gh runs in the cycle
+  # worktree (has the remote); empty/unavailable gh => no skipping (safe).
+  local _open_pr_titles=""
+  if command -v gh >/dev/null 2>&1; then
+    _open_pr_titles=$(gh pr list --state open --json title --jq '.[].title' 2>/dev/null || echo "")
+  fi
+
   # Two passes over the file, once per type prefix, return first hit.
   local prefix
   for prefix in FIX US REFACTOR; do
@@ -9655,6 +9705,11 @@ _loop_pick_next_story() {
       if ! _loop_check_depends_on "$id" "$backlog" >/dev/null 2>&1; then
         continue
       fi
+      # Gate 3 (FIX-141): skip if an open PR already references this story id
+      # (in its title) — avoids duplicate PRs for a story already in review.
+      if [ -n "$_open_pr_titles" ] && printf '%s\n' "$_open_pr_titles" | grep -qE "${id}([^0-9A-Za-z]|$)"; then
+        continue
+      fi
       printf '%s\n' "$id"
       return 0
     done < "$backlog"

package/lib/roll-loop-status.py

@@ -121,16 +121,101 @@ def _git_remote_url(repo_path: str) -> Optional[str]:
 def shared_root() -> Path:
     return Path(os.environ.get("ROLL_SHARED_ROOT") or os.path.expanduser("~/.shared/roll"))
 
+# ════════════════════════════════════════════════════════════════════════════
+# Project path resolution — mirrors bin/roll's _loop_resolve_project_path
+# ════════════════════════════════════════════════════════════════════════════
+def _resolve_project_path(slug: str) -> Optional[Path]:
+    """Mirror bin/roll's _loop_resolve_project_path: resolve a project slug
+    back to the absolute project root directory.
+
+    Priority chain (same as bash):
+      1. ROLL_MAIN_PROJECT env var (set by cycle runner)
+      2. macOS launchd plist WorkingDirectory for com.roll.loop.<slug>
+      3. crontab entry referencing run-<slug>.sh
+      4. inner runner script at ~/.shared/roll/loop/run-<slug>-inner.sh
+    """
+    # 1. Env var
+    env_proj = os.environ.get("ROLL_MAIN_PROJECT", "").strip()
+    if env_proj and Path(env_proj).is_dir():
+        return Path(env_proj)
+
+    # 2. macOS launchd plist
+    if sys.platform == "darwin":
+        plist = Path.home() / "Library" / "LaunchAgents" / f"com.roll.loop.{slug}.plist"
+        if plist.exists():
+            try:
+                text = plist.read_text(errors="ignore")
+                m = re.search(
+                    r"<key>WorkingDirectory</key>\s*<string>([^<]+)</string>",
+                    text
+                )
+                if m:
+                    proj = Path(m.group(1))
+                    if proj.is_dir():
+                        return proj
+            except Exception:
+                pass
+
+    # 3. crontab
+    try:
+        cron_out = subprocess.check_output(
+            ["crontab", "-l"], stderr=subprocess.DEVNULL, text=True
+        )
+        for line in cron_out.splitlines():
+            if f"run-{slug}.sh" in line:
+                # Match: cd "<path>"
+                m = re.search(r'cd\s+"([^"]+)"', line)
+                if m:
+                    proj = Path(m.group(1))
+                    if proj.is_dir():
+                        return proj
+    except Exception:
+        pass
+
+    # 4. Inner runner script (grep for ROLL_MAIN_PROJECT=)
+    inner_script = shared_root() / "loop" / f"run-{slug}-inner.sh"
+    if inner_script.exists():
+        try:
+            text = inner_script.read_text(errors="ignore")
+            m = re.search(r'export ROLL_MAIN_PROJECT="([^"]+)"', text)
+            if m:
+                proj = Path(m.group(1))
+                if proj.is_dir():
+                    return proj
+        except Exception:
+            pass
+
+    return None
+
+
+def _loop_runtime_dir_py(slug: str) -> Optional[Path]:
+    """Mirror bin/roll's _loop_runtime_dir: return <project>/.roll/loop."""
+    proj = _resolve_project_path(slug)
+    if proj is None:
+        return None
+    return proj / ".roll" / "loop"
+
 # ════════════════════════════════════════════════════════════════════════════
 # Loaders
 # ════════════════════════════════════════════════════════════════════════════
 def load_events(slug: str, days: int) -> List[Dict[str, Any]]:
-    # US-LOOP-023: read the head NDJSON plus its rotated siblings .1..4.
-    # bin/roll rotates events-<slug>.ndjson at 10MB keeping 4 archives; without
-    # this loop the dashboard silently dropped any cycle whose events landed in
-    # a rotated file (the "永久留存" promise of US-LOOP-004 only held on disk).
-    head = shared_root() / "loop" / f"events-{slug}.ndjson"
-    candidates = [head] + [head.with_suffix(f".ndjson.{i}") for i in range(1, 5)]
+    # FIX-137: read from project-local .roll/loop/events.ndjson first
+    # (mirrors _loop_event writer), fall back to shared events-<slug>.ndjson
+    # for historical data that hasn't been migrated yet.
+    candidates: List[Path] = []
+
+    # Primary: project-local (same path as _loop_event writer, US-LOOP-020)
+    rt_dir = _loop_runtime_dir_py(slug)
+    if rt_dir is not None:
+        head = rt_dir / "events.ndjson"
+        candidates.append(head)
+        candidates.extend(head.with_suffix(f".ndjson.{i}") for i in range(1, 5))
+
+    # Fallback: shared (old data pre-US-LOOP-020, migration not yet done)
+    shared_head = shared_root() / "loop" / f"events-{slug}.ndjson"
+    candidates.append(shared_head)
+    candidates.extend(shared_head.with_suffix(f".ndjson.{i}") for i in range(1, 5))
+
     existing = [p for p in candidates if p.exists()]
     if not existing:
         return []
@@ -171,8 +256,16 @@ _CRON_PAT = re.compile(
 )
 
 def load_cron_log(slug: str) -> List[Dict[str, Any]]:
-    """Return ordered list of cron entries with local HH:MM:SS + extracted fields."""
-    path = shared_root() / "loop" / f"cron-{slug}.log"
+    """Return ordered list of cron entries with local HH:MM:SS + extracted fields.
+
+    FIX-137: checks project-local .roll/loop/cron.log first, falls back to
+    shared cron-<slug>.log."""
+    # Primary: project-local
+    rt_dir = _loop_runtime_dir_py(slug)
+    path = (rt_dir / "cron.log") if rt_dir is not None else None
+    if path is None or not path.exists():
+        # Fallback: shared
+        path = shared_root() / "loop" / f"cron-{slug}.log"
     if not path.exists():
         return []
     out: List[Dict[str, Any]] = []
@@ -193,8 +286,16 @@ def load_cron_log(slug: str) -> List[Dict[str, Any]]:
     return out
 
 def load_state(slug: str) -> Dict[str, str]:
-    """Tiny YAML reader — only the flat keys bin/roll writes."""
-    path = shared_root() / "loop" / f"state-{slug}.yaml"
+    """Tiny YAML reader — only the flat keys bin/roll writes.
+
+    FIX-137: checks project-local .roll/loop/state.yaml first, falls back to
+    shared state-<slug>.yaml."""
+    # Primary: project-local
+    rt_dir = _loop_runtime_dir_py(slug)
+    path = (rt_dir / "state.yaml") if rt_dir is not None else None
+    if path is None or not path.exists():
+        # Fallback: shared
+        path = shared_root() / "loop" / f"state-{slug}.yaml"
     if not path.exists():
         return {}
     out: Dict[str, str] = {}
@@ -564,10 +665,18 @@ def repair_orphan_cycles_from_git(cycles: List[Dict[str, Any]], git_merges: Dict
 
 def load_runs(slug: str) -> Dict[str, Dict[str, Any]]:
     """Map run_id → run row for the current project (filters out other slugs
-    sharing ~/.shared/roll/loop/runs.jsonl). Lenient slug matching salvages
-    entries written under buggy slugs (FIX-053): the bare project basename
-    (e.g. 'Roll') or worktree paths (e.g. '{slug}-cycle-XXX')."""
-    path = shared_root() / "loop" / "runs.jsonl"
+    sharing runs.jsonl). Lenient slug matching salvages entries written under
+    buggy slugs (FIX-053): the bare project basename (e.g. 'Roll') or worktree
+    paths (e.g. '{slug}-cycle-XXX').
+
+    FIX-137: reads from project-local .roll/loop/runs.jsonl first, falls back
+    to shared runs.jsonl."""
+    # Primary: project-local
+    rt_dir = _loop_runtime_dir_py(slug)
+    path = (rt_dir / "runs.jsonl") if rt_dir is not None else None
+    if path is None or not path.exists():
+        # Fallback: shared (cross-project)
+        path = shared_root() / "loop" / "runs.jsonl"
     if not path.exists():
         return {}
     base = slug.split("-")[0]  # 'Roll-a43d1b' → 'Roll'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seanyao/roll",
-  "version": "2026.529.3",
+  "version": "2026.529.5",
   "description": "Roll — Roll out features with AI agents",
   "scripts": {
     "test": "bash tests/run.sh"

package/skills/roll-doc/SKILL.md

@@ -217,6 +217,61 @@ detection rule and a target output file. Skip any topic whose target file alread
 | Agent 入口 (AGENTS.md) | Project root has no `AGENTS.md` AND `src/` (or equivalent source root) has ≥ 3 subdirectories | `AGENTS.md` |
 | 高引用目录 | Directory imported by ≥ 5 other source files, even if directory itself has < 3 source files | `<dir>/README.md` |
 
+#### Data Flow / Import Chain Tracing
+
+**Entry point selection:** start from entry files — any file matching patterns:
+`bin/*`, `cmd/**/*`, `main.*` (e.g. `main.ts`, `main.py`), `index.*` (e.g. `index.ts`, `index.jsx`),
+`App.*`, `server.*`. Exclude `node_modules/`, `dist/`, `build/`, test files (`*.test.*`, `*.spec.*`, `tests/`).
+
+**Chain construction:**
+1. For each entry file, read its imports from the symbol table's `imports` field.
+2. Recursively follow each imported file to its own imports, building a directed call graph.
+3. Stop at leaf nodes — files that import nothing or whose imports all point to:
+   - External packages (node_modules / stdlib / third-party)
+   - Already-visited nodes (cycle termination)
+4. Each distinct path from an entry file to a leaf is one call chain.
+
+**Threshold (cross-directory filter):**
+A call chain is valid for inclusion only if it spans **≥ 3 distinct source directories**.
+Count based on the unique parent directories of files in the chain:
+  `src/cli/main.ts → src/commands/build.ts → lib/utils/fs.ts` = 3 directories ✅
+  `src/cli/main.ts → src/cli/config.ts → lib/utils/fs.ts` = 2 directories ❌
+If no chain meets the ≥ 3 directory threshold, skip generation entirely (no empty `docs/data-flows.md`).
+
+**Output document structure** (`docs/data-flows.md`):
+
+```markdown
+> **Draft** — auto-generated by roll-doc on YYYY-MM-DD. Review before treating as authoritative.
+
+# Data Flows
+
+## Flow: {short descriptive name from entry file purpose}
+
+**Entry point:** `{entry_file}:{line}`
+**Directories spanned:** N ({comma-separated list})
+
+### Complete Call Chain
+
+{entry_file}
+  → import {symbol} from "{file}" ({line})
+    → import {symbol} from "{file}" ({line})
+      → ... (leaf node)
+
+### Files Involved
+
+| Step | File:Line | Function / Method |
+|------|-----------|-------------------|
+| 1 | `path/to/file:12` | `functionName` |
+| 2 | `path/to/file:34` | `otherFunction` |
+| ... | ... | ... |
+```
+
+- Sort flows by number of directories spanned, descending (widest cross-cutting flow first).
+- If an entry file produces multiple distinct call chains, list each one as a separate flow entry.
+- `file:line` annotations must come from actual symbol table records — do not fabricate.
+
+**Idempotency:** skip (do not overwrite) if `docs/data-flows.md` already exists, unless `--force`.
+
 ### Step 3 — Source Annotations
 
 Every topic document generated in Step 2 must cite `file:line` for each claim (function call,

package/skills/roll-loop/SKILL.md

@@ -344,8 +344,12 @@ After each item completes:
 
    **Path B — heal exhausted (≥`ROLL_LOOP_HEAL_MAX`, default 2) or disabled (`ROLL_LOOP_NO_HEAL=1`) (exit 1):**
 
-   1. Keep story as ✅ Done — commits are already on main; CI red is a follow-up
-      problem, not a story failure.
+   1. Do NOT force ✅ Done here. CI red means the PR will not merge, and
+      FIX-140's merge gate (in `bin/roll`, after `publish_wait_merge`) is the
+      single authority on final status: if the PR actually merges, the story
+      stays ✅ Done; if it does not merge, the gate reverts it ✅ Done → 📋 Todo
+      so BACKLOG never shows a false Done for code that isn't on main. (FIX-141
+      then stops the next cycle re-opening a duplicate PR while this one is open.)
    2. Write ALERT to `~/.shared/roll/loop/ALERT-<slug>.md` with:
       - story ID, time, commit SHA
       - heal attempts made (read `heal_count:` from `state-<slug>.yaml`)