@seanyao/roll 2026.517.2 → 2026.517.4

package/lib/loop-fmt.py

@@ -1,180 +1,329 @@
 #!/usr/bin/env python3
 """
-loop-fmt.py — stream-json → human-readable formatter for roll loop tmux output.
+loop-fmt.py — 3-tier stream-json → tmux formatter for roll loop.
 
-Reads stream-json lines from stdin, emits colored, human-readable events.
-Skips noise (system/init, hook_started, rate_limit_event) and abbreviates
-tool results so the window stays readable.
-
-Color codes: no external deps, plain ANSI.
+Tier 3 (suppressed): init, thinking, Read/Glob/Grep, non-error results, plain Bash
+Tier 2 (muted):      Edit/Write → ✏ path
+Tier 1 (signal):     tcr commit, story skill, peer verdict, ci gate, pr merge, errors
 """
-
 import sys
 import json
 import re
-import textwrap
-
-# ANSI colors
-CYAN    = "\033[36m"
-GREEN   = "\033[32m"
-YELLOW  = "\033[33m"
-RED     = "\033[31m"
-GRAY    = "\033[90m"
-BOLD    = "\033[1m"
-RESET   = "\033[0m"
-DIM     = "\033[2m"
-
-SKIP_SUBTYPES = {"hook_started", "hook_response", "hook_stop_hook_execution",
-                 "hook_stop_hook_active_hooks_ran"}
-
-def trunc(s, n=120):
+import os
+import threading
+import time
+from datetime import datetime, timezone
+
+_SPIN_ENABLED = os.environ.get("LOOP_FMT_NO_SPIN", "0") != "1"
+SPIN_FRAMES   = "⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏"
+
+DARK_GRAY = "\033[90m"
+CYAN      = "\033[36m"
+WHITE     = "\033[97m"
+GREEN     = "\033[32m"
+RED       = "\033[31m"
+YELLOW    = "\033[33m"
+RESET     = "\033[0m"
+
+
+class Spinner:
+    """Animated wait indicator for long-running operations.
+
+    In production (LOOP_FMT_NO_SPIN=0): background thread writes frames using \\r.
+    In test mode  (LOOP_FMT_NO_SPIN=1): writes a static ⏳ line to stdout instead.
+    """
+    def __init__(self):
+        self._thread  = None
+        self._running = False
+        self._label   = ""
+        self._lock    = threading.Lock()
+
+    @property
+    def active(self):
+        return self._running
+
+    def start(self, label):
+        with self._lock:
+            if self._running:
+                self._label = label  # update without restart
+                return
+            self._label   = label
+            self._running = True
+        if _SPIN_ENABLED:
+            self._thread = threading.Thread(target=self._run, daemon=True)
+            self._thread.start()
+        else:
+            sys.stdout.write(f"  {YELLOW}⏳ {label}...{RESET}\n")
+            sys.stdout.flush()
+
+    def stop(self):
+        with self._lock:
+            was_running   = self._running
+            self._running = False
+        if self._thread:
+            self._thread.join(timeout=0.3)
+            self._thread = None
+        if _SPIN_ENABLED and was_running:
+            sys.stdout.write(f"\r{' ' * 60}\r")
+            sys.stdout.flush()
+
+    def _run(self):
+        i = 0
+        while self._running:
+            with self._lock:
+                label = self._label
+            frame = SPIN_FRAMES[i % len(SPIN_FRAMES)]
+            sys.stdout.write(f"\r  {YELLOW}{frame} {label}...{RESET}")
+            sys.stdout.flush()
+            time.sleep(0.12)
+            i += 1
+        sys.stdout.write(f"\r{' ' * 60}\r")
+        sys.stdout.flush()
+
+SUPPRESS_TOOLS = {"Read", "Glob", "Grep", "ReadMcpResourceTool", "ListMcpResourcesTool",
+                  "WebFetch", "WebSearch", "TaskCreate", "TaskGet", "TaskList",
+                  "TaskUpdate", "TaskOutput", "TaskStop"}
+
+def now_hms():
+    return datetime.now(timezone.utc).strftime("%H:%M:%S")
+
+def trunc(s, n=60):
     s = str(s).replace("\n", " ").strip()
     return s[:n] + "…" if len(s) > n else s
 
-def fmt_tool_input(name, inp):
-    if not isinstance(inp, dict):
-        return trunc(str(inp), 80)
-    if name == "Bash":
-        cmd = inp.get("command", "")
-        # show first non-empty line
-        lines = [l.strip() for l in cmd.splitlines() if l.strip()]
-        return trunc(lines[0] if lines else cmd, 100)
-    if name in ("Read", "Write", "Edit"):
-        path = inp.get("file_path", inp.get("path", ""))
-        extra = ""
-        if name == "Edit":
-            old = inp.get("old_string", "")
-            extra = f"  ({trunc(old, 40)})"
-        return f"{path}{extra}"
-    if name in ("Glob", "Grep"):
-        return trunc(inp.get("pattern", inp.get("query", str(inp))), 80)
-    if name == "Skill":
-        return inp.get("skill", "") + (" " + inp.get("args", "") if inp.get("args") else "")
-    if name == "Agent":
-        return trunc(inp.get("description", str(inp)), 80)
-    return trunc(json.dumps(inp, ensure_ascii=False), 80)
-
-def fmt_tool_result(content):
-    if isinstance(content, list):
-        parts = []
-        for c in content:
-            if isinstance(c, dict):
-                t = c.get("type", "")
-                if t == "text":
-                    parts.append(c.get("text", ""))
-                elif t == "image":
-                    parts.append("[image]")
-            else:
-                parts.append(str(c))
-        text = " ".join(parts)
-    else:
-        text = str(content) if content is not None else ""
-    # strip ansi for length check
-    clean = re.sub(r'\033\[[0-9;]*m', '', text)
-    lines = [l for l in clean.splitlines() if l.strip()]
-    if not lines:
-        return "(empty)"
-    # show first 3 lines, trim long lines
-    out = []
-    for l in lines[:3]:
-        out.append("  " + trunc(l, 100))
-    if len(lines) > 3:
-        out.append(f"  {DIM}… ({len(lines)-3} more lines){RESET}")
-    return "\n".join(out)
-
-def process_line(line):
-    line = line.rstrip()
-    if not line:
-        return
-    try:
-        ev = json.loads(line)
-    except json.JSONDecodeError:
-        # plain text passthrough
-        print(line)
-        return
-
-    etype = ev.get("type", "")
-
-    # ── system events ──────────────────────────────────────────────
-    if etype == "system":
-        subtype = ev.get("subtype", "")
-        if subtype in SKIP_SUBTYPES:
+def step(category, label, detail="", ok=True):
+    cat_color = CYAN
+    label_color = GREEN if ok and category in ("ci", "pr") else (RED if not ok else WHITE)
+    arrow = f"{DARK_GRAY}→{RESET}"
+    cat   = f"  {cat_color}{category:<6}{RESET}"
+    lbl   = f"  {label_color}{label:<14}{RESET}"
+    det   = f"  {DARK_GRAY}{detail}{RESET}" if detail else ""
+    return f"{arrow}{cat}{lbl}{det}"
+
+def stamp(text, muted=False):
+    ts = f"{DARK_GRAY}{now_hms()}{RESET}"
+    body = f"{DARK_GRAY}{text}{RESET}" if muted else text
+    return f"{ts}  {body}"
+
+class LoopFmt:
+    def __init__(self):
+        self.last_bash_cmd   = ""
+        self.tcr_count       = 0
+        self.last_test_count = None
+        self.cycle_num       = None
+        self.pending_commit  = False
+        self.pending_pr      = False
+        self.pending_ci      = False
+        self.pending_story   = False
+        self.spinner         = Spinner()
+
+    def _extract_cycle_num(self, text):
+        m = re.search(r'cycle[#\s]+(\d+)', text, re.IGNORECASE)
+        return m.group(1) if m else "?"
+
+    def process(self, line):
+        line = line.rstrip()
+        if not line:
             return
-        if subtype == "init":
-            model = ev.get("model", "")
-            tools = ev.get("tools", [])
-            tool_list = ", ".join(tools[:6])
-            if len(tools) > 6:
-                tool_list += f" +{len(tools)-6}"
-            print(f"{DIM}[init] model={model}  tools={tool_list}{RESET}")
+
+        # Plain text passthrough
+        try:
+            ev = json.loads(line)
+        except json.JSONDecodeError:
+            self._handle_plain(line)
             return
-        # unknown system — show raw briefly
-        print(f"{DIM}[sys/{subtype}]{RESET}")
-        return
 
-    # ── rate limit ────────────────────────────────────────────────
-    if etype == "rate_limit_event":
-        return
+        etype = ev.get("type", "")
+        if etype == "system":
+            return  # Tier 3: suppress all system events
+        if etype == "assistant":
+            self._handle_assistant(ev)
+        elif etype == "user":
+            self._handle_user(ev)
+        elif etype == "result":
+            self._handle_result(ev)
+        # All other types: suppress
+
+    def _handle_plain(self, line):
+        # [loop] cycle N: ... → Tier 1 stamp
+        m = re.search(r'\[loop\]\s+cycle\s+(\d+)[:\s]', line)
+        if m:
+            self.cycle_num = m.group(1)
+            self.tcr_count = 0
+            print(stamp(f"cycle #{self.cycle_num} — picking story"))
+            return
+        # Other plain text: suppress
 
-    # ── assistant ────────────────────────────────────────────────
-    if etype == "assistant":
+    def _handle_assistant(self, ev):
         msg = ev.get("message", {})
         for blk in msg.get("content", []):
             btype = blk.get("type", "")
-            if btype == "tool_use":
-                name = blk.get("name", "?")
-                inp  = blk.get("input", {})
-                summary = fmt_tool_input(name, inp)
-                print(f"{CYAN}→ {BOLD}{name}{RESET}{CYAN}: {summary}{RESET}")
+            if btype == "thinking":
+                return  # Tier 3
             elif btype == "text":
-                text = blk.get("text", "").strip()
-                if text:
-                    # wrap long text
-                    for l in textwrap.wrap(text, 120):
-                        print(f"{GREEN}{l}{RESET}")
-            elif btype == "thinking":
-                thought = blk.get("thinking", "").strip()
-                if thought:
-                    first = trunc(thought, 80)
-                    print(f"{DIM}[thinking] {first}{RESET}")
-        return
-
-    # ── user (tool results) ───────────────────────────────────────
-    if etype == "user":
+                self._handle_text(blk.get("text", ""))
+            elif btype == "tool_use":
+                self._handle_tool_use(blk)
+
+    def _handle_text(self, text):
+        text = text.strip()
+        if not text:
+            return
+        # Peer verdict detection
+        for verdict in ("AGREE", "REFINE", "OBJECT", "ESCALATE"):
+            if verdict in text:
+                m = re.search(r'round\s+(\d+)[/\\](\d+)', text, re.IGNORECASE)
+                round_str = f"round {m.group(1)}/{m.group(2)}" if m else "round ?"
+                # agent names — look for common patterns
+                agents = "claude → peer"
+                m2 = re.search(r'(\w+)\s*→\s*(\w+)', text)
+                if m2:
+                    agents = f"{m2.group(1)} → {m2.group(2)}"
+                print(step("peer", agents, f"{round_str} · {verdict}"))
+                return
+        # All other text: Tier 3, suppress
+
+    def _handle_tool_use(self, blk):
+        name = blk.get("name", "")
+        inp  = blk.get("input", {})
+
+        if name in SUPPRESS_TOOLS:
+            return  # Tier 3
+
+        if name in ("Edit", "Write"):
+            path = inp.get("file_path") or inp.get("path", "")
+            print(f"  {DARK_GRAY}✏ {path}{RESET}")
+            return  # Tier 2
+
+        if name == "Bash":
+            cmd = inp.get("command", "")
+            first_line = next((l.strip() for l in cmd.splitlines() if l.strip()), cmd)
+            self.last_bash_cmd = first_line
+            if re.search(r'git commit.*tcr:', cmd):
+                self.pending_commit = True
+            elif re.search(r'gh pr (create|merge)', cmd):
+                self.pending_pr = True
+                self.spinner.start("merging PR")
+            elif re.search(r'(roll ci|npm run ci|_ci_wait|ci:local)', cmd):
+                self.pending_ci = True
+                self.spinner.start("waiting for CI")
+            return  # Wait for result
+
+        if name == "Skill":
+            skill = inp.get("skill", "")
+            args  = inp.get("args", "").strip()
+            if skill in ("roll-build", "roll-fix"):
+                us_id = args.split()[0] if args else "?"
+                print()
+                print(stamp(f"cycle #{self.cycle_num or '?'} — picking story"))
+                print(step("story", us_id, trunc(args, 60)))
+                self.pending_story = True
+                self.spinner.start("executing story")
+            return
+
+        # All other tools (Agent, ToolSearch, etc.): suppress
+
+    def _handle_user(self, ev):
         msg = ev.get("message", {})
         for blk in msg.get("content", []):
-            if blk.get("type") == "tool_result":
-                is_err = blk.get("is_error", False)
-                content = blk.get("content", "")
-                result_text = fmt_tool_result(content)
-                prefix = f"{RED}  ✗{RESET}" if is_err else f"{GRAY}  ↩{RESET}"
-                print(f"{prefix} {result_text}")
-        return
-
-    # ── result (final) ───────────────────────────────────────────
-    if etype == "result":
+            if blk.get("type") != "tool_result":
+                continue
+            is_err  = blk.get("is_error", False)
+            content = blk.get("content", "")
+            text    = self._extract_text(content)
+
+            # Scan for test count (bats ok N pattern)
+            m = re.search(r'\bok\s+(\d+)', text)
+            if m:
+                self.last_test_count = int(m.group(1))
+
+            if is_err:
+                tool_name = "tool"
+                lines = [l for l in text.splitlines() if l.strip()][:3]
+                detail = " | ".join(lines)
+                print(step("error", tool_name, trunc(detail, 80), ok=False))
+                self.pending_commit = self.pending_pr = self.pending_ci = False
+                return
+
+            if self.pending_commit:
+                self.pending_commit = False
+                # Extract hash and message from git commit output: [branch hash] msg
+                m = re.search(r'\[[\w/\-]+ ([0-9a-f]{7,})\]\s*tcr:\s*(.+)', text)
+                if m:
+                    commit_hash = m.group(1)[:7]
+                    commit_msg  = m.group(2).strip()
+                    self.tcr_count += 1
+                    test_part = f" · {self.last_test_count} tests" if self.last_test_count else ""
+                    print(step("tcr", commit_hash, f"{commit_msg}{test_part}"))
+                return
+
+            if self.pending_story:
+                self.pending_story = False
+                self.spinner.stop()
+                return  # story result content suppressed; TCR events showed the work
+
+            if self.pending_pr:
+                self.spinner.stop()
+                self.pending_pr = False
+                m = re.search(r'#(\d+)', text)
+                if m:
+                    pr_num = f"#{m.group(1)}"
+                    branch = re.search(r'loop/[\w\-]+', self.last_bash_cmd)
+                    branch_str = branch.group(0) if branch else ""
+                    detail = f"auto-merged · {branch_str}" if branch_str else "auto-merged"
+                    print(step("pr", pr_num, detail, ok=True))
+                return
+
+            if self.pending_ci:
+                self.spinner.stop()
+                self.pending_ci = False
+                has_green = re.search(r'(green|pass|success|all tests)', text, re.IGNORECASE)
+                has_red   = re.search(r'(red|fail|error)', text, re.IGNORECASE)
+                m_dur  = re.search(r'(\d+(?:\.\d+)?)\s*s\b', text)
+                m_test = re.search(r'(\d+)\s+tests?', text)
+                dur_str  = f"{m_dur.group(1)}s" if m_dur else ""
+                test_str = f"{m_test.group(1)} tests" if m_test else (f"{self.last_test_count} tests" if self.last_test_count else "")
+                detail   = " · ".join(filter(None, [dur_str, test_str]))
+                if has_green and not has_red:
+                    print(step("ci", "green", detail, ok=True))
+                else:
+                    print(step("ci", "red", detail, ok=False))
+                return
+
+            # Non-matching result: suppress (Tier 3)
+
+    def _extract_text(self, content):
+        if isinstance(content, str):
+            return content
+        if isinstance(content, list):
+            parts = []
+            for c in content:
+                if isinstance(c, dict) and c.get("type") == "text":
+                    parts.append(c.get("text", ""))
+            return "\n".join(parts)
+        return str(content) if content else ""
+
+    def _handle_result(self, ev):
         dur_ms   = ev.get("duration_ms", 0)
         cost_usd = ev.get("total_cost_usd", 0)
-        turns    = ev.get("num_turns", "?")
         dur_s    = dur_ms / 1000
-        cost_str = f"${cost_usd:.4f}" if cost_usd else ""
+        cost_str = f"${cost_usd:.2f}" if cost_usd else ""
+        tcr_str  = f"{self.tcr_count} tcr" if self.tcr_count else ""
+        parts    = [p for p in [tcr_str, f"{dur_s:.0f}s", cost_str] if p]
+        detail   = " · ".join(parts)
         subtype  = ev.get("subtype", "")
         if subtype == "error_max_turns":
-            print(f"{RED}✗ max turns reached  {dur_s:.1f}s{RESET}")
+            print(step("error", "max-turns", f"{dur_s:.0f}s", ok=False))
         else:
-            cost_part = f"  {YELLOW}{cost_str}{RESET}" if cost_str else ""
-            print(f"\n{GREEN}{BOLD}✓ done{RESET}  {dur_s:.1f}s  {GRAY}{turns} turns{RESET}{cost_part}")
-        return
-
-    # ── fallback ────────────────────────────────────────────────
-    print(f"{DIM}{trunc(line, 160)}{RESET}")
+            cycle_str = f"cycle #{self.cycle_num}" if self.cycle_num else "cycle done"
+            print(stamp(f"{cycle_str} — done · {detail}" if detail else f"{cycle_str} — done", muted=True))
 
 
 def main():
+    fmt = LoopFmt()
     for line in sys.stdin:
-        process_line(line)
+        fmt.process(line)
         sys.stdout.flush()
 
-
 if __name__ == "__main__":
     main()

package/package.json

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

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

@@ -416,6 +416,10 @@ prompt 会包含：
   （即使没有 deep doc 也要列）
 - Feature 名跟 `docs/features/<file>.md` 文件名一致时，加链接到该 md
 - 没有对应 deep doc 的 Feature，**只写 plain text 不加链接**
+- **Planning distinction（US-DOC-011）**：
+  - 该 Feature 下**所有** Story 均为 `📋 Todo` → 在描述末尾追加 `*(规划中)*`
+  - 只要有 **≥1 个** `✅ Done` Story → 正常展示，**不加**任何标记
+  - 一眼可见：规划中的 Feature 在每个 Epic 分组的末尾列出
 - 描述写 1 句话 **产品视角**：用户能用它做什么，避免实现细节
 - 分组用 BACKLOG 的 Epic 名，原序，不重排
 - Core Highlights 从所有 Features 里挑 3-5 个最能代表产品定位的，

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

@@ -127,6 +127,18 @@ find docs/ -maxdepth 1 -name '*.md' 2>/dev/null
 
 Flag any `.md` file directly in `docs/` root (allowed subdirs: `guide/`, `domain/`, `features/`, `practices/`, `briefs/`, `dream/`).
 
+**Check D — features.md Feature Coverage (US-DOC-009):**
+
+Dependency gate: skip when `docs/features.md` does not exist.
+
+Parse BACKLOG.md for all `### Feature: <name>` groups that contain ≥1 ✅ Done story. Parse `docs/features.md` for Feature names. If any Feature group with Done stories is absent from `docs/features.md`, the catalog is stale — flag as REFACTOR:
+
+```markdown
+| REFACTOR-XXX | features.md 功能目录落后于 BACKLOG，N 个已完成功能区未收录，用户无法通过产品目录发现这些功能 — flagged by dream YYYY-MM-DD | 📋 Todo |
+```
+
+The catalog is auto-updated by `scripts/release.sh` at release time (Section 8 of roll-.changelog). Between releases, this check surfaces the coverage gap so it isn't silently skipped.
+
 **REFACTOR entry format for doc findings:**
 
 ```markdown
@@ -137,7 +149,8 @@ Flag any `.md` file directly in `docs/` root (allowed subdirs: `guide/`, `domain
 
 ```markdown
 ## 文档覆盖度
-{发现内容 或 "文档结构符合规范，无缺口。"}
+- features.md 功能区覆盖：{N}/{M} 个已完成功能区已收录（缺失：{列表 或 "无"}）
+{其他发现内容 或 "文档结构符合规范，无缺口。"}
 ```
 
 ### Scan 6 — 文档新鲜度 (Doc Freshness)

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

@@ -45,7 +45,9 @@ $roll-.review unstaged
 $roll-.review files src/utils.ts
 ```
 
-## Review Dimensions (6 Core Dimensions)
+## Review Dimensions (7 Core Dimensions)
+
+Original 6 dimensions plus Reuse (added in REFACTOR-022, simplify three-axis integration):
 
 ```
 ┌─────────────────────────────────────────────────────────┐
@@ -54,13 +56,42 @@ $roll-.review files src/utils.ts
 │  ✅ Correctness     - Logic is correct, no bugs         │
 │  ✅ Security        - No vulnerabilities, input valid.  │
 │  ✅ Maintainability - Clear naming, sound structure     │
+│     Quality anti-patterns (check each):                 │
+│       □ Redundant state / cached values that could be   │
+│         derived directly                                │
+│       □ Parameter sprawl — new param vs. restructure    │
+│       □ Copy-paste with slight variation (near-dup)     │
+│       □ Leaky abstraction — exposes internal details    │
+│       □ Stringly-typed — raw string where constant      │
+│         / enum exists                                   │
+│       □ Unnecessary JSX nesting (no layout value)       │
+│       □ Nested conditionals ≥3 deep (ternary chains,    │
+│         nested if/else) — flatten with early return     │
+│       □ Unnecessary comments explaining WHAT            │
 │  ✅ Performance     - No performance pitfalls           │
+│     Efficiency anti-patterns (check each):              │
+│       □ Redundant computation / repeated file read /    │
+│         duplicate API call / N+1 pattern                │
+│       □ Missed concurrency — independent ops sequential │
+│       □ Hot-path bloat — blocking work in startup or    │
+│         per-request path                                │
+│       □ Loop no-op updates — missing change-detection   │
+│         guard                                           │
+│       □ TOCTOU existence pre-check — operate directly + │
+│         handle error instead                            │
+│       □ Memory — unbounded structures / missing cleanup │
+│       □ Overly broad op — reading full file for a slice │
 │  ✅ Testability     - Easy to test, edge cases covered  │
 │  ✅ Scope           - Focused on current task, no       │
 │                       unrelated changes                 │
+│  ✅ Reuse           - No new code duplicating existing  │
+│     □ New function duplicates existing utility/helper   │
+│     □ Inline logic replaceable by existing tool         │
 └─────────────────────────────────────────────────────────┘
 ```
 
+**Usage in TCR**: Each micro-step review is a lightweight self-check against this checklist — no sub-agents, zero extra token cost. The three-axis deep review with parallel agents runs once per Story in `$roll-build` Phase 7.
+
 ## Severity Levels and Decisions
 
 | Level | Definition | Decision |