@seanyao/roll 2026.510.4 → 2026.510.6

package/README.md

@@ -146,7 +146,7 @@ Research → Design → Build → Check → Fix → (loop)
 | Skill | Phase | Description |
 |-------|-------|-------------|
 | `$roll-build` | DESIGN+BUILD | Universal entry: Story ID, fix ID, or free-text fly mode |
-| `$roll-design` | DESIGN | Explore approaches → design solution → write Stories to BACKLOG |
+| `$roll-design` | DESIGN | Multi-turn discuss → [peer review] → DDD model → solution design → [peer review] → write Stories to BACKLOG |
 | `$roll-fix` | FIX | Bug fix / hotfix from BACKLOG |
 | `$roll-jot` | Support | Fast capture a bug or idea into BACKLOG.md |
 | `$roll-spar` | BUILD | Adversarial TDD — Attacker writes tests, Defender writes code |

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.510.4"
+VERSION="2026.510.6"
 ROLL_HOME="${ROLL_HOME:-${HOME}/.roll}"
 ROLL_CONFIG="${ROLL_HOME}/config.yaml"
 ROLL_GLOBAL="${ROLL_HOME}/conventions/global"
@@ -1332,7 +1332,16 @@ _peer_call() {
       output="$(kimi --quiet -p "$prompt" 2>"$stderr_log" || true)"
       ;;
     pi)
-      output="$(pi -p --mode text "$prompt" 2>"$stderr_log" || true)"
+      output="$(pi -p "$prompt" 2>"$stderr_log" || true)"
+      ;;
+    deepseek)
+      output="$(deepseek "$prompt" 2>"$stderr_log" || true)"
+      ;;
+    codex)
+      output="$(codex exec --json --output-last-message "$prompt" 2>"$stderr_log" || true)"
+      ;;
+    opencode)
+      output="$(opencode run "$prompt" 2>"$stderr_log" || true)"
       ;;
     *)
       err "Unsupported peer: $to  不支持的 peer: $to"
@@ -1639,6 +1648,268 @@ cmd_peer_help() {
   echo "  help                Show this help  显示帮助"
 }
 
+# ═══════════════════════════════════════════════════════════════════════════════
+# AGENT — per-project agent configuration
+# ═══════════════════════════════════════════════════════════════════════════════
+
+_project_agent() {
+  if [[ -f ".roll.yaml" ]] && grep -q "^agent:" .roll.yaml 2>/dev/null; then
+    grep "^agent:" .roll.yaml | awk '{print $2}' | tr -d '"' | head -1
+  elif [[ -f "$ROLL_CONFIG" ]] && grep -q "primary_agent:" "$ROLL_CONFIG" 2>/dev/null; then
+    grep "primary_agent:" "$ROLL_CONFIG" | awk '{print $2}' | tr -d '"' | head -1
+  else
+    echo "claude"
+  fi
+}
+
+_agent_run_skill() {
+  local skill="$1"
+  local agent; agent=$(_project_agent)
+  local skill_file="${ROLL_HOME}/skills/${skill}/SKILL.md"
+  [[ -f "$skill_file" ]] || { err "Skill not found: ${skill}"; return 1; }
+  case "$agent" in
+    claude)   claude -p "$(cat "$skill_file")" ;;
+    kimi)     kimi --quiet -p "$(cat "$skill_file")" ;;
+    deepseek) deepseek "$(cat "$skill_file")" ;;
+    pi)       pi -p "$(cat "$skill_file")" ;;
+    codex)    codex exec --json --output-last-message "$(cat "$skill_file")" ;;
+    opencode) opencode run "$(cat "$skill_file")" ;;
+    *)        err "Unknown agent '${agent}'. Run: roll agent use <claude|kimi|deepseek|pi|codex|opencode>"; return 1 ;;
+  esac
+}
+
+cmd_agent() {
+  local subcmd="${1:-}"; shift || true
+  case "$subcmd" in
+    use)
+      local name="${1:-}"
+      [[ -z "$name" ]] && { err "Usage: roll agent use <claude|kimi|deepseek|pi|codex|opencode>"; exit 1; }
+      command -v "$name" &>/dev/null || warn "${name} not found in PATH — setting anyway  未找到，仍写入配置"
+      if [[ -f ".roll.yaml" ]] && grep -q "^agent:" .roll.yaml; then
+        local tmp; tmp=$(mktemp) && sed "s/^agent:.*/agent: ${name}/" .roll.yaml > "$tmp" && mv "$tmp" .roll.yaml
+      else
+        echo "agent: ${name}" >> .roll.yaml
+      fi
+      ok "Agent set to ${name} for this project  当前项目 agent 已设为 ${name}"
+      local project_path; project_path=$(pwd -P)
+      crontab -l 2>/dev/null | grep -q "roll-loop:${project_path}" && \
+        info "Takes effect on next scheduled run — or: roll loop now"
+      ;;
+    list)
+      echo ""; echo "  Available agents  可用 agent:"; echo ""
+      local current; current=$(_project_agent)
+      for a in claude kimi deepseek opencode codex pi; do
+        if command -v "$a" &>/dev/null; then
+          [[ "$a" == "$current" ]] && echo -e "    ${GREEN}✓ ${a}${NC}  (current)" \
+                                   || echo -e "    ${GREEN}✓ ${a}${NC}"
+        else
+          echo -e "    ${YELLOW}✗ ${a}${NC}  (not installed)"
+        fi
+      done; echo ""
+      ;;
+    "")
+      local agent; agent=$(_project_agent)
+      local src="global"; [[ -f ".roll.yaml" ]] && grep -q "^agent:" .roll.yaml 2>/dev/null && src="project (.roll.yaml)"
+      echo -e "\n  Agent  ${CYAN}${agent}${NC}  (${src})\n"
+      echo "  roll agent use <name>   — switch agent for this project"
+      echo "  roll agent list         — show installed agents"; echo ""
+      ;;
+    *) err "Unknown subcommand: $subcmd"; echo "Usage: roll agent [use <name>|list]"; exit 1 ;;
+  esac
+}
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# LOOP — autonomous BACKLOG executor management
+# ═══════════════════════════════════════════════════════════════════════════════
+
+_LOOP_TAG="# roll-loop"
+_LOOP_STATE="${HOME}/.shared/roll/loop/state.yaml"
+_LOOP_ALERT="${HOME}/.shared/roll/loop/ALERT.md"
+
+_agent_skill_cmd() {
+  local skill_path="$1"
+  local agent; agent=$(_project_agent)
+  case "$agent" in
+    claude)   echo "claude -p \"\$(cat '${skill_path}')\"" ;;
+    kimi)     echo "kimi --quiet -p \"\$(cat '${skill_path}')\"" ;;
+    deepseek) echo "deepseek \"\$(cat '${skill_path}')\"" ;;
+    pi)       echo "pi -p \"\$(cat '${skill_path}')\"" ;;
+    codex)    echo "codex exec --json --output-last-message \"\$(cat '${skill_path}')\"" ;;
+    opencode) echo "opencode run \"\$(cat '${skill_path}')\"" ;;
+    *)        err "Unknown agent '${agent}'. Run: roll agent use <claude|kimi|deepseek|pi|codex|opencode>"; return 1 ;;
+  esac
+}
+
+cmd_loop() {
+  local subcmd="${1:-status}"; shift || true
+  case "$subcmd" in
+    on)     _loop_on ;;
+    off)    _loop_off ;;
+    now)    _loop_now ;;
+    status) _loop_status ;;
+    resume) _loop_resume ;;
+    reset)  _loop_reset ;;
+    *) err "Usage: roll loop <on|off|now|status|resume|reset>"; exit 1 ;;
+  esac
+}
+
+_loop_on() {
+  local project_path; project_path=$(pwd -P)
+  local agent; agent=$(_project_agent)
+  local sd="${ROLL_HOME}/skills"
+
+  if crontab -l 2>/dev/null | grep -q "${_LOOP_TAG}:${project_path}"; then
+    warn "Loop already enabled for this project  当前项目 loop 已启用"; return 0
+  fi
+
+  mkdir -p ~/.shared/roll/{loop,dream,brief}
+
+  local loop_cmd dream_cmd brief_cmd
+  loop_cmd="cd \"${project_path}\" && $(_agent_skill_cmd "${sd}/roll-loop/SKILL.md") >> ~/.shared/roll/loop/cron.log 2>&1"
+  dream_cmd="cd \"${project_path}\" && $(_agent_skill_cmd "${sd}/roll-.dream/SKILL.md") >> ~/.shared/roll/dream/cron.log 2>&1"
+  brief_cmd="cd \"${project_path}\" && $(_agent_skill_cmd "${sd}/roll-brief/SKILL.md") >> ~/.shared/roll/brief/cron.log 2>&1"
+
+  (
+    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}"
+  ) | crontab -
+
+  ok "Loop enabled  已启用"
+  echo "  • roll-loop   every hour :00    每小时整点"
+  echo "  • roll-.dream nightly at 01:00  每晚 01:00"
+  echo "  • roll-brief  daily at 08:00    每天 08:00"
+  echo "  • Agent: ${agent}  (change: roll agent use <name>)"
+}
+
+_loop_off() {
+  local project_path; project_path=$(pwd -P)
+  if ! crontab -l 2>/dev/null | grep -q "${_LOOP_TAG}:${project_path}"; then
+    warn "Loop not enabled for this project  当前项目 loop 未启用"; return 0
+  fi
+  crontab -l 2>/dev/null | grep -v "${_LOOP_TAG}:${project_path}" | crontab -
+  ok "Loop disabled  已停用"
+}
+
+_loop_now() {
+  if [[ -f "$_LOOP_STATE" ]] && grep -q "status: running" "$_LOOP_STATE" 2>/dev/null; then
+    warn "Loop already running  loop 正在运行中"; return 0
+  fi
+  info "Triggering loop cycle...  正在触发一个周期..."
+  _agent_run_skill "roll-loop"
+}
+
+_loop_status() {
+  local project_path; project_path=$(pwd -P)
+  local agent; agent=$(_project_agent)
+  echo ""
+  if crontab -l 2>/dev/null | grep -q "${_LOOP_TAG}:${project_path}"; then
+    echo -e "  Scheduler  ${GREEN}● enabled${NC}   Agent: ${CYAN}${agent}${NC}"
+  else
+    echo -e "  Scheduler  ${YELLOW}○ disabled${NC}   run: roll loop on"
+  fi
+  [[ -f "$_LOOP_ALERT" ]] && { echo ""; echo -e "  ${RED}⚠ ALERT:${NC}"; sed 's/^/    /' "$_LOOP_ALERT"; }
+  [[ -f "$_LOOP_STATE" ]] && { echo ""; echo "  State:"; sed 's/^/    /' "$_LOOP_STATE"; }
+  echo ""
+}
+
+_loop_resume() {
+  if [[ ! -f "$_LOOP_STATE" ]]; then
+    warn "No loop state found — nothing to resume  未找到 loop 状态，无需恢复"; return 0
+  fi
+  if grep -q "status: running" "$_LOOP_STATE" 2>/dev/null; then
+    warn "Loop already running  loop 正在运行中"; return 0
+  fi
+  info "Resuming loop from last state...  正在从上次状态恢复..."
+  _agent_run_skill "roll-loop"
+}
+
+_loop_reset() {
+  if [[ -f "$_LOOP_STATE" ]]; then
+    rm -f "$_LOOP_STATE"
+    ok "Loop state cleared — will start fresh on next run  loop 状态已清除，下次运行将重新开始"
+  else
+    info "No loop state to clear  无 loop 状态可清除"
+  fi
+}
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# BRIEF — owner-facing project digest
+# ═══════════════════════════════════════════════════════════════════════════════
+
+cmd_brief() {
+  local briefs_dir="docs/briefs"
+  local latest; latest=$(ls "${briefs_dir}"/*.md 2>/dev/null | sort | tail -1 || true)
+
+  if [[ -z "$latest" ]]; then
+    info "No brief yet — generating...  暂无简报，正在生成..."
+    _agent_run_skill "roll-brief"
+    latest=$(ls "${briefs_dir}"/*.md 2>/dev/null | sort | tail -1 || true)
+  else
+    local mod_time now age
+    mod_time=$(stat -c %Y "$latest" 2>/dev/null || stat -f %m "$latest" 2>/dev/null || echo 0)
+    now=$(date +%s); age=$(( now - mod_time ))
+    if (( age > 86400 )); then
+      info "Brief is $(( age / 3600 ))h old — regenerating...  简报已 $(( age / 3600 )) 小时未更新，重新生成..."
+      _agent_run_skill "roll-brief"
+      latest=$(ls "${briefs_dir}"/*.md 2>/dev/null | sort | tail -1 || true)
+    fi
+  fi
+
+  [[ -f "$latest" ]] && cat "$latest"
+}
+
+cmd_release() {
+  local script="scripts/release.sh"
+  if [[ ! -f "$script" ]]; then
+    err "scripts/release.sh not found — run this command from the roll project root."
+    exit 1
+  fi
+  # Sync CHANGELOG.md before releasing, using the configured agent
+  local last_tag; last_tag=$(git tag --sort=-version:refname | grep "^v" | head -1)
+  if [[ -n "$last_tag" ]] && ! git diff "${last_tag}..HEAD" --name-only | grep -q "CHANGELOG.md"; then
+    info "CHANGELOG.md not updated since ${last_tag}, syncing via $(_project_agent)..."
+    _agent_run_skill "roll-.changelog"
+  fi
+  bash "$script" "$@"
+}
+
+# ─────────────────────────────────────────────────────────────────────────────
+
+_dashboard() {
+  local project_path; project_path=$(pwd -P)
+  local project_name; project_name=$(basename "$project_path")
+  local agent; agent=$(_project_agent)
+
+  echo -e "\n  ${BOLD}${CYAN}${project_name}${NC}  ${YELLOW}v${VERSION}${NC}\n"
+
+  if crontab -l 2>/dev/null | grep -q "${_LOOP_TAG}:${project_path}"; then
+    echo -e "  Loop  ${GREEN}● on${NC}   Agent: ${CYAN}${agent}${NC}"
+  else
+    echo -e "  Loop  ${YELLOW}○ off${NC}   run: roll loop on"
+  fi
+  [[ -f "$_LOOP_ALERT" ]] && echo -e "  ${RED}⚠ ALERT — run: roll loop status${NC}"
+
+  local briefs_dir="docs/briefs"
+  local latest; latest=$(ls "${briefs_dir}"/*.md 2>/dev/null | sort | tail -1 || true)
+  if [[ -n "$latest" ]]; then
+    local mod_time now age
+    mod_time=$(stat -c %Y "$latest" 2>/dev/null || stat -f %m "$latest" 2>/dev/null || echo 0)
+    now=$(date +%s); age=$(( (now - mod_time) / 3600 ))
+    echo -e "\n  Brief  ${CYAN}$(basename "$latest")${NC}  (${age}h ago)"
+    grep -A1 "## Release Readiness" "$latest" 2>/dev/null | tail -1 | sed 's/^/  /'
+    echo ""
+    echo "  run: roll brief   for full brief"
+  else
+    echo -e "\n  No brief yet — run: roll brief"
+  fi
+
+  echo ""
+  echo "  roll loop on|off|now|status|resume|reset · roll brief · roll agent use <name>"
+  echo ""
+}
+
 # ═══════════════════════════════════════════════════════════════════════════════
 # MAIN
 # ═══════════════════════════════════════════════════════════════════════════════
@@ -1661,11 +1932,17 @@ usage() {
   echo "  init                   [Project] Create AGENTS.md + BACKLOG.md + docs/     初始化项目工作流文件"
   echo "  status                 [Diagnostic] Show current state                    显示当前状态"
   echo "  peer                   [Peer Review] Cross-agent negotiation               跨 Agent 协商对审"
+  echo "  loop <on|off|now|status|resume|reset>  [Autonomous] Manage scheduled BACKLOG executor  管理自主执行循环"
+  echo "  brief                  [Digest] Show latest owner brief (regenerate if stale)  展示最新简报"
+  echo "  agent [use <name>|list]   [Config] Per-project agent selection            切换项目 agent"
   echo ""
   echo "Examples / 示例:"
   echo "  roll setup                    # New machine: first-time install            新机器首次安装"
   echo "  roll update                   # Upgrade to latest version + re-sync         升级到最新版并重新同步"
   echo "  roll init                     # New or re-merge project (run in project)   新建或重新合并（项目目录）"
+  echo "  roll loop on                  # Enable autonomous loop (cron)              启用自主执行循环"
+  echo "  roll brief                    # Show latest brief                          查看最新简报"
+  echo "  roll agent use kimi           # Switch this project to kimi               切换当前项目到 kimi"
 
 }
 
@@ -1679,9 +1956,13 @@ main() {
     init)          cmd_init "$@" ;;
     status)        cmd_status "$@" ;;
     peer)          cmd_peer "$@" ;;
+    loop)          cmd_loop "$@" ;;
+    brief)         cmd_brief "$@" ;;
+    agent)         cmd_agent "$@" ;;
+    release)       cmd_release "$@" ;;
     version|--version|-v) echo "roll v${VERSION}" ;;
     help|--help|-h) usage ;;
-    "") usage; _show_changelog ;;
+    "") [[ -f "BACKLOG.md" ]] && _dashboard || { usage; _show_changelog; } ;;
     *)
       err "Unknown command: $cmd  未知命令: $cmd"
       echo ""

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seanyao/roll",
-  "version": "2026.510.4",
+  "version": "2026.510.6",
   "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-.dream/SKILL.md

@@ -0,0 +1,158 @@
+---
+hidden: true
+name: roll-.dream
+license: MIT
+allowed-tools: "Read, Glob, Grep, Bash(git:*), Write, Edit"
+description: |
+  Nightly code and architecture health scan. Passively triggered by scheduler
+  (cron or GitHub Actions), not invoked by users directly. Detects dead code,
+  architectural drift from domain model, pruning candidates, and emerging patterns.
+  Outputs REFACTOR entries to BACKLOG.md and a daily log to docs/dream/.
+  Distinct from roll-sentinel: sentinel monitors runtime behavior; dream reviews
+  code structure and architectural health.
+---
+
+# Roll Dream (Nightly Code Health Scan)
+
+> Follows the Architecture Constraints, Development Discipline, and Engineering
+> Common Sense defined in the project AGENTS.md.
+
+**Passively triggered — do not invoke manually.** Runs nightly via scheduler.
+Consolidates structural signals accumulated during the day, surfaces technical
+debt, and writes REFACTOR entries to BACKLOG. The human reviews the dream log
+in the morning brief.
+
+## Distinction from roll-sentinel
+
+| | roll-sentinel | roll-.dream |
+|--|--------------|------------|
+| **Trigger** | Post-deploy, scheduled patrol | Nightly, fixed schedule |
+| **Target** | Runtime behavior (production) | Code structure (codebase) |
+| **Output** | FIX entries | REFACTOR entries + dream log |
+| **Question** | "Is the product working?" | "Is the code healthy?" |
+
+## Scan Logic
+
+Run all four scans every night. Each scan is independent.
+
+### Scan 1 — Dead Code
+
+Find code that is defined but never referenced:
+
+```bash
+# Unused exports (TypeScript/JS)
+grep -r "^export " src/ --include="*.ts" -l | while read f; do
+  symbol=$(grep -o "export \(function\|const\|class\|type\|interface\) [A-Za-z]*" "$f" | awk '{print $NF}')
+  # check if symbol appears anywhere else in the codebase
+done
+
+# Unused files (no imports pointing to them)
+# Git: files not touched in 90+ days and not imported anywhere
+git log --since="90 days ago" --name-only --format="" | sort -u > /tmp/recently_touched
+```
+
+Flag: files or exports with zero references outside their own file.
+
+### Scan 2 — Architectural Drift
+
+Compare current code structure against the domain model in `docs/domain/`:
+
+```bash
+# Read context-map.md and ubiquitous-language.md if they exist
+# Check: do module/directory names match Bounded Context names?
+# Check: do cross-module imports respect Context boundaries?
+# Check: do any modules import directly across Context lines without ACL?
+```
+
+Flag: modules that import directly from a different Bounded Context without
+an Anti-Corruption Layer, or module names that have diverged from the
+Ubiquitous Language.
+
+### Scan 3 — Pruning Candidates
+
+Find over-engineering that can be simplified:
+
+```bash
+# Abstractions with only one implementation
+grep -r "interface \|abstract class " src/ --include="*.ts" -l
+
+# Wrapper functions that do nothing but delegate
+# Config flags that are never toggled (always true or always false)
+# Error handling for paths that cannot occur
+```
+
+Flag: interfaces with exactly one implementor, feature flags frozen to one
+value, wrapper layers with no logic.
+
+### Scan 4 — Emerging Patterns
+
+Find repeated structures that warrant extraction:
+
+```bash
+# Duplicated code blocks (>10 lines, similar structure)
+# Similar file structures across multiple modules
+# Repeated try/catch patterns with identical handling
+```
+
+Flag: any pattern appearing 3+ times that could be extracted into a shared
+utility or convention.
+
+## Output
+
+### REFACTOR Entry (BACKLOG.md)
+
+For each finding that warrants action, append one row to the `## ♻️ Refactor`
+section of BACKLOG.md:
+
+```markdown
+| REFACTOR-XXX | {one-line description} — flagged by dream {YYYY-MM-DD} | 📋 Todo |
+```
+
+**Threshold**: only flag items where the fix would meaningfully reduce
+complexity or prevent future bugs. Ignore cosmetic issues.
+
+### Dream Log (docs/dream/YYYY-MM-DD.md)
+
+Always write a log, even when no REFACTOR entries are created:
+
+```markdown
+# Dream Log {YYYY-MM-DD}
+
+## Summary
+- Scans run: Dead Code / Architectural Drift / Pruning / Patterns
+- Findings: {N} flagged, {M} REFACTOR entries created
+
+## Dead Code
+{finding or "Nothing flagged."}
+
+## Architectural Drift
+{finding or "No drift detected."}
+
+## Pruning Candidates
+{finding or "Nothing flagged."}
+
+## Emerging Patterns
+{finding or "No patterns detected."}
+
+## REFACTOR Entries Created
+{list or "None."}
+```
+
+## Scheduler Configuration
+
+roll-.dream runs **locally** — it reads the local codebase directly.
+
+### Local cron (default)
+
+Installed automatically via `roll loop on` alongside roll-loop and roll-brief.
+The cron entry is generated using the configured agent — no manual cron editing needed.
+
+## Failure Handling
+
+If the scan fails partway through:
+
+1. Write partial results to `docs/dream/YYYY-MM-DD.md` with a `## Status: PARTIAL` header
+2. Do not write incomplete REFACTOR entries to BACKLOG
+3. Log the error to `~/.shared/roll/dream/error.log`
+
+The scheduler (not this skill) is responsible for retry and human notification.

package/skills/roll-brief/SKILL.md

@@ -0,0 +1,159 @@
+---
+name: roll-brief
+license: MIT
+allowed-tools: "Read, Glob, Grep, Write, Bash(git:*)"
+description: |
+  Owner-facing briefing generator. Summarizes what the agent has done since
+  the last brief: completed US/FIX/REFACTOR, in-progress items, BACKLOG queue
+  status, escalations requiring human attention, and a release-readiness verdict.
+  Three trigger modes: auto on Feature completion, daily morning schedule,
+  or manual $roll-brief invocation. Distinct from roll-.changelog (user-facing
+  release notes) — this is an internal digest for the product owner.
+---
+
+# Roll Brief
+
+> Follows the Architecture Constraints, Development Discipline, and Engineering
+> Common Sense defined in the project AGENTS.md.
+
+Owner-facing digest of autonomous agent activity. Gives the human everything
+needed to decide whether to run `roll-release` — without having to read every
+commit or diff.
+
+## Distinct from roll-.changelog
+
+| | roll-brief | roll-.changelog |
+|--|-----------|----------------|
+| **Audience** | Product owner (internal) | End users (public) |
+| **Content** | All activity including REFACTOR, escalations, health signals | Only user-visible feature changes |
+| **Trigger** | Feature completion / daily / on-demand | Post-deploy |
+| **Tone** | Operational, candid | Product-facing, polished |
+
+## Trigger Modes
+
+### 1. Feature Completion (auto)
+
+Triggered by `roll-loop` when a set of related Stories under one Feature are
+all marked ✅ Done. The loop passes the Feature name as context.
+
+### 2. Daily Morning (scheduled)
+
+Runs at a fixed time each morning (configurable in `~/.roll/config.yaml`).
+Covers all activity since the previous brief.
+
+```yaml
+# ~/.roll/config.yaml
+brief:
+  daily_time: "08:00"   # local time
+  timezone: "Asia/Shanghai"
+```
+
+### 3. On-Demand
+
+```bash
+$roll-brief                    # since last brief
+$roll-brief --since 2026-05-09 # since specific date
+$roll-brief --feature auth     # scoped to one feature
+```
+
+## Workflow
+
+### Step 1 — Determine Scope
+
+```bash
+# Find timestamp of last brief
+ls docs/briefs/ | sort | tail -1
+
+# Read BACKLOG.md — collect all status changes since last brief
+# Read git log — commits since last brief timestamp
+git log --since="{last_brief_timestamp}" --oneline
+```
+
+### Step 2 — Collect Activity
+
+From BACKLOG.md and git log, classify all items since last brief:
+
+- **Completed**: US-XXX ✅, FIX-XXX ✅, REFACTOR-XXX ✅
+- **In progress**: items currently 🔨
+- **Queue**: items still 📋 Todo (ordered by priority)
+- **Dream findings**: any REFACTOR entries added by roll-.dream since last brief
+- **Escalations**: any ALERT files in `~/.shared/roll/loop/` or `~/.shared/roll/dream/`
+
+### Step 3 — Assess Release Readiness
+
+A simple heuristic — not a gate, just a signal for the human:
+
+```
+✅ Release candidate if:
+  - No 🔨 in-progress US items
+  - No open ESCALATE alerts
+  - CI is green (check latest workflow run)
+  - No critical REFACTOR entries flagged in last 48h
+
+⚠️  Hold if any of the above is false
+```
+
+### Step 4 — Write Brief
+
+Output to `docs/briefs/YYYY-MM-DD-HH.md`:
+
+```markdown
+# Brief {YYYY-MM-DD HH:mm}
+
+## What's Done
+| ID | Description | Type |
+|----|-------------|------|
+| US-XXX | {title} | Story |
+| FIX-XXX | {title} | Fix |
+| REFACTOR-XXX | {title} | Refactor |
+
+## In Progress
+| ID | Description |
+|----|-------------|
+| US-XXX | {title} — started {date} |
+
+## Queue ({N} items)
+| ID | Description | Priority |
+|----|-------------|----------|
+| US-XXX | {title} | high |
+
+## Overnight Dream Findings
+{summary from docs/dream/ since last brief, or "No new findings."}
+
+## Escalations Requiring Human Input
+{any alerts, or "None — agent operating normally."}
+
+## Release Readiness
+{✅ Release candidate / ⚠️ Hold — reason}
+
+---
+*Next scheduled brief: {datetime}*
+```
+
+### Step 5 — Notify
+
+After writing the file, print the brief path so it's visible in the terminal
+or CI log:
+
+```
+📋 Brief written: docs/briefs/2026-05-10-08.md
+   Release readiness: ✅ Release candidate
+```
+
+If there are escalations, print them prominently so they're impossible to miss.
+
+## Scheduler Configuration
+
+roll-brief runs **locally**, triggered either by roll-loop (on Feature
+completion) or by local cron (daily morning). The agent reads local
+BACKLOG state and git history directly.
+
+### Local cron (daily morning)
+
+Installed automatically via `roll loop on` alongside roll-loop and roll-.dream.
+The cron entry is generated using the configured agent — no manual cron editing needed.
+
+### Triggered by roll-loop
+
+When roll-loop detects a Feature is fully complete, it invokes roll-brief
+automatically — no separate cron entry needed for that trigger.

package/skills/roll-build/SKILL.md

@@ -263,6 +263,43 @@ MICRO-STEP {N}: {description of smallest testable change}
 
 Accumulate 3–5 micro-commits per Action. Each commit is a guaranteed working state.
 
+#### Architectural Friction Signal (non-blocking)
+
+While implementing, watch for these signals:
+
+- This Action requires touching code in 3+ unrelated modules
+- The existing module boundary has to be bent or bypassed to make this work
+- A data structure or interface needs to change in a way that ripples across contexts
+- The implementation feels "wrong" even when the test passes
+
+When any signal appears, **do not stop — flag it**:
+
+```bash
+# 1. Append to BACKLOG.md under ## ♻️ Refactor
+# REFACTOR-XXX | <one-line description> | 📋 Todo
+
+# 2. Append a brief entry to docs/features/refactor-log.md
+```
+
+**REFACTOR entry format in BACKLOG.md:**
+
+```markdown
+| REFACTOR-001 | Extract payment boundary — leaking into Order module during US-AUTH-003 | 📋 Todo |
+```
+
+**refactor-log.md entry format:**
+
+```markdown
+## REFACTOR-001 Extract payment boundary
+
+**Flagged**: {YYYY-MM-DD} during US-XXX
+**Signal**: {which friction signal triggered this}
+**Observation**: {1–3 sentences describing what felt wrong}
+**Suggested scope**: {rough sense of what a fix would touch}
+```
+
+Then continue implementing the current Story normally.
+
 ### Phase 5.5: E2E Deposit
 
 After TCR micro-steps pass, deposit an E2E test for this Story's core user flow.
@@ -480,6 +517,9 @@ git push
 
 ### Phase 12: Report & Celebrate
 
+**Before reporting, run `$roll-.changelog`** to sync completed Story to CHANGELOG.md.
+This is mandatory — release notes depend on it.
+
 ```
 ✅ Pushed to GitHub: origin/main
 🚀 Deployed: <url>
@@ -564,7 +604,7 @@ Before creating any file or directory:
 - [ ] **Verification Gate passed** (fresh evidence for tests, build, deploy, no regression)
 - [ ] **BACKLOG.md index status updated** (📋 → ✅, REQUIRED)
 - [ ] **`docs/features/<feature>.md` US section updated** (Completed date + [x] ACs, REQUIRED)
-- [ ] **CHANGELOG.md updated** via `$roll-.changelog`
+- [ ] **CHANGELOG.md updated** via `$roll-.changelog` (REQUIRED)
 - [ ] Summary reported to user
 
 ---

package/skills/roll-design/SKILL.md

@@ -144,6 +144,13 @@ User Input
               │ Approach confirmed
               ▼
 ┌─────────────────────────────┐
+│ [peer] Direction Review     │  ← if complexity=large or cross-context; 10s opt-out
+│    Skill("roll-peer",       │
+│      tag="architecture")    │
+└─────────────┬───────────────┘
+              │ AGREE / skipped
+              ▼
+┌─────────────────────────────┐
 │ 2. Analyze + DDD Depth      │  ← Detect scope: Greenfield / Story / Fix
 │    - Requirement analysis    │
 │    - Feasibility assessment  │
@@ -208,6 +215,12 @@ User Input
                                  │
                                  ▼
               ┌─────────────────────────────────────────┐
+              │ [peer] Plan Review                       │  ← if complexity=large; 10s opt-out
+              │    Skill("roll-peer", tag="architecture")│
+              └──────────────────┬──────────────────────┘
+                                 │ AGREE / skipped
+                                 ▼
+              ┌─────────────────────────────────────────┐
               │ 4. Split into Stories                    │
               │    - INVEST principles                   │
               │    - Bounded Context → US domain prefix  │
@@ -435,6 +448,60 @@ Domain: Order Context > Order Aggregate > OrderItem Entity
 - More than 2 viable technical paths exist
 - Requirement involves an unfamiliar tech stack or new domain
 
+### How to Conduct the Discussion
+
+Discuss is **multi-turn by default**. The goal is to reach clarity together, not to produce a complete comparison matrix in one shot.
+
+**Step 1 — Understand before proposing**
+
+Before listing options, make sure the core problem is clear. If context is thin, ask 1–2 focused questions first:
+
+```
+Before I lay out the options — can you tell me [specific constraint / scale / existing system boundary]?
+```
+
+Only skip this if the context is already rich enough to reason from.
+
+**Step 2 — Offer an opinionated starting point, not a menu**
+
+Don't dump 4 options at once. Lead with a concrete recommendation and the key tradeoff:
+
+```
+My read: go with X. The main tradeoff is [Y vs Z]. Want me to walk through why, or should I compare against [alternative] first?
+```
+
+Then wait. Let the user redirect.
+
+**Step 3 — Follow the thread**
+
+If the user wants to dig into a specific option or challenge an assumption, stay on that thread. Don't pivot back to the full comparison until the current thread is resolved.
+
+**Step 4 — Surface hidden assumptions explicitly**
+
+When a direction starts to crystallize, name the assumptions holding it up:
+
+```
+This only holds if [assumption]. Is that true for your situation?
+```
+
+**Step 5 — Name convergence before triggering the gate**
+
+When the discussion reaches a clear conclusion, summarize it explicitly before asking to proceed:
+
+```
+Looks like we've landed on: [decision]. The key reasons: [1–2 points].
+```
+
+Then trigger the gate.
+
+**Gate rule** — after convergence is named, always end with this explicit prompt and **wait for user reply before proceeding**:
+
+```
+➡️  Continue to solution design, or keep exploring?
+```
+
+Do **not** infer "approach confirmed" from the user's reaction to the comparison. Only proceed to Step 2 (Analyze) when the user explicitly says to continue (e.g., "yes", "proceed", "go ahead", "design it").
+
 **Can stop at any time** — if after discussion the user says "let's not do it" or "let me think about it", there's no need to continue to the planning phase.
 
 ---
@@ -559,6 +626,24 @@ $roll-design --fix "fix login API 404" → Create FIX-AUTH-001
 $roll-fix FIX-AUTH-001 → Quick fix
 ```
 
+### With roll-peer
+
+Two checkpoints, both with 10s opt-out:
+
+```
+1. After Discuss — Direction Review
+   Approach confirmed → [peer, tag=architecture] → challenge the direction before DDD
+   Trigger: complexity=large OR requirement touches multiple Bounded Contexts
+
+2. After Solution Design — Plan Review
+   Plan written → [peer, tag=architecture] → full plan review before story split
+   Trigger: complexity=large (greenfield always qualifies)
+```
+
+On AGREE or user skip → continue to the next step normally.
+On REFINE/OBJECT → incorporate feedback, regenerate the relevant output, re-trigger peer.
+On ESCALATE → present both proposals to user for final call.
+
 ---
 
 ## Project Context Rule

package/skills/roll-fix/SKILL.md

@@ -320,6 +320,8 @@ Change the Status of the corresponding row from `📋 Todo` to `✅ Done`.
 
 ### 12. Update Changelog
 
+**Mandatory** — release notes depend on this step. Do not skip.
+
 ```bash
 $roll-.changelog
 ```

package/skills/roll-loop/SKILL.md

@@ -0,0 +1,204 @@
+---
+name: roll-loop
+license: MIT
+allowed-tools: "Read, Glob, Grep, Write, Edit, Bash(git:*), Bash(cat:*), Skill"
+description: |
+  Autonomous BACKLOG executor. Runs on a schedule (hourly via cron or GitHub
+  Actions), scans BACKLOG.md for 📋 Todo items, and routes each to the
+  appropriate skill: US-XXX → $roll-build, FIX-XXX → $roll-fix,
+  REFACTOR-XXX → $roll-build. Handles agent fallback on token/network failure.
+  Never executes roll-release autonomously — release is always a human decision.
+  Triggers roll-brief when a Feature completes.
+---
+
+# Roll Loop (Autonomous BACKLOG Executor)
+
+> Follows the Architecture Constraints, Development Discipline, and Engineering
+> Common Sense defined in the project AGENTS.md.
+
+Runs on a schedule. Picks up pending BACKLOG items and executes them without
+human intervention. The human stays informed via `roll-brief` and retains
+sole authority over `roll-release`.
+
+## Execution Boundary
+
+**What roll-loop executes autonomously:**
+- US-XXX (User Stories) → `$roll-build`
+- FIX-XXX (Bug fixes) → `$roll-fix`
+- REFACTOR-XXX (Refactors) → `$roll-build`
+
+**What roll-loop never executes:**
+- `roll-release` — production deployment is always a human decision
+- Any Story marked 🚫 Hold or flagged for human review
+- Destructive operations outside normal skill scope
+
+## Configuration
+
+```yaml
+# ~/.roll/config.yaml
+loop:
+  primary_agent: claude          # claude | deepseek | kimi
+  fallback_agent: deepseek       # used when primary fails
+  max_items_per_run: 3           # limit parallel risk; adjust as needed
+  brief_on_feature_complete: true
+  retry_backoff: [2, 4, 8, 16]  # seconds, exponential
+```
+
+## Workflow
+
+### Step 1 — Read State
+
+```bash
+STATE_FILE=~/.shared/roll/loop/state.yaml
+
+# If a previous run was interrupted, resume from state
+if [ -f "$STATE_FILE" ] && grep -q "status: interrupted" "$STATE_FILE"; then
+  # Resume the interrupted item first
+fi
+```
+
+### Step 2 — Scan BACKLOG
+
+Read `BACKLOG.md`. Collect all rows where Status = `📋 Todo`, in order:
+
+Priority: FIX-XXX first (bugs block progress), then US-XXX, then REFACTOR-XXX.
+
+Cap at `max_items_per_run` to limit blast radius per cycle.
+
+### Step 3 — Route and Execute
+
+For each item:
+
+```
+Item type         → Skill invoked
+─────────────────────────────────
+US-XXX            → Skill("roll-build", "US-XXX")
+FIX-XXX           → Skill("roll-fix", "FIX-XXX")
+REFACTOR-XXX      → Skill("roll-build", "REFACTOR-XXX")
+```
+
+Before invoking, write current item to state file:
+
+```yaml
+# ~/.shared/roll/loop/state.yaml
+status: running
+current_item: US-AUTO-004
+started_at: "2026-05-10T02:00:00+08:00"
+agent: claude
+run_id: loop-20260510-0200
+```
+
+### Step 4 — Post-Item Cleanup
+
+After each item completes:
+
+1. Update state file: `status: idle`
+2. Check if a Feature is now fully complete (all its Stories ✅)
+3. If yes and `brief_on_feature_complete: true` → invoke `Skill("roll-brief")`
+
+### Step 5 — Write Run Summary
+
+After all items in this cycle:
+
+```yaml
+# ~/.shared/roll/loop/state.yaml
+status: idle
+last_run: "2026-05-10T02:15:00+08:00"
+last_run_items: [US-AUTH-003, FIX-007]
+last_run_outcome: success
+```
+
+## Failure Handling
+
+### Network Error (transient)
+
+```
+Attempt 1 fails
+  → wait 2s → Attempt 2
+  → wait 4s → Attempt 3
+  → wait 8s → Attempt 4
+  → wait 16s → Attempt 5
+  → still failing → escalate to token/agent failure path
+```
+
+### Token Exhausted / Agent Unavailable
+
+```
+Primary agent fails (non-network error)
+  → switch to fallback_agent from config
+  → retry current item with fallback
+  → if fallback also fails → PAUSE
+```
+
+### Pause + Alert
+
+When both agents fail:
+
+1. Write state:
+```yaml
+status: paused
+paused_at: "2026-05-10T02:07:00+08:00"
+paused_on: US-AUTH-003
+reason: "both primary (claude) and fallback (deepseek) unavailable"
+```
+
+2. Write alert:
+```markdown
+# ALERT — roll-loop paused
+
+**Time**: 2026-05-10 02:07
+**Paused on**: US-AUTH-003
+**Reason**: claude: token exhausted; deepseek: network error after 5 retries
+
+**Action required** (choose one):
+- Top up credits and run: `roll loop resume`
+- Switch agent: edit `~/.roll/config.yaml` → `loop.primary_agent`
+- Take over manually: `$roll-build US-AUTH-003`
+```
+
+3. Write alert file to `~/.shared/roll/loop/ALERT.md`
+
+## Resuming After Pause
+
+```bash
+roll loop resume   # picks up from state.yaml current_item
+roll loop status   # show current state without running
+roll loop reset    # clear state and start fresh next scheduled run
+```
+
+## Scheduler Configuration
+
+roll-loop runs **locally** — it needs access to the local codebase, local
+test runner, and local agent CLI. GitHub Actions runs on remote servers and
+cannot fulfill these requirements.
+
+### Local cron (default)
+
+Install once with `roll loop on` — it reads the configured agent from
+`.roll.yaml` or `~/.roll/config.yaml` and writes the correct cron entry
+automatically. No agent-specific command needed.
+
+```bash
+roll loop on      # install cron for loop + dream + brief
+roll loop off     # remove cron entries
+roll loop status  # show current state
+```
+
+### Manual run (for testing)
+
+```bash
+roll loop now     # execute one cycle immediately
+```
+
+## Integration Map
+
+```
+roll-loop
+  ├── reads      BACKLOG.md
+  ├── invokes    $roll-build (US-XXX, REFACTOR-XXX)
+  ├── invokes    $roll-fix (FIX-XXX)
+  ├── invokes    $roll-brief (on Feature completion)
+  ├── reads      ~/.roll/config.yaml (agent routing)
+  ├── writes     ~/.shared/roll/loop/state.yaml
+  └── writes     ~/.shared/roll/loop/ALERT.md (on failure)
+```

package/skills/roll-peer/SKILL.md

@@ -170,12 +170,13 @@ If serve mode is available, prefer HTTP transport over direct CLI invocation.
 
 | Peer | Non-interactive command | Reliability | Notes |
 |------|------------------------|-------------|-------|
-| `claude` | `claude -p "<prompt>"` | ✅ High | Native, stable |
-| `deepseek` | `deepseek "<prompt>"` | ✅ Good | No TTY dependency |
+| `claude` | `claude -p "<prompt>"` | ✅ Verified | Native, stable |
+| `deepseek` | `deepseek "<prompt>"` | ✅ Verified | No TTY dependency |
 | `deepseek` (serve) | `curl localhost:<port>/v1/...` | ✅ High | Start with `deepseek serve --http`; preferred over direct CLI |
-| `kimi` | `kimi --quiet "<prompt>"` | ⚠️ Unverified | Verify non-interactive support before use |
-| `codex` | `codex exec --json --output-last-message "<prompt>"` | ⚠️ Unstable | Known CI failures due to Ink/TTY (issues [#1080](https://github.com/openai/codex/issues/1080), [#1340](https://github.com/openai/codex/issues/1340)); use only as fallback |
-| `pi` | `pi -p "<prompt>"` | ⚠️ Unverified | Verify non-interactive support before use |
+| `kimi` | `kimi --quiet -p "<prompt>"` | ✅ Verified | `--quiet` is alias for `--print --output-format text --final-message-only`; prompt via `-p` |
+| `pi` | `pi -p "<prompt>"` | ✅ Verified | Clean non-interactive output |
+| `opencode` | `opencode run "<prompt>"` | ✅ Verified | Works non-interactively |
+| `codex` | `codex exec "<prompt>"` | ⚠️ Auth required | Token must be valid; re-login with `codex login` if expired |
 
 **CLI vs. API Key**: `claude`, `deepseek`, `kimi`, `codex` CLIs authenticate via existing subscription accounts — no separate API key required. This is the primary advantage of CLI transport over the MCP/HTTP approach.