@seanyao/roll 2026.511.4 → 2026.511.5

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## v2026.511.5
+- **Fixed**: launchd plist 自动 reload — plist 内容变更且服务已加载时自动 unload + reload，升级 roll 后 loop 服务立即生效，无需手动重启
+- **Improved**: roll loop status/monitor 三态展示 — 区分 ● 运行中 / ⚠ 已安装未加载 / ○ 未安装，并给出对应的自愈操作提示
+
 ## v2026.511.4
 - **Fixed**: roll init 自动重建 launchd runner scripts — 升级 roll 后直接跑 `roll init` 即可迁移到独立 runner，无需手动执行 roll setup 或 roll loop on
 

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.511.4"
+VERSION="2026.511.5"
 ROLL_HOME="${ROLL_HOME:-${HOME}/.roll}"
 ROLL_CONFIG="${ROLL_HOME}/config.yaml"
 ROLL_GLOBAL="${ROLL_HOME}/conventions/global"
@@ -352,6 +352,17 @@ ai_deepseek: ~/.deepseek|AGENTS.md|AGENTS.md
 default_language: zh
 default_project_type: fullstack
 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
+# loop_minute: 5        # omit to auto-derive from project hash
+loop_dream_hour: 3
+# loop_dream_minute: 10 # omit to auto-derive
+loop_brief_hour: 9
+# loop_brief_minute: 15 # omit to auto-derive
+primary_agent: claude
 YAML
     ok "Created: ~/.roll/config.yaml  已创建: ~/.roll/config.yaml"
   fi
@@ -1757,6 +1768,28 @@ _project_slug() {
   printf '%s' "${base}-${hash}"
 }
 
+_config_read_int() {
+  local key="$1" default="$2"
+  local val
+  val=$(grep "^${key}:" "$ROLL_CONFIG" 2>/dev/null | awk '{print $2}' | tr -d '"' | head -1)
+  if [[ "$val" =~ ^[0-9]+$ ]]; then echo "$val"; else echo "$default"; fi
+}
+
+# Derive a minute in [1,55] from project path hash + offset so different projects
+# and different services within a project don't fire at the same time.
+# Offsets used: loop=0, dream=2, brief=4 → always three distinct values (2<55).
+_loop_derive_minute() {
+  local project_path="$1" offset="${2:-0}"
+  local hash_hex
+  if command -v md5 &>/dev/null; then
+    hash_hex=$(printf '%s' "$project_path" | md5 | cut -c1-6)
+  else
+    hash_hex=$(printf '%s' "$project_path" | md5sum | cut -c1-6)
+  fi
+  local hash_dec; hash_dec=$(printf '%d' "0x${hash_hex}")
+  echo $(( (hash_dec + offset) % 55 + 1 ))
+}
+
 _launchd_label() {
   local service="$1" project_path="$2"
   printf 'com.roll.%s.%s' "$service" "$(_project_slug "$project_path")"
@@ -1812,12 +1845,42 @@ _write_runner_script() {
   chmod +x "$script_path"
 }
 
+# Like _write_runner_script but prepends an active window guard.
+# Silently exits when current hour is outside [active_start, active_end).
+_write_loop_runner_script() {
+  local script_path="$1" project_path="$2" cmd="$3" log_path="$4"
+  local active_start="${5:-10}" active_end="${6:-18}"
+  mkdir -p "$(dirname "$script_path")"
+  cat > "$script_path" << SCRIPT
+#!/bin/bash -l
+h=\$(printf '%d' "\$(date +%H)")
+if [ "\$h" -lt ${active_start} ] || [ "\$h" -ge ${active_end} ]; then exit 0; fi
+cd "${project_path}" && ${cmd} >> "${log_path}" 2>&1
+SCRIPT
+  chmod +x "$script_path"
+}
+
 _launchd_is_loaded() {
-  launchctl list "$1" &>/dev/null 2>&1
+  launchctl print-disabled "gui/$(id -u)" 2>/dev/null | grep -qF "\"$1\" => enabled"
+}
+
+_launchd_svc_state() {
+  local svc="$1" project_path="$2"
+  local label; label=$(_launchd_label "$svc" "$project_path")
+  local plist; plist=$(_launchd_plist_path "$svc" "$project_path")
+  if _launchd_is_loaded "$label"; then
+    echo "enabled"
+  elif [[ -f "$plist" ]]; then
+    echo "installed-off"
+  else
+    echo "not-installed"
+  fi
 }
 
 # Install launchd plist files (disabled by default) and runner scripts for
 # a given project path. Idempotent — skips unchanged files. Does NOT load.
+# Schedule times are read from ~/.roll/config.yaml; missing fields are
+# auto-derived from the project path hash so different projects don't contend.
 _install_launchd_plists() {
   local project_path="$1"
   local sd="${ROLL_HOME}/skills"
@@ -1826,12 +1889,22 @@ _install_launchd_plists() {
   mkdir -p "$_LAUNCHD_DIR"
   mkdir -p "${shared}/loop" "${shared}/dream" "${shared}/brief"
 
+  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")
+  loop_minute=$(_config_read_int "loop_minute" "$(_loop_derive_minute "$project_path" 0)")
+  dream_hour=$(_config_read_int "loop_dream_hour" "3")
+  dream_minute=$(_config_read_int "loop_dream_minute" "$(_loop_derive_minute "$project_path" 2)")
+  brief_hour=$(_config_read_int "loop_brief_hour" "9")
+  brief_minute=$(_config_read_int "loop_brief_minute" "$(_loop_derive_minute "$project_path" 4)")
+
   local services=("loop" "dream" "brief")
   local skill_names=("roll-loop" "roll-.dream" "roll-brief")
-  local minutes=("0" "0" "0")
-  local hours=("" "3" "9")
+  local minutes=("$loop_minute" "$dream_minute" "$brief_minute")
+  local hours=("" "$dream_hour" "$brief_hour")
 
   local updated=0
+  local slug; slug=$(_project_slug "$project_path")
   for i in "${!services[@]}"; do
     local svc="${services[$i]}"
     local skill="${skill_names[$i]}"
@@ -1839,18 +1912,27 @@ _install_launchd_plists() {
     local hour="${hours[$i]}"
     local label; label=$(_launchd_label "$svc" "$project_path")
     local plist; plist=$(_launchd_plist_path "$svc" "$project_path")
-    local slug; slug=$(_project_slug "$project_path")
     local runner="${shared}/${svc}/run-${slug}.sh"
     local log="${shared}/${svc}/cron.log"
     local cmd; cmd=$(_agent_skill_cmd "${sd}/${skill}/SKILL.md" 2>/dev/null || echo "roll loop now")
 
-    _write_runner_script "$runner" "$project_path" "cd \"${project_path}\" && ${cmd}" "$log"
+    if [[ "$svc" == "loop" ]]; then
+      _write_loop_runner_script "$runner" "$project_path" "cd \"${project_path}\" && ${cmd}" "$log" "$active_start" "$active_end"
+    else
+      _write_runner_script "$runner" "$project_path" "cd \"${project_path}\" && ${cmd}" "$log"
+    fi
 
     local before=""
     [[ -f "$plist" ]] && before=$(cat "$plist")
     _write_launchd_plist "$plist" "$label" "$project_path" "$minute" "$hour" "$runner"
     local after; after=$(cat "$plist")
-    [[ "$before" != "$after" ]] && updated=$((updated + 1))
+    if [[ "$before" != "$after" ]]; then
+      updated=$((updated + 1))
+      if _launchd_is_loaded "$label"; then
+        launchctl unload "$plist" 2>/dev/null || true
+        launchctl load "$plist" 2>/dev/null || true
+      fi
+    fi
   done
 
   if [[ $updated -gt 0 ]]; then
@@ -1895,6 +1977,15 @@ _loop_on() {
   local project_path; project_path=$(pwd -P)
   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")
+  loop_minute=$(_config_read_int "loop_minute" "$(_loop_derive_minute "$project_path" 0)")
+  dream_hour=$(_config_read_int "loop_dream_hour" "3")
+  dream_minute=$(_config_read_int "loop_dream_minute" "$(_loop_derive_minute "$project_path" 2)")
+  brief_hour=$(_config_read_int "loop_brief_hour" "9")
+  brief_minute=$(_config_read_int "loop_brief_minute" "$(_loop_derive_minute "$project_path" 4)")
+
   if [[ "$(uname)" == "Darwin" ]]; then
     _install_launchd_plists "$project_path" >/dev/null
 
@@ -1903,7 +1994,7 @@ _loop_on() {
       local label; label=$(_launchd_label "$svc" "$project_path")
       if ! _launchd_is_loaded "$label"; then
         all_loaded=false
-        launchctl load "$(_launchd_plist_path "$svc" "$project_path")" 2>/dev/null || true
+        launchctl load -w "$(_launchd_plist_path "$svc" "$project_path")" 2>/dev/null || true
       fi
     done
 
@@ -1912,9 +2003,10 @@ _loop_on() {
     fi
 
     ok "Loop enabled  已启用"
-    echo "  • roll-loop   every hour :00    每小时整点"
-    echo "  • roll-.dream nightly at 03:00  每晚 03:00"
-    echo "  • roll-brief  daily at 09:00    每天 09:00"
+    printf "  • roll-loop   every hour :%02d  active %02d:00–%02d:00  每小时 :%02d（窗口 %02d:00–%02d:00）\n" \
+      "$loop_minute" "$active_start" "$active_end" "$loop_minute" "$active_start" "$active_end"
+    printf "  • roll-.dream daily at %02d:%02d  每天 %02d:%02d\n" "$dream_hour" "$dream_minute" "$dream_hour" "$dream_minute"
+    printf "  • roll-brief  daily at %02d:%02d  每天 %02d:%02d\n" "$brief_hour" "$brief_minute" "$brief_hour" "$brief_minute"
     echo "  • Agent: ${agent}  (change: roll agent use <name>)"
     return 0
   fi
@@ -1934,15 +2026,16 @@ _loop_on() {
 
   (
     crontab -l 2>/dev/null
-    echo "0 * * * * ${loop_cmd} ${_LOOP_TAG}:${project_path}"
-    echo "0 1 * * * ${dream_cmd} ${_LOOP_TAG}:${project_path}"
-    echo "0 8 * * * ${brief_cmd} ${_LOOP_TAG}:${project_path}"
+    printf "%d * * * * %s %s:%s\n" "$loop_minute" "$loop_cmd" "$_LOOP_TAG" "$project_path"
+    printf "%d %d * * * %s %s:%s\n" "$dream_minute" "$dream_hour" "$dream_cmd" "$_LOOP_TAG" "$project_path"
+    printf "%d %d * * * %s %s:%s\n" "$brief_minute" "$brief_hour" "$brief_cmd" "$_LOOP_TAG" "$project_path"
   ) | crontab -
 
   ok "Loop enabled  已启用"
-  echo "  • roll-loop   every hour :00    每小时整点"
-  echo "  • roll-.dream nightly at 03:00  每晚 03:00"
-  echo "  • roll-brief  daily at 09:00    每天 09:00"
+  printf "  • roll-loop   every hour :%02d  active %02d:00–%02d:00  每小时 :%02d（窗口 %02d:00–%02d:00）\n" \
+    "$loop_minute" "$active_start" "$active_end" "$loop_minute" "$active_start" "$active_end"
+  printf "  • roll-.dream daily at %02d:%02d  每天 %02d:%02d\n" "$dream_hour" "$dream_minute" "$dream_hour" "$dream_minute"
+  printf "  • roll-brief  daily at %02d:%02d  每天 %02d:%02d\n" "$brief_hour" "$brief_minute" "$brief_hour" "$brief_minute"
   echo "  • Agent: ${agent}  (change: roll agent use <name>)"
 }
 
@@ -1955,7 +2048,7 @@ _loop_off() {
       local label; label=$(_launchd_label "$svc" "$project_path")
       if _launchd_is_loaded "$label"; then
         any_loaded=true
-        launchctl unload "$(_launchd_plist_path "$svc" "$project_path")" 2>/dev/null || true
+        launchctl unload -w "$(_launchd_plist_path "$svc" "$project_path")" 2>/dev/null || true
       fi
     done
     if ! $any_loaded; then
@@ -1995,16 +2088,24 @@ _loop_status() {
   local project_path; project_path=$(pwd -P)
   local agent; agent=$(_project_agent)
   echo ""
-  local loop_enabled=false
   if [[ "$(uname)" == "Darwin" ]]; then
-    _launchd_is_loaded "$(_launchd_label "loop" "$project_path")" && loop_enabled=true
+    echo -e "  Services   Agent: ${CYAN}${agent}${NC}"
+    for svc in loop dream brief; do
+      local state; state=$(_launchd_svc_state "$svc" "$project_path")
+      case "$state" in
+        enabled)       echo -e "    ${GREEN}${svc}     ● enabled${NC}" ;;
+        installed-off) echo -e "    ${YELLOW}${svc}     ⚠ installed/off${NC}   run: roll loop on" ;;
+        not-installed) echo -e "    ${RED}${svc}     ○ not installed${NC}   run: roll setup" ;;
+      esac
+    done
   else
+    local loop_enabled=false
     crontab -l 2>/dev/null | grep -q "${_LOOP_TAG}:${project_path}" && loop_enabled=true
-  fi
-  if $loop_enabled; then
-    echo -e "  Scheduler  ${GREEN}● enabled${NC}   Agent: ${CYAN}${agent}${NC}"
-  else
-    echo -e "  Scheduler  ${YELLOW}○ disabled${NC}   run: roll loop on"
+    if $loop_enabled; then
+      echo -e "  Scheduler  ${GREEN}● enabled${NC}   Agent: ${CYAN}${agent}${NC}"
+    else
+      echo -e "  Scheduler  ${YELLOW}○ disabled${NC}   run: roll loop on"
+    fi
   fi
   [[ -f "$_LOOP_ALERT" ]] && { echo ""; echo -e "  ${RED}⚠ ALERT:${NC}"; sed 's/^/    /' "$_LOOP_ALERT"; }
   [[ -f "$_LOOP_STATE" ]] && { echo ""; echo "  State:"; sed 's/^/    /' "$_LOOP_STATE"; }
@@ -2095,15 +2196,30 @@ _loop_monitor() {
     # Services status (three services on macOS, single on Linux)
     echo -e "  ${BOLD}Services  服务状态${NC}   Agent: ${CYAN}${agent}${NC}"
     if [[ "$(uname)" == "Darwin" ]]; then
-      local svc_info svc schedule
-      for svc_info in "loop:hourly" "dream:03:00" "brief:09:00"; do
-        svc="${svc_info%%:*}"
-        schedule="${svc_info#*:}"
-        if _launchd_is_loaded "$(_launchd_label "$svc" "$project_path")"; then
-          printf "    ${GREEN}%-8s ● enabled${NC}   (%s)\n" "$svc" "$schedule"
-        else
-          printf "    ${YELLOW}%-8s ○ disabled${NC}  (%s)\n" "$svc" "$schedule"
-        fi
+      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")
+      loop_minute=$(_config_read_int "loop_minute" "$(_loop_derive_minute "$project_path" 0)")
+      dream_hour=$(_config_read_int "loop_dream_hour" "3")
+      dream_minute=$(_config_read_int "loop_dream_minute" "$(_loop_derive_minute "$project_path" 2)")
+      brief_hour=$(_config_read_int "loop_brief_hour" "9")
+      brief_minute=$(_config_read_int "loop_brief_minute" "$(_loop_derive_minute "$project_path" 4)")
+
+      local loop_sched dream_sched brief_sched
+      loop_sched=$(printf "every hour :%02d  active %02d:00–%02d:00" "$loop_minute" "$active_start" "$active_end")
+      dream_sched=$(printf "%02d:%02d" "$dream_hour" "$dream_minute")
+      brief_sched=$(printf "%02d:%02d" "$brief_hour" "$brief_minute")
+
+      local svcs=("loop" "dream" "brief")
+      local scheds=("$loop_sched" "$dream_sched" "$brief_sched")
+      for i in "${!svcs[@]}"; do
+        local svc="${svcs[$i]}" schedule="${scheds[$i]}"
+        local state; state=$(_launchd_svc_state "$svc" "$project_path")
+        case "$state" in
+          enabled)       printf "    ${GREEN}%-8s ● enabled${NC}       (%s)\n" "$svc" "$schedule" ;;
+          installed-off) printf "    ${YELLOW}%-8s ⚠ installed/off${NC}  (%s)  run: roll loop on\n" "$svc" "$schedule" ;;
+          not-installed) printf "    ${RED}%-8s ○ not installed${NC}  (%s)  run: roll setup\n" "$svc" "$schedule" ;;
+        esac
       done
     else
       if crontab -l 2>/dev/null | grep -q "${_LOOP_TAG}:${project_path}"; then
@@ -2248,20 +2364,23 @@ cmd_backlog() {
     return 1
   fi
 
-  local us_items fix_items refactor_items total=0
+  local us_items fix_items refactor_items idea_items total=0
 
   us_items=$(grep -E '^\| \[US-' "$backlog" | grep -F '| 📋 Todo |' || true)
   fix_items=$(grep -E '^\| FIX-' "$backlog" | grep -F '| 📋 Todo |' || true)
   refactor_items=$(grep -E '^\| REFACTOR-' "$backlog" | grep -F '| 📋 Todo |' || true)
+  idea_items=$(grep -E '^\| IDEA-' "$backlog" | grep -F '| 📋 Todo |' || true)
 
-  local us_count fix_count refactor_count
+  local us_count fix_count refactor_count idea_count
   us_count=$(echo "$us_items" | grep -c . || true)
   fix_count=$(echo "$fix_items" | grep -c . || true)
   refactor_count=$(echo "$refactor_items" | grep -c . || true)
+  idea_count=$(echo "$idea_items" | grep -c . || true)
   [[ -z "$us_items" ]] && us_count=0
   [[ -z "$fix_items" ]] && fix_count=0
   [[ -z "$refactor_items" ]] && refactor_count=0
-  total=$(( us_count + fix_count + refactor_count ))
+  [[ -z "$idea_items" ]] && idea_count=0
+  total=$(( us_count + fix_count + refactor_count + idea_count ))
 
   echo ""
   echo -e "  ${BOLD}Pending Backlog  待处理任务${NC}  (${total} items)"
@@ -2300,6 +2419,17 @@ cmd_backlog() {
     echo ""
   fi
 
+  if [[ $idea_count -gt 0 ]]; then
+    echo -e "  ${NC}Ideas  创意  (${idea_count})"
+    while IFS= read -r line; do
+      local id desc
+      id=$(echo "$line" | awk -F'|' '{print $2}' | tr -d ' ')
+      desc=$(echo "$line" | awk -F'|' '{print $3}' | sed 's/^ *//;s/ *$//')
+      printf "    %-14s  %s\n" "$id" "$desc"
+    done <<< "$idea_items"
+    echo ""
+  fi
+
   if [[ $total -eq 0 ]]; then
     echo -e "  ${GREEN}✓ Nothing pending — backlog is clear  暂无待处理任务${NC}"
     echo ""

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seanyao/roll",
-  "version": "2026.511.4",
+  "version": "2026.511.5",
   "description": "Roll — Roll out features with AI agents",
   "scripts": {
     "test": "find tests/unit tests/integration -name '*.bats' | sort | xargs ./tests/helpers/bats-core/bin/bats"

package/skills/roll-design/SKILL.md

@@ -48,8 +48,8 @@ $roll-design "user system design"
 # Split Stories from an existing Plan
 $roll-design --from-plan docs/features/auth-plan.md
 
-# Directly create a Story
-$roll-design --story "user login feature"
+# Directly create a Story (auto-detected as User Story → Slice DDD)
+$roll-design "user login feature"
 ```
 
 ## DDD Depth Scale
@@ -622,7 +622,7 @@ $roll-build US-AUTH-001 → TCR → CI/CD → Deploy
 
 ```
 $roll-debug discovers issue → Suggest creating FIX
-$roll-design --fix "fix login API 404" → Create FIX-AUTH-001
+$roll-design "fix login API 404" → Create FIX-AUTH-001  ← auto-detected as Bug Fix
 $roll-fix FIX-AUTH-001 → Quick fix
 ```
 

package/skills/roll-propose/SKILL.md

@@ -0,0 +1,153 @@
+---
+name: roll-propose
+license: MIT
+allowed-tools: "Read, Glob, Grep, Write, Bash(git:*)"
+description: |
+  Human-triggered product proposal generator. Reads project context (BACKLOG,
+  recent commits, existing skills) and generates 1–3 structured US drafts from
+  a user-facing perspective. Writes to PROPOSALS.md for human review — never
+  directly to BACKLOG. Distinct from roll-.dream (which surfaces technical debt
+  from execution experience); roll-propose thinks in user scenarios and feature
+  gaps.
+---
+
+# roll-propose
+
+> Follows the Architecture Constraints, Development Discipline, and Engineering
+> Common Sense defined in the project AGENTS.md.
+
+Human-triggered skill for product-level feature ideation. Generates structured
+User Story drafts from a product/user perspective and queues them in
+PROPOSALS.md for human approval before entering BACKLOG.
+
+## Distinct from roll-.dream
+
+| | roll-propose | roll-.dream |
+|---|---|---|
+| Triggered by | Human explicitly | Nightly schedule |
+| Perspective | User-facing / product scenarios | Code health / technical debt |
+| Output | PROPOSALS.md (pending approval) | BACKLOG (REFACTOR-XXX) |
+| Thinking style | "What would users want next?" | "What is the code telling us?" |
+
+## When to Use
+
+```
+$roll-propose                   # generate proposals from full context
+$roll-propose 用户反馈里提到了XX  # provide a focus hint
+```
+
+## When Not to Use
+
+- Describing a known defect or broken behavior (use `$roll-idea`)
+- A story is already well-defined and ready to build (use `$roll-build`)
+- Exploring technical architecture or design (use `$roll-design`)
+- Surfacing code-level technical debt (use `$roll-.dream`)
+
+## Behavior
+
+### Step 1 — Gather Context
+
+Read in parallel:
+
+1. `BACKLOG.md` — all existing US-XXX, FIX-XXX, REFACTOR-XXX, IDEA-XXX entries (both Todo and Done) to avoid proposing duplicates
+2. `PROPOSALS.md` (if exists) — already-proposed items (avoid re-proposing rejected or pending ones)
+3. Recent 20 commits via `git log --oneline -20` — what has recently shipped
+4. `skills/` directory listing — what capabilities roll already has
+5. Optional: any focus hint passed by the user
+
+### Step 2 — Think from User Perspective
+
+Frame proposals from the **product engineer / end user** point of view:
+
+- What recurring friction do users of roll face that no current skill addresses?
+- What workflow is partially covered but has visible gaps?
+- What would make the autonomous loop more legible, controllable, or trustworthy to its human owner?
+
+Avoid technical-debt reasoning (that is roll-.dream's domain). Focus on:
+- New user-visible commands or behaviors
+- Improvements to existing UX (output clarity, discoverability, onboarding)
+- Integrations that extend reach (new AI tools, editor support, CI patterns)
+
+### Step 3 — Draft 1–3 Proposals
+
+Generate between 1 and 3 proposals. For each:
+
+```
+## PROPOSAL: {Short title}
+
+**Motivation (why):**
+One to two sentences from the user's perspective explaining the pain or opportunity.
+
+**Target scenario:**
+Concrete usage example — what the user does, what they see, what they gain.
+
+**Acceptance Criteria (draft):**
+- [ ] AC 1
+- [ ] AC 2
+- [ ] AC 3
+
+**Suggested ID:** US-{EPIC}-{NNN}  (best-guess prefix; human assigns final ID)
+**Suggested Epic / Feature:** {name}
+**Estimated complexity:** {S | M | L}
+```
+
+Complexity guide: S = one skill file or small bin/roll change, M = skill + bin/roll + tests, L = multi-file + new infrastructure.
+
+### Step 4 — Write to PROPOSALS.md
+
+Append to `PROPOSALS.md` in the project root (create if absent):
+
+```markdown
+---
+proposed: {YYYY-MM-DD HH:MM}
+status: pending
+---
+
+{proposals from Step 3}
+```
+
+Use `---` as separator between proposal batches. Never overwrite existing content.
+
+### Step 5 — Report
+
+```
+✅ roll-propose: {N} proposal(s) written to PROPOSALS.md
+
+To approve: move the entry to BACKLOG.md and assign a US-XXX ID.
+To reject:  annotate with "Rejected: {reason}" to suppress future re-proposals.
+```
+
+## Output Rules
+
+- Write proposals in the same language as the project's primary documentation (Chinese for this project).
+- Never write directly to BACKLOG.md — PROPOSALS.md is the staging area.
+- If a similar proposal already exists in PROPOSALS.md (pending or rejected), note similarity and skip or merge rather than creating a duplicate.
+- Aim for 2 proposals by default; generate 1 if context is thin, 3 if focus hint suggests a rich area.
+
+## PROPOSALS.md Format
+
+```markdown
+# Roll Proposals
+
+> 待审批提案。批准后手工移入 BACKLOG.md 并分配 US-XXX 编号。
+> 拒绝时在条目末尾注明拒绝原因，防止 Agent 重复提出相似提案。
+
+---
+proposed: 2026-05-11 11:30
+status: pending
+---
+
+## PROPOSAL: ...
+
+...
+
+---
+proposed: 2026-05-08 09:00
+status: rejected
+rejected_reason: 与现有 roll-design 功能重叠，不需要单独技能
+---
+
+## PROPOSAL: ...
+
+...
+```