@seanyao/roll 2026.529.1 → 2026.529.2

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/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/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 = [

package/lib/roll-loop-status.py

@@ -706,6 +706,97 @@ def rollup_for_story(cycles: List[Dict[str, Any]], story_id: str) -> Dict[str, A
             r["model"] = cy["model"]
     return r
 
+
+# US-SKILL-014: aggregate the last N self-score notes for the dashboard.
+# Reads .roll/notes/*.md (frontmatter format from US-SKILL-010), returns
+#   "self-score: mean 7.8 / min 4 / redo 2 (last 14)"
+# or "" when no notes / "self-score: (n/a) — N sample(s), need 3 (last N)"
+# when sample is too small.
+def _self_score_summary_line(notes_dir = None, window: int = 14) -> str:
+    notes_dir = notes_dir if notes_dir is not None else Path(".roll/notes")
+    if not notes_dir.exists():
+        return ""
+    files = sorted(notes_dir.glob("*.md"))[-window:]
+    if not files:
+        return ""
+    total = 0
+    count = 0
+    minv = 11
+    redo = 0
+    for f in files:
+        score = None
+        verdict = None
+        for line in f.read_text(errors="ignore").splitlines():
+            if line.startswith("score: "):
+                try:
+                    score = int(line.split(": ", 1)[1].strip())
+                except ValueError:
+                    score = None
+            elif line.startswith("verdict: "):
+                verdict = line.split(": ", 1)[1].strip()
+            if score is not None and verdict is not None:
+                break
+        if score is None:
+            continue
+        count += 1
+        total += score
+        if score < minv:
+            minv = score
+        if verdict == "regression":
+            redo += 1
+        elif verdict == "ok" and score < 6:
+            redo += 1
+    if count < 3:
+        return f"self-score: (n/a) — {count} sample(s), need 3 (last {window})"
+    mean = total / count
+    return f"self-score: mean {mean:.1f} / min {minv} / redo {redo} (last {window})"
+
+
+# US-AGENT-010: per-agent hit-rate summary for the ROLLUP block.
+# Aggregates the last `window_cycles` runs.jsonl records grouped by `agent`.
+# Returns a single-line string like
+#     "agents: pi 8/22 (36%) · deepseek 5/8 (63%) · claude 2/2 (n/a)"
+# Empty agents / missing agent field are skipped. Sample < min_sample renders
+# as "(n/a)" instead of a percentage to avoid noise from tiny windows.
+def _agent_summary_line(records: List[Dict[str, Any]], window_cycles: int = 50,
+                       min_sample: int = 5) -> str:
+    if not records or window_cycles <= 0:
+        return ""
+    # Take the most recent `window_cycles` records that have an agent field.
+    tail: List[Dict[str, Any]] = []
+    for rec in records[-window_cycles:]:
+        agent = (rec or {}).get("agent") or ""
+        if not agent:
+            continue
+        tail.append(rec)
+    if not tail:
+        return ""
+    counts: Dict[str, List[int]] = {}
+    # preserve first-seen order for stable output
+    order: List[str] = []
+    for rec in tail:
+        agent = rec.get("agent") or ""
+        if not agent:
+            continue
+        if agent not in counts:
+            counts[agent] = [0, 0]
+            order.append(agent)
+        counts[agent][1] += 1
+        if rec.get("status") == "built":
+            counts[agent][0] += 1
+    if not order:
+        return ""
+    parts: List[str] = []
+    for agent in order:
+        built, total = counts[agent]
+        if total < min_sample:
+            parts.append(f"{agent} {built}/{total} (n/a)")
+        else:
+            pct = round(100 * built / total) if total else 0
+            parts.append(f"{agent} {built}/{total} ({pct}%)")
+    return "agents: " + " · ".join(parts)
+
+
 def rollup_for_day(day_cycles: List[Dict[str, Any]]) -> Dict[str, Any]:
     # US-VIEW-012: track input + output separately so the daily summary can
     # show two metric rows. cache_read tokens deliberately excluded — they're
@@ -930,6 +1021,24 @@ def render(events, cron, state, backlog, *, days=3, lang="both", now=None,
                       d2["cost_by_cur"].get(_cur, 0.0),
                       partial=is_partial, symbol=_sym)
 
+    # US-AGENT-010: per-agent hit-rate summary (single line).
+    try:
+        runs_records = list(runs.values()) if isinstance(runs, dict) else list(runs or [])
+        runs_records.sort(key=lambda r: (r or {}).get("ts", ""))
+        _agent_line = _agent_summary_line(runs_records, window_cycles=50)
+    except Exception:
+        _agent_line = ""
+    if _agent_line:
+        print("  " + c("dim", _agent_line))
+
+    # US-SKILL-014: per-skill self-score trend (single line) under the agent line.
+    try:
+        _skill_line = _self_score_summary_line()
+    except Exception:
+        _skill_line = ""
+    if _skill_line:
+        print("  " + c("dim", _skill_line))
+
     print()
     print(c("faint", "─" * COLS))
     print()