@seanyao/roll 2026.510.5 → 2026.510.7

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.5"
+VERSION="2026.510.7"
 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"
@@ -1653,16 +1662,25 @@ _project_agent() {
   fi
 }
 
+_skill_content() {
+  # Strip YAML frontmatter (---...---) — it's roll-internal metadata, not agent instructions
+  awk 'NR==1 && /^---$/{skip=1;next} skip && /^---$/{skip=0;next} !skip{print}' "$1"
+}
+
 _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; }
+  local content; content=$(_skill_content "$skill_file")
   case "$agent" in
-    claude)   claude -p "$(cat "$skill_file")" ;;
-    kimi)     kimi --quiet "$(cat "$skill_file")" ;;
-    deepseek) deepseek "$(cat "$skill_file")" ;;
-    *)        warn "Unknown agent '${agent}', falling back to claude"; claude -p "$(cat "$skill_file")" ;;
+    claude)   claude -p "$content" ;;
+    kimi)     kimi --quiet -p "$content" ;;
+    deepseek) deepseek "$content" ;;
+    pi)       pi -p "$content" ;;
+    codex)    codex exec "$content" ;;
+    opencode) opencode run "$content" ;;
+    *)        err "Unknown agent '${agent}'. Run: roll agent use <claude|kimi|deepseek|pi|codex|opencode>"; return 1 ;;
   esac
 }
 
@@ -1671,10 +1689,10 @@ cmd_agent() {
   case "$subcmd" in
     use)
       local name="${1:-}"
-      [[ -z "$name" ]] && { err "Usage: roll agent use <claude|kimi|deepseek>"; exit 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
-        sed -i "s/^agent:.*/agent: ${name}/" .roll.yaml
+        local tmp; tmp=$(mktemp) && sed "s/^agent:.*/agent: ${name}/" .roll.yaml > "$tmp" && mv "$tmp" .roll.yaml
       else
         echo "agent: ${name}" >> .roll.yaml
       fi
@@ -1714,6 +1732,22 @@ _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)
+  # Strip YAML frontmatter inline for cron commands
+  local strip="awk 'NR==1 && /^---$/{skip=1;next} skip && /^---$/{skip=0;next} !skip{print}' '${skill_path}'"
+  case "$agent" in
+    claude)   echo "claude -p \"\$(${strip})\"" ;;
+    kimi)     echo "kimi --quiet -p \"\$(${strip})\"" ;;
+    deepseek) echo "deepseek \"\$(${strip})\"" ;;
+    pi)       echo "pi -p \"\$(${strip})\"" ;;
+    codex)    echo "codex exec \"\$(${strip})\"" ;;
+    opencode) echo "opencode run \"\$(${strip})\"" ;;
+    *)        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
@@ -1721,7 +1755,9 @@ cmd_loop() {
     off)    _loop_off ;;
     now)    _loop_now ;;
     status) _loop_status ;;
-    *) err "Usage: roll loop <on|off|now|status>"; exit 1 ;;
+    resume) _loop_resume ;;
+    reset)  _loop_reset ;;
+    *) err "Usage: roll loop <on|off|now|status|resume|reset>"; exit 1 ;;
   esac
 }
 
@@ -1737,9 +1773,9 @@ _loop_on() {
   mkdir -p ~/.shared/roll/{loop,dream,brief}
 
   local loop_cmd dream_cmd brief_cmd
-  loop_cmd="cd \"${project_path}\" && ${agent} -p \"\$(cat ${sd}/roll-loop/SKILL.md)\" >> ~/.shared/roll/loop/cron.log 2>&1"
-  dream_cmd="cd \"${project_path}\" && ${agent} -p \"\$(cat ${sd}/roll-.dream/SKILL.md)\" >> ~/.shared/roll/dream/cron.log 2>&1"
-  brief_cmd="cd \"${project_path}\" && ${agent} -p \"\$(cat ${sd}/roll-brief/SKILL.md)\" >> ~/.shared/roll/brief/cron.log 2>&1"
+  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
@@ -1786,6 +1822,26 @@ _loop_status() {
   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
 # ═══════════════════════════════════════════════════════════════════════════════
@@ -1812,6 +1868,23 @@ cmd_brief() {
   [[ -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")
@@ -1841,7 +1914,8 @@ _dashboard() {
   fi
 
   echo ""
-  echo "  roll loop on|off|now|status · roll brief · roll agent use <name>"
+  echo "  loop <on|off|now|status|resume|reset>  ·  brief  ·  agent use <name>  ·  release"
+  echo "  setup  ·  update  ·  init  ·  status  ·  peer  ·  help"
   echo ""
 }
 
@@ -1867,9 +1941,10 @@ 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>  [Autonomous] Manage scheduled BACKLOG executor  管理自主执行循环"
+  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 "  release                [Publish] Sync changelog + version bump + npm publish  同步日志并发版"
   echo ""
   echo "Examples / 示例:"
   echo "  roll setup                    # New machine: first-time install            新机器首次安装"
@@ -1894,6 +1969,7 @@ main() {
     loop)          cmd_loop "$@" ;;
     brief)         cmd_brief "$@" ;;
     agent)         cmd_agent "$@" ;;
+    release)       cmd_release "$@" ;;
     version|--version|-v) echo "roll v${VERSION}" ;;
     help|--help|-h) usage ;;
     "") [[ -f "BACKLOG.md" ]] && _dashboard || { usage; _show_changelog; } ;;
@@ -1950,6 +2026,12 @@ _notify_update() {
   [[ -f "$cache" ]] || return
   local latest; latest=$(awk '{print $2}' "$cache" 2>/dev/null || true)
   [[ -z "$latest" || "$latest" == "$VERSION" ]] && return
+  local newer; newer=$(printf '%s\n%s\n' "$VERSION" "$latest" | sort -V | tail -1)
+  if [[ "$newer" == "$VERSION" ]]; then
+    # Running version is newer than cached — stale cache, clear it
+    rm -f "$cache"
+    return
+  fi
   echo ""
   warn "v${latest} available — run 'roll update' to upgrade  有新版本 v${latest} — 运行 'roll update' 升级"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seanyao/roll",
-  "version": "2026.510.5",
+  "version": "2026.510.7",
   "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

@@ -144,18 +144,8 @@ roll-.dream runs **locally** — it reads the local codebase directly.
 
 ### Local cron (default)
 
-```bash
-# Run at 01:00 every night (adjust to your timezone)
-0 1 * * * cd /path/to/project && claude -p "$(cat ~/.roll/skills/roll-.dream/SKILL.md)" >> ~/.shared/roll/dream/cron.log 2>&1
-```
-
-Installed automatically via `roll loop install` alongside roll-loop.
-The agent command is read from `~/.roll/config.yaml → loop.primary_agent`.
-
-### Agent with native scheduling support
-
-If your agent (Claude Code, opencode, etc.) supports scheduled prompts
-natively, prefer that over cron for cleaner lifecycle management.
+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
 

package/skills/roll-brief/SKILL.md

@@ -150,13 +150,8 @@ BACKLOG state and git history directly.
 
 ### Local cron (daily morning)
 
-```bash
-# 08:00 every morning (adjust to your timezone)
-0 8 * * * cd /path/to/project && claude -p "$(cat ~/.roll/skills/roll-brief/SKILL.md)"
-```
-
-Installed automatically via `roll loop install` alongside roll-loop and
-roll-.dream. The agent command respects `~/.roll/config.yaml → loop.primary_agent`.
+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
 

package/skills/roll-build/SKILL.md

@@ -517,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>
@@ -601,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-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

@@ -174,47 +174,20 @@ cannot fulfill these requirements.
 
 ### Local cron (default)
 
-Install once with `roll loop install`:
+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
-# What roll loop install writes to crontab:
-0 * * * * cd /path/to/project && claude -p "$(cat ~/.roll/skills/roll-loop/SKILL.md)" >> ~/.shared/roll/loop/cron.log 2>&1
+roll loop on      # install cron for loop + dream + brief
+roll loop off     # remove cron entries
+roll loop status  # show current state
 ```
 
-The agent invoked (`claude`, `kimi`, `deepseek`, etc.) is read from
-`~/.roll/config.yaml → loop.primary_agent`. The command is agent-agnostic:
-
-```bash
-# claude
-claude -p "$(cat ~/.roll/skills/roll-loop/SKILL.md)"
-
-# kimi
-kimi --quiet "$(cat ~/.roll/skills/roll-loop/SKILL.md)"
-
-# deepseek
-deepseek "$(cat ~/.roll/skills/roll-loop/SKILL.md)"
-```
-
-### Agent with native scheduling support
-
-Some agents support scheduled prompts natively (e.g., Claude Code hooks,
-opencode scheduled tasks). If your agent supports it, prefer that over cron
-— the agent handles its own lifecycle and the setup is cleaner.
-
-Consult your agent's documentation for scheduling configuration.
-
 ### Manual run (for testing)
 
 ```bash
-roll loop run      # execute one cycle immediately
-roll loop status   # show current state without running
-```
-
-### Local cron
-
-```bash
-# Every hour
-0 * * * * cd /path/to/project && claude -p "$(cat ~/.roll/skills/roll-loop/SKILL.md)" >> ~/.shared/roll/loop/cron.log 2>&1
+roll loop now     # execute one cycle immediately
 ```
 
 ## Integration Map

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.