@seanyao/roll 2026.528.2 → 2026.529.2

package/lib/README.md

@@ -0,0 +1,42 @@
+> **Draft** — auto-generated by roll-doc on 2026-05-28. Review before treating as authoritative.
+
+# lib/ — Python helpers and i18n runtime
+
+Python scripts and shell libraries that `bin/roll` delegates to for rendering-heavy or data-processing tasks.
+
+## Key files
+
+| File | Purpose |
+|------|---------|
+| `roll-loop-status.py` | Renders the `roll loop status` health dashboard — reads cycle event NDJSON, computes per-cycle rows, daily rollups, and phase-tracing breakdown |
+| `roll-loop-story.py` | Per-story rollup: aggregates cycles, tokens, cost, and PR outcomes for `roll loop story <ID>` |
+| `roll-status.py` | Renders the `roll status` one-screen sync health view |
+| `roll-init.py` | Init-flow helpers called by `roll init` |
+| `roll-setup.py` | Setup-flow helpers (convention sync, tool config write) |
+| `roll-brief.py` | Brief generation: reads cycle records and produces the feature brief |
+| `roll-backlog.py` | Backlog read/write helpers |
+| `roll-peer.py` | Peer review coordination helpers |
+| `roll-help.py` | Renders `roll --help` output |
+| `roll-plan-validate.py` | Validates plan files before story execution |
+| `model_prices.py` | List-price table for AI model API pricing (per MTok, native currency) |
+| `prices_fetcher.py` | Fetches fresh price snapshots from vendor APIs |
+| `roll_render.py` | Shared rendering utilities (tables, color, formatting) |
+| `loop-fmt.py` | Loop log formatter (ANSI-strip, timestamp alignment) |
+| `loop_unstick.py` | Diagnostic: detects and unsticks hung loop state |
+| `backfill-pi-usage.py` | Backfills pi/deepseek token and cost data into existing cycle records |
+| `changelog_audit.py` | Audits CHANGELOG.md against backlog entries |
+| `i18n.sh` | Shell wrapper that delegates i18n string lookups to `lib/i18n/` |
+| `slides-render.py` | Renders `.deck.md` → HTML slides |
+| `slides-validate.py` | Validates deck file syntax and asset references |
+
+## Sub-directories
+
+- `agent_usage/` — token-usage capture and cost attribution per agent invocation
+- `i18n/` — localized string tables for all CLI output (EN + ZH)
+- `prices/` — price snapshot JSON files (per-vendor, dated)
+- `slides/` — slide component library for `roll deck`
+
+## Dependencies
+
+Imported by `bin/roll` via subprocess calls (`python3 lib/<script>.py`).
+No third-party pip dependencies — standard library only (json, sys, os, re, datetime).

package/lib/agent_routes_lint.py

@@ -0,0 +1,203 @@
+#!/usr/bin/env python3
+"""Lint .roll/agent-routes.yaml against schema v1 (US-AGENT-002).
+
+Usage:
+  agent_routes_lint.py <path>
+
+Exit 0 when valid, exit 1 with line-numbered errors on stderr otherwise.
+"""
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+try:
+    import yaml
+except ImportError:
+    print("agent-routes lint: PyYAML not installed", file=sys.stderr)
+    sys.exit(2)
+
+
+VALID_TYPES = {"FIX", "US", "REFACTOR"}
+VALID_RISK = {"low", "medium", "high"}
+
+
+class LintError:
+    __slots__ = ("line", "msg")
+
+    def __init__(self, line: int, msg: str) -> None:
+        self.line = line
+        self.msg = msg
+
+    def __str__(self) -> str:
+        # Format: "line N: <message>" — match test regex `line[[:space:]]+[0-9]+`
+        if self.line > 0:
+            return f"line {self.line}: {self.msg}"
+        return self.msg
+
+
+def _node_line(node) -> int:
+    """Return 1-based line number of a ruamel node, or 0 if unavailable."""
+    mark = getattr(node, "start_mark", None)
+    if mark is None:
+        return 0
+    return mark.line + 1
+
+
+def _scan(path: Path) -> list[LintError]:
+    """Load and validate the YAML file. Returns a list of LintError."""
+    errs: list[LintError] = []
+
+    try:
+        text = path.read_text()
+    except FileNotFoundError:
+        return [LintError(0, f"file not found: {path}")]
+
+    # Use safe loader with composer to get line info per top-level key.
+    try:
+        # Parse with composer to retain line marks.
+        loader = yaml.SafeLoader(text)
+        try:
+            node = loader.get_single_node()
+        finally:
+            loader.dispose()
+    except yaml.YAMLError as exc:
+        line = getattr(getattr(exc, "problem_mark", None), "line", -1)
+        return [LintError(line + 1 if line >= 0 else 0, f"YAML parse error: {exc}")]
+
+    if node is None:
+        return [LintError(0, "empty YAML document")]
+
+    if not isinstance(node, yaml.MappingNode):
+        return [LintError(_node_line(node), "top-level must be a mapping")]
+
+    # Walk top-level fields to capture line numbers.
+    top: dict[str, tuple[int, yaml.Node]] = {}
+    for key_node, value_node in node.value:
+        if isinstance(key_node, yaml.ScalarNode):
+            top[key_node.value] = (_node_line(key_node), value_node)
+
+    # --- schema field ---
+    if "schema" not in top:
+        errs.append(LintError(1, "missing required field `schema`"))
+    else:
+        schema_line, schema_val = top["schema"]
+        if not (isinstance(schema_val, yaml.ScalarNode) and schema_val.value == "v1"):
+            errs.append(LintError(schema_line, "field `schema` must be `v1`"))
+
+    # --- agents field ---
+    if "agents" not in top:
+        errs.append(LintError(1, "missing required field `agents`"))
+    else:
+        agents_line, agents_val = top["agents"]
+        if not isinstance(agents_val, yaml.MappingNode):
+            errs.append(LintError(agents_line, "field `agents` must be a mapping"))
+        else:
+            for agent_key, agent_val in agents_val.value:
+                if not isinstance(agent_key, yaml.ScalarNode):
+                    continue
+                name = agent_key.value
+                name_line = _node_line(agent_key)
+                _validate_agent(name, name_line, agent_val, errs)
+
+    # --- history (optional) ---
+    if "history" in top:
+        hist_line, hist_val = top["history"]
+        if not isinstance(hist_val, yaml.MappingNode):
+            errs.append(LintError(hist_line, "field `history` must be a mapping"))
+        else:
+            _validate_history(hist_val, errs)
+
+    return errs
+
+
+def _validate_agent(name: str, name_line: int, node: yaml.Node, errs: list[LintError]) -> None:
+    if not isinstance(node, yaml.MappingNode):
+        errs.append(LintError(name_line, f"agent `{name}` must be a mapping"))
+        return
+    fields: dict[str, tuple[int, yaml.Node]] = {}
+    for k, v in node.value:
+        if isinstance(k, yaml.ScalarNode):
+            fields[k.value] = (_node_line(k), v)
+
+    # types
+    if "types" not in fields:
+        errs.append(LintError(name_line, f"agent `{name}` missing `types`"))
+    else:
+        tl, tv = fields["types"]
+        if not isinstance(tv, yaml.SequenceNode):
+            errs.append(LintError(tl, f"agent `{name}`.types must be a list"))
+        else:
+            for item in tv.value:
+                if isinstance(item, yaml.ScalarNode) and item.value not in VALID_TYPES:
+                    errs.append(LintError(_node_line(item), f"agent `{name}`.types: invalid value `{item.value}` (expect one of FIX/US/REFACTOR)"))
+
+    # est_min
+    if "est_min" not in fields:
+        errs.append(LintError(name_line, f"agent `{name}` missing `est_min`"))
+    else:
+        el, ev = fields["est_min"]
+        if not isinstance(ev, yaml.MappingNode):
+            errs.append(LintError(el, f"agent `{name}`.est_min must be a mapping {{min, max}}"))
+        else:
+            est_fields = {k.value: v for k, v in ev.value if isinstance(k, yaml.ScalarNode)}
+            if "min" not in est_fields or "max" not in est_fields:
+                errs.append(LintError(el, f"agent `{name}`.est_min requires both `min` and `max`"))
+
+    # risk
+    if "risk" not in fields:
+        errs.append(LintError(name_line, f"agent `{name}` missing `risk`"))
+    else:
+        rl, rv = fields["risk"]
+        if not isinstance(rv, yaml.SequenceNode):
+            errs.append(LintError(rl, f"agent `{name}`.risk must be a list"))
+        else:
+            for item in rv.value:
+                if isinstance(item, yaml.ScalarNode) and item.value not in VALID_RISK:
+                    errs.append(LintError(_node_line(item), f"agent `{name}`.risk: invalid value `{item.value}` (expect low/medium/high)"))
+
+
+def _validate_history(node: yaml.MappingNode, errs: list[LintError]) -> None:
+    fields = {k.value: (_node_line(k), v) for k, v in node.value if isinstance(k, yaml.ScalarNode)}
+
+    if "window_cycles" in fields:
+        wl, wv = fields["window_cycles"]
+        if isinstance(wv, yaml.ScalarNode):
+            try:
+                n = int(wv.value)
+                if n < 0:
+                    errs.append(LintError(wl, "history.window_cycles must be >= 0 (0 disables history)"))
+            except ValueError:
+                errs.append(LintError(wl, "history.window_cycles must be an integer"))
+
+    if "prefer_threshold" in fields:
+        pl, pv = fields["prefer_threshold"]
+        if isinstance(pv, yaml.ScalarNode):
+            try:
+                f = float(pv.value)
+                if not (0.0 <= f <= 1.0):
+                    errs.append(LintError(pl, f"history.prefer_threshold must be in [0.0, 1.0], got {f}"))
+            except ValueError:
+                errs.append(LintError(pl, "history.prefer_threshold must be a number"))
+
+    if "cold_start_default" in fields:
+        cl, cv = fields["cold_start_default"]
+        if not isinstance(cv, yaml.ScalarNode):
+            errs.append(LintError(cl, "history.cold_start_default must be a string"))
+
+
+def main() -> int:
+    if len(sys.argv) != 2:
+        print("usage: agent_routes_lint.py <path>", file=sys.stderr)
+        return 2
+    path = Path(sys.argv[1])
+    errors = _scan(path)
+    if not errors:
+        return 0
+    for err in errors:
+        print(str(err), file=sys.stderr)
+    return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/lib/i18n/README.md

@@ -0,0 +1,54 @@
+> **Draft** — auto-generated by roll-doc on 2026-05-28. Review before treating as authoritative.
+
+# lib/i18n/ — Localized string tables
+
+All user-visible CLI output strings for both `en` and `zh` locales, organized by command domain.
+
+## Structure
+
+Each `.sh` file under `lib/i18n/` is a shell associative-array fragment exporting a `MSG_*` namespace:
+
+```
+lib/i18n/
+├── agent.sh          # roll agent use / install messages
+├── alert.sh          # ALERT lifecycle messages
+├── backlog.sh        # backlog read/write output
+├── brief.sh          # roll-brief generation output
+├── changelog.sh      # changelog sync messages
+├── ci.sh             # CI self-heal messages
+├── debug.sh          # roll debug diagnostics
+├── doctor.sh         # roll-doctor check output
+├── dream.sh          # roll-.dream scan output
+├── init.sh           # roll init setup messages
+├── lang.sh           # locale detection + ROLL_LANG resolution
+├── loop.sh           # roll loop subcommand output (largest file)
+├── migrate.sh        # roll migrate messages
+├── offboard.sh       # roll offboard output
+├── onboard.sh        # roll onboard / legacy-onboard output
+├── peer.sh           # roll peer review messages
+├── peer_help.sh      # peer --help text
+├── peer_reset.sh     # peer reset confirmation messages
+├── peer_status.sh    # peer status output
+├── prices_refresh.sh # prices refresh output
+└── skills/           # per-skill i18n overrides
+```
+
+## Locale selection
+
+`ROLL_LANG` env var controls which locale is active. Resolved by `lang.sh`:
+
+1. `ROLL_LANG` explicit → use it
+2. `LC_ALL` / `LANG` contains `zh` → `zh`
+3. Default → `en`
+
+Each `.sh` file branches on `ROLL_LANG` and exports the appropriate string set.
+
+## skills/
+
+Per-skill message overrides for `roll-build`, `roll-design`, `roll-fix`, `roll-loop`, `roll-onboard`. Same structure as top-level files — sourced after the base file to allow skill-specific overrides without editing shared strings.
+
+## Adding a new string
+
+1. Add the key to both `en` and `zh` branches in the appropriate domain file.
+2. Reference via `msg <KEY>` in `bin/roll` or the relevant skill.
+3. Never hardcode user-facing strings in `bin/roll` directly — always go through i18n.

package/lib/i18n/doctor.sh

@@ -29,3 +29,16 @@ _i18n_set en doctor.pr_event_without_zh "contributors get AI feedback on PR open
 _i18n_set zh doctor.pr_event_without_zh "PR 一开即触发 AI 评审。"
 _i18n_set en doctor.pr_event_secret "Then set the API key secret for your configured agent in GitHub repo settings."
 _i18n_set zh doctor.pr_event_secret "然后在 GitHub 仓库设置中添加你配置的 agent 对应的 API key secret。"
+
+_i18n_set en doctor.agent_detection "Agent detection"
+_i18n_set zh doctor.agent_detection "Agent 检测"
+_i18n_set en doctor.agent_installed "CLI on PATH"
+_i18n_set zh doctor.agent_installed "CLI 可用"
+_i18n_set en doctor.agent_missing "CLI not found"
+_i18n_set zh doctor.agent_missing "CLI 未安装"
+_i18n_set en doctor.agent_dir_exists "config dir exists"
+_i18n_set zh doctor.agent_dir_exists "配置目录存在"
+_i18n_set en doctor.agent_dir_missing "config dir missing"
+_i18n_set zh doctor.agent_dir_missing "配置目录不存在"
+_i18n_set en doctor.agent_primary_label "primary"
+_i18n_set zh doctor.agent_primary_label "默认"

package/lib/i18n/loop.sh

@@ -3,22 +3,22 @@ _i18n_set en loop.loop_already_enabled_for_this_project "Loop already enabled fo
 _i18n_set zh loop.loop_already_enabled_for_this_project "当前项目 loop 已启用"
 _i18n_set en loop.loop_enabled "Loop enabled"
 _i18n_set zh loop.loop_enabled "已启用"
-_i18n_set en loop.roll_loop_s_active_02d_00 "  • roll-loop   %s  active %02d:00–%02d:00  %s（"
-_i18n_set zh loop.roll_loop_s_active_02d_00 "窗口 %02d:00–%02d:00）\n"
-_i18n_set en loop.roll_dream_daily_at_02d_02d "  • roll-.dream daily at %02d:%02d"
-_i18n_set zh loop.roll_dream_daily_at_02d_02d "每天 %02d:%02d\n"
-_i18n_set en loop.roll_brief_daily_at_02d_02d "  • roll-brief  daily at %02d:%02d"
-_i18n_set zh loop.roll_brief_daily_at_02d_02d "每天 %02d:%02d\n"
+_i18n_set en loop.roll_loop_s_active_02d_00 "  • roll-loop   %s  active %02d:00–%02d:00  %s（窗口 %02d:00–%02d:00）"
+_i18n_set zh loop.roll_loop_s_active_02d_00 "  • roll-loop   %s  有效窗口 %02d:00–%02d:00  %s（active %02d:00–%02d:00）"
+_i18n_set en loop.roll_dream_daily_at_02d_02d "  • roll-.dream daily at %02d:%02d  每天 %02d:%02d"
+_i18n_set zh loop.roll_dream_daily_at_02d_02d "  • roll-.dream daily at %02d:%02d  每天 %02d:%02d"
+_i18n_set en loop.roll_brief_daily_at_02d_02d "  • roll-brief  daily at %02d:%02d  每天 %02d:%02d"
+_i18n_set zh loop.roll_brief_daily_at_02d_02d "  • roll-brief  daily at %02d:%02d  每天 %02d:%02d"
 _i18n_set en loop.loop_already_enabled_for_this_project_2 "Loop already enabled for this project"
 _i18n_set zh loop.loop_already_enabled_for_this_project_2 "当前项目 loop 已启用"
 _i18n_set en loop.loop_enabled_2 "Loop enabled"
 _i18n_set zh loop.loop_enabled_2 "已启用"
-_i18n_set en loop.roll_loop_s_active_02d_00_2 "  • roll-loop   %s  active %02d:00–%02d:00  %s（"
-_i18n_set zh loop.roll_loop_s_active_02d_00_2 "窗口 %02d:00–%02d:00）\n"
-_i18n_set en loop.roll_dream_daily_at_02d_02d_2 "  • roll-.dream daily at %02d:%02d"
-_i18n_set zh loop.roll_dream_daily_at_02d_02d_2 "每天 %02d:%02d\n"
-_i18n_set en loop.roll_brief_daily_at_02d_02d_2 "  • roll-brief  daily at %02d:%02d"
-_i18n_set zh loop.roll_brief_daily_at_02d_02d_2 "每天 %02d:%02d\n"
+_i18n_set en loop.roll_loop_s_active_02d_00_2 "  • roll-loop   %s  active %02d:00–%02d:00  %s（窗口 %02d:00–%02d:00）"
+_i18n_set zh loop.roll_loop_s_active_02d_00_2 "  • roll-loop   %s  有效窗口 %02d:00–%02d:00  %s（active %02d:00–%02d:00）"
+_i18n_set en loop.roll_dream_daily_at_02d_02d_2 "  • roll-.dream daily at %02d:%02d  每天 %02d:%02d"
+_i18n_set zh loop.roll_dream_daily_at_02d_02d_2 "  • roll-.dream daily at %02d:%02d  每天 %02d:%02d"
+_i18n_set en loop.roll_brief_daily_at_02d_02d_2 "  • roll-brief  daily at %02d:%02d  每天 %02d:%02d"
+_i18n_set zh loop.roll_brief_daily_at_02d_02d_2 "  • roll-brief  daily at %02d:%02d  每天 %02d:%02d"
 _i18n_set en loop.loop_not_enabled_for_this_project "Loop not enabled for this project"
 _i18n_set zh loop.loop_not_enabled_for_this_project "当前项目 loop 未启用"
 _i18n_set en loop.loop_disabled "Loop disabled"

package/lib/loop_pick_agent.py

@@ -0,0 +1,245 @@
+#!/usr/bin/env python3
+"""Pick a routing agent for a backlog story (US-AGENT-004).
+
+Reads story metadata from the feature markdown (linked from the BACKLOG row)
+and matches it against agent-routes.yaml hard rules. Emits a single line on
+stdout:
+
+    <agent> <rule_kind> <rationale>
+
+Exit codes:
+  0 — agent picked (rule_kind in {hard, default})
+  1 — story id not found / unrecoverable error
+
+Usage:
+  loop_pick_agent.py --story-id US-AGENT-004 \\
+                     --backlog .roll/backlog.md \\
+                     --routes  .roll/agent-routes.yaml
+
+History-driven soft preference (US-AGENT-005) lands on top of this in a
+later commit; the present module only implements hard-rule selection.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+
+try:
+    import yaml
+except ImportError:
+    print("loop_pick_agent: PyYAML not installed", file=sys.stderr)
+    sys.exit(2)
+
+
+PROFILE_BLOCK_RE = re.compile(r"\*\*Agent profile:\*\*")
+EST_RE = re.compile(r"^\s*-\s*est_min:\s*(\d+)")
+RISK_RE = re.compile(r"^\s*-\s*risk_zone:\s*([a-zA-Z]+)")
+CHAIN_RE = re.compile(r"^\s*-\s*chain_depth:\s*(\d+)")
+ANCHOR_TEMPLATE = '<a id="{anchor}"></a>'
+
+
+def _id_to_anchor(story_id: str) -> str:
+    return story_id.lower()
+
+
+def _find_feature_md(backlog_path: Path, story_id: str) -> Path | None:
+    """Resolve feature md path by scanning backlog rows for the story id."""
+    if not backlog_path.exists():
+        return None
+    link_re = re.compile(
+        r"\[" + re.escape(story_id) + r"\]\((\.roll/features/[^)]+?)#",
+        re.IGNORECASE,
+    )
+    for line in backlog_path.read_text().splitlines():
+        m = link_re.search(line)
+        if m:
+            return Path(m.group(1))
+    return None
+
+
+def _read_profile(feature_md: Path, story_id: str) -> dict | None:
+    """Return {est_min, risk_zone, chain_depth} or None if not found."""
+    if not feature_md.exists():
+        return None
+    anchor = ANCHOR_TEMPLATE.format(anchor=_id_to_anchor(story_id))
+    text = feature_md.read_text()
+    if anchor not in text:
+        return None
+
+    # Slice from the anchor to the next anchor or EOF.
+    start = text.index(anchor)
+    next_anchor_match = re.search(r'<a id="[^"]+"></a>', text[start + len(anchor):])
+    end = start + len(anchor) + (next_anchor_match.start() if next_anchor_match else len(text))
+    section = text[start:end]
+
+    if not PROFILE_BLOCK_RE.search(section):
+        return None
+
+    profile: dict[str, object] = {}
+    for line in section.splitlines():
+        m = EST_RE.match(line)
+        if m:
+            profile["est_min"] = int(m.group(1))
+            continue
+        m = RISK_RE.match(line)
+        if m:
+            profile["risk_zone"] = m.group(1).lower()
+            continue
+        m = CHAIN_RE.match(line)
+        if m:
+            profile["chain_depth"] = int(m.group(1))
+    if "est_min" not in profile or "risk_zone" not in profile:
+        return None
+    profile.setdefault("chain_depth", 0)
+    return profile
+
+
+def _story_type(story_id: str) -> str:
+    # Story id prefix → routing type. US-AGENT-004 → "US", FIX-* → "FIX",
+    # REFACTOR-* → "REFACTOR". Default falls through to "US".
+    prefix = story_id.split("-", 1)[0].upper()
+    return prefix if prefix in {"FIX", "US", "REFACTOR"} else "US"
+
+
+def _agent_matches(agent_cfg: dict, story_type: str, est_min: int, risk_zone: str) -> bool:
+    types = agent_cfg.get("types") or []
+    if story_type not in types:
+        return False
+    est_range = agent_cfg.get("est_min") or {}
+    lo = est_range.get("min")
+    hi = est_range.get("max")
+    if lo is not None and est_min < lo:
+        return False
+    if hi is not None and est_min > hi:
+        return False
+    risk_list = agent_cfg.get("risk") or []
+    if risk_zone not in risk_list:
+        return False
+    return True
+
+
+def _hit_rates(runs_path: Path, story_type: str, window: int) -> dict[str, tuple[int, int]]:
+    """Return {agent: (built_count, total_count)} for the requested story type
+    over the last `window` runs.jsonl records that targeted that type. Records
+    must carry `agent` and `story_type` (forward-looking schema, US-AGENT-005).
+    Older records lacking these fields are skipped silently.
+    """
+    rates: dict[str, list[int]] = {}
+    if window <= 0 or not runs_path.exists():
+        return {}
+    # Read all then take last N matching story_type.
+    matching: list[dict] = []
+    for line in runs_path.read_text().splitlines():
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            rec = json.loads(line)
+        except ValueError:
+            continue
+        if rec.get("story_type") != story_type:
+            continue
+        if "agent" not in rec:
+            continue
+        matching.append(rec)
+    for rec in matching[-window:]:
+        agent = rec["agent"]
+        slot = rates.setdefault(agent, [0, 0])
+        slot[1] += 1
+        if rec.get("status") == "built":
+            slot[0] += 1
+    return {a: (b, t) for a, (b, t) in rates.items()}
+
+
+def pick(story_id: str, backlog_path: Path, routes_path: Path,
+         runs_path: Path | None = None) -> tuple[str, str, str] | None:
+    """Return (agent, rule_kind, rationale) or None on hard error."""
+    if not routes_path.exists():
+        return None
+    routes = yaml.safe_load(routes_path.read_text()) or {}
+    agents = routes.get("agents") or {}
+    history = routes.get("history") or {}
+    cold = history.get("cold_start_default") or next(iter(agents), None)
+    window = int(history.get("window_cycles", 0) or 0)
+    threshold = float(history.get("prefer_threshold", 0.0) or 0.0)
+
+    feature_md = _find_feature_md(backlog_path, story_id)
+    if feature_md is None:
+        return None  # story id not in backlog
+
+    profile = _read_profile(feature_md, story_id)
+    if profile is None:
+        if cold is None:
+            return None
+        return (cold, "default", f"no profile for {story_id}; fell back to cold_start_default")
+
+    story_type = _story_type(story_id)
+    est_min = profile["est_min"]
+    risk_zone = profile["risk_zone"]
+
+    # Hard-rule candidate set in declaration order.
+    matched: list[str] = []
+    for name, cfg in agents.items():
+        if _agent_matches(cfg or {}, story_type, est_min, risk_zone):
+            matched.append(name)
+
+    if not matched:
+        if cold is None:
+            return None
+        return (cold, "default", f"no agent matched {story_type}/{est_min}/{risk_zone}; cold_start_default")
+
+    # Single match → no soft pref needed.
+    if len(matched) == 1 or runs_path is None or window <= 0:
+        chosen = matched[0]
+        rationale = f"hard: type={story_type} est={est_min} risk={risk_zone} matched {chosen}"
+        return (chosen, "hard", rationale)
+
+    # Multiple matches → consider history soft preference.
+    rates = _hit_rates(runs_path, story_type, window)
+    # Filter rates to candidates only, require sample ≥ 5 and rate ≥ threshold.
+    eligible = []
+    for cand in matched:
+        built, total = rates.get(cand, (0, 0))
+        if total >= 5:
+            rate = built / total if total else 0.0
+            if rate >= threshold:
+                eligible.append((rate, cand))
+    if eligible:
+        eligible.sort(reverse=True)  # highest rate first
+        rate, chosen = eligible[0]
+        rationale = (
+            f"soft: type={story_type} est={est_min} risk={risk_zone} "
+            f"history_rate={rate:.2f} (threshold={threshold}) matched {chosen}"
+        )
+        return (chosen, "soft", rationale)
+
+    # Fallback to hard-rule first.
+    chosen = matched[0]
+    rationale = f"hard: type={story_type} est={est_min} risk={risk_zone} matched {chosen} (no eligible history)"
+    return (chosen, "hard", rationale)
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--story-id", required=True)
+    parser.add_argument("--backlog", default=".roll/backlog.md")
+    parser.add_argument("--routes", default=".roll/agent-routes.yaml")
+    parser.add_argument("--runs", default=None,
+                        help="runs.jsonl path for history soft preference (US-AGENT-005)")
+    args = parser.parse_args()
+
+    runs = Path(args.runs) if args.runs else None
+    result = pick(args.story_id, Path(args.backlog), Path(args.routes), runs)
+    if result is None:
+        print(f"loop_pick_agent: cannot route {args.story_id}", file=sys.stderr)
+        return 1
+    agent, rule_kind, rationale = result
+    print(f"{agent} {rule_kind} {rationale}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/lib/prices/README.md

@@ -0,0 +1,35 @@
+> **Draft** — auto-generated by roll-doc on 2026-05-28. Review before treating as authoritative.
+
+# lib/prices/ — Model price snapshots
+
+Dated JSON snapshots of AI model list prices, used by `roll loop status` to compute per-cycle cost in both USD and native currency (CNY for pi/DeepSeek/Kimi).
+
+## Files
+
+| File | Contents |
+|------|---------|
+| `snapshot-2026-05-22.json` | Multi-vendor snapshot (Claude, GPT, Gemini, DeepSeek, Kimi, pi) |
+| `snapshot-2026-05-23-deepseek.json` | DeepSeek-specific refresh |
+| `snapshot-2026-05-23-kimi.json` | Kimi-specific refresh |
+
+## Format
+
+Each snapshot is a JSON object keyed by model ID:
+
+```json
+{
+  "claude-opus-4-7": {
+    "input_per_mtok": 15.0,
+    "output_per_mtok": 75.0,
+    "cache_write_per_mtok": 18.75,
+    "cache_read_per_mtok": 1.5,
+    "currency": "USD"
+  }
+}
+```
+
+CNY-priced models (pi, DeepSeek, Kimi) use `"currency": "CNY"`.
+
+## Refresh
+
+`prices_fetcher.py` fetches fresh snapshots from vendor pricing APIs and writes a new dated file here. Run via `roll prices refresh`.

package/lib/roll-help.py

@@ -42,6 +42,7 @@ AUTONOMY = [
     ("backlog",  "[block|defer|…]",        "view and manage pending tasks",               "查看和管理待处理任务",        True),
     ("peer",     "",                       "cross-agent negotiation & review",            "跨 Agent 协商对审",         False),
     ("alert",    "",                       "view and clear loop alerts",                  "查看 / 清除 loop 告警",     False),
+    ("feedback", "--type bug|idea|ux …",   "open a GitHub issue for this project",        "为本项目提交反馈",            False),
 ]
 
 PROJECT = [