@seanyao/roll 2026.528.2 → 2026.529.2

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.528.2"
+VERSION="2026.529.2"
 ROLL_HOME="${ROLL_HOME:-${HOME}/.roll}"
 ROLL_CONFIG="${ROLL_HOME}/config.yaml"
 ROLL_GLOBAL="${ROLL_HOME}/conventions/global"
@@ -83,31 +83,80 @@ lower_name() {
 }
 
 
-# Check if an AI tool is actually installed.
-# Most tools create their own config dir; Trae on macOS uses Library/Application Support
-# and expects roll to manage ~/.trae/ — so we detect via the app directory instead.
-_is_ai_installed() {
-  local ai_dir="$1"
-  [[ -d "$ai_dir" ]] && return 0
-  local bn
-  bn="$(basename "$ai_dir" | sed 's/^\.//')"
-  case "$bn" in
+# FIX-128: agent → binary-name(s) lookup. First binary found wins. Used by
+# _agent_installed_by_name to enforce "CLI must exist on PATH" detection
+# instead of the old "config dir exists" check (which Roll's own convention
+# sync would fake — see FIX-128).
+_agent_bin_names() {
+  case "$1" in
+    claude)            echo "claude" ;;
+    codex|openai)      echo "codex" ;;        # openai is a Roll alias for codex
+    agy|gemini)        echo "agy gemini" ;;   # gemini reuses ~/.gemini for agy
+    kimi)              echo "kimi-code kimi-cli kimi" ;;  # FIX-126
+    deepseek)          echo "deepseek" ;;
+    qwen)              echo "qwen" ;;
+    pi)                echo "pi" ;;
+    *)                 return 1 ;;
+  esac
+}
+
+# FIX-128: detect whether an AI agent (by canonical name) is actually
+# usable on this machine. For CLI-only agents this means "binary on PATH";
+# GUI / bundled-binary agents keep their special-case paths. Falls back
+# to dir-existence only for unknown agents the operator has registered
+# manually (forward-compatible with future additions).
+_agent_installed_by_name() {
+  local agent="$1"
+  local dir="${2:-}"
+  case "$agent" in
     trae)
-      [[ -d "$HOME/Library/Application Support/Trae" ]] ||
-      [[ -d "$HOME/.config/Trae" ]]
+      [[ -d "$HOME/Library/Application Support/Trae" ]] || [[ -d "$HOME/.config/Trae" ]]
       return
       ;;
     opencode)
       [[ -x "$HOME/.opencode/bin/opencode" ]]
       return
       ;;
-    agent)
-      if [[ "$(basename "$(dirname "$ai_dir")")" == ".pi" ]]; then
-        command -v pi &>/dev/null && return
-      fi
+    cursor)
+      # cursor ships a GUI + an optional CLI; either path counts as "installed".
+      command -v cursor >/dev/null 2>&1 || [[ -d "$HOME/.cursor" ]]
+      return
+      ;;
+    openclaw)
+      [[ -d "$HOME/.openclaw/workspace" ]]
+      return
       ;;
   esac
-  return 1
+  local bins
+  if bins=$(_agent_bin_names "$agent" 2>/dev/null); then
+    local b
+    for b in $bins; do
+      command -v "$b" >/dev/null 2>&1 && return 0
+    done
+    return 1
+  fi
+  # Unknown agent — fall back to dir presence so user-added entries still work.
+  [[ -n "$dir" && -d "$dir" ]]
+}
+
+# Check if an AI tool is actually installed (back-compat shim around
+# _agent_installed_by_name; preserves the dir-path-based signature used
+# throughout bin/roll).
+_is_ai_installed() {
+  local ai_dir="$1"
+  local bn
+  bn="$(basename "$ai_dir" | sed 's/^\.//')"
+  # Nested-dir layouts collapse to their parent agent name.
+  case "$bn" in
+    agent|workspace)
+      bn="$(basename "$(dirname "$ai_dir")" | sed 's/^\.//')"
+      ;;
+  esac
+  # Mirror ai_tool_name's alias normalization so detection routes to the
+  # canonical agent record (e.g. ~/.gemini → agy, ~/.kimi-code → kimi).
+  [[ "$bn" == "gemini" ]] && bn="agy"
+  [[ "$bn" == "kimi-code" ]] && bn="kimi"
+  _agent_installed_by_name "$bn" "$ai_dir"
 }
 
 # ─── Spinner: TTY-aware status display for long-running steps (US-REL-003) ───
@@ -512,8 +561,7 @@ editor: ${EDITOR:-vim}
 
 # Loop schedule (24h format, machine local timezone)
 # Minute fields auto-derive from project path hash when omitted — avoids contention across projects.
-loop_active_start: 10   # loop only fires inside this window (after human reviews brief)
-loop_active_end: 18
+# active_start/active_end moved to per-project .roll/local.yaml loop_schedule block (default 0/24).
 # loop_minute: 5        # omit to auto-derive from project hash
 loop_dream_hour: 3
 # loop_dream_minute: 10 # omit to auto-derive
@@ -522,6 +570,19 @@ loop_brief_hour: 9
 primary_agent: claude
 YAML
     ok "$(msg shared.created_roll_config_yaml)"
+
+    # FIX-128: the heredoc template hardcodes `primary_agent: claude` for
+    # the first-time case. Replace it with the first agent that actually
+    # has its CLI on PATH so users without Claude installed don't get a
+    # silently-broken default. If nothing detected, leave `claude` so the
+    # user still has a clear handle to fix manually.
+    local _detected_primary
+    _detected_primary="$(_first_installed_agent || true)"
+    if [[ -n "$_detected_primary" && "$_detected_primary" != "claude" ]]; then
+      _replace_primary_agent "$_detected_primary"
+      info "$(msg shared.primary_agent_auto_detected "$_detected_primary" 2>/dev/null \
+             || echo "primary_agent → $_detected_primary (auto-detected from installed CLIs)")"
+    fi
   fi
 
   # Ensure all expected ai_* keys exist (handles upgrades where new tools were added)
@@ -529,6 +590,32 @@ YAML
 
 }
 
+# FIX-128: pick the first agent whose CLI is on PATH, scanning the same
+# order the default config template lists them. Empty stdout when none
+# detected; never errors.
+_first_installed_agent() {
+  local agent
+  for agent in claude codex kimi deepseek qwen agy pi cursor opencode trae openclaw; do
+    if _agent_installed_by_name "$agent"; then
+      echo "$agent"
+      return 0
+    fi
+  done
+  return 1
+}
+
+# FIX-128: rewrite the `primary_agent:` line in $ROLL_CONFIG to the given
+# value. Single-line in-place edit, preserves the rest of the file.
+_replace_primary_agent() {
+  local new="$1"
+  [[ -f "$ROLL_CONFIG" && -n "$new" ]] || return 0
+  local tmp; tmp="$(mktemp)"
+  awk -v new="$new" '
+    /^primary_agent:/ { print "primary_agent: " new; next }
+    { print }
+  ' "$ROLL_CONFIG" > "$tmp" && mv "$tmp" "$ROLL_CONFIG"
+}
+
 # ─── Internal: create or repair per-skill symlinks (non-destructive) ─────────
 _link_skills() {
   local force="${1:-false}"
@@ -539,7 +626,18 @@ _link_skills() {
   while IFS= read -r entry; do
     local ai_dir
     ai_dir="$(_ai_dir "$entry")"
-    _is_ai_installed "$ai_dir" || continue
+    # FIX-128: detection is now binary-on-PATH, but skill linking keeps
+    # the same Claude-always-syncs semantics as _apply_conventions and
+    # tolerates pre-existing config dirs (an agent the user is mid-
+    # upgrade or installed via nvm/asdf still has its convention dir;
+    # we don't want to silently stop linking skills there). Strict
+    # binary detection drives chooser logic (primary_agent /
+    # _onboard_discover_agents) — see FIX-128.
+    if [[ "$ai_dir" != "$HOME/.claude" ]] \
+       && ! _is_ai_installed "$ai_dir" \
+       && [[ ! -d "$ai_dir" ]]; then
+      continue
+    fi
     mkdir -p "$ai_dir"
 
     local ai_name ai_dir_real skills_dir
@@ -639,8 +737,13 @@ _sync_convention_for_tool() {
   local dst_dir
   dst_dir="$(dirname "$main_dst")"
 
-  # Only proceed if Claude (always) or the tool is installed
-  if [[ "$dst_dir" != "$HOME/.claude" ]] && ! _is_ai_installed "$dst_dir"; then
+  # Only proceed if Claude (always), the tool is installed (binary-on-PATH
+  # per FIX-128), or the convention dir already exists (mid-upgrade /
+  # nvm-installed binaries that aren't on this shell's PATH still get
+  # their convention refresh).
+  if [[ "$dst_dir" != "$HOME/.claude" ]] \
+     && ! _is_ai_installed "$dst_dir" \
+     && [[ ! -d "$dst_dir" ]]; then
     return
   fi
   mkdir -p "$dst_dir"
@@ -927,10 +1030,46 @@ HINT
 # prints install commands for the ones that aren't, so users who already opted
 # in (or opted out) don't get spammed each upgrade.
 cmd_doctor() {
+  _doctor_agent_section
   _doctor_pr_section
   _doctor_launchd_stale_section
 }
 
+# FIX-128: list every ai_* entry from config, tag each with binary-on-PATH
+# status and config-dir existence so the user can see at a glance which
+# agents are actually usable vs only have Roll-maintained dirs.
+_doctor_agent_section() {
+  [[ -f "$ROLL_CONFIG" ]] || return 0
+  echo ""
+  echo "$(ROLL_LANG_RESOLVED=en msg doctor.agent_detection)"
+  echo "$(ROLL_LANG_RESOLVED=zh msg doctor.agent_detection)"
+  echo ""
+  local _key _value _name _dir _installed _dir_exists _is_primary
+  _is_primary=$(grep -E '^primary_agent:' "$ROLL_CONFIG" 2>/dev/null | sed 's/^primary_agent: *//')
+  while IFS=: read -r _key _value; do
+    [[ "$_key" =~ ^ai_ ]] || continue
+    _name="${_key#ai_}"
+    [[ "$_name" == "kimi_code" ]] && continue  # dedupe
+    _dir="${_value%%|*}"
+    _dir="${_dir# }"
+    _dir="${_dir/#\~/$HOME}"
+    if _agent_installed_by_name "$_name" "$_dir"; then
+      _installed="$(msg doctor.agent_installed)"
+    else
+      _installed="$(msg doctor.agent_missing)"
+    fi
+    if [[ -d "$_dir" ]]; then
+      _dir_exists="$(msg doctor.agent_dir_exists)"
+    else
+      _dir_exists="$(msg doctor.agent_dir_missing)"
+    fi
+    local _tag=""
+    [[ "$_name" == "$_is_primary" ]] && _tag="  ($(msg doctor.agent_primary_label))"
+    printf "  %-10s  %-14s  %s%s\n" "$_name" "$_installed" "$_dir_exists" "$_tag"
+  done < "$ROLL_CONFIG"
+  return 0
+}
+
 # FIX-097: scan ${_LAUNCHD_DIR}/com.roll.*.plist for entries whose
 # WorkingDirectory no longer exists on disk. These are the ghost agents left
 # behind when a user manually reproduces a bug under /private/tmp/ or
@@ -1267,6 +1406,10 @@ cmd_init() {
     _write_backlog "$project_dir/.roll/backlog.md"
     _ensure_features_dir "$project_dir/.roll/features"
     _write_features_md "$project_dir/.roll/features.md"
+    # US-AGENT-003: seed agent-routes.yaml from template. Env override:
+    #   ROLL_AGENT_ROUTES_TEMPLATE=minimal roll init
+    # Onboard plan can also set agent_routes_template; _init_apply reads it.
+    _init_seed_agent_routes "${ROLL_AGENT_ROUTES_TEMPLATE:-default}" "$project_dir" || true
     # US-ONBOARD-019: stamp the project so legacy detection can recognise it
     # as Roll-onboarded without depending on directory-name heuristics.
     _write_version_stamp "$project_dir"
@@ -1467,15 +1610,31 @@ _onboard_discover_agents() {
   while IFS=: read -r _key _value; do
     [[ "$_key" =~ ^ai_ ]] || continue
     _name="${_key#ai_}"
+    # ai_kimi_code → kimi (avoid listing the same agent twice).
+    [[ "$_name" == "kimi_code" ]] && _name="kimi"
     _dir="${_value%%|*}"
     _dir="${_dir# }"
     _dir="${_dir/#\~/$HOME}"
-    if [[ -d "$_dir" ]]; then
-      _ONBOARD_INSTALLED+=("$_name")
+    # FIX-128: route via _agent_installed_by_name so "installed" means the
+    # CLI is actually on PATH for known agents, not just the config dir
+    # that Roll's own convention sync would have created.
+    if _agent_installed_by_name "$_name" "$_dir"; then
+      # Dedupe — kimi may appear under both ai_kimi and ai_kimi_code.
+      # `${arr[@]+...}` keeps `set -u` happy when the array is still empty.
+      local _already=0 _existing
+      for _existing in ${_ONBOARD_INSTALLED[@]+"${_ONBOARD_INSTALLED[@]}"}; do
+        if [[ "$_existing" == "$_name" ]]; then _already=1; break; fi
+      done
+      if [[ $_already -eq 0 ]]; then _ONBOARD_INSTALLED+=("$_name"); fi
     else
-      _ONBOARD_MISSING+=("$_name")
+      local _already=0 _existing
+      for _existing in ${_ONBOARD_MISSING[@]+"${_ONBOARD_MISSING[@]}"}; do
+        if [[ "$_existing" == "$_name" ]]; then _already=1; break; fi
+      done
+      if [[ $_already -eq 0 ]]; then _ONBOARD_MISSING+=("$_name"); fi
     fi
   done < "$ROLL_CONFIG"
+  return 0
 }
 
 # US-ONBOARD-018: pick an agent for the onboard flow.
@@ -1776,6 +1935,26 @@ print(' '.join(p.get('scope', {}).get('approved', [])))
     _write_backlog "$project_dir/.roll/backlog.md"
     _onboard_changeset_record "$project_dir" "files_created" ".roll/backlog.md"
   fi
+
+  # US-AGENT-003: seed agent-routes.yaml. Template precedence:
+  #   1. plan.agent_routes_template (set by $roll-onboard interactive flow)
+  #   2. ROLL_AGENT_ROUTES_TEMPLATE env var
+  #   3. "default"
+  # Set to "skip" to omit seeding entirely.
+  local _routes_template
+  _routes_template=$(python3 -c "
+import yaml
+p = yaml.safe_load(open('$plan')) or {}
+print(p.get('agent_routes_template', '') or '')
+" 2>/dev/null || echo "")
+  if [[ -z "$_routes_template" ]]; then
+    _routes_template="${ROLL_AGENT_ROUTES_TEMPLATE:-default}"
+  fi
+  if [[ "$_routes_template" != "skip" ]]; then
+    if _init_seed_agent_routes "$_routes_template" "$project_dir"; then
+      _onboard_changeset_record "$project_dir" "files_created" ".roll/agent-routes.yaml"
+    fi
+  fi
   if [[ " $approved " == *" features "* ]]; then
     _ensure_features_dir "$project_dir/.roll/features"
     _write_features_md "$project_dir/.roll/features.md"
@@ -2294,6 +2473,31 @@ EOF
   _ROLL_MERGE_SUMMARY+=("created|.roll/backlog.md")
 }
 
+# US-AGENT-003: seed .roll/agent-routes.yaml from a named template (default /
+# minimal / heavy). Idempotent — leaves an existing file untouched. Templates
+# live under ${ROLL_TEMPLATES}/agent-routes/<name>.yaml.
+_init_seed_agent_routes() {
+  local template_name="${1:-default}"
+  local project_dir="${2:-$(pwd)}"
+  local dest="${project_dir}/.roll/agent-routes.yaml"
+
+  if [[ -f "$dest" ]]; then
+    _ROLL_MERGE_SUMMARY+=("unchanged|.roll/agent-routes.yaml")
+    return 0
+  fi
+
+  local src="${ROLL_TEMPLATES}/agent-routes/${template_name}.yaml"
+  if [[ ! -f "$src" ]]; then
+    err "agent-routes template not found: ${template_name} (looked for ${src})"
+    return 1
+  fi
+
+  mkdir -p "$(dirname "$dest")"
+  cp "$src" "$dest"
+  ok "Created: .roll/agent-routes.yaml (template: ${template_name})"
+  _ROLL_MERGE_SUMMARY+=("created|.roll/agent-routes.yaml")
+}
+
 _ensure_features_dir() {
   if [[ -d "$1" ]]; then
     _ROLL_MERGE_SUMMARY+=("unchanged|.roll/features/")
@@ -4624,13 +4828,16 @@ _isolation_tart_check_binary() {
 # returns 1 silently otherwise. Caller decides what to do.
 _isolation_tart_vm_present() {
   local name; name=$(_isolation_tart_vm_name)
-  tart list 2>/dev/null | awk -v n="$name" '$1 == n { found=1 } END { exit !found }'
+  tart list 2>/dev/null | awk -v n="$name" '$2 == n { found=1 } END { exit !found }'
 }
 
 # Returns the VM's IP on stdout when reachable; exit non-zero when the VM
 # is stopped or `tart ip` fails for any other reason.
 _isolation_tart_ip() {
   local name; name=$(_isolation_tart_vm_name)
+  # FIX: tart ip returns a stale DHCP-cached IP even for stopped VMs.
+  # Gate on tart list State field before trusting the IP.
+  tart list 2>/dev/null | awk -v n="$name" '$2 == n && $NF == "running" { found=1 } END { exit !found }' || return 1
   local ip; ip=$(tart ip "$name" 2>/dev/null) || return 1
   [[ "$ip" =~ ^[0-9]+\.[0-9]+\.[0-9]+\.[0-9]+$ ]] || return 1
   printf '%s\n' "$ip"
@@ -4680,7 +4887,7 @@ _isolation_tart_provision() {
   local ip; ip=$(_isolation_tart_ip) || { err "tart provision: VM not running"; return 1; }
   local user; user=$(_isolation_tart_ssh_user)
   ssh -o BatchMode=yes -o StrictHostKeyChecking=no \
-      "${user}@${ip}" "brew list bats >/dev/null 2>&1 || brew install bats-core; \
+      "${user}@${ip}" "export PATH=/opt/homebrew/bin:/usr/local/bin:\$PATH; brew list bats >/dev/null 2>&1 || brew install bats-core; \
                        brew list node >/dev/null 2>&1 || brew install node; \
                        brew list bash >/dev/null 2>&1 || brew install bash"
 }
@@ -4695,7 +4902,7 @@ _isolation_tart_exec() {
   if ! ip=$(_isolation_tart_ip); then
     # VM stopped — start it in the background with the repo mounted.
     local repo_root; repo_root="$(pwd -P)"
-    tart run --dir="roll:${repo_root}" "$name" >/dev/null 2>&1 &
+    tart run --no-graphics --dir="roll:${repo_root}" "$name" >/dev/null 2>&1 &
     # Wait up to ~30s for IP to come up.
     local i=0
     while (( i < 30 )); do
@@ -4706,7 +4913,9 @@ _isolation_tart_exec() {
     [[ -n "${ip:-}" ]] || { err "tart exec: VM failed to start in 30s"; return 1; }
   fi
   local user; user=$(_isolation_tart_ssh_user)
-  ssh -o BatchMode=yes -o StrictHostKeyChecking=no "${user}@${ip}" "$@"
+  local remote_cmd
+  remote_cmd=$(printf '%q ' "$@")
+  ssh -o BatchMode=yes -o StrictHostKeyChecking=no "${user}@${ip}" "export PATH=/opt/homebrew/bin:/usr/local/bin:\$PATH; cd '/Volumes/My Shared Files/roll' && $remote_cmd"
 }
 
 # reset: stop, delete, re-clone from base image, then re-provision.
@@ -4810,7 +5019,8 @@ Flags:
   --help, -h     Show this help.
 
 Examples:
-  roll test                    Run the suite in whatever the config says.
+  roll test                    Run affected tests (default: --affected HEAD~1).
+  roll test -- tests/          Run the full suite explicitly.
   roll test -- --tier=fast     Forward arguments to npm test.
   roll test --where            Don't run; just report routing.
   roll test --reset            Rebuild the VM (or host no-op).
@@ -4855,7 +5065,16 @@ EOF
   fi
 
   # Pass remaining args through to npm test inside the configured adapter.
-  _isolation_dispatch exec npm test "$@"
+  # Default to --affected (HEAD~1 base) when the caller passes no extra args —
+  # mirrors the pre-commit hook's intent and keeps VM runs fast.
+  # To run the full suite explicitly: roll test -- tests/
+  local _npm_args=("$@")
+  if [[ "${#_npm_args[@]}" -eq 0 ]]; then
+    _npm_args=(--affected)
+  fi
+  # Always pass args via `--` so npm doesn't intercept flags like --affected
+  # as npm config options (npm warns and silently drops them otherwise).
+  _isolation_dispatch exec npm test -- "${_npm_args[@]}"
 }
 
 # ═══════════════════════════════════════════════════════════════════════════════
@@ -5431,6 +5650,28 @@ _loop_schedule_spec() {
   echo "60 $offset"
 }
 
+# Read loop active window from .roll/local.yaml loop_schedule block.
+# Resolution order:
+#   1. .roll/local.yaml  loop_schedule.{active_start,active_end}
+#   2. default           0 / 24  (full day)
+# Validation: both values must be integers 0–24, active_start < active_end.
+# Output: "<start> <end>" on stdout.
+_loop_read_active_window() {
+  local project_path="${1:-$(pwd -P)}"
+  local local_file="${project_path}/.roll/local.yaml"
+  if [[ -f "$local_file" ]]; then
+    local val_start val_end
+    val_start=$(awk '/^loop_schedule:/{found=1;next} found && /^[[:space:]]+active_start:/{print $2; exit}' "$local_file")
+    val_end=$(awk '/^loop_schedule:/{found=1;next} found && /^[[:space:]]+active_end:/{print $2; exit}' "$local_file")
+    if [[ "$val_start" =~ ^[0-9]+$ && "$val_end" =~ ^[0-9]+$ ]] \
+        && (( val_start < val_end && val_end <= 24 )); then
+      echo "$val_start $val_end"
+      return 0
+    fi
+  fi
+  echo "0 24"
+}
+
 # US-LOOP-032: human-readable schedule description.
 # Args: period offset [lang]
 #   lang: en (default) or zh
@@ -5914,12 +6155,22 @@ _runs_append() {
   # FIX-123: atomic write — write to .tmp.$$ first, then cat >> to append,
   # then remove. If interrupted between jq and rm, the next call cleans it.
   local _tmp="\$_runs_dst.tmp.\$\$"
+  # US-AGENT-005/010: emit agent + story_type so historical hit rates and
+  # status-page summaries have data to aggregate. Empty when not routed.
+  local _agent_field="\${ROLL_LOOP_ROUTED_AGENT:-\${CYCLE_AGENT:-}}"
+  local _story_field="\${ROLL_LOOP_ROUTED_STORY:-}"
+  local _stype_field=""
+  if [ -n "\$_story_field" ]; then
+    _stype_field="\${_story_field%%-*}"
+  fi
   jq -nc \\
     --arg ts "\$_ts_now" \\
     --arg project "${slug}" \\
     --arg run_id "\$_rid" \\
     --arg status "\$_status" \\
     --arg cycle_id "\$_cid" \\
+    --arg agent "\$_agent_field" \\
+    --arg story_type "\$_stype_field" \\
     --argjson built "\$_built" \\
     --argjson skipped '[]' \\
     --argjson alerts '[]' \\
@@ -5927,7 +6178,7 @@ _runs_append() {
     --argjson duration_sec "\$_dur" \\
     --argjson phases "\$_phases_json" \\
     '{ts:\$ts, project:\$project, run_id:\$run_id, status:\$status,
-      cycle_id:\$cycle_id,
+      cycle_id:\$cycle_id, agent:\$agent, story_type:\$story_type,
       built:\$built, skipped:\$skipped, alerts:\$alerts,
       tcr_count:\$tcr_count, duration_sec:\$duration_sec, phases:\$phases}' \\
     > "\$_tmp" 2>/dev/null || { rm -f "\$_tmp"; return 0; }
@@ -6153,7 +6404,27 @@ if _worktree_fetch_origin main \\
   _worktree_sync_meta "\$WT" 2>/dev/null || true
   echo "[loop] cycle \${CYCLE_ID}: worktree \$WT on \$BRANCH"
   _loop_event cycle_start "\${CYCLE_ID}" "" "" || true
-  _loop_event agent_used "\${CYCLE_ID}" "\$(_project_agent)" "primary" || true
+  # US-AGENT-006: per-story routing — pick the next Todo, route to an agent
+  # based on its Agent profile + agent-routes.yaml, fall back to
+  # _project_agent when no story is pickable or routing returns nothing.
+  ROLL_LOOP_ROUTED_STORY=""
+  ROLL_LOOP_ROUTED_AGENT=""
+  ROLL_LOOP_ROUTED_RULE=""
+  ROLL_LOOP_ROUTE_RATIONALE=""
+  ( cd "\$WT" >/dev/null 2>&1 && ROLL_LOOP_ROUTED_STORY=\$(_loop_pick_next_story 2>/dev/null) || true )
+  ROLL_LOOP_ROUTED_STORY=\$( (cd "\$WT" 2>/dev/null && _loop_pick_next_story 2>/dev/null) || echo "" )
+  if [ -n "\$ROLL_LOOP_ROUTED_STORY" ]; then
+    _route_line=\$( (cd "\$WT" 2>/dev/null && _loop_pick_agent_for_story "\$ROLL_LOOP_ROUTED_STORY" 2>/dev/null) || echo "" )
+    if [ -n "\$_route_line" ]; then
+      ROLL_LOOP_ROUTED_AGENT=\$(echo "\$_route_line" | awk '{print \$1}')
+      ROLL_LOOP_ROUTED_RULE=\$(echo "\$_route_line" | awk '{print \$2}')
+      ROLL_LOOP_ROUTE_RATIONALE=\$(echo "\$_route_line" | cut -d' ' -f3-)
+      echo "[loop] story \${ROLL_LOOP_ROUTED_STORY} routed to \${ROLL_LOOP_ROUTED_AGENT} via \${ROLL_LOOP_ROUTED_RULE}"
+      _loop_event story_routed "\${CYCLE_ID}" "\${ROLL_LOOP_ROUTED_STORY}" "\${ROLL_LOOP_ROUTED_AGENT}|\${ROLL_LOOP_ROUTED_RULE}" || true
+    fi
+  fi
+  CYCLE_AGENT="\${ROLL_LOOP_ROUTED_AGENT:-\$(_project_agent)}"
+  _loop_event agent_used "\${CYCLE_ID}" "\${CYCLE_AGENT}" "primary" || true
   _phase_end worktree_setup ok
 else
   # P3 fix: skip the cycle entirely when worktree isolation fails.
@@ -6180,7 +6451,9 @@ export LOOP_CYCLE_ID="\${CYCLE_ID}"
 export LOOP_SHARED_ROOT="\${_SHARED_ROOT:-\$HOME/.shared/roll}"
 # US-LOOP-010: tell loop-fmt.py which agent is running so it can branch
 # rendering: claude → stream-json parser, others → transparent passthrough.
-export ROLL_LOOP_AGENT="\$(_project_agent)"
+# US-AGENT-006: prefer the per-story routed agent (set above) when present.
+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
 for _attempt in 1 2 3; do
   # FIX-068: defensive reset before each attempt — _CYCLE_TIMED_OUT carries
@@ -6625,8 +6898,8 @@ _install_launchd_plists() {
   mkdir -p "${shared}/loop" "${shared}/dream" "${shared}/brief"
 
   local active_start active_end dream_hour dream_minute brief_hour brief_minute loop_period loop_offset
-  active_start=$(_config_read_int "loop_active_start" "10")
-  active_end=$(_config_read_int "loop_active_end" "18")
+  local _aw; _aw=$(_loop_read_active_window "$project_path")
+  active_start="${_aw%% *}"; active_end="${_aw##* }"
   # US-LOOP-012: use _loop_schedule_spec instead of raw loop_minute
   local loop_spec; loop_spec=$(_loop_schedule_spec "$project_path")
   loop_period="${loop_spec%% *}"
@@ -6757,6 +7030,8 @@ cmd_loop() {
     precheck-ci)          _loop_precheck_ci ;;
     hotfix-head-context)  _loop_hotfix_head_context "${1:-}" ;;
     branches)             _loop_branches "$(pwd -P)" ;;
+    agent-routes)         _loop_agent_routes "${1:-show}" "${@:2}" ;;
+    test-quality-check)   _loop_test_quality_check "$@" ;;
     *)  cat <<'HELP'
 Usage: roll loop <on|off|now|test|status|monitor|runs|log|story|events|attach|mute|unmute|pause|resume|reset|gc|branches>
 
@@ -6779,6 +7054,7 @@ Usage: roll loop <on|off|now|test|status|monitor|runs|log|story|events|attach|mu
   gc [--dry-run] [--keep-days N]
                 Garbage-collect orphan slugs, tmp debris, expired backups
   branches      List loop-related branches
+  agent-routes  Show / lint agent routing config (.roll/agent-routes.yaml)
 
 Internal (called by roll-loop SKILL):
   notify        Send macOS notification
@@ -6802,8 +7078,8 @@ _loop_on() {
   local agent; agent=$(_project_agent)
 
   local active_start active_end loop_minute dream_hour dream_minute brief_hour brief_minute
-  active_start=$(_config_read_int "loop_active_start" "10")
-  active_end=$(_config_read_int "loop_active_end" "18")
+  local _aw; _aw=$(_loop_read_active_window "$project_path")
+  active_start="${_aw%% *}"; active_end="${_aw##* }"
   # US-LOOP-011: read schedule spec from project or global config
   local loop_spec loop_period loop_offset
   loop_spec=$(_loop_schedule_spec "$project_path")
@@ -6849,10 +7125,10 @@ _loop_on() {
     fi
 
     ok "$(msg loop.loop_enabled)"
-    printf "$(msg loop.roll_loop_s_active_02d_00)" \
+    msg loop.roll_loop_s_active_02d_00 \
       "$loop_sched_en" "$active_start" "$active_end" "$loop_sched_zh" "$active_start" "$active_end"
-    printf "$(msg loop.roll_dream_daily_at_02d_02d)" "$dream_hour" "$dream_minute" "$dream_hour" "$dream_minute"
-    printf "$(msg loop.roll_brief_daily_at_02d_02d)" "$brief_hour" "$brief_minute" "$brief_hour" "$brief_minute"
+    msg loop.roll_dream_daily_at_02d_02d "$dream_hour" "$dream_minute" "$dream_hour" "$dream_minute"
+    msg loop.roll_brief_daily_at_02d_02d "$brief_hour" "$brief_minute" "$brief_hour" "$brief_minute"
     echo "  • Agent: ${agent}  (change: roll agent use <name>)"
     return 0
   fi
@@ -6880,10 +7156,10 @@ _loop_on() {
   ) | crontab -
 
   ok "$(msg loop.loop_enabled_2)"
-  printf "$(msg loop.roll_loop_s_active_02d_00_2)" \
+  msg loop.roll_loop_s_active_02d_00_2 \
     "$loop_sched_en" "$active_start" "$active_end" "$loop_sched_zh" "$active_start" "$active_end"
-  printf "$(msg loop.roll_dream_daily_at_02d_02d_2)" "$dream_hour" "$dream_minute" "$dream_hour" "$dream_minute"
-  printf "$(msg loop.roll_brief_daily_at_02d_02d_2)" "$brief_hour" "$brief_minute" "$brief_hour" "$brief_minute"
+  msg loop.roll_dream_daily_at_02d_02d_2 "$dream_hour" "$dream_minute" "$dream_hour" "$dream_minute"
+  msg loop.roll_brief_daily_at_02d_02d_2 "$brief_hour" "$brief_minute" "$brief_hour" "$brief_minute"
   echo "  • Agent: ${agent}  (change: roll agent use <name>)"
 }
 
@@ -7023,8 +7299,8 @@ _loop_test() {
 
   # FIX-054: terminal preference removed — runner always uses Terminal.app.
   local active_start active_end
-  active_start=$(_config_read_int "loop_active_start" "10")
-  active_end=$(_config_read_int "loop_active_end" "18")
+  local _aw; _aw=$(_loop_read_active_window "$project_path")
+  active_start="${_aw%% *}"; active_end="${_aw##* }"
 
   info "$(msg loop.generating_test_runner_agent ${agent})"
   _write_loop_runner_script "$test_runner" "$project_path" \
@@ -8528,6 +8804,205 @@ _loop_mark_in_progress() {
   ' "$backlog" > "$tmp" && mv "$tmp" "$backlog"
 }
 
+# US-AGENT-008: _loop_mark_hold <story-id> <reason> [backlog-path]
+#   Flip "🔨 In Progress" or "📋 Todo" row to "🚫 Hold" with a parenthetical
+#   reason suffix appended to the description column. Idempotent — if the
+#   row is already 🚫 Hold the call is a no-op (status compare is exact).
+_loop_mark_hold() {
+  local story_id="$1"
+  local reason="${2:-self-downgrade}"
+  local backlog="${3:-${ROLL_MAIN_PROJECT:-$PWD}/.roll/backlog.md}"
+  [ -n "$story_id" ] || return 1
+  [ -f "$backlog" ] || return 0
+  local tmp; tmp=$(mktemp "${backlog}.XXXXXX") || return 1
+  awk -v sid="$story_id" -v reason="$reason" '
+    {
+      line = $0
+      changed = 0
+      if (index(line, "🔨 In Progress") > 0 || index(line, "📋 Todo") > 0) {
+        n = split(line, cols, "|")
+        if (n >= 2) {
+          id_cell = cols[2]
+          gsub(/[[:space:]]/, "", id_cell)
+          sub(/^\[/, "", id_cell)
+          sub(/\].*$/, "", id_cell)
+          if (id_cell == sid) {
+            sub(/🔨 In Progress/, "🚫 Hold", line)
+            sub(/📋 Todo/, "🚫 Hold", line)
+            # Append reason to the description column (cols[3]) only if not
+            # already present.
+            if (index(line, "→ " reason) == 0 && index(line, "(" reason ")") == 0) {
+              # Insert before the trailing " | 🚫 Hold |"
+              sub(/ \| 🚫 Hold \|/, " → " reason " | 🚫 Hold |", line)
+            }
+            changed = 1
+          }
+        }
+      }
+      print line
+    }
+  ' "$backlog" > "$tmp" && mv "$tmp" "$backlog"
+}
+
+# US-AGENT-008: self-downgrade primitive.
+#   _loop_self_downgrade <story-id> <reason> <sub-ids-csv>
+# Flips story to 🚫 Hold (with sub list embedded), writes ALERT, emits a
+# story_self_downgrade event. The actual sub-story rows + feature md are
+# produced by the SKILL invocation of roll-design --from-story (this helper
+# just records the contract).
+_loop_self_downgrade() {
+  local story_id="$1"
+  local reason="${2:-too_big}"
+  local subs="${3:-}"
+  [ -n "$story_id" ] || return 1
+  local backlog="${ROLL_MAIN_PROJECT:-$PWD}/.roll/backlog.md"
+  local annotation
+  if [ -n "$subs" ]; then
+    annotation="split to ${subs}"
+  else
+    annotation="$reason"
+  fi
+  _loop_mark_hold "$story_id" "$annotation" "$backlog" || true
+
+  # ALERT line for human visibility. Slug derives from main project dir.
+  local main_dir="${ROLL_MAIN_PROJECT:-$PWD}"
+  local slug; slug=$(_project_slug "$main_dir" 2>/dev/null || basename "$main_dir")
+  local shared_root="${_SHARED_ROOT:-$HOME/.shared/roll}"
+  local alert_file="${shared_root}/loop/ALERT-${slug}.md"
+  mkdir -p "$(dirname "$alert_file")"
+  printf '[%s] self-downgrade: %s — reason: %s; subs: %s\n' \
+    "$(date -u +%Y-%m-%dT%H:%M:%SZ)" "$story_id" "$reason" "${subs:-<none>}" \
+    >> "$alert_file"
+
+  # Best-effort event emission (tolerates missing helpers).
+  if declare -F _loop_event >/dev/null 2>&1; then
+    _loop_event "agent_self_downgrade" "${LOOP_CYCLE_ID:-$story_id}" "$story_id" "${reason}|${subs}" || true
+  fi
+  echo "[loop] self-downgrade ${story_id}: ${reason}; subs=${subs:-<none>}"
+}
+
+# US-AGENT-009: _loop_chain_depth_cap_check <story-id> [backlog]
+#   Returns 0 when auto re-split is still allowed (story's chain_depth < 2),
+#   1 when the cap is hit (≥ 2 already — the third re-split would be #3 in
+#   the chain). Reads chain_depth from the story's feature md profile;
+#   missing profile is treated as depth 0 (split allowed).
+_loop_chain_depth_cap_check() {
+  local story_id="$1"
+  local backlog="${2:-${ROLL_MAIN_PROJECT:-$PWD}/.roll/backlog.md}"
+  [ -n "$story_id" ] || return 0
+  [ -f "$backlog" ] || return 0
+
+  # Resolve feature md from backlog link.
+  local md_path
+  md_path=$(grep -E "\[${story_id}\]\(" "$backlog" 2>/dev/null \
+    | head -1 \
+    | sed -E "s/.*\[${story_id}\]\(([^)#]+)#?[^)]*\).*/\1/")
+  [ -n "$md_path" ] || return 0
+  [ -f "$md_path" ] || return 0
+
+  # Find the section for this story id and extract chain_depth.
+  local anchor; anchor=$(echo "$story_id" | tr '[:upper:]' '[:lower:]')
+  local depth
+  depth=$(awk -v anchor="$anchor" '
+    /<a id="/ {
+      if (match($0, /<a id="[^"]+"/)) {
+        cur = substr($0, RSTART + 7, RLENGTH - 8)
+        in_section = (cur == anchor)
+      }
+      next
+    }
+    in_section && /^- chain_depth:/ {
+      gsub(/^- chain_depth:[ \t]*/, "")
+      gsub(/[ \t].*$/, "")
+      print
+      exit
+    }
+  ' "$md_path")
+
+  # Empty / non-numeric → treat as 0.
+  case "$depth" in
+    ''|*[!0-9]*) depth=0 ;;
+  esac
+
+  [ "$depth" -lt 2 ]
+}
+
+# US-AGENT-009: cap-hit path. Story has reached chain_depth ≥ 2 — refuse
+# further auto re-split, flip 🚫 Hold + write a high-priority ALERT with
+# chain context for human triage.
+_loop_split_cap_hit() {
+  local story_id="$1"
+  local reason="${2:-cap-hit}"
+  [ -n "$story_id" ] || return 1
+  local backlog="${ROLL_MAIN_PROJECT:-$PWD}/.roll/backlog.md"
+  _loop_mark_hold "$story_id" "StorySplitCapHit: $reason" "$backlog" || true
+
+  local main_dir="${ROLL_MAIN_PROJECT:-$PWD}"
+  local slug; slug=$(_project_slug "$main_dir" 2>/dev/null || basename "$main_dir")
+  local shared_root="${_SHARED_ROOT:-$HOME/.shared/roll}"
+  local alert_file="${shared_root}/loop/ALERT-${slug}.md"
+  mkdir -p "$(dirname "$alert_file")"
+  printf '[%s] StorySplitCapHit: %s — chain_depth >= 2 (third auto-split refused). %s. Human triage required.\n' \
+    "$(date -u +%Y-%m-%dT%H:%M:%SZ)" "$story_id" "$reason" \
+    >> "$alert_file"
+
+  if declare -F _loop_event >/dev/null 2>&1; then
+    _loop_event "story_split_cap_hit" "${LOOP_CYCLE_ID:-$story_id}" "$story_id" "$reason" || true
+  fi
+  echo "[loop] StorySplitCapHit ${story_id}: chain_depth >= 2 — held for human triage"
+}
+
+# US-SKILL-010: unified self-score note writer for roll-build /
+# roll-fix / roll-design. Lands under .roll/notes/ with YAML frontmatter
+# so subsequent stories (US-SKILL-014 trend, US-SKILL-015 docs) can
+# read/aggregate without parsing free text.
+#
+# Args: skill story_id score:int verdict [rationale...]
+_skill_write_self_score() {
+  local skill="${1:-}"
+  local story="${2:-}"
+  local score="${3:-}"
+  local verdict="${4:-}"
+  shift 4 2>/dev/null || true
+  local rationale="${*:-}"
+
+  case "$skill" in
+    roll-build|roll-fix|roll-design) ;;
+    *) err "_skill_write_self_score: skill must be roll-build / roll-fix / roll-design (got '$skill')"; return 1 ;;
+  esac
+  [ -n "$story" ] || { err "_skill_write_self_score: story id required"; return 1; }
+  case "$score" in
+    ''|*[!0-9]*) err "_skill_write_self_score: score must be integer 1..10"; return 1 ;;
+  esac
+  if [ "$score" -lt 1 ] || [ "$score" -gt 10 ]; then
+    err "_skill_write_self_score: score out of range (1..10): $score"
+    return 1
+  fi
+  case "$verdict" in
+    good|ok|regression) ;;
+    *) err "_skill_write_self_score: verdict must be good / ok / regression (got '$verdict')"; return 1 ;;
+  esac
+
+  local notes_dir=".roll/notes"
+  mkdir -p "$notes_dir"
+  local ts; ts=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+  local date_part="${ts%%T*}"
+  local epoch; epoch=$(date -u +%s)
+  local file="${notes_dir}/${date_part}-${skill}-${story}-${epoch}.md"
+
+  {
+    printf -- '---\n'
+    printf 'skill: %s\n' "$skill"
+    printf 'story: %s\n' "$story"
+    printf 'score: %s\n' "$score"
+    printf 'verdict: %s\n' "$verdict"
+    printf 'ts: %s\n' "$ts"
+    printf -- '---\n'
+    printf '\n'
+    printf '%s\n' "$rationale"
+  } > "$file"
+}
+
 # _loop_mark_todo <story-id> [backlog-path]
 #   Revert a row from "🔨 In Progress" back to "📋 Todo". Called when a
 #   cycle's executor fails so the next cycle can pick the story up again.
@@ -9058,6 +9533,218 @@ refs/heads/claude/*"
   return 0
 }
 
+# US-AGENT-002: agent-routes.yaml management.
+# `roll loop agent-routes [show|lint] [path]` — dispatch + helpers.
+# Default path order: $ROLL_AGENT_ROUTES (if set) → ./.roll/agent-routes.yaml
+# → built-in default in templates/agent-routes/default.yaml.
+_loop_agent_routes_path() {
+  if [ -n "${ROLL_AGENT_ROUTES:-}" ] && [ -f "$ROLL_AGENT_ROUTES" ]; then
+    printf '%s\n' "$ROLL_AGENT_ROUTES"
+    return 0
+  fi
+  if [ -f ".roll/agent-routes.yaml" ]; then
+    printf '%s\n' ".roll/agent-routes.yaml"
+    return 0
+  fi
+  # Fallback: built-in default shipped with the package.
+  # ROLL_INSTALL_DIR is set when installed via npm; fall back to script dir.
+  local install_dir
+  install_dir="${ROLL_INSTALL_DIR:-$(dirname "$(dirname "$(readlink -f "${BASH_SOURCE[0]}" 2>/dev/null || echo "$0")")")}"
+  local default_tpl="$install_dir/templates/agent-routes/default.yaml"
+  if [ -f "$default_tpl" ]; then
+    printf '%s\n' "$default_tpl"
+    return 0
+  fi
+  return 1
+}
+
+_loop_agent_routes_show() {
+  local path
+  path=$(_loop_agent_routes_path) || {
+    echo "agent-routes: no config found (set ROLL_AGENT_ROUTES, drop .roll/agent-routes.yaml, or run roll init)" >&2
+    return 1
+  }
+  echo "# source: $path"
+  cat "$path"
+}
+
+_loop_agent_routes_lint() {
+  local path="${1:-}"
+  if [ -z "$path" ]; then
+    path=$(_loop_agent_routes_path) || {
+      echo "agent-routes lint: no config found" >&2
+      return 1
+    }
+  fi
+  if [ ! -f "$path" ]; then
+    echo "agent-routes lint: file not found: $path" >&2
+    return 1
+  fi
+  local install_dir
+  install_dir="${ROLL_INSTALL_DIR:-$(dirname "$(dirname "$(readlink -f "${BASH_SOURCE[0]}" 2>/dev/null || echo "$0")")")}"
+  python3 "$install_dir/lib/agent_routes_lint.py" "$path"
+}
+
+# US-AGENT-006: pick the next eligible 📋 Todo story from .roll/backlog.md
+# applying the same gates as the roll-loop SKILL Step 2:
+#   1. Status = 📋 Todo
+#   2. NOT manual-only:* tagged
+#   3. depends-on:* (if any) all ✅ Done
+#   4. Priority order: FIX > US > REFACTOR
+#
+# stdout: chosen story id (single line)
+# exit 0 when picked, 1 when nothing eligible.
+_loop_pick_next_story() {
+  local backlog="${1:-.roll/backlog.md}"
+  [ -f "$backlog" ] || return 1
+
+  # Two passes over the file, once per type prefix, return first hit.
+  local prefix
+  for prefix in FIX US REFACTOR; do
+    local id
+    while IFS= read -r line; do
+      [ -z "$line" ] && continue
+      # Skip non-Todo rows fast
+      case "$line" in
+        *'📋 Todo'*) ;;
+        *) continue ;;
+      esac
+      # Extract id like FIX-XXX-NNN / US-XXX-NNN / REFACTOR-XXX-NNN.
+      id=$(printf '%s\n' "$line" | grep -oE "${prefix}-[A-Za-z0-9_-]+" | head -1)
+      [ -n "$id" ] || continue
+      # Gate 1: manual-only
+      _loop_is_manual_only "$id" "$backlog" 2>/dev/null && continue
+      # Gate 2: depends-on
+      if ! _loop_check_depends_on "$id" "$backlog" >/dev/null 2>&1; then
+        continue
+      fi
+      printf '%s\n' "$id"
+      return 0
+    done < "$backlog"
+  done
+  return 1
+}
+
+# US-AGENT-004: pick the agent for a given backlog story by reading its
+# Agent profile from the linked feature md and matching against the active
+# agent-routes.yaml. Falls back to history.cold_start_default when no agent
+# matches or the story has no profile.
+#
+# stdout: "<agent> <rule_kind> <rationale...>"
+# exit 0 on success, 1 if the story id isn't found.
+_loop_pick_agent_for_story() {
+  local story_id="${1:-}"
+  if [ -z "$story_id" ]; then
+    echo "_loop_pick_agent_for_story: story id required" >&2
+    return 1
+  fi
+  local routes
+  routes=$(_loop_agent_routes_path 2>/dev/null) || {
+    echo "_loop_pick_agent_for_story: no agent-routes.yaml available" >&2
+    return 1
+  }
+  local backlog=".roll/backlog.md"
+  [ -f "$backlog" ] || {
+    echo "_loop_pick_agent_for_story: $backlog not found" >&2
+    return 1
+  }
+  local install_dir
+  install_dir="${ROLL_INSTALL_DIR:-$(dirname "$(dirname "$(readlink -f "${BASH_SOURCE[0]}" 2>/dev/null || echo "$0")")")}"
+  # US-AGENT-005: pass runs.jsonl when available so history soft preference
+  # can layer on top of hard rules. Project-local first, then shared.
+  local runs_arg=""
+  if [ -f ".roll/runs.jsonl" ]; then
+    runs_arg="--runs .roll/runs.jsonl"
+  elif [ -f "${HOME}/.shared/roll/loop/runs.jsonl" ]; then
+    runs_arg="--runs ${HOME}/.shared/roll/loop/runs.jsonl"
+  fi
+  # shellcheck disable=SC2086
+  python3 "$install_dir/lib/loop_pick_agent.py" \
+    --story-id "$story_id" \
+    --backlog "$backlog" \
+    --routes "$routes" \
+    $runs_arg
+}
+
+# US-QA-012: merge-time test-quality gate. Scan bats files for ❼ + ❽
+# violations; loop auto-merge waits on a clean exit. PR description
+# `[skip-test-quality]` marker → US-QA-013 passes --skip here.
+#
+# Usage:
+#   roll loop test-quality-check [--skip] file.bats [file.bats ...]
+_loop_test_quality_check() {
+  local install_dir
+  install_dir="${ROLL_INSTALL_DIR:-$(dirname "$(dirname "$(readlink -f "${BASH_SOURCE[0]}" 2>/dev/null || echo "$0")")")}"
+  python3 "$install_dir/lib/test_quality_gate.py" "$@"
+}
+
+# US-QA-013: PR description marker check. Returns 0 if the body contains
+# `[skip-test-quality]` (case-insensitive); 1 otherwise.
+_loop_pr_body_has_skip_test_quality() {
+  local body="${1:-}"
+  [ -n "$body" ] || return 1
+  printf '%s' "$body" | grep -qiE '\[skip-test-quality\]'
+}
+
+# US-QA-013: gate + ALERT wrapper. Runs the test-quality gate; on
+# violations writes a structured ALERT-<slug>.md entry so the human (or
+# next brief) sees what blocked auto-merge. The wrapper is the entry
+# point loop calls; it accepts --skip to honor the PR bypass marker.
+_loop_test_quality_check_with_alert() {
+  local skip=0
+  if [ "${1:-}" = "--skip" ]; then
+    skip=1; shift
+  fi
+  if [ "$skip" -eq 1 ]; then
+    return 0
+  fi
+  local install_dir
+  install_dir="${ROLL_INSTALL_DIR:-$(dirname "$(dirname "$(readlink -f "${BASH_SOURCE[0]}" 2>/dev/null || echo "$0")")")}"
+  local report
+  report=$(python3 "$install_dir/lib/test_quality_gate.py" "$@" 2>&1)
+  local rc=$?
+  if [ "$rc" -eq 0 ]; then
+    return 0
+  fi
+
+  local main_dir="${ROLL_MAIN_PROJECT:-$PWD}"
+  local slug; slug=$(_project_slug "$main_dir" 2>/dev/null || basename "$main_dir")
+  local shared_root="${_SHARED_ROOT:-$HOME/.shared/roll}"
+  local alert_file="${shared_root}/loop/ALERT-${slug}.md"
+  mkdir -p "$(dirname "$alert_file")"
+  {
+    printf '[%s] test-quality gate blocked auto-merge (rubric ❼ / ❽).\n' \
+      "$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+    printf '%s\n' "$report"
+    printf 'Bypass: add `[skip-test-quality]` to the PR description and re-run.\n'
+    printf '\n'
+  } >> "$alert_file"
+
+  if declare -F _loop_event >/dev/null 2>&1; then
+    _loop_event "test_quality_gate_block" "${LOOP_CYCLE_ID:-test-quality}" "${1:-}" "$report" || true
+  fi
+  echo "[loop] test-quality gate blocked: see $alert_file" >&2
+  return 1
+}
+
+_loop_agent_routes() {
+  local sub="${1:-show}"; shift || true
+  case "$sub" in
+    show) _loop_agent_routes_show ;;
+    lint) _loop_agent_routes_lint "${1:-}" ;;
+    path) _loop_agent_routes_path ;;
+    *)
+      cat >&2 <<'HELP'
+Usage: roll loop agent-routes <show|lint|path> [path]
+
+  show         Print active agent-routes config (source + content)
+  lint [path]  Validate schema (default: active config). Exit 1 on errors.
+  path         Print which file is currently active.
+HELP
+      return 1 ;;
+  esac
+}
+
 # US-AUTO-033: publish a loop cycle branch as a GitHub PR with auto-merge.
 #
 # _loop_publish_pr <branch> [title]
@@ -9307,8 +9994,8 @@ _loop_monitor() {
     echo -e "$(msg loop.services ${BOLD} ${NC} ${CYAN} ${agent})"
     if [[ "$(uname)" == "Darwin" ]]; then
       local active_start active_end dream_hour dream_minute brief_hour brief_minute
-      active_start=$(_config_read_int "loop_active_start" "10")
-      active_end=$(_config_read_int "loop_active_end" "18")
+      local _aw; _aw=$(_loop_read_active_window "$project_path")
+      active_start="${_aw%% *}"; active_end="${_aw##* }"
       # US-LOOP-013: use schedule spec for display
       local loop_spec loop_period loop_offset
       loop_spec=$(_loop_schedule_spec "$project_path")
@@ -9629,6 +10316,185 @@ cmd_alert() {
   esac
 }
 
+# ═══════════════════════════════════════════════════════════════════════════════
+# FEEDBACK — one-shot GitHub issue from the CLI (US-FB-001)
+# ═══════════════════════════════════════════════════════════════════════════════
+
+# Derive owner/repo from git origin. Returns "" when not a github remote.
+_feedback_origin_repo() {
+  local url
+  url=$(git remote get-url origin 2>/dev/null) || return 0
+  case "$url" in
+    git@github.com:*)
+      url="${url#git@github.com:}"
+      url="${url%.git}"
+      printf '%s\n' "$url"
+      ;;
+    https://github.com/*)
+      url="${url#https://github.com/}"
+      url="${url%.git}"
+      printf '%s\n' "$url"
+      ;;
+    *) printf '\n' ;;
+  esac
+}
+
+# US-FB-003: feedback target repo precedence:
+#   1. --repo flag (caller already resolved this; not part of this helper)
+#   2. ROLL_FEEDBACK_REPO env var
+#   3. .roll/local.yaml `feedback_repo:`
+#   4. ~/.roll/config.yaml `feedback_repo:`
+#   5. origin-derived github owner/repo
+_feedback_yaml_field() {
+  local file="$1" field="$2"
+  [ -f "$file" ] || return 0
+  awk -v key="$field" '
+    $0 ~ "^"key":" {
+      v=$0; sub("^"key":[[:space:]]*", "", v); gsub("^[\"\x27]|[\"\x27]$", "", v); print v; exit
+    }' "$file"
+}
+
+_feedback_default_repo() {
+  if [ -n "${ROLL_FEEDBACK_REPO:-}" ]; then
+    printf '%s\n' "$ROLL_FEEDBACK_REPO"
+    return 0
+  fi
+  local project_local=".roll/local.yaml"
+  local v
+  v=$(_feedback_yaml_field "$project_local" "feedback_repo")
+  if [ -n "$v" ]; then
+    printf '%s\n' "$v"
+    return 0
+  fi
+  local global="${HOME}/.roll/config.yaml"
+  v=$(_feedback_yaml_field "$global" "feedback_repo")
+  if [ -n "$v" ]; then
+    printf '%s\n' "$v"
+    return 0
+  fi
+  _feedback_origin_repo
+}
+
+# Map --type to GitHub label list (single, no spaces).
+_feedback_label_for_type() {
+  case "${1:-}" in
+    bug)  printf 'bug,FIX\n' ;;
+    idea) printf 'idea,enhancement,US\n' ;;
+    ux)   printf 'ux,enhancement\n' ;;
+    *)    printf 'feedback\n' ;;
+  esac
+}
+
+# Percent-encode for use in a GitHub issue URL query string.
+_feedback_urlencode() {
+  python3 -c 'import sys, urllib.parse; print(urllib.parse.quote(sys.argv[1], safe=""))' "$1"
+}
+
+# US-FB-002: compose env info appendix attached to feedback body unless
+# --no-env is set. Single source of truth so future feedback paths
+# (web embedded, slack, etc.) can reuse.
+_feedback_env_block() {
+  local roll_v os_name shell_name agent lang project
+  roll_v="${VERSION:-unknown}"
+  os_name="$(uname -srm 2>/dev/null || echo unknown)"
+  shell_name="$(basename "${SHELL:-/bin/sh}")"
+  agent=$(_project_agent 2>/dev/null || echo "unknown")
+  lang="${LANG:-${LC_ALL:-unknown}}"
+  project="$(basename "$(pwd -P)")"
+  cat <<EOF
+
+---
+
+### Environment
+- roll version: $roll_v
+- OS: $os_name
+- shell: $shell_name
+- current agent: $agent
+- language: $lang
+- project: $project
+EOF
+}
+
+cmd_feedback() {
+  local type="" title="" body="" repo="" print_url=0 attach_env=1
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      --type)      type="$2"; shift 2 ;;
+      --title)     title="$2"; shift 2 ;;
+      --body)      body="$2"; shift 2 ;;
+      --repo)      repo="$2"; shift 2 ;;
+      --no-env)    attach_env=0; shift ;;
+      --print-url) print_url=1; shift ;;
+      --help|-h)
+        cat <<'HELP'
+Usage: roll feedback [options]
+        roll feedback (一句话提反馈)
+
+Open a GitHub issue from the CLI. Type auto-labels (bug → FIX label;
+idea → US label; ux → ux label).
+
+Options:
+  --type <bug|idea|ux>      Classify the feedback (default: bug)
+  --title <text>            Issue title (required)
+  --body <text>             Issue body
+  --repo <owner/repo>       Target repo (default: derived from origin)
+  --no-env                  Skip the auto-attached Environment section
+                            (roll version, OS, agent, language, project)
+  --print-url               Print the prefilled github.com URL instead of
+                            invoking `gh`. Falls back to this automatically
+                            when `gh` is not installed.
+HELP
+        return 0 ;;
+      *)
+        err "feedback: unknown flag $1"
+        return 1 ;;
+    esac
+  done
+
+  if [ -z "$title" ]; then
+    err "feedback: --title is required"
+    return 1
+  fi
+  if [ -z "$type" ]; then
+    type="bug"
+  fi
+  case "$type" in
+    bug|idea|ux) ;;
+    *)
+      err "feedback: unknown --type '$type' (expected one of: bug, idea, ux)"
+      return 1 ;;
+  esac
+
+  if [ -z "$repo" ]; then
+    repo=$(_feedback_default_repo)
+  fi
+  if [ -z "$repo" ]; then
+    err "feedback: cannot derive owner/repo from origin; pass --repo owner/repo"
+    return 1
+  fi
+
+  # US-FB-002: compose final body with optional env appendix.
+  if [ "$attach_env" -eq 1 ]; then
+    body="${body}$(_feedback_env_block)"
+  fi
+
+  local labels; labels=$(_feedback_label_for_type "$type")
+
+  # Decide path: --print-url or gh missing → print URL; else use gh.
+  if [ "$print_url" -eq 1 ] || ! command -v gh >/dev/null 2>&1; then
+    local t_enc b_enc l_enc
+    t_enc=$(_feedback_urlencode "$title")
+    b_enc=$(_feedback_urlencode "$body")
+    l_enc=$(_feedback_urlencode "$labels")
+    printf 'https://github.com/%s/issues/new?title=%s&body=%s&labels=%s\n' \
+      "$repo" "$t_enc" "$b_enc" "$l_enc"
+    return 0
+  fi
+
+  # Real path: gh issue create
+  gh issue create --repo "$repo" --title "$title" --body "$body" --label "$labels"
+}
+
 # ═══════════════════════════════════════════════════════════════════════════════
 # LANG — switch / inspect Roll's UI language (US-I18N-001)
 # ═══════════════════════════════════════════════════════════════════════════════
@@ -10178,8 +11044,8 @@ _legacy_home() {
     crontab -l 2>/dev/null | grep -q "${_LOOP_TAG}:${project_path}" && loop_state="enabled"
   fi
   local active_start active_end dream_hour dream_minute brief_hour brief_minute
-  active_start=$(_config_read_int "loop_active_start" "10")
-  active_end=$(_config_read_int "loop_active_end" "18")
+  local _aw; _aw=$(_loop_read_active_window "$project_path")
+  active_start="${_aw%% *}"; active_end="${_aw##* }"
   # US-LOOP-013: use schedule spec for display
   local loop_spec loop_period loop_offset
   loop_spec=$(_loop_schedule_spec "$project_path")
@@ -10489,6 +11355,7 @@ main() {
     brief)         cmd_brief "$@" ;;
     backlog)       cmd_backlog "$@" ;;
     alert)         cmd_alert "$@" ;;
+    feedback)      cmd_feedback "$@" ;;
     lang)          cmd_lang "$@" ;;
     agent)         cmd_agent "$@" ;;
     ci)            cmd_ci "$@" ;;